Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(inputs)!: FR10 prop targets for DateInput, DateRangeInput, DateTimeInput, TimeInput (#7337)

Cindy Zhang2e0dbb5b9a4b
diff --git a/.changeset/field-input-styling-date-time.md b/.changeset/field-input-styling-date-time.md
new file mode 100644
index 0000000000..acf7dbb9b2
--- /dev/null
+++ b/.changeset/field-input-styling-date-time.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/core': minor
+---
+
+[breaking] DateInput, DateRangeInput, DateTimeInput, and TimeInput no longer accept root `xstyle`, `className`, or `style`. Style the field with `containerXstyle`/`containerClassName`/`containerStyle` (the Field box; no effect inside InputGroup or a `horizontal-labels` FormLayout) and the visual control box with `controlXstyle`/`controlClassName`/`controlStyle`. Base props such as `ref`, `id`, `data-*`, `aria-*`, and DOM handlers reach the field's semantic control on every surface (the date, time, or date-time input; DateRangeInput's range trigger) instead of the wrapper, TimeInput no longer drops them, and a caller `id` is now honored there. A caller `aria-describedby` is added to the component's own description ids, and a caller `aria-labelledby` is read after the field's own label (on DateRangeInput, after its label and selected range); a caller `aria-label` on DateRangeInput replaces the trigger's name.
+
+Migration: rename root `xstyle`/`className`/`style` on these components to `controlXstyle`/`controlClassName`/`controlStyle`, which style the same element as before (for DateTimeInput, the row holding the date and time segments). Rename by hand, or run `astryx upgrade` once it includes the `migrate-field-input-styling` transform, which rewrites JSX usage; styling passed through a wrapper's own props or a spread is never rewritten and now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored. A DOM handler or `data-*` attribute that relied on landing on the wrapper now lands on the control; a handler still runs after the component's own and still receives events the component handled.
+
+From #5656 by @harjothkhara.
+
+@cixzhang
diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsx
index f7650bc5da..025b3634c7 100644
--- a/apps/storybook/stories/DateInput.stories.tsx
+++ b/apps/storybook/stories/DateInput.stories.tsx
@@ -3,6 +3,9 @@
import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {DateInput} from '@astryxdesign/core/DateInput';
+import {FormLayout} from '@astryxdesign/core/FormLayout';
+import {Text} from '@astryxdesign/core/Text';
+import {InputGroup, InputGroupText} from '@astryxdesign/core/InputGroup';
import type {ISODateString} from '@astryxdesign/core/Calendar';
import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
@@ -681,3 +684,114 @@ export const ThemedCalendarToggleIcon: Story = {
);
},
};
+
+const CONTROL_STYLE = {outline: '2px dashed #c800ff', outlineOffset: 3};
+const CONTAINER_STYLE = {
+ backgroundColor: 'rgba(0, 150, 255, 0.16)',
+ padding: 8,
+ borderRadius: 8,
+};
+
+/**
+ * Where each styling part lands (family:input-fields FR10). The dashed outline
+ * is `controlStyle` on the visual control box. The blue tint is
+ * `containerStyle` on the Field box; in a `horizontal-labels` FormLayout and
+ * inside InputGroup no Field box renders, so there it has no effect (and warns
+ * in development).
+ */
+export const StylingParts: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24, maxWidth: 360}}>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">controlStyle</Text>
+ <div data-parts-row="control-popover" style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="popover"</Text>
+ <DateInput
+ label="Due date"
+ presentation="popover"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div data-parts-row="control-native" style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="native"</Text>
+ <DateInput
+ label="Due date"
+ presentation="native"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-bottom-sheet"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="bottom-sheet"</Text>
+ <DateInput
+ label="Due date"
+ presentation="bottom-sheet"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateInput label="Due date" controlStyle={CONTROL_STYLE} />
+ </FormLayout>
+ </div>
+ <div
+ data-parts-row="control-input-group"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">InputGroup</Text>
+ <InputGroup label="Due date group">
+ <InputGroupText>At</InputGroupText>
+ <DateInput
+ label="Due date"
+ isLabelHidden
+ controlStyle={CONTROL_STYLE}
+ />
+ </InputGroup>
+ </div>
+ </div>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">containerStyle and controlStyle</Text>
+ <div
+ data-parts-row="container-popover"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="popover"</Text>
+ <DateInput
+ label="Due date"
+ presentation="popover"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="container-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateInput
+ label="Due date"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ <div
+ data-parts-row="container-input-group"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">InputGroup</Text>
+ <InputGroup label="Due date group">
+ <InputGroupText>At</InputGroupText>
+ <DateInput
+ label="Due date"
+ isLabelHidden
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </InputGroup>
+ </div>
+ </div>
+ </div>
+ ),
+};
diff --git a/apps/storybook/stories/DateRangeInput.stories.tsx b/apps/storybook/stories/DateRangeInput.stories.tsx
index 1bdbe5669f..3f2f8f8bc9 100644
--- a/apps/storybook/stories/DateRangeInput.stories.tsx
+++ b/apps/storybook/stories/DateRangeInput.stories.tsx
@@ -3,6 +3,8 @@
import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {DateRangeInput} from '@astryxdesign/core/DateRangeInput';
+import {FormLayout} from '@astryxdesign/core/FormLayout';
+import {Text} from '@astryxdesign/core/Text';
import type {DateRange} from '@astryxdesign/core/DateRangeInput';
import type {ISODateString} from '@astryxdesign/core/Calendar';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
@@ -455,3 +457,82 @@ export const ThemedIcons: Story = {
);
},
};
+
+// The StylingParts fields are uncontrolled demos; nothing reads their value.
+const noop = () => {};
+const CONTROL_STYLE = {outline: '2px dashed #c800ff', outlineOffset: 3};
+const CONTAINER_STYLE = {
+ backgroundColor: 'rgba(0, 150, 255, 0.16)',
+ padding: 8,
+ borderRadius: 8,
+};
+
+/**
+ * Where each styling part lands (family:input-fields FR10). The dashed outline
+ * is `controlStyle` on the visual control box. The blue tint is
+ * `containerStyle` on the Field box; in a `horizontal-labels` FormLayout and
+ * inside InputGroup no Field box renders, so there it has no effect (and warns
+ * in development).
+ */
+export const StylingParts: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24, maxWidth: 360}}>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">controlStyle</Text>
+ <div
+ data-parts-row="control-standalone"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">Standalone</Text>
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ </div>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">containerStyle and controlStyle</Text>
+ <div
+ data-parts-row="container-standalone"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">Standalone</Text>
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="container-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ </div>
+ </div>
+ ),
+};
diff --git a/apps/storybook/stories/DateTimeInput.stories.tsx b/apps/storybook/stories/DateTimeInput.stories.tsx
index 0d563d083f..5d8504b446 100644
--- a/apps/storybook/stories/DateTimeInput.stories.tsx
+++ b/apps/storybook/stories/DateTimeInput.stories.tsx
@@ -4,6 +4,8 @@ import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {expect, userEvent, waitFor, within} from 'storybook/test';
import {DateTimeInput} from '@astryxdesign/core/DateTimeInput';
+import {FormLayout} from '@astryxdesign/core/FormLayout';
+import {Text} from '@astryxdesign/core/Text';
import type {ISODateTimeString} from '@astryxdesign/core/DateTimeInput';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
@@ -620,3 +622,98 @@ export const ThemedSegments: Story = {
);
},
};
+
+// The StylingParts fields are uncontrolled demos; nothing reads their value.
+const noop = () => {};
+const CONTROL_STYLE = {outline: '2px dashed #c800ff', outlineOffset: 3};
+const CONTAINER_STYLE = {
+ backgroundColor: 'rgba(0, 150, 255, 0.16)',
+ padding: 8,
+ borderRadius: 8,
+};
+
+/**
+ * Where each styling part lands (family:input-fields FR10). The dashed outline
+ * is `controlStyle` on the visual control box. The blue tint is
+ * `containerStyle` on the Field box; in a `horizontal-labels` FormLayout and
+ * inside InputGroup no Field box renders, so there it has no effect (and warns
+ * in development).
+ */
+export const StylingParts: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24, maxWidth: 360}}>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">controlStyle</Text>
+ <div data-parts-row="control-popover" style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="popover"</Text>
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ presentation="popover"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div data-parts-row="control-native" style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="native"</Text>
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ presentation="native"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-bottom-sheet"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="bottom-sheet"</Text>
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ presentation="bottom-sheet"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ </div>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">containerStyle and controlStyle</Text>
+ <div
+ data-parts-row="container-popover"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="popover"</Text>
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ presentation="popover"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="container-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <DateTimeInput
+ onChange={noop}
+ label="Starts"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ </div>
+ </div>
+ ),
+};
diff --git a/apps/storybook/stories/TimeInput.stories.tsx b/apps/storybook/stories/TimeInput.stories.tsx
index c10005e203..98d6a1c7e8 100644
--- a/apps/storybook/stories/TimeInput.stories.tsx
+++ b/apps/storybook/stories/TimeInput.stories.tsx
@@ -3,6 +3,9 @@
import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {TimeInput} from '@astryxdesign/core/TimeInput';
+import {FormLayout} from '@astryxdesign/core/FormLayout';
+import {Text} from '@astryxdesign/core/Text';
+import {InputGroup, InputGroupText} from '@astryxdesign/core/InputGroup';
import type {ISOTimeString} from '@astryxdesign/core';
const meta: Meta<typeof TimeInput> = {
@@ -455,3 +458,116 @@ export const StatusVariantComparison: Story = {
);
},
};
+
+const CONTROL_STYLE = {outline: '2px dashed #c800ff', outlineOffset: 3};
+const CONTAINER_STYLE = {
+ backgroundColor: 'rgba(0, 150, 255, 0.16)',
+ padding: 8,
+ borderRadius: 8,
+};
+
+/**
+ * Where each styling part lands (family:input-fields FR10). The dashed outline
+ * is `controlStyle` on the visual control box. The blue tint is
+ * `containerStyle` on the Field box; in a `horizontal-labels` FormLayout and
+ * inside InputGroup no Field box renders, so there it has no effect (and warns
+ * in development).
+ */
+export const StylingParts: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24, maxWidth: 360}}>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">controlStyle</Text>
+ <div
+ data-parts-row="control-text-input"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="text-input"</Text>
+ <TimeInput
+ label="Start time"
+ presentation="text-input"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div data-parts-row="control-native" style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="native"</Text>
+ <TimeInput
+ label="Start time"
+ presentation="native"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-bottom-sheet"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="bottom-sheet"</Text>
+ <TimeInput
+ label="Start time"
+ presentation="bottom-sheet"
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="control-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <TimeInput label="Start time" controlStyle={CONTROL_STYLE} />
+ </FormLayout>
+ </div>
+ <div
+ data-parts-row="control-input-group"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">InputGroup</Text>
+ <InputGroup label="Start time group">
+ <InputGroupText>At</InputGroupText>
+ <TimeInput
+ label="Start time"
+ isLabelHidden
+ controlStyle={CONTROL_STYLE}
+ />
+ </InputGroup>
+ </div>
+ </div>
+ <div style={{display: 'grid', gap: 12}}>
+ <Text type="label">containerStyle and controlStyle</Text>
+ <div
+ data-parts-row="container-text-input"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">presentation="text-input"</Text>
+ <TimeInput
+ label="Start time"
+ presentation="text-input"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </div>
+ <div
+ data-parts-row="container-form-layout"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">horizontal-labels FormLayout</Text>
+ <FormLayout direction="horizontal-labels">
+ <TimeInput
+ label="Start time"
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </FormLayout>
+ </div>
+ <div
+ data-parts-row="container-input-group"
+ style={{display: 'grid', gap: 4}}>
+ <Text type="supporting">InputGroup</Text>
+ <InputGroup label="Start time group">
+ <InputGroupText>At</InputGroupText>
+ <TimeInput
+ label="Start time"
+ isLabelHidden
+ containerStyle={CONTAINER_STYLE}
+ controlStyle={CONTROL_STYLE}
+ />
+ </InputGroup>
+ </div>
+ </div>
+ </div>
+ ),
+};
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index 456d987d53..7618bd598c 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -177,10 +177,16 @@ export const docs = {
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+ 'StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the bordered element that holds the text, icons, and end controls, never the native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept.',
},
],
theming: {
@@ -197,6 +203,11 @@ export const docs = {
description:
'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -290,6 +301,11 @@ export const docsZh = {
description:
'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -482,10 +498,16 @@ export const docsZh = {
'字段宽度(数字按像素处理,字符串按原样使用,例如 “100%”)。统一调整标签、控件和状态消息的宽度。',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
+ type: 'StyleXStyles',
+ description:
+ '作用于包含标签、控件和状态的 Field 容器的 StyleX 样式;containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时(InputGroup 内或 horizontal-labels FormLayout 中)不生效,并在开发环境发出警告。',
+ },
+ {
+ name: 'controlXstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ '作用于可见控件框(带边框、包含文本、图标和末端控件的元素,而非原生 input)的 StyleX 样式;controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。',
},
],
theming: {
@@ -507,6 +529,11 @@ export const docsDense = {
description:
'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -586,6 +613,9 @@ export const docsDense = {
"which surface draws the picker: 'adaptive-native' (default) = Astryx popover on fine, browser/OS on coarse w/ Astryx fallbacks; 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popover fine / Astryx sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens a picker (no text-only value; that is TimeInput's). use non-native for weekStartsOn/numberOfMonths/dateConstraints.",
nativePicker:
"deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
- xstyle: 'StyleX styles for layout; must be stylex.create() value',
+ containerXstyle:
+ 'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
+ controlXstyle:
+ 'visual control box (border/bg/icons), never the native input; also controlClassName/controlStyle. no root xstyle/className/style',
},
};
diff --git a/packages/core/src/DateInput/DateInput.fr10.test.tsx b/packages/core/src/DateInput/DateInput.fr10.test.tsx
new file mode 100644
index 0000000000..bc54a77593
--- /dev/null
+++ b/packages/core/src/DateInput/DateInput.fr10.test.tsx
@@ -0,0 +1,283 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DateInput.fr10.test.tsx
+ * @input Uses vitest, Testing Library, DateInput, FormLayout, and the input-family FR10 test helpers
+ * @output Tests that every DateInput surface takes no root styling and routes
+ * base props, container*, and control* to their FR10 targets
+ * @position Colocated test for family:input-fields FR10
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {DateInput, type DateInputProps} from './DateInput';
+import {FormLayout} from '../FormLayout';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+
+const SURFACES = [
+ ['pointer', 'popover', 'input[role="combobox"]'],
+ ['native', 'native', 'input[type="date"]'],
+ ['touch', 'bottom-sheet', 'input[role="combobox"]'],
+] as const;
+
+// The touch surface's month scroller measures itself and its sheet is a
+// modal <dialog>; jsdom implements neither.
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+beforeAll(() => {
+ Element.prototype.scrollTo = vi.fn();
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.open = true;
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.open = false;
+ });
+});
+
+beforeEach(() => {
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function control(selector: string): HTMLElement {
+ const el = document.querySelector<HTMLElement>(selector);
+ if (el == null) {
+ throw new Error(`no control matching ${selector}`);
+ }
+ return el;
+}
+
+describe('DateInput FR10 styling contract', () => {
+ it('has no root styling props and has the container* and control* parts', () => {
+ expectFieldInputProps<DateInputProps>();
+ });
+
+ it('rejects root xstyle, className, and style at compile time', () => {
+ const typeOnly = () => (
+ <>
+ {/* Control: the same element without root styling compiles. */}
+ <DateInput label="L" controlClassName="x" containerClassName="y" />
+ {/* @ts-expect-error -- root className is not a DateInput prop (FR10) */}
+ <DateInput label="L" className="x" />
+ {/* @ts-expect-error -- root style is not a DateInput prop (FR10) */}
+ <DateInput label="L" style={{margin: 1}} />
+ {/* @ts-expect-error -- root xstyle is not a DateInput prop (FR10) */}
+ <DateInput label="L" xstyle={{}} />
+ </>
+ );
+ void typeOnly;
+ });
+});
+
+for (const [surface, presentation, selector] of SURFACES) {
+ describe(`${surface} surface`, () => {
+ describeFieldInputParts('DateInput', {
+ renderMember: props => (
+ <DateInput label="Due" presentation={presentation} {...props} />
+ ),
+ getControl: () => control(selector),
+ inGroup: true,
+ });
+ });
+
+ describe(`DateInput (${surface}) FR10 details`, () => {
+ it('names the control from its label when the caller sets id', () => {
+ render(<DateInput label="Due" presentation={presentation} id="due" />);
+ expect(control(selector).id).toBe('due');
+ expect(document.querySelector('label[for="due"]')).not.toBeNull();
+ });
+
+ it("adds a caller's aria-describedby to the component's own", () => {
+ render(
+ <DateInput
+ label="Due"
+ description="Pick a weekday"
+ presentation={presentation}
+ aria-describedby="caller-desc"
+ />,
+ );
+ const ids = control(selector)
+ .getAttribute('aria-describedby')
+ ?.split(' ');
+ expect(ids).toContain('caller-desc');
+ expect(ids?.length).toBeGreaterThan(1);
+ });
+
+ it('keeps component-only props off the control', () => {
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+ render(
+ <DateInput
+ label="Due"
+ presentation={presentation}
+ min="2026-01-01"
+ max="2026-12-31"
+ dateConstraints={[]}
+ numberOfMonths={2}
+ weekStartsOn={1}
+ format="date"
+ hasClear
+ size="sm"
+ statusVariant="detached"
+ labelTooltip="tip"
+ placeholder="Pick"
+ isOptional
+ width={240}
+ />,
+ );
+ const attrs = [...control(selector).attributes].map(a => a.name);
+ for (const prop of [
+ 'increment',
+ 'hasautofocus',
+ 'timeincrement',
+ 'timeoptioninterval',
+ 'numberofmonths',
+ 'weekstartson',
+ 'dateconstraints',
+ 'hasclear',
+ 'hasseconds',
+ 'hourformat',
+ 'statusvariant',
+ 'labeltooltip',
+ 'format',
+ 'width',
+ 'size',
+ ]) {
+ expect(attrs).not.toContain(prop);
+ }
+ expect(
+ error.mock.calls.filter(call =>
+ /React does not recognize|Invalid value for prop|non-boolean attribute/.test(
+ String(call[0]),
+ ),
+ ),
+ ).toEqual([]);
+ error.mockRestore();
+ });
+
+ it("names the control by its label and then a caller's aria-labelledby", () => {
+ render(
+ <>
+ <span id="caller-name">Billing</span>
+ <DateInput
+ label="Due"
+ presentation={presentation}
+ aria-labelledby="caller-name"
+ />
+ </>,
+ );
+ const ids = control(selector).getAttribute('aria-labelledby')?.split(' ');
+ expect(ids?.at(-1)).toBe('caller-name');
+ const own = document.getElementById(ids?.[0] ?? '');
+ expect(own?.tagName).toBe('LABEL');
+ expect(own?.textContent).toContain('Due');
+ });
+
+ it('keeps control* on the control box in a horizontal-labels FormLayout', () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <FormLayout direction="horizontal-labels">
+ <DateInput
+ label="Due"
+ presentation={presentation}
+ controlClassName="fr10-control"
+ />
+ </FormLayout>,
+ );
+ const box = container.querySelector('.fr10-control');
+ expect(box).not.toBeNull();
+ expect(box).toContainElement(control(selector));
+ expect(box).not.toBe(control(selector));
+ vi.restoreAllMocks();
+ });
+ });
+}
+
+describe('DateInput FR10 handler composition', () => {
+ it('runs a caller onClick after the pointer field opens its calendar', () => {
+ const onClick = vi.fn();
+ render(<DateInput label="Due" presentation="popover" onClick={onClick} />);
+ const input = screen.getByRole('combobox', {name: 'Due'});
+ fireEvent.click(input);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('runs a caller onKeyDown for keys the field does not consume', () => {
+ const onKeyDown = vi.fn();
+ render(
+ <DateInput label="Due" presentation="popover" onKeyDown={onKeyDown} />,
+ );
+ fireEvent.keyDown(screen.getByRole('combobox', {name: 'Due'}), {key: 'a'});
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ });
+
+ it('runs a caller onClick after the touch field opens its sheet', () => {
+ const onClick = vi.fn();
+ render(
+ <DateInput label="Due" presentation="bottom-sheet" onClick={onClick} />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Due'});
+ fireEvent.click(input);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('still hands a caller onKeyDown the keys the field consumes, after the field', () => {
+ // The caller's handler used to sit on the wrapper and receive every key by
+ // bubbling, after the input's own handler; that order is kept.
+ const seen: {key: string; defaultPrevented: boolean}[] = [];
+ render(
+ <DateInput
+ label="Due"
+ presentation="popover"
+ onKeyDown={event =>
+ seen.push({key: event.key, defaultPrevented: event.defaultPrevented})
+ }
+ />,
+ );
+ fireEvent.keyDown(screen.getByRole('combobox', {name: 'Due'}), {
+ key: 'Enter',
+ });
+ expect(seen).toEqual([{key: 'Enter', defaultPrevented: true}]);
+ });
+
+ it('does not let a caller onClick cancel opening the calendar', () => {
+ render(
+ <DateInput
+ label="Due"
+ presentation="popover"
+ onClick={event => event.preventDefault()}
+ />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Due'});
+ fireEvent.click(input);
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('runs a caller onBlur on the native field', () => {
+ const onBlur = vi.fn();
+ render(<DateInput label="Due" presentation="native" onBlur={onBlur} />);
+ const input = control('input[type="date"]');
+ fireEvent.focus(input);
+ fireEvent.blur(input);
+ expect(onBlur).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index 03f0183a7d..05ea7778b8 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -64,6 +64,7 @@ import {NativeDateField} from './NativeDateField';
import {TouchDateField} from './TouchDateField';
import {useTooltip} from '../Tooltip';
import {getInputARIA, isImeKeyEvent, parseDateInput} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
import {
plainDateFromISO,
plainDateToISO,
@@ -187,7 +188,11 @@ export type {
InputStatusType as DateInputStatusType,
} from '../Field';
import {mergeProps, isFocusDetached} from '../utils';
-import type {BaseProps} from '../BaseProps';
+import {joinAriaIDs} from '../utils/inputAria';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -195,10 +200,10 @@ import {useLocale, useTranslator} from '../i18n';
import {useMergedRefs} from '../hooks/useMergedRefs';
export interface DateInputProps extends Omit<
- BaseProps,
+ FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
- /** Ref forwarded to the root element */
+ /** Ref forwarded to the date input (the field's semantic control) */
ref?: React.Ref<HTMLInputElement>;
/**
* Label text for the input (required for accessibility).
@@ -326,7 +331,7 @@ export interface DateInputProps extends Omit<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `containerXstyle` or `controlXstyle`.
*/
width?: SizeValue;
/**
@@ -487,19 +492,38 @@ function PointerDateField({
weekStartsOn,
format = 'date_long',
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
- ...rest
+ ...restProps
}: DateInputProps) {
+ const {rest, container} = useFieldInputStyling('DateInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onBlur: onBlurProp,
+ onClick: onClickProp,
+ onKeyDown: onKeyDownProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const locale = useLocale();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.dateInput.placeholder');
const size = useSize(sizeProp, 'md');
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -548,6 +572,7 @@ function PointerDateField({
// tooltip's content instead so the status is still announced.
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
],
inputGroup,
);
@@ -773,7 +798,6 @@ function PointerDateField({
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
- {...rest}
{...mergeProps(
themeProps('date-input', {
size,
@@ -790,10 +814,10 @@ function PointerDateField({
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
<button
@@ -826,15 +850,16 @@ function PointerDateField({
/>
</button>
<input
+ {...controlProps}
ref={useMergedRefs(ref, inputRef)}
id={id}
type="text"
role="combobox"
value={displayValue}
onChange={handleInputChange}
- onBlur={handleBlur}
- onClick={handleInputClick}
- onKeyDown={handleInputKeyDown}
+ onBlur={chainEventHandlers(handleBlur, onBlurProp)}
+ onClick={chainEventHandlers(handleInputClick, onClickProp)}
+ onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
placeholder={placeholder}
// With a disabledMessage the input keeps focusability via
// aria-disabled so the reason is focus-discoverable; typing is
@@ -843,7 +868,11 @@ function PointerDateField({
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
readOnly={showsDisabledMessage || undefined}
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy
+ }
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
@@ -902,10 +931,12 @@ function PointerDateField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -961,6 +992,11 @@ PointerDateField.displayName = 'PointerDateField';
* with a calendar icon and the formatted date — and differ only in what
* opens. Nothing moves; the field just starts opening a sheet.
*
+ * Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the date input.
+ * A DOM handler runs after the component's own handler for the same event
+ * and still receives events the component handled, even ones it called
+ * `preventDefault` on, so it cannot cancel built-in behavior.
+ *
* @example
* ```
* <DateInput
diff --git a/packages/core/src/DateInput/NativeDateField.tsx b/packages/core/src/DateInput/NativeDateField.tsx
index a9cdc3a04a..ced524fd92 100644
--- a/packages/core/src/DateInput/NativeDateField.tsx
+++ b/packages/core/src/DateInput/NativeDateField.tsx
@@ -53,6 +53,8 @@ import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {Icon} from '../Icon';
import {useLocale, useTranslator} from '../i18n';
import {useInputGroup} from '../InputGroup';
+import {useFieldInputStyling} from '../Field/fieldParts';
+import {joinAriaIDs} from '../utils/inputAria';
import {groupStyles} from '../InputGroup/groupStyles';
import {useSize} from '../SizeContext';
import {Spinner} from '../Spinner';
@@ -77,6 +79,7 @@ import {
themeProps,
type ISODateString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
const styles = stylex.create({
wrapper: {
@@ -270,12 +273,28 @@ export function NativeDateField({
weekStartsOn: _weekStartsOn,
format = 'date_long',
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
- ...rest
+ ...restProps
}: DateInputProps) {
+ const {rest, container} = useFieldInputStyling('DateInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const locale = useLocale();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
@@ -285,7 +304,9 @@ export function NativeDateField({
// Only breaks a tie the engine probe cannot: see ./nativeDateSegments.
const isTouchPointer = useMediaQuery('(pointer: coarse)');
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -328,6 +349,7 @@ export function NativeDateField({
statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
],
inputGroup,
);
@@ -549,7 +571,6 @@ export function NativeDateField({
ref={el => {
disabledMessageTooltip.ref(el);
}}
- {...rest}
{...mergeProps(
themeProps('date-input', {
size,
@@ -567,10 +588,10 @@ export function NativeDateField({
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
<button
@@ -593,6 +614,7 @@ export function NativeDateField({
</button>
<span {...stylex.props(styles.slot)}>
<input
+ {...controlProps}
ref={mergedInputRef}
id={id}
type="date"
@@ -600,14 +622,18 @@ export function NativeDateField({
// mount — see `initialValueRef` and the sync effect above.
defaultValue={initialValueRef.current ?? ''}
onChange={handleChange}
- onFocus={handleFocus}
- onBlur={handleBlur}
+ onFocus={chainEventHandlers(handleFocus, onFocusProp)}
+ onBlur={chainEventHandlers(handleBlur, onBlurProp)}
min={min}
max={max}
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
readOnly={showsDisabledMessage || undefined}
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy
+ }
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
@@ -661,10 +687,12 @@ export function NativeDateField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
diff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsx
index b817e3087b..eba4404ae4 100644
--- a/packages/core/src/DateInput/TouchDateField.tsx
+++ b/packages/core/src/DateInput/TouchDateField.tsx
@@ -77,6 +77,8 @@ import {Icon} from '../Icon';
import {IconButton} from '../IconButton';
import {useLocale, useTranslator} from '../i18n';
import {useInputGroup} from '../InputGroup';
+import {useFieldInputStyling} from '../Field/fieldParts';
+import {joinAriaIDs} from '../utils/inputAria';
import {groupStyles} from '../InputGroup/groupStyles';
import {useSize} from '../SizeContext';
import {Spinner} from '../Spinner';
@@ -109,6 +111,7 @@ import {
DATE_FORMAT_WEEKDAY_ONLY,
type ISODateString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {normalizeDayOfWeek} from '../utils/dateTypes';
@@ -571,12 +574,28 @@ export function TouchDateField({
weekStartsOn: weekStartsOnProp = 0,
format = 'date_long',
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
- ...rest
+ ...restProps
}: DateInputProps) {
+ const {rest, container} = useFieldInputStyling('DateInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onClick: onClickProp,
+ onKeyDown: onKeyDownProp,
+ ...controlProps
+ } = rest;
const pressable = usePressFeedback();
const t = useTranslator();
const locale = useLocale();
@@ -586,7 +605,9 @@ export function TouchDateField({
const size = useSize(sizeProp, 'md');
const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -627,6 +648,7 @@ export function TouchDateField({
statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
],
inputGroup,
);
@@ -1180,7 +1202,6 @@ export function TouchDateField({
// Gated internally by isEnabled, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
- {...rest}
{...mergeProps(
themeProps('date-input', {
size,
@@ -1198,10 +1219,10 @@ export function TouchDateField({
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
<button
@@ -1225,6 +1246,7 @@ export function TouchDateField({
/>
</button>
<input
+ {...controlProps}
ref={mergedInputRef}
id={id}
type="text"
@@ -1237,12 +1259,16 @@ export function TouchDateField({
readOnly
inputMode="none"
onChange={() => {}}
- onClick={openSheet}
- onKeyDown={handleInputKeyDown}
+ onClick={chainEventHandlers(openSheet, onClickProp)}
+ onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
placeholder={placeholder}
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy
+ }
aria-describedby={ariaDescribedBy}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
@@ -1284,10 +1310,12 @@ export function TouchDateField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
index 11074031ba..4c308ea96d 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
@@ -171,9 +171,16 @@ export const docs = {
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization.',
+ description:
+ 'StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the bordered element that holds the text, icons, and end controls, never the native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept.',
},
],
theming: {
@@ -195,6 +202,11 @@ export const docs = {
description:
'DateRangeInput lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the range trigger, the element that is focused and announced. A DOM handler runs after DateRangeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -294,6 +306,11 @@ export const docsDense = {
description:
'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the range trigger, the element that is focused and announced. A DOM handler runs after DateRangeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -365,6 +382,9 @@ export const docsDense = {
changeAction:
'async action fired after onChange; drives optimistic UI updates via useTransition',
isLoading: 'loading state; disables interaction + shows a spinner',
- xstyle: 'StyleX styles for layout',
+ containerXstyle:
+ 'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
+ controlXstyle:
+ 'visual control box (border/bg/icons), never the native input; also controlClassName/controlStyle. no root xstyle/className/style',
},
};
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.fr10.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.fr10.test.tsx
new file mode 100644
index 0000000000..d34e5c865e
--- /dev/null
+++ b/packages/core/src/DateRangeInput/DateRangeInput.fr10.test.tsx
@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DateRangeInput.fr10.test.tsx
+ * @input Uses vitest, Testing Library, DateRangeInput, FormLayout, and the input-family FR10 test helpers
+ * @output Tests that DateRangeInput takes no root styling and routes base
+ * props to its range trigger, container* to the Field box, and control* to
+ * the control box
+ * @position Colocated test for family:input-fields FR10
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, fireEvent} from '@testing-library/react';
+import {DateRangeInput, type DateRangeInputProps} from './DateRangeInput';
+import {FormLayout} from '../FormLayout';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+
+// The range trigger is the field's semantic control: it carries the value,
+// the popup state, and the accessible name.
+function trigger(): HTMLElement {
+ const el = document.querySelector<HTMLElement>(
+ 'button[aria-haspopup="dialog"]:not([tabindex="-1"])',
+ );
+ if (el == null) {
+ throw new Error('no range trigger');
+ }
+ return el;
+}
+
+// A required value callback the tests do not observe.
+const noop = () => {};
+
+describe('DateRangeInput FR10 styling contract', () => {
+ it('has no root styling props and has the container* and control* parts', () => {
+ expectFieldInputProps<DateRangeInputProps>();
+ });
+
+ it('rejects root xstyle, className, and style at compile time', () => {
+ const req = {value: null, onChange: noop};
+ const typeOnly = () => (
+ <>
+ {/* Control: the same element without root styling compiles. */}
+ <DateRangeInput {...req} label="L" controlClassName="x" />
+ {/* @ts-expect-error -- root className is not a DateRangeInput prop (FR10) */}
+ <DateRangeInput {...req} label="L" className="x" />
+ {/* @ts-expect-error -- root style is not a DateRangeInput prop (FR10) */}
+ <DateRangeInput {...req} label="L" style={{margin: 1}} />
+ {/* @ts-expect-error -- root xstyle is not a DateRangeInput prop (FR10) */}
+ <DateRangeInput {...req} label="L" xstyle={{}} />
+ </>
+ );
+ void typeOnly;
+ });
+});
+
+describeFieldInputParts('DateRangeInput', {
+ renderMember: props => (
+ <DateRangeInput value={null} onChange={noop} label="Stay" {...props} />
+ ),
+ getControl: trigger,
+});
+
+describe('DateRangeInput FR10 details', () => {
+ it('points the label at the trigger when the caller sets id', () => {
+ render(
+ <DateRangeInput value={null} onChange={noop} label="Stay" id="stay" />,
+ );
+ expect(trigger().id).toBe('stay');
+ expect(document.querySelector('label[for="stay"]')).not.toBeNull();
+ });
+
+ it("adds a caller's aria-describedby to the component's own", () => {
+ render(
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ description="Check-in to check-out"
+ aria-describedby="caller-desc"
+ />,
+ );
+ const ids = trigger().getAttribute('aria-describedby')?.split(' ');
+ expect(ids).toContain('caller-desc');
+ expect(ids?.length).toBeGreaterThan(1);
+ });
+
+ it("names the trigger by its label and range, then a caller's aria-labelledby", () => {
+ render(
+ <>
+ <span id="caller-name">Trip dates</span>
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ aria-labelledby="caller-name"
+ />
+ </>,
+ );
+ const ids = trigger().getAttribute('aria-labelledby')?.split(' ');
+ expect(ids?.at(-1)).toBe('caller-name');
+ expect(document.getElementById(ids?.[0] ?? '')?.textContent).toMatch(
+ /^Stay: /,
+ );
+ });
+
+ it("uses a caller's aria-label as the trigger's name", () => {
+ render(
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ aria-label="Trip dates"
+ />,
+ );
+ expect(trigger()).toHaveAttribute('aria-label', 'Trip dates');
+ });
+
+ it('keeps control* on the control box in a horizontal-labels FormLayout', () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <FormLayout direction="horizontal-labels">
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ controlClassName="fr10-control"
+ />
+ </FormLayout>,
+ );
+ const box = container.querySelector('.fr10-control');
+ expect(box).not.toBeNull();
+ expect(box).toContainElement(trigger());
+ expect(box).not.toBe(trigger());
+ vi.restoreAllMocks();
+ });
+
+ it('runs a caller onClick after the trigger opens the calendar', () => {
+ const onClick = vi.fn();
+ render(
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ onClick={onClick}
+ />,
+ );
+ fireEvent.click(trigger());
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(trigger()).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('does not let a caller onClick cancel opening the calendar', () => {
+ render(
+ <DateRangeInput
+ value={null}
+ onChange={noop}
+ label="Stay"
+ onClick={event => event.preventDefault()}
+ />,
+ );
+ fireEvent.click(trigger());
+ expect(trigger()).toHaveAttribute('aria-expanded', 'true');
+ });
+});
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsx
index eb8dcb4353..43aeda46c8 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx
@@ -59,7 +59,12 @@ import {useCalendarConstraints} from '../Calendar/hooks';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {mergeProps} from '../utils';
-import type {BaseProps} from '../BaseProps';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
+import {joinAriaIDs} from '../utils/inputAria';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -253,7 +258,7 @@ function isRangeWithinSpan(
}
export interface DateRangeInputProps extends Omit<
- BaseProps,
+ FieldInputBaseProps<HTMLButtonElement>,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the trigger button */
@@ -422,7 +427,7 @@ export interface DateRangeInputProps extends Omit<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `containerXstyle` or `controlXstyle`.
*/
width?: SizeValue;
/**
@@ -449,6 +454,11 @@ export interface DateRangeInputProps extends Omit<
* A date range picker with a button trigger that opens a popover
* containing a dual-month calendar and optional preset ranges.
*
+ * Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the range trigger.
+ * A DOM handler runs after the component's own handler for the same event
+ * and still receives events the component handled, even ones it called
+ * `preventDefault` on, so it cannot cancel built-in behavior.
+ *
* @example
* ```
* <DateRangeInput
@@ -488,19 +498,37 @@ export function DateRangeInput({
numberOfMonths = 2,
weekStartsOn,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
- ...rest
+ ...restProps
}: DateRangeInputProps) {
+ const {rest, container} = useFieldInputStyling('DateRangeInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-label': ariaLabelProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onClick: onClickProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const locale = useLocale();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.dateRangeInput.placeholder');
const size = useSize(sizeProp, 'md');
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const triggerNameID = useId();
const descriptionID = useId();
const statusMessageID = useId();
const requiredID = useId();
@@ -542,6 +570,7 @@ export function DateRangeInput({
// by describing it with localized, visually hidden required text.
isEffectivelyRequired ? requiredID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
]
.filter(Boolean)
.join(' ') || undefined;
@@ -609,6 +638,7 @@ export function DateRangeInput({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
@@ -637,7 +667,6 @@ export function DateRangeInput({
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
- {...rest}
{...mergeProps(
themeProps('date-range-input', {
size,
@@ -653,10 +682,10 @@ export function DateRangeInput({
!isEffectivelyDisabled &&
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
<button
type="button"
@@ -683,16 +712,24 @@ export function DateRangeInput({
/>
</button>
<button
+ {...controlProps}
ref={ref}
id={id}
type="button"
- onClick={handleToggle}
+ onClick={chainEventHandlers(handleToggle, onClickProp)}
// With a disabledMessage the trigger keeps focusability via
// aria-disabled so the reason is focus-discoverable; activation is
// still blocked by the isEffectivelyDisabled guard in handleToggle.
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
- aria-label={triggerAriaLabel}
+ // A caller aria-label replaces the trigger's name; a caller
+ // aria-labelledby is read after it (label and selected range).
+ aria-label={ariaLabelProp ?? triggerAriaLabel}
+ aria-labelledby={
+ ariaLabelledByProp != null
+ ? joinAriaIDs(triggerNameID, ariaLabelledByProp)
+ : undefined
+ }
aria-describedby={ariaDescribedBy}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
@@ -712,6 +749,11 @@ export function DateRangeInput({
onClick={handleClear}
/>
)}
+ {ariaLabelledByProp != null && (
+ <VisuallyHidden id={triggerNameID}>
+ {ariaLabelProp ?? triggerAriaLabel}
+ </VisuallyHidden>
+ )}
{isBusy && <Spinner size="sm" />}
{statusIcon}
</div>
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
index 45434de3f3..12c2c632f3 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
@@ -209,10 +209,16 @@ export const docs = {
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+ 'StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the row that holds the bordered date and time segments with their icons and end controls, never a native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept.',
},
],
theming: {
@@ -240,6 +246,11 @@ export const docs = {
description:
'DateTimeInput combines date and time selection in one field. With presentation="adaptive-native" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. presentation="native" uses both native controls on every pointer; presentation="adaptive-bottom-sheet" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers; "popover" and "bottom-sheet" force one Astryx surface on every pointer. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateTimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -358,6 +369,11 @@ export const docsZh = {
description:
'DateTimeInput combines date and time selection in one field. With presentation="adaptive-native" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. presentation="native" uses both native controls on every pointer; presentation="adaptive-bottom-sheet" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers; "popover" and "bottom-sheet" force one Astryx surface on every pointer. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateTimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -565,10 +581,16 @@ export const docsZh = {
default: "'touch'",
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
+ type: 'StyleXStyles',
+ description:
+ '作用于包含标签、控件和状态的 Field 容器的 StyleX 样式;containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时(InputGroup 内或 horizontal-labels FormLayout 中)不生效,并在开发环境发出警告。',
+ },
+ {
+ name: 'controlXstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+ '作用于可见控件框(容纳带边框的日期与时间分段及其图标和末端控件的行,而非原生 input)的 StyleX 样式;controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。',
},
],
theming: {
@@ -602,6 +624,11 @@ export const docsDense = {
description:
'DateTimeInput combines date and time selection. presentation="adaptive-native" (default) uses browser/OS date+time controls on coarse pointers and Astryx pointer fields on fine pointers; "native" uses both native controls everywhere; "adaptive-bottom-sheet" uses Astryx\'s coordinated bottom sheet on coarse pointers and pointer fields on fine pointers; "popover"/"bottom-sheet" force one Astryx surface everywhere. Closed segments stay side by side when at least 400px is available and wrap below 400px.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the date input, the element that is focused and announced. A DOM handler runs after DateTimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -684,6 +711,9 @@ export const docsDense = {
"date+time surfaces: 'adaptive-native' (default) = Astryx popovers fine / browser/OS coarse w/ per-segment fallbacks (seconds/timeIncrement/timeOptionInterval); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popovers fine / coordinated sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens pickers (no typed-only value; that is TimeInput's).",
nativePicker:
"deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
- xstyle: 'StyleX styles for layout; must be stylex.create() value',
+ containerXstyle:
+ 'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
+ controlXstyle:
+ 'visual control box = the row holding the date and time segments, never a native input; also controlClassName/controlStyle. no root xstyle/className/style',
},
};
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.fr10.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.fr10.test.tsx
new file mode 100644
index 0000000000..9793e2e84b
--- /dev/null
+++ b/packages/core/src/DateTimeInput/DateTimeInput.fr10.test.tsx
@@ -0,0 +1,319 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DateTimeInput.fr10.test.tsx
+ * @input Uses vitest, Testing Library, DateTimeInput, FormLayout, and the input-family FR10 test helpers
+ * @output Tests that every DateTimeInput surface takes no root styling and routes
+ * base props, container*, and control* to their FR10 targets
+ * @position Colocated test for family:input-fields FR10
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {DateTimeInput, type DateTimeInputProps} from './DateTimeInput';
+import {FormLayout} from '../FormLayout';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+
+// The date input is the field's semantic control: the label names it.
+const SURFACES = [
+ ['pointer', 'popover', 'input[role="combobox"]'],
+ ['native', 'native', 'input[type="date"]'],
+ ['touch', 'bottom-sheet', 'input[role="combobox"]'],
+] as const;
+
+// The touch surface's month scroller measures itself and its sheet is a
+// modal <dialog>; jsdom implements neither.
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+beforeAll(() => {
+ Element.prototype.scrollTo = vi.fn();
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.open = true;
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.open = false;
+ });
+});
+
+beforeEach(() => {
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function control(selector: string): HTMLElement {
+ const el = document.querySelector<HTMLElement>(selector);
+ if (el == null) {
+ throw new Error(`no control matching ${selector}`);
+ }
+ return el;
+}
+
+// A required value callback the tests do not observe.
+const noop = () => {};
+
+describe('DateTimeInput FR10 styling contract', () => {
+ it('has no root styling props and has the container* and control* parts', () => {
+ expectFieldInputProps<DateTimeInputProps>();
+ });
+
+ it('rejects root xstyle, className, and style at compile time', () => {
+ const typeOnly = () => (
+ <>
+ {/* Control: the same element without root styling compiles. */}
+ <DateTimeInput
+ onChange={noop}
+ label="L"
+ controlClassName="x"
+ containerClassName="y"
+ />
+ {/* @ts-expect-error -- root className is not a DateTimeInput prop (FR10) */}
+ <DateTimeInput onChange={noop} label="L" className="x" />
+ {/* @ts-expect-error -- root style is not a DateTimeInput prop (FR10) */}
+ <DateTimeInput onChange={noop} label="L" style={{margin: 1}} />
+ {/* @ts-expect-error -- root xstyle is not a DateTimeInput prop (FR10) */}
+ <DateTimeInput onChange={noop} label="L" xstyle={{}} />
+ </>
+ );
+ void typeOnly;
+ });
+});
+
+for (const [surface, presentation, selector] of SURFACES) {
+ describe(`${surface} surface`, () => {
+ describeFieldInputParts('DateTimeInput', {
+ renderMember: props => (
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation={presentation}
+ {...props}
+ />
+ ),
+ getControl: () => control(selector),
+ inGroup: false,
+ });
+ });
+
+ describe(`DateTimeInput (${surface}) FR10 details`, () => {
+ it('names the control from its label when the caller sets id', () => {
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation={presentation}
+ id="due"
+ />,
+ );
+ expect(control(selector).id).toBe('due');
+ expect(document.querySelector('label[for="due"]')).not.toBeNull();
+ });
+
+ it("adds a caller's aria-describedby to the component's own", () => {
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ description="Pick a weekday"
+ presentation={presentation}
+ aria-describedby="caller-desc"
+ />,
+ );
+ const ids = control(selector)
+ .getAttribute('aria-describedby')
+ ?.split(' ');
+ expect(ids).toContain('caller-desc');
+ expect(ids?.length).toBeGreaterThan(1);
+ });
+
+ it('keeps component-only props off the control', () => {
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation={presentation}
+ hasSeconds
+ hourFormat="24h"
+ timeIncrement={5}
+ timeOptionInterval={30}
+ timeLabel="Time"
+ timePlaceholder="hh:mm"
+ numberOfMonths={2}
+ weekStartsOn={1}
+ hasClear
+ size="sm"
+ labelTooltip="tip"
+ placeholder="Pick"
+ isOptional
+ width={240}
+ />,
+ );
+ const attrs = [...control(selector).attributes].map(a => a.name);
+ for (const prop of [
+ 'increment',
+ 'hasautofocus',
+ 'timeincrement',
+ 'timeoptioninterval',
+ 'numberofmonths',
+ 'weekstartson',
+ 'dateconstraints',
+ 'hasclear',
+ 'hasseconds',
+ 'hourformat',
+ 'statusvariant',
+ 'labeltooltip',
+ 'format',
+ 'width',
+ 'size',
+ ]) {
+ expect(attrs).not.toContain(prop);
+ }
+ expect(
+ error.mock.calls.filter(call =>
+ /React does not recognize|Invalid value for prop|non-boolean attribute/.test(
+ String(call[0]),
+ ),
+ ),
+ ).toEqual([]);
+ error.mockRestore();
+ });
+
+ it("names the control by its label and then a caller's aria-labelledby", () => {
+ render(
+ <>
+ <span id="caller-name">Billing</span>
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation={presentation}
+ aria-labelledby="caller-name"
+ />
+ </>,
+ );
+ const ids = control(selector).getAttribute('aria-labelledby')?.split(' ');
+ expect(ids?.at(-1)).toBe('caller-name');
+ const own = document.getElementById(ids?.[0] ?? '');
+ expect(own?.tagName).toBe('LABEL');
+ expect(own?.textContent).toContain('Due');
+ });
+
+ it('keeps control* on the control box in a horizontal-labels FormLayout', () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <FormLayout direction="horizontal-labels">
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation={presentation}
+ controlClassName="fr10-control"
+ />
+ </FormLayout>,
+ );
+ const box = container.querySelector('.fr10-control');
+ expect(box).not.toBeNull();
+ expect(box).toContainElement(control(selector));
+ expect(box).not.toBe(control(selector));
+ vi.restoreAllMocks();
+ });
+ });
+}
+
+describe('DateTimeInput FR10 handler composition', () => {
+ it('runs a caller onClick after the pointer field opens its calendar', () => {
+ const onClick = vi.fn();
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation="popover"
+ onClick={onClick}
+ />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Due'});
+ fireEvent.click(input);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('runs a caller onKeyDown for keys the field does not consume', () => {
+ const onKeyDown = vi.fn();
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation="popover"
+ onKeyDown={onKeyDown}
+ />,
+ );
+ fireEvent.keyDown(screen.getByRole('combobox', {name: 'Due'}), {key: 'a'});
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ });
+
+ it('runs a caller onClick after the touch field opens its sheet', () => {
+ const onClick = vi.fn();
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation="bottom-sheet"
+ onClick={onClick}
+ />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Due'});
+ fireEvent.click(input);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('still hands a caller onKeyDown the keys the field consumes, after the field', () => {
+ const seen: {key: string; defaultPrevented: boolean}[] = [];
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation="popover"
+ onKeyDown={event =>
+ seen.push({key: event.key, defaultPrevented: event.defaultPrevented})
+ }
+ />,
+ );
+ fireEvent.keyDown(screen.getByRole('combobox', {name: 'Due'}), {
+ key: 'Enter',
+ });
+ expect(seen).toEqual([{key: 'Enter', defaultPrevented: true}]);
+ });
+
+ it('runs a caller onBlur on the native field', () => {
+ const onBlur = vi.fn();
+ render(
+ <DateTimeInput
+ onChange={noop}
+ label="Due"
+ presentation="native"
+ onBlur={onBlur}
+ />,
+ );
+ const input = control('input[type="date"]');
+ fireEvent.focus(input);
+ fireEvent.blur(input);
+ expect(onBlur).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index ae98ad595c..6b39564109 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -80,6 +80,8 @@ import {
mergeProps,
isFocusDetached,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
+import {joinAriaIDs} from '../utils/inputAria';
import {
plainDateFromISO,
plainDateToISO,
@@ -87,7 +89,10 @@ import {
DATE_FORMAT_LONG,
} from '../utils/plainDate';
-import type {BaseProps} from '../BaseProps';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {useAnnounce} from '../hooks/useAnnounce';
import {useMediaQuery} from '../hooks/useMediaQuery';
@@ -284,7 +289,7 @@ const sizeStyles = stylex.create({
});
export interface DateTimeInputProps extends Omit<
- BaseProps,
+ FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the date input element */
@@ -466,7 +471,7 @@ export interface DateTimeInputProps extends Omit<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `containerXstyle` or `controlXstyle`.
*/
width?: SizeValue;
/**
@@ -619,15 +624,32 @@ function PointerDateTimeField({
numberOfMonths = 1,
weekStartsOn,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
nativeMode = 'off',
- ...rest
+ ...restProps
}: DateTimeInputProps & {
nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy';
}) {
+ const {rest, container} = useFieldInputStyling('DateTimeInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onBlur: onBlurProp,
+ onClick: onClickProp,
+ onKeyDown: onKeyDownProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const locale = useLocale();
const usesNativePicker = nativeMode !== 'off';
@@ -652,7 +674,15 @@ function PointerDateTimeField({
const timePlaceholder =
timePlaceholderFromProps ?? t('@astryx.dateTimeInput.timePlaceholder');
const size = useSize(sizeProp, 'md');
- const dateInputId = useId();
+ const generatedID = useId();
+ const dateInputId = idProp ?? generatedID;
+ const fieldLabelID = useId();
+ // A caller aria-labelledby names the date input together with the field's
+ // own label.
+ const controlLabelledBy =
+ ariaLabelledByProp != null
+ ? joinAriaIDs(fieldLabelID, ariaLabelledByProp)
+ : undefined;
const timeInputId = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -706,6 +736,7 @@ function PointerDateTimeField({
status?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
]
.filter(Boolean)
.join(' ') || undefined;
@@ -1582,10 +1613,12 @@ function PointerDateTimeField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={dateInputId}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -1604,7 +1637,6 @@ function PointerDateTimeField({
width={width}>
<div
ref={disabledMessageTooltip.ref}
- {...rest}
{...mergeProps(
themeProps('date-time-input', {
size,
@@ -1614,10 +1646,10 @@ function PointerDateTimeField({
stylex.props(
styles.row,
usesNativePicker && styles.nativeRow,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{/* Date input */}
<div
@@ -1655,6 +1687,13 @@ function PointerDateTimeField({
isBusy={isBusy}
statusType={status?.type}
ariaDescribedBy={ariaDescribedBy}
+ controlProps={{
+ ...controlProps,
+ 'aria-labelledby': controlLabelledBy,
+ onBlur: onBlurProp,
+ onClick: onClickProp,
+ onKeyDown: onKeyDownProp,
+ }}
/>
) : (
<>
@@ -1688,15 +1727,17 @@ function PointerDateTimeField({
/>
</button>
<input
+ {...controlProps}
ref={mergedDateInputRef}
id={dateInputId}
type="text"
role="combobox"
value={dateDisplayValue}
onChange={handleDateInputChange}
- onBlur={handleDateBlur}
- onClick={handleDateInputClick}
- onKeyDown={handleDateKeyDown}
+ onBlur={chainEventHandlers(handleDateBlur, onBlurProp)}
+ onClick={chainEventHandlers(handleDateInputClick, onClickProp)}
+ onKeyDown={chainEventHandlers(handleDateKeyDown, onKeyDownProp)}
+ aria-labelledby={controlLabelledBy}
placeholder={placeholder}
// With a disabledMessage the input keeps focusability via
// aria-disabled so the reason is focus-discoverable; typing is
@@ -1952,6 +1993,11 @@ PointerDateTimeField.displayName = 'PointerDateTimeField';
* surfaces (`spec:AST-043`). Native modes use OS-owned date and time controls
* in Astryx field chrome; the deprecated `nativePicker` maps to the same
* surfaces (FR3).
+ *
+ * Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the date input.
+ * A DOM handler runs after the component's own handler for the same event
+ * and still receives events the component handled, even ones it called
+ * `preventDefault` on, so it cannot cancel built-in behavior.
*/
export function DateTimeInput(props: DateTimeInputProps) {
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
diff --git a/packages/core/src/DateTimeInput/NativeDateSegment.tsx b/packages/core/src/DateTimeInput/NativeDateSegment.tsx
index b59177da45..74e67ef8d7 100644
--- a/packages/core/src/DateTimeInput/NativeDateSegment.tsx
+++ b/packages/core/src/DateTimeInput/NativeDateSegment.tsx
@@ -25,6 +25,10 @@
import {useCallback, useEffect, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
+import type {
+ FieldInputBaseProps,
+ FieldPartStyleProps,
+} from '../Field/fieldParts';
import {hasEditableDateSegments} from '../DateInput/nativeDateSegments';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -40,6 +44,7 @@ import {
themeProps,
type ISODateString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
import type {InputStatusType} from '../Field';
import {nativePickerSegmentStyles as styles} from './nativePickerSegmentStyles';
@@ -60,6 +65,15 @@ export type NativeDateSegmentProps = {
isBusy: boolean;
statusType?: InputStatusType;
ariaDescribedBy?: string;
+ /**
+ * The caller's base props (data-*, aria-*, DOM handlers, …) for the native
+ * input, the field's semantic control (family:input-fields FR10). Focus and
+ * blur handlers run after the segment's own.
+ */
+ controlProps?: Omit<
+ FieldInputBaseProps<HTMLInputElement>,
+ keyof FieldPartStyleProps | 'onChange' | 'defaultValue'
+ >;
};
/** The native date half rendered inside DateTimeInput's date wrapper. */
@@ -78,7 +92,13 @@ export function NativeDateSegment({
isBusy,
statusType,
ariaDescribedBy,
+ controlProps,
}: NativeDateSegmentProps) {
+ const {
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ ...inputProps
+ } = controlProps ?? {};
const t = useTranslator();
const locale = useLocale();
const isTouchPointer = useMediaQuery('(pointer: coarse)');
@@ -259,14 +279,15 @@ export function NativeDateSegment({
</button>
<span {...stylex.props(styles.slot)}>
<input
+ {...inputProps}
ref={mergedInputRef}
id={id}
type="date"
// UNCONTROLLED on purpose; see initialValueRef and the sync effect.
defaultValue={initialValueRef.current ?? ''}
onChange={handleChange}
- onFocus={handleFocus}
- onBlur={handleBlur}
+ onFocus={chainEventHandlers(handleFocus, onFocusProp)}
+ onBlur={chainEventHandlers(handleBlur, onBlurProp)}
min={min}
max={max}
disabled={isEffectivelyDisabled && !hasDisabledMessage}
diff --git a/packages/core/src/DateTimeInput/NativeTimeSegment.tsx b/packages/core/src/DateTimeInput/NativeTimeSegment.tsx
index c88be2ccb3..0b1d54fc03 100644
--- a/packages/core/src/DateTimeInput/NativeTimeSegment.tsx
+++ b/packages/core/src/DateTimeInput/NativeTimeSegment.tsx
@@ -25,6 +25,10 @@
import {useCallback, useEffect, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
+import type {
+ FieldInputBaseProps,
+ FieldPartStyleProps,
+} from '../Field/fieldParts';
import {hasEditableDateSegments} from '../DateInput/nativeDateSegments';
import type {InputStatusType} from '../Field';
import {useMediaQuery} from '../hooks/useMediaQuery';
@@ -42,6 +46,7 @@ import {
parseISOTime,
type ISOTimeString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
import {nativePickerSegmentStyles as styles} from './nativePickerSegmentStyles';
const FRACTIONAL_SECONDS = /\.\d+$/;
@@ -80,6 +85,15 @@ export type NativeTimeSegmentProps = {
isBusy: boolean;
statusType?: InputStatusType;
ariaDescribedBy?: string;
+ /**
+ * The caller's base props (data-*, aria-*, DOM handlers, …) for the native
+ * input, the field's semantic control (family:input-fields FR10). Focus and
+ * blur handlers run after the segment's own.
+ */
+ controlProps?: Omit<
+ FieldInputBaseProps<HTMLInputElement>,
+ keyof FieldPartStyleProps | 'onChange' | 'defaultValue'
+ >;
};
/** The shared native time control rendered inside Astryx field chrome. */
@@ -103,7 +117,13 @@ export function NativeTimeSegment({
isBusy,
statusType,
ariaDescribedBy,
+ controlProps,
}: NativeTimeSegmentProps) {
+ const {
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ ...inputProps
+ } = controlProps ?? {};
const t = useTranslator();
const isTouchPointer = useMediaQuery('(pointer: coarse)');
const internalInputRef = useRef<HTMLInputElement | null>(null);
@@ -277,21 +297,28 @@ export function NativeTimeSegment({
</button>
<span {...stylex.props(styles.slot)}>
<input
+ {...inputProps}
ref={mergedInputRef}
id={id}
type="time"
// UNCONTROLLED on purpose; see initialValueRef and the sync effect.
defaultValue={initialValueRef.current ?? ''}
onChange={handleChange}
- onFocus={handleFocus}
- onBlur={handleBlur}
+ onFocus={chainEventHandlers(handleFocus, onFocusProp)}
+ onBlur={chainEventHandlers(handleBlur, onBlurProp)}
min={min}
max={max}
step={60}
disabled={isEffectivelyDisabled && !hasDisabledMessage}
aria-disabled={hasDisabledMessage ? 'true' : undefined}
readOnly={hasDisabledMessage || undefined}
- aria-label={ariaLabelledBy ? undefined : inputLabel}
+ // The segment's own label applies only when nothing else names it;
+ // otherwise a caller aria-label from the spread above stays.
+ aria-label={
+ !ariaLabelledBy && inputLabel
+ ? inputLabel
+ : inputProps['aria-label']
+ }
aria-labelledby={ariaLabelledBy}
aria-describedby={ariaDescribedBy}
autoFocus={hasAutoFocus}
diff --git a/packages/core/src/DateTimeInput/TouchDateTimeField.tsx b/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
index 6337d8877a..349f24681e 100644
--- a/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
+++ b/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
@@ -54,6 +54,7 @@ import {SegmentedControl, SegmentedControlItem} from '../SegmentedControl';
import {useSize} from '../SizeContext/SizeContext';
import {Spinner} from '../Spinner';
import {useTooltip} from '../Tooltip';
+import {useFieldInputStyling} from '../Field/fieldParts';
import {
colorVars,
fontWeightVars,
@@ -79,6 +80,8 @@ import {
parseISOTime,
type ISOTimeString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
+import {joinAriaIDs} from '../utils/inputAria';
import {
DATE_FORMAT_LONG,
DATE_FORMAT_MONTH_YEAR,
@@ -467,12 +470,28 @@ export function TouchDateTimeField({
numberOfMonths: _numberOfMonths,
weekStartsOn: weekStartsOnProp = 0,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
- ...rest
+ ...restProps
}: DateTimeInputProps) {
+ const {rest, container} = useFieldInputStyling('DateTimeInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onClick: onClickProp,
+ onKeyDown: onKeyDownProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const {locale} = use(InternationalizationContext);
@@ -483,7 +502,15 @@ export function TouchDateTimeField({
const resolvedTimeLabel =
timeLabel ?? t('@astryx.dateTimeInput.timeSuffix', {label});
const size = useSize(sizeProp, 'md');
- const dateInputId = useId();
+ const generatedID = useId();
+ const dateInputId = idProp ?? generatedID;
+ const fieldLabelID = useId();
+ // A caller aria-labelledby names the date input together with the field's
+ // own label.
+ const controlLabelledBy =
+ ariaLabelledByProp != null
+ ? joinAriaIDs(fieldLabelID, ariaLabelledByProp)
+ : undefined;
const timeInputId = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -518,6 +545,7 @@ export function TouchDateTimeField({
status?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
]
.filter(Boolean)
.join(' ') || undefined;
@@ -1236,10 +1264,12 @@ export function TouchDateTimeField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={dateInputId}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -1260,16 +1290,15 @@ export function TouchDateTimeField({
ref={el => {
disabledMessageTooltip.ref(el);
}}
- {...rest}
{...mergeProps(
themeProps('date-time-input', {
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
}),
- stylex.props(styles.touchRow, xstyle),
- className,
- style,
+ stylex.props(styles.touchRow, controlXstyle),
+ controlClassName,
+ controlStyle,
)}>
<div
onClick={event => {
@@ -1315,6 +1344,7 @@ export function TouchDateTimeField({
/>
</button>
<input
+ {...controlProps}
ref={mergedDateInputRef}
id={dateInputId}
type="text"
@@ -1323,8 +1353,13 @@ export function TouchDateTimeField({
readOnly
inputMode="none"
onChange={() => {}}
- onClick={() => openSheet('date')}
- onKeyDown={event => handleInputKeyDown(event, 'date')}
+ onClick={chainEventHandlers(() => openSheet('date'), onClickProp)}
+ onKeyDown={chainEventHandlers(
+ (event: React.KeyboardEvent<HTMLInputElement>) =>
+ handleInputKeyDown(event, 'date'),
+ onKeyDownProp,
+ )}
+ aria-labelledby={controlLabelledBy}
placeholder={placeholder}
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
diff --git a/packages/core/src/Field/fieldInputFamily.test.tsx b/packages/core/src/Field/fieldInputFamily.test.tsx
index a74c02b0cb..4b3f96040d 100644
--- a/packages/core/src/Field/fieldInputFamily.test.tsx
+++ b/packages/core/src/Field/fieldInputFamily.test.tsx
@@ -20,10 +20,6 @@ const NOT_FIELD_INPUTS = new Set(['Field', 'InputGroup', 'FormLayout']);
const PENDING_FR10 = new Set([
// text batch
// date/time batch
- 'DateInput',
- 'DateRangeInput',
- 'DateTimeInput',
- 'TimeInput',
// selector batch
'Selector',
'MultiSelector',
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index edca28b66f..8c14cf20ac 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -23,6 +23,11 @@ export const docs = {
description:
"TimeInput uses a browser/OS time picker on coarse pointers by default and Astryx's typed field on fine pointers. It converts values to a standard format and supports arrow-key adjustment on the typed surface. Use it in forms, scheduling flows, or any interface where users need to select a specific time.",
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the time input, the element that is focused and announced. A DOM handler runs after TimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -263,10 +268,16 @@ export const docs = {
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the Field box around the label, control, and status. containerClassName and containerStyle take a class name and inline styles for the same box. No effect (development warning) where no Field box renders: inside InputGroup (style the group) and in a horizontal-labels FormLayout.',
+ },
+ {
+ name: 'controlXstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+ 'StyleX styles for the visual control box: the bordered element that holds the text, icons, and end controls, never the native input. controlClassName and controlStyle take a class name and inline styles for the same box. Replaces root xstyle, className, and style, which this component does not accept.',
},
],
theming: {
@@ -430,10 +441,16 @@ export const docsZh = {
description: '在标签行末尾以信息图标形式渲染的工具提示文本。',
},
{
- name: 'xstyle',
+ name: 'containerXstyle',
+ type: 'StyleXStyles',
+ description:
+ '作用于包含标签、控件和状态的 Field 容器的 StyleX 样式;containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时(InputGroup 内或 horizontal-labels FormLayout 中)不生效,并在开发环境发出警告。',
+ },
+ {
+ name: 'controlXstyle',
type: 'StyleXStyles',
description:
- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ '作用于可见控件框(带边框、包含文本、图标和末端控件的元素,而非原生 input)的 StyleX 样式;controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。',
},
],
theming: {
@@ -449,6 +466,11 @@ export const docsZh = {
description:
'TimeInput 默认在粗指针设备上使用浏览器/操作系统的时间选择器,在精细指针设备上使用 Astryx 文本字段。它将时间转换为标准格式,并在文本字段界面支持方向键调整。适用于表单、排期流程和其他时间选择场景。',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the time input, the element that is focused and announced. A DOM handler runs after TimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -533,6 +555,11 @@ export const docsDense = {
description:
'TimeInput uses a browser/OS picker on coarse pointers by default and Astryx typed entry on fine pointers. It standardizes values and supports arrow-key adjustment on the typed surface.',
bestPractices: [
+ {
+ guidance: true,
+ description:
+ "Base props such as ref, id, data-*, aria-*, and DOM event handlers go to the time input, the element that is focused and announced. A DOM handler runs after TimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.",
+ },
{
guidance: true,
description:
@@ -607,7 +634,9 @@ export const docsDense = {
statusVariant:
'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'Tooltip as info icon at label row end.',
- xstyle:
- 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
+ containerXstyle:
+ 'Field box (label+control+status); also containerClassName/containerStyle. no effect in InputGroup or horizontal-labels FormLayout',
+ controlXstyle:
+ 'visual control box (border/bg/icons), never the native input; also controlClassName/controlStyle. no root xstyle/className/style',
},
};
diff --git a/packages/core/src/TimeInput/TimeInput.fr10.test.tsx b/packages/core/src/TimeInput/TimeInput.fr10.test.tsx
new file mode 100644
index 0000000000..97d588a75d
--- /dev/null
+++ b/packages/core/src/TimeInput/TimeInput.fr10.test.tsx
@@ -0,0 +1,297 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TimeInput.fr10.test.tsx
+ * @input Uses vitest, Testing Library, TimeInput, FormLayout, and the input-family FR10 test helpers
+ * @output Tests that every TimeInput surface takes no root styling and routes
+ * base props, container*, and control* to their FR10 targets
+ * @position Colocated test for family:input-fields FR10
+ */
+
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {TimeInput, type TimeInputProps} from './TimeInput';
+import type {ISOTimeString} from '../utils';
+import {FormLayout} from '../FormLayout';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+
+const SURFACES = [
+ ['typed', 'text-input', 'input[type="text"]'],
+ ['native', 'native', 'input[type="time"]'],
+ ['touch', 'bottom-sheet', 'input[role="combobox"]'],
+] as const;
+
+// The touch surface's wheels measure themselves and its sheet is a
+// modal <dialog>; jsdom implements neither.
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+beforeAll(() => {
+ Element.prototype.scrollTo = vi.fn();
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.open = true;
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.open = false;
+ });
+});
+
+beforeEach(() => {
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function control(selector: string): HTMLElement {
+ const el = document.querySelector<HTMLElement>(selector);
+ if (el == null) {
+ throw new Error(`no control matching ${selector}`);
+ }
+ return el;
+}
+
+describe('TimeInput FR10 styling contract', () => {
+ it('has no root styling props and has the container* and control* parts', () => {
+ expectFieldInputProps<TimeInputProps>();
+ });
+
+ it('rejects root xstyle, className, and style at compile time', () => {
+ const typeOnly = () => (
+ <>
+ {/* Control: the same element without root styling compiles. */}
+ <TimeInput label="L" controlClassName="x" containerClassName="y" />
+ {/* @ts-expect-error -- root className is not a TimeInput prop (FR10) */}
+ <TimeInput label="L" className="x" />
+ {/* @ts-expect-error -- root style is not a TimeInput prop (FR10) */}
+ <TimeInput label="L" style={{margin: 1}} />
+ {/* @ts-expect-error -- root xstyle is not a TimeInput prop (FR10) */}
+ <TimeInput label="L" xstyle={{}} />
+ </>
+ );
+ void typeOnly;
+ });
+});
+
+for (const [surface, presentation, selector] of SURFACES) {
+ describe(`${surface} surface`, () => {
+ describeFieldInputParts('TimeInput', {
+ renderMember: props => (
+ <TimeInput label="Start" presentation={presentation} {...props} />
+ ),
+ getControl: () => control(selector),
+ inGroup: true,
+ });
+ });
+
+ describe(`TimeInput (${surface}) FR10 details`, () => {
+ it('names the control from its label when the caller sets id', () => {
+ render(
+ <TimeInput label="Start" presentation={presentation} id="start" />,
+ );
+ expect(control(selector).id).toBe('start');
+ expect(document.querySelector('label[for="start"]')).not.toBeNull();
+ });
+
+ it("adds a caller's aria-describedby to the component's own", () => {
+ render(
+ <TimeInput
+ label="Start"
+ description="Local time"
+ presentation={presentation}
+ aria-describedby="caller-desc"
+ />,
+ );
+ const ids = control(selector)
+ .getAttribute('aria-describedby')
+ ?.split(' ');
+ expect(ids).toContain('caller-desc');
+ expect(ids?.length).toBeGreaterThan(1);
+ });
+
+ it('keeps component-only props off the control', () => {
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+ render(
+ <TimeInput
+ label="Start"
+ presentation={presentation}
+ hasSeconds
+ hourFormat="24h"
+ increment={5}
+ hasAutoFocus
+ hasClear
+ size="sm"
+ statusVariant="detached"
+ labelTooltip="tip"
+ placeholder="Pick"
+ isOptional
+ width={240}
+ />,
+ );
+ const attrs = [...control(selector).attributes].map(a => a.name);
+ for (const prop of [
+ 'increment',
+ 'hasautofocus',
+ 'timeincrement',
+ 'timeoptioninterval',
+ 'numberofmonths',
+ 'weekstartson',
+ 'dateconstraints',
+ 'hasclear',
+ 'hasseconds',
+ 'hourformat',
+ 'statusvariant',
+ 'labeltooltip',
+ 'format',
+ 'width',
+ 'size',
+ ]) {
+ expect(attrs).not.toContain(prop);
+ }
+ expect(
+ error.mock.calls.filter(call =>
+ /React does not recognize|Invalid value for prop|non-boolean attribute/.test(
+ String(call[0]),
+ ),
+ ),
+ ).toEqual([]);
+ error.mockRestore();
+ });
+
+ it("names the control by its label and then a caller's aria-labelledby", () => {
+ render(
+ <>
+ <span id="caller-name">Billing</span>
+ <TimeInput
+ label="Start"
+ presentation={presentation}
+ aria-labelledby="caller-name"
+ />
+ </>,
+ );
+ const ids = control(selector).getAttribute('aria-labelledby')?.split(' ');
+ expect(ids?.at(-1)).toBe('caller-name');
+ const own = document.getElementById(ids?.[0] ?? '');
+ expect(own?.tagName).toBe('LABEL');
+ expect(own?.textContent).toContain('Start');
+ });
+
+ it('keeps control* on the control box in a horizontal-labels FormLayout', () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <FormLayout direction="horizontal-labels">
+ <TimeInput
+ label="Start"
+ presentation={presentation}
+ controlClassName="fr10-control"
+ />
+ </FormLayout>,
+ );
+ const box = container.querySelector('.fr10-control');
+ expect(box).not.toBeNull();
+ expect(box).toContainElement(control(selector));
+ expect(box).not.toBe(control(selector));
+ vi.restoreAllMocks();
+ });
+ });
+}
+
+describe('TimeInput FR10 handler composition', () => {
+ it('runs a caller onBlur after the typed field commits its value', () => {
+ const onBlur = vi.fn();
+ const onChange = vi.fn();
+ render(
+ <TimeInput
+ label="Start"
+ presentation="text-input"
+ onBlur={onBlur}
+ onChange={onChange}
+ />,
+ );
+ const input = control('input[type="text"]');
+ fireEvent.focus(input);
+ fireEvent.change(input, {target: {value: '2:30 PM'}});
+ fireEvent.blur(input);
+ expect(onChange).toHaveBeenLastCalledWith('14:30');
+ expect(onBlur).toHaveBeenCalledOnce();
+ });
+
+ it('runs a caller onKeyDown for keys the typed field does not consume', () => {
+ const onKeyDown = vi.fn();
+ render(
+ <TimeInput
+ label="Start"
+ presentation="text-input"
+ onKeyDown={onKeyDown}
+ />,
+ );
+ fireEvent.keyDown(control('input[type="text"]'), {key: 'a'});
+ expect(onKeyDown).toHaveBeenCalledOnce();
+ });
+
+ it('still hands a caller onKeyDown the arrow keys the typed field consumes, after the field', () => {
+ const seen: {key: string; defaultPrevented: boolean}[] = [];
+ const onChange = vi.fn();
+ render(
+ <TimeInput
+ label="Start"
+ presentation="text-input"
+ value={'09:00' as ISOTimeString}
+ onChange={onChange}
+ onKeyDown={event =>
+ seen.push({key: event.key, defaultPrevented: event.defaultPrevented})
+ }
+ />,
+ );
+ fireEvent.keyDown(control('input[type="text"]'), {key: 'ArrowUp'});
+ expect(onChange).toHaveBeenCalled();
+ expect(seen).toEqual([{key: 'ArrowUp', defaultPrevented: true}]);
+ });
+
+ it('runs a caller onClick after the touch field opens its sheet', () => {
+ const onClick = vi.fn();
+ render(
+ <TimeInput label="Start" presentation="bottom-sheet" onClick={onClick} />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Start'});
+ fireEvent.click(input);
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it("puts a caller's aria-label on the native time input", () => {
+ render(
+ <TimeInput
+ label="Start"
+ presentation="native"
+ aria-label="Start (UTC)"
+ />,
+ );
+ expect(control('input[type="time"]')).toHaveAttribute(
+ 'aria-label',
+ 'Start (UTC)',
+ );
+ });
+
+ it('runs a caller onFocus on the native field', () => {
+ const onFocus = vi.fn();
+ render(<TimeInput label="Start" presentation="native" onFocus={onFocus} />);
+ fireEvent.focus(control('input[type="time"]'));
+ expect(onFocus).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 633fe2dbd5..5062a7ea3f 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -61,7 +61,12 @@ import {
mergeProps,
getInputARIA,
} from '../utils';
-import type {BaseProps} from '../BaseProps';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
+import {joinAriaIDs} from '../utils/inputAria';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useAnnounce} from '../hooks/useAnnounce';
@@ -160,10 +165,10 @@ export type {
} from '../Field';
export interface TimeInputProps extends Omit<
- BaseProps,
+ FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'defaultValue'
> {
- /** Ref forwarded to the root element */
+ /** Ref forwarded to the time input (the field's semantic control) */
ref?: React.Ref<HTMLInputElement>;
/**
* Label text for the input (required for accessibility).
@@ -355,7 +360,7 @@ export interface TimeInputProps extends Omit<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `containerXstyle` or `controlXstyle`.
*/
width?: SizeValue;
/**
@@ -403,12 +408,30 @@ function TimeField({
statusVariant = 'attached',
labelTooltip,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
nativeMode = 'off',
+ ...restProps
}: TimeInputProps & {nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy'}) {
+ const {rest, container} = useFieldInputStyling('TimeInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ onKeyDown: onKeyDownProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
@@ -425,7 +448,9 @@ function TimeField({
!hasSeconds &&
increment === 1);
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -483,9 +508,16 @@ function TimeField({
// tooltip's content instead so the status is still announced.
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
],
inputGroup,
);
+ // A caller aria-labelledby names the control together with the field's own
+ // label (the Field label standalone, the group and input labels in a group).
+ const controlLabelledBy =
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy;
// Pending input while user is typing (null = show formatted value)
const [pendingInput, setPendingInput] = useState<string | null>(null);
@@ -715,10 +747,10 @@ function TimeField({
status && !isDisabled && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
{inputGroup && description && (
@@ -739,7 +771,7 @@ function TimeField({
onChange={fireChange}
placeholder={placeholder}
openPickerLabel={t('@astryx.timeInput.openPicker', {label})}
- ariaLabelledBy={ariaLabelledBy}
+ ariaLabelledBy={controlLabelledBy}
hasAutoFocus={hasAutoFocus}
min={min}
max={max}
@@ -750,6 +782,12 @@ function TimeField({
isBusy={isBusy}
statusType={status?.type}
ariaDescribedBy={ariaDescribedBy}
+ controlProps={{
+ ...controlProps,
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ onKeyDown: onKeyDownProp,
+ }}
/>
) : (
<>
@@ -757,14 +795,15 @@ function TimeField({
<Icon icon="clock" size="sm" color="secondary" />
</div>
<input
+ {...controlProps}
ref={mergedInputRef}
id={id}
type="text"
value={displayValue}
onChange={handleInputChange}
- onFocus={handleFocus}
- onBlur={handleBlur}
- onKeyDown={handleInputKeyDown}
+ onFocus={chainEventHandlers(handleFocus, onFocusProp)}
+ onBlur={chainEventHandlers(handleBlur, onBlurProp)}
+ onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
placeholder={displayPlaceholder}
// With a disabledMessage the input keeps focusability via
// aria-disabled so the reason is focus-discoverable; typing and
@@ -780,7 +819,7 @@ function TimeField({
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
aria-busy={isBusy || undefined}
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={controlLabelledBy}
{...stylex.props(
styles.input,
isDisabled && styles.inputDisabled,
@@ -820,10 +859,12 @@ function TimeField({
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -853,6 +894,11 @@ TimeField.displayName = 'TimeField';
* A time input whose `presentation` prop chooses the selection surface
* (`spec:AST-043`); the deprecated `nativePicker` maps to the same surfaces
* (FR3).
+ *
+ * Base props (`ref`, `id`, `data-*`, `aria-*`, DOM event handlers) go to the time input.
+ * A DOM handler runs after the component's own handler for the same event
+ * and still receives events the component handled, even ones it called
+ * `preventDefault` on, so it cannot cancel built-in behavior.
*/
export function TimeInput(props: TimeInputProps) {
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
diff --git a/packages/core/src/TimeInput/TouchTimeField.tsx b/packages/core/src/TimeInput/TouchTimeField.tsx
index 44c20bbf08..6570b0cc3f 100644
--- a/packages/core/src/TimeInput/TouchTimeField.tsx
+++ b/packages/core/src/TimeInput/TouchTimeField.tsx
@@ -37,6 +37,8 @@ import {
inputStatusFocusWithinStyles,
} from '../Field';
import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {useFieldInputStyling} from '../Field/fieldParts';
+import {joinAriaIDs} from '../utils/inputAria';
import {groupStyles} from '../InputGroup/groupStyles';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -62,6 +64,7 @@ import {
parseISOTime,
type ISOTimeString,
} from '../utils';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
import type {TimeInputProps} from './TimeInput';
const sizeStyles = stylex.create({
@@ -190,23 +193,45 @@ export function TouchTimeField({
hasSeconds = false,
hasClear = false,
hourFormat = '12h',
+ // Typed-field only: the wheels step by their own options and the sheet
+ // opens on tap, so neither reaches this surface.
+ increment: _increment,
+ hasAutoFocus: _hasAutoFocus,
placeholder: placeholderFromProps,
size: sizeProp,
status,
statusVariant = 'attached',
labelTooltip,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
ref,
+ ...restProps
}: TimeInputProps) {
+ const {rest, container} = useFieldInputStyling('TimeInput', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ const {
+ id: idProp,
+ 'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
+ onClick: onClickProp,
+ ...controlProps
+ } = rest;
const t = useTranslator();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.timeInput.placeholder');
const size = useSize(sizeProp, 'md');
- const id = useId();
+ const generatedID = useId();
+ const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -234,6 +259,7 @@ export function TouchTimeField({
statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ariaDescribedByProp,
],
inputGroup,
);
@@ -425,10 +451,10 @@ export function TouchTimeField({
status && !isDisabled && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
<button
type="button"
@@ -440,6 +466,7 @@ export function TouchTimeField({
<Icon icon="clock" size="sm" color="secondary" />
</button>
<input
+ {...controlProps}
ref={mergedInputRef}
id={id}
type="text"
@@ -448,7 +475,7 @@ export function TouchTimeField({
readOnly
inputMode="none"
onChange={() => {}}
- onClick={openSheet}
+ onClick={chainEventHandlers(openSheet, onClickProp)}
placeholder={placeholder}
disabled={isEffectivelyDisabled && !showsDisabledMessage}
aria-disabled={showsDisabledMessage ? 'true' : undefined}
@@ -460,7 +487,11 @@ export function TouchTimeField({
aria-haspopup="dialog"
aria-autocomplete="none"
autoComplete="off"
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy
+ }
{...stylex.props(styles.input)}
/>
{isBusy && <Spinner size="sm" />}
@@ -544,10 +575,12 @@ export function TouchTimeField({
}
return (
<Field
+ {...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
diff --git a/packages/core/src/utils/chainEventHandlers.test.ts b/packages/core/src/utils/chainEventHandlers.test.ts
new file mode 100644
index 0000000000..2d1d91154d
--- /dev/null
+++ b/packages/core/src/utils/chainEventHandlers.test.ts
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import type {SyntheticEvent} from 'react';
+import {chainEventHandlers} from './chainEventHandlers';
+
+function fakeEvent(): SyntheticEvent {
+ const event = {
+ defaultPrevented: false,
+ preventDefault() {
+ event.defaultPrevented = true;
+ },
+ };
+ return event as unknown as SyntheticEvent;
+}
+
+describe('chainEventHandlers', () => {
+ it('calls every handler in order, skipping undefined ones', () => {
+ const calls: string[] = [];
+ chainEventHandlers(
+ () => calls.push('a'),
+ undefined,
+ () => calls.push('b'),
+ )(fakeEvent());
+ expect(calls).toEqual(['a', 'b']);
+ });
+
+ it('keeps calling later handlers after one prevents default', () => {
+ const calls: string[] = [];
+ chainEventHandlers(
+ (event: SyntheticEvent) => {
+ event.preventDefault();
+ calls.push('component');
+ },
+ (event: SyntheticEvent) => calls.push(`caller:${event.defaultPrevented}`),
+ )(fakeEvent());
+ expect(calls).toEqual(['component', 'caller:true']);
+ });
+});
diff --git a/packages/core/src/utils/chainEventHandlers.ts b/packages/core/src/utils/chainEventHandlers.ts
new file mode 100644
index 0000000000..de202b9052
--- /dev/null
+++ b/packages/core/src/utils/chainEventHandlers.ts
@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file chainEventHandlers.ts
+ * @input Multiple React event handlers (or undefined)
+ * @output A single handler that calls every handler in order
+ * @position Utility; used where a component's own handler and a consumer
+ * handler share one element and the consumer must observe every event the
+ * component handled, as it did when the consumer's handler sat on an
+ * ancestor and received the event by bubbling.
+ *
+ * Unlike `composeEventHandlers`, `event.preventDefault()` in an earlier handler
+ * does not skip later ones: the component's handler runs first and cannot hide
+ * the event from the consumer, and the consumer cannot cancel the component's
+ * behavior.
+ */
+
+import type {SyntheticEvent} from 'react';
+
+/**
+ * Chain event handlers into one. Every handler runs, in argument order.
+ *
+ * @example
+ * ```
+ * <input onKeyDown={chainEventHandlers(handleKeyDown, onKeyDownProp)} />
+ * ```
+ */
+export function chainEventHandlers<E extends SyntheticEvent>(
+ ...handlers: (((event: E) => void) | undefined)[]
+): (event: E) => void {
+ return (event: E) => {
+ for (const handler of handlers) {
+ handler?.(event);
+ }
+ };
+}
diff --git a/packages/core/src/utils/dateTypes.ts b/packages/core/src/utils/dateTypes.ts
index 75fa00bcb5..14670ed04c 100644
--- a/packages/core/src/utils/dateTypes.ts
+++ b/packages/core/src/utils/dateTypes.ts
@@ -22,13 +22,7 @@ export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
* A more self-documenting alternative to the numeric {@link DayOfWeek}.
*/
export type DayOfWeekName =
- | 'sun'
- | 'mon'
- | 'tue'
- | 'wed'
- | 'thu'
- | 'fri'
- | 'sat';
+ 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat';
/** Weekday names indexed by {@link DayOfWeek} (0 = Sunday). */
const WEEKDAY_NAMES: ReadonlyArray<DayOfWeekName> = [
diff --git a/packages/core/src/utils/inputAria.ts b/packages/core/src/utils/inputAria.ts
index 0ecfd95c24..f36a9032ed 100644
--- a/packages/core/src/utils/inputAria.ts
+++ b/packages/core/src/utils/inputAria.ts
@@ -3,7 +3,7 @@
/**
* @file inputAria.ts
* @input Receives input label/description IDs and optional InputGroup context
- * @output Exports helpers for consistent input ARIA composition
+ * @output Exports getInputARIA and joinAriaIDs for consistent input ARIA composition
* @position Internal utility; used by inputs that compose labels/descriptions
*/
@@ -23,7 +23,7 @@ export interface InputARIA {
type AriaID = string | null | undefined | false;
-function joinAriaIDs(...values: AriaID[]): string | undefined {
+export function joinAriaIDs(...values: AriaID[]): string | undefined {
const ids = values
.flatMap(value =>
typeof value === 'string' ? value.trim().split(/\s+/) : [],