@frame-kit/ui-ng 0.0.1

package/ui/icon-list/README.md

@@ -0,0 +1,205 @@
+# fk-icon-list
+
+A token-driven list that pairs each row's label with an icon marker. Ships as a pair: `fk-icon-list` is the container, `fk-icon-list-item` is the renderable row — use either a data-driven `items` input, content projection with `<fk-icon-list-item>` children, or a standalone `<fk-icon-list-item>` outside any list.
+
+---
+
+## API
+
+### `fk-icon-list`
+
+#### Inputs
+
+| Input       | Type                              | Default     | Description                                                                                     |
+| ----------- | --------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| `items`     | `readonly IconListItem[] \| null` | `null`      | Data-driven rows. When `null`, the list projects `<fk-icon-list-item>` children instead         |
+| `icon`      | `string \| null`                  | `null`      | Default icon for rows that don't set their own                                                  |
+| `variant`   | `IconListVariant`                 | `"default"` | Default tone inherited by items: `"default"`, `"primary"`, `"success"`, `"warning"`, `"danger"` |
+| `size`      | `IconListSize`                    | `"md"`      | Default size inherited by items: `"sm"`, `"md"`, `"lg"`                                         |
+| `className` | `string`                          | `''`        | Additional CSS classes merged onto the host element                                             |
+| `id`        | `string \| null`                  | `null`      | Optional ID applied to the inner `role="list"` container                                        |
+| `ariaLabel` | `string \| null`                  | `null`      | Accessible label on the inner `role="list"` container                                           |
+
+### `fk-icon-list-item`
+
+#### Inputs
+
+| Input       | Type                      | Default | Description                                                   |
+| ----------- | ------------------------- | ------- | ------------------------------------------------------------- |
+| `icon`      | `string \| null`          | `null`  | Per-item icon name. Falls through to the parent list's `icon` |
+| `variant`   | `IconListVariant \| null` | `null`  | Per-item tone override. Falls through to the parent list      |
+| `size`      | `IconListSize \| null`    | `null`  | Per-item size override. Falls through to the parent list      |
+| `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 label alone is insufficient         |
+
+#### Content
+
+`fk-icon-list-item` projects its label content:
+
+```html
+<fk-icon-list-item icon="check">Your label here</fk-icon-list-item>
+```
+
+### Outputs
+
+None on either component.
+
+---
+
+## Features
+
+- Three usage modes — data-driven (`items` input), content-projection (`<fk-icon-list-item>` children), and standalone items outside a list
+- Items inherit the list's `icon`, `variant`, and `size` via element-injector DI; any input on the item overrides the parent
+- Token-driven icon colors (default / primary / success / warning / danger)
+- Three size steps that scale both label typography and icon size
+- Semantic `role="list"` / `role="listitem"` pairing; item roles are only advertised when inside an `fk-icon-list` container, so standalone items don't announce orphan list semantics
+
+---
+
+## Quick Start
+
+Data-driven:
+
+```html
+<fk-icon-list [items]="items" icon="check" variant="success" />
+```
+
+```ts
+readonly items = [
+  { label: "Hierarchical RBAC" },
+  { label: "Organization modeling" },
+  { label: "Permission inheritance" },
+];
+```
+
+Content-projection:
+
+```html
+<fk-icon-list icon="check" variant="primary">
+  <fk-icon-list-item>Admin</fk-icon-list-item>
+  <fk-icon-list-item>Manager</fk-icon-list-item>
+  <fk-icon-list-item>Viewer</fk-icon-list-item>
+</fk-icon-list>
+```
+
+Manual loop:
+
+```html
+<fk-icon-list variant="success">
+  @for (role of roles; track $index) {
+  <fk-icon-list-item [icon]="role.icon">{{ role.label }}</fk-icon-list-item>
+  }
+</fk-icon-list>
+```
+
+Standalone:
+
+```html
+<fk-icon-list-item icon="check" variant="success"> One-off note without a list wrapper </fk-icon-list-item>
+```
+
+---
+
+## Import
+
+```ts
+import { IconListComponent, IconListItemComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [IconListComponent, IconListItemComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selectors
+
+```html
+<fk-icon-list></fk-icon-list> <fk-icon-list-item></fk-icon-list-item>
+```
+
+---
+
+## Examples
+
+### Uniform marker with data-driven items
+
+```html
+<fk-icon-list [items]="items" icon="check" variant="primary" />
+```
+
+### Per-item icons and tone overrides
+
+```html
+<fk-icon-list variant="success" icon="check">
+  <fk-icon-list-item icon="shield-check">Secured endpoints</fk-icon-list-item>
+  <fk-icon-list-item icon="circle-check-outline" variant="primary"> Verified identities </fk-icon-list-item>
+  <fk-icon-list-item variant="danger">Flagged for review</fk-icon-list-item>
+</fk-icon-list>
+```
+
+### Sizing
+
+```html
+<fk-icon-list [items]="items" icon="check" size="sm" />
+<fk-icon-list [items]="items" icon="check" size="md" />
+<fk-icon-list [items]="items" icon="check" size="lg" />
+```
+
+---
+
+## Accessibility
+
+- `fk-icon-list` renders `<div role="list">` so list semantics survive the `list-style: none` reset (Safari otherwise strips the implicit list role).
+- `fk-icon-list-item` sets `role="listitem"` only when nested inside an `fk-icon-list` — this avoids announcing orphan list items when the component is used standalone.
+- Each `fk-icon` child is decorative (`aria-hidden="true"`) — the projected label is the assistive-tech readable content.
+- Set `ariaLabel` on the list when the surrounding context doesn't already name the collection.
+
+---
+
+## Design Tokens
+
+```scss
+/* Container */
+--fk-icon-list-margin-top;
+--fk-icon-list-row-gap;
+
+/* Item */
+--fk-icon-list-item-gap;
+--fk-icon-list-item-label-color;
+--fk-icon-list-item-line-height;
+
+--fk-icon-list-item-sm-font-size;
+--fk-icon-list-item-md-font-size;
+--fk-icon-list-item-lg-font-size;
+
+--fk-icon-list-item-default-color;
+--fk-icon-list-item-primary-color;
+--fk-icon-list-item-success-color;
+--fk-icon-list-item-warning-color;
+--fk-icon-list-item-danger-color;
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-icon-list-row-gap: 0.75rem;
+  --fk-icon-list-item-primary-color: var(--fk-color-primary-hover);
+}
+```
+
+---
+
+## Behavior Notes
+
+- Data-driven mode internally renders `fk-icon-list-item` per row, so the DOM is identical whether you use `[items]` or content projection.
+- If neither a list-level nor per-item icon is set, the icon slot is skipped — label-only rows still render cleanly.
+- Icon color is applied via CSS `color` cascade onto `fk-icon`, whose SVG paths use `currentColor` — no per-icon `color` prop needed.
+- Item `variant` / `size` inputs accept `null` (the default) to mean "inherit from parent"; pass a concrete value to override.

package/ui/inline-edit/README.md

@@ -0,0 +1,135 @@
+# fk-inline-edit
+
+A click-to-edit component that toggles between a display value and an inline text input with save/cancel actions.
+
+---
+
+## API
+
+### Inputs
+
+| Input         | Type             | Default            | Description                          |
+| ------------- | ---------------- | ------------------ | ------------------------------------ |
+| `value`       | `string`         | `''`               | The current display value            |
+| `placeholder` | `string`         | `'Enter a value…'` | Placeholder text shown in the input  |
+| `size`        | `InlineEditSize` | `'md'`             | Size variant (`sm`, `md`, `lg`)      |
+| `emptyText`   | `string`         | `'None'`           | Text shown when `value` is empty     |
+| `disabled`    | `boolean`        | `false`            | Disables editing                     |
+| `ariaLabel`   | `string \| null` | `null`             | ARIA label for the input and trigger |
+| `className`   | `string`         | `''`               | Additional CSS classes               |
+| `id`          | `string \| null` | `null`             | Optional ID for the host             |
+
+### Outputs
+
+| Output        | Type     | Description                            |
+| ------------- | -------- | -------------------------------------- |
+| `valueChange` | `string` | Emitted with the trimmed value on save |
+| `editStart`   | `void`   | Emitted when entering edit mode        |
+| `editCancel`  | `void`   | Emitted when editing is cancelled      |
+
+### Content Slots
+
+| Slot            | Selector       | Description                                        |
+| --------------- | -------------- | -------------------------------------------------- |
+| **Edit icon**   | `[editIcon]`   | Custom icon for the edit trigger (replaces "Edit") |
+| **Save icon**   | `[saveIcon]`   | Custom content for the save button                 |
+| **Cancel icon** | `[cancelIcon]` | Custom content for the cancel button               |
+
+---
+
+## Features
+
+- Click-to-edit with display/edit mode toggle
+- Enter to save, Escape to cancel
+- Auto-focuses input on edit start
+- Size variants for different contexts (headings, body text, captions)
+- Content slots for custom icons on trigger and action buttons
+- Disabled state hides the edit trigger
+
+---
+
+## Quick Start
+
+```html
+<fk-inline-edit [value]="roleName" placeholder="Enter role name" size="lg" ariaLabel="Role name" (valueChange)="onNameChange($event)" />
+```
+
+### With custom icons
+
+```html
+<fk-inline-edit [value]="description" (valueChange)="onDescChange($event)">
+  <fk-icon editIcon name="pen-outline" size="sm" />
+</fk-inline-edit>
+```
+
+---
+
+## Import
+
+```ts
+import { InlineEditComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [InlineEditComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-inline-edit></fk-inline-edit>
+```
+
+---
+
+## Accessibility
+
+- Input receives focus automatically on edit start
+- Enter key saves, Escape key cancels
+- Edit trigger has `aria-label` derived from the `ariaLabel` input
+- Focus ring uses `--fk-focus-ring` token
+
+---
+
+## Design Tokens
+
+```scss
+// Layout
+--fk-inline-edit-gap
+
+// Input
+--fk-inline-edit-input-padding
+--fk-inline-edit-input-bg
+--fk-inline-edit-border-color
+--fk-inline-edit-border-radius
+--fk-inline-edit-focus-border
+--fk-inline-edit-focus-ring
+
+// Typography
+--fk-inline-edit-font-size
+--fk-inline-edit-font-weight
+--fk-inline-edit-color
+--fk-inline-edit-empty-color
+--fk-inline-edit-action-font-size
+
+// Large variant
+--fk-inline-edit-lg-font-size
+--fk-inline-edit-lg-font-weight
+
+// Trigger
+--fk-inline-edit-trigger-color
+--fk-inline-edit-trigger-hover-color
+
+// Actions
+--fk-inline-edit-save-bg
+--fk-inline-edit-save-color
+--fk-inline-edit-cancel-bg
+--fk-inline-edit-cancel-color
+```

package/ui/list-editor/README.md

@@ -0,0 +1,162 @@
+# fk-list-editor
+
+A token-driven list editor for building ordered string lists with add, remove, inline edit, and drag-to-reorder.
+
+## API
+
+### Inputs
+
+| Input          | Type             | Default                 | Description                                        |
+| -------------- | ---------------- | ----------------------- | -------------------------------------------------- |
+| `items`        | `string[]`       | `[]`                    | Two-way bound list of items (model)                |
+| `placeholder`  | `string`         | `"Add an item..."`      | Placeholder for the add input                      |
+| `emptyMessage` | `string`         | `"No items added yet."` | Message shown when the list is empty               |
+| `addLabel`     | `string`         | `"Add"`                 | Label for the add button                           |
+| `orderable`    | `boolean`        | `true`                  | Enable drag-to-reorder                             |
+| `showOrder`    | `boolean`        | `true`                  | Show numbered order badges                         |
+| `size`         | `ListEditorSize` | `"md"`                  | Size variant (`"sm"` or `"md"`)                    |
+| `lockedItems`  | `string[]`       | `[]`                    | Items that cannot be edited or removed (lowercase) |
+| `className`    | `string`         | `""`                    | Additional CSS classes on host                     |
+| `disabled`     | `boolean`        | `false`                 | Disables all interaction                           |
+| `ariaLabel`    | `string \| null` | `null`                  | Accessible label for the list container            |
+
+### Outputs
+
+| Output        | Type                              | Description                          |
+| ------------- | --------------------------------- | ------------------------------------ |
+| `itemsChange` | `string[]`                        | Emitted when the items array changes |
+| `itemAdded`   | `string`                          | Emitted when a new item is added     |
+| `itemRemoved` | `{ item: string; index: number }` | Emitted when an item is removed      |
+
+### Content
+
+`fk-list-editor` does not use content projection. All configuration is via inputs.
+
+## Features
+
+- Add items via text input with Enter key or button click
+- Remove items with the remove button
+- Inline edit existing items
+- Drag-to-reorder with CDK drag-drop
+- Duplicate detection with error message
+- Lock specific items from editing or removal
+- Configurable order badges, placeholder, and labels
+- Two size variants (sm, md)
+- Full keyboard support
+
+## Quick Start
+
+```html
+<fk-list-editor [(items)]="roles" placeholder="e.g. Admin, Editor, Viewer" addLabel="Add Role" />
+```
+
+## Import
+
+```ts
+import { ListEditorComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [ListEditorComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+## Selector
+
+```html
+<fk-list-editor />
+```
+
+## Examples
+
+### Basic role editor
+
+```html
+<fk-list-editor [(items)]="roleNames" placeholder="e.g. Admin, Editor, Viewer" addLabel="Add Role" emptyMessage="No roles defined. Add your first role." />
+```
+
+### Non-orderable list
+
+```html
+<fk-list-editor [(items)]="tags" [orderable]="false" [showOrder]="false" placeholder="Add a tag..." addLabel="Add Tag" />
+```
+
+### With locked items
+
+```html
+<fk-list-editor [(items)]="levels" [lockedItems]="inUseLevels" placeholder="Add a level..." addLabel="Add Level" />
+```
+
+## Accessibility
+
+- The list container supports `ariaLabel` for screen readers
+- Drag handles are keyboard accessible via CDK drag-drop
+- Remove buttons include descriptive `title` attributes
+- Disabled state prevents all interaction and applies `pointer-events: none`
+- Focus ring uses the shared `--fk-focus-ring` token
+
+## Design Tokens
+
+```scss
+--fk-list-editor-row-gap
+--fk-list-editor-item-padding
+--fk-list-editor-item-bg
+--fk-list-editor-item-border-color
+--fk-list-editor-item-radius
+--fk-list-editor-item-hover-shadow
+--fk-list-editor-handle-padding
+--fk-list-editor-order-size
+--fk-list-editor-order-radius
+--fk-list-editor-order-bg
+--fk-list-editor-order-color
+--fk-list-editor-order-font-size
+--fk-list-editor-order-font-weight
+--fk-list-editor-input-padding
+--fk-list-editor-input-border-color
+--fk-list-editor-input-radius
+--fk-list-editor-input-font-size
+--fk-list-editor-input-color
+--fk-list-editor-input-bg
+--fk-list-editor-input-focus-border-color
+--fk-list-editor-remove-color
+--fk-list-editor-remove-hover-color
+--fk-list-editor-remove-padding
+--fk-list-editor-add-clear-reserve
+--fk-list-editor-add-clear-offset
+--fk-list-editor-add-clear-padding
+--fk-list-editor-add-clear-radius
+--fk-list-editor-focus-ring
+--fk-list-editor-placeholder-height
+--fk-list-editor-placeholder-border-color
+--fk-list-editor-placeholder-bg
+--fk-list-editor-empty-padding
+--fk-list-editor-empty-color
+--fk-list-editor-empty-font-size
+--fk-list-editor-add-gap
+--fk-list-editor-error-gap
+--fk-list-editor-error-color
+--fk-list-editor-error-font-size
+--fk-list-editor-disabled-opacity
+--fk-list-editor-drag-shadow
+--fk-list-editor-drag-border-color
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-list-editor-item-radius: 0.75rem;
+  --fk-list-editor-order-bg: #f0f0f0;
+}
+```
+
+## Behavior Notes
+
+- Duplicate detection is case-insensitive
+- Pressing Enter in the add input triggers `addItem()`
+- Locked items are matched case-insensitively against the `lockedItems` input
+- The component uses Angular CDK drag-drop; `@angular/cdk` must be available

package/ui/loader/README.md

@@ -0,0 +1,160 @@
+# fk-loader
+
+A lightweight loading spinner component with token-driven styling and zero external dependencies.
+
+---
+
+## API
+
+### Inputs
+
+| Input       | Type             | Default     | Description                                                                   |
+| ----------- | ---------------- | ----------- | ----------------------------------------------------------------------------- |
+| `size`      | `LoaderSize`     | `"md"`      | Visual size of the loader (`xs`, `sm`, `md`, `lg`, `xl`)                      |
+| `color`     | `LoaderColor`    | `"inherit"` | Color variant (`inherit`, `default`, `muted`, `primary`, `danger`, `success`) |
+| `className` | `string`         | `''`        | Additional CSS classes merged onto the host element                           |
+| `id`        | `string \| null` | `null`      | Optional ID for the loader element                                            |
+| `ariaLabel` | `string`         | `"Loading"` | Accessible label describing what is loading                                   |
+
+### Content Slots
+
+| Slot            | Selector         | Description                                            |
+| --------------- | ---------------- | ------------------------------------------------------ |
+| **Custom icon** | `[fkLoaderIcon]` | Custom spinner icon, replaces the built-in default SVG |
+
+### Outputs
+
+`fk-loader` does not emit outputs; it is purely presentational.
+
+---
+
+## Features
+
+- Built-in inline SVG spinner — no icon registry dependency
+- Optional custom icon via `[fkLoaderIcon]` content projection
+- Size and color variants mapped to design tokens
+- Can be embedded inline inside buttons, cards, and other components
+- Accessible status indicator with `role="status"` and `aria-label`
+
+---
+
+## Quick Start
+
+```html
+<!-- Uses built-in spinner, no setup needed -->
+<fk-loader />
+
+<!-- With a custom icon from the consumer app -->
+<fk-loader size="sm">
+  <fk-icon fkLoaderIcon name="my-spinner" size="sm" />
+</fk-loader>
+```
+
+---
+
+## Import
+
+```ts
+import { LoaderComponent } from '@frame-kit/ui-ng';
+
+// Only needed if using custom icon slot:
+import { FkLoaderIconDirective } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [LoaderComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-loader></fk-loader>
+```
+
+---
+
+## Examples
+
+### Sizes
+
+```html
+<fk-loader size="xs" />
+<fk-loader size="sm" />
+<fk-loader size="md" />
+<fk-loader size="lg" />
+<fk-loader size="xl" />
+```
+
+### Color variants
+
+```html
+<fk-loader color="default" />
+<fk-loader color="primary" />
+<fk-loader color="muted" />
+<fk-loader color="danger" />
+<fk-loader color="success" />
+```
+
+### Custom icon
+
+```html
+<fk-loader size="md">
+  <fk-icon fkLoaderIcon name="my-custom-spinner" size="sm" />
+</fk-loader>
+```
+
+---
+
+## Accessibility
+
+- Uses `role="status"` on the host element
+- `aria-label` describes the loading action (e.g. `"Loading"`, `"Saving"`)
+- Should typically be paired with visible text for users who do not rely on assistive tech
+
+---
+
+## Design Tokens
+
+```scss
+// Animation
+--fk-loader-animation-duration
+
+// Sizes (fallback chain: component token → semantic token → raw value)
+--fk-loader-size-xs   // → --fk-font-size-xs → 0.75rem
+--fk-loader-size-sm   // → --fk-font-size-sm → 1rem
+--fk-loader-size-md   // → --fk-font-size-md → 1.25rem
+--fk-loader-size-lg   // → --fk-font-size-lg → 1.5rem
+--fk-loader-size-xl   // → --fk-font-size-xl → 2rem
+
+// Colors (uses shared icon color tokens)
+--fk-icon-color-default   // → --fk-color-text → #1f2d3d
+--fk-icon-color-primary   // → --fk-color-primary → #0a84ff
+--fk-icon-color-muted     // → --fk-color-muted → #8a98a8
+--fk-icon-color-danger    // → --fk-color-danger → #e02424
+--fk-icon-color-success   // → --fk-color-success → #10b981
+```
+
+### Customizing Tokens
+
+```css
+:root {
+  --fk-loader-size-md: 1.5rem;
+  --fk-loader-animation-duration: 1.2s;
+}
+```
+
+---
+
+## Behavior Notes
+
+- The built-in SVG spinner renders automatically when no `[fkLoaderIcon]` content is projected
+- When a custom icon is provided via `[fkLoaderIcon]`, the built-in SVG is hidden
+- Use `inherit` for `color` when you want the loader to follow the surrounding text color
+- The spinner animation is a simple CSS rotation, controlled by `--fk-loader-animation-duration`