@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/DatePicker/DatetimePicker.tsx

@@ -1,5 +1,10 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ensureFocusVisibleRing,
+  formatAbsoluteDate,
+  useAccentOnSurface,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import { type ComponentProps, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { coerceToDate } from "./utils";
 import { Calendar, X } from "@tamagui/lucide-icons-2";
@@ -9,6 +14,7 @@ import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { FloatingPanel } from "../../FloatingPanel";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
 import { TimeColumn, TimeColumnSeparator, generateRange } from "../../shared/TimeColumn";
 import {
   getFieldError,
@@ -17,20 +23,21 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 import type { FormFieldProps } from "../../fieldLayout";
-import { Input as InputParts } from "../../InputParts";
+import { FocusContext, Input as InputParts } from "../../InputParts";
 import { Skeleton } from "../../Skeleton";
 import type { FieldComponentProps, Validator } from "../../types";
 
 import {
   CalendarHeader,
   WeekView,
+  dayCellRadius,
   isSameDay,
   toWeeks,
   useCalendarData,
   useDateAnimation,
   useDateNavigation,
   yearPageSize,
-  ViewSwitcher,
+  CalendarViewSwitcher,
 } from "./parts";
 
 // ---------------------------------------------------------------------------
@@ -39,6 +46,14 @@ import {
 
 type TimeFormat = "12h" | "24h";
 
+/**
+ * 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) => {} };
+
 export type DatetimePickerProps<
   TParentData = any,
   TName extends DeepKeys<TParentData> = any,
@@ -70,7 +85,12 @@ export type DatetimePickerProps<
     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;
   };
 
@@ -92,11 +112,9 @@ function formatDatetimeDisplay(
   showSeconds: boolean,
 ): string {
   if (!date) return "";
-  const dateStr = date.toLocaleDateString("en-US", {
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  });
+  // Date part in the house absolute register (LC-12 / DF-14); the time part
+  // keeps this picker's explicit timeFormat/showSeconds contract.
+  const dateStr = formatAbsoluteDate(date, { year: "always" });
 
   const h = date.getHours();
   const m = date.getMinutes();
@@ -131,6 +149,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}`,
   );
@@ -162,6 +182,7 @@ function DayGrid({ calendarData, selectedDate, onSelectDate, minDate, maxDate }:
                     key={day.toISOString()}
                     chromeless
                     circular
+                    {...dayCellRadius(knobProps)}
                     flex={1}
                     size={knobProps.sizeToken}
                     disabled={isDisabled}
@@ -189,7 +210,7 @@ function DayGrid({ calendarData, selectedDate, onSelectDate, minDate, maxDate }:
                         key="text-normal"
                         color={
                           isToday
-                            ? "$accentColor"
+                            ? accentText
                             : isCurrentMonth
                               ? formCommonColors.text
                               : formCommonColors.muted
@@ -245,7 +266,7 @@ function TimeSection({
     <>
       <TimeColumnSeparator knobProps={knobProps} />
       <TimeColumn
-        label="Sec"
+        label={t("Sec")}
         values={secondValues}
         selected={s}
         onChange={(newS) => onTimeChange(makeNewDate(h, m, newS))}
@@ -258,7 +279,7 @@ function TimeSection({
     return (
       <View flexDirection="row" gap="$2" alignItems="flex-start" justifyContent="center">
         <TimeColumn
-          label="Hour"
+          label={t("Hour")}
           values={hours24}
           selected={h}
           onChange={(newH) => onTimeChange(makeNewDate(newH, m, s))}
@@ -266,7 +287,7 @@ function TimeSection({
         />
         <TimeColumnSeparator knobProps={knobProps} />
         <TimeColumn
-          label="Min"
+          label={t("Min")}
           values={minuteValues}
           selected={m}
           onChange={(newM) => onTimeChange(makeNewDate(h, newM, s))}
@@ -300,7 +321,7 @@ function TimeSection({
   return (
     <View flexDirection="row" gap="$2" alignItems="flex-start" justifyContent="center">
       <TimeColumn
-        label="Hour"
+        label={t("Hour")}
         values={hours12}
         selected={display12H}
         onChange={handleHourChange}
@@ -308,7 +329,7 @@ function TimeSection({
       />
       <TimeColumnSeparator knobProps={knobProps} />
       <TimeColumn
-        label="Min"
+        label={t("Min")}
         values={minuteValues}
         selected={m}
         onChange={(newM) => onTimeChange(makeNewDate(h, newM, s))}
@@ -437,7 +458,7 @@ function DatetimePickerBody({
           theme={activeTab === "date" ? ("accent" as any) : undefined}
           onPress={() => setActiveTab("date")}
         >
-          <Button.Text>Date</Button.Text>
+          <Button.Text>{t("Date")}</Button.Text>
         </Button>
         <Button
           flex={1}
@@ -446,12 +467,12 @@ function DatetimePickerBody({
           onPress={() => setActiveTab("time")}
           disabled={!selectedDatetime}
         >
-          <Button.Text>Time</Button.Text>
+          <Button.Text>{t("Time")}</Button.Text>
         </Button>
       </View>
 
       {activeTab === "date" ? (
-        <ViewSwitcher
+        <CalendarViewSwitcher
           calendarData={calendarData}
           displayDate={displayDate}
           onSetDisplayDate={onSetDisplayDate}
@@ -486,7 +507,7 @@ function DatetimePickerBody({
               maxDate={maxDate}
             />
           </View>
-        </ViewSwitcher>
+        </CalendarViewSwitcher>
       ) : (
         selectedDatetime && (
           <View padding="$2" width="100%">
@@ -518,10 +539,11 @@ export function DatetimePicker<
   const {
     defaultValue,
     value: controlledValue,
+    onChange,
     onValueChange,
     form,
     inputProps,
-    placeholder = "Select date and time",
+    placeholder = t("Select date and time"),
     minDate,
     maxDate,
     disabled,
@@ -546,8 +568,13 @@ export function DatetimePicker<
     ..._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 [open, setOpen] = useState(false);
   const [selectedDatetime, setSelectedDatetime] = useState<Date | null>(() =>
@@ -557,8 +584,20 @@ export function DatetimePicker<
     if (controlledValue === undefined) return;
     setSelectedDatetime(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 from the current value and re-seed per open.
+  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation(
+    selectedDatetime ?? undefined,
+  );
   const popoverRef = useRef<Popover>(null);
+  const selectedDatetimeRef = useRef(selectedDatetime);
+  selectedDatetimeRef.current = selectedDatetime;
+
+  const openPicker = useCallback(() => {
+    const seed = selectedDatetimeRef.current;
+    if (seed) setDisplayDate(seed);
+    setOpen(true);
+  }, [setDisplayDate]);
 
   const closePopover = useCallback(() => {
     setOpen(false);
@@ -566,32 +605,40 @@ export function DatetimePicker<
   }, []);
 
   const handleDatetimeSelect = useCallback(
-    (date: Date) => {
+    (date: Date, fieldChange?: (value: any) => void) => {
       if (minDate && date < minDate) return;
       if (maxDate && date > maxDate) return;
       setSelectedDatetime(date);
       setDisplayDate(date);
+      fieldChange?.(date);
+      // Canonical `onChange` and the alias `onValueChange` both fire (single emit).
+      onChange?.(date);
       onValueChange?.(date);
     },
-    [minDate, maxDate, setDisplayDate, onValueChange],
+    [minDate, maxDate, setDisplayDate, onChange, onValueChange],
   );
 
-  const handleClearDatetime = useCallback(() => {
-    setSelectedDatetime(null);
-    setDisplayDate(new Date());
-    onValueChange?.(null);
-  }, [setDisplayDate, onValueChange]);
+  const handleClearDatetime = useCallback(
+    (fieldChange?: (value: any) => void) => {
+      setSelectedDatetime(null);
+      setDisplayDate(new Date());
+      fieldChange?.(null);
+      onChange?.(null);
+      onValueChange?.(null);
+    },
+    [setDisplayDate, onChange, onValueChange],
+  );
 
   const displayValue = useMemo(
     () => formatDatetimeDisplay(selectedDatetime, timeFormat, showSeconds),
     [selectedDatetime, timeFormat, showSeconds],
   );
 
-  const pickerContent = (
+  const pickerContent = (fieldChange?: (value: any) => void) => (
     <DatetimePickerBody
       displayDate={displayDate}
       selectedDatetime={selectedDatetime}
-      onSelectDatetime={handleDatetimeSelect}
+      onSelectDatetime={(date) => handleDatetimeSelect(date, fieldChange)}
       onNavigateMonth={navigateMonth}
       onSetDisplayDate={setDisplayDate}
       minDate={minDate}
@@ -602,30 +649,49 @@ export function DatetimePicker<
     />
   );
 
-  const renderTrigger = (value: string, hasError?: boolean) => (
-    <View cursor="pointer" onPress={disabled ? undefined : () => setOpen(true)}>
+  const renderTrigger = (value: string, hasError?: boolean, fieldChange?: (value: any) => void) => (
+    <View cursor="pointer" onPress={disabled ? undefined : openPicker}>
       <InputParts.Box
         theme={hasError ? "red" : undefined}
+        // Elevation is an overlay recipe: it belongs on the open panel, never
+        // on the closed text-field trigger.
+        elevation={undefined}
         {...(disabled ? { opacity: 0.5, pointerEvents: "none" } : undefined)}
       >
         <InputParts.Section>
-          <InputParts.Area
-            readOnly
-            value={value}
-            placeholder={placeholder}
-            disabled={disabled}
-            color={formCommonColors.text}
-            aria-required={required || undefined}
-            aria-invalid={hasError || undefined}
-            {...(inputProps as any)}
-          />
+          <FocusContext.Provider {...suppressBoxFocusRing}>
+            <InputParts.Area
+              readOnly
+              value={value}
+              placeholder={placeholder}
+              disabled={disabled}
+              color={formCommonColors.text}
+              focusStyle={areaFocusRing}
+              focusVisibleStyle={areaFocusRing}
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+              onKeyPress={
+                disabled
+                  ? undefined
+                  : (e: any) => {
+                      const key = e?.nativeEvent?.key ?? e?.key;
+                      if (key === "Enter" || key === " " || key === "Spacebar") {
+                        e?.preventDefault?.();
+                        openPicker();
+                      }
+                    }
+              }
+              {...(inputProps as any)}
+            />
+          </FocusContext.Provider>
         </InputParts.Section>
         <InputParts.Section>
           {value ? (
             <InputParts.Button
+              aria-label={t("Clear date")}
               onPress={(e) => {
                 e.stopPropagation();
-                handleClearDatetime();
+                handleClearDatetime(fieldChange);
               }}
             >
               <InputParts.Icon>
@@ -642,22 +708,32 @@ export function DatetimePicker<
     </View>
   );
 
-  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>
-          <InputParts.Area
-            value={displayValue}
-            readOnly
-            aria-readonly="true"
-            aria-required={required || undefined}
-            aria-invalid={hasError || undefined}
-            placeholder={placeholder}
-          />
+          <FocusContext.Provider {...suppressBoxFocusRing}>
+            <InputParts.Area
+              value={displayValue}
+              readOnly
+              aria-readonly="true"
+              aria-required={required || undefined}
+              aria-invalid={hasError || undefined}
+              focusStyle={areaFocusRing}
+              focusVisibleStyle={areaFocusRing}
+              placeholder={placeholder}
+            />
+          </FocusContext.Provider>
         </InputParts.Box>
       );
     }
     const handleOpenChange = (isOpen: boolean) => {
+      // Re-seed the visible month from the current value on every open.
+      if (isOpen && selectedDatetimeRef.current) setDisplayDate(selectedDatetimeRef.current);
       setOpen(isOpen);
       if (!isOpen) blurHandler?.();
     };
@@ -665,12 +741,13 @@ export function DatetimePicker<
       <FloatingPanel
         open={open}
         onOpenChange={handleOpenChange}
-        trigger={renderTrigger(displayValue, hasError)}
+        trigger={renderTrigger(displayValue, hasError, fieldChange)}
+        disabled={disabled}
         scrollable
         sizing="fill"
         fitContent
       >
-        {pickerContent}
+        {pickerContent(fieldChange)}
       </FloatingPanel>
     );
   };
@@ -695,6 +772,9 @@ export function DatetimePicker<
         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>
       </FieldLayout>
@@ -723,9 +803,15 @@ export function DatetimePicker<
             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/MonthPicker.spec.tsx

@@ -1,8 +1,20 @@
-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 { MonthPicker } from "./MonthPicker";
 
+const MONTH_ABBREVIATIONS = /^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$/;
+
+function getMonthButtons(root: ParentNode): HTMLButtonElement[] {
+  const allButtons = Array.from(
+    root.querySelectorAll('button, [role="button"]'),
+  ) as HTMLButtonElement[];
+  return allButtons.filter((btn) => MONTH_ABBREVIATIONS.test(btn.textContent?.trim() ?? ""));
+}
+
 describe("MonthPicker", () => {
   describe("without form context", () => {
     it("renders with label", () => {
@@ -42,6 +54,36 @@ describe("MonthPicker", () => {
       const input = result.container.querySelector("input");
       expect(input).not.toBeNull();
     });
+
+    it("fires canonical onChange once when a month is picked", async () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <MonthPicker label="Month" name="month" onChange={onChange} />,
+      );
+
+      const trigger = result.container.querySelector("input,button,[role='button']");
+      expect(trigger).toBeTruthy();
+      await act(async () => {
+        if (trigger) fireEvent.click(trigger);
+      });
+
+      await waitFor(() => {
+        expect(getMonthButtons(document.body).length).toBeGreaterThan(0);
+      });
+
+      const monthButtons = getMonthButtons(document.body);
+      await act(async () => {
+        fireEvent.click(monthButtons[0]);
+      });
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          month: expect.any(Number),
+          year: expect.any(Number),
+        }),
+      );
+    });
   });
 
   describe("with form context", () => {
@@ -53,5 +95,51 @@ describe("MonthPicker", () => {
       );
       expect(result.findTextElement("Month")).toBeDefined();
     });
+
+    it("commits the picked month into form state via field.handleChange", async () => {
+      const onSubmit = vi.fn();
+      const FormExample = () => {
+        const form = useForm({
+          defaultValues: { month: null as { month: number; year: number } | null },
+          onSubmit: async ({ value }) => {
+            onSubmit(value);
+          },
+        });
+        return (
+          <Form form={form}>
+            <MonthPicker name="month" label="Month" />
+            <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(getMonthButtons(document.body).length).toBeGreaterThan(0);
+      });
+      const monthButtons = getMonthButtons(document.body);
+      await act(async () => {
+        fireEvent.click(monthButtons[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].month).toEqual(
+        expect.objectContaining({
+          month: expect.any(Number),
+          year: expect.any(Number),
+        }),
+      );
+    });
   });
 });

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

@@ -0,0 +1,114 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useForm } from "@tanstack/react-form";
+import { Text, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { MonthPicker } from "./MonthPicker";
+
+const meta: Meta<typeof MonthPicker> = {
+  title: "Forms/MonthPicker",
+  component: MonthPicker,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Month + year picker with a 4x3 month grid, paginated year grid, and optional min/max year clamping.",
+      },
+    },
+  },
+  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" },
+    minYear: { control: "number", description: "Minimum selectable year" },
+    maxYear: { control: "number", description: "Maximum selectable year" },
+    size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
+  },
+  args: {
+    label: "Select Month",
+    placeholder: "Pick a month",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MonthPicker>;
+
+export const Baseline: Story = {
+  render: (args) => (
+    <MonthPicker {...args} helperText={args.helperText ?? "Choose a month and year"} />
+  ),
+};
+
+export const YearRange: Story = {
+  args: {
+    minYear: 2020,
+    maxYear: 2030,
+    helperText: "Clamped between 2020 and 2030",
+  },
+};
+
+export const ReversedYearRange: Story = {
+  args: {
+    minYear: 2030,
+    maxYear: 2020,
+    helperText: "minYear > maxYear (reversed range edge case)",
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, placeholder: "Cannot select" },
+};
+
+export const ReadOnly: Story = {
+  args: { readOnly: true, helperText: "Read-only display" },
+};
+
+export const WithError: Story = {
+  args: { error: "A month is required", required: true },
+};
+
+export const SkeletonState: Story = {
+  args: { skeleton: true },
+};
+
+export const Compact: Story = {
+  args: { compact: true, helperText: "Compact sizing" },
+};
+
+export const FormBound: Story = {
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: { period: null as { year: number; month: number } | null },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      const FormSubscribe = (form as any).Subscribe;
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={480}>
+            <MonthPicker
+              label="Fiscal Period"
+              name={"period" as any}
+              required
+              helperText="Pick a fiscal period"
+            />
+            <FormSubscribe selector={(s: any) => [s.values.period]}>
+              {([period]: any[]) => <Text>{`form-value:${JSON.stringify(period)}`}</Text>}
+            </FormSubscribe>
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};