@proyecto-viviana/solid-stately 0.3.0 → 0.4.1

package/src/calendar/createDateFieldState.ts

@@ -2,26 +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, type Accessor } from "solid-js";
+import { createSignal, createMemo, createComputed, untrack, type Accessor } from "solid-js";
 import {
-  CalendarDate,
+  type Calendar,
   type CalendarDateTime,
+  type CalendarIdentifier,
   type DateValue,
-  today,
-  getLocalTimeZone,
+  GregorianCalendar,
   DateFormatter,
-  toCalendarDate as intlToCalendarDate,
+  Time,
+  now,
+  getLocalTimeZone,
+  toCalendar,
+  toCalendarDate,
   toCalendarDateTime,
-  endOfMonth,
+  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,
@@ -41,13 +58,16 @@ 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;
   /** The text content of the segment. */
   text: string;
   /** The numeric value of the segment (if applicable). */
-  value?: number;
+  value?: number | null;
   /** The minimum value for the segment. */
   minValue?: number;
   /** The maximum value for the segment. */
@@ -82,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. */
@@ -103,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). */
@@ -139,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. */
@@ -153,115 +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 = CalendarDate>(
+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";
-
-  // State signals
-  const initialValue = props.defaultValue ?? null;
-  const [internalValue, setInternalValue] = createSignal<T | null>(initialValue);
-
-  // Track partial values during editing
-  const [placeholderDate, setPlaceholderDate] = createSignal<Partial<DateParts>>({});
+  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];
 
-  // Controlled vs uncontrolled 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 effective date value
-  const dateValue = createMemo<DateValue | null>(() => {
-    const v = value();
-    if (v) return v;
-
-    // Build from placeholder parts
-    const parts = placeholderDate();
-    const placeholder = props.placeholderValue ?? today(timeZone);
+  // The current value, converted to the display calendar.
+  const calendarValue = createMemo<DateValue | null>(() => convertValue(rawValue(), calendar()) ?? null);
 
-    if (Object.keys(parts).length === 0) return null;
+  const initialValue = untrack(calendarValue);
 
-    // Create a date from the parts
-    const year = parts.year ?? placeholder.year;
-    const month = parts.month ?? placeholder.month;
-    const day = parts.day ?? placeholder.day;
+  // The display override: holds the (possibly invalid/incomplete) value being edited.
+  const [displayValue, setDisplayValue] = createSignal<IncompleteDate>(
+    untrack(() => new IncompleteDate(calendar(), hourCycle(), untrack(calendarValue))),
+  );
 
-    if (granularity === "day") {
-      return intlToCalendarDate(placeholder).set({ year, month, day });
+  // 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));
     }
+  });
+
+  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);
+  });
 
-    // For time granularities
-    const hour = parts.hour ?? 0;
-    const minute = parts.minute ?? 0;
-    const second = parts.second ?? 0;
-
-    return toCalendarDateTime(placeholder).set({
-      year,
-      month,
-      day,
-      hour,
-      minute,
-      second,
-    }) as unknown as T;
+  // 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());
   });
 
-  // Derived states
+  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;
@@ -284,414 +486,368 @@ export function createDateFieldState<T extends DateValue = CalendarDate>(
     () => explicitValidationState() ?? (isInvalid() ? "invalid" : undefined),
   );
 
-  // Generate segments based on granularity and locale
-  const segments = createMemo<DateSegment[]>(() => {
-    const v = value();
-    const placeholder = props.placeholderValue ?? today(timeZone);
-    const parts = placeholderDate();
+  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();
+    },
+  };
+}
 
-    const segs: DateSegment[] = [];
+// ---------------------------------------------------------------------------
+// Segment processing
+// ---------------------------------------------------------------------------
 
-    // Determine format options based on granularity
-    const shouldForceLeadingZeros = props.shouldForceLeadingZeros === true;
-    const formatOptions: Intl.DateTimeFormatOptions = {
-      year: "numeric",
-      month: shouldForceLeadingZeros ? "2-digit" : "numeric",
-      day: shouldForceLeadingZeros ? "2-digit" : "numeric",
-    };
+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,
+  });
 
-    if (granularity !== "day") {
-      formatOptions.hour = "2-digit";
-      formatOptions.minute = "2-digit";
-      if (granularity === "second") {
-        formatOptions.second = "2-digit";
-      }
-      if (props.hourCycle) {
-        formatOptions.hourCycle = props.hourCycle === 12 ? "h12" : "h23";
+  for (const segment of parts) {
+    if (
+      segment.type === "year" ||
+      segment.type === "month" ||
+      segment.type === "day" ||
+      segment.type === "hour"
+    ) {
+      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);
       }
     }
+  }
 
-    const formatter = new DateFormatter(locale, formatOptions);
-    const dateToFormat = v ?? placeholder;
-    const formattedParts = formatter.formatToParts(dateToFormat.toDate(timeZone));
-
-    for (const part of formattedParts) {
-      const type = mapPartType(part.type);
+  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 (type === "literal") {
-        segs.push({
+    // 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: part.value,
-          isEditable: false,
+          text: "⁩",
+          value: undefined,
           isPlaceholder: false,
-          placeholder: part.value,
-        });
-      } else if (type) {
-        const segValue = getSegmentValue(v, type);
-        const partValue = parts[type as keyof DateParts];
-        const hasValue = v !== null || partValue !== undefined;
-
-        segs.push({
-          type,
-          text: hasValue
-            ? part.value
-            : getPlaceholderText(type, locale, granularity, shouldForceLeadingZeros),
-          value: segValue ?? partValue,
-          minValue: getMinValue(type),
-          maxValue: getMaxValue(type, v ?? placeholder),
-          isEditable: !isDisabled() && !isReadOnly(),
-          isPlaceholder: !hasValue,
-          placeholder: getPlaceholderText(type, locale, granularity, shouldForceLeadingZeros),
+          placeholder: "",
+          isEditable: false,
         });
       }
-    }
-
-    return segs;
-  });
-
-  // Set value with onChange callback
-  const setValue = (newValue: T | null) => {
-    if (isDisabled() || isReadOnly()) return;
-
-    const controlled = access(props.value);
-    if (controlled === undefined) {
-      setInternalValue(() => newValue);
-    }
-
-    if (props.onChange) {
-      props.onChange(newValue);
-    }
-
-    // Clear placeholder parts
-    setPlaceholderDate({});
-  };
-
-  // Set a specific segment value
-  const setSegment = (type: DateSegmentType, newValue: number) => {
-    if (isDisabled() || isReadOnly()) return;
-
-    const v = value();
-
-    if (v) {
-      // Update existing value
-      const updated = updateDatePart(v, type, newValue);
-      setValue(updated as T);
-    } else {
-      // Update placeholder parts
-      setPlaceholderDate((prev) => ({
-        ...prev,
-        [type]: newValue,
-      }));
-    }
-  };
-
-  // Increment a segment
-  const incrementSegment = (type: DateSegmentType) => {
-    if (isDisabled() || isReadOnly()) return;
-
-    const v = value();
-    const current = v ? getSegmentValue(v, type) : placeholderDate()[type as keyof DateParts];
-    const max = getMaxValue(type, v ?? props.placeholderValue ?? today(timeZone));
-    const min = getMinValue(type);
-
-    const newValue = current !== undefined ? current + 1 : min;
-    setSegment(type, newValue > max ? min : newValue);
-  };
-
-  // Decrement a segment
-  const decrementSegment = (type: DateSegmentType) => {
-    if (isDisabled() || isReadOnly()) return;
-
-    const v = value();
-    const current = v ? getSegmentValue(v, type) : placeholderDate()[type as keyof DateParts];
-    const max = getMaxValue(type, v ?? props.placeholderValue ?? today(timeZone));
-    const min = getMinValue(type);
-
-    const newValue = current !== undefined ? current - 1 : max;
-    setSegment(type, newValue < min ? max : newValue);
-  };
-
-  // Clear a segment
-  const clearSegment = (type: DateSegmentType) => {
-    if (isDisabled() || isReadOnly()) return;
-    if (type === "literal") return;
-
-    const v = value();
-    if (v) {
-      // Reset only the target segment to its minimum value instead of clearing the entire value
-      const min = getMinValue(type);
-      const updated = updateDatePart(v, type, min);
-      setValue(updated as T);
-    } else {
-      setPlaceholderDate((prev) => {
-        const next = { ...prev };
-        delete next[type as keyof DateParts];
-        return next;
+    } 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);
     }
-  };
-
-  // Confirm placeholder value
-  const confirmPlaceholder = () => {
-    if (isDisabled() || isReadOnly()) return;
-
-    const minValue = access(props.minValue);
-    const maxValue = access(props.maxValue);
-    const constrain = (candidate: DateValue): DateValue => {
-      if (minValue && candidate.compare(minValue) < 0) {
-        return minValue;
-      }
-      if (maxValue && candidate.compare(maxValue) > 0) {
-        return maxValue;
-      }
-      return candidate;
-    };
-
-    const parts = placeholderDate();
-    if (Object.keys(parts).length > 0) {
-      const dv = dateValue();
-      if (dv) {
-        const candidate = constrain(dv);
-        // Commit even if unavailable so isInvalid can flag it; don't leave field stuck
-        setValue(candidate as T);
-      }
-      return;
-    }
-
-    const current = value();
-    if (current) {
-      const constrained = constrain(current);
-      // Apply min/max constraints even if unavailable; isInvalid will flag unavailable dates
-      if (constrained.compare(current) !== 0) {
-        setValue(constrained as T);
-      }
-    }
-  };
-
-  // 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",
-    };
+  }
 
-    if (granularity !== "day") {
-      options.hour = "2-digit";
-      options.minute = "2-digit";
-      if (granularity === "second") {
-        options.second = "2-digit";
-      }
-    }
+  return processedSegments;
+}
 
-    const formatter = new DateFormatter(locale, options);
-    return formatter.format(v.toDate(timeZone));
-  };
+// ---------------------------------------------------------------------------
+// Utilities ported from @react-stately/datepicker utils
+// ---------------------------------------------------------------------------
 
-  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,
-  };
+interface FormatterOptions {
+  timeZone?: string;
+  hideTimeZone?: boolean;
+  granularity?: Granularity;
+  maxGranularity?: "year" | "month" | "day" | "hour" | "minute";
+  hourCycle?: 12 | 24;
+  showEra?: boolean;
+  shouldForceLeadingZeros?: boolean;
 }
 
-interface DateParts {
-  year?: number;
-  month?: number;
-  day?: number;
-  hour?: number;
-  minute?: number;
-  second?: number;
+const DEFAULT_FIELD_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "numeric",
+  day: "numeric",
+  hour: "numeric",
+  minute: "2-digit",
+  second: "2-digit",
+};
+
+const TWO_DIGIT_FIELD_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+};
+
+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;
+    },
+    {},
+  );
+  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 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 convertValue(value: DateValue | null | undefined, calendar: Calendar): DateValue | null | undefined {
+  if (value === null) return null;
+  if (!value) return undefined;
+  return toCalendar(value, calendar);
 }
 
-function getSegmentValue(date: DateValue | null, type: DateSegmentType): number | undefined {
-  if (!date) return undefined;
-
-  switch (type) {
-    case "year":
-      return date.year;
-    case "month":
-      return date.month;
-    case "day":
-      return date.day;
-    case "hour":
-      return "hour" in date ? (date as CalendarDateTime).hour : undefined;
-    case "minute":
-      return "minute" in date ? (date as CalendarDateTime).minute : undefined;
-    case "second":
-      return "second" in date ? (date as CalendarDateTime).second : undefined;
-    default:
-      return undefined;
+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;
 }
 
-function getMinValue(type: DateSegmentType): number {
-  switch (type) {
-    case "year":
-      return 1;
-    case "month":
-      return 1;
-    case "day":
-      return 1;
-    case "hour":
-      return 0;
-    case "minute":
-      return 0;
-    case "second":
-      return 0;
-    default:
-      return 0;
-  }
+/** 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 getMaxValue(type: DateSegmentType, date: DateValue): number {
-  switch (type) {
-    case "year":
-      return 9999;
-    case "month":
-      return 12;
-    case "day":
-      // Get days in month
-      return endOfMonth(date).day;
-    case "hour":
-      return 23;
-    case "minute":
-      return 59;
-    case "second":
-      return 59;
-    default:
-      return 0;
+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"));
   }
-
-  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 "";
-  }
+  const validationDetails: ValidityState = {
+    ...VALID_VALIDITY_STATE,
+    badInput: isUnavailable,
+    rangeOverflow,
+    rangeUnderflow,
+    valid: !isInvalid,
+  };
+  return {
+    isInvalid,
+    validationErrors: errors,
+    validationDetails,
+  };
 }
 
-function updateDatePart(date: DateValue, type: DateSegmentType, value: number): DateValue {
-  if (typeof (date as { set?: unknown }).set !== "function") {
-    return date;
-  }
-
-  switch (type) {
-    case "year":
-      return date.set({ year: value });
-    case "month":
-      return date.set({ month: value });
-    case "day":
-      return date.set({ day: value });
-    case "hour":
-      return date.set({ hour: value });
-    case "minute":
-      return date.set({ minute: value });
-    case "second":
-      return date.set({ second: value });
-    default:
-      return date;
-  }
+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.
+export type { CalendarDateTime };