@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/DatePicker/MonthPicker.tsx

@@ -6,6 +6,7 @@ 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,
   mergeFieldHandler,
@@ -63,6 +64,11 @@ export type MonthPickerProps<
     minYear?: number;
     maxYear?: number;
     inputProps?: Omit<ComponentProps<typeof InputParts.Area>, "value" | "onChangeText" | "ref">;
+    /**
+     * Canonical change handler, consistent with the rest of the field family.
+     * Fires with the selected month or `null` when cleared.
+     */
+    onChange?: (value: MonthPickerValue | null) => void;
   };
 
 // ---------------------------------------------------------------------------
@@ -174,8 +180,9 @@ function MonthPickerBody({
           scaleIcon={1.5}
           onPress={handlePrevYear}
           disabled={minYear !== undefined && year <= minYear}
+          aria-label={t("Previous year")}
         >
-          <Button.Text>◀</Button.Text>
+          <Button.Text aria-hidden>◀</Button.Text>
         </Button>
 
         <Button onPress={() => setViewMode("year")} chromeless padding={0}>
@@ -196,8 +203,9 @@ function MonthPickerBody({
           scaleIcon={1.5}
           onPress={handleNextYear}
           disabled={maxYear !== undefined && year >= maxYear}
+          aria-label={t("Next year")}
         >
-          <Button.Text>▶</Button.Text>
+          <Button.Text aria-hidden>▶</Button.Text>
         </Button>
       </View>
 
@@ -225,7 +233,7 @@ export function MonthPicker<
     defaultValue,
     form,
     inputProps: _inputProps,
-    placeholder = "Select month",
+    placeholder = t("Select month"),
     minYear,
     maxYear,
     disabled,
@@ -241,6 +249,7 @@ export function MonthPicker<
     size,
     readOnly,
     onBlur: _onBlur,
+    onChange,
     skeleton,
     compact,
     id: idProp,
@@ -265,32 +274,43 @@ export function MonthPicker<
   }, [selectedValue, closePopover]);
 
   const handleMonthSelect = useCallback(
-    (value: MonthPickerValue) => {
+    (value: MonthPickerValue, fieldChange?: (value: any) => void) => {
       if (minYear && value.year < minYear) return;
       if (maxYear && value.year > maxYear) return;
       setSelectedValue(value);
+      fieldChange?.(value);
+      onChange?.(value);
       closePopover();
     },
-    [minYear, maxYear, closePopover],
+    [minYear, maxYear, closePopover, onChange],
   );
 
-  const handleClear = useCallback(() => {
-    setSelectedValue(null);
-    setDisplayDate(new Date());
-  }, [setDisplayDate]);
+  const handleClear = useCallback(
+    (fieldChange?: (value: any) => void) => {
+      setSelectedValue(null);
+      setDisplayDate(new Date());
+      fieldChange?.(null);
+      onChange?.(null);
+    },
+    [setDisplayDate, onChange],
+  );
 
-  const pickerContent = (
+  const pickerContent = (fieldChange?: (value: any) => void) => (
     <MonthPickerBody
       displayDate={displayDate}
       selectedValue={selectedValue}
-      onSelectMonth={handleMonthSelect}
+      onSelectMonth={(value) => handleMonthSelect(value, fieldChange)}
       onSetDisplayDate={setDisplayDate}
       minYear={minYear}
       maxYear={maxYear}
     />
   );
 
-  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>
@@ -314,12 +334,13 @@ export function MonthPicker<
         open={open}
         onOpenChange={handleOpenChange}
         popoverRef={popoverRef}
+        disabled={disabled}
         trigger={
           <DatePickerInputTrigger
             value={formatMonthDisplay(selectedValue)}
             placeholder={placeholder}
             disabled={disabled}
-            onReset={handleClear}
+            onReset={() => handleClear(fieldChange)}
             onButtonPress={() => setOpen(true)}
             error={!!hasError}
             aria-required={required || undefined}
@@ -327,7 +348,7 @@ export function MonthPicker<
           />
         }
       >
-        {pickerContent}
+        {pickerContent(fieldChange)}
       </DatePickerPopoverShell>
     );
   };
@@ -352,6 +373,9 @@ export function MonthPicker<
         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>
@@ -380,9 +404,15 @@ export function MonthPicker<
             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/MultiDatePicker.stories.tsx

@@ -0,0 +1,123 @@
+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 { MultiDatePicker } from "./MultiDatePicker";
+
+const meta: Meta<typeof MultiDatePicker> = {
+  title: "Forms/MultiDatePicker",
+  component: MultiDatePicker,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Multiple-date picker built on the DatePicker calendar. Toggle-selects up to `limit` dates.",
+      },
+    },
+  },
+  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" },
+    limit: { control: "number", description: "Max number of selectable dates" },
+    size: { control: "select", options: ["$2", "$3", "$4"], description: "Field size" },
+  },
+  args: {
+    label: "Select Dates",
+    placeholder: "Pick multiple dates",
+    limit: 5,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MultiDatePicker>;
+
+export const Baseline: Story = {
+  render: (args) => <MultiDatePicker {...args} helperText={args.helperText ?? "Up to 5 dates"} />,
+};
+
+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: "Pick at least one date", required: true },
+};
+
+export const SkeletonState: Story = {
+  args: { skeleton: true },
+};
+
+export const Compact: Story = {
+  args: { compact: true, helperText: "Compact sizing" },
+};
+
+export const LimitOne: Story = {
+  args: { limit: 1, helperText: "Only one date allowed" },
+};
+
+export const MinMax: Story = {
+  render: (args) => {
+    const now = new Date();
+    return (
+      <MultiDatePicker
+        {...args}
+        label="Mid-month only"
+        helperText="Only the 10th through the 20th of this month are selectable"
+        minDate={new Date(now.getFullYear(), now.getMonth(), 10)}
+        maxDate={new Date(now.getFullYear(), now.getMonth(), 20)}
+      />
+    );
+  },
+};
+
+export const FormBound: Story = {
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: { dates: [] as Date[] },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+      const FormSubscribe = (form as any).Subscribe;
+      return (
+        <Form form={form}>
+          <YStack gap="$4" maxWidth={480}>
+            <MultiDatePicker
+              label="Meeting Days"
+              name={"dates" as any}
+              required
+              helperText="Select up to 5 meeting days"
+            />
+            <FormSubscribe selector={(s: any) => [s.values.dates]}>
+              {([dates]: any[]) => (
+                <Text>
+                  {`form-value:${JSON.stringify(
+                    Array.isArray(dates)
+                      ? dates.map((d: any) => (d instanceof Date ? d.toDateString() : d))
+                      : dates,
+                  )}`}
+                </Text>
+              )}
+            </FormSubscribe>
+            <Button action="submit">Submit</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};

package/src/fields/DatePicker/MultiDatePicker.tsx

@@ -1,11 +1,12 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
-import { type ComponentProps, useCallback, useMemo, useRef, useState } from "react";
+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 } 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,
@@ -60,6 +62,10 @@ export type MultiDatePickerProps<
     readOnly?: boolean;
     /** Max number of dates that can be selected. Defaults to 5. */
     limit?: number;
+    /** Controlled value for standalone (no form/name) usage */
+    value?: Date[];
+    /** Standalone change callback — fires on each toggle/clear */
+    onChange?: (value: Date[]) => void;
     inputProps?: Omit<ComponentProps<typeof InputParts.Area>, "value" | "onChangeText" | "ref">;
     /** When true, renders a skeleton placeholder instead of the multi-date picker */
     skeleton?: boolean;
@@ -87,6 +93,8 @@ function MultiDayGrid({
   maxDate,
 }: MultiDayGridProps) {
   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}`,
   );
@@ -118,6 +126,7 @@ function MultiDayGrid({
                     key={day.toISOString()}
                     chromeless
                     circular
+                    {...dayCellRadius(knobProps)}
                     flex={1}
                     size={knobProps.sizeToken}
                     disabled={isDisabled}
@@ -145,7 +154,7 @@ function MultiDayGrid({
                         key="text-normal"
                         color={
                           isToday
-                            ? "$accentColor"
+                            ? accentText
                             : isCurrentMonth
                               ? formCommonColors.text
                               : formCommonColors.muted
@@ -200,7 +209,7 @@ function SingleCalendar({
   );
 
   return (
-    <ViewSwitcher
+    <CalendarViewSwitcher
       calendarData={calendarData}
       displayDate={displayDate}
       onSetDisplayDate={onSetDisplayDate}
@@ -231,7 +240,7 @@ function SingleCalendar({
           maxDate={maxDate}
         />
       </View>
-    </ViewSwitcher>
+    </CalendarViewSwitcher>
   );
 }
 
@@ -332,16 +341,22 @@ function DualCalendarBody({
 
 function formatMultiDates(dates: Date[]): string {
   if (dates.length === 0) return "";
-  if (dates.length === 1) return dates[0].toDateString();
-  return dates
-    .map((d) => d.toLocaleDateString("en-US", { month: "short", day: "numeric" }))
-    .join(", ");
+  // House absolute register (LC-12 / DF-14): single selection shows the year
+  // (editing precision), multi-selection lists compact dates with the year
+  // auto-added only when a date leaves the current year.
+  if (dates.length === 1) return formatAbsoluteDate(dates[0], { year: "always" });
+  return dates.map((d) => formatAbsoluteDate(d)).join(", ");
 }
 
 // ---------------------------------------------------------------------------
 // MultiDatePicker — main component
 // ---------------------------------------------------------------------------
 
+// A required multi-date field is empty when no dates are selected — the
+// default isEmpty only catches null/"" and would let `[]` pass validation.
+const isEmptyDates = (value: unknown) =>
+  value == null || value === "" || (Array.isArray(value) && value.length === 0);
+
 export function MultiDatePicker<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -351,9 +366,11 @@ export function MultiDatePicker<
 >(props: MultiDatePickerProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
   const {
     defaultValue,
+    value: valueProp,
+    onChange,
     form,
     inputProps: _inputProps,
-    placeholder = "Select dates",
+    placeholder = t("Select dates"),
     minDate,
     maxDate,
     disabled,
@@ -377,38 +394,71 @@ export function MultiDatePicker<
   } = useProps(props);
 
   const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
-  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const resolvedValidators = useResolvedValidators(required, validators, label, name, isEmptyDates);
 
+  const initialDates = (
+    Array.isArray(valueProp) ? valueProp : Array.isArray(defaultValue) ? defaultValue : []
+  ) as Date[];
   const [open, setOpen] = useState(false);
-  const [selectedDates, setSelectedDates] = useState<Date[]>([]);
-  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation();
+  const [selectedDates, setSelectedDates] = useState<Date[]>(initialDates);
+  // Ref mirror so rapid toggles batched into one render still accumulate.
+  const selectedDatesRef = useRef(selectedDates);
+  // Axiom 11 VALUE IS DATA: the calendar opens at the first selected date's
+  // month, not today's — seed from the value and re-seed per open.
+  const { displayDate, setDisplayDate, navigateMonth } = useDateNavigation(selectedDates[0]);
   const popoverRef = useRef<Popover>(null);
 
+  const openPicker = useCallback(() => {
+    const seed = selectedDatesRef.current[0];
+    if (seed) setDisplayDate(seed);
+    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 : [];
+    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]);
+
   const handleToggleDate = useCallback(
-    (date: Date) => {
+    (date: Date, fieldChange?: (value: any) => void) => {
       if (minDate && date < minDate) return;
       if (maxDate && date > maxDate) return;
 
-      setSelectedDates((prev) => {
-        const existing = prev.findIndex((d) => isSameDay(d, date));
-        if (existing >= 0) {
-          return prev.filter((_, i) => i !== existing);
-        }
-        if (prev.length >= limit) return prev;
-        return [...prev, date].sort((a, b) => a.getTime() - b.getTime());
-      });
+      const current = selectedDatesRef.current;
+      const existing = current.findIndex((d) => isSameDay(d, date));
+      let next: Date[];
+      if (existing >= 0) {
+        next = current.filter((_, i) => i !== existing);
+      } else {
+        if (current.length >= limit) return;
+        next = [...current, date].sort((a, b) => a.getTime() - b.getTime());
+      }
+      selectedDatesRef.current = next;
+      setSelectedDates(next);
+      fieldChange?.(next);
     },
     [minDate, maxDate, limit],
   );
 
-  const handleClear = useCallback(() => {
+  const handleClear = useCallback((fieldChange?: (value: any) => void) => {
+    selectedDatesRef.current = [];
     setSelectedDates([]);
+    fieldChange?.([]);
   }, []);
 
-  const calendarContent = (
+  const calendarContent = (fieldChange?: (value: any) => void) => (
     <DualCalendarBody
       selectedDates={selectedDates}
-      onToggleDate={handleToggleDate}
+      onToggleDate={(date) => handleToggleDate(date, fieldChange)}
       displayDate={displayDate}
       setDisplayDate={setDisplayDate}
       navigateMonth={navigateMonth}
@@ -417,7 +467,11 @@ export function MultiDatePicker<
     />
   );
 
-  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>
@@ -433,6 +487,8 @@ export function MultiDatePicker<
       );
     }
     const handleOpenChange = (isOpen: boolean) => {
+      // Re-seed the visible month from the current selection on every open.
+      if (isOpen && selectedDatesRef.current[0]) setDisplayDate(selectedDatesRef.current[0]);
       setOpen(isOpen);
       if (!isOpen) blurHandler?.();
     };
@@ -441,20 +497,21 @@ export function MultiDatePicker<
         open={open}
         onOpenChange={handleOpenChange}
         popoverRef={popoverRef}
+        disabled={disabled}
         trigger={
           <DatePickerInputTrigger
             value={formatMultiDates(selectedDates)}
             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>
     );
   };
@@ -479,8 +536,13 @@ export function MultiDatePicker<
         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>
     );
   }
@@ -507,9 +569,15 @@ export function MultiDatePicker<
             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>
         );