@frame-kit/ui-ng 0.0.1

package/ui/toast/README.md

@@ -0,0 +1,243 @@
+# Toast System
+
+A token-driven toast notification system with a signal-based service, default severity toasts, and support for fully custom toast components.
+
+---
+
+## Quick Start
+
+### 1. Add the container to your app root (once)
+
+```html
+<router-outlet /> <fk-toast-container position="top-right" />
+```
+
+### 2. Show toasts from anywhere
+
+```ts
+private readonly toast = inject(ToastService);
+
+this.toast.success("Saved successfully");
+this.toast.error("Failed to save", "Please try again.");
+```
+
+---
+
+## Components
+
+### `fk-toast` — Individual Toast
+
+Renders a single toast notification with severity icon, summary, optional detail, and dismiss button. Typically rendered by the container — not placed manually.
+
+#### Inputs
+
+| Input         | Type             | Default  | Description                                      |
+| ------------- | ---------------- | -------- | ------------------------------------------------ |
+| `severity`    | `ToastSeverity`  | `"info"` | Severity (`success`, `error`, `warning`, `info`) |
+| `summary`     | `string`         | `""`     | Primary message                                  |
+| `detail`      | `string`         | —        | Optional secondary detail                        |
+| `dismissible` | `boolean`        | `true`   | Whether to show a dismiss button                 |
+| `className`   | `string`         | `""`     | Additional CSS classes                           |
+| `id`          | `string \| null` | `null`   | Optional ID                                      |
+
+#### Outputs
+
+| Output    | Type   | Description                     |
+| --------- | ------ | ------------------------------- |
+| `dismiss` | `void` | Emitted when dismiss is clicked |
+
+### `fk-toast-container` — Toast Stack
+
+Positioned container that renders toasts from `ToastService`. Place once in the app root.
+
+#### Inputs
+
+| Input       | Type             | Default       | Description                                                                                      |
+| ----------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------ |
+| `position`  | `ToastPosition`  | `"top-right"` | Position (`top-right`, `top-center`, `top-left`, `bottom-right`, `bottom-center`, `bottom-left`) |
+| `className` | `string`         | `""`          | Additional CSS classes                                                                           |
+| `id`        | `string \| null` | `null`        | Optional ID                                                                                      |
+
+---
+
+## ToastService API
+
+| Method                                             | Description                           |
+| -------------------------------------------------- | ------------------------------------- |
+| `success(summary, detail?)`                        | Show a success toast                  |
+| `error(summary, detail?)`                          | Show an error toast (longer duration) |
+| `warning(summary, detail?)`                        | Show a warning toast                  |
+| `info(summary, detail?)`                           | Show an info toast                    |
+| `show({ severity, summary, detail?, duration? })`  | Show with full options                |
+| `open(Component, { severity?, data?, duration? })` | Show a custom component toast         |
+| `dismiss(id)`                                      | Dismiss a specific toast              |
+| `clear()`                                          | Clear all toasts                      |
+
+---
+
+## Import
+
+```ts
+import { ToastContainerComponent, ToastService } from '@frame-kit/ui-ng';
+
+// For custom component toasts:
+import { TOAST_DATA, TOAST_REF, ToastRef } from '@frame-kit/ui-ng';
+```
+
+---
+
+## Features
+
+- Built-in inline SVG icons per severity — no icon registry required
+- Optional global icon overrides via `provideToastConfig()`
+- Signal-based service with auto-dismiss and reference counting
+- Six position variants for the container
+- Custom component toasts via `open()` — render any component inside the toast shell
+- Severity-driven color accents via design tokens
+- Dark mode support
+
+---
+
+## Configuration
+
+### Global config (optional)
+
+```ts
+import { provideToastConfig } from '@frame-kit/ui-ng';
+
+// In app.config.ts providers:
+provideToastConfig({
+  defaultDuration: 4000,
+  errorDuration: 10000,
+  icons: {
+    success: 'circle-check-outline',
+    error: 'circle-xmark-outline',
+  },
+});
+```
+
+When icon names are provided and found in `IconRegistryService`, they replace the built-in SVGs. If not found, the built-in SVGs are used as fallback.
+
+---
+
+## Custom Component Toasts
+
+For toasts that need buttons, custom layouts, or interactive content, pass a component to `open()`:
+
+```ts
+@Component({
+  standalone: true,
+  imports: [ButtonComponent],
+  template: `
+    <div style="padding: 1rem;">
+      <p>{{ data.message }}</p>
+      <div style="display: flex; gap: 0.5rem; margin-top: 0.75rem;">
+        <fk-button variant="primary" size="sm" (click)="retry()">Retry</fk-button>
+        <fk-button variant="outline" size="sm" (click)="ref.dismiss()">Dismiss</fk-button>
+      </div>
+    </div>
+  `,
+})
+export class RetryToastComponent {
+  readonly data = inject(TOAST_DATA) as { message: string; retryFn: () => void };
+  readonly ref = inject(TOAST_REF);
+
+  retry(): void {
+    this.ref.dismiss();
+    this.data.retryFn();
+  }
+}
+```
+
+```ts
+// Call site
+this.toastService.open(RetryToastComponent, {
+  severity: 'error',
+  data: { message: 'Failed to save', retryFn: () => this.save() },
+  duration: 0, // no auto-dismiss
+});
+```
+
+The container provides a severity-accented wrapper (border, background, shadow). The component controls all content inside.
+
+---
+
+## Accessibility
+
+- Default toasts use `role="alert"` for error/warning, `role="status"` for success/info
+- Dismiss buttons have `aria-label="Dismiss"`
+- Focus ring uses `--fk-focus-ring` token
+- Container uses `pointer-events: none` so it doesn't block page interaction
+
+---
+
+## Design Tokens
+
+### Toast
+
+```scss
+// Layout
+--fk-toast-gap                    // → --fk-rhythm-3
+--fk-toast-padding                // → --fk-rhythm-4
+--fk-toast-border-color           // → --fk-color-border
+--fk-toast-border-radius          // → --fk-radius-lg
+--fk-toast-bg                     // → --fk-color-surface
+--fk-toast-shadow
+
+// Icon
+--fk-toast-icon-size
+
+// Severity accents
+--fk-toast-success-accent         // → --fk-color-success
+--fk-toast-success-color
+--fk-toast-error-accent           // → --fk-color-danger
+--fk-toast-error-color
+--fk-toast-warning-accent         // → --fk-color-warning
+--fk-toast-warning-color
+--fk-toast-info-accent            // → --fk-color-primary
+--fk-toast-info-color
+
+// Typography
+--fk-toast-summary-font-size      // → --fk-typography-body-font-size
+--fk-toast-summary-font-weight    // → --fk-font-weight-semibold
+--fk-toast-summary-color          // → --fk-color-text
+--fk-toast-detail-font-size       // → --fk-typography-small-font-size
+--fk-toast-detail-color           // → --fk-color-muted
+--fk-toast-body-gap               // → --fk-rhythm-1
+
+// Dismiss
+--fk-toast-dismiss-size
+--fk-toast-dismiss-color          // → --fk-color-muted
+--fk-toast-dismiss-hover-color    // → --fk-color-text
+```
+
+### Container
+
+```scss
+--fk-toast-container-z-index      // default: 9500
+--fk-toast-container-gap          // → --fk-rhythm-3
+--fk-toast-container-padding      // → --fk-rhythm-4
+--fk-toast-container-max-width    // default: 24rem
+```
+
+### Customizing
+
+```css
+:root {
+  --fk-toast-border-radius: 0.75rem;
+  --fk-toast-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
+  --fk-toast-container-max-width: 30rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Default toast duration: 5s (success/warning/info), 8s (error)
+- Set `duration: 0` to disable auto-dismiss for a specific toast
+- Toast z-index (9500) is below the loading overlay (10000)
+- Container `pointer-events: none` with `pointer-events: auto` on individual toasts
+- Bottom positions stack in reverse order (newest at bottom)
+- Custom component toasts are created imperatively via `createComponent` — same pattern as `DialogService`
+- `TOAST_REF.dismiss()` removes the toast from the stack and cleans up the component

package/ui/user-menu/README.md

@@ -0,0 +1,260 @@
+# fk-user-menu
+
+A token-driven user menu molecule that composes an avatar trigger with a dropdown panel of configurable menu items, supporting keyboard navigation, status indicators, and multiple display variants.
+
+---
+
+## API
+
+### Inputs
+
+| Input         | Type                                                        | Default        | Description                                                                    |
+| ------------- | ----------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------ |
+| name          | `string`                                                    | —              | **Required.** User's display name                                              |
+| email         | `string` \| `null`                                          | `null`         | User's email address                                                           |
+| avatarUrl     | `string` \| `null`                                          | `null`         | URL to the user's avatar image                                                 |
+| initials      | `string` \| `null`                                          | `null`         | Custom initials — auto-derived from `name` if absent                           |
+| userId        | `string` \| `null`                                          | `null`         | Optional user identifier                                                       |
+| status        | `"online"` \| `"offline"` \| `"away"` \| `"busy"` \| `null` | `null`         | Presence status passed to the avatar                                           |
+| showStatus    | `boolean`                                                   | `false`        | Show the status indicator on the avatar                                        |
+| menuItems     | `MenuItem[]`                                                | `[]`           | Configurable list of menu actions                                              |
+| placement     | `"bottom-start"` \| `"bottom-end"`                          | `"bottom-end"` | Preferred panel alignment — auto-flips and shifts to stay within the viewport  |
+| size          | `"sm"` \| `"md"` \| `"lg"`                                  | `"md"`         | Avatar size                                                                    |
+| variant       | `"dropdown"` \| `"popover"`                                 | `"dropdown"`   | `"popover"` adds a user header inside the panel                                |
+| showName      | `boolean`                                                   | `false`        | Show user name next to the avatar in the trigger                               |
+| showEmail     | `boolean`                                                   | `false`        | Show email next to the avatar in the trigger                                   |
+| showChevron   | `boolean`                                                   | `true`         | Show a chevron indicator on the trigger                                        |
+| infoPlacement | `"start"` \| `"end"`                                        | `"end"`        | Position name/email relative to the avatar — `"start"` places text on the left |
+| badge         | `string` \| `null`                                          | `null`         | Badge label (e.g. "Admin", "Pro")                                              |
+| disabled      | `boolean`                                                   | `false`        | Disable the trigger                                                            |
+| loading       | `boolean`                                                   | `false`        | Disable the trigger during loading                                             |
+| className     | `string`                                                    | `""`           | Additional CSS classes merged with hook classes                                |
+| id            | `string` \| `null`                                          | `null`         | Sets the host `id` attribute                                                   |
+| ariaLabel     | `string` \| `null`                                          | `null`         | Custom `aria-label` (defaults to "User menu for {name}")                       |
+
+### Outputs
+
+| Output        | Payload    | Description                                                 |
+| ------------- | ---------- | ----------------------------------------------------------- |
+| avatarClick   | `void`     | Emitted when the trigger is clicked                         |
+| menuOpen      | `void`     | Emitted when the dropdown opens                             |
+| menuClose     | `void`     | Emitted when the dropdown closes                            |
+| menuItemClick | `MenuItem` | Emitted when any menu item is selected                      |
+| logoutClick   | `void`     | Emitted when a menu item with `value: "logout"` is selected |
+
+### MenuItem Type
+
+```ts
+interface MenuItem {
+  label: string;
+  value: string;
+  icon?: string;
+  disabled?: boolean;
+  danger?: boolean;
+  separator?: boolean;
+}
+```
+
+When `separator` is `true`, the item renders as a horizontal divider instead of a button.
+
+---
+
+## Features
+
+- Composes `fk-avatar` for the trigger display
+- Configurable menu items with icons, danger styling, disabled state, and separators
+- Two variants: `dropdown` (items only) and `popover` (user header + items)
+- Optional name, email, badge, and chevron in the trigger with configurable info placement (`start` or `end`)
+- Viewport-aware positioning — panel auto-flips vertically and shifts horizontally to avoid clipping
+- Closes on outside click, Escape, or Tab
+- Full keyboard navigation with ArrowUp/Down, Home/End, Enter/Space
+- Token-driven styling for trigger, panel, items, badge, and separator
+
+---
+
+## Quick Start
+
+```html
+<fk-user-menu name="Jane Doe" [menuItems]="menuItems" (menuItemClick)="onMenuItem($event)" (logoutClick)="onLogout()" />
+```
+
+```ts
+menuItems: MenuItem[] = [
+  { label: "Profile", value: "profile", icon: "user" },
+  { label: "Settings", value: "settings", icon: "gear-outline" },
+  { separator: true, label: "", value: "sep" },
+  { label: "Logout", value: "logout", danger: true },
+];
+```
+
+---
+
+## Import
+
+```ts
+import { UserMenuComponent } from '@frame-kit/ui-ng';
+import type { MenuItem } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-header',
+  imports: [UserMenuComponent],
+  templateUrl: './header.component.html',
+})
+export class HeaderComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-user-menu />
+```
+
+---
+
+## Examples
+
+### Minimal
+
+```html
+<fk-user-menu name="Jane Doe" [menuItems]="menuItems" />
+```
+
+### With Name, Email, and Badge
+
+```html
+<fk-user-menu name="Jane Doe" email="jane@acme.com" avatarUrl="/assets/jane.jpg" [showName]="true" [showEmail]="true" badge="Admin" [menuItems]="menuItems" />
+```
+
+### Popover Variant
+
+Shows a user header (name + email) inside the dropdown panel.
+
+```html
+<fk-user-menu name="Jane Doe" email="jane@acme.com" variant="popover" [menuItems]="menuItems" />
+```
+
+### Info on the Left
+
+Places the name and email to the left of the avatar, right-aligned against it.
+
+```html
+<fk-user-menu name="Jane Doe" email="jane@acme.com" [showName]="true" [showEmail]="true" infoPlacement="start" [menuItems]="menuItems" />
+```
+
+### With Status Indicator
+
+```html
+<fk-user-menu name="Jane Doe" [showStatus]="true" status="online" [menuItems]="menuItems" />
+```
+
+### In a Dashboard Header
+
+```html
+<header class="dashboard-header">
+  <span class="dashboard-header__start">
+    <fk-nav-brand label="Acme" />
+  </span>
+
+  <span class="dashboard-header__end">
+    <fk-user-menu [name]="currentUser.name" [email]="currentUser.email" [avatarUrl]="currentUser.avatar" [showStatus]="true" [status]="currentUser.status" variant="popover" placement="bottom-end" [menuItems]="userMenuItems" (menuItemClick)="handleMenuItem($event)" (logoutClick)="logout()" />
+  </span>
+</header>
+```
+
+---
+
+## Accessibility
+
+- Trigger is a native `<button>` with `aria-haspopup="menu"` and `aria-expanded`
+- Panel has `role="menu"` with an `aria-label`
+- Each item has `role="menuitem"` and `aria-disabled` when applicable
+- Separators have `role="separator"`
+- Keyboard support:
+  - **Enter / Space** — open menu or select focused item
+  - **Escape** — close menu
+  - **ArrowDown / ArrowUp** — move focus between items (skips disabled)
+  - **Home / End** — jump to first / last item
+  - **Tab** — close menu and move focus naturally
+- Focus ring applied via `--fk-user-menu-focus-ring` token on both trigger and items
+
+---
+
+## Design Tokens
+
+### Component Tokens
+
+```
+--fk-user-menu-trigger-gap
+--fk-user-menu-trigger-padding
+--fk-user-menu-trigger-radius
+--fk-user-menu-trigger-bg
+--fk-user-menu-trigger-bg-hover
+--fk-user-menu-focus-ring
+--fk-user-menu-opacity-disabled
+--fk-user-menu-name-font-family
+--fk-user-menu-name-font-size
+--fk-user-menu-name-font-weight
+--fk-user-menu-name-color
+--fk-user-menu-email-font-family
+--fk-user-menu-email-font-size
+--fk-user-menu-email-color
+--fk-user-menu-chevron-color
+--fk-user-menu-badge-radius
+--fk-user-menu-badge-bg
+--fk-user-menu-badge-color
+--fk-user-menu-badge-font-family
+--fk-user-menu-badge-font-size
+--fk-user-menu-badge-font-weight
+--fk-user-menu-panel-z
+--fk-user-menu-panel-min-width
+--fk-user-menu-panel-padding
+--fk-user-menu-panel-radius
+--fk-user-menu-panel-bg
+--fk-user-menu-panel-border
+--fk-user-menu-panel-shadow
+--fk-user-menu-item-gap
+--fk-user-menu-item-padding
+--fk-user-menu-item-radius
+--fk-user-menu-item-font-family
+--fk-user-menu-item-font-size
+--fk-user-menu-item-color
+--fk-user-menu-item-bg-hover
+--fk-user-menu-item-danger-color
+--fk-user-menu-item-danger-bg-hover
+--fk-user-menu-separator-color
+```
+
+Each component token falls back to a semantic token, then a raw value. For example:
+
+```
+--fk-user-menu-panel-bg → --fk-color-surface → #ffffff
+--fk-user-menu-item-color → --fk-color-text → #1f2d3d
+--fk-user-menu-item-bg-hover → --fk-color-surface-muted → #f7f9fb
+--fk-user-menu-panel-radius → --fk-radius-lg → 0.75rem
+--fk-user-menu-item-danger-color → --fk-color-danger → #e02424
+```
+
+### Customizing Tokens
+
+Override tokens at any scope:
+
+```css
+:root {
+  --fk-user-menu-panel-radius: 0.5rem;
+  --fk-user-menu-panel-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+  --fk-user-menu-badge-bg: #7c3aed;
+}
+```
+
+Or scope to a specific context:
+
+```css
+.compact-nav fk-user-menu {
+  --fk-user-menu-trigger-padding: 0.125rem;
+  --fk-user-menu-panel-min-width: 10rem;
+}
+```