@frame-kit/ui-ng 0.0.1

package/ui/wizard-dialog/README.md

@@ -0,0 +1,283 @@
+# fk-wizard-dialog
+
+A service-driven wizard dialog for multi-step workflows. Opens its own dialog via `DialogService`, placing the stepper and scrollable content in the body and action buttons in the pinned footer.
+
+## API
+
+### WizardDialogService
+
+| Method                                  | Returns                           | Description                                            |
+| --------------------------------------- | --------------------------------- | ------------------------------------------------------ |
+| `open<TResult, TData>(content, config)` | `WizardDialogRef<TResult, TData>` | Opens a wizard dialog with the given content component |
+
+### WizardDialogConfig
+
+| Option             | Type                 | Default        | Description                            |
+| ------------------ | -------------------- | -------------- | -------------------------------------- |
+| `steps`            | `WizardDialogStep[]` | required       | Step definitions (title + contentKey)  |
+| `linear`           | `boolean`            | `true`         | Enforce sequential navigation          |
+| `submitLabel`      | `string`             | `"Submit"`     | Label for the final step action button |
+| `cancelLabel`      | `string`             | `"Cancel"`     | Label for cancel button (first step)   |
+| `nextLabel`        | `string`             | `"Next"`       | Label for next step button             |
+| `backLabel`        | `string`             | `"Back"`       | Label for back button                  |
+| `header`           | `string`             | —              | Dialog header title                    |
+| `size`             | `DialogSize`         | `"lg"`         | Dialog size                            |
+| `data`             | `TData`              | —              | Data passed to the content component   |
+| `closable`         | `boolean`            | `true`         | Show close button                      |
+| `closeOnEscape`    | `boolean`            | `true`         | Close on Escape key                    |
+| `closeOnBackdrop`  | `boolean`            | `false`        | Close on backdrop click                |
+| `animation`        | `DialogAnimation`    | `"scale-fade"` | Open/close animation                   |
+| `fullscreenMobile` | `boolean`            | `false`        | Fullscreen on mobile viewports         |
+| `className`        | `string`             | —              | Additional CSS class on dialog         |
+| `ariaLabel`        | `string`             | —              | Accessible label for the dialog        |
+| `ariaDescribedBy`  | `string`             | —              | ID of describing element               |
+
+### WizardDialogRef
+
+| Property / Method | Type                                      | Description                                                                                                     |
+| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `currentIndex`    | `Signal<number>`                          | Current step index                                                                                              |
+| `isFirstStep`     | `Signal<boolean>`                         | Whether on the first step                                                                                       |
+| `isLastStep`      | `Signal<boolean>`                         | Whether on the last step                                                                                        |
+| `totalSteps`      | `Signal<number>`                          | Total number of steps                                                                                           |
+| `currentStep`     | `Signal<WizardDialogStep>`                | Current step definition                                                                                         |
+| `submitDisabled`  | `WritableSignal<boolean>`                 | Disable submit button                                                                                           |
+| `nextDisabled`    | `WritableSignal<boolean>`                 | Disable next button                                                                                             |
+| `chromeVisible`   | `WritableSignal<boolean>`                 | Show or hide the stepper + footer (both flip together)                                                          |
+| `extraAction`     | `WritableSignal<WizardExtraAction\|null>` | Optional third footer button rendered between Back and Submit (see [Extra Footer Action](#extra-footer-action)) |
+| `submitted`       | `Observable<void>`                        | Emitted when submit is clicked                                                                                  |
+| `stepChanged`     | `Observable<number>`                      | Emitted when step changes                                                                                       |
+| `data`            | `TData`                                   | Config data                                                                                                     |
+| `next()`          | `boolean`                                 | Advance to next step                                                                                            |
+| `previous()`      | `boolean`                                 | Go back one step                                                                                                |
+| `goTo(index)`     | `boolean`                                 | Jump to step (respects linear mode)                                                                             |
+| `close(result?)`  | `void`                                    | Close the dialog                                                                                                |
+| `afterClosed()`   | `Observable<TResult>`                     | Emitted after dialog closes                                                                                     |
+
+### WizardExtraAction
+
+Metadata describing the optional third footer button. Set `wizardRef.extraAction` to this shape (or `null` to remove it).
+
+| Field     | Type                                                | Default     | Description                                                                                                   |
+| --------- | --------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `label`   | `string`                                            | required    | Button text                                                                                                   |
+| `variant` | `"primary" \| "outline" \| "secondary" \| "danger"` | `"outline"` | Visual variant. Defaults to outline so the extra action doesn't compete with the primary Submit button.       |
+| `onClick` | `() => void`                                        | required    | Click handler — typically calls `wizardRef.close(...)` with a sentinel that tells the host page how to react. |
+
+### Content
+
+The content component is dynamically created inside the wizard body. It receives a `WIZARD_DIALOG_REF` injection token to access navigation state and lifecycle events. Step content is rendered via `@switch` on `wizardRef.currentIndex()`.
+
+## Features
+
+- Service-driven: opens its own dialog with proper footer pinning
+- Built-in stepper, scrollable body, and fixed action footer
+- Linear and non-linear navigation modes
+- Consumer controls submit/next disabled state via writable signals
+- Token-driven theming with two-tier fallbacks
+- Focus ring on stepper buttons for keyboard navigation
+
+## Quick Start
+
+```ts
+// 1. Create a content component that injects WIZARD_DIALOG_REF
+@Component({
+  template: `
+    @switch (wizardRef.currentIndex()) {
+      @case (0) {
+        <p>Step 1 content</p>
+      }
+      @case (1) {
+        <p>Step 2 content</p>
+      }
+    }
+  `,
+})
+class MyWizardContentComponent {
+  readonly wizardRef = inject(WIZARD_DIALOG_REF) as WizardDialogRef;
+
+  constructor() {
+    this.wizardRef.submitted.subscribe(() => {
+      // handle submit, then close
+      this.wizardRef.close('done');
+    });
+  }
+}
+
+// 2. Open the wizard dialog from a parent component
+const ref = this.wizardDialogService.open(MyWizardContentComponent, {
+  header: 'Create Item',
+  steps: [
+    { title: 'Details', contentKey: 'details' },
+    { title: 'Review', contentKey: 'review' },
+  ],
+  submitLabel: 'Create',
+});
+
+ref.afterClosed().subscribe((result) => {
+  if (result) {
+    /* success */
+  }
+});
+```
+
+## Import
+
+```ts
+import { WizardDialogService, WizardDialogRef, WIZARD_DIALOG_REF } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-my-page',
+  templateUrl: './my-page.component.html',
+})
+export class MyPageComponent {
+  private readonly wizardDialogService = inject(WizardDialogService);
+}
+```
+
+## Selector
+
+This component is service-driven. There is no consumer-facing selector. Use `WizardDialogService.open()` to open the wizard dialog imperatively.
+
+Internally, the container renders as `<fk-wizard-dialog-container>`, but this is not part of the public API.
+
+## Examples
+
+### Three-Step API Key Creation
+
+```ts
+const ref = this.wizardDialogService.open(CreateApiKeyComponent, {
+  header: 'Create API Key',
+  steps: [
+    { title: 'Details', contentKey: 'details' },
+    { title: 'Permissions', contentKey: 'permissions' },
+    { title: 'Review', contentKey: 'review' },
+  ],
+  submitLabel: 'Create API Key',
+  size: 'lg',
+});
+
+ref.afterClosed().subscribe((created) => {
+  if (created) {
+    this.refresh();
+  }
+});
+```
+
+### Non-Linear Navigation
+
+```ts
+const ref = this.wizardDialogService.open(SettingsComponent, {
+  header: 'Settings',
+  steps: [
+    { title: 'General', contentKey: 'general' },
+    { title: 'Advanced', contentKey: 'advanced' },
+    { title: 'Review', contentKey: 'review' },
+  ],
+  linear: false,
+  submitLabel: 'Save',
+});
+```
+
+### Controlling Button State from Content
+
+```ts
+@Component({ ... })
+class MyContentComponent {
+  readonly wizardRef = inject(WIZARD_DIALOG_REF) as WizardDialogRef;
+  readonly form = new FormGroup({ name: new FormControl("", Validators.required) });
+
+  constructor() {
+    // Disable Next when form is invalid
+    effect(() => {
+      this.wizardRef.nextDisabled.set(this.form.invalid);
+    });
+  }
+}
+```
+
+### Extra Footer Action
+
+A single extra `<fk-button>` can be slotted between Back and Submit on any step via `wizardRef.extraAction`. Typical use: a "View X" jump-off on the results/last step so the host page can branch on a sentinel value when the wizard closes.
+
+The button only renders while `extraAction` is non-null, so consumers usually drive it from an `effect` keyed on `currentIndex`:
+
+```ts
+@Component({ ... })
+class MyContentComponent {
+  readonly wizardRef = inject(WIZARD_DIALOG_REF) as WizardDialogRef<"done" | "view">;
+
+  constructor() {
+    effect(() => {
+      const idx = this.wizardRef.currentIndex();
+
+      if (this.wizardRef.isLastStep()) {
+        this.wizardRef.extraAction.set({
+          label: "View Identities",
+          // omit `variant` to default to "outline"
+          onClick: () => this.wizardRef.close("view"),
+        });
+      } else {
+        this.wizardRef.extraAction.set(null);
+      }
+    });
+  }
+}
+```
+
+Then on the consumer side:
+
+```ts
+ref.afterClosed().subscribe((action) => {
+  if (action === 'view') {
+    this.router.navigate(['./directory'], { relativeTo: this.route });
+  }
+});
+```
+
+The footer's existing flex layout (`flex: 1 1 0` on each child) stretches all three buttons evenly when the extra action is present. If a future use case needs more than one extra button or a fully custom footer row, extend this API rather than adding parallel signals — there's no other footer-projection mechanism on the wizard container.
+
+## Accessibility
+
+- Stepper uses `role="tablist"` with `role="tab"` buttons
+- Active tab indicated via `aria-selected`
+- Disabled future steps in linear mode prevent keyboard activation
+- Focus ring on step buttons via `--fk-focus-ring` token
+- Footer buttons are standard `fk-button` components with full keyboard support
+- Dialog provides focus trapping via `cdkTrapFocus` and restores focus on close
+- `ariaLabel` and `ariaDescribedBy` pass through to the underlying dialog
+
+## Design Tokens
+
+```scss
+--fk-wizard-dialog-stepper-gap
+--fk-wizard-dialog-stepper-padding
+--fk-wizard-dialog-step-color
+--fk-wizard-dialog-step-active-color
+--fk-wizard-dialog-step-completed-color
+--fk-wizard-dialog-step-number-active-color
+--fk-wizard-dialog-body-padding
+--fk-wizard-dialog-footer-gap
+--fk-wizard-dialog-footer-padding
+--fk-wizard-dialog-footer-border
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-wizard-dialog-step-active-color: #0070f3;
+  --fk-wizard-dialog-footer-border: none;
+}
+```
+
+## Behavior Notes
+
+- The wizard opens as a full dialog overlay, not as inline content
+- The body section scrolls independently — the stepper and footer remain fixed
+- `--fk-form-field-gap` is set to `0` inside the body to match FormRenderer spacing
+- In linear mode, only previously visited steps can be clicked in the stepper
+- The content component is dynamically created inside the wizard body via `ViewContainerRef`
+- Cancel button closes the dialog with `undefined`; submit emits on the `submitted` observable for the consumer to handle