hs-uix 2.1.1 → 2.2.0

package/src/kanban/index.d.ts

@@ -86,6 +86,13 @@ export interface KanbanStage<Row = Record<string, unknown>> {
   icon?: string;
   terminal?: boolean;
   order?: number;
+  /**
+   * WIP limit for this stage. The header shows "count / limit" and an
+   * "Over WIP" StatusTag when exceeded. 0 is valid ("stay empty"). The
+   * top-level `wipLimits` prop overrides this per stage. Advisory only —
+   * transitions that exceed the limit still complete.
+   */
+  wipLimit?: number;
   footer?: (rows: Row[]) => ReactNode;
   canEnter?: (row: Row) => boolean;
   onEnterRequired?: {
@@ -93,6 +100,46 @@ export interface KanbanStage<Row = Record<string, unknown>> {
   };
 }
 
+// ---------------------------------------------------------------------------
+// WIP limits
+// ---------------------------------------------------------------------------
+
+export interface KanbanWipStatus {
+  /** Cards counted against the limit (stageMeta.totalCount when present, else the loaded bucket size). */
+  count: number;
+  /** Effective limit (top-level override beats stage.wipLimit), or null when the stage has none. */
+  limit: number | null;
+  /** True only when count is STRICTLY greater than limit. */
+  exceeded: boolean;
+}
+
+export type KanbanWipEvaluation = Record<string, KanbanWipStatus>;
+
+export interface KanbanWipExceededEvent {
+  stageId: string;
+  count: number;
+  limit: number;
+}
+
+// ---------------------------------------------------------------------------
+// Swimlanes
+// ---------------------------------------------------------------------------
+
+export type KanbanSwimlaneBy<Row = Record<string, unknown>> =
+  | string
+  | ((row: Row) => string | number | boolean | null | undefined);
+
+export type KanbanSwimlaneLabels<Row = Record<string, unknown>> =
+  | Record<string, string>
+  | ((laneKey: string, rows: Row[]) => ReactNode);
+
+export interface KanbanLanePartition<Row = Record<string, unknown>> {
+  /** Lane keys in render order (swimlaneOrder first — including empty explicit lanes — then first-seen). */
+  laneKeys: string[];
+  /** Rows per lane in original data order. Every key in laneKeys is present. */
+  rowsByLane: Record<string, Row[]>;
+}
+
 // ---------------------------------------------------------------------------
 // Pagination
 // ---------------------------------------------------------------------------
@@ -147,6 +194,7 @@ export interface KanbanParams {
   filters: Record<string, unknown>;
   sort: string | null;
   collapsedStages: string[];
+  collapsedLanes: string[];
 }
 
 export interface KanbanEmptyStateRenderContext {
@@ -183,6 +231,13 @@ export interface KanbanLabels {
   errorTitle?: string;
   errorMessage?: string;
   cardCount?: (n: number) => string;
+  /** Stage-header count when a WIP limit is set. Default "{count} / {limit}". */
+  wipCount?: (count: number, limit: number) => string;
+  /** Warning StatusTag text on over-limit stage headers. Default "Over WIP". */
+  overWip?: string;
+  laneCount?: (n: number) => string;
+  /** Lane header label for rows whose swimlane value is null/undefined/"". Default "Unassigned". */
+  unassignedLane?: string;
   moveTo?: string;
   clearAll?: string;
   selectAll?: string | ((count: number, label: string) => string);
@@ -278,6 +333,37 @@ export interface KanbanProps<Row = Record<string, unknown>, Id = string | number
   stageMeta?: Record<string, KanbanStageMeta>;
   onLoadMore?: (stage: string) => void;
 
+  // WIP limits
+  /** Top-level per-stage limit overrides: `{ [stageId]: n }`. Beats `stage.wipLimit`. */
+  wipLimits?: Record<string, number>;
+  /**
+   * Fires when a stage TRANSITIONS into the exceeded state (count > limit) —
+   * once per crossing, including a board that mounts already over a limit;
+   * never on every render. Over-limit transitions still complete: the server
+   * is the source of truth, so WIP limits are a signal, not a gate.
+   */
+  onWipExceeded?: (stageId: string, count: number, limit: number) => void;
+
+  // Swimlanes
+  /** Field name or accessor that groups the board vertically into lanes. */
+  swimlaneBy?: KanbanSwimlaneBy<Row>;
+  /** `{ key: label }` map or `(laneKey, rows) => label` function for lane headers. */
+  swimlaneLabels?: KanbanSwimlaneLabels<Row>;
+  /** Explicit lane order. Listed keys render first (even when empty); unlisted lanes append first-seen. */
+  swimlaneOrder?: string[];
+  /** Show the collapse chevron on lane headers. Default true. */
+  collapseLanes?: boolean;
+  /** Controlled list of collapsed lane keys. */
+  collapsedLanes?: string[];
+  /** Initial collapsed lane keys (uncontrolled). */
+  defaultCollapsedLanes?: string[];
+  onCollapsedLanesChange?: (laneKeys: string[]) => void;
+  /**
+   * Render the metrics panel inside each lane instead of globally. Requires
+   * `metrics` to be a function — it's called per lane with `(laneRows, laneKey)`.
+   */
+  metricsPerLane?: boolean;
+
   // Selection
   selectable?: boolean;
   selectedIds?: Id[];
@@ -345,8 +431,16 @@ export interface KanbanProps<Row = Record<string, unknown>, Id = string | number
   onCollapsedStagesChange?: (stages: string[]) => void;
 
   // Metrics panel (toggled via the toolbar's Metrics button)
-  /** Array of stat items for the <Statistics> panel, or a custom ReactNode. */
-  metrics?: KanbanMetricItem[] | ReactNode;
+  /**
+   * Array of stat items for the <Statistics> panel, a custom ReactNode, or a
+   * function of the (filtered) rows. The function form receives
+   * `(rows, laneKey)` — laneKey is null for the global panel and the lane key
+   * when `metricsPerLane` is active.
+   */
+  metrics?:
+    | KanbanMetricItem[]
+    | ReactNode
+    | ((rows: Row[], laneKey: string | null) => KanbanMetricItem[] | ReactNode);
   /** Controlled visibility of the metrics panel. */
   showMetrics?: boolean;
   /** Fires when the Metrics button is clicked. Receives the new visible state. */
@@ -376,3 +470,60 @@ export interface KanbanProps<Row = Record<string, unknown>, Id = string | number
 export declare function Kanban<Row = Record<string, unknown>, Id = string | number>(
   props: KanbanProps<Row, Id>
 ): ReactElement | null;
+
+// ---------------------------------------------------------------------------
+// Pure lane / WIP helpers (from kanbanLanes.js) — usable outside the component,
+// e.g. to evaluate WIP server-side or render custom lane summaries.
+// ---------------------------------------------------------------------------
+
+/** Lane key used for rows whose swimlane value is null/undefined/"". */
+export declare const UNASSIGNED_LANE_KEY: "__unassigned";
+
+/** Resolve the swimlane key for a row (String-coerced; empty values map to UNASSIGNED_LANE_KEY). */
+export declare function getLaneKey<Row = Record<string, unknown>>(
+  row: Row,
+  swimlaneBy: KanbanSwimlaneBy<Row>
+): string;
+
+/** Order lane keys: explicit swimlaneOrder first (deduped, kept even when empty), then first-seen. */
+export declare function orderLaneKeys(seenKeys: string[], swimlaneOrder?: string[]): string[];
+
+/** Partition rows into swimlanes — render order plus rows per lane. */
+export declare function partitionLanes<Row = Record<string, unknown>>(
+  rows: Row[],
+  options?: { swimlaneBy?: KanbanSwimlaneBy<Row>; swimlaneOrder?: string[] }
+): KanbanLanePartition<Row>;
+
+/** Resolve a lane's display label from a map or function, with unassigned/key fallbacks. */
+export declare function resolveLaneLabel<Row = Record<string, unknown>>(
+  laneKey: string,
+  swimlaneLabels?: KanbanSwimlaneLabels<Row>,
+  rows?: Row[],
+  unassignedLabel?: string
+): ReactNode;
+
+/** Effective WIP limit for a stage (wipLimits override beats stage.wipLimit; invalid → null). */
+export declare function resolveWipLimit<Row = Record<string, unknown>>(
+  stage: KanbanStage<Row>,
+  wipLimits?: Record<string, number>
+): number | null;
+
+/** Per-stage counts for WIP evaluation (stageMeta.totalCount when present, else bucket length). */
+export declare function computeStageCounts<Row = Record<string, unknown>>(
+  stages: KanbanStage<Row>[],
+  buckets: Record<string, Row[]>,
+  stageMeta?: Record<string, KanbanStageMeta>
+): Record<string, number>;
+
+/** Evaluate `{ count, limit, exceeded }` for every stage. */
+export declare function evaluateWip<Row = Record<string, unknown>>(
+  stages: KanbanStage<Row>[],
+  counts: Record<string, number>,
+  wipLimits?: Record<string, number>
+): KanbanWipEvaluation;
+
+/** Diff two evaluations; returns stages that newly crossed into exceeded (the onWipExceeded contract). */
+export declare function findNewlyExceededWip(
+  prev: KanbanWipEvaluation | null | undefined,
+  next: KanbanWipEvaluation
+): KanbanWipExceededEvent[];

package/src/safe/README.md

@@ -0,0 +1,108 @@
+# Safe wrappers (`hs-uix/safe`)
+
+Hardened drop-ins for the components that fail worst when given bad props.
+HubSpot's primitives have two ugly failure modes:
+
+- **Silent fails** — `Icon` renders *nothing* for an invalid `name` (no error,
+  no fallback, just empty space). `StatisticsTrend` rejects any `direction`
+  that isn't exactly `"increase"`/`"decrease"`.
+- **Throw-blanks-page** — `EmptyState` throws on a bad `imageName`, and
+  collection components (`DataTable`, `Select`, …) throw inside HubSpot's
+  reconciler when a required array prop arrives `undefined` — which blanks the
+  **whole extension** in production.
+
+Every wrapper here keeps the native prop API and turns those failures into
+safe degrades plus a **one-time** `console.warn`. They were battle-tested in
+[hs-uix-studio](https://github.com/05bmckay/hs-uix-studio)'s renderer, where
+LLM-generated UIs hit every one of these traps constantly.
+
+## Quick Start
+
+```jsx
+import {
+  SafeIcon,        // bad name → alias repair, else red xCircle placeholder
+  SafeEmptyState,  // bad imageName → known alias or "components", not a throw
+  SafeDataTable,   // data/columns/… undefined → [] (empty table, not a blank page)
+  SafePopover,     // children auto-padded in a compact Tile
+} from "hs-uix/safe";
+
+<SafeIcon name="duplicate" />        {/* renders "copy", warns once */}
+<SafeEmptyState imageName="new-project" title="Nothing here" />
+<SafeDataTable data={rows} columns={columns} />  {/* rows may be undefined while loading */}
+```
+
+## What's included
+
+### Repairing wrappers (native components)
+
+| Component | Repairs | Behavior |
+|---|---|---|
+| `SafeIcon` | `name` | Valid → native pass-through. Known alias (`duplicate`→`copy`, `alert`→`warning`, `trash`→`delete`, …) → repaired with one-time warn. Unknown → alert-colored `xCircle` placeholder with `screenReaderText="Invalid icon: <name>"`. |
+| `SafeEmptyState` | `imageName` | `null`/valid → pass-through. Known alias (`new-project`→`components`, …) or unknown → falls back (default `"components"`) instead of throwing. |
+| `SafeStatisticsTrend` | `direction` | Valid / non-string → pass-through. Alias (`increasing`, `up`, `positive`, …) → repaired. Unknown string → `"increase"`. |
+| `SafePopover` | padding | Wraps children in `<Tile compact>` so popover content gets default padding (the experimental Popover renders children flush). Nesting your own Tile still works. |
+
+### Array-coercing wrappers
+
+Required collection props are forced to arrays: `null`/`undefined` → `[]`
+silently, any other non-array → `[]` with a one-time warn. The component's own
+empty state renders instead of the page blanking. Refs forward through, so
+`SafeFormBuilder` keeps FormBuilder's imperative ref API.
+
+| Component | Coerced props |
+|---|---|
+| `SafeSelect` / `SafeMultiSelect` / `SafeToggleGroup` | `options` |
+| `SafeStepIndicator` | `stepNames` |
+| `SafeDataTable` | `data`, `columns`, `searchFields`, `filters`, `selectionActions` |
+| `SafeKanban` | `data`, `stages` |
+| `SafeFormBuilder` | `fields` |
+| `SafeAvatarStack` / `SafeKeyValueList` | `items` |
+| `SafeFeed` | `items`, `fields` |
+| `SafeCalendar` | `events` |
+| `SafeCrmKanban` | `cardFields` |
+
+`SafeCrmDataTable.columns` and `SafeCrmKanban.stages` are different: those
+props **auto-derive when omitted** (columns from CRM properties, stages from
+the batch), and a coerced `[]` would silently turn derivation off. They pass
+`null`/`undefined` through untouched, and an invalid non-array is *dropped*
+(with a warn) so the derive path takes over.
+
+Wrap anything else yourself:
+
+```js
+import { withSafeArrayProps, SAFE_ARRAY_PROPS, SAFE_DERIVE_PROPS } from "hs-uix/safe";
+
+const SafeMyList = withSafeArrayProps(MyList, "MyList", ["entries"]);
+// withSafeArrayProps(Component, name, arrayProps, deriveProps?) — the
+// SAFE_ARRAY_PROPS / SAFE_DERIVE_PROPS registries hold the lists used above
+```
+
+### Catalogs
+
+The validation data is exported for building your own linting/repair layers
+(spec validators, codegen checks):
+
+| Export | Contents |
+|---|---|
+| `NATIVE_ICON_NAMES` | the native `<Icon>` `name` whitelist (190 names) |
+| `ICON_NAME_ALIASES` | common mistakes → nearest valid icon |
+| `EMPTY_STATE_IMAGES` / `EMPTY_STATE_IMAGE_ALIASES` | valid `imageName` values + repairs |
+| `TREND_DIRECTIONS` / `TREND_DIRECTION_ALIASES` | valid `direction` values + repairs |
+| `SAFE_ARRAY_PROPS` | required collection props per component |
+
+### Warnings
+
+Each distinct problem warns **once** per session (a bad icon name in a 50-row
+table logs one line, not fifty). `resetSafeWarnings()` clears the dedup memory
+(useful in tests); `warnOnce(key, message)` is the underlying helper.
+
+## When to use
+
+- Rendering **model-generated or user-configured** UI, where prop values are
+  data, not code you control.
+- Any surface where `props.data` comes from an async source that can resolve
+  `undefined` — the Safe collection components keep the page alive while you
+  fix the data path.
+
+If your props are static and hand-written, the natives are fine — these
+wrappers add one function call per render and nothing else.

package/src/safe/index.d.ts

@@ -0,0 +1,158 @@
+import type { ComponentType, ReactNode } from "react";
+import type { DataTableProps } from "../datatable/index";
+import type { KanbanProps } from "../kanban/index";
+import type { FormBuilderProps } from "../form/index";
+import type { FeedItem, FeedProps } from "../feed/index";
+import type { CalendarProps } from "../calendar/index";
+import type { AvatarStackProps, KeyValueListProps } from "../../common-components";
+import type { CrmDataTableProps, CrmKanbanProps } from "../../utils";
+
+// ---------------------------------------------------------------------------
+// Catalogs
+// ---------------------------------------------------------------------------
+
+/** The native <Icon> `name` whitelist. */
+export declare const NATIVE_ICON_NAMES: ReadonlySet<string>;
+/** Common icon-name mistakes → the nearest valid native name. */
+export declare const ICON_NAME_ALIASES: Readonly<Record<string, string>>;
+/** Valid EmptyState `imageName` values. */
+export declare const EMPTY_STATE_IMAGES: ReadonlySet<string>;
+/** Common imageName mistakes → a valid value. */
+export declare const EMPTY_STATE_IMAGE_ALIASES: Readonly<Record<string, string>>;
+/** Valid StatisticsTrend `direction` values ("increase" | "decrease"). */
+export declare const TREND_DIRECTIONS: ReadonlySet<string>;
+/** Common direction mistakes ("increasing", "up", …) → a valid value. */
+export declare const TREND_DIRECTION_ALIASES: Readonly<Record<string, string>>;
+/** Required collection props per component name (coerced to []), as used by the Safe* exports. */
+export declare const SAFE_ARRAY_PROPS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Auto-derived-when-omitted collection props (CrmDataTable columns, CrmKanban
+ * stages). Never coerced to [] — that would suppress the derive path; invalid
+ * non-array values are dropped instead.
+ */
+export declare const SAFE_DERIVE_PROPS: Readonly<Record<string, readonly string[]>>;
+
+// ---------------------------------------------------------------------------
+// Warning dedup
+// ---------------------------------------------------------------------------
+
+/** console.warn `message` the first time `key` is seen; no-op after that. */
+export declare function warnOnce(key: string, message: string): void;
+/** Clear the warn-once memory — for tests or long-lived sessions. */
+export declare function resetSafeWarnings(): void;
+
+// ---------------------------------------------------------------------------
+// Generic hardening wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap any component so the listed props are always arrays: null/undefined
+ * coerce to [] silently, any other non-array coerces to [] with a one-time
+ * console.warn. `derivePropNames` lists auto-derived-when-omitted props,
+ * which instead pass null/undefined through and DROP invalid non-arrays so
+ * the component's own derivation still runs. Refs forward through. Returns a
+ * drop-in with displayName `Safe<componentName>`.
+ */
+export declare function withSafeArrayProps<Props extends object>(
+  Component: ComponentType<Props>,
+  componentName: string,
+  propNames: ReadonlyArray<string>,
+  derivePropNames?: ReadonlyArray<string>
+): ComponentType<Props>;
+
+// ---------------------------------------------------------------------------
+// Hardened native components (drop-ins for @hubspot/ui-extensions)
+// ---------------------------------------------------------------------------
+
+export interface SafeIconProps {
+  /** Native icon name. Known aliases auto-repair; anything else renders an alert-colored xCircle placeholder. */
+  name: string;
+  color?: "alert" | "warning" | "success" | "inherit";
+  size?: "sm" | "small" | "md" | "medium" | "lg" | "large";
+  screenReaderText?: string;
+  [prop: string]: unknown;
+}
+
+export interface SafeEmptyStateProps {
+  /** Invalid values fall back to a known alias or "components" instead of throwing. */
+  imageName?: string;
+  children?: ReactNode;
+  [prop: string]: unknown;
+}
+
+export interface SafeStatisticsTrendProps {
+  /** "increase" | "decrease"; aliases like "increasing"/"up" auto-repair, anything else defaults to "increase". */
+  direction?: "increase" | "decrease" | (string & {});
+  value?: string;
+  [prop: string]: unknown;
+}
+
+export interface SafePopoverProps {
+  /** Wrapped in a compact <Tile> so content gets default padding. */
+  children?: ReactNode;
+  [prop: string]: unknown;
+}
+
+export interface SafeOptionsProps {
+  /** Coerced to [] when missing or non-array. */
+  options?: Array<Record<string, unknown>> | null;
+  [prop: string]: unknown;
+}
+
+export interface SafeStepIndicatorProps {
+  /** Coerced to [] when missing or non-array. */
+  stepNames?: string[] | null;
+  [prop: string]: unknown;
+}
+
+export declare const SafeIcon: ComponentType<SafeIconProps>;
+export declare const SafeEmptyState: ComponentType<SafeEmptyStateProps>;
+export declare const SafeStatisticsTrend: ComponentType<SafeStatisticsTrendProps>;
+export declare const SafePopover: ComponentType<SafePopoverProps>;
+export declare const SafeSelect: ComponentType<SafeOptionsProps>;
+export declare const SafeMultiSelect: ComponentType<SafeOptionsProps>;
+export declare const SafeToggleGroup: ComponentType<SafeOptionsProps>;
+export declare const SafeStepIndicator: ComponentType<SafeStepIndicatorProps>;
+
+// ---------------------------------------------------------------------------
+// Hardened hs-uix components — same props as the originals, except the
+// coerced collection props (see SAFE_ARRAY_PROPS / SAFE_DERIVE_PROPS) also
+// accept null/undefined, matching the runtime tolerance that is the point of
+// these wrappers.
+// ---------------------------------------------------------------------------
+
+/** The original props with the hardened collection props widened to optional-and-nullable. */
+type WithNullableArrays<Props, K extends keyof Props> = Omit<Props, K> & {
+  [P in K]?: Props[P] | null;
+};
+
+export declare function SafeDataTable<Row = Record<string, unknown>>(
+  props: WithNullableArrays<
+    DataTableProps<Row>,
+    "data" | "columns" | "searchFields" | "filters" | "selectionActions"
+  >
+): ReactNode;
+export declare function SafeKanban<Row = Record<string, unknown>, Id = string | number>(
+  props: WithNullableArrays<KanbanProps<Row, Id>, "data" | "stages">
+): ReactNode;
+export declare const SafeFormBuilder: ComponentType<
+  WithNullableArrays<FormBuilderProps, "fields">
+>;
+export declare function SafeFeed<Row = FeedItem>(
+  props: WithNullableArrays<FeedProps<Row>, "items" | "fields">
+): ReactNode;
+export declare function SafeCalendar<Event = Record<string, unknown>>(
+  props: WithNullableArrays<CalendarProps<Event>, "events">
+): ReactNode;
+export declare const SafeAvatarStack: ComponentType<
+  WithNullableArrays<AvatarStackProps, "items">
+>;
+export declare const SafeKeyValueList: ComponentType<
+  WithNullableArrays<KeyValueListProps, "items">
+>;
+export declare function SafeCrmDataTable<Row = Record<string, unknown>>(
+  props: WithNullableArrays<CrmDataTableProps<Row>, "columns">
+): ReactNode;
+export declare function SafeCrmKanban<Row = Record<string, unknown>>(
+  props: WithNullableArrays<CrmKanbanProps<Row>, "stages" | "cardFields">
+): ReactNode;

package/src/utils/README.md

@@ -12,6 +12,7 @@ Pure helper functions for formatting, mapping, guards, and lightweight data tran
 - `viewAdapters.js` — shape transforms between DataTable columns and Kanban cardFields (power a single "same data, different view" toggle)
 - `query.js` — shared collection query helpers: empty filter values, filter reset, active-filter chips, filtering, and search
 - `crmSearchAdapters.js` — CRM-bound data components (`CrmDataTable`, `CrmKanban`) plus the lower-level CRM search hooks and config builders behind them
+- `applyPatches.js` — RFC 6902 JSON Patch applier (add/replace/remove/move/copy) with structural sharing, built for streaming-UI flows
 
 ## Purpose
 
@@ -503,6 +504,44 @@ If you need to drive a custom view, the hooks and helpers are exported directly:
 
 ---
 
+## applyPatches.js
+
+RFC 6902 JSON Patch applier — the minimal subset that streaming UIs need.
+Supported ops: `add`, `replace`, `remove`, `move`, `copy`; anything else
+(including `test`) is skipped with a console warning.
+
+### `applyPatches(doc, patches)`
+
+```js
+import { applyPatches } from "hs-uix/utils";
+
+const doc = { meta: { title: "Dashboard" }, rows: [] };
+
+const next = applyPatches(doc, [
+  { op: "replace", path: "/meta/title", value: "Pipeline" },
+  { op: "add", path: "/rows/-", value: { id: "r1" } },
+]);
+// → { meta: { title: "Pipeline" }, rows: [{ id: "r1" }] }
+
+next === doc;          // → false (never mutates input)
+next.meta === doc.meta; // → false (changed branch)
+```
+
+Behavior worth knowing:
+
+| Behavior | Detail |
+|---|---|
+| Immutability | Returns a **new** document; untouched branches keep reference equality (structural sharing), so memoized renderers only re-render what changed. |
+| Permissive paths | Where RFC 6902 would error on a missing path prefix, `add`/`replace` create it — objects by default, arrays when the next segment is numeric or `-`. Built for patch streams where `/elements/x/props` can arrive before `/elements`. |
+| Root pointer | `path: ""` (or `"/"`) replaces the whole document. |
+| Array `add` vs `replace` | Per RFC 6902, `add` at an existing index **inserts** (shifts the rest right); `replace` overwrites in place. The standard `-` index appends (`{ op: "add", path: "/rows/-", value }`). |
+| Array `remove` | An invalid or out-of-range index (`/rows/-`, `/rows/foo`, `/rows/99`) is a safe no-op — same spirit as removing a missing object key. |
+| Escaping | Standard RFC 6901 unescaping: `~1` → `/`, `~0` → `~`. |
+| `copy` / `move` | `copy` deep-clones the source (JSON-safe values only — no `Date`/`Map`/`Set`). Pointers resolve own properties only, so `/constructor`-style segments read as missing instead of leaking functions into the document. |
+| Null doc | `applyPatches(null, patches)` starts from `{}`. Empty/missing `patches` returns the input as-is. |
+
+---
+
 ## Guidelines
 
 - Keep helpers pure and side-effect free

package/src/wizard/README.md

@@ -0,0 +1,158 @@
+# Wizard (hs-uix/experimental)
+
+Orchestrated multi-step flows for HubSpot UI Extensions — plus the "getting started" checklist card. `Wizard` steps render **arbitrary content** (tables, CRM pickers, review summaries — anything), which makes it the right tool when FormBuilder's form-only multi-step mode isn't enough. The Wizard owns the orchestration: a shared values bag, validate-gated Next, linear step reachability with success markers, a side step-nav (vertical) or native StepIndicator (horizontal), and a Back/Next/Finish footer. `OnboardingChecklist` is the companion setup tracker: a ProgressBar headline over rows of done/pending tasks with inline action buttons.
+
+## Quick Start
+
+```jsx
+import { Wizard } from "hs-uix/experimental";
+import { Input, Flex, Text } from "@hubspot/ui-extensions";
+
+<Wizard
+  steps={[
+    {
+      id: "details",
+      title: "Details",
+      description: "Who is this for?",
+      render: ({ values, setValues }) => (
+        <Input
+          name="email"
+          label="Email"
+          value={values.email || ""}
+          onChange={(email) => setValues({ email })}
+        />
+      ),
+      validate: ({ values }) => (values.email ? true : "Email is required."),
+    },
+    {
+      id: "options",
+      title: "Options",
+      optional: true,
+      render: ({ values, setValues }) => (
+        <Flex direction="column" gap="xs">{/* anything */}</Flex>
+      ),
+    },
+    {
+      id: "review",
+      title: "Review",
+      render: ({ values }) => <Text>Sending to {values.email || "--"}</Text>,
+    },
+  ]}
+  onComplete={(values) => createRecord(values)}
+/>
+```
+
+```jsx
+import { OnboardingChecklist } from "hs-uix/experimental";
+
+<OnboardingChecklist
+  title="Getting started"
+  items={[
+    { id: "connect", title: "Connect your calendar", done: true },
+    {
+      id: "import",
+      title: "Import contacts",
+      description: "CSV or CRM sync",
+      done: false,
+      action: { label: "Import", onClick: openImportPanel },
+    },
+  ]}
+  onItemClick={(item) => openDetail(item.id)}
+/>
+```
+
+## Features
+
+- **Arbitrary step content** — each step's `render(ctx)` returns any node; the wizard is layout, navigation, and gating only.
+- **Shared values bag** — `ctx.values` / `ctx.setValues` let steps accumulate data; `onComplete(values)` hands the finished bag back.
+- **Validate gating** — a step's `validate(ctx)` returning a non-empty string blocks Next/Finish and renders the message as an inline error `Alert`.
+- **Linear reachability** — future steps are disabled until every prior required step is completed; `optional` steps are skippable; `allowJumpAhead` opens everything.
+- **Side step-nav** (vertical, default): `checkCircle` success markers for completed steps, filled circle for the current step, hollow circles for upcoming; reachable steps are clickable Links.
+- **Native StepIndicator** (horizontal): `stepNames` + `currentStep` + click-to-navigate, with `stepIndicatorProps` pass-through.
+- **Back / Next / Finish footer** — secondary Back (disabled on the first step), primary Next/Finish; replace it wholesale with `renderFooter`.
+- **Controlled or uncontrolled** — `step` / `defaultStep` / `onStepChange`, by step id or index.
+- **OnboardingChecklist** — native `ProgressBar` (done/total), success-marker rows, inline action buttons, optional Accordion collapse that defaults open while work remains.
+
+## Review / summary step
+
+A review step is just a step that renders the values bag. Pair it with `KeyValueList` from `hs-uix/common-components`:
+
+```jsx
+import { KeyValueList } from "hs-uix/common-components";
+
+{
+  id: "review",
+  title: "Review",
+  description: "Confirm before creating the record.",
+  render: ({ values, goTo }) => (
+    <Flex direction="column" gap="sm">
+      <KeyValueList
+        items={[
+          { label: "Email", value: values.email },
+          { label: "Plan", value: values.plan },
+        ]}
+      />
+      <Link onClick={() => goTo("details")}>Edit details</Link>
+    </Flex>
+  ),
+}
+```
+
+The Finish button on the last step runs that step's `validate` (if any) and then calls `onComplete(values)`.
+
+## `<Wizard>` props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `steps` | `WizardStep[]` | `[]` | `{ id, title, description?, optional?, render?, validate? }`. Missing ids become `step-<index>`. |
+| `step` | `string \| number` | — | Controlled current step (id or zero-based index). |
+| `defaultStep` | `string \| number` | `0` | Initial step when uncontrolled. |
+| `onStepChange` | `(stepId, stepIndex) => void` | — | Fires on every transition (Next, Back, nav click). |
+| `onComplete` | `(values) => void` | — | Finish pressed on the last step and its validate passed. |
+| `defaultValues` | `object` | `{}` | Initial contents of the shared values bag. |
+| `onValuesChange` | `(values) => void` | — | Observer for every `setValues` call. |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Vertical = side step-nav; horizontal = native StepIndicator above content. |
+| `showStepNav` | `boolean` | `true` | Hide the nav entirely (footer still navigates). |
+| `allowJumpAhead` | `boolean` | `false` | Let users click any future step without completing prior ones. |
+| `showStepHeader` | `boolean` | `true` | Render the active step's title/description above its content. |
+| `labels` | `WizardLabels` | — | `{ back, next, finish, optional, errorTitle }` overrides. |
+| `renderFooter` | `(ctx) => node` | — | Replaces the footer; ctx adds `{ isFirst, isLast, error, labels }`. |
+| `navFlex` / `contentFlex` | `number` | `1` / `3` | Flex ratios for the vertical layout columns. |
+| `stepIndicatorProps` | `object` | — | Spread onto the native StepIndicator (e.g. `variant="compact"`). |
+
+### Step context (`ctx`)
+
+Passed to `render`, `validate`, and `renderFooter`:
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `stepId` | `string` | Active step id. |
+| `stepIndex` | `number` | Zero-based index. |
+| `goNext()` | `() => void` | Validates, then advances (or completes on the last step). |
+| `goBack()` | `() => void` | Previous step — never gated. |
+| `goTo(stepOrId)` | `(string \| number) => void` | No-op when the target isn't reachable. |
+| `values` | `object` | Shared values bag. |
+| `setValues(patch)` | `(object \| fn) => void` | Object patches shallow-merge; updater functions replace. |
+
+### Gating rules
+
+- **Back** is never gated; revisiting a completed step keeps its success marker.
+- **Next/Finish** runs the active step's `validate(ctx)`. A non-empty string blocks and shows an error Alert; `true`/`undefined`/`false` pass. Validation is sync-only.
+- A future step is clickable only when every step before it is completed or `optional` (linear), or when `allowJumpAhead` is on.
+- Completion is recorded per step id and is not invalidated by later edits — re-validate in `onComplete` if steps can be undone retroactively.
+
+## `<OnboardingChecklist>` props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `items` | `OnboardingChecklistItem[]` | `[]` | `{ id, title, description?, done, action? }`; `action` is `{ label, onClick, variant?, disabled? }`. |
+| `title` | `ReactNode` | — | Card heading (Accordion title in collapsible mode). |
+| `description` | `ReactNode` | — | Microcopy under the heading (non-collapsible mode only). |
+| `progress` | `boolean` | `true` | Show the `ProgressBar` headline (`value=done`, `maxValue=total`). |
+| `onItemClick` | `(item) => void` | — | Makes item titles clickable Links. |
+| `collapsible` | `boolean` | `false` | Wrap in an Accordion; defaults open while items remain incomplete. |
+| `defaultOpen` | `boolean` | data-driven | Override the collapsible default-open behavior. |
+| `showCompletedActions` | `boolean` | `false` | Keep action buttons on done rows. |
+| `labels` | `{ progress }` | — | `progress(done, total)` formats the bar's value description. |
+
+Completion is data-driven: the host marks items `done`. The checklist renders state, it never owns it.