@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/DatePicker/DateRangePicker.tsx

@@ -1,11 +1,12 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { formatAbsoluteDate, useAccentOnSurface, useResolvedKnobs } from "@multiplatform.one/theme";
 import { type ComponentProps, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { AnimatePresence, type Popover, Separator, View, useMedia, useProps } from "tamagui";
 
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
 import {
   getFieldError,
   mergeFieldHandler,
@@ -21,8 +22,9 @@ import {
   CalendarHeader,
   DatePickerInputTrigger,
   DatePickerPopoverShell,
-  ViewSwitcher,
+  CalendarViewSwitcher,
   WeekView,
+  dayCellRadius,
   isSameDay,
   toWeeks,
   useCalendarData,
@@ -63,6 +65,10 @@ export type DateRangePickerProps<
     maxDate?: Date;
     disabled?: boolean;
     readOnly?: boolean;
+    /** Controlled value for standalone (no form/name) usage */
+    value?: DateRange | null;
+    /** Standalone change callback — fires when a complete range is set/cleared */
+    onChange?: (value: DateRange | null) => void;
     inputProps?: Omit<ComponentProps<typeof InputParts.Area>, "value" | "onChangeText" | "ref">;
     /** When true, renders a skeleton placeholder instead of the date range picker */
     skeleton?: boolean;
@@ -107,6 +113,8 @@ function RangeDayGrid({
   maxDate,
 }: RangeDayGridProps) {
   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}`,
   );
@@ -170,16 +178,17 @@ function RangeDayGrid({
                           exitStyle={{ opacity: 0 }}
                           opacity={1}
                           {...(rangeStatus === "range-start"
-                            ? { left: "50%", right: 0, width: "50%" }
+                            ? { insetInlineStart: "50%", insetInlineEnd: 0, width: "50%" }
                             : rangeStatus === "range-end"
-                              ? { left: 0, right: "50%", width: "50%" }
-                              : { left: 0, right: 0, width: "100%" })}
+                              ? { insetInlineStart: 0, insetInlineEnd: "50%", width: "50%" }
+                              : { insetInlineStart: 0, insetInlineEnd: 0, width: "100%" })}
                         />
                       )}
 
                       <Button
                         chromeless
                         circular
+                        {...dayCellRadius(knobProps)}
                         size={knobProps.sizeToken}
                         disabled={isDisabled}
                         onPress={() => !isDisabled && onSelectDate(day)}
@@ -205,7 +214,7 @@ function RangeDayGrid({
                         ) : (
                           <Button.Text
                             key="text-normal"
-                            color={isToday ? "$accentColor" : formCommonColors.text}
+                            color={isToday ? accentText : formCommonColors.text}
                           >
                             {day.getDate()}
                           </Button.Text>
@@ -260,7 +269,7 @@ function SingleCalendar({
   );
 
   return (
-    <ViewSwitcher
+    <CalendarViewSwitcher
       calendarData={calendarData}
       displayDate={displayDate}
       onSetDisplayDate={onSetDisplayDate}
@@ -292,7 +301,7 @@ function SingleCalendar({
           maxDate={maxDate}
         />
       </View>
-    </ViewSwitcher>
+    </CalendarViewSwitcher>
   );
 }
 
@@ -396,7 +405,9 @@ function DualCalendarBody({
 
 function formatRange(start: Date | null, end: Date | null): string {
   if (!start) return "";
-  const formatDate = (date: Date) => date.toDateString();
+  // House absolute register (LC-12 / DF-14) — never the toDateString()
+  // system voice ("Sat Aug 09 2026").
+  const formatDate = (date: Date) => formatAbsoluteDate(date, { year: "always" });
   if (!end) return `${formatDate(start)} – end date`;
   return `${formatDate(start)} – ${formatDate(end)}`;
 }
@@ -414,9 +425,11 @@ export function DateRangePicker<
 >(props: DateRangePickerProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
   const {
     defaultValue,
+    value: valueProp,
+    onChange,
     form,
     inputProps: _inputProps,
-    placeholder = "Start date – End date",
+    placeholder = t("Start date – End date"),
     minDate,
     maxDate,
     disabled,
@@ -441,11 +454,41 @@ export function DateRangePicker<
   const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
 
+  const initialRange = (valueProp ?? defaultValue) as DateRange | null | undefined;
   const [open, setOpen] = useState(false);
-  const [rangeStart, setRangeStart] = useState<Date | null>(null);
-  const [rangeEnd, setRangeEnd] = useState<Date | null>(null);
-  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation();
+  const [rangeStart, setRangeStart] = useState<Date | null>(() => initialRange?.start ?? null);
+  const [rangeEnd, setRangeEnd] = useState<Date | null>(() => initialRange?.end ?? null);
+  // Axiom 11 VALUE IS DATA: the calendar opens at the current range's start
+  // month, not today's — seed from the value and re-seed per open.
+  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation(rangeStart ?? undefined);
   const popoverRef = useRef<Popover>(null);
+  const rangeStartRef = useRef(rangeStart);
+  rangeStartRef.current = rangeStart;
+
+  const openPicker = useCallback(() => {
+    const seed = rangeStartRef.current;
+    if (seed) setDisplayDate(seed);
+    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).
+  const pickingRangeRef = useRef(false);
+  useEffect(() => {
+    if (valueProp === undefined) return;
+    if (pickingRangeRef.current && valueProp == null) return;
+    pickingRangeRef.current = false;
+    const nextStart = valueProp?.start ?? null;
+    const nextEnd = valueProp?.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]);
 
   const closePopover = useCallback(() => {
     setOpen(false);
@@ -457,41 +500,52 @@ export function DateRangePicker<
   }, [rangeStart, rangeEnd, closePopover]);
 
   const handleSelectDate = useCallback(
-    (date: Date) => {
+    (date: Date, fieldChange?: (value: any) => void) => {
       if (minDate && date < minDate) return;
       if (maxDate && date > maxDate) return;
 
       if (!rangeStart || (rangeStart && rangeEnd)) {
+        // Begin a new range locally only — do not commit null to a controlled
+        // parent (that would sync-wipe rangeStart before the end date is picked).
+        pickingRangeRef.current = true;
         setRangeStart(date);
         setRangeEnd(null);
         return;
       }
 
       if (date < rangeStart) {
+        pickingRangeRef.current = false;
         setRangeEnd(rangeStart);
         setRangeStart(date);
+        fieldChange?.({ start: date, end: rangeStart });
         closePopover();
       } else if (isSameDay(date, rangeStart)) {
+        pickingRangeRef.current = false;
         setRangeStart(null);
         setRangeEnd(null);
+        fieldChange?.(null);
       } else {
+        pickingRangeRef.current = false;
         setRangeEnd(date);
+        fieldChange?.({ start: rangeStart, end: date });
         closePopover();
       }
     },
     [rangeStart, rangeEnd, minDate, maxDate, closePopover],
   );
 
-  const handleClear = useCallback(() => {
+  const handleClear = useCallback((fieldChange?: (value: any) => void) => {
+    pickingRangeRef.current = false;
     setRangeStart(null);
     setRangeEnd(null);
+    fieldChange?.(null);
   }, []);
 
-  const calendarContent = (
+  const calendarContent = (fieldChange?: (value: any) => void) => (
     <DualCalendarBody
       rangeStart={rangeStart}
       rangeEnd={rangeEnd}
-      onSelectDate={handleSelectDate}
+      onSelectDate={(date) => handleSelectDate(date, fieldChange)}
       displayDate={displayDate}
       setDisplayDate={setDisplayDate}
       navigateMonth={navigateMonth}
@@ -500,7 +554,11 @@ export function DateRangePicker<
     />
   );
 
-  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>
@@ -516,6 +574,8 @@ export function DateRangePicker<
       );
     }
     const handleOpenChange = (isOpen: boolean) => {
+      // Re-seed the visible month from the current range on every open.
+      if (isOpen && rangeStartRef.current) setDisplayDate(rangeStartRef.current);
       setOpen(isOpen);
       if (!isOpen) blurHandler?.();
     };
@@ -524,20 +584,21 @@ export function DateRangePicker<
         open={open}
         onOpenChange={handleOpenChange}
         popoverRef={popoverRef}
+        disabled={disabled}
         trigger={
           <DatePickerInputTrigger
             value={formatRange(rangeStart, rangeEnd)}
             placeholder={placeholder}
             disabled={disabled}
-            onReset={handleClear}
-            onButtonPress={() => setOpen(true)}
+            onReset={() => handleClear(fieldChange)}
+            onButtonPress={openPicker}
             error={!!hasError}
             aria-required={required || undefined}
             aria-invalid={hasError || undefined}
           />
         }
       >
-        {calendarContent}
+        {calendarContent(fieldChange)}
       </DatePickerPopoverShell>
     );
   };
@@ -562,8 +623,13 @@ export function DateRangePicker<
         required={required}
         size={size}
         knobProps={knobProps}
+        // 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>
+        <InputParts size={size || knobProps.sizeToken}>
+          {renderPopover(!!errorProp, undefined, onChange)}
+        </InputParts>
       </FieldLayout>
     );
   }
@@ -590,9 +656,15 @@ export function DateRangePicker<
             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))}
+              {renderPopover(
+                !!resolvedError,
+                mergeFieldHandler(field, "handleBlur", _onBlur),
+                mergeFieldHandler(field, "handleChange"),
+              )}
             </InputParts>
           </FieldLayout>
         );

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

@@ -1,8 +1,26 @@
-import { describe, expect, it } from "vitest";
+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 { Button } from "../../Button";
 import { Form } from "../../Form";
 import { DatetimePicker } from "./DatetimePicker";
 
+function getEnabledDayButtons(root: ParentNode): HTMLButtonElement[] {
+  const allButtons = Array.from(
+    root.querySelectorAll('button, [role="button"]'),
+  ) as HTMLButtonElement[];
+  return allButtons.filter((btn) => {
+    const text = btn.textContent?.trim() ?? "";
+    const isDay = /^\d{1,2}$/.test(text);
+    const disabled =
+      btn.hasAttribute("disabled") ||
+      btn.getAttribute("aria-disabled") === "true" ||
+      btn.hasAttribute("data-disabled");
+    return isDay && !disabled;
+  });
+}
+
 describe("DatetimePicker", () => {
   describe("without form context", () => {
     it("renders with label", () => {
@@ -42,6 +60,39 @@ describe("DatetimePicker", () => {
       const input = result.container.querySelector("input");
       expect(input).not.toBeNull();
     });
+
+    it("fires canonical onChange and the deprecated onValueChange alias once when a day is picked", async () => {
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      const result = renderWithProviders(
+        <DatetimePicker
+          label="Appointment"
+          name="appt"
+          onChange={onChange}
+          onValueChange={onValueChange}
+        />,
+      );
+
+      const trigger = result.container.querySelector("input,button,[role='button']");
+      expect(trigger).toBeTruthy();
+      await act(async () => {
+        if (trigger) fireEvent.click(trigger);
+      });
+
+      await waitFor(() => {
+        expect(getEnabledDayButtons(document.body).length).toBeGreaterThan(0);
+      });
+
+      const dayButtons = getEnabledDayButtons(document.body);
+      await act(async () => {
+        fireEvent.click(dayButtons[0]);
+      });
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0]).toBeInstanceOf(Date);
+      expect(onChange.mock.calls[0][0]).toEqual(onValueChange.mock.calls[0][0]);
+    });
   });
 
   describe("with form context", () => {
@@ -53,5 +104,46 @@ describe("DatetimePicker", () => {
       );
       expect(result.findTextElement("Appointment")).toBeDefined();
     });
+
+    it("commits the picked datetime into form state via field.handleChange", async () => {
+      const onSubmit = vi.fn();
+      const FormExample = () => {
+        const form = useForm({
+          defaultValues: { appt: null as Date | null },
+          onSubmit: async ({ value }) => {
+            onSubmit(value);
+          },
+        });
+        return (
+          <Form form={form}>
+            <DatetimePicker name="appt" label="Appointment" />
+            <Button action="submit">Submit</Button>
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<FormExample />);
+
+      const trigger = result.container.querySelector("input,button,[role='button']");
+      expect(trigger).toBeTruthy();
+      await act(async () => {
+        if (trigger) fireEvent.click(trigger);
+      });
+      await waitFor(() => {
+        expect(getEnabledDayButtons(document.body).length).toBeGreaterThan(0);
+      });
+      const dayButtons = getEnabledDayButtons(document.body);
+      await act(async () => {
+        fireEvent.click(dayButtons[0]);
+      });
+
+      const submitButton = result.getSubmitButton();
+      await act(async () => {
+        if (submitButton) fireEvent.click(submitButton);
+      });
+      await waitFor(() => {
+        expect(onSubmit).toHaveBeenCalledTimes(1);
+      });
+      expect(onSubmit.mock.calls[0][0].appt).toBeInstanceOf(Date);
+    });
   });
 });

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

@@ -0,0 +1,148 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { useState } from "react";
+import { Text, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { DatetimePicker } from "./DatetimePicker";
+
+const meta: Meta<typeof DatetimePicker> = {
+  title: "Forms/DatetimePicker",
+  component: DatetimePicker,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Combined date + time picker with Date/Time tabs, 12h/24h formats, minute stepping, optional seconds, and a standalone controlled value API.",
+      },
+    },
+  },
+  argTypes: {
+    label: { control: "text", description: "Field label" },
+    placeholder: { control: "text", description: "Placeholder text" },
+    helperText: { control: "text", description: "Helper text below the field" },
+    error: { control: "text", description: "Error message" },
+    required: { control: "boolean", description: "Mark field as required" },
+    disabled: { control: "boolean", description: "Disable the picker" },
+    readOnly: { control: "boolean", description: "Read-only display" },
+    skeleton: { control: "boolean", description: "Render a skeleton placeholder" },
+    compact: { control: "boolean", description: "Use compact sizing" },
+    timeFormat: { control: "select", options: ["12h", "24h"], description: "Clock format" },
+    minuteStep: { control: "number", description: "Minute increment" },
+    showSeconds: { control: "boolean", description: "Show a seconds column" },
+    value: { control: "text", description: "Controlled value (Date or ISO string)" },
+    size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
+  },
+  args: {
+    label: "Select Date & Time",
+    placeholder: "Pick date and time",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DatetimePicker>;
+
+export const Baseline: Story = {
+  render: (args) => (
+    <DatetimePicker {...args} helperText={args.helperText ?? "Choose a date and time"} />
+  ),
+};
+
+export const TwentyFourHour: Story = {
+  args: { timeFormat: "24h", helperText: "24-hour format" },
+};
+
+export const WithSeconds: Story = {
+  args: { showSeconds: true, helperText: "With seconds" },
+};
+
+export const MinuteStepSeven: Story = {
+  args: { minuteStep: 7, helperText: "Minute step 7 (does not divide 60)" },
+};
+
+export const JanThirtyOne: Story = {
+  args: {
+    defaultValue: "2026-01-31T12:00:00" as any,
+    helperText: "Starts on Jan 31 — use the next-month arrow to test month-boundary arithmetic",
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, placeholder: "Cannot select" },
+};
+
+export const ReadOnly: Story = {
+  args: { readOnly: true, defaultValue: "2026-01-15T09:30:00" as any },
+};
+
+export const WithError: Story = {
+  args: { error: "A date and time is required", required: true },
+};
+
+export const SkeletonState: Story = {
+  args: { skeleton: true },
+};
+
+export const Compact: Story = {
+  args: { compact: true, helperText: "Compact sizing" },
+};
+
+export const ControlledRejection: Story = {
+  render: () => {
+    const Example = () => {
+      const [pinned] = useState(() => new Date(2026, 5, 15, 10, 30, 0));
+      const [attempts, setAttempts] = useState(0);
+      return (
+        <YStack gap="$4" maxWidth={480}>
+          <DatetimePicker
+            label="Pinned Value"
+            value={pinned}
+            onValueChange={(v) => {
+              setAttempts((a) => a + 1);
+              action("onValueChange")(v);
+            }}
+            helperText="Parent ignores onValueChange — the value must not drift"
+          />
+          <Text>{`attempts:${attempts}`}</Text>
+        </YStack>
+      );
+    };
+    return <Example />;
+  },
+};
+
+export const FormBound: Story = {
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: { when: null as Date | null },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      const FormSubscribe = (form as any).Subscribe;
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={480}>
+            <DatetimePicker
+              label="Appointment"
+              name={"when" as any}
+              required
+              helperText="Pick appointment time"
+            />
+            <FormSubscribe selector={(s: any) => [s.values.when]}>
+              {([when]: any[]) => (
+                <Text>
+                  {`form-value:${when instanceof Date ? when.toISOString() : JSON.stringify(when)}`}
+                </Text>
+              )}
+            </FormSubscribe>
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};