@happyvertical/smrt-ui 0.51.38 → 0.52.0

package/dist/components/data/list-sort-state.svelte.js

@@ -0,0 +1,47 @@
+/**
+ * Reactive list-sort state for pages — the one object a list's headers
+ * (`SortableHeader list={...}`), phone picker (`ListSortSelect list={...}`),
+ * rows (`sortListRows(rows, list.sort, ...)`), and data surface (`sort` /
+ * `onSort`) share. Call during component initialisation.
+ *
+ * - `createUrlListSort(spec, { url, navigate })` — server-paginated lists:
+ *   the sort lives in the URL (`?sort=&dir=`); headers are links, and `set`
+ *   navigates. Framework-agnostic: pass the router's current URL and its
+ *   navigate function (SvelteKit: `() => page.url` and `goto`).
+ * - `createLocalListSort(spec)` — lists that load every row: page state.
+ */
+import { isValidListSort, listSortHref, parseListSort, toggleListSort, } from './list-sort.js';
+export function createUrlListSort(spec, options) {
+    const sort = $derived(parseListSort(options.url().searchParams, spec));
+    return {
+        get sort() {
+            return sort;
+        },
+        spec,
+        href: (columnId) => listSortHref(options.url(), toggleListSort(sort, columnId, spec), spec),
+        toggle: () => { },
+        set: (next) => {
+            if (!isValidListSort(spec, next))
+                return;
+            return options.navigate(listSortHref(options.url(), next, spec));
+        },
+    };
+}
+export function createLocalListSort(spec, initial) {
+    let sort = $state(isValidListSort(spec, initial) ? { ...initial } : { ...spec.default });
+    return {
+        get sort() {
+            return sort;
+        },
+        spec,
+        href: () => undefined,
+        toggle: (columnId) => {
+            sort = toggleListSort(sort, columnId, spec);
+        },
+        set: (next) => {
+            if (!isValidListSort(spec, next))
+                return;
+            sort = { columnId: next.columnId, direction: next.direction };
+        },
+    };
+}

package/dist/components/data/list-sort.d.ts

@@ -0,0 +1,94 @@
+/**
+ * List sorting — one contract for every list, client or server paginated.
+ *
+ * - A list declares its sortable columns and a default sort (usually its main
+ *   date column, newest first).
+ * - Clicking a header toggles that column between ascending and descending;
+ *   a column not yet sorted starts at its `firstDirection` (dates and numbers
+ *   usually `desc`, text `asc`). Sorting never "clears" back to unsorted: the
+ *   list always has one well-defined order.
+ * - Server-paginated lists keep the sort in the URL (`?sort=<column>&dir=<asc|desc>`)
+ *   so the database orders the WHOLE result set, not just the current page.
+ *   The default sort is omitted from the URL, and changing the sort drops the
+ *   page parameter (back to page 1).
+ * - Values are validated against the declared columns, so a URL or an agent
+ *   command can only pick a declared column and a known direction.
+ *
+ * Pure functions, no Svelte or DOM: usable in `+page.server.ts` loads,
+ * components, and data-surface handlers alike.
+ */
+export type ListSortDirection = 'asc' | 'desc';
+export interface ListSort {
+    columnId: string;
+    direction: ListSortDirection;
+}
+export interface ListSortColumnSpec {
+    id: string;
+    /** Direction on the first click of this column (default `asc`; use `desc` for dates and counts). */
+    firstDirection?: ListSortDirection;
+}
+/** A column offered by `ListSortSelect` (the phone / card-list sort picker). */
+export interface ListSortSelectColumn {
+    id: string;
+    label: string;
+    /** Picks the plain words: dates "newest first", numbers "highest first", text "A–Z". */
+    kind?: 'date' | 'number' | 'text';
+}
+export interface ListSortSpec {
+    /** Sortable columns. Ids are what the URL and agents use. */
+    columns: readonly (ListSortColumnSpec | string)[];
+    /** The list's order with no `sort` parameter. Must name a declared column. */
+    default: ListSort;
+    /** Query parameter names (default `sort` and `dir`). */
+    sortParam?: string;
+    dirParam?: string;
+    /** Page parameter to drop when the sort changes (default `page`; `null` keeps it). */
+    pageParam?: string | null;
+}
+/** The ids of the sortable columns. */
+export declare function listSortColumnIds(spec: ListSortSpec): string[];
+/** Whether `sort` names a declared column and a known direction. */
+export declare function isValidListSort(spec: ListSortSpec, sort: Partial<ListSort> | null | undefined): sort is ListSort;
+/**
+ * Read the sort from URL parameters. An unknown column falls back to the
+ * default; a missing or unknown direction falls back to the column's first
+ * direction (or the default's direction for the default column).
+ */
+export declare function parseListSort(params: URLSearchParams | {
+    get(name: string): string | null;
+}, spec: ListSortSpec): ListSort;
+/** The sort after activating a column's header (toggle; never cleared). */
+export declare function toggleListSort(current: ListSort, columnId: string, spec: ListSortSpec): ListSort;
+/**
+ * URL parameters for `sort`: sets (or, for the default, removes) the sort
+ * parameters and drops the page parameter when the sort changed.
+ */
+export declare function listSortSearchParams(params: URLSearchParams | string, sort: ListSort, spec: ListSortSpec): URLSearchParams;
+/** `?query` string (with the leading `?`, or `''`) for a sort link. */
+export declare function listSortHref(url: URL | {
+    pathname: string;
+    search: string;
+}, sort: ListSort, spec: ListSortSpec): string;
+/** `aria-sort` for a header cell. */
+export declare function listSortAria(current: ListSort | null | undefined, columnId: string): 'ascending' | 'descending' | 'none';
+/** A plain-language label for the header's action, e.g. "Sort by Date, newest first". */
+export declare function listSortActionLabel(current: ListSort | null | undefined, columnId: string, label: string, spec?: ListSortSpec): string;
+export type ListSortValue = string | number | boolean | Date | null | undefined;
+/**
+ * Compare two values for `direction`. Empty values (null, undefined, '',
+ * invalid dates) always sort last. Strings compare with `localeCompare`
+ * (numeric-aware, case-insensitive).
+ */
+export declare function compareListValues(left: ListSortValue, right: ListSortValue, direction: ListSortDirection): number;
+/** A sorted copy of `rows` (stable; empties last). */
+export declare function sortListRows<T>(rows: readonly T[], sort: ListSort | null | undefined, getValue: (row: T, columnId: string) => ListSortValue): T[];
+/**
+ * Resolve a sort to an allow-listed ORDER BY term for a server query. `map`
+ * names the SQL expression (or ORM field) for each sortable column; the
+ * result is only ever built from `map` values, never from the input.
+ * Returns e.g. `COALESCE(c.publish_date, c.created_at) DESC NULLS LAST`.
+ */
+export declare function listSortOrderBy(sort: ListSort, map: Readonly<Record<string, string>>, options?: {
+    nulls?: 'last' | 'first' | false;
+}): string;
+//# sourceMappingURL=list-sort.d.ts.map

package/dist/components/data/list-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sort.d.ts","sourceRoot":"","sources":["../../../src/components/data/list-sort.ts"],"names":[],"mappings":"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"}

package/dist/components/data/list-sort.js

@@ -0,0 +1,182 @@
+/**
+ * List sorting — one contract for every list, client or server paginated.
+ *
+ * - A list declares its sortable columns and a default sort (usually its main
+ *   date column, newest first).
+ * - Clicking a header toggles that column between ascending and descending;
+ *   a column not yet sorted starts at its `firstDirection` (dates and numbers
+ *   usually `desc`, text `asc`). Sorting never "clears" back to unsorted: the
+ *   list always has one well-defined order.
+ * - Server-paginated lists keep the sort in the URL (`?sort=<column>&dir=<asc|desc>`)
+ *   so the database orders the WHOLE result set, not just the current page.
+ *   The default sort is omitted from the URL, and changing the sort drops the
+ *   page parameter (back to page 1).
+ * - Values are validated against the declared columns, so a URL or an agent
+ *   command can only pick a declared column and a known direction.
+ *
+ * Pure functions, no Svelte or DOM: usable in `+page.server.ts` loads,
+ * components, and data-surface handlers alike.
+ */
+function columnSpecs(spec) {
+    return spec.columns.map((column) => typeof column === 'string' ? { id: column } : column);
+}
+function columnSpec(spec, columnId) {
+    return columnSpecs(spec).find((column) => column.id === columnId);
+}
+function isDirection(value) {
+    return value === 'asc' || value === 'desc';
+}
+/** The ids of the sortable columns. */
+export function listSortColumnIds(spec) {
+    return columnSpecs(spec).map((column) => column.id);
+}
+/** Whether `sort` names a declared column and a known direction. */
+export function isValidListSort(spec, sort) {
+    return (!!sort &&
+        typeof sort.columnId === 'string' &&
+        columnSpec(spec, sort.columnId) !== undefined &&
+        isDirection(sort.direction));
+}
+/**
+ * Read the sort from URL parameters. An unknown column falls back to the
+ * default; a missing or unknown direction falls back to the column's first
+ * direction (or the default's direction for the default column).
+ */
+export function parseListSort(params, spec) {
+    const columnId = params.get(spec.sortParam ?? 'sort');
+    const direction = params.get(spec.dirParam ?? 'dir');
+    const column = columnId ? columnSpec(spec, columnId) : undefined;
+    if (!column) {
+        return isDirection(direction) && !columnId
+            ? { columnId: spec.default.columnId, direction }
+            : { ...spec.default };
+    }
+    if (isDirection(direction))
+        return { columnId: column.id, direction };
+    return {
+        columnId: column.id,
+        direction: column.id === spec.default.columnId
+            ? spec.default.direction
+            : (column.firstDirection ?? 'asc'),
+    };
+}
+/** The sort after activating a column's header (toggle; never cleared). */
+export function toggleListSort(current, columnId, spec) {
+    const column = columnSpec(spec, columnId);
+    if (!column)
+        return current;
+    if (current.columnId === columnId) {
+        return {
+            columnId,
+            direction: current.direction === 'asc' ? 'desc' : 'asc',
+        };
+    }
+    return { columnId, direction: column.firstDirection ?? 'asc' };
+}
+/**
+ * URL parameters for `sort`: sets (or, for the default, removes) the sort
+ * parameters and drops the page parameter when the sort changed.
+ */
+export function listSortSearchParams(params, sort, spec) {
+    const next = new URLSearchParams(params);
+    const sortParam = spec.sortParam ?? 'sort';
+    const dirParam = spec.dirParam ?? 'dir';
+    const previous = parseListSort(next, spec);
+    const isDefault = sort.columnId === spec.default.columnId &&
+        sort.direction === spec.default.direction;
+    if (isDefault) {
+        next.delete(sortParam);
+        next.delete(dirParam);
+    }
+    else {
+        next.set(sortParam, sort.columnId);
+        next.set(dirParam, sort.direction);
+    }
+    const pageParam = spec.pageParam === undefined ? 'page' : spec.pageParam;
+    if (pageParam &&
+        (previous.columnId !== sort.columnId ||
+            previous.direction !== sort.direction)) {
+        next.delete(pageParam);
+    }
+    return next;
+}
+/** `?query` string (with the leading `?`, or `''`) for a sort link. */
+export function listSortHref(url, sort, spec) {
+    const query = listSortSearchParams(url.search, sort, spec).toString();
+    return `${url.pathname}${query ? `?${query}` : ''}`;
+}
+/** `aria-sort` for a header cell. */
+export function listSortAria(current, columnId) {
+    if (!current || current.columnId !== columnId)
+        return 'none';
+    return current.direction === 'asc' ? 'ascending' : 'descending';
+}
+/** A plain-language label for the header's action, e.g. "Sort by Date, newest first". */
+export function listSortActionLabel(current, columnId, label, spec) {
+    const next = spec
+        ? toggleListSort(current ?? spec.default, columnId, spec).direction
+        : current?.columnId === columnId && current.direction === 'asc'
+            ? 'desc'
+            : 'asc';
+    return `Sort by ${label}, ${next === 'asc' ? 'ascending' : 'descending'}`;
+}
+function comparable(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (value instanceof Date) {
+        const time = value.getTime();
+        return Number.isNaN(time) ? null : time;
+    }
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    return value;
+}
+/**
+ * Compare two values for `direction`. Empty values (null, undefined, '',
+ * invalid dates) always sort last. Strings compare with `localeCompare`
+ * (numeric-aware, case-insensitive).
+ */
+export function compareListValues(left, right, direction) {
+    const a = comparable(left);
+    const b = comparable(right);
+    if (a === null && b === null)
+        return 0;
+    if (a === null)
+        return 1;
+    if (b === null)
+        return -1;
+    const sign = direction === 'asc' ? 1 : -1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return (a - b) * sign;
+    return (String(a).localeCompare(String(b), undefined, {
+        numeric: true,
+        sensitivity: 'base',
+    }) * sign);
+}
+/** A sorted copy of `rows` (stable; empties last). */
+export function sortListRows(rows, sort, getValue) {
+    if (!sort)
+        return [...rows];
+    return rows
+        .map((row, index) => ({ row, index }))
+        .sort((left, right) => compareListValues(getValue(left.row, sort.columnId), getValue(right.row, sort.columnId), sort.direction) || left.index - right.index)
+        .map((entry) => entry.row);
+}
+/**
+ * Resolve a sort to an allow-listed ORDER BY term for a server query. `map`
+ * names the SQL expression (or ORM field) for each sortable column; the
+ * result is only ever built from `map` values, never from the input.
+ * Returns e.g. `COALESCE(c.publish_date, c.created_at) DESC NULLS LAST`.
+ */
+export function listSortOrderBy(sort, map, options = {}) {
+    const expression = Object.hasOwn(map, sort.columnId)
+        ? map[sort.columnId]
+        : undefined;
+    if (!expression) {
+        throw new Error(`Unknown sort column: ${sort.columnId}`);
+    }
+    const nulls = options.nulls === undefined ? 'last' : options.nulls;
+    return `${expression} ${sort.direction === 'asc' ? 'ASC' : 'DESC'}${nulls ? ` NULLS ${nulls === 'last' ? 'LAST' : 'FIRST'}` : ''}`;
+}

package/dist/components/data/step-surface.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A multi-step flow (a wizard, a setup checklist) as a mounted data surface,
+ * so an agent can see where a person is and move the flow forward.
+ *
+ * The published state lists the steps (`state.steps`: id, label, status) and
+ * the current one. Three controls move between them:
+ *
+ * - `next` — advance from the current step. A step whose forward button only
+ *   checks input and shows the next step runs the page's `next` handler, the
+ *   same function the button calls. A step whose forward button SAVES or
+ *   CREATES something (`nextWrites`) is never pressed by an agent: `next`
+ *   reveals and highlights that button instead, and publishes
+ *   `awaitingPerson: true` until the page moves on. People apply writes.
+ * - `back` — return to the previous step (never a write).
+ * - `go-to` — jump to a step the page marks `available` (payload
+ *   `{ target }`: a step id or label).
+ *
+ * A handler that returns `false` (validation failed) refuses the command, so
+ * the agent sees the step did not change and can read the form's errors.
+ */
+import type { DataSurfaceDescriptor, DataSurfaceJsonValue, DataSurfaceRegistry, DataSurfaceSubject } from '@happyvertical/smrt-types';
+export interface StepSurfaceStep {
+    id: string;
+    /** Plain label a person sees in the progress row. */
+    label: string;
+    description?: string;
+    /** The step's work is done. */
+    complete?: boolean;
+    /** `go-to` may jump here (default: complete steps and the current one). */
+    available?: boolean;
+}
+type StepHandler = () => boolean | undefined | Promise<boolean | undefined>;
+export interface StepSurfaceOptions {
+    registry: DataSurfaceRegistry;
+    surfaceId: string;
+    subject?: DataSurfaceSubject;
+    label: string;
+    description: string;
+    steps: readonly StepSurfaceStep[];
+    /** Id of the step on screen. */
+    current: string;
+    /**
+     * The forward action of the current step, when it does not write — the
+     * same function its Continue button calls. Return `false` to refuse.
+     */
+    next?: StepHandler;
+    /**
+     * The current step's forward button saves or creates something. An agent's
+     * `next` then only reveals the button (see {@link StepSurfaceOptions.showNext}).
+     */
+    nextWrites?: boolean;
+    /** Reveal and highlight the current step's forward button for the person. */
+    showNext?: () => void;
+    /** Return to the previous step. Return `false` to refuse. */
+    back?: StepHandler;
+    /** Jump to a step. Return `false` to refuse. */
+    goTo?: (stepId: string) => boolean | undefined | Promise<boolean | undefined>;
+    /** Extra JSON state published alongside the steps. */
+    state?: Record<string, DataSurfaceJsonValue>;
+}
+export type StepSurfaceUpdate = Partial<Pick<StepSurfaceOptions, 'steps' | 'current' | 'next' | 'nextWrites' | 'showNext' | 'back' | 'goTo' | 'state'>>;
+export interface StepSurfaceHandle {
+    update(next: StepSurfaceUpdate): void;
+    destroy(): void;
+}
+/** Resolve a `go-to` payload to a step id (id, exact label, unique prefix). */
+export declare function resolveStepTarget(payload: DataSurfaceJsonValue | undefined, steps: readonly StepSurfaceStep[]): string | null;
+/** The descriptor {@link registerStepSurface} mounts. */
+export declare function stepSurfaceDescriptor(options: Pick<StepSurfaceOptions, 'surfaceId' | 'subject' | 'label' | 'description'>): DataSurfaceDescriptor;
+/** Mount a multi-step flow on a data-surface registry. */
+export declare function registerStepSurface(options: StepSurfaceOptions): StepSurfaceHandle;
+export {};
+//# sourceMappingURL=step-surface.d.ts.map

package/dist/components/data/step-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-surface.d.ts","sourceRoot":"","sources":["../../../src/components/data/step-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,KAAK,WAAW,GAAG,MAAM,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gDAAgD;IAChD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9E,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACrC,IAAI,CACF,kBAAkB,EAChB,OAAO,GACP,SAAS,GACT,MAAM,GACN,YAAY,GACZ,UAAU,GACV,MAAM,GACN,MAAM,GACN,OAAO,CACV,CACF,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,OAAO,IAAI,IAAI,CAAC;CACjB;AAUD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,MAAM,GAAG,IAAI,CAaf;AAED,yDAAyD;AACzD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CACX,kBAAkB,EAClB,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAClD,GACA,qBAAqB,CA2CvB;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CA6FnB"}

package/dist/components/data/step-surface.js

@@ -0,0 +1,177 @@
+/**
+ * A multi-step flow (a wizard, a setup checklist) as a mounted data surface,
+ * so an agent can see where a person is and move the flow forward.
+ *
+ * The published state lists the steps (`state.steps`: id, label, status) and
+ * the current one. Three controls move between them:
+ *
+ * - `next` — advance from the current step. A step whose forward button only
+ *   checks input and shows the next step runs the page's `next` handler, the
+ *   same function the button calls. A step whose forward button SAVES or
+ *   CREATES something (`nextWrites`) is never pressed by an agent: `next`
+ *   reveals and highlights that button instead, and publishes
+ *   `awaitingPerson: true` until the page moves on. People apply writes.
+ * - `back` — return to the previous step (never a write).
+ * - `go-to` — jump to a step the page marks `available` (payload
+ *   `{ target }`: a step id or label).
+ *
+ * A handler that returns `false` (validation failed) refuses the command, so
+ * the agent sees the step did not change and can read the form's errors.
+ */
+import { linkTargetFromPayload } from './link-surface.js';
+function normalize(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function stepAvailable(step, current) {
+    return step.available ?? (step.complete === true || step.id === current);
+}
+/** Resolve a `go-to` payload to a step id (id, exact label, unique prefix). */
+export function resolveStepTarget(payload, steps) {
+    const target = linkTargetFromPayload(payload);
+    if (!target)
+        return null;
+    const wanted = normalize(target);
+    const byId = steps.find((step) => normalize(step.id) === wanted);
+    if (byId)
+        return byId.id;
+    const byLabel = steps.filter((step) => normalize(step.label) === wanted);
+    if (byLabel.length === 1)
+        return byLabel[0].id;
+    if (byLabel.length > 1)
+        return null;
+    const byPrefix = steps.filter((step) => normalize(step.label).startsWith(wanted));
+    return byPrefix.length === 1 ? byPrefix[0].id : null;
+}
+/** The descriptor {@link registerStepSurface} mounts. */
+export function stepSurfaceDescriptor(options) {
+    const columns = [
+        { id: 'id', label: 'ID', capabilities: ['read'], role: 'row-key' },
+        { id: 'label', label: 'Step', capabilities: ['read'] },
+        { id: 'status', label: 'Status', capabilities: ['read'], role: 'status' },
+        { id: 'description', label: 'About', capabilities: ['read'] },
+    ];
+    return {
+        version: 1,
+        identity: {
+            kind: 'custom',
+            surfaceId: options.surfaceId,
+            ...(options.subject ? { subject: options.subject } : {}),
+        },
+        schemaVersion: 1,
+        label: options.label,
+        description: options.description,
+        rowKey: 'id',
+        columns,
+        query: {
+            modes: ['rows'],
+            projectableColumnIds: columns.map((column) => column.id),
+            filterableColumnIds: [],
+            sortableColumnIds: [],
+        },
+        controls: [
+            {
+                id: 'next',
+                label: 'Next step',
+                description: 'Continue from the current step. When the step saves or creates something (state.nextWrites), this only shows the person the button to press.',
+            },
+            { id: 'back', label: 'Previous step' },
+            {
+                id: 'go-to',
+                label: 'Go to step',
+                description: 'Jump to an available step. Payload: { target } — a step id or label.',
+            },
+        ],
+        actions: [],
+        limits: { maxQueryRows: 50, maxQueryBytes: 100_000, maxSelectionSize: 1 },
+    };
+}
+/** Mount a multi-step flow on a data-surface registry. */
+export function registerStepSurface(options) {
+    let current = { ...options };
+    let awaitingPerson = false;
+    let revision = 1;
+    const publishedState = () => {
+        const index = current.steps.findIndex((step) => step.id === current.current);
+        return {
+            ...(current.state ?? {}),
+            current: current.current,
+            currentLabel: current.steps[index]?.label ?? null,
+            stepNumber: index + 1,
+            stepCount: current.steps.length,
+            nextWrites: current.nextWrites === true,
+            awaitingPerson,
+            steps: current.steps.map((step) => ({
+                id: step.id,
+                label: step.label,
+                ...(step.description ? { description: step.description } : {}),
+                status: step.id === current.current
+                    ? 'current'
+                    : step.complete
+                        ? 'complete'
+                        : stepAvailable(step, current.current)
+                            ? 'available'
+                            : 'upcoming',
+            })),
+        };
+    };
+    let signature = JSON.stringify(publishedState());
+    const publish = () => {
+        const next = JSON.stringify(publishedState());
+        if (next !== signature) {
+            signature = next;
+            revision += 1;
+        }
+    };
+    const run = async (handler) => {
+        if (!handler)
+            return { ok: false };
+        const result = await handler();
+        return result === false ? { ok: false } : undefined;
+    };
+    const dispose = options.registry.register({
+        descriptor: stepSurfaceDescriptor(options),
+        getSnapshot: () => ({ revision, state: publishedState(), selection: null }),
+        execute: async (command) => {
+            switch (command.controlId) {
+                case 'next': {
+                    if (current.nextWrites) {
+                        if (!current.showNext)
+                            return { ok: false };
+                        current.showNext();
+                        awaitingPerson = true;
+                        publish();
+                        return undefined;
+                    }
+                    return run(current.next);
+                }
+                case 'back':
+                    return run(current.back);
+                case 'go-to': {
+                    const stepId = resolveStepTarget(command.payload, current.steps);
+                    const step = current.steps.find((item) => item.id === stepId);
+                    if (!step || !current.goTo)
+                        return { ok: false };
+                    if (!stepAvailable(step, current.current))
+                        return { ok: false };
+                    const goTo = current.goTo;
+                    return run(() => goTo(step.id));
+                }
+                default:
+                    return { ok: false };
+            }
+        },
+    });
+    return {
+        update(next) {
+            const moved = next.current !== undefined && next.current !== current.current;
+            current = { ...current, ...next };
+            // The person pressed the button (or the flow moved another way).
+            if (moved || next.nextWrites === false)
+                awaitingPerson = false;
+            publish();
+        },
+        destroy() {
+            dispose();
+        },
+    };
+}

package/dist/components/data/surface-navigation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * "Has the page settled after that command?"
+ *
+ * A visible command on a navigation surface (a link list, a tab row) starts a
+ * page change and returns at once: awaiting it inside the command would make
+ * the registry report `not_found` whenever the new page unmounts the surface
+ * that ran it. The navigation's promise is tracked here instead, keyed by the
+ * registry the command ran on, so whoever drives the page next — an in-page
+ * assistant about to show the model the page's tools, a test — can wait for
+ * it to finish and for the new page's surfaces to register:
+ *
+ * ```ts
+ * await registry.execute(openEventsCommand);
+ * await whenSurfaceNavigationSettled(registry); // new page mounted and quiet
+ * ```
+ *
+ * `registerLinkSurface` tracks its own `navigate` result. A bespoke surface
+ * whose command navigates calls {@link trackSurfaceNavigation} itself.
+ */
+import type { DataSurfaceRegistry } from '@happyvertical/smrt-types';
+/**
+ * Record a navigation a command on `registry` started. Returns the same
+ * promise. A rejection is swallowed for waiting purposes (a failed navigation
+ * is still a finished one); the caller keeps its own handling.
+ */
+export declare function trackSurfaceNavigation<T>(registry: DataSurfaceRegistry, navigation: T | Promise<T>): T | Promise<T>;
+/** Whether a tracked navigation on `registry` is still running. */
+export declare function hasPendingSurfaceNavigation(registry: DataSurfaceRegistry): boolean;
+export interface SurfaceNavigationSettleOptions {
+    /**
+     * How long the registry must go without a surface registering or
+     * unregistering before the page counts as settled. Default 120 ms.
+     */
+    quietMs?: number;
+    /** Give up waiting after this long. Default 5000 ms. */
+    timeoutMs?: number;
+    /** Extra sources whose changes also reset the quiet timer (e.g. page tools). */
+    alsoWatch?: ReadonlyArray<{
+        subscribe?: (listener: (event: unknown) => void) => () => void;
+    } | null | undefined>;
+    signal?: AbortSignal;
+}
+/**
+ * Resolve once every navigation tracked on `registry` has finished AND the
+ * registry (plus `alsoWatch` sources) has been quiet for `quietMs`, or after
+ * `timeoutMs`, whichever comes first. Never rejects.
+ */
+export declare function whenSurfaceNavigationSettled(registry: DataSurfaceRegistry, options?: SurfaceNavigationSettleOptions): Promise<void>;
+//# sourceMappingURL=surface-navigation.d.ts.map

package/dist/components/data/surface-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-navigation.d.ts","sourceRoot":"","sources":["../../../src/components/data/surface-navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAIrE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,QAAQ,EAAE,mBAAmB,EAC7B,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACzB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBhB;AAED,mEAAmE;AACnE,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAET;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,aAAa,CACrB;QAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;KAAE,GAClE,IAAI,GACJ,SAAS,CACZ,CAAC;IACF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiDf"}