` that aren't `contentEditable`, so a touch device's on-screen keyboard doesn't open for typing — on mobile, use the calendar popover to pick a date (desktop keyboard entry and the calendar both work fully). The APG patterns are implemented and unit-tested but **not yet screen-reader-audited**, and RTL arrow-key flipping isn't handled.
+- **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
+- **Whole-date shortcuts:** `t` today · `m`/`h` start/end of the entered month · `y`/`r` start/end of the year · `w`/`k` start/end of the week · `-` previous day · `=`/`+` next day.
+- **Calendar grid:** arrows move by day/week, `Home`/`End` to week start/end, `PageUp`/`PageDown` by month, `Shift`+`PageUp`/`PageDown` by year, `Enter`/`Space` selects. `Alt`+`↓` opens the calendar from the field.
## Props
-The tables below list props this variant **actually implements** for v1 (date granularity). A few props are part of the type surface — kept identical to the react-aria variant so a later swap is source-compatible — but aren't acted on yet; those are called out under [Proposed / not yet implemented](#proposed--not-yet-implemented).
-
### DateFieldProps
-| Prop | Type | Description |
-| ----------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `label` | `LocalizedString` | Field label |
-| `description` | `LocalizedString` | Helper text below the field |
-| `errorMessage` | `LocalizedString` | Error text; also sets the invalid state |
-| `value` / `defaultValue` | `DateValue \| null` | Controlled / uncontrolled value (`CalendarDate` at date granularity) |
-| `onChange` | `(v: DateValue \| null) => void` | Fires on a complete, valid value; `null` when cleared |
-| `isDisabled` / `isReadOnly` / `isInvalid` | `boolean` | State flags |
-| `isRequired` | `boolean` | Sets `aria-required` on the segments (no visual required indicator yet) |
-| `placeholderValue` | `DateValue` | Seeds unset segments (increment start + segment order) |
-| `autoFocus` | `boolean` | Focus the first segment on mount |
-| `locale` | `string` | BCP-47 locale override (defaults to the AppShell formatting locale) |
-| `name` | `string` | Emits a hidden `
` with the ISO value for form submission |
-| `firstDayOfWeek` | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale's week start for the `w`/`k` keyboard shortcuts; omit to follow the locale |
-| `aria-label` | `string` | Accessible name when there's no visible `label` (e.g. compact filters) |
-| `className` | `string` | Root element class |
-
-> `DateField` has no calendar, so `minValue` / `maxValue` / `isDateUnavailable` don't apply to it — they're honoured by `DatePicker` and `Calendar` below.
+| Prop | Type | Description |
+| -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
+| `value` / `defaultValue` | `DateValue \| null` | Controlled / uncontrolled value |
+| `onChange` | `(v: DateValue \| null) => void` | Fires when the value changes |
+| `onBlur` | `() => void` | Fires when focus leaves the whole segmented control |
+| `minValue` / `maxValue` | `DateValue` | Inclusive date range bounds |
+| `isDateUnavailable` | `(date: DateValue) => boolean` | Marks specific dates unavailable |
+| `isDisabled` | `boolean` | Disables interaction and form submission |
+| `isReadOnly` | `boolean` | Allows focus/navigation without editing |
+| `isRequired` | `boolean` | Marks the control required |
+| `isInvalid` | `boolean` | Adds invalid styling / `aria-invalid` to the segmented UI |
+| `placeholderValue` | `DateValue` | Seeds unset segments |
+| `autoFocus` | `boolean` | Focus the first segment on mount |
+| `locale` | `string` | BCP-47 locale override |
+| `name` | `string` | Emits a form value through the proxy input |
+| `id` | `string` | Proxy input id (use with external `
`). |
+| `firstDayOfWeek` | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts |
+| `aria-label` / `aria-labelledby` | `string` | Accessible name |
+| `aria-describedby` | `string` | IDs of description / error elements |
+| `className` | `string` | Root element class |
### DatePickerProps
All `DateFieldProps`, plus:
-| Prop | Type | Description |
-| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `minValue` / `maxValue` | `DateValue` | Earliest / latest selectable date in the calendar |
-| `isDateUnavailable` | `(date: DateValue) => boolean` | Mark individual dates unselectable (still keyboard-navigable) |
-| `firstDayOfWeek` | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Force the calendar's first column; omit to follow the locale |
-| `timeZone` | `string` | IANA timezone for resolving "today"; defaults to AppShell `timeZone` |
+| Prop | Type | Description |
+| ---------------- | ----------------------- | ----------------------------------- |
+| `timeZone` | `string` | IANA timezone for resolving "today" |
+| `firstDayOfWeek` | `"sun" \| "mon" \| ...` | Force the calendar's first column |
### CalendarProps
-The standalone calendar grid. It has no segmented input, so its surface is listed in full:
-
-| Prop | Type | Description |
-| -------------------------------------- | ------------------------------ | ------------------------------------------------------------- |
-| `value` / `defaultValue` | `DateValue \| null` | Controlled / uncontrolled selected date |
-| `onChange` | `(v: DateValue) => void` | Fires when a date is selected |
-| `minValue` / `maxValue` | `DateValue` | Earliest / latest selectable date |
-| `isDateUnavailable` | `(date: DateValue) => boolean` | Mark individual dates unselectable (still keyboard-navigable) |
-| `focusedValue` / `defaultFocusedValue` | `DateValue` | Controlled / initial focused (visible) date |
-| `onFocusChange` | `(date: CalendarDate) => void` | Fires when the focused date changes (arrows, month paging) |
-| `firstDayOfWeek` | `"sun" \| "mon" \| …` | Force the first column; omit to follow the locale |
-| `isDisabled` / `isReadOnly` | `boolean` | Disable the grid / prevent selection changes |
-| `timeZone` | `string` | IANA timezone for "today"; defaults to AppShell `timeZone` |
-| `locale` | `string` | BCP-47 locale override |
-| `aria-label` / `aria-labelledby` | `string` | Accessible name for the grid |
-| `className` | `string` | Root element class |
-
-### Proposed / not yet implemented
-
-Accepted by the prop types (for parity with the react-aria variant) but **not acted on** in this variant yet:
-
-| Prop | Type | Status |
-| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `granularity` | `"day" \| "hour" \| "minute" \| "second"` | Only `"day"` is supported (the default). Time granularities — and the `CalendarDateTime` / `ZonedDateTime` values they produce — are the tracked **DateTime fast-follow**; the calendar has no time selection yet. |
-| `hourCycle` | `12 \| 24` | No effect until time granularity lands (12h/24h only matters with an hour segment). |
-| `hideTimeZone` | `boolean` | Unused; only relevant to `ZonedDateTime` display (time granularity). |
-
-Only date granularity is supported in v1; DateTime support is planned for a later release.
+See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailable dates, focused date, locale, timezone, accessible naming, and className.
## Related
-- [Form](./form.md) — wrap date fields with validation
-- [Input](./input.md) — plain text input
-- [useTimeZone](../api/use-time-zone.md) — access the configured timezone consumed automatically by these components
-- [useResolvedLocale](../api/use-resolved-locale.md) — access the locale used for segment order and month names
+- [useTimeZone](../api/use-time-zone.md)
+- [useResolvedLocale](../api/use-resolved-locale.md)
diff --git a/examples/vite-app/src/pages/date-picker/page.tsx b/examples/vite-app/src/pages/date-picker/page.tsx
index b421d4e5..91961c13 100644
--- a/examples/vite-app/src/pages/date-picker/page.tsx
+++ b/examples/vite-app/src/pages/date-picker/page.tsx
@@ -1,10 +1,10 @@
-import { useState, type FormEvent } from "react";
+import { useState, type FormEvent, type ReactElement } from "react";
import {
Layout,
+ Field,
DateField,
DatePicker,
Calendar,
- Form,
Button,
useTimeZone,
parseDate,
@@ -14,6 +14,29 @@ import {
} from "@tailor-platform/app-shell";
import { CalendarDays } from "lucide-react";
+function DemoField({
+ id,
+ label,
+ description,
+ error,
+ children,
+}: {
+ id: string;
+ label: string;
+ description?: string;
+ error?: string;
+ children: ReactElement;
+}) {
+ return (
+
+ {label}
+ {children}
+ {description && {description} }
+ {error && {error} }
+
+ );
+}
+
const DatePickerPage = () => {
const tz = useTimeZone();
const [fieldValue, setFieldValue] = useState(null);
@@ -29,8 +52,8 @@ const DatePickerPage = () => {
const tomorrow = tz.today().add({ days: 1 });
const threeMonths = tz.today().add({ months: 3 });
- // Validation runs on submit; the DatePicker surfaces the message through its
- // own `errorMessage` / `isInvalid` props (it isn't a Base UI Field control).
+ // Validation runs on submit; the example uses AppShell's `Field` wiring so
+ // the date controls behave like the other form inputs in the library.
const handleDeliverySubmit = (e: FormEvent) => {
e.preventDefault();
if (!deliveryDate) {
@@ -72,19 +95,25 @@ const DatePickerPage = () => {
DateField
- setFieldValue(v as CalendarDate | null)}
- />
-
+ setFieldValue(v as CalendarDate | null)}
+ />
+
+
+
+
+
{fieldValue && (
@@ -99,30 +128,38 @@ const DatePickerPage = () => {
DatePicker
- setPickerValue(v as CalendarDate | null)}
- />
-
+ setPickerValue(v as CalendarDate | null)}
+ />
+
+
+ {
- const day = d.toDate(tz.value).getDay();
- return day === 0 || day === 6;
- }}
- />
-
+ {
+ const day = d.toDate(tz.value).getDay();
+ return day === 0 || day === 6;
+ }}
+ />
+
+
{pickerValue && (
@@ -136,31 +173,32 @@ const DatePickerPage = () => {
In a form (submit validation)
- Standard Form +{" "}
- Button. Submitting empty (or
- with a past date) triggers validation — the error surfaces through the DatePicker's
- own errorMessage /{" "}
- isInvalid props, and clears as
- soon as a valid date is picked.
+ Standard form submit with AppShell{" "}
+ Field wiring. Submitting empty
+ (or with a past date) marks the date picker invalid, and the error clears as soon as a
+ valid date is picked.
-
+
{confirmedDate && (
✓ Delivery scheduled for {confirmedDate}
@@ -177,9 +215,15 @@ const DatePickerPage = () => {
explicitly to force a specific start day regardless of locale.
-
+
+
+
+
+
@@ -189,9 +233,15 @@ const DatePickerPage = () => {
Locale (segment order + names)
-
+
+
+
+
+
diff --git a/packages/core/__snapshots__/src__components__date-field__date-field.test.tsx.snap b/packages/core/__snapshots__/src__components__date-field__date-field.test.tsx.snap
index 856ed2c5..dd087381 100644
--- a/packages/core/__snapshots__/src__components__date-field__date-field.test.tsx.snap
+++ b/packages/core/__snapshots__/src__components__date-field__date-field.test.tsx.snap
@@ -1,7 +1,7 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-exports[`snapshots > DateField 1`] = `""`;
+exports[`snapshots > DateField 1`] = `""`;
-exports[`snapshots > DateField — invalid with error 1`] = `""`;
+exports[`snapshots > DateField — manually labelled + described 1`] = `"Date Pick a date
Required
"`;
-exports[`snapshots > DatePicker — closed 1`] = `""`;
+exports[`snapshots > DatePicker — closed 1`] = `""`;
diff --git a/packages/core/src/components/date-field/date-field.test.tsx b/packages/core/src/components/date-field/date-field.test.tsx
index d5a95433..088d12a1 100644
--- a/packages/core/src/components/date-field/date-field.test.tsx
+++ b/packages/core/src/components/date-field/date-field.test.tsx
@@ -12,6 +12,7 @@ import {
isSameDay,
} from "@internationalized/date";
import { createAppShellWrapper } from "../../../tests/test-utils";
+import { Field } from "../field";
import { DateField, DatePicker } from "./date-field";
// This suite is the parity contract shared with the react-aria implementation:
@@ -42,65 +43,123 @@ function getEnabledCalendarCells() {
describe("snapshots", () => {
it("DateField", () => {
- const { container } = render(
+ Date
+
+ Pick a date
+ Required
+ ,
);
expect(container.innerHTML).toMatchSnapshot();
});
it("DatePicker — closed", () => {
- const { container } = render(
+ Date
+
+ Date
+ Pick a date
+ Required
+ ,
+ );
+
+ const group = screen.getByRole("group");
+ expect(group.getAttribute("aria-describedby")).toBe("date-help date-error");
+ expect(group.hasAttribute("data-invalid")).toBe(true);
+ expect(screen.getByText("Required")).toBeDefined();
+ });
+
+ it("integrates with Field.Root label + description wiring", async () => {
+ const user = userEvent.setup();
+ render(
+
+ Invoice date
+ Pick the invoice date
+ ,
+ );
+
+ const group = screen.getByRole("group", { name: "Invoice date" });
+ expect(group.getAttribute("aria-describedby")).toBeTruthy();
+ expect(screen.getByText("Pick the invoice date")).toBeDefined();
+
+ await user.click(screen.getByText("Invoice date"));
+ expect(document.activeElement?.getAttribute("role")).toBe("spinbutton");
+ });
+
+ it("inherits invalid state from Field.Root", () => {
+ render(
+
+ Invoice date
+ Required
+ ,
+ );
+
+ expect(screen.getByRole("group").hasAttribute("data-invalid")).toBe(true);
expect(screen.getByText("Required")).toBeDefined();
});
it("renders as disabled", () => {
- render( (locale === "ja" ? "日付" : "Date")} />);
- // default locale resolves to english
- expect(screen.getByText("Date")).toBeDefined();
- });
-
it("fires onChange once a complete date is typed across the segments", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
- render(elsewhere
,
);
@@ -198,7 +257,7 @@ describe("DateField", () => {
const onChange = vi.fn();
render(
<>
- elsewhere
,
);
@@ -224,7 +283,7 @@ describe("DateField", () => {
return (
<>
{
setV(nv as CalendarDate | null);
@@ -283,7 +342,7 @@ describe("DateField", () => {
it("auto-corrects an impossible day as soon as the year is complete (no blur)", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
- render(elsewhere
,
);
@@ -350,7 +409,7 @@ describe("DateField", () => {
const onChange = vi.fn();
render(
<>
- elsewhere
,
);
@@ -372,7 +431,7 @@ describe("DateField", () => {
const onChange = vi.fn();
render(
<>
- elsewhere
,
);
@@ -388,7 +447,7 @@ describe("DateField", () => {
it("clears a controlled DateField when the value is reset to null", () => {
const { rerender } = render(
{}}
/>,
@@ -396,14 +455,14 @@ describe("DateField", () => {
expect(screen.getByRole("spinbutton", { name: "day" }).textContent).toBe("15");
// Parent clears the field: value={null} is controlled-empty, not uncontrolled.
- rerender( {}} />);
+ rerender( {}} />);
expect(screen.getByRole("spinbutton", { name: "day" }).getAttribute("aria-valuetext")).toBe(
"Empty",
);
});
it("sets aria-required on the segments when isRequired", () => {
- render(elsewhere
,
);
@@ -588,7 +667,7 @@ describe("DateField keyboard shortcuts", () => {
it("expands a 2-digit year as soon as the year segment is left (still inside the field)", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
- render( {
const onChange = vi.fn();
render(
{
const onChange = vi.fn();
render(
{
it("flags a typed date before minValue invalid, but still emits it", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
- render( isSameDay(d, unavailable)}
onChange={onChange}
/>,
@@ -720,13 +799,12 @@ describe("DateField keyboard shortcuts", () => {
await user.keyboard("06122025"); // the unavailable 12 Jun 2025
await lastEmit(onChange, "2025-06-12");
expect(screen.getByRole("group").hasAttribute("data-invalid")).toBe(true);
- expect(screen.getByText("This date is unavailable.")).toBeDefined();
});
it("'/' commits the current segment and advances to the next ('1/' ⇒ month 01)", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
- render( true} />);
+ render( true} />);
await user.click(screen.getAllByRole("button")[0]);
await waitFor(() => expect(screen.getByRole("grid")).toBeDefined());
@@ -816,29 +894,61 @@ describe("DatePicker", () => {
expect(unavailable.length).toBeGreaterThan(0);
});
- it("renders error message when errorMessage is set", () => {
- render(
+ Ship date
+ Choose a ship date
+ ,
+ );
+
+ const group = screen.getByRole("group", { name: "Ship date" });
+ expect(group.getAttribute("aria-disabled")).toBe("true");
+ expect(group.getAttribute("aria-describedby")).toBeTruthy();
+
+ await user.click(screen.getByText("Ship date"));
+ expect(document.activeElement?.getAttribute("role")).not.toBe("spinbutton");
+ });
+
+ it("uses the Field.Root label for the popup dialog and calendar", async () => {
+ const user = userEvent.setup();
+ render(
+
+ Ship date
+ ,
+ );
+
+ await user.click(screen.getAllByRole("button")[0]);
+ expect(await screen.findByRole("dialog", { name: "Ship date" })).toBeDefined();
+ expect(screen.getByRole("grid", { name: "Ship date" })).toBeDefined();
});
it("clears a controlled DatePicker when the value is reset to null", () => {
const { rerender } = render(
{}}
/>,
);
expect(screen.getByRole("spinbutton", { name: "day" }).textContent).toBe("15");
- rerender( {}} />);
+ rerender( {}} />);
expect(screen.getByRole("spinbutton", { name: "day" }).getAttribute("aria-valuetext")).toBe(
"Empty",
);
});
it("localizes segment names and chrome from the AppShell locale (ja)", () => {
- render(elsewhere
+ ,
+ );
+
+ await user.click(screen.getAllByRole("button")[0]);
+ await waitFor(() => {
+ expect(document.activeElement?.closest('[role="grid"]')).not.toBeNull();
+ });
+
+ await user.click(screen.getByRole("button", { name: "elsewhere" }));
+ await waitFor(() => {
+ expect(onBlur).toHaveBeenCalledTimes(1);
+ });
+ });
+
// While the popover is open, focus is in the grid — the shortcuts move the
// highlight (like the arrows), and Enter confirms. This is the calendar path,
// not the segment path.
@@ -881,7 +1024,11 @@ describe("DatePicker keyboard", () => {
const user = userEvent.setup();
const onChange = vi.fn();
render(
- {
const onChange = vi.fn();
render(
`.
+ *
+ * Because of that, they also render a hidden **proxy input**.
+ *
+ * What the proxy input is:
+ * - a real `` and Base UI's `Field` / `Form` infrastructure need a
+ * concrete control element to point at / register
+ * - native validation bubbles should anchor near the date widget rather than at
+ * some unrelated off-screen element
+ *
+ * When rendered inside `Field.Root`, the proxy input is also bridged into Base
+ * UI's field/form wiring so `Field.Label`, `Field.Description`, `Field.Error`,
+ * and form error routing work the same way they do for the other AppShell form
+ * controls.
*/
-// Built-in validation message key for a field's invalid reason (null = none, so
-// the consumer's `errorMessage` — or no message — stands). A lookup rather than
-// a nested ternary keeps the lint happy.
function invalidMessageKey(
- reason: DateFieldInvalidReason | null | undefined,
+ reason: "range" | "unavailable" | null | undefined,
): "dateUnavailable" | "dateOutOfRange" | null {
if (reason === "unavailable") return "dateUnavailable";
if (reason === "range") return "dateOutOfRange";
return null;
}
-// ─── Small controlled-state helper ────────────────────────────────────────────
+function assignRef(ref: Ref | undefined, value: T | null) {
+ if (!ref) return;
+ if (typeof ref === "function") {
+ ref(value);
+ return;
+ }
+ ref.current = value;
+}
+
+/**
+ * Produces the ref callback used by the hidden proxy input.
+ *
+ * The proxy input has two distinct consumers:
+ * - Base UI field/form internals, which need the DOM node to register the
+ * control, run validation, and focus it from `Field.Label`
+ * - the component's forwarded `ref`, so consumers can still receive the input
+ * element exposed by `DateField` / `DatePicker`
+ *
+ * It also applies the current custom validity message to the DOM node via
+ * `setCustomValidity()`. That imperative step must happen on the actual
+ * ` | undefined,
+ forwardedRef: Ref | undefined,
+ customValidity: string,
+) {
+ return useCallback(
+ (node: HTMLInputElement | null) => {
+ if (node) node.setCustomValidity(customValidity);
+ assignRef(fieldRef, node);
+ assignRef(forwardedRef, node);
+ },
+ [customValidity, fieldRef, forwardedRef],
+ );
+}
+
function useControlledState(
controlled: V | undefined,
defaultValue: V,
@@ -57,101 +127,297 @@ function useControlledState(
return [value, set];
}
-// ─── Shared prop types (names unchanged from react-aria) ──────────────────────
+function isSameDateValue(a: DateValue | null | undefined, b: DateValue | null | undefined) {
+ if (a == null || b == null) return a == null && b == null;
+ return a.compare(b as never) === 0;
+}
-interface DateFieldMetaProps {
- label?: LocalizedString;
- description?: LocalizedString;
- errorMessage?: LocalizedString;
- className?: string;
+function isTargetWithin(
+ target: EventTarget | null,
+ ref: RefObject,
+): target is Node {
+ return target instanceof Node && ref.current?.contains(target) === true;
}
-interface DateBehaviorProps {
+interface DateFieldBridgeOptions {
+ id?: string;
+ name?: string;
+ value: DateValue | null;
+ hasValue: boolean;
+ isDisabled?: boolean;
+ isInvalid?: boolean;
+ customValidity: string;
+ "aria-labelledby"?: string;
+ "aria-describedby"?: string;
+ ref?: Ref;
+}
+
+/**
+ * Adapts the standalone date widgets to Base UI's `Field` / `Form` contract.
+ *
+ * Why this exists:
+ * - `DateField` / `DatePicker` are hand-rolled composite widgets made of a
+ * labelled `role="group"` plus per-segment `role="spinbutton"` elements.
+ * - Base UI's form ecosystem (`Field.Root`, `Field.Label`, `Field.Description`,
+ * `Field.Error`, `Form`) is built around a *registered control* that exposes
+ * an id, name, ref, value, validation lifecycle, and field state updates.
+ * - The date widgets already render a hidden proxy `(value);
+ latestValueRef.current = value;
+
+ const didMountRef = useRef(false);
+ const pendingBlurValidationRef = useRef(false);
+
+ useEffect(() => {
+ const initialValue = validityData.initialValue as DateValue | null;
+ const isDirty =
+ value != null && initialValue != null
+ ? !isSameDateValue(value, initialValue)
+ : hasValue || initialValue != null;
+
+ setFilled(hasValue);
+ setDirty(isDirty);
+
+ if (!didMountRef.current) {
+ didMountRef.current = true;
+ return;
+ }
+
+ if (resolvedName) clearErrors(resolvedName);
+
+ if (pendingBlurValidationRef.current) {
+ pendingBlurValidationRef.current = false;
+ validation.commit(latestValueRef.current);
+ return;
+ }
+
+ if (shouldValidateOnChange() && (value != null || !hasValue)) {
+ validation.commit(latestValueRef.current);
+ }
+ }, [
+ clearErrors,
+ hasValue,
+ resolvedName,
+ setDirty,
+ setFilled,
+ shouldValidateOnChange,
+ validation,
+ validityData.initialValue,
+ value,
+ ]);
+
+ const handleGroupFocus = useCallback(() => {
+ setFocused(true);
+ }, [setFocused]);
+
+ const handleGroupBlur = useCallback(() => {
+ setTouched(true);
+ setFocused(false);
+
+ if (validationMode === "onBlur") {
+ pendingBlurValidationRef.current = true;
+ queueMicrotask(() => {
+ if (!pendingBlurValidationRef.current) return;
+ pendingBlurValidationRef.current = false;
+ validation.commit(latestValueRef.current);
+ });
+ }
+ }, [setFocused, setTouched, validation, validationMode]);
+
+ return {
+ id,
+ name: resolvedName,
+ isDisabled: resolvedDisabled,
+ isInvalid: resolvedInvalid,
+ ariaLabelledby,
+ describedById,
+ setProxyRef,
+ onGroupFocus: handleGroupFocus,
+ onGroupBlur: handleGroupBlur,
+ };
+}
+
+interface DateControlProps {
value?: T | null;
defaultValue?: T | null;
onChange?: (value: T | null) => void;
+ onBlur?: () => void;
granularity?: Granularity;
minValue?: DateValue;
maxValue?: DateValue;
- isDateUnavailable?: (date: DateValue) => boolean;
+ isDateUnavailable?: (date: T) => boolean;
isDisabled?: boolean;
isReadOnly?: boolean;
isRequired?: boolean;
isInvalid?: boolean;
autoFocus?: boolean;
hourCycle?: HourCycle;
- hideTimeZone?: boolean;
placeholderValue?: DateValue;
- /**
- * First day of the week (0 = Sunday … 6 = Saturday); defaults to the locale.
- * Only affects the `w`/`k` (start/end of week) keyboard shortcuts here.
- */
firstDayOfWeek?: FirstDayOfWeek;
name?: string;
- /** Accessible name when no visible `label` is provided (e.g. a compact filter input). */
+ className?: string;
+ id?: string;
+ /** Accessible name when there is no visible label. */
"aria-label"?: string;
+ /** ID of the element(s) that label the control. */
+ "aria-labelledby"?: string;
+ /** ID of the element(s) that describe the control. */
+ "aria-describedby"?: string;
/** BCP-47 locale override; defaults to the AppShell formatting locale. */
locale?: string;
}
-export type DateFieldProps = DateFieldMetaProps &
- DateBehaviorProps;
+export type DateFieldProps = DateControlProps;
-export type DatePickerProps = DateFieldProps & {
+export type DatePickerProps = DateControlProps & {
/** IANA timezone; defaults to the AppShell `timeZone`. */
timeZone?: string;
};
-// ─── DateField ────────────────────────────────────────────────────────────────
+function toDateUnavailablePredicate(
+ predicate?: (date: T) => boolean,
+): ((date: DateValue) => boolean) | undefined {
+ if (!predicate) return undefined;
+ return (date: DateValue) => predicate(date as T);
+}
+
+function hasSegmentValue(segments: Segment[]) {
+ return segments.some((segment) => segment.type !== "literal" && !segment.isPlaceholder);
+}
/**
* A segmented date/time input field with no popover.
*
+ * Provide an accessible name with `aria-label` or `aria-labelledby`. When used
+ * inside `Field.Root`, `Field.Label` / `Field.Description` / `Field.Error`
+ * wiring is automatic.
+ *
* @example
* ```tsx
- * import { DateField } from "@tailor-platform/app-shell";
+ * import { DateField, Field } from "@tailor-platform/app-shell";
+ *
+ *
+ * Invoice date
+ * ;
* ```
*/
-function DateField({
- label,
- description,
- errorMessage,
- className,
- locale: localeProp,
- value,
- defaultValue,
- onChange,
- granularity,
- hourCycle,
- placeholderValue,
- minValue,
- maxValue,
- isDateUnavailable,
- isDisabled,
- isReadOnly,
- isInvalid,
- isRequired,
- autoFocus,
- firstDayOfWeek,
- name,
- "aria-label": ariaLabel,
-}: DateFieldProps) {
- const { locale: shellLocale, language } = useResolvedLocale();
+const DateField = forwardRef(function DateField(
+ {
+ id,
+ className,
+ locale: localeProp,
+ value,
+ defaultValue,
+ onChange,
+ onBlur,
+ granularity,
+ minValue,
+ maxValue,
+ isDateUnavailable,
+ isDisabled,
+ isReadOnly,
+ isRequired,
+ isInvalid,
+ hourCycle,
+ placeholderValue,
+ autoFocus,
+ firstDayOfWeek,
+ name,
+ "aria-label": ariaLabel,
+ "aria-labelledby": ariaLabelledby,
+ "aria-describedby": ariaDescribedby,
+ }: DateFieldProps,
+ ref: ForwardedRef,
+) {
+ const { locale: shellLocale } = useResolvedLocale();
const resolvedLocale = localeProp ?? shellLocale;
- const resolve = buildLocaleResolver(language);
+ const groupRef = useRef(null);
const t = useDateFieldT();
-
- const labelId = useId();
- const descId = useId();
- const errId = useId();
+ const dateUnavailable = useMemo(
+ () => toDateUnavailablePredicate(isDateUnavailable),
+ [isDateUnavailable],
+ );
const state = useDateFieldState({
- // Pass `value` through as-is: `null` is a controlled-empty value and must
- // stay distinct from `undefined` (uncontrolled), or a parent clearing the
- // field with `value={null}` would be treated as uncontrolled and ignored.
value,
defaultValue,
onChange: onChange as (v: DateValue | null) => void,
@@ -159,31 +425,59 @@ function DateField({
locale: resolvedLocale,
hourCycle,
placeholderValue,
- // min/max and unavailability flag a typed/shortcut value invalid (not
- // clamped) — the field is free-entry with no calendar to gate selection.
minValue,
maxValue,
- isDateUnavailable,
- // Drives the `w`/`k` (start/end of week) shortcuts; the standalone field has
- // no calendar to pair with, so this is the only week-start override.
+ isDateUnavailable: dateUnavailable,
firstDayOfWeek,
isReadOnly,
});
- const labelText = label ? resolve(label, "") : undefined;
- const descText = description ? resolve(description, "") : undefined;
- const errorText = errorMessage ? resolve(errorMessage, "") : undefined;
- // Consumer `errorMessage` wins; otherwise fall back to the built-in message
- // for an out-of-range / unavailable typed value.
- const msgKey = invalidMessageKey(state.invalidReason);
- const shownError = errorText ?? (msgKey ? t(msgKey) : undefined);
- const derivedInvalid = !!errorText || !!isInvalid || state.isInvalid;
+ const localValidationMessage = useMemo(() => {
+ const key = invalidMessageKey(state.invalidReason);
+ return key ? t(key) : "";
+ }, [state.invalidReason, t]);
- const describedBy = cn(descText && descId, derivedInvalid && shownError && errId) || undefined;
+ const bridge = useDateFieldFieldBridge({
+ id,
+ name,
+ value: state.fieldValue,
+ hasValue: hasSegmentValue(state.segments),
+ isDisabled,
+ isInvalid: !!isInvalid || !!localValidationMessage,
+ customValidity: localValidationMessage,
+ ref,
+ "aria-labelledby": ariaLabelledby,
+ "aria-describedby": ariaDescribedby,
+ });
+
+ const focusFirstSegment = useCallback(() => {
+ const first = groupRef.current?.querySelector('[role="spinbutton"]');
+ first?.focus();
+ }, []);
return (
-
- {labelText &&
{labelText} }
+
+ {/*
+ Hidden proxy input:
+ - carries the serialized form value
+ - receives native/custom validity
+ - is the target for external labels / Base UI Field wiring
+ - forwards focus into the first visible date segment
+ */}
+ ({
applyShortcut={state.applyShortcut}
commitOnBlur={state.commitOnBlur}
expandShortYear={state.expandShortYear}
- isDisabled={isDisabled}
+ isDisabled={bridge.isDisabled}
isReadOnly={isReadOnly}
- isInvalid={derivedInvalid}
+ isInvalid={bridge.isInvalid}
isRequired={isRequired}
autoFocus={autoFocus}
- labelId={labelText ? labelId : undefined}
+ ariaLabelledby={bridge.ariaLabelledby}
ariaLabel={ariaLabel}
- describedById={describedBy}
+ describedById={bridge.describedById}
+ groupRef={groupRef}
+ onGroupFocus={bridge.onGroupFocus}
+ onGroupBlur={() => {
+ bridge.onGroupBlur();
+ onBlur?.();
+ }}
/>
- {descText && {descText} }
- {derivedInvalid && shownError && {shownError} }
- {name &&
);
-}
-
-// ─── DatePicker ───────────────────────────────────────────────────────────────
+}) as
(
+ props: DateFieldProps & { ref?: Ref },
+) => ReactElement;
/**
* A date/time input with a popover calendar.
*
- * Value type is driven by `granularity`:
- * - `"day"` (default) → `CalendarDate`
- * - `"hour" | "minute" | "second"` → `CalendarDateTime` (or `ZonedDateTime` when a `timeZone` is set)
+ * Provide an accessible name with `aria-label` or `aria-labelledby`. When used
+ * inside `Field.Root`, `Field.Label` / `Field.Description` / `Field.Error`
+ * wiring is automatic.
*
* @example
* ```tsx
- * import { DatePicker, today, getLocalTimeZone, type CalendarDate } from "@tailor-platform/app-shell";
+ * import { DatePicker, Field, getLocalTimeZone, today } from "@tailor-platform/app-shell";
*
- * const [date, setDate] = useState(null);
- *
+ * Ship date
+ * ;
* ```
*/
-function DatePicker({
- label,
- description,
- errorMessage,
- className,
- locale: localeProp,
- timeZone: timeZoneProp,
- value,
- defaultValue,
- onChange,
- granularity,
- hourCycle,
- placeholderValue,
- minValue,
- maxValue,
- isDateUnavailable,
- isDisabled,
- isReadOnly,
- isInvalid,
- isRequired,
- autoFocus,
- firstDayOfWeek,
- name,
- "aria-label": ariaLabel,
-}: DatePickerProps) {
- const { locale: shellLocale, language } = useResolvedLocale();
+const DatePicker = forwardRef(function DatePicker(
+ {
+ id,
+ className,
+ locale: localeProp,
+ timeZone: timeZoneProp,
+ value,
+ defaultValue,
+ onChange,
+ onBlur,
+ granularity,
+ minValue,
+ maxValue,
+ isDateUnavailable,
+ isDisabled,
+ isReadOnly,
+ isRequired,
+ isInvalid,
+ hourCycle,
+ placeholderValue,
+ autoFocus,
+ firstDayOfWeek,
+ name,
+ "aria-label": ariaLabel,
+ "aria-labelledby": ariaLabelledby,
+ "aria-describedby": ariaDescribedby,
+ }: DatePickerProps,
+ ref: ForwardedRef,
+) {
+ const { locale: shellLocale } = useResolvedLocale();
const shellTz = useTimeZone();
const resolvedLocale = localeProp ?? shellLocale;
const resolvedTz = timeZoneProp ?? shellTz.value;
- const resolve = buildLocaleResolver(language);
const t = useDateFieldT();
-
- const labelId = useId();
- const descId = useId();
- const errId = useId();
-
- const labelText = label ? resolve(label, "") : undefined;
- const descText = description ? resolve(description, "") : undefined;
- const errorText = errorMessage ? resolve(errorMessage, "") : undefined;
+ const dateUnavailable = useMemo(
+ () => toDateUnavailablePredicate(isDateUnavailable),
+ [isDateUnavailable],
+ );
const [open, setOpen] = useState(false);
const fieldRef = useRef(null);
+ const popupRef = useRef(null);
+ const hasFocusWithinRef = useRef(false);
const [val, setVal] = useControlledState(
- // `null` is controlled-empty; only `undefined` means uncontrolled (see above).
value,
defaultValue ?? null,
onChange as (v: DateValue | null) => void,
@@ -280,31 +581,89 @@ function DatePicker({
onChange: setVal,
granularity,
locale: resolvedLocale,
- // Use the resolved timezone (prop → AppShell → local), matching the calendar
- // below — otherwise the field falls back to UTC for its "today"/anchor while
- // the calendar uses the AppShell zone, and they disagree on defaults.
timeZone: resolvedTz,
hourCycle,
placeholderValue,
- // Same bounds the calendar enforces, but on the field they flag a typed/
- // shortcut value invalid (the calendar gates selection; typing can't be).
minValue,
maxValue,
- isDateUnavailable,
- // Match the calendar's week-start so field + calendar `w`/`k` agree.
+ isDateUnavailable: dateUnavailable,
firstDayOfWeek,
isReadOnly,
});
+ const localValidationMessage = useMemo(() => {
+ const key = invalidMessageKey(fieldState.invalidReason);
+ return key ? t(key) : "";
+ }, [fieldState.invalidReason, t]);
+
+ const bridge = useDateFieldFieldBridge({
+ id,
+ name,
+ value: fieldState.fieldValue,
+ hasValue: hasSegmentValue(fieldState.segments),
+ isDisabled,
+ isInvalid: !!isInvalid || !!localValidationMessage,
+ customValidity: localValidationMessage,
+ ref,
+ "aria-labelledby": ariaLabelledby,
+ "aria-describedby": ariaDescribedby,
+ });
+
+ const focusFirstSegment = useCallback(() => {
+ const first = fieldRef.current?.querySelector('[role="spinbutton"]');
+ first?.focus();
+ }, []);
+
+ const handleCompositeFocus = useCallback(() => {
+ hasFocusWithinRef.current = true;
+ bridge.onGroupFocus();
+ }, [bridge]);
+
+ const handleCompositeBlur = useCallback(() => {
+ if (!hasFocusWithinRef.current) return;
+ hasFocusWithinRef.current = false;
+ bridge.onGroupBlur();
+ onBlur?.();
+ }, [bridge, onBlur]);
+
+ const handleGroupBlur = useCallback(
+ (nextFocused: EventTarget | null) => {
+ if (isTargetWithin(nextFocused, popupRef)) return;
+ handleCompositeBlur();
+ },
+ [handleCompositeBlur],
+ );
+
+ const handlePopupBlur = useCallback(
+ (nextFocused: EventTarget | null) => {
+ if (isTargetWithin(nextFocused, fieldRef) || isTargetWithin(nextFocused, popupRef)) return;
+ handleCompositeBlur();
+ },
+ [handleCompositeBlur],
+ );
+
+ const handleOpenChange = useCallback(
+ (nextOpen: boolean) => {
+ setOpen(nextOpen);
+ if (nextOpen) return;
+ queueMicrotask(() => {
+ if (isTargetWithin(document.activeElement, fieldRef)) return;
+ if (isTargetWithin(document.activeElement, popupRef)) return;
+ handleCompositeBlur();
+ });
+ },
+ [handleCompositeBlur],
+ );
+
const calState = useCalendarState({
value: val,
onChange: (d) => {
setVal(d);
- setOpen(false);
+ handleOpenChange(false);
},
minValue,
maxValue,
- isDateUnavailable,
+ isDateUnavailable: dateUnavailable,
isDisabled,
isReadOnly,
firstDayOfWeek,
@@ -312,25 +671,41 @@ function DatePicker({
timeZone: resolvedTz,
});
- // Consumer `errorMessage` wins; otherwise the built-in out-of-range /
- // unavailable message for a typed or shortcut-entered value.
- const msgKey = invalidMessageKey(fieldState.invalidReason);
- const shownError = errorText ?? (msgKey ? t(msgKey) : undefined);
- const derivedInvalid = !!errorText || !!isInvalid || fieldState.isInvalid;
-
- const describedBy = cn(descText && descId, derivedInvalid && shownError && errId) || undefined;
- const accessibleName = labelText ?? ariaLabel;
- const popoverAriaLabel = accessibleName
- ? t("chooseDateFor", { name: accessibleName })
- : t("chooseDate");
+ let popoverAriaLabel: string | undefined;
+ if (!bridge.ariaLabelledby) {
+ popoverAriaLabel = ariaLabel ? t("chooseDateFor", { name: ariaLabel }) : t("chooseDate");
+ }
return (
-
- {labelText &&
{labelText} }
+
+ {/*
+ Hidden proxy input:
+ - carries the serialized form value
+ - receives native/custom validity
+ - is the target for external labels / Base UI Field wiring
+ - forwards focus into the first visible date segment
+ */}
+ ({
applyShortcut={fieldState.applyShortcut}
commitOnBlur={fieldState.commitOnBlur}
expandShortYear={fieldState.expandShortYear}
- onOpenCalendar={() => setOpen(true)}
- isDisabled={isDisabled}
+ onOpenCalendar={() => handleOpenChange(true)}
+ isDisabled={bridge.isDisabled}
isReadOnly={isReadOnly}
- isInvalid={derivedInvalid}
+ isInvalid={bridge.isInvalid}
isRequired={isRequired}
autoFocus={autoFocus}
- labelId={labelText ? labelId : undefined}
+ ariaLabelledby={bridge.ariaLabelledby}
ariaLabel={ariaLabel}
- describedById={describedBy}
+ describedById={bridge.describedById}
groupRef={fieldRef}
- trigger={
- {descText && {descText} }
- {derivedInvalid && shownError && {shownError} }
- {name &&
);
-}
+}) as
(
+ props: DatePickerProps & { ref?: Ref },
+) => ReactElement;
export { DateField, DatePicker };
diff --git a/packages/core/src/components/date-field/date-input-group.tsx b/packages/core/src/components/date-field/date-input-group.tsx
index 21fa3093..75da4436 100644
--- a/packages/core/src/components/date-field/date-input-group.tsx
+++ b/packages/core/src/components/date-field/date-input-group.tsx
@@ -1,4 +1,13 @@
-import * as React from "react";
+import {
+ useEffect,
+ useMemo,
+ useRef,
+ type ComponentProps,
+ type KeyboardEvent,
+ type ReactNode,
+ type Ref,
+ type RefObject,
+} from "react";
import { Popover } from "@base-ui/react/popover";
import { CalendarIcon } from "lucide-react";
import { cn } from "@/lib/utils";
@@ -8,51 +17,15 @@ import { DATE_SHORTCUT_KEYS, type DateShortcut } from "@/lib/date-shortcuts";
import type { Segment } from "./use-date-field-state";
/**
- * Field presentation for the date components — the segmented spinbutton group,
- * its labels/description/error, and the popover wrapper used by `DatePicker`.
- * Built on Base UI primitives (`Popover`) + plain accessible markup, driven by
+ * Field presentation for the date components — the segmented spinbutton group
+ * and the popover wrapper used by `DatePicker`. Built on Base UI primitives
+ * (`Popover`) + plain accessible markup, driven by
* our own `useDateFieldState` engine. Not exported from the package.
*
* Styling mirrors the rest of the library (`astw:` tokens, dark mode, the same
* popover token set as our other Base UI popovers).
*/
-// ─── Field labels / description / error ───────────────────────────────────────
-
-// A composite spinbutton group can't be labelled by a native ,
-// so the label is a referenced via the group's `aria-labelledby` (the
-// APG date-field pattern).
-export function DatePickerLabel({ className, ...props }: React.ComponentProps<"span">) {
- return (
-
- );
-}
-
-export function DatePickerError({ className, ...props }: React.ComponentProps<"p">) {
- return (
-
- );
-}
-
// ─── Segmented input group ────────────────────────────────────────────────────
const groupClasses = cn(
@@ -93,14 +66,19 @@ interface DateInputGroupProps {
isInvalid?: boolean;
isRequired?: boolean;
autoFocus?: boolean;
- labelId?: string;
+ /** ID of the element(s) that label the group. */
+ ariaLabelledby?: string;
/** Accessible name when there is no visible label (e.g. a compact filter input). */
ariaLabel?: string;
describedById?: string;
className?: string;
- trigger?: React.ReactNode;
+ trigger?: ReactNode;
/** Ref to the group element — used to anchor the popover to the whole field. */
- groupRef?: React.Ref;
+ groupRef?: Ref;
+ /** Called once when focus enters the group from outside. */
+ onGroupFocus?: () => void;
+ /** Called once when focus leaves the group entirely. */
+ onGroupBlur?: (nextFocused: EventTarget | null) => void;
}
export function DateInputGroup({
@@ -118,27 +96,29 @@ export function DateInputGroup({
isInvalid,
isRequired,
autoFocus,
- labelId,
+ ariaLabelledby,
ariaLabel,
describedById,
className,
trigger,
groupRef,
+ onGroupFocus,
+ onGroupBlur,
}: DateInputGroupProps) {
const t = useDateFieldT();
- const editableRefs = React.useRef<(HTMLDivElement | null)[]>([]);
+ const editableRefs = useRef<(HTMLDivElement | null)[]>([]);
// Digits typed into the currently-focused segment this session. Reset on
// focus; the first digit (count 0) replaces, and the count decides when the
// segment is "full" and should auto-advance.
- const typedCountRef = React.useRef(0);
+ const typedCountRef = useRef(0);
- React.useEffect(() => {
+ useEffect(() => {
if (autoFocus && !isDisabled) editableRefs.current[0]?.focus();
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
// Index editable segments for left/right focus movement.
- const editableIndexById = React.useMemo(() => {
+ const editableIndexById = useMemo(() => {
const map = new Map();
let i = 0;
segments.forEach((s, idx) => {
@@ -153,7 +133,7 @@ export function DateInputGroup({
};
const handleKeyDown = (
- e: React.KeyboardEvent,
+ e: KeyboardEvent,
segment: Segment,
editableIndex: number,
) => {
@@ -248,13 +228,16 @@ export function DateInputGroup({
ref={groupRef}
role="group"
data-slot="date-picker-group"
- aria-labelledby={labelId}
- aria-label={labelId ? undefined : ariaLabel}
+ aria-labelledby={ariaLabelledby}
+ aria-label={ariaLabelledby ? undefined : ariaLabel}
aria-describedby={describedById}
aria-disabled={isDisabled || undefined}
data-disabled={isDisabled || undefined}
data-invalid={isInvalid || undefined}
className={cn(groupClasses, className)}
+ onFocus={(e) => {
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) onGroupFocus?.();
+ }}
onBlur={(e) => {
// Leaving the year segment (to a sibling, the calendar icon, or out of
// the field) expands a 1–2 digit year to the 2000s right away — the icon
@@ -264,7 +247,10 @@ export function DateInputGroup({
// Focus left the whole group (not just moved between segments) →
// backfill the current month/year for a partial entry and clamp an
// impossible day.
- if (!e.currentTarget.contains(e.relatedTarget as Node | null)) commitOnBlur();
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+ commitOnBlur();
+ onGroupBlur?.(e.relatedTarget);
+ }
}}
>
@@ -344,7 +330,7 @@ const triggerClasses = cn(
export function DatePickerPopoverTrigger({
className,
...props
-}: React.ComponentProps
) {
+}: ComponentProps) {
const t = useDateFieldT();
return (
void;
/** The field group — must contain a `DatePickerPopoverTrigger`. */
- field: React.ReactNode;
- children: React.ReactNode;
+ field: ReactNode;
+ children: ReactNode;
ariaLabel?: string;
+ ariaLabelledby?: string;
+ popupRef?: Ref;
+ onPopupBlur?: (nextFocused: EventTarget | null) => void;
/**
* Element to position the calendar against. Defaults to the trigger; pass the
* field group so the calendar aligns to the field's edge (not the icon),
* overlapping it horizontally and shifting inward near the viewport edge.
*/
- anchor?: React.RefObject;
+ anchor?: RefObject;
}
export function DatePopover({
@@ -383,6 +372,9 @@ export function DatePopover({
field,
children,
ariaLabel,
+ ariaLabelledby,
+ popupRef,
+ onPopupBlur,
anchor,
}: DatePopoverProps) {
const t = useDateFieldT();
@@ -393,14 +385,21 @@ export function DatePopover({
{/* APG date-picker dialog pattern — the popup is a labelled dialog. */}
{
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+ onPopupBlur?.(e.relatedTarget);
+ }
+ }}
>
{children}