Skip to content

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

TypeScript

feat(input): add disabledMessage to choice inputs (#3509) (#3517)

Cindy Zhang07fadf03961d
diff --git a/.changeset/choice-disabled-message.md b/.changeset/choice-disabled-message.md
new file mode 100644
index 0000000000..ecdea18491
--- /dev/null
+++ b/.changeset/choice-disabled-message.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] CheckboxInput/Switch/Slider/RadioList/CheckboxList/SegmentedControl/Tokenizer/PowerSearch: disabledMessage prop shows a tooltip explaining the disabled state (#3509)
+@cixzhang
diff --git a/apps/storybook/stories/CheckboxInput.stories.tsx b/apps/storybook/stories/CheckboxInput.stories.tsx
index 9889d7e83d..3763cded3b 100644
--- a/apps/storybook/stories/CheckboxInput.stories.tsx
+++ b/apps/storybook/stories/CheckboxInput.stories.tsx
@@ -37,6 +37,11 @@ const meta: Meta<typeof CheckboxInput> = {
control: 'boolean',
description: 'Whether the checkbox is disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip.',
+ },
isRequired: {
control: 'boolean',
description: 'Whether the checkbox is required',
@@ -211,11 +216,7 @@ export const AllVariations: Story = {
gap: '16px',
maxWidth: '400px',
}}>
- <CheckboxInput
- label="Unchecked"
- value={value1}
- onChange={setValue1}
- />
+ <CheckboxInput label="Unchecked" value={value1} onChange={setValue1} />
<CheckboxInput label="Checked" value={value2} onChange={setValue2} />
<CheckboxInput
label="Indeterminate"
@@ -467,3 +468,29 @@ export const StatusVariations: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the checkbox to
+// see why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the checkbox stays focusable (toggling is still
+// blocked). Use disabledMessage instead of wrapping a disabled CheckboxInput in
+// Tooltip: disabled controls swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const [value, setValue] = useState<boolean | 'indeterminate'>(
+ args.value ?? false,
+ );
+ const {value: _, onChange: __, ...restArgs} = args;
+ return (
+ <CheckboxInput
+ {...restArgs}
+ value={value}
+ onChange={checked => setValue(checked)}
+ />
+ );
+ },
+ args: {
+ label: 'Accept terms',
+ isDisabled: true,
+ disabledMessage: 'Terms are managed by your administrator',
+ },
+};
diff --git a/apps/storybook/stories/CheckboxList.stories.tsx b/apps/storybook/stories/CheckboxList.stories.tsx
index 8070b6d344..dadda7d996 100644
--- a/apps/storybook/stories/CheckboxList.stories.tsx
+++ b/apps/storybook/stories/CheckboxList.stories.tsx
@@ -37,6 +37,11 @@ const meta: Meta<typeof CheckboxList> = {
control: 'boolean',
description: 'Whether all checkbox items are disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the group is disabled (whole-group state, not per item). With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkboxes focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxList in Tooltip.',
+ },
},
};
@@ -104,11 +109,7 @@ export const DynamicItems: Story = {
return (
<CheckboxList {...restArgs} value={value} onChange={setValue}>
{items.map(item => (
- <CheckboxListItem
- key={item.id}
- label={item.label}
- value={item.id}
- />
+ <CheckboxListItem key={item.id} label={item.label} value={item.id} />
))}
</CheckboxList>
);
@@ -352,10 +353,7 @@ export const AllVariations: Story = {
<CheckboxListItem label="Option A" value="a" />
<CheckboxListItem label="Option B" value="b" />
</CheckboxList>
- <CheckboxList
- label="Pre-selected"
- value={value2}
- onChange={setValue2}>
+ <CheckboxList label="Pre-selected" value={value2} onChange={setValue2}>
<CheckboxListItem label="Email" value="email" />
<CheckboxListItem label="SMS" value="sms" />
</CheckboxList>
@@ -460,3 +458,28 @@ export const InsideCardWithDividers: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the group to see
+// why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the checkboxes stay focusable (toggling is still
+// blocked). disabledMessage applies to the whole-group disabled state. Use it
+// instead of wrapping a disabled CheckboxList in Tooltip: disabled controls
+// swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(['email']);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <CheckboxList {...restArgs} value={value} onChange={setValue}>
+ <CheckboxListItem label="Email" value="email" />
+ <CheckboxListItem label="SMS" value="sms" />
+ <CheckboxListItem label="Push notification" value="push" />
+ </CheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ isDisabled: true,
+ disabledMessage: 'Notifications are managed by your administrator',
+ },
+};
diff --git a/apps/storybook/stories/PowerSearch.stories.tsx b/apps/storybook/stories/PowerSearch.stories.tsx
index d3d67ca1f4..154a3b7cb4 100644
--- a/apps/storybook/stories/PowerSearch.stories.tsx
+++ b/apps/storybook/stories/PowerSearch.stories.tsx
@@ -3,7 +3,10 @@
import React, {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {PowerSearch} from '@astryxdesign/core/PowerSearch';
-import type {PowerSearchConfig, PowerSearchFilter} from '@astryxdesign/core/PowerSearch';
+import type {
+ PowerSearchConfig,
+ PowerSearchFilter,
+} from '@astryxdesign/core/PowerSearch';
import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
import {Button} from '@astryxdesign/core/Button';
import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
@@ -308,6 +311,11 @@ const meta: Meta<typeof PowerSearch> = {
argTypes: {
placeholder: {control: 'text'},
isDisabled: {control: 'boolean'},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip.',
+ },
isReadOnly: {control: 'boolean'},
hasClear: {control: 'boolean'},
maxTokenLength: {control: 'number'},
@@ -1341,3 +1349,29 @@ export const WithCustomComponents: Story = {
],
name: 'Custom Components Map',
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the input to see
+// why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the input stays focusable (input is still blocked). Use
+// disabledMessage instead of wrapping a disabled PowerSearch in Tooltip:
+// disabled controls swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const filters: PowerSearchFilter[] = [
+ {field: 'status', operator: 'is', value: {type: 'enum', value: 'open'}},
+ ];
+ return (
+ <PowerSearch
+ {...args}
+ config={basicConfig}
+ filters={filters}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="You need edit access to search"
+ />
+ );
+ },
+ args: {
+ placeholder: 'Search...',
+ },
+};
diff --git a/apps/storybook/stories/RadioList.stories.tsx b/apps/storybook/stories/RadioList.stories.tsx
index ed1a653d08..10acb3720e 100644
--- a/apps/storybook/stories/RadioList.stories.tsx
+++ b/apps/storybook/stories/RadioList.stories.tsx
@@ -35,6 +35,11 @@ const meta: Meta<typeof RadioList> = {
control: 'boolean',
description: 'Whether all radio items are disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the group is disabled (whole-group state, not per item). With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip.',
+ },
isRequired: {
control: 'boolean',
description: 'Whether the radio group is required',
@@ -215,11 +220,7 @@ export const WithStartContent: Story = {
value="email"
startContent={<span>📧</span>}
/>
- <RadioListItem
- label="SMS"
- value="sms"
- startContent={<span>💬</span>}
- />
+ <RadioListItem label="SMS" value="sms" startContent={<span>💬</span>} />
<RadioListItem
label="Push notification"
value="push"
@@ -332,3 +333,28 @@ export const AllVariations: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the group to see
+// why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the radios stay focusable (selection is still blocked).
+// disabledMessage applies to the whole-group disabled state. Use it instead of
+// wrapping a disabled RadioList in Tooltip: disabled controls swallow the
+// pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const [value, setValue] = useState(args.value ?? 'email');
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <RadioList {...restArgs} value={value} onChange={setValue}>
+ <RadioListItem label="Email" value="email" />
+ <RadioListItem label="SMS" value="sms" />
+ <RadioListItem label="Push notification" value="push" />
+ </RadioList>
+ );
+ },
+ args: {
+ label: 'Notification preference',
+ isDisabled: true,
+ disabledMessage: 'Upgrade your account to change preferences',
+ },
+};
diff --git a/apps/storybook/stories/SegmentedControl.stories.tsx b/apps/storybook/stories/SegmentedControl.stories.tsx
index aa329b9a12..38cfdbf2dd 100644
--- a/apps/storybook/stories/SegmentedControl.stories.tsx
+++ b/apps/storybook/stories/SegmentedControl.stories.tsx
@@ -27,6 +27,11 @@ const meta: Meta<typeof SegmentedControl> = {
control: 'boolean',
description: 'Whether the entire control is disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the control is disabled (whole-group state, not per segment). With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip.',
+ },
},
};
@@ -200,3 +205,27 @@ export const DisabledItem: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the control to
+// see why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the selected segment stays focusable (selection is still
+// blocked). disabledMessage applies to the whole-group disabled state. Use it
+// instead of wrapping a disabled SegmentedControl in Tooltip: disabled controls
+// swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: () => {
+ const [value, setValue] = useState('all');
+ return (
+ <SegmentedControl
+ value={value}
+ onChange={setValue}
+ label="Filter"
+ isDisabled
+ disabledMessage="Choose a project to filter tasks">
+ <SegmentedControlItem value="all" label="All" />
+ <SegmentedControlItem value="active" label="Active" />
+ <SegmentedControlItem value="completed" label="Completed" />
+ </SegmentedControl>
+ );
+ },
+};
diff --git a/apps/storybook/stories/Slider.stories.tsx b/apps/storybook/stories/Slider.stories.tsx
index 9de4b5712c..ef78d34916 100644
--- a/apps/storybook/stories/Slider.stories.tsx
+++ b/apps/storybook/stories/Slider.stories.tsx
@@ -23,6 +23,11 @@ const meta: Meta<typeof Slider> = {
control: 'boolean',
description: 'Whether the slider is disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip.',
+ },
min: {
control: 'number',
description: 'Minimum value',
@@ -237,3 +242,20 @@ export const AllVariations: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the thumb to see
+// why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the thumb stays focusable (value changes are still
+// blocked). Use disabledMessage instead of wrapping a disabled Slider in
+// Tooltip: disabled controls swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ return <Slider {...(args as any)} />;
+ },
+ args: {
+ label: 'Volume',
+ value: 50,
+ isDisabled: true,
+ disabledMessage: 'Volume is locked while sharing your screen',
+ },
+};
diff --git a/apps/storybook/stories/Switch.stories.tsx b/apps/storybook/stories/Switch.stories.tsx
index 7268e744ca..d513a114da 100644
--- a/apps/storybook/stories/Switch.stories.tsx
+++ b/apps/storybook/stories/Switch.stories.tsx
@@ -36,6 +36,11 @@ const meta: Meta<typeof Switch> = {
control: 'boolean',
description: 'Whether the switch is disabled',
},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip.',
+ },
isOptional: {
control: 'boolean',
description: 'Whether the field is optional',
@@ -539,3 +544,27 @@ export const StatusVariations: Story = {
);
},
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the switch to
+// see why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the switch stays focusable (toggling is still blocked).
+// Use disabledMessage instead of wrapping a disabled Switch in Tooltip: disabled
+// controls swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const [value, setValue] = useState(args.value ?? false);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <Switch
+ {...restArgs}
+ value={value}
+ onChange={checked => setValue(checked)}
+ />
+ );
+ },
+ args: {
+ label: 'Enable notifications',
+ isDisabled: true,
+ disabledMessage: 'Notifications are turned off org-wide',
+ },
+};
diff --git a/apps/storybook/stories/Tokenizer.stories.tsx b/apps/storybook/stories/Tokenizer.stories.tsx
index 8031f599f9..a64abf7aa6 100644
--- a/apps/storybook/stories/Tokenizer.stories.tsx
+++ b/apps/storybook/stories/Tokenizer.stories.tsx
@@ -33,6 +33,11 @@ const meta: Meta<typeof Tokenizer> = {
label: {control: 'text'},
placeholder: {control: 'text'},
isDisabled: {control: 'boolean'},
+ disabledMessage: {
+ control: 'text',
+ description:
+ 'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip.',
+ },
isRequired: {control: 'boolean'},
isOptional: {control: 'boolean'},
hasClear: {control: 'boolean'},
@@ -282,10 +287,7 @@ export const OverflowLayer: Story = {
export const WithEndContent: Story = {
render: args => {
- const [value, setValue] = useState<SearchableItem[]>([
- users[0],
- users[2],
- ]);
+ const [value, setValue] = useState<SearchableItem[]>([users[0], users[2]]);
return (
<Tokenizer
{...args}
@@ -396,3 +398,27 @@ export const CreatableWithSearch: Story = {
},
name: 'Creatable + Search',
};
+
+// Disabled with an explanation tooltip. Hover or keyboard-focus the input to see
+// why it's disabled — the reason is announced to assistive tech via
+// aria-describedby, and the input stays focusable (input is still blocked). Use
+// disabledMessage instead of wrapping a disabled Tokenizer in Tooltip: disabled
+// controls swallow the pointer events a Tooltip wrapper needs.
+export const DisabledWithMessage: Story = {
+ render: args => {
+ const [value] = useState([users[0], users[1]]);
+ return (
+ <Tokenizer
+ {...args}
+ searchSource={userSource}
+ value={value}
+ onChange={() => {}}
+ />
+ );
+ },
+ args: {
+ label: 'Team Members',
+ isDisabled: true,
+ disabledMessage: 'You need edit access to change members',
+ },
+};
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index b960154300..8d8a43e1af 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -63,6 +63,12 @@ export const docs = {
description: 'Whether the checkbox is disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isReadOnly',
type: 'boolean',
@@ -124,6 +130,7 @@ export const docs = {
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
{ guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
{ guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+ { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
anatomy: [
{ name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },
@@ -146,6 +153,7 @@ export const docsZh = {
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
{ guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
{ guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+ { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
props: [
@@ -163,6 +171,7 @@ export const docsZh = {
},
{name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
{name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
+ {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.'},
{name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同,只读复选框不会变暗。', default: 'false'},
{name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
{name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
@@ -200,6 +209,7 @@ export const docsDense = {
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
{ guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
{ guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+ { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
index 32d89f4e2d..54d7cb0a35 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
@@ -9,11 +9,38 @@
* SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} 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 {CheckboxInput} from './CheckboxInput';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('CheckboxInput', () => {
it('renders with label', () => {
render(
@@ -236,4 +263,133 @@ describe('CheckboxInput', () => {
'true',
);
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function getRow(): HTMLElement {
+ return screen.getByRole('checkbox', h).closest('div')!.parentElement!;
+ }
+
+ it('shows the reason tooltip on hover when disabled with a reason', async () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent(
+ 'Terms are managed by your administrator',
+ );
+ fireEvent.mouseEnter(getRow());
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(getRow());
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ expect(screen.getByRole('checkbox', h)).toHaveFocus();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the checkbox focusable via aria-disabled when a reason is provided', () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ const checkbox = screen.getByRole('checkbox', h);
+ expect(checkbox).not.toBeDisabled();
+ expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('links the reason tooltip via aria-describedby', () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ const checkbox = screen.getByRole('checkbox', h);
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(checkbox.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks toggling while focusable-disabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={onChange}
+ isDisabled
+ disabledMessage="Terms are managed by your administrator"
+ />,
+ );
+ const checkbox = screen.getByRole('checkbox', h);
+ await user.click(checkbox);
+ expect(onChange).not.toHaveBeenCalled();
+ expect(checkbox).not.toBeChecked();
+ });
+
+ it('remains natively disabled when disabled without a reason', () => {
+ render(
+ <CheckboxInput
+ label="Accept terms"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.getByRole('checkbox')).toBeDisabled();
+ });
+ });
});
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index 197114471c..80bfbf2670 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx
@@ -4,7 +4,7 @@
/**
* @file CheckboxInput.tsx
- * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus
+ * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
* @output Exports CheckboxInput component, CheckboxInputProps
* @position Core implementation; consumed by index.ts, tested by CheckboxInput.test.tsx
*
@@ -19,6 +19,7 @@
import {
useId,
useCallback,
+ use,
useOptimistic,
useTransition,
type ChangeEvent,
@@ -44,9 +45,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
import type {IconType} from '../Icon';
import type {InputStatus} from '../Field/types';
import {Spinner} from '../Spinner';
+import {useTooltip} from '../Tooltip';
import {mergeProps, mergeRefs} from '../utils';
import {checkboxScope} from './checkbox.markers.stylex';
import {themeProps} from '../utils/themeProps';
+import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
const styles = stylex.create({
container: {
@@ -269,6 +272,27 @@ export interface CheckboxInputProps extends Omit<BaseProps, 'onChange'> {
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Explains why the checkbox is disabled. When set together with
+ * `isDisabled`, the checkbox shows a tooltip with this text on hover and
+ * keyboard focus, and the control 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 checkbox in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ *
+ * @example
+ * ```
+ * <CheckboxInput
+ * label="Accept terms"
+ * value={accepted}
+ * isDisabled
+ * disabledMessage="Terms are managed by your administrator"
+ * />
+ * ```
+ */
+ disabledMessage?: string;
/**
* Whether the checkbox is read-only.
* Displays the current state at full opacity but prevents interaction.
@@ -350,6 +374,7 @@ export function CheckboxInput({
isLoading = false,
value,
isDisabled = false,
+ disabledMessage,
isReadOnly = false,
isOptional = false,
isRequired = false,
@@ -372,6 +397,29 @@ export function CheckboxInput({
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 checkbox row (which already exists) and the
+ // native checkbox stays perceivable via aria-disabled instead of the disabled
+ // attribute. Value mutation is blocked by the isDisabled guard in onChange.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ // Keep the native checkbox focusable via aria-disabled either when it renders
+ // its own reason tooltip, or when it sits in a CheckboxList whose whole-group
+ // `disabledMessage` (shown on the group container) needs each checkbox to
+ // stay keyboard-perceivable. The group signals this through context rather
+ // than a public prop.
+ const checkboxListContext = use(CheckboxListContext);
+ const isFocusableDisabled =
+ isDisabled &&
+ (showsDisabledMessage ||
+ (checkboxListContext?.hasDisabledMessage ?? false));
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The container row is not naturally focusable; focusin bubbles up from the
+ // native checkbox, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
const isIndeterminate = optimisticValue === 'indeterminate';
const isChecked = optimisticValue === true;
const isCheckedOrIndeterminate = isChecked || isIndeterminate;
@@ -398,6 +446,9 @@ export function CheckboxInput({
if (status?.message) {
describedByParts.push(statusMessageID);
}
+ if (showsDisabledMessage) {
+ describedByParts.push(disabledMessageTooltip.describedBy);
+ }
const ariaDescribedBy =
describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
@@ -410,6 +461,15 @@ export function CheckboxInput({
style,
)}>
<div
+ ref={el => {
+ // Interaction (hover/focus) listeners for the disabled-message
+ // tooltip attach to the whole row for a larger trigger target;
+ // positioning anchors on the checkbox itself (below) so the tooltip
+ // appears next to the control, not the far edge of the row.
+ // Handlers are gated internally by isEnabled, so attaching
+ // unconditionally is safe.
+ disabledMessageTooltip.interactionRef(el);
+ }}
{...stylex.props(
styles.container,
isLabelHidden && styles.containerLabelHidden,
@@ -417,15 +477,23 @@ export function CheckboxInput({
)}>
<div {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}>
<input
- ref={mergeRefs(ref, indeterminateRef)}
+ ref={mergeRefs(
+ ref,
+ indeterminateRef,
+ disabledMessageTooltip.positionRef,
+ )}
id={id}
type="checkbox"
checked={isChecked}
- disabled={isDisabled}
+ // With a disabledMessage the checkbox keeps focusability via
+ // aria-disabled so the reason is focus-discoverable; toggling is
+ // still blocked by the isDisabled guard in onChange below.
+ disabled={isDisabled && !isFocusableDisabled}
+ aria-disabled={isFocusableDisabled ? 'true' : undefined}
readOnly={isReadOnly}
required={isRequired}
onChange={e => {
- if (isBusy || isReadOnly) {
+ if (isDisabled || isBusy || isReadOnly) {
return;
}
const checked = e.target.checked;
@@ -527,6 +595,8 @@ export function CheckboxInput({
variant="detached"
/>
)}
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</div>
);
}
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index 47003cee48..afc3fab5b0 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -77,6 +77,12 @@ export const docs = {
description: 'Whether all checkbox items are disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkboxes focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxList in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'status',
type: 'InputStatus',
@@ -99,6 +105,7 @@ export const docs = {
{ guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
{ guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
{ guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+ { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -113,6 +120,7 @@ export const docsZh = {
{ guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
{ guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
{ guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+ { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -129,6 +137,7 @@ export const docsDense = {
{ guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
{ guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
{ guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+ { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index da35dfa4c8..a0e8118647 100644
--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx
@@ -9,13 +9,46 @@
* SYNC: When CheckboxList.tsx or CheckboxListItem.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent, within} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {
+ render,
+ screen,
+ fireEvent,
+ within,
+ waitFor,
+} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {CheckboxList} from './CheckboxList';
import {CheckboxListItem} from './CheckboxListItem';
import {List} from '../List/List';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('CheckboxList', () => {
it('renders with label', () => {
render(
@@ -516,4 +549,108 @@ describe('CheckboxListItem ARIA props', () => {
expect(item).toHaveAttribute('aria-describedby', 'help-text');
expect(item).toHaveAttribute('aria-label', 'custom label');
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function renderGroup(props?: {onChange?: (v: string[]) => void}) {
+ return render(
+ <CheckboxList
+ label="Notifications"
+ value={['email']}
+ onChange={props?.onChange ?? (() => {})}
+ isDisabled
+ disabledMessage="Notifications are managed by your administrator">
+ <CheckboxListItem label="Email" value="email" />
+ <CheckboxListItem label="SMS" value="sms" />
+ </CheckboxList>,
+ );
+ }
+
+ it('shows the reason tooltip on hover when the group is disabled with a reason', async () => {
+ renderGroup();
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent(
+ 'Notifications are managed by your administrator',
+ );
+ const group = screen.getByRole('group');
+ fireEvent.mouseEnter(group);
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(group);
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ renderGroup();
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <CheckboxList
+ label="Notifications"
+ value={['email']}
+ onChange={() => {}}
+ disabledMessage="Notifications are managed by your administrator">
+ <CheckboxListItem label="Email" value="email" />
+ </CheckboxList>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <CheckboxList
+ label="Notifications"
+ value={['email']}
+ onChange={() => {}}
+ isDisabled>
+ <CheckboxListItem label="Email" value="email" />
+ </CheckboxList>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps checkboxes focusable via aria-disabled when a reason is provided', () => {
+ renderGroup();
+ for (const checkbox of screen.getAllByRole('checkbox', h)) {
+ expect(checkbox).not.toBeDisabled();
+ expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+ }
+ });
+
+ it('links the reason tooltip from the group via aria-describedby', () => {
+ renderGroup();
+ const group = screen.getByRole('group');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks toggling while focusable-disabled', () => {
+ const onChange = vi.fn();
+ renderGroup({onChange});
+ const sms = screen.getByRole('checkbox', {name: 'SMS', hidden: true});
+ fireEvent.click(sms);
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('keeps checkboxes natively disabled when disabled without a reason', () => {
+ render(
+ <CheckboxList
+ label="Notifications"
+ value={['email']}
+ onChange={() => {}}
+ isDisabled>
+ <CheckboxListItem label="Email" value="email" />
+ <CheckboxListItem label="SMS" value="sms" />
+ </CheckboxList>,
+ );
+ for (const checkbox of screen.getAllByRole('checkbox', h)) {
+ expect(checkbox).toBeDisabled();
+ }
+ });
+ });
});
diff --git a/packages/core/src/CheckboxList/CheckboxList.tsx b/packages/core/src/CheckboxList/CheckboxList.tsx
index 258dd33b5c..33d332f867 100644
--- a/packages/core/src/CheckboxList/CheckboxList.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.tsx
@@ -30,6 +30,7 @@ import {Field} from '../Field/Field';
import type {InputStatus} from '../Field/types';
import {List} from '../List/List';
import type {ListDensity} from '../List/ListContext';
+import {useTooltip} from '../Tooltip';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
import {
@@ -93,6 +94,18 @@ export interface CheckboxListProps extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Explains why the checkbox group is disabled. Applies to the whole-group
+ * disabled state (`isDisabled`), not individual items. When set together with
+ * `isDisabled`, the group shows a tooltip with this text on hover and keyboard
+ * focus, and its checkboxes stay focusable (via `aria-disabled`) so the reason
+ * is discoverable by keyboard and assistive technology. Toggling stays
+ * blocked.
+ *
+ * Use this instead of wrapping a disabled group in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ */
+ disabledMessage?: string;
/**
* Whether all checkbox items are read-only.
* Displays the current state at full opacity but prevents interaction.
@@ -141,6 +154,7 @@ export function CheckboxList({
density = 'balanced',
hasDividers = false,
isDisabled = false,
+ disabledMessage,
isReadOnly = false,
children,
ref,
@@ -163,6 +177,19 @@ export function CheckboxList({
// the transition settles, so the spinner clears without manual cleanup.
const [loadingValue, setLoadingValue] = useOptimistic<string | null>(null);
+ // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+ // controls swallow pointer events, so the tooltip listeners attach to the
+ // group container and the checkboxes stay perceivable via aria-disabled
+ // instead of the disabled attribute. Toggling is blocked in the item.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The group container is not naturally focusable; focusin bubbles up from
+ // the checkboxes, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
const handleChange = useCallback(
(newValues: string[], toggledValue?: string) => {
onChange?.(newValues);
@@ -190,6 +217,7 @@ export function CheckboxList({
value: isCollectionMode ? optimisticValue : undefined,
onChange: isCollectionMode ? handleChange : undefined,
isDisabled,
+ hasDisabledMessage: showsDisabledMessage,
isReadOnly,
loadingValue,
}),
@@ -198,6 +226,7 @@ export function CheckboxList({
optimisticValue,
handleChange,
isDisabled,
+ showsDisabledMessage,
isReadOnly,
loadingValue,
],
@@ -230,12 +259,19 @@ export function CheckboxList({
{...mergeProps(themeProps('checkbox-list'), {className, style})}>
<CheckboxListContext value={contextValue}>
<div
+ ref={el => {
+ // Anchor + hover/focus listeners for the disabled-message tooltip.
+ // Handlers are gated internally by isEnabled, so attaching
+ // unconditionally is safe.
+ disabledMessageTooltip.ref(el);
+ }}
role="group"
aria-labelledby={labelID}
aria-describedby={
[
description ? descriptionID : null,
status?.message ? statusMessageID : null,
+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
.join(' ') || undefined
@@ -245,6 +281,8 @@ export function CheckboxList({
</List>
</div>
</CheckboxListContext>
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
diff --git a/packages/core/src/CheckboxList/CheckboxListContext.tsx b/packages/core/src/CheckboxList/CheckboxListContext.tsx
index 5e324eb739..9112809cef 100644
--- a/packages/core/src/CheckboxList/CheckboxListContext.tsx
+++ b/packages/core/src/CheckboxList/CheckboxListContext.tsx
@@ -21,6 +21,13 @@ export interface CheckboxListContextValue {
*/
onChange?: (values: string[], toggledValue?: string) => void;
isDisabled: boolean;
+ /**
+ * True when the whole group is disabled *and* a `disabledMessage` is set. In
+ * that mode items stay focusable via `aria-disabled` (instead of the native
+ * `disabled` attribute) so the group's disabled-reason tooltip is keyboard-
+ * and AT-discoverable; toggling is still blocked.
+ */
+ hasDisabledMessage?: boolean;
isReadOnly: boolean;
/**
* The value of the item with a pending `changeAction`, or null when idle.
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 7c19a92350..83e02f43a4 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -71,6 +71,12 @@ export const docs = {
description: 'Disables the entire component.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'status',
type: 'InputStatus',
@@ -136,6 +142,7 @@ export const docs = {
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
{ guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -212,6 +219,12 @@ export const docsZh = {
description: '禁用整个组件。',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'status',
type: 'InputStatus',
@@ -269,6 +282,7 @@ export const docsZh = {
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
{ guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -284,6 +298,7 @@ export const docsDense = {
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
{ guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/PowerSearch/PowerSearch.test.tsx b/packages/core/src/PowerSearch/PowerSearch.test.tsx
index 2e5b87d18d..2caa1b614a 100644
--- a/packages/core/src/PowerSearch/PowerSearch.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.test.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {PowerSearch} from './PowerSearch';
import type {PowerSearchConfig, PowerSearchFilter} from './types';
@@ -199,4 +199,100 @@ describe('PowerSearch', () => {
expect(pasteResults).toEqual(typeResults);
});
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+ const isOpen = (el: Element) => el.matches(':popover-open');
+
+ function renderSearch(props?: {onChange?: () => void}) {
+ return render(
+ <PowerSearch
+ config={config}
+ filters={[]}
+ onChange={props?.onChange ?? (() => {})}
+ isDisabled
+ disabledMessage="You need edit access to search"
+ />,
+ );
+ }
+
+ it('shows the reason tooltip on hover when disabled with a reason', async () => {
+ renderSearch();
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent('You need edit access to search');
+ const wrapper = screen.getByRole('group');
+ fireEvent.mouseEnter(wrapper);
+ await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+ fireEvent.mouseLeave(wrapper);
+ await waitFor(() => expect(isOpen(tooltip)).toBe(false));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ renderSearch();
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ expect(screen.getByRole('combobox')).toHaveFocus();
+ await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <PowerSearch
+ config={config}
+ filters={[]}
+ onChange={() => {}}
+ disabledMessage="You need edit access to search"
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <PowerSearch
+ config={config}
+ filters={[]}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+ renderSearch();
+ const input = screen.getByRole('combobox');
+ expect(input).not.toBeDisabled();
+ expect(input).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('links the reason tooltip via aria-describedby', () => {
+ renderSearch();
+ const input = screen.getByRole('combobox');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks input while focusable-disabled', async () => {
+ const user = userEvent.setup();
+ renderSearch();
+ const input = screen.getByRole('combobox');
+ input.focus();
+ await user.keyboard('open');
+ expect((input as HTMLInputElement).value).toBe('');
+ });
+
+ it('keeps the input natively disabled when disabled without a reason', () => {
+ render(
+ <PowerSearch
+ config={config}
+ filters={[]}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.getByRole('combobox')).toBeDisabled();
+ });
+ });
});
diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsx
index cf1f208348..67ed258227 100644
--- a/packages/core/src/PowerSearch/PowerSearch.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.tsx
@@ -358,6 +358,16 @@ export interface PowerSearchProps extends Omit<
isReadOnly?: boolean;
/** Whether the input is disabled. @default false */
isDisabled?: boolean;
+ /**
+ * Explains why the search is disabled. When set together with `isDisabled`,
+ * the search shows a tooltip with this text on hover and keyboard focus, and
+ * the input stays focusable (via `aria-disabled`) so the reason is
+ * discoverable by keyboard and assistive technology. Input stays blocked.
+ *
+ * Use this instead of wrapping a disabled PowerSearch in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ */
+ disabledMessage?: string;
/**
* Icon to display at the start of the input.
* Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -508,6 +518,7 @@ export function PowerSearch({
hasClear = true,
isReadOnly = false,
isDisabled = false,
+ disabledMessage,
startIcon,
onFocus,
onBlur,
@@ -798,9 +809,7 @@ export function PowerSearch({
filter.value.value[0].photo
) {
const entity = filter.value.value[0];
- tokenIcon = (
- <Avatar src={entity.photo} name={entity.label} size={16} />
- );
+ tokenIcon = <Avatar src={entity.photo} name={entity.label} size={16} />;
}
return (
@@ -985,6 +994,7 @@ export function PowerSearch({
startIcon={startIcon}
endContent={combinedEndContent}
isDisabled={isDisabled}
+ disabledMessage={disabledMessage}
size={size}
tokenOverflowBehavior={tokenOverflowBehavior}
hasEntriesOnFocus
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 19d5317c6f..37ca127abe 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -74,6 +74,12 @@ export const docs = {
description: 'Whether all radio items are disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isRequired',
type: 'boolean',
@@ -121,6 +127,7 @@ export const docs = {
{ guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
{ guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
{ guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+ { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -142,6 +149,7 @@ export const docsZh = {
{ guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
{ guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
{ guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+ { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -165,6 +173,7 @@ export const docsDense = {
{ guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
{ guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
{ guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+ { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsx
index 7e8f58987c..a1930d5e21 100644
--- a/packages/core/src/RadioList/RadioList.test.tsx
+++ b/packages/core/src/RadioList/RadioList.test.tsx
@@ -9,12 +9,39 @@
* SYNC: When RadioList.tsx or RadioListItem.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} 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 {RadioList} from './RadioList';
import {RadioListItem} from './RadioListItem';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('RadioList', () => {
it('renders with label', () => {
render(
@@ -455,4 +482,98 @@ describe('RadioList', () => {
expect(optionB).toHaveFocus();
});
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function renderGroup(props?: {onChange?: (v: string) => void}) {
+ return render(
+ <RadioList
+ label="Plan"
+ value="free"
+ onChange={props?.onChange ?? (() => {})}
+ isDisabled
+ disabledMessage="Upgrade your account to change plans">
+ <RadioListItem label="Free" value="free" />
+ <RadioListItem label="Pro" value="pro" />
+ </RadioList>,
+ );
+ }
+
+ it('shows the reason tooltip on hover when the group is disabled with a reason', async () => {
+ renderGroup();
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent('Upgrade your account to change plans');
+ const group = screen.getByRole('radiogroup');
+ fireEvent.mouseEnter(group);
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(group);
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ renderGroup();
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <RadioList
+ label="Plan"
+ value="free"
+ onChange={() => {}}
+ disabledMessage="Upgrade your account to change plans">
+ <RadioListItem label="Free" value="free" />
+ </RadioList>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
+ <RadioListItem label="Free" value="free" />
+ </RadioList>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps radios focusable via aria-disabled when a reason is provided', () => {
+ renderGroup();
+ for (const radio of screen.getAllByRole('radio', h)) {
+ expect(radio).not.toBeDisabled();
+ expect(radio).toHaveAttribute('aria-disabled', 'true');
+ }
+ });
+
+ it('links the reason tooltip from the group via aria-describedby', () => {
+ renderGroup();
+ const group = screen.getByRole('radiogroup');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks selection while focusable-disabled', () => {
+ const onChange = vi.fn();
+ renderGroup({onChange});
+ const pro = screen.getByRole('radio', {name: 'Pro', hidden: true});
+ fireEvent.click(pro);
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('keeps radios natively disabled when disabled without a reason', () => {
+ render(
+ <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
+ <RadioListItem label="Free" value="free" />
+ <RadioListItem label="Pro" value="pro" />
+ </RadioList>,
+ );
+ for (const radio of screen.getAllByRole('radio', h)) {
+ expect(radio).toBeDisabled();
+ }
+ });
+ });
});
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
index 7708ca161a..181e96e7be 100644
--- a/packages/core/src/RadioList/RadioList.tsx
+++ b/packages/core/src/RadioList/RadioList.tsx
@@ -28,6 +28,7 @@ import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
import {Field} from '../Field/Field';
import type {InputStatus} from '../Field/types';
+import {useTooltip} from '../Tooltip';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
@@ -43,6 +44,13 @@ export interface RadioListContextValue {
value: string;
onChange: (value: string) => void;
isDisabled: boolean;
+ /**
+ * True when the whole group is disabled *and* a `disabledMessage` is set. In
+ * that mode radios stay focusable via `aria-disabled` (instead of the native
+ * `disabled` attribute) so the disabled-reason tooltip is keyboard- and
+ * AT-discoverable; selection is still blocked in the item's onChange guard.
+ */
+ hasDisabledMessage: boolean;
isRequired: boolean;
size: RadioListSize;
status?: InputStatus;
@@ -103,6 +111,17 @@ export interface RadioListProps extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Explains why the radio group is disabled. Applies to the whole-group
+ * disabled state (`isDisabled`), not individual items. When set together with
+ * `isDisabled`, the group shows a tooltip with this text on hover and keyboard
+ * focus, and its radios stay focusable (via `aria-disabled`) so the reason is
+ * discoverable by keyboard and assistive technology. Selection stays blocked.
+ *
+ * Use this instead of wrapping a disabled group in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ */
+ disabledMessage?: string;
/**
* Whether the radio group is required.
* @default false
@@ -169,6 +188,7 @@ export function RadioList({
onChange,
orientation = 'vertical',
isDisabled = false,
+ disabledMessage,
isRequired = false,
isOptional = false,
size = 'md',
@@ -189,9 +209,41 @@ export function RadioList({
const groupRef = useRef<HTMLDivElement>(null);
+ // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+ // controls swallow pointer events, so the tooltip listeners attach to the
+ // radiogroup container and the radios stay perceivable via aria-disabled
+ // instead of the disabled attribute. Selection is blocked in the item's
+ // onChange guard.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The radiogroup container is not naturally focusable; focusin bubbles up
+ // from the radios, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
const contextValue = useMemo<RadioListContextValue>(
- () => ({name, value, onChange, isDisabled, isRequired, size, status}),
- [name, value, onChange, isDisabled, isRequired, size, status],
+ () => ({
+ name,
+ value,
+ onChange,
+ isDisabled,
+ hasDisabledMessage: showsDisabledMessage,
+ isRequired,
+ size,
+ status,
+ }),
+ [
+ name,
+ value,
+ onChange,
+ isDisabled,
+ showsDisabledMessage,
+ isRequired,
+ size,
+ status,
+ ],
);
/**
@@ -306,7 +358,13 @@ export function RadioList({
className={className}
style={style}>
<div
- ref={groupRef}
+ ref={el => {
+ groupRef.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);
+ }}
role="radiogroup"
aria-labelledby={labelID}
onFocus={handleFocus}
@@ -314,6 +372,7 @@ export function RadioList({
[
description ? descriptionID : null,
status?.message ? statusMessageID : null,
+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
.join(' ') || undefined
@@ -329,6 +388,8 @@ export function RadioList({
)}>
<RadioListContext value={contextValue}>{children}</RadioListContext>
</div>
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
diff --git a/packages/core/src/RadioList/RadioListItem.tsx b/packages/core/src/RadioList/RadioListItem.tsx
index 1bf53f2bb4..c435851912 100644
--- a/packages/core/src/RadioList/RadioListItem.tsx
+++ b/packages/core/src/RadioList/RadioListItem.tsx
@@ -230,6 +230,12 @@ export function RadioListItem({
const id = useId();
const descriptionID = useId();
const isDisabled = context.isDisabled || isItemDisabled;
+ // When the whole group is disabled with a disabledMessage, radios stay
+ // focusable via aria-disabled (instead of native `disabled`) so the group's
+ // reason tooltip is keyboard-discoverable. Per-item disabling is unaffected
+ // and always uses the native disabled attribute.
+ const keepsFocusableForMessage =
+ context.hasDisabledMessage && !isItemDisabled;
const isChecked = context.value === value;
const size = context.size;
@@ -246,9 +252,15 @@ export function RadioListItem({
name={context.name}
value={value}
checked={isChecked}
- disabled={isDisabled}
+ disabled={isDisabled && !keepsFocusableForMessage}
+ aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
required={context.isRequired}
- onChange={() => context.onChange(value)}
+ onChange={() => {
+ if (isDisabled) {
+ return;
+ }
+ context.onChange(value);
+ }}
aria-describedby={description ? descriptionID : undefined}
{...stylex.props(
styles.input,
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index fe6a5e715c..56897fc2b2 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -65,6 +65,12 @@ export const docs = {
description: 'Whether the entire control is disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'children',
type: 'ReactNode',
@@ -97,6 +103,7 @@ export const docs = {
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
{guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
{guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
};
@@ -111,6 +118,7 @@ export const docsZh = {
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
{guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
{guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
};
@@ -125,6 +133,7 @@ export const docsDense = {
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
{guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
{guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.test.tsx b/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
index e8d5055fd0..ef92f2b6c0 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
+++ b/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
@@ -9,12 +9,39 @@
* SYNC: When SegmentedControl components change, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} 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 {SegmentedControl} from './SegmentedControl';
import {SegmentedControlItem} from './SegmentedControlItem';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('SegmentedControl', () => {
it('renders a radiogroup with radio buttons', () => {
render(
@@ -459,4 +486,105 @@ describe('SegmentedControl disabled state', () => {
expect(handleChange).toHaveBeenCalledWith('table');
expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function renderControl(props?: {onChange?: (v: string) => void}) {
+ return render(
+ <SegmentedControl
+ value="grid"
+ onChange={props?.onChange ?? (() => {})}
+ label="View mode"
+ isDisabled
+ disabledMessage="Choose a project to switch views">
+ <SegmentedControlItem value="grid" label="Grid" />
+ <SegmentedControlItem value="list" label="List" />
+ </SegmentedControl>,
+ );
+ }
+
+ it('shows the reason tooltip on hover when the control is disabled with a reason', async () => {
+ renderControl();
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent('Choose a project to switch views');
+ const group = screen.getByRole('radiogroup');
+ fireEvent.mouseEnter(group);
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(group);
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ renderControl();
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <SegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ disabledMessage="Choose a project to switch views">
+ <SegmentedControlItem value="grid" label="Grid" />
+ </SegmentedControl>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <SegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ isDisabled>
+ <SegmentedControlItem value="grid" label="Grid" />
+ </SegmentedControl>,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the selected segment focusable when a reason is provided', () => {
+ renderControl();
+ const selected = screen.getByRole('radio', {name: 'Grid', hidden: true});
+ expect(selected).toHaveAttribute('aria-disabled', 'true');
+ expect(selected).toHaveAttribute('tabindex', '0');
+ });
+
+ it('links the reason tooltip from the group via aria-describedby', () => {
+ renderControl();
+ const group = screen.getByRole('radiogroup');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks selection while focusable-disabled', () => {
+ const onChange = vi.fn();
+ renderControl({onChange});
+ const list = screen.getByRole('radio', {name: 'List', hidden: true});
+ fireEvent.click(list);
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('drops all segments from the tab order when disabled without a reason', () => {
+ render(
+ <SegmentedControl
+ value="grid"
+ onChange={() => {}}
+ label="View mode"
+ isDisabled>
+ <SegmentedControlItem value="grid" label="Grid" />
+ <SegmentedControlItem value="list" label="List" />
+ </SegmentedControl>,
+ );
+ for (const radio of screen.getAllByRole('radio', h)) {
+ expect(radio).toHaveAttribute('tabindex', '-1');
+ }
+ });
+ });
});
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.tsx b/packages/core/src/SegmentedControl/SegmentedControl.tsx
index ba5044dba4..075b331236 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.tsx
+++ b/packages/core/src/SegmentedControl/SegmentedControl.tsx
@@ -21,6 +21,7 @@ import {colorVars, spacingVars, radiusVars} from '../theme/tokens.stylex';
import {SegmentedControlContext} from './SegmentedControlContext';
import {useListFocus} from '../hooks/useListFocus';
import {useKeyboardHint} from '../hooks/useKeyboardHint';
+import {useTooltip} from '../Tooltip';
import type {
SegmentedControlSize,
SegmentedControlLayout,
@@ -64,6 +65,17 @@ export interface SegmentedControlProps extends Omit<
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Explains why the control is disabled. Applies to the whole-group disabled
+ * state (`isDisabled`), not individual segments. When set together with
+ * `isDisabled`, the control shows a tooltip with this text on hover and
+ * keyboard focus, and stays focusable (via `aria-disabled`) so the reason is
+ * discoverable by keyboard and assistive technology. Selection stays blocked.
+ *
+ * Use this instead of wrapping a disabled control in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ */
+ disabledMessage?: string;
/**
* SegmentedControlItem children.
*/
@@ -91,6 +103,12 @@ const styles = stylex.create({
opacity: 0.5,
pointerEvents: 'none',
},
+ // Disabled *with* a disabledMessage: keep the dimmed look but leave pointer
+ // events on so the group can receive hover and surface the reason tooltip.
+ // Selection is still blocked by the isDisabled guards.
+ disabledWithMessage: {
+ opacity: 0.5,
+ },
});
const sizeStyles = stylex.create({
@@ -129,6 +147,7 @@ export function SegmentedControl({
size: sizeProp,
layout = 'hug',
isDisabled = false,
+ disabledMessage,
children,
xstyle,
className,
@@ -136,6 +155,20 @@ export function SegmentedControl({
}: SegmentedControlProps) {
const size = useSize(sizeProp, 'md');
+ // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+ // controls swallow pointer events, so the tooltip listeners attach to the
+ // radiogroup container (and the container keeps pointer events on in this
+ // mode) while the radios stay perceivable via aria-disabled. Selection is
+ // blocked by the isDisabled guards in the click/focus handlers.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The radiogroup container is not naturally focusable; focusin bubbles up
+ // from the radios, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
// Roving tabindex + arrow/Home/End navigation is owned by the shared
// useListFocus primitive: it stamps a single tab stop (tabIndex 0/-1) across
// the radios, skips disabled ones, wraps at the ends, handles Home/End, and
@@ -190,17 +223,27 @@ export function SegmentedControl({
);
const contextValue = useMemo(
- () => ({value, onChange, size, layout, isDisabled}),
- [value, onChange, size, layout, isDisabled],
+ () => ({
+ value,
+ onChange,
+ size,
+ layout,
+ isDisabled,
+ hasDisabledMessage: showsDisabledMessage,
+ }),
+ [value, onChange, size, layout, isDisabled, showsDisabledMessage],
);
return (
<SegmentedControlContext value={contextValue}>
<div
- ref={mergeRefs(ref, listRef)}
+ ref={mergeRefs(ref, listRef, disabledMessageTooltip.ref)}
role="radiogroup"
aria-label={label}
aria-disabled={isDisabled || undefined}
+ aria-describedby={
+ showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
+ }
onKeyDown={handleContainerKeyDown}
onFocus={handleContainerFocus}
onBlur={hint.onBlur}
@@ -210,7 +253,10 @@ export function SegmentedControl({
styles.container,
sizeStyles[size],
layout === 'fill' && styles.fill,
- isDisabled && styles.disabled,
+ isDisabled &&
+ (showsDisabledMessage
+ ? styles.disabledWithMessage
+ : styles.disabled),
xstyle,
),
className,
@@ -219,6 +265,8 @@ export function SegmentedControl({
{children}
{hint.hintElement}
</div>
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</SegmentedControlContext>
);
}
diff --git a/packages/core/src/SegmentedControl/SegmentedControlContext.ts b/packages/core/src/SegmentedControl/SegmentedControlContext.ts
index 36d4d0eb5b..b5b6f45acc 100644
--- a/packages/core/src/SegmentedControl/SegmentedControlContext.ts
+++ b/packages/core/src/SegmentedControl/SegmentedControlContext.ts
@@ -22,6 +22,13 @@ export interface SegmentedControlContextValue {
size: SegmentedControlSize;
layout: SegmentedControlLayout;
isDisabled: boolean;
+ /**
+ * True when the whole control is disabled *and* a `disabledMessage` is set.
+ * In that mode the selected segment stays focusable (via `aria-disabled`
+ * rather than being dropped from the tab order) so the group's disabled-reason
+ * tooltip is keyboard-discoverable; selection is still blocked.
+ */
+ hasDisabledMessage?: boolean;
}
export const SegmentedControlContext =
diff --git a/packages/core/src/SegmentedControl/SegmentedControlItem.tsx b/packages/core/src/SegmentedControl/SegmentedControlItem.tsx
index c0bf17b371..d87f1c8d6e 100644
--- a/packages/core/src/SegmentedControl/SegmentedControlItem.tsx
+++ b/packages/core/src/SegmentedControl/SegmentedControlItem.tsx
@@ -173,6 +173,12 @@ export function SegmentedControlItem({
const isSelected = ctx.value === value;
const isItemDisabled = isDisabled || ctx.isDisabled;
+ // When the whole group is disabled with a disabledMessage, keep the selected
+ // segment focusable so the group's reason tooltip is keyboard-discoverable.
+ // Per-item disabling (`isDisabled` on the item) always drops out of the tab
+ // order. Activation stays blocked by the isItemDisabled guard in handleClick.
+ const keepsSelectedFocusable =
+ isSelected && (ctx.hasDisabledMessage ?? false) && !isDisabled;
const size: SegmentedControlSize = ctx.size;
const isFill = ctx.layout === 'fill';
@@ -197,8 +203,12 @@ export function SegmentedControlItem({
data-value={value}
// Disabled items (including when the whole group is disabled) are not tab
// stops — otherwise the selected segment stays keyboard-focusable but is
- // silently dead (arrows and activation are no-ops) (navigation-13).
- tabIndex={isSelected && !isItemDisabled ? 0 : -1}
+ // silently dead (arrows and activation are no-ops) (navigation-13). The
+ // exception is a whole-group disabledMessage, where the selected segment
+ // stays focusable so the reason tooltip is keyboard-discoverable.
+ tabIndex={
+ (isSelected && !isItemDisabled) || keepsSelectedFocusable ? 0 : -1
+ }
onClick={handleClick}
{...mergeProps(
themeProps('segmented-control-item', {
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index ef39ecbbcc..7f2aad08f2 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -95,6 +95,12 @@ export const docs = {
description: 'Whether the slider is disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isOptional',
type: 'boolean',
@@ -151,6 +157,7 @@ export const docs = {
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
{guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
{guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
};
@@ -237,6 +244,12 @@ export const docsZh = {
description: '是否禁用滑块。',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isOptional',
type: 'boolean',
@@ -293,6 +306,7 @@ export const docsZh = {
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
{guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
{guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
};
@@ -307,6 +321,7 @@ export const docsDense = {
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
{guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
{guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Slider/Slider.test.tsx b/packages/core/src/Slider/Slider.test.tsx
index fa3aa5a7e6..5328f3f967 100644
--- a/packages/core/src/Slider/Slider.test.tsx
+++ b/packages/core/src/Slider/Slider.test.tsx
@@ -9,11 +9,44 @@
* SYNC: When Slider.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, act, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Slider} from './Slider';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ // jsdom does not derive :focus-visible from keyboard focus for a
+ // div[role="slider"] thumb; treat the focused thumb as focus-visible so the
+ // disabled-reason tooltip's keyboard-focus path can be exercised.
+ if (selector === ':focus-visible') {
+ return this === document.activeElement;
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('Slider', () => {
// --- Aria labels ---
@@ -382,4 +415,124 @@ describe('Slider', () => {
await user.keyboard('{ArrowLeft}');
expect(handleChange).toHaveBeenCalledWith(0);
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function getTrack(): HTMLElement {
+ return screen.getByRole('slider').parentElement!;
+ }
+
+ it('shows the reason tooltip on hover when disabled with a reason', async () => {
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ isDisabled
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent(
+ 'Volume is locked while sharing your screen',
+ );
+ fireEvent.mouseEnter(getTrack());
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(getTrack());
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ isDisabled
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ expect(screen.getByRole('slider')).toHaveFocus();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <Slider label="Volume" value={50} valueDisplay="none" isDisabled />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the thumb focusable via aria-disabled when a reason is provided', () => {
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ isDisabled
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ const thumb = screen.getByRole('slider');
+ expect(thumb).toHaveAttribute('aria-disabled', 'true');
+ expect(thumb).toHaveAttribute('tabindex', '0');
+ });
+
+ it('links the reason tooltip via aria-describedby', () => {
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ isDisabled
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ const thumb = screen.getByRole('slider');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(thumb.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks value changes while focusable-disabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Slider
+ label="Volume"
+ value={50}
+ valueDisplay="none"
+ onChange={onChange}
+ isDisabled
+ disabledMessage="Volume is locked while sharing your screen"
+ />,
+ );
+ const thumb = screen.getByRole('slider');
+ thumb.focus();
+ await user.keyboard('{ArrowRight}');
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('remains non-focusable when disabled without a reason', () => {
+ render(
+ <Slider label="Volume" value={50} valueDisplay="none" isDisabled />,
+ );
+ expect(screen.getByRole('slider')).toHaveAttribute('tabindex', '-1');
+ });
+ });
});
diff --git a/packages/core/src/Slider/Slider.tsx b/packages/core/src/Slider/Slider.tsx
index 9868666753..7fbf67d8d3 100644
--- a/packages/core/src/Slider/Slider.tsx
+++ b/packages/core/src/Slider/Slider.tsx
@@ -4,7 +4,7 @@
/**
* @file Slider.tsx
- * @input Uses React, useId, useRef, useCallback, Field, Tooltip
+ * @input Uses React, useId, useRef, useCallback, Field, Tooltip, useTooltip
* @output Exports Slider component, SliderProps, SliderSingleProps, SliderRangeProps, SliderBaseProps
* @position Core implementation; consumed by index.ts, tested by Slider.test.tsx
*
@@ -37,6 +37,7 @@ import {
} from '../theme/tokens.stylex';
import {Field} from '../Field/Field';
import {Tooltip} from '../Tooltip/Tooltip';
+import {useTooltip} from '../Tooltip';
import type {InputStatus} from '../Field/types';
import {mergeProps, mergeRefs} from '../utils';
import type {BaseProps} from '../BaseProps';
@@ -61,6 +62,27 @@ export interface SliderBaseProps extends Omit<
description?: string;
/** Whether the slider is disabled. @default false */
isDisabled?: boolean;
+ /**
+ * Explains why the slider is disabled. When set together with `isDisabled`,
+ * the slider shows a tooltip with this text on hover and keyboard focus, and
+ * the thumb stays focusable (via `aria-disabled`) so the reason is
+ * discoverable by keyboard and assistive technology. Value changes stay
+ * blocked.
+ *
+ * Use this instead of wrapping a disabled slider in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ *
+ * @example
+ * ```
+ * <Slider
+ * label="Volume"
+ * value={50}
+ * isDisabled
+ * disabledMessage="Volume is locked while sharing your screen"
+ * />
+ * ```
+ */
+ disabledMessage?: string;
/** Whether the field is optional. @default false */
isOptional?: boolean;
/** Whether the field is required. @default false */
@@ -331,6 +353,7 @@ export function Slider({ref, ...props}: SliderProps) {
isLabelHidden = false,
description,
isDisabled = false,
+ disabledMessage,
isOptional = false,
isRequired = false,
status,
@@ -368,6 +391,20 @@ export function Slider({ref, ...props}: SliderProps) {
const draggingThumbRef = useRef<number | null>(null);
const [draggingThumb, setDraggingThumb] = useState<number | null>(null);
+ // Disabled-reason tooltip. This is a *separate* useTooltip instance from the
+ // per-thumb value bubble (the `<Tooltip>` component below): it anchors to the
+ // track container and fires on hover/focus of the whole control. Disabled
+ // controls swallow pointer events, so the thumb stays perceivable via
+ // aria-disabled while pointer/keyboard handlers early-return on isDisabled.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The track container is not naturally focusable; focusin bubbles up from
+ // the thumb, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
// Build aria-describedby
const describedByParts: string[] = [];
if (description) {
@@ -376,6 +413,9 @@ export function Slider({ref, ...props}: SliderProps) {
if (status?.message) {
describedByParts.push(statusMessageID);
}
+ if (showsDisabledMessage) {
+ describedByParts.push(disabledMessageTooltip.describedBy);
+ }
const ariaDescribedBy =
describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
@@ -641,7 +681,10 @@ export function Slider({ref, ...props}: SliderProps) {
: `${label}, maximum value`
: label;
- const useTooltip = valueDisplay === 'tooltip';
+ // Suppress the per-thumb value bubble while the disabled-message tooltip is
+ // showing, so a disabled slider surfaces the *reason* on hover/focus rather
+ // than stacking two tooltips over the same thumb.
+ const useValueTooltip = valueDisplay === 'tooltip' && !showsDisabledMessage;
const tooltipPlacement = isHorizontal ? 'above' : 'start';
const thumbElement = (
@@ -649,7 +692,10 @@ export function Slider({ref, ...props}: SliderProps) {
key={thumbIndex}
id={!isRange ? id : undefined}
role="slider"
- tabIndex={isDisabled ? -1 : 0}
+ // With a disabledMessage the thumb keeps focusability so the reason is
+ // focus-discoverable; value changes stay blocked by the isDisabled
+ // guards in the pointer/keyboard handlers.
+ tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
aria-valuemin={min}
aria-valuemax={max}
aria-valuenow={val}
@@ -678,7 +724,7 @@ export function Slider({ref, ...props}: SliderProps) {
/>
);
- if (useTooltip) {
+ if (useValueTooltip) {
return (
<Tooltip
key={thumbIndex}
@@ -758,7 +804,7 @@ export function Slider({ref, ...props}: SliderProps) {
stylex.props(styles.sliderRow),
)}>
<div
- ref={mergeRefs(ref, trackRef)}
+ ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
{...(isRange ? {role: 'group', 'aria-label': label} : undefined)}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
@@ -855,6 +901,8 @@ export function Slider({ref, ...props}: SliderProps) {
{textDisplay}
</div>
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 37d07138fd..ad0823df17 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -62,6 +62,12 @@ export const docs = {
description: 'Whether the switch is disabled.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isOptional',
type: 'boolean',
@@ -133,6 +139,7 @@ export const docs = {
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
{ guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
{ guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+ { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -196,6 +203,12 @@ export const docsZh = {
description: '开关是否被禁用。',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the switch is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the switch focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled Switch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'isOptional',
type: 'boolean',
@@ -267,6 +280,7 @@ export const docsZh = {
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
{ guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
{ guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+ { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
};
@@ -282,6 +296,7 @@ export const docsDense = {
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
{ guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
{ guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
+ { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Switch/Switch.test.tsx b/packages/core/src/Switch/Switch.test.tsx
index a6a8b71651..b42234f156 100644
--- a/packages/core/src/Switch/Switch.test.tsx
+++ b/packages/core/src/Switch/Switch.test.tsx
@@ -9,41 +9,56 @@
* SYNC: When Switch.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} 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 {Switch} from './Switch';
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
describe('Switch', () => {
it('renders with label', () => {
render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- />,
+ <Switch label="Enable notifications" value={false} onChange={() => {}} />,
);
expect(screen.getByLabelText('Enable notifications')).toBeInTheDocument();
});
it('renders as off by default', () => {
render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- />,
+ <Switch label="Enable notifications" value={false} onChange={() => {}} />,
);
expect(screen.getByRole('switch')).not.toBeChecked();
});
it('renders as on when value prop is true', () => {
render(
- <Switch
- label="Enable notifications"
- value={true}
- onChange={() => {}}
- />,
+ <Switch label="Enable notifications" value={true} onChange={() => {}} />,
);
expect(screen.getByRole('switch')).toBeChecked();
});
@@ -184,11 +199,7 @@ describe('Switch', () => {
it('shows label visually by default', () => {
render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- />,
+ <Switch label="Enable notifications" value={false} onChange={() => {}} />,
);
const label = screen.getByText('Enable notifications');
expect(label).toBeVisible();
@@ -230,11 +241,7 @@ describe('Switch', () => {
it('has role="switch" for accessibility', () => {
render(
- <Switch
- label="Enable notifications"
- value={false}
- onChange={() => {}}
- />,
+ <Switch label="Enable notifications" value={false} onChange={() => {}} />,
);
expect(screen.getByRole('switch')).toBeInTheDocument();
});
@@ -335,4 +342,132 @@ describe('Switch', () => {
expect(screen.getByRole('switch')).toBeRequired();
});
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+
+ function getRow(): HTMLElement {
+ return screen.getByRole('switch', h).closest('div')!.parentElement!;
+ }
+
+ it('shows the reason tooltip on hover when disabled with a reason', async () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent(
+ 'Notifications are turned off org-wide',
+ );
+ fireEvent.mouseEnter(getRow());
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ fireEvent.mouseLeave(getRow());
+ await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ expect(screen.getByRole('switch', h)).toHaveFocus();
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the switch focusable via aria-disabled when a reason is provided', () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ const control = screen.getByRole('switch', h);
+ expect(control).not.toBeDisabled();
+ expect(control).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('links the reason tooltip via aria-describedby', () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ const control = screen.getByRole('switch', h);
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(control.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks toggling while focusable-disabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={onChange}
+ isDisabled
+ disabledMessage="Notifications are turned off org-wide"
+ />,
+ );
+ const control = screen.getByRole('switch', h);
+ await user.click(control);
+ expect(onChange).not.toHaveBeenCalled();
+ expect(control).not.toBeChecked();
+ });
+
+ it('remains natively disabled when disabled without a reason', () => {
+ render(
+ <Switch
+ label="Enable notifications"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.getByRole('switch')).toBeDisabled();
+ });
+ });
});
diff --git a/packages/core/src/Switch/Switch.tsx b/packages/core/src/Switch/Switch.tsx
index d3668055ea..a0b4107c13 100644
--- a/packages/core/src/Switch/Switch.tsx
+++ b/packages/core/src/Switch/Switch.tsx
@@ -4,7 +4,7 @@
/**
* @file Switch.tsx
- * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus
+ * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
* @output Exports Switch component, SwitchProps, SwitchLabelPosition, SwitchLabelSpacing
* @position Core implementation; consumed by index.ts, tested by Switch.test.tsx
*
@@ -39,7 +39,8 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
import type {IconType} from '../Icon';
import type {InputStatus} from '../Field/types';
import {Spinner} from '../Spinner';
-import {mergeProps} from '../utils';
+import {useTooltip} from '../Tooltip';
+import {mergeProps, mergeRefs} from '../utils';
import {switchScope} from './switch.markers.stylex';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
@@ -227,6 +228,27 @@ export interface SwitchProps extends Omit<BaseProps, 'onChange'> {
* @default false
*/
isDisabled?: boolean;
+ /**
+ * Explains why the switch is disabled. When set together with `isDisabled`,
+ * the switch shows a tooltip with this text on hover and keyboard focus, and
+ * the control 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 switch in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ *
+ * @example
+ * ```
+ * <Switch
+ * label="Enable notifications"
+ * value={enabled}
+ * isDisabled
+ * disabledMessage="Notifications are turned off org-wide"
+ * />
+ * ```
+ */
+ disabledMessage?: string;
/**
* Whether the field is optional. Mutually exclusive with isRequired.
* @default false
@@ -312,6 +334,7 @@ export function Switch({
isLoading = false,
value,
isDisabled = false,
+ disabledMessage,
isOptional = false,
isRequired = false,
onFocus,
@@ -337,6 +360,19 @@ export function Switch({
const isOn = optimisticValue === true;
+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+ // tooltip listeners attach to the switch row (which already exists) and the
+ // native checkbox stays perceivable via aria-disabled instead of the disabled
+ // attribute. Toggling is blocked by the isDisabled guard in onChange.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The container row is not naturally focusable; focusin bubbles up from the
+ // native input, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
// Build aria-describedby from description and status message
// Only include descriptionID when the element actually renders
const describedByParts: string[] = [];
@@ -346,21 +382,28 @@ export function Switch({
if (status?.message) {
describedByParts.push(statusMessageID);
}
+ if (showsDisabledMessage) {
+ describedByParts.push(disabledMessageTooltip.describedBy);
+ }
const ariaDescribedBy =
describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
const switchElement = (
<div {...stylex.props(styles.switchWrapper)}>
<input
- ref={ref}
+ ref={mergeRefs(ref, disabledMessageTooltip.positionRef)}
id={id}
type="checkbox"
role="switch"
checked={isOn}
- disabled={isDisabled}
+ // With a disabledMessage the switch keeps focusability via aria-disabled
+ // so the reason is focus-discoverable; toggling is still blocked by the
+ // isDisabled guard in onChange below.
+ disabled={isDisabled && !showsDisabledMessage}
+ aria-disabled={showsDisabledMessage ? 'true' : undefined}
required={isRequired}
onChange={e => {
- if (isBusy) {
+ if (isDisabled || isBusy) {
return;
}
const checked = e.target.checked;
@@ -439,6 +482,15 @@ export function Switch({
style,
)}>
<div
+ ref={el => {
+ // Interaction (hover/focus) listeners for the disabled-message
+ // tooltip attach to the whole row for a larger trigger target;
+ // positioning anchors on the switch itself (above) so the tooltip
+ // appears next to the control, not the far edge of the row.
+ // Handlers are gated internally by isEnabled, so attaching
+ // unconditionally is safe.
+ disabledMessageTooltip.interactionRef(el);
+ }}
{...stylex.props(
styles.container,
labelSpacing === 'spread' && styles.containerSpread,
@@ -467,6 +519,8 @@ export function Switch({
/>
</div>
)}
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</div>
);
}
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index de62e14fe2..8be1211885 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -70,6 +70,12 @@ export const docs = {
description: 'Disables the input and all token interactions.',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'status',
type: 'InputStatus',
@@ -191,6 +197,7 @@ export const docs = {
{guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
{guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
{guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+ {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
@@ -270,6 +277,12 @@ export const docsZh = {
description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',
default: 'false',
},
+ {
+ name: 'disabledMessage',
+ type: 'string',
+ description:
+ 'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+ },
{
name: 'status',
type: 'InputStatus',
@@ -380,6 +393,7 @@ export const docsZh = {
{guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
{guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
{guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+ {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
@@ -406,6 +420,7 @@ export const docsDense = {
{guidance: false, description: 'Don\u2019t use for single-item selection \u2014 use Typeahead instead.'},
{guidance: false, description: 'Avoid custom token colors \u2014 default style for consistency.'},
{guidance: false, description: 'Don\u2019t hide the label unless context makes purpose obvious.'},
+ {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Tokenizer/Tokenizer.test.tsx b/packages/core/src/Tokenizer/Tokenizer.test.tsx
index bb8e6e99bf..100176a12f 100644
--- a/packages/core/src/Tokenizer/Tokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Tokenizer} from './Tokenizer';
import type {SearchSource, SearchableItem} from '../Typeahead/types';
@@ -763,4 +763,108 @@ describe('Tokenizer', () => {
expect(screen.getByText('Create "NewTag"')).toBeInTheDocument();
});
});
+
+ describe('disabledMessage', () => {
+ const h = {hidden: true} as const;
+ const isOpen = (el: Element) => el.matches(':popover-open');
+
+ function renderTokenizer(props?: {onChange?: () => void}) {
+ return render(
+ <Tokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[]}
+ onChange={props?.onChange ?? (() => {})}
+ isDisabled
+ disabledMessage="You need edit access to change members"
+ />,
+ );
+ }
+
+ it('shows the reason tooltip on hover when disabled with a reason', async () => {
+ renderTokenizer();
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent(
+ 'You need edit access to change members',
+ );
+ const wrapper = screen.getByRole('group', {name: 'Members'});
+ fireEvent.mouseEnter(wrapper);
+ await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+ fireEvent.mouseLeave(wrapper);
+ await waitFor(() => expect(isOpen(tooltip)).toBe(false));
+ });
+
+ it('shows the reason tooltip on keyboard focus', async () => {
+ const user = userEvent.setup();
+ renderTokenizer();
+ const tooltip = screen.getByRole('tooltip', h);
+ await user.tab();
+ expect(screen.getByRole('combobox')).toHaveFocus();
+ await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+ });
+
+ it('does not render a tooltip when not disabled', () => {
+ render(
+ <Tokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[]}
+ onChange={() => {}}
+ disabledMessage="You need edit access to change members"
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('does not render a tooltip when disabled without a reason', () => {
+ render(
+ <Tokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[]}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+ });
+
+ it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+ renderTokenizer();
+ const input = screen.getByRole('combobox');
+ expect(input).not.toBeDisabled();
+ expect(input).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('links the reason tooltip via aria-describedby', () => {
+ renderTokenizer();
+ const input = screen.getByRole('combobox');
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('blocks input while focusable-disabled', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ renderTokenizer({onChange});
+ const input = screen.getByRole('combobox');
+ input.focus();
+ await user.keyboard('Ali');
+ expect((input as HTMLInputElement).value).toBe('');
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('keeps the input natively disabled when disabled without a reason', () => {
+ render(
+ <Tokenizer
+ label="Members"
+ searchSource={userSource}
+ value={[]}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.getByRole('combobox')).toBeDisabled();
+ });
+ });
});
diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsx
index 335e158c0b..fde87ebb5b 100644
--- a/packages/core/src/Tokenizer/Tokenizer.tsx
+++ b/packages/core/src/Tokenizer/Tokenizer.tsx
@@ -42,6 +42,7 @@ import {Token} from '../Token';
import {renderIconSlot, type IconType} from '../Icon';
import {OverflowList} from '../OverflowList';
import {useLayer} from '../Layer/useLayer';
+import {useTooltip} from '../Tooltip';
import {
colorVars,
spacingVars,
@@ -145,6 +146,17 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
emptySearchResultsText?: string;
/** Whether the input is disabled. @default false */
isDisabled?: boolean;
+ /**
+ * Explains why the tokenizer is disabled. When set together with
+ * `isDisabled`, the tokenizer shows a tooltip with this text on hover and
+ * keyboard focus, and the input stays focusable (via `aria-disabled`) so the
+ * reason is discoverable by keyboard and assistive technology. Input stays
+ * blocked.
+ *
+ * Use this instead of wrapping a disabled tokenizer in `Tooltip` — disabled
+ * controls don't emit the pointer events an external tooltip needs.
+ */
+ disabledMessage?: string;
/** Show clear button (clears all tokens). @default false */
hasClear?: boolean;
/**
@@ -365,6 +377,7 @@ export function Tokenizer<T extends SearchableItem>({
maxMenuItems,
emptySearchResultsText,
isDisabled = false,
+ disabledMessage,
hasClear = false,
endContent,
hasAutoFocus,
@@ -390,6 +403,19 @@ export function Tokenizer<T extends SearchableItem>({
const inputRef = useRef<HTMLInputElement>(null);
const wrapperRef = useRef<HTMLDivElement>(null);
+ // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+ // tooltip listeners attach to the input wrapper and the typeahead input stays
+ // perceivable via aria-disabled instead of the disabled attribute. Input is
+ // blocked by the isDisabled guards in BaseTypeahead and handleWrapperClick.
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ // The wrapper is not naturally focusable; focusin bubbles up from the
+ // input, so always attach focus listeners.
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+
useImperativeHandle(handleRef, () => ({
focus() {
inputRef.current?.focus();
@@ -620,6 +646,7 @@ export function Tokenizer<T extends SearchableItem>({
[
description ? descriptionId : null,
status?.message ? statusMessageId : null,
+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
.join(' ') || undefined;
@@ -659,7 +686,13 @@ export function Tokenizer<T extends SearchableItem>({
const wrapperContent = (
<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);
+ }}
role="group"
aria-label={label}
onClick={handleWrapperClick}
@@ -710,6 +743,7 @@ export function Tokenizer<T extends SearchableItem>({
maxMenuItems={maxMenuItems}
emptySearchResultsText={emptySearchResultsText}
isDisabled={isDisabled}
+ isFocusableDisabled={showsDisabledMessage}
hasAutoFocus={hasAutoFocus}
inputId={inputId}
ariaDescribedBy={ariaDescribedBy}
@@ -831,6 +865,8 @@ export function Tokenizer<T extends SearchableItem>({
className={className}
style={style}>
{tokenizerContent}
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}