@vsn-ux/ngx-gaia 0.9.2 → 0.9.4

package/DOCS.md

@@ -0,0 +1,951 @@
+# ngx-gaia
+
+Angular component library providing common Gaia UI components built with Angular 20+ features including signals and new input syntax. Components use `ga-` prefix and require `@angular/cdk`, `@vsn-ux/gaia-styles`, and `lucide-angular` dependencies.
+
+## Alert
+
+Alert components for displaying contextual information with optional progress indicators and dismissal functionality.
+
+**Angular module: GaAlertModule**
+
+### `<ga-alert>`
+
+Alert component for displaying notifications and contextual information.
+
+#### Inputs:
+
+- `variant: GaAlertVariant` - Alert type ('brand' | 'information' | 'error' | 'warning' | 'success', default: 'brand')
+- `icon: GaIconData` - Custom icon override
+- `dismissible: boolean` - Show dismiss button (default: false)
+- `progress: number | 'indeterminate'` - Progress value 0-100 or indeterminate state
+- `progressLabel: string` - Accessible label for progress bar
+- `progressLabelledBy: string` - ID of element labeling progress bar
+
+#### Outputs:
+
+- `dismiss()` - Emitted when dismiss button is clicked
+
+### `<ga-alert-title>`
+
+Alert title component for structured alert content.
+
+### `<ga-alert-title-actions>`
+
+Alert title actions component for action buttons in alert header.
+
+### GaAlertI18n
+
+Service for alert internationalization.
+
+#### Methods:
+
+- `dismissLabel: string` - Label for dismiss button
+
+### Providers:
+
+- `provideGaAlertI18n(value: GaAlertI18n | (() => GaAlertI18n))` - Configure alert i18n labels
+
+### Examples:
+
+```html
+<ga-alert variant="success" [dismissible]="true" (dismiss)="onDismiss()">
+  <ga-alert-title>Success!</ga-alert-title>
+  Operation completed successfully.
+</ga-alert>
+
+<ga-alert
+  variant="information"
+  [progress]="75"
+  progressLabel="Loading progress"
+>
+  Processing data...
+</ga-alert>
+```
+
+## Badge
+
+Badge component for displaying status indicators and labels.
+
+**Angular module: GaBadgeModule**
+
+### `<ga-badge>`
+
+#### Inputs:
+
+- `variant: 'default' | 'default-inverted' | 'information' | 'error' | 'warning' | 'success' | 'muted' | 'disabled'` - Badge variant (default: 'default')
+- `type: 'text' | 'dot'` - Badge type (default: 'text')
+
+### Examples:
+
+Badge variants
+
+```html
+<ga-badge variant="information" type="text">42</ga-badge>
+<ga-badge variant="error" type="dot"></ga-badge>
+```
+
+## Button
+
+Button directives for interactive elements with loading states and variants.
+
+**Angular module: GaButtonModule**
+
+### `[gaButton]`
+
+Button directive for styling button and anchor elements.
+
+#### Inputs:
+
+- `gaButton: GaButtonType` - Button variant ('primary' | 'secondary' | 'ghost' | 'transparent')
+- `gaButtonLoading: boolean` - Show loading state (default: false)
+- `gaButtonLoadingLabel: string` - Loading state label
+- `disabled: boolean` - Disabled state
+
+### `[gaIconButton]`
+
+Icon button directive for buttons with icons.
+
+#### Inputs:
+
+- `gaIconButton: GaIconData` - Icon to display (required)
+- `gaIconButtonVariant: GaIconButtonVariant` - Button variant (default: 'secondary')
+- `gaIconButtonLoading: boolean` - Show loading state (default: false)
+- `gaIconButtonLoadingLabel: string` - Loading state label
+- `disabled: boolean` - Disabled state
+
+### GaButtonI18n
+
+Service for button internationalization.
+
+#### Methods:
+
+- `loadingLabel: string` - Default loading label
+
+### Providers:
+
+- `provideGaButtonI18n(value: GaButtonI18n | (() => GaButtonI18n))` - Configure button i18n labels
+
+### Examples:
+
+```html
+<button gaButton="primary">Primary Button</button>
+<button gaButton="secondary" [gaButtonLoading]="isLoading">Save</button>
+<button [gaIconButton]="PlusIcon" gaIconButtonVariant="primary">Add</button>
+```
+
+## Card
+
+Card component for grouping related content.
+
+**Angular module: GaCardModule**
+
+### `<ga-card>`
+
+#### Inputs:
+
+- `selectable: boolean` - Can be selected (default: false)
+- `selected: boolean` - Is selected (default: false)
+- `disabled: boolean` - Disabled state (default: false)
+
+### Examples:
+
+Selectable card
+
+```html
+<ga-card selectable [selected]="isSelected">
+  <h3>Card Title</h3>
+  <p>Card content</p>
+</ga-card>
+```
+
+## Checkbox
+
+Checkbox component for boolean selections.
+
+**Angular module: GaCheckboxModule**
+
+### `<ga-checkbox>`
+
+#### Inputs:
+
+- `value: string | null` - Input value (default: null)
+- `checked: boolean` - Checked state (default: false)
+- `indeterminate: boolean` - Indeterminate state (default: false)
+- `name: string | null` - Input name (default: null)
+- `id: string | null` - Input ID (default: null)
+- `disabled: boolean` - Disabled state (default: false)
+- `required: boolean` - Required field (default: false)
+
+#### Outputs:
+
+- `change(value: boolean)` - Change event
+
+### Examples:
+
+Basic checkbox
+
+```html
+<ga-checkbox [(checked)]="isChecked">Accept terms</ga-checkbox>
+<ga-checkbox [(ngModel)]="value" [indeterminate]="someChecked"
+  >Select all</ga-checkbox
+>
+```
+
+## Datepicker
+
+Comprehensive datepicker with input integration, toggles, and multiple value adapters.
+
+**Angular module: GaDatepickerModule**
+
+### `<ga-datepicker>`
+
+Inline datepicker component for date selection.
+
+#### Inputs:
+
+- `value: any` - Selected date value (model binding)
+- `min: any` - Minimum selectable date
+- `max: any` - Maximum selectable date
+
+#### Outputs:
+
+- `valueChange(value: any)` - Emitted when date is selected
+
+### `[gaDatepicker]`
+
+Input directive for datepicker integration.
+
+#### Inputs:
+
+- `gaDatepicker: GaDatepickerComponent` - Associated datepicker instance
+- `min: any` - Minimum date constraint
+- `max: any` - Maximum date constraint
+
+### `<ga-datepicker-toggle>`
+
+Toggle button component for opening datepicker.
+
+#### Inputs:
+
+- `for: GaDatepickerComponent` - Associated datepicker instance
+
+### GaDatepickerI18n
+
+Service for datepicker internationalization.
+
+#### Methods:
+
+- `weekDays: string[]` - Week day labels
+- `monthNames: string[]` - Full month names
+- `monthNamesShort: string[]` - Abbreviated month names
+
+### GaDatepickerParserFormatter
+
+Service for parsing and formatting date strings.
+
+#### Methods:
+
+- `parse(value: string): any` - Parse string to date value
+- `format(value: any): string` - Format date value to string
+
+### GaDatepickerValueAdapter
+
+Abstract service for converting between external and internal date representations.
+
+### Value Adapters:
+
+- `GaDateStructAdapter` - Works with `{year, month, day}` objects
+- `GaDateNativeUtcAdapter` - Works with native Date objects in UTC
+- `GaDateNativeUtcIsoAdapter` - Works with ISO date strings
+
+### Providers:
+
+- `provideGaDatepickerI18n(value: GaDatepickerI18n)` - Configure datepicker i18n
+- `provideGaDatepickerParserFormatter(value: GaDatepickerParserFormatter)` - Configure parser/formatter
+- `provideGaDatepickerValueAdapter<T>(value: GaDatepickerValueAdapter<T>)` - Configure value adapter
+
+### Examples:
+
+```html
+<ga-datepicker
+  [(value)]="selectedDate"
+  [min]="minDate"
+  [max]="maxDate"
+></ga-datepicker>
+
+<ga-form-field>
+  <label gaFieldLabel>Select Date</label>
+  <input gaInput [gaDatepicker]="picker" [(ngModel)]="date" />
+  <ga-datepicker-toggle [for]="picker"></ga-datepicker-toggle>
+</ga-form-field>
+<ga-datepicker #picker></ga-datepicker>
+```
+
+## Form Field
+
+Form field components for creating accessible form inputs with labels and error handling.
+
+**Angular module: GaFormFieldModule**
+
+### `<ga-form-field>`
+
+Form field wrapper component.
+
+### `<ga-label>`
+
+Form label component.
+
+#### Inputs:
+
+- `state: string` - Additional state text
+- `definition: string | TemplateRef` - Help text or template
+
+### `<ga-info>`
+
+Information text component.
+
+### `[gaFormControl]`
+
+Form control directive.
+
+### `[gaError]`
+
+Error template directive.
+
+### `[gaFormControlErrors]`
+
+Custom errors directive for adding client-side validation errors.
+
+#### Inputs:
+
+- `gaFormControlErrors: ValidationErrors` - Custom validation errors (required)
+
+### `[gaLabelledByFormField]`
+
+Directive for connecting form controls to form field labels.
+
+#### Inputs:
+
+- `aria-labelledby: string | null` - Override aria-labelledby attribute
+
+### Examples:
+
+Complete form field
+
+```html
+<ga-form-field>
+  <ga-label state="(optional)" definition="Help text">Field Label</ga-label>
+  <input gaFormControl gaInput [(ngModel)]="value" required />
+  <ga-info>Additional information</ga-info>
+  <ng-template gaError="required">This field is required</ng-template>
+</ga-form-field>
+```
+
+Custom validation errors
+
+```html
+<ga-form-field>
+  <ga-label>Password</ga-label>
+  <input
+    gaFormControl
+    gaInput
+    [gaFormControlErrors]="{ weakPassword: isPasswordWeak ? 'Password too weak' : null }"
+    [(ngModel)]="password"
+  />
+  <ng-template gaError="weakPassword" let-error>{{ error }}</ng-template>
+</ga-form-field>
+```
+
+Form control with custom labelling
+
+```html
+<input gaInput gaLabelledByFormField [(ngModel)]="value" />
+```
+
+## Icon
+
+Icon component for displaying Lucide icons.
+
+**Angular module: GaIconModule**
+
+### `<ga-icon>`
+
+#### Inputs:
+
+- `icon: GaIconData | string` - Lucide icon (required)
+- `size: string | number` - Icon size (default: 24)
+- `color: string` - Icon color
+- `strokeWidth: number` - Stroke width
+
+### Examples:
+
+Icon with custom styling
+
+```html
+<ga-icon [icon]="icons.Settings" size="32" color="var(--ga-color-primary)" />
+```
+
+## Input
+
+Input components and directives for text input fields.
+
+**Angular module: GaInputModule**
+
+### `[gaInput]`
+
+Input directive for styling input elements.
+
+#### Inputs:
+
+- `id: string` - Element ID
+- `disabled: boolean` - Disabled state
+- `invalid: boolean` - Invalid state styling
+
+### `<ga-input>`
+
+Input component wrapper.
+
+### Examples:
+
+```html
+<input gaInput type="text" placeholder="Enter text" [(ngModel)]="value" />
+
+<ga-input>
+  <input type="text" placeholder="Wrapped input" [(ngModel)]="value" />
+</ga-input>
+```
+
+## Link
+
+Link directive for styled navigation links.
+
+**Angular module: GaLinkModule**
+
+### `[gaLink]`
+
+Link directive.
+
+#### Inputs:
+
+- `gaLink: 'inline' | ''` - Link variant (default: '')
+- `gaLinkSize: 'small' | 'medium' | 'large'` - Link size (default: 'medium')
+- `gaLinkDisabled: boolean` - Disabled state (default: false)
+- `gaLinkLeadingIcon: GaIconData | string` - Leading icon (default: '')
+- `gaLinkTrailingIcon: GaIconData | string` - Trailing icon (default: '')
+
+### Examples:
+
+Link variants
+
+```html
+<a gaLink href="/page">Standard link</a>
+<a gaLink="inline" href="/page">Inline link</a>
+<a gaLink [gaLinkTrailingIcon]="icons.ExternalLink" href="/external"
+  >External</a
+>
+```
+
+## Menu
+
+Menu components for dropdown navigation and actions.
+
+**Angular module: GaMenuModule**
+
+### `<ga-menu>`
+
+Menu container component.
+
+### `<ga-menu-title>`
+
+Menu title component.
+
+### `[gaMenuItem]`
+
+Menu item directive.
+
+#### Inputs:
+
+- `gaMenuItemIcon: GaIconData` - Item icon
+- `gaMenuItemDescription: string` - Item description
+- `gaMenuItemShortcut: string` - Keyboard shortcut
+
+### `<ga-menu-separator>`
+
+Menu separator component.
+
+### `<ga-menu-trigger-icon>`
+
+Trigger icon component.
+
+### `[gaMenuTrigger]`
+
+Menu trigger directive.
+
+#### Inputs:
+
+- `gaMenuTrigger: TemplateRef` - Menu template (required)
+
+#### Outputs:
+
+- `gaMenuOpened()` - Opened event
+- `gaMenuClosed()` - Closed event
+
+### Examples:
+
+Menu with trigger
+
+```html
+<button gaButton [gaMenuTrigger]="menu">Menu <ga-menu-trigger-icon /></button>
+<ng-template #menu>
+  <ga-menu>
+    <ga-menu-title>Actions</ga-menu-title>
+    <button gaMenuItem [gaMenuItemIcon]="icons.Edit">Edit</button>
+    <ga-menu-separator />
+    <button gaMenuItem [gaMenuItemIcon]="icons.Trash2">Delete</button>
+  </ga-menu>
+</ng-template>
+```
+
+## Modal
+
+Modal service and components for creating overlay dialogs.
+
+**Angular module: GaModalModule**
+
+### `<ga-modal>`
+
+Base modal component for creating dialog content.
+
+#### Inputs:
+
+- `data: any` - Modal data passed from service
+
+#### Outputs:
+
+- `afterClosed(): Observable<any>` - Emitted when modal closes
+
+#### Methods:
+
+- `close(result?: any): void` - Close the modal with optional result
+
+### `<ga-modal-header>`
+
+Modal header component.
+
+### `<ga-modal-content>`
+
+Modal content component for main dialog content.
+
+### `<ga-modal-description>`
+
+Modal description component for additional context.
+
+### `<ga-modal-actions>`
+
+Modal actions component for buttons and controls.
+
+### GaModalService
+
+Service for opening and managing modals.
+
+#### Methods:
+
+- `open<T>(component: ComponentType<T>, data?: any): T` - Open modal with component
+- `closeAll(): void` - Close all open modals
+
+### GaModalRef
+
+Reference to an opened modal instance.
+
+#### Methods:
+
+- `close(result?: any): void` - Close the modal
+
+### GaModalI18n
+
+Service for modal internationalization.
+
+### Providers:
+
+- `provideGaModalI18n(value: GaModalI18n)` - Configure modal i18n
+- `provideGaModalOptions(options: GaModalOptions)` - Configure modal options
+
+### Examples:
+
+```html
+<ga-modal>
+  <ga-modal-header>Confirm Action</ga-modal-header>
+  <ga-modal-content>Are you sure you want to proceed?</ga-modal-content>
+  <ga-modal-actions>
+    <button gaButton="secondary" (click)="close()">Cancel</button>
+    <button gaButton="primary" (click)="confirm()">Confirm</button>
+  </ga-modal-actions>
+</ga-modal>
+```
+
+```typescript
+constructor(private modalService: GaModalService) {}
+
+openDialog() {
+  const modal = this.modalService.open(ConfirmModalComponent, {
+    message: 'Are you sure?'
+  });
+}
+```
+
+## Radio
+
+Radio button components for single-choice selections.
+
+**Angular module: GaRadioModule**
+
+### `<ga-radio-group>`
+
+Radio group component.
+
+#### Inputs:
+
+- `value: any` - Selected value
+
+#### Outputs:
+
+- `change(value: any)` - Change event
+
+### `<ga-radio-button>`
+
+Radio button component.
+
+#### Inputs:
+
+- `value: any` - Button value
+
+### Examples:
+
+Radio group
+
+```html
+<ga-radio-group [(value)]="selectedValue">
+  <ga-radio-button value="option1">Option 1</ga-radio-button>
+  <ga-radio-button value="option2">Option 2</ga-radio-button>
+  <ga-radio-button value="option3">Option 3</ga-radio-button>
+</ga-radio-group>
+```
+
+## Segmented Control
+
+Segmented control components for grouped button selections.
+
+**Angular module: GaSegmentedControlModule**
+
+### `<ga-segmented-control>`
+
+Segmented control container component.
+
+#### Inputs:
+
+- `selected: any` - Selected value
+
+#### Outputs:
+
+- `change(value: any)` - Change event
+
+### `<ga-segmented-control-text-button>`
+
+Text button component.
+
+#### Inputs:
+
+- `value: any` - Button value
+
+### `<ga-segmented-control-icon-button>`
+
+Icon button component.
+
+#### Inputs:
+
+- `value: any` - Button value
+- `icon: GaIconData` - Button icon
+
+### Examples:
+
+Text buttons
+
+```html
+<ga-segmented-control [(selected)]="view">
+  <ga-segmented-control-text-button value="list"
+    >List</ga-segmented-control-text-button
+  >
+  <ga-segmented-control-text-button value="grid"
+    >Grid</ga-segmented-control-text-button
+  >
+</ga-segmented-control>
+```
+
+Icon buttons
+
+```html
+<ga-segmented-control [(selected)]="view">
+  <ga-segmented-control-icon-button [icon]="icons.List" value="list"
+    >List</ga-segmented-control-icon-button
+  >
+  <ga-segmented-control-icon-button [icon]="icons.Grid" value="grid"
+    >Grid</ga-segmented-control-icon-button
+  >
+</ga-segmented-control>
+```
+
+## Select
+
+Select components for dropdown selections with search and multi-select capabilities.
+
+**Angular module: GaSelectModule**
+
+### `<ga-select>`
+
+Select component.
+
+#### Inputs:
+
+- `value: any` - Selected value (single/multiple)
+- `placeholder: string` - Placeholder text
+- `canSelectNullable: boolean` - Allow null selection
+- `compareWith: (a: any, b: any) => boolean` - Value comparison function
+- `leftIcon: GaIconData` - Left icon
+- `multiple: boolean` - Multiple selection
+- `searchable: boolean` - Enable search
+- `clearable: boolean` - Show clear button
+- `textValue: string` - Search text (searchable mode)
+
+### `<ga-select-dropdown>`
+
+Dropdown container component.
+
+#### Inputs:
+
+- `loading: boolean` - Loading state
+
+### `<ga-option>`
+
+Option component.
+
+#### Inputs:
+
+- `value: any` - Option value
+- `withInput: boolean` - Include input
+- `typeaheadLabel: string` - Typeahead label
+- `hidden: boolean` - Hidden state
+
+### `<ga-optgroup>`
+
+Option group component.
+
+#### Inputs:
+
+- `label: string` - Group label
+
+### `<ga-select-value>`
+
+Custom trigger value display component.
+
+### `<ga-select-dropdown-spinner>`
+
+Loading spinner component.
+
+### Providers:
+
+- `provideGaSelectI18n` - Configure clear button label
+
+### Examples:
+
+Basic select
+
+```html
+<ga-select placeholder="Choose option" [(value)]="selected">
+  <ga-select-dropdown>
+    <ga-option value="1">Option 1</ga-option>
+    <ga-option value="2">Option 2</ga-option>
+  </ga-select-dropdown>
+</ga-select>
+```
+
+Multi-select
+
+```html
+<ga-select multiple [(value)]="selectedItems">
+  <ga-select-dropdown>
+    <ga-option value="1">Item 1</ga-option>
+    <ga-option value="2">Item 2</ga-option>
+  </ga-select-dropdown>
+</ga-select>
+```
+
+Searchable select
+
+```html
+<ga-select searchable clearable [(textValue)]="searchText" [(value)]="selected">
+  <ga-select-dropdown>
+    <ga-option *ngFor="let item of filteredItems" [value]="item"
+      >{{ item.name }}</ga-option
+    >
+  </ga-select-dropdown>
+</ga-select>
+```
+
+Select with groups
+
+```html
+<ga-select [(value)]="selected">
+  <ga-select-dropdown>
+    <ga-optgroup label="Group 1">
+      <ga-option value="1">Option 1</ga-option>
+    </ga-optgroup>
+    <ga-optgroup label="Group 2">
+      <ga-option value="2">Option 2</ga-option>
+    </ga-optgroup>
+  </ga-select-dropdown>
+</ga-select>
+```
+
+i18n configuration
+
+```typescript
+provideGaSelectI18n({ clearLabel: 'Clear selection' });
+```
+
+## Spinner
+
+Spinner component for loading indicators.
+
+**Angular module: GaSpinnerModule**
+
+### `<ga-spinner>`
+
+#### Inputs:
+
+- `size: number` - Size in pixels (default: 32)
+
+### Examples:
+
+Custom sized spinner
+
+```html
+<ga-spinner size="48" />
+```
+
+## Switch
+
+Switch component for boolean toggle controls.
+
+**Angular module: GaSwitchModule**
+
+### `<ga-switch>`
+
+#### Inputs:
+
+- `label: string` - Switch label (default: '')
+- `checked: boolean` - Checked state (default: false)
+- `disabled: boolean` - Disabled state (default: false)
+
+#### Outputs:
+
+- `checkedChange(value: boolean)` - Change event
+
+### Examples:
+
+Switch with label
+
+```html
+<ga-switch label="Enable notifications" [(checked)]="enabled" />
+<ga-switch [(ngModel)]="value" label="Dark mode" />
+```
+
+## Text Area
+
+Text area directive for multi-line text input.
+
+**Angular module: GaTextAreaModule**
+
+### `[gaTextArea]`
+
+Text area directive.
+
+#### Inputs:
+
+- `invalid: boolean` - Invalid state
+
+### Examples:
+
+Basic text area
+
+```html
+<textarea gaTextArea rows="5" placeholder="Enter text"></textarea>
+```
+
+Text area in form field
+
+```html
+<ga-form-field>
+  <ga-label>Description</ga-label>
+  <textarea gaFormControl gaTextArea [(ngModel)]="description"></textarea>
+</ga-form-field>
+```
+
+## Tooltip
+
+Tooltip directive and component for contextual information overlays.
+
+**Angular module: GaTooltipModule**
+
+### `[gaTooltip]`
+
+Tooltip directive for contextual information overlays.
+
+#### Inputs:
+
+- `gaTooltip: string | TemplateRef<any>` - Tooltip content
+- `gaTooltipDisabled: boolean` - Disable tooltip (default: false)
+- `gaTooltipControlMode: 'hover' | 'click' | 'none'` - Control mode (default: 'hover')
+- `gaTooltipShowControlMode: 'hover' | 'click' | 'none'` - Show control mode
+- `gaTooltipHideControlMode: 'hover' | 'click' | 'none'` - Hide control mode
+- `gaTooltipOffsetSize: number` - Offset from target (default: 5)
+- `gaTooltipPlacement: GaTooltipPlacement` - Preferred placement (default: 'right-center')
+
+#### Methods:
+
+- `show(): void` - Show tooltip programmatically
+- `hide(): void` - Hide tooltip programmatically
+- `toggle(): void` - Toggle tooltip visibility
+
+### `<ga-tooltip>`
+
+Tooltip component for rendering tooltip content.
+
+### Examples:
+
+```html
+<button gaTooltip="This is a tooltip">Hover me</button>
+<span [gaTooltip]="tooltipContent" gaTooltipPlacement="top-center"
+  >Top tooltip</span
+>
+<button gaTooltip="Click tooltip" gaTooltipControlMode="click">Click me</button>
+```
+
+## Utils
+
+Utility tokens and providers for configuring library behavior.
+
+### Providers:
+
+- `provideGaBaseFontSize` - Configure base font size for rem calculations
+
+### Tokens:
+
+- `GA_BASE_FONT_SIZE` - Base font size injection token
+
+### Examples:
+
+Base font size configuration
+
+```typescript
+provideGaBaseFontSize(14); // Use 14px as base instead of default 16px
+```