@proyecto-viviana/solid-stately 0.4.0 → 0.5.0

package/src/calendar/createDateFieldState.ts

@@ -2,34 +2,43 @@
  * DateFieldState for Solid-Stately
  *
  * Provides state management for date field components with segment-based editing.
- * Based on @react-stately/datepicker useDateFieldState
+ * Faithful port of @react-stately/datepicker useDateFieldState.
  *
  * Editing is modeled with an {@link IncompleteDate} display value so that invalid
  * intermediate dates (e.g. February 31st, produced by editing the day before the
  * month) are held as-typed while the field is focused and only constrained on blur
  * via `confirmPlaceholder`, matching upstream behavior. Out-of-range values are
  * never snapped to `minValue`/`maxValue`; they are kept and reported as invalid.
+ *
+ * The upstream "derived state during render" resync (which re-mints the display
+ * value when the committed value / calendar / hour cycle changes) is ported to a
+ * Solid `createComputed` so it runs synchronously before render effects — mirroring
+ * React's render-phase setState rather than a post-render `createEffect`.
  */
 
-import { createSignal, createMemo, createEffect, type Accessor } from "solid-js";
+import { createSignal, createMemo, createComputed, untrack, type Accessor } from "solid-js";
 import {
-  type AnyDateTime,
   type Calendar,
   type CalendarDateTime,
+  type CalendarIdentifier,
   type DateValue,
   GregorianCalendar,
-  today,
-  getLocalTimeZone,
   DateFormatter,
-  toCalendarDate as intlToCalendarDate,
+  Time,
+  now,
+  getLocalTimeZone,
+  toCalendar,
+  toCalendarDate,
   toCalendarDateTime,
+  isEqualCalendar,
+  createCalendar as intlCreateCalendar,
 } from "@internationalized/date";
 import { access, type MaybeAccessor } from "../utils";
 import type { ValidationState } from "./createCalendarState";
 import { IncompleteDate } from "./IncompleteDate";
+import { formatDateFieldError, getPlaceholder, type DateFieldErrorKey } from "./intl";
 import {
   createFormValidationState,
-  DEFAULT_VALIDATION_RESULT,
   VALID_VALIDITY_STATE,
   type ValidationBehavior,
   type ValidationFunction,
@@ -49,6 +58,9 @@ export type DateSegmentType =
   | "timeZoneName"
   | "literal";
 
+type Granularity = "year" | "month" | "day" | "hour" | "minute" | "second";
+type FieldGranularity = "day" | "hour" | "minute" | "second";
+
 export interface DateSegment {
   /** The type of segment. */
   type: DateSegmentType;
@@ -90,7 +102,9 @@ export interface DateFieldStateProps<T extends DateValue = DateValue> {
   /** The locale to use for formatting. */
   locale?: string;
   /** The granularity of the date/time (day, hour, minute, second). */
-  granularity?: "day" | "hour" | "minute" | "second";
+  granularity?: FieldGranularity;
+  /** The maximum granularity (largest editable unit). Defaults to `year`. */
+  maxGranularity?: "year" | "month" | "day" | "hour" | "minute";
   /** Whether to show the hour in 12 or 24 hour format. */
   hourCycle?: 12 | 24;
   /** Whether to hide the time zone. */
@@ -111,29 +125,43 @@ export interface DateFieldStateProps<T extends DateValue = DateValue> {
   errorMessage?: string;
   /** Whether dates outside the min/max range are allowed. */
   allowsNonContiguousRanges?: boolean;
-  /** Whether to create a date or datetime. */
-  createCalendar?: (name: string) => unknown;
+  /** Resolves a calendar system by its Unicode identifier. */
+  createCalendar?: (name: CalendarIdentifier) => Calendar;
   /** Whether a date is unavailable. */
   isDateUnavailable?: (date: DateValue) => boolean;
 }
 
 export interface DateFieldState<T extends DateValue = DateValue> {
-  /** The current value. */
-  value: Accessor<T | null>;
-  /** The date value (may be partial during editing). */
-  dateValue: Accessor<DateValue | null>;
+  /** The current value, converted to the display calendar. */
+  value: Accessor<DateValue | null>;
+  /** The current value as a native JavaScript Date (may be partial during editing). */
+  dateValue: Accessor<Date>;
+  /** The display calendar system. */
+  readonly calendar: Calendar;
   /** Sets the date value. */
   setValue: (value: T | null) => void;
   /** The segments that make up the date. */
   segments: Accessor<DateSegment[]>;
-  /** The format string. */
+  /** The formatter used to render the field. */
+  readonly dateFormatter: DateFormatter;
+  /** Formats the current value with the given field options. */
   formatValue: (fieldOptions?: Intl.DateTimeFormatOptions) => string;
+  /** Returns a formatter with the field's resolved options merged with the given ones. */
+  getDateFormatter: (locale: string, formatOptions: FormatterOptions) => DateFormatter;
   /** Sets a segment value. */
   setSegment: (type: DateSegmentType, value: number) => void;
-  /** Increments a segment. */
-  incrementSegment: (type: DateSegmentType) => void;
-  /** Decrements a segment. */
-  decrementSegment: (type: DateSegmentType) => void;
+  /** Increments a segment by one. */
+  increment: (type: DateSegmentType) => void;
+  /** Decrements a segment by one. */
+  decrement: (type: DateSegmentType) => void;
+  /** Increments a segment by a larger page step. */
+  incrementPage: (type: DateSegmentType) => void;
+  /** Decrements a segment by a larger page step. */
+  decrementPage: (type: DateSegmentType) => void;
+  /** Sets a segment to its maximum value. */
+  incrementToMax: (type: DateSegmentType) => void;
+  /** Sets a segment to its minimum value. */
+  decrementToMin: (type: DateSegmentType) => void;
   /** Clears a segment. */
   clearSegment: (type: DateSegmentType) => void;
   /** Confirms the value (after typing). */
@@ -147,7 +175,9 @@ export interface DateFieldState<T extends DateValue = DateValue> {
   /** The validation state. */
   validationState: Accessor<ValidationState | undefined>;
   /** The granularity. */
-  granularity: "day" | "hour" | "minute" | "second";
+  readonly granularity: FieldGranularity;
+  /** The maximum granularity. */
+  readonly maxGranularity: "year" | "month" | "day" | "hour" | "minute";
   /** Whether the value is invalid. */
   isInvalid: Accessor<boolean>;
   /** Realtime validation results, including native and custom constraints. */
@@ -161,106 +191,279 @@ export interface DateFieldState<T extends DateValue = DateValue> {
   /** Commits realtime validation to displayed validation. */
   commitValidation: () => void;
   /** The locale. */
-  locale: string;
+  readonly locale: string;
   /** The time zone. */
-  timeZone: string;
+  readonly timeZone: string;
   /** The default value. */
-  defaultValue: T | null;
+  defaultValue: DateValue | null;
 }
 
 type HourCycle = "h11" | "h12" | "h23" | "h24";
 
+const EDITABLE_SEGMENTS: Record<string, boolean> = {
+  year: true,
+  month: true,
+  day: true,
+  hour: true,
+  minute: true,
+  second: true,
+  dayPeriod: true,
+  era: true,
+};
+
+const PAGE_STEP: Record<string, number> = {
+  year: 5,
+  month: 2,
+  day: 7,
+  hour: 2,
+  minute: 15,
+  second: 15,
+};
+
+const TYPE_MAPPING: Record<string, string> = {
+  // Node seems to convert everything to lowercase...
+  dayperiod: "dayPeriod",
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts#named_years
+  relatedYear: "year",
+  yearName: "literal",
+  unknown: "literal",
+};
+
 /**
  * Provides state management for a date field component.
  */
 export function createDateFieldState<T extends DateValue = DateValue>(
   props: DateFieldStateProps<T> = {},
 ): DateFieldState<T> {
-  const timeZone = getLocalTimeZone();
-  const locale = props.locale ?? "en-US";
-  const granularity = props.granularity ?? "day";
-  const calendar: Calendar = new GregorianCalendar();
-  const hourCycle = resolveHourCycle(locale, props.hourCycle);
-  const displaySegments = computeDisplaySegments(granularity, hourCycle);
-
-  const getPlaceholderValue = (): DateValue => {
-    const base = props.placeholderValue ?? today(timeZone);
-    return granularity === "day" ? intlToCalendarDate(base) : toCalendarDateTime(base);
+  const locale = (): string => props.locale ?? "en-US";
+  const createCalendarFn = (name: CalendarIdentifier): Calendar =>
+    (props.createCalendar ?? intlCreateCalendar)(name);
+
+  // The initial resolved value (used only for its calendar identity and defaults).
+  const v0 = (): DateValue | null =>
+    access(props.value) ?? props.defaultValue ?? props.placeholderValue ?? null;
+
+  // Compute default granularity and time zone from the value, keeping the last
+  // values when the value becomes null (mirrors useDefaultProps).
+  const initialDefaults = untrack(() => {
+    const v = v0();
+    return {
+      granularity: (v && "minute" in v ? "minute" : "day") as Granularity,
+      timeZone: v && "timeZone" in v ? (v as { timeZone: string }).timeZone : undefined,
+    };
+  });
+  const [lastDefaults, setLastDefaults] = createSignal<{
+    granularity: Granularity;
+    timeZone: string | undefined;
+  }>(initialDefaults);
+  createComputed(() => {
+    const v = v0();
+    if (!v) return;
+    const defaultGranularity = ("minute" in v ? "minute" : "day") as Granularity;
+    const defaultTimeZone = "timeZone" in v ? (v as { timeZone: string }).timeZone : undefined;
+    const last = untrack(lastDefaults);
+    if (last.granularity !== defaultGranularity || last.timeZone !== defaultTimeZone) {
+      setLastDefaults({ granularity: defaultGranularity, timeZone: defaultTimeZone });
+    }
+  });
+  const granularity = (): FieldGranularity => {
+    if (props.granularity) return props.granularity;
+    const v = v0();
+    if (v) return ("minute" in v ? "minute" : "day") as FieldGranularity;
+    return lastDefaults().granularity as FieldGranularity;
   };
+  const defaultTimeZone = (): string | undefined => {
+    const v = v0();
+    return v
+      ? "timeZone" in v
+        ? (v as { timeZone: string }).timeZone
+        : undefined
+      : lastDefaults().timeZone;
+  };
+  const timeZone = (): string => defaultTimeZone() || "UTC";
+
+  // Resolve default hour cycle and calendar system.
+  const calendarAndHourCycle = createMemo<[Calendar, HourCycle]>(() => {
+    const formatter = new DateFormatter(locale(), {
+      dateStyle: "short",
+      timeStyle: "short",
+      hour12: props.hourCycle != null ? props.hourCycle === 12 : undefined,
+    });
+    const opts = formatter.resolvedOptions();
+    return [createCalendarFn(opts.calendar as CalendarIdentifier), opts.hourCycle as HourCycle];
+  });
+  const calendar = (): Calendar => calendarAndHourCycle()[0];
+  const hourCycle = (): HourCycle => calendarAndHourCycle()[1];
 
-  const toSource = (v: DateValue | null): Partial<Omit<AnyDateTime, "copy">> | null =>
-    (v as Partial<Omit<AnyDateTime, "copy">> | null) ?? null;
-
-  // State signals
-  const initialValue = props.defaultValue ?? null;
-  const [internalValue, setInternalValue] = createSignal<T | null>(initialValue);
-
-  // Controlled vs uncontrolled committed value
-  const value = createMemo<T | null>(() => {
+  // Controlled vs uncontrolled committed value.
+  const [internalValue, setInternalValue] = createSignal<T | null>(props.defaultValue ?? null);
+  const rawValue = createMemo<T | null>(() => {
     const controlled = access(props.value);
     return controlled !== undefined ? controlled : internalValue();
   });
+  const setDate = (v: T | null) => {
+    if (access(props.value) === undefined) setInternalValue(() => v);
+    props.onChange?.(v);
+  };
+
+  // The current value, converted to the display calendar.
+  const calendarValue = createMemo<DateValue | null>(() => convertValue(rawValue(), calendar()) ?? null);
+
+  const initialValue = untrack(calendarValue);
 
   // The display override: holds the (possibly invalid/incomplete) value being edited.
   const [displayValue, setDisplayValue] = createSignal<IncompleteDate>(
-    new IncompleteDate(calendar, hourCycle, toSource(value())),
+    untrack(() => new IncompleteDate(calendar(), hourCycle(), untrack(calendarValue))),
   );
 
-  // Reset the display override whenever the committed value changes from the outside
-  // (e.g. a controlled `value` prop update).
-  let lastSyncedValue = value();
-  createEffect(() => {
-    const v = value();
-    if (v !== lastSyncedValue) {
-      lastSyncedValue = v;
-      setDisplayValue(new IncompleteDate(calendar, hourCycle, toSource(v)));
+  // Render-phase resync: whenever the committed value, calendar, or hour cycle changes
+  // from the outside, re-mint the display override. Ported to createComputed so it runs
+  // synchronously (like React's render-phase setState), never leaving a stale frame.
+  let lastValue = untrack(calendarValue);
+  let lastCalendar = untrack(calendar);
+  let lastHourCycle = untrack(hourCycle);
+  createComputed(() => {
+    const cv = calendarValue();
+    const cal = calendar();
+    const hc = hourCycle();
+    if (cv !== lastValue || hc !== lastHourCycle || !isEqualCalendar(cal, lastCalendar)) {
+      lastValue = cv;
+      lastCalendar = cal;
+      lastHourCycle = hc;
+      setDisplayValue(new IncompleteDate(cal, hc, cv));
     }
   });
 
-  // Derived states
+  const showEra = (): boolean => calendar().identifier === "gregory" && displayValue().era === "BC";
+  const maxGranularity = (): "year" | "month" | "day" | "hour" | "minute" =>
+    props.maxGranularity ?? "year";
+
+  const placeholderDate = createMemo<DateValue>(() =>
+    createPlaceholderDate(props.placeholderValue, granularity(), calendar(), defaultTimeZone()),
+  );
+
+  const formatOpts = createMemo<FormatterOptions>(() => ({
+    granularity: granularity(),
+    maxGranularity: maxGranularity(),
+    timeZone: defaultTimeZone(),
+    hideTimeZone: props.hideTimeZone,
+    hourCycle: props.hourCycle,
+    showEra: showEra(),
+    shouldForceLeadingZeros: props.shouldForceLeadingZeros,
+  }));
+
+  const dateFormatter = createMemo(() => new DateFormatter(locale(), getFormatOptions({}, formatOpts())));
+  const resolvedOptions = createMemo(() => dateFormatter().resolvedOptions());
+
+  const displaySegments = createMemo<DateSegmentType[]>(() => {
+    const hc = hourCycle();
+    const is12HourClock = hc === "h11" || hc === "h12";
+    const segments: DateSegmentType[] = [
+      "era",
+      "year",
+      "month",
+      "day",
+      "hour",
+      ...(is12HourClock ? (["dayPeriod"] as const) : []),
+      "minute",
+      "second",
+    ];
+    const minIndex = segments.indexOf((maxGranularity() as DateSegmentType) || "era");
+    const maxIndex = segments.indexOf(
+      granularity() === "hour" && is12HourClock ? "dayPeriod" : granularity(),
+    );
+    return segments.slice(minIndex, maxIndex + 1);
+  });
+
+  // The effective date value as a native Date, derived from the display override.
+  const dateValue = createMemo<Date>(() => {
+    const v = displayValue().toValue(calendarValue() ?? placeholderDate());
+    return v.toDate(timeZone());
+  });
+
+  const segments = createMemo<DateSegment[]>(() =>
+    processSegments(
+      dateValue(),
+      displayValue(),
+      dateFormatter(),
+      resolvedOptions() as unknown as Record<string, string>,
+      calendar(),
+      locale(),
+      granularity(),
+    ),
+  );
+
+  // Set value with the upstream split: complete + valid commits eagerly; an incomplete
+  // or invalid (e.g. Feb 31) value is held as a display override until blur.
+  const setValue = (newValue: T | IncompleteDate | null) => {
+    if (access(props.isDisabled) || access(props.isReadOnly)) return;
+
+    const cv = calendarValue();
+    const cal = calendar();
+    const hc = hourCycle();
+    const v = v0();
+
+    if (
+      newValue == null ||
+      (newValue instanceof IncompleteDate && newValue.isCleared(displaySegments()))
+    ) {
+      setDisplayValue(new IncompleteDate(cal, hc, cv));
+      setDate(null);
+    } else if (!(newValue instanceof IncompleteDate)) {
+      // The display calendar should not have any effect on the emitted value.
+      // Emit dates in the same calendar as the original value, if any, otherwise gregorian.
+      const emitted = toCalendar(
+        newValue as DateValue,
+        (v as { calendar?: Calendar } | null)?.calendar || new GregorianCalendar(),
+      );
+      setDisplayValue(new IncompleteDate(cal, hc, cv));
+      setDate(emitted as T);
+    } else {
+      // If the new value is complete and valid, trigger onChange eagerly. If it represents
+      // an incomplete or invalid value (e.g. February 30th), wait until blur to trigger onChange.
+      if (newValue.isComplete(displaySegments())) {
+        const dv = newValue.toValue(cv ?? placeholderDate());
+        if (newValue.validate(dv, displaySegments())) {
+          const newDateValue = toCalendar(
+            dv,
+            (v as { calendar?: Calendar } | null)?.calendar || new GregorianCalendar(),
+          );
+          const committed = rawValue();
+          if (!committed || newDateValue.compare(committed) !== 0) {
+            setDisplayValue(new IncompleteDate(cal, hc, cv)); // reset in case prop isn't updated
+            setDate(newDateValue as T);
+            return;
+          }
+        }
+      }
+      // Incomplete/invalid value. Set temporary display override.
+      setDisplayValue(newValue);
+    }
+  };
+
+  const adjustSegment = (type: DateSegmentType, amount: number) => {
+    setValue(displayValue().cycle(type, amount, placeholderDate(), displaySegments()));
+  };
+
+  const builtinValidation = createMemo<ValidationResult>(() =>
+    getValidationResult(
+      rawValue(),
+      access(props.minValue),
+      access(props.maxValue),
+      props.isDateUnavailable,
+      formatOpts(),
+    ),
+  );
+
   const isDisabled = createMemo(() => access(props.isDisabled) ?? false);
   const isReadOnly = createMemo(() => access(props.isReadOnly) ?? false);
   const isRequired = createMemo(() => access(props.isRequired) ?? false);
   const explicitValidationState = createMemo(() => access(props.validationState));
   const validationBehavior = () => props.validationBehavior ?? "native";
-  const builtinValidation = createMemo<ValidationResult>(() => {
-    const v = value();
-    if (!v) return DEFAULT_VALIDATION_RESULT;
-
-    const minValue = access(props.minValue);
-    const maxValue = access(props.maxValue);
-    const validationDetails: ValidityState = { ...VALID_VALIDITY_STATE };
-    const validationErrors: string[] = [];
-
-    if (minValue && v.compare(minValue) < 0) {
-      validationDetails.rangeUnderflow = true;
-      validationErrors.push("Value is below the minimum date.");
-    }
-
-    if (maxValue && v.compare(maxValue) > 0) {
-      validationDetails.rangeOverflow = true;
-      validationErrors.push("Value is above the maximum date.");
-    }
-
-    if (props.isDateUnavailable?.(v)) {
-      validationDetails.customError = true;
-      validationErrors.push("Date is unavailable.");
-    }
-
-    if (validationErrors.length === 0) {
-      return DEFAULT_VALIDATION_RESULT;
-    }
 
-    validationDetails.valid = false;
-    return {
-      isInvalid: true,
-      validationDetails,
-      validationErrors,
-    };
-  });
   const validation = createFormValidationState<T>({
     get value() {
-      return value();
+      return rawValue();
     },
     get isInvalid() {
       return props.isInvalid;
@@ -283,415 +486,367 @@ export function createDateFieldState<T extends DateValue = DateValue>(
     () => explicitValidationState() ?? (isInvalid() ? "invalid" : undefined),
   );
 
-  // The effective date value, derived from the display override.
-  const dateValue = createMemo<DateValue | null>(() => {
-    const v = value();
-    if (v) return v;
-    const dv = displayValue();
-    if (dv.isCleared(displaySegments)) return null;
-    return dv.toValue(getPlaceholderValue());
-  });
-
-  // Generate segments from the display override (so invalid intermediate values render as typed).
-  const segments = createMemo<DateSegment[]>(() => {
-    const dv = displayValue();
-    const base = value() ?? getPlaceholderValue();
-    const resolved = dv.toValue(base);
-    const jsDate = resolved.toDate(timeZone);
-
-    const shouldForceLeadingZeros = props.shouldForceLeadingZeros === true;
-    const formatOptions = buildFormatOptions(granularity, shouldForceLeadingZeros, props.hourCycle);
-    const formatter = new DateFormatter(locale, formatOptions);
-    const resolvedOptions = formatter.resolvedOptions() as unknown as Record<string, string>;
-    const parts = formatter.formatToParts(jsDate);
-
-    const numberFormatter = new Intl.NumberFormat(locale, { useGrouping: false });
-    const twoDigitFormatter = new Intl.NumberFormat(locale, {
-      useGrouping: false,
-      minimumIntegerDigits: 2,
-    });
-
-    const result: DateSegment[] = [];
-    for (const part of parts) {
-      const type = mapPartType(part.type);
-
-      if (type === "literal") {
-        result.push({
-          type: "literal",
-          text: part.value,
-          isEditable: false,
-          isPlaceholder: false,
-          placeholder: part.value,
-        });
-        continue;
-      }
-      if (!type) continue;
-
-      const editable = isEditableSegment(type);
-      const rawValue = rawSegmentValue(dv, type);
-      const isPlaceholder = editable && rawValue == null;
-      const limits = dv.getSegmentLimits(type);
-      const placeholderText = getPlaceholderText(
-        type,
-        locale,
-        granularity,
-        shouldForceLeadingZeros,
-      );
-
-      // For numeric date/time segments, render the raw edited value (e.g. "31" even
-      // when the resolved date is Feb 28) using a NumberFormatter, mirroring upstream.
-      let text = part.value;
-      if (
-        (type === "year" || type === "month" || type === "day" || type === "hour") &&
-        typeof rawValue === "number"
-      ) {
-        const numeric = rawValue ?? 0;
-        text =
-          resolvedOptions[type] === "2-digit"
-            ? twoDigitFormatter.format(numeric)
-            : numberFormatter.format(numeric);
+  return {
+    ...validation,
+    value: calendarValue,
+    defaultValue: props.defaultValue ?? initialValue,
+    dateValue,
+    get calendar() {
+      return calendar();
+    },
+    setValue,
+    segments,
+    get dateFormatter() {
+      return dateFormatter();
+    },
+    validationState,
+    isInvalid,
+    get granularity() {
+      return granularity();
+    },
+    get maxGranularity() {
+      return maxGranularity();
+    },
+    isDisabled,
+    isReadOnly,
+    isRequired,
+    increment(part) {
+      adjustSegment(part, 1);
+    },
+    decrement(part) {
+      adjustSegment(part, -1);
+    },
+    incrementPage(part) {
+      adjustSegment(part, PAGE_STEP[part] || 1);
+    },
+    decrementPage(part) {
+      adjustSegment(part, -(PAGE_STEP[part] || 1));
+    },
+    incrementToMax(part) {
+      const max =
+        part === "hour" && hourCycle() === "h12"
+          ? 11
+          : displayValue().getSegmentLimits(part)?.maxValue;
+      if (max != null) setValue(displayValue().set(part, max, placeholderDate()));
+    },
+    decrementToMin(part) {
+      const min =
+        part === "hour" && hourCycle() === "h12"
+          ? 12
+          : displayValue().getSegmentLimits(part)?.minValue;
+      if (min != null) setValue(displayValue().set(part, min, placeholderDate()));
+    },
+    setSegment(part, value) {
+      setValue(displayValue().set(part, value, placeholderDate()));
+    },
+    confirmPlaceholder() {
+      if (access(props.isDisabled) || access(props.isReadOnly)) return;
+      // If the display value is complete but invalid, constrain it and emit onChange on blur.
+      if (displayValue().isComplete(displaySegments())) {
+        const cv = calendarValue();
+        const dv = displayValue().toValue(cv ?? placeholderDate());
+        const v = v0();
+        const newDateValue = toCalendar(
+          dv,
+          (v as { calendar?: Calendar } | null)?.calendar || new GregorianCalendar(),
+        );
+        const committed = rawValue();
+        if (!committed || newDateValue.compare(committed) !== 0) setDate(newDateValue as T);
+        setDisplayValue(new IncompleteDate(calendar(), hourCycle(), cv));
       }
+    },
+    clearSegment(part) {
+      let value = displayValue();
+      if (part !== "timeZoneName" && part !== "literal") value = displayValue().clear(part);
+      setValue(value);
+    },
+    formatValue(fieldOptions) {
+      if (!calendarValue()) return "";
+      const formatOptions = getFormatOptions(fieldOptions, formatOpts());
+      const formatter = new DateFormatter(locale(), formatOptions);
+      return formatter.format(dateValue());
+    },
+    getDateFormatter(loc, formatOptions) {
+      const newOptions = { ...formatOpts(), ...formatOptions };
+      const newFormatOptions = getFormatOptions({}, newOptions);
+      return new DateFormatter(loc, newFormatOptions);
+    },
+    get locale() {
+      return locale();
+    },
+    get timeZone() {
+      return timeZone();
+    },
+  };
+}
 
-      result.push({
-        type,
-        text: isPlaceholder ? placeholderText : text,
-        value: limits?.value,
-        minValue: limits?.minValue,
-        maxValue: limits?.maxValue,
-        isEditable: editable && !isDisabled() && !isReadOnly(),
-        isPlaceholder,
-        placeholder: placeholderText,
-      });
-    }
+// ---------------------------------------------------------------------------
+// Segment processing
+// ---------------------------------------------------------------------------
 
-    return result;
+function processSegments(
+  dateValue: Date,
+  displayValue: IncompleteDate,
+  dateFormatter: DateFormatter,
+  resolvedOptions: Record<string, string>,
+  calendar: Calendar,
+  locale: string,
+  granularity: FieldGranularity,
+): DateSegment[] {
+  const timeValue = ["hour", "minute", "second"];
+  const parts = dateFormatter.formatToParts(dateValue) as Array<{
+    type: string;
+    value: string;
+  }>;
+
+  // Allow formatting temporarily invalid dates during editing (e.g. February 30th) by
+  // rendering numeric segments directly from raw numbers. On blur they are constrained.
+  const numberFormatter = new Intl.NumberFormat(locale, { useGrouping: false });
+  const twoDigitFormatter = new Intl.NumberFormat(locale, {
+    useGrouping: false,
+    minimumIntegerDigits: 2,
   });
 
-  // Commit a concrete value (updates the controlled/uncontrolled value and fires onChange).
-  const commitDate = (newValue: T | null) => {
-    const controlled = access(props.value);
-    if (controlled === undefined) {
-      lastSyncedValue = newValue;
-      setInternalValue(() => newValue);
-    }
-    props.onChange?.(newValue);
-  };
-
-  // Set value with the upstream split: complete + valid commits eagerly; an incomplete
-  // or invalid (e.g. Feb 31) value is held as a display override until blur.
-  const setValue = (newValue: T | IncompleteDate | null) => {
-    if (isDisabled() || isReadOnly()) return;
-
+  for (const segment of parts) {
     if (
-      newValue == null ||
-      (newValue instanceof IncompleteDate && newValue.isCleared(displaySegments))
+      segment.type === "year" ||
+      segment.type === "month" ||
+      segment.type === "day" ||
+      segment.type === "hour"
     ) {
-      commitDate(null);
-      setDisplayValue(new IncompleteDate(calendar, hourCycle, null));
-      return;
-    }
-
-    if (!(newValue instanceof IncompleteDate)) {
-      commitDate(newValue);
-      setDisplayValue(new IncompleteDate(calendar, hourCycle, toSource(newValue)));
-      return;
-    }
-
-    // If the new value is complete and valid, trigger onChange eagerly. If it represents
-    // an incomplete or invalid value (e.g. February 30th), wait until blur to trigger onChange.
-    if (newValue.isComplete(displaySegments)) {
-      const resolved = newValue.toValue(value() ?? getPlaceholderValue());
-      if (newValue.validate(resolved, displaySegments)) {
-        const committed = value();
-        if (!committed || resolved.compare(committed) !== 0) {
-          setDisplayValue(new IncompleteDate(calendar, hourCycle, toSource(resolved)));
-          commitDate(resolved as T);
-          return;
-        }
+      const value =
+        (displayValue[segment.type as keyof IncompleteDate] as number | null | undefined) ?? 0;
+      if (resolvedOptions[segment.type] === "2-digit") {
+        segment.value = twoDigitFormatter.format(value);
+      } else {
+        segment.value = numberFormatter.format(value);
       }
     }
+  }
 
-    // Incomplete/invalid value. Set temporary display override.
-    setDisplayValue(newValue);
-  };
-
-  const adjustSegment = (type: DateSegmentType, amount: number) => {
-    if (isDisabled() || isReadOnly()) return;
-    setValue(displayValue().cycle(type, amount, getPlaceholderValue(), displaySegments));
-  };
-
-  // Set a specific segment value
-  const setSegment = (type: DateSegmentType, newValue: number) => {
-    if (isDisabled() || isReadOnly()) return;
-    setValue(displayValue().set(type, newValue, getPlaceholderValue()));
-  };
-
-  const incrementSegment = (type: DateSegmentType) => adjustSegment(type, 1);
-  const decrementSegment = (type: DateSegmentType) => adjustSegment(type, -1);
-
-  // Clear a segment, reverting it to its placeholder.
-  const clearSegment = (type: DateSegmentType) => {
-    if (isDisabled() || isReadOnly()) return;
-    let dv = displayValue();
-    if (type !== "timeZoneName" && type !== "literal") {
-      dv = dv.clear(type);
-    }
-    setValue(dv);
-  };
-
-  // When the field is blurred, constrain a complete-but-invalid display value
-  // (e.g. February 31st -> February 28th) and emit onChange. Out-of-range values
-  // are left as-is and reported via validation rather than being snapped.
-  const confirmPlaceholder = () => {
-    if (isDisabled() || isReadOnly()) return;
-    const dv = displayValue();
-    if (!dv.isComplete(displaySegments)) return;
-
-    const resolved = dv.toValue(value() ?? getPlaceholderValue());
-    const committed = value();
-    const needsCommit = !committed || resolved.compare(committed) !== 0;
-    if (needsCommit) {
-      commitDate(resolved as T);
-    }
-
-    // Reset the display override so a constrained value (e.g. February 31st ->
-    // February 28th) renders. Only touch the signal when the displayed raw value
-    // diverged from the resolved value, or when we committed — otherwise leave it
-    // untouched so blur (which fires on every focus move) does not churn the
-    // segments and drop focus.
-    if (needsCommit || !dv.validate(resolved, displaySegments)) {
-      setDisplayValue(new IncompleteDate(calendar, hourCycle, toSource(value() ?? resolved)));
-    }
-  };
-
-  // Format the current value
-  const formatValue = (fieldOptions?: Intl.DateTimeFormatOptions): string => {
-    const v = value();
-    if (!v) return "";
-
-    const options: Intl.DateTimeFormatOptions = fieldOptions ?? {
-      year: "numeric",
-      month: props.shouldForceLeadingZeros === true ? "2-digit" : "numeric",
-      day: props.shouldForceLeadingZeros === true ? "2-digit" : "numeric",
+  const processedSegments: DateSegment[] = [];
+  for (const segment of parts) {
+    const type = (TYPE_MAPPING[segment.type] || segment.type) as DateSegmentType;
+    let isEditable = EDITABLE_SEGMENTS[type] === true;
+    if (type === "era" && calendar.getEras().length === 1) isEditable = false;
+    const isPlaceholder =
+      EDITABLE_SEGMENTS[type] === true &&
+      displayValue[segment.type as keyof IncompleteDate] == null;
+    const placeholder = EDITABLE_SEGMENTS[type]
+      ? getPlaceholder(type, segment.value, locale)
+      : "";
+    const limits = displayValue.getSegmentLimits(type);
+    const dateSegment: DateSegment = {
+      type,
+      text: isPlaceholder ? placeholder : segment.value,
+      value: limits?.value ?? undefined,
+      minValue: limits?.minValue,
+      maxValue: limits?.maxValue,
+      isPlaceholder,
+      placeholder,
+      isEditable,
     };
 
-    if (granularity !== "day") {
-      options.hour = "2-digit";
-      options.minute = "2-digit";
-      if (granularity === "second") {
-        options.second = "2-digit";
+    // There is an issue in RTL languages where time fields render (minute:hour) instead of
+    // (hour:minute). To force LTR on the time field, wrap the time segments in LRI/PDI
+    // (left-to-right isolate) unicode marks. See
+    // https://www.w3.org/International/questions/qa-bidi-unicode-controls.
+    if (type === "hour") {
+      processedSegments.push({
+        type: "literal",
+        text: "⁦",
+        value: undefined,
+        isPlaceholder: false,
+        placeholder: "",
+        isEditable: false,
+      });
+      processedSegments.push(dateSegment);
+      if (type === granularity) {
+        processedSegments.push({
+          type: "literal",
+          text: "⁩",
+          value: undefined,
+          isPlaceholder: false,
+          placeholder: "",
+          isEditable: false,
+        });
       }
+    } else if (timeValue.includes(type) && type === granularity) {
+      processedSegments.push(dateSegment);
+      processedSegments.push({
+        type: "literal",
+        text: "⁩",
+        value: undefined,
+        isPlaceholder: false,
+        placeholder: "",
+        isEditable: false,
+      });
+    } else {
+      processedSegments.push(dateSegment);
     }
+  }
 
-    const formatter = new DateFormatter(locale, options);
-    return formatter.format(v.toDate(timeZone));
-  };
-
-  return {
-    value,
-    defaultValue: initialValue,
-    dateValue,
-    setValue,
-    segments,
-    formatValue,
-    setSegment,
-    incrementSegment,
-    decrementSegment,
-    clearSegment,
-    confirmPlaceholder,
-    isDisabled,
-    isReadOnly,
-    isRequired,
-    validationState,
-    granularity,
-    isInvalid,
-    realtimeValidation: validation.realtimeValidation,
-    displayValidation: validation.displayValidation,
-    updateValidation: validation.updateValidation,
-    resetValidation: validation.resetValidation,
-    commitValidation: validation.commitValidation,
-    locale,
-    timeZone,
-  };
+  return processedSegments;
 }
 
-const EDITABLE_SEGMENTS: Record<string, boolean> = {
-  year: true,
-  month: true,
-  day: true,
-  hour: true,
-  minute: true,
-  second: true,
-  dayPeriod: true,
-  era: true,
-};
+// ---------------------------------------------------------------------------
+// Utilities ported from @react-stately/datepicker utils
+// ---------------------------------------------------------------------------
 
-function isEditableSegment(type: DateSegmentType): boolean {
-  return EDITABLE_SEGMENTS[type] === true;
+interface FormatterOptions {
+  timeZone?: string;
+  hideTimeZone?: boolean;
+  granularity?: Granularity;
+  maxGranularity?: "year" | "month" | "day" | "hour" | "minute";
+  hourCycle?: 12 | 24;
+  showEra?: boolean;
+  shouldForceLeadingZeros?: boolean;
 }
 
-function rawSegmentValue(dv: IncompleteDate, type: DateSegmentType): number | string | null {
-  switch (type) {
-    case "era":
-      return dv.era;
-    case "year":
-      return dv.year;
-    case "month":
-      return dv.month;
-    case "day":
-      return dv.day;
-    case "hour":
-      return dv.hour;
-    case "minute":
-      return dv.minute;
-    case "second":
-      return dv.second;
-    case "dayPeriod":
-      return dv.dayPeriod;
-    default:
-      return null;
-  }
-}
+const DEFAULT_FIELD_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "numeric",
+  day: "numeric",
+  hour: "numeric",
+  minute: "2-digit",
+  second: "2-digit",
+};
 
-function resolveHourCycle(locale: string, hourCycle?: 12 | 24): HourCycle {
-  const formatter = new DateFormatter(locale, {
-    hour: "numeric",
-    hour12: hourCycle != null ? hourCycle === 12 : undefined,
-  });
-  return (formatter.resolvedOptions().hourCycle as HourCycle) ?? "h23";
-}
+const TWO_DIGIT_FIELD_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+};
 
-function computeDisplaySegments(
-  granularity: "day" | "hour" | "minute" | "second",
-  hourCycle: HourCycle,
-): DateSegmentType[] {
-  const is12HourClock = hourCycle === "h11" || hourCycle === "h12";
-  const segments: DateSegmentType[] = [
-    "era",
-    "year",
-    "month",
-    "day",
-    "hour",
-    ...(is12HourClock ? (["dayPeriod"] as const) : []),
-    "minute",
-    "second",
-  ];
-  // We never expose era as an editable segment, so the maximum displayed unit is the year.
-  const minIndex = segments.indexOf("era");
-  const maxIndex = segments.indexOf(
-    granularity === "hour" && is12HourClock ? "dayPeriod" : granularity,
+export function getFormatOptions(
+  fieldOptions: Intl.DateTimeFormatOptions | undefined,
+  options: FormatterOptions,
+): Intl.DateTimeFormatOptions {
+  const defaultFieldOptions = options.shouldForceLeadingZeros
+    ? TWO_DIGIT_FIELD_OPTIONS
+    : DEFAULT_FIELD_OPTIONS;
+  const merged: Record<string, unknown> = { ...defaultFieldOptions, ...fieldOptions };
+  const granularity = options.granularity || "minute";
+  const keys = Object.keys(merged);
+  let startIdx = keys.indexOf(options.maxGranularity ?? "year");
+  if (startIdx < 0) startIdx = 0;
+  let endIdx = keys.indexOf(granularity);
+  if (endIdx < 0) endIdx = 2;
+  if (startIdx > endIdx) throw new Error("maxGranularity must be greater than granularity");
+  const opts: Record<string, unknown> = keys.slice(startIdx, endIdx + 1).reduce(
+    (acc: Record<string, unknown>, key) => {
+      acc[key] = merged[key];
+      return acc;
+    },
+    {},
   );
-  return segments.slice(minIndex, maxIndex + 1);
+  if (options.hourCycle != null) opts.hour12 = options.hourCycle === 12;
+  opts.timeZone = options.timeZone || "UTC";
+  const hasTime = granularity === "hour" || granularity === "minute" || granularity === "second";
+  if (hasTime && options.timeZone && !options.hideTimeZone) opts.timeZoneName = "short";
+  if (options.showEra && startIdx === 0) opts.era = "short";
+  return opts as Intl.DateTimeFormatOptions;
 }
 
-function buildFormatOptions(
-  granularity: "day" | "hour" | "minute" | "second",
-  shouldForceLeadingZeros: boolean,
-  hourCycle?: 12 | 24,
-): Intl.DateTimeFormatOptions {
-  const formatOptions: Intl.DateTimeFormatOptions = {
-    year: "numeric",
-    month: shouldForceLeadingZeros ? "2-digit" : "numeric",
-    day: shouldForceLeadingZeros ? "2-digit" : "numeric",
-  };
+function convertValue(value: DateValue | null | undefined, calendar: Calendar): DateValue | null | undefined {
+  if (value === null) return null;
+  if (!value) return undefined;
+  return toCalendar(value, calendar);
+}
 
-  if (granularity !== "day") {
-    formatOptions.hour = "2-digit";
-    formatOptions.minute = "2-digit";
-    if (granularity === "second") {
-      formatOptions.second = "2-digit";
-    }
-    if (hourCycle) {
-      formatOptions.hourCycle = hourCycle === 12 ? "h12" : "h23";
-    }
+function createPlaceholderDate(
+  placeholderValue: DateValue | undefined,
+  granularity: string,
+  calendar: Calendar,
+  timeZone: string | undefined,
+): DateValue {
+  if (placeholderValue) return convertValue(placeholderValue, calendar) as DateValue;
+  const date = toCalendar(
+    now(timeZone ?? getLocalTimeZone()).set({ hour: 0, minute: 0, second: 0, millisecond: 0 }),
+    calendar,
+  );
+  if (granularity === "year" || granularity === "month" || granularity === "day") {
+    return toCalendarDate(date);
   }
+  if (!timeZone) return toCalendarDateTime(date);
+  return date;
+}
 
-  return formatOptions;
+/** The placeholder time, used by time-only fields. */
+export function getPlaceholderTime(placeholderValue?: DateValue): Time | DateValue {
+  if (placeholderValue && "hour" in placeholderValue) return placeholderValue;
+  return new Time();
 }
 
-function mapPartType(type: Intl.DateTimeFormatPartTypes): DateSegmentType | null {
-  switch (type) {
-    case "year":
-      return "year";
-    case "month":
-      return "month";
-    case "day":
-      return "day";
-    case "hour":
-      return "hour";
-    case "minute":
-      return "minute";
-    case "second":
-      return "second";
-    case "dayPeriod":
-      return "dayPeriod";
-    case "era":
-      return "era";
-    case "timeZoneName":
-      return "timeZoneName";
-    case "literal":
-      return "literal";
-    default:
-      return null;
+function getValidationLocale(): string {
+  let locale =
+    (typeof navigator !== "undefined" &&
+      ((navigator.language as string) ||
+        (navigator as unknown as { userLanguage?: string }).userLanguage)) ||
+    "en-US";
+  try {
+    Intl.DateTimeFormat.supportedLocalesOf([locale]);
+  } catch {
+    locale = "en-US";
   }
+  return locale;
 }
 
-function getPlaceholderText(
-  type: DateSegmentType,
-  locale: string,
-  granularity: "day" | "hour" | "minute" | "second",
-  shouldForceLeadingZeros = false,
-): string {
-  if (type === "literal") return "";
-  if (type === "dayPeriod") return "AM";
-
-  const formatOptions: Intl.DateTimeFormatOptions = {
-    year: "numeric",
-    month: shouldForceLeadingZeros ? "2-digit" : "numeric",
-    day: shouldForceLeadingZeros ? "2-digit" : "numeric",
-  };
-
-  if (granularity !== "day") {
-    formatOptions.hour = "2-digit";
-    formatOptions.minute = "2-digit";
-    if (granularity === "second") {
-      formatOptions.second = "2-digit";
+export function getValidationResult(
+  value: DateValue | null,
+  minValue: DateValue | undefined,
+  maxValue: DateValue | undefined,
+  isDateUnavailable: ((date: DateValue) => boolean) | undefined,
+  options: FormatterOptions,
+): ValidationResult {
+  const rangeOverflow = value != null && maxValue != null && value.compare(maxValue) > 0;
+  const rangeUnderflow = value != null && minValue != null && value.compare(minValue) < 0;
+  const isUnavailable = (value != null && isDateUnavailable?.(value)) || false;
+  const isInvalid = rangeOverflow || rangeUnderflow || isUnavailable;
+  const errors: string[] = [];
+  if (isInvalid) {
+    const locale = getValidationLocale();
+    const dateFormatter = new DateFormatter(locale, getFormatOptions({}, options));
+    const timeZone = dateFormatter.resolvedOptions().timeZone;
+    if (rangeUnderflow && minValue != null) {
+      errors.push(
+        formatError(locale, "rangeUnderflow", {
+          minValue: dateFormatter.format(minValue.toDate(timeZone)),
+        }),
+      );
     }
-  }
-
-  const formatter = new DateFormatter(locale, formatOptions);
-  // Use a reference date with recognizable digits
-  const refDate = new Date(2222, 10, 22, 22, 22, 22);
-  const parts = formatter.formatToParts(refDate);
-
-  for (const part of parts) {
-    const mappedType = mapPartType(part.type);
-    if (mappedType === type) {
-      return part.value.replace(/\d/g, (_d) => {
-        if (type === "year") return "y";
-        if (type === "month") return "m";
-        if (type === "day") return "d";
-        return "–";
-      });
+    if (rangeOverflow && maxValue != null) {
+      errors.push(
+        formatError(locale, "rangeOverflow", {
+          maxValue: dateFormatter.format(maxValue.toDate(timeZone)),
+        }),
+      );
     }
+    if (isUnavailable) errors.push(formatError(locale, "unavailableDate"));
   }
+  const validationDetails: ValidityState = {
+    ...VALID_VALIDITY_STATE,
+    badInput: isUnavailable,
+    rangeOverflow,
+    rangeUnderflow,
+    valid: !isInvalid,
+  };
+  return {
+    isInvalid,
+    validationErrors: errors,
+    validationDetails,
+  };
+}
 
-  switch (type) {
-    case "year":
-      return "yyyy";
-    case "month":
-      return "mm";
-    case "day":
-      return "dd";
-    case "hour":
-      return "––";
-    case "minute":
-      return "––";
-    case "second":
-      return "––";
-    default:
-      return "";
-  }
+function formatError(
+  locale: string,
+  key: DateFieldErrorKey,
+  args?: { minValue?: string; maxValue?: string },
+): string {
+  return formatDateFieldError(locale, key, args);
 }
 
 // Re-export so existing imports of CalendarDateTime keep resolving through this module.