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.mdnew file mode 100644index 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)+@cixzhangdiff --git a/apps/storybook/stories/CheckboxInput.stories.tsx b/apps/storybook/stories/CheckboxInput.stories.tsxindex 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} /><CheckboxInputlabel="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.tsxindex 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.tsxindex 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.tsxindex 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>} /><RadioListItemlabel="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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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}hasEntriesOnFocusdiff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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-describedbyconst 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 (<Tooltipkey={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.mjsindex 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.tsxindex 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.tsxindex 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 rendersconst 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.mjsindex 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.tsxindex 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.tsxindex 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>);}