@trackunit/react-form-components 1.25.2 → 1.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-form-components",
-  "version": "1.25.2",
+  "version": "1.25.3",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -15,11 +15,11 @@
     "zod": "^3.25.76",
     "tailwind-merge": "^2.0.0",
     "@trackunit/css-class-variance-utilities": "1.13.1",
-    "@trackunit/react-components": "1.24.1",
+    "@trackunit/react-components": "1.24.2",
     "@trackunit/ui-icons": "1.13.1",
     "@trackunit/shared-utils": "1.15.1",
     "@trackunit/ui-design-tokens": "1.13.1",
-    "@trackunit/i18n-library-translation": "1.21.1",
+    "@trackunit/i18n-library-translation": "1.21.2",
     "string-ts": "^2.0.0",
     "es-toolkit": "^1.39.10"
   },

package/src/components/BaseInput/BaseInput.variants.d.ts

@@ -19,7 +19,7 @@ export declare const cvaInput: (props?: ({
  *! Relies on the specific grid layout of cvaInput ☝️
  */
 export declare const cvaInputItemPlacementManager: (props?: ({
-    position?: "span" | "before" | "after" | null | undefined;
+    position?: "before" | "after" | "span" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const cvaAccessoriesContainer: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 /**

package/src/components/Checkbox/Checkbox.variants.d.ts

@@ -4,7 +4,7 @@
  */
 export declare const cvaCheckbox: (props?: ({
     invalid?: boolean | null | undefined;
-    state?: "indeterminate" | "selected" | "deselected" | null | undefined;
+    state?: "selected" | "deselected" | "indeterminate" | null | undefined;
     disabled?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**

package/src/components/DateField/DateBaseInput/DateBaseInput.d.ts

@@ -1,5 +1,7 @@
-import { type ReactElement } from "react";
+import { type FocusEvent, type ReactElement } from "react";
 import { BaseInputProps } from "../../BaseInput/BaseInput";
+import { type DateFieldPickerCloseReason } from "./utils/useDatePickerController";
+export type { DateFieldPickerCloseReason } from "./utils/useDatePickerController";
 type BaseInputExposedProps = Omit<BaseInputProps, "defaultValue" | "min" | "max" | "value">;
 export interface DateBaseInputProps extends BaseInputExposedProps {
     /**
@@ -18,6 +20,42 @@ export interface DateBaseInputProps extends BaseInputExposedProps {
      * A value with type Date added
      */
     value?: Date | string | number;
+    /**
+     * Optional override for the BCP-47 locale used for placeholder, display formatting, and
+     * locale-aware parsing of typed input.
+     *
+     * When omitted (recommended for production), the locale resolves via `useDateFieldLocale`,
+     * which prefers the browser's region-qualified `navigator.language` and falls back to the
+     * user-selected Manager UI language. Pass an explicit value (e.g. `"en-GB"`, `"da-DK"`,
+     * `"ja-JP"`) only for deliberate overrides — for example, embedded reports that require a
+     * fixed format, or Storybook/locale showcase stories.
+     */
+    locale?: string;
+    /**
+     * Called when the calendar popover closes, regardless of how it was dismissed.
+     *
+     * Receives a synthetic `FocusEvent` whose `target.value` is the canonical `YYYY-MM-DD` value
+     * currently committed to the input (or `""` when empty). The `reason` argument distinguishes
+     * Apply / Clear / Cancel from the new "outside" auto-apply, so consumers can opt out of
+     * server-side validation when the user explicitly cancelled.
+     *
+     * Use this as a middle ground between `onChange` (fires per keystroke / per pick) and
+     * `onBlur` (fires when the input itself loses focus, which may be much later or never if the
+     * user only interacts with the popover).
+     */
+    onPickerClose?: (event: FocusEvent<HTMLInputElement>, reason: DateFieldPickerCloseReason) => void;
+    /**
+     * When `true`, the calendar popover opens automatically the moment the input gains focus
+     * (for example, by tabbing into the field). The popover trigger (calendar icon, Space, or
+     * Enter on the icon) continues to work as before.
+     *
+     * Focus events that originate from the popover closing — Floating UI's `returnFocus`
+     * placing focus back on the input after Cancel/Apply/Escape/outside-press — are ignored,
+     * so the picker does not loop open immediately after closing.
+     *
+     * @default false
+     */
+    openOnFocus?: boolean;
 }
 /**
  * A wrapper around BaseInput with a pop-up day picker using the same calendar UI as DayPicker.
@@ -26,5 +64,4 @@ export interface DateBaseInputProps extends BaseInputExposedProps {
  *
  * NOTE: If shown with a label, please use the `DateField` component instead.
  */
-export declare const DateBaseInput: ({ min, max, defaultValue, value, ref, onChange, suffix: suffixProp, "data-testid": dataTestId, ...rest }: DateBaseInputProps) => ReactElement;
-export {};
+export declare const DateBaseInput: ({ min, max, defaultValue, value, ref, onChange, onBlur, onPickerClose, openOnFocus, locale: localeProp, suffix: suffixProp, "data-testid": dataTestId, ...rest }: DateBaseInputProps) => ReactElement;

package/src/components/DateField/DateBaseInput/DateBaseInputPickerContent.d.ts

@@ -0,0 +1,34 @@
+import { type ReactElement } from "react";
+type CalendarView = "month" | "year" | "century" | "decade";
+export interface DateBaseInputPickerContentProps {
+    /** Currently staged date inside the open popover (not yet committed to the input). */
+    pendingDate: Date | null;
+    /** Currently committed date held by the input. Used as a fallback for the calendar's active month. */
+    selectedDate: Date | undefined;
+    /** Disables individual day tiles based on the current `[min, max]` range. */
+    tileDisabled: (info: {
+        date: Date;
+        view: CalendarView;
+    }) => boolean;
+    /** Closes the surrounding popover. Provided by `<PopoverContent>` render prop. */
+    closePopover: () => void;
+    /** Fires when the user picks a new day in the calendar. */
+    onCalendarChange: (next: Date | null) => void;
+    /** Fires when the user clicks the Clear action. */
+    onClear: () => void;
+    /** Fires when the user clicks the Cancel action. */
+    onCancel: () => void;
+    /** Fires when the user clicks the Apply action. */
+    onApply: () => void;
+    /** Stages and commits the given date in one step (used for Enter on a focused day tile). */
+    applyDate: (next: Date | null) => void;
+    "data-testid"?: string;
+}
+/**
+ * Renders the calendar + Clear/Cancel/Apply buttons inside the DateBaseInput popover.
+ *
+ * Action callbacks are responsible for parent state changes only — this component handles
+ * closing the popover after each action completes.
+ */
+export declare const DateBaseInputPickerContent: ({ pendingDate, selectedDate, tileDisabled, closePopover, onCalendarChange, onClear, onCancel, onApply, applyDate, "data-testid": dataTestId, }: DateBaseInputPickerContentProps) => ReactElement;
+export {};

package/src/components/DateField/DateBaseInput/utils/dateValueUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export declare function parseToDate(v: Date | string | number | undefined, locale: string): Date | undefined;
+/** Formats a `Date` as a canonical `YYYY-MM-DD` ISO date string, or `""` when undefined. */
+export declare function formatToInputString(d: Date | undefined): string;
+/** Returns the epoch millis at the start of `d`'s local calendar day. */
+export declare function startOfDayMs(d: Date): number;
+/** Clamp a date to `[minDate, maxDate]`; returns the same date if in range or no bounds. */
+export declare function clampToRange(date: Date | null | undefined, minDate: Date | undefined, maxDate: Date | undefined): Date | null;

package/src/components/DateField/DateBaseInput/utils/useCanonicalInputEmitter.d.ts

@@ -0,0 +1,39 @@
+import { type ChangeEvent, type FocusEvent, type Ref, type RefObject } from "react";
+export interface UseCanonicalInputEmitterInput {
+    /** External ref forwarded by the consumer. Forwarded to the underlying `<input>`. */
+    ref: Ref<HTMLInputElement> | undefined;
+    /** Consumer's `onChange`. Invoked with synthetic events whose `target.value` is canonical. */
+    onChange: ((event: ChangeEvent<HTMLInputElement>) => void) | undefined;
+    /** Consumer's `onBlur`. Invoked with synthetic events whose `target.value` is canonical. */
+    onBlur: ((event: FocusEvent<HTMLInputElement>) => void) | undefined;
+    /** The locale-formatted display string the underlying `<input>` should always show. */
+    resolvedValue: string;
+}
+export interface CanonicalInputEmitter {
+    /** Internal ref to the underlying `<input>` element. */
+    inputRef: RefObject<HTMLInputElement | null>;
+    /** Ref-callback to attach to the underlying `<input>`; also forwards to the external `ref`. */
+    setInputRef: (node: HTMLInputElement | null) => void;
+    /** Builds (without emitting) a synthetic change event with a given value. */
+    createInputChangeEvent: (value: string, sourceInput: HTMLInputElement | null) => ChangeEvent<HTMLInputElement>;
+    /** Builds (without emitting) a synthetic blur event with a given value. */
+    createInputBlurEvent: (value: string, sourceInput: HTMLInputElement | null) => FocusEvent<HTMLInputElement>;
+    /** Mutates the input DOM value to `canonicalValue` and emits a synthetic change event. */
+    emitCanonicalValueChange: (canonicalValue: string) => void;
+    /**
+     * Mutates the input DOM value to `canonicalValue`, emits a synthetic blur event, then
+     * resyncs the DOM value back to `resolvedValue` (the locale-formatted display value).
+     */
+    emitCanonicalValueBlur: (canonicalValue: string) => void;
+}
+/**
+ * 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.
+ */
+export declare const useCanonicalInputEmitter: ({ ref, onChange, onBlur, resolvedValue, }: UseCanonicalInputEmitterInput) => CanonicalInputEmitter;

package/src/components/DateField/DateBaseInput/utils/useDatePickerController.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reason the calendar popover closed. Surfaced via `notifyPickerClose` so consumers (e.g.
+ * server-side validation) can decide whether to act on the close event:
+ * - `"apply"`: user clicked the Apply button.
+ * - `"clear"`: user clicked the Clear button.
+ * - `"cancel"`: user clicked the Cancel button (selection discarded).
+ * - `"outside"`: user clicked/tapped outside the popover or pressed Escape — selection auto-applied.
+ */
+export type DateFieldPickerCloseReason = "apply" | "clear" | "cancel" | "outside";
+type CalendarView = "month" | "year" | "century" | "decade";
+export interface UseDatePickerControllerInput {
+    /** Currently committed date held by the input (the source of truth shown in the field). */
+    selectedDate: Date | undefined;
+    /** Lower bound for the calendar (already parsed). */
+    minDate: Date | undefined;
+    /** Upper bound for the calendar (already parsed). */
+    maxDate: Date | undefined;
+    /** Called when the user commits a new canonical (ISO `YYYY-MM-DD` or empty) value. */
+    commitValue: (canonicalValue: string) => void;
+    /** Called whenever the popover closes, with the canonical value at close time and the reason. */
+    notifyPickerClose: (canonicalValue: string, reason: DateFieldPickerCloseReason) => void;
+}
+export interface DatePickerController {
+    /** Currently staged date inside the open popover (not yet committed to the input). */
+    pendingDate: Date | null;
+    /** Disables individual day tiles based on the current `[min, max]` range. */
+    tileDisabled: (info: {
+        date: Date;
+        view: CalendarView;
+    }) => boolean;
+    /** Stages a new date as the user navigates the calendar. */
+    onCalendarChange: (next: Date | null) => void;
+    /** Clears the field and notifies picker-close with reason `"clear"`. */
+    onClear: () => void;
+    /** Discards the staged date and notifies picker-close with reason `"cancel"`. */
+    onCancel: () => void;
+    /** Commits the staged date (clamped to bounds) and notifies picker-close with reason `"apply"`. */
+    onApply: () => void;
+    /**
+     * Stages and commits the given date in one step (clamped to bounds), and notifies
+     * picker-close with reason `"apply"`. Used for keyboard-driven selection (Enter on a
+     * day tile) where the staged value must be applied without an extra Apply click.
+     */
+    applyDate: (next: Date | null) => void;
+    /**
+     * Reacts to the popover open/close lifecycle. On open: stages the currently selected date.
+     * On close: auto-applies the staged date (only commits if it differs from current) and
+     * notifies picker-close with reason `"outside"`.
+     */
+    onPopoverOpenStateChange: (open: boolean) => void;
+}
+/**
+ * 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.
+ */
+export declare const useDatePickerController: ({ selectedDate, minDate, maxDate, commitValue, notifyPickerClose, }: UseDatePickerControllerInput) => DatePickerController;
+export {};

package/src/components/DateField/DateField.d.ts

@@ -55,6 +55,29 @@ export interface DateFieldProps extends DateBaseInputProps, FormGroupExposedProp
  *   );
  * };
  * ```
+ * @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 />
+ * );
+ * ```
  */
 export declare const DateField: {
     ({ label, id, tip, helpText, errorMessage, helpAddon, isInvalid, className, defaultValue, "data-testid": dataTestId, ref, required, ...rest }: DateFieldProps): ReactElement;

package/src/index.d.ts

@@ -54,7 +54,7 @@ export * from "./components/UploadField/UploadField";
 export * from "./components/UploadInput/UploadInput";
 export * from "./components/UrlField/UrlField";
 export * from "./utilities/emailUtils";
-export * from "./utilities/parseDateFieldValue";
+export { dateToISODateUTC, parseDateFieldValue, toISODateStringUTC } from "./utilities/parseDateFieldValue";
 export * from "./utilities/useCreateInputChangeEvent";
 export * from "./utilities/useGetPhoneValidationRules";
 export * from "./utilities/usePhoneInput";

package/src/translation.d.ts

@@ -14,8 +14,8 @@ export declare const translations: TranslationResource<TranslationKeys>;
 /**
  *  Local useTranslation for this specific library
  */
-export declare const useTranslation: () => [TransForLibs<"baseInput.copyAction.toolTip" | "clearIndicator.icon.tooltip.clearAll" | "colorField.error.INVALID_HEX_CODE" | "colorField.error.REQUIRED" | "colorField.tooltip" | "dateField.actions.apply" | "dateField.actions.cancel" | "dateField.actions.clear" | "dateField.placeholder" | "dropzone.input.title" | "dropzone.label.default" | "emailField.error.INVALID_EMAIL" | "emailField.error.REQUIRED" | "field.notEditable.tooltip" | "field.required.asterisk.tooltip" | "numberField.error.GREATER_THAN" | "numberField.error.INVALID_NUMBER" | "numberField.error.LESS_THAN" | "numberField.error.NOT_IN_BETWEEN" | "numberField.error.REQUIRED" | "phoneField.error.INVALID_COUNTRY" | "phoneField.error.INVALID_LENGTH" | "phoneField.error.INVALID_NUMBER" | "phoneField.error.NOT_A_NUMBER" | "phoneField.error.REQUIRED" | "phoneField.error.REQUIRED_COUNTRY" | "phoneField.error.TOO_LONG" | "phoneField.error.TOO_SHORT" | "phoneField.error.undefined" | "schedule.label.active" | "schedule.label.allDay" | "schedule.label.day" | "search.placeholder" | "select.loadingMessage" | "select.noOptionsMessage" | "urlField.error.INVALID_URL" | "urlField.error.REQUIRED">, import("i18next").i18n, boolean] & {
-    t: TransForLibs<"baseInput.copyAction.toolTip" | "clearIndicator.icon.tooltip.clearAll" | "colorField.error.INVALID_HEX_CODE" | "colorField.error.REQUIRED" | "colorField.tooltip" | "dateField.actions.apply" | "dateField.actions.cancel" | "dateField.actions.clear" | "dateField.placeholder" | "dropzone.input.title" | "dropzone.label.default" | "emailField.error.INVALID_EMAIL" | "emailField.error.REQUIRED" | "field.notEditable.tooltip" | "field.required.asterisk.tooltip" | "numberField.error.GREATER_THAN" | "numberField.error.INVALID_NUMBER" | "numberField.error.LESS_THAN" | "numberField.error.NOT_IN_BETWEEN" | "numberField.error.REQUIRED" | "phoneField.error.INVALID_COUNTRY" | "phoneField.error.INVALID_LENGTH" | "phoneField.error.INVALID_NUMBER" | "phoneField.error.NOT_A_NUMBER" | "phoneField.error.REQUIRED" | "phoneField.error.REQUIRED_COUNTRY" | "phoneField.error.TOO_LONG" | "phoneField.error.TOO_SHORT" | "phoneField.error.undefined" | "schedule.label.active" | "schedule.label.allDay" | "schedule.label.day" | "search.placeholder" | "select.loadingMessage" | "select.noOptionsMessage" | "urlField.error.INVALID_URL" | "urlField.error.REQUIRED">;
+export declare const useTranslation: () => [TransForLibs<"baseInput.copyAction.toolTip" | "clearIndicator.icon.tooltip.clearAll" | "colorField.error.INVALID_HEX_CODE" | "colorField.error.REQUIRED" | "colorField.tooltip" | "dateField.actions.apply" | "dateField.actions.cancel" | "dateField.actions.clear" | "dateField.openPicker.ariaLabel" | "dropzone.input.title" | "dropzone.label.default" | "emailField.error.INVALID_EMAIL" | "emailField.error.REQUIRED" | "field.notEditable.tooltip" | "field.required.asterisk.tooltip" | "numberField.error.GREATER_THAN" | "numberField.error.INVALID_NUMBER" | "numberField.error.LESS_THAN" | "numberField.error.NOT_IN_BETWEEN" | "numberField.error.REQUIRED" | "phoneField.error.INVALID_COUNTRY" | "phoneField.error.INVALID_LENGTH" | "phoneField.error.INVALID_NUMBER" | "phoneField.error.NOT_A_NUMBER" | "phoneField.error.REQUIRED" | "phoneField.error.REQUIRED_COUNTRY" | "phoneField.error.TOO_LONG" | "phoneField.error.TOO_SHORT" | "phoneField.error.undefined" | "schedule.label.active" | "schedule.label.allDay" | "schedule.label.day" | "search.placeholder" | "select.loadingMessage" | "select.noOptionsMessage" | "urlField.error.INVALID_URL" | "urlField.error.REQUIRED">, import("i18next").i18n, boolean] & {
+    t: TransForLibs<"baseInput.copyAction.toolTip" | "clearIndicator.icon.tooltip.clearAll" | "colorField.error.INVALID_HEX_CODE" | "colorField.error.REQUIRED" | "colorField.tooltip" | "dateField.actions.apply" | "dateField.actions.cancel" | "dateField.actions.clear" | "dateField.openPicker.ariaLabel" | "dropzone.input.title" | "dropzone.label.default" | "emailField.error.INVALID_EMAIL" | "emailField.error.REQUIRED" | "field.notEditable.tooltip" | "field.required.asterisk.tooltip" | "numberField.error.GREATER_THAN" | "numberField.error.INVALID_NUMBER" | "numberField.error.LESS_THAN" | "numberField.error.NOT_IN_BETWEEN" | "numberField.error.REQUIRED" | "phoneField.error.INVALID_COUNTRY" | "phoneField.error.INVALID_LENGTH" | "phoneField.error.INVALID_NUMBER" | "phoneField.error.NOT_A_NUMBER" | "phoneField.error.REQUIRED" | "phoneField.error.REQUIRED_COUNTRY" | "phoneField.error.TOO_LONG" | "phoneField.error.TOO_SHORT" | "phoneField.error.undefined" | "schedule.label.active" | "schedule.label.allDay" | "schedule.label.day" | "search.placeholder" | "select.loadingMessage" | "select.noOptionsMessage" | "urlField.error.INVALID_URL" | "urlField.error.REQUIRED">;
     i18n: import("i18next").i18n;
     ready: boolean;
 };

package/src/utilities/parseDateFieldValue.d.ts

@@ -7,6 +7,35 @@
  * @returns {Date | null} - Date at local midnight for the given day, or null if value is empty or invalid
  */
 export declare function parseDateFieldValue(value: string): Date | null;
+/**
+ * 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"`.
+ */
+export declare function resolveDateFieldLocale(locale: string | undefined): string;
+/**
+ * Returns the locale-aligned placeholder shown in the DateField. Result is memoized per locale —
+ * see `datePlaceholderByLocale` above.
+ */
+export declare function getDateFieldPlaceholder(locale: string): string;
+/**
+ * Formats a Date for display in the DateField while keeping event payloads canonical.
+ */
+export declare function formatDateFieldValueForLocale(value: Date, locale: string): string;
+/**
+ * Parses localized or quick-typed DateField input into a Date.
+ * Supports canonical YYYY-MM-DD, locale-ordered quick typing (e.g. DDMMYYYY), and YYYYMMDD.
+ */
+export declare function parseDateFieldDisplayValue(value: string, locale: string): Date | null;
 /**
  * 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

package/src/utilities/useCreateInputChangeEvent.d.ts

@@ -1,4 +1,4 @@
-import { type ChangeEvent } from "react";
+import { type ChangeEvent, type FocusEvent } from "react";
 /**
  * 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
@@ -9,3 +9,13 @@ import { type ChangeEvent } from "react";
  * onChange?.(createInputChangeEvent(str, inputRef.current));
  */
 export declare const useCreateInputChangeEvent: () => ((value: string, sourceInput: HTMLInputElement | null) => ChangeEvent<HTMLInputElement>);
+/**
+ * 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));
+ */
+export declare const useCreateInputBlurEvent: () => ((value: string, sourceInput: HTMLInputElement | null) => FocusEvent<HTMLInputElement>);

package/src/utilities/useDateFieldLocale.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export declare const useDateFieldLocale: () => string;