@frame-kit/ui-ng 0.0.1

package/ui/node-tree/README.md

@@ -0,0 +1,278 @@
+# fk-node-tree
+
+A token-driven, hierarchical tree component for Angular with expand/collapse, selection, drag-and-drop reparenting, position-aware sibling insertion, consumer drop validation, and custom row templates.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                     | Default     | Description                                                         |
+| ----------------- | ------------------------ | ----------- | ------------------------------------------------------------------- |
+| `nodes`           | `TreeNode[]`             | _required_  | Flat array of tree nodes; parent-child relationships via `parentId` |
+| `selectedNodeId`  | `string \| undefined`    | `undefined` | Currently selected node ID                                          |
+| `expandedNodeIds` | `string[] \| undefined`  | `undefined` | Controlled expanded state; `undefined` uses internal state          |
+| `draggable`       | `boolean`                | `false`     | Enables drag-and-drop with drag handles                             |
+| `canDrop`         | `CanDropFn \| undefined` | `undefined` | Consumer callback to validate drop targets                          |
+| `className`       | `string`                 | `''`        | Additional CSS classes for the host                                 |
+
+### Outputs
+
+| Output       | Type              | Description                                     |
+| ------------ | ----------------- | ----------------------------------------------- |
+| `nodeSelect` | `TreeNode`        | Emitted when a row is clicked                   |
+| `nodeExpand` | `NodeExpandEvent` | Emitted when a node is expanded or collapsed    |
+| `nodeDrop`   | `NodeDropEvent`   | Emitted when a valid drag-and-drop is completed |
+
+### Types
+
+```ts
+interface TreeNode<T = unknown> {
+  id: string;
+  label: string;
+  icon?: string;
+  parentId?: string | null;
+  draggable?: boolean;
+  data?: T;
+}
+
+interface NodeExpandEvent {
+  nodeId: string;
+  expanded: boolean;
+}
+
+type DropPosition = 'before' | 'inside' | 'after';
+
+interface NodeDropEvent {
+  nodeId: string;
+  newParentId: string | null;
+  previousParentId: string | null;
+  position: DropPosition;
+  referenceNodeId: string;
+}
+
+type CanDropFn = (draggedNode: FlatNode, targetNode: FlatNode, position: DropPosition) => boolean;
+```
+
+### Content Projection
+
+Custom row templates use the `fkNodeTreeRow` structural directive:
+
+```html
+<fk-node-tree [nodes]="nodes">
+  <ng-template fkNodeTreeRow let-node>
+    <fk-icon [name]="node.icon" size="sm" />
+    <span>{{ node.label }}</span>
+  </ng-template>
+</fk-node-tree>
+```
+
+---
+
+## Features
+
+- Hierarchical tree rendering from flat node array
+- Expand/collapse (uncontrolled and controlled)
+- Row selection
+- Drag-and-drop reparenting via drag handle
+- Position-aware drops (before, inside, after)
+- Consumer drop validation via `canDrop` callback
+- Auto-expand on hover during drag
+- Custom row templates
+- Token-driven styling with dark mode support
+- Accessible (role=tree, treeitem, aria-level, aria-expanded, aria-selected)
+
+---
+
+## Quick Start
+
+```html
+<fk-node-tree [nodes]="nodes" [selectedNodeId]="selectedId" (nodeSelect)="onSelect($event)" (nodeExpand)="onExpand($event)" />
+```
+
+---
+
+## Import
+
+```ts
+import { FkNodeTreeComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-org-tree',
+  imports: [FkNodeTreeComponent],
+  templateUrl: './org-tree.component.html',
+})
+export class OrgTreeComponent {
+  nodes: TreeNode[] = [
+    { id: 'root', label: 'Acme Realty', parentId: null },
+    { id: 'west', label: 'West Region', parentId: 'root' },
+    { id: 'east', label: 'East Region', parentId: 'root' },
+  ];
+}
+```
+
+---
+
+## Selector
+
+```html
+<fk-node-tree></fk-node-tree>
+```
+
+---
+
+## Examples
+
+### Basic tree
+
+```html
+<fk-node-tree [nodes]="nodes" [selectedNodeId]="selectedId" (nodeSelect)="onSelect($event)" (nodeExpand)="onExpand($event)" />
+```
+
+### Controlled expand
+
+```html
+<fk-node-tree [nodes]="nodes" [expandedNodeIds]="expandedIds" (nodeExpand)="onExpand($event)" />
+```
+
+When `expandedNodeIds` is provided, the tree delegates expand/collapse state to the consumer.
+
+### Drag and drop
+
+```html
+<fk-node-tree [nodes]="nodes" [draggable]="true" (nodeDrop)="onDrop($event)" />
+```
+
+When `draggable` is true, each row with `draggable !== false` shows a grip handle. Dragging to the top 25% of a row triggers a `'before'` drop, the middle 50% triggers `'inside'`, and the bottom 25% triggers `'after'`.
+
+### Drop validation
+
+```ts
+canDrop: CanDropFn = (dragged, target, position) => {
+  // Block agents from being dropped into regions
+  if (dragged.id.startsWith('agent-') && target.id.startsWith('region-')) {
+    return false;
+  }
+  return true;
+};
+```
+
+```html
+<fk-node-tree [nodes]="nodes" [draggable]="true" [canDrop]="canDrop" (nodeDrop)="onDrop($event)" />
+```
+
+When `canDrop` returns `false`, the drop target is not highlighted and the drop is blocked.
+
+### Custom row template
+
+```html
+<fk-node-tree [nodes]="nodes">
+  <ng-template fkNodeTreeRow let-node>
+    @if (node.icon) {
+    <fk-icon [name]="node.icon" size="sm" />
+    }
+    <span style="font-weight: 500;">{{ node.label }}</span>
+    <span style="margin-left: auto; font-size: 0.75rem;">Level {{ node.level }}</span>
+  </ng-template>
+</fk-node-tree>
+```
+
+### Locked nodes
+
+Set `draggable: false` on individual `TreeNode` entries to prevent them from being dragged while keeping the rest of the tree draggable.
+
+```ts
+nodes = [
+  { id: 'root', label: 'Root', parentId: null, draggable: false },
+  { id: 'child', label: 'Child', parentId: 'root' },
+];
+```
+
+---
+
+## Accessibility
+
+- Host element has `role="tree"`
+- Each row has `role="treeitem"` with `aria-level` (1-based), `aria-expanded`, and `aria-selected`
+- All rows are keyboard-focusable (`tabindex="0"`)
+- Expand/collapse toggle has `aria-label` ("Expand" / "Collapse")
+- Drag handle SVG is `aria-hidden="true"`
+- Focus ring uses the `--fk-focus-ring` token
+
+---
+
+## Design Tokens
+
+`fk-node-tree` uses the following design tokens:
+
+```scss
+// Row layout
+--fk-node-tree-row-gap
+--fk-node-tree-row-padding
+--fk-node-tree-row-radius
+--fk-node-tree-row-color
+--fk-node-tree-row-font-size
+
+// Hover & selection
+--fk-node-tree-row-bg-hover
+--fk-node-tree-row-bg-selected
+--fk-node-tree-row-color-selected
+--fk-node-tree-row-font-weight-selected
+
+// Toggle chevron
+--fk-node-tree-row-toggle-color
+--fk-node-tree-row-toggle-color-hover
+--fk-node-tree-row-toggle-bg-hover
+
+// Drag handle
+--fk-node-tree-row-handle-color
+--fk-node-tree-row-handle-color-hover
+
+// Drop target
+--fk-node-tree-row-bg-drop-target
+--fk-node-tree-row-border-drop-target
+--fk-node-tree-row-drag-source-opacity
+
+// Drag preview & placeholder
+--fk-node-tree-drag-preview-bg
+--fk-node-tree-drag-preview-shadow
+--fk-node-tree-drag-placeholder-bg
+```
+
+### Customizing Tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```css
+:root {
+  --fk-node-tree-row-bg-selected: #ede9fe;
+  --fk-node-tree-row-color-selected: #7c3aed;
+  --fk-node-tree-row-border-drop-target: #7c3aed;
+}
+```
+
+Or scope overrides to a specific context:
+
+```css
+.dark-theme fk-node-tree {
+  --fk-node-tree-row-color: #e2e8f0;
+  --fk-node-tree-row-bg-hover: #1e293b;
+  --fk-node-tree-row-bg-selected: rgba(99, 102, 241, 0.15);
+  --fk-node-tree-row-handle-color: #64748b;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Nodes are provided as a flat array. Parent-child relationships are derived from `parentId`.
+- Nodes with `parentId: null` or `parentId: undefined` are treated as root nodes.
+- When `expandedNodeIds` is provided, the tree operates in controlled mode and will not manage expand state internally.
+- Self-drops and drops onto descendants are blocked automatically.
+- The `canDrop` callback is invoked during drag movement, not at drop time, so invalid targets never highlight.
+- Auto-expand during drag (800ms hover delay) only triggers for the `'inside'` drop position.
+- The drag handle (`cdkDragHandle`) restricts drag initiation to the grip icon, allowing normal click interactions on the rest of the row.

package/ui/node-tree-breadcrumb/README.md

@@ -0,0 +1,164 @@
+# fk-node-tree-breadcrumb
+
+A token-driven breadcrumb that displays the ancestry path from root to a
+selected node in a tree hierarchy. Paired with `fk-node-tree` — consume a
+flat `TreeNode[]` array plus a selected node id and render the path as
+clickable ancestor buttons terminating in the current node.
+
+Use this when the breadcrumb reflects a tree/hierarchy selection. For
+route-driven crumbs (e.g. URL segments), use a route-based breadcrumb
+instead — this component does not consume routes.
+
+---
+
+## API
+
+### Inputs
+
+| Input            | Type                  | Default     | Description                                         |
+| ---------------- | --------------------- | ----------- | --------------------------------------------------- |
+| `nodes`          | `TreeNode[]`          | _required_  | Flat array of tree nodes with `parentId` references |
+| `selectedNodeId` | `string \| undefined` | `undefined` | ID of the currently selected node                   |
+| `className`      | `string`              | `''`        | Additional CSS classes merged onto the host element |
+
+### Outputs
+
+| Output       | Type                     | Description                                  |
+| ------------ | ------------------------ | -------------------------------------------- |
+| `nodeSelect` | `NodeTreeBreadcrumbItem` | Emits when an ancestor breadcrumb is clicked |
+
+---
+
+## Features
+
+- Computes full ancestry path from root to selected node
+- Ancestor crumbs are clickable buttons; current node is a non-interactive span
+- Inline SVG chevron separators
+- Token-driven styling with two-tier fallbacks
+- Self-sufficient rendering without any theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-node-tree-breadcrumb [nodes]="nodes()" [selectedNodeId]="selectedNodeId()" (nodeSelect)="onNodeSelect($event)" />
+```
+
+---
+
+## Import
+
+```ts
+import { NodeTreeBreadcrumbComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [NodeTreeBreadcrumbComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-node-tree-breadcrumb></fk-node-tree-breadcrumb>
+```
+
+---
+
+## Examples
+
+### Root node selected
+
+```html
+<fk-node-tree-breadcrumb [nodes]="nodes" selectedNodeId="org-1" />
+```
+
+Renders: **Acme Realty**
+
+### Deep node selected
+
+```html
+<fk-node-tree-breadcrumb [nodes]="nodes" selectedNodeId="office-1" />
+```
+
+Renders: Acme Realty > West Region > **Downtown Office**
+
+---
+
+## Accessibility
+
+`fk-node-tree-breadcrumb` renders a `<nav>` element with proper ARIA attributes.
+
+Accessibility behavior:
+
+- Host has `role="navigation"` and `aria-label="Breadcrumb"`
+- Rendered as an ordered list (`<ol>`) for semantic structure
+- Ancestor crumbs are `<button>` elements for keyboard interaction
+- Current (last) crumb has `aria-current="location"`
+- Chevron separators are marked `aria-hidden="true"`
+
+---
+
+## Design Tokens
+
+`fk-node-tree-breadcrumb` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-node-tree-breadcrumb-gap
+--fk-node-tree-breadcrumb-font-size
+--fk-node-tree-breadcrumb-link-color
+--fk-node-tree-breadcrumb-link-color-hover
+--fk-node-tree-breadcrumb-current-color
+--fk-node-tree-breadcrumb-current-font-weight
+--fk-node-tree-breadcrumb-separator-color
+```
+
+### Shared tokens
+
+```
+--fk-rhythm-1
+--fk-typography-caption-font-size
+--fk-font-weight-medium
+--fk-color-muted
+--fk-color-text
+--fk-focus-ring
+--fk-radius-sm
+```
+
+### Customizing Tokens
+
+Override tokens in your application's stylesheet:
+
+```scss
+:root {
+  --fk-node-tree-breadcrumb-font-size: 0.875rem;
+  --fk-node-tree-breadcrumb-link-color: #475569;
+  --fk-node-tree-breadcrumb-current-font-weight: 600;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.dark-theme fk-node-tree-breadcrumb {
+  --fk-node-tree-breadcrumb-link-color: #94a3b8;
+  --fk-node-tree-breadcrumb-current-color: #e2e8f0;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Returns an empty list when `selectedNodeId` is `undefined` or does not match any node
+- The `NodeTreeBreadcrumbItem` type includes `id`, `label`, and optional `icon` fields (icon is not rendered by the breadcrumb but is available for consumers)
+- `text-transform` is not applied by the component; consumers can apply it externally via CSS

package/ui/note/README.md

@@ -0,0 +1,146 @@
+# fk-note
+
+A lightweight, token-driven inline callout that draws attention to a line of prose with a colored left rail — no box chrome, no background, no border radius.
+
+---
+
+## API
+
+### Inputs
+
+| Input       | Type             | Default  | Description                                                           |
+| ----------- | ---------------- | -------- | --------------------------------------------------------------------- |
+| `variant`   | `NoteVariant`    | `"info"` | Accent tone: `"info"`, `"success"`, `"warning"`, or `"danger"`        |
+| `italic`    | `boolean`        | `false`  | Render the note's text in italic style                                |
+| `className` | `string`         | `''`     | Additional CSS classes merged onto the host element                   |
+| `id`        | `string \| null` | `null`   | Optional ID applied to the host element                               |
+| `ariaLabel` | `string \| null` | `null`   | Accessible label when the note's visual content alone is insufficient |
+
+### Outputs
+
+None.
+
+### Content
+
+`fk-note` projects its content:
+
+```html
+<fk-note>Permissions inherit through the hierarchy.</fk-note>
+```
+
+---
+
+## Features
+
+- Left-rail accent in info / success / warning / danger tones
+- No box chrome — sits inline with surrounding prose
+- Fully token-driven accent colors, border width, and padding
+- Works with any inline or block content (text, links, code)
+- Renders correctly without any theme file via two-tier fallbacks
+
+---
+
+## Quick Start
+
+```html
+<fk-note>Your first request is ready to send.</fk-note>
+```
+
+```html
+<fk-note variant="warning"> API keys are shown only once. Copy yours before leaving this screen. </fk-note>
+```
+
+---
+
+## Import
+
+```ts
+import { NoteComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [NoteComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-note></fk-note>
+```
+
+---
+
+## Examples
+
+### Tone variants
+
+```html
+<fk-note variant="info">Neutral attention marker.</fk-note>
+<fk-note variant="success">Positive confirmation.</fk-note>
+<fk-note variant="warning">Caveat or caution.</fk-note>
+<fk-note variant="danger">Destructive or irreversible action.</fk-note>
+```
+
+### With rich inline content
+
+```html
+<fk-note variant="info"> Use the <code>X-API-Key</code> header for server-to-server requests. <a href="/docs/api-reference">Learn more</a>. </fk-note>
+```
+
+### Custom accessible label
+
+```html
+<fk-note variant="warning" ariaLabel="Deprecation notice"> This endpoint will be removed in v2. </fk-note>
+```
+
+---
+
+## Accessibility
+
+- Renders as a plain block container; content inside is read in source order
+- Use `ariaLabel` when the note conveys meaning beyond its visible text (e.g. "Deprecation notice", "Security warning")
+- For a note that announces dynamic updates, wrap it in a parent `role="status"` or `role="alert"` element — `fk-note` itself stays presentation-only
+- Color alone is never the sole signal; pair the variant with clear wording so screen-reader users get the same cue
+
+---
+
+## Design Tokens
+
+```scss
+--fk-note-border-width;
+--fk-note-padding-block;
+--fk-note-padding-inline-start;
+--fk-note-color;
+--fk-note-font-size;
+--fk-note-line-height;
+
+--fk-note-info-accent;
+--fk-note-success-accent;
+--fk-note-warning-accent;
+--fk-note-danger-accent;
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-note-border-width: 4px;
+  --fk-note-padding-inline-start: 1.25rem;
+  --fk-note-info-accent: var(--fk-color-primary-hover);
+}
+```
+
+---
+
+## Behavior Notes
+
+- The left rail uses `border-inline-start` so it automatically flips for RTL languages
+- Vertical rhythm above and below is the caller's responsibility — `fk-note` does not carry its own margin. Use utility classes (`.fk-mt-4`, etc.) or parent `gap` for spacing
+- Accent tokens resolve to `--fk-color-primary / success / warning / danger` by default, so dark mode is picked up from the semantic color layer without per-note overrides