@multiplatform.one/components 7.4.1 → 7.6.0

package/src/Wizard/Wizard.spec.tsx

@@ -0,0 +1,257 @@
+import { Form, Input, Switch, useFormContext } from "@multiplatform.one/forms";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { __resetDevWarnSeen } from "@multiplatform.one/theme";
+import { act, fireEvent } from "@testing-library/react";
+import { useEffect } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Wizard, useWizard, type WizardFormLike, type WizardStep } from "./index";
+
+const STEPS: WizardStep[] = [
+  { id: "identity", label: "Identity", fields: ["name"], fieldLabels: { name: "Name" } },
+  { id: "sprites", label: "Sprites", fields: ["url"], fieldLabels: { url: "URL" } },
+  { id: "review", label: "Review", review: true },
+];
+
+interface HarnessProps {
+  onStore?: (form: WizardFormLike) => void;
+  onComplete?: () => void;
+  labels?: "visible" | "hidden" | "auto";
+}
+
+function ClearStep() {
+  const { setFieldValue } = useWizard();
+  return (
+    <>
+      <Switch
+        id="derive"
+        name="derive"
+        label="Derive URL"
+        onChange={(checked: boolean) => {
+          if (checked) setFieldValue("url", "");
+        }}
+      />
+      <Wizard.Clearable names={["url"]}>
+        <Input id="url" name="url" label="URL" />
+      </Wizard.Clearable>
+    </>
+  );
+}
+
+function WizardInner({ onStore, onComplete, labels }: HarnessProps) {
+  const form = useFormContext<Record<string, string>>();
+  useEffect(() => {
+    onStore?.(form as unknown as WizardFormLike);
+  }, [form, onStore]);
+  return (
+    <Wizard
+      form={form as unknown as WizardFormLike}
+      steps={STEPS}
+      completeLabel="Restore backup"
+      labels={labels ?? "visible"}
+      onCancel={() => undefined}
+      onComplete={onComplete}
+    >
+      <Wizard.Panel>
+        <Input id="name" name="name" label="Name" required />
+      </Wizard.Panel>
+      <Wizard.Panel>
+        <ClearStep />
+      </Wizard.Panel>
+      <Wizard.Panel>
+        <Wizard.Review />
+      </Wizard.Panel>
+    </Wizard>
+  );
+}
+
+function renderWizard(props: HarnessProps = {}) {
+  const store: { form?: WizardFormLike } = {};
+  const view = renderWithProviders(
+    <Form
+      formOptions={{
+        defaultValues: { name: "", url: "https://old.example", derive: false },
+      }}
+      showErrorSummary={false}
+    >
+      <WizardInner
+        {...props}
+        onStore={(form) => {
+          store.form = form;
+          props.onStore?.(form);
+        }}
+      />
+    </Form>,
+  );
+  return { ...view, store };
+}
+
+function panelDisplay(el: Element) {
+  const html = el as HTMLElement;
+  return html.style.display || getComputedStyle(html).display;
+}
+
+describe("Wizard LC-63 / DG-VAL", () => {
+  it("LC-63 wizard probe: fill step 1, advance, return — DOM and store match", async () => {
+    const { container, store } = renderWizard();
+    const name = container.querySelector("#name") as HTMLInputElement;
+    expect(name).toBeTruthy();
+    fireEvent.change(name, { target: { value: "Pikachu" } });
+    fireEvent.input(name, { target: { value: "Pikachu" } });
+
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-primary']") as Element);
+    });
+
+    const shell = container.querySelector("[data-wizard-shell]") as HTMLElement;
+    expect(shell.getAttribute("data-wizard-current")).toBe("1");
+
+    const hidden = [
+      ...container.querySelectorAll('[data-wizard-panel][data-active="false"]'),
+    ] as HTMLElement[];
+    expect(hidden.length).toBe(2);
+    for (const panel of hidden) {
+      expect(panelDisplay(panel) === "none" || panel.getAttribute("data-active") === "false").toBe(
+        true,
+      );
+      expect(panel.isConnected).toBe(true);
+    }
+
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-back']") as Element);
+    });
+
+    const nameAgain = container.querySelector("#name") as HTMLInputElement;
+    expect(nameAgain.value).toBe("Pikachu");
+    expect(store.form?.getFieldValue?.("name")).toBe("Pikachu");
+    expect(
+      container.querySelector("[data-wizard-shell]")?.getAttribute("data-wizard-current"),
+    ).toBe("0");
+  });
+
+  it("LC-63 clear probe: derived-value toggle clears visible value and store", async () => {
+    const { container, store } = renderWizard();
+    const name = container.querySelector("#name") as HTMLInputElement;
+    fireEvent.change(name, { target: { value: "Pikachu" } });
+    fireEvent.input(name, { target: { value: "Pikachu" } });
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-primary']") as Element);
+    });
+
+    const url = container.querySelector("#url") as HTMLInputElement;
+    expect(url.value).toBe("https://old.example");
+    expect(store.form?.getFieldValue?.("url")).toBe("https://old.example");
+
+    const derive = container.querySelector("#derive") as HTMLElement;
+    expect(derive).toBeTruthy();
+    await act(async () => {
+      fireEvent.click(derive);
+    });
+
+    const urlAfter = container.querySelector("#url") as HTMLInputElement;
+    expect(urlAfter.value).toBe("");
+    expect(store.form?.getFieldValue?.("url")).toBe("");
+
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-primary']") as Element);
+    });
+    expect({
+      name: store.form?.getFieldValue?.("name"),
+      url: store.form?.getFieldValue?.("url"),
+    }).toEqual({ name: "Pikachu", url: "" });
+  });
+
+  it("per-step validation blocks advance and focuses the first invalid field", async () => {
+    const { container } = renderWizard();
+    const primary = container.querySelector("[data-testid='wizard-primary']") as HTMLButtonElement;
+    expect(primary.getAttribute("aria-disabled")).not.toBe("true");
+    expect(primary.disabled).toBeFalsy();
+
+    await act(async () => {
+      fireEvent.click(primary);
+    });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    expect(
+      container.querySelector("[data-wizard-shell]")?.getAttribute("data-wizard-current"),
+    ).toBe("0");
+    expect(
+      container.querySelector("[data-testid='error-summary'], [data-error-summary]"),
+    ).toBeTruthy();
+    expect(container.querySelector('[data-step-state="error"]')).toBeTruthy();
+
+    const name = container.querySelector("#name") as HTMLInputElement;
+    expect(
+      document.activeElement === name || document.activeElement?.closest?.("#name"),
+    ).toBeTruthy();
+  });
+
+  it("last-step primary is the task verb, never Submit", async () => {
+    const { container } = renderWizard();
+    const name = container.querySelector("#name") as HTMLInputElement;
+    fireEvent.change(name, { target: { value: "Pikachu" } });
+    fireEvent.input(name, { target: { value: "Pikachu" } });
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-primary']") as Element);
+    });
+    await act(async () => {
+      fireEvent.click(container.querySelector("[data-testid='wizard-primary']") as Element);
+    });
+    const primary = container.querySelector("[data-testid='wizard-primary']") as HTMLElement;
+    expect(primary.textContent).toBe("Restore backup");
+    expect(primary.textContent).not.toMatch(/submit/i);
+    expect(container.querySelector("[data-primary]")).toBe(primary);
+  });
+
+  it("hides rail labels at labels=hidden and keeps the step caption", () => {
+    const { container } = renderWizard({ labels: "hidden" });
+    expect(container.querySelector("[data-labels='hidden']")).toBeTruthy();
+    expect(container.querySelector("[data-wizard-step-caption]")?.textContent).toContain(
+      "Step 1 of 3",
+    );
+    const rail = container.querySelector("[data-wizard-rail]");
+    expect(rail?.textContent).not.toContain("Identity");
+  });
+});
+
+describe("Wizard LC-57 guardrail-clean at rest", () => {
+  it("a ready wizard at rest emits zero [theme] guardrail warnings", async () => {
+    __resetDevWarnSeen();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+      renderWizard();
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+      const themeWarns = [...warn.mock.calls, ...error.mock.calls]
+        .map((args) => String(args[0]))
+        .filter((msg) => msg.startsWith("[theme]"));
+      expect(themeWarns).toEqual([]);
+    } finally {
+      warn.mockRestore();
+      error.mockRestore();
+    }
+  });
+});
+
+describe("Wizard states", () => {
+  it("draws loading, empty, and error shells", () => {
+    const loading = renderWithProviders(
+      <Wizard steps={STEPS} completeLabel="Restore backup" status="loading" />,
+    );
+    expect(loading.container.querySelector("[data-wizard-status='loading']")).toBeTruthy();
+    expect(loading.container.querySelector("[data-skeleton]")).toBeTruthy();
+
+    const empty = renderWithProviders(
+      <Wizard steps={STEPS} completeLabel="Restore backup" status="empty" />,
+    );
+    expect(empty.container.querySelector("[data-wizard-status='empty']")).toBeTruthy();
+
+    const error = renderWithProviders(
+      <Wizard steps={STEPS} completeLabel="Restore backup" status="error" />,
+    );
+    expect(error.container.querySelector("[data-wizard-status='error']")).toBeTruthy();
+  });
+});

package/src/Wizard/Wizard.stories.tsx

@@ -0,0 +1,180 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Form, Input, Switch, useFormContext } from "@multiplatform.one/forms";
+import { useState } from "react";
+import { Wizard, useWizard, type WizardFormLike, type WizardStep } from "./index";
+
+const steps: WizardStep[] = [
+  {
+    id: "snapshot",
+    label: "Snapshot",
+    fields: ["source"],
+    fieldLabels: { source: "Source" },
+  },
+  {
+    id: "destination",
+    label: "Destination",
+    fields: ["volume", "region"],
+    fieldLabels: { volume: "Destination volume", region: "Region" },
+  },
+  {
+    id: "verify",
+    label: "Verify",
+    fields: ["checksums"],
+    fieldLabels: { checksums: "Checksums" },
+  },
+  { id: "review", label: "Review", review: true },
+];
+
+const meta: Meta<typeof Wizard> = {
+  title: "Components/Wizard",
+  component: Wizard,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Multi-step form container. ProgressSteps is the rail; every panel stays mounted (LC-63). Per-step validation on Next (DG-VAL-01/02). Last primary is the task verb, never Submit.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Wizard>;
+
+function DeriveToggle() {
+  const { setFieldValue } = useWizard();
+  const [derived, setDerived] = useState(false);
+  return (
+    <Switch
+      id="derive"
+      label="Derive destination from snapshot"
+      checked={derived}
+      onChange={(checked) => {
+        setDerived(checked);
+        if (checked) setFieldValue("volume", "");
+      }}
+    />
+  );
+}
+
+function ReadyWizard({
+  labels = "visible",
+  defaultCurrent = 1,
+}: {
+  labels?: "visible" | "hidden";
+  defaultCurrent?: number;
+}) {
+  const form = useFormContext<Record<string, string>>();
+  return (
+    <Wizard
+      form={form as unknown as WizardFormLike}
+      steps={steps}
+      defaultCurrent={defaultCurrent}
+      completeLabel="Restore backup"
+      labels={labels}
+      onCancel={() => undefined}
+    >
+      <Wizard.Panel>
+        <Input id="source" name="source" label="Source" required />
+      </Wizard.Panel>
+      <Wizard.Panel>
+        <DeriveToggle />
+        <Wizard.Clearable names={["volume"]}>
+          <Input
+            id="volume"
+            name="volume"
+            label="Destination volume"
+            helperText="Must be empty before restore begins."
+            required
+          />
+        </Wizard.Clearable>
+        <Input id="region" name="region" label="Region" required />
+      </Wizard.Panel>
+      <Wizard.Panel>
+        <Input id="checksums" name="checksums" label="Checksums" />
+      </Wizard.Panel>
+      <Wizard.Panel>
+        <Wizard.Review />
+      </Wizard.Panel>
+    </Wizard>
+  );
+}
+
+function ReadyForm(props: { labels?: "visible" | "hidden"; defaultCurrent?: number }) {
+  return (
+    <Form
+      formOptions={{
+        defaultValues: {
+          source: "backup-2026-08-27-0300",
+          volume: "vol-restore-2026-08",
+          region: "eu-central",
+          checksums: "After restore",
+        },
+      }}
+      showErrorSummary={false}
+    >
+      <ReadyWizard {...props} />
+    </Form>
+  );
+}
+
+export const Main: Story = {
+  name: "Ready",
+  render: () => <ReadyForm />,
+};
+
+export const Loading: Story = {
+  parameters: {
+    skeletonSpecimen: true,
+    docs: {
+      description: {
+        story: "SKELETON SPECIMEN (D-10 / LC-61) — loading promise for the wizard shell.",
+      },
+    },
+  },
+  render: () => <Wizard steps={steps} completeLabel="Restore backup" status="loading" />,
+};
+
+export const Empty: Story = {
+  render: () => (
+    <Wizard
+      steps={steps}
+      completeLabel="Restore backup"
+      status="empty"
+      emptyTitle="No restore steps"
+    />
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <Wizard
+      steps={steps}
+      completeLabel="Restore backup"
+      status="error"
+      errorTitle="Could not load this flow"
+      errorDescription="The snapshot catalog did not respond."
+    />
+  ),
+};
+
+export const ValidationError: Story = {
+  render: () => (
+    <Form
+      formOptions={{ defaultValues: { source: "", volume: "", region: "" } }}
+      showErrorSummary={false}
+    >
+      <ReadyWizard defaultCurrent={1} />
+    </Form>
+  ),
+};
+
+export const HiddenLabels: Story = {
+  name: "Labels hidden (390)",
+  render: () => <ReadyForm labels="hidden" />,
+};
+
+export const Review: Story = {
+  render: () => <ReadyForm defaultCurrent={3} />,
+};