@vsn-ux/ngx-gaia 0.9.13 → 0.9.14

package/DOCS.md

@@ -158,6 +158,100 @@ Selectable card
 </ga-card>
 ```
 
+## 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>
+```
+
 ## Checkbox
 
 Checkbox component for boolean selections.
@@ -286,6 +380,333 @@ Abstract service for converting between external and internal date representatio
 <ga-datepicker #picker></ga-datepicker>
 ```
 
+## Data Select
+
+Data-driven select component that works with arrays of items and provides advanced features like search, multi-select, grouping, and custom templates.
+
+**Angular module: GaDataSelectModule**
+
+### `<ga-data-select>`
+
+Data select component that automatically generates options from an items array.
+
+#### Inputs:
+
+- `items: IGaSelectOption[]` - Array of items to display as options (default: [])
+- `value: any | any[] | null` - Selected value (default: null)
+- `placeholder: string` - Placeholder text (default: '')
+- `multiple: boolean` - Enable multi-select mode (default: false)
+- `disabled: boolean` - Disabled state (default: false)
+- `invalid: boolean | null` - Invalid state styling (default: null)
+- `compareFn: (o1: any, o2: any) => boolean` - Comparison function for object values (default: (a, b) => a === b)
+- `searchable: boolean` - Enable search/filter functionality (default: false)
+- `customFilter: boolean` - Disable built-in filtering for custom implementation (default: false)
+- `clearable: boolean` - Show clear button (default: false)
+- `clearableLabel: string` - Custom label for clear button
+- `noOptionsLabel: string` - Custom message when no options available
+- `canSelectNullable: boolean` - Allow selection of null/undefined/empty values (default: false)
+- `leftIcon: GaIconData` - Icon to display on the left
+- `id: string | null` - Element ID (default: auto-generated)
+- `bindValue: string` - Property path to use as option value
+- `bindLabel: string` - Property path to use as option label
+- `groupBy: string | ((item: IGaSelectOption) => string)` - Property or function for grouping options
+- `loading: boolean` - Show loading spinner (default: false)
+- `withOptionInput: boolean | null` - Show radio/checkbox in options (default: null)
+
+#### Outputs:
+
+- `valueChange(value: any | any[] | null)` - Emitted when value changes
+- `searchValueChange(value: string | null)` - Emitted when search text changes
+- `opened()` - Emitted when dropdown opens
+- `closed()` - Emitted when dropdown closes
+- `optionsEndReached()` - Emitted when user scrolls to bottom of options
+
+### `IGaSelectOption<T>`
+
+Type for option items with special properties:
+
+- `$disabled?: boolean` - Marks option as disabled
+- `$typeaheadLabel?: string` - Custom label for search/typeahead functionality
+
+### `[gaDataSelectValueTpl]`
+
+Directive for customizing the selected value display.
+
+#### Template Context:
+
+- `$implicit` - The label of the selected item
+- `value` - The value of the selected item
+- `item` - The full item object
+
+### `[gaDataSelectOptionTpl]`
+
+Directive for customizing option labels in dropdown.
+
+#### Template Context:
+
+- `$implicit` - The label of the option
+- `value` - The value of the option
+- `item` - The full item object
+
+### `[gaDataSelectOptgroupLabelTpl]`
+
+Directive for customizing optgroup labels.
+
+#### Template Context:
+
+- `$implicit` - The label of the optgroup
+- `label` - The label of the optgroup
+- `items` - Array of items in the group
+
+### GaDataSelectI18n
+
+Service for data-select internationalization.
+
+#### Properties:
+
+- `clearLabel: string` - Label for clear button (default: 'Clear')
+- `searchInputLabel: string` - Accessible label for search input (default: 'Search')
+- `noOptionsLabel: string` - Message when no options available (default: 'No options')
+
+### GaDataSelectRequiredValidator
+
+Built-in required validator for Angular Forms integration.
+
+### Providers:
+
+- `provideGaDataSelectI18n(value: GaDataSelectI18n | (() => GaDataSelectI18n))` - Configure data-select i18n labels
+
+### Examples:
+
+Basic usage with bindValue and bindLabel
+
+```html
+<ga-data-select
+  placeholder="Select an option"
+  [items]="options"
+  bindValue="id"
+  bindLabel="name"
+  [(value)]="selectedId"
+/>
+```
+
+```typescript
+options = [
+  { id: 1, name: 'Option 1' },
+  { id: 2, name: 'Option 2' },
+  { id: 3, name: 'Option 3' },
+];
+selectedId = 1;
+```
+
+Multi-select mode
+
+```html
+<ga-data-select
+  multiple
+  placeholder="Select multiple"
+  [items]="options"
+  [(value)]="selectedValues"
+/>
+```
+
+```typescript
+selectedValues = ['Option 1', 'Option 2'];
+```
+
+Searchable with built-in filtering
+
+```html
+<ga-data-select
+  searchable
+  clearable
+  placeholder="Search and select"
+  [items]="options"
+  bindLabel="name"
+  [(value)]="selected"
+/>
+```
+
+Searchable with custom filtering (server-side)
+
+```html
+<ga-data-select
+  searchable
+  customFilter
+  [items]="filteredOptions.value() ?? []"
+  [loading]="filteredOptions.isLoading()"
+  (searchValueChange)="searchText.set($event)"
+  [(value)]="selected"
+/>
+```
+
+```typescript
+readonly searchText = signal<string | null>(null);
+readonly filteredOptions = rxResource({
+  params: () => ({ searchText: this.searchText() }),
+  stream: ({ params }) => {
+    if (params.searchText === null) {
+      return of([]);
+    }
+    return this.http.get('/api/options', { params });
+  },
+});
+```
+
+Grouped options
+
+```html
+<ga-data-select
+  [items]="options"
+  bindLabel="name"
+  groupBy="category"
+  [(value)]="selected"
+/>
+```
+
+```typescript
+options = [
+  { category: 'Fruits', name: 'Apple' },
+  { category: 'Fruits', name: 'Banana' },
+  { category: 'Vegetables', name: 'Carrot' },
+];
+```
+
+Disabled options
+
+```typescript
+options = [
+  { value: 1, label: 'Option 1' },
+  { value: 2, label: 'Option 2', $disabled: true },
+  { value: 3, label: 'Option 3' },
+];
+```
+
+Custom typeahead labels
+
+```typescript
+options = [
+  {
+    code: 'EMP001',
+    name: 'John Smith',
+    $typeaheadLabel: 'John Smith EMP001',
+  },
+];
+```
+
+Custom value template
+
+```html
+<ga-data-select [items]="options" [(value)]="selected">
+  <ng-template gaDataSelectValueTpl let-label let-item="item">
+    <strong>{{ label }}</strong> - {{ item.description }}
+  </ng-template>
+</ga-data-select>
+```
+
+Custom option label template
+
+```html
+<ga-data-select
+  [items]="options"
+  [(value)]="selected"
+  bindValue="id"
+  bindLabel="name"
+>
+  <ng-template gaDataSelectOptionTpl let-label let-item="item">
+    {{ label }}: {{ item.description }}
+  </ng-template>
+</ga-data-select>
+```
+
+Custom optgroup label template
+
+```html
+<ga-data-select [items]="options" groupBy="group" [(value)]="selected">
+  <ng-template gaDataSelectOptgroupLabelTpl let-label let-items="items">
+    <strong>{{ label }}</strong> ({{ items.length }} items)
+  </ng-template>
+</ga-data-select>
+```
+
+Angular Forms with required validation
+
+```html
+<ga-data-select
+  placeholder="Select value"
+  [items]="options"
+  [(ngModel)]="value"
+  required
+  clearable
+  #ngModel="ngModel"
+/>
+```
+
+With form field
+
+```html
+<ga-form-field>
+  <ga-label>Select Option</ga-label>
+  <ga-data-select
+    placeholder="Choose..."
+    [items]="options"
+    [(ngModel)]="value"
+  />
+</ga-form-field>
+```
+
+Object values with comparison function
+
+```html
+<ga-data-select
+  [items]="options"
+  [compareFn]="compareFn"
+  bindLabel="name"
+  [(value)]="selectedObject"
+/>
+```
+
+```typescript
+options = [
+  { id: 1, name: 'Option 1' },
+  { id: 2, name: 'Option 2' },
+];
+selectedObject = { id: 1, name: 'Option 1' };
+compareFn = (a: any, b: any) => a?.id === b?.id;
+```
+
+Infinite scroll with optionsEndReached
+
+```html
+<ga-data-select
+  [items]="items"
+  [loading]="isLoading"
+  (optionsEndReached)="loadMore()"
+  [(value)]="selected"
+/>
+```
+
+i18n configuration
+
+```typescript
+// Static configuration
+provideGaDataSelectI18n({
+  clearLabel: 'Clear',
+  searchInputLabel: 'Search',
+  noOptionsLabel: 'No results found',
+});
+
+// Factory function with injection context
+provideGaDataSelectI18n(() => {
+  const i18n = inject(MyI18nService);
+  return {
+    clearLabel: i18n.translate('clear'),
+    searchInputLabel: i18n.translate('search'),
+    noOptionsLabel: i18n.translate('no-results'),
+  };
+});
+```
+
 ## Form Field
 
 Form field components for creating accessible form inputs with labels and error handling.
@@ -745,7 +1166,7 @@ Icon buttons
 
 ## Select
 
-Select components for dropdown selections with search and multi-select capabilities.
+Select components for dropdown selections with multi-select capabilities. Use for static selects where all options are loaded upfront.
 
 **Angular module: GaSelectModule**
 
@@ -761,9 +1182,7 @@ Select component.
 - `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>`
 
@@ -828,18 +1247,6 @@ Multi-select
 </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