@frame-kit/ui-ng 0.0.1

package/package.json

@@ -0,0 +1,253 @@
+{
+  "name": "@frame-kit/ui-ng",
+  "version": "0.0.1",
+  "description": "Style-agnostic, token-driven Angular UI component library for FrameKit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frame-kit/packages.git",
+    "directory": "packages/ui-ng"
+  },
+  "homepage": "https://github.com/frame-kit/packages/tree/main/packages/ui-ng#readme",
+  "bugs": "https://github.com/frame-kit/packages/issues",
+  "peerDependencies": {
+    "@angular/cdk": "^21.2.0",
+    "@angular/common": "^21.2.0",
+    "@angular/core": "^21.2.0",
+    "@angular/forms": "^21.2.0",
+    "@angular/platform-browser": "^21.2.0",
+    "@angular/router": "^21.2.0",
+    "rxjs": "^7.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "fesm2022/frame-kit-ui-ng.mjs",
+  "typings": "types/frame-kit-ui-ng.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/frame-kit-ui-ng.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng.mjs"
+    },
+    "./core/headline": {
+      "types": "./types/frame-kit-ui-ng-core-headline.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-headline.mjs"
+    },
+    "./core/icon": {
+      "types": "./types/frame-kit-ui-ng-core-icon.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-icon.mjs"
+    },
+    "./core/image": {
+      "types": "./types/frame-kit-ui-ng-core-image.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-image.mjs"
+    },
+    "./core/link": {
+      "types": "./types/frame-kit-ui-ng-core-link.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-link.mjs"
+    },
+    "./core/separator": {
+      "types": "./types/frame-kit-ui-ng-core-separator.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-separator.mjs"
+    },
+    "./core/text": {
+      "types": "./types/frame-kit-ui-ng-core-text.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-core-text.mjs"
+    },
+    "./directives/infinite-scroll": {
+      "types": "./types/frame-kit-ui-ng-directives-infinite-scroll.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-directives-infinite-scroll.mjs"
+    },
+    "./directives/spotlight": {
+      "types": "./types/frame-kit-ui-ng-directives-spotlight.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-directives-spotlight.mjs"
+    },
+    "./directives/tooltip": {
+      "types": "./types/frame-kit-ui-ng-directives-tooltip.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-directives-tooltip.mjs"
+    },
+    "./docs/endpoint-link": {
+      "types": "./types/frame-kit-ui-ng-docs-endpoint-link.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-docs-endpoint-link.mjs"
+    },
+    "./docs/method-badge": {
+      "types": "./types/frame-kit-ui-ng-docs-method-badge.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-docs-method-badge.mjs"
+    },
+    "./forms": {
+      "types": "./types/frame-kit-ui-ng-forms.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-forms.mjs"
+    },
+    "./layouts/app-shell": {
+      "types": "./types/frame-kit-ui-ng-layouts-app-shell.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-layouts-app-shell.mjs"
+    },
+    "./layouts/content-split": {
+      "types": "./types/frame-kit-ui-ng-layouts-content-split.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-layouts-content-split.mjs"
+    },
+    "./services/overlay-orchestrator": {
+      "types": "./types/frame-kit-ui-ng-services-overlay-orchestrator.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-services-overlay-orchestrator.mjs"
+    },
+    "./services/spotlight": {
+      "types": "./types/frame-kit-ui-ng-services-spotlight.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-services-spotlight.mjs"
+    },
+    "./services/toast": {
+      "types": "./types/frame-kit-ui-ng-services-toast.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-services-toast.mjs"
+    },
+    "./ui/accordion": {
+      "types": "./types/frame-kit-ui-ng-ui-accordion.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-accordion.mjs"
+    },
+    "./ui/alert": {
+      "types": "./types/frame-kit-ui-ng-ui-alert.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-alert.mjs"
+    },
+    "./ui/avatar": {
+      "types": "./types/frame-kit-ui-ng-ui-avatar.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-avatar.mjs"
+    },
+    "./ui/avatar-stack": {
+      "types": "./types/frame-kit-ui-ng-ui-avatar-stack.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-avatar-stack.mjs"
+    },
+    "./ui/badge": {
+      "types": "./types/frame-kit-ui-ng-ui-badge.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-badge.mjs"
+    },
+    "./ui/breadcrumb": {
+      "types": "./types/frame-kit-ui-ng-ui-breadcrumb.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-breadcrumb.mjs"
+    },
+    "./ui/button": {
+      "types": "./types/frame-kit-ui-ng-ui-button.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-button.mjs"
+    },
+    "./ui/callout": {
+      "types": "./types/frame-kit-ui-ng-ui-callout.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-callout.mjs"
+    },
+    "./ui/card": {
+      "types": "./types/frame-kit-ui-ng-ui-card.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-card.mjs"
+    },
+    "./ui/copyable-field": {
+      "types": "./types/frame-kit-ui-ng-ui-copyable-field.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-copyable-field.mjs"
+    },
+    "./ui/data-table": {
+      "types": "./types/frame-kit-ui-ng-ui-data-table.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-data-table.mjs"
+    },
+    "./ui/dialog": {
+      "types": "./types/frame-kit-ui-ng-ui-dialog.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-dialog.mjs"
+    },
+    "./ui/drawer": {
+      "types": "./types/frame-kit-ui-ng-ui-drawer.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-drawer.mjs"
+    },
+    "./ui/dropdown-menu": {
+      "types": "./types/frame-kit-ui-ng-ui-dropdown-menu.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-dropdown-menu.mjs"
+    },
+    "./ui/editable-field": {
+      "types": "./types/frame-kit-ui-ng-ui-editable-field.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-editable-field.mjs"
+    },
+    "./ui/icon-badge": {
+      "types": "./types/frame-kit-ui-ng-ui-icon-badge.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-icon-badge.mjs"
+    },
+    "./ui/icon-list": {
+      "types": "./types/frame-kit-ui-ng-ui-icon-list.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-icon-list.mjs"
+    },
+    "./ui/inline-edit": {
+      "types": "./types/frame-kit-ui-ng-ui-inline-edit.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-inline-edit.mjs"
+    },
+    "./ui/list-editor": {
+      "types": "./types/frame-kit-ui-ng-ui-list-editor.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-list-editor.mjs"
+    },
+    "./ui/loader": {
+      "types": "./types/frame-kit-ui-ng-ui-loader.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-loader.mjs"
+    },
+    "./ui/menu-item": {
+      "types": "./types/frame-kit-ui-ng-ui-menu-item.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-menu-item.mjs"
+    },
+    "./ui/nav-brand": {
+      "types": "./types/frame-kit-ui-ng-ui-nav-brand.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-nav-brand.mjs"
+    },
+    "./ui/nav-group": {
+      "types": "./types/frame-kit-ui-ng-ui-nav-group.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-nav-group.mjs"
+    },
+    "./ui/nav-separator": {
+      "types": "./types/frame-kit-ui-ng-ui-nav-separator.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-nav-separator.mjs"
+    },
+    "./ui/node-tree": {
+      "types": "./types/frame-kit-ui-ng-ui-node-tree.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-node-tree.mjs"
+    },
+    "./ui/node-tree-breadcrumb": {
+      "types": "./types/frame-kit-ui-ng-ui-node-tree-breadcrumb.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-node-tree-breadcrumb.mjs"
+    },
+    "./ui/note": {
+      "types": "./types/frame-kit-ui-ng-ui-note.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-note.mjs"
+    },
+    "./ui/numbered-list": {
+      "types": "./types/frame-kit-ui-ng-ui-numbered-list.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-numbered-list.mjs"
+    },
+    "./ui/pagination": {
+      "types": "./types/frame-kit-ui-ng-ui-pagination.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-pagination.mjs"
+    },
+    "./ui/progress-bar": {
+      "types": "./types/frame-kit-ui-ng-ui-progress-bar.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-progress-bar.mjs"
+    },
+    "./ui/sidenav-link": {
+      "types": "./types/frame-kit-ui-ng-ui-sidenav-link.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-sidenav-link.mjs"
+    },
+    "./ui/tabs": {
+      "types": "./types/frame-kit-ui-ng-ui-tabs.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-tabs.mjs"
+    },
+    "./ui/timeline": {
+      "types": "./types/frame-kit-ui-ng-ui-timeline.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-timeline.mjs"
+    },
+    "./ui/toast": {
+      "types": "./types/frame-kit-ui-ng-ui-toast.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-toast.mjs"
+    },
+    "./ui/user-menu": {
+      "types": "./types/frame-kit-ui-ng-ui-user-menu.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-user-menu.mjs"
+    },
+    "./ui/wizard-dialog": {
+      "types": "./types/frame-kit-ui-ng-ui-wizard-dialog.d.ts",
+      "default": "./fesm2022/frame-kit-ui-ng-ui-wizard-dialog.mjs"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

package/services/overlay-orchestrator/README.md

@@ -0,0 +1,184 @@
+# OverlayOrchestrator
+
+A centralized service for managing overlay interactions (dialogs, drawers, popovers, navigation panels, tooltips) using a priority-based stack. Prevents UI conflicts like drawers staying open behind dialogs, or menus persisting when modals appear.
+
+---
+
+## Initialization
+
+The `OverlayOrchestrator` is provided at the root level (`providedIn: 'root'`). No setup is needed — inject it wherever you need overlay coordination.
+
+```ts
+import { OverlayOrchestrator, OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
+```
+
+### Built-in Integration
+
+`DialogService` and `DrawerService` automatically register with the orchestrator. Opening a dialog auto-closes any open drawer or popover. Opening a drawer auto-closes any open popover. No consumer code is needed for these — it works out of the box.
+
+### Registering Custom Overlays
+
+For overlays not managed by `DialogService` or `DrawerService` (e.g., custom popovers, app navigation panels, kebab menus), register them manually:
+
+```ts
+@Component({ ... })
+export class MyComponent {
+  private readonly orchestrator = inject(OverlayOrchestrator);
+  private overlayId: string | null = null;
+
+  open(): void {
+    // Register with a priority — closes all lower-priority overlays
+    this.overlayId = this.orchestrator.register({
+      priority: OVERLAY_PRIORITY.POPOVER,
+      type: "my-popover",
+      close: () => this.close(),
+    });
+  }
+
+  close(): void {
+    if (this.overlayId) {
+      this.orchestrator.unregister(this.overlayId);
+      this.overlayId = null;
+    }
+
+    // ... your close logic
+  }
+}
+```
+
+### Registering App Navigation
+
+The app shell sidebar should register at the highest priority so it always opens on top:
+
+```ts
+@Component({ ... })
+export class AppShellComponent {
+  private readonly orchestrator = inject(OverlayOrchestrator);
+  private navOverlayId: string | null = null;
+
+  openNav(): void {
+    this.navOverlayId = this.orchestrator.register({
+      priority: OVERLAY_PRIORITY.NAVIGATION,
+      type: "navigation",
+      close: () => this.closeNav(),
+    });
+  }
+
+  closeNav(): void {
+    if (this.navOverlayId) {
+      this.orchestrator.unregister(this.navOverlayId);
+      this.navOverlayId = null;
+    }
+
+    // ... your close logic
+  }
+}
+```
+
+### Guarding Before Opening
+
+Check if a higher-priority overlay is already open before opening yours:
+
+```ts
+if (!this.orchestrator.hasOverlayAtOrAbove(OVERLAY_PRIORITY.DIALOG)) {
+  this.openDrawer();
+}
+```
+
+---
+
+## API
+
+### OverlayOrchestrator (Injectable)
+
+#### Methods
+
+| Method                | Signature                                     | Description                                                                    |
+| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `register`            | `(entry: Omit<OverlayEntry, 'id'>) => string` | Register an overlay. Auto-closes lower-priority overlays. Returns a unique ID. |
+| `unregister`          | `(id: string) => void`                        | Remove an overlay by ID. Call when the overlay closes.                         |
+| `closeAll`            | `() => void`                                  | Close all overlays, lowest priority first.                                     |
+| `closeAtOrBelow`      | `(priority: number) => void`                  | Close all overlays at or below the given priority.                             |
+| `hasOverlayAtOrAbove` | `(priority: number) => boolean`               | Check if any overlay at or above a priority is open.                           |
+| `hasOverlayOfType`    | `(type: string) => boolean`                   | Check if any overlay of a given type is open.                                  |
+
+#### Signals (Reactive)
+
+| Signal             | Type                           | Description                        |
+| ------------------ | ------------------------------ | ---------------------------------- |
+| `hasActiveOverlay` | `Signal<boolean>`              | Whether any overlay is open.       |
+| `topOverlay`       | `Signal<OverlayEntry \| null>` | The highest-priority open overlay. |
+| `count`            | `Signal<number>`               | Number of active overlays.         |
+
+---
+
+## Priority Levels
+
+Default priority constants are provided via `OVERLAY_PRIORITY`. You can use any number — these are conventions, not constraints.
+
+```ts
+import { OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
+
+OVERLAY_PRIORITY.TOOLTIP; // 0  — tooltips, inline hints
+OVERLAY_PRIORITY.POPOVER; // 10 — dropdown menus, kebab menus
+OVERLAY_PRIORITY.DRAWER; // 20 — side panels, detail drawers
+OVERLAY_PRIORITY.DIALOG; // 30 — modal dialogs, confirmations
+OVERLAY_PRIORITY.NAVIGATION; // 40 — app-level navigation sidebar
+```
+
+### Custom Priorities
+
+Use any number to fine-tune behavior:
+
+```ts
+// A toast notification that sits between popover and drawer
+orchestrator.register({
+  priority: 15,
+  type: 'toast',
+  close: () => this.dismissToast(),
+});
+```
+
+---
+
+## OverlayEntry Interface
+
+```ts
+interface OverlayEntry {
+  id: string; // Auto-generated unique ID
+  priority: number; // Higher = stays open longer
+  type: string; // Label for debugging/querying
+  close: () => void; // Called by orchestrator to close
+}
+```
+
+---
+
+## Behavior Rules
+
+1. **Opening a new overlay closes all overlays with LOWER priority.**
+   - Opening a dialog (30) closes drawers (20), popovers (10), tooltips (0).
+   - Opening a drawer (20) closes popovers (10) and tooltips (0).
+   - Opening the nav (40) does not close dialogs (30) — they have lower priority.
+
+2. **Overlays with EQUAL or HIGHER priority are left open.**
+   - Opening a second dialog does not close the first dialog.
+   - Opening the nav while a dialog is open leaves the dialog open.
+
+3. **Unregistration is the consumer's responsibility.**
+   - The orchestrator calls `close()` on entries to request closure.
+   - The consumer must call `unregister(id)` when the overlay actually closes.
+   - `DialogService` and `DrawerService` handle this automatically.
+
+4. **Priority is set per instance, not per type.**
+   - The same component can register at different priorities depending on context.
+   - A critical confirmation dialog could register at 35 to stay above normal dialogs.
+
+---
+
+## Import
+
+```ts
+import { OverlayOrchestrator, OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
+import type { OverlayEntry } from '@frame-kit/ui-ng';
+```

package/services/spotlight/README.md

@@ -0,0 +1,61 @@
+# SpotlightService
+
+Coordinates a single global "active key" with reference-counted holders, so unrelated parts of the DOM can pulse together when the same key is active. The `fkSpotlightTrigger` and `fkSpotlightTarget` directives are the typical consumers — this service is the registry they talk through.
+
+For most use cases you don't inject `SpotlightService` directly; you bind the directives to a shared key. Reach for the service when you need a programmatic activation (e.g. auto-spotlight on panel open) that should coexist with hover-driven triggers.
+
+---
+
+## Initialization
+
+Provided in root (`@Injectable({ providedIn: "root" })`). No setup required:
+
+```ts
+import { SpotlightService } from '@frame-kit/ui-ng';
+
+export class MyComponent {
+  private readonly spotlight = inject(SpotlightService);
+}
+```
+
+There's a single coordinator across the whole app — keys broadcast in any feature module are picked up by targets in any other module.
+
+---
+
+## API
+
+### Signals
+
+| Signal      | Type                     | Description                                                         |
+| ----------- | ------------------------ | ------------------------------------------------------------------- |
+| `activeKey` | `Signal<string \| null>` | The currently active spotlight key, or `null` when nothing is held. |
+
+### Methods
+
+| Method            | Returns | Description                                                                                                                                 |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activate(key)`   | `void`  | Add a holder for `key` and set it as the active key. If a different key is currently active, this replaces it (last write wins).            |
+| `deactivate(key)` | `void`  | Release a holder for `key`. The key only clears when every holder has released; if it's still the active key, `activeKey` resets to `null`. |
+
+---
+
+## Usage
+
+```ts
+const spotlight = inject(SpotlightService);
+
+// One-shot activation (e.g. on panel open) — release after 2s
+spotlight.activate('open-roadmap');
+setTimeout(() => spotlight.deactivate('open-roadmap'), 2000);
+```
+
+A hover-driven `fkSpotlightTrigger` activating the same key while the timer is still pending coexists with this programmatic holder — the spotlight only clears when both have released.
+
+---
+
+## Behavior Notes
+
+- **Holders are reference-counted, not idempotent.** Calling `activate(key)` twice requires two `deactivate(key)` calls to clear. This is what lets a hover trigger and a programmatic one-shot coexist without one cancelling the other.
+- **Single global active key.** If `activate("foo")` runs while `"bar"` is held, the active key flips to `"foo"`. The `"bar"` holders still count, so re-activating `"bar"` later restores it. This matches the primary use case (onboarding "find this thing" cues are mutually exclusive by nature).
+- **Pure read interface.** `activeKey` is exposed as a read-only signal — consumers (typically the `fkSpotlightTarget` directive) read it via `computed(() => spotlight.activeKey() === myKey)` and react.
+- `deactivate(key)` on a key with no holders is a no-op — safe to call defensively.

package/services/toast/README.md

@@ -0,0 +1,118 @@
+# ToastService
+
+Global notification queue. Push transient messages onto a single stack rendered by `<fk-toast-container>` somewhere near the app root. Default toasts cover the four severities (success / error / warning / info); custom-component toasts let you embed action affordances (retry buttons, undo links, etc.) inside the toast body.
+
+---
+
+## Initialization
+
+Provided in root (`@Injectable({ providedIn: "root" })`). No setup required to use:
+
+```ts
+import { ToastService } from '@frame-kit/ui-ng';
+
+export class MyComponent {
+  private readonly toast = inject(ToastService);
+}
+```
+
+### Container placement
+
+The service holds the queue; rendering is the consumer's job. Place a single `<fk-toast-container />` near the app root so toasts surface above everything else:
+
+```html
+<!-- app.component.html -->
+<router-outlet />
+<fk-toast-container />
+```
+
+### Optional configuration
+
+Override defaults via the `TOAST_CONFIG` injection token at app bootstrap:
+
+```ts
+import { TOAST_CONFIG } from '@frame-kit/ui-ng';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    {
+      provide: TOAST_CONFIG,
+      useValue: { defaultDuration: 4000, errorDuration: 10000 },
+    },
+  ],
+});
+```
+
+If absent, defaults are 5000 ms for non-error toasts and 8000 ms for errors.
+
+---
+
+## API
+
+### Signals
+
+| Signal   | Type              | Description                                               |
+| -------- | ----------------- | --------------------------------------------------------- |
+| `toasts` | `Signal<Toast[]>` | Current toast stack. The container renders this directly. |
+
+### Severity helpers
+
+| Method                      | Returns  | Description                                                            |
+| --------------------------- | -------- | ---------------------------------------------------------------------- |
+| `success(summary, detail?)` | `string` | Push a green/success toast. Returns the toast id for manual dismissal. |
+| `error(summary, detail?)`   | `string` | Push a red/error toast. Defaults to the longer `errorDuration`.        |
+| `warning(summary, detail?)` | `string` | Push a yellow/warning toast.                                           |
+| `info(summary, detail?)`    | `string` | Push a neutral/info toast.                                             |
+
+### Generic API
+
+| Method                                                  | Returns           | Description                                                                                                                   |
+| ------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `show({ severity, summary, detail?, duration? })`       | `string`          | Push a default toast with explicit fields. Returns the toast id.                                                              |
+| `open<TData>(component, { severity, data, duration? })` | `ToastRef<TData>` | Push a custom-component toast. Use this when the toast needs interactive children (retry buttons, undo links, progress bars). |
+| `dismiss(id)`                                           | `void`            | Remove a toast by id (e.g. when its associated work completes early).                                                         |
+| `clear()`                                               | `void`            | Drop every queued toast.                                                                                                      |
+
+---
+
+## Usage
+
+### Default severity helpers
+
+```ts
+const toast = inject(ToastService);
+
+toast.success('Saved successfully');
+toast.error('Something went wrong', 'Please try again.');
+toast.info('Sync started');
+```
+
+### Custom-component toast
+
+```ts
+toast.open(RetryToastComponent, {
+  severity: 'error',
+  data: { message: 'Failed to save', retryFn: () => this.save() },
+});
+```
+
+The custom component receives the `data` payload via DI (typically `inject(TOAST_DATA)` inside the component) and can call `dismiss()` on the returned `ToastRef` to close itself.
+
+### Manual dismissal
+
+```ts
+const id = toast.info('Uploading…', '0 of 10 files');
+
+// later, when the upload finishes early:
+toast.dismiss(id);
+```
+
+---
+
+## Behavior Notes
+
+- **Auto-dismiss** is scheduled per toast at push time. The default duration depends on severity (`errorDuration` for `"error"`, `defaultDuration` otherwise) unless an explicit `duration` is passed.
+- **Stack growth is uncapped** — the service doesn't drop old toasts when the queue grows. The container renders them in arrival order; if you expect bursts (e.g. reacting to a multi-error response), call `clear()` first or batch your message into a single toast.
+- **Custom toasts return a `ToastRef`** with `dismiss()` and the toast id. The base `show()` and severity helpers return just the id — call `dismiss(id)` on the service to remove them.
+- **The container is a separate component** (`fk-toast-container`) — placing it once near the app root is enough; the service is global.
+- **Resolved config** is exposed as `resolvedConfig` on the service for tests or for components that want to align their own timeouts with the toast duration.

package/types/frame-kit-ui-ng-core-headline.d.ts

@@ -0,0 +1,38 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+
+type HeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+type HeadlineVariant = 'default' | 'muted';
+
+declare class HeadlineComponent {
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    readonly className: _angular_core.InputSignal<string>;
+    /** Custom font-size override applied directly to the host element. */
+    readonly fontSize: _angular_core.InputSignal<string | null>;
+    readonly id: _angular_core.InputSignal<string | null>;
+    /** Semantic heading level rendered in the DOM (h1–h6). */
+    readonly level: _angular_core.InputSignal<HeadlineLevel>;
+    /** Visual style applied to the heading — `"muted"` reduces contrast. */
+    readonly variant: _angular_core.InputSignal<HeadlineVariant>;
+    /** Hides the heading visually while keeping it in the accessibility tree. */
+    readonly visuallyHidden: _angular_core.InputSignal<boolean>;
+    private readonly h1;
+    private readonly h2;
+    private readonly h3;
+    private readonly h4;
+    private readonly h5;
+    private readonly h6;
+    private readonly injector;
+    private readonly doc;
+    readonly classes: _angular_core.Signal<string>;
+    get hostClass(): string;
+    get hostFontSize(): string | null;
+    readonly template: _angular_core.Signal<TemplateRef<unknown>>;
+    private static lastWarnedH1Count;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HeadlineComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HeadlineComponent, "fk-headline", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "fontSize": { "alias": "fontSize"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "level": { "alias": "level"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "visuallyHidden": { "alias": "visuallyHidden"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+export { HeadlineComponent };
+export type { HeadlineLevel, HeadlineVariant };