@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/patterns/form-wizard/form-wizard.js

@@ -0,0 +1,468 @@
+import { FormWizardController } from "./controller.js";
+import { ProgressSteps } from "../../components/feedback/progress-steps.js";
+import { BaseElement } from "../../core/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-form-wizard";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** Attribute payloads are author input — validate every record. */
+const isWizardStepRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const step = value;
+    return typeof step.id === "string" && step.id.length > 0 && typeof step.label === "string";
+};
+const elementStyles = `
+        :host {
+          display: block;
+          color: inherit;
+          font: inherit;
+        }
+
+        [part="wizard"] {
+          display: grid;
+          gap: ${boePanel.gap};
+          padding: ${boePanel.padding};
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 82%, transparent);
+          border-radius: ${boePanel.radius};
+          background: var(--boe-token-surface-surface, #ffffff);
+        }
+
+        [part="title"] {
+          margin: 0;
+          font: inherit;
+          font-size: 1.1rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="layout"] {
+          display: grid;
+          grid-template-columns: minmax(180px, 260px) 1fr;
+          gap: ${boePanel.gap};
+          align-items: start;
+        }
+
+        @media (max-width: 720px) {
+          [part="layout"] {
+            grid-template-columns: 1fr;
+          }
+        }
+
+        [part="panels"] {
+          display: grid;
+          gap: ${boePanel.gap};
+        }
+
+        [part="panel"][hidden] {
+          display: none;
+        }
+
+        [part="error"] {
+          margin: 0;
+          padding: 0.55rem 0.7rem;
+          border-radius: ${boeRadius.large};
+          font-size: 0.9rem;
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 10%, var(--boe-token-surface-surface, #ffffff));
+          border: 1px solid color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 34%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 72%, black 28%);
+        }
+
+        [part="error"][hidden] {
+          display: none;
+        }
+
+        [part="footer"] {
+          display: flex;
+          align-items: center;
+          gap: ${boePanel.gap};
+          padding-top: 0.2rem;
+          border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 62%, transparent);
+        }
+
+        [part="footer-spacer"] {
+          flex: 1;
+        }
+
+        [part="back"],
+        [part="draft"],
+        [part="next"],
+        [part="submit"] {
+          appearance: none;
+          font: inherit;
+          font-size: 0.875rem;
+          font-weight: 600;
+          min-height: 2.1rem;
+          padding: 0.4rem 0.9rem;
+          border-radius: ${boeRadius.control};
+          cursor: pointer;
+          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard}, border-color ${boeMotionDuration.interactive} ${boeMotionEasing.standard}, box-shadow ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        [part="back"],
+        [part="draft"] {
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: var(--boe-token-text-text, #222222);
+        }
+
+        [part="back"]:hover:not(:disabled),
+        [part="draft"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+          border-color: var(--boe-token-stroke-stroke-hover, #bcbcbc);
+        }
+
+        [part="back"]:disabled {
+          cursor: not-allowed;
+          opacity: 0.55;
+        }
+
+        [part="next"],
+        [part="submit"] {
+          border: 1px solid transparent;
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+          color: var(--boe-token-text-text-on-brand, #ffffff);
+        }
+
+        [part="next"]:hover,
+        [part="submit"]:hover {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 88%, black 12%);
+        }
+
+        [part="next"][hidden],
+        [part="submit"][hidden],
+        [part="draft"][hidden] {
+          display: none;
+        }
+
+        [part="back"]:focus-visible,
+        [part="draft"]:focus-visible,
+        [part="next"]:focus-visible,
+        [part="submit"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+      `;
+export class FormWizard extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["draft-label", "heading", "steps", "submit-label"];
+    }
+    controller = null;
+    pendingStart = false;
+    unsubscribeFns = [];
+    validatorsValue = {};
+    initialValuesValue = {};
+    titleEl;
+    railEl;
+    panelsEl;
+    errorEl;
+    backEl;
+    draftEl;
+    nextEl;
+    submitEl;
+    panelsSignature = "";
+    suppressRailEvent = false;
+    get heading() {
+        return this.getAttribute("heading") ?? "";
+    }
+    set heading(value) {
+        if (!value) {
+            this.removeAttribute("heading");
+            return;
+        }
+        this.setAttribute("heading", value);
+    }
+    /**
+     * Step configuration; JSON `[{"id","label","description?","optional?"}]`.
+     * A step's id doubles as the slot name feeding its panel.
+     */
+    get steps() {
+        const raw = this.getAttribute("steps");
+        if (!raw) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) && parsed.every(isWizardStepRecord) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set steps(value) {
+        if (value.length) {
+            this.setAttribute("steps", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("steps");
+    }
+    get submitLabel() {
+        return this.getAttribute("submit-label") ?? "Submit";
+    }
+    set submitLabel(value) {
+        this.setAttribute("submit-label", value);
+    }
+    /** When set, a Save draft button renders and emits `draft-saved`. */
+    get draftLabel() {
+        return this.getAttribute("draft-label");
+    }
+    set draftLabel(value) {
+        if (!value) {
+            this.removeAttribute("draft-label");
+            return;
+        }
+        this.setAttribute("draft-label", value);
+    }
+    get validators() {
+        return this.validatorsValue;
+    }
+    set validators(value) {
+        this.validatorsValue = value;
+        this.scheduleStart();
+    }
+    get initialValues() {
+        return this.initialValuesValue;
+    }
+    set initialValues(value) {
+        this.initialValuesValue = value;
+        this.scheduleStart();
+    }
+    get values() {
+        return this.controller?.getState().values ?? {};
+    }
+    get activeStep() {
+        return this.controller?.getState().currentStepId ?? "";
+    }
+    /** The live session controller. Null until steps are configured. */
+    get wizardController() {
+        return this.controller;
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        // Labels are presentation-only; steps re-create the session.
+        if (name === "steps") {
+            this.scheduleStart();
+        }
+        super.attributeChangedCallback(name, oldValue, newValue);
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.scheduleStart();
+    }
+    disconnectedCallback() {
+        this.teardownController();
+    }
+    setValue(field, value) {
+        this.controller?.setValue(field, value);
+    }
+    setValues(patch) {
+        this.controller?.setValues(patch);
+    }
+    next() {
+        return this.controller?.next() ?? false;
+    }
+    previous() {
+        return this.controller?.previous() ?? false;
+    }
+    goTo(stepId) {
+        return this.controller?.goTo(stepId) ?? false;
+    }
+    saveDraft() {
+        this.controller?.saveDraft();
+    }
+    submit() {
+        return this.controller?.submit() ?? false;
+    }
+    reset() {
+        this.controller?.reset();
+    }
+    scheduleStart() {
+        if (this.pendingStart) {
+            return;
+        }
+        this.pendingStart = true;
+        queueMicrotask(() => {
+            this.pendingStart = false;
+            this.startController();
+        });
+    }
+    startController() {
+        if (!this.isConnected) {
+            return;
+        }
+        const steps = this.steps;
+        if (!steps.length) {
+            this.teardownController();
+            if (this.isRendered) {
+                this.update();
+            }
+            return;
+        }
+        this.teardownController();
+        const controller = new FormWizardController({
+            steps,
+            validators: this.validatorsValue,
+            initialValues: this.initialValuesValue,
+        });
+        this.controller = controller;
+        this.subscribeToController(controller);
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    subscribeToController(controller) {
+        const events = [
+            ["stepChanged", "step-changed"],
+            ["valuesChanged", "values-changed"],
+            ["stepInvalid", "step-invalid"],
+            ["draftSaved", "draft-saved"],
+            ["submitted", "submitted"],
+        ];
+        this.unsubscribeFns = events.map(([eventName, domEventName]) => controller.subscribe(eventName, payload => {
+            this.dispatchEvent(new CustomEvent(domEventName, {
+                bubbles: true,
+                composed: true,
+                detail: payload,
+            }));
+            if (this.isRendered) {
+                this.update();
+            }
+        }));
+    }
+    teardownController() {
+        for (const unsubscribe of this.unsubscribeFns) {
+            unsubscribe();
+        }
+        this.unsubscribeFns = [];
+        this.controller?.destroy();
+        this.controller = null;
+        this.panelsSignature = "";
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <section part="wizard" aria-label="Form wizard">
+        <h2 part="title" hidden></h2>
+        <div part="layout">
+          <box-progress-steps part="rail"></box-progress-steps>
+          <div part="body">
+            <p part="error" role="alert" hidden></p>
+            <div part="panels"></div>
+          </div>
+        </div>
+        <footer part="footer">
+          <button type="button" part="back">Back</button>
+          <span part="footer-spacer"></span>
+          <button type="button" part="draft" hidden></button>
+          <button type="button" part="next">Next</button>
+          <button type="button" part="submit" hidden></button>
+        </footer>
+      </section>
+    `;
+        this.titleEl = this.shadowRoot.querySelector('[part="title"]');
+        this.railEl = this.shadowRoot.querySelector('[part="rail"]');
+        this.panelsEl = this.shadowRoot.querySelector('[part="panels"]');
+        this.errorEl = this.shadowRoot.querySelector('[part="error"]');
+        this.backEl = this.shadowRoot.querySelector('[part="back"]');
+        this.draftEl = this.shadowRoot.querySelector('[part="draft"]');
+        this.nextEl = this.shadowRoot.querySelector('[part="next"]');
+        this.submitEl = this.shadowRoot.querySelector('[part="submit"]');
+    }
+    setupListeners() {
+        this.backEl.addEventListener("click", () => {
+            this.previous();
+        });
+        this.nextEl.addEventListener("click", () => {
+            this.next();
+        });
+        this.submitEl.addEventListener("click", () => {
+            this.submit();
+        });
+        this.draftEl.addEventListener("click", () => {
+            this.saveDraft();
+        });
+        // Rail clicks route through the controller's gating: visited steps are
+        // reachable, jumping ahead validates the steps in between.
+        this.railEl.addEventListener("value-changed", event => {
+            event.stopPropagation();
+            if (this.suppressRailEvent) {
+                return;
+            }
+            const stepId = event.detail?.value ?? "";
+            const current = this.controller?.getState().currentStepId ?? "";
+            if (stepId && stepId !== current) {
+                this.goTo(stepId);
+                // goTo may refuse (or stop partway); re-sync the rail to the truth.
+                if (this.isRendered) {
+                    this.update();
+                }
+            }
+        });
+    }
+    /** One panel per step, fed by a slot named after the step id. */
+    rebuildPanels(steps) {
+        this.panelsEl.innerHTML = steps
+            .map(step => `
+          <div part="panel" data-step-id="${escapeHtml(step.id)}" role="group" aria-label="${escapeHtml(step.label)}" hidden>
+            <slot name="${escapeHtml(step.id)}"></slot>
+          </div>
+        `)
+            .join("");
+    }
+    update() {
+        if (!this.railEl) {
+            return;
+        }
+        const state = this.controller?.getState() ?? null;
+        const steps = state?.steps ?? [];
+        this.titleEl.hidden = !this.heading;
+        this.titleEl.textContent = this.heading;
+        const signature = JSON.stringify(steps.map(step => step.id));
+        if (signature !== this.panelsSignature) {
+            this.panelsSignature = signature;
+            this.rebuildPanels(steps);
+        }
+        this.suppressRailEvent = true;
+        try {
+            this.railEl.label = this.heading ? `${this.heading} steps` : "Wizard steps";
+            this.railEl.items = steps.map(step => ({
+                label: step.label,
+                value: step.id,
+                ...(step.description ? { description: step.description } : {}),
+            }));
+            if (state && this.railEl.value !== state.currentStepId) {
+                this.railEl.value = state.currentStepId;
+            }
+        }
+        finally {
+            this.suppressRailEvent = false;
+        }
+        this.panelsEl.querySelectorAll('[part="panel"]').forEach(panel => {
+            panel.hidden = panel.dataset.stepId !== state?.currentStepId;
+        });
+        const error = state?.stepError ?? null;
+        this.errorEl.hidden = !error;
+        this.errorEl.textContent = error?.message ?? (error ? "Complete the required fields to continue." : "");
+        const isLast = this.controller?.isLastStep ?? false;
+        this.backEl.disabled = this.controller?.isFirstStep ?? true;
+        this.nextEl.hidden = isLast;
+        this.submitEl.hidden = !isLast;
+        this.submitEl.textContent = this.submitLabel;
+        const draftLabel = this.draftLabel;
+        this.draftEl.hidden = !draftLabel;
+        if (draftLabel) {
+            this.draftEl.textContent = draftLabel;
+        }
+    }
+}
+ProgressSteps.register();
+FormWizard.register();

package/dist/patterns/form-wizard/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./controller.js";
+export * from "./form-wizard.js";
+export * from "./wizard-summary.js";

package/dist/patterns/form-wizard/index.js

@@ -0,0 +1,8 @@
+// Wizard step model, validation contract, and state types
+export * from "./types.js";
+// Headless step/session controller
+export * from "./controller.js";
+// Composed workflow surface
+export * from "./form-wizard.js";
+// Review step: collected values grouped by step, with per-step Edit intents
+export * from "./wizard-summary.js";

package/dist/patterns/form-wizard/types.d.ts

@@ -0,0 +1,109 @@
+export interface WizardStepConfig {
+    /** Step id — doubles as the slot name feeding the step's panel. */
+    id: string;
+    label: string;
+    description?: string;
+    /** Optional steps can be skipped by Next without passing validation. */
+    optional?: boolean;
+}
+/** Result of validating one step against the current values. */
+export interface WizardStepValidation {
+    valid: boolean;
+    /** Human-readable summary shown by the shell when the step blocks. */
+    message?: string;
+    /** Field-level errors for hosts that render per-field messaging. */
+    fieldErrors?: Record<string, string>;
+}
+export type WizardStepValidator = (values: Readonly<Record<string, unknown>>) => WizardStepValidation;
+export interface WizardSessionConfig {
+    steps: WizardStepConfig[];
+    /** Per-step gate, keyed by step id. Steps without a validator always pass. */
+    validators?: Record<string, WizardStepValidator>;
+    /** Seed values (e.g. a restored draft). */
+    initialValues?: Record<string, unknown>;
+}
+export interface WizardState {
+    steps: WizardStepConfig[];
+    currentStepId: string;
+    currentStepIndex: number;
+    values: Record<string, unknown>;
+    /** Ids the user has reached — the rail lets them jump back to any of these. */
+    visitedStepIds: string[];
+    /** Last validation failure for the current step; null once it passes or changes. */
+    stepError: WizardStepValidation | null;
+    /** True after a successful submit(). */
+    submitted: boolean;
+}
+export interface WizardEvents {
+    stepChanged: {
+        stepId: string;
+        stepIndex: number;
+    };
+    valuesChanged: {
+        values: Record<string, unknown>;
+    };
+    /** The current step blocked navigation or submission. */
+    stepInvalid: {
+        stepId: string;
+        validation: WizardStepValidation;
+    };
+    draftSaved: {
+        values: Record<string, unknown>;
+    };
+    submitted: {
+        values: Record<string, unknown>;
+    };
+}
+/**
+ * One collected value to show on the review step. `stepId` is what makes the
+ * Edit link possible: the summary knows which step to send the user back to.
+ */
+export interface WizardSummaryField {
+    /** Key into the wizard's `values`. */
+    key: string;
+    label: string;
+    /** Step this field was collected on. */
+    stepId: string;
+    /** Display override. Return an empty string to render the not-provided state. */
+    format?: (value: unknown) => string;
+}
+export interface WizardSummaryRow {
+    key: string;
+    label: string;
+    /** Already formatted for display; empty string when nothing was collected. */
+    value: string;
+    /** Nothing was collected — rendered as a placeholder rather than a blank line. */
+    empty: boolean;
+}
+export interface WizardSummarySection {
+    stepId: string;
+    label: string;
+    rows: WizardSummaryRow[];
+    /**
+     * The field named a step that is not in `steps`. Surfaced rather than
+     * dropped — see `summarizeWizardValues`.
+     */
+    unknownStep: boolean;
+}
+/**
+ * Default rendering for a collected value. Deliberately conservative: a
+ * boolean reads as Yes/No because `false` is a real answer that must not look
+ * like an unanswered question, and an empty array counts as nothing collected.
+ */
+export declare const formatWizardValue: (value: unknown) => string;
+/**
+ * Group collected values into per-step sections for a review card.
+ *
+ * Sections follow **step order**, not field order, so the summary reads back
+ * in the sequence the user filled it in.
+ *
+ * A field naming a step that does not exist is collected into a trailing
+ * section rather than dropped. Dropping would be the dangerous behaviour: the
+ * review step exists so someone can confirm what they are about to submit, and
+ * a mistyped `stepId` silently hiding an answer would let them confirm a value
+ * they never saw. A visibly odd extra section is a bug someone reports; a
+ * missing row is a bug nobody notices.
+ */
+export declare const summarizeWizardValues: (fields: readonly WizardSummaryField[], values: Readonly<Record<string, unknown>>, steps: readonly WizardStepConfig[]) => WizardSummarySection[];
+/** Attribute payloads are author input — validate every record. */
+export declare const isWizardSummaryFieldRecord: (value: unknown) => value is WizardSummaryField;

package/dist/patterns/form-wizard/types.js

@@ -0,0 +1,83 @@
+const WIZARD_SUMMARY_UNKNOWN_LABEL = "Other answers";
+/**
+ * Default rendering for a collected value. Deliberately conservative: a
+ * boolean reads as Yes/No because `false` is a real answer that must not look
+ * like an unanswered question, and an empty array counts as nothing collected.
+ */
+export const formatWizardValue = (value) => {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return value ? "Yes" : "No";
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : "";
+    }
+    if (Array.isArray(value)) {
+        return value.map(entry => formatWizardValue(entry)).filter(Boolean).join(", ");
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? "" : value.toISOString().slice(0, 10);
+    }
+    if (typeof value === "object") {
+        return "";
+    }
+    return String(value);
+};
+/**
+ * Group collected values into per-step sections for a review card.
+ *
+ * Sections follow **step order**, not field order, so the summary reads back
+ * in the sequence the user filled it in.
+ *
+ * A field naming a step that does not exist is collected into a trailing
+ * section rather than dropped. Dropping would be the dangerous behaviour: the
+ * review step exists so someone can confirm what they are about to submit, and
+ * a mistyped `stepId` silently hiding an answer would let them confirm a value
+ * they never saw. A visibly odd extra section is a bug someone reports; a
+ * missing row is a bug nobody notices.
+ */
+export const summarizeWizardValues = (fields, values, steps) => {
+    const order = new Map(steps.map((step, index) => [step.id, index]));
+    const sections = new Map();
+    for (const field of fields) {
+        const known = order.has(field.stepId);
+        let section = sections.get(field.stepId);
+        if (!section) {
+            section = {
+                stepId: field.stepId,
+                label: known
+                    ? (steps[order.get(field.stepId)]?.label ?? field.stepId)
+                    : WIZARD_SUMMARY_UNKNOWN_LABEL,
+                rows: [],
+                unknownStep: !known,
+            };
+            sections.set(field.stepId, section);
+        }
+        const raw = values[field.key];
+        const formatted = field.format ? field.format(raw) : formatWizardValue(raw);
+        section.rows.push({
+            key: field.key,
+            label: field.label,
+            value: formatted,
+            empty: formatted.length === 0,
+        });
+    }
+    const known = [...sections.values()].filter(section => !section.unknownStep);
+    known.sort((left, right) => (order.get(left.stepId) ?? 0) - (order.get(right.stepId) ?? 0));
+    return [...known, ...[...sections.values()].filter(section => section.unknownStep)];
+};
+/** Attribute payloads are author input — validate every record. */
+export const isWizardSummaryFieldRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const field = value;
+    return (typeof field.key === "string" &&
+        field.key.length > 0 &&
+        typeof field.label === "string" &&
+        field.label.length > 0 &&
+        typeof field.stepId === "string" &&
+        field.stepId.length > 0);
+};