@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/Skeleton/index.tsx

@@ -38,22 +38,32 @@ const SkeletonFrame = styled(View, {
         borderRadius: "$3",
       },
     },
-    animate: {
-      true: isWeb
-        ? {
-            animation: "skeleton-pulse 1.5s ease-in-out infinite" as any,
-          }
-        : {},
-      false: {},
-    },
   } as const,
 
   defaultVariants: {
     variant: "text",
-    animate: true,
   },
 });
 
+// Size-knob geometry (spec: Skeleton block/text/circle scale with
+// `sizeToken`); medium keeps the previous 16px line and 40px circle.
+const skeletonTextHeightMap: Record<string, number> = { $3: 14, $4: 16, $5: 20 };
+const skeletonCircleSizeMap: Record<string, number> = { $3: 32, $4: 40, $5: 48 };
+// SP-GAP: text-line gap follows the space knob; medium keeps $2.
+const skeletonGapMap: Record<string, string> = { small: "$1", medium: "$2", large: "$3" };
+
+// Self-contained pulse keyframes: the app root layout injects the same rule,
+// but Skeleton must not depend on a particular host (Storybook, tests, docs).
+const PULSE_STYLE_ID = "__mp-skeleton-pulse";
+function ensurePulseKeyframes() {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(PULSE_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = PULSE_STYLE_ID;
+  style.textContent = "@keyframes skeleton-pulse{0%{opacity:1}50%{opacity:0.4}100%{opacity:1}}";
+  document.head.appendChild(style);
+}
+
 // ── Skeleton Component ────────────────────────────────────────
 
 export function Skeleton({
@@ -61,18 +71,44 @@ export function Skeleton({
   width,
   height,
   animate = true,
+  style,
   ...props
 }: SkeletonProps) {
   const { knobProps } = useResolvedKnobs();
+  // Pulse only when animating is on AND the animation knob is not "none"
+  // (knobProps.transition resolves to undefined at animation:none).
+  const pulsing = animate && knobProps.transition !== undefined;
+  if (pulsing) ensurePulseKeyframes();
+
+  // Merge pulse last into `style` so a consumer style prop cannot kill the
+  // animation (LC-20: animation:none stops the pulse via the knob; otherwise
+  // it must run).
+  const mergedStyle =
+    isWeb && pulsing
+      ? { ...(style as object), animation: "skeleton-pulse 1.5s ease-in-out infinite" }
+      : style;
 
   return (
     <SkeletonFrame
       variant={variant}
-      animate={animate}
       width={width}
-      height={height}
-      {...(variant === "rounded" ? knobProps.borderRadius : undefined)}
+      // Text lines follow the size knob; explicit height ejects.
+      height={
+        height ?? (variant === "text" ? skeletonTextHeightMap[knobProps.sizeToken] : undefined)
+      }
+      // Radius only — a skeleton is a flat blob, it never draws the knob's border.
+      // Consumers that clamp (Checkbox/Radio/Switch) pass an explicit borderRadius
+      // which wins via ...props below.
+      // Text lines are R-CLAMP (spec Skeleton): radius scales to the $2
+      // anatomy cap but honors the square world at `none` (Axiom 3 NULL) —
+      // a 5px arc at radius:none was the UX-P06 residual.
+      {...(variant === "rounded"
+        ? { borderRadius: knobProps.borderRadius.borderRadius }
+        : variant === "text" && knobProps.pointy
+          ? { borderRadius: 0 }
+          : undefined)}
       {...props}
+      {...(mergedStyle ? { style: mergedStyle } : undefined)}
     />
   );
 }
@@ -81,7 +117,7 @@ export function Skeleton({
 
 export function SkeletonText({
   lines = 1,
-  gap = "$2",
+  gap: gapProp,
   lastLineWidth = "70%",
   ...props
 }: SkeletonProps & {
@@ -89,6 +125,8 @@ export function SkeletonText({
   gap?: string | number;
   lastLineWidth?: string | number;
 }) {
+  const { knobProps } = useResolvedKnobs();
+  const gap = gapProp ?? skeletonGapMap[knobProps.space] ?? "$2";
   if (lines === 1) {
     return <Skeleton variant="text" width={lastLineWidth} {...props} />;
   }
@@ -109,7 +147,9 @@ export function SkeletonText({
 
 // ── Skeleton.Circle - for avatar placeholder ──────────────────
 
-export function SkeletonCircle({ size = 40, ...props }: SkeletonProps & { size?: number }) {
+export function SkeletonCircle({ size: sizeProp, ...props }: SkeletonProps & { size?: number }) {
+  const { knobProps } = useResolvedKnobs();
+  const size = sizeProp ?? skeletonCircleSizeMap[knobProps.sizeToken] ?? 40;
   return <Skeleton variant="circular" width={size} height={size} {...props} />;
 }
 

package/src/Spinner/Spinner.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { XStack, YStack, Paragraph } from "tamagui";
+import { Button } from "../Button";
+import { Spinner } from "./index";
+
+const meta: Meta<typeof Spinner> = {
+  title: "Forms/Spinner",
+  component: Spinner,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    size: { control: "select", options: ["small", "large"] },
+    color: { control: "color" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Spinner>;
+
+export const Basic: Story = {
+  render: (args) => <Spinner {...args} />,
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <XStack gap="$6" alignItems="center">
+      <YStack gap="$2" alignItems="center">
+        <Spinner size="small" />
+        <Paragraph size="$2">small</Paragraph>
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Spinner size="large" />
+        <Paragraph size="$2">large</Paragraph>
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Spinner size="small" color="#e5484d" />
+        <Paragraph size="$2">custom color</Paragraph>
+      </YStack>
+    </XStack>
+  ),
+};
+
+export const MountUnmount: Story = {
+  render: () => {
+    const Example = () => {
+      const [mounted, setMounted] = useState(true);
+      return (
+        <YStack gap="$4" alignItems="flex-start">
+          <Button onPress={() => setMounted((m) => !m)}>
+            {mounted ? "Unmount spinner" : "Mount spinner"}
+          </Button>
+          <XStack height={48} alignItems="center">
+            {mounted ? <Spinner size="large" /> : <Paragraph size="$2">unmounted</Paragraph>}
+          </XStack>
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};

package/src/Spinner/index.tsx

@@ -1,5 +1,9 @@
-import { Spinner as TamaguiSpinner } from "tamagui";
+import { useEffect, useRef } from "react";
+import { Spinner as TamaguiSpinner, isWeb } from "tamagui";
+import type { TamaguiElement } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { formCommonColors } from "../shared/colorRamps";
+import { t } from "../shared/t";
 
 export interface SpinnerProps {
   size?: "small" | "large";
@@ -7,11 +11,53 @@ export interface SpinnerProps {
   [key: string]: unknown;
 }
 
+// The spin keyframe lives inside react-native-web's ActivityIndicator, so the
+// animation:none knob and prefers-reduced-motion need a CSS override injected
+// once at module scope (web only).
+const MOTION_STYLE_ID = "mp1-spinner-motion";
+function ensureMotionStyles() {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(MOTION_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = MOTION_STYLE_ID;
+  style.textContent = [
+    ".mp1-spinner-static, .mp1-spinner-static * { animation: none !important; }",
+    "@media (prefers-reduced-motion: reduce) { .mp1-spinner, .mp1-spinner * { animation: none !important; } }",
+  ].join("\n");
+  document.head.appendChild(style);
+}
+
 /** Form-styled Spinner with theme colors. Override size as needed. */
-export function Spinner({
-  size = "small",
-  color = formCommonColors.muted,
-  ...props
-}: SpinnerProps) {
-  return <TamaguiSpinner size={size} color={color} {...props} />;
+export function Spinner({ size, color = formCommonColors.muted, ...props }: SpinnerProps) {
+  const { knobProps } = useResolvedKnobs();
+  // ActivityIndicator only has two sizes; the size knob's top step maps to
+  // "large" so the spinner follows the one pipeline (LC-18).
+  const resolvedSize = size ?? (knobProps.sizeToken === "$5" ? "large" : "small");
+  // transition is undefined exactly when the animation knob is "none"
+  const animationsOff = !knobProps.transition;
+  ensureMotionStyles();
+  const ref = useRef<TamaguiElement>(null);
+  // react-native-web's ActivityIndicator renders an inner unnamed
+  // role="progressbar" node that Tamagui props cannot reach; the accessible
+  // name lives on this wrapper (role="status"), so hide the inner node from
+  // the a11y tree (axe aria-progressbar-name).
+  useEffect(() => {
+    if (!isWeb) return;
+    const host = ref.current as unknown as HTMLElement | null;
+    host?.querySelector?.("[role=progressbar]")?.setAttribute("aria-hidden", "true");
+  });
+  return (
+    <TamaguiSpinner
+      ref={ref}
+      size={resolvedSize}
+      color={color}
+      role="status"
+      aria-label={t("Loading")}
+      aria-live="polite"
+      {...(isWeb
+        ? { className: animationsOff ? "mp1-spinner mp1-spinner-static" : "mp1-spinner" }
+        : undefined)}
+      {...props}
+    />
+  );
 }

package/src/Wheel/index.tsx

@@ -159,7 +159,11 @@ function getItemTransform(
   containerHeight: number,
 ): { translateY: number; rotateX: number; scale: number; opacity: number } {
   const centerY = containerHeight / 2;
-  const itemCenterY = index * itemHeight + itemHeight / 2 - scrollOffset;
+  // Rows are laid out so the row at `scrollOffset / itemHeight` sits under the
+  // selection indicator (which is centered at `containerHeight / 2`), hence the
+  // `(containerHeight - itemHeight) / 2` padding shift.
+  const itemCenterY =
+    index * itemHeight + itemHeight / 2 - scrollOffset + (containerHeight - itemHeight) / 2;
   const distanceFromCenter = itemCenterY - centerY;
   const normalizedDistance = distanceFromCenter / (containerHeight / 2);
 
@@ -170,8 +174,9 @@ function getItemTransform(
   // Scale: items get smaller as they rotate away
   const scale = 1 - Math.abs(normalizedDistance) * 0.3;
 
-  // Opacity: items fade as they move away from center
-  const opacity = 1 - Math.abs(normalizedDistance) * 0.6;
+  // Opacity: items fade as they move away from center (kept gentle enough that
+  // the rows adjacent to the selection stay readable, ~3:1 contrast)
+  const opacity = 1 - Math.abs(normalizedDistance) * 0.35;
 
   // Y position adjusted for 3D perspective effect
   // Items appear to curve back
@@ -182,7 +187,7 @@ function getItemTransform(
     translateY,
     rotateX: Math.max(-85, Math.min(85, rotateX)),
     scale: Math.max(0.5, Math.min(1, scale)),
-    opacity: Math.max(0.1, Math.min(1, opacity)),
+    opacity: Math.max(0.2, Math.min(1, opacity)),
   };
 }
 
@@ -666,6 +671,7 @@ export function Wheel<T = string | number>({
                 data-testid="wheel-item"
                 data-index={dataIndex}
                 data-selected={isSelected}
+                aria-hidden={isSelected ? undefined : true}
                 style={{
                   position: "absolute",
                   left: 0,
@@ -689,7 +695,7 @@ export function Wheel<T = string | number>({
                     {...knobProps.body}
                     fontSize={size}
                     fontWeight={isSelected ? "600" : "400"}
-                    color={isSelected ? "$color12" : "$color10"}
+                    color={isSelected ? "$color12" : "$color11"}
                   >
                     {getItemLabel(item)}
                   </Text>
@@ -745,7 +751,7 @@ export function Wheel<T = string | number>({
                     {...knobProps.body}
                     fontSize={size}
                     fontWeight={isSelected ? "600" : "400"}
-                    color={isSelected ? "$color12" : "$color10"}
+                    color={isSelected ? "$color12" : "$color11"}
                   >
                     {getItemLabel(item)}
                   </Text>

package/src/actionLabel.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { formatActionLabel } from "./actionLabel";
+
+describe("formatActionLabel (DG-ACT-02)", () => {
+  it("formats verb alone in sentence case", () => {
+    expect(formatActionLabel({ verb: "delete" })).toBe("Delete");
+    expect(formatActionLabel({ verb: "Save" })).toBe("Save");
+  });
+
+  it("appends noun without articles", () => {
+    expect(formatActionLabel({ verb: "Delete", noun: "pipeline" })).toBe("Delete pipeline");
+    expect(formatActionLabel({ verb: "Archive", noun: "the invoice" })).toBe("Archive invoice");
+    expect(formatActionLabel({ verb: "Remove", noun: "an attachment" })).toBe("Remove attachment");
+  });
+
+  it("ignores empty / whitespace noun", () => {
+    expect(formatActionLabel({ verb: "Cancel", noun: "  " })).toBe("Cancel");
+    expect(formatActionLabel({ verb: "Cancel" })).toBe("Cancel");
+  });
+
+  it("collapses internal whitespace", () => {
+    expect(formatActionLabel({ verb: "  Soft   delete  ", noun: " draft  row " })).toBe(
+      "Soft delete draft row",
+    );
+  });
+});

package/src/actionLabel.ts

@@ -0,0 +1,47 @@
+/**
+ * DG-ACT-02 / DG-COPY-03 — action labels are verb (+ optional noun), sentence case, no articles.
+ */
+
+const LEADING_ARTICLE = /^(the|a|an)\s+/i;
+
+export type ActionLabelParts = {
+  verb: string;
+  noun?: string;
+};
+
+function sentenceCaseWord(word: string): string {
+  if (!word) return word;
+  return word.charAt(0).toLowerCase() + word.slice(1);
+}
+
+function normalizePart(raw: string): string {
+  const trimmed = raw.trim().replace(/\s+/g, " ");
+  if (!trimmed) return "";
+  // Drop a leading article if a caller still passed one.
+  const withoutArticle = trimmed.replace(LEADING_ARTICLE, "");
+  const words = withoutArticle.split(" ").filter(Boolean);
+  if (words.length === 0) return "";
+  // Sentence case: first word keeps its casing intent from the verb (often Title for
+  // single-word UI verbs like "Delete"); subsequent words lowercased unless ALL CAPS
+  // / already mixed. We only force the first character of the whole label uppercase.
+  const joined = words.map((w, i) => (i === 0 ? w : sentenceCaseWord(w))).join(" ");
+  return joined.charAt(0).toUpperCase() + joined.slice(1);
+}
+
+/**
+ * Build a chrome action label from structured `{ verb, noun? }`.
+ *
+ * @example formatActionLabel({ verb: "Delete" }) // "Delete"
+ * @example formatActionLabel({ verb: "delete", noun: "pipeline" }) // "Delete pipeline"
+ * @example formatActionLabel({ verb: "Archive", noun: "the invoice" }) // "Archive invoice"
+ */
+export function formatActionLabel({ verb, noun }: ActionLabelParts): string {
+  const v = normalizePart(verb);
+  if (!v) return "";
+  if (noun == null || String(noun).trim() === "") return v;
+  const n = normalizePart(String(noun));
+  if (!n) return v;
+  // Noun stays sentence-case continuation (first char lower unless proper-looking).
+  const nounTail = n.charAt(0).toLowerCase() + n.slice(1);
+  return `${v} ${nounTail}`;
+}

package/src/fieldDefaults.spec.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import {
+  FIELD_WIDTH_BY_PURPOSE,
+  fieldWidthStyle,
+  isFieldPurpose,
+  resolveFieldInputProps,
+  resolveFieldPurpose,
+  resolveFieldWidth,
+} from "./fieldDefaults";
+
+describe("FIELD_WIDTH_BY_PURPOSE", () => {
+  it("maps blueprint purposes to ch widths / full", () => {
+    expect(FIELD_WIDTH_BY_PURPOSE).toEqual({
+      postalCode: 12,
+      year: 4,
+      phone: 16,
+      email: 24,
+      description: "full",
+    });
+  });
+});
+
+describe("resolveFieldPurpose", () => {
+  it("prefers explicit purpose over autocomplete", () => {
+    expect(resolveFieldPurpose("year", "email")).toBe("year");
+  });
+
+  it("maps HTML autocomplete tokens", () => {
+    expect(resolveFieldPurpose(undefined, "postal-code")).toBe("postalCode");
+    expect(resolveFieldPurpose(undefined, "tel")).toBe("phone");
+    expect(resolveFieldPurpose(undefined, "tel-national")).toBe("phone");
+    expect(resolveFieldPurpose(undefined, "email")).toBe("email");
+    expect(resolveFieldPurpose(undefined, "bday-year")).toBe("year");
+  });
+
+  it("accepts purpose keys case-sensitively via purpose prop", () => {
+    expect(resolveFieldPurpose("postalCode")).toBe("postalCode");
+    expect(resolveFieldPurpose("PostalCode")).toBeUndefined();
+  });
+
+  it("returns undefined for unknown tokens", () => {
+    expect(resolveFieldPurpose(undefined, "given-name")).toBeUndefined();
+    expect(resolveFieldPurpose(undefined, "")).toBeUndefined();
+    expect(resolveFieldPurpose(undefined, null)).toBeUndefined();
+  });
+});
+
+describe("resolveFieldWidth / fieldWidthStyle", () => {
+  it("returns numeric ch widths", () => {
+    expect(resolveFieldWidth("postalCode")).toBe(12);
+    expect(fieldWidthStyle("postalCode")).toEqual({ maxWidth: "12ch" });
+    expect(fieldWidthStyle(undefined, "email")).toEqual({ maxWidth: "24ch" });
+    expect(fieldWidthStyle(undefined, "tel")).toEqual({ maxWidth: "16ch" });
+    expect(fieldWidthStyle("year")).toEqual({ maxWidth: "4ch" });
+  });
+
+  it("returns full-width style for description", () => {
+    expect(resolveFieldWidth("description")).toBe("full");
+    expect(fieldWidthStyle("description")).toEqual({
+      width: "100%",
+      maxWidth: "100%",
+    });
+  });
+
+  it("returns undefined when purpose cannot be resolved", () => {
+    expect(resolveFieldWidth()).toBeUndefined();
+    expect(fieldWidthStyle(undefined, "on")).toBeUndefined();
+  });
+});
+
+describe("isFieldPurpose", () => {
+  it("narrows known keys", () => {
+    expect(isFieldPurpose("phone")).toBe(true);
+    expect(isFieldPurpose("nope")).toBe(false);
+    expect(isFieldPurpose(undefined)).toBe(false);
+  });
+});
+
+describe("resolveFieldInputProps (DG §32 keyboard/autofill)", () => {
+  it("email → email autocomplete + email keyboard", () => {
+    expect(resolveFieldInputProps("email")).toEqual({
+      autoComplete: "email",
+      inputMode: "email",
+      keyboardType: "email-address",
+    });
+  });
+
+  it("phone → tel autocomplete + tel keyboard", () => {
+    expect(resolveFieldInputProps("phone")).toEqual({
+      autoComplete: "tel",
+      inputMode: "tel",
+      keyboardType: "phone-pad",
+    });
+  });
+
+  it("postalCode → postal-code autocomplete, keyboard stays text (alphanumeric)", () => {
+    const props = resolveFieldInputProps("postalCode");
+    expect(props.autoComplete).toBe("postal-code");
+    expect(props.inputMode).toBeUndefined();
+    expect(props.keyboardType).toBeUndefined();
+  });
+
+  it("year → numeric via text + inputmode (no autocomplete guess)", () => {
+    expect(resolveFieldInputProps("year")).toEqual({
+      inputMode: "numeric",
+      keyboardType: "number-pad",
+    });
+  });
+
+  it("derives purpose from an autocomplete token and passes the token through", () => {
+    expect(resolveFieldInputProps(undefined, "tel-national")).toEqual({
+      autoComplete: "tel-national",
+      inputMode: "tel",
+      keyboardType: "phone-pad",
+    });
+  });
+
+  it("explicit autoComplete wins over the purpose-derived token", () => {
+    expect(resolveFieldInputProps("email", "work email")).toMatchObject({
+      autoComplete: "work email",
+      inputMode: "email",
+    });
+  });
+
+  it("unknown purposes yield no keyboard/autofill props", () => {
+    expect(resolveFieldInputProps("description")).toEqual({});
+    expect(resolveFieldInputProps()).toEqual({});
+    expect(resolveFieldInputProps(undefined, "given-name")).toEqual({
+      autoComplete: "given-name",
+    });
+  });
+});

package/src/fieldDefaults.ts

@@ -0,0 +1,138 @@
+/**
+ * Field anatomy defaults (DG-FORM-07 / W1).
+ *
+ * Character widths follow the GOV.UK / USWDS convention: short expected
+ * content → short control (`ch`), free-text description → full width.
+ */
+
+export type FieldPurpose = "postalCode" | "year" | "phone" | "email" | "description";
+
+export type FieldWidth = number | "full";
+
+/** Default max character widths keyed by semantic purpose. */
+export const FIELD_WIDTH_BY_PURPOSE: Record<FieldPurpose, FieldWidth> = {
+  postalCode: 12,
+  year: 4,
+  phone: 16,
+  email: 24,
+  description: "full",
+};
+
+/** HTML `autocomplete` tokens → purpose keys. */
+const AUTOCOMPLETE_TO_PURPOSE: Record<string, FieldPurpose> = {
+  "postal-code": "postalCode",
+  postalcode: "postalCode",
+  zip: "postalCode",
+  "zip-code": "postalCode",
+  year: "year",
+  "bday-year": "year",
+  "cc-exp-year": "year",
+  tel: "phone",
+  "tel-national": "phone",
+  "tel-local": "phone",
+  "tel-country-code": "phone",
+  phone: "phone",
+  email: "email",
+  description: "description",
+};
+
+const PURPOSE_KEYS = new Set<string>(Object.keys(FIELD_WIDTH_BY_PURPOSE));
+
+export function isFieldPurpose(value: string | undefined | null): value is FieldPurpose {
+  return typeof value === "string" && PURPOSE_KEYS.has(value);
+}
+
+/**
+ * Resolve a purpose key from an explicit `purpose` prop or an HTML
+ * `autoComplete` / `autocomplete` token.
+ */
+export function resolveFieldPurpose(
+  purpose?: string | null,
+  autoComplete?: string | null,
+): FieldPurpose | undefined {
+  if (isFieldPurpose(purpose ?? undefined)) return purpose as FieldPurpose;
+  if (!autoComplete) return undefined;
+  const normalized = autoComplete.trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (isFieldPurpose(normalized)) return normalized;
+  return AUTOCOMPLETE_TO_PURPOSE[normalized];
+}
+
+/** Character width (or `"full"`) for a purpose / autocomplete pair. */
+export function resolveFieldWidth(
+  purpose?: string | null,
+  autoComplete?: string | null,
+): FieldWidth | undefined {
+  const resolved = resolveFieldPurpose(purpose, autoComplete);
+  if (!resolved) return undefined;
+  return FIELD_WIDTH_BY_PURPOSE[resolved];
+}
+
+export type FieldWidthStyle = {
+  maxWidth?: string;
+  width?: string;
+};
+
+export interface FieldInputProps {
+  /** HTML autocomplete token (web) — also feeds RNW textContentType mapping. */
+  autoComplete?: string;
+  /** HTML inputmode (web keyboard hint). */
+  inputMode?: "text" | "email" | "tel" | "numeric" | "decimal" | "search" | "url";
+  /** React Native keyboardType (native keyboard hint). */
+  keyboardType?:
+    | "default"
+    | "email-address"
+    | "phone-pad"
+    | "number-pad"
+    | "decimal-pad"
+    | "numeric"
+    | "url";
+}
+
+/**
+ * Purpose → keyboard/autofill input props (DG research §32).
+ *
+ * - email → autocomplete `email`, inputmode `email`, keyboardType `email-address`
+ * - phone → autocomplete `tel`, inputmode `tel`, keyboardType `phone-pad`
+ * - postalCode → autocomplete `postal-code`; keyboard stays text (postal codes
+ *   are alphanumeric in UK/CA/NL — never force numeric)
+ * - year → numeric via text + inputmode `numeric` (no `type=number` spinner)
+ */
+const INPUT_PROPS_BY_PURPOSE: Record<FieldPurpose, FieldInputProps> = {
+  email: { autoComplete: "email", inputMode: "email", keyboardType: "email-address" },
+  phone: { autoComplete: "tel", inputMode: "tel", keyboardType: "phone-pad" },
+  postalCode: { autoComplete: "postal-code" },
+  year: { inputMode: "numeric", keyboardType: "number-pad" },
+  description: {},
+};
+
+/**
+ * Resolve keyboard/autofill props from `purpose` / `autoComplete`.
+ * An explicit `autoComplete` always passes through verbatim (eject); the
+ * purpose only fills the token when the consumer did not provide one.
+ */
+export function resolveFieldInputProps(
+  purpose?: string | null,
+  autoComplete?: string | null,
+): FieldInputProps {
+  const resolved = resolveFieldPurpose(purpose, autoComplete);
+  const base = resolved ? INPUT_PROPS_BY_PURPOSE[resolved] : {};
+  if (autoComplete) return { ...base, autoComplete };
+  return { ...base };
+}
+
+/**
+ * Style props for FieldLayout / Input Box. Numeric widths become `Nch`
+ * maxWidth; `"full"` stretches to 100%.
+ */
+export function fieldWidthStyle(
+  purpose?: string | null,
+  autoComplete?: string | null,
+): FieldWidthStyle | undefined {
+  const width = resolveFieldWidth(purpose, autoComplete);
+  if (width === undefined) return undefined;
+  if (width === "full") {
+    return { width: "100%", maxWidth: "100%" };
+  }
+  return { maxWidth: `${width}ch` };
+}