@frame-kit/ui-ng 0.0.1

package/core/text/README.md

@@ -0,0 +1,240 @@
+# fk-text
+
+A flexible typography component that renders semantic text elements with design-token-driven variants, tones, alignment, truncation, and accessibility options.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                                                            | Default     | Description                                            |
+| ----------------- | --------------------------------------------------------------- | ----------- | ------------------------------------------------------ |
+| `as`              | `'p' \| 'span' \| 'div' \| 'label' \| 'small'`                  | `'p'`       | Underlying HTML element to render                      |
+| `variant`         | `'body' \| 'lead' \| 'small' \| 'caption' \| 'label' \| 'code'` | `'body'`    | Typography variant (type scale)                        |
+| `tone`            | `'default' \| 'muted' \| 'subtle' \| 'danger' \| 'success'`     | `'default'` | Color tone                                             |
+| `align`           | `'inherit' \| 'start' \| 'center' \| 'end' \| 'justify'`        | `'inherit'` | Text alignment                                         |
+| `weight`          | `'normal' \| 'medium' \| 'semibold' \| 'bold' \| null`          | `null`      | Font weight override (uses variant default when null)  |
+| `truncate`        | `boolean`                                                       | `false`     | Single-line truncation with ellipsis                   |
+| `maxLines`        | `number \| null`                                                | `null`      | Multi-line clamp count; adds ellipsis after N lines    |
+| `gutterBottom`    | `boolean`                                                       | `false`     | Adds bottom margin                                     |
+| `italic`          | `boolean`                                                       | `false`     | Italic style                                           |
+| `visuallyHidden`  | `boolean`                                                       | `false`     | Visually hide text while keeping it for screen readers |
+| `className`       | `string`                                                        | `''`        | Additional CSS classes                                 |
+| `id`              | `string \| null`                                                | `null`      | ID attribute                                           |
+| `ariaLabel`       | `string \| null`                                                | `null`      | ARIA label                                             |
+| `ariaDescribedBy` | `string \| null`                                                | `null`      | ARIA described-by                                      |
+| `role`            | `string \| null`                                                | `null`      | ARIA role (usually not needed)                         |
+| `htmlFor`         | `string \| null`                                                | `null`      | `for` attribute when `as="label"`                      |
+
+### Outputs
+
+`fk-text` is presentational and does not emit outputs.
+
+### Content
+
+Content is provided via projection:
+
+```html
+<fk-text variant="body" tone="muted">Last updated 2 hours ago</fk-text>
+```
+
+---
+
+## Features
+
+- Unified API for semantic text elements (`p`, `span`, `div`, `label`, `small`)
+- Variant-driven typography scale
+- Tone and weight controls
+- Single-line and multi-line truncation
+- Alignment, gutter, italic, and screen-reader-only options
+- Token-driven styling
+- Self-sufficient rendering without any theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-text>This is body text.</fk-text>
+```
+
+---
+
+## Import
+
+```ts
+import { TextComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [TextComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-text></fk-text>
+```
+
+---
+
+## Examples
+
+### Variants
+
+```html
+<fk-text variant="body">Body text</fk-text>
+<fk-text variant="lead">Lead text</fk-text>
+<fk-text variant="small">Small text</fk-text>
+<fk-text variant="caption">Caption text</fk-text>
+<fk-text variant="label">Label text</fk-text>
+<fk-text variant="code">Code text</fk-text>
+```
+
+### Tones
+
+```html
+<fk-text tone="default">Default tone</fk-text>
+<fk-text tone="muted">Muted tone</fk-text>
+<fk-text tone="subtle">Subtle tone</fk-text>
+<fk-text tone="danger">Danger tone</fk-text>
+<fk-text tone="success">Success tone</fk-text>
+```
+
+### Weight override
+
+```html
+<fk-text weight="bold">Bold body text</fk-text>
+```
+
+### Truncated single-line
+
+```html
+<fk-text [truncate]="true">This is a very long piece of text that will be truncated with an ellipsis when it overflows the container.</fk-text>
+```
+
+### Multi-line clamp
+
+```html
+<fk-text [maxLines]="3">Long description that will be clamped to three lines with ellipsis.</fk-text>
+```
+
+### Label usage
+
+```html
+<fk-text as="label" variant="label" htmlFor="email-input">Email address</fk-text> <input id="email-input" type="email" />
+```
+
+### Inline span
+
+```html
+<fk-text as="span" variant="small" tone="muted">Inline text</fk-text>
+```
+
+---
+
+## Accessibility
+
+- `visuallyHidden` adds a screen-reader-only class, preserving content for assistive technologies.
+- When used as `"label"`, `htmlFor` should be set to the corresponding input's ID.
+- `ariaLabel`, `ariaDescribedBy`, and `role` are available for advanced scenarios; in most cases, semantic HTML and visible text are sufficient.
+
+---
+
+## Design Tokens
+
+`fk-text` is styled entirely through design tokens.
+
+### Component tokens
+
+```
+--fk-text-margin-block-start
+--fk-text-margin-block-end
+--fk-text-color-default
+--fk-text-color-muted
+--fk-text-color-subtle
+--fk-text-color-danger
+--fk-text-color-success
+```
+
+### Typography scale tokens (per variant)
+
+```
+--fk-typography-body-font-size
+--fk-typography-body-font-weight
+--fk-typography-body-line-height
+--fk-typography-body-letter-spacing
+
+--fk-typography-lead-font-size
+--fk-typography-lead-font-weight
+--fk-typography-lead-line-height
+--fk-typography-lead-letter-spacing
+
+--fk-typography-small-font-size
+--fk-typography-small-font-weight
+--fk-typography-small-line-height
+--fk-typography-small-letter-spacing
+
+--fk-typography-caption-font-size
+--fk-typography-caption-font-weight
+--fk-typography-caption-line-height
+--fk-typography-caption-letter-spacing
+
+--fk-typography-label-font-size
+--fk-typography-label-font-weight
+--fk-typography-label-line-height
+--fk-typography-label-letter-spacing
+
+--fk-typography-code-font-family
+--fk-typography-code-font-size
+--fk-typography-code-font-weight
+--fk-typography-code-line-height
+--fk-typography-code-letter-spacing
+
+--fk-typography-gutter-bottom
+```
+
+### Font weight tokens
+
+```
+--fk-font-weight-normal
+--fk-font-weight-medium
+--fk-font-weight-semibold
+--fk-font-weight-bold
+```
+
+### Customizing Tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```scss
+:root {
+  --fk-text-color-default: #111827;
+  --fk-typography-body-font-size: 1rem;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.dark-theme fk-text {
+  --fk-text-color-default: #e2e8f0;
+  --fk-text-color-muted: #94a3b8;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When both `truncate` and `maxLines` are set, `maxLines` takes precedence for multi-line clamping.
+- Use semantic `as` values (`p`, `label`, etc.) appropriate for the content's role in the document.
+- `weight` overrides the variant's default font weight. When `null`, the variant's own weight applies.

package/directives/infinite-scroll/README.md

@@ -0,0 +1,102 @@
+# fkInfiniteScroll
+
+A sentinel-based infinite-scroll directive. Apply it to a small marker element at the bottom of a scrollable list — when that element enters the viewport the directive emits `(scrolled)`, which the parent uses to load the next page.
+
+Implemented with `IntersectionObserver` instead of scroll-event listening, so there's no debounce or throttle to tune and no work runs on every scroll frame.
+
+---
+
+## API
+
+### Inputs
+
+| Input        | Type     | Default | Description                                                                                            |
+| ------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `threshold`  | `number` | `0.1`   | Visibility ratio (0–1) at which the sentinel is considered intersecting. Default fires at 10% visible. |
+| `rootMargin` | `string` | `"0px"` | CSS-margin syntax that expands or shrinks the detection area (e.g. `"200px 0px"` to pre-fetch early).  |
+
+### Outputs
+
+| Output     | Type   | Description                                           |
+| ---------- | ------ | ----------------------------------------------------- |
+| `scrolled` | `void` | Fires every time the sentinel re-enters the viewport. |
+
+---
+
+## Features
+
+- Zero scroll-event work — `IntersectionObserver` runs off the main thread.
+- SSR-safe: setup is gated on `isPlatformBrowser`, so server render does nothing and the browser pass wires up after hydration.
+- Pre-fetch via `rootMargin` to load the next page before the user reaches the bottom.
+- Tear-down via `ngOnDestroy` disconnects the observer — safe to mount/unmount inside `@if`.
+
+---
+
+## Quick Start
+
+```html
+@for (item of items(); track item.id) {
+<div>{{ item.name }}</div>
+} @if (hasMore()) {
+<div fkInfiniteScroll (scrolled)="loadNextPage()">
+  @if (loading()) {
+  <fk-loader />
+  }
+</div>
+}
+```
+
+To stop firing, remove the sentinel from the DOM (set `hasMore()` to `false`).
+
+---
+
+## Import
+
+```ts
+import { FkInfiniteScrollDirective } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [FkInfiniteScrollDirective],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Examples
+
+### Pre-fetch before the user hits the bottom
+
+```html
+<div fkInfiniteScroll rootMargin="400px 0px" (scrolled)="loadNextPage()"></div>
+```
+
+A 400px bottom margin fires `scrolled` while the sentinel is still 400px below the viewport — enough headroom for the next page to land before the user notices.
+
+### Higher visibility threshold
+
+```html
+<div fkInfiniteScroll [threshold]="0.5" (scrolled)="loadNextPage()"></div>
+```
+
+Fire only when the sentinel is at least 50% in view.
+
+---
+
+## Accessibility
+
+The sentinel itself is non-interactive — it doesn't take focus, doesn't announce, and doesn't appear in the tab order. Place it inside the same scrollable container as the list so screen-reader users encountering the loader see it in the natural reading order.
+
+If the loader inside the sentinel is animated, respect `prefers-reduced-motion` in your loader component (the shared `fk-loader` already does).
+
+---
+
+## Behavior Notes
+
+- The directive sets up the observer in `ngAfterViewInit` and tears it down in `ngOnDestroy`. Re-mounting via `@if` resets the observer — there's no internal state to reset.
+- `scrolled` fires every time the sentinel re-enters the viewport, so the parent must guard against double-firing while a page is loading (typical pattern: track a `loading` signal and short-circuit `loadNextPage()` while it's `true`).
+- On SSR the directive does nothing — the observer only exists in the browser.

package/directives/spotlight/README.md

@@ -0,0 +1,154 @@
+# fkSpotlightTrigger / fkSpotlightTarget
+
+A pair of directives that coordinate a "spotlight" pulse across unrelated parts of the DOM. Apply `fkSpotlightTrigger="<key>"` to a hover/focus zone (e.g. an open-the-help-panel button); apply `fkSpotlightTarget="<key>"` to one or more elements that should pulse while the trigger is hovered/focused. Triggers and targets bound to the same key activate together.
+
+The directives talk through `SpotlightService`, which is reference-counted — a hover-driven trigger and a programmatic activation can hold the same key at the same time without one cancelling the other.
+
+---
+
+## API
+
+### `fkSpotlightTrigger`
+
+#### Inputs
+
+| Input                | Type     | Default  | Description                                                                           |
+| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------- |
+| `fkSpotlightTrigger` | `string` | required | Key broadcast on enter (mouseenter/focusin); released on leave (mouseleave/focusout). |
+
+#### Outputs
+
+None.
+
+### `fkSpotlightTarget`
+
+#### Inputs
+
+| Input               | Type                 | Default   | Description                                                                                  |
+| ------------------- | -------------------- | --------- | -------------------------------------------------------------------------------------------- |
+| `fkSpotlightTarget` | `string`             | required  | Key the target listens for. Multiple targets may share a key.                                |
+| `treatment`         | `SpotlightTreatment` | `"pulse"` | Visual treatment while active. `"pulse"` = animated ring, `"overlay"` = static tinted layer. |
+
+#### Outputs
+
+None.
+
+#### Types
+
+```ts
+type SpotlightTreatment = 'pulse' | 'overlay';
+```
+
+---
+
+## Features
+
+- Decoupled trigger ↔ target communication via `SpotlightService` — no `@Input`/`@Output` plumbing between unrelated components.
+- Reference-counted holders: a hover trigger and a programmatic one-shot can coexist; the key clears when the last holder releases.
+- Two visual treatments: `pulse` for compact action-anchored targets (buttons, list rows) and `overlay` for wide surfaces (panels, columns) where the pulse animation would feel busy.
+- Single global active key — last activation wins, which matches the "find this thing" onboarding use case (mutually exclusive cues).
+
+---
+
+## Quick Start
+
+```html
+<button [fkSpotlightTrigger]="'open-roadmap'">Open setup roadmap</button>
+
+<lib-button [fkSpotlightTarget]="'open-roadmap'">Setup</lib-button>
+```
+
+Hovering or focusing the trigger pulses every target sharing the same key.
+
+---
+
+## Import
+
+```ts
+import { SpotlightTriggerDirective, SpotlightTargetDirective, type SpotlightTreatment } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [SpotlightTriggerDirective, SpotlightTargetDirective],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Examples
+
+### Multiple targets per key
+
+```html
+<button [fkSpotlightTrigger]="'invite-flow'">Invite an admin</button>
+
+<a [fkSpotlightTarget]="'invite-flow'" routerLink="/users">Users</a>
+<button [fkSpotlightTarget]="'invite-flow'">+ Invite</button>
+```
+
+Both list-nav links and the invite button pulse together while the trigger is hovered, walking the user through a multi-step path.
+
+### Overlay treatment for wide surfaces
+
+```html
+<button [fkSpotlightTrigger]="'permissions-column'">Where do permissions appear?</button>
+
+<div class="dashboard-column" [fkSpotlightTarget]="'permissions-column'" treatment="overlay">...</div>
+```
+
+`treatment="overlay"` swaps the pulse ring for a static tinted overlay — much less busy on a column-wide surface.
+
+### Programmatic activation
+
+```ts
+constructor(private readonly spotlight: SpotlightService) {}
+
+ngAfterViewInit(): void {
+  // Auto-spotlight the setup roadmap on first open
+  this.spotlight.activate("open-roadmap");
+  setTimeout(() => this.spotlight.deactivate("open-roadmap"), 2000);
+}
+```
+
+A programmatic holder coexists with hover-driven triggers — the spotlight only clears once every holder releases.
+
+---
+
+## Accessibility
+
+- Triggers listen on both pointer and keyboard (`mouseenter`/`mouseleave` and `focusin`/`focusout`), so keyboard-only users get the same cue as pointer users.
+- Targets are non-focusable by default; the spotlight is a visual hint, not an interactive surface. The element underneath the target keeps its own keyboard semantics.
+- The `pulse` animation respects `prefers-reduced-motion` via the SCSS in `fk-spotlight-target` (no JavaScript-driven animation to gate).
+
+---
+
+## Design Tokens
+
+The treatments draw their colors and timing from these tokens:
+
+```scss
+--fk-spotlight-pulse-color
+--fk-spotlight-pulse-duration
+--fk-spotlight-overlay-color
+--fk-spotlight-overlay-fade-duration
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-spotlight-pulse-color: var(--fk-color-primary);
+}
+```
+
+---
+
+## Behavior Notes
+
+- The active key is single-valued: activating a different key while one is held replaces the active key (last write wins). The previous key's holders still count, so re-activating it later restores the spotlight.
+- `SpotlightService` is provided in root — there's a single coordinator across the whole app. Targets in any feature module pick up triggers in any other feature module, as long as the keys match.
+- The visual `.fk-spotlight-target--active` and `.fk-spotlight-target--overlay` classes are the directive's contract with the SCSS — overriding the tokens is the supported customization path; redefining the classes is not.

package/directives/tooltip/README.md

@@ -0,0 +1,147 @@
+# fkTooltip
+
+A token-driven tooltip directive for Angular. Applied as an attribute on any element to display informational text on hover, focus, or touch.
+
+---
+
+## API
+
+### Inputs
+
+| Input                | Type              | Default  | Description                            |
+| -------------------- | ----------------- | -------- | -------------------------------------- |
+| `fkTooltip`          | `string`          | required | Tooltip text content                   |
+| `fkTooltipPosition`  | `TooltipPosition` | `'top'`  | Preferred placement                    |
+| `fkTooltipOffset`    | `number`          | `8`      | Gap (px) between anchor and tooltip    |
+| `fkTooltipShowDelay` | `number`          | `200`    | Delay (ms) before showing              |
+| `fkTooltipHideDelay` | `number`          | `0`      | Delay (ms) before hiding               |
+| `fkTooltipDisabled`  | `boolean`         | `false`  | Suppresses tooltip                     |
+| `fkTooltipClassName` | `string`          | `''`     | Extra CSS class on the tooltip element |
+
+### Types
+
+```ts
+type TooltipPosition = 'top' | 'right' | 'bottom' | 'left';
+```
+
+---
+
+## Features
+
+- Attribute directive — works on any element
+- Automatic flip when near viewport edge
+- Shift along cross-axis to stay in viewport
+- Arrow indicator pointing at anchor
+- Show on hover and focus, hide on blur and Escape
+- Touch support with auto-hide
+- Configurable show/hide delays
+- Token-driven styling with two-tier fallbacks
+- `prefers-reduced-motion` disables animations
+
+---
+
+## Quick Start
+
+```html
+<button fkTooltip="Save changes">Save</button>
+```
+
+---
+
+## Import
+
+```ts
+import { TooltipDirective } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  imports: [TooltipDirective],
+})
+export class ExampleComponent {}
+```
+
+## Selector
+
+```html
+<any-element fkTooltip="text" />
+```
+
+---
+
+## Examples
+
+### On a Button
+
+```html
+<button fkTooltip="Save your changes" fkTooltipPosition="bottom">Save</button>
+```
+
+### On an Icon
+
+```html
+<fk-icon name="info" fkTooltip="This field is required" />
+```
+
+### With Custom Delay
+
+```html
+<button fkTooltip="Slow tooltip" [fkTooltipShowDelay]="500">Hover me</button>
+```
+
+### Disabled
+
+```html
+<button fkTooltip="Hidden tooltip" [fkTooltipDisabled]="true">No tooltip</button>
+```
+
+---
+
+## Accessibility
+
+- Tooltip element has `role="tooltip"` and a unique `id`
+- `aria-describedby` set on host when tooltip is visible, removed when hidden
+- Shows on `focusin`, hides on `focusout`
+- Hides on `Escape` key
+- Touch: shows on `touchstart`, auto-hides after 1500ms
+- `prefers-reduced-motion: reduce` disables all animations
+
+---
+
+## Design Tokens
+
+`fkTooltip` is styled entirely through design tokens.
+
+### Token Reference
+
+| Token                        | Default                          | Description          |
+| ---------------------------- | -------------------------------- | -------------------- |
+| `--fk-tooltip-bg`            | `var(--fk-color-text)`           | Background color     |
+| `--fk-tooltip-color`         | `var(--fk-color-surface)`        | Text color           |
+| `--fk-tooltip-font-size`     | `var(--fk-typography-caption-…)` | Font size            |
+| `--fk-tooltip-font-weight`   | `var(--fk-font-weight-medium)`   | Font weight          |
+| `--fk-tooltip-padding`       | `0.25rem 0.5rem`                 | Inner padding        |
+| `--fk-tooltip-border-radius` | `var(--fk-radius-sm)`            | Corner radius        |
+| `--fk-tooltip-shadow`        | `0 2px 8px rgba(0,0,0,0.15)`     | Box shadow           |
+| `--fk-tooltip-max-width`     | `20rem`                          | Maximum width        |
+| `--fk-tooltip-arrow-size`    | `6px`                            | Arrow indicator size |
+| `--fk-tooltip-z-index`       | `1100`                           | Stacking order       |
+
+### Customizing Tokens
+
+```css
+:root {
+  --fk-tooltip-bg: #1e293b;
+  --fk-tooltip-border-radius: 0.5rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Tooltip is appended to `document.body` to escape `overflow: hidden` ancestors
+- Uses `position: fixed` with `getBoundingClientRect()` for positioning
+- Flips to opposite side when insufficient space, then shifts along cross-axis
+- Arrow offset adjusts dynamically to always point at the anchor center
+- Repositions on scroll and resize while visible