@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/DatePicker/index.tsx

@@ -1,5 +1,5 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useAccentOnSurface, useResolvedKnobs } from "@multiplatform.one/theme";
 import { type ComponentProps, useCallback, useEffect, useRef, useState } from "react";
 import { coerceToDate } from "./utils";
 import { AnimatePresence, type Popover, View, useProps } from "tamagui";
@@ -7,6 +7,7 @@ import { AnimatePresence, type Popover, View, useProps } from "tamagui";
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formCommonColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
 import {
   getFieldError,
   mergeFieldHandler,
@@ -22,7 +23,7 @@ import {
   CalendarHeader,
   DatePickerInputTrigger,
   DatePickerPopoverShell,
-  ViewSwitcher,
+  CalendarViewSwitcher,
   WeekView,
   formatDateDisplay,
   isSameDay,
@@ -49,7 +50,9 @@ export type DatePickerProps<
   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<
@@ -70,7 +73,12 @@ export type DatePickerProps<
     compact?: boolean;
     /** Standalone controlled value (Date or ISO string). Ignored when used inside a form. */
     value?: Date | string | null;
-    /** Standalone change callback. Ignored when used inside a form. */
+    /**
+     * Canonical change handler, consistent with the rest of the field family.
+     * Prefer this over `onValueChange`.
+     */
+    onChange?: (value: Date | null) => void;
+    /** @deprecated Use `onChange` instead. */
     onValueChange?: (value: Date | null) => void;
   };
 
@@ -88,6 +96,8 @@ interface DayGridProps {
 
 function DayGrid({ calendarData, selectedDate, onSelectDate, minDate, maxDate }: DayGridProps) {
   const { knobProps } = useResolvedKnobs();
+  // UX-P03 / Axiom 12: page-readable accent for the today marker (see Calendar).
+  const accentText = useAccentOnSurface();
   const { animation, animationKey } = useDateAnimation(
     `${calendarData.year}-${calendarData.month}`,
   );
@@ -146,7 +156,7 @@ function DayGrid({ calendarData, selectedDate, onSelectDate, minDate, maxDate }:
                         key="text-normal"
                         color={
                           isToday
-                            ? "$accentColor"
+                            ? accentText
                             : isCurrentMonth
                               ? formCommonColors.text
                               : formCommonColors.muted
@@ -197,7 +207,7 @@ function CalendarBody({
   );
 
   return (
-    <ViewSwitcher
+    <CalendarViewSwitcher
       calendarData={calendarData}
       displayDate={displayDate}
       onSetDisplayDate={onSetDisplayDate}
@@ -232,7 +242,7 @@ function CalendarBody({
           maxDate={maxDate}
         />
       </View>
-    </ViewSwitcher>
+    </CalendarViewSwitcher>
   );
 }
 
@@ -250,10 +260,11 @@ export function DatePicker<
   const {
     defaultValue,
     value: controlledValue,
+    onChange,
     onValueChange,
     form,
     inputProps: _inputProps,
-    placeholder = "Select date",
+    placeholder = t("Select date"),
     format: _format = "MM/DD/YYYY",
     minDate,
     maxDate,
@@ -278,6 +289,7 @@ export function DatePicker<
 
   const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const hasLabel = Boolean(label);
 
   const [open, setOpen] = useState(false);
   const [selectedDate, setSelectedDate] = useState<Date | null>(() =>
@@ -288,7 +300,12 @@ export function DatePicker<
     if (controlledValue === undefined) return;
     setSelectedDate(coerceToDate(controlledValue));
   }, [controlledValue]);
-  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation();
+  // Axiom 11 VALUE IS DATA: the calendar opens at the selected value's
+  // month, not today's — seed the display date from the current value and
+  // re-seed on every open (see openCalendar / handleOpenChange).
+  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation(
+    selectedDate ?? undefined,
+  );
   const popoverRef = useRef<Popover>(null);
 
   const closePopover = useCallback(() => {
@@ -301,28 +318,37 @@ export function DatePicker<
   }, [selectedDate, closePopover]);
 
   const handleDateSelect = useCallback(
-    (date: Date) => {
+    (date: Date, fieldChange?: (value: any) => void) => {
       if (minDate && date < minDate) return;
       if (maxDate && date > maxDate) return;
       setSelectedDate(date);
       setDisplayDate(date);
+      // Form mode: commit into TanStack field state (clears meta errors on change).
+      fieldChange?.(date);
+      // Canonical `onChange` and the alias `onValueChange` both fire (single emit).
+      onChange?.(date);
       onValueChange?.(date);
       closePopover();
     },
-    [minDate, maxDate, setDisplayDate, closePopover, onValueChange],
+    [minDate, maxDate, setDisplayDate, closePopover, onChange, onValueChange],
   );
 
-  const handleClearDate = useCallback(() => {
-    setSelectedDate(null);
-    setDisplayDate(new Date());
-    onValueChange?.(null);
-  }, [setDisplayDate, onValueChange]);
+  const handleClearDate = useCallback(
+    (fieldChange?: (value: any) => void) => {
+      setSelectedDate(null);
+      setDisplayDate(new Date());
+      fieldChange?.(null);
+      onChange?.(null);
+      onValueChange?.(null);
+    },
+    [setDisplayDate, onChange, onValueChange],
+  );
 
-  const calendarContent = (
+  const calendarContent = (fieldChange?: (value: any) => void) => (
     <CalendarBody
       displayDate={displayDate}
       selectedDate={selectedDate}
-      onSelectDate={handleDateSelect}
+      onSelectDate={(date) => handleDateSelect(date, fieldChange)}
       onNavigateMonth={navigateMonth}
       onSetDisplayDate={setDisplayDate}
       minDate={minDate}
@@ -330,7 +356,11 @@ export function DatePicker<
     />
   );
 
-  const renderPopover = (hasError?: boolean, blurHandler?: (...args: any[]) => void) => {
+  const renderPopover = (
+    hasError?: boolean,
+    blurHandler?: (...args: any[]) => void,
+    fieldChange?: (value: any) => void,
+  ) => {
     if (readOnly) {
       return (
         <InputParts.Box>
@@ -347,6 +377,9 @@ export function DatePicker<
     }
 
     const handleOpenChange = (isOpen: boolean) => {
+      // Re-seed the visible month from the current value on every open —
+      // the value may have changed (externally or by a pick) since mount.
+      if (isOpen && selectedDate) setDisplayDate(selectedDate);
       setOpen(isOpen);
       if (!isOpen) {
         blurHandler?.();
@@ -358,20 +391,41 @@ export function DatePicker<
         open={open}
         onOpenChange={handleOpenChange}
         popoverRef={popoverRef}
+        // "Date, Jul 15 2026": VO gets the field name + current value on the
+        // native trigger (the web trigger announces via aria on the Area).
+        triggerA11y={{
+          label: (typeof label === "string" && label) || t("Date"),
+          value: formatDateDisplay(selectedDate) || placeholder,
+          hint: helperText,
+        }}
         trigger={
           <DatePickerInputTrigger
             value={formatDateDisplay(selectedDate)}
             placeholder={placeholder}
             disabled={disabled}
-            onReset={handleClearDate}
-            onButtonPress={() => setOpen(true)}
+            onReset={() => handleClearDate(fieldChange)}
+            onButtonPress={() => {
+              if (selectedDate) setDisplayDate(selectedDate);
+              setOpen(true);
+            }}
             error={!!hasError}
+            id={id}
+            aria-labelledby={hasLabel ? `${id}-label` : undefined}
+            aria-label={hasLabel ? undefined : t("Date")}
+            aria-describedby={
+              [
+                helperText && id ? `${id}-description` : undefined,
+                hasError && id ? `${id}-error` : undefined,
+              ]
+                .filter(Boolean)
+                .join(" ") || undefined
+            }
             aria-required={required || undefined}
             aria-invalid={hasError || undefined}
           />
         }
       >
-        {calendarContent}
+        {calendarContent(fieldChange)}
       </DatePickerPopoverShell>
     );
   };
@@ -397,6 +451,9 @@ export function DatePicker<
         size={size}
         knobProps={knobProps}
         onBlur={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}>{renderPopover(!!errorProp)}</InputParts>
       </FieldLayout>
@@ -414,7 +471,6 @@ export function DatePicker<
     >
       {(field) => {
         const resolvedError = getFieldError(field, errorProp);
-        const blurHandler = mergeFieldHandler(field, "handleBlur", onBlur);
 
         return (
           <FieldLayout
@@ -426,9 +482,15 @@ export function DatePicker<
             required={required}
             size={size}
             knobProps={knobProps}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             <InputParts size={size || knobProps.sizeToken}>
-              {renderPopover(!!resolvedError, blurHandler)}
+              {renderPopover(
+                !!resolvedError,
+                mergeFieldHandler(field, "handleBlur", onBlur),
+                mergeFieldHandler(field, "handleChange"),
+              )}
             </InputParts>
           </FieldLayout>
         );

package/src/fields/DatePicker/parts.tsx

@@ -1,5 +1,9 @@
 import { Calendar, ChevronLeft, ChevronRight, X } from "@tamagui/lucide-icons-2";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ensureFocusVisibleRing,
+  formatAbsoluteDate,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import {
   type ReactNode,
   type RefObject,
@@ -9,12 +13,22 @@ import {
   useRef,
   useState,
 } from "react";
-import { AnimatePresence, Text, View } from "tamagui";
+import { AnimatePresence, Text, View, isWeb } from "tamagui";
 
 import { Button } from "../../Button";
 import { FloatingPanel } from "../../FloatingPanel";
-import { Input as InputParts } from "../../InputParts";
+import { FocusContext, Input as InputParts } from "../../InputParts";
 import { formCommonColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
+
+/**
+ * The knob focus ring must be CSS-driven on the focused trigger input itself
+ * (DG-A11Y-01): Input.Box paints its ring from React `focused` state one
+ * frame after focus, which synchronous a11y probes never see. The Box ring
+ * is suppressed via this no-op FocusContext so the trigger shows exactly one
+ * ring — same pattern as OTPInput/Stepper/Input.
+ */
+const suppressBoxFocusRing = { focused: false, setFocused: (_val: boolean) => {} };
 
 // ---------------------------------------------------------------------------
 // Types
@@ -154,6 +168,21 @@ export function isSameDay(a: Date | null | undefined, b: Date | null | undefined
   return a.toDateString() === b.toDateString();
 }
 
+// ---------------------------------------------------------------------------
+// dayCellRadius — binary-pointy day cells
+// ---------------------------------------------------------------------------
+
+/**
+ * Day cells are circular by default; at the "none" borderRadius knob they go
+ * square (binary-pointy, same contract as Switch/Radio). Uses an inline style
+ * because the `circular` variant's expansion wins over a plain borderRadius prop.
+ */
+export function dayCellRadius(knobProps: {
+  pointy?: boolean;
+}): { style: { borderRadius: number } } | undefined {
+  return knobProps.pointy ? { style: { borderRadius: 0 } } : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // WeekView — weekday header row
 // ---------------------------------------------------------------------------
@@ -168,11 +197,12 @@ export function WeekView() {
           flex={1}
           textAlign="center"
           fontSize={knobProps.sizeToken}
-          color="$placeholderColor"
+          // muted tier, not $placeholderColor: real text, AA 4.5:1 floor
+          color={formCommonColors.muted}
           {...knobProps.body}
           {...knobProps.textWeight}
         >
-          {day}
+          {t(day)}
         </Text>
       ))}
     </View>
@@ -214,6 +244,7 @@ export function CalendarHeader({
           chromeless
           scaleIcon={1.5}
           onPress={onPrevMonth}
+          aria-label={t("Previous month")}
         >
           <Button.Icon>
             <ChevronLeft />
@@ -227,7 +258,9 @@ export function CalendarHeader({
         <Button onPress={onYearPress} chromeless padding={0}>
           <Text
             fontSize={knobProps.sizeToken}
-            color="$placeholderColor"
+            // muted tier, not $placeholderColor: this is real text and
+            // $placeholderColor measured under the 4.5:1 AA floor
+            color={formCommonColors.muted}
             {...knobProps.body}
             {...knobProps.textWeight}
           >
@@ -253,6 +286,7 @@ export function CalendarHeader({
           chromeless
           scaleIcon={1.5}
           onPress={onNextMonth}
+          aria-label={t("Next month")}
         >
           <Button.Icon>
             <ChevronRight />
@@ -307,7 +341,7 @@ export function MonthGrid({ currentYear, selectedMonth, onSelectMonth }: MonthGr
                 color={isSelected ? "$color" : formCommonColors.text}
                 fontWeight={isSelected ? "bold" : "400"}
               >
-                {name.slice(0, 3)}
+                {t(name.slice(0, 3))}
               </Text>
             </Button>
           );
@@ -350,7 +384,14 @@ export function YearGrid({
   return (
     <View width="100%" {...knobProps.gapLg}>
       <View flexDirection="row" width="100%" alignItems="center" justifyContent="space-between">
-        <Button circular size={knobProps.sizeToken} chromeless scaleIcon={1.5} onPress={onPrevPage}>
+        <Button
+          circular
+          size={knobProps.sizeToken}
+          chromeless
+          scaleIcon={1.5}
+          onPress={onPrevPage}
+          aria-label={t("Previous years")}
+        >
           <Button.Icon>
             <ChevronLeft />
           </Button.Icon>
@@ -358,7 +399,14 @@ export function YearGrid({
         <Text fontSize={knobProps.sizeToken} {...knobProps.body} {...knobProps.textWeight}>
           {years[0]} – {years[years.length - 1]}
         </Text>
-        <Button circular size={knobProps.sizeToken} chromeless scaleIcon={1.5} onPress={onNextPage}>
+        <Button
+          circular
+          size={knobProps.sizeToken}
+          chromeless
+          scaleIcon={1.5}
+          onPress={onNextPage}
+          aria-label={t("Next years")}
+        >
           <Button.Icon>
             <ChevronRight />
           </Button.Icon>
@@ -414,49 +462,111 @@ interface DatePickerInputTriggerProps {
   onReset: () => void;
   onButtonPress: () => void;
   error?: boolean;
+  id?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
   "aria-required"?: boolean;
   "aria-invalid"?: boolean;
 }
 
 export const DatePickerInputTrigger = InputParts.Area.styleable<DatePickerInputTriggerProps>(
   (triggerProps, ref) => {
-    const { value, onButtonPress, onReset, disabled, placeholder, error, ...props } = triggerProps;
+    const {
+      value,
+      onButtonPress,
+      onReset,
+      disabled,
+      placeholder,
+      error,
+      id,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
+      ...props
+    } = triggerProps;
+    // Clear is rendered via FloatingPanel `triggerEnd` by callers that need a
+    // live clear control on native (pointerEvents="none" on the open trigger).
+    // Here we keep a compact clear for web; on native FloatingPanel owns open
+    // and a second onPress would double-toggle the sheet closed.
+    const { control } = useResolvedKnobs();
+    // Inset (-2) keeps the ring inside the Box chrome (OTP/Stepper template).
+    const areaFocusRing = ensureFocusVisibleRing({
+      ...control.focusVisibleKnobProps,
+      outlineOffset: -2,
+    });
     return (
-      <View cursor="pointer" onPress={disabled ? undefined : onButtonPress}>
-        <InputParts.Box
-          theme={error ? "red" : undefined}
-          {...(disabled ? { opacity: 0.5, pointerEvents: "none" } : undefined)}
-        >
-          <InputParts.Section>
-            <InputParts.Area
-              readOnly
-              value={value}
-              ref={ref}
-              placeholder={placeholder}
-              disabled={disabled}
-              color={formCommonColors.text}
-              {...(props as any)}
-            />
-          </InputParts.Section>
-          <InputParts.Section>
-            {value ? (
-              <InputParts.Button
-                onPress={(e) => {
-                  e.stopPropagation();
-                  onReset();
-                }}
-              >
-                <InputParts.Icon>
-                  <X />
+      // LC-40: the disabled Box below is pointerEvents-none, so the cursor
+      // affordance must ride this wrapper — the fragment's not-allowed never
+      // reaches the pointer otherwise (the wrapper kept advertising
+      // "pointer" on a disabled field).
+      <View
+        flexDirection="row"
+        alignItems="center"
+        width="100%"
+        cursor={disabled ? "not-allowed" : "pointer"}
+      >
+        <View flex={1} minWidth={0} onPress={isWeb && !disabled ? onButtonPress : undefined}>
+          <InputParts.Box
+            theme={error ? "red" : undefined}
+            // Elevation is an overlay recipe: it belongs on the open panel, never
+            // on the closed text-field trigger.
+            elevation={undefined}
+            onPress={isWeb && !disabled ? onButtonPress : undefined}
+            {...(disabled ? { opacity: 0.5, pointerEvents: "none" } : undefined)}
+          >
+            <InputParts.Section>
+              <FocusContext.Provider {...suppressBoxFocusRing}>
+                <InputParts.Area
+                  readOnly
+                  pointerEvents="none"
+                  value={value}
+                  ref={ref}
+                  id={id}
+                  placeholder={placeholder}
+                  disabled={disabled}
+                  color={formCommonColors.text}
+                  focusStyle={areaFocusRing}
+                  focusVisibleStyle={areaFocusRing}
+                  aria-label={ariaLabel}
+                  aria-labelledby={ariaLabelledBy}
+                  aria-describedby={ariaDescribedBy}
+                  onKeyPress={
+                    disabled
+                      ? undefined
+                      : (e: any) => {
+                          const key = e?.nativeEvent?.key ?? e?.key;
+                          if (key === "Enter" || key === " " || key === "Spacebar") {
+                            e?.preventDefault?.();
+                            onButtonPress();
+                          }
+                        }
+                  }
+                  {...(props as any)}
+                />
+              </FocusContext.Provider>
+            </InputParts.Section>
+            <InputParts.Section>
+              {value ? (
+                <InputParts.Button
+                  aria-label={t("Clear date")}
+                  onPress={(e) => {
+                    e.stopPropagation();
+                    onReset();
+                  }}
+                >
+                  <InputParts.Icon>
+                    <X />
+                  </InputParts.Icon>
+                </InputParts.Button>
+              ) : (
+                <InputParts.Icon adornment="trailing">
+                  <Calendar />
                 </InputParts.Icon>
-              </InputParts.Button>
-            ) : (
-              <InputParts.Icon adornment="trailing">
-                <Calendar />
-              </InputParts.Icon>
-            )}
-          </InputParts.Section>
-        </InputParts.Box>
+              )}
+            </InputParts.Section>
+          </InputParts.Box>
+        </View>
       </View>
     );
   },
@@ -470,24 +580,34 @@ interface DatePickerPopoverShellProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   trigger: ReactNode;
+  triggerEnd?: ReactNode;
   children: ReactNode;
+  disabled?: boolean;
   popoverRef?: RefObject<any>;
+  /** Native trigger announcement (name / current value / hint) — see FloatingPanel. */
+  triggerA11y?: { label?: string; value?: string; hint?: string };
 }
 
 export function DatePickerPopoverShell({
   open,
   onOpenChange,
   trigger,
+  triggerEnd,
   children,
+  disabled,
+  triggerA11y,
 }: DatePickerPopoverShellProps) {
   return (
     <FloatingPanel
       open={open}
       onOpenChange={onOpenChange}
       trigger={trigger}
+      triggerEnd={triggerEnd}
+      disabled={disabled}
       scrollable
       sizing="fill"
       fitContent
+      triggerA11y={triggerA11y}
     >
       {children}
     </FloatingPanel>
@@ -495,10 +615,10 @@ export function DatePickerPopoverShell({
 }
 
 // ---------------------------------------------------------------------------
-// ViewSwitcher — orchestrates day/month/year view modes
+// CalendarViewSwitcher — orchestrates day/month/year view modes
 // ---------------------------------------------------------------------------
 
-interface ViewSwitcherProps {
+interface CalendarViewSwitcherProps {
   calendarData: CalendarData;
   displayDate: Date;
   onSetDisplayDate: (date: Date) => void;
@@ -509,7 +629,7 @@ interface ViewSwitcherProps {
   children: ReactNode;
 }
 
-export function ViewSwitcher({
+export function CalendarViewSwitcher({
   calendarData,
   displayDate,
   onSetDisplayDate,
@@ -518,7 +638,7 @@ export function ViewSwitcher({
   yearPageStart,
   setYearPageStart,
   children,
-}: ViewSwitcherProps) {
+}: CalendarViewSwitcherProps) {
   const { knobProps } = useResolvedKnobs();
   const handleSelectMonth = useCallback(
     (month: number) => {
@@ -593,11 +713,12 @@ export function ViewSwitcher({
 // formatDateDisplay — shared date formatting
 // ---------------------------------------------------------------------------
 
+/**
+ * Picker display value in the house absolute register (LC-12 / DF-14):
+ * "Jan 15, 2024" — same voice as table date cells and Timeline, with the
+ * year always shown because an editing surface is a precision context.
+ */
 export function formatDateDisplay(date: Date | null): string {
   if (!date) return "";
-  return date.toLocaleDateString("en-US", {
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  });
+  return formatAbsoluteDate(date, { year: "always" });
 }

package/src/fields/DatePicker/utils.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { coerceToDate } from "./utils";
+
+describe("coerceToDate (forgiving paste normalization)", () => {
+  it("parses strict ISO date-only strings as local midnight", () => {
+    const d = coerceToDate("2024-01-15");
+    expect(d?.getFullYear()).toBe(2024);
+    expect(d?.getMonth()).toBe(0);
+    expect(d?.getDate()).toBe(15);
+    expect(d?.getHours()).toBe(0);
+  });
+
+  it("accepts `/`, `.`, and space separators (paste normalization)", () => {
+    for (const value of ["2024/01/15", "2024.01.15", "2024 01 15"]) {
+      const d = coerceToDate(value);
+      expect(d?.getFullYear(), value).toBe(2024);
+      expect(d?.getMonth(), value).toBe(0);
+      expect(d?.getDate(), value).toBe(15);
+    }
+  });
+
+  it("accepts 1-digit month/day and surrounding whitespace", () => {
+    const d = coerceToDate("  2024-1-5  ");
+    expect(d?.getMonth()).toBe(0);
+    expect(d?.getDate()).toBe(5);
+  });
+
+  it("rejects out-of-range months/days instead of rolling over", () => {
+    expect(coerceToDate("2024-13-01")).toBeNull();
+    expect(coerceToDate("2024-02-31")).toBeNull();
+  });
+
+  it("passes through Date instances and epoch numbers", () => {
+    const now = new Date();
+    expect(coerceToDate(now)).toBe(now);
+    expect(coerceToDate(now.getTime())?.getTime()).toBe(now.getTime());
+  });
+
+  it("returns null for empty / invalid inputs", () => {
+    expect(coerceToDate(null)).toBeNull();
+    expect(coerceToDate("")).toBeNull();
+    expect(coerceToDate("   ")).toBeNull();
+    expect(coerceToDate("not a date")).toBeNull();
+    expect(coerceToDate(new Date("invalid"))).toBeNull();
+  });
+
+  it("still parses full ISO datetime strings", () => {
+    const d = coerceToDate("2024-01-15T10:30:00.000Z");
+    expect(d?.toISOString()).toBe("2024-01-15T10:30:00.000Z");
+  });
+});