@egose/shadcn-theme-ng-tw 0.6.0 → 0.6.2

package/searchable-multiselect/README.md

@@ -1,6 +1,6 @@
 # Searchable Multiselect (`@egose/shadcn-theme-ng/searchable-multiselect`)
 
-A shadcn/ui-style **multi-select with chips + popover picker** — selected values render as removable chips, and a popover holds the checkbox option list. There is no exact single shadcn/ui counterpart; it composes the `Popover`, `Button`, and `Checkbox` patterns into one opinionated control.
+A shadcn/ui-style **multi-select with chips + searchable popover picker** — selected values render as named removable chips, and a labeled local search filters the checkbox option list. There is no exact single shadcn/ui counterpart; it composes the `Popover`, `Button`, and `Checkbox` patterns into one opinionated control.
 
 It is a **standalone `ControlValueAccessor` component** (`EgSearchableMultiselect`), so it binds directly to Angular reactive forms (`formControlName`) and template-driven forms (`ngModel`) with a `string[]` value. Internally it reuses `HlmPopover`/`HlmCheckbox`/`HlmButton` — you do not import those yourself.
 
@@ -23,7 +23,7 @@ import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multi
 // import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng-tw/searchable-multiselect';
 ```
 
-Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`. (No `@spartan-ng/brain` peer — popover/checkbox/button come along as regular library dependencies.)
+Peer dependencies include Angular and `@spartan-ng/brain` (`>=1.3.2 <2.0.0`); see the [package README](../../README.md) for the complete peer list and supported versions. The composed popover/checkbox/button implementations are included in the theme package, but their Spartan behavior is supplied by that peer.
 
 ## Imports
 
@@ -64,11 +64,13 @@ Renders (internally — you do not write this yourself):
     <span><!-- {{ placeholder }} or chip {{ item.label }} + ✕ button --></span>
   </div>
 
-  <!-- popover trigger + checkbox list -->
+  <!-- popover trigger + local search + checkbox list -->
   <hlm-popover>
     <button hlmPopoverTrigger hlmButton>N selected</button>
     <hlm-popover-content>
+      <label>Search options <input type="search" /></label>
       <label><!-- <hlm-checkbox> per option + label text --></label>
+      <div role="status" aria-live="polite"><!-- No matching options, when empty --></div>
     </hlm-popover-content>
   </hlm-popover>
 </eg-searchable-multiselect>
@@ -80,25 +82,47 @@ Real selector: `eg-searchable-multiselect` (element). The `✕` chip buttons and
 
 ### EgSearchableMultiselect (component, `ControlValueAccessor`)
 
-| Input                 | Type                  | Default                  | Description                                                                      |
-| --------------------- | --------------------- | ------------------------ | -------------------------------------------------------------------------------- |
-| `options`             | `SelectOption[]`      | `[]`                     | Full option list (`{ label, value }`)                                            |
-| `value`               | `string[]`            | `[]`                     | Selected values (one-way in; pairs with `valueChange` for two-way `[(value)]`)   |
-| `placeholder`         | `string`              | `'Start typing to add…'` | Text of the pill shown when nothing is selected                                  |
-| `id`                  | `string`              | `''`                     | `id` placed on the trigger button                                                |
-| `disabled`            | `boolean`             | `false`                  | Disables chips + trigger + checkboxes                                            |
-| `wrapperDisabled`     | `boolean`             | `false`                  | Second disable flag (e.g. set by wrapper form components); OR-ed with `disabled` |
-| `ariaLabel`           | `string \| undefined` | `undefined`              | `aria-label` for the trigger button                                              |
-| `ariaDescribedby`     | `string \| null`      | `null`                   | `aria-describedby` for the trigger button                                        |
-| `class` (`userClass`) | `ClassValue`          | `''`                     | Extra classes on the host                                                        |
-
-| Output        | Type       | Description                                          |
-| ------------- | ---------- | ---------------------------------------------------- |
-| `valueChange` | `string[]` | Emitted with the new value array on every add/remove |
+| Input                 | Type                  | Default                  | Description                                                                                           |
+| --------------------- | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `options`             | `SelectOption[]`      | `[]`                     | Full option list (`{ label, value }`)                                                                 |
+| `value`               | `string[]`            | `[]`                     | Standalone selected IDs; pairs with `valueChange` for `[(value)]`. Ignored after the first CVA write. |
+| `placeholder`         | `string`              | `'Start typing to add…'` | Text of the pill shown when nothing is selected                                                       |
+| `id`                  | `string`              | `''`                     | `id` placed on the trigger button                                                                     |
+| `disabled`            | `boolean`             | `false`                  | Disables chips + trigger + search + checkboxes                                                        |
+| `wrapperDisabled`     | `boolean`             | `false`                  | Second disable flag (e.g. set by wrapper form components); OR-ed with `disabled`                      |
+| `ariaLabel`           | `string \| undefined` | `undefined`              | `aria-label` for the trigger button                                                                   |
+| `ariaDescribedby`     | `string \| null`      | `null`                   | `aria-describedby` for the trigger button                                                             |
+| `class` (`userClass`) | `ClassValue`          | `''`                     | Extra classes on the host                                                                             |
+
+| Output        | Type       | Description                                                      |
+| ------------- | ---------- | ---------------------------------------------------------------- |
+| `valueChange` | `string[]` | Emitted with a new value array on each effective user add/remove |
 
 `ControlValueAccessor` contract: `writeValue(values)`, `registerOnChange`, `registerOnTouched`, `setDisabledState` are implemented, so `formControl` / `formControlName` / `ngModel` all work. Effective disabled state = `disabled() \|\| wrapperDisabled() \|\| formDisabled()` (the last set by forms via `setDisabledState`).
 
-API surprise worth knowing: despite the "searchable" name, the current template ships **no filter text field** — the popover shows the full checkbox list and empty state reads "No options". Treat `options` as the complete visible list (filter it yourself before passing it in if you need search). Also `value` is a plain `input`, not a `model`: form writes flow through `writeValue`, and user edits flow out through `valueChange` + the CVA `onChange` callback.
+`value` is a plain `input`, not a `model`: form writes flow through `writeValue`, and user edits flow out through `valueChange` + the CVA `onChange` callback.
+
+### Local search
+
+Additional copy inputs:
+
+- `searchLabel: string` (default `'Search options'`): visible, associated native search label; supply nonempty localized text.
+- `searchPlaceholder: string` (default `'Type to filter…'`): search input hint, separate from the empty-selection pill.
+- `emptyMessage: string` (default `'No matching options'`): polite live-region copy for no matches or no supplied options.
+- `removeLabel: (option: SelectOption) => string` (default ``option => `Remove ${option.label}` ``): pure formatter for each chip button's accessible name; unresolved labels are raw IDs.
+
+Pass the complete `options` list. The native search field trims the query and performs case-insensitive substring matching on **labels**, retaining source order. An empty/whitespace query restores all choices. Search is local to the supplied list: it does not search IDs, fetch remote options, or virtualize results. New option arrays and label replacements recompute the current filter immediately.
+
+Filtering hides checkbox rows only. All selections, including unresolved IDs, remain selected; chip labels still resolve from the complete options list. Search edits never emit `valueChange`/CVA changes or mark touched. The query persists across close/reopen and external value writes/resets; clear its text to restore all choices. The empty message occupies a persistent polite status region while the popover is open.
+
+### Selection ownership and asynchronous options
+
+- **Standalone:** `[value]` initializes selection, and each new input array replaces it (including `[]` to clear). User edits update the displayed selection immediately and emit `valueChange`; `[(value)]` keeps the parent synchronized. With one-way binding, local edits persist until a new input array arrives.
+- **Angular forms:** the first `writeValue` takes ownership for the component's lifetime. Subsequent `[value]` changes are ignored; use `formControl`, `formControlName`, or `ngModel` as the source of truth. Every form write replaces selection; `null` and `[]` clear it, including resets.
+- Selected IDs are stored independently of `options`, in value-array order. Unresolved IDs render as removable chips labeled with the raw ID and count toward the selected total. When options arrive or labels change, chips update automatically. When an option disappears, its chip falls back to the ID. Adding/removing another option never discards these unresolved IDs; explicitly remove their chips or write a replacement value to clear them.
+- External input/form writes and option updates never emit `valueChange`, call CVA `onChange`, or mark touched. Effective user adds/removes emit once per channel and call `onTouched`. Opening/focusing the picker alone does not mark touched; duplicate adds and absent removals are no-ops.
+- Disabled state combines the input, wrapper, and form flags. It blocks trigger/chip/search/checkbox edits, including when disabled with the panel open, while still accepting external value and option updates.
+- Input arrays and option objects are never mutated. Output and CVA callbacks receive separate fresh arrays. Supply unique selected IDs and unique option values, and replace arrays/option objects rather than mutating them in place so signal updates are observed.
 
 ## Examples
 
@@ -224,47 +248,44 @@ export class DisabledMultiComponent {
 
 Disabling via `formControl.disable()` works too — it flows through `setDisabledState`.
 
-### 5. Client-side search (filter `options` yourself)
+### 5. Local search with configurable copy
 
-Since the popover lists exactly what you pass in `options`, implement search by filtering upstream:
+Supply all options so hidden selections retain their labels:
 
 ```ts
-import { Component, computed, signal } from '@angular/core';
-import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multiselect';
+import { Component, signal } from '@angular/core';
+import { EgSearchableMultiselect, type SelectOption } from '@egose/shadcn-theme-ng/searchable-multiselect';
 
 @Component({
   selector: 'app-search-multi',
   standalone: true,
   imports: [EgSearchableMultiselect],
   template: `
-    <input
-      type="search"
-      placeholder="Filter options…"
-      [value]="query()"
-      (input)="query.set($any($event.target).value)"
-      aria-label="Filter options"
+    <eg-searchable-multiselect
+      [options]="frameworks"
+      [(value)]="selected"
+      ariaLabel="Framework assignments"
+      searchLabel="Find frameworks"
+      searchPlaceholder="Type a framework name…"
+      emptyMessage="No frameworks match your search"
+      [removeLabel]="removeFrameworkLabel"
     />
-    <eg-searchable-multiselect [options]="filtered()" [(value)]="selected" />
   `,
 })
 export class SearchMultiComponent {
-  readonly query = signal('');
   readonly selected = signal<string[]>([]);
-  private readonly all = [
+  readonly removeFrameworkLabel = (option: SelectOption) => `Unassign ${option.label}`;
+  readonly frameworks: SelectOption[] = [
     { label: 'Angular', value: 'angular' },
     { label: 'React', value: 'react' },
     { label: 'Vue', value: 'vue' },
     { label: 'Svelte', value: 'svelte' },
     { label: 'Solid', value: 'solid' },
   ];
-  readonly filtered = computed(() => {
-    const q = this.query().trim().toLowerCase();
-    return q ? this.all.filter((o) => o.label.toLowerCase().includes(q)) : this.all;
-  });
 }
 ```
 
-Note: selections whose option is currently filtered out stay selected internally (chips still show) but have no checkbox row until the filter matches again. Unknown values passed via `value`/`writeValue` that match no option are dropped from the chip row.
+The form wrapper `EgFormSearchableMultiselect` forwards the same `searchLabel`, `searchPlaceholder`, `emptyMessage`, and `removeLabel` inputs. For localization, the remove formatter receives the current label and value, so it can include an ID to distinguish duplicate display names.
 
 ### 6. Async options + reacting to changes
 
@@ -308,9 +329,10 @@ export class AsyncMultiComponent {
 ## Accessibility notes
 
 - The trigger is a real `<button>` — give it an accessible name via `ariaLabel` (or a visible `<label>` paired with `id`) and descriptions via `ariaDescribedby`.
-- Options render as native checkbox-backed `hlm-checkbox` rows inside `<label>` elements, so they are keyboard-operable and announced per option.
-- Chip `✕` buttons are real buttons and disabled along with the control; keep chip text concise so screen readers announce removals cleanly.
-- The empty state is a plain text pill (not focusable) — the popover trigger remains the single keyboard entry point, which keeps tab order simple.
+- Open the trigger with Enter/Space. With the default popover focus configuration, focus moves to the labeled native search field. Type to filter, clear the text to restore choices, and Tab/Shift+Tab among controls. Enter in search does not submit a surrounding form. Escape closes the popover and restores trigger focus.
+- Options use native buttons with checkbox roles inside `<label>` elements. Use Space/Enter to toggle a focused choice.
+- Chip `✕` buttons are named `Remove <label>` by default (`Remove <ID>` when unresolved); customize with `removeLabel`. They are disabled along with the control.
+- No matches (including an empty options list) displays `emptyMessage` in a polite, atomic status region. The search remains editable when there are no results. Browser DOM/focus tests verify these contracts; they do not constitute screen-reader testing.
 
 ## Theming / CSS variables
 

package/searchable-multiselect/fesm2022/searchable-multiselect.mjs

@@ -1,17 +1,34 @@
 import * as i0 from '@angular/core';
-import { input, output, signal, computed, forwardRef, ChangeDetectionStrategy, Component } from '@angular/core';
+import { input, output, signal, linkedSignal, computed, forwardRef, ChangeDetectionStrategy, Component } from '@angular/core';
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import { HlmPopover, HlmPopoverTrigger, HlmPopoverContent, HlmPopoverPortal } from '@egose/shadcn-theme-ng-tw/popover';
 import { HlmButton } from '@egose/shadcn-theme-ng-tw/button';
 import { HlmCheckbox } from '@egose/shadcn-theme-ng-tw/checkbox';
 import { hlm } from '@egose/shadcn-theme-ng-tw/utils';
 
+/**
+ * Chip multiselect with local, case-insensitive label search over the complete options input.
+ * Filtering never changes selected IDs or chip labels. Search edits do not emit or touch the form.
+ * Import from `@egose/shadcn-theme-ng-tw/searchable-multiselect` (or the `-tw` variant).
+ */
 class EgSearchableMultiselect {
     /** Full option list with labels/values */
     options = input([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     placeholder = input('Start typing to add…', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /** Visible, associated label for the native search field; provide nonempty localized text. */
+    searchLabel = input('Search options', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "searchLabel" }] : /* istanbul ignore next */ []));
+    /** Search field hint, independent of the empty-selection chip placeholder. */
+    searchPlaceholder = input('Type to filter…', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "searchPlaceholder" }] : /* istanbul ignore next */ []));
+    /** Polite live-region message when no supplied option labels match, including an empty options list. */
+    emptyMessage = input('No matching options', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "emptyMessage" }] : /* istanbul ignore next */ []));
+    /** Accessible remove name from the current chip label (raw ID when unresolved). Supply a pure formatter. */
+    removeLabel = input((option) => `Remove ${option.label}`, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "removeLabel" }] : /* istanbul ignore next */ []));
     id = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "id" }] : /* istanbul ignore next */ []));
     disabled = input(false, /* @ts-ignore */
@@ -23,21 +40,42 @@ class EgSearchableMultiselect {
     ariaDescribedby = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "ariaDescribedby" }] : /* istanbul ignore next */ []));
     userClass = input('', { ...(ngDevMode ? { debugName: "userClass" } : /* istanbul ignore next */ {}), alias: 'class' });
-    /** Value: array of selected values (string[]) */
+    /** Standalone selected IDs. New input arrays replace local edits; ignored after the first CVA writeValue. */
     value = input([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
+    /** User selection changes only; external input/CVA writes and option updates do not emit. */
     valueChange = output();
-    selectedItems = signal([], /* @ts-ignore */
+    // Undefined means standalone ownership; even a null CVA write takes form ownership with an empty array.
+    formValue = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "formValue" }] : /* istanbul ignore next */ []));
+    selectedValues = linkedSignal(() => [...(this.formValue() ?? this.value())], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "selectedValues" }] : /* istanbul ignore next */ []));
+    selectedItems = computed(() => {
+        const options = new Map(this.options().map((option) => [option.value, option]));
+        return this.selectedValues().map((value) => options.get(value) ?? { value, label: value });
+    }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "selectedItems" }] : /* istanbul ignore next */ []));
     formDisabled = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "formDisabled" }] : /* istanbul ignore next */ []));
     disabledState = computed(() => this.disabled() || this.wrapperDisabled() || this.formDisabled(), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "disabledState" }] : /* istanbul ignore next */ []));
-    isFormBound = false;
+    // Local UI state persists across popover closes and external writes; it never owns selection.
+    searchQuery = signal('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "searchQuery" }] : /* istanbul ignore next */ []));
+    filteredOptions = computed(() => {
+        const query = this.searchQuery().trim().toLowerCase();
+        return this.options().filter((option) => option.label.toLowerCase().includes(query));
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "filteredOptions" }] : /* istanbul ignore next */ []));
     _hostClass = computed(() => hlm(this.userClass()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_hostClass" }] : /* istanbul ignore next */ []));
+    updateSearch(query) {
+        if (this.disabledState())
+            return;
+        this.searchQuery.set(query);
+    }
     isSelected(value) {
-        return this.selectedItems().some((s) => s.value === value);
+        return this.selectedValues().includes(value);
     }
     toggle(value, checked) {
         if (this.disabledState())
@@ -50,40 +88,29 @@ class EgSearchableMultiselect {
         }
     }
     addItem(value) {
-        if (!this.selectedItems().some((s) => s.value === value)) {
-            const opt = this.options()?.find((o) => o.value === value);
-            if (!opt)
-                return;
-            const updated = [...this.selectedItems(), opt];
-            this.updateValueFromSelected(updated);
-        }
+        if (this.disabledState() || this.isSelected(value) || !this.options().some((option) => option.value === value))
+            return;
+        this.updateValueFromSelected([...this.selectedValues(), value]);
     }
     removeItem(value) {
-        if (this.disabledState())
+        if (this.disabledState() || !this.isSelected(value))
             return;
-        const updated = this.selectedItems().filter((i) => i.value !== value);
+        const updated = this.selectedValues().filter((selected) => selected !== value);
         this.updateValueFromSelected(updated);
     }
-    updateSelectedFromValues(values) {
-        const opts = this.options() || [];
-        this.selectedItems.set(opts.filter((o) => values.includes(o.value)));
-    }
-    updateValueFromSelected(items) {
-        this.selectedItems.set(items);
-        const values = items.map((i) => i.value);
-        this.valueChange.emit(values);
-        this.onChange(values);
+    updateValueFromSelected(values) {
+        this.selectedValues.set(values);
+        // Neither consumer channel owns the internal array or the other channel's payload.
+        this.valueChange.emit([...values]);
+        this.onChange([...values]);
         this.onTouched();
     }
-    constructor() {
-        // No effect needed; we read `value` input directly via writeValue for form-bound usage.
-    }
     // --- ControlValueAccessor ---
     onChange = () => { };
     onTouched = () => { };
+    /** Takes CVA ownership, retaining all IDs independently of options. Null clears; never emits or touches. */
     writeValue(values) {
-        this.isFormBound = true;
-        this.updateSelectedFromValues(values || []);
+        this.formValue.set([...(values ?? [])]);
     }
     registerOnChange(fn) {
         this.onChange = fn;
@@ -95,7 +122,7 @@ class EgSearchableMultiselect {
         this.formDisabled.set(isDisabled);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgSearchableMultiselect, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: EgSearchableMultiselect, isStandalone: true, selector: "eg-searchable-multiselect", inputs: { options: { classPropertyName: "options", publicName: "options", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, wrapperDisabled: { classPropertyName: "wrapperDisabled", publicName: "wrapperDisabled", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "ariaDescribedby", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { valueChange: "valueChange" }, host: { properties: { "class": "_hostClass()" } }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: EgSearchableMultiselect, isStandalone: true, selector: "eg-searchable-multiselect", inputs: { options: { classPropertyName: "options", publicName: "options", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, searchLabel: { classPropertyName: "searchLabel", publicName: "searchLabel", isSignal: true, isRequired: false, transformFunction: null }, searchPlaceholder: { classPropertyName: "searchPlaceholder", publicName: "searchPlaceholder", isSignal: true, isRequired: false, transformFunction: null }, emptyMessage: { classPropertyName: "emptyMessage", publicName: "emptyMessage", isSignal: true, isRequired: false, transformFunction: null }, removeLabel: { classPropertyName: "removeLabel", publicName: "removeLabel", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, wrapperDisabled: { classPropertyName: "wrapperDisabled", publicName: "wrapperDisabled", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "ariaDescribedby", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { valueChange: "valueChange" }, host: { properties: { "class": "_hostClass()" } }, providers: [
             {
                 provide: NG_VALUE_ACCESSOR,
                 useExisting: forwardRef(() => EgSearchableMultiselect),
@@ -122,6 +149,7 @@ class EgSearchableMultiselect {
               <button
                 type="button"
                 [disabled]="disabledState()"
+                [attr.aria-label]="removeLabel()(item)"
                 (click)="removeItem(item.value)"
                 class="tw:bg-transparent tw:border-0 tw:text-gray-600
                        tw:hover:text-red-500 tw:cursor-pointer"
@@ -150,8 +178,21 @@ class EgSearchableMultiselect {
         </button>
 
         <hlm-popover-content class="tw:w-64 tw:p-2" *hlmPopoverPortal="let ctx">
+          <label class="tw:flex tw:flex-col tw:gap-1 tw:text-sm">
+            <span>{{ searchLabel() }}</span>
+            <input
+              #search
+              type="search"
+              [value]="searchQuery()"
+              [placeholder]="searchPlaceholder()"
+              [disabled]="disabledState()"
+              (input)="updateSearch(search.value)"
+              (keydown.enter)="$event.preventDefault()"
+              class="tw:w-full tw:rounded-md tw:border tw:border-input tw:bg-transparent tw:px-2 tw:py-1 tw:outline-none tw:focus-visible:ring-2 tw:focus-visible:ring-ring tw:disabled:opacity-50"
+            />
+          </label>
           <div class="tw:max-h-60 tw:overflow-auto tw:flex tw:flex-col tw:gap-1">
-            @for (option of options(); track option.value) {
+            @for (option of filteredOptions(); track option.value) {
               <label
                 class="tw:flex tw:items-center tw:gap-2 tw:cursor-pointer tw:px-2 tw:py-1 tw:rounded-sm tw:hover:bg-secondary"
               >
@@ -162,8 +203,11 @@ class EgSearchableMultiselect {
                 />
                 <span class="tw:text-sm">{{ option.label }}</span>
               </label>
-            } @empty {
-              <span class="tw:text-xs tw:text-muted-foreground tw:px-2 tw:py-1">No options</span>
+            }
+          </div>
+          <div role="status" aria-live="polite" aria-atomic="true" class="tw:text-xs tw:text-muted-foreground">
+            @if (filteredOptions().length === 0) {
+              {{ emptyMessage() }}
             }
           </div>
         </hlm-popover-content>
@@ -209,6 +253,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
               <button
                 type="button"
                 [disabled]="disabledState()"
+                [attr.aria-label]="removeLabel()(item)"
                 (click)="removeItem(item.value)"
                 class="tw:bg-transparent tw:border-0 tw:text-gray-600
                        tw:hover:text-red-500 tw:cursor-pointer"
@@ -237,8 +282,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
         </button>
 
         <hlm-popover-content class="tw:w-64 tw:p-2" *hlmPopoverPortal="let ctx">
+          <label class="tw:flex tw:flex-col tw:gap-1 tw:text-sm">
+            <span>{{ searchLabel() }}</span>
+            <input
+              #search
+              type="search"
+              [value]="searchQuery()"
+              [placeholder]="searchPlaceholder()"
+              [disabled]="disabledState()"
+              (input)="updateSearch(search.value)"
+              (keydown.enter)="$event.preventDefault()"
+              class="tw:w-full tw:rounded-md tw:border tw:border-input tw:bg-transparent tw:px-2 tw:py-1 tw:outline-none tw:focus-visible:ring-2 tw:focus-visible:ring-ring tw:disabled:opacity-50"
+            />
+          </label>
           <div class="tw:max-h-60 tw:overflow-auto tw:flex tw:flex-col tw:gap-1">
-            @for (option of options(); track option.value) {
+            @for (option of filteredOptions(); track option.value) {
               <label
                 class="tw:flex tw:items-center tw:gap-2 tw:cursor-pointer tw:px-2 tw:py-1 tw:rounded-sm tw:hover:bg-secondary"
               >
@@ -249,8 +307,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
                 />
                 <span class="tw:text-sm">{{ option.label }}</span>
               </label>
-            } @empty {
-              <span class="tw:text-xs tw:text-muted-foreground tw:px-2 tw:py-1">No options</span>
+            }
+          </div>
+          <div role="status" aria-live="polite" aria-atomic="true" class="tw:text-xs tw:text-muted-foreground">
+            @if (filteredOptions().length === 0) {
+              {{ emptyMessage() }}
             }
           </div>
         </hlm-popover-content>
@@ -258,7 +319,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     </div>
   `,
                 }]
-        }], ctorParameters: () => [], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], wrapperDisabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "wrapperDisabled", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], ariaDescribedby: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaDescribedby", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], valueChange: [{ type: i0.Output, args: ["valueChange"] }] } });
+        }], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], searchLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "searchLabel", required: false }] }], searchPlaceholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "searchPlaceholder", required: false }] }], emptyMessage: [{ type: i0.Input, args: [{ isSignal: true, alias: "emptyMessage", required: false }] }], removeLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "removeLabel", required: false }] }], id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], wrapperDisabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "wrapperDisabled", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], ariaDescribedby: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaDescribedby", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], valueChange: [{ type: i0.Output, args: ["valueChange"] }] } });
 
 /*
  * Public API Surface of searchable-multiselect

package/searchable-multiselect/types/searchable-multiselect.d.ts

@@ -6,39 +6,56 @@ interface SelectOption {
     label: string;
     value: string;
 }
+/**
+ * Chip multiselect with local, case-insensitive label search over the complete options input.
+ * Filtering never changes selected IDs or chip labels. Search edits do not emit or touch the form.
+ * Import from `@egose/shadcn-theme-ng-tw/searchable-multiselect` (or the `-tw` variant).
+ */
 declare class EgSearchableMultiselect implements ControlValueAccessor {
     /** Full option list with labels/values */
     options: _angular_core.InputSignal<SelectOption[]>;
     placeholder: _angular_core.InputSignal<string>;
+    /** Visible, associated label for the native search field; provide nonempty localized text. */
+    searchLabel: _angular_core.InputSignal<string>;
+    /** Search field hint, independent of the empty-selection chip placeholder. */
+    searchPlaceholder: _angular_core.InputSignal<string>;
+    /** Polite live-region message when no supplied option labels match, including an empty options list. */
+    emptyMessage: _angular_core.InputSignal<string>;
+    /** Accessible remove name from the current chip label (raw ID when unresolved). Supply a pure formatter. */
+    removeLabel: _angular_core.InputSignal<(option: SelectOption) => string>;
     id: _angular_core.InputSignal<string>;
     disabled: _angular_core.InputSignal<boolean>;
     wrapperDisabled: _angular_core.InputSignal<boolean>;
     ariaLabel: _angular_core.InputSignal<string | undefined>;
     ariaDescribedby: _angular_core.InputSignal<string | null>;
     userClass: _angular_core.InputSignal<ClassValue>;
-    /** Value: array of selected values (string[]) */
+    /** Standalone selected IDs. New input arrays replace local edits; ignored after the first CVA writeValue. */
     value: _angular_core.InputSignal<string[]>;
+    /** User selection changes only; external input/CVA writes and option updates do not emit. */
     valueChange: _angular_core.OutputEmitterRef<string[]>;
-    protected readonly selectedItems: _angular_core.WritableSignal<SelectOption[]>;
+    private readonly formValue;
+    private readonly selectedValues;
+    protected readonly selectedItems: _angular_core.Signal<SelectOption[]>;
     protected readonly formDisabled: _angular_core.WritableSignal<boolean>;
     protected readonly disabledState: _angular_core.Signal<boolean>;
-    private isFormBound;
+    protected readonly searchQuery: _angular_core.WritableSignal<string>;
+    protected readonly filteredOptions: _angular_core.Signal<SelectOption[]>;
     protected readonly _hostClass: _angular_core.Signal<string>;
+    protected updateSearch(query: string): void;
     protected isSelected(value: string): boolean;
     protected toggle(value: string, checked: boolean): void;
     protected addItem(value: string): void;
     protected removeItem(value: string): void;
-    private updateSelectedFromValues;
     private updateValueFromSelected;
-    constructor();
     private onChange;
     private onTouched;
+    /** Takes CVA ownership, retaining all IDs independently of options. Null clears; never emits or touches. */
     writeValue(values: string[] | null): void;
     registerOnChange(fn: (value: string[]) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<EgSearchableMultiselect, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EgSearchableMultiselect, "eg-searchable-multiselect", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "wrapperDisabled": { "alias": "wrapperDisabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "ariaDescribedby"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EgSearchableMultiselect, "eg-searchable-multiselect", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "searchLabel": { "alias": "searchLabel"; "required": false; "isSignal": true; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "removeLabel": { "alias": "removeLabel"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "wrapperDisabled": { "alias": "wrapperDisabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "ariaDescribedby"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }
 
 export { EgSearchableMultiselect };

package/slider/fesm2022/slider.mjs

@@ -1,18 +1,22 @@
 import * as i0 from '@angular/core';
-import { ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
+import { inject, input, ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
+import { BrnFieldControl, BrnFieldControlDescribedBy } from '@spartan-ng/brain/field';
 import * as i1 from '@spartan-ng/brain/slider';
 import { injectBrnSlider, BrnSlider, BrnSliderImports } from '@spartan-ng/brain/slider';
 import { classes } from '@egose/shadcn-theme-ng-tw/utils';
 
 class HlmSlider {
     _slider = injectBrnSlider();
+    _fieldControl = inject(BrnFieldControl);
+    /** Description IDs applied to every thumb, merged with enclosing Spartan field descriptions. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
     constructor() {
         classes(() => [
             'tw:group tw:flex tw:w-full tw:touch-none tw:flex-col tw:select-none tw:data-[orientation=vertical]:h-full tw:data-[orientation=vertical]:min-h-40 tw:data-[orientation=vertical]:w-auto tw:data-[orientation=vertical]:flex-row tw:data-[disabled]:pointer-events-none tw:data-[disabled]:opacity-50',
         ]);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSlider, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmSlider, isStandalone: true, selector: "hlm-slider, brn-slider [hlm]", hostDirectives: [{ directive: i1.BrnSlider, inputs: ["id", "id", "value", "value", "disabled", "disabled", "min", "min", "max", "max", "step", "step", "minStepsBetweenThumbs", "minStepsBetweenThumbs", "inverted", "inverted", "orientation", "orientation", "showTicks", "showTicks", "maxTicks", "maxTicks", "tickLabelInterval", "tickLabelInterval", "formatTick", "formatTick", "draggableRange", "draggableRange", "draggableRangeOnly", "draggableRangeOnly", "aria-label", "aria-label", "aria-labelledby", "aria-labelledby"], outputs: ["valueChange", "valueChange"] }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmSlider, isStandalone: true, selector: "hlm-slider, brn-slider [hlm]", inputs: { ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null } }, hostDirectives: [{ directive: i1.BrnSlider, inputs: ["id", "id", "value", "value", "disabled", "disabled", "min", "min", "max", "max", "step", "step", "minStepsBetweenThumbs", "minStepsBetweenThumbs", "inverted", "inverted", "orientation", "orientation", "showTicks", "showTicks", "maxTicks", "maxTicks", "tickLabelInterval", "tickLabelInterval", "formatTick", "formatTick", "draggableRange", "draggableRange", "draggableRangeOnly", "draggableRangeOnly", "aria-label", "aria-label", "aria-labelledby", "aria-labelledby"], outputs: ["valueChange", "valueChange"] }], ngImport: i0, template: `
     <div
       class="tw:relative tw:flex tw:w-full tw:items-center tw:group-data-[orientation=vertical]:w-auto tw:group-data-[orientation=vertical]:flex-col"
     >
@@ -30,6 +34,9 @@ class HlmSlider {
         <span
           class="tw:border-primary tw:ring-ring/50 tw:size-4 tw:rounded-full tw:border tw:bg-white tw:shadow-sm tw:transition-[color,box-shadow] tw:hover:ring-4 tw:focus-visible:ring-4 tw:focus-visible:outline-hidden tw:absolute tw:block tw:shrink-0 tw:select-none tw:after:absolute tw:after:-inset-2"
           brnSliderThumb
+          brnFieldControlDescribedBy
+          [aria-describedby]="ariaDescribedBy()"
+          [attr.aria-invalid]="_fieldControl.invalid() ? 'true' : null"
         ></span>
       }
     </div>
@@ -49,13 +56,13 @@ class HlmSlider {
         </div>
       </div>
     }
-  `, isInline: true, dependencies: [{ kind: "directive", type: i1.BrnSliderTrack, selector: "[brnSliderTrack]" }, { kind: "directive", type: i1.BrnSliderThumb, selector: "[brnSliderThumb]" }, { kind: "directive", type: i1.BrnSliderRange, selector: "[brnSliderRange]" }, { kind: "directive", type: i1.BrnSliderTick, selector: "[brnSliderTick]" }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, dependencies: [{ kind: "directive", type: i1.BrnSliderTrack, selector: "[brnSliderTrack]" }, { kind: "directive", type: i1.BrnSliderThumb, selector: "[brnSliderThumb]" }, { kind: "directive", type: i1.BrnSliderRange, selector: "[brnSliderRange]" }, { kind: "directive", type: i1.BrnSliderTick, selector: "[brnSliderTick]" }, { kind: "directive", type: BrnFieldControlDescribedBy, selector: "[brnFieldControlDescribedBy]", inputs: ["aria-describedby"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSlider, decorators: [{
             type: Component,
             args: [{
                     selector: 'hlm-slider, brn-slider [hlm]',
-                    imports: [BrnSliderImports],
+                    imports: [BrnSliderImports, BrnFieldControlDescribedBy],
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     hostDirectives: [
                         {
@@ -100,6 +107,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
         <span
           class="tw:border-primary tw:ring-ring/50 tw:size-4 tw:rounded-full tw:border tw:bg-white tw:shadow-sm tw:transition-[color,box-shadow] tw:hover:ring-4 tw:focus-visible:ring-4 tw:focus-visible:outline-hidden tw:absolute tw:block tw:shrink-0 tw:select-none tw:after:absolute tw:after:-inset-2"
           brnSliderThumb
+          brnFieldControlDescribedBy
+          [aria-describedby]="ariaDescribedBy()"
+          [attr.aria-invalid]="_fieldControl.invalid() ? 'true' : null"
         ></span>
       }
     </div>
@@ -121,7 +131,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     }
   `,
                 }]
-        }], ctorParameters: () => [] });
+        }], ctorParameters: () => [], propDecorators: { ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }] } });
 
 /*
  * Public API Surface of slider

package/slider/types/slider.d.ts

@@ -1,12 +1,16 @@
+import * as i0 from '@angular/core';
+import { BrnFieldControl } from '@spartan-ng/brain/field';
 import * as i1 from '@spartan-ng/brain/slider';
 import { BrnSlider } from '@spartan-ng/brain/slider';
-import * as i0 from '@angular/core';
 
 declare class HlmSlider {
     protected readonly _slider: BrnSlider;
+    protected readonly _fieldControl: BrnFieldControl;
+    /** Description IDs applied to every thumb, merged with enclosing Spartan field descriptions. */
+    readonly ariaDescribedBy: i0.InputSignal<string | null>;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmSlider, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<HlmSlider, "hlm-slider, brn-slider [hlm]", never, {}, {}, never, never, true, [{ directive: typeof i1.BrnSlider; inputs: { "id": "id"; "value": "value"; "disabled": "disabled"; "min": "min"; "max": "max"; "step": "step"; "minStepsBetweenThumbs": "minStepsBetweenThumbs"; "inverted": "inverted"; "orientation": "orientation"; "showTicks": "showTicks"; "maxTicks": "maxTicks"; "tickLabelInterval": "tickLabelInterval"; "formatTick": "formatTick"; "draggableRange": "draggableRange"; "draggableRangeOnly": "draggableRangeOnly"; "aria-label": "aria-label"; "aria-labelledby": "aria-labelledby"; }; outputs: { "valueChange": "valueChange"; }; }]>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HlmSlider, "hlm-slider, brn-slider [hlm]", never, { "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.BrnSlider; inputs: { "id": "id"; "value": "value"; "disabled": "disabled"; "min": "min"; "max": "max"; "step": "step"; "minStepsBetweenThumbs": "minStepsBetweenThumbs"; "inverted": "inverted"; "orientation": "orientation"; "showTicks": "showTicks"; "maxTicks": "maxTicks"; "tickLabelInterval": "tickLabelInterval"; "formatTick": "formatTick"; "draggableRange": "draggableRange"; "draggableRangeOnly": "draggableRangeOnly"; "aria-label": "aria-label"; "aria-labelledby": "aria-labelledby"; }; outputs: { "valueChange": "valueChange"; }; }]>;
 }
 
 declare const HlmSliderImports: readonly [typeof HlmSlider];