@multiplatform.one/forms 6.4.2 → 6.6.0

package/src/fields/DatePicker/DatePicker.stories.tsx

@@ -116,7 +116,8 @@ export const Disabled: Story = {
 export const WithError: Story = {
   args: {
     label: "Required Date",
-    error: "Please select a date",
+    // DG-COPY-02: error copy states the rule broken — never "please"/"invalid"/"error".
+    error: "A date is required",
     required: true,
   },
 };

package/src/fields/DatePicker/DateRangePicker.spec.tsx

@@ -1,6 +1,8 @@
+import { useForm } from "@tanstack/react-form";
 import { act, fireEvent, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Form } from "../../Form";
 
 vi.mock("react-native", () => ({
   Platform: {
@@ -87,4 +89,74 @@ describe("DateRangePicker", () => {
       expect(input?.value ?? "").toContain("–");
     });
   });
+
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // The form branch displays from `rangeStart`/`rangeEnd`, which only user
+    // picks and the standalone `value` prop used to update — a field value
+    // applied AFTER first paint (create-mode engine seeding, setFieldValue)
+    // never rendered. Adopting a programmatic value must not emit onChange
+    // (LC-14: a seeded value is not a user edit).
+    it("form-integrated: a field value set after mount displays, without onChange", async () => {
+      const DateRangePicker = await loadDateRangePicker();
+      const onChange = vi.fn();
+      type Range = { start: Date; end: Date } | null;
+      let formApi: { setFieldValue: (name: "range", value: Range) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { range: null as Range } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <DateRangePicker label="Range" name="range" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      const getInput = () => result.container.querySelector("input") as HTMLInputElement | null;
+      expect(getInput()?.value ?? "").toBe("");
+
+      await act(async () => {
+        formApi?.setFieldValue("range", {
+          start: new Date(2026, 2, 5),
+          end: new Date(2026, 2, 12),
+        });
+      });
+      await waitFor(() => {
+        expect(getInput()?.value).toBe("Mar 5, 2026 – Mar 12, 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("form-integrated: clearing the field value programmatically clears the display", async () => {
+      const DateRangePicker = await loadDateRangePicker();
+      const onChange = vi.fn();
+      type Range = { start: Date; end: Date } | null;
+      let formApi: { setFieldValue: (name: "range", value: Range) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({
+          defaultValues: {
+            range: { start: new Date(2026, 2, 5), end: new Date(2026, 2, 12) } as Range,
+          },
+        });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <DateRangePicker label="Range" name="range" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      const getInput = () => result.container.querySelector("input") as HTMLInputElement | null;
+      await waitFor(() => {
+        expect(getInput()?.value).toBe("Mar 5, 2026 – Mar 12, 2026");
+      });
+
+      await act(async () => {
+        formApi?.setFieldValue("range", null);
+      });
+      await waitFor(() => {
+        expect(getInput()?.value ?? "").toBe("");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/fields/DatePicker/DateRangePicker.tsx

@@ -32,6 +32,7 @@ import {
   useDateNavigation,
   yearPageSize,
 } from "./parts";
+import { FieldValueSync } from "./fieldValueSync";
 
 import type { ViewMode } from "./parts";
 
@@ -471,24 +472,31 @@ export function DateRangePicker<
     setOpen(true);
   }, [setDisplayDate]);
 
-  // Keep standalone/controlled state in sync when the parent value changes.
-  // Skip while a range is half-picked (start set, end pending): the first click
-  // of a new range used to call onChange(null), and syncing that null wiped
-  // rangeStart so the second click could never complete (SB-T2-03).
+  // Adopt an externally-applied value (controlled `value` prop or the live
+  // TanStack field value) into the display state without emitting onChange
+  // (LC-14). Skip while a range is half-picked (start set, end pending): the
+  // first click of a new range used to call onChange(null), and syncing that
+  // null wiped rangeStart so the second click could never complete (SB-T2-03).
   const pickingRangeRef = useRef(false);
-  useEffect(() => {
-    if (valueProp === undefined) return;
-    if (pickingRangeRef.current && valueProp == null) return;
+  const adoptExternalValue = useCallback((raw: unknown) => {
+    const next = (raw ?? null) as DateRange | null;
+    if (pickingRangeRef.current && next == null) return;
     pickingRangeRef.current = false;
-    const nextStart = valueProp?.start ?? null;
-    const nextEnd = valueProp?.end ?? null;
+    const nextStart = next?.start ?? null;
+    const nextEnd = next?.end ?? null;
     setRangeStart((prev) =>
       prev === nextStart || (prev && nextStart && isSameDay(prev, nextStart)) ? prev : nextStart,
     );
     setRangeEnd((prev) =>
       prev === nextEnd || (prev && nextEnd && isSameDay(prev, nextEnd)) ? prev : nextEnd,
     );
-  }, [valueProp]);
+  }, []);
+
+  // Keep standalone/controlled state in sync when the parent value changes.
+  useEffect(() => {
+    if (valueProp === undefined) return;
+    adoptExternalValue(valueProp);
+  }, [valueProp, adoptExternalValue]);
 
   const closePopover = useCallback(() => {
     setOpen(false);
@@ -647,26 +655,32 @@ export function DateRangePicker<
         const resolvedError = getFieldError(field, errorProp);
 
         return (
-          <FieldLayout
-            id={id}
-            label={label}
-            labelProps={labelProps}
-            error={resolvedError}
-            helperText={helperText}
-            required={required}
-            size={size}
-            knobProps={knobProps}
-            // LC-40: see standalone branch — FieldLayout carries dimWhole.
-            disabled={disabled}
-          >
-            <InputParts size={size || knobProps.sizeToken}>
-              {renderPopover(
-                !!resolvedError,
-                mergeFieldHandler(field, "handleBlur", _onBlur),
-                mergeFieldHandler(field, "handleChange"),
-              )}
-            </InputParts>
-          </FieldLayout>
+          <>
+            {/* Form branch displays from `rangeStart`/`rangeEnd` — keep them
+                synced to the live field value (late seeds / programmatic
+                updates). */}
+            <FieldValueSync value={field.state.value} onSync={adoptExternalValue} />
+            <FieldLayout
+              id={id}
+              label={label}
+              labelProps={labelProps}
+              error={resolvedError}
+              helperText={helperText}
+              required={required}
+              size={size}
+              knobProps={knobProps}
+              // LC-40: see standalone branch — FieldLayout carries dimWhole.
+              disabled={disabled}
+            >
+              <InputParts size={size || knobProps.sizeToken}>
+                {renderPopover(
+                  !!resolvedError,
+                  mergeFieldHandler(field, "handleBlur", _onBlur),
+                  mergeFieldHandler(field, "handleChange"),
+                )}
+              </InputParts>
+            </FieldLayout>
+          </>
         );
       }}
     </Field>

package/src/fields/DatePicker/DatetimePicker.spec.tsx

@@ -146,4 +146,43 @@ describe("DatetimePicker", () => {
       expect(onSubmit.mock.calls[0][0].appt).toBeInstanceOf(Date);
     });
   });
+
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // The form branch displays from `selectedDatetime`, kept synced to the
+    // live field value by DatePickerFieldValueSync — a value applied AFTER
+    // first paint (create-mode engine seeding, setFieldValue, live server
+    // merge) must render. Adopting a programmatic value must not emit
+    // onChange (LC-14: a seeded value is not a user edit).
+    it("form-integrated: a field value set after mount displays, without onChange", async () => {
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      let formApi: { setFieldValue: (name: "appt", value: Date | null) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { appt: null as Date | null } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <DatetimePicker
+              name="appt"
+              label="Appointment"
+              onChange={onChange}
+              onValueChange={onValueChange}
+            />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      const getInput = () => result.container.querySelector("input") as HTMLInputElement | null;
+      expect(getInput()?.value ?? "").toBe("");
+
+      await act(async () => {
+        formApi?.setFieldValue("appt", new Date(2026, 2, 5, 14, 30));
+      });
+      await waitFor(() => {
+        expect(getInput()?.value ?? "").toContain("Mar 5, 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+      expect(onValueChange).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/fields/DatePicker/DatetimePicker.tsx

@@ -368,7 +368,7 @@ function TimeSection({
                 backgroundColor={isSelected ? formInputColors.background.focus : "transparent"}
                 hoverStyle={{ backgroundColor: formInputColors.background.focus }}
                 onPress={() => handlePeriodChange(p)}
-                {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+                {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
               >
                 <Text
                   fontSize="$3"

package/src/fields/DatePicker/MonthPicker.spec.tsx

@@ -142,4 +142,65 @@ describe("MonthPicker", () => {
       );
     });
   });
+
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // `selectedValue` was hardcoded to null at mount and only user picks set
+    // it, so a field value applied at ANY point (even the Field-level
+    // defaultValue) never displayed. The form branch now adopts the live
+    // field value — without emitting onChange (LC-14: a seeded value is not
+    // a user edit).
+    it("form-integrated: a field value set after mount displays, without onChange", async () => {
+      const onChange = vi.fn();
+      let formApi:
+        | { setFieldValue: (name: "month", value: { month: number; year: number } | null) => void }
+        | undefined;
+      const TestComponent = () => {
+        const form = useForm({
+          defaultValues: { month: null as { month: number; year: number } | null },
+        });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <MonthPicker name="month" label="Month" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      const getInput = () => result.container.querySelector("input") as HTMLInputElement | null;
+      expect(getInput()?.value ?? "").toBe("");
+
+      await act(async () => {
+        formApi?.setFieldValue("month", { month: 2, year: 2026 });
+      });
+      await waitFor(() => {
+        expect(getInput()?.value).toBe("March 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("form-integrated: a Field-level defaultValue displays at mount", async () => {
+      const onChange = vi.fn();
+      const TestComponent = () => {
+        const form = useForm({
+          defaultValues: { month: undefined as { month: number; year: number } | undefined },
+        });
+        return (
+          <Form form={form}>
+            <MonthPicker
+              name="month"
+              label="Month"
+              defaultValue={{ month: 6, year: 2025 }}
+              onChange={onChange}
+            />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      await waitFor(() => {
+        const input = result.container.querySelector("input") as HTMLInputElement | null;
+        expect(input?.value).toBe("July 2025");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/fields/DatePicker/MonthPicker.tsx

@@ -5,7 +5,6 @@ import { Text, View, useProps, type Popover } from "tamagui";
 
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
-import { formCommonColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
 import {
   getFieldError,
@@ -28,6 +27,7 @@ import {
   useDateNavigation,
   yearPageSize,
 } from "./parts";
+import { FieldValueSync } from "./fieldValueSync";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -264,6 +264,27 @@ export function MonthPicker<
   const { displayDate, setDisplayDate } = useDateNavigation();
   const popoverRef = useRef<Popover>(null);
 
+  // Display comes from `selectedValue`, which only user picks used to set —
+  // a field value applied AFTER mount (create-mode seeding, setFieldValue,
+  // even the Field-level defaultValue) never rendered. Adopt the live field
+  // value without emitting onChange (LC-14). Identity is preserved when the
+  // month is unchanged so the close-on-select effect never re-fires.
+  const adoptFieldValue = useCallback((raw: unknown) => {
+    const next =
+      raw !== null &&
+      typeof raw === "object" &&
+      typeof (raw as MonthPickerValue).month === "number" &&
+      typeof (raw as MonthPickerValue).year === "number"
+        ? (raw as MonthPickerValue)
+        : null;
+    setSelectedValue((prev) =>
+      prev === next ||
+      (prev !== null && next !== null && prev.month === next.month && prev.year === next.year)
+        ? prev
+        : next,
+    );
+  }, []);
+
   const closePopover = useCallback(() => {
     setOpen(false);
     popoverRef.current?.close();
@@ -395,26 +416,31 @@ export function MonthPicker<
         const resolvedError = getFieldError(field, errorProp);
 
         return (
-          <FieldLayout
-            id={id}
-            label={label}
-            labelProps={labelProps}
-            error={resolvedError}
-            helperText={helperText}
-            required={required}
-            size={size}
-            knobProps={knobProps}
-            // LC-40: see standalone branch — FieldLayout carries dimWhole.
-            disabled={disabled}
-          >
-            <InputParts size={size || knobProps.sizeToken}>
-              {renderPopover(
-                !!resolvedError,
-                mergeFieldHandler(field, "handleBlur", _onBlur),
-                mergeFieldHandler(field, "handleChange"),
-              )}
-            </InputParts>
-          </FieldLayout>
+          <>
+            {/* Form branch displays from `selectedValue` — keep it synced to
+                the live field value (late seeds / programmatic updates). */}
+            <FieldValueSync value={field.state.value} onSync={adoptFieldValue} />
+            <FieldLayout
+              id={id}
+              label={label}
+              labelProps={labelProps}
+              error={resolvedError}
+              helperText={helperText}
+              required={required}
+              size={size}
+              knobProps={knobProps}
+              // LC-40: see standalone branch — FieldLayout carries dimWhole.
+              disabled={disabled}
+            >
+              <InputParts size={size || knobProps.sizeToken}>
+                {renderPopover(
+                  !!resolvedError,
+                  mergeFieldHandler(field, "handleBlur", _onBlur),
+                  mergeFieldHandler(field, "handleChange"),
+                )}
+              </InputParts>
+            </FieldLayout>
+          </>
         );
       }}
     </Field>

package/src/fields/DatePicker/MultiDatePicker.spec.tsx

@@ -1,6 +1,8 @@
+import { useForm } from "@tanstack/react-form";
 import { act, fireEvent, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Form } from "../../Form";
 
 vi.mock("react-native", () => ({
   Platform: {
@@ -90,4 +92,36 @@ describe("MultiDatePicker", () => {
       expect(input?.value ?? "").toBe("");
     });
   });
+
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // The form branch displays from `selectedDates`, which only user picks
+    // and the standalone `value` prop used to update — a field value applied
+    // AFTER first paint (create-mode engine seeding, setFieldValue) never
+    // rendered. Adopting a programmatic value must not emit onChange (LC-14).
+    it("form-integrated: a field value set after mount displays, without onChange", async () => {
+      const MultiDatePicker = await loadMultiDatePicker();
+      const onChange = vi.fn();
+      let formApi: { setFieldValue: (name: "dates", value: Date[]) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { dates: [] as Date[] } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <MultiDatePicker label="Dates" name="dates" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      const getInput = () => result.container.querySelector("input") as HTMLInputElement | null;
+      expect(getInput()?.value ?? "").toBe("");
+
+      await act(async () => {
+        formApi?.setFieldValue("dates", [new Date(2026, 2, 5)]);
+      });
+      await waitFor(() => {
+        expect(getInput()?.value).toBe("Mar 5, 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/fields/DatePicker/MultiDatePicker.tsx

@@ -32,6 +32,7 @@ import {
   useDateNavigation,
   yearPageSize,
 } from "./parts";
+import { FieldValueSync } from "./fieldValueSync";
 
 import type { ViewMode } from "./parts";
 
@@ -414,19 +415,25 @@ export function MultiDatePicker<
     setOpen(true);
   }, [setDisplayDate]);
 
-  // Keep standalone/controlled state in sync when the parent value changes.
-  // Skip setState when the calendar days are unchanged so a new array identity
-  // from the parent cannot force a render storm.
-  useEffect(() => {
-    if (valueProp === undefined) return;
-    const next = Array.isArray(valueProp) ? valueProp : [];
+  // Adopt an externally-applied value (controlled `value` prop or the live
+  // TanStack field value) into the display state without emitting onChange
+  // (LC-14). Skip setState when the calendar days are unchanged so a new
+  // array identity from the parent cannot force a render storm.
+  const adoptExternalValue = useCallback((raw: unknown) => {
+    const next = Array.isArray(raw) ? (raw as Date[]) : [];
     const prev = selectedDatesRef.current;
     const same =
       prev.length === next.length && prev.every((d, i) => next[i] != null && isSameDay(d, next[i]));
     if (same) return;
     selectedDatesRef.current = next;
     setSelectedDates(next);
-  }, [valueProp]);
+  }, []);
+
+  // Keep standalone/controlled state in sync when the parent value changes.
+  useEffect(() => {
+    if (valueProp === undefined) return;
+    adoptExternalValue(valueProp);
+  }, [valueProp, adoptExternalValue]);
 
   const handleToggleDate = useCallback(
     (date: Date, fieldChange?: (value: any) => void) => {
@@ -560,26 +567,31 @@ export function MultiDatePicker<
         const resolvedError = getFieldError(field, errorProp);
 
         return (
-          <FieldLayout
-            id={id}
-            label={label}
-            labelProps={labelProps}
-            error={resolvedError}
-            helperText={helperText}
-            required={required}
-            size={size}
-            knobProps={knobProps}
-            // LC-40: see standalone branch — FieldLayout carries dimWhole.
-            disabled={disabled}
-          >
-            <InputParts size={size || knobProps.sizeToken}>
-              {renderPopover(
-                !!resolvedError,
-                mergeFieldHandler(field, "handleBlur", _onBlur),
-                mergeFieldHandler(field, "handleChange"),
-              )}
-            </InputParts>
-          </FieldLayout>
+          <>
+            {/* Form branch displays from `selectedDates` — keep it synced to
+                the live field value (late seeds / programmatic updates). */}
+            <FieldValueSync value={field.state.value} onSync={adoptExternalValue} />
+            <FieldLayout
+              id={id}
+              label={label}
+              labelProps={labelProps}
+              error={resolvedError}
+              helperText={helperText}
+              required={required}
+              size={size}
+              knobProps={knobProps}
+              // LC-40: see standalone branch — FieldLayout carries dimWhole.
+              disabled={disabled}
+            >
+              <InputParts size={size || knobProps.sizeToken}>
+                {renderPopover(
+                  !!resolvedError,
+                  mergeFieldHandler(field, "handleBlur", _onBlur),
+                  mergeFieldHandler(field, "handleChange"),
+                )}
+              </InputParts>
+            </FieldLayout>
+          </>
         );
       }}
     </Field>

package/src/fields/DatePicker/fieldValueSync.tsx

@@ -32,3 +32,26 @@ export function DatePickerFieldValueSync({
   }, [value, onSync]);
   return null;
 }
+
+/**
+ * Shape-agnostic variant for pickers whose display state is not a single
+ * Date (MonthPicker's {month,year}, MultiDatePicker's Date[],
+ * DateRangePicker's {start,end}): mirrors the live TanStack field value into
+ * the picker's adoption callback whenever it changes (including mount, so a
+ * Field-level defaultValue displays too). Each picker's `onSync` owns its
+ * coercion + identity-preserving equality guard, and must never emit
+ * onChange from this path (LC-14 — a programmatic value application is not
+ * a user edit).
+ */
+export function FieldValueSync({
+  value,
+  onSync,
+}: {
+  value: unknown;
+  onSync: (value: unknown) => void;
+}) {
+  useEffect(() => {
+    onSync(value);
+  }, [value, onSync]);
+  return null;
+}

package/src/fields/DatePicker/parts.tsx

@@ -2,6 +2,7 @@ import { Calendar, ChevronLeft, ChevronRight, X } from "@tamagui/lucide-icons-2"
 import {
   ensureFocusVisibleRing,
   formatAbsoluteDate,
+  getMonthNames,
   useResolvedKnobs,
 } from "@multiplatform.one/theme";
 import {
@@ -100,6 +101,10 @@ export function useDateAnimation(current: string | number) {
 // useCalendarData — compute calendar grid for a given month
 // ---------------------------------------------------------------------------
 
+// Picker headers speak the house month register (LC-12 render channel), not
+// a locale pinned to en-US at the call site.
+const monthNames = getMonthNames();
+
 export function useCalendarData(displayDate: Date): CalendarData {
   return useMemo(() => {
     const year = displayDate.getFullYear();
@@ -122,7 +127,7 @@ export function useCalendarData(displayDate: Date): CalendarData {
     return {
       year,
       month,
-      monthName: displayDate.toLocaleDateString("en-US", { month: "long" }),
+      monthName: monthNames[month],
       days,
       today: new Date(),
     };

package/src/fields/FileUpload/FileUpload.stories.tsx

@@ -107,6 +107,15 @@ export const Basic: Story = {
 };
 
 export const Disabled: Story = {
+  parameters: {
+    // LC-57 allowlist: disabled-dial demo; FileUpload's internal upload Button
+    // has no disabledReason plumbing yet (component-contract follow-up).
+    guardrailSpecimen: {
+      warns: ["bare-disabled"],
+      reason:
+        "Disabled-dial specimen: FileUpload's internal upload Button has no disabledReason plumbing yet.",
+    },
+  },
   render: (args) => <FileUpload {...args} />,
   args: {
     label: "Disabled Upload",
@@ -119,7 +128,8 @@ export const WithError: Story = {
   render: (args) => <FileUpload {...args} />,
   args: {
     label: "Required File",
-    error: "Please upload a file",
+    // DG-COPY-02: error copy states the rule broken — never "please"/"invalid"/"error".
+    error: "A file is required",
     required: true,
   },
 };

package/src/fields/Geolocation/Geolocation.stories.tsx

@@ -95,6 +95,15 @@ export const Basic: Story = {
 };
 
 export const Disabled: Story = {
+  parameters: {
+    // LC-57 allowlist: disabled-dial demo; Geolocation's internal action
+    // Buttons have no disabledReason plumbing yet (component-contract follow-up).
+    guardrailSpecimen: {
+      warns: ["bare-disabled"],
+      reason:
+        "Disabled-dial specimen: Geolocation's internal action Buttons have no disabledReason plumbing yet.",
+    },
+  },
   args: {
     label: "Location",
     helperText: "This field is disabled",