@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/ControlGroup/ControlGroup.stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Input as TamaguiInput, Paragraph, YStack } from "tamagui";
+import { Button } from "../Button";
+import { ControlGroup } from "./index";
+
+const meta: Meta<typeof ControlGroup> = {
+  title: "Forms/ControlGroup",
+  component: ControlGroup,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    orientation: { control: "select", options: ["horizontal", "vertical"] },
+  },
+  args: {
+    orientation: "horizontal",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ControlGroup>;
+
+export const Basic: Story = {
+  render: (args) => (
+    <YStack maxWidth={420}>
+      <ControlGroup {...args}>
+        <Button>First</Button>
+        <Button>Middle</Button>
+        <Button>Last</Button>
+      </ControlGroup>
+    </YStack>
+  ),
+};
+
+export const Vertical: Story = {
+  render: () => (
+    <YStack maxWidth={240}>
+      <ControlGroup orientation="vertical">
+        <Button>Top</Button>
+        <Button>Middle</Button>
+        <Button>Bottom</Button>
+      </ControlGroup>
+    </YStack>
+  ),
+};
+
+export const ChildCounts: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={420}>
+      <Paragraph size="$2">empty</Paragraph>
+      <ControlGroup>{null}</ControlGroup>
+      <Paragraph size="$2">one child</Paragraph>
+      <ControlGroup>
+        <Button>Only</Button>
+      </ControlGroup>
+      <Paragraph size="$2">two children</Paragraph>
+      <ControlGroup>
+        <Button>One</Button>
+        <Button>Two</Button>
+      </ControlGroup>
+      <Paragraph size="$2">five children</Paragraph>
+      <ControlGroup>
+        <Button>A</Button>
+        <Button>B</Button>
+        <Button>C</Button>
+        <Button>D</Button>
+        <Button>E</Button>
+      </ControlGroup>
+    </YStack>
+  ),
+};
+
+export const MixedControls: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={480}>
+      <ControlGroup>
+        <Button>Action</Button>
+        <TamaguiInput placeholder="type here" flex={1} />
+        <Button>Go</Button>
+      </ControlGroup>
+      <ControlGroup>
+        <Button>Enabled</Button>
+        <Button disabled>Disabled middle</Button>
+        <Button>Enabled</Button>
+      </ControlGroup>
+      <ControlGroup>
+        <Button>Short</Button>
+        <Button>A much much much longer label that may overflow</Button>
+        <Button>End</Button>
+      </ControlGroup>
+    </YStack>
+  ),
+};
+
+export const RTL: Story = {
+  render: () => (
+    <div dir="rtl">
+      <YStack maxWidth={420}>
+        <ControlGroup>
+          <Button>الأول</Button>
+          <Button>الأوسط</Button>
+          <Button>الأخير</Button>
+        </ControlGroup>
+      </YStack>
+    </div>
+  ),
+};

package/src/ControlGroup/index.tsx

@@ -2,7 +2,7 @@ import { Children, isValidElement, useMemo, useState, type ReactNode } from "rea
 import { View, isWeb, styled } from "tamagui";
 import type { GetProps } from "tamagui";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
-import { FocusContext, InputContext } from "../InputParts";
+import { FocusContext, getInputFrameTransitionProps, InputContext } from "../InputParts";
 import { formInputColors } from "../shared/colorRamps";
 import { getElevationWrapperProps } from "../shared/utils";
 import { ControlGroupCtx } from "../shared/groupContext";
@@ -76,7 +76,14 @@ export function ControlGroup({
           >
             {Children.map(children, (child) => {
               if (!isValidElement(child)) return child;
-              return <View flex={1}>{child}</View>;
+              // minWidth 0: flex items floor at min-content (the raw web
+              // <input>'s intrinsic width) — in a cell the wrapper must
+              // shrink to the cell width instead (LC-06/LC-10, UX-P12).
+              return (
+                <View flex={1} minWidth={0}>
+                  {child}
+                </View>
+              );
             })}
           </ControlGroupFrame>
         </FocusContext.Provider>
@@ -94,7 +101,9 @@ export function ControlGroup({
           backgroundColor={knobProps.outlined ? "transparent" : formInputColors.background.base}
           {...knobProps.borderRadius}
           {...elevationWrapperProps}
-          {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
+          {...getInputFrameTransitionProps(
+            typeof knobProps.transition === "string" ? knobProps.transition : undefined,
+          )}
           {...(control.hoverKnobProps ? { hoverStyle: control.hoverKnobProps } : undefined)}
           {...(control.pressKnobProps ? { pressStyle: control.pressKnobProps } : undefined)}
           {...(control.focusKnobProps
@@ -143,19 +152,28 @@ export function ControlGroup({
             const isFirst = index === 0;
             const isLast = index === count - 1;
             const isMiddle = count > 2 && !isFirst && !isLast;
-            const needsFlex = isMiddle || count === 2;
+            // Native: a lone child (Stepper showButtons={false} renders just
+            // the input) must fill the frame — RN TextInput has no intrinsic
+            // width, so a content-sized wrapper measures 0pt wide and iOS
+            // culls the zero-rect subtree from the a11y tree. Web keeps the
+            // content-sized wrapper (CSS inputs have intrinsic width; the
+            // added minWidth:0 could let the frame collapse there instead).
+            const needsFlex = isMiddle || count === 2 || (!isWeb && count === 1);
             const isVertical = orientation === "vertical";
+            // Logical (start/end) corners so RTL flips the rounding with the
+            // children — physical corners would land rounded edges on
+            // interior seams.
             const wrapperProps =
               isFirst && isLast
                 ? { borderRadius: radius }
                 : isFirst
                   ? isVertical
-                    ? { borderTopLeftRadius: radius, borderTopRightRadius: radius }
-                    : { borderTopLeftRadius: radius, borderBottomLeftRadius: radius }
+                    ? { borderStartStartRadius: radius, borderStartEndRadius: radius }
+                    : { borderStartStartRadius: radius, borderEndStartRadius: radius }
                   : isLast
                     ? isVertical
-                      ? { borderBottomLeftRadius: radius, borderBottomRightRadius: radius }
-                      : { borderTopRightRadius: radius, borderBottomRightRadius: radius }
+                      ? { borderEndStartRadius: radius, borderEndEndRadius: radius }
+                      : { borderStartEndRadius: radius, borderEndEndRadius: radius }
                     : {};
             const flexProps = needsFlex
               ? { flex: 1, ...(isVertical ? { minHeight: 0 } : { minWidth: 0 }) }

package/src/ErrorSummary.spec.tsx

@@ -0,0 +1,205 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { act, fireEvent, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Button } from "./Button";
+import {
+  ErrorSummary,
+  collectFormFieldErrors,
+  formatFieldError,
+  normalizeFieldError,
+  warnBannedErrorWords,
+} from "./ErrorSummary";
+import { Input } from "./fields/Input";
+import { Form } from "./Form";
+import { __resetDevWarnSeen } from "./shared/devWarn";
+
+vi.mock("@multiplatform.one/router", () => ({
+  useUrlState: vi.fn(() => [{}, vi.fn()]),
+}));
+
+describe("formatFieldError / normalizeFieldError", () => {
+  it("formats string errors", () => {
+    expect(formatFieldError("Enter a full name")).toBe("Enter a full name");
+  });
+
+  it("formats structured { problem, action }", () => {
+    expect(
+      formatFieldError({
+        problem: "Email is incomplete.",
+        action: "Include an @ and a domain.",
+      }),
+    ).toBe("Email is incomplete. Include an @ and a domain.");
+  });
+
+  it("normalizes objects and rejects empty", () => {
+    expect(normalizeFieldError({ problem: "Missing date" })).toEqual({
+      problem: "Missing date",
+    });
+    expect(normalizeFieldError("")).toBeUndefined();
+    expect(normalizeFieldError(null)).toBeUndefined();
+  });
+});
+
+describe("collectFormFieldErrors", () => {
+  it("collects first error per field and skips empty", () => {
+    const items = collectFormFieldErrors({
+      email: { errors: ["Enter an email address"] },
+      name: { errors: [] },
+      phone: { errors: [{ problem: "Phone is too short.", action: "Use 10 digits." }] },
+    });
+    expect(items).toHaveLength(2);
+    expect(items[0]).toMatchObject({ name: "email", id: "email" });
+    expect(items[1].name).toBe("phone");
+    expect(formatFieldError(items[1].error)).toContain("10 digits");
+  });
+});
+
+describe("warnBannedErrorWords", () => {
+  beforeEach(() => {
+    __resetDevWarnSeen();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    __resetDevWarnSeen();
+  });
+
+  it("warns in development for banned wording", () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnBannedErrorWords("Invalid email, please try again", "email");
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining("banned-error-word"));
+    process.env.NODE_ENV = prev;
+  });
+
+  it("is silent for clean copy", () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnBannedErrorWords("Enter an email address", "email");
+    expect(console.warn).not.toHaveBeenCalled();
+    process.env.NODE_ENV = prev;
+  });
+});
+
+describe("ErrorSummary", () => {
+  it("renders role=alert with title and linked errors", () => {
+    const result = renderWithProviders(
+      <ErrorSummary
+        errors={[
+          { name: "name", id: "name", error: "Enter a full name" },
+          {
+            name: "email",
+            id: "email",
+            error: { problem: "Email is incomplete.", action: "Include an @." },
+          },
+        ]}
+      />,
+    );
+
+    const summary = result.container.querySelector('[data-testid="error-summary"]');
+    expect(summary?.getAttribute("role")).toBe("alert");
+    expect(summary?.textContent).toContain("There is a problem");
+    expect(summary?.textContent).toContain("Enter a full name");
+    expect(summary?.textContent).toContain("Email is incomplete.");
+
+    const links = result.container.querySelectorAll("a[href='#name'], a[href='#email']");
+    expect(links.length).toBe(2);
+  });
+
+  it("focuses the summary on appear", async () => {
+    const focusSpy = vi.spyOn(HTMLElement.prototype, "focus");
+    renderWithProviders(
+      <ErrorSummary errors={[{ name: "name", id: "name", error: "Enter a full name" }]} />,
+    );
+    await waitFor(() => {
+      expect(focusSpy).toHaveBeenCalled();
+    });
+    focusSpy.mockRestore();
+  });
+
+  it("invokes onFocusField when a link is activated", () => {
+    const onFocusField = vi.fn();
+    const result = renderWithProviders(
+      <form>
+        <ErrorSummary
+          errors={[{ name: "name", id: "name", error: "Enter a full name" }]}
+          onFocusField={onFocusField}
+          disableAutoFocus
+        />
+        <input id="name" />
+      </form>,
+    );
+    const link = result.container.querySelector("a[href='#name']");
+    expect(link).toBeTruthy();
+    fireEvent.click(link!);
+    expect(onFocusField).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "name", id: "name" }),
+    );
+  });
+});
+
+describe("Form + ErrorSummary integration", () => {
+  it("shows ErrorSummary after failed submit and hides when showErrorSummary=false", async () => {
+    const onSubmit = vi.fn();
+    const result = renderWithProviders(
+      <Form
+        formOptions={{
+          defaultValues: { username: "", email: "" },
+        }}
+        onSubmit={onSubmit}
+      >
+        <Input id="username" name="username" label="Username" required />
+        <Input id="email" name="email" label="Email" required />
+        <Button action="submit" testID="submit-button">
+          Submit
+        </Button>
+      </Form>,
+    );
+
+    expect(result.container.querySelector('[data-testid="error-summary"]')).toBeNull();
+
+    const button = result.container.querySelector('[data-testid="submit-button"]');
+    await act(async () => {
+      if (button) fireEvent.click(button);
+    });
+
+    await waitFor(() => {
+      const summary = result.container.querySelector('[data-testid="error-summary"]');
+      expect(summary).toBeTruthy();
+      expect(summary?.getAttribute("role")).toBe("alert");
+      expect(summary?.textContent).toMatch(/required/i);
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("does not render ErrorSummary when showErrorSummary is false", async () => {
+    const result = renderWithProviders(
+      <Form
+        showErrorSummary={false}
+        formOptions={{ defaultValues: { username: "" } }}
+        onSubmit={vi.fn()}
+      >
+        <Input id="username" name="username" label="Username" required />
+        <Button action="submit" testID="submit-button">
+          Submit
+        </Button>
+      </Form>,
+    );
+
+    const button = result.container.querySelector('[data-testid="submit-button"]');
+    await act(async () => {
+      if (button) fireEvent.click(button);
+    });
+
+    await waitFor(() => {
+      // Inline field error still appears; summary does not.
+      expect(result.container.textContent).toMatch(/required/i);
+    });
+    expect(result.container.querySelector('[data-testid="error-summary"]')).toBeNull();
+  });
+});

package/src/ErrorSummary.tsx

@@ -0,0 +1,205 @@
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { WarningCircleIcon } from "@phosphor-icons/react";
+import { type ReactNode, useEffect, useId, useRef } from "react";
+import { Anchor, H4, Paragraph, YStack, isWeb } from "tamagui";
+import { formCommonColors } from "./shared/colorRamps";
+import { t } from "./shared/t";
+import { warnBannedErrorWords as warnBannedErrorWordsShared } from "./shared/devWarn";
+import { focusFieldTarget } from "./hooks/useFocusManagement";
+
+/** Structured field error (DG-VAL-04). */
+export type StructuredFieldError = {
+  problem: string;
+  action?: string;
+  cta?: { label: string; href?: string };
+};
+
+/** Validators may return a plain string or a structured `{ problem, action }`. */
+export type FieldErrorMessage = string | StructuredFieldError;
+
+export interface ErrorSummaryItem {
+  /** TanStack field name (used as React key and default focus target). */
+  name: string;
+  /** DOM id of the control to focus; defaults to `name`. Prefer `id={name}` on fields. */
+  id?: string;
+  /** Error payload — string or `{ problem, action?, cta? }`. */
+  error: FieldErrorMessage;
+  /** Optional human label; defaults to formatted error text for the link. */
+  label?: string;
+}
+
+export interface ErrorSummaryProps {
+  errors: ErrorSummaryItem[];
+  /** Heading text (GOV.UK default). */
+  title?: string;
+  /** Skip moving focus to the summary when it appears. */
+  disableAutoFocus?: boolean;
+  /** Root form element used to resolve focus targets. */
+  formElement?: HTMLElement | null;
+  /** Called after a summary link focuses a field. */
+  onFocusField?: (item: ErrorSummaryItem) => void;
+  children?: ReactNode;
+}
+
+/** Flatten structured / string errors into display copy. */
+export function formatFieldError(error: FieldErrorMessage): string {
+  if (typeof error === "string") return error;
+  const problem = error.problem?.trim() ?? "";
+  const action = error.action?.trim();
+  if (problem && action) return `${problem} ${action}`;
+  return problem || action || "";
+}
+
+/** Normalize unknown validator return values into FieldErrorMessage. */
+export function normalizeFieldError(raw: unknown): FieldErrorMessage | undefined {
+  if (raw == null || raw === false || raw === "") return undefined;
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "object" && raw !== null && "problem" in raw) {
+    const problem = String((raw as StructuredFieldError).problem ?? "").trim();
+    if (!problem) return undefined;
+    return raw as StructuredFieldError;
+  }
+  return String(raw);
+}
+
+/**
+ * DEV-only banned-word guard (DG-COPY-02 / blueprint §5 `banned-error-word`).
+ * Tree-shaken when `NODE_ENV === "production"`.
+ */
+export function warnBannedErrorWords(message: string, fieldName?: string): void {
+  warnBannedErrorWordsShared(message, {
+    component: "ErrorSummary",
+    fieldName,
+    id: fieldName,
+  });
+}
+
+type FieldMetaLike = { errors?: unknown[] } | undefined;
+
+/** Collect field errors from TanStack `state.fieldMeta` for ErrorSummary. */
+export function collectFormFieldErrors(
+  fieldMeta: Partial<Record<string, FieldMetaLike>> | null | undefined,
+): ErrorSummaryItem[] {
+  if (!fieldMeta) return [];
+  const items: ErrorSummaryItem[] = [];
+  for (const [name, meta] of Object.entries(fieldMeta)) {
+    const error = normalizeFieldError(meta?.errors?.[0]);
+    if (!error) continue;
+    const message = formatFieldError(error);
+    if (!message) continue;
+    warnBannedErrorWords(message, name);
+    items.push({ name, id: name, error });
+  }
+  return items;
+}
+
+/**
+ * Form-level error summary (DG-VAL-02). Lists field errors with focusable
+ * links, `role="alert"`, and moves keyboard focus onto itself when it appears.
+ */
+export function ErrorSummary({
+  errors,
+  title = t("There is a problem"),
+  disableAutoFocus = false,
+  formElement,
+  onFocusField,
+}: ErrorSummaryProps) {
+  const { knobProps } = useResolvedKnobs({ component: "ErrorSummary" });
+  const headingId = useId();
+  const containerRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (disableAutoFocus || !isWeb || errors.length === 0) return;
+    const node = containerRef.current;
+    if (!node || typeof node.focus !== "function") return;
+    // Defer so the alert is in the accessibility tree before focus moves.
+    const timer = setTimeout(() => {
+      node.focus();
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [disableAutoFocus, errors.length]);
+
+  if (errors.length === 0) return null;
+
+  const focusItem = (item: ErrorSummaryItem) => {
+    if (!isWeb) {
+      onFocusField?.(item);
+      return;
+    }
+    const root =
+      formElement ??
+      (containerRef.current?.closest?.("form") as HTMLElement | null) ??
+      (typeof document !== "undefined" ? document.body : null);
+    focusFieldTarget(root, { id: item.id ?? item.name, name: item.name });
+    onFocusField?.(item);
+  };
+
+  return (
+    <YStack
+      ref={containerRef as any}
+      role="alert"
+      aria-labelledby={headingId}
+      tabIndex={-1}
+      theme="error"
+      backgroundColor="$color3"
+      width="100%"
+      gap="$2"
+      marginBottom="$3"
+      padding={knobProps.panelPadding?.padding ?? "$3"}
+      {...knobProps.borderRadius}
+      outlineWidth={0}
+      focusVisibleStyle={{
+        outlineWidth: 2,
+        outlineStyle: "solid",
+        outlineColor: "$color8",
+        outlineOffset: 2,
+      }}
+      data-testid="error-summary"
+    >
+      <YStack flexDirection="row" alignItems="center" gap="$2">
+        <WarningCircleIcon size={20} aria-hidden />
+        <H4 id={headingId} size="$4" color="$color12" fontWeight="700" margin={0}>
+          {title}
+        </H4>
+      </YStack>
+      <YStack {...({ tag: "ul" } as any)} gap="$1" paddingInlineStart="$1" margin={0}>
+        {errors.map((item) => {
+          const message = item.label ?? formatFieldError(item.error);
+          const targetId = item.id ?? item.name;
+          return (
+            <YStack key={item.name} {...({ tag: "li" } as any)}>
+              <Paragraph
+                size="$3"
+                color="$color12"
+                {...(knobProps.body as Record<string, unknown>)}
+              >
+                {isWeb ? (
+                  <Anchor
+                    href={`#${targetId}`}
+                    color={formCommonColors.error}
+                    textDecorationLine="underline"
+                    cursor="pointer"
+                    onPress={(e: any) => {
+                      e?.preventDefault?.();
+                      focusItem(item);
+                    }}
+                  >
+                    {message}
+                  </Anchor>
+                ) : (
+                  <Paragraph
+                    color={formCommonColors.error}
+                    textDecorationLine="underline"
+                    onPress={() => focusItem(item)}
+                  >
+                    {message}
+                  </Paragraph>
+                )}
+              </Paragraph>
+            </YStack>
+          );
+        })}
+      </YStack>
+    </YStack>
+  );
+}