@frame-kit/ui-ng 0.0.1

package/ui/dropdown-menu/README.md

@@ -0,0 +1,336 @@
+# fk-dropdown-menu
+
+A compound dropdown menu component that orchestrates a trigger, floating panel, and projected menu items using Angular content projection.
+
+---
+
+## API
+
+### fk-dropdown-menu
+
+#### Inputs
+
+| Input        | Type                               | Default        | Description                                                                                                                                                                                                             |
+| ------------ | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `placement`  | `'bottom-start'` \| `'bottom-end'` | `'bottom-end'` | Horizontal alignment of the panel                                                                                                                                                                                       |
+| `disabled`   | `boolean`                          | `false`        | Disables opening the menu                                                                                                                                                                                               |
+| `portal`     | `boolean`                          | `false`        | When true, the panel is teleported to `document.body` and positioned with `position: fixed`. Use this when the menu lives inside an ancestor with `overflow: hidden` (e.g. an app sidebar) that would otherwise clip it |
+| `panelClass` | `string \| null`                   | `null`         | Extra CSS class applied to the floating panel element. Useful for instance-specific overrides when the panel is portaled                                                                                                |
+| `ariaLabel`  | `string \| null`                   | `null`         | ARIA label for the menu panel                                                                                                                                                                                           |
+| `className`  | `string`                           | `''`           | Additional CSS classes for the host                                                                                                                                                                                     |
+| `id`         | `string \| null`                   | `null`         | Optional ID for the host                                                                                                                                                                                                |
+
+#### Outputs
+
+| Output      | Type   | Description                  |
+| ----------- | ------ | ---------------------------- |
+| `menuOpen`  | `void` | Emitted when the menu opens  |
+| `menuClose` | `void` | Emitted when the menu closes |
+
+#### Methods
+
+| Method     | Description                     |
+| ---------- | ------------------------------- |
+| `open()`   | Programmatically open the menu  |
+| `close()`  | Programmatically close the menu |
+| `toggle()` | Toggle the menu open/closed     |
+
+#### Content Slots
+
+| Slot        | Selector              | Description                                         |
+| ----------- | --------------------- | --------------------------------------------------- |
+| **Trigger** | `[fkDropdownTrigger]` | The element that opens the menu on click/keyboard   |
+| **Panel**   | `[fkDropdownPanel]`   | An `<ng-template>` containing the menu item content |
+
+### fkDropdownTrigger (directive)
+
+Applied to the element that toggles the menu. Sets `aria-haspopup="menu"` and manages `aria-expanded` automatically.
+
+### fkDropdownPanel (directive)
+
+Applied to an `<ng-template>` that contains menu items. The template is rendered inside a positioned panel only when the menu is open.
+
+### fk-menu-item
+
+| Input      | Type             | Default | Description                               |
+| ---------- | ---------------- | ------- | ----------------------------------------- |
+| `icon`     | `string \| null` | `null`  | Optional icon name shown before the label |
+| `danger`   | `boolean`        | `false` | Applies destructive/danger styling        |
+| `disabled` | `boolean`        | `false` | Disables the item                         |
+
+| Output      | Type   | Description                        |
+| ----------- | ------ | ---------------------------------- |
+| `itemClick` | `void` | Emitted when the item is activated |
+
+The item label is provided through content projection.
+
+### fk-menu-separator
+
+A visual divider between menu item groups. No inputs or outputs.
+
+---
+
+## Features
+
+- Compound component architecture (trigger, panel, items composed independently)
+- Viewport-aware panel positioning with automatic flip/shift
+- Full keyboard navigation (ArrowDown/Up, Home, End, Escape, Tab)
+- Outside click detection
+- Auto-close on item selection
+- Disabled state for entire menu or individual items
+- Danger variant for destructive actions
+- Token-driven styling
+- Accessible by default
+
+---
+
+## Quick Start
+
+```html
+<fk-dropdown-menu>
+  <button fkDropdownTrigger>Actions</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item icon="eye">View</fk-menu-item>
+    <fk-menu-item icon="gear-outline">Settings</fk-menu-item>
+    <fk-menu-separator />
+    <fk-menu-item icon="open-rect-arrow-out-fill" [danger]="true">Delete</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+---
+
+## Import
+
+```ts
+import { DropdownMenuComponent, DropdownTriggerDirective, DropdownPanelDirective, MenuItemComponent, MenuSeparatorComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [DropdownMenuComponent, DropdownTriggerDirective, DropdownPanelDirective, MenuItemComponent, MenuSeparatorComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selectors
+
+```html
+<fk-dropdown-menu></fk-dropdown-menu>
+<fk-menu-item></fk-menu-item>
+<fk-menu-separator></fk-menu-separator>
+```
+
+Directives:
+
+```html
+<button fkDropdownTrigger>...</button> <ng-template fkDropdownPanel>...</ng-template>
+```
+
+---
+
+## Examples
+
+### Bottom-start placement
+
+```html
+<fk-dropdown-menu placement="bottom-start">
+  <button fkDropdownTrigger>Options</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item>Copy</fk-menu-item>
+    <fk-menu-item>Paste</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### With disabled items
+
+```html
+<fk-dropdown-menu>
+  <button fkDropdownTrigger>Options</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item icon="eye">View</fk-menu-item>
+    <fk-menu-item icon="gear-outline" [disabled]="true">Settings (locked)</fk-menu-item>
+    <fk-menu-separator />
+    <fk-menu-item icon="info">Help</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### Danger items
+
+```html
+<fk-dropdown-menu>
+  <button fkDropdownTrigger>Manage</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item icon="eye">View</fk-menu-item>
+    <fk-menu-separator />
+    <fk-menu-item icon="open-rect-arrow-out-fill" [danger]="true">Remove</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### Disabled menu
+
+```html
+<fk-dropdown-menu [disabled]="true">
+  <button fkDropdownTrigger>Disabled</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item>This won't show</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### Inside an `overflow: hidden` ancestor (sidebar, drawer, scroll container)
+
+When the dropdown sits inside a container that clips its overflow — most commonly the app-shell sidebar or a drawer — the inline-positioned panel gets cut off. Set `[portal]="true"` to teleport the panel to `document.body` and position it with `position: fixed` using viewport coordinates. The trigger stays in place; only the floating panel relocates.
+
+```html
+<fk-dropdown-menu placement="bottom-start" [portal]="true">
+  <button fkDropdownTrigger>Switch workspace</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item>Production</fk-menu-item>
+    <fk-menu-item>Staging</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### Custom trigger (kebab menu)
+
+Any focusable element can serve as the trigger:
+
+```html
+<fk-dropdown-menu>
+  <span fkDropdownTrigger tabindex="0" role="button">&#8942;</span>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item>Edit</fk-menu-item>
+    <fk-menu-item [danger]="true">Delete</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+### Handling item clicks
+
+```html
+<fk-dropdown-menu>
+  <button fkDropdownTrigger>Actions</button>
+  <ng-template fkDropdownPanel>
+    <fk-menu-item (itemClick)="onView()">View</fk-menu-item>
+    <fk-menu-item (itemClick)="onEdit()">Edit</fk-menu-item>
+    <fk-menu-separator />
+    <fk-menu-item (itemClick)="onDelete()" [danger]="true">Delete</fk-menu-item>
+  </ng-template>
+</fk-dropdown-menu>
+```
+
+The menu automatically closes when any non-disabled item is clicked.
+
+---
+
+## Accessibility
+
+- Trigger receives `aria-haspopup="menu"` and `aria-expanded` automatically via the `fkDropdownTrigger` directive
+- Panel uses `role="menu"` with optional `aria-label`
+- Items use `role="menuitem"` with `tabindex="-1"` for roving focus
+- Disabled items receive `aria-disabled="true"` and are excluded from keyboard navigation
+- Separators use `role="separator"`
+
+### Keyboard behavior
+
+| Key       | Context   | Action                              |
+| --------- | --------- | ----------------------------------- |
+| Enter     | Trigger   | Toggle menu                         |
+| Space     | Trigger   | Toggle menu                         |
+| ArrowDown | Trigger   | Open menu and focus first item      |
+| ArrowDown | Menu open | Move focus to next item             |
+| ArrowUp   | Menu open | Move focus to previous item         |
+| Home      | Menu open | Move focus to first item            |
+| End       | Menu open | Move focus to last item             |
+| Escape    | Menu open | Close menu, return focus to trigger |
+| Tab       | Menu open | Close menu                          |
+| Enter     | Menu item | Activate item                       |
+| Space     | Menu item | Activate item                       |
+
+---
+
+## Design Tokens
+
+### Panel tokens
+
+```
+--fk-dropdown-menu-panel-z
+--fk-dropdown-menu-panel-min-width
+--fk-dropdown-menu-panel-padding
+--fk-dropdown-menu-panel-radius
+--fk-dropdown-menu-panel-bg
+--fk-dropdown-menu-panel-border
+--fk-dropdown-menu-panel-shadow
+--fk-dropdown-menu-enter-duration
+--fk-dropdown-menu-enter-easing
+```
+
+### Menu item tokens
+
+```
+--fk-menu-item-gap
+--fk-menu-item-padding
+--fk-menu-item-radius
+--fk-menu-item-font-family
+--fk-menu-item-font-size
+--fk-menu-item-color
+--fk-menu-item-bg-hover
+--fk-menu-item-focus-ring
+--fk-menu-item-opacity-disabled
+--fk-menu-item-transition-duration
+--fk-menu-item-transition-easing
+--fk-menu-item-danger-color
+--fk-menu-item-danger-bg-hover
+```
+
+### Separator tokens
+
+```
+--fk-menu-separator-color
+```
+
+### Customizing tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```css
+:root {
+  --fk-dropdown-menu-panel-radius: 0.25rem;
+  --fk-menu-item-bg-hover: #f5f3ff;
+  --fk-menu-item-danger-color: #dc2626;
+}
+```
+
+Or scope overrides to a specific instance:
+
+```html
+<div
+  style="
+  --fk-dropdown-menu-panel-bg: #fefce8;
+  --fk-dropdown-menu-panel-border: #ca8a04;
+  --fk-menu-item-bg-hover: #fef9c3;
+"
+>
+  <fk-dropdown-menu>
+    <!-- ... -->
+  </fk-dropdown-menu>
+</div>
+```
+
+---
+
+## Behavior Notes
+
+- The panel is positioned absolutely relative to the host and flips vertically when there is not enough space below
+- Horizontal placement shifts the panel to stay within the viewport
+- Clicking outside the menu or pressing Tab closes it
+- Items dispatch a custom `fkmenuitemselect` event that bubbles up, triggering auto-close at the panel level
+- `fk-menu-item` and `fk-menu-separator` are standalone atom components that can be reused in other menu-like contexts (e.g., context menus)

package/ui/editable-field/README.md

@@ -0,0 +1,171 @@
+# fk-editable-field
+
+A bordered single-line text field that switches between a display read-out and a live editable input, with the affordance icon (pencil → cancel) anchored _inside_ the trailing edge. Built for form-shaped surfaces (billing details, profile pages) where every row should _look_ like a regular form input even when it's not being edited.
+
+## API
+
+### Inputs
+
+| Input             | Type                | Default            | Description                                                                   |
+| ----------------- | ------------------- | ------------------ | ----------------------------------------------------------------------------- |
+| `value`           | `string`            | `""`               | Current committed value shown in display mode.                                |
+| `placeholder`     | `string`            | `"Enter a value…"` | Placeholder shown inside the input when the edit buffer is empty.             |
+| `size`            | `EditableFieldSize` | `"md"`             | `"sm" \| "md" \| "lg"` — font + spacing scale.                                |
+| `emptyText`       | `string`            | `"None"`           | Text rendered in display mode when `value` is empty.                          |
+| `className`       | `string`            | `""`               | Additional CSS classes merged onto the host.                                  |
+| `id`              | `string \| null`    | `null`             | Optional `id` forwarded to the host element.                                  |
+| `ariaLabel`       | `string \| null`    | `null`             | Accessible label. In display mode the rendered label is `"Edit {ariaLabel}"`. |
+| `ariaDescribedBy` | `string \| null`    | `null`             | `aria-describedby` forwarded onto the field surface.                          |
+| `disabled`        | `boolean`           | `false`            | When `true`, the field is read-only and the pencil affordance is hidden.      |
+
+### Outputs
+
+| Output        | Type                   | Description                                               |
+| ------------- | ---------------------- | --------------------------------------------------------- |
+| `valueChange` | `EventEmitter<string>` | Fires on save with the trimmed value the user typed.      |
+| `editStart`   | `EventEmitter<void>`   | Fires when the component enters edit mode.                |
+| `editCancel`  | `EventEmitter<void>`   | Fires when the user cancels without saving (X or Escape). |
+
+### Content
+
+Three optional named slots — each accepts any markup, typically an `<fk-icon>`:
+
+| Slot           | When it renders                                                     |
+| -------------- | ------------------------------------------------------------------- |
+| `[editIcon]`   | Display mode, replaces the default pencil.                          |
+| `[cancelIcon]` | Edit mode, replaces the default `circleXmarkOutline`.               |
+| `[saveIcon]`   | Edit mode, replaces the default `"Save"` text on the action button. |
+
+```html
+<fk-editable-field [value]="name" (valueChange)="onSave($event)">
+  <fk-icon editIcon name="pen-outline" size="sm" />
+  <fk-icon cancelIcon name="circle-xmark-outline" size="sm" />
+</fk-editable-field>
+```
+
+### Types
+
+```ts
+export type EditableFieldSize = 'sm' | 'md' | 'lg';
+```
+
+## Features
+
+- Display mode reads as a full bordered input — no visual jump when the user enters edit mode.
+- Affordance icon (pencil) sits inside the trailing edge, replaced by a cancel (✗) icon while editing.
+- A single Save button slides in as a sibling on the right only while editing.
+- Save commits via Enter or Save button; cancel via Escape or the trailing X.
+- Focus ring spans the whole bordered shell, including the trailing slot.
+- Custom edit / cancel / save icons via named content slots.
+- Six exposed component tokens for typography, padding, colors, and the focus ring.
+
+## Quick Start
+
+```html
+<fk-editable-field [value]="billingName" ariaLabel="Billing name" (valueChange)="saveBillingName($event)" />
+```
+
+## Import
+
+```ts
+import { EditableFieldComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-billing-details',
+  standalone: true,
+  imports: [EditableFieldComponent],
+  templateUrl: './billing-details.component.html',
+})
+export class BillingDetailsComponent {}
+```
+
+## Selector
+
+```
+<fk-editable-field />
+```
+
+## Examples
+
+### A row in a form-shaped card
+
+```html
+<div class="row">
+  <span class="label">Billing name</span>
+  <fk-editable-field [value]="name()" (valueChange)="onSaveName($event)" />
+</div>
+```
+
+### Empty / placeholder state
+
+```html
+<fk-editable-field [value]="line2 ?? ''" emptyText="Not set" placeholder="Apt / suite / care-of" (valueChange)="onSaveLine2($event)" />
+```
+
+### Disabled (read-only)
+
+```html
+<fk-editable-field value="locked@acme.test" [disabled]="true" />
+```
+
+### Custom icons
+
+```html
+<fk-editable-field [value]="city" (valueChange)="onSaveCity($event)">
+  <fk-icon editIcon name="pen-outline" size="sm" />
+</fk-editable-field>
+```
+
+## Accessibility
+
+- The display surface is a real `<button>` so it's reachable via Tab and activatable with Enter or Space.
+- `ariaLabel` is forwarded to the display button as `"Edit {ariaLabel}"` so screen-reader users hear the intent without an extra hidden label.
+- The trailing cancel button in edit mode carries `aria-label="Cancel"`; the Save button carries `aria-label="Save"`.
+- Keyboard: Enter commits the edit, Escape cancels.
+- Focus ring is owned by the bordered shell (via `:focus-within` in edit mode) so it spans the full visual field including the trailing slot.
+- When `disabled`, the display surface is a disabled `<button>` and the pencil slot is removed entirely so the row reads as static text.
+
+## Design Tokens
+
+```scss
+--fk-editable-field-bg
+--fk-editable-field-border-color
+--fk-editable-field-border-radius
+--fk-editable-field-focus-border
+--fk-editable-field-hover-border
+--fk-editable-field-color
+--fk-editable-field-empty-color
+--fk-editable-field-font-size
+--fk-editable-field-sm-font-size
+--fk-editable-field-lg-font-size
+--fk-editable-field-lg-font-weight
+--fk-editable-field-input-padding
+--fk-editable-field-trailing-padding
+--fk-editable-field-gap
+--fk-editable-field-trigger-color
+--fk-editable-field-trigger-hover-color
+--fk-editable-field-inline-btn-size
+--fk-editable-field-save-bg
+--fk-editable-field-save-color
+--fk-editable-field-action-font-size
+--fk-editable-field-disabled-opacity
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-editable-field-border-radius: 0.5rem;
+  --fk-editable-field-save-bg: var(--fk-color-success);
+}
+```
+
+## Behavior Notes
+
+- Saving emits the **trimmed** value — leading / trailing whitespace is stripped before `valueChange` fires.
+- Save and Cancel each exit edit mode; the parent's `valueChange` handler is responsible for any network round-trip.
+- The component does not re-fetch the displayed `value` after `valueChange` — the parent owns the source of truth (typically a store / signal that the input re-renders from).
+- `value` is reset to `value()` on every `startEdit()` call, so external updates between sessions always win on the next edit.
+- Disabled fields keep the bordered display shell but drop the pencil — clicking the row is a no-op.

package/ui/icon-badge/README.md

@@ -0,0 +1,131 @@
+# fk-icon-badge
+
+An icon-only badge component that combines `fk-icon` with token-driven background, border, and shape styles.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                | Default     | Description                                                     |
+| ----------------- | ------------------- | ----------- | --------------------------------------------------------------- |
+| `name`            | `string` (required) | —           | Icon name registered in the icon registry                       |
+| `size`            | `IconSize`          | `"md"`      | Icon size (`xs`, `sm`, `md`, `lg`, `xl`)                        |
+| `shape`           | `IconBadgeShape`    | `"circle"`  | Badge shape (`circle`, `square`, etc., depending on type union) |
+| `color`           | `IconColor`         | `"inherit"` | Icon color variant or custom when mapped to tokens              |
+| `borderColor`     | `string \| null`    | `null`      | Optional custom border color                                    |
+| `backgroundColor` | `string \| null`    | `null`      | Optional custom background color                                |
+| `className`       | `string`            | `''`        | Additional CSS classes for the host element                     |
+| `id`              | `string \| null`    | `null`      | Optional ID                                                     |
+| `ariaLabel`       | `string \| null`    | `null`      | Accessible label when the badge conveys meaning                 |
+| `ariaHidden`      | `boolean \| null`   | `null`      | Explicit ARIA hidden flag; falls back to `ariaLabel` when null  |
+
+### Outputs
+
+`fk-icon-badge` is presentational and does not emit outputs.
+
+---
+
+## Features
+
+- Icon-centered badge with configurable size, shape, and colors
+- Accessible by default when `ariaLabel` is provided
+- Token-driven styles for radius, padding, and colors
+- Can be used for statuses, steps, or decorative accents
+
+---
+
+## Quick Start
+
+```html
+<fk-icon-badge name="check-circle" color="success"></fk-icon-badge>
+```
+
+---
+
+## Import
+
+```ts
+import { IconBadgeComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [IconBadgeComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-icon-badge></fk-icon-badge>
+```
+
+---
+
+## Examples
+
+### Status badge
+
+```html
+<fk-icon-badge name="check" color="success" ariaLabel="Completed"></fk-icon-badge>
+```
+
+### Warning badge with custom background
+
+```html
+<fk-icon-badge name="alert-triangle" color="danger" [backgroundColor]="'#fef2f2'" [borderColor]="'#fecaca'" ariaLabel="Attention needed"></fk-icon-badge>
+```
+
+### Step indicator
+
+```html
+<fk-icon-badge name="1" shape="square" ariaLabel="Step 1"></fk-icon-badge>
+```
+
+---
+
+## Accessibility
+
+- If `ariaHidden` is not explicitly set:
+  - When `ariaLabel` is provided, the badge uses `role="img"` and is exposed to assistive technologies.
+  - When `ariaLabel` is `null`, the badge is treated as decorative (`aria-hidden="true"`).
+- Use `ariaLabel` for badges that indicate status or steps; omit it for purely visual decoration.
+
+---
+
+## Design Tokens
+
+`fk-icon-badge` uses badge-related tokens such as:
+
+```scss
+--fk-icon-badge-size-xs;
+--fk-icon-badge-size-sm;
+--fk-icon-badge-size-md;
+--fk-icon-badge-size-lg;
+--fk-icon-badge-radius-circle;
+--fk-icon-badge-radius-square;
+--fk-icon-badge-bg;
+--fk-icon-badge-border-color;
+```
+
+Override tokens in your theme stylesheet:
+
+```scss
+:root {
+  --fk-icon-badge-bg: #eff6ff;
+}
+```
+
+---
+
+## Behavior Notes
+
+- `borderColor` and `backgroundColor` override the corresponding token values via inline styles.
+- `ariaHidden` input lets you explicitly mark the badge as decorative even when an `ariaLabel` is present elsewhere in the UI.