@connextar/house 0.2.0 → 0.4.0

package/dist/wizard/invalid.d.ts

@@ -0,0 +1,91 @@
+import { type ActionReporter } from "../ux/feedback.js";
+/**
+ * Saying why a form refused, when the reason is somewhere nobody can look.
+ *
+ * A wizard keeps fields on steps that are mounted but hidden, and a form library
+ * will not call a submit handler while any field is invalid. An error shown
+ * beside its field speaks for itself. One on a field nobody can see — another
+ * step, a field the form hides because it does not apply, a rule that belongs to
+ * no field at all — makes the button look broken, and that one has to be said
+ * out loud. This is the half of the wizard that has to read the DOM, so it is
+ * kept apart from the rules.
+ *
+ * Where it is said is the app's decision, not this package's: the message goes to
+ * the `ActionFeedbackProvider` that `@connextar/house/ux` already defines, so an
+ * app wires one reporter to whatever it uses to tell people things and this
+ * module imports no toast library.
+ */
+/**
+ * The attribute a field's error message carries, so a visible one can be told
+ * from a hidden one. `FieldError` sets it; an app's own message component sets
+ * it too (`<p data-error-for="title">`), which is the whole integration.
+ */
+export declare const ERROR_ATTRIBUTE = "data-error-for";
+/** How long to wait before looking. */
+export declare const REPORT_DELAY = 50;
+export interface InvalidMessages {
+    /** The heading. */
+    title: string;
+    /** Used when no problem carried a message of its own. */
+    fallback: string;
+}
+export declare const INVALID_MESSAGES: InvalidMessages;
+export interface FieldProblem {
+    name: string;
+    message: string | null;
+}
+/**
+ * The problems in an error object, whatever shape the form library gave them.
+ * Only the entries that are objects count: a form library's error map holds one
+ * per field, and anything else in there is not a field error.
+ */
+export declare function fieldProblems(errors: object): FieldProblem[];
+/**
+ * Rendered, outside a hidden step, and — where the page has layout at all —
+ * taking up space.
+ *
+ * A DOM without layout, like a test's, has no boxes to measure, so `hidden`
+ * decides there on its own. Measuring alone was AltEd's version, and under jsdom
+ * it called every message invisible and said everything twice.
+ */
+export declare function isOnScreen(element: HTMLElement): boolean;
+/** The field names whose message is on screen right now. */
+export declare function shownErrorFields(root: ParentNode): string[];
+/**
+ * The problems with nothing on screen to show them.
+ *
+ * A name matches a shown message exactly, or as its prefix: an error on
+ * `times` is answered by a message on `times.0.start`, because that is where a
+ * form library puts the message for an array field's row.
+ */
+export declare function unseenProblems(problems: readonly FieldProblem[], shown: readonly string[]): FieldProblem[];
+export type InvalidReporter = (errors: object) => void;
+/**
+ * Report the errors an invalid form refused on, if any of them has nowhere to
+ * show itself.
+ *
+ * Deferred, because it has to run after the form has re-rendered with its errors
+ * and after a wizard has moved to the failing step — before that, every message
+ * is still hidden and it would say everything twice. Returns a way to cancel,
+ * for a component that unmounts in between.
+ *
+ * Two silences and one noise:
+ *
+ * - Problems, all of them showing → quiet. The fields say it better.
+ * - Problems, at least one unseen → the first unseen message, or the fallback.
+ * - **No problems at all → the fallback**, not quiet. A form that refuses with
+ *   an empty error map is the worst of the cases, not the mildest: something
+ *   said no and named nothing, and the person is left pressing a dead button.
+ */
+export declare function reportInvalid(errors: object, report: ActionReporter, options?: {
+    delay?: number;
+    root?: ParentNode;
+    messages?: Partial<InvalidMessages>;
+}): () => void;
+/**
+ * `reportInvalid` bound to the app's reporter — pass it straight to a form
+ * library's invalid handler (`handleSubmit(onSubmit, report)`), or let
+ * `stepValidator` from `@connextar/house/wizard/react-hook-form` call it.
+ */
+export declare function useInvalidReporter(messages?: Partial<InvalidMessages>): InvalidReporter;
+//# sourceMappingURL=invalid.d.ts.map

package/dist/wizard/invalid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid.d.ts","sourceRoot":"","sources":["../../src/wizard/invalid.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,uCAAuC;AACvC,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,gBAAgB,EAAE,eAG9B,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAIxD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAI3D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,CAE1G;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;CAAO,GACvF,MAAM,IAAI,CAcZ;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAYvF"}

package/dist/wizard/invalid.js

@@ -0,0 +1,121 @@
+"use client";
+import * as React from "react";
+import { useActionReporter } from "../ux/feedback.js";
+/**
+ * Saying why a form refused, when the reason is somewhere nobody can look.
+ *
+ * A wizard keeps fields on steps that are mounted but hidden, and a form library
+ * will not call a submit handler while any field is invalid. An error shown
+ * beside its field speaks for itself. One on a field nobody can see — another
+ * step, a field the form hides because it does not apply, a rule that belongs to
+ * no field at all — makes the button look broken, and that one has to be said
+ * out loud. This is the half of the wizard that has to read the DOM, so it is
+ * kept apart from the rules.
+ *
+ * Where it is said is the app's decision, not this package's: the message goes to
+ * the `ActionFeedbackProvider` that `@connextar/house/ux` already defines, so an
+ * app wires one reporter to whatever it uses to tell people things and this
+ * module imports no toast library.
+ */
+/**
+ * The attribute a field's error message carries, so a visible one can be told
+ * from a hidden one. `FieldError` sets it; an app's own message component sets
+ * it too (`<p data-error-for="title">`), which is the whole integration.
+ */
+export const ERROR_ATTRIBUTE = "data-error-for";
+/** How long to wait before looking. */
+export const REPORT_DELAY = 50;
+export const INVALID_MESSAGES = {
+    title: "That can't be saved yet",
+    fallback: "Something on the form needs changing — check the highlighted fields.",
+};
+/**
+ * The problems in an error object, whatever shape the form library gave them.
+ * Only the entries that are objects count: a form library's error map holds one
+ * per field, and anything else in there is not a field error.
+ */
+export function fieldProblems(errors) {
+    return Object.entries(errors).flatMap(([name, value]) => {
+        if (typeof value !== "object" || value === null)
+            return [];
+        const message = value.message;
+        return [{ name, message: typeof message === "string" && message !== "" ? message : null }];
+    });
+}
+/**
+ * Rendered, outside a hidden step, and — where the page has layout at all —
+ * taking up space.
+ *
+ * A DOM without layout, like a test's, has no boxes to measure, so `hidden`
+ * decides there on its own. Measuring alone was AltEd's version, and under jsdom
+ * it called every message invisible and said everything twice.
+ */
+export function isOnScreen(element) {
+    if (element.closest("[hidden]"))
+        return false;
+    const hasLayout = element.ownerDocument.documentElement.getClientRects().length > 0;
+    return !hasLayout || element.getClientRects().length > 0;
+}
+/** The field names whose message is on screen right now. */
+export function shownErrorFields(root) {
+    return [...root.querySelectorAll(`[${ERROR_ATTRIBUTE}]`)]
+        .filter(isOnScreen)
+        .map((element) => element.getAttribute(ERROR_ATTRIBUTE) ?? "");
+}
+/**
+ * The problems with nothing on screen to show them.
+ *
+ * A name matches a shown message exactly, or as its prefix: an error on
+ * `times` is answered by a message on `times.0.start`, because that is where a
+ * form library puts the message for an array field's row.
+ */
+export function unseenProblems(problems, shown) {
+    return problems.filter(({ name }) => !shown.some((on) => on === name || on.startsWith(`${name}.`)));
+}
+/**
+ * Report the errors an invalid form refused on, if any of them has nowhere to
+ * show itself.
+ *
+ * Deferred, because it has to run after the form has re-rendered with its errors
+ * and after a wizard has moved to the failing step — before that, every message
+ * is still hidden and it would say everything twice. Returns a way to cancel,
+ * for a component that unmounts in between.
+ *
+ * Two silences and one noise:
+ *
+ * - Problems, all of them showing → quiet. The fields say it better.
+ * - Problems, at least one unseen → the first unseen message, or the fallback.
+ * - **No problems at all → the fallback**, not quiet. A form that refuses with
+ *   an empty error map is the worst of the cases, not the mildest: something
+ *   said no and named nothing, and the person is left pressing a dead button.
+ */
+export function reportInvalid(errors, report, options = {}) {
+    const { delay = REPORT_DELAY, messages } = options;
+    const words = { ...INVALID_MESSAGES, ...messages };
+    const problems = fieldProblems(errors);
+    const timer = setTimeout(() => {
+        const root = options.root ?? globalThis.document;
+        const unseen = unseenProblems(problems, shownErrorFields(root));
+        if (problems.length > 0 && unseen.length === 0)
+            return;
+        const message = unseen.map((problem) => problem.message).find((text) => text !== null);
+        report({ tone: "error", title: words.title, description: message ?? words.fallback });
+    }, delay);
+    return () => clearTimeout(timer);
+}
+/**
+ * `reportInvalid` bound to the app's reporter — pass it straight to a form
+ * library's invalid handler (`handleSubmit(onSubmit, report)`), or let
+ * `stepValidator` from `@connextar/house/wizard/react-hook-form` call it.
+ */
+export function useInvalidReporter(messages) {
+    const report = useActionReporter();
+    const title = messages?.title;
+    const fallback = messages?.fallback;
+    return React.useCallback((errors) => {
+        reportInvalid(errors, report, {
+            messages: { ...(title === undefined ? {} : { title }), ...(fallback === undefined ? {} : { fallback }) },
+        });
+    }, [report, title, fallback]);
+}
+//# sourceMappingURL=invalid.js.map

package/dist/wizard/invalid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid.js","sourceRoot":"","sources":["../../src/wizard/invalid.ts"],"names":[],"mappings":"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"}

package/dist/wizard/react-hook-form-index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@connextar/house/wizard/react-hook-form` — the step check for a
+ * react-hook-form wizard.
+ *
+ * Its own entry point so that `react-hook-form` stays an optional peer
+ * dependency: every import of it in here is `import type`, which erases, but a
+ * declaration file that names a package an app has not installed still fails
+ * that app's typecheck. An app on plain state imports `@connextar/house/wizard`
+ * and never comes near this.
+ */
+export { stepValidator, useStepValidator } from "./rhf-adapter.js";
+//# sourceMappingURL=react-hook-form-index.d.ts.map

package/dist/wizard/react-hook-form-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-hook-form-index.d.ts","sourceRoot":"","sources":["../../src/wizard/react-hook-form-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/wizard/react-hook-form-index.js

@@ -0,0 +1,12 @@
+/**
+ * `@connextar/house/wizard/react-hook-form` — the step check for a
+ * react-hook-form wizard.
+ *
+ * Its own entry point so that `react-hook-form` stays an optional peer
+ * dependency: every import of it in here is `import type`, which erases, but a
+ * declaration file that names a package an app has not installed still fails
+ * that app's typecheck. An app on plain state imports `@connextar/house/wizard`
+ * and never comes near this.
+ */
+export { stepValidator, useStepValidator } from "./rhf-adapter.js";
+//# sourceMappingURL=react-hook-form-index.js.map

package/dist/wizard/react-hook-form-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-hook-form-index.js","sourceRoot":"","sources":["../../src/wizard/react-hook-form-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/wizard/rhf-adapter.d.ts

@@ -0,0 +1,32 @@
+import type { FieldValues, UseFormReturn } from "react-hook-form";
+import { type InvalidReporter } from "./invalid.js";
+import type { StepCheck } from "./rules.js";
+/**
+ * `@connextar/house/wizard/react-hook-form` — the step check most of the cohort
+ * wants, for the library most of the cohort uses.
+ *
+ * Its own entry point, and the reason is types rather than code: every import
+ * from `react-hook-form` here is `import type`, so the emitted JavaScript
+ * mentions it nowhere and an app without it can still run every part of
+ * `@connextar/house/wizard`. What an app without it *cannot* do is typecheck a
+ * declaration file that names the package — so the names live behind a subpath
+ * nobody has to reach for. MAS has no `react-hook-form` and never will;
+ * `entry-points.test.ts` keeps this split honest.
+ */
+/**
+ * The usual step check for a react-hook-form wizard: validate just this step's
+ * fields, and when one fails, say why if its message is not on screen.
+ *
+ * Returns `false` rather than a sentence, because a form library puts its
+ * messages beside the fields they belong to and a second copy in a banner above
+ * them is noise. The exception is the message with nowhere to go, which is what
+ * the reporter is for.
+ */
+export declare function stepValidator<T extends FieldValues>(form: UseFormReturn<T>, report: InvalidReporter): StepCheck;
+/**
+ * `stepValidator` wired to the app's `ActionFeedbackProvider`, with an identity
+ * that does not change between renders — a check that is a new function on every
+ * render makes the wizard re-render every step's content for nothing.
+ */
+export declare function useStepValidator<T extends FieldValues>(form: UseFormReturn<T>): StepCheck;
+//# sourceMappingURL=rhf-adapter.d.ts.map

package/dist/wizard/rhf-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rhf-adapter.d.ts","sourceRoot":"","sources":["../../src/wizard/rhf-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS,CAgB/G;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAazF"}

package/dist/wizard/rhf-adapter.js

@@ -0,0 +1,58 @@
+"use client";
+import * as React from "react";
+import { useInvalidReporter } from "./invalid.js";
+/**
+ * `@connextar/house/wizard/react-hook-form` — the step check most of the cohort
+ * wants, for the library most of the cohort uses.
+ *
+ * Its own entry point, and the reason is types rather than code: every import
+ * from `react-hook-form` here is `import type`, so the emitted JavaScript
+ * mentions it nowhere and an app without it can still run every part of
+ * `@connextar/house/wizard`. What an app without it *cannot* do is typecheck a
+ * declaration file that names the package — so the names live behind a subpath
+ * nobody has to reach for. MAS has no `react-hook-form` and never will;
+ * `entry-points.test.ts` keeps this split honest.
+ */
+/**
+ * The usual step check for a react-hook-form wizard: validate just this step's
+ * fields, and when one fails, say why if its message is not on screen.
+ *
+ * Returns `false` rather than a sentence, because a form library puts its
+ * messages beside the fields they belong to and a second copy in a banner above
+ * them is noise. The exception is the message with nowhere to go, which is what
+ * the reporter is for.
+ */
+export function stepValidator(form, report) {
+    return async (fields) => {
+        if (fields.length === 0)
+            return true;
+        const names = fields;
+        const ok = await form.trigger(names);
+        if (ok)
+            return true;
+        report(Object.fromEntries(names.flatMap((name) => {
+            const error = form.getFieldState(name).error;
+            return error ? [[name, error]] : [];
+        })));
+        return false;
+    };
+}
+/**
+ * `stepValidator` wired to the app's `ActionFeedbackProvider`, with an identity
+ * that does not change between renders — a check that is a new function on every
+ * render makes the wizard re-render every step's content for nothing.
+ */
+export function useStepValidator(form) {
+    const report = useInvalidReporter();
+    // Written after the render, so the check always reads the current form and
+    // reporter without itself having to change.
+    const latest = React.useRef({ form, report });
+    React.useEffect(() => {
+        latest.current = { form, report };
+    });
+    return React.useCallback((fields, step) => {
+        const { form: current, report: tell } = latest.current;
+        return stepValidator(current, tell)(fields, step);
+    }, []);
+}
+//# sourceMappingURL=rhf-adapter.js.map

package/dist/wizard/rhf-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rhf-adapter.js","sourceRoot":"","sources":["../../src/wizard/rhf-adapter.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,kBAAkB,EAAwB,MAAM,cAAc,CAAC;AAGxE;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAwB,IAAsB,EAAE,MAAuB;IAClG,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,MAAM,KAAK,GAAG,MAAwB,CAAC;QACvC,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC;QACpB,MAAM,CACJ,MAAM,CAAC,WAAW,CAChB,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;YAC7C,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,CAAC,CAAC,CACH,CACF,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAwB,IAAsB;IAC5E,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,2EAA2E;IAC3E,4CAA4C;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC,WAAW,CAAY,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;QACnD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;QACvD,OAAO,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC,EAAE,EAAE,CAAC,CAAC;AACT,CAAC"}

package/dist/wizard/rules.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The rules a stepped form follows — where you are, where you may go, and what
+ * has to pass before you get there. No React and no DOM, so they are tested
+ * without a browser and hold whatever draws them.
+ *
+ * The one decision worth spelling out is what a *check* is. Five apps wrote a
+ * wizard and arrived at two different answers: a react-hook-form app asks the
+ * form to validate some field names and gets a boolean back, while an app
+ * holding its values in plain state knows the sentence it wants to show and
+ * returns that. Neither is wrong, and a shared wizard that picked one of them
+ * would shut the other out — so a check may answer either way:
+ *
+ * | Returned                     | Means                                            |
+ * | ---------------------------- | ------------------------------------------------ |
+ * | `true`, `null`, `undefined`  | The step is complete                             |
+ * | `false`                      | Not complete; the host is showing why, in place   |
+ * | a sentence                   | Not complete, and this is what to say             |
+ *
+ * An empty string counts as complete. It is not part of either contract, and a
+ * check that returns one by accident must not be able to wedge a form shut with
+ * nothing on screen — which is the whole failure this module exists to prevent.
+ */
+/** What a check answers. See the table above. */
+export type StepOutcome = boolean | string | null | undefined | void;
+/** The part of a step these rules need: what it owns, and its own check. */
+export interface StepCheckable {
+    /**
+     * Field names this step owns. Passed to the form-level check, which is how a
+     * react-hook-form host validates one step's worth of fields and no more.
+     */
+    fields?: readonly string[];
+    /**
+     * This step's own check, for a host that keeps validation beside the step
+     * rather than in one function. Asked before the form-level check.
+     */
+    validate?: StepCheck;
+}
+/** Is this step complete? Asked before leaving it, and again for every step on submit. */
+export type StepCheck = (fields: string[], step: StepCheckable) => StepOutcome | Promise<StepOutcome>;
+export type StepResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string | null;
+};
+/** Normalise whatever a check answered. */
+export declare function stepResult(outcome: StepOutcome): StepResult;
+/**
+ * Ask everything that has a say about one step. The step's own check first, then
+ * the form-level one; the first refusal is the answer, so its message is the one
+ * shown rather than the last one computed.
+ */
+export declare function checkStep(step: StepCheckable, onValidateStep?: StepCheck): Promise<StepResult>;
+export interface StepFailure {
+    index: number;
+    message: string | null;
+}
+/**
+ * The first step that will not pass, checked in order from the beginning.
+ *
+ * This is what a submit does, and checking only the last step is the defect
+ * every one of the five copies had at some point. Step back by a marker (which
+ * does not validate), clear a required field, jump to the end and press Save:
+ * the form refuses with the problem on a step nobody is looking at, and the
+ * button looks broken. In MAS it was worse — nothing was checked on submit at
+ * all, so a second press after a successful create sent a record whose first
+ * step had been cleared.
+ *
+ * In order matters as much as every: the person is sent to the earliest thing
+ * that needs fixing, which is the one they will understand.
+ */
+export declare function firstFailure<S extends StepCheckable>(steps: readonly S[], onValidateStep?: StepCheck): Promise<StepFailure | null>;
+export type MarkerState = "done" | "current" | "upcoming";
+/** How a marker reads: behind you, where you are, or ahead. */
+export declare function markerState(index: number, current: number): MarkerState;
+/**
+ * May this marker be clicked?
+ *
+ * Anything reached before now, including the step you are on — clicking that one
+ * does nothing, and disabling it takes the tracker's "you are here" out of the
+ * tab order for no gain. Steps never reached stay locked, because skipping
+ * forward past a step that has never been checked is how people arrive at a
+ * submit button that will not work with nothing saying why.
+ */
+export declare function isReachable(index: number, furthest: number): boolean;
+/** The next index, not past the end. */
+export declare function nextIndex(current: number, total: number): number;
+/** The previous index, not past the beginning. */
+export declare function previousIndex(current: number): number;
+/** How far through, for the apps that show a bar rather than a count. */
+export declare function percentComplete(current: number, total: number): number;
+//# sourceMappingURL=rules.d.ts.map

package/dist/wizard/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/wizard/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;AAErE,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAEtG,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAI9E,2CAA2C;AAC3C,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAI3D;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,cAAc,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAQpG;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,aAAa,EACxD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,cAAc,CAAC,EAAE,SAAS,GACzB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAQ7B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAGvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtE"}

package/dist/wizard/rules.js

@@ -0,0 +1,105 @@
+/**
+ * The rules a stepped form follows — where you are, where you may go, and what
+ * has to pass before you get there. No React and no DOM, so they are tested
+ * without a browser and hold whatever draws them.
+ *
+ * The one decision worth spelling out is what a *check* is. Five apps wrote a
+ * wizard and arrived at two different answers: a react-hook-form app asks the
+ * form to validate some field names and gets a boolean back, while an app
+ * holding its values in plain state knows the sentence it wants to show and
+ * returns that. Neither is wrong, and a shared wizard that picked one of them
+ * would shut the other out — so a check may answer either way:
+ *
+ * | Returned                     | Means                                            |
+ * | ---------------------------- | ------------------------------------------------ |
+ * | `true`, `null`, `undefined`  | The step is complete                             |
+ * | `false`                      | Not complete; the host is showing why, in place   |
+ * | a sentence                   | Not complete, and this is what to say             |
+ *
+ * An empty string counts as complete. It is not part of either contract, and a
+ * check that returns one by accident must not be able to wedge a form shut with
+ * nothing on screen — which is the whole failure this module exists to prevent.
+ */
+const PASSED = { ok: true };
+/** Normalise whatever a check answered. */
+export function stepResult(outcome) {
+    if (outcome === false)
+        return { ok: false, message: null };
+    if (typeof outcome === "string" && outcome !== "")
+        return { ok: false, message: outcome };
+    return PASSED;
+}
+/**
+ * Ask everything that has a say about one step. The step's own check first, then
+ * the form-level one; the first refusal is the answer, so its message is the one
+ * shown rather than the last one computed.
+ */
+export async function checkStep(step, onValidateStep) {
+    const fields = [...(step.fields ?? [])];
+    for (const check of [step.validate, onValidateStep]) {
+        if (!check)
+            continue;
+        const result = stepResult(await check(fields, step));
+        if (!result.ok)
+            return result;
+    }
+    return PASSED;
+}
+/**
+ * The first step that will not pass, checked in order from the beginning.
+ *
+ * This is what a submit does, and checking only the last step is the defect
+ * every one of the five copies had at some point. Step back by a marker (which
+ * does not validate), clear a required field, jump to the end and press Save:
+ * the form refuses with the problem on a step nobody is looking at, and the
+ * button looks broken. In MAS it was worse — nothing was checked on submit at
+ * all, so a second press after a successful create sent a record whose first
+ * step had been cleared.
+ *
+ * In order matters as much as every: the person is sent to the earliest thing
+ * that needs fixing, which is the one they will understand.
+ */
+export async function firstFailure(steps, onValidateStep) {
+    for (let index = 0; index < steps.length; index++) {
+        const step = steps[index];
+        if (!step)
+            continue;
+        const result = await checkStep(step, onValidateStep);
+        if (!result.ok)
+            return { index, message: result.message };
+    }
+    return null;
+}
+/** How a marker reads: behind you, where you are, or ahead. */
+export function markerState(index, current) {
+    if (index < current)
+        return "done";
+    return index === current ? "current" : "upcoming";
+}
+/**
+ * May this marker be clicked?
+ *
+ * Anything reached before now, including the step you are on — clicking that one
+ * does nothing, and disabling it takes the tracker's "you are here" out of the
+ * tab order for no gain. Steps never reached stay locked, because skipping
+ * forward past a step that has never been checked is how people arrive at a
+ * submit button that will not work with nothing saying why.
+ */
+export function isReachable(index, furthest) {
+    return index <= furthest;
+}
+/** The next index, not past the end. */
+export function nextIndex(current, total) {
+    return Math.min(current + 1, Math.max(total - 1, 0));
+}
+/** The previous index, not past the beginning. */
+export function previousIndex(current) {
+    return Math.max(current - 1, 0);
+}
+/** How far through, for the apps that show a bar rather than a count. */
+export function percentComplete(current, total) {
+    if (total <= 0)
+        return 0;
+    return Math.round((Math.min(current + 1, total) / total) * 100);
+}
+//# sourceMappingURL=rules.js.map

package/dist/wizard/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/wizard/rules.ts"],"names":[],"mappings":"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"}