@egose/shadcn-theme-ng 0.1.0 → 0.2.0

package/popover/README.md

@@ -1,3 +1,332 @@
-# Popover Subpath
+# Popover (`@egose/shadcn-theme-ng/popover`)
 
-This project ships only as `@egose/shadcn-theme-ng/popover` or `@egose/shadcn-theme-ng-tw/popover`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+Floating panel anchored to a button (shadcn/ui `popover` equivalent). Thin shadcn styling directives over the spartan-ng `BrnPopover` brain family: a stateful `hlm-popover` root, a `button[hlmPopoverTrigger]` opener, portal/content pieces for the floating panel, and header/title/description typography helpers.
+
+Ships as `@egose/shadcn-theme-ng/popover` and `@egose/shadcn-theme-ng-tw/popover` (tw: variant). See the [package README](../../README.md) for installation, peer dependencies, Tailwind setup, and testing. 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
+```
+
+Peer dependencies are inherited from the package root (see [package README](../../README.md)). This subpath itself declares `@angular/common`, `@angular/core` as peers plus a `tslib` runtime dependency; at runtime it uses `@spartan-ng/brain/popover` and `@spartan-ng/brain/core`. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmPopover, // directive: [hlmPopover],hlm-popover
+  HlmPopoverTrigger, // directive: button[hlmPopoverTrigger],button[hlmPopoverTriggerFor]
+  HlmPopoverPortal, // directive: [hlmPopoverPortal]
+  HlmPopoverContent, // directive: [hlmPopoverContent],hlm-popover-content
+  HlmPopoverHeader, // directive: [hlmPopoverHeader],hlm-popover-header
+  HlmPopoverTitle, // directive: [hlmPopoverTitle]
+  HlmPopoverDescription, // directive: [hlmPopoverDescription]
+  HlmPopoverImports, // all seven above
+  HlmPopoverModule, // NgModule wrapping HlmPopoverImports
+} from '@egose/shadcn-theme-ng/popover';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Open</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <p>Hello</p>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmPopoverModule } from '@egose/shadcn-theme-ng/popover';
+
+@NgModule({ imports: [HlmPopoverModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/popover`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<hlm-popover>
+  <!-- opener (must be a <button>) -->
+  <button hlmPopoverTrigger type="button">Settings</button>
+
+  <!-- floating panel: content styling + portal projection -->
+  <hlm-popover-content *hlmPopoverPortal class="tw:w-80">
+    <div hlmPopoverHeader>
+      <h4 hlmPopoverTitle>Dimensions</h4>
+      <p hlmPopoverDescription>Set the size of the layer.</p>
+    </div>
+    <!-- panel body -->
+  </hlm-popover-content>
+</hlm-popover>
+```
+
+The two-directive split on the panel is load-bearing: `hlmPopoverContent` paints the panel (fixed `w-72`, animations, `data-state` reflection), while `*hlmPopoverPortal` (a `BrnPopoverContent` host) projects it into the overlay at the anchored position. Always use them together as `hlm-popover-content *hlmPopoverPortal`.
+
+| Class                   | Selector                                                 | Role                                                  |
+| ----------------------- | -------------------------------------------------------- | ----------------------------------------------------- |
+| `HlmPopover`            | `[hlmPopover],hlm-popover`                               | Stateful root (`BrnPopover` host)                     |
+| `HlmPopoverTrigger`     | `button[hlmPopoverTrigger],button[hlmPopoverTriggerFor]` | Opener (`BrnPopoverTrigger` host; must be `<button>`) |
+| `HlmPopoverPortal`      | `[hlmPopoverPortal]`                                     | Overlay projection (`BrnPopoverContent` host)         |
+| `HlmPopoverContent`     | `[hlmPopoverContent],hlm-popover-content`                | Panel styling + `data-state` mirror                   |
+| `HlmPopoverHeader`      | `[hlmPopoverHeader],hlm-popover-header`                  | Header stack (`flex flex-col gap-1 text-sm`)          |
+| `HlmPopoverTitle`       | `[hlmPopoverTitle]`                                      | Title (`font-medium`)                                 |
+| `HlmPopoverDescription` | `[hlmPopoverDescription]`                                | Subtitle (`text-muted-foreground`)                    |
+
+## API reference
+
+| Selector                                                               | Inputs (incl. host passthroughs)                                                                                         | Outputs                                     | Notes                                                                                                                                                       |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[hlmPopover],hlm-popover` (`HlmPopover`)                              | `align`, `attachTo`, `autoFocus`, `closeOnOutsidePointerEvents`, `offsetX`, `sideOffset`, `state` (all via `BrnPopover`) | `stateChanged`, `closed` (via `BrnPopover`) | No shadcn inputs of its own; `data-slot="popover"`                                                                                                          |
+| `button[hlmPopoverTrigger]` (`HlmPopoverTrigger`)                      | `id`, `hlmPopoverTriggerFor` (→ `brnPopoverTriggerFor`), `type` (all via `BrnPopoverTrigger`)                            | —                                           | `data-slot="popover-trigger"`. `hlmPopoverTriggerFor` targets an explicit popover when the trigger lives outside the root                                   |
+| `[hlmPopoverPortal]` (`HlmPopoverPortal`)                              | `context`, `class` (via `BrnPopoverContent`)                                                                             | —                                           | Structural directive (`*hlmPopoverPortal`); `class` merges onto the overlay panel                                                                           |
+| `[hlmPopoverContent]` (`HlmPopoverContent`)                            | —                                                                                                                        | —                                           | Exposes `state` (brain state signal, default `signal('closed')`); mirrors it to `data-state` via `Renderer2` for the `data-open:`/`data-closed:` animations |
+| `[hlmPopoverHeader]` / `[hlmPopoverTitle]` / `[hlmPopoverDescription]` | —                                                                                                                        | —                                           | Typography only                                                                                                                                             |
+
+Panel styling (`HlmPopoverContent`): `bg-popover text-popover-foreground rounded-md p-4 text-sm shadow-md ring-1 ring-foreground/10 relative flex w-72 flex-col gap-4 outline-none` plus open/close zoom+fade animations keyed off `data-state`/`data-side`.
+
+## Examples
+
+### 1. Basic popover with header
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-popover-basic',
+  standalone: true,
+  imports: [...HlmPopoverImports, HlmButton],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger hlmButton variant="secondary" appearance="outline" type="button">Open settings</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Dimensions</h4>
+          <p hlmPopoverDescription>Set the size of the layer.</p>
+        </div>
+        <div class="tw:grid tw:gap-2 tw:text-sm">
+          <label class="tw:grid tw:gap-1"
+            >Width <input class="tw:border tw:rounded tw:px-2 tw:py-1" value="100%"
+          /></label>
+          <label class="tw:grid tw:gap-1"
+            >Height <input class="tw:border tw:rounded tw:px-2 tw:py-1" value="24px"
+          /></label>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverBasicComponent {}
+```
+
+### 2. Placement, offsets, and state events
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-placement',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover
+      align="start"
+      [sideOffset]="8"
+      [closeOnOutsidePointerEvents]="true"
+      (stateChanged)="open.set($event === 'open')"
+      (closed)="open.set(false)"
+    >
+      <button hlmPopoverTrigger type="button">Aligned start, offset 8</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <p class="tw:text-sm">Panel state: {{ open() ? 'open' : 'closed' }}.</p>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverPlacementComponent {
+  readonly open = signal(false);
+}
+```
+
+`align`, `sideOffset`, `closeOnOutsidePointerEvents` are brain inputs on `HlmPopover`; `stateChanged`/`closed` are its outputs.
+
+### 3. Form inside a popover (template-driven)
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+
+@Component({
+  selector: 'app-popover-form',
+  standalone: true,
+  imports: [FormsModule, ...HlmPopoverImports, HlmInput, ...HlmLabelImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Invite member</button>
+      <hlm-popover-content *hlmPopoverPortal class="tw:w-80">
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Invite</h4>
+          <p hlmPopoverDescription>They receive an email invitation.</p>
+        </div>
+        <div class="tw:grid tw:gap-1.5">
+          <label hlmLabel for="invite-email">Email</label>
+          <input hlmInput id="invite-email" [(ngModel)]="email" type="email" placeholder="ada@example.com" />
+          <button type="button" (click)="invite()">Send invite</button>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverFormComponent {
+  email = '';
+
+  invite(): void {
+    console.log('invite', this.email);
+  }
+}
+```
+
+### 4. Custom panel width via portal `class`
+
+The portal's `class` input lands on the overlay host; the content directive keeps its own `w-72` unless you override it on the element as well.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-wide',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Wide panel</button>
+      <hlm-popover-content *hlmPopoverPortal class="tw:w-96">
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Preview</h4>
+          <p hlmPopoverDescription>A wider panel for rich content.</p>
+        </div>
+        <div class="tw:grid tw:grid-cols-2 tw:gap-2 tw:text-sm">
+          <div class="tw:rounded tw:bg-muted tw:p-2">Column A</div>
+          <div class="tw:rounded tw:bg-muted tw:p-2">Column B</div>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverWideComponent {}
+```
+
+### 5. External trigger (`hlmPopoverTriggerFor`)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-external',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover #pop="hlmPopover">
+      <hlm-popover-content *hlmPopoverPortal>
+        <p class="tw:text-sm">Triggered from outside the root.</p>
+      </hlm-popover-content>
+    </hlm-popover>
+
+    <button hlmPopoverTriggerFor [hlmPopoverTriggerFor]="pop" type="button">Open from here</button>
+  `,
+})
+export class PopoverExternalComponent {}
+```
+
+> The exact template-ref export name follows the brain `BrnPopover` directive (`#pop="…"`) — verify against your installed `@spartan-ng/brain` version if the alias differs.
+
+### 6. Async content + loading state
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-async',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover (stateChanged)="onState($event)">
+      <button hlmPopoverTrigger type="button">Recent activity</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Activity</h4>
+          <p hlmPopoverDescription>{{ loading() ? 'Loading…' : 'Last 3 events.' }}</p>
+        </div>
+        @for (e of events(); track e) {
+          <p class="tw:text-sm">{{ e }}</p>
+        } @empty {
+          <p class="tw:text-sm tw:text-muted-foreground">Nothing yet.</p>
+        }
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverAsyncComponent {
+  readonly events = signal<string[]>([]);
+  readonly loading = signal(false);
+
+  async onState(state: string): Promise<void> {
+    if (state !== 'open' || this.events().length) return;
+    this.loading.set(true);
+    await new Promise((r) => setTimeout(r, 400));
+    this.events.set(['Deploy succeeded', 'Review requested', 'Comment added']);
+    this.loading.set(false);
+  }
+}
+```
+
+## Accessibility notes
+
+- Triggers must be `<button>` (both selector variants require it) with a text label; the brain layer wires `aria-expanded`, `aria-controls`, and focus return.
+- Keep a heading (`hlmPopoverTitle`) as the first element when the panel conveys a topic — screen-reader users land inside the panel on open.
+- `autoFocus` (brain input) controls initial focus; form panels should focus the first field, read-only panels should keep focus on the trigger side and let users tab in.
+- `Escape`/outside-pointer close comes from the brain defaults (`closeOnOutsidePointerEvents` is configurable); don't trap focus manually.
+
+## Theming / CSS variables
+
+No theming inputs. The panel uses `bg-popover text-popover-foreground ring-foreground/10`; header/title/description use text tokens. Widen via portal `class` (example 4); state-driven animations read the mirrored `data-state`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/tooltip` — hover hint vs this component's click-anchored panel.
+- `@egose/shadcn-theme-ng/dropdown-menu`, `@egose/shadcn-theme-ng/select` — menu/select overlays built on the same brain overlay concepts.
+- `@egose/shadcn-theme-ng/input`, `@egose/shadcn-theme-ng/label` — form controls commonly hosted inside popover panels.

package/progress/README.md

@@ -1,11 +1,317 @@
-# Progress
+# Progress (`@egose/shadcn-theme-ng/progress`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+Determinate/indeterminate progress bar (shadcn/ui `progress` equivalent). Thin shadcn styling directives over the spartan-ng `BrnProgress` brain family: `hlm-progress` owns the track + value semantics (`value`, `max`, `getValueLabel`), and the inner `hlmProgressIndicator` bar positions itself from the brain value with RTL awareness and an indeterminate animation state.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/progress` and `@egose/shadcn-theme-ng-tw/progress` (tw: variant). See the [package README](../../README.md) for installation, peer dependencies, Tailwind setup, and testing. Do not publish this project directory independently.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build progress
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies are inherited from the package root (see [package README](../../README.md)). This subpath itself declares `@angular/common`, `@angular/core`, `@spartan-ng/brain` as peers plus a `tslib` runtime dependency; at runtime the indicator also reads Angular CDK `Directionality` for RTL. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmProgress, // directive: hlm-progress,[hlmProgress]
+  HlmProgressIndicator, // directive: [hlmProgressIndicator],hlm-progress-indicator
+  HlmProgressImports, // readonly [HlmProgress, HlmProgressIndicator]
+  HlmProgressModule, // NgModule wrapping HlmProgressImports
+} from '@egose/shadcn-theme-ng/progress';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="40" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+  `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmProgressModule } from '@egose/shadcn-theme-ng/progress';
+
+@NgModule({ imports: [HlmProgressModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/progress`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<!-- determinate -->
+<hlm-progress [value]="value()" [max]="100">
+  <hlm-progress-indicator hlmProgressIndicator />
+</hlm-progress>
+
+<!-- attribute-selector form -->
+<div hlmProgress [value]="40" [max]="100">
+  <div hlmProgressIndicator></div>
+</div>
+
+<!-- indeterminate (no value) -->
+<hlm-progress>
+  <hlm-progress-indicator hlmProgressIndicator />
+</hlm-progress>
+```
+
+| Class                  | Selector                                        | Role                                                                                |
+| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `HlmProgress`          | `hlm-progress,[hlmProgress]`                    | Track (`BrnProgress` host: `value`, `max`, `getValueLabel`); `data-slot="progress"` |
+| `HlmProgressIndicator` | `[hlmProgressIndicator],hlm-progress-indicator` | Fill bar (`BrnProgressIndicator` host); `data-slot="progress-indicator"`            |
+
+The indicator computes `translateX(-offset%)` from `100 - value` (defaulting `null`/`undefined` value to `100` for the offset math) and flips the sign in RTL via CDK `Directionality`. When the brain value is `null`/`undefined` it adds the `animate-indeterminate` class instead of a static fill.
+
+## API reference
+
+### `HlmProgress` (`hlm-progress,[hlmProgress]`)
+
+| Member          | Kind                      | Type                          | Notes                                                        |
+| --------------- | ------------------------- | ----------------------------- | ------------------------------------------------------------ |
+| `value`         | input (via `BrnProgress`) | `number \| null \| undefined` | Current value; `null`/`undefined` → indeterminate            |
+| `max`           | input (via `BrnProgress`) | `number`                      | Scale maximum (commonly `100`)                               |
+| `getValueLabel` | input (via `BrnProgress`) | `(value, max) => string`      | Accessible value-text factory (see brain docs for signature) |
+
+No shadcn inputs of its own. Track styling: `bg-muted h-1.5 rounded-full relative inline-flex w-full overflow-hidden`.
+
+### `HlmProgressIndicator` (`[hlmProgressIndicator],hlm-progress-indicator`)
+
+No public inputs/outputs/methods. Internals (protected, for understanding only): `_transform` (computed `translateX()`), `_indeterminate` (computed `value == null`). Fill styling: `bg-primary h-full w-full flex-1 transition-all`; indeterminate state toggles `animate-indeterminate`.
+
+## Examples
+
+### 1. Basic determinate bar
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-basic',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="value()" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm tw:text-muted-foreground">{{ value() }}%</p>
+    <button type="button" (click)="value.set(Math.min(100, value() + 10))">+10</button>
+  `,
+})
+export class ProgressBasicComponent {
+  readonly value = signal(40);
+  protected readonly Math = Math;
+}
+```
+
+### 2. Timer / simulated upload
+
+```ts
+import { Component, signal, OnDestroy } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-timer',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="progress()" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <div class="tw:flex tw:gap-2">
+      <button type="button" (click)="start()">Start</button>
+      <button type="button" (click)="reset()">Reset</button>
+    </div>
+  `,
+})
+export class ProgressTimerComponent implements OnDestroy {
+  readonly progress = signal(0);
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  start(): void {
+    this.stop();
+    this.timer = setInterval(() => {
+      this.progress.update((v) => (v >= 100 ? 100 : v + 2));
+      if (this.progress() >= 100) this.stop();
+    }, 100);
+  }
+
+  reset(): void {
+    this.stop();
+    this.progress.set(0);
+  }
+
+  ngOnDestroy(): void {
+    this.stop();
+  }
+
+  private stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+}
+```
+
+### 3. Indeterminate (unknown duration)
+
+Omit `value` entirely — the indicator switches to the `animate-indeterminate` treatment.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-indeterminate',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <button type="button" (click)="load()">Fetch report</button>
+    @if (loading()) {
+      <hlm-progress aria-label="Loading report">
+        <hlm-progress-indicator hlmProgressIndicator />
+      </hlm-progress>
+    }
+  `,
+})
+export class ProgressIndeterminateComponent {
+  readonly loading = signal(false);
+
+  async load(): Promise<void> {
+    this.loading.set(true);
+    await new Promise((r) => setTimeout(r, 1500));
+    this.loading.set(false);
+  }
+}
 ```
+
+### 4. Custom scale (`max !== 100`) + accessible label
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-scale',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="done()" [max]="total()" [getValueLabel]="label" aria-label="Migration progress">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm">{{ done() }} of {{ total() }} rows migrated</p>
+  `,
+})
+export class ProgressScaleComponent {
+  readonly done = signal(37);
+  readonly total = signal(200);
+
+  readonly label = (value: number | null | undefined, max: number): string => `${value ?? 0} of ${max} rows`;
+}
+```
+
+> `getValueLabel` is the brain hook for the `aria-valuetext`; keep the visible text in sync (as above) so sighted and SR users agree.
+
+### 5. Multi-step wizard
+
+```ts
+import { Component, signal, computed } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-steps',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="step()" [max]="steps.length">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm">Step {{ step() }} of {{ steps.length }}: {{ steps[step() - 1] }}</p>
+    <div class="tw:flex tw:gap-2">
+      <button type="button" (click)="prev()" [disabled]="step() <= 1">Back</button>
+      <button type="button" (click)="next()" [disabled]="step() >= steps.length">Next</button>
+    </div>
+  `,
+})
+export class ProgressStepsComponent {
+  readonly steps = ['Account', 'Profile', 'Confirm'];
+  readonly step = signal(1);
+
+  prev(): void {
+    this.step.update((s) => Math.max(1, s - 1));
+  }
+  next(): void {
+    this.step.update((s) => Math.min(this.steps.length, s + 1));
+  }
+}
+```
+
+### 6. Error / complete states and NgModule form
+
+```ts
+import { NgModule, Component, signal, computed } from '@angular/core';
+import { HlmProgressImports, HlmProgressModule } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-states',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="value()" [max]="100" [class]="barClass()">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm" [class.tw:text-destructive]="failed()">
+      {{ failed() ? 'Upload failed — retrying…' : value() >= 100 ? 'Complete' : 'Uploading…' }}
+    </p>
+  `,
+})
+export class ProgressStatesComponent {
+  readonly value = signal(75);
+  readonly failed = signal(false);
+  readonly barClass = computed(() => (this.failed() ? 'tw:[&>[data-slot=progress-indicator]]:tw:bg-destructive' : ''));
+}
+
+@NgModule({ imports: [HlmProgressModule] })
+export class ProgressLegacyModule {}
+```
+
+> There is no `state`/`variant` input — success/error tints are done with plain `class` overrides targeting the indicator (as above), since the indicator carries `data-slot="progress-indicator"`.
+
+## Accessibility notes
+
+- The brain `BrnProgress` exposes `role="progressbar"` with `aria-valuemin`/`max`/`now` (plus `aria-valuetext` via `getValueLabel`) — always provide `aria-label`/`aria-labelledby` unless surrounding text already names the bar.
+- Indeterminate bars (no `value`) must still be labelled ("Loading report") so SR users know what is pending; pair with status text or an `aria-live` region for completion.
+- Don't use progress as the _only_ conveyor of state — mirror percent/steps in text (examples 1/4/5).
+- Color overrides (example 6) are decorative; keep the text label as the source of truth for error/complete states.
+
+## Theming / CSS variables
+
+No theming inputs. Track is `bg-muted`, fill is `bg-primary`; both follow shadcn tokens automatically. Tint the fill per-instance with a `class` override on the track targeting `[data-slot=progress-indicator]`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/skeleton`, `@egose/shadcn-theme-ng/spinner` — alternative loading indicators (skeleton screens, spinners) vs this determinate bar.
+- `@egose/shadcn-theme-ng/sonner` — toast completion notices to pair with a finished upload.