@xemahq/ui-kernel 0.6.1 → 0.8.0

package/src/ui/capture/use-wizard.ts

@@ -0,0 +1,134 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// useWizard — headless multi-step engine
+//
+// The state machine the hand-rolled wizards lack: step index, next/prev, goTo,
+// isFirst/isLast, per-step advance gating, and a `status(i)` that maps 1:1 onto
+// the presentational `FormStepper`'s `FormStepStatus`. Controlled (pass `step`)
+// and uncontrolled (pass `initialStep`) modes. No timers, no side effects.
+// ═══════════════════════════════════════════════════════════════════════════
+import { useCallback, useMemo, useState } from 'react';
+
+import { FormStepStatus } from '../primitives/form-stepper';
+
+export interface WizardStepDef {
+  readonly key: string;
+  readonly label: string;
+  readonly hint?: string;
+}
+
+export interface UseWizardOptions {
+  readonly steps: readonly WizardStepDef[];
+  /**
+   * Per-step forward gate. `canAdvance(i)` must return true before the wizard
+   * will move PAST step `i`. Backward navigation is always allowed. Defaults to
+   * always-advanceable.
+   */
+  readonly canAdvance?: (index: number) => boolean;
+  /** Uncontrolled initial index (default 0). Ignored when `step` is provided. */
+  readonly initialStep?: number;
+  /** Controlled active index. When set, the hook is controlled. */
+  readonly step?: number;
+  /** Fired on every requested index change (both modes). */
+  readonly onStepChange?: (index: number) => void;
+}
+
+export interface WizardApi {
+  readonly steps: readonly WizardStepDef[];
+  readonly activeIndex: number;
+  readonly activeStep: WizardStepDef;
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+  /** Whether the CURRENT step's forward gate is satisfied. */
+  readonly canAdvance: boolean;
+  /** 0..1 progress across the steps. */
+  readonly progress: number;
+  readonly next: () => void;
+  readonly prev: () => void;
+  /** Jump to `index`. Backward is free; forward requires every intervening gate. */
+  readonly goTo: (index: number) => void;
+  /** {@link FormStepStatus} for step `index` — feeds `<FormStepper>`. */
+  readonly status: (index: number) => FormStepStatus;
+}
+
+/**
+ * @example
+ * const wizard = useWizard({
+ *   steps: [{ key: 'details', label: 'Details' }, { key: 'review', label: 'Review' }],
+ *   canAdvance: (i) => (i === 0 ? isValid : true),
+ * });
+ * <Wizard api={wizard} onFinish={submit}>
+ *   <WizardStep stepKey="details"><SchemaForm … /></WizardStep>
+ *   <WizardStep stepKey="review"><DocumentPreview … /></WizardStep>
+ * </Wizard>
+ */
+export function useWizard(options: UseWizardOptions): WizardApi {
+  const { steps, canAdvance, initialStep = 0, step, onStepChange } = options;
+  const count = steps.length;
+  const clamp = useCallback((i: number) => Math.max(0, Math.min(count - 1, i)), [count]);
+
+  const isControlled = step !== undefined;
+  const [internal, setInternal] = useState(() => clamp(initialStep));
+  const activeIndex = clamp(isControlled ? (step as number) : internal);
+
+  const gate = useCallback((i: number) => (canAdvance ? canAdvance(i) : true), [canAdvance]);
+
+  const request = useCallback(
+    (target: number) => {
+      const next = clamp(target);
+      if (next === activeIndex) return;
+      onStepChange?.(next);
+      if (!isControlled) setInternal(next);
+    },
+    [activeIndex, clamp, isControlled, onStepChange],
+  );
+
+  const goTo = useCallback(
+    (index: number) => {
+      const target = clamp(index);
+      if (target <= activeIndex) {
+        request(target); // backward is always allowed
+        return;
+      }
+      // Forward: every step from active..target-1 must pass its gate.
+      for (let i = activeIndex; i < target; i += 1) {
+        if (!gate(i)) return;
+      }
+      request(target);
+    },
+    [activeIndex, clamp, gate, request],
+  );
+
+  const next = useCallback(() => {
+    if (activeIndex >= count - 1) return;
+    if (!gate(activeIndex)) return;
+    request(activeIndex + 1);
+  }, [activeIndex, count, gate, request]);
+
+  const prev = useCallback(() => request(activeIndex - 1), [activeIndex, request]);
+
+  const status = useCallback(
+    (index: number): FormStepStatus => {
+      if (index < activeIndex) return FormStepStatus.DONE;
+      if (index === activeIndex) return FormStepStatus.ACTIVE;
+      return FormStepStatus.PENDING;
+    },
+    [activeIndex],
+  );
+
+  return useMemo<WizardApi>(
+    () => ({
+      steps,
+      activeIndex,
+      activeStep: steps[activeIndex],
+      isFirst: activeIndex === 0,
+      isLast: activeIndex === count - 1,
+      canAdvance: gate(activeIndex),
+      progress: count <= 1 ? 1 : activeIndex / (count - 1),
+      next,
+      prev,
+      goTo,
+      status,
+    }),
+    [steps, activeIndex, count, gate, next, prev, goTo, status],
+  );
+}

package/src/ui/capture/value-format.ts

@@ -0,0 +1,22 @@
+// Shared value coercion/formatting for the capture kit — used by the input
+// boundary (SchemaForm) and the read-only view (DocumentPreview) so the two
+// never disagree on how a stored value maps to its display/edit string.
+import { CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+
+/** Coerce any stored value to a display/edit string (empty for absent). */
+export function asString(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value === undefined || value === null) return '';
+  return String(value);
+}
+
+/** Human-readable rendering of a scalar field value for the read-only preview. */
+export function formatScalar(field: CaptureFieldSpec, value: unknown, emptyText: string): string {
+  if (value === undefined || value === null || value === '') return emptyText;
+  switch (field.type) {
+    case CaptureFieldType.Boolean:
+      return value === true ? 'Yes' : 'No';
+    default:
+      return asString(value);
+  }
+}

package/src/ui/capture/wizard.tsx

@@ -0,0 +1,100 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// <Wizard> / <WizardStep> — thin presentational shell over useWizard
+//
+// Composes the existing `<FormStepper>` for the numbered rail (with the ACTIVE
+// step's body rendered inline, guided-style — pending steps stay empty) and
+// renders a Back / Next / Finish nav bar. All state lives in the `useWizard`
+// engine you pass via `api`; this component is presentation only.
+// ═══════════════════════════════════════════════════════════════════════════
+import { Children, isValidElement, type ReactElement, type ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Button } from '../primitives/button';
+import { FormStepper, type FormStep } from '../primitives/form-stepper';
+
+import type { WizardApi } from './use-wizard';
+
+export interface WizardStepProps {
+  /** Must match a `useWizard` step `key`. */
+  readonly stepKey: string;
+  readonly children: ReactNode;
+}
+
+/**
+ * Declarative wrapper for one wizard step's body. Rendered by `<Wizard>` only
+ * when its `stepKey` is the active step.
+ */
+export function WizardStep(_props: WizardStepProps): null {
+  // Rendering is orchestrated by <Wizard>; this component only carries props.
+  return null;
+}
+
+export interface WizardProps {
+  readonly api: WizardApi;
+  readonly children: ReactNode;
+  /** Called when Finish is pressed on the last step (gate already satisfied). */
+  readonly onFinish?: () => void;
+  readonly nextLabel?: string;
+  readonly backLabel?: string;
+  readonly finishLabel?: string;
+  /** Hide the built-in nav bar (caller renders its own using `api`). */
+  readonly hideNav?: boolean;
+  readonly className?: string;
+}
+
+function stepBodies(children: ReactNode): Map<string, ReactNode> {
+  const map = new Map<string, ReactNode>();
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && (child as ReactElement<WizardStepProps>).props?.stepKey) {
+      const p = (child as ReactElement<WizardStepProps>).props;
+      map.set(p.stepKey, p.children);
+    }
+  });
+  return map;
+}
+
+export function Wizard({
+  api,
+  children,
+  onFinish,
+  nextLabel = 'Continue',
+  backLabel = 'Back',
+  finishLabel = 'Finish',
+  hideNav = false,
+  className,
+}: WizardProps) {
+  const bodies = stepBodies(children);
+
+  const formSteps: FormStep[] = api.steps.map((step, index) => ({
+    key: step.key,
+    label: step.label,
+    hint: step.hint,
+    status: api.status(index),
+    // Render the active step's body inline; pending/done steps stay empty so
+    // the rail reads as a guided one-step-at-a-time flow.
+    children: index === api.activeIndex ? bodies.get(step.key) ?? null : null,
+  }));
+
+  return (
+    <div className={cn('space-y-5', className)}>
+      <FormStepper steps={formSteps} />
+
+      {!hideNav && (
+        <div className="flex items-center justify-between gap-2 border-t border-rule pt-4">
+          <Button variant="ghost" onClick={api.prev} disabled={api.isFirst}>
+            {backLabel}
+          </Button>
+          {api.isLast ? (
+            <Button onClick={onFinish} disabled={!api.canAdvance}>
+              {finishLabel}
+            </Button>
+          ) : (
+            <Button onClick={api.next} disabled={!api.canAdvance}>
+              {nextLabel}
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/ui/index.ts

@@ -88,3 +88,6 @@ export { default as LoadingState, type LoadingStateVariant } from './chrome/Load
 export { default as AsyncBoundary } from './chrome/AsyncBoundary';
 
 export { PdfPreview, type PdfPreviewProps } from './pdf/pdf-preview';
+
+// ── guided-capture UX kit (B5 — wizard, validation, prefill, schema form) ──
+export * from './capture';

package/src/lib/biome-host/define-web-biome.test.js

@@ -1,93 +0,0 @@
-// Test suite for defineWebBiome's define-time scope/access validation and the
-// chrome default. Runs on Node's native test runner against the COMPILED dist
-// (CommonJS), so the package needs no jest/vitest/ts-jest toolchain — the
-// `test` script builds first, then runs this file with `node --test`.
-//
-// Covered:
-//   1. A `public` page with access `'member'` (or omitted) throws at define time.
-//   2. A `public` + access `'public'` page is accepted; its route carries no
-//      nav item and mounts with access `'public'`.
-//   3. A non-public page declaring access `'public'` throws at define time.
-//   4. `chrome` defaults to `'host'` when a page omits it; `'none'` passes through.
-
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-
-const { defineWebBiome } = require('../../../dist/lib/biome-host/define-web-biome.js');
-
-const load = () => Promise.resolve({ default: () => null });
-const bridge = /** @type {any} */ ({});
-
-test('rejects a public page whose access is not public (member default)', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
-      }),
-    /a 'public' scope page MUST declare access: 'public'/,
-  );
-});
-
-test('rejects a public page with an explicit non-public access tier', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [
-          { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'org-admin', load },
-        ],
-      }),
-    /a 'public' scope page MUST declare access: 'public'/,
-  );
-});
-
-test('rejects a non-public page that declares access public', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
-      }),
-    /access: 'public' is only valid on a 'public' scope page/,
-  );
-});
-
-test('accepts a public + access:public page and emits no nav item', () => {
-  const factory = defineWebBiome({
-    id: 'test-biome',
-    displayName: 'Test',
-    pages: [
-      { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'public', load },
-    ],
-  });
-  const biome = factory(bridge);
-  assert.equal(biome.routes.length, 1);
-  const route = biome.routes[0];
-  assert.equal(route.path, 'ext/:id');
-  assert.equal(route.access, 'public');
-  assert.equal(route.projectScoped, false);
-  // Public routes never enter the authenticated app rail.
-  assert.equal(biome.navItems.length, 0);
-});
-
-test('chrome defaults to host and none passes through', () => {
-  const factory = defineWebBiome({
-    id: 'test-biome',
-    displayName: 'Test',
-    pages: [
-      { slug: 'system/a', label: 'A', load },
-      { slug: 'system/b', label: 'B', chrome: 'none', load },
-    ],
-  });
-  const biome = factory(bridge);
-  const a = biome.routes.find((r) => r.path === 'system/a');
-  const b = biome.routes.find((r) => r.path === 'system/b');
-  assert.equal(a.chrome, 'host');
-  assert.equal(b.chrome, 'none');
-});