@vsn-ux/ngx-gaia 0.11.3 → 0.11.5

package/DOCS.md

@@ -422,6 +422,10 @@ Data select component that automatically generates options from an items array.
 - `closed()` - Emitted when dropdown closes
 - `optionsEndReached()` - Emitted when user scrolls to bottom of options
 
+#### Methods:
+
+- `focus(): void` - Focus the select trigger
+
 ### `IGaSelectOption<T>`
 
 Type for option items with special properties:
@@ -941,6 +945,7 @@ Menu item directive.
 - `gaMenuItemIcon: GaIconData` - Item icon
 - `gaMenuItemDescription: string` - Item description
 - `gaMenuItemShortcut: string` - Keyboard shortcut
+- `gaMenuItemSelected: boolean` - Selected state (default: false)
 
 ### `<ga-menu-separator>`
 
@@ -979,6 +984,37 @@ Menu with trigger
 </ng-template>
 ```
 
+Menu with selected item
+
+```html
+<button gaButton [gaMenuTrigger]="menu">Options</button>
+<ng-template #menu>
+  <ga-menu>
+    <button
+      gaMenuItem
+      [gaMenuItemSelected]="selected === 1"
+      (click)="selected = 1"
+    >
+      Option 1
+    </button>
+    <button
+      gaMenuItem
+      [gaMenuItemSelected]="selected === 2"
+      (click)="selected = 2"
+    >
+      Option 2
+    </button>
+    <button
+      gaMenuItem
+      [gaMenuItemSelected]="selected === 3"
+      (click)="selected = 3"
+    >
+      Option 3
+    </button>
+  </ga-menu>
+</ng-template>
+```
+
 ## Modal
 
 Modal service and components for creating overlay dialogs.
@@ -1211,6 +1247,10 @@ Select component.
 - `multiple: boolean` - Multiple selection
 - `clearable: boolean` - Show clear button
 
+#### Methods:
+
+- `focus(): void` - Focus the select trigger
+
 ### `<ga-select-dropdown>`
 
 Dropdown container component.
@@ -1325,9 +1365,9 @@ Switch component for boolean toggle controls.
 
 #### Inputs:
 
-- `label: string` - Switch label (default: '')
 - `checked: boolean` - Checked state (default: false)
 - `disabled: boolean` - Disabled state (default: false)
+- `label: string` - **@deprecated** Use content projection instead (default: '')
 
 #### Outputs:
 
@@ -1335,11 +1375,11 @@ Switch component for boolean toggle controls.
 
 ### Examples:
 
-Switch with label
+Switch with visible label
 
 ```html
-<ga-switch label="Enable notifications" [(checked)]="enabled" />
-<ga-switch [(ngModel)]="value" label="Dark mode" />
+<ga-switch [(checked)]="enabled">Enable notifications</ga-switch>
+<ga-switch [(ngModel)]="value">Dark mode</ga-switch>
 ```
 
 ## Tabs
@@ -1381,6 +1421,18 @@ Individual tab component for tab content.
 
 Directive for explicit tab content template definition.
 
+### GaTabsI18n
+
+Service for tabs internationalization.
+
+#### Properties:
+
+- `moreLabel: string` - Label for the overflow menu trigger button (default: 'More')
+
+### Providers:
+
+- `provideGaTabsI18n(value: GaTabsI18n | (() => GaTabsI18n))` - Configure tabs i18n labels
+
 ### Examples:
 
 Basic tabs
@@ -1452,6 +1504,19 @@ Explicit content template
 </ga-tabs>
 ```
 
+i18n configuration
+
+```typescript
+// Static configuration
+provideGaTabsI18n({ moreLabel: 'More options' });
+
+// Factory function with injection context
+provideGaTabsI18n(() => {
+  const i18n = inject(MyI18nService);
+  return { moreLabel: i18n.translate('tabs.more') };
+});
+```
+
 ## Text Area
 
 Text area directive for multi-line text input.
@@ -1483,6 +1548,114 @@ Text area in form field
 </ga-form-field>
 ```
 
+## Toast
+
+Service-based toast notification system for displaying temporary messages with auto-dismiss functionality.
+
+### GaToaster
+
+Service for displaying toast notifications.
+
+#### Methods:
+
+- `show(content: GaToastContent | TemplateRef<any> | { template: TemplateRef<any>, context: any }, duration?: number | null): { id: number, hide: () => void }` - Display a toast notification
+- `hide(id: number): void` - Hide a specific toast by ID
+- `hideAll(): void` - Hide all visible toasts
+
+### GaToastContent
+
+Content configuration interface for toast messages.
+
+#### Properties:
+
+- `title?: string` - Optional title
+- `message: string` - Main message content (required)
+- `variant?: GaToastVariant` - Visual variant ('information' | 'success' | 'warning' | 'error', default: 'information')
+- `importance?: 'assertive' | 'polite' | 'auto'` - Accessibility importance level (default: 'auto')
+
+### Providers:
+
+- `provideGaToastOptions(options: Partial<GaToastGlobalOptions>)` - Configure global toast options including variant, duration, importance, position, offsetX, and offsetY
+
+### Examples:
+
+Simple toast message
+
+```typescript
+import { GaToaster } from '@vsn-ux/ngx-gaia';
+
+const toaster = inject(GaToaster);
+toaster.show({ message: 'Some fancy toast message!' });
+```
+
+Toast with all options
+
+```typescript
+toaster.show(
+  {
+    title: 'Success!',
+    message: 'Your changes have been saved.',
+    variant: 'success',
+    importance: 'polite',
+  },
+  5000,
+);
+```
+
+Custom template content
+
+```html
+<ng-template #content let-data let-hide="hide">
+  <ga-alert variant="error">
+    <ga-alert-title>{{ data.title }}</ga-alert-title>
+    {{ data.message }}
+    <button gaButton (click)="hide()">Dismiss</button>
+  </ga-alert>
+</ng-template>
+```
+
+```typescript
+// Pass TemplateRef directly
+toaster.show(contentTemplateRef);
+
+// With template and context
+toaster.show({
+  template: contentTemplateRef,
+  context: { title: 'Error', message: 'Something went wrong' },
+});
+```
+
+Controlling toast visibility
+
+```typescript
+const toast = toaster.show({ message: 'Some fancy toast message!' });
+
+// Hide specific toast
+toast.hide();
+// or
+toaster.hide(toast.id);
+
+// Hide all toasts
+toaster.hideAll();
+```
+
+Global configuration
+
+```typescript
+import { provideGaToastOptions } from '@vsn-ux/ngx-gaia';
+
+providers: [
+  provideGaToastOptions({
+    variant: 'information',
+    duration: 5000,
+    importance: 'auto',
+    position: 'top-right',
+    offsetX: '0.8rem',
+    offsetY: '7.2rem',
+  }),
+];
+```
+
 ## Tooltip
 
 Tooltip directive and component for contextual information overlays.

package/README.md

@@ -43,6 +43,15 @@ ng add @vsn-ux/ngx-gaia
    // @import '@vsn-ux/gaia-styles/all.css';
    ```
 
+## Claude Code Integration (Optional)
+
+If you use [Claude Code](https://claude.ai/code), you can install the ngx-gaia plugin for better AI assistance with components:
+
+```sh
+/plugin marketplace add ./node_modules/@vsn-ux/ngx-gaia/claude --scope project
+/plugin install ngx-gaia@ngx-gaia --scope project
+```
+
 ## Browser support
 
 Follows PDAB Compatibility Policy:  

package/docs/alert.md

@@ -0,0 +1,105 @@
+# Alert
+
+Alert components for displaying contextual notifications with optional progress indicators and dismissal functionality.
+
+**Angular module: GaAlertModule**
+
+## `<ga-alert>`
+
+Alert component for displaying notifications and contextual information. Uses `role="alert"` for screen reader announcements.
+
+### Inputs:
+
+- `variant: GaAlertVariant` - Visual style ('brand' | 'information' | 'error' | 'warning' | 'success', default: 'brand')
+- `icon: GaIconData` - Custom icon override (default: variant-specific icon, 'brand' has no icon)
+- `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: EventEmitter<void>` - Emitted when dismiss button is clicked
+
+### Properties:
+
+- `progressId: string` - Auto-generated ID for progress bar (use with aria-describedby)
+
+### Default variant icons:
+
+- `information` - Info icon
+- `success` - CircleCheck icon
+- `warning` - TriangleAlert icon
+- `error` - OctagonAlert icon
+- `brand` - No icon
+
+## `<ga-alert-title>`
+
+Title component projected into alert header.
+
+## `<ga-alert-title-actions>`
+
+Container for action buttons in alert header, positioned next to the title.
+
+## GaAlertI18n
+
+Abstract class for alert internationalization.
+
+### Properties:
+
+- `dismissLabel: string` - Label for dismiss button (default: 'Dismiss')
+
+## Providers:
+
+- `provideGaAlertI18n(value: GaAlertI18n | (() => GaAlertI18n))` - Configure alert i18n labels
+
+## Examples:
+
+Basic alert with title and dismiss:
+
+```html
+<ga-alert variant="success" [dismissible]="true" (dismiss)="onDismiss()">
+  <ga-alert-title>Success!</ga-alert-title>
+  Operation completed successfully.
+</ga-alert>
+```
+
+Alert with progress bar:
+
+```html
+<ga-alert variant="information" [progress]="75" progressLabel="Upload progress">
+  <ga-alert-title>Uploading...</ga-alert-title>
+  Your file is being uploaded.
+</ga-alert>
+```
+
+Alert with title actions:
+
+```html
+<ga-alert>
+  <ga-alert-title>Notification</ga-alert-title>
+  <ga-alert-title-actions>
+    <button [gaIconButton]="MoreIcon" gaIconButtonVariant="ghost">more</button>
+  </ga-alert-title-actions>
+  This is a notification with actions.
+</ga-alert>
+```
+
+Using progressId for accessibility:
+
+```html
+<ga-alert #alert variant="information" [progress]="50">
+  <ga-alert-title>Processing</ga-alert-title>
+</ga-alert>
+<p [attr.aria-describedby]="alert.progressId">Status indicator above</p>
+```
+
+Configuring i18n:
+
+```typescript
+import { provideGaAlertI18n } from '@vsn-ux/ngx-gaia';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideGaAlertI18n({ dismissLabel: $localize`Close` })],
+};
+```

package/docs/badge.md

@@ -0,0 +1,21 @@
+# 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>
+```

package/docs/button.md

@@ -0,0 +1,46 @@
+# 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', default: 'secondary')
+- `gaButtonLoading: boolean` - Show loading state (default: false)
+- `gaButtonLoadingLabel: string` - Loading state label
+
+## `[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
+
+## GaButtonI18n
+
+Service for button internationalization.
+
+### Properties:
+
+- `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>
+```

package/docs/card.md

@@ -0,0 +1,24 @@
+# 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>
+```

package/docs/checkbox.md

@@ -0,0 +1,40 @@
+# 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)
+
+### Outputs:
+
+- `checkedChange(value: boolean)` - Emits when checked state changes
+- `indeterminateChange(value: boolean)` - Emits when indeterminate state changes
+- `change(value: boolean)` - **Deprecated**: Use `checkedChange` instead
+
+## `GaCheckboxRequiredValidator`
+
+Directive that provides required validation for `ga-checkbox` in template-driven forms.
+
+**Selector:** `ga-checkbox[required][formControlName], ga-checkbox[required][formControl], ga-checkbox[required][ngModel]`
+
+Automatically applied when using `required` attribute with reactive or template-driven forms.
+
+## Examples:
+
+Basic checkbox
+
+```html
+<ga-checkbox [(checked)]="isChecked">Accept terms</ga-checkbox>
+<ga-checkbox [(ngModel)]="value" [indeterminate]="someChecked"
+  >Select all</ga-checkbox
+>
+```

package/docs/chip.md

@@ -0,0 +1,93 @@
+# Chip
+
+Chip components for selectable options in a compact, pill-shaped format.
+
+**Angular module: GaChipModule**
+
+## `<ga-chip-listbox>`
+
+Container component for managing chip selection and keyboard navigation.
+
+### Inputs:
+
+- `value: any | any[]` - Selected value (single value or array for multiple selection)
+- `multiple: boolean` - Enable multiple selection
+- `disabled: boolean` - Disable entire listbox
+- `compareWith: (a: any, b: any) => boolean` - Custom value comparison function
+- `orientation: 'horizontal' | 'vertical'` - Keyboard navigation orientation (default: 'horizontal')
+- `variant: 'default' | 'transparent'` - Visual variant (default: 'default')
+
+### Outputs:
+
+- `valueChange(value: any | any[])` - Emitted when selection changes
+
+### Methods:
+
+- `focus(): void` - Focus the listbox
+
+## `<ga-chip>`
+
+Individual chip component for selectable options.
+
+### Inputs:
+
+- `value: any` - Chip value (required)
+- `disabled: boolean` - Disable individual chip (default: false)
+
+### Properties:
+
+- `selected: Signal<boolean | null>` - Read-only signal indicating if chip is selected
+
+## Examples:
+
+Single selection
+
+```html
+<ga-chip-listbox [(value)]="selectedValue">
+  <ga-chip value="Apple">Apple</ga-chip>
+  <ga-chip value="Banana">Banana</ga-chip>
+  <ga-chip value="Orange">Orange</ga-chip>
+</ga-chip-listbox>
+```
+
+Multiple selection
+
+```html
+<ga-chip-listbox [(value)]="selectedValues" multiple>
+  <ga-chip value="Apple">Apple</ga-chip>
+  <ga-chip value="Banana">Banana</ga-chip>
+  <ga-chip value="Orange" disabled>Orange</ga-chip>
+</ga-chip-listbox>
+```
+
+With icons
+
+```html
+<ga-chip-listbox [(value)]="selected" multiple>
+  <ga-chip value="Apple">
+    <ga-icon [icon]="icons.Apple" size="16" />
+    Apple
+  </ga-chip>
+  <ga-chip #chip value="Grape">
+    <ga-icon [icon]="icons.Grape" size="16" />
+    Grape @if(chip.selected()){
+    <ga-icon [icon]="icons.CircleX" size="24" />
+    }
+  </ga-chip>
+</ga-chip-listbox>
+```
+
+Custom value comparison
+
+```typescript
+compareUsers(user1: User, user2: User): boolean {
+  return user1.id === user2.id;
+}
+```
+
+```html
+<ga-chip-listbox [value]="selectedUser" [compareWith]="compareUsers">
+  <ga-chip [value]="user1">{{ user1.name }}</ga-chip>
+  <ga-chip [value]="user2">{{ user2.name }}</ga-chip>
+</ga-chip-listbox>
+```