@peripheries/renderer 0.21.0 → 0.23.0

package/dist/types/core/sources.d.ts

@@ -1,3 +1,4 @@
+import { type VersionContext } from '@peripheries/runtime';
 import type { CellSource, ResolvedCell } from './cells.js';
 import type { PageRuntime } from './load-page.js';
 import type { StateOrigin } from './types.js';
@@ -42,7 +43,7 @@ export declare const STRUCTURE_FIELDS: readonly ["title", "applicable", "startsP
  * The new value (and, for a page edit, the version seen) is the caller's. `fn: null` says why the
  * value can't be edited here; the write functions still decide everything that can.
  */
-export type EditTarget = {
+export type EditTarget = ({
     fn: 'doc_edit_content';
     graphNodeId: string;
     path: string[];
@@ -59,6 +60,9 @@ export type EditTarget = {
 } | {
     fn: 'page_edit_data';
     path: string[];
+}) & {
+    /** The branch the edit writes (`p_version_id`, versions.md §4.3); absent on main. */
+    versionId?: string;
 } | {
     fn: null;
     reason: EditRefusal;
@@ -83,7 +87,9 @@ export type EditRefusal =
  * (`jsonb_set_path`). The host no longer refuses list paths itself: the functions write at a
  * path into a list (DF-SCH-9), and their dry run says whether the element exists.
  */
- | 'LIST_ELEMENT';
+ | 'LIST_ELEMENT'
+/** Read at a release or a channel (or another scope's published version): releases are read-only (versions.md §5.3). */
+ | 'VERSION_IS_RELEASE';
 /** The cell a value is in, and how its content was resolved (ResolvedCell.source). */
 export type EditCell = {
     id: string;
@@ -99,7 +105,7 @@ export type EditCell = {
  * - everything else nowhere, with the reason.
  * Paths may run through list indices: the functions write at a path into a list (DF-SCH-9).
  */
-export declare function editTarget(source: PropSource, cell: EditCell): EditTarget;
+export declare function editTarget(source: PropSource, cell: EditCell, version?: VersionContext): EditTarget;
 /** A value at a path, as the nested object a patch is (`['props', 'caption']` → `{ props: { caption } }`). */
 export declare function patchAt(path: readonly string[], value: unknown): unknown;
 /**

package/dist/types/core/types.d.ts

@@ -24,6 +24,8 @@ export type StateOrigin = {
     systemId: string;
     name?: string;
     stateId: string | null;
+    versionId?: string | null;
+    outOfScope?: boolean;
 };
 /**
  * Where a label's value came from (INV-DOC-6), so an edit can go back to it (design/data.md §9.5).

package/dist/types/forms/conditions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Conditions on pages, sections, questions and content blocks (design/forms.md §3.1).
+ *
+ * One shape: `{ all: [{ q: '<question key>', op, value }], not?: boolean }`, operators
+ * in lower case only. Ported from the PWA's `lib/forms/evaluate-conditional.ts` and
+ * `lib/forms/normalize-conditional-logic.ts`; the semantics are theirs:
+ *
+ * - every clause must hold (AND); `not: true` negates the result;
+ * - absent or empty conditions show the target;
+ * - an unknown operator, or an error while evaluating, SHOWS the target. Hiding would
+ *   silently remove a question from a workbook; an extra one is visible and correctable.
+ *
+ * The PWA had two stored shapes and mixed operator casing (`equals`, `not_equals`,
+ * `notEquals`, `is_not_empty`, `greaterThan` …). `normalizeCondition` maps all of them
+ * to this shape once, at migration and validation time, so the evaluator reads only
+ * the canonical operators.
+ */
+export declare const CONDITION_OPS: readonly ["eq", "ne", "in", "not_in", "gt", "lt", "gte", "lte", "contains", "not_contains", "empty", "not_empty"];
+export type ConditionOp = (typeof CONDITION_OPS)[number];
+export interface ConditionClause {
+    /** The question key the clause reads from the answers. */
+    q: string;
+    /** A `ConditionOp`; anything else shows the target and is reported. */
+    op: ConditionOp | (string & {});
+    value?: unknown;
+}
+export interface Condition {
+    all: ConditionClause[];
+    not?: boolean;
+}
+export declare function isConditionOp(op: unknown): op is ConditionOp;
+/**
+ * True when the condition passes and the target should render.
+ *
+ * @param answers Answers keyed by question key, unwrapped (`unwrapAnswerValue`).
+ * @param onProblem Called for an unknown operator or an evaluation error; the target
+ *   is shown in both cases.
+ */
+export declare function evaluateCondition(condition: Condition | null | undefined, answers: Record<string, unknown>, onProblem?: (problem: string) => void): boolean;
+/** The canonical operator for a legacy spelling, or null when it is not one we know. */
+export declare function normalizeOperator(op: unknown): ConditionOp | null;
+/**
+ * Map a stored condition to the one shape.
+ *
+ * Accepts the new shape, the PWA's current `{ conditions: [{ questionId, operator, value }],
+ * not? }`, its legacy `[{ when, operator, is }]`, and any of them as a JSON string (the
+ * column is jsonb and some seeding wrote it stringified).
+ *
+ * `condition: null` means UNGATED, i.e. the target shows: the safe direction for input
+ * that is absent or unusable. Unusable input and dropped clauses are listed in `problems`.
+ */
+export declare function normalizeCondition(legacy: unknown): {
+    condition: Condition | null;
+    problems: string[];
+};

package/dist/types/forms/index.d.ts

@@ -0,0 +1,3 @@
+export { CONDITION_OPS, evaluateCondition, isConditionOp, normalizeCondition, normalizeOperator, type Condition, type ConditionClause, type ConditionOp } from './conditions.js';
+export { defaultMode, enterAdvances, fromPageSteps, goTo, goToQuestion, isReadOnlyStatus, linkTo, missing, move, positionFromLink, positionsOf, progress, questionsOf, settle, stepKind, visibleSteps, type DisplayMode, type FormChapter, type FormItem, type FormItemKind, type FormLink, type FormModel, type FormQuestion, type FormQuestionDefinition, type FormStep, type Position, type StepKind, type StepProgress, type SubmissionStatus, } from './model.js';
+export type { AnswerToSave, FileToUpload, FormsPort, FormsRefusal, FormsResult } from './port.js';

package/dist/types/forms/model.d.ts

@@ -0,0 +1,134 @@
+import { type Condition } from './conditions.js';
+/**
+ * A form as the forms runtime reads it (forms-as-pages.md §4.2–§4.3): steps, an overlay on the
+ * page's flat cells, each holding items (cells) and the questions they ask. Where it comes from
+ * is an adapter's business: a page's `layout.steps` (`fromPageSteps`) or, until forms are pages
+ * (SCH M3b), the legacy definition (the host's adapter). Pure: no React, no network.
+ */
+export type FormQuestion = {
+    /** The answer's key: what conditions, progress and the port name. */
+    key: string;
+    label: string;
+    required: boolean;
+    /** Enter may move on from it (forms-as-pages.md §4.3): a one-line question. */
+    singleLine: boolean;
+    when?: Condition | null;
+    /** The question node an answer is saved against (answer_save's p_question_node), when the form is a page. */
+    node?: string;
+    /** How to ask it, from the question node's state: what a cell renders its control from. */
+    definition?: FormQuestionDefinition;
+};
+/**
+ * A question's definition as its node's state holds it (forms-as-pages.md §4.2): the control's
+ * type, its options, validation and help. The runtime passes it through to the cell untouched.
+ */
+export type FormQuestionDefinition = {
+    type: string;
+    options?: unknown[];
+    validation?: Record<string, unknown>;
+    description?: string;
+    helpText?: string;
+};
+export type FormItemKind = 'question' | 'content' | 'document' | 'review' | 'upload' | 'other';
+/** One cell of a step: its questions, if any. */
+export type FormItem = {
+    id: string;
+    kind: FormItemKind;
+    questions: FormQuestion[];
+    when?: Condition | null;
+};
+/** `label`: an authored word for the step shown in place of its derived kind's (advisor review, status); the kind stays derived. */
+export type FormStep = {
+    id: string;
+    title: string;
+    chapter?: string;
+    label?: string;
+    items: FormItem[];
+    when?: Condition | null;
+};
+export type FormChapter = {
+    id: string;
+    title: string;
+};
+export type FormModel = {
+    title: string;
+    chapters: FormChapter[];
+    steps: FormStep[];
+    /** On submit: `warn` lists what's missing and submits; `block` refuses until it's answered (owner, Q-F7; default warn). */
+    submitRequired: 'warn' | 'block';
+    /** Back is offered (the template's `allow_back`, default true). */
+    allowBack: boolean;
+    /** The form takes a submission (false for a legacy form, which has none); default true. */
+    submittable?: boolean;
+};
+/** A step's kind, derived from its cells (§4.2): for labels and progress. */
+export type StepKind = 'answer' | 'read' | 'review' | 'upload' | 'submit';
+/** Where a submission stands (the `submission` layer's status, schema-g2.md §2.7). */
+export type SubmissionStatus = 'in_progress' | 'submitted' | 'changes_requested' | 'completed';
+export type DisplayMode = 'step' | 'question';
+/** Steps, cells and questions whose conditions hold for these answers; a step left with nothing visible is skipped. */
+export declare function visibleSteps(model: FormModel, values: Record<string, unknown>): FormStep[];
+export declare const questionsOf: (step: FormStep) => FormQuestion[];
+export declare function stepKind(step: FormStep, isLast: boolean): StepKind;
+/** Where a person is: a step, and in question mode one of its questions. */
+export type Position = {
+    step: string;
+    question?: string;
+};
+/** The places Next and Back move through: a step each, or in question mode each question (a step with none counts once). */
+export declare function positionsOf(steps: FormStep[], mode: DisplayMode): Position[];
+/** A position in these steps: the same, else its step's first, else the first. */
+export declare function settle(steps: FormStep[], mode: DisplayMode, at: Position | null): Position | null;
+/** One move on, or back; null at either end. A move across a step boundary is a step change (it pushes history). */
+export declare function move(steps: FormStep[], mode: DisplayMode, at: Position, by: 1 | -1): Position | null;
+/** The contents click (§4.3): that step, in question mode at its first unanswered question, else its first. */
+export declare function goTo(steps: FormStep[], mode: DisplayMode, stepId: string, values: Record<string, unknown>): Position | null;
+/** A question's place (§4.3 question mode, `?question=`): its step, settled for the mode. Null when no visible step has it. */
+export declare function goToQuestion(steps: FormStep[], mode: DisplayMode, key: string): Position | null;
+/** Enter moves on (§4.3): a step with exactly one visible one-line question, or a one-line question in question mode. */
+export declare function enterAdvances(step: FormStep, mode: DisplayMode, question?: string): boolean;
+/** Required questions not yet answered, in order: in one step, or (no step) in the whole form. */
+export declare function missing(steps: FormStep[], values: Record<string, unknown>, stepId?: string): FormQuestion[];
+export type StepProgress = {
+    answered: number;
+    total: number;
+    complete: boolean;
+};
+/**
+ * Progress (§4.3): overall, required answered of required visible; per step, answered of visible
+ * questions, complete when all its required ones are answered. A read step counts once visited.
+ */
+export declare function progress(steps: FormStep[], values: Record<string, unknown>, visited: ReadonlySet<string>): {
+    answered: number;
+    required: number;
+    ratio: number;
+    total: {
+        answered: number;
+        count: number;
+    };
+    perStep: Record<string, StepProgress>;
+};
+/** Answers can't change: submitted or completed (Edit answers reopens a submitted form). */
+export declare const isReadOnlyStatus: (status: SubmissionStatus | null | undefined) => status is "submitted" | "completed";
+/** Step mode on desktop, one question at a time on a phone (§4.3). */
+export declare const defaultMode: (phone: boolean) => DisplayMode;
+/**
+ * Steps from a page's overlay (§4.2): `layout.steps: [{ id, title, chapter?, cell_ids, when? }]`
+ * and `layout.chapters`, each cell's questions from `questionsOfCell` (the page knows its
+ * question cells' bindings). Cells the overlay doesn't name aren't in the form.
+ */
+export declare function fromPageSteps(page: {
+    name?: string | null;
+    layout?: Record<string, unknown> | null;
+}, itemOf: (cellId: string) => FormItem | null): FormModel;
+/** A deep link (§4.3, the URL contract `?mode=&page=&section=&question=`): `section` a step id, `page` a chapter id, `question` a question key. */
+export type FormLink = {
+    mode?: 'question';
+    page?: string;
+    section?: string;
+    question?: string;
+};
+/** Where a link lands: the step it names (and question), else its chapter's first step, else the first. */
+export declare function positionFromLink(steps: FormStep[], mode: DisplayMode, link: FormLink): Position | null;
+/** The link to a position, as an assistant reply carries it. */
+export declare function linkTo(steps: FormStep[], mode: DisplayMode, at: Position): FormLink;

package/dist/types/forms/port.d.ts

@@ -0,0 +1,69 @@
+/**
+ * How the forms runtime saves (joint-releases.md §2.4): an injected port, so the runtime never
+ * names a table or a function. The legacy adapter (the host's, over form_answer_save) implements
+ * it in G2; answer_save, form_submit, form_visit and form_reopen (SCH M3b; schema-g2.md §2.7) in
+ * G3, with no renderer release. A refusal is a code, never a throw, so it's said in words like an edit's.
+ */
+import type { FileAnswer } from '@peripheries/runtime';
+/** The codes a port answers with (schema-g2.md §2.7), and NETWORK when the call didn't arrive. */
+export type FormsRefusal = 'CONFLICT' | 'ANSWER_TYPE' | 'ANSWER_OPTION' | 'ANSWER_REQUIRED' | 'ANSWER_FILE_PATH' | 'ANSWER_VALIDATION' | 'FORM_INCOMPLETE' | 'FORM_NOT_OPEN' | 'FORM_COMPLETED' | 'FORM_STEP_UNKNOWN' | 'NO_CAPABILITY' | 'NETWORK' | (string & {});
+export type FormsResult<T extends object = object> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    code: FormsRefusal;
+    message?: string;
+    detail?: unknown;
+};
+/** A file to upload for an answer: any Blob with a name (a File in the browser). */
+export type FileToUpload = Blob & {
+    readonly name: string;
+};
+/** One answer to save: its key, the question node when the form is a page, and the state it replaces. */
+export type AnswerToSave = {
+    key: string;
+    node?: string;
+    value: unknown;
+    expectedStateId?: string | null;
+};
+export interface FormsPort {
+    /** Save one answer; the state it wrote is what the next save of that key expects (CONFLICT otherwise). */
+    save(answer: AnswerToSave): Promise<FormsResult<{
+        stateId?: string | null;
+    }>>;
+    /** Submit: `missing` is what the runtime found unanswered (recorded under `warn`; `block` refuses FORM_INCOMPLETE). */
+    submit(input: {
+        missing: string[];
+    }): Promise<FormsResult<{
+        status: 'submitted';
+        missing: string[];
+    }>>;
+    /**
+     * Edit answers (forms-as-pages.md §4.3): a submitted form back to `in_progress`, recorded in the
+     * submission. Refused once staff have completed it (FORM_COMPLETED).
+     */
+    reopen(): Promise<FormsResult<{
+        status: 'in_progress';
+    }>>;
+    /** A step was seen (`submission.visited_steps`): read steps count once visited. A repeat is a no-op. */
+    visit(stepId: string): Promise<FormsResult>;
+    /**
+     * Upload a file for a file question, as the viewer: the adapter stores it where answer_save
+     * accepts it and returns the answer to save (`{ v: 1, file }`); saving it is `save`'s. Absent
+     * where the host takes no files.
+     */
+    upload?(input: {
+        key: string;
+        node?: string;
+        file: FileToUpload;
+    }): Promise<FormsResult<{
+        answer: {
+            v: 1;
+            file: FileAnswer;
+        };
+    }>>;
+    /** A short-lived URL to open a saved file answer, as the viewer (storage decides who may). */
+    openFile?(file: FileAnswer): Promise<FormsResult<{
+        url: string;
+    }>>;
+}

package/dist/types/react/cell-view.d.ts

@@ -51,6 +51,8 @@ export type CellEnvironment = {
     onDiagnostic?: (d: Diagnostic) => void;
     /** Extra attributes and style for a cell's frame (RendererEnvironment.frameProps). */
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
+    /** Props from the page's runtime, merged last (RendererEnvironment.cellProps). */
+    cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
 };
 export type FrameProps = {
     attributes?: Record<string, string>;

package/dist/types/react/index.d.ts

@@ -5,3 +5,4 @@ export { StructureView, useStructureFacts } from './structure-view.js';
 export { useCellStore } from './use-cell-store.js';
 export { useContainerSize, type Size } from './use-container-size.js';
 export { cellLabels, usePaging, type LabelPaging, type LoadPage } from './use-paging.js';
+export { answerInputId, FORM_SAVE_DEBOUNCE_MS, useFormsRuntime, type FormAnswer, type FormSaveState, type FormSlotProps, type FormsRuntimeOptions } from './use-forms-runtime.js';

package/dist/types/react/page-renderer.d.ts

@@ -48,6 +48,11 @@ export type RendererEnvironment = {
     retry?: () => void;
     /** Extra attributes and style for each cell's frame, e.g. a print policy the host doesn't apply yet. */
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
+    /**
+     * Props a cell gets from the page's runtime, merged over everything else: on a form page, the
+     * forms runtime's `form`, `answers` and `answer` (useFormsRuntime's `cellProps`).
+     */
+    cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
 };
 export type PageRendererProps = {
     runtime: PageRuntime;

package/dist/types/react/use-forms-runtime.d.ts

@@ -0,0 +1,201 @@
+import { type KeyboardEvent } from 'react';
+import { type DisplayMode, type FileToUpload, type FormLink, type FormModel, type FormQuestionDefinition, type FormsPort, type FormsRefusal, type Position, type StepKind, type SubmissionStatus } from '../forms/index.js';
+/** How long after the last change an answer is saved (forms-as-pages.md §4.3: 3 s). */
+export declare const FORM_SAVE_DEBOUNCE_MS = 3000;
+export type FormSaveState = 'idle' | 'saving' | 'saved' | 'error';
+/**
+ * What the form's shell slots read (forms-as-pages.md §4.4; DS M1's `host:Form*` defaults and an
+ * org's replacements): the contents, the header, the footer, the phone app bar and step bar.
+ * Frozen in 0.23.0. The names an org's workbook components bind (`forms.sections`,
+ * `forms.progress`, `forms.goToSection`, `forms.advance`, `forms.setDisplayMode`) are these.
+ */
+/**
+ * One question as a cell gets it (forms-as-pages.md §4.3; agreed with DS for 0.23.0): the same
+ * words as the slot props. `answers` holds only the questions its conditions show.
+ */
+export type FormAnswer = {
+    /** The answer's key (`?question=`, conditions, the port). */
+    key: string;
+    label: string;
+    /** How to ask it, from the question node (FormQuestion.definition); null when the page gives none. */
+    question: FormQuestionDefinition | null;
+    /** As saved, or as typed while its save is pending. */
+    value: unknown;
+    /** Saves through the port, debounced and flushed on every move; a no-op while read-only. */
+    change(value: unknown): void;
+    readOnly: boolean;
+    required: boolean;
+    /** Required and unanswered, once the person has moved past its step or tried to submit. */
+    missing: boolean;
+    /** Its last refusal from the port, in words; null once a save of it succeeds. */
+    refusal: string | null;
+    /** The DOM id the runtime moves focus to (goToQuestion, Review's Edit links): unique on the page; put it on the control. */
+    inputId: string;
+    /** A file question: upload, then save the file answer. Absent where the port takes no files. */
+    upload?(file: FileToUpload): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        refusal: string;
+    }>;
+    /** A short-lived URL for the saved file; null when there is none or it can't be opened. */
+    openFile?(): Promise<string | null>;
+};
+/** The id a question's control carries (FormAnswer.inputId). */
+export declare const answerInputId: (key: string) => string;
+export type FormSlotProps = {
+    title: string;
+    chapter: {
+        id: string;
+        title: string;
+    } | null;
+    /** `label`: the step's authored word, shown in place of its derived kind's when present. */
+    step: {
+        id: string;
+        title: string;
+        index: number;
+        count: number;
+        kind: StepKind;
+        label?: string;
+    };
+    sections: Array<{
+        id: string;
+        title: string;
+        chapter?: string;
+        kind: StepKind;
+        label?: string;
+        complete: boolean;
+        answered: number;
+        total: number;
+        current: boolean;
+    }>;
+    /**
+     * Required answered of required (what "complete" and the bar mean; `ratio`), and `total`: every
+     * visible question, answered of all ("X of Y questions answered").
+     */
+    progress: {
+        answered: number;
+        required: number;
+        ratio: number;
+        total: {
+            answered: number;
+            count: number;
+        };
+    };
+    /**
+     * In question mode, the question shown: its place in the step, its key (`?question=`), and the
+     * next question in the step ("Next question"). Null in step mode, or on a step without questions.
+     */
+    question: {
+        index: number;
+        count: number;
+        key: string;
+        next: {
+            label: string;
+        } | null; /** The question shown, as a cell gets it. */
+        answer?: FormAnswer;
+    } | null;
+    /** Go to a question by key: its step, and in question mode the question (review's Edit links, deep links). */
+    goToQuestion(key: string): void;
+    displayMode: DisplayMode;
+    setDisplayMode(mode: DisplayMode): void;
+    goToSection(stepId: string): void;
+    advance(): void;
+    back(): void;
+    canBack: boolean;
+    next: {
+        title: string;
+    } | null;
+    /** The last step's action; absent elsewhere. `blocked` under `submit.required: 'block'` while anything is missing. */
+    submit?: {
+        label: string;
+        run(): void;
+        blocked: boolean;
+    } | null;
+    /** Edit answers, on a submitted form (forms-as-pages.md §4.3); absent otherwise. */
+    reopen?: {
+        label: string;
+        run(): void;
+    } | null;
+    save: {
+        state: FormSaveState;
+        at?: string;
+        error?: string;
+    };
+    /** Required questions still to answer here (warn while moving, never block). */
+    missing: Array<{
+        key: string;
+        label: string;
+    }>;
+    /** Every chapter, in order, so a nav can group its rows under each (`sections[].chapter` names one). */
+    chapters?: Array<{
+        id: string;
+        title: string;
+    }>;
+    /** The submission's status (null for a form that takes none), and whether answers can be changed now. */
+    status?: SubmissionStatus | null;
+    readOnly?: boolean;
+    /** The newest staff review (form_review): what they asked for, or that they completed it. Null when none. */
+    review?: {
+        status: SubmissionStatus;
+        note: string;
+        at: string;
+        by: string | null;
+    } | null;
+};
+export type FormsRuntimeOptions = {
+    model: FormModel;
+    port: FormsPort;
+    /** Answers as loaded, and the state each was read at (what the next save expects). */
+    initial: Record<string, {
+        value: unknown;
+        stateId?: string | null;
+    }>;
+    status: SubmissionStatus | null;
+    visited?: string[];
+    /** The deep link the route was opened with. */
+    link?: FormLink;
+    /** A phone opens in question mode. */
+    phone?: boolean;
+    /** Tell the route where the person is: a step change pushes history, a move within a step replaces it. */
+    onNavigate?(link: FormLink, how: {
+        replace: boolean;
+    }): void;
+    /** A refusal's words (the host's text for a code). */
+    describe?(code: FormsRefusal): string;
+    /**
+     * The submission's staff notes as loaded (`SubmissionData.notes`), `by` as the host can name the
+     * writer to this viewer (else null): the newest review is the `review` slot.
+     */
+    notes?: Array<{
+        at: string;
+        text: string;
+        status?: SubmissionStatus;
+        by?: string | null;
+    }>;
+};
+/**
+ * The forms runtime (forms-as-pages.md §4.3) for a form page: modes, Next / Back, the contents
+ * click, Enter, required (warn while moving; warn or block on submit), history, scroll and focus,
+ * saving through the port (debounced per question, flushed on every move, on submit, on
+ * `pagehide` and on unmount, in order, retried with the next change or flush), progress (read
+ * steps once visited), read-only states and deep links. The route renders the cells; the shell's
+ * slots render `slots`.
+ */
+export declare function useFormsRuntime(o: FormsRuntimeOptions): {
+    slots: FormSlotProps | null;
+    cellProps: (cell: {
+        id: string;
+    }) => Record<string, unknown> | undefined;
+    steps: import("../forms/index.js").FormStep[];
+    step: import("../forms/index.js").FormStep;
+    position: Position | null;
+    values: Record<string, unknown>;
+    change: (key: string, value: unknown) => void;
+    flush: () => Promise<void>;
+    readOnly: boolean;
+    status: SubmissionStatus | null;
+    headingRef: import("react").RefObject<HTMLElement | null>;
+    contentRef: import("react").RefObject<HTMLElement | null>;
+    onKeyDown: (e: KeyboardEvent) => void;
+};

package/dist/types/testing/form-workbook.d.ts

@@ -0,0 +1,106 @@
+import { type FormItem, type FormModel } from '../forms/index.js';
+/** The fixture page, as `project_page` holds it. */
+export declare const formWorkbookPage: {
+    id: string;
+    name: string;
+    org_id: string;
+    project_id: string;
+    process_id: null;
+    graph_node_id: null;
+    page_type: string;
+    status: string;
+    is_template: boolean;
+    metadata: null;
+    content: {
+        cells: ({
+            id: string;
+            component: string;
+            props: {
+                blocks: {
+                    text: string;
+                }[];
+                question?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options?: undefined;
+                };
+                blocks?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options: {
+                        value: string;
+                        label: string;
+                    }[];
+                };
+                blocks?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options?: undefined;
+                };
+                blocks?: undefined;
+            };
+            when: {
+                all: {
+                    q: string;
+                    op: string;
+                    value: string;
+                }[];
+            };
+        } | {
+            id: string;
+            component: string;
+            props: {
+                blocks?: undefined;
+                question?: undefined;
+            };
+            when?: undefined;
+        })[];
+    };
+    layout: {
+        type: string;
+        chapters: {
+            id: string;
+            title: string;
+        }[];
+        steps: {
+            id: string;
+            title: string;
+            chapter: string;
+            cell_ids: string[];
+        }[];
+        submit: {
+            required: string;
+        };
+    };
+};
+/** A cell's place in the form: its question, if it asks one. */
+export declare function formWorkbookItem(cellId: string): FormItem | null;
+/** The fixture as the forms runtime reads it. */
+export declare const formWorkbookModel: () => FormModel;

package/dist/types/testing/index.d.ts

@@ -3,3 +3,4 @@ export * as fixtureComponents from './components.js';
 export { dashboardPage, documentPage, GOLDEN_PAGES, mixedPage, thinRefPage, walkPage, type GoldenBundle, type GoldenPage } from './golden.js';
 export { ADVISOR_ORG, CLIENT_ORG, FIXTURE_EMAIL_DOMAIN, FIXTURE_ID, FIXTURE_ORG_SLUGS, fixtureId } from './ids.js';
 export { goldenBundleRow, goldenBundles, goldenGraphSource, goldenScope, type SourceCall } from './sources.js';
+export { formWorkbookItem, formWorkbookModel, formWorkbookPage } from './form-workbook.js';