@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/PhoneInput/PhoneInput.spec.tsx

@@ -32,6 +32,22 @@ describe("PhoneInput", () => {
         expect(input.value).not.toContain("c");
       }
     });
+
+    it("forgiving paste normalization: strips dots/letters, keeps digits + separators", async () => {
+      const result = renderWithProviders(<PhoneInput label="Pasted Phone" name="pasted" />);
+      const input = result.container.querySelector("input") as HTMLInputElement;
+      // Simulate pasting a dotted-format number (change event carries the paste).
+      await act(async () => {
+        fireEvent.change(input, { target: { value: "+1 512.400.9021" } });
+      });
+      expect(input.value).toBe("+1 5124009021");
+
+      // Vanity letters are dropped; dashes/parens/spaces are preserved.
+      await act(async () => {
+        fireEvent.change(input, { target: { value: "(800) FLO-9021" } });
+      });
+      expect(input.value).toBe("(800) -9021");
+    });
   });
 
   describe("country selection", () => {

package/src/fields/PhoneInput/PhoneInput.stories.tsx

@@ -193,3 +193,8 @@ export const DifferentCountries: Story = {
     </YStack>
   ),
 };
+
+/** Loading placeholder — the skeleton mirrors the field's anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: () => <PhoneInput label="Phone Number" skeleton />,
+};

package/src/fields/PhoneInput/index.tsx

@@ -1,4 +1,5 @@
 import { GlobeIcon } from "@phosphor-icons/react";
+import { ensureFocusVisibleRing } from "@multiplatform.one/theme";
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
 import type { ComponentProps, FocusEventHandler, ReactNode } from "react";
 import { useEffect, useRef, useState } from "react";
@@ -14,13 +15,22 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 import type { FormFieldProps } from "../../fieldLayout";
-import { Input as InputParts } from "../../InputParts";
+import { FocusContext, Input as InputParts } from "../../InputParts";
+import { t } from "../../shared/t";
 import type { FieldComponentProps } from "../../types";
 import { Combobox, type ComboboxOption } from "../Combobox";
 import { dialCodes, regionCodes } from "./dialCodes";
 
 // ── Helpers ───────────────────────────────────────────────────
 
+/**
+ * The knob focus ring must be CSS-driven on the focused input itself
+ * (DG-A11Y-01): Input.Box paints its ring from React `focused` state one
+ * frame after focus, which synchronous a11y probes never see. Same
+ * OTP/Stepper/Input template — Box ring suppressed, ring lives on the Area.
+ */
+const suppressBoxFocusRing = { focused: false, setFocused: (_val: boolean) => {} };
+
 function countryCodeToFlag(countryCode: string): string {
   const codePoints = countryCode
     .toUpperCase()
@@ -49,7 +59,9 @@ export type PhoneInputProps<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = Omit<
   FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-  "children" | "field"
+  // "onChange": FormFieldProps carries the DOM ChangeEventHandler from
+  // YStackProps; this field exposes a canonical value callback instead.
+  "children" | "field" | "onChange"
 > &
   Partial<
     Omit<
@@ -62,6 +74,8 @@ export type PhoneInputProps<
     showFlags?: boolean;
     placeholder?: string;
     inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onChangeText" | "ref">;
+    /** Standalone (no form/name) change callback */
+    onChange?: (value: string) => void;
     /** When true, renders a skeleton placeholder instead of the phone input */
     skeleton?: boolean;
     /** When true, uses compact sizing */
@@ -87,6 +101,7 @@ interface PhoneInputFieldRendererProps<TData> {
   labelProps?: any;
   helperText?: string;
   required?: boolean;
+  disabled?: boolean;
   renderPhoneRow: (hasError?: boolean) => ReactNode;
 }
 
@@ -103,6 +118,7 @@ function PhoneInputFieldRenderer<TData>({
   labelProps,
   helperText,
   required,
+  disabled,
   renderPhoneRow,
 }: PhoneInputFieldRendererProps<TData>) {
   const lastSyncedRef = useRef<string>("");
@@ -145,6 +161,9 @@ function PhoneInputFieldRenderer<TData>({
       size={size as any}
       knobProps={knobProps as any}
       onBlur={mergeFieldHandler(field as SimpleFieldApi<any>, "handleBlur", onBlur)}
+      // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+      // the sibling label/helper readable) — it needs the disabled state.
+      disabled={disabled}
     >
       <InputParts size={size || knobProps.sizeToken}>{renderPhoneRow(!!resolvedError)}</InputParts>
     </FieldLayout>
@@ -166,7 +185,7 @@ export function PhoneInput<
     inputProps,
     defaultCountry = "US",
     showFlags = true,
-    placeholder = "Phone number",
+    placeholder = t("Phone number"),
     mode,
     name,
     preserveValue,
@@ -180,18 +199,28 @@ export function PhoneInput<
     required,
     size,
     onBlur,
+    onChange,
     skeleton,
     compact,
     id: idProp,
     ..._restProps
   } = useProps(props);
 
-  const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
+  const { resolvedForm, knobProps, control, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  // Inset (-2) keeps the ring inside the Box chrome (OTP/Stepper template).
+  const areaFocusRing = ensureFocusVisibleRing({
+    ...control.focusVisibleKnobProps,
+    outlineOffset: -2,
+  });
 
   const [regionCode, setRegionCode] = useState(defaultCountry);
-  const [phoneNumber, setPhoneNumber] = useState(() => dialPrefix(defaultCountry));
+  const [phoneNumber, setPhoneNumber] = useState(() => {
+    if (typeof defaultValue === "string" && defaultValue) return defaultValue;
+    return dialPrefix(defaultCountry);
+  });
   const regionCodeMountedRef = useRef(false);
+  const standaloneSyncedRef = useRef(phoneNumber);
 
   // Filter phone input to only allow valid phone number characters
   const handlePhoneChange = (text: string) => {
@@ -200,6 +229,17 @@ export function PhoneInput<
     setPhoneNumber(filtered);
   };
 
+  // Standalone path: push local edits to the consumer (form path syncs via FieldRenderer).
+  // onChange is read from a ref so callback-identity churn cannot re-emit (SB-T2-10).
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  useEffect(() => {
+    if (resolvedForm && name) return;
+    if (phoneNumber === standaloneSyncedRef.current) return;
+    standaloneSyncedRef.current = phoneNumber;
+    onChangeRef.current?.(phoneNumber);
+  }, [phoneNumber, resolvedForm, name]);
+
   // Only reset phoneNumber when the user explicitly changes the country after mount.
   // The initial value is already set by useState, so skip the first run to avoid
   // overwriting a phone number synced from form defaultValues.
@@ -224,17 +264,22 @@ export function PhoneInput<
   }
 
   const renderPhoneRow = (hasError?: boolean) => (
-    <InputParts.Box>
+    // LC-40: forward `disabled` so the Box renders the washed disabled chrome.
+    <InputParts.Box disabled={disabled}>
       <InputParts.Section>
         <View data-focus-skip {...(readOnly ? { pointerEvents: "none" as const } : undefined)}>
           <Combobox
             options={countryOptions}
             value={regionCode}
             onValueChange={(val) => setRegionCode(typeof val === "string" ? val : (val[0] ?? ""))}
-            searchPlaceholder="Search countries..."
-            emptyMessage="No countries found."
+            searchPlaceholder={t("Search countries...")}
+            emptyMessage={t("No countries found.")}
             popoverWidth={280}
             tabIndex={-1}
+            // LC-40 behavior gap: a disabled field must also inert the inner
+            // country picker (it stayed interactive on a disabled PhoneInput).
+            disabled={disabled}
+            aria-label={t("Country code")}
             trigger={(selected) => {
               const opt = Array.isArray(selected) ? selected[0] : selected;
               return (
@@ -253,19 +298,24 @@ export function PhoneInput<
         </View>
       </InputParts.Section>
       <InputParts.Section>
-        {/* @ts-expect-error Tamagui Input type widening */}
-        <InputParts.Area
-          keyboardType="numeric"
-          value={phoneNumber}
-          onChangeText={handlePhoneChange}
-          placeholder={placeholder}
-          disabled={disabled}
-          {...(readOnly ? { readOnly: true } : {})}
-          aria-required={required || undefined}
-          aria-invalid={hasError || undefined}
-          aria-readonly={readOnly || undefined}
-          {...inputProps}
-        />
+        <FocusContext.Provider {...suppressBoxFocusRing}>
+          {/* @ts-expect-error Tamagui Input type widening */}
+          <InputParts.Area
+            id={id}
+            keyboardType="numeric"
+            value={phoneNumber}
+            onChangeText={handlePhoneChange}
+            placeholder={placeholder}
+            disabled={disabled}
+            focusStyle={areaFocusRing}
+            focusVisibleStyle={areaFocusRing}
+            {...(readOnly ? { readOnly: true } : {})}
+            aria-required={required || undefined}
+            aria-invalid={hasError || undefined}
+            aria-readonly={readOnly || undefined}
+            {...inputProps}
+          />
+        </FocusContext.Provider>
       </InputParts.Section>
     </InputParts.Box>
   );
@@ -282,6 +332,8 @@ export function PhoneInput<
         size={size}
         knobProps={knobProps as any}
         onBlur={onBlur}
+        // LC-40: see form renderer — FieldLayout carries dimWhole.
+        disabled={disabled}
       >
         <InputParts size={size || knobProps.sizeToken}>{renderPhoneRow(!!errorProp)}</InputParts>
       </FieldLayout>
@@ -311,6 +363,7 @@ export function PhoneInput<
           labelProps={labelProps}
           helperText={helperText}
           required={required}
+          disabled={disabled}
           renderPhoneRow={renderPhoneRow}
         />
       )}

package/src/fields/Progress/Progress.stories.tsx

@@ -16,6 +16,9 @@ const meta: Meta<typeof Progress> = {
     helperText: { control: "text", description: "Helper text below the field" },
     error: { control: "text", description: "Error message" },
     required: { control: "boolean", description: "Mark field as required" },
+    readOnly: { control: "boolean", description: "Read-only semantics" },
+    skeleton: { control: "boolean", description: "Render a skeleton placeholder" },
+    compact: { control: "boolean", description: "Use compact sizing" },
     size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
     value: { control: { type: "number", min: 0, max: 100 }, description: "Progress value" },
     max: { control: "number", description: "Maximum value" },
@@ -165,3 +168,8 @@ export const Comparison: Story = {
     </XStack>
   ),
 };
+
+/** Loading placeholder — the skeleton mirrors the bar anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Upload progress", skeleton: true },
+};

package/src/fields/Progress/index.tsx

@@ -11,6 +11,7 @@ import {
 import { Field, FieldLayout } from "../../fieldLayout";
 import { Skeleton } from "../../Skeleton";
 import { formControlColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
 import {
   getElevationWrapperProps,
   getFieldError,
@@ -106,6 +107,8 @@ export function Progress({
         size={knobProps.sizeToken}
         borderRadius={knobProps.borderRadius.borderRadius}
         outlined={knobProps.outlined}
+        // htmlFor labels don't name div[role=progressbar] — set the name directly
+        aria-label={typeof label === "string" && label ? label : t("Progress")}
         {...progressProps}
         id={id}
         value={progressValue}

package/src/fields/RadioGroup/RadioGroup.spec.tsx

@@ -56,6 +56,29 @@ describe("RadioGroup Components", () => {
         expect(label?.textContent).toContain("Required Radio Group");
         expect(label?.textContent).toContain("*");
       });
+
+      it("fires canonical onChange and the deprecated onValueChange alias once each", async () => {
+        const onChange = vi.fn();
+        const onValueChange = vi.fn();
+        const result = renderWithProviders(
+          <RadioGroup
+            label="Choose Option"
+            name="option"
+            options={mockOptions}
+            onChange={onChange}
+            onValueChange={onValueChange}
+          />,
+        );
+        const radio = result.container.querySelector("[role='radio']");
+        expect(radio).toBeTruthy();
+        await act(async () => {
+          if (radio) fireEvent.click(radio);
+        });
+        expect(onChange).toHaveBeenCalledTimes(1);
+        expect(onChange).toHaveBeenCalledWith("option1");
+        expect(onValueChange).toHaveBeenCalledTimes(1);
+        expect(onValueChange).toHaveBeenCalledWith("option1");
+      });
     });
 
     describe("with form context", () => {
@@ -184,5 +207,124 @@ describe("RadioGroup Components", () => {
         });
       });
     });
+
+    describe("roving wrapper tab order (voiceover pass residual)", () => {
+      // Tamagui's RadioGroup leaves a focusable role-less RovingFocusGroup
+      // View around [role=radiogroup]; the field must strip it from the tab
+      // order so only the radios themselves are tab stops.
+      it("keeps the role-less outer wrapper out of the tab order", async () => {
+        const result = renderWithProviders(
+          <RadioGroup label="Choose Option" name="option" options={mockOptions} />,
+        );
+        const group = result.container.querySelector("[role='radiogroup']");
+        expect(group).toBeTruthy();
+        const wrapper = group?.parentElement;
+        expect(wrapper?.getAttribute("role")).toBeNull();
+        // The roving group re-applies tabIndex=0 after focusable items
+        // register; the MutationObserver must settle it back to -1.
+        await waitFor(() => {
+          expect(wrapper?.getAttribute("tabindex")).toBe("-1");
+        });
+      });
+
+      it("exposes exactly one tab stop among the radios (roving tabindex)", async () => {
+        // WAI-ARIA radio group: the group is ONE tab stop — the checked radio
+        // (or the first when none is checked) carries tabindex=0, the rest
+        // are -1 and reached with arrow keys (keyboard-nav audit).
+        const result = renderWithProviders(
+          <RadioGroup label="Choose Option" name="option" options={mockOptions} />,
+        );
+        const radios = [...result.container.querySelectorAll("[role='radio']")];
+        expect(radios.length).toBe(mockOptions.length);
+        expect(radios.map((radio) => radio.getAttribute("tabindex"))).toEqual(["0", "-1", "-1"]);
+      });
+
+      it("moves the tab stop to the checked radio", async () => {
+        const result = renderWithProviders(
+          <RadioGroup
+            label="Choose Option"
+            name="option"
+            value={mockOptions[1].value}
+            options={mockOptions}
+          />,
+        );
+        const radios = [...result.container.querySelectorAll("[role='radio']")];
+        expect(radios.map((radio) => radio.getAttribute("tabindex"))).toEqual(["-1", "0", "-1"]);
+      });
+
+      it("re-strips the wrapper tabindex when the roving group re-applies it", async () => {
+        const result = renderWithProviders(
+          <RadioGroup label="Choose Option" name="option" options={mockOptions} />,
+        );
+        const wrapper = result.container.querySelector("[role='radiogroup']")?.parentElement;
+        await waitFor(() => expect(wrapper?.getAttribute("tabindex")).toBe("-1"));
+        // Simulate the roving group's blur-cycle write of tabIndex=0
+        wrapper?.setAttribute("tabindex", "0");
+        await waitFor(() => {
+          expect(wrapper?.getAttribute("tabindex")).toBe("-1");
+        });
+      });
+    });
+
+    describe("card mode (LC-22 SELECTION-CARD)", () => {
+      const cardOptions = [
+        { label: "Card A", value: "a", description: "Description for A" },
+        { label: "Card B", value: "b" },
+      ];
+
+      it("renders option descriptions in card mode", () => {
+        const result = renderWithProviders(
+          <RadioGroup label="Pick" name="opts" card options={cardOptions} />,
+        );
+        expect(result.findTextElement("Card A")).toBeDefined();
+        expect(result.findTextElement("Description for A")).toBeDefined();
+      });
+
+      it("does not render descriptions in plain mode", () => {
+        const result = renderWithProviders(
+          <RadioGroup label="Pick" name="opts" options={cardOptions} />,
+        );
+        expect(result.findTextElement("Card A")).toBeDefined();
+        expect(result.findTextElement("Description for A")).toBeUndefined();
+      });
+
+      it("labels the radio via aria-labelledby and aria-describedby", () => {
+        const result = renderWithProviders(
+          <RadioGroup label="Pick" name="opts" card options={cardOptions} />,
+        );
+        const radio = result.container.querySelector("[role='radio']");
+        const labelId = radio?.getAttribute("aria-labelledby");
+        const descId = radio?.getAttribute("aria-describedby");
+        expect(labelId).toBeTruthy();
+        expect(document.getElementById(labelId!)?.textContent).toBe("Card A");
+        expect(descId).toBeTruthy();
+        expect(document.getElementById(descId!)?.textContent).toBe("Description for A");
+      });
+
+      it("radio click in card mode emits onChange with the selected value", () => {
+        const onChange = vi.fn();
+        const result = renderWithProviders(
+          <RadioGroup label="Pick" name="opts" card options={cardOptions} onChange={onChange} />,
+        );
+        const radio = result.container.querySelector("[role='radio']");
+        if (radio) fireEvent.click(radio);
+        expect(onChange).toHaveBeenCalledWith("a");
+        // last emit wins and must be the selected value (no double-fire revert)
+        expect(onChange.mock.calls[onChange.mock.calls.length - 1][0]).toBe("a");
+      });
+
+      it("keeps index-based ids unique for duplicate option values", () => {
+        const dupes = [
+          { label: "One", value: "same", description: "d1" },
+          { label: "Two", value: "same", description: "d2" },
+        ];
+        const result = renderWithProviders(
+          <RadioGroup label="Pick" name="opts" card options={dupes} />,
+        );
+        const radios = [...result.container.querySelectorAll("[role='radio']")];
+        const ids = radios.map((r) => r.id);
+        expect(new Set(ids).size).toBe(2);
+      });
+    });
   });
 });

package/src/fields/RadioGroup/RadioGroup.stories.tsx

@@ -135,6 +135,43 @@ export const Standalone: Story = {
   render: (args) => <RadioGroup {...args} />,
 };
 
+/**
+ * Selection-card mode: radio in a leading slot, bold label to its right,
+ * muted `option.description` under the label; the whole card selects.
+ * Consumes the shared CheckboxCard primitives (LC-22).
+ */
+export const CardMode: Story = {
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <RadioGroup
+        {...args}
+        card
+        label="Payment methods"
+        helperText={undefined}
+        options={[
+          {
+            value: "card",
+            label: "Credit or debit card",
+            description: "Visa, Mastercard, and American Express.",
+          },
+          {
+            value: "bank",
+            label: "Bank transfer",
+            description: "Direct transfer from your bank account.",
+          },
+          {
+            value: "wallet",
+            label: "Digital wallet",
+            description: "Apple Pay, Google Pay, or PayPal.",
+          },
+        ]}
+        defaultValue="card"
+        onChange={action("onChange")}
+      />
+    </YStack>
+  ),
+};
+
 export const Basic: Story = {
   args: {
     label: "Choose an option",
@@ -295,3 +332,8 @@ export const Comparison: Story = {
     return <ComparisonExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors control + label rows (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: () => <RadioGroup label="Notification Preference" options={sampleOptions} skeleton />,
+};