@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,180 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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.types';
-
-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;
-}
-
-/**
- * Strict access guard — keeps `steps[index]` typed as defined.
- *
- * `activeIndex` is clamped into `[0, count - 1]`, so the only way this misses is
- * an EMPTY `steps` array: `clamp` floors at 0 and `steps[0]` is then `undefined`.
- * `WizardApi.activeStep` is declared non-optional and consumers dereference it
- * (`api.activeStep.key`), so a zero-step wizard must fail here with a message
- * naming the cause rather than hand back an `undefined` typed as `WizardStepDef`.
- */
-function requireStep(
-  steps: readonly WizardStepDef[],
-  index: number,
-): WizardStepDef {
-  const step = steps[index];
-  if (!step) {
-    throw new Error(
-      `useWizard: no step at index ${index} (have ${steps.length}). ` +
-        '`steps` must contain at least one entry.',
-    );
-  }
-  return step;
-}
-
-/**
- * @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 : 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: requireStep(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

@@ -1,32 +0,0 @@
-// 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

@@ -1,105 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// <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 ReactNode,
-} from 'react';
-
-import { cn } from '../cn';
-import { Button } from '../primitives/button';
-import { FormStepper } from '../primitives/form-stepper';
-
-import type { WizardApi } from './use-wizard';
-import type { FormStep } from '../primitives/form-stepper.types';
-
-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<WizardStepProps>(child) && child.props.stepKey) {
-      const p = child.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/charts/bar-chart.tsx

@@ -1,139 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// BarChart — categorical bars, pure SVG (Wave 9.2)
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
-import {
-  buildAriaSummary,
-  chartColorAt,
-  defaultFormatValue,
-  finitePoints,
-  niceScale,
-} from './chart-utils';
-
-import type { ChartBaseProps, ChartDatum } from './chart-types';
-import type { ReactNode } from 'react';
-
-// Internal coordinate space — the `viewBox`. `width="100%"` makes the SVG scale
-// to its container (D20 fluid), so these are ratios, not device pixels.
-const VIEW_W = 640;
-const VIEW_H = 360;
-const PAD = { top: 12, right: 12, bottom: 44, left: 48 } as const;
-const PLOT_L = PAD.left;
-const PLOT_R = VIEW_W - PAD.right;
-const PLOT_T = PAD.top;
-const PLOT_B = VIEW_H - PAD.bottom;
-const PLOT_W = PLOT_R - PLOT_L;
-const PLOT_H = PLOT_B - PLOT_T;
-
-export interface BarChartProps extends ChartBaseProps {
-  /** The bars — one per labelled datum. */
-  readonly data: readonly ChartDatum[];
-}
-
-export function BarChart({
-  data,
-  title,
-  ariaLabel,
-  formatValue,
-  className,
-  emptyLabel = 'No data',
-}: BarChartProps): ReactNode {
-  const format = formatValue ?? defaultFormatValue;
-  const points = finitePoints(data);
-
-  if (points.length === 0) {
-    return (
-      <ChartEmpty title={title} label={emptyLabel} className={className} />
-    );
-  }
-
-  const values = points.map((p) => p.value);
-  const scale = niceScale(Math.min(...values), Math.max(...values));
-  const span = scale.max - scale.min;
-  const yToPx = (v: number): number =>
-    PLOT_B - ((v - scale.min) / span) * PLOT_H;
-  const baseline = yToPx(0);
-
-  const band = PLOT_W / points.length;
-  const barW = Math.min(band * 0.62, 72);
-
-  const legend: ChartLegendItem[] = points.map((p, i) => ({
-    label: p.label,
-    value: format(p.value),
-    color: chartColorAt(i, p.color),
-  }));
-
-  const summary = ariaLabel ?? buildAriaSummary(title, points, format, 'bar');
-
-  const plot = (
-    <svg
-      role="img"
-      aria-label={summary}
-      width="100%"
-      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
-      preserveAspectRatio="xMidYMid meet"
-      className="block h-auto w-full overflow-visible text-ink-4"
-    >
-      {/* y gridlines + tick labels */}
-      {scale.ticks.map((t) => {
-        const y = yToPx(t);
-        return (
-          <g key={`y-${t}`}>
-            <line
-              x1={PLOT_L}
-              x2={PLOT_R}
-              y1={y}
-              y2={y}
-              stroke="currentColor"
-              strokeOpacity={t === 0 ? 0.35 : 0.12}
-            />
-            <text
-              x={PLOT_L - 8}
-              y={y}
-              textAnchor="end"
-              dominantBaseline="middle"
-              fontSize={12}
-              fill="currentColor"
-            >
-              {format(t)}
-            </text>
-          </g>
-        );
-      })}
-
-      {/* bars + x labels */}
-      {points.map((p, i) => {
-        const cx = PLOT_L + band * i + band / 2;
-        const yv = yToPx(p.value);
-        const top = Math.min(yv, baseline);
-        const h = Math.max(1, Math.abs(baseline - yv));
-        return (
-          <g key={`bar-${p.label}-${i}`}>
-            <rect
-              x={cx - barW / 2}
-              y={top}
-              width={barW}
-              height={h}
-              rx={3}
-              fill={chartColorAt(i, p.color)}
-            >
-              <title>{`${p.label}: ${format(p.value)}`}</title>
-            </rect>
-            <text
-              x={cx}
-              y={PLOT_B + 16}
-              textAnchor="middle"
-              fontSize={12}
-              fill="currentColor"
-            >
-              {p.label}
-            </text>
-          </g>
-        );
-      })}
-    </svg>
-  );
-
-  return <ChartFrame plot={plot} legend={legend} className={className} />;
-}

package/src/ui/charts/chart-frame.tsx

@@ -1,125 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Chart primitives — shared layout frame, legend and empty state (Wave 9.2)
-//
-// `ChartFrame` owns the D20 responsive contract: the plot is a fluid container
-// and the legend sits BESIDE it on wide viewports but MOVES BELOW the plot
-// below `md`. That decision is driven by `useIsMobile()` — which reads the one
-// shared `MOBILE_BREAKPOINT` token — never a second breakpoint.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { cn } from '../cn';
-import { useIsMobile } from '../hooks/use-is-mobile';
-
-import type { ReactNode } from 'react';
-
-/** One row of the legend: a color swatch + its label + (optional) value. */
-export interface ChartLegendItem {
-  readonly label: string;
-  readonly color: string;
-  readonly value?: string;
-}
-
-interface ChartLegendProps {
-  readonly items: readonly ChartLegendItem[];
-  /** `below` stacks items into a wrapping row; `beside` stacks them vertically. */
-  readonly layout: 'beside' | 'below';
-}
-
-/**
- * The legend. Meaning is carried by the text label + value — the swatch is a
- * secondary cue, so a color-blind or monochrome reader loses nothing.
- */
-export function ChartLegend({ items, layout }: ChartLegendProps): ReactNode {
-  if (items.length === 0) {
-    return null;
-  }
-  return (
-    <ul
-      className={cn(
-        'm-0 list-none p-0 text-body-2 text-ink-3',
-        layout === 'below'
-          ? 'flex flex-row flex-wrap gap-x-4 gap-y-1.5'
-          : 'flex flex-col gap-1.5',
-      )}
-    >
-      {items.map((item, i) => (
-        <li key={`${item.label}-${i}`} className="flex items-center gap-2">
-          <span
-            aria-hidden="true"
-            className="inline-block h-2.5 w-2.5 shrink-0 rounded-sm"
-            style={{ backgroundColor: item.color }}
-          />
-          <span className="text-ink-3">{item.label}</span>
-          {item.value !== undefined && (
-            <span className="ml-auto font-medium tabular-nums text-ink">
-              {item.value}
-            </span>
-          )}
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-interface ChartFrameProps {
-  /** The plot itself — a fluid `<svg>` with `width="100%"` + a `viewBox`. */
-  readonly plot: ReactNode;
-  readonly legend: readonly ChartLegendItem[];
-  readonly className?: string;
-}
-
-/**
- * Wraps a plot + legend with the responsive D20 layout. Uses `useIsMobile()`
- * so below `md` the legend renders BELOW the plot; at/above `md` it sits to the
- * right. One token (`MOBILE_BREAKPOINT`), no second breakpoint.
- */
-export function ChartFrame({
-  plot,
-  legend,
-  className,
-}: ChartFrameProps): ReactNode {
-  const isMobile = useIsMobile();
-  return (
-    <div className={cn('w-full min-w-0 text-ink-3', className)}>
-      <div
-        className={cn(
-          'flex min-w-0 gap-4',
-          isMobile ? 'flex-col' : 'flex-row items-start',
-        )}
-      >
-        <div className="min-w-0 flex-1">{plot}</div>
-        <ChartLegend items={legend} layout={isMobile ? 'below' : 'beside'} />
-      </div>
-    </div>
-  );
-}
-
-interface ChartEmptyProps {
-  readonly title: string;
-  readonly label: string;
-  readonly className?: string;
-}
-
-/**
- * Explicit empty state — rendered instead of a broken/NaN SVG when a series has
- * no finite points. Still carries `role="img"` + an `aria-label` so assistive
- * tech announces the (empty) chart rather than a silent gap.
- */
-export function ChartEmpty({
-  title,
-  label,
-  className,
-}: ChartEmptyProps): ReactNode {
-  return (
-    <div
-      role="img"
-      aria-label={`${title}: ${label}`}
-      className={cn(
-        'flex w-full items-center justify-center rounded-lg border border-dashed border-border/60 bg-muted/20 px-4 py-10 text-body-2 text-ink-4',
-        className,
-      )}
-    >
-      {label}
-    </div>
-  );
-}

package/src/ui/charts/chart-types.ts

@@ -1,52 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Chart primitives — public typed contracts (Wave 9.2)
-//
-// Pure-SVG chart primitives shipped by the kernel (NO external chart library).
-// These are the closed, typed shapes every chart primitive consumes. No `any`.
-// ═══════════════════════════════════════════════════════════════════════════
-
-/** A single labelled numeric point. The atom of every chart series. */
-export interface ChartDatum {
-  /** Human-readable category / x-axis label. Always present (never color-only). */
-  readonly label: string;
-  /** The numeric value. Non-finite values (NaN/Infinity) are skipped, never plotted. */
-  readonly value: number;
-  /**
-   * Optional per-datum color override — any CSS color, `currentColor`, or a
-   * `var(--…)` token. When omitted the themeable palette assigns one by index.
-   */
-  readonly color?: string;
-}
-
-/** A named line series over a shared set of x-labels (LineChart). */
-export interface ChartLineSeries {
-  /** Series name — shown in the legend and the aria summary. */
-  readonly name: string;
-  /** The ordered points of this line. */
-  readonly points: readonly ChartDatum[];
-  /** Optional color override (CSS color / `currentColor` / `var(--…)`). */
-  readonly color?: string;
-}
-
-/** Formats a raw numeric value for axis ticks, legend and the aria summary. */
-export type ChartValueFormatter = (value: number) => string;
-
-/** Props shared by every chart primitive. */
-export interface ChartBaseProps {
-  /**
-   * Chart title — the spine of the `aria-label` summary and (optionally) a
-   * visible caption. Required: an accessible chart always announces what it is.
-   */
-  readonly title: string;
-  /**
-   * Overrides the auto-generated `aria-label`. When omitted, each primitive
-   * builds a deterministic summary from `title` + the data.
-   */
-  readonly ariaLabel?: string;
-  /** Formats values in ticks / legend / summary. Deterministic by contract. */
-  readonly formatValue?: ChartValueFormatter;
-  /** Extra classes for the outermost wrapper. */
-  readonly className?: string;
-  /** Label rendered by the empty state when the series has no finite points. */
-  readonly emptyLabel?: string;
-}