@frame-kit/ui-ng 0.0.1

package/ui/avatar-stack/README.md

@@ -0,0 +1,164 @@
+# fk-avatar-stack
+
+A token-driven avatar stack molecule that displays a row of overlapping user avatars with an overflow badge for additional users.
+
+---
+
+## API
+
+### Inputs
+
+| Input        | Type                | Default | Description                                     |
+| ------------ | ------------------- | ------- | ----------------------------------------------- |
+| `users`      | `AvatarStackUser[]` | `[]`    | Array of users to display in the stack          |
+| `maxVisible` | `number`            | `5`     | Maximum number of avatars shown before overflow |
+| `size`       | `AvatarStackSize`   | `'sm'`  | Avatar size variant (`'sm'`, `'md'`, `'lg'`)    |
+| `className`  | `string`            | `''`    | Additional CSS classes for the host element     |
+| `id`         | `string \| null`    | `null`  | ID bound to the host element                    |
+| `ariaLabel`  | `string \| null`    | `null`  | `aria-label` bound to the host element          |
+
+### Outputs
+
+| Output          | Type              | Description                                |
+| --------------- | ----------------- | ------------------------------------------ |
+| `avatarClick`   | `AvatarStackUser` | Emitted when a visible avatar is clicked   |
+| `overflowClick` | `void`            | Emitted when the overflow badge is clicked |
+
+### AvatarStackUser
+
+```ts
+interface AvatarStackUser {
+  id: string;
+  name: string;
+  avatarUrl?: string | null;
+}
+```
+
+`AvatarStackSize` is an alias for `AvatarSize` (`'sm' | 'md' | 'lg'`).
+
+---
+
+## Features
+
+- Displays overlapping user avatars with configurable visibility limit
+- Overflow badge shows the count of hidden users (e.g. "+3")
+- Tooltip on each avatar shows the user's name
+- Tooltip on the overflow badge lists all hidden user names
+- Three size variants: `sm`, `md`, `lg`
+- Delegates avatar rendering to `fk-avatar` (supports images and initials fallback)
+- Token-driven styling for full theme customization
+
+---
+
+## Quick Start
+
+```html
+<fk-avatar-stack [users]="teamMembers" [maxVisible]="4" (avatarClick)="onUserClick($event)" (overflowClick)="showAllMembers()"></fk-avatar-stack>
+```
+
+```ts
+onUserClick(user: AvatarStackUser): void {
+  console.log("Clicked user:", user.name);
+}
+
+showAllMembers(): void {
+  // Open a dialog or panel showing all team members
+}
+```
+
+---
+
+## Import
+
+```ts
+import { AvatarStackComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [AvatarStackComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-avatar-stack></fk-avatar-stack>
+```
+
+---
+
+## Examples
+
+### Basic stack
+
+```html
+<fk-avatar-stack [users]="users" [maxVisible]="5"></fk-avatar-stack>
+```
+
+### Medium size with click handlers
+
+```html
+<fk-avatar-stack [users]="users" [maxVisible]="3" size="md" (avatarClick)="onUserClick($event)" (overflowClick)="showAll()"></fk-avatar-stack>
+```
+
+### Large size with custom aria-label
+
+```html
+<fk-avatar-stack [users]="users" size="lg" ariaLabel="Project team members"></fk-avatar-stack>
+```
+
+---
+
+## Accessibility
+
+- Each avatar item displays a tooltip with the user's name via `fkTooltip`
+- The overflow button uses `aria-label="Show all users"` for screen readers
+- The overflow button is a native `<button>` element, ensuring keyboard focus and activation
+- The host element supports `aria-label` binding for group-level labeling
+
+---
+
+## Design Tokens
+
+```scss
+/* Ring / border around avatars */
+--fk-avatar-stack-ring
+
+/* Overlap spacing between avatars */
+--fk-avatar-stack-overlap
+
+/* Overflow badge colors */
+--fk-avatar-stack-overflow-color
+--fk-avatar-stack-overflow-bg
+--fk-avatar-stack-overflow-bg-hover
+
+/* Overflow badge focus ring */
+--fk-avatar-stack-overflow-focus-ring
+
+/* Size-specific overflow badge font sizes */
+--fk-avatar-stack-overflow-font-size-sm
+--fk-avatar-stack-overflow-font-size-md
+--fk-avatar-stack-overflow-font-size-lg
+
+/* Avatar size tokens (shared with fk-avatar) */
+--fk-avatar-size-sm
+--fk-avatar-size-md
+--fk-avatar-size-lg
+```
+
+---
+
+## Behavior Notes
+
+- `visibleUsers` is computed as `users.slice(0, maxVisible)` -- only the first N users are rendered as avatars
+- `overflowCount` is `total - maxVisible` when there are more users than `maxVisible`, otherwise `0`
+- `overflowTooltip` joins the names of all hidden users with commas (e.g. "Frank Miller, Grace Lee, Hank Wilson")
+- The overflow badge is only rendered when `overflowCount > 0`
+- Avatar items have `cursor: pointer` and a `z-index` bump on hover for visual stacking feedback
+- The component uses `ChangeDetectionStrategy.OnPush` for optimal performance

package/ui/badge/README.md

@@ -0,0 +1,162 @@
+# fk-badge
+
+A small, token-driven label for secondary metadata such as statuses, counts, and tags.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type             | Default     | Description                                                                |
+| ----------------- | ---------------- | ----------- | -------------------------------------------------------------------------- |
+| `variant`         | `BadgeVariant`   | `"default"` | Visual style of the badge (e.g. `default`, `success`, `warning`, `danger`) |
+| `color`           | `string \| null` | `null`      | Overrides text color via inline `color` style                              |
+| `backgroundColor` | `string \| null` | `null`      | Overrides background color via inline `background-color` style             |
+| `borderColor`     | `string \| null` | `null`      | Optional border color (`1px solid {borderColor}`)                          |
+| `padding`         | `string \| null` | `null`      | Overrides full padding (e.g. `"2px 8px"`)                                  |
+| `paddingInline`   | `string \| null` | `null`      | Overrides horizontal padding only                                          |
+| `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 badge content alone is not sufficient                |
+
+### Content
+
+`fk-badge` projects its content:
+
+```html
+<fk-badge>New</fk-badge>
+```
+
+---
+
+## Features
+
+- Token-driven visual variants for statuses and labels
+- Compact, inline-friendly layout for chips, tags, and counters
+- Customizable colors and padding via inputs and design tokens
+- Works inside buttons, cards, tables, and lists
+- Simple content projection for arbitrary text or inline elements
+
+---
+
+## Quick Start
+
+```html
+<fk-badge>New</fk-badge>
+```
+
+```html
+<fk-badge variant="success">Active</fk-badge>
+```
+
+---
+
+## Import
+
+```ts
+import { BadgeComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [BadgeComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-badge></fk-badge>
+```
+
+---
+
+## Examples
+
+### Status badges
+
+```html
+<fk-badge variant="default">Draft</fk-badge>
+<fk-badge variant="success">Active</fk-badge>
+<fk-badge variant="warning">Pending</fk-badge>
+<fk-badge variant="danger">Overdue</fk-badge>
+```
+
+### With custom colors
+
+```html
+<fk-badge variant="default" color="#1f2933" backgroundColor="#e0f2fe" borderColor="#7fb4ff"> Beta </fk-badge>
+```
+
+### Inside other components
+
+```html
+<fk-text as="div" variant="body">
+  Order #1234
+  <fk-badge variant="success">Closed</fk-badge>
+</fk-text>
+```
+
+---
+
+## Accessibility
+
+- Renders as a semantic inline element (typically `span`) with visible text
+- `ariaLabel` can be used when the visual label is abbreviated or symbolic
+- Can be associated with other elements via `id` and `aria-describedby` on the target
+- Intended as supplementary information; do not use for critical messaging without text
+
+Recommended for abbreviations:
+
+```html
+<fk-badge ariaLabel="High priority">P1</fk-badge>
+```
+
+---
+
+## Design Tokens
+
+`fk-badge` is styled via badge-related design tokens and host classes such as
+`fk-badge` and `fk-badge--{variant}`.
+
+Example tokens (see the theme token files for the full contract):
+
+```scss
+--fk-badge-font-size;
+--fk-badge-font-weight;
+--fk-badge-radius;
+--fk-badge-padding-inline;
+
+--fk-badge-bg-default;
+--fk-badge-color-default;
+--fk-badge-border-color-default;
+
+--fk-badge-bg-success;
+--fk-badge-color-success;
+--fk-badge-border-color-success;
+```
+
+Override tokens in your app stylesheet:
+
+```scss
+:root {
+  --fk-badge-radius: 9999px;
+  --fk-badge-font-size: 11px;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When `borderColor` is provided, a `1px solid` border is applied automatically
+- `paddingInline` overrides only horizontal padding, allowing vertical spacing
+  to remain token-driven
+- Prefer using `variant` and tokens for consistent theming; fall back to `color`
+  and `backgroundColor` only for one-off customizations

package/ui/breadcrumb/README.md

@@ -0,0 +1,240 @@
+# fk-breadcrumb
+
+A generic, route-driven breadcrumb for page navigation. Consumers pass an
+ordered list of crumbs; the component renders each earlier crumb as a
+router-linked `<a>` (or plain text when no `routerLink` is provided) and
+the final crumb as the current location, marked with `aria-current="page"`.
+
+Use this for URL-path breadcrumbs (e.g. `Docs > API Reference > Get an
+organization`). For breadcrumbs that reflect a tree/hierarchy selection
+(e.g. org-node ancestry) use [`fk-node-tree-breadcrumb`](../node-tree-breadcrumb/README.md)
+instead.
+
+---
+
+## API
+
+### Inputs
+
+| Input       | Type                        | Default        | Description                                                    |
+| ----------- | --------------------------- | -------------- | -------------------------------------------------------------- |
+| `items`     | `readonly BreadcrumbItem[]` | _required_     | Ordered crumbs, first is root and last is the current location |
+| `ariaLabel` | `string`                    | `'Breadcrumb'` | Accessible label for the navigation landmark                   |
+| `className` | `string`                    | `''`           | Additional CSS classes merged onto the host element            |
+
+### Outputs
+
+None. Navigation happens via Angular's `routerLink` on each crumb's anchor.
+
+### Content Projection Slots
+
+| Slot                     | Kind                    | Description                                                                                                                     |
+| ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `#fkBreadcrumbSeparator` | `ng-template` reference | Optional custom separator instantiated once per gap between crumbs. Defaults to an inline chevron SVG shipped by the component. |
+
+```html
+<fk-breadcrumb [items]="crumbs">
+  <ng-template #fkBreadcrumbSeparator>
+    <span>/</span>
+  </ng-template>
+</fk-breadcrumb>
+```
+
+If the slot isn't populated, the library renders its own inline chevron —
+no consumer setup required.
+
+### `BreadcrumbItem`
+
+```ts
+interface BreadcrumbItem {
+  label: string;
+  routerLink?: string | any[];
+  icon?: string;
+}
+```
+
+- `label` — text shown for the crumb
+- `routerLink` — optional router command array or path. When present on a
+  non-terminal crumb, the crumb renders as an `<a [routerLink]>` anchor
+- `icon` — optional icon name (reserved for consumers; not rendered by the
+  component itself)
+
+---
+
+## Features
+
+- Route-driven navigation via Angular `routerLink`
+- Automatic current-location marking on the last crumb
+- Non-navigable ancestors supported (crumbs without `routerLink` render as
+  plain text)
+- Inline SVG chevron separators
+- Token-driven styling with two-tier fallbacks
+- Renders correctly with no theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-breadcrumb [items]="crumbs" />
+```
+
+```ts
+crumbs: BreadcrumbItem[] = [
+  { label: "Docs", routerLink: ["/docs"] },
+  { label: "Introduction" },
+];
+```
+
+---
+
+## Import
+
+```ts
+import { BreadcrumbComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [BreadcrumbComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-breadcrumb [items]="items" />
+```
+
+---
+
+## Examples
+
+### Two-level breadcrumb
+
+```html
+<fk-breadcrumb
+  [items]="[
+    { label: 'Docs', routerLink: ['/docs'] },
+    { label: 'Introduction' },
+  ]"
+/>
+```
+
+Renders: Docs > **Introduction**
+
+### Deep path
+
+```html
+<fk-breadcrumb
+  [items]="[
+    { label: 'Docs', routerLink: ['/docs'] },
+    { label: 'API Reference', routerLink: ['/docs/api-reference'] },
+    { label: 'Get an organization' },
+  ]"
+/>
+```
+
+Renders: Docs > API Reference > **Get an organization**
+
+### With a non-navigable ancestor
+
+```html
+<fk-breadcrumb
+  [items]="[
+    { label: 'Section' },
+    { label: 'Article', routerLink: ['/article'] },
+    { label: 'Current' },
+  ]"
+/>
+```
+
+`Section` renders as plain text (no `routerLink`), `Article` as a link,
+`Current` as the current-page span.
+
+### Custom aria-label
+
+```html
+<fk-breadcrumb [items]="crumbs" ariaLabel="Docs trail" />
+```
+
+---
+
+## Accessibility
+
+- Host element exposes `role="navigation"` and `aria-label="Breadcrumb"`
+  (customize with the `ariaLabel` input)
+- Rendered as an ordered list (`<ol>`) for semantic structure
+- The current (last) crumb is marked with `aria-current="page"`
+- Non-terminal crumbs with `routerLink` are `<a>` elements — Tab + Enter
+  navigates
+- Chevron separators are `aria-hidden="true"`
+- Focus ring uses `--fk-focus-ring`
+
+---
+
+## Design Tokens
+
+`fk-breadcrumb` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-breadcrumb-gap
+--fk-breadcrumb-font-size
+--fk-breadcrumb-link-color
+--fk-breadcrumb-link-color-hover
+--fk-breadcrumb-current-color
+--fk-breadcrumb-current-font-weight
+--fk-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-breadcrumb-font-size: 0.875rem;
+  --fk-breadcrumb-link-color: #475569;
+  --fk-breadcrumb-current-font-weight: 600;
+}
+```
+
+Or scope overrides to a specific surface:
+
+```scss
+ca-docs-shell {
+  --fk-breadcrumb-link-color: #94a3b8;
+  --fk-breadcrumb-current-color: #e2e8f0;
+}
+```
+
+---
+
+## Behavior Notes
+
+- When `items` is empty, the component renders an empty `<ol>` (no crumbs)
+- The last crumb is always rendered as the current-location span,
+  regardless of whether a `routerLink` is provided — this matches the
+  typical breadcrumb pattern where the final segment represents the page
+  the user is already on
+- `text-transform` is not applied by the component; consumers can apply it
+  externally via CSS