@mercury-fx/core 2.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonnify <mercury@jonnify.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @mercury-fx/core
+
+The UI-free foundation of the **Mercury** design system: a class utility (`cx`),
+locale-aware date formatters, headless behaviour hooks, and the shared type kit.
+No React components, no styles.
+
+Most consumers get this package **transitively** through
+[`@mercury-fx/ui`](https://www.npmjs.com/package/@mercury-fx/ui) — install it
+directly only if you want the bare utilities.
+
+## Install
+
+```bash
+npm i @mercury-fx/core react      # react is a peer dependency
+```
+
+## Use
+
+```ts
+import { cx, createFormatter } from "@mercury-fx/core";
+
+cx("btn", isActive && "btn--active");   // conditional classNames
+const fmt = createFormatter("en-US");   // locale-aware Intl wrapper
+```
+
+Ships as a single ES-module bundle (`dist/mercury-core.js`) with type
+declarations. `react` and `@internationalized/date` are kept external (a peer and
+a runtime dependency, respectively).
+
+## License
+
+MIT

package/dist/cx.d.ts

@@ -0,0 +1,3 @@
+export type ClassValue = string | false | null | undefined;
+/** Tiny classNames join — filters falsy, joins with spaces. */
+export declare function cx(...parts: ClassValue[]): string;

package/dist/date.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@mercury-fx/ui` date utilities — the locale-aware formatters that back the date
+ * field / calendar components, surfaced for app and `@mercury-fx/effector` use.
+ * Pure (no React, no Effector); for reactive store wiring see
+ * `@mercury-fx/effector`'s `createFormatterModel`.
+ */
+export { createFormatter, createTimeFormatter, type Formatter, type TimeFormatter, type FormatterOptions, type TimeFormatterOptions, type MonthFormat, type YearFormat, type DayPeriodValue, type MaybeReadable, type Readable, } from './internal/date-time/formatter';

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @mercury-fx/core — Mercury's UI-free foundation.
+ *
+ * The layer that sits below `@mercury-fx/ui` and `@mercury-fx/effector`: the class
+ * utility, the locale-aware date formatters, and (in `internal/`, `shared/`,
+ * `utils/`, `types`) the headless hooks and shared types the components build
+ * on. No React components, no styles. Published as a bundled ES module
+ * (`dist/mercury-core.js`) with type declarations; the apps resolve it from
+ * source via a vite/tsconfig alias in dev.
+ *
+ * This barrel surfaces what crosses the package boundary today: `cx` (consumed
+ * by every component) and the `date` formatters (re-exported by `@mercury-fx/ui`
+ * for app and `@mercury-fx/effector` use). The deeper foundation lives here as
+ * files and is surfaced as consumers need it.
+ */
+export { cx } from './cx';
+export type { ClassValue } from './cx';
+export * from './date';
+export { useDateField } from './internal/date-time/field/use-date-field';
+export type { UseDateFieldOptions, UseDateFieldReturn } from './internal/date-time/field/use-date-field';
+export type { DateValue } from '@internationalized/date';
+export { CalendarDate, parseDate } from '@internationalized/date';
+export { useCalendar } from './internal/date-time/calendar/use-calendar';
+export type { UseCalendarOptions, UseCalendarReturn, CalendarCell, CalendarCellProps, CalendarNavProps } from './internal/date-time/calendar/use-calendar';
+export { useFocusTrap } from './internal/use-focus-trap';
+export type { UseFocusTrapOptions } from './internal/use-focus-trap';
+export { useDismiss } from './internal/use-dismiss';
+export type { UseDismissOptions } from './internal/use-dismiss';
+export { useAnchoredPosition } from './internal/use-anchored-position';
+export type { UseAnchoredPositionOptions, UseAnchoredPositionReturn, AnchoredPlacement, AnchoredAlign, AnchoredPoint, } from './internal/use-anchored-position';
+export { useId } from './internal/use-id';
+export { useArrowNavigation } from './internal/use-arrow-navigation';

package/dist/internal/arrays.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Checks if two arrays are equal by comparing their values.
+ */
+export declare function arraysAreEqual<T extends Array<unknown>>(arr1: T, arr2: T): boolean;
+/**
+ * Splits an array into chunks of a given size.
+ * @param arr The array to split.
+ * @param size The size of each chunk.
+ * @returns An array of arrays, where each sub-array has `size` elements from the original array.
+ * @example ```ts
+ * const arr = [1, 2, 3, 4, 5, 6, 7, 8];
+ * const chunks = chunk(arr, 3);
+ * // chunks = [[1, 2, 3], [4, 5, 6], [7, 8]]
+ * ```
+ */
+export declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * Checks if the given index is valid for the given array.
+ *
+ * @param index - The index to check
+ * @param arr - The array to check
+ */
+export declare function isValidIndex(index: number, arr: unknown[]): boolean;
+/**
+ * Returns the array element after the given index, or undefined for out-of-bounds or empty arrays.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the beginning of the array if the next index is out of bounds?
+ */
+/**
+ * Returns the array element after the given index, or undefined for out-of-bounds or empty arrays.
+ * For single-element arrays, returns the element if the index is 0.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the beginning of the array if the next index is out of bounds?
+ */
+export declare function next<T>(array: T[], index: number, loop?: boolean): T | undefined;
+/**
+ * Returns the array element prior to the given index, or undefined for out-of-bounds or empty arrays.
+ * For single-element arrays, returns the element if the index is 0.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param loop loop to the end of the array if the previous index is out of bounds?
+ */
+export declare function prev<T>(array: T[], index: number, loop?: boolean): T | undefined;
+/**
+ * Returns the element some number after the given index. If the target index is out of bounds:
+ *   - If looping is disabled, the first or last element will be returned.
+ *   - If looping is enabled, it will wrap around the array.
+ * Returns undefined for empty arrays or out-of-bounds initial indices.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param increment the number of elements to move forward (can be negative).
+ * @param loop loop around the array if the target index is out of bounds?
+ */
+export declare function forward<T>(array: T[], index: number, increment: number, loop?: boolean): T | undefined;
+/**
+ * Returns the element some number before the given index. If the target index is out of bounds:
+ *   - If looping is disabled, the first or last element will be returned.
+ *   - If looping is enabled, it will wrap around the array.
+ * Returns undefined for empty arrays or out-of-bounds initial indices.
+ * @param array the array.
+ * @param index the index of the current element.
+ * @param decrement the number of elements to move backward (can be negative).
+ * @param loop loop around the array if the target index is out of bounds?
+ */
+export declare function backward<T>(array: T[], index: number, decrement: number, loop?: boolean): T | undefined;
+/**
+ * Finds the next matching item from a list of values based on a search string.
+ *
+ * This function handles several special cases in typeahead behavior:
+ *
+ * 1. Space handling: When a search string ends with a space, it handles it specially:
+ *    - If there's only one match for the text before the space, it ignores the space
+ *    - If there are multiple matches and the current match already starts with the search prefix
+ *      followed by a space, it keeps the current match (doesn't change selection on space)
+ *    - Only after typing characters beyond the space will it move to a more specific match
+ *
+ * 2. Repeated character handling: If a search consists of repeated characters (e.g., "aaa"),
+ *    it treats it as a single character for matching purposes
+ *
+ * 3. Cycling behavior: The function wraps around the values array starting from the current match
+ *    to find the next appropriate match, creating a cycling selection behavior
+ *
+ * @param values - Array of string values to search through (e.g., the text content of menu items)
+ * @param search - The current search string typed by the user
+ * @param currentMatch - The currently selected/matched item, if any
+ * @returns The next matching value that should be selected, or undefined if no match is found
+ */
+export declare function getNextMatch(values: string[], search: string, currentMatch?: string): string | undefined;
+/**
+ * Wraps an array around itself at a given start index
+ * Example: `wrapArray(['a', 'b', 'c', 'd'], 2) === ['c', 'd', 'a', 'b']`
+ */
+export declare function wrapArray<T>(array: T[], startIndex: number): T[];

package/dist/internal/attrs.d.ts

@@ -0,0 +1,33 @@
+export declare function boolToStr(condition: boolean): "true" | "false";
+export declare function boolToStrTrueOrUndef(condition: boolean): "true" | undefined;
+export declare function boolToEmptyStrOrUndef(condition: boolean): "" | undefined;
+export declare function boolToTrueOrUndef(condition: boolean): true | undefined;
+export declare function getDataOpenClosed(condition: boolean): "open" | "closed";
+export declare function getDataChecked(condition: boolean): "checked" | "unchecked";
+export type TransitionState = "starting" | "ending" | "idle" | undefined;
+export declare function getDataTransitionAttrs(state: TransitionState): {
+    "data-starting-style"?: "";
+    "data-ending-style"?: "";
+};
+export declare function getAriaChecked(checked: boolean, indeterminate: boolean): "true" | "false" | "mixed";
+export type BitsAttrsConfig<T extends readonly string[]> = {
+    component: string;
+    parts: T;
+    getVariant?: () => string | null;
+};
+export type CreateBitsAttrsReturn<T extends readonly string[]> = {
+    [K in T[number]]: string;
+} & {
+    selector: (part: T[number]) => string;
+    getAttr: (part: T[number], variant?: string) => string;
+};
+export declare class BitsAttrs<T extends readonly string[]> {
+    #private;
+    attrs: Record<T[number], string>;
+    constructor(config: BitsAttrsConfig<T>);
+    getAttr(part: T[number], variantOverride?: string): string;
+    selector(part: T[number], variantOverride?: string): string;
+}
+export declare function createBitsAttrs<const T extends readonly string[]>(config: Omit<BitsAttrsConfig<T>, "parts"> & {
+    parts: T;
+}): CreateBitsAttrsReturn<T>;

package/dist/internal/clamp.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Clamps a number between a minimum and maximum value.
+ */
+export declare function clamp(n: number, min: number, max: number): number;

package/dist/internal/create-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates a unique ID for a given uid and optional prefix.
+ *
+ * @param uid - the uid generated by $props.id()
+ * @param prefix - optional prefix to use for the id (defaults to "bits")
+ */
+export declare function createId(uid: string): string;
+export declare function createId(prefix: string, uid: string): string;

package/dist/internal/css-escape.d.ts

@@ -0,0 +1,7 @@
+/**
+ * https://github.com/mathiasbynens/CSS.escape
+ *
+ * @param value - The value to escape for use as a CSS identifier
+ * @returns The escaped CSS identifier string
+ */
+export declare function cssEscape(value: string): string;

package/dist/internal/date-time/calendar/use-calendar.d.ts

@@ -0,0 +1,63 @@
+import { DateValue } from '@internationalized/date';
+/** Options for {@link useCalendar}. */
+export type UseCalendarOptions = {
+    /** Controlled selected day. */
+    value?: DateValue;
+    /** Uncontrolled initial selected day. */
+    defaultValue?: DateValue;
+    /** Fires when a day is chosen. */
+    onChange?: (value: DateValue) => void;
+    /** BCP-47 locale for the month/weekday labels + week ordering. Default "en". */
+    locale?: string;
+    /** First column of the week, 0=Sun .. 6=Sat. Default 0. */
+    firstDayOfWeek?: number;
+};
+/** Props spread onto a single day cell. */
+export interface CalendarCellProps {
+    role: "gridcell";
+    "aria-selected": boolean;
+    "aria-label": string;
+    tabIndex: number;
+    onClick: () => void;
+}
+/** One rendered day in the month grid. */
+export interface CalendarCell {
+    date: DateValue;
+    label: string;
+    isSelected: boolean;
+    isToday: boolean;
+    isOutsideMonth: boolean;
+    cellProps: CalendarCellProps;
+}
+/** Props for a prev/next month navigation control. */
+export interface CalendarNavProps {
+    onClick: () => void;
+    "aria-label": string;
+}
+/** Return shape of {@link useCalendar}. */
+export interface UseCalendarReturn {
+    /** Localized "month year" header, e.g. "March 2024". */
+    monthLabel: string;
+    /** Seven localized weekday headers, in `firstDayOfWeek` order. */
+    weekdays: string[];
+    /** The 42 grid cells (6 weeks) for the visible month. */
+    cells: CalendarCell[];
+    /** Props for the grid container. */
+    gridProps: {
+        role: "grid";
+        "aria-label": string;
+    };
+    /** The current selected value (controlled or uncontrolled). */
+    selected: DateValue | undefined;
+    /** Props for the previous-month control. */
+    prevButtonProps: CalendarNavProps;
+    /** Props for the next-month control. */
+    nextButtonProps: CalendarNavProps;
+}
+/**
+ * Headless month-grid calendar composable. Composes the owned `internal/date-time`
+ * machinery (locale formatter, week alignment, value conversion) over
+ * `@internationalized/date` values; the only new logic is the grid assembly and
+ * month paging. Presentational-ready: spread the cell/nav prop kits.
+ */
+export declare function useCalendar(options?: UseCalendarOptions): UseCalendarReturn;

package/dist/internal/date-time/field/helpers.d.ts

@@ -0,0 +1,86 @@
+import { DateValue } from '@internationalized/date';
+import { Formatter } from '../../..internal/date-time/formatter.js';
+import { DateAndTimeSegmentObj, DateSegmentPart, EditableSegmentPart, SegmentContentObj, SegmentPart, SegmentStateMap, SegmentValueObj } from './types.js';
+import { Granularity, HourCycle } from '../../..shared/date/types.js';
+export declare function initializeSegmentValues(granularity: Granularity): SegmentValueObj;
+type SharedContentProps = {
+    granularity: Granularity;
+    dateRef: DateValue;
+    formatter: Formatter;
+    hideTimeZone: boolean;
+    hourCycle: HourCycle | undefined;
+};
+type CreateContentObjProps = SharedContentProps & {
+    segmentValues: SegmentValueObj;
+    locale: string;
+};
+type CreateContentProps = CreateContentObjProps;
+export declare function createContent(props: CreateContentProps): {
+    obj: SegmentContentObj;
+    arr: {
+        part: SegmentPart;
+        value: string;
+    }[];
+};
+export declare function initSegmentStates(): SegmentStateMap;
+export declare function initSegmentIds(): any;
+export declare function isDateSegmentPart(part: unknown): part is DateSegmentPart;
+export declare function isSegmentPart(part: string): part is EditableSegmentPart;
+export declare function isAnySegmentPart(part: unknown): part is SegmentPart;
+type GetValueFromSegments = {
+    segmentObj: SegmentValueObj;
+    fieldNode: HTMLElement | null;
+    dateRef: DateValue;
+};
+export declare function getValueFromSegments(props: GetValueFromSegments): DateValue;
+/**
+ * Check if all the segments being used have been filled.
+ * We use this to determine when we should set the value
+ * store of the date field(s).
+ *
+ * @param segmentValues - The current `SegmentValueObj`
+ * @param fieldNode  - The id of the date field
+ */
+export declare function areAllSegmentsFilled(segmentValues: SegmentValueObj, fieldNode: HTMLElement | null): boolean;
+/**
+ * Determines if the provided object is a valid `DateAndTimeSegmentObj`
+ * by checking if it has the correct keys and values for each key.
+ */
+export declare function isDateAndTimeSegmentObj(obj: unknown): obj is DateAndTimeSegmentObj;
+/**
+ * Infer the granularity to use based on the
+ * value and granularity props.
+ */
+export declare function inferGranularity(value: DateValue, granularity: Granularity | undefined): Granularity;
+export declare function isAcceptableSegmentKey(key: string): boolean;
+/**
+ * Determines if the element with the provided id is the first focusable
+ * segment in the date field with the provided fieldId.
+ *
+ * @param id - The id of the element to check if it's the first segment
+ * @param fieldNode - The id of the date field associated with the segment
+ */
+export declare function isFirstSegment(id: string, fieldNode: HTMLElement | null): boolean;
+type SetDescriptionProps = {
+    id: string;
+    formatter: Formatter;
+    value: DateValue;
+    doc: Document;
+};
+/**
+ * Creates or updates a description element for a date field
+ * which enables screen readers to read the date field's value.
+ *
+ * This element is hidden from view, and is portalled to the body
+ * so it can be associated via `aria-describedby` and read by
+ * screen readers as the user interacts with the date field.
+ */
+export declare function setDescription(props: SetDescriptionProps): void;
+/**
+ * Removes the description element for the date field with
+ * the provided ID. This function should be called when the
+ * date field is unmounted.
+ */
+export declare function removeDescriptionElement(id: string, doc: Document): void;
+export declare function getDefaultHourCycle(locale: string): 12 | 24;
+export {};

package/dist/internal/date-time/field/parts.d.ts

@@ -0,0 +1,8 @@
+export declare const DATE_SEGMENT_PARTS: readonly ["day", "month", "year"];
+export declare const EDITABLE_TIME_SEGMENT_PARTS: readonly ["hour", "minute", "second", "dayPeriod"];
+export declare const NON_EDITABLE_SEGMENT_PARTS: readonly ["literal", "timeZoneName"];
+export declare const EDITABLE_SEGMENT_PARTS: readonly ["day", "month", "year", "hour", "minute", "second", "dayPeriod"];
+export declare const ALL_SEGMENT_PARTS: readonly ["day", "month", "year", "hour", "minute", "second", "dayPeriod", "literal", "timeZoneName"];
+export declare const ALL_TIME_SEGMENT_PARTS: readonly ["hour", "minute", "second", "dayPeriod", "literal", "timeZoneName"];
+export declare const ALL_EXCEPT_LITERAL_PARTS: ("day" | "month" | "year" | "hour" | "minute" | "second" | "dayPeriod" | "timeZoneName")[];
+export declare const ALL_TIME_EXCEPT_LITERAL_PARTS: ("hour" | "minute" | "second" | "dayPeriod" | "timeZoneName")[];

package/dist/internal/date-time/field/segments.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Handles segment navigation based on the provided keyboard event and field ID.
+ *
+ * @param e - The keyboard event
+ * @param fieldNode - The ID of the field we're navigating within
+ */
+export declare function handleSegmentNavigation(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+export declare function handleTimeSegmentNavigation(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+/**
+ * Retrieves the next segment in the list of segments relative to the provided node.
+ *
+ * @param node - The node we're starting from
+ * @param segments - The list of candidate segments to navigate through
+ */
+export declare function getNextSegment(node: HTMLElement, segments: HTMLElement[]): HTMLElement | null | undefined;
+/**
+ * Retrieves the previous segment in the list of segments relative to the provided node.
+ *
+ * @param node - The node we're starting from
+ * @param segments - The list of candidate segments to navigate through
+ */
+export declare function getPrevSegment(node: HTMLElement, segments: HTMLElement[]): HTMLElement | null | undefined;
+/**
+ * Retrieves an object containing the next and previous segments relative to the current node.
+ *
+ * @param startingNode - The node we're starting from
+ * @param fieldNode - The ID of the field we're navigating within
+ */
+export declare function getPrevNextSegments(startingNode: HTMLElement, fieldNode: HTMLElement | null): {
+    next: HTMLElement | null | undefined;
+    prev: HTMLElement | null | undefined;
+};
+export declare function getPrevNextTimeSegments(startingNode: HTMLElement, fieldNode: HTMLElement | null): {
+    next: HTMLElement | null | undefined;
+    prev: HTMLElement | null | undefined;
+};
+/**
+ * Shifts the focus to the next segment in the list of segments
+ * within the field identified by the provided ID.
+ */
+export declare function moveToNextSegment(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+export declare function moveToNextTimeSegment(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+export declare function moveToPrevTimeSegment(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+/**
+ * Shifts the focus to the previous segment in the list of segments
+ * within the field identified by the provided ID. If this is the first
+ * segment, focus will not be shifted.
+ */
+export declare function moveToPrevSegment(e: KeyboardEvent, fieldNode: HTMLElement | null): void;
+export declare function isSegmentNavigationKey(key: string): boolean;
+/**
+ * Retrieves all the interactive segments within the field identified by the provided ID.
+ */
+export declare function getSegments(fieldNode: HTMLElement | null): HTMLElement[];
+export declare function getTimeSegments(fieldNode: HTMLElement | null): HTMLElement[];
+export declare function getFirstTimeSegment(fieldNode: HTMLElement | null): HTMLElement | undefined;
+/**
+ * Get the first interactive segment within the field identified by the provided ID.
+ */
+export declare function getFirstSegment(fieldNode: HTMLElement | null): HTMLElement | undefined;

package/dist/internal/date-time/field/time-helpers.d.ts

@@ -0,0 +1,82 @@
+import { EditableTimeSegmentPart, HourCycle, TimeGranularity, TimeSegmentContentObj, TimeSegmentStateMap, TimeSegmentValueObj, TimeValue } from '../../..shared/date/types.js';
+import { Time } from '@internationalized/date';
+import { TimeFormatter } from '../../..internal/date-time/formatter.js';
+import { TimeSegmentPart } from './types.js';
+export declare function initializeSegmentValues(): TimeSegmentValueObj;
+type SharedTimeContentProps = {
+    granularity: TimeGranularity;
+    timeRef: TimeValue;
+    formatter: TimeFormatter;
+    hideTimeZone: boolean;
+    hourCycle: HourCycle | undefined;
+};
+type CreateTimeContentObjProps = SharedTimeContentProps & {
+    segmentValues: TimeSegmentValueObj;
+    locale: string;
+};
+type CreateTimeContentProps = CreateTimeContentObjProps;
+export declare function createTimeContent(props: CreateTimeContentProps): {
+    obj: TimeSegmentContentObj;
+    arr: {
+        part: TimeSegmentPart;
+        value: string;
+    }[];
+};
+export declare function initTimeSegmentStates(): TimeSegmentStateMap;
+export declare function initTimeSegmentIds(): any;
+export declare function isEditableTimeSegmentPart(part: unknown): part is EditableTimeSegmentPart;
+export declare function isAnyTimeSegmentPart(part: unknown): part is TimeSegmentPart;
+type GetTimeValueFromSegments<T extends TimeValue = Time> = {
+    segmentObj: TimeSegmentValueObj;
+    fieldNode: HTMLElement | null;
+    timeRef: T;
+};
+export declare function getTimeValueFromSegments<T extends TimeValue = Time>(props: GetTimeValueFromSegments<T>): T;
+/**
+ * Check if all the segments being used have been filled.
+ * We use this to determine when we should set the value
+ * store of the date field(s).
+ *
+ * @param segmentValues - The current `SegmentValueObj`
+ * @param fieldNode  - The id of the date field
+ */
+export declare function areAllTimeSegmentsFilled(segmentValues: TimeSegmentValueObj, fieldNode: HTMLElement | null): boolean;
+/**
+ * Infer the granularity to use based on the
+ * value and granularity props.
+ */
+export declare function inferTimeGranularity(granularity: TimeGranularity | undefined): TimeGranularity;
+/**
+ * Determines if the element with the provided id is the first focusable
+ * segment in the date field with the provided fieldId.
+ *
+ * @param id - The id of the element to check if it's the first segment
+ * @param fieldNode - The id of the date field associated with the segment
+ */
+export declare function isFirstTimeSegment(id: string, fieldNode: HTMLElement | null): boolean;
+type SetTimeDescriptionProps = {
+    id: string;
+    formatter: TimeFormatter;
+    value: TimeValue;
+    doc: Document;
+};
+/**
+ * Creates or updates a description element for a date field
+ * which enables screen readers to read the date field's value.
+ *
+ * This element is hidden from view, and is portalled to the body
+ * so it can be associated via `aria-describedby` and read by
+ * screen readers as the user interacts with the date field.
+ */
+export declare function setTimeDescription(props: SetTimeDescriptionProps): void;
+/**
+ * Removes the description element for the date field with
+ * the provided ID. This function should be called when the
+ * date field is unmounted.
+ */
+export declare function removeTimeDescriptionElement(id: string, doc: Document): void;
+export { convertTimeValueToDateValue } from '../../..internal/date-time/time-value.js';
+export declare function convertTimeValueToTime(time: TimeValue): Time;
+export declare function isTimeBefore(timeToCompare: Time, referenceTime: Time): boolean;
+export declare function isTimeAfter(timeToCompare: Time, referenceTime: Time): boolean;
+export declare function getISOTimeValue(time: TimeValue): string;

package/dist/internal/date-time/field/types.d.ts

@@ -0,0 +1,25 @@
+import { DATE_SEGMENT_PARTS, EDITABLE_SEGMENT_PARTS, NON_EDITABLE_SEGMENT_PARTS, EDITABLE_TIME_SEGMENT_PARTS } from './parts.js';
+export type DateSegmentPart = (typeof DATE_SEGMENT_PARTS)[number];
+export type TimeSegmentPart = (typeof EDITABLE_TIME_SEGMENT_PARTS)[number];
+export type EditableSegmentPart = (typeof EDITABLE_SEGMENT_PARTS)[number];
+export type NonEditableSegmentPart = (typeof NON_EDITABLE_SEGMENT_PARTS)[number];
+export type SegmentPart = EditableSegmentPart | NonEditableSegmentPart;
+export type AnyExceptLiteral = Exclude<SegmentPart, "literal">;
+export type DayPeriod = "AM" | "PM" | null;
+export type DateSegmentObj = {
+    [K in DateSegmentPart]: string | null;
+};
+export type TimeSegmentObj = {
+    [K in TimeSegmentPart]: K extends "dayPeriod" ? DayPeriod : string | null;
+};
+export type DateAndTimeSegmentObj = DateSegmentObj & TimeSegmentObj;
+export type SegmentValueObj = DateSegmentObj | DateAndTimeSegmentObj;
+export type SegmentContentObj = Record<EditableSegmentPart, string>;
+export type SegmentState = {
+    lastKeyZero: boolean;
+    hasLeftFocus: boolean;
+    updating: string | null;
+};
+export type SegmentStateMap = {
+    [K in EditableSegmentPart]: SegmentState;
+};

package/dist/internal/date-time/field/use-date-field.d.ts

@@ -0,0 +1,61 @@
+import { KeyboardEvent, RefObject } from 'react';
+import { DateValue } from '@internationalized/date';
+/** Options for {@link useDateField}. */
+export type UseDateFieldOptions = {
+    /** Controlled value. When set, the hook reflects this value and reports edits via `onChange`. */
+    value?: DateValue;
+    /** Uncontrolled initial value — seeds the segments on first render. */
+    defaultValue?: DateValue;
+    /** Called with the reconstructed value when every editable segment is filled, or `undefined` otherwise. */
+    onChange?: (v: DateValue | undefined) => void;
+    /** BCP-47 locale that orders the segments and renders the literals. Defaults to `"en"`. */
+    locale?: string;
+    /** Granularity of the field. Date-only for this wave. */
+    granularity?: "day";
+};
+/** One rendered slot of the date field — an editable part or a literal separator. */
+export interface DateSegment {
+    part: string;
+    value: string;
+}
+/** Props for the field container element. */
+export interface FieldProps {
+    ref: RefObject<HTMLElement | null>;
+    role: "group";
+}
+/** Props for an editable segment (spinbutton) — spread onto the part element. */
+export interface EditableSegmentProps {
+    "data-segment": string;
+    role: "spinbutton";
+    inputMode: "numeric";
+    tabIndex: number;
+    "aria-label": string;
+    "aria-valuenow"?: number;
+    "aria-valuemin": number;
+    "aria-valuemax": number;
+    onKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+}
+/** Props for a literal (separator) segment. */
+export interface LiteralSegmentProps {
+    "data-segment": string;
+}
+/** The two segment shapes spread by {@link UseDateFieldReturn.segmentProps}. */
+export type SegmentProps = EditableSegmentProps | LiteralSegmentProps;
+/** Return shape of {@link useDateField}. */
+export interface UseDateFieldReturn {
+    /** Ordered render list — editable parts and literal separators, in locale order. */
+    segments: DateSegment[];
+    /** Props for the field container (carries the ref the machinery queries). */
+    fieldProps: FieldProps;
+    /** Props builder for a single segment, keyed by its part name. */
+    segmentProps: (part: string) => SegmentProps;
+    /** The current value — controlled value when set, else the reconstruction when all parts are filled. */
+    value: DateValue | undefined;
+}
+/**
+ * Headless date-field composable. Composes the owned `internal/date-time` machinery
+ * (segment seeding, locale formatter, content layout, value reconstruction, caret
+ * navigation) into a presentational-ready prop kit. The keyboard reducer is the only
+ * new logic; no native date math is hand-rolled.
+ */
+export declare function useDateField(options?: UseDateFieldOptions): UseDateFieldReturn;