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

package/sonner/README.md

@@ -1,3 +1,347 @@
-# Sonner Subpath
+# Sonner (`@egose/shadcn-theme-ng/sonner`)
 
-This project ships only as `@egose/shadcn-theme-ng/sonner` or `@egose/shadcn-theme-ng-tw/sonner`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+Toast notifications for Angular, styled like [shadcn/ui Sonner](https://ui.shadcn.com/docs/components/sonner). This subpath ships a single standalone component, `HlmToaster`, which is a thin shadcn-styled wrapper around the `NgxSonnerToaster` component from [`ngx-sonner`](https://github.com/adamwathan/ngx-sonner) (the Angular port of [sonner](https://sonner.emilkowal.ski/)). Place one `<hlm-toaster />` at your app root, then fire toasts imperatively with the `toast()` helpers from `ngx-sonner`.
+
+> **Ships as:** `@egose/shadcn-theme-ng/sonner` and `@egose/shadcn-theme-ng-tw/sonner` (the `tw:`-prefixed Tailwind variant). See the [package README](../../README.md) for install steps, peer dependencies, Tailwind setup, and testing/release guidance. 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
+```
+
+This library has no extra runtime install beyond the package itself — `ngx-sonner` is installed transitively. See the [package README](../../README.md) for the full peer-dependency table (`@angular/core`, `@angular/common`, `@spartan-ng/brain`, `rxjs`, etc.) and the Tailwind variant contract.
+
+> You call `toast()`, `toast.success()`, etc. from the **`ngx-sonner`** package, not from this subpath. This subpath only provides the styled `<hlm-toaster />` outlet component.
+
+## Imports
+
+All public symbols are re-exported from `projects/sonner/src/public-api.ts`:
+
+```ts
+import { HlmToaster, HlmToasterImports, HlmToasterModule } from '@egose/shadcn-theme-ng/sonner';
+// tw variant:
+// import { HlmToaster, HlmToasterImports, HlmToasterModule } from '@egose/shadcn-theme-ng-tw/sonner';
+```
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmToasterImports } from '@egose/shadcn-theme-ng/sonner';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [...HlmToasterImports],
+  template: `<hlm-toaster />`,
+})
+export class AppComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmToasterModule } from '@egose/shadcn-theme-ng/sonner';
+
+@NgModule({ imports: [HlmToasterModule] })
+export class AppModule {}
+```
+
+| Symbol              | Kind                 | Description                                      |
+| ------------------- | -------------------- | ------------------------------------------------ |
+| `HlmToaster`        | Standalone component | The `<hlm-toaster>` outlet. Renders toasts.      |
+| `HlmToasterImports` | `const` array        | `[HlmToaster]` — spread into `imports: [...]`.   |
+| `HlmToasterModule`  | NgModule             | Imports + re-exports `HlmToaster` for NgModules. |
+
+## Anatomy / Structure
+
+Render exactly one toaster outlet, typically in `AppComponent`:
+
+```html
+<!-- app.component.html -->
+<hlm-toaster />
+<router-outlet />
+```
+
+With common options:
+
+```html
+<hlm-toaster
+  theme="system"
+  position="top-center"
+  [richColors]="true"
+  [expand]="true"
+  [closeButton]="true"
+  [duration]="5000"
+  [visibleToasts]="5"
+/>
+```
+
+The component template forwards everything to `<ngx-sonner-toaster>` internally — you never write `<ngx-sonner-toaster>` yourself.
+
+## API reference
+
+### `HlmToaster` — selector `hlm-toaster` (component)
+
+All inputs are Angular signal `input()`s mirroring `ToasterProps` from `ngx-sonner`.
+
+| Input           | Type                                                              | Default                                                                                                                                                                                                               | Description                                                                                                     |
+| --------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `invert`        | `boolean` (coerced with `booleanAttribute`)                       | `false`                                                                                                                                                                                                               | Dark mode inversion.                                                                                            |
+| `theme`         | `ToasterProps['theme']` (`'light' \| 'dark' \| 'system'` approx.) | `'light'`                                                                                                                                                                                                             | Color theme of the toasts.                                                                                      |
+| `position`      | `ToasterProps['position']`                                        | `'bottom-right'`                                                                                                                                                                                                      | Screen corner/edge: e.g. `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. |
+| `hotKey`        | `ToasterProps['hotkey']` (`string[]`)                             | `['altKey', 'KeyT']`                                                                                                                                                                                                  | Hotkey that focuses/expands toasts.                                                                             |
+| `richColors`    | `boolean` (coerced)                                               | `false`                                                                                                                                                                                                               | Success/error color accents.                                                                                    |
+| `expand`        | `boolean` (coerced)                                               | `false`                                                                                                                                                                                                               | Expand all toasts by default (else stacked).                                                                    |
+| `duration`      | `number` (coerced with `numberAttribute`)                         | `4000`                                                                                                                                                                                                                | Default toast lifetime in ms.                                                                                   |
+| `visibleToasts` | `number` (coerced)                                                | `3`                                                                                                                                                                                                                   | Max simultaneously visible toasts.                                                                              |
+| `closeButton`   | `boolean` (coerced)                                               | `false`                                                                                                                                                                                                               | Show an × close button on every toast.                                                                          |
+| `toastOptions`  | `ToasterProps['toastOptions']`                                    | `{ classes: { toast: 'group toast group-[.toaster]:bg-background …', description: 'group-[.toast]:text-muted-foreground', actionButton: 'group-[.toast]:bg-primary …', cancelButton: 'group-[.toast]:bg-muted …' } }` | Per-toast default options + shadcn class overrides.                                                             |
+| `offset`        | `ToasterProps['offset']`                                          | `null`                                                                                                                                                                                                                | Pixel offset from the viewport edge.                                                                            |
+| `dir`           | `ToasterProps['dir']`                                             | `'auto'`                                                                                                                                                                                                              | Text direction (`auto` / `ltr` / `rtl`).                                                                        |
+| `class`         | `ClassValue` (aliased input `userClass`)                          | `''`                                                                                                                                                                                                                  | Extra classes merged via `hlm('toaster group', …)` onto the outlet.                                             |
+| `style`         | `Record<string, string>` (aliased input `userStyle`)              | `{}`                                                                                                                                                                                                                  | Inline styles forwarded to `ngx-sonner-toaster`.                                                                |
+
+No outputs, no methods. The host element gets computed class `toaster group` (+ your `class`).
+
+> `toast()`, `toast.success()`, `toast.error()`, `toast.promise()`, `toast.dismiss()` etc. are imported from **`ngx-sonner`**, not from this subpath:
+>
+> ```ts
+> import { toast } from 'ngx-sonner';
+> ```
+
+## Examples
+
+### 1. Basic setup + plain toast
+
+Add the outlet once at the app root.
+
+```ts
+// app.component.ts
+import { Component } from '@angular/core';
+import { HlmToasterImports } from '@egose/shadcn-theme-ng/sonner';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [...HlmToasterImports],
+  template: `
+    <hlm-toaster />
+    <router-outlet />
+  `,
+})
+export class AppComponent {}
+```
+
+Fire a toast from anywhere:
+
+```ts
+// demo.component.ts
+import { Component } from '@angular/core';
+import { toast } from 'ngx-sonner';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-basic',
+  standalone: true,
+  imports: [HlmButton],
+  template: `<button hlmBtn (click)="notify()">Show toast</button>`,
+})
+export class DemoBasic {
+  notify() {
+    toast('Event created', { description: 'Your event is now live.' });
+  }
+}
+```
+
+### 2. Success / error / warning states
+
+```ts
+// demo-states.component.ts
+import { Component } from '@angular/core';
+import { toast } from 'ngx-sonner';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-states',
+  standalone: true,
+  imports: [...HlmButtonImports],
+  template: `
+    <div class="flex gap-2">
+      <button hlmBtn variant="default" (click)="ok()">Success</button>
+      <button hlmBtn variant="destructive" (click)="fail()">Error</button>
+      <button hlmBtn variant="secondary" (click)="warn()">Warning</button>
+      <button hlmBtn variant="outline" (click)="info()">Info</button>
+    </div>
+  `,
+})
+export class DemoStates {
+  ok() {
+    toast.success('Profile saved', { description: 'Your changes are live.' });
+  }
+  fail() {
+    toast.error('Upload failed', { description: 'File exceeds 10 MB.' });
+  }
+  warn() {
+    toast.warning('Session expiring', { description: 'You will be logged out in 2 minutes.' });
+  }
+  info() {
+    toast.info('New version', { description: 'Refresh to get the latest UI.' });
+  }
+}
+```
+
+### 3. Positions, themes, rich colors
+
+```html
+<!-- Top-center, system theme, colored toasts with close buttons -->
+<hlm-toaster position="top-center" theme="system" [richColors]="true" [closeButton]="true" [expand]="true" />
+```
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmToasterImports } from '@egose/shadcn-theme-ng/sonner';
+
+@Component({
+  selector: 'demo-position',
+  standalone: true,
+  imports: [...HlmToasterImports],
+  template: ` <hlm-toaster [position]="position()" theme="dark" [visibleToasts]="5" /> `,
+})
+export class DemoPosition {
+  // 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  readonly position = signal<'top-center'>('top-center');
+}
+```
+
+### 4. Actions, cancellation, and durations
+
+```ts
+// demo-actions.component.ts
+import { Component } from '@angular/core';
+import { toast } from 'ngx-sonner';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-actions',
+  standalone: true,
+  imports: [...HlmButtonImports],
+  template: `
+    <div class="flex gap-2">
+      <button hlmBtn (click)="withAction()">Undoable delete</button>
+      <button hlmBtn variant="outline" (click)="sticky()">Sticky toast</button>
+      <button hlmBtn variant="ghost" (click)="dismissAll()">Dismiss all</button>
+    </div>
+  `,
+})
+export class DemoActions {
+  withAction() {
+    toast('Conversation archived', {
+      description: 'You can undo this within 10 seconds.',
+      duration: 10000,
+      action: { label: 'Undo', onClick: () => toast.success('Restored') },
+      cancel: { label: 'Dismiss', onClick: () => {} },
+    });
+  }
+  sticky() {
+    toast('Sync paused — offline', { duration: Infinity, closeButton: true });
+  }
+  dismissAll() {
+    toast.dismiss();
+  }
+}
+```
+
+### 5. Async / promise toasts (loading → success → error)
+
+```ts
+// demo-promise.component.ts
+import { Component, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { toast } from 'ngx-sonner';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+
+@Component({
+  selector: 'demo-promise',
+  standalone: true,
+  imports: [...HlmButtonImports, ...HlmSpinnerImports],
+  template: `<button hlmBtn (click)="save()">Save report</button>`,
+})
+export class DemoPromise {
+  private readonly http = inject(HttpClient);
+
+  save() {
+    const request = this.http.post('/api/reports', { title: 'Q3' }).toPromise();
+    toast.promise(request, {
+      loading: 'Saving report…',
+      success: 'Report saved',
+      error: 'Could not save report',
+    });
+  }
+}
+```
+
+Combine with a spinner while the promise is pending by driving `show` from a signal — see `@egose/shadcn-theme-ng/spinner`.
+
+### 6. Custom styling via `toastOptions`, `class`, and `style`
+
+```ts
+// app.component.ts
+import { Component } from '@angular/core';
+import { HlmToasterImports } from '@egose/shadcn-theme-ng/sonner';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [...HlmToasterImports],
+  template: ` <hlm-toaster class="my-toaster" [toastOptions]="toastOptions" [offset]="24" dir="ltr" /> `,
+})
+export class AppComponent {
+  readonly toastOptions = {
+    classes: {
+      toast: 'group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground',
+      description: 'group-[.toast]:text-muted-foreground',
+      actionButton: 'group-[.toast]:bg-primary group-[.toast]:text-primary-foreground',
+      cancelButton: 'group-[.toast]:bg-muted group-[.toast]:text-muted-foreground',
+    },
+    // per-toast defaults can also set duration/style here
+    duration: 6000,
+  };
+}
+```
+
+Per-toast override (description + action button classes come from `toastOptions.classes` above unless overridden):
+
+```ts
+toast('Custom toast', {
+  description: 'This toast uses the global toastOptions classes.',
+  className: 'border-primary',
+  style: { borderWidth: '2px' },
+});
+```
+
+## Accessibility notes
+
+- `ngx-sonner` renders toasts in an `aria-live` region so screen readers announce them; keep messages short and put detail in `description`.
+- Always pair an icon-only trigger with visible text or an `aria-label` on the button that fires the toast.
+- Do not use toasts as the only feedback for errors on form submit — also surface the error inline near the field (the `description` alone is not focusable).
+- `duration: Infinity` toasts trap no focus but persist; always provide a `closeButton` or explicit dismiss action for sticky toasts.
+- Hotkey defaults to `Alt+T` (`hotKey` input); document it if your app relies on keyboard flows, or override it to avoid conflicts.
+
+## Theming / CSS variables
+
+The outlet merges `hlm('toaster group', userClass)` and ships `toastOptions.classes` mapped onto shadcn theme tokens (`bg-background`, `text-foreground`, `border-border`, `bg-primary`, `bg-muted`, …). It follows your shadcn CSS-variable theme automatically. Override via the `class` input (outlet position/layout) or `toastOptions.classes` (toast/description/action/cancel styling).
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/button` — trigger buttons for toast demos.
+- `@egose/shadcn-theme-ng/spinner` — loading indicator to pair with `toast.promise()`.
+- `@egose/shadcn-theme-ng/alert` / `@egose/shadcn-theme-ng/basic-alert` — persistent inline feedback (vs. transient toasts).
+- `@egose/shadcn-theme-ng/utils` — `hlm()` merger used internally for outlet classes.

package/spinner/README.md

@@ -1,3 +1,285 @@
-# Spinner Subpath
+# Spinner (`@egose/shadcn-theme-ng/spinner`)
 
-This project ships only as `@egose/shadcn-theme-ng/spinner` or `@egose/shadcn-theme-ng-tw/spinner`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+A loading spinner, equivalent to [shadcn/ui Spinner](https://ui.shadcn.com/docs/components/spinner). This subpath ships a single standalone component, `HlmSpinner`, that renders an animated [`@ng-icons`](https://www.ng-icons.dev/) `tablerLoader2` icon (spinning via `animate-spin`) inside a flex container with `role="status"`. There is no spartan-ng primitive underneath — it is a pure styled icon wrapper with `size`/`show` inputs.
+
+> **Ships as:** `@egose/shadcn-theme-ng/spinner` and `@egose/shadcn-theme-ng-tw/spinner` (the `tw:`-prefixed Tailwind variant). See the [package README](../../README.md) for install steps, peer dependencies, Tailwind setup, and testing/release guidance. 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
+```
+
+No extra runtime install is needed — `@ng-icons/core` / `@ng-icons/tabler-icons` and `clsx`/`tailwind-merge` (via `utils`) arrive transitively. See the [package README](../../README.md) for the full peer-dependency table.
+
+## Imports
+
+All public symbols are re-exported from `projects/spinner/src/public-api.ts`:
+
+```ts
+import { HlmSpinner, HlmSpinnerImports, HlmSpinnerModule } from '@egose/shadcn-theme-ng/spinner';
+// tw variant:
+// import { HlmSpinner, HlmSpinnerImports, HlmSpinnerModule } from '@egose/shadcn-theme-ng-tw/spinner';
+```
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmSpinnerImports],
+  template: `<hlm-spinner />`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmSpinnerModule } from '@egose/shadcn-theme-ng/spinner';
+
+@NgModule({ imports: [HlmSpinnerModule] })
+export class FeatureModule {}
+```
+
+| Symbol              | Kind                 | Description                                    |
+| ------------------- | -------------------- | ---------------------------------------------- |
+| `HlmSpinner`        | Standalone component | The `<hlm-spinner>` loading indicator.         |
+| `HlmSpinnerImports` | `const` array        | `[HlmSpinner]` — spread into `imports: [...]`. |
+| `HlmSpinnerModule`  | NgModule             | Imports + re-exports `HlmSpinner`.             |
+
+## Anatomy / Structure
+
+```html
+<!-- host element: <hlm-spinner role="status" class="flex … | hidden"> -->
+<hlm-spinner />
+<hlm-spinner size="2rem" />
+<hlm-spinner [show]="loading()" class="my-4" spinnerClass="text-primary" />
+```
+
+The host carries `role="status"` and toggles `flex`/`hidden` from `show()`. The inner `<ng-icon>` always renders the fixed `tablerLoader2` glyph at `size()` with `animate-spin`.
+
+## API reference
+
+### `HlmSpinner` — selector `hlm-spinner` (component)
+
+| Input          | Type                                        | Default    | Description                                                                                                                      |
+| -------------- | ------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `size`         | `string`                                    | `'1.5rem'` | Passed as `[size]` to the inner `<ng-icon>`; any CSS length (`'1rem'`, `'24px'`, …).                                             |
+| `show`         | `boolean`                                   | `true`     | Toggles the host between `flex` (visible) and `hidden`.                                                                          |
+| `class`        | `ClassValue` (aliased input `wrapperClass`) | `''`       | Extra classes merged onto the **host container** via `hlm('flex-col items-center justify-center', show ? 'flex' : 'hidden', …)`. |
+| `spinnerClass` | `ClassValue`                                | `''`       | Extra classes merged onto the **inner icon** (`animate-spin`, primary color, inherit sizing).                                    |
+
+Public field:
+
+| Member | Type                  | Description                                                                                               |
+| ------ | --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `icon` | `tablerLoader2` glyph | Fixed icon data bound to the inner `<ng-icon [svg]>`. Not an input — the glyph cannot be swapped via API. |
+
+No outputs, no methods. Host attributes: `role="status"`.
+
+## Examples
+
+### 1. Basic usage
+
+```ts
+// demo-basic.component.ts
+import { Component } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+
+@Component({
+  selector: 'demo-basic',
+  standalone: true,
+  imports: [...HlmSpinnerImports],
+  template: `<hlm-spinner />`,
+})
+export class DemoBasic {}
+```
+
+```html
+<hlm-spinner />
+```
+
+### 2. Sizes
+
+`size` accepts any CSS length string passed straight to `<ng-icon [size]>`.
+
+```ts
+// demo-sizes.component.ts
+import { Component } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+
+@Component({
+  selector: 'demo-sizes',
+  standalone: true,
+  imports: [...HlmSpinnerImports],
+  template: `
+    <div class="flex items-end gap-6">
+      <hlm-spinner size="1rem" />
+      <hlm-spinner size="1.5rem" />
+      <hlm-spinner size="2.5rem" />
+      <hlm-spinner size="48px" />
+    </div>
+  `,
+})
+export class DemoSizes {}
+```
+
+### 3. Async loading state with `show`
+
+```ts
+// demo-async.component.ts
+import { Component, inject, signal } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-async',
+  standalone: true,
+  imports: [...HlmSpinnerImports, ...HlmButtonImports],
+  template: `
+    <button hlmBtn (click)="reload()" [disabled]="loading()">Reload</button>
+    <hlm-spinner [show]="loading()" class="my-4" />
+    @if (!loading()) {
+      <p hlmP>Data: {{ data() ?? '—' }}</p>
+    }
+  `,
+})
+export class DemoAsync {
+  private readonly http = inject(HttpClient);
+  readonly loading = signal(false);
+  readonly data = signal<string | null>(null);
+
+  reload() {
+    this.loading.set(true);
+    this.http.get('/api/status', { responseType: 'text' }).subscribe({
+      next: (v) => {
+        this.data.set(v);
+        this.loading.set(false);
+      },
+      error: () => {
+        this.data.set('error');
+        this.loading.set(false);
+      },
+    });
+  }
+}
+```
+
+> `show` hides with `display: none` (`hidden`) — the icon stays in the DOM. For conditional mounting instead, use `@if (loading()) { <hlm-spinner /> }`.
+
+### 4. Inside a button (inline submitting state)
+
+The spinner inherits font sizing from `spinnerClass`; pair it with a disabled button.
+
+```ts
+// demo-button.component.ts
+import { Component, signal } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-button',
+  standalone: true,
+  imports: [...HlmSpinnerImports, ...HlmButtonImports],
+  template: `
+    <button hlmBtn [disabled]="saving()">
+      @if (saving()) {
+        <hlm-spinner size="1rem" spinnerClass="[&>svg]:text-primary-foreground" />
+      }
+      {{ saving() ? 'Saving…' : 'Save changes' }}
+    </button>
+  `,
+})
+export class DemoButton {
+  readonly saving = signal(false);
+
+  save() {
+    this.saving.set(true);
+    setTimeout(() => this.saving.set(false), 1500);
+  }
+}
+```
+
+### 5. Custom colors and layout via `class` / `spinnerClass`
+
+```ts
+// demo-styled.component.ts
+import { Component } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+
+@Component({
+  selector: 'demo-styled',
+  standalone: true,
+  imports: [...HlmSpinnerImports],
+  template: `
+    <!-- centered page loader -->
+    <hlm-spinner size="3rem" class="min-h-40 w-full" spinnerClass="[&>svg]:text-muted-foreground" />
+
+    <!-- destructive-tinted spinner -->
+    <hlm-spinner size="1.25rem" spinnerClass="[&>svg]:text-destructive" />
+  `,
+})
+export class DemoStyled {}
+```
+
+`class` targets the outer flex container; `spinnerClass` targets the inner `<ng-icon>`/`<svg>`. Both merge through `hlm()` so Tailwind conflicts resolve.
+
+### 6. Overlay + empty-state composition
+
+```ts
+// demo-overlay.component.ts
+import { Component, signal } from '@angular/core';
+import { HlmSpinnerImports } from '@egose/shadcn-theme-ng/spinner';
+import { HlmCardImports } from '@egose/shadcn-theme-ng/card';
+
+@Component({
+  selector: 'demo-overlay',
+  standalone: true,
+  imports: [...HlmSpinnerImports, ...HlmCardImports],
+  template: `
+    <section hlmCard class="relative min-h-48 p-6">
+      <h3 hlmH3>Dashboard</h3>
+      @if (loading()) {
+        <div class="absolute inset-0 flex items-center justify-center rounded-md bg-background/70 backdrop-blur-[1px]">
+          <hlm-spinner size="2rem" />
+          <span class="sr-only">Loading dashboard…</span>
+        </div>
+      } @else {
+        <p hlmP>Dashboard content goes here.</p>
+      }
+    </section>
+  `,
+})
+export class DemoOverlay {
+  readonly loading = signal(true);
+}
+```
+
+## Accessibility notes
+
+- The host has `role="status"` so assistive tech announces the loading state; add adjacent text (visible or `.sr-only`, e.g. “Loading…”) describing _what_ is loading — the icon alone conveys nothing to screen readers.
+- Keep `show`-hidden spinners out of the tab order (they contain no focusable elements by default — do not add any).
+- For actions that take >1s, disable the triggering control while `show` is true to prevent duplicate submissions.
+- Avoid stacking multiple spinners in one view; a single `role="status"` region per async region is enough.
+
+## Theming / CSS variables
+
+The icon inherits `text-primary` by default (`[&>svg]:text-primary`); override with `spinnerClass` (e.g. `spinnerClass="[&>svg]:text-muted-foreground"`). Sizing is fully controlled by `size`. No additional CSS variables.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/button` — inline submitting states.
+- `@egose/shadcn-theme-ng/skeleton` — content placeholders to pair with spinners.
+- `@egose/shadcn-theme-ng/sonner` — notify on async completion (`toast.promise()`).
+- `@egose/shadcn-theme-ng/card` — surfaces to overlay a spinner on.