@edsis/ui 0.0.2

package/toast/README.md

@@ -0,0 +1,321 @@
+# Toast
+
+Imperative notification service wrapping `MatSnackBar` with shadcn styling and a Sonner-style API surface.
+
+## Import
+
+```ts
+import { ToastService } from '@your-scope/ui/toast';
+```
+
+## Application Setup
+
+Angular Material snack bars require animations to be configured once at application bootstrap.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideAnimationsAsync()],
+});
+```
+
+Use `provideNoopAnimations()` instead when the host application intentionally disables animations.
+
+## Basic Usage
+
+```ts
+import { inject } from '@angular/core';
+import { ToastService } from '@your-scope/ui/toast';
+
+export class SaveButtonComponent {
+  private readonly toast = inject(ToastService);
+
+  save(): void {
+    this.toast.success({
+      title: 'Saved',
+      description: 'Your changes have been saved.',
+      action: 'Undo',
+    });
+  }
+
+  fail(): void {
+    this.toast.error({ title: 'Upload failed', description: 'Check your connection.' });
+  }
+}
+```
+
+## Common Patterns
+
+### Variants
+
+```ts
+this.toast.show({ title: 'Draft created' });
+this.toast.success({ title: 'Invoice paid' });
+this.toast.info({ title: 'Deploy starts in 10 minutes' });
+this.toast.warning({ title: 'Storage is almost full' });
+this.toast.error({ title: 'Payment failed' });
+```
+
+### Position
+
+```ts
+this.toast.show({
+  title: 'Event has been created',
+  horizontalPosition: 'start',
+  verticalPosition: 'top',
+});
+```
+
+### Promise State
+
+```ts
+void this.toast.promise(() => this.createEvent(), {
+  loading: 'Loading...',
+  success: (event) => `${event.name} has been created`,
+  error: 'Error',
+});
+```
+
+The loading toast uses `durationMs: null` internally so it stays visible until the promise settles.
+
+## API Reference
+
+### `ToastService`
+
+| Method                             | Returns                   |
+| ---------------------------------- | ------------------------- |
+| `show(options: ToastOptions)`      | `MatSnackBarRef<unknown>` |
+| `success(options)`                 | `MatSnackBarRef<unknown>` |
+| `info(options)`                    | `MatSnackBarRef<unknown>` |
+| `warning(options)`                 | `MatSnackBarRef<unknown>` |
+| `error(options)`                   | `MatSnackBarRef<unknown>` |
+| `promise(taskOrFactory, messages)` | `Promise<T>`              |
+| `dismiss()`                        | `void`                    |
+
+### `ToastOptions`
+
+| Field                | Type                                                             | Default     |
+| -------------------- | ---------------------------------------------------------------- | ----------- |
+| `title`              | `string`                                                         | —           |
+| `description`        | `string`                                                         | —           |
+| `action`             | `string`                                                         | `''`        |
+| `variant`            | `'default' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` |
+| `durationMs`         | `number \| null`                                                 | `5000`      |
+| `horizontalPosition` | `MatSnackBarConfig['horizontalPosition']`                        | `'end'`     |
+| `verticalPosition`   | `MatSnackBarConfig['verticalPosition']`                          | `'bottom'`  |
+
+Set `durationMs` to `null` when the toast should stay visible until `dismiss()` is called.
+
+### `ToastPromiseMessages<T>`
+
+| Field     | Type                                     | Notes                                     |
+| --------- | ---------------------------------------- | ----------------------------------------- |
+| `loading` | `string`                                 | Title shown while the promise is pending. |
+| `success` | `string \| ((value: T) => string)`       | Title shown when the promise resolves.    |
+| `error`   | `string \| ((error: unknown) => string)` | Title shown when the promise rejects.     |
+
+## Styling And Theming
+
+The service applies `ui-toast-panel` plus `ui-toast-<variant>` panel classes to the Angular Material snack-bar container.
+
+- `default` keeps the background and foreground tokens from the active theme.
+- `success` uses the primary theme tokens.
+- `info` uses the shared `info` tokens.
+- `warning` uses the shared `warning` tokens.
+- `error` maps to the destructive tokens.
+
+If you need to override a variant, target the container class and set the Material snack-bar CSS custom properties:
+
+```css
+.mat-mdc-snack-bar-container.ui-toast-warning {
+  --mdc-snackbar-container-color: hsl(var(--warning));
+  --mdc-snackbar-supporting-text-color: hsl(var(--warning-foreground));
+  --mat-snack-bar-button-color: hsl(var(--warning-foreground));
+}
+```
+
+## Accessibility
+
+`MatSnackBar` manages live-region announcements automatically. Keep titles short, use `action` for a single primary follow-up, and avoid moving focus into the toast.
+
+## Angular Notes
+
+Inject the service where the interaction starts instead of creating a global host component. `MatSnackBar` shows one visible toast at a time, so `promise()` dismisses the loading state before showing its success or error follow-up.
+
+## Source Parity
+
+This entrypoint is the local Angular mapping for shadcn Sonner as well as the simpler toast examples in the demo. It intentionally preserves the imperative API mental model, variant coverage, and placement controls while staying honest about the implementation boundary: the runtime surface is still a focused `MatSnackBar` wrapper, not Sonner's stacked multi-toast viewport.
+
+# Toast
+
+Imperative notification service backed by `MatSnackBar`, styled for the local shadcn-inspired theme.
+
+The upstream shadcn toast page is deprecated in favor of Sonner. This entrypoint remains useful for lightweight single-message flows in Angular apps, while richer stacked notification workflows can move to a future Sonner-style surface.
+
+## Import
+
+```ts
+import { ToastService } from '@edsis/ui/toast';
+```
+
+## App setup
+
+Enable browser or noop animations so the underlying snackbar overlay can render correctly.
+
+```ts
+import type { ApplicationConfig } from '@angular/core';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideAnimationsAsync()],
+};
+```
+
+Use `provideNoopAnimations()` instead when the host application deliberately disables animations.
+
+## Structure
+
+This entrypoint exports a service rather than a component tree. `ToastService` keeps the API at the same event-handling layer as your save, delete, archive, or publish action, while rendering is delegated to Angular Material overlays.
+
+## Basic usage
+
+```ts
+import { inject } from '@angular/core';
+import { ToastService } from '@edsis/ui/toast';
+
+export class SaveButton {
+  private readonly toast = inject(ToastService);
+
+  save(): void {
+    this.toast.success({
+      title: 'Saved',
+      description: 'Your changes have been saved.',
+    });
+  }
+}
+```
+
+## Common patterns
+
+### Status shortcuts
+
+```ts
+this.toast.show({
+  title: 'Deployment queued',
+  description: 'We will notify you when the build is ready.',
+});
+
+this.toast.success({
+  title: 'Saved',
+  description: 'Your changes have been saved.',
+});
+
+this.toast.info({
+  title: 'Heads up',
+  description: 'The deployment window starts in 10 minutes.',
+});
+
+this.toast.warning({
+  title: 'Storage almost full',
+  description: 'Archive older uploads before the next sync.',
+});
+
+this.toast.error({
+  title: 'Failed to save',
+  description: 'Network error. Please retry.',
+});
+```
+
+### Persistent action
+
+For an important action, keep the toast open and handle the snackbar action from the returned reference.
+
+```ts
+const ref = this.toast.show({
+  title: 'Event archived',
+  description: 'Restore it from the calendar within the next minute.',
+  action: 'Undo',
+  durationMs: null,
+});
+
+ref.onAction().subscribe(() => {
+  this.toast.info({
+    title: 'Archive cancelled',
+    description: 'The event is back on the calendar.',
+  });
+});
+```
+
+### Promise helper
+
+Use `toast.promise()` when one async task should produce loading, success, and failure feedback in sequence.
+
+```ts
+await this.toast.promise(
+  () =>
+    new Promise<{ name: string }>((resolve) => {
+      window.setTimeout(() => resolve({ name: 'Summer launch checklist' }), 900);
+    }),
+  {
+    loading: 'Archiving draft...',
+    success: (draft) => `${draft.name} archived`,
+    error: 'Unable to archive draft',
+  },
+);
+```
+
+## API Reference
+
+### `ToastService`
+
+| Method                             | Returns                   | Notes                                                      |
+| ---------------------------------- | ------------------------- | ---------------------------------------------------------- |
+| `show(options)`                    | `MatSnackBarRef<unknown>` | Lowest-level method with full option control.              |
+| `success(options)`                 | `MatSnackBarRef<unknown>` | Shortcut for `variant: 'success'`.                         |
+| `info(options)`                    | `MatSnackBarRef<unknown>` | Angular-local semantic shortcut.                           |
+| `warning(options)`                 | `MatSnackBarRef<unknown>` | Angular-local semantic shortcut.                           |
+| `error(options)`                   | `MatSnackBarRef<unknown>` | Shortcut for `variant: 'destructive'`.                     |
+| `promise(taskOrFactory, messages)` | `Promise<T>`              | Shows loading first, then success or destructive feedback. |
+| `dismiss()`                        | `void`                    | Closes the active toast.                                   |
+
+### `ToastOptions`
+
+| Field                | Type                                                             | Default     | Notes                                                      |
+| -------------------- | ---------------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
+| `title`              | `string`                                                         | unset       | Primary message line.                                      |
+| `description`        | `string`                                                         | unset       | Optional secondary line.                                   |
+| `action`             | `string`                                                         | `''`        | Single action label shown by the snackbar.                 |
+| `variant`            | `'default' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` | Visual variant applied through `ui-toast-*` panel classes. |
+| `durationMs`         | `number \| null`                                                 | `5000`      | Set to `null` to keep the toast open until dismissed.      |
+| `horizontalPosition` | `MatSnackBarConfig['horizontalPosition']`                        | `'end'`     | Snackbar x-axis placement.                                 |
+| `verticalPosition`   | `MatSnackBarConfig['verticalPosition']`                          | `'bottom'`  | Snackbar y-axis placement.                                 |
+
+### `ToastPromiseMessages<T>`
+
+| Field     | Type                                     | Notes                                               |
+| --------- | ---------------------------------------- | --------------------------------------------------- |
+| `loading` | `string`                                 | Required loading message while the task is pending. |
+| `success` | `string \| ((value: T) => string)`       | Static or data-derived success copy.                |
+| `error`   | `string \| ((error: unknown) => string)` | Static or error-derived destructive copy.           |
+
+## Styling and theming
+
+The service applies `ui-toast-panel` and `ui-toast-<variant>` classes on the snackbar container. The shared Material integration maps those classes to the local semantic tokens for default, destructive, success, info, and warning states, and preserves line breaks between `title` and `description`.
+
+## Accessibility
+
+`MatSnackBar` manages live-region announcements automatically. Keep toast copy short, reserve it for transient status updates, and prefer `durationMs: null` when the action button must stay available long enough for keyboard and assistive-technology users.
+
+## Keyboard interactions
+
+The toast body itself is not a roving-focus widget. Keyboard interaction is limited to the optional action button exposed by the snackbar when `action` is present.
+
+## Angular notes
+
+This API is intentionally Angular-first rather than a one-to-one port of Radix toast composition. You trigger notifications from event handlers or async workflows, not by managing a dedicated toast viewport in every template.
+
+## Source parity
+
+Default and destructive map most closely to the historical shadcn toast examples. `success`, `info`, and `warning` are Angular-local semantic additions that fit the service-style API better. The upstream shadcn page now points users to Sonner, so this entrypoint deliberately focuses on simple, single-message feedback instead of stacked queue management.

package/toggle/README.md

@@ -0,0 +1,131 @@
+# Toggle
+
+A two-state button that can be either on or off.
+
+Use Toggle for persistent formatting, bookmarking, pinning, or filter state where a pressed button is the right semantic pattern.
+
+## Import
+
+```ts
+import { ToggleComponent } from '@edsis/ui/toggle';
+```
+
+## Composition
+
+The Angular surface keeps the same single-host shape as shadcn and Radix while mapping it to a native button selector.
+
+```text
+button[ui-toggle]
+```
+
+## Basic usage
+
+Bind `[(pressed)]` when the parent should observe or control the state. The host always renders as a native button with `aria-pressed`.
+
+```ts
+readonly bookmarked = signal(false);
+```
+
+```html
+<button ui-toggle aria-label="Toggle bookmark" [(pressed)]="bookmarked" variant="outline" size="sm">
+  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <path d="M6 4.75c0-.41.34-.75.75-.75h10.5c.41 0 .75.34.75.75V20l-6-3.5L6 20V4.75Z" />
+  </svg>
+  Bookmark
+</button>
+```
+
+## Common patterns
+
+### Outline variant
+
+Use `variant="outline"` when the toggle should read like a bordered tool button.
+
+```html
+<button ui-toggle aria-label="Toggle italic" variant="outline">Italic</button>
+```
+
+### With text
+
+Project an icon and visible text when the label should stay on screen.
+
+```html
+<button ui-toggle aria-label="Toggle italic">
+  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <path d="M10 4h8" />
+    <path d="M6 20h8" />
+    <path d="M14 4 10 20" />
+  </svg>
+  Italic
+</button>
+```
+
+### Sizes
+
+The toggle supports the shadcn size names `sm`, `default`, and `lg`.
+
+```html
+<button ui-toggle size="sm" variant="outline" aria-label="Toggle small">Small</button>
+<button ui-toggle size="default" variant="outline" aria-label="Toggle default">Default</button>
+<button ui-toggle size="lg" variant="outline" aria-label="Toggle large">Large</button>
+```
+
+### Disabled state
+
+Set `[disabled]="true"` when the control should remain visible but unavailable.
+
+```html
+<button ui-toggle aria-label="Toggle bookmark" [disabled]="true">Bookmark</button>
+```
+
+### RTL
+
+Direction comes from the surrounding layout. The API stays the same.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <button ui-toggle aria-label="تبديل الإشارة المرجعية" variant="outline" size="sm">إشارة مرجعية</button>
+</div>
+```
+
+## API reference
+
+| Input or model | Type                        | Default     |
+| -------------- | --------------------------- | ----------- |
+| `pressed`      | `boolean`                   | `false`     |
+| `disabled`     | `boolean`                   | `false`     |
+| `variant`      | `'default' \| 'outline'`    | `'default'` |
+| `size`         | `'sm' \| 'default' \| 'lg'` | `'default'` |
+| `class`        | `string`                    | `''`        |
+
+Host: `button[ui-toggle]`.
+
+The host exposes `aria-pressed`, `data-state="on|off"`, `data-variant`, `data-size`, and `data-disabled` for styling and testing hooks.
+
+## Styling and theming
+
+The primitive uses the shared library color tokens for `foreground`, `accent`, `muted`, `input`, and `ring`.
+
+Use `class` to add width, shape, or layout utilities such as `rounded-full`, `w-full`, or responsive flex helpers.
+
+## Accessibility
+
+- `button[ui-toggle]` keeps the native button semantics and adds `aria-pressed` for the two-state pattern.
+- Provide an `aria-label` for icon-only toggles.
+- Use Toggle for persistent on/off state. If the control changes application state like a checkbox field, prefer the dedicated switch or checkbox primitive.
+- Disabled toggles remain visible but non-interactive.
+
+## Keyboard interactions
+
+- Native button behavior covers Tab focus plus Enter and Space activation.
+- Pressing Enter or Space toggles the `pressed` model through the native click event.
+
+## Angular notes
+
+- Import `ToggleComponent` into the standalone component that renders the host.
+- `[(pressed)]` is the Angular replacement for React's `pressed` and `onPressedChange` pairing.
+- The host always defaults to `type="button"` so it does not submit ancestor forms accidentally.
+
+## Source parity
+
+This Angular implementation follows the shadcn Toggle information architecture, variants, sizes, and RTL guidance while translating the runtime API to a native button host with signal-friendly two-way binding.

package/toggle-group/README.md

@@ -0,0 +1,206 @@
+# Toggle Group
+
+A set of two-state buttons that can be toggled on or off with either single or multiple selection.
+
+Use Toggle Group for formatting toolbars, persistent filters, view-mode switches, or any compact control cluster where each item represents a pressed state instead of an immediate action.
+
+## Import
+
+```ts
+import { ToggleGroupComponent, ToggleGroupItemDirective } from '@edsis/ui/toggle-group';
+```
+
+## Composition
+
+The Angular structure keeps the same root-plus-items shape as shadcn and Radix while translating the API to strongly typed Angular bindings.
+
+```text
+ui-toggle-group
+├── button[ui-toggle-group-item]
+└── button[ui-toggle-group-item]
+```
+
+## Basic usage
+
+Use `[(value)]` for single-select groups and `[(values)]` for multi-select groups.
+
+```ts
+readonly alignment = signal<string | null>('center');
+readonly styles = signal<string[]>(['bold']);
+```
+
+```html
+<ui-toggle-group type="single" [(value)]="alignment" variant="outline" aria-label="Text alignment">
+  <button ui-toggle-group-item value="left" aria-label="Left aligned">Left</button>
+  <button ui-toggle-group-item value="center" aria-label="Center aligned">Center</button>
+  <button ui-toggle-group-item value="right" aria-label="Right aligned">Right</button>
+</ui-toggle-group>
+```
+
+```html
+<ui-toggle-group type="multiple" [(values)]="styles" variant="outline" aria-label="Text styles">
+  <button ui-toggle-group-item value="bold" aria-label="Bold">Bold</button>
+  <button ui-toggle-group-item value="italic" aria-label="Italic">Italic</button>
+  <button ui-toggle-group-item value="underline" aria-label="Underline">Underline</button>
+</ui-toggle-group>
+```
+
+## Common patterns
+
+### Outline
+
+Use `variant="outline"` when the group should read like a bordered toolbar or filter control.
+
+```html
+<ui-toggle-group type="single" [(value)]="filter" variant="outline" aria-label="Message filters">
+  <button ui-toggle-group-item value="all">All</button>
+  <button ui-toggle-group-item value="missed">Missed</button>
+</ui-toggle-group>
+```
+
+### Size
+
+Set `size` on the root so every child item scales together.
+
+```html
+<ui-toggle-group type="single" [(value)]="alignment" variant="outline" size="lg" aria-label="Large alignment">
+  <button ui-toggle-group-item value="left">Left</button>
+  <button ui-toggle-group-item value="center">Center</button>
+  <button ui-toggle-group-item value="right">Right</button>
+</ui-toggle-group>
+```
+
+### Spacing
+
+Spacing defaults to `2`, matching the current shadcn docs. Use `spacing="0"` for connected items or larger values for looser toolbars.
+
+```html
+<ui-toggle-group type="single" [(value)]="alignment" variant="outline" spacing="0" aria-label="Connected alignment">
+  <button ui-toggle-group-item value="left">Left</button>
+  <button ui-toggle-group-item value="center">Center</button>
+  <button ui-toggle-group-item value="right">Right</button>
+</ui-toggle-group>
+```
+
+### Vertical orientation
+
+Use `orientation="vertical"` to stack items while keeping the same roving-focus keyboard behavior.
+
+```html
+<ui-toggle-group type="multiple" [(values)]="styles" orientation="vertical" spacing="1" aria-label="Text styles">
+  <button ui-toggle-group-item value="bold" aria-label="Toggle bold">Bold</button>
+  <button ui-toggle-group-item value="italic" aria-label="Toggle italic">Italic</button>
+  <button ui-toggle-group-item value="underline" aria-label="Toggle underline">Underline</button>
+</ui-toggle-group>
+```
+
+### Disabled group
+
+Disable the root when the whole cluster is unavailable.
+
+```html
+<ui-toggle-group
+  type="multiple"
+  [(values)]="styles"
+  variant="outline"
+  [disabled]="true"
+  aria-label="Unavailable text styles">
+  <button ui-toggle-group-item value="bold">Bold</button>
+  <button ui-toggle-group-item value="italic">Italic</button>
+  <button ui-toggle-group-item value="underline">Underline</button>
+</ui-toggle-group>
+```
+
+### Custom controlled state
+
+The selected value can drive any Angular signal, such as font weight, filters, or an editor mode.
+
+```ts
+readonly fontWeight = signal<string | null>('normal');
+```
+
+```html
+<ui-toggle-group type="single" [(value)]="fontWeight" variant="outline" size="lg" aria-label="Font weight">
+  <button ui-toggle-group-item value="light" class="min-w-24">Light</button>
+  <button ui-toggle-group-item value="normal" class="min-w-24">Normal</button>
+  <button ui-toggle-group-item value="medium" class="min-w-24">Medium</button>
+  <button ui-toggle-group-item value="bold" class="min-w-24">Bold</button>
+</ui-toggle-group>
+```
+
+### RTL
+
+Direction comes from the surrounding layout. Horizontal arrow navigation respects the active text direction automatically.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <ui-toggle-group type="single" [(value)]="view" variant="outline" aria-label="طريقة العرض">
+    <button ui-toggle-group-item value="list">قائمة</button>
+    <button ui-toggle-group-item value="grid">شبكة</button>
+    <button ui-toggle-group-item value="cards">بطاقات</button>
+  </ui-toggle-group>
+</div>
+```
+
+## API reference
+
+### `ToggleGroupComponent`
+
+| Input or model | Type                         | Default        |
+| -------------- | ---------------------------- | -------------- |
+| `type`         | `'single' \| 'multiple'`     | required       |
+| `value`        | `string \| null`             | `null`         |
+| `values`       | `string[]`                   | `[]`           |
+| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `variant`      | `'default' \| 'outline'`     | `'default'`    |
+| `size`         | `'sm' \| 'default' \| 'lg'`  | `'default'`    |
+| `spacing`      | `0 \| 1 \| 2 \| 3 \| 4`      | `2`            |
+| `loop`         | `boolean`                    | `true`         |
+| `disabled`     | `boolean`                    | `false`        |
+| `dir`          | `'ltr' \| 'rtl' \| null`     | `null`         |
+| `class`        | `string`                     | `''`           |
+
+### `ToggleGroupItemDirective`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+Host: `button[ui-toggle-group-item]`.
+
+The item host exposes `aria-pressed`, `data-state="on|off"`, `data-variant`, `data-size`, `data-orientation`, and `data-disabled` for styling and testing hooks.
+
+## Styling and theming
+
+- Toggle Group items intentionally share the same `variant` and `size` contract as the standalone Toggle primitive, so grouped toolbars and standalone toggles stay visually aligned.
+- Use `spacing` for inter-item layout. When `spacing="0"`, the root collapses adjacent radius and borders so outline items read as a connected control.
+- Use `class` on the root or an item for width, alignment, or card-like custom presentations.
+
+## Accessibility
+
+- `ui-toggle-group` renders `role="group"`; provide `aria-label` or `aria-labelledby` when the cluster needs an accessible name.
+- `button[ui-toggle-group-item]` keeps native button semantics and exposes `aria-pressed` for the two-state pattern.
+- Add an `aria-label` to icon-only items.
+- Disabled items stay visible and are skipped by the group keyboard navigation.
+
+## Keyboard interactions
+
+- Tab moves focus to the pressed item or the first enabled item in the group.
+- Enter and Space activate or deactivate the current item through the native button click.
+- Arrow keys move focus through the group.
+- `Home` and `End` jump to the first or last enabled item.
+- Horizontal arrow movement respects RTL direction.
+
+## Angular notes
+
+- Use `[(value)]` in single mode and `[(values)]` in multiple mode instead of overloading one input with two types.
+- The item host selector is `button[ui-toggle-group-item]`; consumers do not add `ui-toggle` separately.
+- The root owns roving focus, so consumer templates do not need extra CDK focus utilities.
+
+## Source parity
+
+This Angular implementation follows the current shadcn Toggle Group docs for outline styling, size scaling, spacing, vertical orientation, disabled groups, custom controlled state, RTL behavior, and the Radix roving-focus keyboard contract.
+
+The intentional Angular deviation is the binding split between `value` and `values`, which keeps signal types explicit for single and multiple modes.