@frame-kit/ui-ng 0.0.1

package/ui/sidenav-link/README.md

@@ -0,0 +1,214 @@
+# fk-sidenav-link
+
+A token-driven sidebar navigation link that renders an icon and label, automatically hiding the label when the parent `fk-app-shell` is collapsed.
+
+---
+
+## API
+
+### Inputs
+
+| Input      | Type                             | Default | Description                                                                    |
+| ---------- | -------------------------------- | ------- | ------------------------------------------------------------------------------ |
+| icon       | `string`                         | —       | **Required.** Icon name from the icon registry                                 |
+| iconSize   | `IconSize`                       | `"sm"`  | Size of the icon (`"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or custom CSS value) |
+| label      | `string`                         | —       | **Required.** Visible text label                                               |
+| routerLink | `string` \| `string[]` \| `null` | `null`  | Angular Router link — renders `<a>` when set                                   |
+| exact      | `boolean`                        | `false` | Use exact match for `routerLinkActive` highlighting                            |
+
+### Methods
+
+| Method    | Description                                                              |
+| --------- | ------------------------------------------------------------------------ |
+| dismiss() | Calls `dismissSidenav()` on the parent app-shell (closes mobile overlay) |
+
+### Computed (read-only)
+
+| Property    | Type              | Description                                        |
+| ----------- | ----------------- | -------------------------------------------------- |
+| isCollapsed | `Signal<boolean>` | Whether the parent app-shell is in collapsed state |
+
+---
+
+## Features
+
+- Renders `<a>` with `routerLink` when a route is provided, `<button>` otherwise
+- `routerLinkActive` class applied automatically for active route highlighting
+- Label hides when parent `fk-app-shell` is collapsed (icon-only rail)
+- Auto-dismisses mobile sidebar overlay on click
+- Works standalone (outside an app-shell) — collapse detection gracefully defaults to `false`
+- Token-driven styling with full override capability
+
+---
+
+## Quick Start
+
+```html
+<fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+```
+
+---
+
+## Import
+
+```ts
+import { SidenavLinkComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-sidebar',
+  imports: [SidenavLinkComponent],
+  templateUrl: './sidebar.component.html',
+})
+export class SidebarComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-sidenav-link />
+```
+
+---
+
+## Examples
+
+### With Router Link
+
+```html
+<fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+```
+
+### Button Mode (no route)
+
+Renders a `<button>` instead of `<a>`. Useful for actions like opening a dialog.
+
+```html
+<fk-sidenav-link icon="email" label="Notifications" />
+```
+
+### Nav List
+
+```html
+<nav style="display: flex; flex-direction: column; gap: 0.25rem;">
+  <fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+  <fk-sidenav-link icon="organization" label="Properties" />
+  <fk-sidenav-link icon="email" label="Notifications" />
+  <fk-sidenav-link icon="lock" label="Compliance" />
+  <fk-sidenav-link icon="shield-alert" label="Insurance" />
+</nav>
+```
+
+### Inside App Shell
+
+```html
+<fk-app-shell mode="icon">
+  <nav appShellSidenav>
+    <fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+    <fk-sidenav-link icon="organization" label="Properties" />
+    <fk-sidenav-link icon="email" label="Notifications" />
+  </nav>
+
+  <div appShellSidenavFooter>
+    <fk-sidenav-link icon="info" label="Help & Support" />
+  </div>
+
+  <div appShellContent>
+    <router-outlet />
+  </div>
+</fk-app-shell>
+```
+
+When the shell is collapsed, only icons are shown. When expanded, icons and labels are both visible.
+
+---
+
+## Accessibility
+
+- Renders a native `<a>` or `<button>` element — keyboard accessible by default
+- Supports Enter and Space through native element behavior
+- `focus-visible` ring applied via CSS token
+- `routerLinkActive` provides visual indication of the current route
+- When collapsed, the icon remains visible and the label is removed from the DOM (not just hidden)
+- When collapsed, the host carries `aria-label="<label>"` so screen readers still get a name for the link, and a tooltip appears to the right on hover or keyboard focus (via the `[fkTooltip]` directive). When expanded, the visible label text serves both purposes — `aria-label` is omitted and the tooltip is disabled.
+
+### Recommended
+
+Always register the icon before use:
+
+```ts
+provideIcons({
+  'chart-activity-fill': chartActivityFill,
+  organization,
+  email,
+});
+```
+
+---
+
+## Design Tokens
+
+### Component Tokens
+
+```
+--fk-sidenav-link-gap
+--fk-sidenav-link-padding-block
+--fk-sidenav-link-padding-inline
+--fk-sidenav-link-radius
+--fk-sidenav-link-bg
+--fk-sidenav-link-bg-hover
+--fk-sidenav-link-bg-active
+--fk-sidenav-link-font-family
+--fk-sidenav-link-font-size
+--fk-sidenav-link-font-weight-active
+--fk-sidenav-link-color
+--fk-sidenav-link-color-hover
+--fk-sidenav-link-color-active
+--fk-sidenav-link-focus-ring
+```
+
+Each component token falls back to a semantic token, then a raw value. For example:
+
+```
+--fk-sidenav-link-color → --fk-color-text → #1f2d3d
+--fk-sidenav-link-color-hover → --fk-color-primary → #0a84ff
+--fk-sidenav-link-color-active → --fk-color-primary → #0a84ff
+--fk-sidenav-link-radius → --fk-radius-md → 0.5rem
+--fk-sidenav-link-bg-hover → --fk-color-surface-dim → #edf1f5
+```
+
+### Customizing Tokens
+
+Override tokens at any scope:
+
+```css
+:root {
+  --fk-sidenav-link-color: #4338ca;
+  --fk-sidenav-link-bg-hover: #eef2ff;
+  --fk-sidenav-link-bg-active: #e0e7ff;
+  --fk-sidenav-link-font-weight-active: 700;
+  --fk-sidenav-link-radius: 0.25rem;
+}
+```
+
+Or scope to a specific context:
+
+```css
+.dark-theme fk-sidenav-link {
+  --fk-sidenav-link-color: #e2e8f0;
+  --fk-sidenav-link-bg-hover: #1e293b;
+  --fk-sidenav-link-bg-active: #334155;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When used inside `fk-app-shell`, the component injects the parent via `inject(AppShellComponent, { optional: true })` to read collapse state
+- When used outside an app-shell, `isCollapsed` is always `false` and labels are always visible
+- Clicking any link calls `dismissSidenav()` on the parent shell, which closes the mobile overlay
+- In collapsed state, the anchor centers its icon with `justify-content: center` and removes inline padding via the `.fk-app-shell--collapsed .fk-sidenav-link__anchor` rule

package/ui/tabs/README.md

@@ -0,0 +1,204 @@
+# fk-tabs
+
+A compound component system for building accessible, keyboard-navigable tabbed interfaces. Follows the [WAI-ARIA Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+
+---
+
+## API
+
+### `fk-tabs`
+
+Root container that provides shared state to all child tab components.
+
+| Input               | Type                                   | Default        | Description                                     |
+| ------------------- | -------------------------------------- | -------------- | ----------------------------------------------- |
+| `value`             | `string \| undefined`                  | `undefined`    | Controlled active tab value                     |
+| `defaultValue`      | `string \| undefined`                  | `undefined`    | Initial active tab (uncontrolled mode)          |
+| `variant`           | `'underline' \| 'pill' \| 'contained'` | `'underline'`  | Visual style of the tabs                        |
+| `size`              | `'sm' \| 'md' \| 'lg'`                 | `'md'`         | Size of tab labels                              |
+| `orientation`       | `'horizontal' \| 'vertical'`           | `'horizontal'` | Layout direction                                |
+| `activationMode`    | `'automatic' \| 'manual'`              | `'automatic'`  | Whether tabs activate on focus or require Enter |
+| `lazy`              | `boolean`                              | `false`        | Defer panel rendering until first activation    |
+| `keepMounted`       | `boolean`                              | `true`         | Keep lazy panels in DOM after deactivation      |
+| `stretch`           | `boolean`                              | `false`        | Stretch tabs to fill available width            |
+| `fullWidth`         | `boolean`                              | `false`        | Make the tab bar span full width                |
+| `scrollable`        | `boolean`                              | `false`        | Enable horizontal scrolling for overflow tabs   |
+| `showScrollButtons` | `boolean`                              | `false`        | Show prev/next scroll buttons                   |
+| `className`         | `string`                               | `''`           | Additional CSS classes                          |
+
+| Output        | Type               | Description                            |
+| ------------- | ------------------ | -------------------------------------- |
+| `valueChange` | `string`           | Emits new value when selection changes |
+| `tabChange`   | `FkTabChangeEvent` | Emits `{ previousValue, value }`       |
+| `tabClose`    | `FkTabCloseEvent`  | Emits `{ value }` when a tab is closed |
+
+### `fk-tab-list`
+
+Container for tab triggers. Applies `role="tablist"` and handles keyboard navigation.
+
+| Input       | Type             | Default | Description                       |
+| ----------- | ---------------- | ------- | --------------------------------- |
+| `ariaLabel` | `string \| null` | `null`  | Accessible label for the tab list |
+| `className` | `string`         | `''`    | Additional CSS classes            |
+
+### `fk-tab`
+
+Individual tab trigger. Applies `role="tab"` with full ARIA attributes.
+
+| Input       | Type                                          | Default     | Description                     |
+| ----------- | --------------------------------------------- | ----------- | ------------------------------- |
+| `value`     | `string` (required)                           | —           | Unique identifier for this tab  |
+| `disabled`  | `boolean`                                     | `false`     | Prevents selection              |
+| `closable`  | `boolean`                                     | `false`     | Shows a close button            |
+| `badge`     | `string \| number \| undefined`               | `undefined` | Badge content next to the label |
+| `icon`      | `TemplateRef<unknown> \| string \| undefined` | `undefined` | Icon before the label           |
+| `className` | `string`                                      | `''`        | Additional CSS classes          |
+
+### `fk-tab-panel`
+
+Content panel associated with a tab. Applies `role="tabpanel"`.
+
+| Input       | Type                | Default | Description                               |
+| ----------- | ------------------- | ------- | ----------------------------------------- |
+| `value`     | `string` (required) | —       | Must match a corresponding `fk-tab` value |
+| `className` | `string`            | `''`    | Additional CSS classes                    |
+
+---
+
+## Features
+
+- WAI-ARIA Tabs pattern with full keyboard support (arrow keys, Home/End, Enter/Space in manual mode)
+- Three visual variants: `underline` (default, with sliding indicator), `pill`, `contained`
+- Three sizes: `sm`, `md`, `lg`
+- Horizontal and vertical orientations
+- Automatic and manual activation modes
+- Lazy panel rendering with optional keep-mounted (state preservation across deactivation)
+- Closable tabs with `(tabClose)` event for dynamic tab strips
+- Optional badge and icon slots on each tab
+- Stretch / fullWidth / scrollable layouts for dense or overflow tab strips
+- Controlled and uncontrolled modes (bind `[value]` + `(valueChange)`, or pass `defaultValue`)
+- Auto-select fallback when the active tab is removed
+
+---
+
+## Quick Start
+
+```html
+<fk-tabs defaultValue="account">
+  <fk-tab-list>
+    <fk-tab value="account">Account</fk-tab>
+    <fk-tab value="documents">Documents</fk-tab>
+    <fk-tab value="settings">Settings</fk-tab>
+  </fk-tab-list>
+
+  <fk-tab-panel value="account">Account content</fk-tab-panel>
+  <fk-tab-panel value="documents">Documents content</fk-tab-panel>
+  <fk-tab-panel value="settings">Settings content</fk-tab-panel>
+</fk-tabs>
+```
+
+---
+
+## Import
+
+```ts
+import { FkTabsComponent, FkTabListComponent, FkTabComponent, FkTabPanelComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [FkTabsComponent, FkTabListComponent, FkTabComponent, FkTabPanelComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Examples
+
+### Controlled mode
+
+```html
+<fk-tabs [value]="activeTab()" (valueChange)="activeTab.set($event)">
+  <fk-tab-list>
+    <fk-tab value="a">A</fk-tab>
+    <fk-tab value="b">B</fk-tab>
+  </fk-tab-list>
+  <fk-tab-panel value="a">Panel A</fk-tab-panel>
+  <fk-tab-panel value="b">Panel B</fk-tab-panel>
+</fk-tabs>
+```
+
+### Closable tabs
+
+```html
+<fk-tabs (tabClose)="removeTab($event.value)">
+  <fk-tab-list>
+    @for (tab of tabs(); track tab.id) {
+    <fk-tab [value]="tab.id" [closable]="true">{{ tab.label }}</fk-tab>
+    }
+  </fk-tab-list>
+  @for (tab of tabs(); track tab.id) {
+  <fk-tab-panel [value]="tab.id">{{ tab.content }}</fk-tab-panel>
+  }
+</fk-tabs>
+```
+
+### Lazy rendering
+
+```html
+<fk-tabs defaultValue="first" [lazy]="true" [keepMounted]="true">
+  <fk-tab-list>
+    <fk-tab value="first">First</fk-tab>
+    <fk-tab value="second">Second</fk-tab>
+  </fk-tab-list>
+  <fk-tab-panel value="first">Rendered immediately</fk-tab-panel>
+  <fk-tab-panel value="second">Rendered on first activation, then kept alive</fk-tab-panel>
+</fk-tabs>
+```
+
+### Vertical orientation
+
+```html
+<fk-tabs defaultValue="a" orientation="vertical">
+  <div style="display: flex;">
+    <fk-tab-list>
+      <fk-tab value="a">Account</fk-tab>
+      <fk-tab value="b">Security</fk-tab>
+    </fk-tab-list>
+    <div>
+      <fk-tab-panel value="a">Account settings</fk-tab-panel>
+      <fk-tab-panel value="b">Security settings</fk-tab-panel>
+    </div>
+  </div>
+</fk-tabs>
+```
+
+---
+
+## Accessibility
+
+- `fk-tab-list` renders `role="tablist"` with `aria-orientation`
+- Each `fk-tab` renders `role="tab"` with `aria-selected`, `aria-controls`, `aria-disabled`, and roving `tabindex`
+- Each `fk-tab-panel` renders `role="tabpanel"` with `aria-labelledby` and `tabindex="0"`
+- Tab and panel IDs are auto-generated and cross-linked
+- Keyboard navigation: `ArrowLeft`/`ArrowRight` (horizontal), `ArrowUp`/`ArrowDown` (vertical), `Home`, `End`, `Enter`/`Space` (manual mode)
+- Disabled tabs are skipped during keyboard navigation
+
+---
+
+## Design Tokens
+
+Tab styling is driven by CSS custom properties scoped under the `.fk-tabs`, `.fk-tab-list`, `.fk-tab`, and `.fk-tab-panel` blocks. Override these in your theme to adjust colors, spacing, border radius, and indicator dimensions. The component responds to the global light/dark theme tokens from `@canopy/ui-shared`.
+
+---
+
+## Behavior Notes
+
+- **Uncontrolled mode** (default): Pass `defaultValue` and the component manages selection internally.
+- **Controlled mode**: Bind `[value]` and listen to `(valueChange)` to drive selection externally.
+- **Auto-select**: If no `value` or `defaultValue` is provided, the first non-disabled tab is selected automatically.
+- **Fallback**: When the active tab is removed, the first remaining enabled tab is selected.
+- **Indicator**: The underline variant renders a sliding indicator that tracks the active tab via DOM measurement.

package/ui/timeline/README.md

@@ -0,0 +1,285 @@
+# fk-timeline
+
+A token-driven timeline component for displaying ordered steps, resolution chains, audit trails, and workflow progress with status indicators and connectors.
+
+---
+
+## API
+
+### Inputs
+
+| Input         | Type                              | Default      | Description                                  |
+| ------------- | --------------------------------- | ------------ | -------------------------------------------- |
+| `items`       | `TimelineItemData[]`              | `[]`         | Declarative data for timeline entries        |
+| `orientation` | `'vertical' \| 'horizontal'`      | `'vertical'` | Layout direction                             |
+| `align`       | `'start' \| 'end' \| 'alternate'` | `'start'`    | Content alignment relative to connector line |
+| `size`        | `'sm' \| 'md' \| 'lg'`            | `'md'`       | Marker and connector sizing                  |
+| `reverse`     | `boolean`                         | `false`      | Reverse item order                           |
+| `ariaLabel`   | `string \| null`                  | `null`       | Accessible label                             |
+| `id`          | `string \| null`                  | `null`       | Element ID                                   |
+| `className`   | `string`                          | `''`         | Additional CSS classes merged onto the host  |
+
+### Types
+
+```ts
+interface TimelineItemData {
+  id?: string;
+  title?: string;
+  description?: string;
+  timestamp?: string;
+  icon?: string;
+  status?: TimelineItemStatus;
+}
+
+type TimelineItemStatus = 'default' | 'active' | 'completed' | 'error' | 'warning';
+type TimelineOrientation = 'vertical' | 'horizontal';
+type TimelineAlign = 'start' | 'end' | 'alternate';
+type TimelineSize = 'sm' | 'md' | 'lg';
+```
+
+### Outputs
+
+None.
+
+---
+
+## Features
+
+- Vertical and horizontal orientations
+- Three alignment modes (start, end, alternate)
+- Three size presets (sm, md, lg)
+- Five status variants (default, active, completed, error, warning)
+- Custom icon support per item
+- Optional timestamp display
+- Reversible item order
+- Content projection for complex custom items
+- Token-driven styling with two-tier fallbacks
+- Full ARIA list semantics
+- Dark mode support
+
+---
+
+## Quick Start
+
+```html
+<fk-timeline
+  [items]="[
+    { title: 'Step 1', status: 'completed' },
+    { title: 'Step 2', status: 'active' },
+    { title: 'Step 3', status: 'default' }
+  ]"
+></fk-timeline>
+```
+
+---
+
+## Import
+
+```ts
+import { TimelineComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [TimelineComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-timeline></fk-timeline>
+```
+
+---
+
+## Examples
+
+### Default (vertical, start-aligned)
+
+```html
+<fk-timeline [items]="items"></fk-timeline>
+```
+
+### Horizontal
+
+```html
+<fk-timeline [items]="items" orientation="horizontal"></fk-timeline>
+```
+
+### Alternate alignment
+
+```html
+<fk-timeline [items]="items" align="alternate"></fk-timeline>
+```
+
+### Sizes
+
+```html
+<fk-timeline [items]="items" size="sm"></fk-timeline>
+<fk-timeline [items]="items" size="md"></fk-timeline>
+<fk-timeline [items]="items" size="lg"></fk-timeline>
+```
+
+### All status variants
+
+```html
+<fk-timeline
+  [items]="[
+    { title: 'Done', status: 'completed' },
+    { title: 'Current', status: 'active' },
+    { title: 'Attention', status: 'warning' },
+    { title: 'Failed', status: 'error' },
+    { title: 'Pending', status: 'default' }
+  ]"
+></fk-timeline>
+```
+
+### With icons
+
+```html
+<fk-timeline
+  [items]="[
+    { title: 'Submitted', icon: 'circle-check-outline', status: 'completed' },
+    { title: 'In Review', icon: 'shield-alert', status: 'active' },
+    { title: 'Approved', icon: 'lock', status: 'default' }
+  ]"
+></fk-timeline>
+```
+
+### With timestamps
+
+```html
+<fk-timeline
+  [items]="[
+    { title: 'Created', timestamp: 'Jan 15', status: 'completed' },
+    { title: 'Updated', timestamp: 'Feb 1', status: 'active' }
+  ]"
+></fk-timeline>
+```
+
+### Reversed order
+
+```html
+<fk-timeline [items]="items" [reverse]="true"></fk-timeline>
+```
+
+### Content projection (advanced)
+
+```html
+<fk-timeline>
+  <ng-content />
+</fk-timeline>
+```
+
+---
+
+## Accessibility
+
+`fk-timeline` applies `role="list"` on the host element with `aria-orientation` reflecting the layout direction.
+
+Accessibility behavior:
+
+- `role="list"` on the timeline container
+- `role="listitem"` on each timeline item
+- `aria-orientation` reflects vertical or horizontal
+- Supports `ariaLabel` for additional context
+
+### Recommended
+
+```html
+<fk-timeline [items]="items" ariaLabel="Policy resolution chain"></fk-timeline>
+```
+
+---
+
+## Design Tokens
+
+`fk-timeline` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-timeline-gap
+--fk-timeline-item-gap
+--fk-timeline-marker-size-sm
+--fk-timeline-marker-size-md
+--fk-timeline-marker-size-lg
+--fk-timeline-marker-bg
+--fk-timeline-marker-border-color
+--fk-timeline-marker-border-width
+--fk-timeline-marker-color
+--fk-timeline-marker-active
+--fk-timeline-marker-completed
+--fk-timeline-marker-error
+--fk-timeline-marker-warning
+--fk-timeline-connector-width
+--fk-timeline-connector-color
+--fk-timeline-connector-length
+--fk-timeline-content-gap
+--fk-timeline-title-font-size
+--fk-timeline-title-font-weight
+--fk-timeline-title-color
+--fk-timeline-description-font-size
+--fk-timeline-description-color
+--fk-timeline-timestamp-font-size
+--fk-timeline-timestamp-color
+```
+
+### Shared tokens
+
+```
+--fk-color-primary
+--fk-color-success
+--fk-color-danger
+--fk-color-warning
+--fk-color-surface
+--fk-color-border
+--fk-color-text
+--fk-color-muted
+--fk-typography-body-font-size
+--fk-typography-small-font-size
+--fk-typography-caption-font-size
+--fk-font-weight-medium
+--fk-rhythm-1
+--fk-rhythm-2
+--fk-rhythm-3
+--fk-radius-md
+```
+
+### Customizing Tokens
+
+Override tokens in your application's stylesheet:
+
+```scss
+:root {
+  --fk-timeline-marker-size-md: 2rem;
+  --fk-timeline-connector-color: #e5e7eb;
+  --fk-timeline-marker-active: #6366f1;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.compact-timeline fk-timeline {
+  --fk-timeline-marker-size-md: 1rem;
+  --fk-timeline-item-gap: 0.5rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Horizontal timelines expand to fill the parent container width; wrap in a sized container to constrain
+- Vertical timelines take only the height of their content
+- The last item never renders a connector line
+- Alternate alignment uses CSS grid to keep the connector line centered
+- Icons must be registered via `provideIcons()` before use
+- Status variants control marker fill color; the default status renders as an outlined circle