Angular Awesome - Rules & Guidelines

Purpose

Create Angular components/directives to wrap Web Awesome web components and:

• Use Angular template-driven forms primarily (avoid Reactive Forms)
• Enable ngModel binding, value binding support, and template interactivity
• Bridge Input/Output with web component props/events
• Support named slot projection using ng-content select
• Simplify styling for Angular users (inputs become CSS vars on host)
• Ensure lazy initialization with customElements.whenDefined()
• Enable slot layout rendering for wa-page and related patterns
• Ensure boolean attributes are rendered only when true (omit otherwise)
• Use native tag selectors for all components (wa-button, wa-badge, etc.)
• Avoid Signals for inputs/outputs in Angular libraries (due to scope issues)

Component Categories

1. Input Components

Web Components: wa-input, wa-select, wa-textarea

Responsibilities:

• Provide ngModel or value + valueChange support
• Wait for component load before syncing props/events
• Allow placeholder, size, variant, etc. as Input
• Apply component style via individual Input properties that are bound to CSS custom properties
• Project wa-icon and other slot="prefix"/"suffix" elements

2. UI Components

Examples: wa-badge, wa-tag, wa-button, wa-icon, wa-avatar

Responsibilities:

• Use directive wrappers with Directive selector
• Map known attributes as Input
• Use individual Input properties for CSS custom properties
• Ensure boolean inputs render as attributes only when true
• Booleans must be assignable with boolean or strings
• Avoid wrapping in ng-template or using TemplateRef
• Use ngOnInit lifecycle for setup

3. Pattern Components

Example: wa-page

Responsibilities:

• Project child content to named slots (e.g., slot="header", slot="aside")
• Expose mobileBreakpoint, view, and theming attributes
• Declare individual style inputs as Input properties that bind to CSS custom properties on the host element
• Support wa-dark, wa-light, etc. mode switching via attribute

Global Requirements (for Consumers)

Required Assets (CDN Defaults)

Include the Web Awesome CSS and JavaScript files in your application.

Optional: Add data-fa-kit-code if integrating with Font Awesome Kit.

For cherry-picking or bundling, use the setBasePath function.

Layout and Styling Utilities

Alignment Classes

wa-align-items-start, wa-align-items-end, wa-align-items-center, wa-align-items-stretch, wa-align-items-baseline

Gap Classes (for clusters, stacks, and splits)

wa-gap-0, wa-gap-3xs, wa-gap-2xs, wa-gap-xs, wa-gap-s, wa-gap-m, wa-gap-l, wa-gap-xl, wa-gap-2xl, wa-gap-3xl

Appearance Classes

.wa-accent, .wa-outlined, .wa-filled, .wa-plain

These utilities set tokens such as:

• --background-color, --border-color, --text-color

Color Variant Classes

.wa-brand, .wa-neutral, .wa-success, .wa-warning, .wa-danger

Tokens are semantic, consumed via --wa-color-fill-* and related

Layout Primitives

wa-cluster

Align items in a row with consistent spacing, wrapping when needed. Supports wa-align-items-* and wa-gap-*.

wa-stack

Arrange items in a column with spacing.

wa-flank

Two items side-by-side with one stretching to fill space. Wraps when needed.

wa-split

Distribute items across available space. Append :column or :row to control direction.

• Directional: wa-split:row, wa-split:column
• Alignment: wa-align-items-*
• Gap support: wa-gap-*

wa-frame

Responsive container with consistent proportions. Ideal for wrapping images or visuals.

wa-grid

Responsive grid layout. Use --min-column-size to control columns. wa-span-grid spans full row.

Angular Implementation Guidelines

• Use native Web Component tag selectors (wa-*) as Angular directive selectors
• Wrap UI components like badges, icons, buttons using Directive (not Component)
• Use Input for properties; bind via Renderer2 in ngOnInit
• Output event bindings for animation lifecycle and other custom web component events
• Boolean inputs: render attribute if true, omit otherwise
• Avoid using Signals inside libraries
• Avoid TemplateRef or ng-template unless required by slotting patterns
• Use individual Input properties for CSS custom properties
• Always ensure the module declares CUSTOM_ELEMENTS_SCHEMA

Attribute Coercion Rules

To support template usage without bindings:

• All Inputs should accept string or the native type (number | string, boolean | string) to ensure Angular doesn't reject unbound literal inputs.
• Boolean inputs must render as attributes only when the value is truthy — this includes the string "true".
• Number inputs passed as strings (e.g., duration="300") should be converted to numbers in the directive/component logic before assigning to properties or attributes.
• Avoid relying on native type inference — always normalize input types manually.

Custom Event Support

• Angular wrappers must allow users to bind to custom events emitted by Web Awesome components.
• For components that emit events, document all event names and map them in the directive/component.
• Events can be passed through natively using event binding, or explicitly exposed via Output as needed for type safety.