@trackunit/react-form-components 1.25.2 → 1.25.3

package/index.esm.js

@@ -1,14 +1,14 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation, NamespaceTrans } from '@trackunit/i18n-library-translation';
-import { Temporal, toDateUtil, startOfDayUtil } from '@trackunit/date-and-time-utils';
-import { IconButton, Icon, Tooltip, Popover, PopoverTrigger, PopoverContent, Button, cvaMenu, cvaMenuList, Tag, useIsTextTruncated, ZStack, MenuItem, useMeasure, useDebounce, useMergeRefs, Spinner, useScrollBlock, Text, Heading, useIsFirstRender } from '@trackunit/react-components';
-import { useCallback, useRef, useEffect, useImperativeHandle, useState, cloneElement, isValidElement, useLayoutEffect, useMemo, useReducer, createContext, useContext, useId } from 'react';
-import ReactCalendar from 'react-calendar';
+import { IconButton, Icon, Tooltip, Button, Popover, PopoverTrigger, PopoverContent, cvaMenu, cvaMenuList, Tag, useIsTextTruncated, ZStack, MenuItem, useMeasure, useDebounce, useMergeRefs, Spinner, useScrollBlock, Text, Heading, useIsFirstRender } from '@trackunit/react-components';
+import { useMemo, useRef, useEffect, useImperativeHandle, useState, useCallback, useLayoutEffect, cloneElement, isValidElement, useReducer, createContext, useContext, useId } from 'react';
 import { twMerge } from 'tailwind-merge';
-import { themeSpacing } from '@trackunit/ui-design-tokens';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
+import { themeSpacing } from '@trackunit/ui-design-tokens';
 import { titleCase } from 'string-ts';
 import { useCopyToClipboard } from 'usehooks-ts';
+import ReactCalendar from 'react-calendar';
+import { Temporal, toDateUtil, startOfDayUtil } from '@trackunit/date-and-time-utils';
 import parsePhoneNumberFromString, { isSupportedCountry, getCountries, getCountryCallingCode, AsYouType, parseIncompletePhoneNumber, isValidPhoneNumber } from 'libphonenumber-js';
 import ReactSelect, { components } from 'react-select';
 export { default as ValueType } from 'react-select';
@@ -29,7 +29,7 @@ var defaultTranslations = {
 	"dateField.actions.apply": "Apply",
 	"dateField.actions.cancel": "Cancel",
 	"dateField.actions.clear": "Clear",
-	"dateField.placeholder": "yyyy-mm-dd",
+	"dateField.openPicker.ariaLabel": "Open date picker",
 	"dropzone.input.title": "Drag-and-drop file input",
 	"dropzone.label.default": "<clickable>Browse</clickable> or drag files here...",
 	"emailField.error.INVALID_EMAIL": "Please enter a valid email address",
@@ -107,6 +107,45 @@ const setupLibraryTranslations = () => {
 };
 
 const ISO_DATE_REGEX = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_PART_SEQUENCE = ["day", "month", "year"];
+const PLACEHOLDER_BY_PART = {
+    day: "dd",
+    month: "mm",
+    year: "yyyy",
+};
+const ISO_PART_ORDER = ["year", "month", "day"];
+// i18next's built-in key-debug mode. The "Developer" entry in `LanguageSelection` writes this
+// value to `localStorage["i18nextLng"]`, so this is the actual token we have to filter out
+// before it reaches `Intl.DateTimeFormat`.
+const KEY_DEBUG_LANGUAGE = "cimode";
+const isDatePartName = (value) => DATE_PART_SEQUENCE.some(part => part === value);
+const getBrowserLanguage = () => typeof navigator !== "undefined" && navigator.language ? navigator.language : "en";
+function parseAndValidateDateParts(parts) {
+    const { year: yearValue, month: monthValue, day: dayValue } = parts;
+    if (yearValue.length !== 4 ||
+        monthValue.length < 1 ||
+        monthValue.length > 2 ||
+        dayValue.length < 1 ||
+        dayValue.length > 2) {
+        return null;
+    }
+    const year = Number.parseInt(yearValue, 10);
+    const month = Number.parseInt(monthValue, 10) - 1;
+    const day = Number.parseInt(dayValue, 10);
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+        return null;
+    }
+    if (month < 0 || month > 11 || day < 1 || day > 31) {
+        return null;
+    }
+    const local = new Date(year, month, day);
+    if (Number.isNaN(local.getTime()))
+        return null;
+    if (local.getFullYear() !== year || local.getMonth() !== month || local.getDate() !== day) {
+        return null;
+    }
+    return { year, month: month + 1, day };
+}
 function parseAndValidateYYYYMMDD(value) {
     if (value === "")
         return null;
@@ -116,18 +155,76 @@ function parseAndValidateYYYYMMDD(value) {
     const [, y, m, d] = isoMatch;
     if (y === undefined || m === undefined || d === undefined)
         return null;
-    const year = Number.parseInt(y, 10);
-    const month = Number.parseInt(m, 10) - 1;
-    const day = Number.parseInt(d, 10);
-    if (month < 0 || month > 11 || day < 1 || day > 31)
+    return parseAndValidateDateParts({ year: y, month: m, day: d });
+}
+function buildDatePartValues(partOrder, getPartAt) {
+    const values = { day: "", month: "", year: "" };
+    for (const [index, part] of partOrder.entries()) {
+        const value = getPartAt(part, index);
+        if (value === undefined) {
+            return null;
+        }
+        values[part] = value;
+    }
+    return values;
+}
+function parseDateByPartOrder(value, partOrder) {
+    const parts = value
+        .split(/\D+/)
+        .map(part => part.trim())
+        .filter(Boolean);
+    if (parts.length !== DATE_PART_SEQUENCE.length) {
+        return null;
+    }
+    const partValues = buildDatePartValues(partOrder, (_part, index) => parts[index]);
+    if (!partValues)
         return null;
-    const local = new Date(year, month, day);
-    if (Number.isNaN(local.getTime()))
+    const parsed = parseAndValidateDateParts(partValues);
+    if (!parsed)
         return null;
-    if (local.getFullYear() !== year || local.getMonth() !== month || local.getDate() !== day) {
+    return new Date(parsed.year, parsed.month - 1, parsed.day);
+}
+function parseQuickTypedDateByPartOrder(digits, partOrder) {
+    if (!/^\d{8}$/.test(digits)) {
         return null;
     }
-    return { year, month: month + 1, day };
+    let cursor = 0;
+    const partValues = buildDatePartValues(partOrder, part => {
+        const length = part === "year" ? 4 : 2;
+        const slice = digits.slice(cursor, cursor + length);
+        cursor += length;
+        return slice;
+    });
+    if (!partValues || cursor !== digits.length) {
+        return null;
+    }
+    const parsed = parseAndValidateDateParts(partValues);
+    if (!parsed)
+        return null;
+    return new Date(parsed.year, parsed.month - 1, parsed.day);
+}
+const datePartOrderByLocale = new Map();
+const datePlaceholderByLocale = new Map();
+function getDateFieldFormatParts(locale) {
+    return new Intl.DateTimeFormat(locale, {
+        day: "2-digit",
+        month: "2-digit",
+        year: "numeric",
+    }).formatToParts(new Date(2006, 0, 22));
+}
+function getDateFieldPartOrder(locale) {
+    const cached = datePartOrderByLocale.get(locale);
+    if (cached !== undefined)
+        return cached;
+    const orderedParts = [];
+    for (const part of getDateFieldFormatParts(locale)) {
+        if (isDatePartName(part.type)) {
+            orderedParts.push(part.type);
+        }
+    }
+    const resolved = orderedParts.length === DATE_PART_SEQUENCE.length ? orderedParts : ISO_PART_ORDER;
+    datePartOrderByLocale.set(locale, resolved);
+    return resolved;
 }
 /**
  * Parses the value from a DateField change event (YYYY-MM-DD string) to a Date at local midnight.
@@ -143,6 +240,88 @@ function parseDateFieldValue(value) {
         return null;
     return new Date(parsed.year, parsed.month - 1, parsed.day);
 }
+/**
+ * Normalises a locale tag for use with `Intl.DateTimeFormat`.
+ *
+ * Filters out tags that are not real Intl locales (the empty string and i18next's `cimode`
+ * key-debug pseudo-language, surfaced as "Developer" in `LanguageSelection`) and replaces them
+ * with the browser locale. Region-qualified and bare-language Intl tags are returned unchanged
+ * so that the caller (`useDateFieldLocale`, callers passing a manual `locale` prop, etc.) keeps
+ * full control of the policy decision.
+ *
+ * Note: prior versions of this function additionally rewrote bare `"en"` to the browser locale
+ * so that UK browsers would not see US-style dates when the Manager UI language was English.
+ * That policy now lives in `useDateFieldLocale` (browser-first), so this function no longer
+ * special-cases `"en"`.
+ */
+function resolveDateFieldLocale(locale) {
+    if (!locale || locale === KEY_DEBUG_LANGUAGE) {
+        return getBrowserLanguage();
+    }
+    return locale;
+}
+/**
+ * Returns the locale-aligned placeholder shown in the DateField. Result is memoized per locale —
+ * see `datePlaceholderByLocale` above.
+ */
+function getDateFieldPlaceholder(locale) {
+    const cached = datePlaceholderByLocale.get(locale);
+    if (cached !== undefined)
+        return cached;
+    const placeholder = getDateFieldFormatParts(locale)
+        .map(part => {
+        if (part.type === "literal") {
+            return part.value;
+        }
+        if (isDatePartName(part.type)) {
+            return PLACEHOLDER_BY_PART[part.type];
+        }
+        return "";
+    })
+        .join("");
+    datePlaceholderByLocale.set(locale, placeholder);
+    return placeholder;
+}
+/**
+ * Formats a Date for display in the DateField while keeping event payloads canonical.
+ */
+function formatDateFieldValueForLocale(value, locale) {
+    return new Intl.DateTimeFormat(locale, {
+        day: "2-digit",
+        month: "2-digit",
+        year: "numeric",
+    }).format(value);
+}
+/**
+ * Parses localized or quick-typed DateField input into a Date.
+ * Supports canonical YYYY-MM-DD, locale-ordered quick typing (e.g. DDMMYYYY), and YYYYMMDD.
+ */
+function parseDateFieldDisplayValue(value, locale) {
+    const trimmedValue = value.trim();
+    if (trimmedValue === "") {
+        return null;
+    }
+    const strictIsoDate = parseDateFieldValue(trimmedValue);
+    if (strictIsoDate) {
+        return strictIsoDate;
+    }
+    const digitsOnly = trimmedValue.replace(/\D/g, "");
+    if (digitsOnly.length === 8) {
+        const quickTypedIsoDate = parseQuickTypedDateByPartOrder(digitsOnly, ISO_PART_ORDER);
+        if (quickTypedIsoDate) {
+            return quickTypedIsoDate;
+        }
+        const quickTypedLocalizedDate = parseQuickTypedDateByPartOrder(digitsOnly, getDateFieldPartOrder(locale));
+        if (quickTypedLocalizedDate) {
+            return quickTypedLocalizedDate;
+        }
+    }
+    const localizedDate = parseDateByPartOrder(trimmedValue, getDateFieldPartOrder(locale));
+    if (localizedDate) {
+        return localizedDate;
+    }
+    return parseDateByPartOrder(trimmedValue, ISO_PART_ORDER);
+}
 /**
  * Converts a YYYY-MM-DD string (e.g. from DateField) to an ISO string at UTC midnight for that calendar day.
  * Use this when storing or sending date-only values so that the calendar day is preserved regardless of
@@ -176,44 +355,68 @@ function dateToISODateUTC(date) {
     return `${year}-${mm}-${dd}T00:00:00.000Z`;
 }
 
-const createSyntheticInputChangeEvent = (value, sourceInput) => {
-    const target = document.createElement("input");
-    target.value = value;
-    if (sourceInput) {
-        target.name = sourceInput.name;
-        target.id = sourceInput.id;
-    }
-    const native = new Event("change", { bubbles: true });
-    return {
-        target,
-        currentTarget: target,
-        type: "change",
-        bubbles: native.bubbles,
-        cancelable: native.cancelable,
-        defaultPrevented: native.defaultPrevented,
-        eventPhase: native.eventPhase,
-        isTrusted: native.isTrusted,
-        nativeEvent: native,
-        timeStamp: native.timeStamp,
-        preventDefault: () => native.preventDefault(),
-        stopPropagation: () => native.stopPropagation(),
-        persist: () => {
-            return;
-        },
-        isDefaultPrevented: () => native.defaultPrevented,
-        isPropagationStopped: () => false,
-    };
-};
+const LANG_STORAGE_KEY = "i18nextLng";
 /**
- * Returns a stable function that builds a synthetic change event for an input with a given value.
- * Use when calling onChange from code (e.g. clear, apply, clamped value) so consumers
- * that use `onChange={e => setValue(e.target.value)}` still receive the expected shape.
- *
- * @example
- * const createInputChangeEvent = useCreateInputChangeEvent();
- * onChange?.(createInputChangeEvent(str, inputRef.current));
+ * Resolves the locale used by `DateField` for placeholder, parsing, and display formatting.
+ *
+ * Date format is a *regional* preference (e.g. `dd/mm/yyyy` vs `mm/dd/yyyy`), independent of the
+ * UI translation language. We therefore prefer `navigator.language` — a region-qualified browser
+ * locale (`en-GB`, `en-US`, `fr-CA`, `da-DK`, …) is the user's explicit regional preference and
+ * wins over the user-selected Manager UI language. The selected language is only used as a
+ * fallback when the browser locale is missing or has no region.
+ *
+ * Examples (selected | browser → resolved):
+ * - `en` | `en-GB` → `en-GB` (UK customers see `dd/mm/yyyy`)
+ * - `en` | `en-US` → `en-US` (US customers see `mm/dd/yyyy`)
+ * - `da` | `en-US` → `en-US` (browser region wins for date format)
+ * - `da` | `da-DK` → `da-DK` (`dd.mm.yyyy`, dotted separator is the native Danish format)
+ * - `en` | `en` (no region) → falls through to `resolveDateFieldLocale`, which keeps `en`
+ * - `cimode` | `en-US` → `en-US` (browser wins; i18next's key-debug pseudo-language is non-Intl)
+ * - `cimode` | `en` → `en` (`resolveDateFieldLocale` filters `cimode` out and returns the browser locale)
+ *
+ * Note: this hook reads `localStorage` and `navigator.language` synchronously and does not
+ * subscribe to changes. Re-renders on same-tab language change rely on the consuming component
+ * also using `useTranslation` (which re-renders on `i18next.languageChanged`). Cross-tab sync
+ * is not supported.
  */
-const useCreateInputChangeEvent = () => useCallback((value, sourceInput) => createSyntheticInputChangeEvent(value, sourceInput), []);
+const useDateFieldLocale = () => {
+    const browserLocale = typeof navigator !== "undefined" ? navigator.language : "";
+    const selectedLanguage = typeof localStorage !== "undefined" ? localStorage.getItem(LANG_STORAGE_KEY) : null;
+    return useMemo(() => {
+        if (browserLocale.includes("-")) {
+            return browserLocale;
+        }
+        return resolveDateFieldLocale(selectedLanguage || browserLocale || "en");
+    }, [browserLocale, selectedLanguage]);
+};
+
+const cvaActionButton = cvaMerge(["drop-shadow-none", "rounded-md"], {
+    variants: {
+        size: {
+            small: ["w-6", "h-6", "min-h-0"],
+            medium: ["w-6", "h-6", "min-h-0"],
+            large: ["w-8", "h-8"],
+        },
+    },
+    defaultVariants: {
+        size: "medium",
+    },
+});
+const cvaActionContainer = cvaMerge(["flex", "items-center"], {
+    variants: {
+        size: {
+            //I just measured manually the top/bottom spacing
+            //when using the action button inside an input
+            //might need tweaking in the future
+            small: ["m-[1px]"],
+            medium: ["m-[3px]"],
+            large: ["m-[7px]"],
+        },
+    },
+    defaultVariants: {
+        size: "medium",
+    },
+});
 
 const cvaInputBase = cvaMerge([
     "component-baseInput-shadow",
@@ -398,34 +601,6 @@ const AddonRenderer = ({ addon, "data-testid": dataTestId, className, fieldSize,
     return (jsx("div", { className: cvaInputAddon({ size: fieldSize, position, className }), "data-testid": dataTestId ? `${dataTestId}-addon${titleCase(position)}` : null, children: addon }));
 };
 
-const cvaActionButton = cvaMerge(["drop-shadow-none", "rounded-md"], {
-    variants: {
-        size: {
-            small: ["w-6", "h-6", "min-h-0"],
-            medium: ["w-6", "h-6", "min-h-0"],
-            large: ["w-8", "h-8"],
-        },
-    },
-    defaultVariants: {
-        size: "medium",
-    },
-});
-const cvaActionContainer = cvaMerge(["flex", "items-center"], {
-    variants: {
-        size: {
-            //I just measured manually the top/bottom spacing
-            //when using the action button inside an input
-            //might need tweaking in the future
-            small: ["m-[1px]"],
-            medium: ["m-[3px]"],
-            large: ["m-[7px]"],
-        },
-    },
-    defaultVariants: {
-        size: "medium",
-    },
-});
-
 /**
  * The ActionButton component is a wrapper over IconButton to perform an action when the onClick event is triggered.
  *
@@ -600,7 +775,11 @@ const BaseInput = ({ className, isInvalid = false, "data-testid": dataTestId, pr
 };
 BaseInput.displayName = "BaseInput";
 
-function parseToDate(v) {
+/**
+ * Parses a heterogeneous date input (Date, ISO string, locale-formatted string, or epoch number)
+ * into a `Date`. Returns `undefined` when the input is empty or unparseable.
+ */
+function parseToDate(v, locale) {
     if (v === undefined || v === "")
         return undefined;
     if (v instanceof Date)
@@ -610,12 +789,13 @@ function parseToDate(v) {
         return Number.isNaN(d.getTime()) ? undefined : d;
     }
     const str = String(v);
-    const fromField = parseDateFieldValue(str);
+    const fromField = parseDateFieldDisplayValue(str, locale);
     if (fromField !== null)
         return fromField;
     const fallback = new Date(str);
     return Number.isNaN(fallback.getTime()) ? undefined : fallback;
 }
+/** Formats a `Date` as a canonical `YYYY-MM-DD` ISO date string, or `""` when undefined. */
 function formatToInputString(d) {
     if (!d)
         return "";
@@ -627,10 +807,11 @@ function formatToInputString(d) {
         .toPlainDate()
         .toString();
 }
+/** Returns the epoch millis at the start of `d`'s local calendar day. */
 function startOfDayMs(d) {
     return toDateUtil(startOfDayUtil(d)).getTime();
 }
-/** Clamp a date to [minDate, maxDate]; returns the same date if in range or no bounds. */
+/** Clamp a date to `[minDate, maxDate]`; returns the same date if in range or no bounds. */
 function clampToRange(date, minDate, maxDate) {
     if (date === null || date === undefined)
         return null;
@@ -641,96 +822,532 @@ function clampToRange(date, minDate, maxDate) {
         return maxDate;
     return date;
 }
+
+const CALENDAR_TILE_CLASS = "react-calendar__tile";
+const DAY_TILE_CLASS = "react-calendar__month-view__days__day";
+const CALENDAR_TILE_DATE_ATTRIBUTE = "data-date-field-picker-date";
+const CALENDAR_TILE_DATE_SELECTOR = `[${CALENDAR_TILE_DATE_ATTRIBUTE}]`;
 /**
- * A wrapper around BaseInput with a pop-up day picker using the same calendar UI as DayPicker.
+ * Renders the calendar + Clear/Cancel/Apply buttons inside the DateBaseInput popover.
  *
- * The value is formatted to an ISO date string (YYYY-MM-DD)
+ * Action callbacks are responsible for parent state changes only — this component handles
+ * closing the popover after each action completes.
+ */
+const DateBaseInputPickerContent = ({ pendingDate, selectedDate, tileDisabled, closePopover, onCalendarChange, onClear, onCancel, onApply, applyDate, "data-testid": dataTestId, }) => {
+    const [t] = useTranslation();
+    const displayDate = pendingDate ?? selectedDate ?? null;
+    const [activeStartDate, setActiveStartDate] = useState(displayDate ?? undefined);
+    const [focusedDate, setFocusedDate] = useState(displayDate);
+    const [calendarView, setCalendarView] = useState("month");
+    // Set when Enter is pressed on a day tile so the resulting calendar `onChange` (fired
+    // by the browser-synthesised click) can apply the date in a single keystroke instead
+    // of just staging it. Without this, keyboard users have to also Tab to Apply.
+    const commitOnNextChangeRef = useRef(false);
+    const calendarWrapperRef = useRef(null);
+    const pendingFocusValueRef = useRef(null);
+    const allowNextOutsideFocusRef = useRef(false);
+    const getCalendarTileButtons = useCallback(() => {
+        return Array.from(calendarWrapperRef.current?.querySelectorAll(`.${CALENDAR_TILE_CLASS}`) ?? []);
+    }, []);
+    const getButtonDateValue = useCallback((button) => {
+        return button.querySelector(CALENDAR_TILE_DATE_SELECTOR)?.getAttribute(CALENDAR_TILE_DATE_ATTRIBUTE) ?? null;
+    }, []);
+    const getTabbablePickerButtons = useCallback(() => {
+        return Array.from(calendarWrapperRef.current?.querySelectorAll("button:not(:disabled)") ?? []).filter(button => button.tabIndex >= 0);
+    }, []);
+    const getFocusableDateForView = useCallback((date, view) => {
+        switch (view) {
+            case "month":
+                return date;
+            case "year":
+                return new Date(date.getFullYear(), date.getMonth(), 1);
+            case "decade":
+                return new Date(date.getFullYear(), 0, 1);
+            case "century":
+                return new Date(Math.floor((date.getFullYear() - 1) / 10) * 10 + 1, 0, 1);
+            default: {
+                const exhaustiveCheck = view;
+                throw new Error(`Unknown calendar view: ${exhaustiveCheck}`);
+            }
+        }
+    }, []);
+    const getCalendarTileColumnCount = useCallback((view) => {
+        switch (view) {
+            case "month":
+                return 7;
+            case "year":
+            case "decade":
+            case "century":
+                return 3;
+            default: {
+                const exhaustiveCheck = view;
+                throw new Error(`Unknown calendar view: ${exhaustiveCheck}`);
+            }
+        }
+    }, []);
+    useEffect(() => {
+        setFocusedDate(displayDate);
+        if (displayDate !== null) {
+            setActiveStartDate(new Date(displayDate.getFullYear(), displayDate.getMonth(), 1));
+        }
+    }, [displayDate]);
+    useEffect(() => {
+        const buttons = getCalendarTileButtons();
+        if (buttons.length === 0)
+            return;
+        const focusedDateValue = focusedDate ? formatToInputString(getFocusableDateForView(focusedDate, calendarView)) : "";
+        const fallbackButton = buttons.find(button => !button.disabled);
+        const focusedButton = focusedDateValue
+            ? buttons.find(button => getButtonDateValue(button) === focusedDateValue && !button.disabled)
+            : undefined;
+        const rovingButton = focusedButton ?? fallbackButton;
+        buttons.forEach(button => {
+            button.tabIndex = button === rovingButton ? 0 : -1;
+        });
+        if (pendingFocusValueRef.current === null)
+            return;
+        const buttonToFocus = buttons.find(button => getButtonDateValue(button) === pendingFocusValueRef.current && !button.disabled);
+        if (buttonToFocus === undefined)
+            return;
+        pendingFocusValueRef.current = null;
+        buttonToFocus.focus({ preventScroll: true });
+    }, [activeStartDate, calendarView, focusedDate, getButtonDateValue, getCalendarTileButtons, getFocusableDateForView]);
+    useEffect(() => {
+        const handlePointerDown = (event) => {
+            const target = event.target;
+            allowNextOutsideFocusRef.current =
+                target instanceof Node && calendarWrapperRef.current !== null && !calendarWrapperRef.current.contains(target);
+        };
+        const handleFocusIn = (event) => {
+            if (allowNextOutsideFocusRef.current) {
+                allowNextOutsideFocusRef.current = false;
+                return;
+            }
+            const target = event.target;
+            if (!(target instanceof Node) ||
+                calendarWrapperRef.current === null ||
+                calendarWrapperRef.current.contains(target)) {
+                return;
+            }
+            getTabbablePickerButtons()[0]?.focus({ preventScroll: true });
+        };
+        document.addEventListener("pointerdown", handlePointerDown, true);
+        document.addEventListener("focusin", handleFocusIn);
+        return () => {
+            document.removeEventListener("pointerdown", handlePointerDown, true);
+            document.removeEventListener("focusin", handleFocusIn);
+        };
+    }, [getTabbablePickerButtons]);
+    const handleClear = () => {
+        onClear();
+        closePopover();
+    };
+    const handleCancel = () => {
+        onCancel();
+        closePopover();
+    };
+    const handleApply = () => {
+        onApply();
+        closePopover();
+    };
+    const moveFocusBy = useCallback((target, steps) => {
+        const dateValue = getButtonDateValue(target);
+        if (dateValue === null)
+            return;
+        const currentDate = parseDateFieldValue(dateValue);
+        if (currentDate === null)
+            return;
+        const nextDate = new Date(currentDate);
+        switch (calendarView) {
+            case "month":
+                nextDate.setDate(currentDate.getDate() + steps);
+                break;
+            case "year":
+                nextDate.setMonth(currentDate.getMonth() + steps);
+                break;
+            case "decade":
+                nextDate.setFullYear(currentDate.getFullYear() + steps);
+                break;
+            case "century":
+                nextDate.setFullYear(currentDate.getFullYear() + steps * 10);
+                break;
+            default: {
+                const exhaustiveCheck = calendarView;
+                throw new Error(`Unknown calendar view: ${exhaustiveCheck}`);
+            }
+        }
+        const focusableDate = getFocusableDateForView(nextDate, calendarView);
+        pendingFocusValueRef.current = formatToInputString(focusableDate);
+        setFocusedDate(focusableDate);
+        setActiveStartDate(new Date(focusableDate.getFullYear(), focusableDate.getMonth(), 1));
+    }, [calendarView, getButtonDateValue, getFocusableDateForView]);
+    const handleKeyDownCapture = (e) => {
+        const target = e.target;
+        if (!(target instanceof HTMLButtonElement) || !target.classList.contains(CALENDAR_TILE_CLASS))
+            return;
+        if (e.key === "Enter" && target.classList.contains(DAY_TILE_CLASS)) {
+            commitOnNextChangeRef.current = true;
+            return;
+        }
+        if (e.key === "ArrowLeft") {
+            e.preventDefault();
+            moveFocusBy(target, -1);
+            return;
+        }
+        if (e.key === "ArrowRight") {
+            e.preventDefault();
+            moveFocusBy(target, 1);
+            return;
+        }
+        if (e.key === "ArrowUp") {
+            e.preventDefault();
+            moveFocusBy(target, -getCalendarTileColumnCount(calendarView));
+            return;
+        }
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            moveFocusBy(target, getCalendarTileColumnCount(calendarView));
+        }
+    };
+    return (jsxs("div", { className: twMerge("flex w-min flex-col overflow-hidden rounded-md border border-neutral-300 bg-white p-0"), onKeyDownCapture: handleKeyDownCapture, ref: calendarWrapperRef, children: [jsx(ReactCalendar, { activeStartDate: activeStartDate, allowPartialRange: true, className: twMerge("custom-day-picker", "range-picker", "p-0"), onActiveStartDateChange: ({ activeStartDate: nextActiveStartDate }) => {
+                    setActiveStartDate(nextActiveStartDate ?? undefined);
+                }, onChange: val => {
+                    const next = val instanceof Date ? val : Array.isArray(val) ? (val[0] instanceof Date ? val[0] : null) : null;
+                    if (commitOnNextChangeRef.current) {
+                        commitOnNextChangeRef.current = false;
+                        applyDate(next);
+                        closePopover();
+                        return;
+                    }
+                    onCalendarChange(next);
+                }, onViewChange: ({ action, activeStartDate: nextActiveStartDate, view }) => {
+                    setCalendarView(view);
+                    const nextFocusedDate = getFocusableDateForView((action === "drillDown" ? nextActiveStartDate : focusedDate) ?? nextActiveStartDate ?? new Date(), view);
+                    pendingFocusValueRef.current = formatToInputString(nextFocusedDate);
+                    setFocusedDate(nextFocusedDate);
+                    setActiveStartDate(nextActiveStartDate ?? undefined);
+                }, selectRange: false, tileContent: ({ date }) => jsx("span", { "aria-hidden": true, "data-date-field-picker-date": formatToInputString(date) }), tileDisabled: tileDisabled, value: displayDate, view: calendarView }), jsx("hr", {}), jsxs("div", { className: "flex w-full justify-between gap-2 px-4 py-3", children: [jsx(Button, { className: "mr-auto", "data-testid": dataTestId ? `${dataTestId}-clear-button` : undefined, onClick: handleClear, size: "small", variant: "secondary", children: t("dateField.actions.clear") }), jsxs("div", { className: "flex gap-2", children: [jsx(Button, { "data-testid": dataTestId ? `${dataTestId}-cancel-button` : undefined, onClick: handleCancel, size: "small", variant: "ghost-neutral", children: t("dateField.actions.cancel") }), jsx(Button, { "data-testid": dataTestId ? `${dataTestId}-apply-button` : undefined, onClick: handleApply, size: "small", children: t("dateField.actions.apply") })] })] })] }));
+};
+
+function buildSyntheticInputEvent(type, value, sourceInput) {
+    const target = document.createElement("input");
+    target.value = value;
+    if (sourceInput) {
+        target.name = sourceInput.name;
+        target.id = sourceInput.id;
+    }
+    const native = new Event(type, { bubbles: true });
+    return {
+        target,
+        currentTarget: target,
+        type,
+        bubbles: native.bubbles,
+        cancelable: native.cancelable,
+        defaultPrevented: native.defaultPrevented,
+        eventPhase: native.eventPhase,
+        isTrusted: native.isTrusted,
+        nativeEvent: native,
+        timeStamp: native.timeStamp,
+        preventDefault: () => native.preventDefault(),
+        stopPropagation: () => native.stopPropagation(),
+        persist: () => undefined,
+        isDefaultPrevented: () => native.defaultPrevented,
+        isPropagationStopped: () => false,
+        relatedTarget: null,
+    };
+}
+/**
+ * Returns a stable function that builds a synthetic change event for an input with a given value.
+ * Use when calling onChange from code (e.g. clear, apply, clamped value) so consumers
+ * that use `onChange={e => setValue(e.target.value)}` still receive the expected shape.
  *
- * NOTE: If shown with a label, please use the `DateField` component instead.
+ * @example
+ * const createInputChangeEvent = useCreateInputChangeEvent();
+ * onChange?.(createInputChangeEvent(str, inputRef.current));
  */
-const DateBaseInput = ({ min, max, defaultValue, value, ref, onChange, suffix: suffixProp, "data-testid": dataTestId, ...rest }) => {
-    const isControlled = value !== undefined;
-    const [internalValue, setInternalValue] = useState(() => formatToInputString(parseToDate(defaultValue)));
-    const [pendingDate, setPendingDate] = useState(null);
-    // For controlled string value, only normalize when it's strict YYYY-MM-DD so partial input (e.g. "2025-03") is preserved.
-    const resolvedValue = isControlled
-        ? typeof value === "string"
-            ? (() => {
-                const strict = parseDateFieldValue(value);
-                return strict !== null ? formatToInputString(strict) : value;
-            })()
-            : formatToInputString(parseToDate(value))
-        : internalValue;
-    const selectedDate = isControlled && typeof value === "string"
-        ? (parseDateFieldValue(value) ?? undefined)
-        : parseToDate(isControlled ? value : internalValue);
+const useCreateInputChangeEvent = () => useCallback((value, sourceInput) => buildSyntheticInputEvent("change", value, sourceInput), []);
+/**
+ * Returns a stable function that builds a synthetic blur (FocusEvent) for an input with a given value.
+ * Use when calling onBlur from code (e.g. when a typed-in value is normalized on blur) so consumers
+ * that use `onBlur={e => doSomething(e.target.value)}` still receive the expected shape.
+ *
+ * @example
+ * const createInputBlurEvent = useCreateInputBlurEvent();
+ * onBlur?.(createInputBlurEvent(canonicalValue, inputRef.current));
+ */
+const useCreateInputBlurEvent = () => useCallback((value, sourceInput) => buildSyntheticInputEvent("blur", value, sourceInput), []);
+
+/**
+ * Owns the underlying `<input>` ref, ref forwarding, the DOM-value sync layout effect, and the
+ * synthetic change/blur emitters used to surface the canonical (ISO) value to consumers while
+ * the displayed input value remains in the locale-specific format.
+ *
+ * The dual format is the reason this hook exists at all: the rendered `value` is locale-formatted
+ * (e.g. `15/03/2025`) but `e.target.value` on `onChange`/`onBlur` should be canonical ISO
+ * (`2025-03-15`). The synthetic events carry the canonical value, and the layout effect ensures
+ * the DOM value is reconciled back to the display string on the next paint.
+ */
+const useCanonicalInputEmitter = ({ ref, onChange, onBlur, resolvedValue, }) => {
     const inputRef = useRef(null);
     const createInputChangeEvent = useCreateInputChangeEvent();
-    const [t] = useTranslation();
-    useImperativeHandle(ref, () => inputRef.current ?? document.createElement("input"), []);
-    const syncPendingFromValue = useCallback(() => {
-        setPendingDate(selectedDate ?? null);
-    }, [selectedDate]);
+    const createInputBlurEvent = useCreateInputBlurEvent();
+    const setInputRef = useCallback((node) => {
+        inputRef.current = node;
+        if (typeof ref === "function") {
+            ref(node);
+        }
+        else if (ref !== null && ref !== undefined) {
+            ref.current = node;
+        }
+    }, [ref]);
+    useLayoutEffect(() => {
+        const input = inputRef.current;
+        if (input && input.value !== resolvedValue) {
+            input.value = resolvedValue;
+        }
+    });
+    const emitCanonicalValueChange = useCallback((canonicalValue) => {
+        if (inputRef.current) {
+            inputRef.current.value = canonicalValue;
+        }
+        onChange?.(createInputChangeEvent(canonicalValue, inputRef.current));
+    }, [createInputChangeEvent, onChange]);
+    const emitCanonicalValueBlur = useCallback((canonicalValue) => {
+        if (inputRef.current) {
+            inputRef.current.value = canonicalValue;
+        }
+        onBlur?.(createInputBlurEvent(canonicalValue, inputRef.current));
+        if (inputRef.current && inputRef.current.value !== resolvedValue) {
+            inputRef.current.value = resolvedValue;
+        }
+    }, [createInputBlurEvent, onBlur, resolvedValue]);
+    return useMemo(() => ({
+        inputRef,
+        setInputRef,
+        createInputChangeEvent,
+        createInputBlurEvent,
+        emitCanonicalValueChange,
+        emitCanonicalValueBlur,
+    }), [setInputRef, createInputChangeEvent, createInputBlurEvent, emitCanonicalValueChange, emitCanonicalValueBlur]);
+};
+
+/**
+ * Picker state machine for `DateBaseInput`. Owns the staged date, the popover's
+ * "was-open" tracking, the tile-disabled predicate, and all four user-driven action handlers
+ * plus the auto-apply behaviour for outside dismissals.
+ */
+const useDatePickerController = ({ selectedDate, minDate, maxDate, commitValue, notifyPickerClose, }) => {
+    const [pendingDate, setPendingDate] = useState(null);
+    const wasOpenRef = useRef(false);
     const tileDisabled = useCallback(({ date, view }) => {
         if (view !== "month")
             return false;
-        const minDate = parseToDate(min);
-        const maxDate = parseToDate(max);
         const dayStart = startOfDayMs(date);
         if (minDate !== undefined && dayStart < startOfDayMs(minDate))
             return true;
         if (maxDate !== undefined && dayStart > startOfDayMs(maxDate))
             return true;
         return false;
-    }, [min, max]);
-    const handleCalendarChange = useCallback((next) => {
+    }, [minDate, maxDate]);
+    const onCalendarChange = useCallback((next) => {
         setPendingDate(next);
     }, []);
-    const handleClear = useCallback((closePopover) => {
+    const onClear = useCallback(() => {
         setPendingDate(null);
-        if (!isControlled)
-            setInternalValue("");
-        onChange?.(createInputChangeEvent("", inputRef.current));
-        closePopover();
-    }, [createInputChangeEvent, isControlled, onChange]);
-    const handleCancel = useCallback((closePopover) => {
-        closePopover();
-    }, []);
-    const handleApply = useCallback((closePopover) => {
-        const minDate = parseToDate(min);
-        const maxDate = parseToDate(max);
+        commitValue("");
+        notifyPickerClose("", "clear");
+    }, [commitValue, notifyPickerClose]);
+    const onCancel = useCallback(() => {
+        notifyPickerClose(formatToInputString(selectedDate), "cancel");
+    }, [notifyPickerClose, selectedDate]);
+    const commitDate = useCallback((date) => {
+        const clamped = clampToRange(date, minDate, maxDate);
+        const canonicalStr = clamped ? formatToInputString(clamped) : "";
+        commitValue(canonicalStr);
+        notifyPickerClose(canonicalStr, "apply");
+    }, [commitValue, maxDate, minDate, notifyPickerClose]);
+    const onApply = useCallback(() => commitDate(pendingDate), [commitDate, pendingDate]);
+    const applyDate = useCallback((next) => {
+        setPendingDate(next);
+        commitDate(next);
+    }, [commitDate]);
+    const onPopoverOpenStateChange = useCallback((open) => {
+        if (open) {
+            wasOpenRef.current = true;
+            setPendingDate(selectedDate ?? null);
+            return;
+        }
+        if (!wasOpenRef.current)
+            return;
+        wasOpenRef.current = false;
         const clamped = clampToRange(pendingDate, minDate, maxDate);
-        const str = clamped ? formatToInputString(clamped) : "";
+        const canonicalStr = clamped ? formatToInputString(clamped) : "";
+        const currentCanonical = formatToInputString(selectedDate);
+        if (canonicalStr !== currentCanonical) {
+            commitValue(canonicalStr);
+        }
+        notifyPickerClose(canonicalStr, "outside");
+    }, [commitValue, maxDate, minDate, notifyPickerClose, pendingDate, selectedDate]);
+    return useMemo(() => ({
+        pendingDate,
+        tileDisabled,
+        onCalendarChange,
+        onClear,
+        onCancel,
+        onApply,
+        applyDate,
+        onPopoverOpenStateChange,
+    }), [pendingDate, tileDisabled, onCalendarChange, onClear, onCancel, onApply, applyDate, onPopoverOpenStateChange]);
+};
+
+/**
+ * A wrapper around BaseInput with a pop-up day picker using the same calendar UI as DayPicker.
+ *
+ * The value is formatted to an ISO date string (YYYY-MM-DD)
+ *
+ * NOTE: If shown with a label, please use the `DateField` component instead.
+ */
+const DateBaseInput = ({ min, max, defaultValue, value, ref, onChange, onBlur, onPickerClose, openOnFocus = false, locale: localeProp, suffix: suffixProp, "data-testid": dataTestId, ...rest }) => {
+    const [t] = useTranslation();
+    const autoLocale = useDateFieldLocale();
+    const locale = localeProp ? resolveDateFieldLocale(localeProp) : autoLocale;
+    const isControlled = value !== undefined;
+    const [internalValue, setInternalValue] = useState(() => formatToInputString(parseToDate(defaultValue, locale)));
+    const rawValue = isControlled
+        ? typeof value === "string"
+            ? value
+            : formatToInputString(parseToDate(value, locale))
+        : internalValue;
+    const resolvedValue = useMemo(() => {
+        const parsed = parseDateFieldValue(rawValue) ?? parseDateFieldDisplayValue(rawValue, locale);
+        return parsed ? formatDateFieldValueForLocale(parsed, locale) : rawValue;
+    }, [rawValue, locale]);
+    const selectedDate = useMemo(() => isControlled && typeof value === "string"
+        ? (parseDateFieldDisplayValue(value, locale) ?? undefined)
+        : parseToDate(isControlled ? value : internalValue, locale), [isControlled, value, internalValue, locale]);
+    const minDate = useMemo(() => parseToDate(min, locale), [min, locale]);
+    const maxDate = useMemo(() => parseToDate(max, locale), [max, locale]);
+    const { inputRef, setInputRef, createInputChangeEvent, createInputBlurEvent, emitCanonicalValueChange, emitCanonicalValueBlur, } = useCanonicalInputEmitter({ ref, onChange, onBlur, resolvedValue });
+    const commitValue = useCallback((canonicalValue) => {
         if (!isControlled)
-            setInternalValue(str);
-        onChange?.(createInputChangeEvent(str, inputRef.current));
-        closePopover();
-    }, [createInputChangeEvent, isControlled, min, max, onChange, pendingDate]);
+            setInternalValue(canonicalValue);
+        emitCanonicalValueChange(canonicalValue);
+    }, [emitCanonicalValueChange, isControlled]);
+    // Guards against `openOnFocus` re-opening the picker as soon as Floating UI returns focus
+    // to the input after a close (Cancel/Apply/Escape/outside-press). The flag is set when the
+    // picker closes and consumed by the very next focus event on the input; a setTimeout
+    // fallback clears it so a later, user-initiated focus can still re-open the picker.
+    const skipNextFocusOpenRef = useRef(false);
+    const notifyPickerClose = useCallback((canonicalValue, reason) => {
+        onPickerClose?.(createInputBlurEvent(canonicalValue, inputRef.current), reason);
+        if (reason === "outside") {
+            // The user dismissed the popover without an explicit action — they're done with
+            // this field. Emit a synthetic blur so form libraries (e.g. react-hook-form) can
+            // run validation; the underlying `<input>` may never have lost focus naturally
+            // during the popover's lifecycle, depending on the browser and click target.
+            emitCanonicalValueBlur(canonicalValue);
+        }
+        skipNextFocusOpenRef.current = true;
+        setTimeout(() => {
+            skipNextFocusOpenRef.current = false;
+        }, 0);
+        // Floating UI's `FloatingFocusManager` suppresses `returnFocus` for outside-press
+        // dismissals, so the trigger never gets focus back. Restore focus to the input
+        // ourselves, but only if focus was lost (active element is the body) — never steal
+        // focus from a focusable element the user just clicked. The microtask defers this
+        // past Floating UI's own focus handling and React's commit phase.
+        queueMicrotask(() => {
+            if (document.activeElement === document.body) {
+                inputRef.current?.focus({ preventScroll: true });
+            }
+        });
+    }, [createInputBlurEvent, emitCanonicalValueBlur, inputRef, onPickerClose]);
+    const { pendingDate, tileDisabled, onCalendarChange, onClear, onCancel, onApply, applyDate, onPopoverOpenStateChange, } = useDatePickerController({ selectedDate, minDate, maxDate, commitValue, notifyPickerClose });
     const handleInputChange = useCallback((e) => {
         const raw = e.target.value;
-        const parsed = parseDateFieldValue(raw);
-        const minDate = parseToDate(min);
-        const maxDate = parseToDate(max);
+        const parsed = parseDateFieldDisplayValue(raw, locale);
         if (parsed !== null) {
             const clamped = clampToRange(parsed, minDate, maxDate);
-            const str = clamped ? formatToInputString(clamped) : "";
-            if (!isControlled)
-                setInternalValue(str);
-            onChange?.(createInputChangeEvent(str, inputRef.current));
+            commitValue(clamped ? formatToInputString(clamped) : "");
         }
         else {
             if (!isControlled)
                 setInternalValue(raw);
             onChange?.(e);
         }
-    }, [createInputChangeEvent, isControlled, min, max, onChange]);
-    return (jsxs(Popover, { onOpenStateChange: open => open && syncPendingFromValue(), placement: "bottom-start", children: [jsx(PopoverTrigger, { children: jsx("div", { className: twMerge("flex w-full min-w-0 cursor-pointer items-center", (Boolean(rest.disabled) || Boolean(rest.readOnly)) && "pointer-events-none"), children: jsx(BaseInput, { ...rest, "aria-readonly": true, className: twMerge("w-full min-w-0", rest.className), "data-testid": dataTestId ? `${dataTestId}-input` : undefined, onChange: handleInputChange, placeholder: rest.placeholder ?? t("dateField.placeholder"), ref: inputRef, suffix: suffixProp ?? (jsx(Icon, { "aria-label": undefined, className: Boolean(rest.disabled) || Boolean(rest.readOnly) ? "text-neutral-500" : undefined, "data-testid": dataTestId ? `${dataTestId}-calendar` : "calendar", name: "Calendar", size: "medium", type: "solid" })), type: "text", value: resolvedValue }) }) }), jsx(PopoverContent, { children: closePopover => {
-                    const displayDate = pendingDate ?? selectedDate ?? null;
-                    return (jsxs("div", { className: twMerge("flex w-min flex-col overflow-hidden rounded-md border border-neutral-300 bg-white p-0"), children: [jsx(ReactCalendar, { allowPartialRange: true, className: twMerge("custom-day-picker", "range-picker", "p-0"), defaultActiveStartDate: displayDate ?? undefined, defaultView: "month", onChange: val => {
-                                    const next = val instanceof Date ? val : Array.isArray(val) ? (val[0] instanceof Date ? val[0] : null) : null;
-                                    handleCalendarChange(next);
-                                }, selectRange: false, tileDisabled: tileDisabled, value: displayDate }), jsx("hr", {}), jsxs("div", { className: "flex w-full justify-between gap-2 px-4 py-3", children: [jsx(Button, { className: "mr-auto", "data-testid": dataTestId ? `${dataTestId}-clear-button` : undefined, onClick: () => handleClear(closePopover), size: "small", variant: "secondary", children: t("dateField.actions.clear") }), jsxs("div", { className: "flex gap-2", children: [jsx(Button, { "data-testid": dataTestId ? `${dataTestId}-cancel-button` : undefined, onClick: () => handleCancel(closePopover), size: "small", variant: "ghost-neutral", children: t("dateField.actions.cancel") }), jsx(Button, { "data-testid": dataTestId ? `${dataTestId}-apply-button` : undefined, onClick: () => handleApply(closePopover), size: "small", children: t("dateField.actions.apply") })] })] })] }));
-                } })] }));
+    }, [commitValue, isControlled, locale, minDate, maxDate, onChange]);
+    const handleInputBlur = useCallback((e) => {
+        const raw = e.target.value;
+        if (raw === "") {
+            if (!isControlled)
+                setInternalValue("");
+            emitCanonicalValueBlur("");
+            return;
+        }
+        const parsed = parseDateFieldDisplayValue(raw, locale);
+        if (parsed !== null) {
+            const clamped = clampToRange(parsed, minDate, maxDate);
+            const canonicalStr = clamped ? formatToInputString(clamped) : "";
+            if (!isControlled)
+                setInternalValue(canonicalStr);
+            emitCanonicalValueBlur(canonicalStr);
+            return;
+        }
+        if (!isControlled)
+            setInternalValue("");
+        onChange?.(createInputChangeEvent("", inputRef.current));
+        onBlur?.(createInputBlurEvent("", inputRef.current));
+    }, [
+        createInputBlurEvent,
+        createInputChangeEvent,
+        emitCanonicalValueBlur,
+        inputRef,
+        isControlled,
+        locale,
+        maxDate,
+        minDate,
+        onBlur,
+        onChange,
+    ]);
+    const isPickerDisabled = Boolean(rest.disabled) || Boolean(rest.readOnly);
+    return (jsx(Popover, { activation: { click: false, hover: false, keyboardHandlers: false }, isModal: true, onOpenStateChange: onPopoverOpenStateChange, placement: "bottom-start", children: ({ isOpen, setIsOpen }) => {
+            // Click activation is disabled on the popover itself so that focusing or clicking
+            // the input does not open the picker — only the calendar IconButton does. Toggling
+            // via the IconButton bypasses Floating UI's `onOpenChange`, so we forward the state
+            // change to the controller manually to keep `notifyPickerClose` and pending-date
+            // staging in sync with the rest of the lifecycle.
+            const togglePopover = () => {
+                const next = !isOpen;
+                setIsOpen(next);
+                onPopoverOpenStateChange(next);
+            };
+            // Restores the previous keyboard affordance: pressing Space while the input is focused
+            // opens (or toggles) the picker. Enter is intentionally not handled here so that form
+            // submission semantics on a text input remain intact.
+            const handleInputKeyDown = (event) => {
+                if (event.key === " " && !isPickerDisabled) {
+                    event.preventDefault();
+                    togglePopover();
+                    return;
+                }
+                rest.onKeyDown?.(event);
+            };
+            // Opt-in: opens the picker the moment the input gains focus. The `skipNextFocusOpenRef`
+            // guard prevents the synthetic focus event fired by FloatingFocusManager's returnFocus
+            // (after Cancel/Apply/Escape/outside-press) from immediately reopening the picker.
+            const handleInputFocus = (event) => {
+                rest.onFocus?.(event);
+                if (skipNextFocusOpenRef.current) {
+                    skipNextFocusOpenRef.current = false;
+                    return;
+                }
+                if (openOnFocus && !isOpen && !isPickerDisabled) {
+                    setIsOpen(true);
+                    onPopoverOpenStateChange(true);
+                }
+            };
+            return (jsxs(Fragment, { children: [jsx(PopoverTrigger, { children: jsx("div", { className: "flex w-full min-w-0 items-center", children: jsx(BaseInput, { ...rest, "aria-readonly": true, className: twMerge("w-full min-w-0", rest.className), "data-testid": dataTestId ? `${dataTestId}-input` : undefined, onBlur: handleInputBlur, onChange: handleInputChange, onFocus: handleInputFocus, onKeyDown: handleInputKeyDown, placeholder: rest.placeholder ?? getDateFieldPlaceholder(locale), ref: setInputRef, suffix: suffixProp ?? (jsx("div", { className: cvaActionContainer({ size: "medium" }), children: jsx(IconButton, { "aria-expanded": isOpen, "aria-label": t("dateField.openPicker.ariaLabel"), className: cvaActionButton({ size: "small" }), "data-testid": dataTestId ? `${dataTestId}-calendar` : "calendar", disabled: isPickerDisabled, icon: jsx(Icon, { "aria-label": undefined, name: "Calendar", size: "small", type: "solid" }), onClick: togglePopover, size: "small", tabIndex: isOpen ? -1 : undefined, variant: "ghost-neutral" }) })), tabIndex: isOpen ? -1 : rest.tabIndex, type: "text", value: resolvedValue }) }) }), jsx(PopoverContent, { initialFocus: 1, children: closePopover => (jsx(DateBaseInputPickerContent, { applyDate: applyDate, closePopover: closePopover, "data-testid": dataTestId, onApply: onApply, onCalendarChange: onCalendarChange, onCancel: onCancel, onClear: onClear, pendingDate: pendingDate, selectedDate: selectedDate, tileDisabled: tileDisabled })) })] }));
+        } }));
 };
 
 /**
@@ -2567,11 +3184,34 @@ ColorField.displayName = "ColorField";
  *   );
  * };
  * ```
+ * @example Server-side validation when the calendar popover closes
+ * ```tsx
+ * import { DateField } from "@trackunit/react-form-components";
+ *
+ * const ValidatedField = () => (
+ *   <DateField
+ *     label="Start date"
+ *     onChange={(e) => setLocalValue(e.target.value)}
+ *     onPickerClose={(e, reason) => {
+ *       if (reason === "cancel") return;
+ *       validateOnServer(e.target.value);
+ *     }}
+ *   />
+ * );
+ * ```
+ * @example Open the picker automatically when the field is focused (e.g. via Tab)
+ * ```tsx
+ * import { DateField } from "@trackunit/react-form-components";
+ *
+ * const QuickPickField = () => (
+ *   <DateField label="Start date" openOnFocus />
+ * );
+ * ```
  */
 const DateField = ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid = undefined, className, defaultValue, "data-testid": dataTestId, ref, required = false, ...rest }) => {
     const renderAsInvalid = isInvalid === undefined ? Boolean(errorMessage) : isInvalid;
     const htmlForId = id ? id : "dateField-" + uuidv4();
-    return (jsx(FormGroup, { "data-testid": dataTestId ? `${dataTestId}-FormGroup` : undefined, helpAddon: helpAddon, helpText: (renderAsInvalid && errorMessage) || helpText, htmlFor: htmlForId, isInvalid: renderAsInvalid, label: label, required: required ? !(Boolean(rest.disabled) || Boolean(rest.readOnly)) : false, tip: tip, children: jsx(DateBaseInput, { "aria-labelledby": htmlForId + "-label", defaultValue: defaultValue, id: htmlForId, isInvalid: renderAsInvalid, ref: ref, required: required, ...rest, className: className, "data-testid": dataTestId }) }));
+    return (jsx(FormGroup, { "data-testid": dataTestId ? `${dataTestId}-FormGroup` : undefined, helpAddon: helpAddon, helpText: (renderAsInvalid && errorMessage) || helpText, htmlFor: htmlForId, isInvalid: renderAsInvalid, label: label, required: required ? !(Boolean(rest.disabled) || Boolean(rest.readOnly)) : false, tip: tip, children: jsx(DateBaseInput, { ...rest, "aria-labelledby": htmlForId + "-label", className: className, "data-testid": dataTestId, defaultValue: defaultValue, id: htmlForId, isInvalid: renderAsInvalid, ref: ref, required: required }) }));
 };
 DateField.displayName = "DateField";
 
@@ -4950,4 +5590,4 @@ const useZodValidators = () => {
  */
 setupLibraryTranslations();
 
-export { ActionButton, BaseInput, BaseSelect, Checkbox, CheckboxField, ColorField, CreatableSelect, CreatableSelectField, DEFAULT_TIME, DateBaseInput, DateField, DropZone, DropZoneDefaultLabel, EMAIL_REGEX, EmailField, FormFieldSelectAdapter, FormGroup, Label, MultiSelectField, NumberBaseInput, NumberField, OptionCard, PasswordBaseInput, PasswordField, PhoneBaseInput, PhoneField, PhoneFieldWithController, RadioGroup, RadioGroupContext, RadioItem, Schedule, ScheduleVariant, Search, SelectField, TextAreaBaseInput, TextAreaField, TextBaseInput, TextField, TimeRange, TimeRangeField, ToggleSwitch, ToggleSwitchOption, UploadField, UploadInput, UrlField, checkIfPhoneNumberHasPlus, countryCodeToFlagEmoji, cvaAccessoriesContainer, cvaActionButton, cvaActionContainer, cvaInput$1 as cvaInput, cvaInputAddon, cvaInputBase, cvaInputBaseDisabled, cvaInputBaseInvalid, cvaInputBaseReadOnly, cvaInputBaseSize, cvaInputElement, cvaInputGroup, cvaInputItemPlacementManager, cvaInputPrefix, cvaInputSuffix, cvaLabel, cvaRadioItem, cvaSelectClearIndicator, cvaSelectContainer, cvaSelectControl, cvaSelectDropdownIconContainer, cvaSelectDropdownIndicator, cvaSelectIndicatorsContainer, cvaSelectLoadingMessage, cvaSelectMenu, cvaSelectMenuList, cvaSelectMultiValue, cvaSelectNoOptionsMessage, cvaSelectPlaceholder, cvaSelectPrefixSuffix, cvaSelectSingleValue, cvaSelectValueContainer, dateToISODateUTC, getCountryAbbreviation, getPhoneNumberWithPlus, isInvalidCountryCode, isInvalidPhoneNumber, isValidHEXColor, parseDateFieldValue, parseSchedule, phoneErrorMessage, serializeSchedule, toISODateStringUTC, useCreatableSelect, useCreateInputChangeEvent, useCustomComponents, useGetPhoneValidationRules, usePhoneInput, useRadioItemChecked, useSelect, useZodValidators, validateEmailAddress, validatePhoneNumber, weekDay };
+export { ActionButton, BaseInput, BaseSelect, Checkbox, CheckboxField, ColorField, CreatableSelect, CreatableSelectField, DEFAULT_TIME, DateBaseInput, DateField, DropZone, DropZoneDefaultLabel, EMAIL_REGEX, EmailField, FormFieldSelectAdapter, FormGroup, Label, MultiSelectField, NumberBaseInput, NumberField, OptionCard, PasswordBaseInput, PasswordField, PhoneBaseInput, PhoneField, PhoneFieldWithController, RadioGroup, RadioGroupContext, RadioItem, Schedule, ScheduleVariant, Search, SelectField, TextAreaBaseInput, TextAreaField, TextBaseInput, TextField, TimeRange, TimeRangeField, ToggleSwitch, ToggleSwitchOption, UploadField, UploadInput, UrlField, checkIfPhoneNumberHasPlus, countryCodeToFlagEmoji, cvaAccessoriesContainer, cvaActionButton, cvaActionContainer, cvaInput$1 as cvaInput, cvaInputAddon, cvaInputBase, cvaInputBaseDisabled, cvaInputBaseInvalid, cvaInputBaseReadOnly, cvaInputBaseSize, cvaInputElement, cvaInputGroup, cvaInputItemPlacementManager, cvaInputPrefix, cvaInputSuffix, cvaLabel, cvaRadioItem, cvaSelectClearIndicator, cvaSelectContainer, cvaSelectControl, cvaSelectDropdownIconContainer, cvaSelectDropdownIndicator, cvaSelectIndicatorsContainer, cvaSelectLoadingMessage, cvaSelectMenu, cvaSelectMenuList, cvaSelectMultiValue, cvaSelectNoOptionsMessage, cvaSelectPlaceholder, cvaSelectPrefixSuffix, cvaSelectSingleValue, cvaSelectValueContainer, dateToISODateUTC, getCountryAbbreviation, getPhoneNumberWithPlus, isInvalidCountryCode, isInvalidPhoneNumber, isValidHEXColor, parseDateFieldValue, parseSchedule, phoneErrorMessage, serializeSchedule, toISODateStringUTC, useCreatableSelect, useCreateInputBlurEvent, useCreateInputChangeEvent, useCustomComponents, useGetPhoneValidationRules, usePhoneInput, useRadioItemChecked, useSelect, useZodValidators, validateEmailAddress, validatePhoneNumber, weekDay };