@egose/shadcn-theme-ng 0.0.28 → 0.2.0

package/README.md

@@ -14,17 +14,28 @@ npm install @egose/shadcn-theme-ng
 npm install @egose/shadcn-theme-ng-tw
 ```
 
-`pnpm` / `yarn` equivalents work too. Make sure your project's versions satisfy the peer ranges below.
+`pnpm` / `yarn` equivalents work too. npm installs peer dependencies automatically when it can resolve compatible
+versions; applications must keep their existing framework versions inside the supported ranges below.
 
 ### Peer dependencies
 
-| Package             | Supported version   |
-| ------------------- | ------------------- |
-| `@angular/common`   | `^20.2.0`           |
-| `@angular/core`     | `^20.2.0`           |
-| `@spartan-ng/brain` | `^0.0.1-alpha.512+` |
+| Package             | Supported version  | Tested version |
+| ------------------- | ------------------ | -------------- |
+| `@angular/cdk`      | `>=22.0.0 <23.0.0` | `22.1.3`       |
+| `@angular/common`   | `>=22.0.0 <23.0.0` | `22.1.3`       |
+| `@angular/core`     | `>=22.0.0 <23.0.0` | `22.1.3`       |
+| `@angular/forms`    | `>=22.0.0 <23.0.0` | `22.1.3`       |
+| `@angular/router`   | `>=22.0.0 <23.0.0` | `22.1.3`       |
+| `@ng-icons/core`    | `>=35.0.1 <36.0.0` | `35.0.1`       |
+| `@spartan-ng/brain` | `>=1.3.2 <2.0.0`   | `1.3.2`        |
+| `rxjs`              | `>=7.8.0 <8.0.0`   | `7.8.2`        |
 
-`@spartan-ng/brain` is the underlying primitive library that powers most components.
+Angular and CDK must use the same major version. The tested consumer contract is Angular 22, CDK 22, and Spartan 1.3.2;
+the ranges above are copied from the published peer metadata and validated with strict isolated installs.
+
+Runtime implementation dependencies such as `@ng-icons/lucide`, `@ng-icons/tabler-icons`, `class-variance-authority`,
+`clsx`, `embla-carousel`, `embla-carousel-angular`, `ngx-scrollbar`, `ngx-sonner`, `tailwind-merge`, and `tslib` are
+installed transitively. Do not install them directly unless your application also imports them.
 
 ### Tailwind variants
 
@@ -37,6 +48,59 @@ There are two published variants of this package. They produce identical markup
 
 If your project mixes shadcn styles with other Tailwind utilities that share class names, use the `-tw` variant to avoid collisions.
 
+Class utilities are normalized to one unprefixed canonical representation during packaging. The plain artifact emits
+unprefixed utilities, while the `-tw` artifact prefixes every recognized utility with `tw:`. Generated JavaScript source
+maps are intentionally excluded because this post-build class and package-identity transformation invalidates ng-packagr's
+maps; shipping no map is safer than shipping a map that points at different generated code.
+
+## Release preparation
+
+Prepare both release candidates without publishing by supplying the intended version explicitly:
+
+```bash
+pnpm --dir packages/angular prepare:release --version 1.2.3
+```
+
+This runs `@repo-toolkit/publish-package` with `publish.config.mjs`: it serially
+builds, validates, and packs the plain (`release/plain` → `@egose/shadcn-theme-ng`)
+and `tw:` (`release/tw` → `@egose/shadcn-theme-ng-tw`) variants. The inspectable
+stages and two exact `.tgz` artifacts are written under `packages/angular/release/`.
+Neither package is published unless both candidates pass every step. Publishing is
+intended to run from protected CI with npm trusted publishing/OIDC; `--otp` remains
+available for manual publishes (passed to the toolkit publish command, never logged).
+
+## Source tests
+
+Headless-test prerequisite (local and CI): the Karma suites need a
+Chrome-compatible binary. The repository-supported setup downloads it into
+the repo-local `.puppeteer-cache/` directory:
+
+```bash
+pnpm --dir packages/angular install:browser
+```
+
+Alternatively, set `CHROME_BIN` to any Chrome/Chromium binary yourself
+(`test/karma.conf.js` honors a pre-set `CHROME_BIN`, then falls back to a
+system Chrome).
+
+Focused library tests are intentionally separate from staged-package and artifact validation:
+
+```bash
+# One selected library
+pnpm --dir packages/angular test:library form-text-input
+pnpm --dir packages/angular test:library utils
+
+# Source export contracts plus every selected library, serially and headlessly
+pnpm --dir packages/angular test:libraries
+
+# The example shell and router behavior
+pnpm --dir packages/angular/@examples/standard test:ci
+```
+
+The browser suites share `packages/angular/test/setup.ts`, which provides zoneless Angular setup and assertions for form
+bindings and resource teardown. DOM reconciliation uses real `MutationObserver` and animation-frame scheduling; server-mode
+coverage verifies those browser resources are not created. All CI commands disable watch mode so they terminate after one run.
+
 ## Import forms
 
 Import each component via its own npm subpath:
@@ -72,23 +136,27 @@ export class MyModule {}
 
 Import by component name. Component `NameX` is reachable at `@egose/shadcn-theme-ng/<name-x>` (kebab-case). The current surface:
 
-`accordion`, `alert`, `autocomplete`, `badge`, `basic-alert`, `button`, `calendar`, `checkbox`, `confirmation-dialog`, `date-picker`, `dialog`, `form-checkbox`, `form-date-picker`, `form-field`, `form-field-simple`, `form-searchable-multiselect`, `form-select`, `form-text-input`, `form-textarea`, `icon`, `input`, `label`, `layout-simple`, `menu`, `popover`, `radio-group`, `searchable-multiselect`, `select`, `separator`, `sheet`, `sonner`, `spinner`, `switch`, `tabs`, `tooltip`, `utils`.
+<!-- BEGIN GENERATED SUBPATHS -->
+
+`accordion`, `alert`, `alert-dialog`, `aspect-ratio`, `autocomplete`, `avatar`, `badge`, `basic-alert`, `breadcrumb`, `button`, `button-group`, `calendar`, `card`, `carousel`, `checkbox`, `collapsible`, `combobox`, `command`, `confirmation-dialog`, `context-menu`, `date-picker`, `dialog`, `drawer`, `dropdown-menu`, `empty`, `field`, `form-checkbox`, `form-date-picker`, `form-field`, `form-field-simple`, `form-searchable-multiselect`, `form-select`, `form-text-input`, `form-textarea`, `hover-card`, `icon`, `input`, `input-group`, `input-otp`, `item`, `kbd`, `label`, `layout-simple`, `menu`, `menubar`, `native-select`, `navigation-menu`, `pagination`, `popover`, `progress`, `radio-group`, `resizable`, `scroll-area`, `searchable-multiselect`, `select`, `separator`, `sheet`, `sidebar`, `skeleton`, `slider`, `sonner`, `spinner`, `switch`, `table`, `tabs`, `textarea`, `toggle`, `toggle-group`, `tooltip`, `typography`, `utils`.
+
+<!-- END GENERATED SUBPATHS -->
 
 Anything not in this list is not part of the public surface. The published `exports` map in `package.json` reflects this set exactly — if a subpath is not listed, do not assume it is importable.
 
 ## Quick start (Angular standalone)
 
 ```ts
-import { Component } from "@angular/core";
-import { HlmButtonImports } from "@egose/shadcn-theme-ng/button";
-import { EgLayoutSimple, MenuItem } from "@egose/shadcn-theme-ng/layout-simple";
+import { Component } from '@angular/core';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { EgLayoutSimple, MenuItem } from '@egose/shadcn-theme-ng/layout-simple';
 
 @Component({
   selector: "app-demo",
   standalone: true,
-  imports: [...HlmButtonImports],
+  imports: [EgLayoutSimple, ...HlmButtonImports],
   template: \`
-    <eg-layout-simple [menuItems]="items">
+    <eg-layout-simple brandName="My workspace" [primaryNavigation]="items">
       <button hlmBtn variant="primary">Click</button>
     </eg-layout-simple>
   \`,
@@ -98,6 +166,55 @@ export class DemoComponent {
 }
 ```
 
+## Date picker values
+
+`hlm-date-picker` emits a native JS `Date` (or `null` when cleared) via the `dateChange` output. Read it in the
+controller with `(dateChange)`, a template ref (`picker.value()`), or a form binding (`ngModel`/`formControlName`,
+the picker is a `ControlValueAccessor`):
+
+```html
+<hlm-date-picker (dateChange)="onDate($event)">
+  <hlm-date-picker-input placeholder="Pick a date" />
+</hlm-date-picker>
+```
+
+```ts
+onDate(date: Date | null) {
+  // date is a JS Date, e.g. 2026-09-23T00:00:00 local time (or null on clear)
+}
+```
+
+Unlike the React `FormDatePicker` (which normalizes to local midnight), the Angular picker passes dates through
+untouched by default: calendar clicks usually arrive at local midnight already, but dates typed into the input are
+parsed with `new Date(value)`, where `"YYYY-MM-DD"` means UTC midnight — so the time portion can be non-zero. To
+normalize every value reaching the controller to local midnight, provide a custom config (no library changes needed):
+
+```ts
+import { provideHlmDatePickerConfig } from '@egose/shadcn-theme-ng/date-picker';
+
+@Component({
+  // ...
+  providers: [
+    provideHlmDatePickerConfig({
+      // Strip the time portion, mirroring React's normalizeDate.
+      transformDate: (date: Date) => new Date(date.getFullYear(), date.getMonth(), date.getDate()),
+      // Parse typed "YYYY-MM-DD" as a local date instead of new Date(value) (UTC).
+      parseDate: (value: string) => {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        if (!match) return null;
+        const date = new Date(+match[1], +match[2] - 1, +match[3]);
+        return isNaN(date.getTime()) ? null : date;
+      },
+    }),
+  ],
+})
+export class MyComponent {}
+```
+
+`transformDate` runs on every path into the model (calendar selection, typed input, `writeValue`), so the controller
+then always sees local-midnight dates. Related: the picker stays open after selection by default; add the
+`autoCloseOnSelect` attribute (or set it in the same config) to close it on select.
+
 ## Working example
 
 A complete Angular consumer app lives at [`@examples/standard`](https://github.com/egose/shadcn-theme/tree/main/packages/angular/@examples/standard) — see its `src/app/...` for real usage of `@egose/shadcn-theme-ng/button`, `.../layout-simple`, `.../form-text-input`, `.../autocomplete`, `.../select`, `.../form-checkbox`, `.../sheet`, etc.

package/accordion/README.md

@@ -1,64 +1,406 @@
-# Accordion
+# Accordion (`@egose/shadcn-theme-ng/accordion`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.2.0.
+A collapsible content panel set in the shadcn/ui Accordion style. Each section pairs a clickable
+trigger row with an expanding content region, so long option lists, FAQs, and settings groups stay
+compact until the user opens them.
 
-## Code scaffolding
+The Angular implementation is a thin styling layer over the headless
+[`BrnAccordion*` primitives from `@spartan-ng/brain/accordion`](https://www.spartan-ng.com/):
+`HlmAccordion` / `HlmAccordionItem` / `HlmAccordionTrigger` / `HlmAccordionContent` compose
+`BrnAccordion` / `BrnAccordionItem` / `BrnAccordionTrigger` / `BrnAccordionContent` via
+`hostDirectives` (or inheritance for the content), adding shadcn spacing, borders, typography, and
+`class` merging through `hlm()` from `@egose/shadcn-theme-ng/utils`. `HlmAccordionIcon` is a
+companion directive that styles an `ng-icon` (chevron-down) placed inside a trigger.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+> **Ships as:** `@egose/shadcn-theme-ng/accordion` and `@egose/shadcn-theme-ng-tw/accordion`
+> (the `tw:`-prefixed Tailwind variant). Both expose the identical TypeScript surface; only the
+> emitted Tailwind class strings differ. See the [package README](../../README.md) for install
+> steps, peer dependencies, and Tailwind setup. Do not publish this project directory independently.
+
+## Installation
 
 ```bash
-ng generate component component-name
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# tw:-prefixed Tailwind variant
+npm install @egose/shadcn-theme-ng-tw
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+Peer dependencies (Angular, `@spartan-ng/brain`, `@ng-icons/*`, `rxjs`, …) are documented in the
+[package README](../../README.md#peer-dependencies). This subpath additionally relies at runtime on
+`@egose/shadcn-theme-ng/utils` (`hlm()`), `@egose/shadcn-theme-ng/icon` (`provideHlmIconConfig`),
+and `@ng-icons/lucide` (`lucideChevronDown`) for the icon directive.
 
-```bash
-ng generate --help
+## Imports
+
+All symbols are exported from the subpath root (`projects/accordion/src/public-api.ts`):
+
+```ts
+import {
+  HlmAccordion,
+  HlmAccordionItem,
+  HlmAccordionTrigger,
+  HlmAccordionContent,
+  HlmAccordionIcon,
+  HlmAccordionImports,
+  HlmAccordionModule,
+} from '@egose/shadcn-theme-ng/accordion';
+// tw variant: replace with '@egose/shadcn-theme-ng-tw/accordion'
 ```
 
-## Building
+Standalone component — spread the `*Imports` array:
 
-To build the library, run:
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
 
-```bash
-ng build accordion
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `...`,
+})
+export class DemoComponent {}
+```
+
+NgModule-based consumer — import the module:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmAccordionModule } from '@egose/shadcn-theme-ng/accordion';
+
+@NgModule({ imports: [HlmAccordionModule] })
+export class DemoModule {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+## Anatomy / Structure
 
-### Publishing the Library
+```html
+<!-- hlm-accordion OR any element with hlmAccordion -->
+<hlm-accordion type="single" orientation="vertical">
+  <!-- hlm-accordion-item OR [hlmAccordionItem] OR brn-accordion-item[hlm] -->
+  <hlm-accordion-item>
+    <!-- any element with hlmAccordionTrigger -->
+    <button hlmAccordionTrigger>
+      Section title
+      <!-- chevron icon (either attribute spelling works) -->
+      <ng-icon hlmAccIcon name="lucideChevronDown" />
+    </button>
+    <!-- content element -->
+    <hlm-accordion-content>
+      <p>Collapsible body.</p>
+    </hlm-accordion-content>
+  </hlm-accordion-item>
+</hlm-accordion>
+```
 
-Once the project is built, you can publish your library by following these steps:
+Real selectors (from source):
 
-1. Navigate to the `dist` directory:
+| Class                 | Selector(s)                                                       | Kind      |
+| --------------------- | ----------------------------------------------------------------- | --------- |
+| `HlmAccordion`        | `[hlmAccordion], hlm-accordion`                                   | Directive |
+| `HlmAccordionItem`    | `[hlmAccordionItem], brn-accordion-item[hlm], hlm-accordion-item` | Directive |
+| `HlmAccordionTrigger` | `[hlmAccordionTrigger]`                                           | Directive |
+| `HlmAccordionContent` | `hlm-accordion-content`                                           | Component |
+| `HlmAccordionIcon`    | `ng-icon[egAccordionIcon], ng-icon[hlmAccIcon]`                   | Directive |
 
-   ```bash
-   cd dist/accordion
-   ```
+## API reference
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+### `HlmAccordion` — `[hlmAccordion], hlm-accordion`
 
-## Running unit tests
+Thin directive wrapper around `BrnAccordion` (inputs forwarded via `hostDirectives`).
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+| Input         | Type                        | Default         | Description                                                                 |
+| ------------- | --------------------------- | --------------- | --------------------------------------------------------------------------- |
+| `type`        | forwarded to `BrnAccordion` | (brain default) | `'single'` or `'multiple'` open-item behavior.                              |
+| `orientation` | forwarded to `BrnAccordion` | (brain default) | `'horizontal'` renders the root as `flex-row`, anything else as `flex-col`. |
+| `class`       | `ClassValue`                | `''`            | Extra classes merged via `hlm()`.                                           |
 
-```bash
-ng test
+### `HlmAccordionItem` — `[hlmAccordionItem], brn-accordion-item[hlm], hlm-accordion-item`
+
+Thin wrapper around `BrnAccordionItem`.
+
+| Input      | Type                            | Default | Description                               |
+| ---------- | ------------------------------- | ------- | ----------------------------------------- |
+| `isOpened` | forwarded to `BrnAccordionItem` | —       | Whether this item starts/sets open state. |
+| `class`    | `ClassValue`                    | `''`    | Extra classes merged via `hlm()`.         |
+
+### `HlmAccordionTrigger` — `[hlmAccordionTrigger]`
+
+Thin wrapper around `BrnAccordionTrigger` (no extra inputs — the whole `BrnAccordionTrigger`
+surface is inherited through `hostDirectives`).
+
+| Input   | Type         | Default | Description                       |
+| ------- | ------------ | ------- | --------------------------------- |
+| `class` | `ClassValue` | `''`    | Extra classes merged via `hlm()`. |
+
+### `HlmAccordionContent` — `hlm-accordion-content`
+
+Component **extending** `BrnAccordionContent`, so the `state()` signal (`'open' | 'closed'`) and
+all brain behavior are inherited. The open state switches the host between
+`grid-rows-[1fr]` and `hidden`; an inner `div[attr.inert]` keeps closed content out of the
+tab order.
+
+| Input   | Type         | Default | Description                       |
+| ------- | ------------ | ------- | --------------------------------- |
+| `class` | `ClassValue` | `''`    | Extra classes merged via `hlm()`. |
+
+### `HlmAccordionIcon` — `ng-icon[egAccordionIcon], ng-icon[hlmAccIcon]`
+
+Styling directive for the chevron `ng-icon` inside a trigger. It registers
+`provideIcons({ lucideChevronDown })` and `provideHlmIconConfig({ size: 'sm' })`, and applies the
+muted, small, animated sizing classes.
+
+| Input   | Type         | Default | Description                       |
+| ------- | ------------ | ------- | --------------------------------- |
+| `class` | `ClassValue` | `''`    | Extra classes merged via `hlm()`. |
+
+> **Selector quirk (read from source):** the trigger stylesheet contains a
+> `[&[data-state=open]>[egAccIcon]]:rotate-180` rule, but the icon directive itself matches
+> `egAccordionIcon` / `hlmAccIcon`. If you want the chevron to rotate automatically on open, add a
+> plain `egAccIcon` attribute to the icon element alongside the directive attribute
+> (see the rotation example below).
+
+## Examples
+
+### 1. Basic single accordion
+
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-basic',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <hlm-accordion type="single">
+      <hlm-accordion-item>
+        <button hlmAccordionTrigger>
+          Is it accessible?
+          <ng-icon hlmAccIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content>
+          <p>Yes. Triggers are real buttons and closed panels are inert.</p>
+        </hlm-accordion-content>
+      </hlm-accordion-item>
+      <hlm-accordion-item>
+        <button hlmAccordionTrigger>
+          Is it styled?
+          <ng-icon hlmAccIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content>
+          <p>Yes. It follows the shadcn/ui accordion look.</p>
+        </hlm-accordion-content>
+      </hlm-accordion-item>
+    </hlm-accordion>
+  `,
+})
+export class AccordionBasicComponent {}
+```
+
+```html
+<app-accordion-basic />
 ```
 
-## Running end-to-end tests
+### 2. Multiple open panels + attribute selectors on native elements
 
-For end-to-end (e2e) testing, run:
+`HlmAccordion` also works as an attribute on a `div`, and items accept the long
+`brn-accordion-item[hlm]` spelling for interop with raw brain templates.
 
-```bash
-ng e2e
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-multiple',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <div hlmAccordion type="multiple">
+      <div hlmAccordionItem>
+        <button hlmAccordionTrigger>
+          Shipping
+          <ng-icon egAccordionIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content><p>Ships worldwide.</p></hlm-accordion-content>
+      </div>
+      <div hlmAccordionItem>
+        <button hlmAccordionTrigger>
+          Returns
+          <ng-icon egAccordionIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content><p>30-day returns.</p></hlm-accordion-content>
+      </div>
+    </div>
+  `,
+})
+export class AccordionMultipleComponent {}
+```
+
+### 3. Pre-opened item via `isOpened`
+
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-open',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <hlm-accordion type="single">
+      <hlm-accordion-item [isOpened]="true">
+        <button hlmAccordionTrigger>
+          Open by default
+          <ng-icon hlmAccIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content>
+          <p>This panel renders expanded on first paint.</p>
+        </hlm-accordion-content>
+      </hlm-accordion-item>
+      <hlm-accordion-item>
+        <button hlmAccordionTrigger>
+          Closed by default
+          <ng-icon hlmAccIcon name="lucideChevronDown" />
+        </button>
+        <hlm-accordion-content><p>Opens on click.</p></hlm-accordion-content>
+      </hlm-accordion-item>
+    </hlm-accordion>
+  `,
+})
+export class AccordionOpenComponent {}
+```
+
+### 4. Chevron that rotates on open
+
+The stylesheet rotates a child carrying a bare `egAccIcon` attribute when the trigger reports
+`data-state="open"`. Combine it with the icon directive so you keep both the sizing and the
+rotation:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-rotate',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <hlm-accordion type="single">
+      @for (faq of faqs; track faq.q) {
+        <hlm-accordion-item>
+          <button hlmAccordionTrigger>
+            {{ faq.q }}
+            <ng-icon hlmAccIcon egAccIcon name="lucideChevronDown" />
+          </button>
+          <hlm-accordion-content>
+            <p>{{ faq.a }}</p>
+          </hlm-accordion-content>
+        </hlm-accordion-item>
+      }
+    </hlm-accordion>
+  `,
+})
+export class AccordionRotateComponent {
+  readonly faqs = [
+    { q: 'What is shadcn?', a: 'A set of re-usable UI patterns.' },
+    { q: 'What is spartan-ng?', a: 'Headless Angular primitives (brain) plus styled (helm) components.' },
+  ];
+}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### 5. Data-driven FAQ with custom classes
+
+Every piece accepts a `class` input merged through `hlm()`, so per-item tweaks compose cleanly:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-faq',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <hlm-accordion type="single" class="tw:rounded-lg tw:border tw:px-4">
+      @for (faq of faqs(); track faq.q) {
+        <hlm-accordion-item class="tw:last:border-b-0">
+          <button hlmAccordionTrigger class="tw:text-base">
+            {{ faq.q }}
+            <ng-icon hlmAccIcon name="lucideChevronDown" />
+          </button>
+          <hlm-accordion-content class="tw:text-muted-foreground">
+            <p>{{ faq.a }}</p>
+            @if (faq.link) {
+              <a class="tw:underline" [href]="faq.link">Learn more</a>
+            }
+          </hlm-accordion-content>
+        </hlm-accordion-item>
+      }
+    </hlm-accordion>
+  `,
+})
+export class AccordionFaqComponent {
+  readonly faqs = signal([
+    { q: 'How do I install?', a: 'npm install @egose/shadcn-theme-ng', link: '' },
+    { q: 'Which Tailwind setup?', a: 'Pick the plain or tw: variant.', link: '' },
+  ]);
+}
+```
+
+### 6. Horizontal orientation
+
+`HlmAccordion` reads the brain `orientation()` signal: `'horizontal'` switches the root to
+`flex-row`, anything else stays `flex-col`.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmAccordionImports } from '@egose/shadcn-theme-ng/accordion';
+
+@Component({
+  selector: 'app-accordion-horizontal',
+  standalone: true,
+  imports: [...HlmAccordionImports],
+  template: `
+    <hlm-accordion type="multiple" orientation="horizontal" class="tw:gap-2">
+      <hlm-accordion-item class="tw:border tw:rounded-md tw:px-3">
+        <button hlmAccordionTrigger>A <ng-icon hlmAccIcon name="lucideChevronDown" /></button>
+        <hlm-accordion-content><p>First column.</p></hlm-accordion-content>
+      </hlm-accordion-item>
+      <hlm-accordion-item class="tw:border tw:rounded-md tw:px-3">
+        <button hlmAccordionTrigger>B <ng-icon hlmAccIcon name="lucideChevronDown" /></button>
+        <hlm-accordion-content><p>Second column.</p></hlm-accordion-content>
+      </hlm-accordion-item>
+    </hlm-accordion>
+  `,
+})
+export class AccordionHorizontalComponent {}
+```
+
+## Accessibility notes
+
+- Triggers are native `<button>` elements enhanced by `BrnAccordionTrigger`: keyboard focus,
+  `Enter`/`Space` activation, and arrow-key navigation between items come from the brain primitive.
+- `HlmAccordionContent` marks its inner wrapper `inert` while closed so hidden content is removed
+  from the tab order and assistive-technology traversal.
+- The icon is decorative (`pointer-events-none`); keep the trigger label as real text so screen
+  readers announce the section name. If you add `sr-only` helper text, put it inside the trigger,
+  not the icon.
+- `HlmAccordionIcon` sets the icon size through `provideHlmIconConfig({ size: 'sm' })` — overriding
+  the global icon config locally, so surrounding icons are unaffected.
+
+## Theming / CSS variables
+
+Styling is class-based (`hlm()` + Tailwind tokens such as `border-border`, `text-muted-foreground`,
+`ring-ring/50`); no component-specific CSS variables are declared. Pass `class` to any piece to
+extend the look, and configure the shadcn theme tokens globally as described in the
+[package README](../../README.md).
 
-## Additional Resources
+## Related subpaths
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+- `@egose/shadcn-theme-ng/icon` — `provideHlmIconConfig`, `HlmIcon` (icon sizing used by the trigger icon)
+- `@egose/shadcn-theme-ng/collapsible` — single-region expand/collapse primitive
+- `@egose/shadcn-theme-ng/separator` — dividers between accordion items
+- `@egose/shadcn-theme-ng/typography` — prose styling for rich accordion bodies