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

package/toggle-group/README.md

@@ -1,11 +1,346 @@
-# ToggleGroup
+# Toggle Group (`@egose/shadcn-theme-ng/toggle-group`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A set of related two-state buttons, equivalent to [shadcn/ui Toggle Group](https://ui.shadcn.com/docs/components/toggle-group). This subpath ships `HlmToggleGroup` (container, `[hlmToggleGroup]` / `<hlm-toggle-group>`) and `HlmToggleGroupItem` (member, `button[hlmToggleGroupItem]`) over spartan-ng's `BrnToggleGroup` / `BrnToggleGroupItem` primitives, plus the `HlmToggleGroupToken` injection context (`injectHlmToggleGroup()`, `provideHlmToggleGroup()`). Sizing/variant cascade from the group to items via DI; item-level inputs override the group.
 
-## Building
+> **Ships as:** `@egose/shadcn-theme-ng/toggle-group` and `@egose/shadcn-theme-ng-tw/toggle-group` (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.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build toggle-group
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+`@spartan-ng/brain` and `@egose/shadcn-theme-ng/toggle` (for `toggleVariants`) arrive transitively. See the [package README](../../README.md) for the full peer-dependency table.
+
+## Imports
+
+All public symbols are re-exported from `projects/toggle-group/src/public-api.ts`:
+
+```ts
+import {
+  HlmToggleGroup,
+  HlmToggleGroupImports,
+  HlmToggleGroupItem,
+  HlmToggleGroupModule,
+  HlmToggleGroupToken,
+  injectHlmToggleGroup,
+  provideHlmToggleGroup,
+} from '@egose/shadcn-theme-ng/toggle-group';
+import type { HlmToggleGroupContext } from '@egose/shadcn-theme-ng/toggle-group';
+// tw variant: swap to '@egose/shadcn-theme-ng-tw/toggle-group'
+```
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmToggleGroupImports],
+  template: `
+    <div hlmToggleGroup>
+      <button hlmToggleGroupItem value="a">A</button>
+    </div>
+  `,
+})
+export class DemoComponent {}
 ```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmToggleGroupModule } from '@egose/shadcn-theme-ng/toggle-group';
+
+@NgModule({ imports: [HlmToggleGroupModule] })
+export class FeatureModule {}
+```
+
+| Symbol                    | Kind             | Description                                                              |
+| ------------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `HlmToggleGroup`          | Directive        | Container: `[hlmToggleGroup], hlm-toggle-group`. Provides group context. |
+| `HlmToggleGroupItem`      | Directive        | Member: `button[hlmToggleGroupItem]`. Inherits group variant/size.       |
+| `HlmToggleGroupToken`     | `InjectionToken` | DI token for `HlmToggleGroupContext` (variant/size/spacing).             |
+| `injectHlmToggleGroup()`  | Function         | Injects the parent group context (for custom items).                     |
+| `provideHlmToggleGroup()` | Function         | Provides the group context for a custom container.                       |
+| `HlmToggleGroupContext`   | Interface (type) | `{ variant, size, spacing }` input signals shared via DI.                |
+| `HlmToggleGroupImports`   | `const` array    | `[HlmToggleGroup, HlmToggleGroupItem]`.                                  |
+| `HlmToggleGroupModule`    | NgModule         | Imports + re-exports both directives.                                    |
+
+## Anatomy / Structure
+
+```html
+<!-- single-select formatting group -->
+<div hlmToggleGroup type="single" variant="outline" size="default">
+  <button hlmToggleGroupItem value="bold" aria-label="Toggle bold">B</button>
+  <button hlmToggleGroupItem value="italic" aria-label="Toggle italic">I</button>
+  <button hlmToggleGroupItem value="underline" aria-label="Toggle underline">U</button>
+</div>
+
+<!-- multi-select with spacing + vertical orientation -->
+<div hlmToggleGroup type="multiple" variant="outline" [spacing]="1" orientation="vertical">
+  <button hlmToggleGroupItem value="left" aria-label="Align left">L</button>
+  <button hlmToggleGroupItem value="center" aria-label="Align center">C</button>
+  <button hlmToggleGroupItem value="right" aria-label="Align right">R</button>
+</div>
+```
+
+> Items must be `<button hlmToggleGroupItem value="…">`. The group `type` is `'single' | 'multiple'` (from Brn); omit `type` only for uncontrolled demos.
+
+## API reference
+
+### `HlmToggleGroup` — selector `[hlmToggleGroup], hlm-toggle-group` (directive, hosts `BrnToggleGroup`)
+
+Own styling inputs:
+
+| Input         | Type                                                   | Default        | Description                                                                                                       |
+| ------------- | ------------------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `variant`     | `ToggleVariants['variant']` (`'default' \| 'outline'`) | `'default'`    | Cascades to items (item input wins when set). Reflected to `data-variant`.                                        |
+| `size`        | `ToggleVariants['size']` (`'default' \| 'sm' \| 'lg'`) | `'default'`    | Cascades to items. Reflected to `data-size`.                                                                      |
+| `spacing`     | `number` (coerced with `numberAttribute`)              | `0`            | Gap level. Reflected to `data-spacing` + `--gap` (`gap-[--spacing(var(--gap))]`). `0` = joined segmented control. |
+| `orientation` | `'horizontal' \| 'vertical'`                           | `'horizontal'` | Layout direction. Reflected to `data-orientation`.                                                                |
+
+Forwarded to `BrnToggleGroup` via `hostDirectives`:
+
+| Input / Output | Direction | Description                                                   |
+| -------------- | --------- | ------------------------------------------------------------- |
+| `type`         | input     | `'single' \| 'multiple'` selection mode.                      |
+| `value`        | input     | Current value(s). Supports two-way binding.                   |
+| `nullable`     | input     | (single mode) whether deselecting the active item is allowed. |
+| `disabled`     | input     | Disables the whole group.                                     |
+| `valueChange`  | output    | Emits when the group value changes.                           |
+
+Host: `data-slot="toggle-group"`, `flex w-fit` (column when `data-vertical`).
+
+### `HlmToggleGroupItem` — selector `button[hlmToggleGroupItem]` (directive, hosts `BrnToggleGroupItem`)
+
+| Input     | Type                        | Default     | Description                                                                                           |
+| --------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| `variant` | `ToggleVariants['variant']` | `'default'` | Overrides the group variant when set (group wins when the group value is truthy — see surprise note). |
+| `size`    | `ToggleVariants['size']`    | `'default'` | Overrides the group size when set (same precedence rule).                                             |
+
+Forwarded to `BrnToggleGroupItem`: `id`, `value` (required per item), `disabled`, `state`, `aria-label`, `type` inputs and `stateChange` output.
+
+Host: `data-slot="toggle-group-item"`, reflects resolved `data-variant` / `data-size` and group `data-spacing`. Styling = item overrides + `toggleVariants({ variant, size })`.
+
+### Token helpers — `hlm-toggle-group.token.ts`
+
+```ts
+interface HlmToggleGroupContext {
+  readonly variant: InputSignal<ToggleVariants['variant']>;
+  readonly size: InputSignal<ToggleVariants['size']>;
+  readonly spacing: InputSignalWithTransform<number, NumberInput>;
+}
+```
+
+`provideHlmToggleGroup(HlmToggleGroup)` is wired automatically on the group directive; call it manually only for custom container components. `injectHlmToggleGroup()` reads the parent context (throws outside a group).
+
+## Examples
+
+### 1. Basic single-select formatting group
+
+```ts
+// demo-basic.component.ts
+import { Component } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideBold, lucideItalic, lucideUnderline } from '@ng-icons/lucide';
+
+@Component({
+  selector: 'demo-basic',
+  standalone: true,
+  imports: [...HlmToggleGroupImports, NgIcon],
+  providers: [provideIcons({ lucideBold, lucideItalic, lucideUnderline })],
+  template: `
+    <div hlmToggleGroup type="single" variant="outline">
+      <button hlmToggleGroupItem value="bold" aria-label="Toggle bold"><ng-icon name="lucideBold" /></button>
+      <button hlmToggleGroupItem value="italic" aria-label="Toggle italic"><ng-icon name="lucideItalic" /></button>
+      <button hlmToggleGroupItem value="underline" aria-label="Toggle underline">
+        <ng-icon name="lucideUnderline" />
+      </button>
+    </div>
+  `,
+})
+export class DemoBasic {}
+```
+
+### 2. Controlled value (`value` / `valueChange`)
+
+```ts
+// demo-controlled.component.ts
+import { Component, signal } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'demo-controlled',
+  standalone: true,
+  imports: [...HlmToggleGroupImports],
+  template: `
+    <div hlmToggleGroup type="single" [value]="align()" (valueChange)="align.set($event)" variant="outline">
+      <button hlmToggleGroupItem value="left">Left</button>
+      <button hlmToggleGroupItem value="center">Center</button>
+      <button hlmToggleGroupItem value="right">Right</button>
+    </div>
+    <p class="text-sm text-muted-foreground">Align: {{ align() ?? 'none' }}</p>
+  `,
+})
+export class DemoControlled {
+  readonly align = signal<string | null>('left');
+}
+```
+
+Multi-select holds an array:
+
+```html
+<div hlmToggleGroup type="multiple" [value]="picked()" (valueChange)="picked.set($event)">
+  <button hlmToggleGroupItem value="a">A</button>
+  <button hlmToggleGroupItem value="b">B</button>
+  <button hlmToggleGroupItem value="c">C</button>
+</div>
+```
+
+```ts
+readonly picked = signal<string[]>(['a']);
+```
+
+### 3. Sizes, spacing, and orientation
+
+```ts
+// demo-layout.component.ts
+import { Component } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'demo-layout',
+  standalone: true,
+  imports: [...HlmToggleGroupImports],
+  template: `
+    <!-- joined segmented control (spacing 0) -->
+    <div hlmToggleGroup type="single" variant="outline" size="sm">
+      <button hlmToggleGroupItem value="day">Day</button>
+      <button hlmToggleGroupItem value="week">Week</button>
+      <button hlmToggleGroupItem value="month">Month</button>
+    </div>
+
+    <!-- separated pills -->
+    <div hlmToggleGroup type="multiple" variant="default" [spacing]="2" class="mt-4">
+      <button hlmToggleGroupItem value="a">A</button>
+      <button hlmToggleGroupItem value="b">B</button>
+      <button hlmToggleGroupItem value="c">C</button>
+    </div>
+
+    <!-- vertical stack -->
+    <div hlmToggleGroup type="single" variant="outline" orientation="vertical" class="mt-4">
+      <button hlmToggleGroupItem value="top">Top</button>
+      <button hlmToggleGroupItem value="mid">Middle</button>
+      <button hlmToggleGroupItem value="bot">Bottom</button>
+    </div>
+  `,
+})
+export class DemoLayout {}
+```
+
+### 4. Disabled group / disabled item
+
+```ts
+// demo-disabled.component.ts
+import { Component } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'demo-disabled',
+  standalone: true,
+  imports: [...HlmToggleGroupImports],
+  template: `
+    <div hlmToggleGroup type="single" disabled variant="outline">
+      <button hlmToggleGroupItem value="a">A</button>
+      <button hlmToggleGroupItem value="b">B</button>
+    </div>
+    <div hlmToggleGroup type="single" variant="outline" class="mt-2">
+      <button hlmToggleGroupItem value="a">A</button>
+      <button hlmToggleGroupItem value="b" disabled>B (off)</button>
+    </div>
+  `,
+})
+export class DemoDisabled {}
+```
+
+### 5. Per-item variant/size override
+
+```ts
+// demo-override.component.ts
+import { Component } from '@angular/core';
+import { HlmToggleGroupImports } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'demo-override',
+  standalone: true,
+  imports: [...HlmToggleGroupImports],
+  template: `
+    <div hlmToggleGroup type="single" variant="outline" size="sm">
+      <button hlmToggleGroupItem value="a">A (group sm)</button>
+      <button hlmToggleGroupItem value="b" size="lg">B (own lg)</button>
+    </div>
+  `,
+})
+export class DemoOverride {}
+```
+
+> Precedence surprise: `_variant = group.variant() || item.variant()` — the **group value wins whenever truthy**. Since both default to `'default'` (truthy), item overrides only take effect when the group variant/size is set to a falsy value or the group input is removed. In practice, set variant/size on the group _or_ per item, not both.
+
+### 6. Advanced: custom item via `injectHlmToggleGroup()`
+
+Build your own item that still follows the group:
+
+```ts
+// custom-item.component.ts
+import { Component, computed } from '@angular/core';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+import { toggleVariants } from '@egose/shadcn-theme-ng/toggle';
+import { injectHlmToggleGroup } from '@egose/shadcn-theme-ng/toggle-group';
+
+@Component({
+  selector: 'button[customGroupItem]',
+  standalone: true,
+  template: `<ng-content />`,
+  host: { '[class]': 'classes()' },
+})
+export class CustomGroupItem {
+  private readonly group = injectHlmToggleGroup(); // must sit inside [hlmToggleGroup]
+  protected classes = computed(() =>
+    hlm(toggleVariants({ variant: this.group.variant(), size: this.group.size() }), 'uppercase'),
+  );
+}
+```
+
+```html
+<div hlmToggleGroup type="single" variant="outline">
+  <button customGroupItem value="a">A</button>
+</div>
+```
+
+## Accessibility notes
+
+- Give the group an accessible name (`aria-label` on the group element) when its purpose is not obvious from surrounding headings.
+- Icon-only items need `aria-label` each; text items get names from content.
+- Keyboard follows the toolbar pattern via the Brn primitive (arrows move, Space/Enter toggle). Keep DOM order = visual order, especially in `vertical` orientation.
+- `disabled` on the group disables all items; a single `disabled` item is skipped in navigation — explain why when it blocks a workflow.
+- Single-select groups should allow a null/empty state or document that one option is always active (`nullable` input).
+
+## Theming / CSS variables
+
+Group and items share the toggle token set (`bg-muted` pressed, `border-input` outline, `ring-ring/50` focus). `spacing="0"` + `outline` renders a joined segmented control with `shadow-xs`; non-zero spacing renders separated pills with `--gap`. Follows your shadcn theme automatically.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/toggle` — standalone toggle button + `toggleVariants` reused here.
+- `@egose/shadcn-theme-ng/button-group` — action button groups (vs. pressed-state groups).
+- `@egose/shadcn-theme-ng/tooltip` — labels for icon-only items.
+- `@egose/shadcn-theme-ng/utils` — `hlm()` merger used for custom items.

package/tooltip/README.md

@@ -1,3 +1,270 @@
-# Tooltip Subpath
+# Tooltip (`@egose/shadcn-theme-ng/tooltip`)
 
-This project ships only as `@egose/shadcn-theme-ng/tooltip` or `@egose/shadcn-theme-ng-tw/tooltip`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+Contextual hints, equivalent to [shadcn/ui Tooltip](https://ui.shadcn.com/docs/components/tooltip). This subpath ships a single thin directive, `HlmTooltip` (`[hlmTooltip]`), that configures spartan-ng's `BrnTooltip` primitive with shadcn styling: it provides default content classes (`DEFAULT_TOOLTIP_CONTENT_CLASSES`), arrow SVG classes (`DEFAULT_TOOLTIP_SVG_CLASS`), and per-position arrow placement (`tooltipPositionVariants`). All show/hide behavior comes from `BrnTooltip` — this package only themes it.
+
+> **Ships as:** `@egose/shadcn-theme-ng/tooltip` and `@egose/shadcn-theme-ng-tw/tooltip` (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
+```
+
+`@spartan-ng/brain` and `class-variance-authority` arrive transitively. See the [package README](../../README.md) for the full peer-dependency table.
+
+## Imports
+
+All public symbols are re-exported from `projects/tooltip/src/public-api.ts`:
+
+```ts
+import {
+  DEFAULT_TOOLTIP_CONTENT_CLASSES,
+  DEFAULT_TOOLTIP_SVG_CLASS,
+  HlmTooltip,
+  HlmTooltipImports,
+  HlmTooltipModule,
+  tooltipPositionVariants,
+} from '@egose/shadcn-theme-ng/tooltip';
+// tw variant: swap to '@egose/shadcn-theme-ng-tw/tooltip'
+```
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmTooltipImports],
+  template: `<button [hlmTooltip]="'Save document'">Save</button>`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmTooltipModule } from '@egose/shadcn-theme-ng/tooltip';
+
+@NgModule({ imports: [HlmTooltipModule] })
+export class FeatureModule {}
+```
+
+| Symbol                            | Kind             | Description                                                                                                                                          |
+| --------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HlmTooltip`                      | Directive        | `[hlmTooltip]` — themed `BrnTooltip` with shadcn defaults.                                                                                           |
+| `DEFAULT_TOOLTIP_CONTENT_CLASSES` | `const` (string) | Default bubble classes (`bg-foreground text-background rounded-md px-3 py-1.5 text-xs …`).                                                           |
+| `DEFAULT_TOOLTIP_SVG_CLASS`       | `const` (string) | Default arrow classes (`bg-foreground fill-foreground size-2.5 rotate-45 …`). (Note: unprefixed utilities; overridden by the provider with `hlm()`.) |
+| `tooltipPositionVariants`         | cva fn           | `tooltipPositionVariants({ position })` — arrow placement for `top/bottom/left/right`.                                                               |
+| `HlmTooltipImports`               | `const` array    | `[HlmTooltip]` — spread into `imports: [...]`.                                                                                                       |
+| `HlmTooltipModule`                | NgModule         | Imports + re-exports `HlmTooltip`.                                                                                                                   |
+
+## Anatomy / Structure
+
+```html
+<!-- basic: string content -->
+<button hlmBtn [hlmTooltip]="'Add to library'">Add</button>
+
+<!-- positioned, delayed -->
+<button hlmBtn [hlmTooltip]="'Settings'" position="right" [showDelay]="300" [hideDelay]="100">Settings</button>
+
+<!-- disabled tooltip -->
+<button hlmBtn [hlmTooltip]="'Hidden hint'" [tooltipDisabled]="true">No tooltip</button>
+```
+
+The directive takes the tooltip **text as its input value** (`brnTooltip: hlmTooltip`) and renders the floating bubble + arrow via the CDK overlay. No extra outlet component is needed.
+
+## API reference
+
+### `HlmTooltip` — selector `[hlmTooltip]` (directive, hosts `BrnTooltip`)
+
+The directive declares **no own inputs** — everything is forwarded to `BrnTooltip` (plus provider defaults):
+
+| Input             | Type                                                            | Default (via provider) | Description                                                          |
+| ----------------- | --------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `hlmTooltip`      | `string` (forwarded as `brnTooltip`)                            | —                      | Tooltip text content. Required to show anything.                     |
+| `position`        | `BrnTooltipPosition` (`'top' \| 'bottom' \| 'left' \| 'right'`) | — (Brn default)        | Bubble side + arrow placement (arrow via `tooltipPositionVariants`). |
+| `showDelay`       | `number` (forwarded)                                            | — (Brn default)        | ms before the tooltip appears on hover/focus.                        |
+| `hideDelay`       | `number` (forwarded)                                            | — (Brn default)        | ms before the tooltip hides on leave/blur.                           |
+| `tooltipDisabled` | `boolean` (forwarded)                                           | — (Brn default)        | Suppress the tooltip entirely.                                       |
+
+Provider defaults (`provideBrnTooltipDefaultOptions`, applied automatically): `svgClasses: DEFAULT_TOOLTIP_SVG_CLASS`, `tooltipContentClasses: DEFAULT_TOOLTIP_CONTENT_CLASSES`, `arrowClasses: (position) => hlm(tooltipPositionVariants({ position }))`.
+
+No outputs. Can attach to any element (buttons, icons, toggles, links).
+
+## Examples
+
+### 1. Basic usage
+
+```ts
+// demo-basic.component.ts
+import { Component } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-basic',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmButtonImports],
+  template: ` <button hlmBtn variant="outline" [hlmTooltip]="'Add to library'">Add</button> `,
+})
+export class DemoBasic {}
+```
+
+### 2. All positions
+
+```ts
+// demo-positions.component.ts
+import { Component } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-positions',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmButtonImports],
+  template: `
+    <div class="flex flex-wrap gap-2">
+      <button hlmBtn variant="outline" [hlmTooltip]="'On top'" position="top">Top</button>
+      <button hlmBtn variant="outline" [hlmTooltip]="'Below'" position="bottom">Bottom</button>
+      <button hlmBtn variant="outline" [hlmTooltip]="'On the left'" position="left">Left</button>
+      <button hlmBtn variant="outline" [hlmTooltip]="'On the right'" position="right">Right</button>
+    </div>
+  `,
+})
+export class DemoPositions {}
+```
+
+The arrow repositions automatically per side via `tooltipPositionVariants({ position })`.
+
+### 3. Delays + disabled state
+
+```ts
+// demo-delays.component.ts
+import { Component, signal } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-delays',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmButtonImports],
+  template: `
+    <div class="flex gap-2">
+      <button hlmBtn variant="outline" [hlmTooltip]="'Slow to appear'" [showDelay]="600" [hideDelay]="100">
+        Hover me
+      </button>
+      <button hlmBtn variant="outline" [hlmTooltip]="'Never shows'" [tooltipDisabled]="muted()">
+        {{ muted() ? 'Muted (no tip)' : 'Unmuted' }}
+      </button>
+      <button hlmBtn size="sm" (click)="muted.set(!muted())">Toggle mute</button>
+    </div>
+  `,
+})
+export class DemoDelays {
+  readonly muted = signal(false);
+}
+```
+
+### 4. Icon-only buttons and toggles (accessible names still required)
+
+```ts
+// demo-icons.component.ts
+import { Component } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+import { HlmToggleImports } from '@egose/shadcn-theme-ng/toggle';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideBold, lucideItalic } from '@ng-icons/lucide';
+
+@Component({
+  selector: 'demo-icons',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmToggleImports, NgIcon],
+  providers: [provideIcons({ lucideBold, lucideItalic })],
+  template: `
+    <div class="flex gap-1">
+      <button hlmToggle aria-label="Toggle bold" [hlmTooltip]="'Bold (Ctrl+B)'">
+        <ng-icon name="lucideBold" />
+      </button>
+      <button hlmToggle aria-label="Toggle italic" [hlmTooltip]="'Italic (Ctrl+I)'" position="bottom">
+        <ng-icon name="lucideItalic" />
+      </button>
+    </div>
+  `,
+})
+export class DemoIcons {}
+```
+
+> The tooltip is a visual hint only — icon buttons still need `aria-label` (tooltips are not reliably announced).
+
+### 5. Dynamic content from signals
+
+```ts
+// demo-dynamic.component.ts
+import { Component, computed, signal } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'demo-dynamic',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmButtonImports],
+  template: `
+    <button hlmBtn variant="outline" [hlmTooltip]="tip()" (click)="count.set(count() + 1)">
+      Clicked {{ count() }}×
+    </button>
+  `,
+})
+export class DemoDynamic {
+  readonly count = signal(0);
+  readonly tip = computed(() => (this.count() === 0 ? 'Click to start' : `Clicked ${this.count()} times`));
+}
+```
+
+### 6. Advanced: reusing the class constants
+
+```ts
+// demo-classes.component.ts
+import { Component } from '@angular/core';
+import { DEFAULT_TOOLTIP_CONTENT_CLASSES, tooltipPositionVariants } from '@egose/shadcn-theme-ng/tooltip';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+@Component({
+  selector: 'demo-classes',
+  standalone: true,
+  template: `<p class="text-sm">Content classes length: {{ len }}</p>`,
+})
+export class DemoClasses {
+  readonly len = DEFAULT_TOOLTIP_CONTENT_CLASSES.length;
+
+  arrowFor(position: 'top' | 'bottom' | 'left' | 'right') {
+    return hlm(tooltipPositionVariants({ position }));
+  }
+}
+```
+
+## Accessibility notes
+
+- Tooltips appear on hover **and** focus (via Brn) — keyboard users get them automatically; do not gate hints behind hover-only behavior.
+- Never put essential information _only_ in a tooltip: screen-reader and touch support is best-effort. Mirror critical hints as visible text or `aria-label`s.
+- Icon-only triggers need `aria-label` regardless of tooltip text.
+- Keep tooltip text short (a few words); long prose belongs in a popover/dialog.
+- `tooltipDisabled` removes the hint entirely — only use it when the control is self-explanatory in that state, not to hide errors.
+
+## Theming / CSS variables
+
+The bubble uses `bg-foreground text-background` with entrance/exit animations per side and theme-aware shadows; the arrow inherits the same fill. Follows your shadcn theme automatically. Override globally by providing your own `provideBrnTooltipDefaultOptions`, or per case by wrapping triggers with custom classes.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/button` — most common tooltip anchor.
+- `@egose/shadcn-theme-ng/toggle` / `@egose/shadcn-theme-ng/toggle-group` — icon toggles that pair well with hints.
+- `@egose/shadcn-theme-ng/popover` / `@egose/shadcn-theme-ng/hover-card` — richer floating content (vs. short tooltip text).
+- `@egose/shadcn-theme-ng/utils` — `hlm()` used to compose arrow/content classes.