@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/FormGrid.stories.tsx

@@ -0,0 +1,135 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Input as TamaguiInput, Paragraph, YStack } from "tamagui";
+import { FieldGroup } from "./FieldGroup";
+import { FormGrid } from "./FormGrid";
+import { FormSection, FormSectionStack } from "./FormSection";
+import { FieldLayout } from "./fieldLayout";
+
+const meta: Meta<typeof FormGrid> = {
+  title: "Forms/FormGrid",
+  component: FormGrid,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    columns: { control: { type: "number", min: 1, max: 2 } },
+    maxColumns: { control: { type: "number", min: 1, max: 2 } },
+    gap: { control: { type: "number", min: 0, max: 64 } },
+  },
+  args: {
+    columns: 1,
+    maxColumns: 2,
+    gap: 16,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FormGrid>;
+
+function GridField({ id, label }: { id: string; label: string }) {
+  return (
+    <FieldLayout id={id} label={label}>
+      <TamaguiInput id={id} placeholder={label} />
+    </FieldLayout>
+  );
+}
+
+export const Basic: Story = {
+  name: "Basic (single column default)",
+  render: (args) => (
+    <YStack maxWidth={640}>
+      <FormGrid {...args}>
+        <GridField id="fg-first" label="First name" />
+        <GridField id="fg-last" label="Last name" />
+        <GridField id="fg-email" label="Email" />
+        <GridField id="fg-phone" label="Phone" />
+      </FormGrid>
+    </YStack>
+  ),
+};
+
+export const TwoColumnsWide: Story = {
+  name: "Two columns (wide)",
+  render: () => (
+    <YStack maxWidth={720} borderWidth={1} borderColor="$borderColor" padding="$3">
+      <FormGrid columns={2} gap={16}>
+        <GridField id="fg2-first" label="First name" />
+        <GridField id="fg2-last" label="Last name" />
+        <GridField id="fg2-email" label="Email" />
+        <GridField id="fg2-phone" label="Phone" />
+      </FormGrid>
+    </YStack>
+  ),
+};
+
+export const ChildCounts: Story = {
+  render: () => (
+    <YStack gap="$6" maxWidth={640}>
+      <Paragraph size="$2">zero children</Paragraph>
+      <FormGrid columns={2}>{null}</FormGrid>
+      <Paragraph size="$2">one child</Paragraph>
+      <FormGrid columns={2}>
+        <GridField id="fg1-only" label="Only field" />
+      </FormGrid>
+      <Paragraph size="$2">odd count (last cell hangs)</Paragraph>
+      <FormGrid columns={2}>
+        <GridField id="fgo-a" label="A" />
+        <GridField id="fgo-b" label="B" />
+        <GridField id="fgo-c" label="C" />
+      </FormGrid>
+    </YStack>
+  ),
+};
+
+export const NarrowContainer: Story = {
+  name: "Narrow container (collapses to 1)",
+  render: () => (
+    <YStack maxWidth={280} borderWidth={1} borderColor="$borderColor" padding="$2">
+      <Paragraph size="$2" marginBottom="$2">
+        columns=2 inside 280px → must render as 1 column
+      </Paragraph>
+      <FormGrid columns={2} gap={12}>
+        <GridField id="fgn-a" label="Cramped field one" />
+        <GridField id="fgn-b" label="Cramped field two" />
+        <GridField id="fgn-c" label="Cramped field three" />
+        <GridField id="fgn-d" label="Cramped field four" />
+      </FormGrid>
+    </YStack>
+  ),
+};
+
+export const LongErrors: Story = {
+  render: () => (
+    <YStack maxWidth={640}>
+      <FormGrid columns={2}>
+        <FieldLayout
+          id="fge-a"
+          label="With long error"
+          error="This validation message is extremely long and should wrap inside its own grid cell without breaking the neighbouring column alignment or overflowing the grid container"
+        >
+          <TamaguiInput id="fge-a" />
+        </FieldLayout>
+        <GridField id="fge-b" label="Neighbour" />
+      </FormGrid>
+    </YStack>
+  ),
+};
+
+export const FieldGroupAndSections: Story = {
+  name: "FieldGroup + FormSection rhythm",
+  render: () => (
+    <FormSectionStack>
+      <FormSection label="Contact">
+        <FieldGroup legend="Name" columns={2}>
+          <GridField id="fgs-first" label="First name" />
+          <GridField id="fgs-last" label="Last name" />
+        </FieldGroup>
+        <GridField id="fgs-email" label="Email" />
+      </FormSection>
+      <FormSection label="Address">
+        <FieldGroup legend="Location">
+          <GridField id="fgs-street" label="Street" />
+          <GridField id="fgs-city" label="City" />
+        </FieldGroup>
+      </FormSection>
+    </FormSectionStack>
+  ),
+};

package/src/FormGrid.tsx

@@ -1,45 +1,181 @@
-import { Children, type ReactNode } from "react";
-import { XStack, YStack, isWeb } from "tamagui";
+import {
+  Children,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { XStack, YStack, isWeb, useMedia } from "tamagui";
+
+/** Container/media width below which multi-column form grids collapse to 1 col. */
+export const FORM_GRID_COLLAPSE_WIDTH = 480;
+
+export type FormGridColumns = 1 | 2;
 
 export interface FormGridProps {
-  /** Number of columns. Default: 2 */
-  columns?: number;
+  /**
+   * Requested columns when the container is comfortable.
+   * Default: 1 (DG-FORM-01 single-column default).
+   */
+  columns?: FormGridColumns;
+  /**
+   * Hard cap on columns (DG-FORM-01 / responsive 2-col groups).
+   * Default: 2.
+   */
+  maxColumns?: FormGridColumns;
   /** Gap between fields in pixels. Default: 16 */
   gap?: number;
   children: ReactNode;
 }
 
+function resolveWideColumns(
+  columns: FormGridColumns,
+  maxColumns: FormGridColumns,
+): FormGridColumns {
+  return Math.min(columns, maxColumns) as FormGridColumns;
+}
+
 /**
  * Lays out form fields in a grid with correct tab order (left-to-right across rows).
  *
  * List children in visual row order: [row1col1, row1col2, row2col1, row2col2, ...]
  *
- * On web, uses CSS grid so DOM order matches visual row order and tab follows rows.
- * On native, groups children into XStack rows.
+ * Defaults to a single column. When `columns={2}`, expands to two columns only when
+ * the container is at least {@link FORM_GRID_COLLAPSE_WIDTH} wide (container measure
+ * on web; viewport media on native).
  */
-export function FormGrid({ columns = 2, gap = 16, children }: FormGridProps) {
+export function FormGrid({ columns = 1, maxColumns = 2, gap = 16, children }: FormGridProps) {
+  const wideColumns = resolveWideColumns(columns, maxColumns);
+
   if (isWeb) {
     return (
-      <div
-        style={{
-          display: "grid",
-          gridTemplateColumns: `repeat(${columns}, 1fr)`,
-          gap: `${gap}px`,
-        }}
-      >
+      <FormGridWeb columns={wideColumns} maxColumns={maxColumns} gap={gap}>
         {children}
-      </div>
+      </FormGridWeb>
     );
   }
 
+  return (
+    <FormGridNative columns={wideColumns} gap={gap}>
+      {children}
+    </FormGridNative>
+  );
+}
+
+function FormGridWeb({
+  columns,
+  maxColumns,
+  gap,
+  children,
+}: {
+  columns: FormGridColumns;
+  maxColumns: FormGridColumns;
+  gap: number;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [containerWide, setContainerWide] = useState(true);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || columns <= 1) {
+      setContainerWide(true);
+      return;
+    }
+
+    const update = (width: number) => {
+      setContainerWide(width >= FORM_GRID_COLLAPSE_WIDTH);
+    };
+
+    update(el.getBoundingClientRect().width);
+
+    if (typeof ResizeObserver === "undefined") {
+      const onResize = () => update(el.getBoundingClientRect().width);
+      window.addEventListener("resize", onResize);
+      return () => window.removeEventListener("resize", onResize);
+    }
+
+    const ro = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? el.getBoundingClientRect().width;
+      update(width);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [columns]);
+
+  const effectiveColumns: FormGridColumns = columns <= 1 || !containerWide ? 1 : columns;
+
+  const style: CSSProperties = {
+    display: "grid",
+    gap: `${gap}px`,
+    gridTemplateColumns: `repeat(${effectiveColumns}, minmax(0, 1fr))`,
+    // Enable container queries for consumers / CSS extensions (DG-FORM-09).
+    containerType: columns > 1 ? "inline-size" : undefined,
+  };
+
+  return (
+    <div
+      ref={ref}
+      data-mpo-form-grid=""
+      data-columns={effectiveColumns}
+      data-max-columns={maxColumns}
+      data-requested-columns={columns}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}
+
+function FormGridNative({
+  columns,
+  gap,
+  children,
+}: {
+  columns: FormGridColumns;
+  gap: number;
+  children: ReactNode;
+}) {
+  const media = useMedia();
+  // React Native defines a `window` global without DOM event methods or
+  // innerWidth, so bare `typeof window` checks are not enough — the resize
+  // listener crashed on native ("window.addEventListener is not a function").
+  const canUseDomResize =
+    typeof window !== "undefined" &&
+    typeof window.addEventListener === "function" &&
+    typeof window.innerWidth === "number";
+  // Prefer live viewport width when available; fall back to Tamagui media
+  // (gtSm ≈ 801), which stays reactive on native.
+  const [domViewportWide, setDomViewportWide] = useState(() =>
+    canUseDomResize ? window.innerWidth >= FORM_GRID_COLLAPSE_WIDTH : true,
+  );
+
+  useEffect(() => {
+    if (!canUseDomResize) return;
+    const handler = () => setDomViewportWide(window.innerWidth >= FORM_GRID_COLLAPSE_WIDTH);
+    handler();
+    window.addEventListener("resize", handler);
+    return () => window.removeEventListener("resize", handler);
+  }, [canUseDomResize]);
+
+  const viewportWide = canUseDomResize ? domViewportWide : media.gtSm === true;
+  const effectiveColumns: FormGridColumns = columns <= 1 || !viewportWide ? 1 : columns;
+
   const childArray = Children.toArray(children);
   const rows: ReactNode[][] = [];
-  for (let i = 0; i < childArray.length; i += columns) {
-    rows.push(childArray.slice(i, i + columns));
+  for (let i = 0; i < childArray.length; i += effectiveColumns) {
+    rows.push(childArray.slice(i, i + effectiveColumns));
   }
 
   return (
-    <YStack gap={gap}>
+    <YStack
+      gap={gap}
+      data-columns={effectiveColumns}
+      data-max-columns={columns}
+      data-requested-columns={columns}
+    >
       {rows.map((row, rowIndex) => (
         <XStack key={rowIndex} gap={gap}>
           {row.map((child, colIndex) => (

package/src/FormSection.tsx

@@ -0,0 +1,130 @@
+import type { ReactNode } from "react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Text, YStack, isWeb } from "tamagui";
+import { formReadableMaxWidth } from "./formSpacing";
+
+export interface FormSectionProps {
+  /** Section heading / legend. */
+  label?: string;
+  children: ReactNode;
+  /**
+   * Cap readable width (DG-FORM-08). Pass `"fluid"` to opt out.
+   * Default: {@link formReadableMaxWidth} (560).
+   */
+  maxWidth?: number | "fluid";
+  /**
+   * Gap between fields inside the section. Defaults to the semantic
+   * within-group gap (`knobProps.gap`, DG-LAY-03) so the space knob
+   * restyles form rhythm; explicit values eject.
+   */
+  gap?: number | string;
+  /** Extra props forwarded to the outer stack (e.g. test ids). */
+  testID?: string;
+  /**
+   * When true (default), render semantic `<fieldset>` + `<legend>` on web
+   * so assistive tech groups the fields. Native keeps a heading label.
+   */
+  fieldset?: boolean;
+}
+
+/**
+ * Labeled form section with semantic gap rhythm.
+ *
+ * Field gap defaults to the within-group semantic gap (`knobProps.gap`);
+ * stack multiple sections with {@link FormSectionStack}, whose gap defaults
+ * to the between-groups gap (`knobProps.gapLg`) — always one step larger, so
+ * section rhythm stays larger than field rhythm at every space knob value
+ * (DG-FORM-06 / DG-LAY-03). Gallery **Fieldset** is this component (also
+ * exported as {@link Fieldset}).
+ */
+export function FormSection({
+  label,
+  children,
+  maxWidth = formReadableMaxWidth,
+  gap,
+  testID,
+  fieldset = true,
+}: FormSectionProps) {
+  const useFieldset = fieldset && isWeb;
+  const { knobProps } = useResolvedKnobs();
+  const resolvedGap = gap ?? knobProps.gap.gap;
+
+  return (
+    <YStack
+      {...(useFieldset ? { render: "fieldset" as const } : {})}
+      data-mpo-form-section=""
+      data-mpo-fieldset={useFieldset ? "" : undefined}
+      data-field-gap={String(resolvedGap)}
+      data-testid={testID}
+      gap={resolvedGap as any}
+      width="100%"
+      maxWidth={maxWidth === "fluid" ? undefined : maxWidth}
+      alignSelf={maxWidth === "fluid" ? undefined : "flex-start"}
+      // Reset browser fieldset chrome; we own spacing via tokens.
+      {...(useFieldset
+        ? {
+            style: {
+              borderWidth: 0,
+              margin: 0,
+              minWidth: 0,
+              padding: 0,
+            } as Record<string, unknown>,
+          }
+        : {})}
+    >
+      {label ? (
+        useFieldset ? (
+          <Text
+            render="legend"
+            fontWeight="600"
+            fontSize="$5"
+            // legend is inline by default; stretch to a full heading row
+            style={{ padding: 0, marginBottom: 0, float: "left", width: "100%" } as any}
+          >
+            {label}
+          </Text>
+        ) : (
+          <Text fontWeight="600" fontSize="$5" role="heading" aria-level={3}>
+            {label}
+          </Text>
+        )
+      ) : null}
+      {children}
+    </YStack>
+  );
+}
+
+/**
+ * Gallery Fieldset — semantic fieldset/legend grouping.
+ * Alias of {@link FormSection} (same API, form-section rhythm tokens).
+ */
+export const Fieldset = FormSection;
+export type FieldsetProps = FormSectionProps;
+
+export interface FormSectionStackProps {
+  children: ReactNode;
+  /**
+   * Gap between sections. Defaults to the semantic between-groups gap
+   * (`knobProps.gapLg`) — one step above the field gap at every space
+   * knob value (DG-FORM-06). Explicit values eject.
+   */
+  gap?: number | string;
+}
+
+/** Stacks FormSections with section > field spacing. */
+export function FormSectionStack({ children, gap }: FormSectionStackProps) {
+  const { knobProps } = useResolvedKnobs();
+  const resolvedGap = gap ?? knobProps.gapLg.gap;
+  return (
+    <YStack
+      data-mpo-form-section-stack=""
+      data-section-gap={String(resolvedGap)}
+      gap={resolvedGap as any}
+      width="100%"
+    >
+      {children}
+    </YStack>
+  );
+}
+
+export { formFieldGap, formReadableMaxWidth, formSectionGap } from "./formSpacing";

package/src/FormsIntegration.stories.tsx

@@ -114,7 +114,8 @@ export const multiStepRegistration = () => {
           onChange: ({ value }) => {
             if (!value) return "Email is required";
             if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
-              return "Please enter a valid email";
+              // DG-COPY-02: no please/invalid — state the requirement.
+              return "Email must include an @ and a domain";
             }
           },
         }}
@@ -157,7 +158,7 @@ export const multiStepRegistration = () => {
         validators={{
           onChange: ({ value }) => {
             const password = form.getFieldValue("password");
-            if (!value) return "Please confirm your password";
+            if (!value) return "Enter the password again to confirm";
             if (value !== password) return "Passwords do not match";
           },
         }}
@@ -182,6 +183,7 @@ export const multiStepRegistration = () => {
           { label: "United Kingdom", value: "GB" },
           { label: "Germany", value: "DE" },
           { label: "France", value: "FR" },
+          { label: "Japan", value: "JP" },
         ]}
         placeholder="Select your country"
       />
@@ -223,7 +225,7 @@ export const multiStepRegistration = () => {
         Verification
       </Paragraph>
 
-      <Paragraph>Please enter the 6-digit verification code sent to your email.</Paragraph>
+      <Paragraph>Enter the 6-digit verification code sent to your email.</Paragraph>
 
       <OTPInput
         form={form as unknown as AnyFormApi}
@@ -233,7 +235,8 @@ export const multiStepRegistration = () => {
         validators={{
           onChange: ({ value }) => {
             if (!value || value.length !== 6) {
-              return "Please enter a valid 6-digit code";
+              // DG-COPY-02: no please/valid-shaming — state the requirement.
+              return "Code must be 6 digits";
             }
           },
         }}
@@ -307,10 +310,12 @@ export const inputComposition = () => {
 
             <Input label="Required Field" placeholder="This field is required" required />
 
+            {/* DG-COPY-02: error copy states the problem + fix without the
+                banned invalid/error/please words. */}
             <Input
               label="With Error"
-              placeholder="Invalid input"
-              error="This field has a validation error"
+              placeholder="Letters and spaces"
+              error="Value must use letters and spaces only"
               defaultValue="bad value"
             />
 
@@ -322,12 +327,17 @@ export const inputComposition = () => {
               maxLength={500}
             />
 
+            {/* DG-CTRL-01: >5 options so the Select doesn't trip
+                `select-too-few-options` (UX-P19). */}
             <Select
               label="Country"
               options={[
                 { label: "United States", value: "US" },
                 { label: "Canada", value: "CA" },
                 { label: "United Kingdom", value: "GB" },
+                { label: "Germany", value: "DE" },
+                { label: "France", value: "FR" },
+                { label: "Japan", value: "JP" },
               ]}
               placeholder="Select your country"
             />
@@ -352,7 +362,7 @@ export const inputComposition = () => {
             </Input>
 
             <Input>
-              <Input.Label color="$blue10" fontWeight="bold">
+              <Input.Label color="$blue11" fontWeight="bold">
                 Styled Label
               </Input.Label>
               <Input.Box>
@@ -361,12 +371,12 @@ export const inputComposition = () => {
             </Input>
 
             <Input error>
-              <Input.Label color="$red10">Error State (compound)</Input.Label>
+              <Input.Label color="$red11">Error State (compound)</Input.Label>
               <Input.Box>
                 <Input.Area placeholder="Something went wrong" />
               </Input.Box>
-              <Input.Info color="$red10" role="alert">
-                This field is invalid
+              <Input.Info color="$red11" role="alert">
+                This value must match the expected format
               </Input.Info>
             </Input>
           </YStack>

package/src/InputParts/index.spec.tsx

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Input } from "./index";
+
+describe("Input.Meta reserved message slot (Axiom 8 / DG-FORM-04)", () => {
+  it("renders helper text when there is no error", () => {
+    const { getByText, queryByRole } = renderWithProviders(
+      <Input.Meta helperText="We never share this" />,
+    );
+    expect(getByText("We never share this")).toBeTruthy();
+    expect(queryByRole("alert")).toBeNull();
+  });
+
+  it("renders the error when there is no helper", () => {
+    const { getByRole } = renderWithProviders(<Input.Meta displayError="Enter a value" />);
+    expect(getByRole("alert").textContent).toBe("Enter a value");
+  });
+
+  it("error replaces helper — one slot, never siblings", () => {
+    const { getByRole, queryByText } = renderWithProviders(
+      <Input.Meta helperText="We never share this" displayError="Enter a value" />,
+    );
+    expect(getByRole("alert").textContent).toBe("Enter a value");
+    expect(queryByText("We never share this")).toBeNull();
+  });
+
+  it("boolean error carries no message, so the helper keeps the slot", () => {
+    const { getByText, queryByRole } = renderWithProviders(
+      <Input.Meta helperText="We never share this" displayError />,
+    );
+    expect(getByText("We never share this")).toBeTruthy();
+    expect(queryByRole("alert")).toBeNull();
+  });
+
+  it("renders nothing when neither helper nor error is provided", () => {
+    const { container } = renderWithProviders(<Input.Meta />);
+    expect(container.textContent).toBe("");
+  });
+});