An open source design system that's fully customizable and agent ready
TypeScript
feat(input): add disabledMessage to picker inputs (#3509) (#3512)
Cindy Zhangc612bb2dd931
diff --git a/.changeset/picker-inputs-disabled-message.md b/.changeset/picker-inputs-disabled-message.mdnew file mode 100644index 0000000000..3e083f0771--- /dev/null+++ b/.changeset/picker-inputs-disabled-message.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] Typeahead, DateInput, DateRangeInput, DateTimeInput, and TimeInput: `disabledMessage` prop shows a tooltip explaining the disabled state on hover and keyboard focus, keeping the control focusable via `aria-disabled` while activation stays blocked (#3509)+@cixzhangdiff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsxindex b24c63faf1..7204718117 100644--- a/apps/storybook/stories/DateInput.stories.tsx+++ b/apps/storybook/stories/DateInput.stories.tsx@@ -42,6 +42,11 @@ const meta: Meta<typeof DateInput> = {control: 'boolean',description: 'Whether the input is disabled',},+ disabledMessage: {+ control: 'text',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateInput in Tooltip.',+ },size: {control: 'radio',options: ['sm', 'md', 'lg'],@@ -142,6 +147,23 @@ export const Disabled: Story = {},};+// Disabled with an explanation tooltip. Hover or keyboard-focus the field to+// see why it's disabled — the reason is announced to assistive tech via+// aria-describedby, and the field stays focusable (activation is still+// blocked). Use disabledMessage instead of wrapping a disabled DateInput in Tooltip:+// disabled controls swallow the pointer events a Tooltip wrapper needs.+export const DisabledWithMessage: Story = {+ render: args => {+ const [value, setValue] = useState<ISODateString | undefined>(undefined);+ return <DateInput {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Event date',+ isDisabled: true,+ disabledMessage: 'You need the Editor role to change this',+ },+};+export const SmallSize: Story = {render: args => {const [value, setValue] = useState<ISODateString | undefined>(undefined);@@ -326,9 +348,7 @@ export const AllVariations: Story = {export const Clearable: Story = {render: args => {const [value, setValue] = useState<ISODateString | undefined>('2026-04-06');- return (- <DateInput {...args} value={value} onChange={setValue} hasClear />- );+ return <DateInput {...args} value={value} onChange={setValue} hasClear />;},args: {label: 'Event date',@@ -339,9 +359,7 @@ export const Clearable: Story = {export const ClearableWithStatus: Story = {render: args => {const [value, setValue] = useState<ISODateString | undefined>('2026-04-06');- return (- <DateInput {...args} value={value} onChange={setValue} hasClear />- );+ return <DateInput {...args} value={value} onChange={setValue} hasClear />;},args: {label: 'Deadline',diff --git a/apps/storybook/stories/DateRangeInput.stories.tsx b/apps/storybook/stories/DateRangeInput.stories.tsxindex 6cf2cc54bd..db147a6783 100644--- a/apps/storybook/stories/DateRangeInput.stories.tsx+++ b/apps/storybook/stories/DateRangeInput.stories.tsx@@ -55,6 +55,11 @@ const meta: Meta<typeof DateRangeInput> = {isOptional: {control: 'boolean', description: 'Show optional indicator'},isRequired: {control: 'boolean', description: 'Mark as required'},isDisabled: {control: 'boolean', description: 'Disable the picker'},+ disabledMessage: {+ control: 'text',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateRangeInput in Tooltip.',+ },size: {control: 'radio',options: ['sm', 'md', 'lg'],@@ -179,6 +184,23 @@ export const Disabled: Story = {},};+// Disabled with an explanation tooltip. Hover or keyboard-focus the field to+// see why it's disabled — the reason is announced to assistive tech via+// aria-describedby, and the field stays focusable (activation is still+// blocked). Use disabledMessage instead of wrapping a disabled DateRangeInput in Tooltip:+// disabled controls swallow the pointer events a Tooltip wrapper needs.+export const DisabledWithMessage: Story = {+ render: args => {+ const [value, setValue] = useState<DateRange | null>(null);+ return <DateRangeInput {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Reporting period',+ isDisabled: true,+ disabledMessage: 'You need the Editor role to change this',+ },+};+export const SizeVariants: Story = {render: () => {const [sm, setSm] = useState<DateRange | null>(null);diff --git a/apps/storybook/stories/DateTimeInput.stories.tsx b/apps/storybook/stories/DateTimeInput.stories.tsxindex c6530c6154..a661b54ad0 100644--- a/apps/storybook/stories/DateTimeInput.stories.tsx+++ b/apps/storybook/stories/DateTimeInput.stories.tsx@@ -41,6 +41,11 @@ const meta: Meta<typeof DateTimeInput> = {control: 'boolean',description: 'Whether the input is disabled',},+ disabledMessage: {+ control: 'text',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateTimeInput in Tooltip.',+ },size: {control: 'radio',options: ['sm', 'md', 'lg'],@@ -220,6 +225,25 @@ export const Disabled: Story = {},};+// Disabled with an explanation tooltip. Hover or keyboard-focus the field to+// see why it's disabled — the reason is announced to assistive tech via+// aria-describedby, and the field stays focusable (activation is still+// blocked). Use disabledMessage instead of wrapping a disabled DateTimeInput in Tooltip:+// disabled controls swallow the pointer events a Tooltip wrapper needs.+export const DisabledWithMessage: Story = {+ render: args => {+ const [value, setValue] = useState<ISODateTimeString | undefined>(+ undefined,+ );+ return <DateTimeInput {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Meeting time',+ isDisabled: true,+ disabledMessage: 'You need the Editor role to change this',+ },+};+export const SizeVariants: Story = {render: () => {const [sm, setSm] = useState<ISODateTimeString | undefined>(undefined);diff --git a/apps/storybook/stories/TimeInput.stories.tsx b/apps/storybook/stories/TimeInput.stories.tsxindex cfda35886e..41ef512001 100644--- a/apps/storybook/stories/TimeInput.stories.tsx+++ b/apps/storybook/stories/TimeInput.stories.tsx@@ -41,6 +41,11 @@ const meta: Meta<typeof TimeInput> = {control: 'boolean',description: 'Whether the input is disabled',},+ disabledMessage: {+ control: 'text',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip.',+ },size: {control: 'radio',options: ['sm', 'md', 'lg'],@@ -208,6 +213,23 @@ export const Disabled: Story = {},};+// Disabled with an explanation tooltip. Hover or keyboard-focus the field to+// see why it's disabled — the reason is announced to assistive tech via+// aria-describedby, and the field stays focusable (activation is still+// blocked). Use disabledMessage instead of wrapping a disabled TimeInput in Tooltip:+// disabled controls swallow the pointer events a Tooltip wrapper needs.+export const DisabledWithMessage: Story = {+ render: args => {+ const [value, setValue] = useState<ISOTimeString | undefined>(undefined);+ return <TimeInput {...args} value={value} onChange={setValue} />;+ },+ args: {+ label: 'Start time',+ isDisabled: true,+ disabledMessage: 'You need the Editor role to change this',+ },+};+export const SmallSize: Story = {render: args => {const [value, setValue] = useState<ISOTimeString | undefined>(undefined);diff --git a/apps/storybook/stories/Typeahead.stories.tsx b/apps/storybook/stories/Typeahead.stories.tsxindex f39223671b..58618ec484 100644--- a/apps/storybook/stories/Typeahead.stories.tsx+++ b/apps/storybook/stories/Typeahead.stories.tsx@@ -32,6 +32,11 @@ const meta: Meta<typeof Typeahead> = {label: {control: 'text'},placeholder: {control: 'text'},isDisabled: {control: 'boolean'},+ disabledMessage: {+ control: 'text',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip.',+ },isRequired: {control: 'boolean'},isOptional: {control: 'boolean'},hasEntriesOnFocus: {control: 'boolean'},@@ -138,6 +143,20 @@ export const Disabled: Story = {},};+// Disabled with an explanation tooltip. Hover or keyboard-focus the field to+// see why it's disabled — the reason is announced to assistive tech via+// aria-describedby, and the field stays focusable (activation is still+// blocked). Use disabledMessage instead of wrapping a disabled Typeahead in Tooltip:+// disabled controls swallow the pointer events a Tooltip wrapper needs.+export const DisabledWithMessage: Story = {+ ...Default,+ args: {+ ...Default.args,+ isDisabled: true,+ disabledMessage: 'You need the Editor role to change this',+ },+};+export const NoClear: Story = {...Default,args: {diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 48f3b5e1f6..2ff6314f7b 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -7,7 +7,15 @@ export const docs = {displayName: 'Date Input',group: 'DateInput',category: 'Data Input',- keywords: ["dateinput","datepicker","datefield","calendar","dateselect","dateentry","datechooser"],+ keywords: [+ 'dateinput',+ 'datepicker',+ 'datefield',+ 'calendar',+ 'dateselect',+ 'dateentry',+ 'datechooser',+ ],props: [{name: 'label',@@ -44,6 +52,12 @@ export const docs = {description: 'Disable the input and calendar.',default: 'false',},+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',+ },{name: 'value',type: 'ISODateString',@@ -57,12 +71,14 @@ export const docs = {{name: 'changeAction',type: '(value: ISODateString | undefined) => void | Promise<void>',- description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',+ description:+ 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',},{name: 'isLoading',type: 'boolean',- description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.',+ description:+ 'Whether the input is in a loading state. Disables interaction and shows a spinner.',default: 'false',},{@@ -102,7 +118,8 @@ export const docs = {{name: 'labelTooltip',type: 'string',- description: 'Tooltip text displayed via an info icon at the end of the label.',+ description:+ 'Tooltip text displayed via an info icon at the end of the label.',},{name: 'hasClear',@@ -131,23 +148,85 @@ export const docs = {],},usage: {- 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.',+ 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: 'Provide clear labels and descriptions so users understand what date is expected.' },- { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },- { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },- { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },- { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },+ {+ guidance: true,+ description:+ 'Provide clear labels and descriptions so users understand what date is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the date is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ 'Show a loading state with changeAction when the date triggers a server-side save.',+ },+ {+ guidance: false,+ description:+ 'Use a DateInput for free-form text that does not represent a calendar date.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Label', required: true, description: 'Text above the input describing what date is expected.'},- {name: 'Text input', required: true, description: 'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.'},- {name: 'Calendar icon', required: true, description: 'A button that opens the calendar popover for visual date picking.'},- {name: 'Calendar popover', required: false, description: 'A month grid that appears when the icon is clicked or the input is focused.'},- {name: 'Clear button', required: false, description: 'A × button that resets the date value. Shown when hasClear is true and a date is set.'},- {name: 'Status message', required: false, description: 'An error, warning, or success message below the input.'},+ {+ name: 'Label',+ required: true,+ description: 'Text above the input describing what date is expected.',+ },+ {+ name: 'Text input',+ required: true,+ description:+ 'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.',+ },+ {+ name: 'Calendar icon',+ required: true,+ description:+ 'A button that opens the calendar popover for visual date picking.',+ },+ {+ name: 'Calendar popover',+ required: false,+ description:+ 'A month grid that appears when the icon is clicked or the input is focused.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'A × button that resets the date value. Shown when hasClear is true and a date is set.',+ },+ {+ name: 'Status message',+ required: false,+ description: 'An error, warning, or success message below the input.',+ },],},};@@ -157,40 +236,153 @@ export const docsZh = {name: 'DateInput',displayName: 'Date Input',usage: {- 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.',+ 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: 'Provide clear labels and descriptions so users understand what date is expected.' },- { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },- { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },- { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },- { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },+ {+ guidance: true,+ description:+ 'Provide clear labels and descriptions so users understand what date is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the date is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ 'Show a loading state with changeAction when the date triggers a server-side save.',+ },+ {+ guidance: false,+ description:+ 'Use a DateInput for free-form text that does not represent a calendar date.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},props: [{name: 'label', type: 'string', description: '标签文本。', required: true},- {name: 'isLabelHidden', type: 'boolean', description: '视觉隐藏标签。', default: 'false'},- {name: 'description', type: 'string', description: '显示在标签下方的辅助文本。'},- {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(optional)"指示器。', default: 'false'},- {name: 'isRequired', type: 'boolean', description: '将字段标记为必填。', default: 'false'},- {name: 'isDisabled', type: 'boolean', description: '禁用输入框和日历。', default: 'false'},- {name: 'value', type: 'ISODateString', description: '选中的日期,YYYY-MM-DD 格式。'},- {name: 'onChange', type: '(value: ISODateString | undefined) => void', description: '选中日期变更时调用的回调。'},+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: '视觉隐藏标签。',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: '显示在标签下方的辅助文本。',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: '在标签旁显示"(optional)"指示器。',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: '将字段标记为必填。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '禁用输入框和日历。',+ default: 'false',+ },+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ '说明输入框为何被禁用。与 isDisabled 一起使用时,在悬停/键盘聚焦时显示提示,并通过 aria-disabled 保持输入框可聚焦(仍阻止输入和激活)。请使用此属性,而不是用 Tooltip 包裹已禁用的 DateInput。',+ },+ {+ name: 'value',+ type: 'ISODateString',+ description: '选中的日期,YYYY-MM-DD 格式。',+ },+ {+ name: 'onChange',+ type: '(value: ISODateString | undefined) => void',+ description: '选中日期变更时调用的回调。',+ },{name: 'changeAction',type: '(value: ISODateString | undefined) => void | Promise<void>',- description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',- },- {name: 'isLoading', type: 'boolean', description: '输入框是否处于加载状态。禁用交互并显示加载指示器。', default: 'false'},- {name: 'min', type: 'ISODateString', description: '可选择的最早日期(YYYY-MM-DD)。'},- {name: 'max', type: 'ISODateString', description: '可选择的最晚日期(YYYY-MM-DD)。'},- {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数数组,用于禁用特定日期。'},- {name: 'placeholder', type: 'string', description: '文本输入框中显示的占位符文本。', default: "'Select a date'"},- {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},- {name: 'status', type: 'InputStatus', description: '错误、警告或成功状态的状态指示对象,附带消息。'},- {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},- {name: 'numberOfMonths', type: '1 | 2', description: '日历弹出层中同时显示的月份数量。', default: '1'},+ description:+ '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '输入框是否处于加载状态。禁用交互并显示加载指示器。',+ default: 'false',+ },+ {+ name: 'min',+ type: 'ISODateString',+ description: '可选择的最早日期(YYYY-MM-DD)。',+ },+ {+ name: 'max',+ type: 'ISODateString',+ description: '可选择的最晚日期(YYYY-MM-DD)。',+ },+ {+ name: 'dateConstraints',+ type: 'Array<(date: Date) => boolean>',+ description: '自定义约束函数数组,用于禁用特定日期。',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: '文本输入框中显示的占位符文本。',+ default: "'Select a date'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: '输入控件的尺寸。',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'InputStatus',+ description: '错误、警告或成功状态的状态指示对象,附带消息。',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: '通过标签末尾的信息图标显示的提示文本。',+ },+ {+ name: 'numberOfMonths',+ type: '1 | 2',+ description: '日历弹出层中同时显示的月份数量。',+ default: '1',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -202,10 +394,7 @@ export const docsZh = {targets: [{className: 'astryx-date-input',- visualProps: [- 'size',- 'status',- ],+ visualProps: ['size', 'status'],},],},@@ -215,15 +404,49 @@ export const docsZh = {export const docsDense = {description: 'text input w/ calendar popover for picking a date',usage: {- 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.',+ 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: 'Provide clear labels + descriptions so users understand what date is expected.' },- { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },- { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },- { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },- { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },+ {+ guidance: true,+ description:+ 'Provide clear labels + descriptions so users understand what date is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the date is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ 'Show a loading state with changeAction when the date triggers a server-side save.',+ },+ {+ guidance: false,+ description:+ 'Use a DateInput for free-form text that does not represent a calendar date.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},propDescriptions: {@@ -233,6 +456,8 @@ export const docsDense = {isOptional: 'show "(optional)" indicator',isRequired: 'mark field required',isDisabled: 'disable input+calendar',+ disabledMessage:+ 'reason shown in a tooltip on hover/focus when disabled; keeps field focusable via aria-disabled',value: 'selected date YYYY-MM-DD',onChange: 'callback on date change',changeAction: 'async action after onChange; drives optimistic UI',diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsxindex 827aec1adc..74acf76e74 100644--- a/packages/core/src/DateInput/DateInput.test.tsx+++ b/packages/core/src/DateInput/DateInput.test.tsx@@ -9,8 +9,9 @@* SYNC: When DateInput.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {describe, it, expect, vi, beforeEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import userEvent from '@testing-library/user-event';import {DateInput} from './DateInput';describe('DateInput', () => {@@ -644,4 +645,130 @@ describe('DateInput', () => {expect(input).toHaveValue('March 20, 2026');});});+ describe('disabledMessage', () => {+ // jsdom does not implement the Popover API used by the tooltip, so mock+ // showPopover/hidePopover to toggle a `popover-open` attribute the tests+ // can assert on.+ beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ });+ });++ // jsdom popover content is in the DOM but not "visible" in the+ // accessibility tree; use hidden: true to find it.+ const h = {hidden: true} as const;++ it('shows the reason tooltip on hover when disabled with a reason', async () => {+ render(+ <DateInput+ label="Date"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const container = screen.getByRole('combobox')+ .parentElement as HTMLElement;+ const tooltip = screen.getByRole('tooltip', h);+ expect(tooltip).toHaveTextContent('You need the Editor role');++ fireEvent.mouseEnter(container);+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });++ fireEvent.mouseLeave(container);+ await waitFor(() => {+ expect(tooltip).not.toHaveAttribute('popover-open');+ });+ });++ it('shows the reason tooltip on keyboard focus', async () => {+ const user = userEvent.setup();+ render(+ <DateInput+ label="Date"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const tooltip = screen.getByRole('tooltip', h);+ await user.tab();+ expect(screen.getByRole('combobox')).toHaveFocus();+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });+ });++ it('does not render a tooltip when not disabled', () => {+ render(+ <DateInput label="Date" disabledMessage="You need the Editor role" />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('does not render a tooltip when disabled without a reason', () => {+ render(<DateInput label="Date" isDisabled />);+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('keeps the input focusable via aria-disabled when a reason is provided', () => {+ render(+ <DateInput+ label="Date"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByRole('combobox');+ expect(input).not.toBeDisabled();+ expect(input).toHaveAttribute('aria-disabled', 'true');+ expect(input).toHaveAttribute('readonly');+ });++ it('links the reason tooltip from the input via aria-describedby', () => {+ render(+ <DateInput+ label="Date"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByRole('combobox');+ const tooltip = screen.getByRole('tooltip', h);+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);+ });++ it('blocks value changes and opening while focusable-disabled', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <DateInput+ label="Date"+ onChange={onChange}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const input = screen.getByRole('combobox');+ await user.click(input);+ await user.type(input, '2026-03-15');+ expect(input).toHaveValue('');+ expect(input).toHaveAttribute('aria-expanded', 'false');+ expect(onChange).not.toHaveBeenCalled();+ });++ it('remains natively disabled when disabled without a reason', () => {+ render(<DateInput label="Date" isDisabled />);+ const input = screen.getByRole('combobox');+ expect(input).toBeDisabled();+ expect(input).not.toHaveAttribute('aria-disabled');+ });+ });});diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsxindex 954117bc99..3bf0f83191 100644--- a/packages/core/src/DateInput/DateInput.tsx+++ b/packages/core/src/DateInput/DateInput.tsx@@ -49,6 +49,7 @@ import {Spinner} from '../Spinner';import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';import {useCalendarConstraints} from '../Calendar/hooks';import {usePopover} from '../Popover';+import {useTooltip} from '../Tooltip';import {parseDateInput} from '../utils';import {plainDateFromISO,@@ -174,6 +175,29 @@ export interface DateInputProps extends Omit<*/isDisabled?: boolean;+ /**+ * Explains why the input is disabled. When set together with+ * `isDisabled`, the input shows a tooltip with this text on hover and+ * keyboard focus, and the field stays focusable (via `aria-disabled`)+ * so the reason is discoverable by keyboard and assistive technology.+ * Typing and calendar activation stay blocked.+ *+ * Use this instead of wrapping a disabled input in `Tooltip` — disabled+ * controls don't emit the pointer events an external tooltip needs.+ *+ * @example+ * ```+ * <DateInput+ * label="Event date"+ * value={date}+ * onChange={setDate}+ * isDisabled+ * disabledMessage="You need the Editor role to change this"+ * />+ * ```+ */+ disabledMessage?: string;+/*** The selected date in ISO format (YYYY-MM-DD).*/@@ -276,6 +300,7 @@ export function DateInput({isOptional = false,isRequired = false,isDisabled = false,+ disabledMessage,value,onChange,changeAction,@@ -308,6 +333,22 @@ export function DateInput({const isBusy = isLoading || optimisticValue !== value;const isEffectivelyDisabled = isDisabled || isBusy;+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the+ // tooltip listeners attach to the input container (which already exists) and+ // the text input stays perceivable via aria-disabled instead of the disabled+ // attribute. Typing is blocked with readOnly and value mutation guards;+ // calendar activation is blocked by the isEffectivelyDisabled guards. Only+ // the persistent isDisabled state (not the transient busy state) surfaces a+ // reason.+ const showsDisabledMessage = isDisabled && !!disabledMessage;+ const disabledMessageTooltip = useTooltip({+ placement: 'above',+ // The container div is not naturally focusable; focusin bubbles up from+ // the input, so always attach focus listeners.+ focusTrigger: 'always',+ isEnabled: showsDisabledMessage,+ });+// Status icon mappingconst statusIconMap: Record<InputStatusType, IconName> = {warning: 'warning',@@ -331,6 +372,7 @@ export function DateInput({[description ? descriptionID : null,status?.message ? statusMessageID : null,+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,].filter(Boolean).join(' ') || undefined;@@ -425,6 +467,11 @@ export function DateInput({// Handle input text change - update immediately if valid and allowedconst handleInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {+ // With a disabledMessage the input drops `disabled` for focusability, so+ // guard value mutation explicitly (readOnly also blocks typing).+ if (isEffectivelyDisabled) {+ return;+ }const newValue = e.target.value;setPendingInput(newValue);@@ -442,7 +489,7 @@ export function DateInput({calendarRef.current?.navigateTo(parsedISO);}},- [value, fireChange, isDateDisabled],+ [value, fireChange, isDateDisabled, isEffectivelyDisabled],);// Commit pending input (shared by blur and Enter key)@@ -520,7 +567,13 @@ export function DateInput({labelTooltip={labelTooltip}width={width}><div- ref={popover.triggerRef}+ ref={el => {+ popover.triggerRef(el);+ // Anchor + hover/focus listeners for the disabled-message tooltip.+ // Handlers are gated internally by isEnabled, and anchor names+ // compose, so attaching unconditionally is safe.+ disabledMessageTooltip.ref(el);+ }}{...rest}{...mergeProps(themeProps('date-input', {size, status: status?.type ?? null}),@@ -558,7 +611,13 @@ export function DateInput({onClick={handleInputClick}onKeyDown={handleInputKeyDown}placeholder={placeholder}- disabled={isEffectivelyDisabled}+ // With a disabledMessage the input keeps focusability via+ // aria-disabled so the reason is focus-discoverable; typing is+ // blocked with readOnly and the mutation guards, and calendar+ // activation is blocked by the isEffectivelyDisabled guards.+ disabled={isEffectivelyDisabled && !showsDisabledMessage}+ aria-disabled={showsDisabledMessage ? 'true' : undefined}+ readOnly={showsDisabledMessage || undefined}aria-describedby={ariaDescribedBy}aria-required={isRequired === true ? 'true' : undefined}aria-invalid={@@ -615,6 +674,9 @@ export function DateInput({/>,{placement: 'below', alignment: 'start'},)}++ {showsDisabledMessage &&+ disabledMessageTooltip.renderTooltip(disabledMessage)}</Field>);}diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjsindex dddec853e7..2793f49a80 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs@@ -7,69 +7,271 @@ export const docs = {displayName: 'Date Range Input',group: 'DateInput',category: 'Data Input',- keywords: ["daterangepicker","daterange","range","calendar","filter","analytics","period","schedule"],+ keywords: [+ 'daterangepicker',+ 'daterange',+ 'range',+ 'calendar',+ 'filter',+ 'analytics',+ 'period',+ 'schedule',+ ],props: [- { name: 'label', type: 'string', description: 'Label text.', required: true },- { name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false' },- { name: 'description', type: 'string', description: 'Helper text displayed below the label.' },- { name: 'isOptional', type: 'boolean', description: 'Show an "(optional)" indicator.', default: 'false' },- { name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false' },- { name: 'isDisabled', type: 'boolean', description: 'Disable the trigger and picker.', default: 'false' },- { name: 'value', type: 'DateRange | null', description: 'Selected date range ({start, end} in ISO format), or null.', required: true },- { name: 'onChange', type: '(value: DateRange | null) => void', description: 'Callback when the range changes. Called with null on clear.', required: true },- { name: 'changeAction', type: '(value: DateRange | null) => void | Promise<void>', description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.' },- { name: 'isLoading', type: 'boolean', description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.', default: 'false' },- { name: 'min', type: 'ISODateString', description: 'Minimum selectable date.' },- { name: 'max', type: 'ISODateString', description: 'Maximum selectable date.' },- { name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: 'Custom constraint functions to disable specific dates.' },- { name: 'presets', type: 'Array<DateRangePreset>', description: 'Preset ranges shown as quick-select options beside the calendar.' },- { name: 'hasClear', type: 'boolean', description: 'Shows a clear button when a range is selected.', default: 'true' },- { name: 'placeholder', type: 'string', description: 'Placeholder text when no range is selected.', default: "'Select date range'" },- { name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Size of the trigger.', default: "'md'" },- { name: 'status', type: 'InputStatus', description: 'Status indicator for error, warning, or success states.' },- { name: 'labelTooltip', type: 'string', description: 'Tooltip text via info icon at label end.' },- { name: 'numberOfMonths', type: '1 | 2', description: 'Number of months in the calendar.', default: '2' },- { name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.' },+ {name: 'label', type: 'string', description: 'Label text.', required: true},+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Show an "(optional)" indicator.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Mark the field as required.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disable the trigger and picker.',+ default: 'false',+ },+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateRangeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',+ },+ {+ name: 'value',+ type: 'DateRange | null',+ description: 'Selected date range ({start, end} in ISO format), or null.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: DateRange | null) => void',+ description:+ 'Callback when the range changes. Called with null on clear.',+ required: true,+ },+ {+ name: 'changeAction',+ type: '(value: DateRange | null) => void | Promise<void>',+ description:+ 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description:+ 'Whether the input is in a loading state. Disables interaction and shows a spinner.',+ default: 'false',+ },+ {+ name: 'min',+ type: 'ISODateString',+ description: 'Minimum selectable date.',+ },+ {+ name: 'max',+ type: 'ISODateString',+ description: 'Maximum selectable date.',+ },+ {+ name: 'dateConstraints',+ type: 'Array<(date: Date) => boolean>',+ description: 'Custom constraint functions to disable specific dates.',+ },+ {+ name: 'presets',+ type: 'Array<DateRangePreset>',+ description:+ 'Preset ranges shown as quick-select options beside the calendar.',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description: 'Shows a clear button when a range is selected.',+ default: 'true',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text when no range is selected.',+ default: "'Select date range'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size of the trigger.',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'InputStatus',+ description: 'Status indicator for error, warning, or success states.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text via info icon at label end.',+ },+ {+ name: 'numberOfMonths',+ type: '1 | 2',+ description: 'Number of months in the calendar.',+ default: '2',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: 'StyleX styles for layout customization.',+ },],theming: {targets: [- { className: 'astryx-date-range-input', visualProps: ['size', 'status'] },+ {className: 'astryx-date-range-input', visualProps: ['size', 'status']},],},usage: {- 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.',+ 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: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },- { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },- { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },- { guidance: true, description: 'Provide clear labels and descriptions so users understand what the range controls.' },- { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },+ {+ guidance: true,+ description:+ 'Use presets for common ranges like "Last 7 days" to speed up selection.',+ },+ {+ guidance: true,+ description:+ 'Use min/max to constrain selectable dates to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Keep hasClear enabled (default) so users can reset the filter.',+ },+ {+ guidance: true,+ description:+ 'Provide clear labels and descriptions so users understand what the range controls.',+ },+ {+ guidance: false,+ description:+ 'Use DateRangeInput when only a single date is needed; use DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- { name: 'Label', required: true, description: 'Text above the trigger describing what date range is expected.' },- { name: 'Trigger button', required: true, description: 'A button showing the formatted range or placeholder. Clicking opens the popover.' },- { name: 'Calendar icon', required: true, description: 'A trailing icon that also opens the popover.' },- { name: 'Calendar popover', required: true, description: 'A dual-month calendar grid with range selection and hover preview.' },- { name: 'Preset sidebar', required: false, description: 'A list of preset range options beside the calendar.' },- { name: 'Clear button', required: false, description: 'A × button that resets the range to null.' },- { name: 'Status message', required: false, description: 'An error, warning, or success message below the trigger.' },+ {+ name: 'Label',+ required: true,+ description:+ 'Text above the trigger describing what date range is expected.',+ },+ {+ name: 'Trigger button',+ required: true,+ description:+ 'A button showing the formatted range or placeholder. Clicking opens the popover.',+ },+ {+ name: 'Calendar icon',+ required: true,+ description: 'A trailing icon that also opens the popover.',+ },+ {+ name: 'Calendar popover',+ required: true,+ description:+ 'A dual-month calendar grid with range selection and hover preview.',+ },+ {+ name: 'Preset sidebar',+ required: false,+ description: 'A list of preset range options beside the calendar.',+ },+ {+ name: 'Clear button',+ required: false,+ description: 'A × button that resets the range to null.',+ },+ {+ name: 'Status message',+ required: false,+ description: 'An error, warning, or success message below the trigger.',+ },],},};/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'date range picker with dual-month calendar popover and preset ranges',+ description:+ 'date range picker with dual-month calendar popover and preset ranges',usage: {- description: 'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',+ description:+ 'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',bestPractices: [- { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },- { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },- { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },- { guidance: true, description: 'Provide clear labels + descriptions so users understand what the range controls.' },- { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },+ {+ guidance: true,+ description:+ 'Use presets for common ranges like "Last 7 days" to speed up selection.',+ },+ {+ guidance: true,+ description:+ 'Use min/max to constrain selectable dates to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Keep hasClear enabled (default) so users can reset the filter.',+ },+ {+ guidance: true,+ description:+ 'Provide clear labels + descriptions so users understand what the range controls.',+ },+ {+ guidance: false,+ description:+ 'Use DateRangeInput when only a single date is needed; use DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},propDescriptions: {@@ -79,6 +281,8 @@ export const docsDense = {isOptional: 'show "(optional)" indicator',isRequired: 'mark field required',isDisabled: 'disable trigger+picker',+ disabledMessage:+ 'reason shown in a tooltip on hover/focus when disabled; keeps trigger focusable via aria-disabled',value: 'selected range {start, end} or null',onChange: 'callback on range change; null on clear',min: 'min selectable date',@@ -91,7 +295,8 @@ export const docsDense = {status: 'error/warning/success status',labelTooltip: 'tooltip via info icon at label end',numberOfMonths: 'months in calendar (default 2)',- changeAction: 'async action fired after onChange; drives optimistic UI updates via useTransition',+ 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',},diff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsxindex 50e3c196df..0b59dbde88 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx@@ -9,8 +9,9 @@* SYNC: When DateRangeInput.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {describe, it, expect, vi, beforeEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import userEvent from '@testing-library/user-event';import {DateRangeInput} from './DateRangeInput';import type {DateRange} from './DateRangeInput';@@ -372,4 +373,114 @@ describe('DateRangeInput', () => {expect(inactive).not.toHaveAttribute('aria-current');});});+ describe('disabledMessage', () => {+ // jsdom does not implement the Popover API used by the tooltip, so mock+ // showPopover/hidePopover to toggle a `popover-open` attribute the tests+ // can assert on.+ beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ });+ });++ // jsdom popover content is in the DOM but not "visible" in the+ // accessibility tree; use hidden: true to find it.+ const h = {hidden: true} as const;++ function renderDisabled(props?: {disabledMessage?: string}) {+ return render(+ <DateRangeInput+ label="Range"+ value={null}+ onChange={() => {}}+ isDisabled+ {...props}+ />,+ );+ }++ it('shows the reason tooltip on hover when disabled with a reason', async () => {+ renderDisabled({disabledMessage: 'You need the Editor role'});++ const trigger = screen.getByRole('button', {name: /Range:/, ...h});+ const container = trigger.parentElement as HTMLElement;+ const tooltip = screen.getByRole('tooltip', h);+ expect(tooltip).toHaveTextContent('You need the Editor role');++ fireEvent.mouseEnter(container);+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });++ fireEvent.mouseLeave(container);+ await waitFor(() => {+ expect(tooltip).not.toHaveAttribute('popover-open');+ });+ });++ it('shows the reason tooltip on keyboard focus', async () => {+ const user = userEvent.setup();+ renderDisabled({disabledMessage: 'You need the Editor role'});++ const tooltip = screen.getByRole('tooltip', h);+ await user.tab();+ expect(screen.getByRole('button', {name: /Range:/, ...h})).toHaveFocus();+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });+ });++ it('does not render a tooltip when not disabled', () => {+ render(+ <DateRangeInput+ label="Range"+ value={null}+ onChange={() => {}}+ disabledMessage="You need the Editor role"+ />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('does not render a tooltip when disabled without a reason', () => {+ renderDisabled();+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('keeps the trigger focusable via aria-disabled when a reason is provided', () => {+ renderDisabled({disabledMessage: 'You need the Editor role'});+ const trigger = screen.getByRole('button', {name: /Range:/, ...h});+ expect(trigger).not.toBeDisabled();+ expect(trigger).toHaveAttribute('aria-disabled', 'true');+ });++ it('links the reason tooltip from the trigger via aria-describedby', () => {+ renderDisabled({disabledMessage: 'You need the Editor role'});+ const trigger = screen.getByRole('button', {name: /Range:/, ...h});+ const tooltip = screen.getByRole('tooltip', h);+ expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);+ });++ it('blocks activation while focusable-disabled', async () => {+ const user = userEvent.setup();+ renderDisabled({disabledMessage: 'You need the Editor role'});++ const trigger = screen.getByRole('button', {name: /Range:/, ...h});+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ await user.keyboard('{Enter}');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('remains natively disabled when disabled without a reason', () => {+ renderDisabled();+ const trigger = screen.getByRole('button', {name: /Range:/, ...h});+ expect(trigger).toBeDisabled();+ expect(trigger).not.toHaveAttribute('aria-disabled');+ });+ });});diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsxindex 0b87c3b720..4cbb35c013 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx@@ -48,6 +48,7 @@ import {Icon} from '../Icon';import {Spinner} from '../Spinner';import {Calendar, type ISODateString, type DateRange} from '../Calendar';import {usePopover} from '../Popover';+import {useTooltip} from '../Tooltip';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';import type {SizeValue} from '../utils/types';@@ -240,6 +241,29 @@ export interface DateRangeInputProps extends Omit<*/isDisabled?: boolean;+ /**+ * Explains why the input is disabled. When set together with+ * `isDisabled`, the input shows a tooltip with this text on hover and+ * keyboard focus, and the trigger stays focusable (via `aria-disabled`)+ * so the reason is discoverable by keyboard and assistive technology.+ * Activation stays blocked.+ *+ * Use this instead of wrapping a disabled input in `Tooltip` — disabled+ * controls don't emit the pointer events an external tooltip needs.+ *+ * @example+ * ```+ * <DateRangeInput+ * label="Reporting period"+ * value={range}+ * onChange={setRange}+ * isDisabled+ * disabledMessage="You need the Editor role to change this"+ * />+ * ```+ */+ disabledMessage?: string;+/*** The selected date range, or null if no range is selected.*/@@ -347,6 +371,7 @@ export function DateRangeInput({isOptional = false,isRequired = false,isDisabled = false,+ disabledMessage,value,onChange,changeAction,@@ -378,6 +403,21 @@ export function DateRangeInput({const isBusy = isLoading || optimisticValue !== value;const isEffectivelyDisabled = isDisabled || isBusy;+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the+ // tooltip listeners attach to the trigger container (which already exists)+ // and the trigger button stays perceivable via aria-disabled instead of the+ // disabled attribute. Activation is blocked by the isEffectivelyDisabled+ // guard in handleToggle. Only the persistent isDisabled state (not the+ // transient busy state) surfaces a reason.+ const showsDisabledMessage = isDisabled && !!disabledMessage;+ const disabledMessageTooltip = useTooltip({+ placement: 'above',+ // The container div is not naturally focusable; focusin bubbles up from+ // the trigger button, so always attach focus listeners.+ focusTrigger: 'always',+ isEnabled: showsDisabledMessage,+ });+const statusIconMap: Record<InputStatusType, IconName> = {warning: 'warning',error: 'error',@@ -397,6 +437,7 @@ export function DateRangeInput({[description ? descriptionID : null,status?.message ? statusMessageID : null,+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,].filter(Boolean).join(' ') || undefined;@@ -487,7 +528,13 @@ export function DateRangeInput({labelTooltip={labelTooltip}width={width}><div- ref={popover.triggerRef}+ ref={el => {+ popover.triggerRef(el);+ // Anchor + hover/focus listeners for the disabled-message tooltip.+ // Handlers are gated internally by isEnabled, and anchor names+ // compose, so attaching unconditionally is safe.+ disabledMessageTooltip.ref(el);+ }}{...rest}{...mergeProps(themeProps('date-range-input', {@@ -523,7 +570,11 @@ export function DateRangeInput({id={id}type="button"onClick={handleToggle}- disabled={isEffectivelyDisabled}+ // 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}aria-describedby={ariaDescribedBy}aria-required={isRequired === true ? 'true' : undefined}@@ -600,6 +651,9 @@ export function DateRangeInput({</div>,{placement: 'below', alignment: 'start'},)}++ {showsDisabledMessage &&+ disabledMessageTooltip.renderTooltip(disabledMessage)}</Field>);}diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjsindex 20e35b8712..0ce0a46228 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs@@ -7,7 +7,17 @@ export const docs = {displayName: 'Date Time Input',group: 'DateInput',category: 'Data Input',- keywords: ["datetimepicker","datetime","datepicker","timepicker","calendar","schedule","event","deadline","timestamp"],+ keywords: [+ 'datetimepicker',+ 'datetime',+ 'datepicker',+ 'timepicker',+ 'calendar',+ 'schedule',+ 'event',+ 'deadline',+ 'timestamp',+ ],props: [{name: 'label',@@ -44,10 +54,17 @@ export const docs = {description: 'Disable the input and picker.',default: 'false',},+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateTimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',+ },{name: 'value',type: 'ISODateTimeString',- description: 'Selected datetime in ISO 8601 format (YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS).',+ description:+ 'Selected datetime in ISO 8601 format (YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS).',},{name: 'onChange',@@ -58,28 +75,33 @@ export const docs = {{name: 'changeAction',type: '(value: ISODateTimeString | undefined) => void | Promise<void>',- description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',+ description:+ 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',},{name: 'isLoading',type: 'boolean',- description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.',+ description:+ 'Whether the input is in a loading state. Disables interaction and shows a spinner.',default: 'false',},{name: 'min',type: 'ISODateTimeString',- description: 'Minimum selectable datetime. Constrains both date and time selection.',+ description:+ 'Minimum selectable datetime. Constrains both date and time selection.',},{name: 'max',type: 'ISODateTimeString',- description: 'Maximum selectable datetime. Constrains both date and time selection.',+ description:+ 'Maximum selectable datetime. Constrains both date and time selection.',},{name: 'dateConstraints',type: 'Array<(date: Date) => boolean>',- description: 'Array of custom constraint functions that disable specific dates.',+ description:+ 'Array of custom constraint functions that disable specific dates.',},{name: 'hasSeconds',@@ -90,13 +112,15 @@ export const docs = {{name: 'hourFormat',type: "'12h' | '24h'",- description: "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",+ description:+ "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",default: "'12h'",},{name: 'timeIncrement',type: 'number',- description: 'Minutes to add or subtract when using arrow keys in the time input.',+ description:+ 'Minutes to add or subtract when using arrow keys in the time input.',default: '1',},{@@ -108,19 +132,22 @@ export const docs = {{name: 'placeholder',type: 'string',- description: 'Placeholder text shown in the date portion when no date is selected.',+ description:+ 'Placeholder text shown in the date portion when no date is selected.',default: "'Select a date'",},{name: 'timePlaceholder',type: 'string',- description: 'Placeholder text shown in the time portion when no time is selected.',+ description:+ 'Placeholder text shown in the time portion when no time is selected.',default: "'Select a time'",},{name: 'timeLabel',type: 'string',- description: 'Accessible label for the time portion. Defaults to "{label} time" so it is tied to the field label and localizable.',+ description:+ 'Accessible label for the time portion. Defaults to "{label} time" so it is tied to the field label and localizable.',},{name: 'size',@@ -131,12 +158,14 @@ export const docs = {{name: 'status',type: 'InputStatus',- description: 'Status indicator object for error, warning, or success states with a message.',+ description:+ 'Status indicator object for error, warning, or success states with a message.',},{name: 'labelTooltip',type: 'string',- description: 'Tooltip text displayed via an info icon at the end of the label.',+ description:+ 'Tooltip text displayed via an info icon at the end of the label.',},{name: 'numberOfMonths',@@ -157,24 +186,90 @@ export const docs = {],},usage: {- description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',+ description:+ 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',bestPractices: [- { guidance: true, description: 'Provide clear labels and descriptions so users understand what datetime is expected.' },- { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },- { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },- { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },- { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ {+ guidance: true,+ description:+ 'Provide clear labels and descriptions so users understand what datetime is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min and max to restrict selectable datetimes to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the datetime is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ "Choose the hour format (12h or 24h) that matches your audience's locale.",+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a date is needed; use DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a time is needed; use TimeInput instead.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Label', required: true, description: 'Text above the input describing what datetime is expected.'},- {name: 'Date input', required: true, description: 'A text input where the user can type a date. Clicking opens a calendar popover.'},- {name: 'Calendar icon', required: true, description: 'A button that opens the calendar popover.'},- {name: 'Calendar popover', required: false, description: 'A month grid that appears when the icon is clicked or the date input is focused.'},- {name: 'Time input', required: true, description: 'A text input for entering the time, displayed beside the date input.'},- {name: 'Clear button', required: false, description: 'A × button that resets the datetime value.'},- {name: 'Status message', required: false, description: 'An error, warning, or success message below the inputs.'},+ {+ name: 'Label',+ required: true,+ description:+ 'Text above the input describing what datetime is expected.',+ },+ {+ name: 'Date input',+ required: true,+ description:+ 'A text input where the user can type a date. Clicking opens a calendar popover.',+ },+ {+ name: 'Calendar icon',+ required: true,+ description: 'A button that opens the calendar popover.',+ },+ {+ name: 'Calendar popover',+ required: false,+ description:+ 'A month grid that appears when the icon is clicked or the date input is focused.',+ },+ {+ name: 'Time input',+ required: true,+ description:+ 'A text input for entering the time, displayed beside the date input.',+ },+ {+ name: 'Clear button',+ required: false,+ description: 'A × button that resets the datetime value.',+ },+ {+ name: 'Status message',+ required: false,+ description: 'An error, warning, or success message below the inputs.',+ },],},};@@ -184,43 +279,196 @@ export const docsZh = {name: 'DateTimeInput',displayName: 'Date Time Input',usage: {- description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',+ description:+ 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',bestPractices: [- { guidance: true, description: 'Provide clear labels and descriptions so users understand what datetime is expected.' },- { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },- { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },- { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },- { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ {+ guidance: true,+ description:+ 'Provide clear labels and descriptions so users understand what datetime is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min and max to restrict selectable datetimes to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the datetime is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ "Choose the hour format (12h or 24h) that matches your audience's locale.",+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a date is needed; use DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a time is needed; use TimeInput instead.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},props: [{name: 'label', type: 'string', description: '标签文本。', required: true},- {name: 'isLabelHidden', type: 'boolean', description: '视觉隐藏标签。', default: 'false'},- {name: 'description', type: 'string', description: '显示在标签下方的辅助文本。'},- {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(optional)"指示器。', default: 'false'},- {name: 'isRequired', type: 'boolean', description: '将字段标记为必填。', default: 'false'},- {name: 'isDisabled', type: 'boolean', description: '禁用输入框和选择器。', default: 'false'},- {name: 'value', type: 'ISODateTimeString', description: '选中的日期时间,ISO 8601 格式。'},- {name: 'onChange', type: '(value: ISODateTimeString | undefined) => void', description: '选中日期时间变更时调用的回调。', required: true},- {name: 'changeAction', type: '(value: ISODateTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。'},- {name: 'isLoading', type: 'boolean', description: '输入框是否处于加载状态。禁用交互并显示加载指示器。', default: 'false'},- {name: 'min', type: 'ISODateTimeString', description: '可选择的最早日期时间。同时约束日期和时间选择。'},- {name: 'max', type: 'ISODateTimeString', description: '可选择的最晚日期时间。同时约束日期和时间选择。'},- {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数数组,用于禁用特定日期。'},- {name: 'hasSeconds', type: 'boolean', description: '在时间部分包含秒。', default: 'false'},- {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM;'24h' 使用 24 小时制。", default: "'12h'"},- {name: 'timeIncrement', type: 'number', description: '在时间输入中按箭头键时增减的分钟数。', default: '1'},- {name: 'hasClear', type: 'boolean', description: '当有值时显示清除按钮。', default: 'false'},- {name: 'placeholder', type: 'string', description: '日期部分未选择日期时显示的占位符文本。', default: "'Select a date'"},- {name: 'timePlaceholder', type: 'string', description: '时间部分未选择时间时显示的占位符文本。', default: "'Select a time'"},- {name: 'timeLabel', type: 'string', description: '时间部分的无障碍标签。默认为“{label} time”,与字段标签关联且可本地化。'},- {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},- {name: 'status', type: 'InputStatus', description: '错误、警告或成功状态的状态指示对象,附带消息。'},- {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},- {name: 'numberOfMonths', type: '1 | 2', description: '日历中同时显示的月份数量。', default: '1'},- {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。'},+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: '视觉隐藏标签。',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: '显示在标签下方的辅助文本。',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: '在标签旁显示"(optional)"指示器。',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: '将字段标记为必填。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '禁用输入框和选择器。',+ default: 'false',+ },+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ '说明输入框为何被禁用。与 isDisabled 一起使用时,在悬停/键盘聚焦时显示提示,并通过 aria-disabled 保持日期和时间字段可聚焦(仍阻止输入和激活)。请使用此属性,而不是用 Tooltip 包裹已禁用的 DateTimeInput。',+ },+ {+ name: 'value',+ type: 'ISODateTimeString',+ description: '选中的日期时间,ISO 8601 格式。',+ },+ {+ name: 'onChange',+ type: '(value: ISODateTimeString | undefined) => void',+ description: '选中日期时间变更时调用的回调。',+ required: true,+ },+ {+ name: 'changeAction',+ type: '(value: ISODateTimeString | undefined) => void | Promise<void>',+ description:+ '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '输入框是否处于加载状态。禁用交互并显示加载指示器。',+ default: 'false',+ },+ {+ name: 'min',+ type: 'ISODateTimeString',+ description: '可选择的最早日期时间。同时约束日期和时间选择。',+ },+ {+ name: 'max',+ type: 'ISODateTimeString',+ description: '可选择的最晚日期时间。同时约束日期和时间选择。',+ },+ {+ name: 'dateConstraints',+ type: 'Array<(date: Date) => boolean>',+ description: '自定义约束函数数组,用于禁用特定日期。',+ },+ {+ name: 'hasSeconds',+ type: 'boolean',+ description: '在时间部分包含秒。',+ default: 'false',+ },+ {+ name: 'hourFormat',+ type: "'12h' | '24h'",+ description: "控制显示格式。'12h' 显示 AM/PM;'24h' 使用 24 小时制。",+ default: "'12h'",+ },+ {+ name: 'timeIncrement',+ type: 'number',+ description: '在时间输入中按箭头键时增减的分钟数。',+ default: '1',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description: '当有值时显示清除按钮。',+ default: 'false',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: '日期部分未选择日期时显示的占位符文本。',+ default: "'Select a date'",+ },+ {+ name: 'timePlaceholder',+ type: 'string',+ description: '时间部分未选择时间时显示的占位符文本。',+ default: "'Select a time'",+ },+ {+ name: 'timeLabel',+ type: 'string',+ description:+ '时间部分的无障碍标签。默认为“{label} time”,与字段标签关联且可本地化。',+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: '输入控件的尺寸。',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'InputStatus',+ description: '错误、警告或成功状态的状态指示对象,附带消息。',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: '通过标签末尾的信息图标显示的提示文本。',+ },+ {+ name: 'numberOfMonths',+ type: '1 | 2',+ description: '日历中同时显示的月份数量。',+ default: '1',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',+ },],theming: {targets: [@@ -231,17 +479,52 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'combined date + time picker with calendar popover and time input',+ description:+ 'combined date + time picker with calendar popover and time input',usage: {- description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time. Use for scheduling, events, deadlines, or any form field needing a datetime.',+ description:+ 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time. Use for scheduling, events, deadlines, or any form field needing a datetime.',bestPractices: [- { guidance: true, description: 'Provide clear labels + descriptions so users understand what datetime is expected.' },- { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },- { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },- { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },- { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ {+ guidance: true,+ description:+ 'Provide clear labels + descriptions so users understand what datetime is expected.',+ },+ {+ guidance: true,+ description:+ 'Use min and max to restrict selectable datetimes to valid ranges.',+ },+ {+ guidance: true,+ description:+ 'Use hasClear when the datetime is optional so the user can reset it.',+ },+ {+ guidance: true,+ description:+ "Choose the hour format (12h or 24h) that matches your audience's locale.",+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a date is needed; use DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Use DateTimeInput when only a time is needed; use TimeInput instead.',+ },+ {+ guidance: false,+ description:+ 'Hide the label without surrounding context that makes the field purpose obvious.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},propDescriptions: {@@ -251,6 +534,8 @@ export const docsDense = {isOptional: 'show "(optional)" indicator',isRequired: 'mark field required',isDisabled: 'disable input+picker',+ disabledMessage:+ 'reason shown in a tooltip on hover/focus when disabled; keeps fields focusable via aria-disabled',value: 'selected datetime ISO 8601',onChange: 'callback on datetime change',changeAction: 'async action after onChange; drives optimistic UI',@@ -264,7 +549,8 @@ export const docsDense = {hasClear: 'Shows clear button when datetime is set',placeholder: 'date-portion placeholder when empty',timePlaceholder: 'time-portion placeholder when empty',- timeLabel: 'accessible label for the time input; defaults to "{label} time"',+ timeLabel:+ 'accessible label for the time input; defaults to "{label} time"',size: 'input control size',status: 'error/warning/success status w/ message',labelTooltip: 'tooltip text via info icon at label end',diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsxindex cbc36976b0..0aa82bdb4b 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx@@ -9,8 +9,9 @@* SYNC: When DateTimeInput.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {describe, it, expect, vi, beforeEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import userEvent from '@testing-library/user-event';import {DateTimeInput} from './DateTimeInput';import type {ISODateTimeString} from './DateTimeInput';@@ -522,4 +523,158 @@ describe('DateTimeInput', () => {expect(screen.getByText('Invalid time')).toBeInTheDocument();});});+ describe('disabledMessage', () => {+ // jsdom does not implement the Popover API used by the tooltip, so mock+ // showPopover/hidePopover to toggle a `popover-open` attribute the tests+ // can assert on.+ beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ });+ });++ // jsdom popover content is in the DOM but not "visible" in the+ // accessibility tree; use hidden: true to find it.+ const h = {hidden: true} as const;++ it('shows the reason tooltip on hover when disabled with a reason', async () => {+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ // The tooltip anchors on the outer row that wraps both inputs.+ const dateInput = screen.getByRole('combobox');+ const row = dateInput.parentElement?.parentElement as HTMLElement;+ const tooltip = screen.getByRole('tooltip', h);+ expect(tooltip).toHaveTextContent('You need the Editor role');++ fireEvent.mouseEnter(row);+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });++ fireEvent.mouseLeave(row);+ await waitFor(() => {+ expect(tooltip).not.toHaveAttribute('popover-open');+ });+ });++ it('shows the reason tooltip on keyboard focus', async () => {+ const user = userEvent.setup();+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const tooltip = screen.getByRole('tooltip', h);+ await user.tab();+ expect(screen.getByRole('combobox')).toHaveFocus();+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });+ });++ it('does not render a tooltip when not disabled', () => {+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ disabledMessage="You need the Editor role"+ />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('does not render a tooltip when disabled without a reason', () => {+ render(<DateTimeInput label="When" onChange={() => {}} isDisabled />);+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('keeps both inputs focusable via aria-disabled when a reason is provided', () => {+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const dateInput = screen.getByRole('combobox');+ const timeInput = screen.getByLabelText('When time');+ expect(dateInput).not.toBeDisabled();+ expect(dateInput).toHaveAttribute('aria-disabled', 'true');+ expect(dateInput).toHaveAttribute('readonly');+ expect(timeInput).not.toBeDisabled();+ expect(timeInput).toHaveAttribute('aria-disabled', 'true');+ expect(timeInput).toHaveAttribute('readonly');+ });++ it('links the reason tooltip from the date input via aria-describedby', () => {+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const dateInput = screen.getByRole('combobox');+ const tooltip = screen.getByRole('tooltip', h);+ expect(dateInput.getAttribute('aria-describedby')).toContain(tooltip.id);+ });++ it('blocks value changes and opening while focusable-disabled', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <DateTimeInput+ label="When"+ onChange={onChange}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const dateInput = screen.getByRole('combobox');+ await user.click(dateInput);+ await user.type(dateInput, '2026-03-15');+ expect(dateInput).toHaveValue('');+ expect(dateInput).toHaveAttribute('aria-expanded', 'false');+ expect(onChange).not.toHaveBeenCalled();+ });++ it('remains natively disabled when disabled without a reason', () => {+ render(<DateTimeInput label="When" onChange={() => {}} isDisabled />);+ const dateInput = screen.getByRole('combobox');+ expect(dateInput).toBeDisabled();+ expect(dateInput).not.toHaveAttribute('aria-disabled');+ });++ it('does not swap in the time format-hint placeholder on focus while disabled', () => {+ render(+ <DateTimeInput+ label="When"+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const timeInput = screen.getByLabelText('When time');+ timeInput.focus();+ fireEvent.focus(timeInput);+ expect(timeInput).toHaveAttribute('placeholder', 'Select a time');+ });+ });});diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsxindex 743eac8274..05faa0c7f8 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx@@ -52,6 +52,7 @@ import {Spinner} from '../Spinner';import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';import {useCalendarConstraints} from '../Calendar/hooks';import {usePopover} from '../Popover';+import {useTooltip} from '../Tooltip';import {useInputContainer} from '../hooks/useInputContainer';import {type ISOTimeString,@@ -210,6 +211,29 @@ export interface DateTimeInputProps extends Omit<*/isDisabled?: boolean;+ /**+ * Explains why the input is disabled. When set together with+ * `isDisabled`, the input shows a tooltip with this text on hover and+ * keyboard focus, and the date and time fields stay focusable (via+ * `aria-disabled`) so the reason is discoverable by keyboard and assistive+ * technology. Typing and calendar activation stay blocked.+ *+ * Use this instead of wrapping a disabled input in `Tooltip` — disabled+ * controls don't emit the pointer events an external tooltip needs.+ *+ * @example+ * ```+ * <DateTimeInput+ * label="Meeting time"+ * value={dateTime}+ * onChange={setDateTime}+ * isDisabled+ * disabledMessage="You need the Editor role to change this"+ * />+ * ```+ */+ disabledMessage?: string;+/*** The selected datetime in ISO 8601 format ("YYYY-MM-DDTHH:MM" or "YYYY-MM-DDTHH:MM:SS").*/@@ -383,6 +407,7 @@ export function DateTimeInput({isOptional = false,isRequired = false,isDisabled = false,+ disabledMessage,value,onChange,changeAction,@@ -424,6 +449,22 @@ export function DateTimeInput({const isBusy = isLoading || optimisticValue !== value;const isEffectivelyDisabled = isDisabled || isBusy;+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the+ // tooltip listeners attach to the outer row container (which already exists)+ // and both the date and time inputs stay perceivable via aria-disabled+ // instead of the disabled attribute. Typing is blocked with readOnly and the+ // value mutation guards; calendar activation is blocked by the+ // isEffectivelyDisabled guards. Only the persistent isDisabled state (not the+ // transient busy state) surfaces a reason.+ const showsDisabledMessage = isDisabled && !!disabledMessage;+ const disabledMessageTooltip = useTooltip({+ placement: 'above',+ // The container div is not naturally focusable; focusin bubbles up from+ // the inputs, so always attach focus listeners.+ focusTrigger: 'always',+ isEnabled: showsDisabledMessage,+ });+const statusIconMap: Record<InputStatusType, IconName> = {warning: 'warning',error: 'error',@@ -443,6 +484,7 @@ export function DateTimeInput({[description ? descriptionID : null,status?.message ? statusMessageID : null,+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,].filter(Boolean).join(' ') || undefined;@@ -610,6 +652,11 @@ export function DateTimeInput({const handleDateInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {+ // With a disabledMessage the input drops `disabled` for focusability, so+ // guard value mutation explicitly (readOnly also blocks typing).+ if (isEffectivelyDisabled) {+ return;+ }const text = e.target.value;setDatePendingInput(text);@@ -625,7 +672,7 @@ export function DateTimeInput({calendarRef.current?.navigateTo(parsedISO);}},- [valueParts.date, isDateDisabled, handleDateChange],+ [valueParts.date, isDateDisabled, handleDateChange, isEffectivelyDisabled],);const commitDatePendingInput = useCallback(() => {@@ -678,6 +725,11 @@ export function DateTimeInput({// --- Time handlers ---const handleTimeInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {+ // With a disabledMessage the input drops `disabled` for focusability, so+ // guard value mutation explicitly (readOnly also blocks typing).+ if (isEffectivelyDisabled) {+ return;+ }const text = e.target.value;setTimePendingInput(text);@@ -702,10 +754,19 @@ export function DateTimeInput({valueParts.time,valueParts.date,fireChange,+ isEffectivelyDisabled,],);- const handleTimeFocus = useCallback(() => setIsTimeFocused(true), []);+ const handleTimeFocus = useCallback(() => {+ // A disabled/busy input stays focusable (via aria-disabled) so its reason+ // is discoverable, but it must not present editing affordances — keep the+ // static placeholder rather than swapping in the format hint.+ if (isEffectivelyDisabled) {+ return;+ }+ setIsTimeFocused(true);+ }, [isEffectivelyDisabled]);const handleTimeBlur = useCallback(() => {setIsTimeFocused(false);@@ -800,6 +861,7 @@ export function DateTimeInput({statusVariant="detached"width={width}><div+ ref={disabledMessageTooltip.ref}{...rest}{...mergeProps(themeProps('date-time-input', {@@ -844,7 +906,13 @@ export function DateTimeInput({onClick={handleDateInputClick}onKeyDown={handleDateKeyDown}placeholder={placeholder}- disabled={isEffectivelyDisabled}+ // With a disabledMessage the input keeps focusability via+ // aria-disabled so the reason is focus-discoverable; typing is+ // blocked with readOnly and the mutation guards, and calendar+ // activation is blocked by the isEffectivelyDisabled guards.+ disabled={isEffectivelyDisabled && !showsDisabledMessage}+ aria-disabled={showsDisabledMessage ? 'true' : undefined}+ readOnly={showsDisabledMessage || undefined}aria-describedby={ariaDescribedBy}aria-required={isRequired === true ? 'true' : undefined}aria-invalid={@@ -917,7 +985,12 @@ export function DateTimeInput({onBlur={handleTimeBlur}onKeyDown={handleTimeKeyDown}placeholder={resolvedTimePlaceholder}- disabled={isEffectivelyDisabled}+ // With a disabledMessage the input keeps focusability via+ // aria-disabled so the reason is focus-discoverable; typing is+ // blocked with readOnly and the mutation guards.+ disabled={isEffectivelyDisabled && !showsDisabledMessage}+ aria-disabled={showsDisabledMessage ? 'true' : undefined}+ readOnly={showsDisabledMessage || undefined}aria-label={timeLabel ?? `${label} time`}aria-required={isRequired === true ? 'true' : undefined}aria-invalid={@@ -952,6 +1025,9 @@ export function DateTimeInput({/>,{placement: 'below', alignment: 'start'},)}++ {showsDisabledMessage &&+ disabledMessageTooltip.renderTooltip(disabledMessage)}</Field>);}diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjsindex d74efc8177..1a5ec33b92 100644--- a/packages/core/src/TimeInput/TimeInput.doc.mjs+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs@@ -6,26 +6,95 @@ export const docs = {name: 'TimeInput',displayName: 'Time Input',category: 'Data Input',- keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield","schedule"],+ keywords: [+ 'timeinput',+ 'timepicker',+ 'time',+ 'clock',+ 'hour',+ 'minute',+ 'ampm',+ 'timeselect',+ 'timefield',+ 'schedule',+ ],usage: {description:'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',bestPractices: [- {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},- {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},- {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},- {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},- {guidance: true, description: 'Enable hasClear when the field is optional, so users can remove a previously selected time.'},- {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},- {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},+ {+ guidance: true,+ description:+ 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',+ },+ {+ guidance: true,+ description:+ 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.',+ },+ {+ guidance: true,+ description:+ 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.',+ },+ {+ guidance: true,+ description:+ 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.',+ },+ {+ guidance: true,+ description:+ 'Enable hasClear when the field is optional, so users can remove a previously selected time.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},- {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},- {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},- {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},- {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},+ {+ name: 'Clock icon',+ required: false,+ description:+ 'A leading clock icon that identifies the field as a time input.',+ },+ {+ name: 'Text input',+ required: true,+ description:+ 'The editable text field where users type or see the formatted time.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'A trailing button to reset the value, shown when hasClear is true and a value is set.',+ },+ {+ name: 'Status icon',+ required: false,+ description:+ 'A trailing icon indicating error, warning, or success state.',+ },+ {+ name: 'Spinner',+ required: false,+ description:+ 'Replaces trailing content during loading to show an async action is in progress.',+ },],},@@ -33,8 +102,7 @@ export const docs = {{name: 'label',type: 'string',- description:- 'Label text for the input (required for accessibility).',+ description: 'Label text for the input (required for accessibility).',required: true,},{@@ -69,6 +137,12 @@ export const docs = {description: 'Disables the input and suppresses interactions.',default: 'false',},+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',+ },{name: 'value',type: 'ISOTimeString',@@ -176,27 +250,134 @@ export const docsZh = {displayName: 'Time Input',props: [- {name: 'label', type: 'string', description: '输入框的标签文本(无障碍性所必需)。', required: true},- {name: 'isLabelHidden', type: 'boolean', description: '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。', default: 'false'},- {name: 'description', type: 'string', description: '显示在标签和输入框之间的描述文本。'},- {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(可选)"指示器。与 isRequired 互斥。', default: 'false'},- {name: 'isRequired', type: 'boolean', description: '将字段标记为必填并设置 aria-required。与 isOptional 互斥。', default: 'false'},- {name: 'isDisabled', type: 'boolean', description: '禁用输入框并抑制交互。', default: 'false'},- {name: 'value', type: 'ISOTimeString', description: 'ISO 格式的受控时间值(HH:MM 或 HH:MM:SS)。'},- {name: 'onChange', type: '(value: ISOTimeString | undefined) => void', description: '时间变化时触发的回调。输入被清除时接收 undefined。'},- {name: 'changeAction', type: '(value: ISOTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。'},- {name: 'isLoading', type: 'boolean', description: '使输入框进入加载状态,显示旋转器。', default: 'false'},- {name: 'min', type: 'ISOTimeString', description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。'},- {name: 'max', type: 'ISOTimeString', description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。'},- {name: 'hasSeconds', type: 'boolean', description: '在时间显示和解析中包含秒。', default: 'false'},- {name: 'hasClear', type: 'boolean', description: '当有值且输入框未被禁用时显示清除按钮。', default: 'false'},- {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM(例如 '2:30 PM');'24h' 使用 24 小时制(例如 '14:30')。", default: "'12h'"},- {name: 'increment', type: 'number', description: '用户按上或下方向键时增加或减少的分钟数。', default: '1'},- {name: 'placeholder', type: 'string', description: '未选择时间时显示的占位符文本。当输入框聚焦且为空时,格式提示会覆盖此文本。', default: "'Select a time'"},- {name: 'size', type: "'sm' | 'md' | 'lg'", description: '控制输入框元素的高度。', default: "'md'"},- {name: 'status', type: 'InputStatus', description: '为边框着色并显示图标的状态指示器。当提供消息时,消息渲染在输入框下方。'},- {name: 'labelTooltip', type: 'string', description: '在标签行末尾以信息图标形式渲染的工具提示文本。'},- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。'},+ {+ name: 'label',+ type: 'string',+ description: '输入框的标签文本(无障碍性所必需)。',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: '显示在标签和输入框之间的描述文本。',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: '在标签旁显示"(可选)"指示器。与 isRequired 互斥。',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: '将字段标记为必填并设置 aria-required。与 isOptional 互斥。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '禁用输入框并抑制交互。',+ default: 'false',+ },+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ '说明输入框为何被禁用。与 isDisabled 一起使用时,在悬停/键盘聚焦时显示提示,并通过 aria-disabled 保持输入框可聚焦(仍阻止输入和调整)。请使用此属性,而不是用 Tooltip 包裹已禁用的 TimeInput。',+ },+ {+ name: 'value',+ type: 'ISOTimeString',+ description: 'ISO 格式的受控时间值(HH:MM 或 HH:MM:SS)。',+ },+ {+ name: 'onChange',+ type: '(value: ISOTimeString | undefined) => void',+ description: '时间变化时触发的回调。输入被清除时接收 undefined。',+ },+ {+ name: 'changeAction',+ type: '(value: ISOTimeString | undefined) => void | Promise<void>',+ description:+ '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '使输入框进入加载状态,显示旋转器。',+ default: 'false',+ },+ {+ name: 'min',+ type: 'ISOTimeString',+ description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。',+ },+ {+ name: 'max',+ type: 'ISOTimeString',+ description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。',+ },+ {+ name: 'hasSeconds',+ type: 'boolean',+ description: '在时间显示和解析中包含秒。',+ default: 'false',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description: '当有值且输入框未被禁用时显示清除按钮。',+ default: 'false',+ },+ {+ name: 'hourFormat',+ type: "'12h' | '24h'",+ description:+ "控制显示格式。'12h' 显示 AM/PM(例如 '2:30 PM');'24h' 使用 24 小时制(例如 '14:30')。",+ default: "'12h'",+ },+ {+ name: 'increment',+ type: 'number',+ description: '用户按上或下方向键时增加或减少的分钟数。',+ default: '1',+ },+ {+ name: 'placeholder',+ type: 'string',+ description:+ '未选择时间时显示的占位符文本。当输入框聚焦且为空时,格式提示会覆盖此文本。',+ default: "'Select a time'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: '控制输入框元素的高度。',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'InputStatus',+ description:+ '为边框着色并显示图标的状态指示器。当提供消息时,消息渲染在输入框下方。',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: '在标签行末尾以信息图标形式渲染的工具提示文本。',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',+ },],theming: {targets: [@@ -207,61 +388,155 @@ export const docsZh = {description:'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',bestPractices: [- {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},- {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},- {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},- {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},- {guidance: true, description: 'Enable hasClear when the field is optional, so users can remove a previously selected time.'},- {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},- {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},+ {+ guidance: true,+ description:+ 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',+ },+ {+ guidance: true,+ description:+ 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.',+ },+ {+ guidance: true,+ description:+ 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.',+ },+ {+ guidance: true,+ description:+ 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.',+ },+ {+ guidance: true,+ description:+ 'Enable hasClear when the field is optional, so users can remove a previously selected time.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},- {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},- {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},- {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},- {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},+ {+ name: 'Clock icon',+ required: false,+ description:+ 'A leading clock icon that identifies the field as a time input.',+ },+ {+ name: 'Text input',+ required: true,+ description:+ 'The editable text field where users type or see the formatted time.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'A trailing button to reset the value, shown when hasClear is true and a value is set.',+ },+ {+ name: 'Status icon',+ required: false,+ description:+ 'A trailing icon indicating error, warning, or success state.',+ },+ {+ name: 'Spinner',+ required: false,+ description:+ 'Replaces trailing content during loading to show an async action is in progress.',+ },],},};/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'Time input that converts free-text entry to standard format with arrow-key adjustment.',+ description:+ 'Time input that converts free-text entry to standard format with arrow-key adjustment.',usage: {description:'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',bestPractices: [- {guidance: true, description: 'Choose hour format (12h/24h) to match locale \u2014 12h for US, 24h for international.'},- {guidance: true, description: 'Set min/max constraints for valid ranges like business hours.'},- {guidance: true, description: 'Provide description or placeholder hinting at expected format.'},- {guidance: true, description: 'Use status prop for inline validation errors.'},+ {+ guidance: true,+ description:+ 'Choose hour format (12h/24h) to match locale \u2014 12h for US, 24h for international.',+ },+ {+ guidance: true,+ description:+ 'Set min/max constraints for valid ranges like business hours.',+ },+ {+ guidance: true,+ description:+ 'Provide description or placeholder hinting at expected format.',+ },+ {+ guidance: true,+ description: 'Use status prop for inline validation errors.',+ },{guidance: true, description: 'Enable hasClear for optional fields.'},- {guidance: false, description: 'Don\u2019t use for date-and-time \u2014 pair with DateInput instead.'},- {guidance: false, description: 'Don\u2019t hide the label \u2014 keep it visible for clarity.'},+ {+ guidance: false,+ description:+ 'Don\u2019t use for date-and-time \u2014 pair with DateInput instead.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t hide the label \u2014 keep it visible for clarity.',+ },+ {+ guidance: false,+ description:+ 'Don\u2019t wrap a disabled TimeInput in Tooltip; use the disabledMessage prop instead.',+ },],},propDescriptions: {label: 'Label text (required for a11y).',isLabelHidden: 'Visually hides label; keeps screen reader access.',description: 'Description text between label+input.',- isOptional: 'Shows "(optional)" indicator. Mutually exclusive w/ isRequired.',- isRequired: 'Marks required+sets aria-required. Mutually exclusive w/ isOptional.',+ isOptional:+ 'Shows "(optional)" indicator. Mutually exclusive w/ isRequired.',+ isRequired:+ 'Marks required+sets aria-required. Mutually exclusive w/ isOptional.',isDisabled: 'Disables input, suppresses interactions.',+ disabledMessage:+ 'Reason shown in a tooltip on hover/focus when disabled; keeps input focusable via aria-disabled.',value: 'Controlled time in ISO format (HH:MM or HH:MM:SS).',onChange: 'Fired on time change. Receives undefined when cleared.',- changeAction: 'Async action after onChange in React transition; triggers spinner while pending.',+ changeAction:+ 'Async action after onChange in React transition; triggers spinner while pending.',isLoading: 'Loading state w/ spinner.',min: 'Min selectable time in ISO format. Out-of-range rejected.',max: 'Max selectable time in ISO format. Out-of-range rejected.',hasSeconds: 'Includes seconds in display+parsing.',hasClear: 'Shows clear button when value set+not disabled.',- hourFormat: "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",+ hourFormat:+ "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",increment: 'Minutes to add/subtract on arrow up/down.',placeholder: 'Placeholder when empty. Focused+empty shows format hint.',size: 'Input element height.',status: 'Colored border+icon. Message rendered below input.',labelTooltip: 'Tooltip as info icon at label row end.',- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',+ xstyle:+ 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',},};diff --git a/packages/core/src/TimeInput/TimeInput.test.tsx b/packages/core/src/TimeInput/TimeInput.test.tsxindex 23b87bc8eb..69ee78ad86 100644--- a/packages/core/src/TimeInput/TimeInput.test.tsx+++ b/packages/core/src/TimeInput/TimeInput.test.tsx@@ -9,8 +9,8 @@* SYNC: When TimeInput.tsx changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {describe, it, expect, vi, beforeEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {TimeInput} from './TimeInput';import type {ISOTimeString} from '../utils';@@ -23,11 +23,7 @@ describe('TimeInput', () => {it('renders with placeholder', () => {render(- <TimeInput- label="Time"- onChange={() => {}}- placeholder="Pick a time"- />,+ <TimeInput label="Time" onChange={() => {}} placeholder="Pick a time" />,);expect(screen.getByPlaceholderText('Pick a time')).toBeInTheDocument();});@@ -210,4 +206,145 @@ describe('TimeInput', () => {fireEvent.click(wrapper);expect(input).toHaveFocus();});+ describe('disabledMessage', () => {+ // jsdom does not implement the Popover API used by the tooltip, so mock+ // showPopover/hidePopover to toggle a `popover-open` attribute the tests+ // can assert on.+ beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ });+ });++ // jsdom popover content is in the DOM but not "visible" in the+ // accessibility tree; use hidden: true to find it.+ const h = {hidden: true} as const;++ it('shows the reason tooltip on hover when disabled with a reason', async () => {+ render(+ <TimeInput+ label="Time"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const container = screen.getByLabelText('Time')+ .parentElement as HTMLElement;+ const tooltip = screen.getByRole('tooltip', h);+ expect(tooltip).toHaveTextContent('You need the Editor role');++ fireEvent.mouseEnter(container);+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });++ fireEvent.mouseLeave(container);+ await waitFor(() => {+ expect(tooltip).not.toHaveAttribute('popover-open');+ });+ });++ it('shows the reason tooltip on keyboard focus', async () => {+ const user = userEvent.setup();+ render(+ <TimeInput+ label="Time"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const tooltip = screen.getByRole('tooltip', h);+ await user.tab();+ expect(screen.getByLabelText('Time')).toHaveFocus();+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });+ });++ it('does not render a tooltip when not disabled', () => {+ render(+ <TimeInput label="Time" disabledMessage="You need the Editor role" />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('does not render a tooltip when disabled without a reason', () => {+ render(<TimeInput label="Time" isDisabled />);+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('keeps the input focusable via aria-disabled when a reason is provided', () => {+ render(+ <TimeInput+ label="Time"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByLabelText('Time');+ expect(input).not.toBeDisabled();+ expect(input).toHaveAttribute('aria-disabled', 'true');+ expect(input).toHaveAttribute('readonly');+ });++ it('links the reason tooltip from the input via aria-describedby', () => {+ render(+ <TimeInput+ label="Time"+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByLabelText('Time');+ const tooltip = screen.getByRole('tooltip', h);+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);+ });++ it('blocks typing and arrow-key changes while focusable-disabled', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <TimeInput+ label="Time"+ onChange={onChange}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const input = screen.getByLabelText('Time');+ await user.type(input, '2:30 PM');+ expect(input).toHaveValue('');+ input.focus();+ fireEvent.keyDown(input, {key: 'ArrowUp'});+ expect(onChange).not.toHaveBeenCalled();+ });++ it('remains natively disabled when disabled without a reason', () => {+ render(<TimeInput label="Time" isDisabled />);+ const input = screen.getByLabelText('Time');+ expect(input).toBeDisabled();+ expect(input).not.toHaveAttribute('aria-disabled');+ });++ it('does not swap in the format-hint placeholder on focus while disabled', () => {+ render(+ <TimeInput+ label="Time"+ isDisabled+ disabledMessage="You need the Editor role"+ placeholder="Select a time"+ />,+ );+ const input = screen.getByLabelText('Time');+ input.focus();+ fireEvent.focus(input);+ expect(input).toHaveAttribute('placeholder', 'Select a time');+ });+ });});diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsxindex 2453a6e6ed..9c363b656a 100644--- a/packages/core/src/TimeInput/TimeInput.tsx+++ b/packages/core/src/TimeInput/TimeInput.tsx@@ -63,6 +63,7 @@ import type {BaseProps} from '../BaseProps';import type {SizeValue} from '../utils/types';import {useSize} from '../SizeContext/SizeContext';import {useInputContainer} from '../hooks/useInputContainer';+import {useTooltip} from '../Tooltip';import {themeProps} from '../utils/themeProps';const styles = stylex.create({@@ -183,6 +184,29 @@ export interface TimeInputProps extends Omit<*/isDisabled?: boolean;+ /**+ * Explains why the input is disabled. When set together with+ * `isDisabled`, the input shows a tooltip with this text on hover and+ * keyboard focus, and the field stays focusable (via `aria-disabled`)+ * so the reason is discoverable by keyboard and assistive technology.+ * Typing and arrow-key adjustment stay blocked.+ *+ * Use this instead of wrapping a disabled input in `Tooltip` — disabled+ * controls don't emit the pointer events an external tooltip needs.+ *+ * @example+ * ```+ * <TimeInput+ * label="Start time"+ * value={time}+ * onChange={setTime}+ * isDisabled+ * disabledMessage="You need the Editor role to change this"+ * />+ * ```+ */+ disabledMessage?: string;+/*** The selected time in ISO format (HH:MM or HH:MM:SS).*/@@ -301,6 +325,7 @@ export function TimeInput({isOptional = false,isRequired = false,isDisabled = false,+ disabledMessage,value,onChange,changeAction,@@ -334,6 +359,19 @@ export function TimeInput({const [optimisticValue, setOptimisticValue] = useOptimistic(value);const isBusy = isLoading || optimisticValue !== value;+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the+ // tooltip listeners attach to the input container (which already exists) and+ // the input stays perceivable via aria-disabled instead of the disabled+ // attribute. Typing is blocked with readOnly and value mutation guards.+ const showsDisabledMessage = isDisabled && !!disabledMessage;+ const disabledMessageTooltip = useTooltip({+ placement: 'above',+ // The container div is not naturally focusable; focusin bubbles up from+ // the input, so always attach focus listeners.+ focusTrigger: 'always',+ isEnabled: showsDisabledMessage,+ });+// Status icon mappingconst statusIconMap: Record<InputStatusType, IconName> = {warning: 'warning',@@ -354,6 +392,7 @@ export function TimeInput({[description ? descriptionID : null,status?.message ? statusMessageID : null,+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,].filter(Boolean).join(' ') || undefined;@@ -415,6 +454,11 @@ export function TimeInput({// Handle input text change - update immediately if validconst handleInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {+ // With a disabledMessage the input drops `disabled` for focusability, so+ // guard value mutation explicitly (readOnly also blocks typing).+ if (isDisabled) {+ return;+ }const newValue = e.target.value;setPendingInput(newValue);@@ -424,13 +468,19 @@ export function TimeInput({fireChange(parsed);}},- [hasSeconds, min, max, value, fireChange],+ [hasSeconds, min, max, value, fireChange, isDisabled],);// Handle focusconst handleFocus = useCallback(() => {+ // A disabled input stays focusable (via aria-disabled) so its reason is+ // discoverable, but it must not present editing affordances — keep the+ // static placeholder rather than swapping in the format hint.+ if (isDisabled) {+ return;+ }setIsFocused(true);- }, []);+ }, [isDisabled]);// Handle blur - validate and clear pending inputconst handleBlur = useCallback(@@ -466,6 +516,11 @@ export function TimeInput({// Handle keyboard navigation on inputconst handleInputKeyDown = useCallback((e: KeyboardEvent<HTMLInputElement>) => {+ // Arrow-key adjustment mutates the value; block it while showing a+ // disabled reason (the input keeps focusability via aria-disabled).+ if (isDisabled) {+ return;+ }if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {e.preventDefault();@@ -492,7 +547,7 @@ export function TimeInput({}}},- [value, hasSeconds, increment, min, max, fireChange],+ [value, hasSeconds, increment, min, max, fireChange, isDisabled],);// Handle clear button click@@ -531,7 +586,13 @@ export function TimeInput({labelTooltip={labelTooltip}width={width}><div- ref={containerRef}+ ref={el => {+ containerRef.current = el;+ // Anchor + hover/focus listeners for the disabled-message tooltip.+ // Handlers are gated internally by isEnabled, so attaching+ // unconditionally is safe.+ disabledMessageTooltip.ref(el);+ }}onClick={handleWrapperClick}onMouseUp={handleWrapperMouseUp}{...mergeProps(@@ -561,7 +622,12 @@ export function TimeInput({onBlur={handleBlur}onKeyDown={handleInputKeyDown}placeholder={displayPlaceholder}- disabled={isDisabled}+ // With a disabledMessage the input keeps focusability via+ // aria-disabled so the reason is focus-discoverable; typing and+ // arrow-key adjustment are blocked with readOnly and the guards.+ disabled={isDisabled && !showsDisabledMessage}+ aria-disabled={showsDisabledMessage ? 'true' : undefined}+ readOnly={showsDisabledMessage || undefined}autoFocus={hasAutoFocus}data-autofocus={hasAutoFocus || undefined}aria-describedby={ariaDescribedBy}@@ -592,6 +658,9 @@ export function TimeInput({/>)}</div>++ {showsDisabledMessage &&+ disabledMessageTooltip.renderTooltip(disabledMessage)}</Field>);}diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsxindex bf6c87643f..1d375f5240 100644--- a/packages/core/src/Typeahead/BaseTypeahead.tsx+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx@@ -103,6 +103,16 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<*/isDisabled?: boolean;+ /**+ * When disabled with a reason, keeps the input focusable via `aria-disabled`+ * (instead of the native `disabled` attribute) and `readOnly` so an+ * associated disabled-reason tooltip stays discoverable by keyboard and+ * assistive technology. Value mutation is still blocked by the `isDisabled`+ * guards. Consumers (Typeahead) own the tooltip and wrapper.+ * @default false+ */+ isFocusableDisabled?: boolean;+/*** Auto-focus on mount.* @default false@@ -292,6 +302,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({maxMenuItems = 10,emptySearchResultsText = 'No results found',isDisabled = false,+ isFocusableDisabled = false,hasAutoFocus = false,onChangeQuery,onOpenChange,@@ -704,6 +715,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({}aria-autocomplete="list"aria-describedby={ariaDescribedBy}+ aria-disabled={isFocusableDisabled ? 'true' : undefined}value={query}onChange={handleInputChange}onPointerDown={() => {@@ -720,7 +732,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({onBlur={handleBlur}onKeyDown={handleKeyDown}placeholder={placeholder}- disabled={isDisabled}+ // When a disabled-reason tooltip is shown the input keeps focusability+ // via aria-disabled + readOnly instead of the native disabled+ // attribute; value mutation stays blocked by the isDisabled guards.+ disabled={isDisabled && !isFocusableDisabled}+ readOnly={isFocusableDisabled || undefined}autoFocus={hasAutoFocus}data-autofocus={hasAutoFocus || undefined}autoComplete="off"diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsindex d176e8d492..45baff1163 100644--- a/packages/core/src/Typeahead/Typeahead.doc.mjs+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -7,8 +7,21 @@ export const docs = {displayName: 'Typeahead',group: 'Typeahead',category: 'Data Input',- keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],- description: 'Styled typeahead with label, description, validation, and all field features. Wraps BaseTypeahead with Field for the primary use case.',+ keywords: [+ 'typeahead',+ 'autocomplete',+ 'combobox',+ 'searchbox',+ 'autosuggest',+ 'select',+ 'dropdown',+ 'lookup',+ 'searchable',+ 'suggestion',+ 'picker',+ ],+ description:+ 'Styled typeahead with label, description, validation, and all field features. Wraps BaseTypeahead with Field for the primary use case.',props: [{name: 'label',@@ -19,7 +32,8 @@ export const docs = {{name: 'searchSource',type: 'SearchSource<T>',- description: 'Data source providing search and bootstrap methods for populating the dropdown.',+ description:+ 'Data source providing search and bootstrap methods for populating the dropdown.',required: true,},{@@ -57,6 +71,12 @@ export const docs = {description: 'Disables the input.',default: 'false',},+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',+ },{name: 'maxMenuItems',type: 'number',@@ -66,12 +86,14 @@ export const docs = {{name: 'status',type: 'InputStatus',- description: 'Validation status object with type and message for error/warning/success states.',+ description:+ 'Validation status object with type and message for error/warning/success states.',},{name: 'renderItem',type: '(item: T) => ReactNode',- description: 'Custom render function for dropdown items. Default renders TypeaheadItem.',+ description:+ 'Custom render function for dropdown items. Default renders TypeaheadItem.',},{name: 'isLabelHidden',@@ -122,7 +144,8 @@ export const docs = {{name: 'debounceMs',type: 'number',- description: 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',+ description:+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',default: '150',},{@@ -138,13 +161,11 @@ export const docs = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',+ description:+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',},],- components: [- {name: 'BaseTypeahead'},- {name: 'TypeaheadItem'},- ],+ components: [{name: 'BaseTypeahead'}, {name: 'TypeaheadItem'}],theming: {targets: [{className: 'astryx-typeahead', visualProps: ['status']},@@ -156,12 +177,40 @@ export const docs = {description:'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',bestPractices: [- {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},- {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},- {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},- {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},- {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},- {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},+ {+ guidance: true,+ description:+ 'Provide descriptive placeholder text that hints at what users can search for.',+ },+ {+ guidance: true,+ description:+ 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',+ },+ {+ guidance: true,+ description:+ 'Add a search delay for remote data sources to avoid excessive network requests.',+ },+ {+ guidance: false,+ description:+ 'Use for short, static option lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description: 'Use for multi-selection; use Tokenizer instead.',+ },+ {+ guidance: false,+ description:+ 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},};@@ -172,29 +221,86 @@ export const docsZh = {description:'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',bestPractices: [- {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},- {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},- {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},- {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},- {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},- {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},+ {+ guidance: true,+ description:+ 'Provide descriptive placeholder text that hints at what users can search for.',+ },+ {+ guidance: true,+ description:+ 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',+ },+ {+ guidance: true,+ description:+ 'Add a search delay for remote data sources to avoid excessive network requests.',+ },+ {+ guidance: false,+ description:+ 'Use for short, static option lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description: 'Use for multi-selection; use Tokenizer instead.',+ },+ {+ guidance: false,+ description:+ 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},};/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',+ description:+ 'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',usage: {description:'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',bestPractices: [- {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},- {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},- {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},- {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},- {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},- {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},+ {+ guidance: true,+ description:+ 'Provide descriptive placeholder text that hints at what users can search for.',+ },+ {+ guidance: true,+ description:+ 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',+ },+ {+ guidance: true,+ description:+ 'Add a search delay for remote data sources to avoid excessive network requests.',+ },+ {+ guidance: false,+ description:+ 'Use for short, static option lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description: 'Use for multi-selection; use Tokenizer instead.',+ },+ {+ guidance: false,+ description:+ 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},};diff --git a/packages/core/src/Typeahead/Typeahead.test.tsx b/packages/core/src/Typeahead/Typeahead.test.tsxindex e7fca3eb0f..61e07494ed 100644--- a/packages/core/src/Typeahead/Typeahead.test.tsx+++ b/packages/core/src/Typeahead/Typeahead.test.tsx@@ -9,7 +9,15 @@* SYNC: When Typeahead components change, update tests to match*/-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';+import {+ describe,+ it,+ expect,+ vi,+ beforeAll,+ afterAll,+ beforeEach,+} from 'vitest';import {render, screen, fireEvent, waitFor} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Typeahead} from './Typeahead';@@ -734,3 +742,165 @@ describe('BaseTypeahead paste behavior', () => {}});});++describe('Typeahead disabledMessage', () => {+ // jsdom does not implement the Popover API used by the tooltip, so mock+ // showPopover/hidePopover to toggle a `popover-open` attribute the tests+ // can assert on.+ beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ });+ });++ // jsdom popover content is in the DOM but not "visible" in the+ // accessibility tree; use hidden: true to find it.+ const h = {hidden: true} as const;++ it('shows the reason tooltip on hover when disabled with a reason', async () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const container = screen.getByRole('combobox').parentElement as HTMLElement;+ const tooltip = screen.getByRole('tooltip', h);+ expect(tooltip).toHaveTextContent('You need the Editor role');++ fireEvent.mouseEnter(container);+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });++ fireEvent.mouseLeave(container);+ await waitFor(() => {+ expect(tooltip).not.toHaveAttribute('popover-open');+ });+ });++ it('shows the reason tooltip on keyboard focus', async () => {+ const user = userEvent.setup();+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const tooltip = screen.getByRole('tooltip', h);+ await user.tab();+ expect(screen.getByRole('combobox')).toHaveFocus();+ await waitFor(() => {+ expect(tooltip).toHaveAttribute('popover-open');+ });+ });++ it('does not render a tooltip when not disabled', () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ disabledMessage="You need the Editor role"+ />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('does not render a tooltip when disabled without a reason', () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ />,+ );+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();+ });++ it('keeps the input focusable via aria-disabled when a reason is provided', () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByRole('combobox');+ expect(input).not.toBeDisabled();+ expect(input).toHaveAttribute('aria-disabled', 'true');+ expect(input).toHaveAttribute('readonly');+ });++ it('links the reason tooltip from the input via aria-describedby', () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );+ const input = screen.getByRole('combobox');+ const tooltip = screen.getByRole('tooltip', h);+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);+ });++ it('blocks typing and selection while focusable-disabled', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={onChange}+ isDisabled+ disabledMessage="You need the Editor role"+ />,+ );++ const input = screen.getByRole('combobox');+ await user.click(input);+ await user.type(input, 'App');+ expect(input).toHaveValue('');+ expect(input).toHaveAttribute('aria-expanded', 'false');+ expect(onChange).not.toHaveBeenCalled();+ });++ it('remains natively disabled when disabled without a reason', () => {+ render(+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={() => {}}+ isDisabled+ />,+ );+ const input = screen.getByRole('combobox');+ expect(input).toBeDisabled();+ expect(input).not.toHaveAttribute('aria-disabled');+ });+});diff --git a/packages/core/src/Typeahead/Typeahead.tsx b/packages/core/src/Typeahead/Typeahead.tsxindex ba4d861530..e4c7f23e1d 100644--- a/packages/core/src/Typeahead/Typeahead.tsx+++ b/packages/core/src/Typeahead/Typeahead.tsx@@ -38,6 +38,7 @@ import {inputStatusFocusWithinStyles,} from '../Field';import {Token} from '../Token';+import {useTooltip} from '../Tooltip';import {renderIconSlot, type IconType} from '../Icon';import {spacingVars, sizeVars} from '../theme/tokens.stylex';import {mergeProps} from '../utils';@@ -101,6 +102,29 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<emptySearchResultsText?: string;/** Whether the input is disabled. @default false */isDisabled?: boolean;+ /**+ * Explains why the input is disabled. When set together with `isDisabled`,+ * the input shows a tooltip with this text on hover and keyboard focus, and+ * the field stays focusable (via `aria-disabled`) so the reason is+ * discoverable by keyboard and assistive technology. Editing and selection+ * stay blocked.+ *+ * Use this instead of wrapping a disabled input in `Tooltip` — disabled+ * controls don't emit the pointer events an external tooltip needs.+ *+ * @example+ * ```+ * <Typeahead+ * label="Assignee"+ * searchSource={userSource}+ * value={assignee}+ * onChange={setAssignee}+ * isDisabled+ * disabledMessage="You need the Editor role to change this"+ * />+ * ```+ */+ disabledMessage?: string;/** Show clear button. @default true */hasClear?: boolean;/** Auto-focus on mount. @default false */@@ -209,6 +233,7 @@ export function Typeahead<T extends SearchableItem>({maxMenuItems,emptySearchResultsText,isDisabled = false,+ disabledMessage,hasClear = true,hasAutoFocus,size: sizeProp,@@ -230,6 +255,21 @@ export function Typeahead<T extends SearchableItem>({const inputRef = useRef<HTMLInputElement>(null);const tokenRef = useRef<HTMLElement>(null);+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the+ // tooltip listeners attach to the input wrapper (which already exists) and+ // the input stays perceivable via aria-disabled + readOnly instead of the+ // disabled attribute. Editing and selection stay blocked by the isDisabled+ // guards (handleWrapperClick, handleEnterEditMode, and BaseTypeahead's own+ // focus/change guards).+ const showsDisabledMessage = isDisabled && !!disabledMessage;+ const disabledMessageTooltip = useTooltip({+ placement: 'above',+ // The wrapper div is not naturally focusable; focusin bubbles up from the+ // input, so always attach focus listeners.+ focusTrigger: 'always',+ isEnabled: showsDisabledMessage,+ });+// Edit mode: when the user clicks the token to edit the selected valueconst [isEditing, setIsEditing] = useState(false);const [editingValue, setEditingValue] = useState<T | null>(null);@@ -339,6 +379,7 @@ export function Typeahead<T extends SearchableItem>({[description ? descriptionId : null,status?.message ? statusMessageId : null,+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,].filter(Boolean).join(' ') || undefined;@@ -371,7 +412,13 @@ export function Typeahead<T extends SearchableItem>({className={className}style={style}><div- ref={wrapperRef}+ ref={el => {+ wrapperRef.current = el;+ // Anchor + hover/focus listeners for the disabled-message tooltip.+ // Handlers are gated internally by isEnabled, so attaching+ // unconditionally is safe.+ disabledMessageTooltip.ref(el);+ }}data-testid={testId}onClick={handleWrapperClick}onBlur={handleBlur}@@ -411,6 +458,7 @@ export function Typeahead<T extends SearchableItem>({emptySearchResultsText={emptySearchResultsText}isDisabled={isDisabled}hasAutoFocus={hasAutoFocus}+ isFocusableDisabled={showsDisabledMessage}inputId={inputId}ariaDescribedBy={ariaDescribedBy}onChangeQuery={onChangeQuery}@@ -432,6 +480,9 @@ export function Typeahead<T extends SearchableItem>({/>)}</div>++ {showsDisabledMessage &&+ disabledMessageTooltip.renderTooltip(disabledMessage)}</Field>);}