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

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.

package/utils/README.md

@@ -1,3 +1,304 @@
-# Utils Subpath
+# Utils (`@egose/shadcn-theme-ng/utils`)
 
-This project ships only as `@egose/shadcn-theme-ng/utils` or `@egose/shadcn-theme-ng-tw/utils`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+Shared styling and setup helpers used by every component in this library — equivalent to the `cn()`/`lib/utils` module in [shadcn/ui](https://ui.shadcn.com/docs/installation). This subpath exports **`hlm()`** (the `clsx` + `tailwind-merge` class merger), **`classes()`** (the reactive host-class manager behind every `hlm*` directive), and **`provideSpartanHlm()`** (the app-level overlay provider). It has no components and no `*Imports`/`*Module` — import the functions directly. Notably, `classes()` is SSR-safe (no `MutationObserver` on the server), transition-flash-safe (suppresses CSS transitions on first apply), and teardown-safe (disconnects observers / cancels animation frames via `DestroyRef`).
+
+> **Ships as:** `@egose/shadcn-theme-ng/utils` and `@egose/shadcn-theme-ng-tw/utils` (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
+```
+
+`clsx` and `tailwind-merge` arrive transitively. See the [package README](../../README.md) for the full peer-dependency table.
+
+Register the environment provider once at bootstrap (required for overlay-based components):
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideSpartanHlm } from '@egose/shadcn-theme-ng/utils';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideSpartanHlm()],
+};
+```
+
+## Imports
+
+All public symbols are re-exported from `projects/utils/src/public-api.ts` (`./lib/utils` + `./lib/provide-spartan-hlm`):
+
+```ts
+import { classes, hlm, provideSpartanHlm } from '@egose/shadcn-theme-ng/utils';
+// tw variant: swap to '@egose/shadcn-theme-ng-tw/utils'
+```
+
+| Symbol              | Kind     | Signature (real)                                                                  | Description                                                  |
+| ------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `hlm`               | Function | `hlm(...inputs: ClassValue[]): string`                                            | Merges class lists (`twMerge(clsx(inputs))`).                |
+| `classes`           | Function | `classes(computed: () => ClassValue[] \| string, options?: ClassesOptions): void` | Reactively applies computed classes to the host element.     |
+| `provideSpartanHlm` | Function | `provideSpartanHlm(): EnvironmentProviders`                                       | Provides `OVERLAY_DEFAULT_CONFIG` (`{ usePopover: false }`). |
+
+`ClassesOptions` (interface, not exported from the barrel — structural shape):
+
+```ts
+interface ClassesOptions {
+  elementRef?: ElementRef<HTMLElement>;
+  injector?: Injector;
+}
+```
+
+There is no `UtilsImports` / `UtilsModule` — nothing to add to `imports: [...]`.
+
+## Anatomy / Structure
+
+```ts
+// 1. One-off merge (templates, custom components)
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+const cls = hlm('px-4 py-2', condition && 'bg-primary', userClass);
+
+// 2. Reactive host styling (directives/components)
+import { Directive } from '@angular/core';
+import { classes } from '@egose/shadcn-theme-ng/utils';
+
+@Directive({ selector: '[myStyled]' })
+export class MyStyled {
+  constructor() {
+    classes(() => 'rounded-md border bg-background');
+  }
+}
+
+// 3. App bootstrap (once)
+import { provideSpartanHlm } from '@egose/shadcn-theme-ng/utils';
+export const appConfig: ApplicationConfig = { providers: [provideSpartanHlm()] };
+```
+
+## API reference
+
+### `hlm(...inputs: ClassValue[]): string`
+
+Merges any `clsx`-compatible inputs (`string | string[] | Record<string, boolean> | false | null | undefined`, nested) and resolves Tailwind conflicts with `twMerge`. Later arguments win on conflict.
+
+| Call                                                    | Result                       |
+| ------------------------------------------------------- | ---------------------------- |
+| `hlm('px-2 px-4')`                                      | `'px-4'` (conflict resolved) |
+| `hlm('text-sm', isActive && 'text-primary', userClass)` | conditional merge            |
+| `hlm(['rounded', { 'bg-muted': selected }])`            | array/object forms           |
+
+Backed by `clsx` + `tailwind-merge`; string inputs are cached (up to 1000 entries) internally.
+
+### `classes(computed, options?): void`
+
+Runs in an injection context (`runInInjectionContext`) and wires the host element to a reactive class computation. Must be called in a constructor (or any injection context) of a directive/component.
+
+- `computed: () => ClassValue[] | string` — re-evaluated in an `effect()`; any signals read inside are tracked, so class updates are automatic.
+- `options.elementRef?: ElementRef<HTMLElement>` — defaults to the injected host `ElementRef`. Pass explicitly for out-of-band elements (tests, portals, iframes).
+- `options.injector?: Injector` — defaults to the current injector. Pass explicitly when calling outside the construction context (e.g. per-document setup in tests).
+
+Behavioral guarantees (verified by `utils.spec.ts`):
+
+- Base-class preservation: pre-existing `class` attribute values and externally added classes are kept and re-merged (not wiped) via a per-document `MutationObserver`.
+- Scoped observation: one shared observer per `Document` (isolated per iframe document); unrelated elements never trigger callbacks.
+- Transition suppression: CSS `transition` is forced to `none !important` on first apply, then restored on the next animation frame — prevents initial style flashes.
+- Teardown: `DestroyRef.onDestroy` removes the source, cancels pending RAFs, restores transitions, disconnects the observer when the last managed element is destroyed, and cleans per-document state.
+- SSR-safe: no `MutationObserver` is created when `PLATFORM_ID` is `'server'`.
+
+### `provideSpartanHlm(): EnvironmentProviders`
+
+```ts
+export function provideSpartanHlm(): EnvironmentProviders {
+  return makeEnvironmentProviders([{ provide: OVERLAY_DEFAULT_CONFIG, useValue: { usePopover: false } }]);
+}
+```
+
+Call once in `appConfig.providers`. Forces CDK overlays (tooltip, popover, dropdown, dialog, …) to use the classic overlay strategy instead of the native `popover` API.
+
+## Examples
+
+### 1. `hlm()` — conditional class merging
+
+```ts
+// demo-merge.component.ts
+import { Component, input } from '@angular/core';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+@Component({
+  selector: 'demo-merge',
+  standalone: true,
+  template: `<div [class]="cls()">Hello</div>`,
+})
+export class DemoMerge {
+  readonly active = input(false);
+  readonly userClass = input<string>('', { alias: 'class' });
+
+  protected cls() {
+    return hlm(
+      'rounded-md border px-4 py-2 text-sm',
+      this.active() && 'border-primary bg-primary/10',
+      this.userClass(),
+    );
+  }
+}
+```
+
+```html
+<demo-merge [active]="true" class="shadow-lg" />
+<!-- later utilities win: hlm('px-2 px-4') === 'px-4' -->
+```
+
+### 2. `hlm()` — object / array forms
+
+```ts
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+const cls = hlm(
+  ['inline-flex items-center gap-2', 'rounded-md'],
+  { 'bg-primary text-primary-foreground': true, 'opacity-50': false },
+  null,
+  undefined,
+);
+```
+
+### 3. `classes()` — custom styled directive (signal-reactive)
+
+```ts
+// status-dot.directive.ts
+import { Directive, input } from '@angular/core';
+import { classes } from '@egose/shadcn-theme-ng/utils';
+
+@Directive({ selector: '[statusDot]' })
+export class StatusDot {
+  readonly tone = input<'ok' | 'warn' | 'bad'>('ok');
+
+  constructor() {
+    classes(() => [
+      'inline-block size-2 rounded-full',
+      this.tone() === 'ok' && 'bg-emerald-500',
+      this.tone() === 'warn' && 'bg-amber-500',
+      this.tone() === 'bad' && 'bg-destructive',
+    ]);
+  }
+}
+```
+
+```ts
+// usage
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'demo-dot',
+  standalone: true,
+  imports: [StatusDot],
+  template: `
+    <span statusDot tone="ok"></span>
+    <span statusDot tone="bad" class="ml-2"></span>
+  `,
+})
+export class DemoDot {}
+```
+
+The trailing `class="ml-2"` is preserved — `classes()` merges base classes instead of overwriting them.
+
+### 4. `classes()` — variant-driven component (cva + signals)
+
+```ts
+// pill.component.ts
+import { Component, input } from '@angular/core';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { classes } from '@egose/shadcn-theme-ng/utils';
+
+export const pillVariants = cva('inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium', {
+  variants: { tone: { default: 'bg-muted', brand: 'bg-primary text-primary-foreground' } },
+  defaultVariants: { tone: 'default' },
+});
+export type PillTones = VariantProps<typeof pillVariants>;
+
+@Component({
+  selector: 'demo-pill',
+  standalone: true,
+  template: `<ng-content />`,
+})
+export class DemoPill {
+  readonly tone = input<PillTones['tone']>('default');
+
+  constructor() {
+    classes(() => pillVariants({ tone: this.tone() }));
+  }
+}
+```
+
+### 5. `provideSpartanHlm()` — app bootstrap + overlay consumers
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { provideSpartanHlm } from '@egose/shadcn-theme-ng/utils';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideAnimations(), provideSpartanHlm()],
+};
+```
+
+Any overlay component (tooltip, popover, dropdown-menu, dialog, hover-card, …) then uses the supported overlay strategy without per-component configuration:
+
+```ts
+// demo-overlay.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-overlay',
+  standalone: true,
+  imports: [...HlmTooltipImports, ...HlmButtonImports],
+  template: `<button hlmBtn [hlmTooltip]="'Overlay-styled hint'">Hover</button>`,
+})
+export class DemoOverlay {}
+```
+
+### 6. Advanced: explicit `elementRef` / multi-document usage
+
+```ts
+// managed-element.service.ts (e.g. portals, iframes, tests)
+import { DOCUMENT, Injectable, inject, Injector, ElementRef } from '@angular/core';
+import { classes } from '@egose/shadcn-theme-ng/utils';
+
+@Injectable({ providedIn: 'root' })
+export class ManagedElementService {
+  private readonly injector = inject(Injector);
+  private readonly document = inject(DOCUMENT);
+
+  styleDetached(element: HTMLElement, extra: string) {
+    // Drives classes on an element outside the current host,
+    // tracked against this injector's DestroyRef lifecycle.
+    classes(() => ['rounded-md border', extra], {
+      elementRef: new ElementRef(element),
+      injector: this.injector,
+    });
+  }
+}
+```
+
+Per-document observer isolation means elements in different `Document`s (iframes) each get their own observer lifecycle — destroying the injector disconnects only its own document's observer.
+
+## Accessibility notes
+
+- `hlm()`/`classes()` are styling-only — they confer no semantics. Pair visual treatments with real roles, labels, and focus management from the component subpaths.
+- When toggling state classes (e.g. `bg-destructive` for errors), always also surface a text cue (`hlm-error`, `aria-invalid`, `aria-describedby`) — color alone is not perceivable.
+- Transition suppression in `classes()` avoids first-paint flashes but does not disable motion for users with `prefers-reduced-motion` — respect that media query in your own animation utilities.
+
+## Theming / CSS variables
+
+No theme of its own — `hlm()`/`classes()` are token-agnostic mergers. They resolve whatever utilities you pass (including shadcn theme tokens like `bg-background`, `text-muted-foreground`, `border-input`), so output follows your configured theme automatically.
+
+## Related subpaths
+
+- Every component subpath (`button`, `dialog`, `table`, …) — all consume `hlm()`/`classes()` internally; import this subpath when building custom shadcn-styled directives.
+- `@egose/shadcn-theme-ng/tooltip` — example consumer of `hlm()` for arrow/content classes (`tooltipPositionVariants`).
+- `@egose/shadcn-theme-ng/toggle` / `@egose/shadcn-theme-ng/toggle-group` — example consumers of the cva + `classes()` pattern.
+- `@egose/shadcn-theme-ng/typography` — example consumer re-exporting class constants composed with `hlm()`.