@multiplatform.one/forms 6.7.0 → 7.0.0

package/src/Form/Form.stories.tsx

@@ -12,8 +12,11 @@ import {
 import { useForm } from "@tanstack/react-form";
 import { useCallback, useState } from "react";
 import { H3, Separator, YStack } from "tamagui";
-import { FormGrid } from "../FormGrid";
 import { Button } from "../Button";
+import { FieldGroup } from "../FieldGroup";
+import { FormGrid } from "../FormGrid";
+import { FormSection, FormSectionStack } from "../FormSection";
+import { formReadableMaxWidth } from "../formSpacing";
 // Note: DataTable was moved to @multiplatform.one/table
 // See table package stories for DataTable + Form integration examples
 import { Barcode } from "../fields/Barcode";
@@ -48,7 +51,7 @@ import { TimePicker } from "../fields/TimePicker";
 import { ToggleGroup } from "../fields/ToggleGroup";
 import { formatFieldError } from "../ErrorSummary";
 import type { AnyFormApi } from "../types";
-import { Form } from "./index";
+import { Form, FormActions } from "./index";
 
 const meta: Meta<typeof Form> = {
   title: "Forms/Form",
@@ -70,6 +73,10 @@ const meta: Meta<typeof Form> = {
       control: "number",
       description: "Debounce time for URL sync in milliseconds",
     },
+    compact: {
+      control: "boolean",
+      description: "Nested scale — compact density for dialogs/overlays (LC-73)",
+    },
   },
 };
 
@@ -78,6 +85,8 @@ type _Story = StoryObj<typeof Form>;
 
 export const Basic = () => (
   <Form
+    maxWidth={formReadableMaxWidth}
+    width="100%"
     formOptions={{
       defaultValues: {
         username: "",
@@ -86,11 +95,11 @@ export const Basic = () => (
     }}
     onSubmit={(values) => action("onSubmit")(values)}
   >
-    <YStack gap="$4">
-      <Input label="Username" name="username" required />
-      <Input label="Email" name="email" required />
+    <Input label="Username" name="username" required />
+    <Input label="Email" name="email" required />
+    <FormActions>
       <Button action="submit">Submit</Button>
-    </YStack>
+    </FormActions>
   </Form>
 );
 Basic.storyName = "Main";
@@ -105,30 +114,30 @@ export const WithValidation = () => (
     }}
     onSubmit={(values) => action("onSubmit")(values)}
   >
-    <YStack gap="$4">
-      <Input
-        label="Password"
-        name="password"
-        validators={{
-          onChange: ({ value }) =>
-            value.length < 8 ? "Password must be at least 8 characters" : undefined,
-        }}
-        required
-      />
-      <Input
-        label="Confirm Password"
-        name="confirmPassword"
-        validators={{
-          onChangeListenTo: ["password"],
-          onChange: ({ value, fieldApi }) => {
-            const password = fieldApi.form.getFieldValue("password");
-            return value !== password ? "Passwords must match" : undefined;
-          },
-        }}
-        required
-      />
+    <Input
+      label="Password"
+      name="password"
+      validators={{
+        onChange: ({ value }) =>
+          value.length < 8 ? "Password must be at least 8 characters" : undefined,
+      }}
+      required
+    />
+    <Input
+      label="Confirm Password"
+      name="confirmPassword"
+      validators={{
+        onChangeListenTo: ["password"],
+        onChange: ({ value, fieldApi }) => {
+          const password = fieldApi.form.getFieldValue("password");
+          return value !== password ? "Passwords must match" : undefined;
+        },
+      }}
+      required
+    />
+    <FormActions>
       <Button action="submit">Create Account</Button>
-    </YStack>
+    </FormActions>
   </Form>
 );
 
@@ -151,49 +160,51 @@ export const WithErrorSummary = () => (
     }}
     onSubmit={(values) => action("onSubmit")(values)}
     errorSummaryTitle="There is a problem"
+    maxWidth={formReadableMaxWidth}
+    width="100%"
   >
-    <YStack gap="$4" maxWidth={480}>
-      <Input
-        id="fullName"
-        name="fullName"
-        label="Full name"
-        required
-        validators={{
-          onSubmit: ({ value }) =>
-            !String(value || "").trim()
-              ? formatFieldError({
-                  problem: "Full name is empty.",
-                  action: "Enter your first and last name.",
-                })
-              : undefined,
-        }}
-      />
-      <Input
-        id="email"
-        name="email"
-        label="Email"
-        required
-        validators={{
-          onSubmit: ({ value }) => {
-            const v = String(value || "");
-            if (!v.trim()) {
-              return formatFieldError({
-                problem: "Email is empty.",
-                action: "Enter an email address.",
-              });
-            }
-            if (!v.includes("@")) {
-              return formatFieldError({
-                problem: "Email is incomplete.",
-                action: "Include an @ and a domain.",
-              });
-            }
-            return undefined;
-          },
-        }}
-      />
+    <Input
+      id="fullName"
+      name="fullName"
+      label="Full name"
+      required
+      validators={{
+        onSubmit: ({ value }) =>
+          !String(value || "").trim()
+            ? formatFieldError({
+                problem: "Full name is empty.",
+                action: "Enter your first and last name.",
+              })
+            : undefined,
+      }}
+    />
+    <Input
+      id="email"
+      name="email"
+      label="Email"
+      required
+      validators={{
+        onSubmit: ({ value }) => {
+          const v = String(value || "");
+          if (!v.trim()) {
+            return formatFieldError({
+              problem: "Email is empty.",
+              action: "Enter an email address.",
+            });
+          }
+          if (!v.includes("@")) {
+            return formatFieldError({
+              problem: "Email is incomplete.",
+              action: "Include an @ and a domain.",
+            });
+          }
+          return undefined;
+        },
+      }}
+    />
+    <FormActions>
       <Button action="submit">Save contact</Button>
-    </YStack>
+    </FormActions>
   </Form>
 );
 WithErrorSummary.parameters = {
@@ -219,54 +230,54 @@ export const DynamicFields = () => {
 
   return (
     <Form form={form} onSubmit={() => form.handleSubmit()}>
-      <YStack gap="$4">
-        <Select
-          label="Account Type"
-          name="accountType"
-          required
-          // >5 options: shorter single-select lists trip `select-too-few-options` (DG-CTRL-01).
-          options={[
-            { label: "Personal", value: "personal" },
-            { label: "Business", value: "business" },
-            { label: "Nonprofit", value: "nonprofit" },
-            { label: "Government", value: "government" },
-            { label: "Education", value: "education" },
-            { label: "Other", value: "other" },
-          ]}
-        />
+      <Select
+        label="Account Type"
+        name="accountType"
+        required
+        // >5 options: shorter single-select lists trip `select-too-few-options` (DG-CTRL-01).
+        options={[
+          { label: "Personal", value: "personal" },
+          { label: "Business", value: "business" },
+          { label: "Nonprofit", value: "nonprofit" },
+          { label: "Government", value: "government" },
+          { label: "Education", value: "education" },
+          { label: "Other", value: "other" },
+        ]}
+      />
 
-        {(() => {
-          const FormSubscribe = (
-            form as {
-              Subscribe: (p: { selector: (s: any) => any[]; children: (v: any[]) => any }) => any;
-            }
-          ).Subscribe;
-          return (
-            <FormSubscribe selector={(state: any) => [state.values.accountType]}>
-              {([accountType]) => (
-                <>
-                  {accountType === "business" ? (
-                    <Input
-                      label="Company Name"
-                      name="companyName"
-                      required
-                      helperText="Enter your company name"
-                    />
-                  ) : (
-                    <Input
-                      label="Personal Info"
-                      name="personalInfo"
-                      helperText="Tell us about yourself"
-                    />
-                  )}
-                </>
-              )}
-            </FormSubscribe>
-          );
-        })()}
+      {(() => {
+        const FormSubscribe = (
+          form as {
+            Subscribe: (p: { selector: (s: any) => any[]; children: (v: any[]) => any }) => any;
+          }
+        ).Subscribe;
+        return (
+          <FormSubscribe selector={(state: any) => [state.values.accountType]}>
+            {([accountType]) => (
+              <>
+                {accountType === "business" ? (
+                  <Input
+                    label="Company Name"
+                    name="companyName"
+                    required
+                    helperText="Enter your company name"
+                  />
+                ) : (
+                  <Input
+                    label="Personal Info"
+                    name="personalInfo"
+                    helperText="Tell us about yourself"
+                  />
+                )}
+              </>
+            )}
+          </FormSubscribe>
+        );
+      })()}
 
+      <FormActions>
         <Button action="submit">Submit</Button>
-      </YStack>
+      </FormActions>
     </Form>
   );
 };
@@ -282,12 +293,12 @@ export const ReadOnlyAndDisabledSubmit = () => (
     }}
     onSubmit={(values) => action("onSubmit")(values)}
   >
-    <YStack gap="$4">
-      <Input label="Editable" name="editable" />
-      <Input label="Read Only" name="readOnlyField" readOnly />
-      <Input label="Disabled" name="disabledField" disabled />
+    <Input label="Editable" name="editable" />
+    <Input label="Read Only" name="readOnlyField" readOnly />
+    <Input label="Disabled" name="disabledField" disabled />
+    <FormActions>
       <Button action="submit">Submit</Button>
-    </YStack>
+    </FormActions>
   </Form>
 );
 ReadOnlyAndDisabledSubmit.parameters = {
@@ -308,15 +319,15 @@ export const InputWithLinkResolver = () => (
     }}
     onSubmit={(values) => action("onSubmit")(values)}
   >
-    <YStack gap="$4">
-      <Input
-        label="Item Code (readOnly + linkResolver)"
-        name="itemCode"
-        readOnly
-        linkResolver={(v) => (v ? (`/items/${String(v)}` as any) : null)}
-      />
+    <Input
+      label="Item Code (readOnly + linkResolver)"
+      name="itemCode"
+      readOnly
+      linkResolver={(v) => (v ? (`/items/${String(v)}` as any) : null)}
+    />
+    <FormActions>
       <Button action="submit">Submit</Button>
-    </YStack>
+    </FormActions>
   </Form>
 );
 InputWithLinkResolver.parameters = {
@@ -664,7 +675,7 @@ export const AllFields = () => {
     <Form form={form}>
       <YStack gap="$4">
         <H3>Field Height Comparison (2 columns)</H3>
-        <FormGrid columns={2} gap={16}>
+        <FormGrid columns={2}>
           <Input
             label="Full Name"
             name="fullName"
@@ -800,7 +811,7 @@ export const AllFields = () => {
 
         <Separator marginTop="$4" />
         <H3>Multi-line Fields</H3>
-        <FormGrid columns={2} gap={16}>
+        <FormGrid columns={2}>
           <TextArea
             label="Bio"
             name="bio"
@@ -931,6 +942,46 @@ AllFields.parameters = {
   },
 };
 
+/**
+ * Polaris FormLayout + GOV.UK fieldset rhythm: single column, related
+ * short fields grouped, section gap > field gap, left-aligned actions.
+ */
+export const Layout = () => (
+  <Form
+    maxWidth={formReadableMaxWidth}
+    width="100%"
+    formOptions={{
+      defaultValues: {
+        firstName: "",
+        lastName: "",
+        email: "",
+        city: "",
+        postcode: "",
+      },
+    }}
+    onSubmit={(values) => action("onSubmit")(values)}
+  >
+    <FormSectionStack>
+      <FormSection label="Contact">
+        <FieldGroup legend="Name" columns={2}>
+          <Input label="First name" name="firstName" required />
+          <Input label="Last name" name="lastName" required />
+        </FieldGroup>
+        <Input label="Email" name="email" required />
+      </FormSection>
+      <FormSection label="Address">
+        <FieldGroup legend="Location" columns={2}>
+          <Input label="City" name="city" />
+          <Input label="Postcode" name="postcode" />
+        </FieldGroup>
+      </FormSection>
+    </FormSectionStack>
+    <FormActions>
+      <Button action="submit">Save</Button>
+    </FormActions>
+  </Form>
+);
+
 const shortListDefaults = {
   fullName: "",
   email: "",

package/src/Form/form.spec.tsx

@@ -3,9 +3,10 @@ import { act, fireEvent, waitFor } from "@testing-library/react";
 import { YStack } from "tamagui";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
 import { Button } from "../Button";
 import { Input } from "../fields/Input";
-import { Form, useFormContext } from "./index";
+import { Form, FormActions, useFormContext } from "./index";
 
 // Mock @multiplatform.one/router at top level
 const mockSetUrlState = vi.fn();
@@ -370,4 +371,45 @@ describe("Form", () => {
       });
     });
   });
+
+  describe("layout recipes (DG-FORM-01/06, LC-73)", () => {
+    it("owns vertical rhythm from the space recipe, not sizeToken", () => {
+      const result = renderWithProviders(
+        <Preset overrides={{ size: "large", space: "small" }}>
+          <Form onSubmit={vi.fn()} aria-label="Layout Form">
+            <YStack>Content</YStack>
+          </Form>
+        </Preset>,
+      );
+      const layout = result.container.querySelector("[data-mpo-form-layout]");
+      expect(layout?.getAttribute("data-gap")).toBe("$2");
+      expect(layout?.getAttribute("data-size")).toBe("large");
+      expect(layout?.getAttribute("data-density")).toBe("comfortable");
+    });
+
+    it("compact nested scale steps space and size together via shared density", () => {
+      const result = renderWithProviders(
+        <Form compact onSubmit={vi.fn()}>
+          <YStack>Content</YStack>
+        </Form>,
+      );
+      const layout = result.container.querySelector("[data-mpo-form-layout]");
+      expect(layout?.getAttribute("data-nested")).toBe("true");
+      expect(layout?.getAttribute("data-density")).toBe("compact");
+      expect(layout?.getAttribute("data-size")).toBe("small");
+      expect(layout?.getAttribute("data-gap")).toBe("$2");
+    });
+
+    it("FormActions hugs content and uses the space recipe", () => {
+      const result = renderWithProviders(
+        <Preset overrides={{ space: "small", size: "large" }}>
+          <FormActions>
+            <Button action="submit">Save</Button>
+          </FormActions>
+        </Preset>,
+      );
+      const actions = result.container.querySelector("[data-mpo-form-actions]");
+      expect(actions?.getAttribute("data-gap")).toBe("$2");
+    });
+  });
 });

package/src/Form/index.tsx

@@ -1,5 +1,5 @@
 import { useUrlState } from "@multiplatform.one/router";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Preset, useResolvedKnobs } from "@multiplatform.one/theme";
 import { type FormApi, type FormOptions, useForm } from "@tanstack/react-form";
 import {
   type FormEvent,
@@ -10,7 +10,13 @@ import {
   useMemo,
   useRef,
 } from "react";
-import { Form as TamaguiForm, type FormProps as TamaguiFormProps, isWeb } from "tamagui";
+import {
+  Form as TamaguiForm,
+  type FormProps as TamaguiFormProps,
+  XStack,
+  YStack,
+  isWeb,
+} from "tamagui";
 import { ErrorSummary, collectFormFieldErrors, type ErrorSummaryItem } from "../ErrorSummary";
 import { RequiredMarkingContext, mapHouseRequiredMarking } from "../requiredMarking";
 import { type FormValidateOn, resolveEffectiveValidateOn } from "./validateOn";
@@ -86,6 +92,13 @@ export interface FormProps<TFormData, _TFormValidator = any> extends Omit<
    * Explicit `"blur"` / `"change"` always attach those listeners.
    */
   validateOn?: FormValidateOn;
+  /**
+   * Nested scale (LC-73). Steps space + size down one level and wraps
+   * descendants in a compact density Preset so fields inherit the same
+   * scale without a per-field `compact` prop. Density/space still own
+   * gaps; size still owns control height (density≠size).
+   */
+  compact?: boolean;
 }
 
 function AutoErrorSummary({
@@ -174,9 +187,10 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
   showErrorSummary = true,
   errorSummaryTitle,
   validateOn = "submit",
+  compact,
   ...tamaguiFormProps
 }: FormProps<TFormData, TFormValidator>) {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps } = useResolvedKnobs(compact === undefined ? undefined : { compact });
   const requiredMarkMode = mapHouseRequiredMarking(knobProps.requiredMarking);
   const formAutofocusOn = knobProps.formAutofocus === "on";
 
@@ -269,24 +283,65 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
     didAutofocusRef.current = true;
   }, [formAutofocusOn, children]);
 
-  return (
+  const formNode = (
     <FormContext.Provider value={form}>
       <RequiredMarkingContext.Provider value={{ mode: requiredMarkMode }}>
         <FormValidateProvider form={form} validateOn={validateOn}>
           <TamaguiForm ref={setFormRef} onSubmit={handleSubmit} {...tamaguiFormProps}>
-            {showErrorSummary ? (
-              <AutoErrorSummary
-                form={form}
-                title={errorSummaryTitle}
-                formElement={formElementRef.current}
-              />
-            ) : null}
-            {children}
+            <YStack
+              data-mpo-form-layout=""
+              data-gap={knobProps.gap.gap}
+              data-density={knobProps.density}
+              data-size={knobProps.size}
+              data-nested={compact ? "true" : undefined}
+              width="100%"
+              minWidth={0}
+              {...knobProps.gap}
+              {...(tamaguiFormProps.flex != null ? { flex: tamaguiFormProps.flex as never } : {})}
+            >
+              {showErrorSummary ? (
+                <AutoErrorSummary
+                  form={form}
+                  title={errorSummaryTitle}
+                  formElement={formElementRef.current}
+                />
+              ) : null}
+              {children}
+            </YStack>
           </TamaguiForm>
         </FormValidateProvider>
       </RequiredMarkingContext.Provider>
     </FormContext.Provider>
   );
+
+  return compact ? <Preset overrides={{ density: "compact" }}>{formNode}</Preset> : formNode;
+}
+
+export interface FormActionsProps {
+  children: ReactNode;
+  /** Eject the within-group gap recipe. */
+  gap?: number | string;
+}
+
+/**
+ * GOV.UK / Polaris action row: left-aligned, wraps, gapped via the space
+ * recipe — never stretched to the form column and never sized from `sizeToken`.
+ */
+export function FormActions({ children, gap }: FormActionsProps) {
+  const { knobProps } = useResolvedKnobs();
+  const resolvedGap = gap ?? knobProps.gap.gap;
+  return (
+    <XStack
+      data-mpo-form-actions=""
+      data-gap={String(resolvedGap)}
+      gap={resolvedGap as never}
+      alignSelf="flex-start"
+      alignItems="center"
+      flexWrap="wrap"
+    >
+      {children}
+    </XStack>
+  );
 }
 
 /** @internal test helper — effective timing for current FormValidate context. */

package/src/FormGrid.spec.tsx

@@ -78,6 +78,9 @@ describe("FormGrid", () => {
     expect(grid?.getAttribute("data-columns")).toBe("1");
     expect(grid?.getAttribute("data-requested-columns")).toBe("1");
     expect(grid?.getAttribute("data-max-columns")).toBe("2");
+    expect(grid?.getAttribute("data-gap")).toBe("$4");
+    expect(grid?.getAttribute("data-density")).toBe("comfortable");
+    expect(grid?.getAttribute("data-size")).toBe("medium");
   });
 
   it("caps columns at maxColumns", () => {
@@ -126,6 +129,31 @@ describe("FormGrid", () => {
     expect(grid.getAttribute("data-columns")).toBe("1");
     expect(grid.style.gridTemplateColumns).toBe("repeat(1, minmax(0, 1fr))");
   });
+
+  it("gap follows the space recipe, not sizeToken (density≠size)", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ size: "large", space: "small" }}>
+        <FormGrid>
+          <div>a</div>
+        </FormGrid>
+      </Preset>,
+    );
+    const grid = result.container.querySelector("[data-mpo-form-grid]");
+    expect(grid?.getAttribute("data-gap")).toBe("$2");
+    expect(grid?.getAttribute("data-size")).toBe("large");
+  });
+
+  it("compact steps space down without reading sizeToken as gap", () => {
+    const result = renderWithProviders(
+      <FormGrid compact>
+        <div>a</div>
+      </FormGrid>,
+    );
+    const grid = result.container.querySelector("[data-mpo-form-grid]");
+    expect(grid?.getAttribute("data-density")).toBe("compact");
+    expect(grid?.getAttribute("data-size")).toBe("small");
+    expect(grid?.getAttribute("data-gap")).toBe("$2");
+  });
 });
 
 describe("FieldGroup", () => {
@@ -153,6 +181,19 @@ describe("FieldGroup", () => {
       result.container.querySelector("[data-mpo-field-group]")?.getAttribute("data-columns"),
     ).toBe("2");
   });
+
+  it("field gap follows space, not size (density≠size)", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ size: "large", space: "small" }}>
+        <FieldGroup legend="Billing">
+          <div>card</div>
+        </FieldGroup>
+      </Preset>,
+    );
+    const group = result.container.querySelector("[data-mpo-field-group]");
+    expect(group?.getAttribute("data-field-gap")).toBe("$2");
+    expect(group?.getAttribute("data-size")).toBe("large");
+  });
 });
 
 describe("FormSection", () => {