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

package/tooltip/README.md

@@ -1,64 +1,270 @@
-# Tooltip
+# Tooltip (`@egose/shadcn-theme-ng/tooltip`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.2.0.
+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.
 
-## Code scaffolding
+> **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.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Installation
 
 ```bash
-ng generate component component-name
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+`@spartan-ng/brain` and `class-variance-authority` arrive transitively. See the [package README](../../README.md) for the full peer-dependency table.
 
-```bash
-ng generate --help
+## 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'
 ```
 
-## Building
+Standalone-component usage (preferred):
 
-To build the library, run:
+```ts
+import { Component } from '@angular/core';
+import { HlmTooltipImports } from '@egose/shadcn-theme-ng/tooltip';
 
-```bash
-ng build tooltip
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmTooltipImports],
+  template: `<button [hlmTooltip]="'Save document'">Save</button>`,
+})
+export class DemoComponent {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+NgModule usage:
 
-### Publishing the Library
+```ts
+import { NgModule } from '@angular/core';
+import { HlmTooltipModule } from '@egose/shadcn-theme-ng/tooltip';
 
-Once the project is built, you can publish your library by following these steps:
+@NgModule({ imports: [HlmTooltipModule] })
+export class FeatureModule {}
+```
 
-1. Navigate to the `dist` directory:
+| 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`.                                                                                                                   |
 
-   ```bash
-   cd dist/tooltip
-   ```
+## Anatomy / Structure
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```html
+<!-- basic: string content -->
+<button hlmBtn [hlmTooltip]="'Add to library'">Add</button>
 
-## Running unit tests
+<!-- positioned, delayed -->
+<button hlmBtn [hlmTooltip]="'Settings'" position="right" [showDelay]="300" [hideDelay]="100">Settings</button>
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+<!-- disabled tooltip -->
+<button hlmBtn [hlmTooltip]="'Hidden hint'" [tooltipDisabled]="true">No tooltip</button>
+```
 
-```bash
-ng test
+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 {}
 ```
 
-## Running end-to-end tests
+### 2. All positions
 
-For end-to-end (e2e) testing, run:
+```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';
 
-```bash
-ng e2e
+@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 {}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+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.
 
-## 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/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.

package/tooltip/fesm2022/tooltip.mjs

@@ -6,20 +6,20 @@ import { hlm } from '@egose/shadcn-theme-ng-tw/utils';
 import { cva } from 'class-variance-authority';
 
 const DEFAULT_TOOLTIP_SVG_CLASS = 'bg-foreground fill-foreground z-50 block size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px]';
-const DEFAULT_TOOLTIP_CONTENT_CLASSES = hlm('data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 rounded-md px-3 py-1.5 text-xs bg-foreground text-background data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) text-balance');
-const tooltipPositionVariants = cva('absolute', {
+const DEFAULT_TOOLTIP_CONTENT_CLASSES = hlm('tw:data-open:animate-in data-open:fade-in-0 tw:data-open:zoom-in-95 tw:data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 tw:data-[state=delayed-open]:zoom-in-95 tw:data-closed:animate-out data-closed:fade-out-0 tw:data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 tw:rounded-md tw:px-3 tw:py-1.5 tw:text-xs tw:bg-foreground tw:text-background tw:data-open:animate-in data-open:fade-in-0 tw:data-open:zoom-in-95 tw:data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 tw:data-[state=delayed-open]:zoom-in-95 tw:data-closed:animate-out data-closed:fade-out-0 tw:data-closed:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 tw:z-50 tw:w-fit tw:origin-(--radix-tooltip-content-transform-origin) tw:text-balance');
+const tooltipPositionVariants = cva('tw:absolute', {
     variants: {
         position: {
-            top: 'bottom-0 left-[calc(50%-5px)] translate-y-full',
-            bottom: '-top-2.5 left-[calc(50%-5px)] translate-y-0 rotate-180',
-            left: '-end-2.5 top-[calc(50%-5px)] translate-y-0 rotate-270 rtl:-rotate-270',
-            right: '-start-2.5 top-[calc(50%-5px)] translate-y-0 rotate-90 rtl:-rotate-90',
+            top: 'tw:bottom-0 tw:left-[calc(50%-5px)] tw:translate-y-full',
+            bottom: 'tw:-top-2.5 tw:left-[calc(50%-5px)] tw:translate-y-0 tw:rotate-180',
+            left: 'tw:-end-2.5 tw:top-[calc(50%-5px)] tw:translate-y-0 tw:rotate-270 tw:rtl:-rotate-270',
+            right: 'tw:-start-2.5 tw:top-[calc(50%-5px)] tw:translate-y-0 tw:rotate-90 tw:rtl:-rotate-90',
         },
     },
 });
 class HlmTooltip {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltip, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmTooltip, isStandalone: true, selector: "[hlmTooltip]", providers: [
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltip, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmTooltip, isStandalone: true, selector: "[hlmTooltip]", providers: [
             provideBrnTooltipDefaultOptions({
                 svgClasses: DEFAULT_TOOLTIP_SVG_CLASS,
                 tooltipContentClasses: DEFAULT_TOOLTIP_CONTENT_CLASSES,
@@ -27,7 +27,7 @@ class HlmTooltip {
             }),
         ], hostDirectives: [{ directive: i1.BrnTooltip, inputs: ["brnTooltip", "hlmTooltip", "position", "position", "hideDelay", "hideDelay", "showDelay", "showDelay", "tooltipDisabled", "tooltipDisabled"] }], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltip, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltip, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmTooltip]',
@@ -52,11 +52,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 const HlmTooltipImports = [HlmTooltip];
 class HlmTooltipModule {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltipModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltipModule, imports: [HlmTooltip], exports: [HlmTooltip] });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltipModule });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltipModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltipModule, imports: [HlmTooltip], exports: [HlmTooltip] });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltipModule });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmTooltipModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmTooltipModule, decorators: [{
             type: NgModule,
             args: [{
                     imports: [...HlmTooltipImports],
@@ -69,4 +69,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { DEFAULT_TOOLTIP_CONTENT_CLASSES, DEFAULT_TOOLTIP_SVG_CLASS, HlmTooltip, HlmTooltipImports, HlmTooltipModule, tooltipPositionVariants };
-//# sourceMappingURL=tooltip.mjs.map
+

package/typography/README.md

@@ -1,11 +1,277 @@
-# Typography
+# Typography (`@egose/shadcn-theme-ng/typography`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+Document type styles, equivalent to [shadcn/ui Typography](https://ui.shadcn.com/docs/components/typography). This subpath ships twelve **thin styling directives** — no behavior, no primitives, no inputs/outputs. Attach them to native elements (`h1`–`h4`, `p`, `blockquote`, `code`, `ul`, …) for shadcn type scale, plus matching exported class constants (`hlmH1`, `hlmP`, …) for reuse in custom components.
 
-## Building
+> **Ships as:** `@egose/shadcn-theme-ng/typography` and `@egose/shadcn-theme-ng-tw/typography` (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 typography
+# 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 dependencies. See the [package README](../../README.md) for the peer-dependency table.
+
+## Imports
+
+All public symbols are re-exported from `projects/typography/src/public-api.ts`:
+
+```ts
+import {
+  HlmBlockquote,
+  HlmCode,
+  HlmH1,
+  HlmH2,
+  HlmH3,
+  HlmH4,
+  HlmLarge,
+  HlmLead,
+  HlmMuted,
+  HlmP,
+  HlmSmall,
+  HlmTypographyImports,
+  HlmTypographyModule,
+  HlmUl,
+} from '@egose/shadcn-theme-ng/typography';
+// tw variant: swap to '@egose/shadcn-theme-ng-tw/typography'
+```
+
+Class constants are exported alongside (`hlmH1`, `hlmH2`, `hlmH3`, `hlmH4`, `hlmP`, `hlmBlockquote`, `hlmCode`, `hlmLarge`, `hlmLead`, `hlmMuted`, `hlmSmall`, `hlmUl`).
+
+Standalone-component usage (preferred):
+
+```ts
+import { Component } from '@angular/core';
+import { HlmTypographyImports } from '@egose/shadcn-theme-ng/typography';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmTypographyImports],
+  template: `<h1 hlmH1>Title</h1>`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmTypographyModule } from '@egose/shadcn-theme-ng/typography';
+
+@NgModule({ imports: [HlmTypographyModule] })
+export class FeatureModule {}
+```
+
+| Symbol                 | Kind          | Host selector (real)             |
+| ---------------------- | ------------- | -------------------------------- |
+| `HlmH1`                | Directive     | `[hlmH1]`                        |
+| `HlmH2`                | Directive     | `[hlmH2]`                        |
+| `HlmH3`                | Directive     | `[hlmH3]`                        |
+| `HlmH4`                | Directive     | `[hlmH4]`                        |
+| `HlmP`                 | Directive     | `[hlmP]`                         |
+| `HlmBlockquote`        | Directive     | `[hlmBlockquote]`                |
+| `HlmCode`              | Directive     | `[hlmCode]`                      |
+| `HlmLarge`             | Directive     | `[hlmLarge]`                     |
+| `HlmLead`              | Directive     | `[hlmLead]`                      |
+| `HlmMuted`             | Directive     | `[hlmMuted]`                     |
+| `HlmSmall`             | Directive     | `[hlmSmall]`                     |
+| `HlmUl`                | Directive     | `[hlmUl]`                        |
+| `HlmTypographyImports` | `const` array | All twelve directives.           |
+| `HlmTypographyModule`  | NgModule      | Imports + re-exports all twelve. |
+
+## Anatomy / Structure
+
+```html
+<h1 hlmH1>The Joke Tax Chronicles</h1>
+<p hlmLead>Once upon a time, in a far-off land, there was a very lazy king.</p>
+<h2 hlmH2>The King's Plan</h2>
+<p hlmP>The king thought…</p>
+<blockquote hlmBlockquote>"After all," he said, "everyone enjoys a good joke."</blockquote>
+<h3 hlmH3>The Joke Tax</h3>
+<ul hlmUl>
+  <li>1st level of puns: 5 gold coins</li>
+  <li>2nd level of jokes: 10 gold coins</li>
+</ul>
+<p hlmP>Learn more with <code hlmCode>ng add</code>.</p>
+<p hlmLarge>Large callout line.</p>
+<p hlmMuted>Muted fine print.</p>
+<p hlmSmall>Small label text.</p>
+<h4 hlmH4>Appendix</h4>
+```
+
+Attach each directive to its matching semantic element (`HlmH1`→`<h1>`, `HlmUl`→`<ul>`, `HlmCode`→`<code>`, …) — the directive adds classes only and does not change semantics.
+
+## API reference
+
+None of the twelve directives declare inputs, outputs, or methods. Each merges a fixed class string (also exported as a constant) via `classes()`:
+
+| Directive / constant              | Element        | Fixed classes (abridged)                                                            |
+| --------------------------------- | -------------- | ----------------------------------------------------------------------------------- |
+| `HlmH1` / `hlmH1`                 | `<h1>`         | `scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl`                    |
+| `HlmH2` / `hlmH2`                 | `<h2>`         | `scroll-m-20 border-b pb-2 text-3xl font-semibold tracking-tight first:mt-0`        |
+| `HlmH3` / `hlmH3`                 | `<h3>`         | `scroll-m-20 text-2xl font-semibold tracking-tight`                                 |
+| `HlmH4` / `hlmH4`                 | `<h4>`         | `scroll-m-20 text-xl font-semibold tracking-tight`                                  |
+| `HlmP` / `hlmP`                   | `<p>`          | `leading-7 [&:not(:first-child)]:mt-6`                                              |
+| `HlmBlockquote` / `hlmBlockquote` | `<blockquote>` | `mt-6 border-l-2 pl-6 italic`                                                       |
+| `HlmCode` / `hlmCode`             | `<code>`       | `relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm font-semibold` |
+| `HlmUl` / `hlmUl`                 | `<ul>`         | `my-6 ml-6 list-disc [&>li]:mt-2`                                                   |
+| `HlmLarge` / `hlmLarge`           | any            | `text-lg font-semibold`                                                             |
+| `HlmLead` / `hlmLead`             | `<p>`          | `text-xl text-muted-foreground`                                                     |
+| `HlmMuted` / `hlmMuted`           | `<p>`          | `text-sm text-muted-foreground`                                                     |
+| `HlmSmall` / `hlmSmall`           | any            | `text-sm font-medium leading-none`                                                  |
+
+User `class` attributes merge (not clobbered) through the shared `classes()` helper.
+
+## Examples
+
+### 1. Full article page
+
+```ts
+// demo-article.component.ts
+import { Component } from '@angular/core';
+import { HlmTypographyImports } from '@egose/shadcn-theme-ng/typography';
+
+@Component({
+  selector: 'demo-article',
+  standalone: true,
+  imports: [...HlmTypographyImports],
+  template: `
+    <article class="max-w-2xl">
+      <h1 hlmH1>Taxing Laughter: The Joke Tax</h1>
+      <p hlmLead>Once upon a time, a king decided to tax every joke told in his kingdom.</p>
+      <h2 hlmH2>The King's Plan</h2>
+      <p hlmP>The king thought long and hard, and finally came up with a brilliant plan.</p>
+      <blockquote hlmBlockquote>"After all," he said, "everyone enjoys a good joke, so it's only fair."</blockquote>
+      <h3 hlmH3>The Joke Tax</h3>
+      <p hlmP>The king's subjects were not amused. They grumbled and complained.</p>
+      <ul hlmUl>
+        <li>1st level of puns: 5 gold coins</li>
+        <li>2nd level of jokes: 10 gold coins</li>
+        <li>3rd level of one-liners: 20 gold coins</li>
+      </ul>
+    </article>
+  `,
+})
+export class DemoArticle {}
+```
+
+### 2. Headings hierarchy (h1–h4)
+
+```ts
+// demo-headings.component.ts
+import { Component } from '@angular/core';
+import { HlmTypographyImports } from '@egose/shadcn-theme-ng/typography';
+
+@Component({
+  selector: 'demo-headings',
+  standalone: true,
+  imports: [...HlmTypographyImports],
+  template: `
+    <h1 hlmH1>Heading 1 — page title</h1>
+    <h2 hlmH2>Heading 2 — section (with bottom border)</h2>
+    <h3 hlmH3>Heading 3 — subsection</h3>
+    <h4 hlmH4>Heading 4 — detail header</h4>
+  `,
+})
+export class DemoHeadings {}
+```
+
+Keep one `<h1>` per page and nest levels without skipping (h1→h2→h3).
+
+### 3. Lead, large, muted, small
+
+```ts
+// demo-scale.component.ts
+import { Component } from '@angular/core';
+import { HlmTypographyImports } from '@egose/shadcn-theme-ng/typography';
+
+@Component({
+  selector: 'demo-scale',
+  standalone: true,
+  imports: [...HlmTypographyImports],
+  template: `
+    <p hlmLead>A lead paragraph introduces the page — larger, muted.</p>
+    <p hlmP>Body copy with comfortable <code hlmCode>leading-7</code> rhythm.</p>
+    <div hlmLarge>Large: callouts, card titles, key figures.</div>
+    <p hlmMuted>Muted: timestamps, helper text, captions.</p>
+    <span hlmSmall>Small: labels, badges, table meta.</span>
+  `,
+})
+export class DemoScale {}
+```
+
+### 4. Inline code + blockquote
+
+```html
+<p hlmP>Run <code hlmCode>ng build my-lib</code> to build, then ship the output.</p>
+<blockquote hlmBlockquote>
+  "Design is the silent ambassador of your brand." — pair with a <cite>cite</cite> for attribution.
+</blockquote>
+```
+
+### 5. Lists (bulleted + mixed content)
+
+```html
+<ul hlmUl>
+  <li>Ship one library per component.</li>
+  <li>
+    Consume via subpath imports:
+    <code hlmCode>@egose/shadcn-theme-ng/button</code>
+  </li>
+  <li>Theme with CSS variables — no forks.</li>
+</ul>
+```
+
+### 6. Advanced: reusing class constants in custom components
+
+```ts
+// prose.component.ts
+import { Component, input } from '@angular/core';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+import { hlmH2, hlmP } from '@egose/shadcn-theme-ng/typography';
+
+@Component({
+  selector: 'app-prose-title',
+  standalone: true,
+  template: `<h2 [class]="classes()"><ng-content /></h2>`,
+})
+export class ProseTitle {
+  readonly tone = input<'default' | 'muted'>('default');
+
+  protected classes() {
+    return hlm(hlmH2, this.tone() === 'muted' && 'text-muted-foreground');
+  }
+}
+
+@Component({
+  selector: 'app-prose-body',
+  standalone: true,
+  template: `<p [class]="hlmP"><ng-content /></p>`,
+})
+export class ProseBody {
+  protected readonly hlmP = hlmP;
+}
 ```
+
+## Accessibility notes
+
+- Use real heading levels in order (`h1`→`h2`→`h3`); the directives style but never repair skipped levels — screen-reader navigation depends on the elements you choose.
+- `HlmMuted`/`HlmSmall` reduce size/contrast — verify contrast ratios for body text (muted grays can fail on light backgrounds at small sizes).
+- `<blockquote>` should contain the quote; add `<cite>`/attribution outside or within per your style guide.
+- `<code hlmCode>` is inline; for multi-line samples use `<pre><code>` with your own overflow handling and a plaintext alternative when meaning depends on formatting.
+
+## Theming / CSS variables
+
+Type styles key off `border-border`, `bg-muted`, and `text-muted-foreground` tokens, so they track your shadcn theme automatically. No per-component CSS variables.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/card` — `CardTitle`/`CardDescription` surfaces that pair with type scale.
+- `@egose/shadcn-theme-ng/table` — tabular content styled alongside prose.
+- `@egose/shadcn-theme-ng/badge` / `@egose/shadcn-theme-ng/kbd` — inline semantics to mix into paragraphs.
+- `@egose/shadcn-theme-ng/utils` — `hlm()` for composing the exported class constants.