@egose/shadcn-theme-ng-tw 0.1.0 → 0.2.0

package/scroll-area/README.md

@@ -1,11 +1,239 @@
-# ScrollArea
+# Scroll Area (`@egose/shadcn-theme-ng/scroll-area`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A shadcn/ui-style **Scroll Area** — a themed scrollable container with hover-reveal scrollbars. This is the Angular equivalent of shadcn/ui `ScrollArea`.
 
-## Building
+Unlike most subpaths in this library it is **not** built on spartan-ng/brain: it is a thin directive wrapper over `NgScrollbar` from **ngx-scrollbar**. The directive matches `ng-scrollbar[hlm]` (or `ng-scrollbar[hlmScrollbar]`), forces `visibility: 'hover'` scrollbar options, and pins the shadcn scrollbar CSS variables (thumb color, track color/thickness) so every scroll area looks consistent with the theme.
 
-To build the library, run:
+> **Ships as:** `@egose/shadcn-theme-ng/scroll-area` and `@egose/shadcn-theme-ng-tw/scroll-area` (the `tw:`-prefixed Tailwind variant — same API, class strings prefixed with `tw:`).
+> See the [package README](../../README.md) for installation, peer dependencies, and Tailwind setup. Do not publish this project directory independently.
+
+## Installation
 
 ```bash
-ng build scroll-area
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+```ts
+import { HlmScrollAreaImports } from '@egose/shadcn-theme-ng/scroll-area';
+// tw variant:
+// import { HlmScrollAreaImports } from '@egose/shadcn-theme-ng-tw/scroll-area';
 ```
+
+Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`, `@spartan-ng/brain`. Runtime `ngx-scrollbar` is installed transitively — but note you must import `NgScrollbar` itself (from `ngx-scrollbar`) wherever you use the directive, since this package only provides the `hlm` styling layer.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+| Symbol                 | Kind          | Description                                                                                       |
+| ---------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
+| `HlmScrollArea`        | Directive     | Styling/behavior layer for `NgScrollbar`; selector `ng-scrollbar[hlm],ng-scrollbar[hlmScrollbar]` |
+| `HlmScrollAreaImports` | `const` array | `[HlmScrollArea]` standalone imports                                                              |
+| `HlmScrollAreaModule`  | `NgModule`    | NgModule wrapper re-exporting `HlmScrollArea`                                                     |
+
+Standalone usage (you almost always pair it with `NgScrollbar`):
+
+```ts
+import { Component } from '@angular/core';
+import { NgScrollbar } from 'ngx-scrollbar';
+import { HlmScrollAreaImports } from '@egose/shadcn-theme-ng/scroll-area';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [NgScrollbar, HlmScrollAreaImports],
+  template: ` <ng-scrollbar hlm class="tw:h-64"> ... </ng-scrollbar> `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { NgScrollbar } from 'ngx-scrollbar';
+import { HlmScrollAreaModule } from '@egose/shadcn-theme-ng/scroll-area';
+
+@NgModule({ imports: [NgScrollbar, HlmScrollAreaModule] })
+export class DemoModule {}
+```
+
+## Anatomy / Structure
+
+```html
+<ng-scrollbar hlm class="tw:h-72 tw:w-80 tw:rounded-md tw:border">
+  <div class="tw:p-4">
+    <h4>Title</h4>
+    <p>Scrollable content…</p>
+  </div>
+</ng-scrollbar>
+```
+
+Real selectors:
+
+| Selector                                          | Class           | Notes                                                                                                    |
+| ------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| `ng-scrollbar[hlm]`, `ng-scrollbar[hlmScrollbar]` | `HlmScrollArea` | `data-slot="scroll-area"`; requires the `NgScrollbar` component from `ngx-scrollbar` as the host element |
+
+The directive sets these host bindings: `--scrollbar-thumb-color` and `--scrollbar-thumb-hover-color` to `var(--border)`, `--scrollbar-track-color: transparent`, `--scrollbar-track-thickness: 0.625rem`, `--scrollbar-track-offset: 1.5px`, plus a rounded/pill thumb shape and block layout classes. Scrollbars appear on hover (`visibility: 'hover'`).
+
+## API reference
+
+`HlmScrollArea` declares **no inputs, outputs, or methods of its own** — it is a pure styling directive. All scrolling behavior/inputs (e.g. `orientation`, `visibility` overrides, viewport access) come from the host `NgScrollbar` component itself; consult the `ngx-scrollbar` API for those.
+
+| Host CSS variables set by the directive | Value                |
+| --------------------------------------- | -------------------- |
+| `--scrollbar-thumb-color`               | `var(--border)`      |
+| `--scrollbar-thumb-hover-color`         | `var(--border)`      |
+| `--scrollbar-track-color`               | `transparent`        |
+| `--scrollbar-track-thickness`           | `0.625rem`           |
+| `--scrollbar-track-offset`              | `1.5px`              |
+| `--scrollbar-thumb-shape`               | `9999px` (via class) |
+
+## Examples
+
+### 1. Basic vertical scroll area
+
+```ts
+import { Component } from '@angular/core';
+import { NgScrollbar } from 'ngx-scrollbar';
+import { HlmScrollAreaImports } from '@egose/shadcn-theme-ng/scroll-area';
+
+@Component({
+  selector: 'app-basic-scroll',
+  standalone: true,
+  imports: [NgScrollbar, HlmScrollAreaImports],
+  template: `
+    <ng-scrollbar hlm class="tw:h-64 tw:w-80 tw:rounded-md tw:border">
+      <div class="tw:p-4 tw:space-y-2">
+        @for (item of items; track item) {
+          <p class="tw:text-sm">{{ item }}</p>
+        }
+      </div>
+    </ng-scrollbar>
+  `,
+})
+export class BasicScrollComponent {
+  readonly items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);
+}
+```
+
+### 2. Fixed-height log / chat window
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NgScrollbar } from 'ngx-scrollbar';
+import { HlmScrollAreaImports } from '@egose/shadcn-theme-ng/scroll-area';
+
+@Component({
+  selector: 'app-log-scroll',
+  standalone: true,
+  imports: [NgScrollbar, HlmScrollAreaImports],
+  template: `
+    <ng-scrollbar hlm class="tw:h-72 tw:rounded-md tw:border tw:bg-muted/30">
+      <div class="tw:p-4 tw:font-mono tw:text-xs tw:space-y-1">
+        @for (line of lines(); track $index) {
+          <div>{{ line }}</div>
+        }
+      </div>
+    </ng-scrollbar>
+    <button type="button" (click)="addLine()">Add line</button>
+  `,
+})
+export class LogScrollComponent {
+  readonly lines = signal(['[ok] booted', '[ok] connected']);
+
+  addLine(): void {
+    this.lines.update((ls) => [...ls, `[log] event ${ls.length}`]);
+  }
+}
+```
+
+### 3. Horizontal scrolling row
+
+`NgScrollbar` supports horizontal viewports — the `hlm` styling applies the same way:
+
+```html
+<ng-scrollbar hlm orientation="horizontal" class="tw:w-full tw:max-w-xl tw:rounded-md tw:border">
+  <div class="tw:flex tw:gap-3 tw:p-4 tw:w-max">
+    @for (card of cards; track card) {
+    <div class="tw:h-24 tw:w-40 tw:shrink-0 tw:rounded-md tw:bg-muted tw:p-2">{{ card }}</div>
+    }
+  </div>
+</ng-scrollbar>
+```
+
+### 4. Scroll area inside a card
+
+```html
+<div class="tw:rounded-lg tw:border tw:p-4">
+  <h3 class="tw:mb-2 tw:font-semibold">Recent activity</h3>
+  <ng-scrollbar hlm class="tw:h-48">
+    <ul class="tw:space-y-2 tw:pe-4">
+      @for (event of activity; track event.id) {
+      <li class="tw:flex tw:justify-between tw:text-sm">
+        <span>{{ event.label }}</span>
+        <span class="tw:text-muted-foreground">{{ event.at }}</span>
+      </li>
+      }
+    </ul>
+  </ng-scrollbar>
+</div>
+```
+
+Leave end-padding (`pe-4`) so text never slides under the hover scrollbar.
+
+### 5. Long select/popover content
+
+Scrollable dropdown content with the themed thumb:
+
+```html
+<ng-scrollbar hlm class="tw:max-h-60 tw:w-64 tw:rounded-md tw:border">
+  <div class="tw:p-1">
+    @for (option of options; track option.value) {
+    <button
+      type="button"
+      (click)="pick(option)"
+      class="tw:w-full tw:rounded-sm tw:px-2 tw:py-1.5 tw:text-left tw:text-sm tw:hover:bg-accent"
+    >
+      {{ option.label }}
+    </button>
+    }
+  </div>
+</ng-scrollbar>
+```
+
+### 6. Overriding thumb color per instance
+
+The colors are CSS variables, so any instance can be re-themed inline:
+
+```html
+<ng-scrollbar
+  hlm
+  class="tw:h-64 tw:rounded-md tw:border"
+  style="--scrollbar-thumb-color: var(--primary); --scrollbar-thumb-hover-color: var(--primary);"
+>
+  <div class="tw:p-4">Brand-colored scrollbar…</div>
+</ng-scrollbar>
+```
+
+## Accessibility notes
+
+- `NgScrollbar` keeps native scroll semantics; keyboard users can scroll the region with arrows/PageUp/PageDown when it has focus — make sure scrollable regions with important content are focusable (`tabindex="0"`) and labelled (`aria-label`/`role="region"`).
+- Hover-only scrollbars can be hard to discover for pointer users and invisible to some low-vision users — for primary page-level scrolling prefer native overflow; reserve this component for secondary panes (sidebars, dropdowns, logs).
+- Do not nest scroll areas with competing orientations unless each has a clear label; nested scroll traps confuse both keyboard and screen-reader users.
+
+## Theming / CSS variables
+
+The component is driven by `--scrollbar-*` variables (see table above) plus the theme's `--border` token. Override per instance with inline `style` as shown in example 6; dark mode follows automatically through the theme tokens.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/resizable` — fixed-size panes that pair well with internal scroll areas
+- `@egose/shadcn-theme-ng/select` — its dropdown content scrolls internally for long option lists
+- `@egose/shadcn-theme-ng/sidebar` — sidebar content areas that often need themed scrolling
+- `@egose/shadcn-theme-ng/card` — bordered containers frequently wrapped around scroll areas

package/searchable-multiselect/README.md

@@ -1,3 +1,324 @@
-# Searchable Multiselect Subpath
+# Searchable Multiselect (`@egose/shadcn-theme-ng/searchable-multiselect`)
 
-This project ships only as `@egose/shadcn-theme-ng/searchable-multiselect` or `@egose/shadcn-theme-ng-tw/searchable-multiselect`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+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.
+
+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.
+
+> **Ships as:** `@egose/shadcn-theme-ng/searchable-multiselect` and `@egose/shadcn-theme-ng-tw/searchable-multiselect` (the `tw:`-prefixed Tailwind variant — same API, class strings prefixed with `tw:`).
+> See the [package README](../../README.md) for installation, peer dependencies, and Tailwind setup. Do not publish this project directory independently.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+```ts
+import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multiselect';
+// tw variant:
+// 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.)
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+| Symbol                    | Kind                                               | Description                                                |
+| ------------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
+| `EgSearchableMultiselect` | Standalone component (`eg-searchable-multiselect`) | The whole control; provides `NG_VALUE_ACCESSOR` for itself |
+| `SelectOption`            | Interface                                          | `{ label: string; value: string }`                         |
+
+> Note: unlike most subpaths, this one exposes **no `*Imports` array and no `*Module`**. Import `EgSearchableMultiselect` directly — it is standalone.
+
+```ts
+import { Component } from '@angular/core';
+import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [EgSearchableMultiselect],
+  template: ` <eg-searchable-multiselect [options]="options" [(value)]="selected" /> `,
+})
+export class DemoComponent {}
+```
+
+## Anatomy / Structure
+
+```html
+<eg-searchable-multiselect [options]="options" placeholder="Pick frameworks…" [(value)]="selected" />
+```
+
+Renders (internally — you do not write this yourself):
+
+```html
+<eg-searchable-multiselect>
+  <!-- chip row: placeholder pill when empty, removable chips otherwise -->
+  <div>
+    <span><!-- {{ placeholder }} or chip {{ item.label }} + ✕ button --></span>
+  </div>
+
+  <!-- popover trigger + checkbox list -->
+  <hlm-popover>
+    <button hlmPopoverTrigger hlmButton>N selected</button>
+    <hlm-popover-content>
+      <label><!-- <hlm-checkbox> per option + label text --></label>
+    </hlm-popover-content>
+  </hlm-popover>
+</eg-searchable-multiselect>
+```
+
+Real selector: `eg-searchable-multiselect` (element). The `✕` chip buttons and popover trigger honor the disabled state; the popover panel is `tw:w-64` with a `tw:max-h-60` scrolling option list.
+
+## API reference
+
+### 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 |
+
+`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.
+
+## Examples
+
+### 1. Basic two-way binding
+
+```ts
+import { Component, signal } from '@angular/core';
+import { EgSearchableMultiselect, type SelectOption } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-basic-multi',
+  standalone: true,
+  imports: [EgSearchableMultiselect],
+  template: `
+    <eg-searchable-multiselect [options]="frameworks" placeholder="Pick frameworks…" [(value)]="selected" />
+    <p>Selected: {{ selected().join(', ') || 'none' }}</p>
+  `,
+})
+export class BasicMultiComponent {
+  readonly frameworks: SelectOption[] = [
+    { label: 'Angular', value: 'angular' },
+    { label: 'React', value: 'react' },
+    { label: 'Vue', value: 'vue' },
+    { label: 'Svelte', value: 'svelte' },
+  ];
+  readonly selected = signal<string[]>(['angular']);
+}
+```
+
+### 2. Reactive forms
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { EgSearchableMultiselect, type SelectOption } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-reactive-multi',
+  standalone: true,
+  imports: [EgSearchableMultiselect, ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <label for="skills">Skills (pick at least one)</label>
+      <eg-searchable-multiselect id="skills" [options]="skills" formControlName="skillIds" />
+      @if (form.controls.skillIds.invalid && form.controls.skillIds.touched) {
+        <p class="tw:text-destructive tw:text-sm">Choose at least one skill.</p>
+      }
+      <button type="submit">Save</button>
+    </form>
+  `,
+})
+export class ReactiveMultiComponent {
+  readonly skills: SelectOption[] = [
+    { label: 'TypeScript', value: 'ts' },
+    { label: 'CSS', value: 'css' },
+    { label: 'Testing', value: 'testing' },
+  ];
+  readonly form = new FormGroup({
+    skillIds: new FormControl<string[]>(['ts'], { validators: Validators.required }),
+  });
+
+  submit(): void {
+    this.form.markAllAsTouched();
+    console.log(this.form.value);
+  }
+}
+```
+
+### 3. Template-driven forms (`ngModel`)
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { EgSearchableMultiselect, type SelectOption } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-ngmodel-multi',
+  standalone: true,
+  imports: [EgSearchableMultiselect, FormsModule],
+  template: `
+    <eg-searchable-multiselect name="tags" [options]="tags" [(ngModel)]="selected" #tagsCtrl="ngModel" />
+    @if (tagsCtrl.touched && !selected.length) {
+      <p class="tw:text-destructive tw:text-sm">Pick at least one tag.</p>
+    }
+  `,
+})
+export class NgModelMultiComponent {
+  readonly tags: SelectOption[] = [
+    { label: 'Bug', value: 'bug' },
+    { label: 'Feature', value: 'feature' },
+    { label: 'Docs', value: 'docs' },
+  ];
+  selected: string[] = [];
+}
+```
+
+### 4. Disabled / read-only states
+
+```ts
+import { Component } from '@angular/core';
+import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-disabled-multi',
+  standalone: true,
+  imports: [EgSearchableMultiselect],
+  template: `
+    <!-- fully disabled: chips, ✕ buttons, trigger, checkboxes -->
+    <eg-searchable-multiselect [options]="options" [value]="['a']" disabled />
+
+    <!-- wrapper-driven disable (e.g. parent form section locked) -->
+    <eg-searchable-multiselect [options]="options" [value]="['a']" [wrapperDisabled]="locked" />
+  `,
+})
+export class DisabledMultiComponent {
+  readonly locked = true;
+  readonly options = [
+    { label: 'Alpha', value: 'a' },
+    { label: 'Beta', value: 'b' },
+  ];
+}
+```
+
+Disabling via `formControl.disable()` works too — it flows through `setDisabledState`.
+
+### 5. Client-side search (filter `options` yourself)
+
+Since the popover lists exactly what you pass in `options`, implement search by filtering upstream:
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { EgSearchableMultiselect } 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]="filtered()" [(value)]="selected" />
+  `,
+})
+export class SearchMultiComponent {
+  readonly query = signal('');
+  readonly selected = signal<string[]>([]);
+  private readonly all = [
+    { 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.
+
+### 6. Async options + reacting to changes
+
+```ts
+import { Component, resource, signal } from '@angular/core';
+import { EgSearchableMultiselect, type SelectOption } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-async-multi',
+  standalone: true,
+  imports: [EgSearchableMultiselect],
+  template: `
+    @if (users.isLoading()) {
+      <p>Loading users…</p>
+    } @else {
+      <eg-searchable-multiselect
+        [options]="users.value() ?? []"
+        [(value)]="assignees"
+        (valueChange)="onChange($event)"
+        ariaLabel="Assignees"
+      />
+    }
+  `,
+})
+export class AsyncMultiComponent {
+  readonly assignees = signal<string[]>([]);
+  readonly users = resource({
+    loader: async (): Promise<SelectOption[]> => {
+      const res = await fetch('/api/users');
+      const list = (await res.json()) as Array<{ id: string; name: string }>;
+      return list.map((u) => ({ label: u.name, value: u.id }));
+    },
+  });
+
+  onChange(values: string[]): void {
+    console.log('assignees now:', values);
+  }
+}
+```
+
+## 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.
+
+## Theming / CSS variables
+
+Class-driven (chips, popover panel, checkbox rows). Extend via the `class` input on the host; inner popover width (`tw:w-64`) and list height (`tw:max-h-60`) are fixed in the template.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/form-searchable-multiselect` — form-field wrapper (label/description/error) around this control
+- `@egose/shadcn-theme-ng/select` — single-select dropdown counterpart
+- `@egose/shadcn-theme-ng/popover` — the underlying popover primitive
+- `@egose/shadcn-theme-ng/checkbox` — the underlying option-row primitive