@multiplatform.one/forms 7.7.0 → 7.7.1

package/src/ContextualSaveBar/UnsavedChangesDialog.stories.tsx

@@ -0,0 +1,118 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { Paragraph, YStack } from "tamagui";
+import { Button } from "../Button";
+import { UnsavedChangesDialog } from "./UnsavedChangesDialog";
+
+const meta: Meta<typeof UnsavedChangesDialog> = {
+  title: "Forms/ContextualSaveBar/UnsavedChangesDialog",
+  component: UnsavedChangesDialog,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The route-leave confirm ContextualSaveBar raises (DG-OVL-02) when a navigation would throw away edits. It is an `alertdialog`, it cannot be dismissed by clicking the scrim, and the destructive choice is the one on the right — so nobody discards work by reflex. It lives in forms rather than components because ConfirmDialog would import the forms Button and cycle.",
+      },
+    },
+  },
+  argTypes: {
+    open: { control: "boolean" },
+    fieldCount: { control: { type: "number", min: 0, step: 1 } },
+  },
+  args: {
+    open: true,
+    fieldCount: 3,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof UnsavedChangesDialog>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <UnsavedChangesDialog
+      {...args}
+      onKeepEditing={action("onKeepEditing")}
+      onDiscard={action("onDiscard")}
+    />
+  ),
+};
+
+/**
+ * The body pluralises: one field reads "1 field ... has edits", more than one
+ * reads "N fields ... have edits". Getting this wrong is the tell that a count
+ * was interpolated into a fixed string.
+ */
+export const SingleField: Story = {
+  render: () => (
+    <UnsavedChangesDialog
+      open
+      fieldCount={1}
+      onKeepEditing={action("onKeepEditing")}
+      onDiscard={action("onDiscard")}
+    />
+  ),
+};
+
+export const ManyFields: Story = {
+  render: () => (
+    <UnsavedChangesDialog
+      open
+      fieldCount={14}
+      onKeepEditing={action("onKeepEditing")}
+      onDiscard={action("onDiscard")}
+    />
+  ),
+};
+
+/** Closed is a real state: it renders no scrim and nothing takes focus. */
+export const Closed: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={420}>
+      <Paragraph size="$3">Nothing should paint below this line.</Paragraph>
+      <UnsavedChangesDialog
+        open={false}
+        fieldCount={3}
+        onKeepEditing={action("onKeepEditing")}
+        onDiscard={action("onDiscard")}
+      />
+    </YStack>
+  ),
+};
+
+/**
+ * The live loop. "Keep editing" is the safe path and is also what Escape and
+ * `onOpenChange(false)` resolve to; "Discard changes" is the only way to lose
+ * the edits, and it is the destructive-styled button.
+ */
+export const Interactive: Story = {
+  render: () => {
+    const Example = () => {
+      const [open, setOpen] = useState(false);
+      const [outcome, setOutcome] = useState<string>("nothing yet");
+      return (
+        <YStack gap="$4" maxWidth={420} alignItems="flex-start">
+          <Button onPress={() => setOpen(true)}>Leave the page</Button>
+          <Paragraph size="$3">last outcome: {outcome}</Paragraph>
+          <UnsavedChangesDialog
+            open={open}
+            fieldCount={3}
+            onKeepEditing={() => {
+              setOpen(false);
+              setOutcome("kept editing");
+              action("onKeepEditing")();
+            }}
+            onDiscard={() => {
+              setOpen(false);
+              setOutcome("discarded");
+              action("onDiscard")();
+            }}
+          />
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};

package/src/ContextualSaveBar/unsavedChangesDialogStories.spec.tsx

@@ -0,0 +1,79 @@
+/**
+ * Mounts every Forms/ContextualSaveBar/UnsavedChangesDialog story and asserts
+ * what it exists to show — chiefly the copy pluralisation and that the safe
+ * choice, not the destructive one, is what a dismissal resolves to.
+ *
+ * Only one open dialog per test: Dialog.Portal mounts to the document body, so
+ * two open at once make every text query ambiguous.
+ */
+import { cleanup, fireEvent, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import * as storiesModule from "./UnsavedChangesDialog.stories";
+
+afterEach(cleanup);
+
+const meta = storiesModule.default;
+const { Basic, SingleField, ManyFields, Closed, Interactive } = storiesModule;
+
+type StoryLike = { render?: (args: Record<string, unknown>) => ReactElement };
+
+function mount(story: StoryLike) {
+  if (!story.render) throw new Error("story has no render");
+  return renderWithProviders(story.render({ ...(meta.args as Record<string, unknown>) }));
+}
+
+describe("Forms/ContextualSaveBar/UnsavedChangesDialog stories", () => {
+  it("nests under ContextualSaveBar so the gallery keeps it with the bar that raises it", () => {
+    expect(meta.title).toBe("Forms/ContextualSaveBar/UnsavedChangesDialog");
+  });
+
+  it("Basic opens an alertdialog with both choices", () => {
+    mount(Basic as StoryLike);
+    expect(screen.getByText("Discard unsaved changes?")).toBeTruthy();
+    expect(screen.getByText("Keep editing")).toBeTruthy();
+    expect(screen.getByText("Discard changes")).toBeTruthy();
+    expect(document.querySelector("[role='alertdialog']")).toBeTruthy();
+  });
+
+  it("SingleField uses the singular sentence", () => {
+    mount(SingleField as StoryLike);
+    expect(
+      screen.getByText("1 field on this page has edits that aren't saved. Leaving discards them."),
+    ).toBeTruthy();
+  });
+
+  it("ManyFields uses the plural sentence with the count interpolated", () => {
+    mount(ManyFields as StoryLike);
+    expect(
+      screen.getByText(
+        "14 fields on this page have edits that aren't saved. Leaving discards them.",
+      ),
+    ).toBeTruthy();
+  });
+
+  it("Closed paints no dialog at all", () => {
+    const { getByText } = mount(Closed as StoryLike);
+    expect(getByText("Nothing should paint below this line.")).toBeTruthy();
+    expect(document.querySelector("[role='alertdialog']")).toBeNull();
+    expect(screen.queryByText("Discard unsaved changes?")).toBeNull();
+  });
+
+  it("Interactive opens on the trigger and closes on Keep editing", () => {
+    const { getByText } = mount(Interactive as StoryLike);
+    expect(screen.queryByText("Discard unsaved changes?")).toBeNull();
+    fireEvent.click(getByText("Leave the page"));
+    expect(screen.getByText("Discard unsaved changes?")).toBeTruthy();
+    fireEvent.click(screen.getByText("Keep editing"));
+    expect(getByText("last outcome: kept editing")).toBeTruthy();
+  });
+
+  it("Interactive records a discard as a distinct outcome from keeping", () => {
+    const { getByText } = mount(Interactive as StoryLike);
+    fireEvent.click(getByText("Leave the page"));
+    fireEvent.click(screen.getByText("Discard changes"));
+    expect(getByText("last outcome: discarded")).toBeTruthy();
+  });
+});

package/src/DescriptionList/index.tsx

@@ -161,7 +161,9 @@ function TermText({ children }: { children: ReactNode }) {
       {...knobProps.body}
       color="$color11"
       minWidth={0}
-      {...(isWeb ? ({ overflowWrap: "break-word" } as Record<string, unknown>) : undefined)}
+      // `overflowWrap` is not a tamagui style prop; passed as one it reaches
+      // the DOM host as an unknown React prop. Web takes it through `style`.
+      {...(isWeb ? { style: { overflowWrap: "break-word" } } : undefined)}
     >
       {children}
     </Text>

package/src/ErrorSummary.stories.tsx

@@ -0,0 +1,197 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { useState } from "react";
+import { Input as TamaguiInput, Paragraph, YStack } from "tamagui";
+import { Button } from "./Button";
+import { ErrorSummary, collectFormFieldErrors } from "./ErrorSummary";
+import { FieldLayout } from "./fieldLayout";
+import { Form } from "./Form";
+import { FormSection } from "./FormSection";
+
+const meta: Meta<typeof ErrorSummary> = {
+  title: "Forms/ErrorSummary",
+  component: ErrorSummary,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          'Form-level error summary (DG-VAL-02), the GOV.UK pattern. It lists every field error as a link that focuses the offending control, carries `role="alert"`, and takes keyboard focus itself the moment it appears — so a submit failure is announced once and the keyboard lands somewhere useful instead of at the top of the document.',
+      },
+    },
+  },
+  argTypes: {
+    title: { control: "text" },
+    disableAutoFocus: { control: "boolean" },
+  },
+  args: {
+    disableAutoFocus: true,
+    errors: [
+      { name: "email", error: "Enter an email address in the format name@example.com" },
+      { name: "password", error: "Enter a password" },
+    ],
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ErrorSummary>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <YStack maxWidth={520}>
+      <ErrorSummary {...args} onFocusField={action("onFocusField")} />
+    </YStack>
+  ),
+};
+
+/**
+ * Structured errors (DG-VAL-04): a validator may return `{ problem, action }`
+ * instead of a string, and the summary flattens the pair into one sentence —
+ * what is wrong, then what to do about it.
+ */
+export const StructuredErrors: Story = {
+  render: () => (
+    <YStack maxWidth={520}>
+      <ErrorSummary
+        disableAutoFocus
+        errors={[
+          {
+            name: "vatNumber",
+            error: {
+              problem: "That VAT number is not registered.",
+              action: "Check it against your registration certificate.",
+            },
+          },
+          {
+            name: "startDate",
+            error: { problem: "The start date is in the past." },
+          },
+        ]}
+        onFocusField={action("onFocusField")}
+      />
+    </YStack>
+  ),
+};
+
+/** A custom `label` overrides the link text without touching the error payload. */
+export const CustomLabels: Story = {
+  render: () => (
+    <YStack maxWidth={520}>
+      <ErrorSummary
+        disableAutoFocus
+        title="Check these before continuing"
+        errors={[
+          { name: "email", label: "Email address", error: "Enter an email address" },
+          { name: "phone", label: "Phone number", error: "Enter a phone number" },
+        ]}
+        onFocusField={action("onFocusField")}
+      />
+    </YStack>
+  ),
+};
+
+/** One error, the common case after a single missed required field. */
+export const SingleError: Story = {
+  render: () => (
+    <YStack maxWidth={520}>
+      <ErrorSummary
+        disableAutoFocus
+        errors={[{ name: "terms", error: "You must accept the terms to continue" }]}
+        onFocusField={action("onFocusField")}
+      />
+    </YStack>
+  ),
+};
+
+/** An empty list renders nothing at all — no empty banner, no reserved space. */
+export const EmptyRendersNothing: Story = {
+  render: () => (
+    <YStack maxWidth={520} gap="$3">
+      <Paragraph size="$3">Nothing should paint between these two lines.</Paragraph>
+      <ErrorSummary errors={[]} />
+      <Paragraph size="$3">Second line.</Paragraph>
+    </YStack>
+  ),
+};
+
+/**
+ * The live loop: submit empty, the summary appears, and clicking a link puts
+ * the caret in the field that caused it. `collectFormFieldErrors` turns
+ * TanStack `fieldMeta` into the item list.
+ */
+export const FocusesTheFieldOnPress: Story = {
+  render: () => {
+    const Example = () => {
+      const [errors, setErrors] = useState<ReturnType<typeof collectFormFieldErrors>>([]);
+      const form = useForm({
+        defaultValues: { email: "", password: "" },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      const submit = () => {
+        const next = collectFormFieldErrors({
+          email: { errors: [form.state.values.email ? undefined : "Enter an email address"] },
+          password: { errors: [form.state.values.password ? undefined : "Enter a password"] },
+        });
+        setErrors(next);
+        if (next.length === 0) void form.handleSubmit();
+      };
+      return (
+        <Form form={form}>
+          <YStack maxWidth={520} gap="$4">
+            <ErrorSummary errors={errors} disableAutoFocus onFocusField={action("onFocusField")} />
+            <FormSection label="Sign in">
+              <FieldLayout id="email" label="Email">
+                <TamaguiInput
+                  id="email"
+                  placeholder="you@example.com"
+                  onChangeText={(text) => form.setFieldValue("email", text)}
+                />
+              </FieldLayout>
+              <FieldLayout id="password" label="Password">
+                <TamaguiInput
+                  id="password"
+                  secureTextEntry
+                  onChangeText={(text) => form.setFieldValue("password", text)}
+                />
+              </FieldLayout>
+            </FormSection>
+            <Button onPress={submit}>Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <Example />;
+  },
+};
+
+/**
+ * `disableAutoFocus` off is the shipping default: the summary steals focus so
+ * a screen reader announces it. Toggle the control to feel the difference.
+ */
+export const AutoFocusOnAppear: Story = {
+  render: () => {
+    const Example = () => {
+      const [shown, setShown] = useState(false);
+      return (
+        <YStack maxWidth={520} gap="$4">
+          <Button onPress={() => setShown((prev) => !prev)}>
+            {shown ? "Hide the summary" : "Show the summary"}
+          </Button>
+          {shown ? (
+            <ErrorSummary
+              errors={[
+                { name: "email", error: "Enter an email address" },
+                { name: "postcode", error: "Enter a postcode" },
+              ]}
+              onFocusField={action("onFocusField")}
+            />
+          ) : null}
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};

package/src/InputParts/InputParts.stories.tsx

@@ -0,0 +1,230 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import {
+  EnvelopeIcon,
+  EyeIcon,
+  MagnifyingGlassIcon,
+  WarningCircleIcon,
+} from "@phosphor-icons/react";
+import { useState } from "react";
+import { Paragraph, YStack } from "tamagui";
+import { Input as InputParts } from "./index";
+
+const meta: Meta<typeof InputParts> = {
+  title: "Forms/InputParts",
+  component: InputParts,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The unstyled anatomy the Input field is assembled from, for consumers who need a shape the field does not offer. `InputParts.Box` is the bordered frame that owns the focus ring; `Area` is the text-entry itself and never rings; `Icon`, `Button` and `Section` are the slots either side of it; `Label`, `Info` and `Meta` are the chrome above and below. Reach for the `Input` FIELD first — this is the escape hatch.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof InputParts>;
+
+/**
+ * The whole anatomy at once: Label above, Box holding a leading Icon and the
+ * Area, Meta reserving the caption line underneath.
+ */
+export const Anatomy: Story = {
+  render: () => (
+    <InputParts width={320}>
+      <InputParts.Label htmlFor="anatomy-email">Email</InputParts.Label>
+      <InputParts.Box>
+        <InputParts.Icon adornment="leading">
+          <EnvelopeIcon />
+        </InputParts.Icon>
+        <InputParts.Area
+          id="anatomy-email"
+          placeholder="you@example.com"
+          onChangeText={action("onChangeText")}
+        />
+      </InputParts.Box>
+      <InputParts.Meta helperText="We only use this to send receipts." />
+    </InputParts>
+  ),
+};
+
+/**
+ * RING-ON-BOX (LC-71): the Box carries the focus ring so adornments sit inside
+ * it; the Area's own outline is killed. Tab into the field and the whole frame
+ * rings once, not the text run.
+ */
+export const FocusRingOnTheBox: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <Paragraph size="$2">Tab in — the border box rings, the input does not.</Paragraph>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Search" onChangeText={action("onChangeText")} />
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/** Leading and trailing slots. The trailing end-cap is square by size recipe. */
+export const Adornments: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Leading icon" />
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Trailing icon" />
+          <InputParts.Icon adornment="trailing">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Icon adornment="leading">
+            <MagnifyingGlassIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Both ends" />
+          <InputParts.Icon adornment="trailing">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/**
+ * `InputParts.Button` is the pressable end-cap — a reveal toggle, a clear, a
+ * copy. It squares off to the control height so the frame stays rectangular.
+ */
+export const TrailingButton: Story = {
+  render: () => {
+    const Example = () => {
+      const [secure, setSecure] = useState(true);
+      return (
+        <InputParts width={320}>
+          <InputParts.Label htmlFor="parts-password">Password</InputParts.Label>
+          <InputParts.Box paddingInlineEnd={0}>
+            <InputParts.Area
+              id="parts-password"
+              placeholder="••••••••"
+              secureTextEntry={secure}
+              onChangeText={action("onChangeText")}
+            />
+            <InputParts.Button
+              glyphRing
+              type="button"
+              aria-label={secure ? "Show password" : "Hide password"}
+              onPress={() => {
+                setSecure((prev) => !prev);
+                action("togglePasswordVisibility")(!secure);
+              }}
+            >
+              <InputParts.Icon aria-hidden>
+                <EyeIcon />
+              </InputParts.Icon>
+            </InputParts.Button>
+          </InputParts.Box>
+          <InputParts.Meta helperText={secure ? "Hidden" : "Visible"} />
+        </InputParts>
+      );
+    };
+    return <Example />;
+  },
+};
+
+/**
+ * STABLE GROUND (Axiom 8 / DG-FORM-04): `Meta` owns ONE caption slot. The error
+ * replaces the helper in place, so surfacing it shifts nothing below.
+ */
+export const MetaReservesOneLine: Story = {
+  render: () => (
+    <YStack gap="$5" width={320}>
+      <InputParts>
+        <InputParts.Label>Helper</InputParts.Label>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Valid" />
+        </InputParts.Box>
+        <InputParts.Meta helperText="Two to thirty characters." />
+      </InputParts>
+      <InputParts>
+        <InputParts.Label>Error replaces it</InputParts.Label>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Invalid" aria-invalid />
+          <InputParts.Icon adornment="trailing" color="$red10">
+            <WarningCircleIcon aria-hidden />
+          </InputParts.Icon>
+        </InputParts.Box>
+        <InputParts.Meta
+          helperText="Two to thirty characters."
+          displayError="Enter at least two characters."
+        />
+      </InputParts>
+    </YStack>
+  ),
+};
+
+/** `Info` is the caption primitive `Meta` picks; use it directly for prose. */
+export const Info: Story = {
+  render: () => (
+    <InputParts width={320}>
+      <InputParts.Label>Display name</InputParts.Label>
+      <InputParts.Box>
+        <InputParts.Area placeholder="Ada Lovelace" />
+      </InputParts.Box>
+      <InputParts.Info>Shown next to everything you publish.</InputParts.Info>
+    </InputParts>
+  ),
+};
+
+/** `TextArea` is the multi-line Area: same focus wiring, no ring of its own. */
+export const MultiLine: Story = {
+  render: () => (
+    <InputParts width={360}>
+      <InputParts.Label htmlFor="parts-notes">Notes</InputParts.Label>
+      <InputParts.Box alignItems="flex-start" height="auto" paddingVertical="$2">
+        <InputParts.TextArea
+          id="parts-notes"
+          rows={4}
+          placeholder="Anything the team should know"
+          onChangeText={action("onChangeText")}
+        />
+      </InputParts.Box>
+      <InputParts.Meta helperText="Markdown is not parsed here." />
+    </InputParts>
+  ),
+};
+
+/** Disabled chrome lives on the Box, not on the Area. */
+export const DisabledBox: Story = {
+  render: () => (
+    <YStack gap="$4" width={320}>
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Area placeholder="Enabled" />
+        </InputParts.Box>
+      </InputParts>
+      <InputParts>
+        <InputParts.Box disabled>
+          <InputParts.Icon adornment="leading">
+            <EnvelopeIcon />
+          </InputParts.Icon>
+          <InputParts.Area placeholder="Disabled" disabled />
+        </InputParts.Box>
+      </InputParts>
+    </YStack>
+  ),
+};