@egose/shadcn-theme-ng 0.1.0 → 0.2.0

package/checkbox/README.md

@@ -1,3 +1,321 @@
-# Checkbox Subpath
+# Checkbox (`@egose/shadcn-theme-ng/checkbox`)
 
-This project ships only as `@egose/shadcn-theme-ng/checkbox` or `@egose/shadcn-theme-ng-tw/checkbox`. 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 checkbox — the Angular port of shadcn/ui `Checkbox`. A single standalone `hlm-checkbox` component wraps `BrnCheckbox` from `@spartan-ng/brain/checkbox`, renders the `lucideCheck` icon when checked, and fully implements `ControlValueAccessor`, so it works with `[(checked)]`, `[(ngModel)]`, and reactive `FormControl`s. Supports the tri-state `boolean | 'indeterminate'` model, separate `disabled` (form-aware) vs `wrapperDisabled` (visual-only) locks, and a `changed` output.
+
+Ships as `@egose/shadcn-theme-ng/checkbox` and `@egose/shadcn-theme-ng-tw/checkbox` (the `tw:`-prefixed variant). See the [package README](../../README.md) for install, peer dependencies, and Tailwind setup. Do not publish this project directory independently — it is consumed via the published subpath only.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peers are listed in the [package README](../../README.md). This subpath declares `@angular/common` and `@angular/core` as peers (see `projects/checkbox/package.json`); `FormsModule`/`ReactiveFormsModule` come from your app when you use form bindings.
+
+## Imports
+
+```ts
+import {
+  HlmCheckbox,
+  HlmCheckboxImports,
+  HlmCheckboxModule,
+  HLM_CHECKBOX_VALUE_ACCESSOR,
+} from '@egose/shadcn-theme-ng/checkbox';
+// tw variant:
+// import { ... } from '@egose/shadcn-theme-ng-tw/checkbox';
+```
+
+Standalone:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmCheckboxImports],
+  template: `<hlm-checkbox />`,
+})
+export class DemoComponent {}
+```
+
+NgModule:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmCheckboxModule } from '@egose/shadcn-theme-ng/checkbox';
+
+@NgModule({ imports: [HlmCheckboxModule] })
+export class DemoModule {}
+```
+
+## Anatomy / Structure
+
+```html
+<!-- Two-way model binding -->
+<hlm-checkbox [(checked)]="accept" aria-label="Accept terms" />
+
+<!-- With visible label -->
+<div class="flex items-center gap-2">
+  <hlm-checkbox id="marketing" [(checked)]="marketing" />
+  <label for="marketing">Email me product updates</label>
+</div>
+
+<!-- Reactive form -->
+<hlm-checkbox formControlName="accept" />
+
+<!-- Template-driven -->
+<hlm-checkbox name="accept" [(ngModel)]="accept" />
+```
+
+Real selector: `hlm-checkbox` (element only). The host renders `class="contents peer"` so sibling label/description selectors (`peer-*`) keep working; `id` / `aria-*` attributes are nulled on the host and forwarded to the inner `brn-checkbox` instead. Set a visible label with a native `<label for>` — the component does not render label text itself.
+
+## API reference
+
+### `HlmCheckbox` (`hlm-checkbox`)
+
+| Input                                  | Type                                | Default | Description                                                                                                                                        |
+| -------------------------------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`                              | `model<boolean \| 'indeterminate'>` | `false` | Checked state. Two-way bindable (`[(checked)]`). `'indeterminate'` renders the checked icon; clicking it resolves to `true`.                       |
+| `class` (`userClass`)                  | `ClassValue`                        | `''`    | Extra classes merged into the box.                                                                                                                 |
+| `id`                                   | `string \| null`                    | `null`  | Forwarded to inner `brn-checkbox`. Pair with `<label for>`.                                                                                        |
+| `aria-label` (`ariaLabel`)             | `string \| null`                    | `null`  | Forwarded aria-label.                                                                                                                              |
+| `aria-labelledby` (`ariaLabelledby`)   | `string \| null`                    | `null`  | Forwarded aria-labelledby.                                                                                                                         |
+| `aria-describedby` (`ariaDescribedby`) | `string \| null`                    | `null`  | Forwarded aria-describedby.                                                                                                                        |
+| `name`                                 | `string \| null`                    | `null`  | Forwarded `name`.                                                                                                                                  |
+| `required`                             | `boolean`                           | `false` | Forwarded `required` (boolean-coerced).                                                                                                            |
+| `disabled`                             | `boolean`                           | `false` | Visual + interaction lock (boolean-coerced). Clicks are ignored.                                                                                   |
+| `wrapperDisabled`                      | `boolean`                           | `false` | Additional visual/interaction lock that does **not** write to a reactive form control (unlike `setDisabledState`). Useful for preview-only states. |
+
+| Signal          | Type              | Description                                                                                                  |
+| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `disabledState` | `Signal<boolean>` | `disabled() \|\| wrapperDisabled() \|\| formDisabled()` — the effective lock. Host reflects `data-disabled`. |
+
+| Output    | Payload   | Description                                                                                                    |
+| --------- | --------- | -------------------------------------------------------------------------------------------------------------- |
+| `changed` | `boolean` | Emitted on user toggle with the new boolean (`!previous`). Note: toggling from `'indeterminate'` emits `true`. |
+
+ControlValueAccessor: `writeValue(value)`, `registerOnChange`, `registerOnTouched`, `setDisabledState(isDisabled)` (writes `formDisabled`, hence `disabledState`). `HLM_CHECKBOX_VALUE_ACCESSOR` (`NG_VALUE_ACCESSOR`, `forwardRef(HlmCheckbox)`, `multi: true`) is provided on the component.
+
+## Examples
+
+### 1. Basic with label
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-basic-checkbox',
+  standalone: true,
+  imports: [...HlmCheckboxImports],
+  template: `
+    <div class="flex items-center gap-2">
+      <hlm-checkbox id="terms" [(checked)]="accept" />
+      <label for="terms" class="text-sm">Accept terms and conditions</label>
+    </div>
+    <p class="mt-2 text-sm">Value: {{ accept() }}</p>
+  `,
+})
+export class BasicCheckboxComponent {
+  readonly accept = signal<boolean | 'indeterminate'>(false);
+}
+```
+
+### 2. Reactive form with validation
+
+`hlm-checkbox` is a `ControlValueAccessor` — `formControlName` just works, including `disable()`.
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-reactive-checkbox',
+  standalone: true,
+  imports: [ReactiveFormsModule, ...HlmCheckboxImports],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()" class="space-y-3">
+      <div class="flex items-center gap-2">
+        <hlm-checkbox id="accept" formControlName="accept" />
+        <label for="accept" class="text-sm">I agree to the privacy policy</label>
+      </div>
+      @if (form.controls.accept.touched && form.controls.accept.invalid) {
+        <p class="text-destructive text-sm">You must accept to continue.</p>
+      }
+      <button type="submit" [disabled]="form.invalid">Continue</button>
+      <button type="button" (click)="form.controls.accept.disable()">Disable via form</button>
+    </form>
+  `,
+})
+export class ReactiveCheckboxComponent {
+  readonly form = new FormGroup({
+    accept: new FormControl(false, { validators: Validators.requiredTrue, nonNullable: true }),
+  });
+  submit() {
+    console.log(this.form.getRawValue());
+  }
+}
+```
+
+### 3. Template-driven (`ngModel`)
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-ngmodel-checkbox',
+  standalone: true,
+  imports: [FormsModule, ...HlmCheckboxImports],
+  template: `
+    <div class="flex items-center gap-2">
+      <hlm-checkbox id="news" name="news" [(ngModel)]="subscribed" aria-label="Subscribe to newsletter" />
+      <label for="news" class="text-sm">Subscribe to newsletter</label>
+    </div>
+  `,
+})
+export class NgModelCheckboxComponent {
+  subscribed = true;
+}
+```
+
+### 4. Indeterminate + select-all pattern
+
+Parent shows `'indeterminate'` when some (not all) children are checked — the classic bulk-select header.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-select-all',
+  standalone: true,
+  imports: [...HlmCheckboxImports],
+  template: `
+    <div class="flex items-center gap-2 border-b pb-2">
+      <hlm-checkbox id="all" [checked]="parentState()" (changed)="toggleAll($event)" aria-label="Select all files" />
+      <label for="all" class="text-sm font-medium">Select all</label>
+    </div>
+    @for (f of files(); track f.id) {
+      <div class="flex items-center gap-2 py-1">
+        <hlm-checkbox [id]="f.id" [checked]="f.done" (changed)="toggleOne(f.id, $event)" />
+        <label [for]="f.id" class="text-sm">{{ f.name }}</label>
+      </div>
+    }
+  `,
+})
+export class SelectAllComponent {
+  readonly files = signal([
+    { id: 'f1', name: 'invoice.pdf', done: true },
+    { id: 'f2', name: 'photo.png', done: false },
+    { id: 'f3', name: 'notes.md', done: false },
+  ]);
+  readonly parentState = computed<boolean | 'indeterminate'>(() => {
+    const all = this.files();
+    if (all.every((f) => f.done)) return true;
+    if (all.some((f) => f.done)) return 'indeterminate';
+    return false;
+  });
+  toggleAll(next: boolean) {
+    this.files.update((fs) => fs.map((f) => ({ ...f, done: next })));
+  }
+  toggleOne(id: string, next: boolean) {
+    this.files.update((fs) => fs.map((f) => (f.id === id ? { ...f, done: next } : f)));
+  }
+}
+```
+
+### 5. Disabled / wrapper-disabled / required states
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-states-checkbox',
+  standalone: true,
+  imports: [...HlmCheckboxImports],
+  template: `
+    <div class="space-y-2">
+      <div class="flex items-center gap-2">
+        <hlm-checkbox id="d1" [disabled]="true" aria-label="Disabled unchecked" />
+        <label for="d1" class="text-sm opacity-70">Disabled (unchecked)</label>
+      </div>
+      <div class="flex items-center gap-2">
+        <hlm-checkbox id="d2" [checked]="true" [disabled]="true" aria-label="Disabled checked" />
+        <label for="d2" class="text-sm opacity-70">Disabled (checked)</label>
+      </div>
+      <div class="flex items-center gap-2">
+        <hlm-checkbox id="w1" [wrapperDisabled]="preview()" aria-label="Preview lock" />
+        <label for="w1" class="text-sm">Preview lock (visual only — form value untouched)</label>
+      </div>
+      <div class="flex items-center gap-2">
+        <hlm-checkbox id="r1" [(checked)]="v" [required]="true" aria-label="Required" />
+        <label for="r1" class="text-sm">Required</label>
+      </div>
+    </div>
+  `,
+})
+export class StatesCheckboxComponent {
+  readonly preview = signal(true);
+  v = false;
+}
+```
+
+### 6. Listening to `changed` + custom styling
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCheckboxImports } from '@egose/shadcn-theme-ng/checkbox';
+
+@Component({
+  selector: 'app-changed-checkbox',
+  standalone: true,
+  imports: [...HlmCheckboxImports],
+  template: `
+    <div class="flex items-center gap-2">
+      <hlm-checkbox
+        id="audit"
+        class="data-[state=checked]:border-emerald-600 data-[state=checked]:bg-emerald-600"
+        aria-label="Enable audit log"
+        (changed)="onChanged($event)"
+      />
+      <label for="audit" class="text-sm">Enable audit log</label>
+    </div>
+    <p class="mt-1 text-sm">Last event: {{ lastChanged === null ? 'none' : lastChanged }}</p>
+  `,
+})
+export class ChangedCheckboxComponent {
+  lastChanged: boolean | null = null;
+  onChanged(next: boolean) {
+    this.lastChanged = next;
+    console.log('checkbox changed →', next);
+  }
+}
+```
+
+## Accessibility notes
+
+- The component renders a native-checkbox-equivalent `brn-checkbox` with `aria-label`/`labelledby`/`describedby` forwarding — always provide one: visible `<label for>` preferred, `aria-label` for icon-only rows.
+- `disabledState` adds `data-disabled`, `cursor-not-allowed`, and `opacity-50`; disabled boxes are skipped correctly because clicks early-return.
+- The check glyph is decorative (`lucideCheck` icon, no text) — state is exposed via `data-[state]` / native semantics, not the icon.
+- Tri-state: `'indeterminate'` is a visual/model state, not `aria-checked="mixed"` — if you need mixed semantics for a tree, add `aria-checked` handling at your own level and test with a screen reader.
+
+## Theming / CSS variables
+
+No component-specific CSS variables. The box uses `border-input`, `data-[state=checked]:bg-primary` / `text-primary-foreground`, `focus-visible:ring-ring/50`, `aria-invalid:border-destructive`, `size-4 rounded-[4px]`. Invalid-form styling integrates via `aria-invalid` ring tokens. Pass `class` to extend (merged with `hlm()`).
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/form-checkbox` — labeled + described + validated field composition.
+- `@egose/shadcn-theme-ng/label` — accessible labels for the `for`/`id` pair.
+- `@egose/shadcn-theme-ng/field` — form layout rows that host checkboxes.
+- `@egose/shadcn-theme-ng/icon` — `HlmIcon` sizing used by the inner check glyph.

package/collapsible/README.md

@@ -1,11 +1,338 @@
-# Collapsible
+# Collapsible (`@egose/shadcn-theme-ng/collapsible`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A show/hide disclosure container — the Angular port of shadcn/ui `Collapsible`. Three thin directives compose it: `HlmCollapsible` (state owner, wraps `BrnCollapsible`), `HlmCollapsibleTrigger` (toggle button, wraps `BrnCollapsibleTrigger`), and `HlmCollapsibleContent` (collapsing panel, wraps `BrnCollapsibleContent`). All behavior — expanded state, disabled locking, `expandedChange` events, trigger/content wiring — comes from `@spartan-ng/brain/collapsible`; this package only adds `data-slot` attributes and (for content) the `data-[state=closed]:hidden` rule.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/collapsible` and `@egose/shadcn-theme-ng-tw/collapsible` (the `tw:`-prefixed variant). See the [package README](../../README.md) for install, peer dependencies, and Tailwind setup. Do not publish this project directory independently — it is consumed via the published subpath only.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build collapsible
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peers are listed in the [package README](../../README.md). This subpath declares `@angular/common`, `@angular/core`, and `@spartan-ng/brain` as peers (see `projects/collapsible/package.json`).
+
+## Imports
+
+```ts
+import {
+  HlmCollapsible,
+  HlmCollapsibleTrigger,
+  HlmCollapsibleContent,
+  HlmCollapsibleImports,
+  HlmCollapsibleModule,
+} from '@egose/shadcn-theme-ng/collapsible';
+// tw variant:
+// import { ... } from '@egose/shadcn-theme-ng-tw/collapsible';
+```
+
+Standalone:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmCollapsibleImports],
+  template: `...`,
+})
+export class DemoComponent {}
 ```
+
+NgModule:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmCollapsibleModule } from '@egose/shadcn-theme-ng/collapsible';
+
+@NgModule({ imports: [HlmCollapsibleModule] })
+export class DemoModule {}
+```
+
+## Anatomy / Structure
+
+```html
+<hlm-collapsible [expanded]="open" (expandedChange)="open = $event">
+  <button hlmCollapsibleTrigger>Toggle details</button>
+  <hlm-collapsible-content>
+    <p>Hidden until expanded.</p>
+  </hlm-collapsible-content>
+</hlm-collapsible>
+```
+
+Real selectors (from source — note the trigger is button-only):
+
+| Class                   | Selector                                             | `data-slot`           |
+| ----------------------- | ---------------------------------------------------- | --------------------- |
+| `HlmCollapsible`        | `[hlmCollapsible]`, `hlm-collapsible`                | `collapsible`         |
+| `HlmCollapsibleTrigger` | `button[hlmCollapsibleTrigger]`                      | `collapsible-trigger` |
+| `HlmCollapsibleContent` | `[hlmCollapsibleContent]`, `hlm-collapsible-content` | `collapsible-content` |
+
+The trigger **must** be a `<button>` element (`button[hlmCollapsibleTrigger]` — an `<a>` or `<div>` with the attribute will not match). Trigger and content must be descendants of the same `HlmCollapsible` host.
+
+## API reference
+
+### `HlmCollapsible` (`[hlmCollapsible]`, `hlm-collapsible`)
+
+Thin wrapper around `BrnCollapsible`:
+
+| Brain input | Type      | Description                                                                        |
+| ----------- | --------- | ---------------------------------------------------------------------------------- |
+| `expanded`  | `boolean` | Controlled expanded state. Bind + listen to `expandedChange` for two-way behavior. |
+| `disabled`  | `boolean` | Locks the trigger; content stays as-is.                                            |
+
+| Brain output     | Payload   | Description                                                              |
+| ---------------- | --------- | ------------------------------------------------------------------------ |
+| `expandedChange` | `boolean` | Emitted whenever the trigger toggles (or state is set programmatically). |
+
+No own inputs/outputs/methods.
+
+### `HlmCollapsibleTrigger` (`button[hlmCollapsibleTrigger]`)
+
+Thin wrapper around `BrnCollapsibleTrigger`:
+
+| Brain input | Type     | Description                                                                                                               |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `type`      | `string` | Forwarded button `type` (`'button'`, `'submit'`, …). Default to `type="button"` inside forms to avoid accidental submits. |
+
+No outputs of its own — activation flows through the parent's `expandedChange`.
+
+### `HlmCollapsibleContent` (`[hlmCollapsibleContent]`, `hlm-collapsible-content`)
+
+Thin wrapper around `BrnCollapsibleContent`:
+
+| Brain input | Type     | Description                              |
+| ----------- | -------- | ---------------------------------------- |
+| `id`        | `string` | Content panel id (aria-controls wiring). |
+
+Adds `data-[state=closed]:hidden` — the open/close animation (if any) is yours to add via `data-[state]` selectors.
+
+## Examples
+
+### 1. Basic collapsible (two-way binding pattern)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-basic-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports, ...HlmButtonImports],
+  template: `
+    <hlm-collapsible [expanded]="open" (expandedChange)="open = $event" class="w-96 rounded-lg border p-4">
+      <div class="flex items-center justify-between">
+        <h4 class="text-sm font-medium">Repository settings</h4>
+        <button hlmBtn variant="ghost" size="sm" hlmCollapsibleTrigger>
+          {{ open ? 'Hide' : 'Show' }}
+        </button>
+      </div>
+      <hlm-collapsible-content>
+        <p class="pt-3 text-sm">Visibility, branch protection, and secrets live here.</p>
+      </hlm-collapsible-content>
+    </hlm-collapsible>
+  `,
+})
+export class BasicCollapsibleComponent {
+  open = false;
+}
+```
+
+### 2. Default-open + disabled lock
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+
+@Component({
+  selector: 'app-disabled-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports],
+  template: `
+    <div class="space-y-4">
+      <hlm-collapsible [expanded]="true" class="rounded-lg border p-4">
+        <button hlmCollapsibleTrigger type="button" class="text-sm font-medium">Starts open (expanded=true)</button>
+        <hlm-collapsible-content>
+          <p class="pt-2 text-sm">This panel renders visible on first paint.</p>
+        </hlm-collapsible-content>
+      </hlm-collapsible>
+
+      <hlm-collapsible [disabled]="true" class="rounded-lg border p-4 opacity-80">
+        <button hlmCollapsibleTrigger type="button" class="text-sm font-medium">
+          Locked (disabled=true) — trigger does nothing
+        </button>
+        <hlm-collapsible-content>
+          <p class="pt-2 text-sm">You cannot reach this content while disabled.</p>
+        </hlm-collapsible-content>
+      </hlm-collapsible>
+    </div>
+  `,
+})
+export class DisabledCollapsibleComponent {}
+```
+
+### 3. Chevron rotation driven by state
+
+Bind the icon rotation to your `open` flag — the classic shadcn pattern.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideChevronsUpDown } from '@ng-icons/lucide';
+
+@Component({
+  selector: 'app-chevron-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports, NgIcon],
+  providers: [provideIcons({ lucideChevronsUpDown })],
+  template: `
+    <hlm-collapsible [expanded]="open" (expandedChange)="open = $event" class="w-96 rounded-lg border p-4">
+      <button hlmCollapsibleTrigger type="button" class="flex w-full items-center justify-between text-sm font-medium">
+        Can I use this in my project?
+        <ng-icon name="lucideChevronsUpDown" class="transition-transform duration-200" [class.rotate-180]="open" />
+      </button>
+      <hlm-collapsible-content>
+        <p class="pt-3 text-sm">Yes — free for personal and commercial use.</p>
+      </hlm-collapsible-content>
+    </hlm-collapsible>
+  `,
+})
+export class ChevronCollapsibleComponent {
+  open = false;
+}
+```
+
+### 4. FAQ list (repeated collapsibles)
+
+Each item owns its state — use an array of booleans or a Set of open ids.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+
+@Component({
+  selector: 'app-faq-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports],
+  template: `
+    <div class="w-full max-w-xl space-y-2">
+      @for (item of faqs; track item.q; let i = $index) {
+        <hlm-collapsible [expanded]="open[i]" (expandedChange)="open[i] = $event" class="rounded-lg border px-4 py-3">
+          <button hlmCollapsibleTrigger type="button" class="w-full text-left text-sm font-medium">
+            {{ item.q }}
+          </button>
+          <hlm-collapsible-content>
+            <p class="pt-2 text-sm">{{ item.a }}</p>
+          </hlm-collapsible-content>
+        </hlm-collapsible>
+      }
+    </div>
+  `,
+})
+export class FaqCollapsibleComponent {
+  readonly faqs = [
+    { q: 'Is it accessible?', a: 'Yes — triggers are real buttons with aria-expanded wiring from BrnCollapsible.' },
+    { q: 'Is it animated?', a: 'Not by default; add data-[state] transitions (see example 6).' },
+    { q: 'Can I nest them?', a: 'Yes — nest a full hlm-collapsible inside any content panel.' },
+  ];
+  open: boolean[] = [true, false, false];
+}
+```
+
+### 5. Programmatic control (open all / close all)
+
+Because `expanded` is a plain input, external buttons can drive it.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-controlled-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports, ...HlmButtonImports],
+  template: `
+    <div class="mb-3 flex gap-2">
+      <button hlmBtn variant="outline" size="sm" (click)="setAll(true)">Expand all</button>
+      <button hlmBtn variant="outline" size="sm" (click)="setAll(false)">Collapse all</button>
+    </div>
+    @for (s of sections; track s.title; let i = $index) {
+      <hlm-collapsible [expanded]="open[i]" (expandedChange)="open[i] = $event" class="mb-2 rounded-lg border p-4">
+        <button hlmCollapsibleTrigger type="button" class="text-sm font-medium">{{ s.title }}</button>
+        <hlm-collapsible-content>
+          <p class="pt-2 text-sm">{{ s.body }}</p>
+        </hlm-collapsible-content>
+      </hlm-collapsible>
+    }
+  `,
+})
+export class ControlledCollapsibleComponent {
+  readonly sections = [
+    { title: 'Billing', body: 'Invoices, seats, and receipts.' },
+    { title: 'Security', body: 'SSO, 2FA, and audit log.' },
+  ];
+  open = [false, false];
+  setAll(v: boolean) {
+    this.open = this.open.map(() => v);
+  }
+}
+```
+
+### 6. Animated height (advanced, `data-[state]` + grid trick)
+
+The content host exposes `data-state="open" | "closed"` from the brain directive — animate with a grid-rows transition instead of `hidden`.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmCollapsibleImports } from '@egose/shadcn-theme-ng/collapsible';
+
+@Component({
+  selector: 'app-animated-collapsible',
+  standalone: true,
+  imports: [...HlmCollapsibleImports],
+  template: `
+    <hlm-collapsible [expanded]="open" (expandedChange)="open = $event" class="w-96 rounded-lg border p-4">
+      <button hlmCollapsibleTrigger type="button" class="text-sm font-medium">
+        {{ open ? 'Collapse' : 'Expand' }} with animation
+      </button>
+      <hlm-collapsible-content
+        class="grid transition-all duration-200 data-[state=closed]:hidden data-[state=open]:grid-rows-[1fr] data-[state=closed]:grid-rows-[0fr]"
+      >
+        <div class="overflow-hidden">
+          <p class="pt-3 text-sm">Smooth grid-rows open/close. Keep the inner overflow-hidden wrapper.</p>
+        </div>
+      </hlm-collapsible-content>
+    </hlm-collapsible>
+  `,
+})
+export class AnimatedCollapsibleComponent {
+  open = false;
+}
+```
+
+## Accessibility notes
+
+- Trigger is a native `<button>` with `aria-expanded` / `aria-controls` wired by `BrnCollapsibleTrigger` — never replace it with a `<div (click)>`; keyboard (Enter/Space) support depends on the button.
+- Always use `type="button"` on triggers inside `<form>`s to avoid accidental submits (the `type` input is forwarded).
+- `disabled` on the parent locks the trigger (`aria-disabled` semantics from brain) — announce why it is locked with adjacent hint text.
+- Content is hidden with `data-[state=closed]:hidden` (display:none), so screen readers skip closed panels — correct disclosure behavior.
+
+## Theming / CSS variables
+
+No component-specific CSS variables and no default open/close animation. Style hooks: `data-slot` (`collapsible`, `collapsible-trigger`, `collapsible-content`) and `data-state="open|closed"` / `data-disabled`. Add your own `data-[state=open]:…` transitions as in example 6.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/accordion` — mutually-exclusive multi-item disclosures (use instead of hand-rolled FAQ state).
+- `@egose/shadcn-theme-ng/button` — ghost/small trigger styling (`hlmBtn`).
+- `@egose/shadcn-theme-ng/icon` — chevron affordances rotated from your `open` flag.
+- `@egose/shadcn-theme-ng/card` — bordered shells that host collapsible rows.