Skip to content

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

TypeScript

feat(selectors)!: FR10 prop targets for Selector, MultiSelector, ComplexSelector (#7341)

Cindy Zhang5777977fea4a
diff --git a/.changeset/field-input-styling-selectors.md b/.changeset/field-input-styling-selectors.md
new file mode 100644
index 0000000000..87ade21b40
--- /dev/null
+++ b/.changeset/field-input-styling-selectors.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/core': minor
+'@astryxdesign/cli': minor
+---
+
+[breaking] Selector, MultiSelector, and ComplexSelector no longer accept root `xstyle`, `className`, or `style`. Style the field with `containerXstyle`/`containerClassName`/`containerStyle` (the Field box; no effect inside InputGroup, a `horizontal-labels` FormLayout, or with `renderTrigger`) and the visual control box with `controlXstyle`/`controlClassName`/`controlStyle`. Base props such as `ref`, `id`, `data-*` (including `data-testid`), `aria-*`, and DOM handlers reach the trigger button that carries the combobox role (or, with `renderTrigger`, the caller's control), and a caller `aria-describedby` is kept alongside the field's own description and status instead of being replaced. Handlers keep their existing order: a ComplexSelector `onClick` on its own trigger can still cancel opening, and newly forwarded handlers (including those reaching a `renderTrigger` control) run after the built-in toggle and keyboard handling. CLI templates use the new props.
+
+Migration: rename root `xstyle`/`className`/`style` on these components to `controlXstyle`/`controlClassName`/`controlStyle`, which style the same element as before. Not a rename: a `data-testid` or other base prop now lands on the trigger button rather than the bordered box around it (query the box with `.closest()` if a test measured it), and with `renderTrigger` base props and `ref` now reach the caller's control. Rename JSX usage by hand, or with `astryx upgrade` once its `migrate-field-input-styling` transform is available; that transform does not follow styling passed through a wrapper's own props or a spread, which now fails type-checking at that callsite, so rename it there. Untyped callers get a development warning and the value is ignored.
+
+From #5656 by @harjothkhara.
+
+@cixzhang
diff --git a/apps/docsite/src/app/playground/propertyEditor/PropertyEditor.tsx b/apps/docsite/src/app/playground/propertyEditor/PropertyEditor.tsx
index bb91b22698..a843e904d1 100644
--- a/apps/docsite/src/app/playground/propertyEditor/PropertyEditor.tsx
+++ b/apps/docsite/src/app/playground/propertyEditor/PropertyEditor.tsx
@@ -206,7 +206,7 @@ function PropRow({prop, instance, code, onCodeChange}: PropRowProps) {
value={value}
options={control.options}
onChange={next => commit('enum', coerceEnumOption(control, next))}
- xstyle={s.inputControl}
+ controlXstyle={s.inputControl}
/>
);
} else if (control.kind === 'string') {
diff --git a/apps/docsite/src/app/playground/themeEditor/BaseStylesPanel.tsx b/apps/docsite/src/app/playground/themeEditor/BaseStylesPanel.tsx
index ce40702a4e..080d51bc18 100644
--- a/apps/docsite/src/app/playground/themeEditor/BaseStylesPanel.tsx
+++ b/apps/docsite/src/app/playground/themeEditor/BaseStylesPanel.tsx
@@ -419,7 +419,7 @@ export function BaseStylesPanel({
isLabelHidden
size="sm"
placeholder="Custom"
- xstyle={styles.fullWidthField}
+ controlXstyle={styles.fullWidthField}
options={FONT_OPTIONS}
value={fontValue(token)}
onChange={(val: string) => onTokenChange(token, val)}
@@ -432,7 +432,7 @@ export function BaseStylesPanel({
isLabelHidden
size="sm"
placeholder="Default"
- xstyle={styles.fullWidthField}
+ controlXstyle={styles.fullWidthField}
options={[
...RATIO_OPTIONS.map(opt => ({
value: String(opt.value),
diff --git a/apps/docsite/src/app/playground/themeEditor/ComponentTokensPanel.tsx b/apps/docsite/src/app/playground/themeEditor/ComponentTokensPanel.tsx
index 54fa076707..47071d6b4e 100644
--- a/apps/docsite/src/app/playground/themeEditor/ComponentTokensPanel.tsx
+++ b/apps/docsite/src/app/playground/themeEditor/ComponentTokensPanel.tsx
@@ -189,7 +189,7 @@ export function ComponentTokensPanel({
label={v.name}
isLabelHidden
size="sm"
- xstyle={styles.fullWidthField}
+ controlXstyle={styles.fullWidthField}
options={[
...v.options.map(o => ({
value: o.value,
diff --git a/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
index 8c03fa6a42..0632905d4d 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
@@ -909,7 +909,7 @@ export default function ComponentScoresPage() {
hasClear
variant="ghost"
size="sm"
- xstyle={styles.filterToken}
+ controlXstyle={styles.filterToken}
/>
<Selector
label="Package"
@@ -923,7 +923,7 @@ export default function ComponentScoresPage() {
hasClear
variant="ghost"
size="sm"
- xstyle={styles.filterToken}
+ controlXstyle={styles.filterToken}
/>
<Text type="supporting" color="secondary">
{visible.length}{' '}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/mobile-type/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/mobile-type/page.tsx
index 724bcd58d2..594fe9d076 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/mobile-type/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/mobile-type/page.tsx
@@ -485,7 +485,7 @@ export default function MobileTypePage() {
isLabelHidden
size="sm"
placeholder="Select ratio"
- xstyle={styles.fullWidth}
+ controlXstyle={styles.fullWidth}
options={RATIO_OPTIONS}
value={ratio}
onChange={(v: string) => setRatio(v)}
@@ -542,7 +542,7 @@ export default function MobileTypePage() {
label="Pin anchor"
isLabelHidden
size="sm"
- xstyle={styles.fullWidth}
+ controlXstyle={styles.fullWidth}
options={PIN_ANCHORS}
value={String(pinStep)}
onChange={(v: string) => setPinStep(Number(v))}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-examples/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-examples/page.tsx
index a30a6efcfb..b5bd120153 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-examples/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-examples/page.tsx
@@ -365,7 +365,7 @@ function MicroInteractionsCard() {
options={['Apple', 'Banana', 'Orange', 'Mango']}
value={selectorValue}
onChange={setSelectorValue}
- xstyle={styles.maxW220}
+ controlXstyle={styles.maxW220}
/>
</VStack>
</VStack>
diff --git a/apps/sandbox/src/app/(sandbox)/templates/page.tsx b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
index daa752ac65..2dc8480631 100644
--- a/apps/sandbox/src/app/(sandbox)/templates/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
@@ -865,7 +865,7 @@ export default function TemplatesPage() {
)
}
options={TEMPLATE_AUDIT_FILTER_OPTIONS}
- xstyle={styles.filterToken}
+ controlXstyle={styles.filterToken}
/>
<Selector
label="Template type"
@@ -880,7 +880,7 @@ export default function TemplatesPage() {
)
}
options={TEMPLATE_TYPE_FILTER_OPTIONS}
- xstyle={styles.filterToken}
+ controlXstyle={styles.filterToken}
/>
<Text type="supporting" color="secondary">
{visible.length}{' '}
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index 94a4c5e3a9..4632c5d1cf 100644
--- a/apps/storybook/stories/Selector.stories.tsx
+++ b/apps/storybook/stories/Selector.stories.tsx
@@ -783,10 +783,10 @@ export const SizeVariants: Story = {
styles.getPropertyValue(`--size-element-${trigger.dataset.size}`),
);
const height = trigger.getBoundingClientRect().height;
- if (
- trigger.dataset.testid === 'large-text' ||
- trigger.dataset.testid === 'large-custom'
- ) {
+ // `data-testid` lands on the trigger button inside the control box.
+ const testId =
+ trigger.querySelector<HTMLElement>('[data-testid]')?.dataset.testid;
+ if (testId === 'large-text' || testId === 'large-custom') {
// Text larger than the token can hold keeps its whole line box.
const walker = document.createTreeWalker(trigger, NodeFilter.SHOW_TEXT);
let text: Node | null = walker.nextNode();
@@ -814,7 +814,7 @@ export const SizeVariants: Story = {
expect(textBox.top).toBeGreaterThanOrEqual(clip.top - 0.5);
expect(textBox.bottom).toBeLessThanOrEqual(clip.bottom + 0.5);
expect(height).toBeGreaterThan(size);
- } else if (trigger.dataset.testid?.endsWith('-multiline')) {
+ } else if (testId?.endsWith('-multiline')) {
// Two text rows, plus whatever padding remains once the first row
// fills the token (padding never goes below zero).
const row = Number.parseFloat(styles.lineHeight);
diff --git a/apps/storybook/stories/TransferList.stories.tsx b/apps/storybook/stories/TransferList.stories.tsx
index 8386407e89..abbd549b54 100644
--- a/apps/storybook/stories/TransferList.stories.tsx
+++ b/apps/storybook/stories/TransferList.stories.tsx
@@ -655,7 +655,7 @@ function TableColumnSettingsExample() {
onChange={setAppliedColumns}
triggerLabel="View Options"
placement="below"
- xstyle={styles.viewOptionsTrigger}
+ controlXstyle={styles.viewOptionsTrigger}
contentXstyle={styles.viewOptionsContent}>
{(_currentColumns, commit, close, state) => (
<div {...stylex.props(styles.viewOptionsSurface)}>
diff --git a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx
index 15afc5169a..bd6dca9a0b 100644
--- a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx
+++ b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx
@@ -47,7 +47,7 @@ export default function ComplexSelectorDeadlinePicker() {
value={value}
onChange={setValue}
triggerLabel={formatDeadline(value)}
- style={{width: 320}}>
+ controlStyle={{width: 320}}>
{(selectedValue, onChange, close) => {
const set = (patch: Partial<Deadline>) =>
onChange({...selectedValue, ...patch});
diff --git a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx
index f7942882a8..3fac01acbf 100644
--- a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx
+++ b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx
@@ -184,7 +184,7 @@ export default function ComplexSelectorShowcase() {
value={value}
onChange={setValue}
triggerLabel={`${value.fruit} · ${value.ripeness}`}
- style={{width: 280}}>
+ controlStyle={{width: 280}}>
{(selectedValue, onChange, close) => (
<FruitRipenessGrid
value={selectedValue}
diff --git a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx
index f1c493d24d..8a16f0093f 100644
--- a/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx
+++ b/packages/cli/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx
@@ -175,7 +175,7 @@ export default function ComplexSelectorTreeSearch() {
value={value}
onChange={setValue}
triggerLabel={value.path}
- style={{width: 360}}>
+ controlStyle={{width: 360}}>
{(selectedValue, onChange, close) => (
<DestinationSearch
value={selectedValue}
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx
index 2ec6056dc0..53c828d3fd 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx
@@ -29,7 +29,7 @@ export default function InternationalizationProviderShippedLocale() {
<SegmentedControlItem value="fr-FR" label="FR" />
</SegmentedControl>
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Billing region"
options={[
{value: 'americas', label: 'Americas'},
diff --git a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx
index 4eb5fe9901..6decf0fb6d 100644
--- a/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx
+++ b/packages/cli/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider02Overrides.tsx
@@ -17,7 +17,7 @@ export default function InternationalizationProviderOverrides() {
},
}}>
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Billing region"
options={[
{value: 'americas', label: 'Americas'},
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorClearable.tsx b/packages/cli/assets/templates/blocks/components/Selector/SelectorClearable.tsx
index 226a8dc62d..ef2ba913dd 100644
--- a/packages/cli/assets/templates/blocks/components/Selector/SelectorClearable.tsx
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorClearable.tsx
@@ -9,7 +9,7 @@ export default function SelectorClearable() {
const [value, setValue] = useState<string | null>('engineering');
return (
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Department"
options={[
{value: 'engineering', label: 'Engineering'},
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorOptionDescriptions.tsx b/packages/cli/assets/templates/blocks/components/Selector/SelectorOptionDescriptions.tsx
index fa2ca56646..606a1afa2d 100644
--- a/packages/cli/assets/templates/blocks/components/Selector/SelectorOptionDescriptions.tsx
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorOptionDescriptions.tsx
@@ -32,7 +32,7 @@ export default function SelectorOptionDescriptions() {
return (
<Stack direction="vertical" gap={6}>
<Selector
- style={{width: 320}}
+ controlStyle={{width: 320}}
label="Visibility"
description="Default trigger: one line at the size token."
options={VISIBILITY}
@@ -40,7 +40,7 @@ export default function SelectorOptionDescriptions() {
onChange={setCondensed}
/>
<Selector
- style={{width: 320}}
+ controlStyle={{width: 320}}
label="Visibility"
description="A stacked SelectorOption: the description gets its own line, and the trigger grows by exactly one line."
options={VISIBILITY}
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorShowcase.tsx b/packages/cli/assets/templates/blocks/components/Selector/SelectorShowcase.tsx
index 2f550a9f96..976425f99e 100644
--- a/packages/cli/assets/templates/blocks/components/Selector/SelectorShowcase.tsx
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorShowcase.tsx
@@ -9,7 +9,7 @@ export default function SelectorShowcase() {
const [value, setValue] = useState<string | undefined>();
return (
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Fruit"
options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}
placeholder="Select a fruit..."
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorWithSections.tsx b/packages/cli/assets/templates/blocks/components/Selector/SelectorWithSections.tsx
index 3432cf9aaf..a3f97ad410 100644
--- a/packages/cli/assets/templates/blocks/components/Selector/SelectorWithSections.tsx
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorWithSections.tsx
@@ -9,7 +9,7 @@ export default function SelectorWithSections() {
const [value, setValue] = useState<string | undefined>();
return (
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Office"
options={[
{
diff --git a/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx b/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx
index dfed2f030d..6796c305e8 100644
--- a/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx
+++ b/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionBasic.tsx
@@ -22,7 +22,7 @@ export default function SelectorOptionBasic() {
return (
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Role"
options={roles}
value={value}
diff --git a/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx b/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx
index f4cd20e2a9..f881bde1ab 100644
--- a/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx
+++ b/packages/cli/assets/templates/blocks/components/SelectorOption/SelectorOptionShowcase.tsx
@@ -25,7 +25,7 @@ export default function SelectorOptionShowcase() {
return (
<Selector
- style={{width: 300}}
+ controlStyle={{width: 300}}
label="Role"
options={roles}
value={value}
diff --git a/packages/cli/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx b/packages/cli/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx
index 517e3e4de9..e87e03e79f 100644
--- a/packages/cli/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx
+++ b/packages/cli/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx
@@ -231,7 +231,7 @@ export default function ToolbarTableFilter() {
hasClear
options={field.options}
value={clauses[field.key] ?? null}
- xstyle={clauses[field.key] != null ? styles.filterFill : undefined}
+ controlXstyle={clauses[field.key] != null ? styles.filterFill : undefined}
onChange={value => setClauses(prev => ({...prev, [field.key]: value}))}
renderValue={option =>
`${field.label} is ${option.label ?? option.value}`
diff --git a/packages/cli/assets/templates/pages/canvas-editor/page.tsx b/packages/cli/assets/templates/pages/canvas-editor/page.tsx
index aac9b86def..76a4ffb175 100644
--- a/packages/cli/assets/templates/pages/canvas-editor/page.tsx
+++ b/packages/cli/assets/templates/pages/canvas-editor/page.tsx
@@ -2329,7 +2329,7 @@ export default function CanvasEditor() {
// enough for the longest option
// ("100%") to avoid truncation.
width={92}
- xstyle={[
+ controlXstyle={[
styles.toolBarControl,
styles.toolBarTrailing,
]}
diff --git a/packages/cli/assets/templates/pages/table-filter/page.tsx b/packages/cli/assets/templates/pages/table-filter/page.tsx
index 006516449d..da1f7e339d 100644
--- a/packages/cli/assets/templates/pages/table-filter/page.tsx
+++ b/packages/cli/assets/templates/pages/table-filter/page.tsx
@@ -3249,7 +3249,7 @@ export default function TableFilterTemplate() {
renderValue={option =>
`${field.label} ${field.operatorLabel} ${option.label ?? option.value}`
}
- xstyle={active ? styles.filterFill : undefined}
+ controlXstyle={active ? styles.filterFill : undefined}
onChange={next =>
setFieldFilter(
field.key,
@@ -3318,7 +3318,7 @@ export default function TableFilterTemplate() {
}
options={[...field.options]}
value={multiValues[field.key]}
- xstyle={
+ controlXstyle={
multiValues[field.key].length > 0 ? styles.filterFill : undefined
}
onChange={next => setMultiValues(field.key, next)}
@@ -3341,7 +3341,7 @@ export default function TableFilterTemplate() {
value={quoteDraft}
onChange={commitQuote}
contentXstyle={styles.quotePopover}
- xstyle={hasQuoteFilter ? styles.filterFill : undefined}>
+ controlXstyle={hasQuoteFilter ? styles.filterFill : undefined}>
{(range, onChange, close) => (
<VStack gap={4}>
<VStack gap={0}>
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
index 894a1e1aa9..b8faf16a4a 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
+++ b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
@@ -207,6 +207,52 @@ export const docs = {
type: 'StyleXStyles',
description: 'StyleX styles for the popup content container.',
},
+ {
+ name: 'onClick',
+ type: '(event: MouseEvent) => void',
+ description:
+ 'Click handler on the trigger. Runs before the popup opens; call preventDefault() to keep it closed. A press elsewhere in the control box goes through the trigger too. With renderTrigger it runs after the built-in toggle and cannot cancel it.',
+ },
+ {
+ name: 'onKeyDown',
+ type: '(event: KeyboardEvent) => void',
+ description:
+ 'Key handler on the trigger. Runs after the built-in handling and receives every key, including the ArrowDown that opens the popup. With renderTrigger it is skipped for keys the built-in handling cancels.',
+ },
+ {
+ name: 'containerXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.',
+ },
+ {
+ name: 'containerClassName',
+ type: 'string',
+ description:
+ 'Class name for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'containerStyle',
+ type: 'CSSProperties',
+ description:
+ 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the element that paints the border and background and holds the value, icons, and end controls. Never the trigger button itself.',
+ },
+ {
+ name: 'controlClassName',
+ type: 'string',
+ description: 'Class name for the visual control box.',
+ },
+ {
+ name: 'controlStyle',
+ type: 'CSSProperties',
+ description: 'Inline styles for the visual control box.',
+ },
],
},
],
@@ -338,6 +384,18 @@ export const docsDense = {
'Caller-rendered opener replacing the field+button; spread the given props; popup anchored to it, labelled by label.',
handleRef: 'Imperative open/close/toggle handle.',
onOpenChange: 'Notified on every open and close, whatever caused it.',
+ onClick:
+ 'Trigger click; runs before opening, preventDefault() keeps the popup closed.',
+ onKeyDown:
+ 'Trigger keys; runs after built-in handling, sees the opening ArrowDown.',
+ containerXstyle:
+ 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+ containerClassName: 'Class name for the field container.',
+ containerStyle: 'Inline styles for the field container.',
+ controlXstyle:
+ 'StyleX styles for the visual control box (border, background, icons); not the trigger button.',
+ controlClassName: 'Class name for the visual control box.',
+ controlStyle: 'Inline styles for the visual control box.',
statusVariant:
'How status message is placed: attached overlaps below input (detached for ghost); detached floats below w/ spacing; tooltip shows on status icon.',
accessibility:
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.fr10.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.fr10.test.tsx
new file mode 100644
index 0000000000..15520133fe
--- /dev/null
+++ b/packages/core/src/ComplexSelector/ComplexSelector.fr10.test.tsx
@@ -0,0 +1,262 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ComplexSelector.fr10.test.tsx
+ * @input Uses vitest, Testing Library, the shared FR10 suites, and ComplexSelector
+ * @output Tests that ComplexSelector's base props, container*, and control* reach
+ * their family:input-fields FR10 targets
+ * @position Tests; ComplexSelector's FR10 conformance alongside ComplexSelector.test.tsx
+ */
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+import {ComplexSelector, type ComplexSelectorProps} from './ComplexSelector';
+
+const VALUE = 'Apple';
+const content = () => <p>Pick a fruit</p>;
+
+// jsdom has no Popover API; reflect open state the way the browser does.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle');
+ 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');
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+});
+
+describe('ComplexSelector props type (family:input-fields FR10)', () => {
+ it('accepts container* and control* and no root styling', () => {
+ expectFieldInputProps<ComplexSelectorProps<string>>();
+ });
+});
+
+describeFieldInputParts('ComplexSelector', {
+ renderMember: props => (
+ <ComplexSelector label="Fruit" value={VALUE} onChange={() => {}} {...props}>
+ {content}
+ </ComplexSelector>
+ ),
+ getControl: () => screen.getByRole('button', {name: 'Fruit'}),
+ // No shipped InputGroup support (family:input-fields adoption table).
+ inGroup: false,
+});
+
+describe('ComplexSelector FR10 targets', () => {
+ it('keeps a caller aria-describedby alongside the field description', () => {
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ description="Pick one"
+ aria-describedby="caller-help">
+ {content}
+ </ComplexSelector>,
+ );
+ const ids = (
+ screen
+ .getByRole('button', {name: 'Fruit'})
+ .getAttribute('aria-describedby') ?? ''
+ ).split(' ');
+ expect(ids).toContain('caller-help');
+ expect(
+ ids.map(id => document.getElementById(id)?.textContent ?? '').join(' '),
+ ).toContain('Pick one');
+ });
+
+ it('puts control* on the bordered control box around the trigger, not on the trigger or the popup', () => {
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ containerClassName="fr10-container">
+ {content}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Fruit'});
+ const controlBox = document.querySelector('.fr10-control') as HTMLElement;
+ expect(controlBox).toHaveClass('astryx-complex-selector');
+ expect(controlBox).toContainElement(trigger);
+ expect(trigger).not.toHaveClass('fr10-control');
+
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(document.querySelectorAll('.fr10-control')).toHaveLength(1);
+ expect(document.querySelectorAll('.fr10-container')).toHaveLength(1);
+ expect(screen.getByRole('dialog', {hidden: true})).not.toHaveClass(
+ 'fr10-control',
+ );
+ });
+
+ it('lets a caller onClick on the trigger cancel opening, as before', () => {
+ const targets: EventTarget[] = [];
+ const {container} = render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ onClick={event => {
+ targets.push(event.currentTarget);
+ event.preventDefault();
+ }}>
+ {content}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Fruit'});
+ fireEvent.click(trigger);
+ expect(targets).toEqual([trigger]);
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ // A press elsewhere in the control box goes through the trigger too.
+ fireEvent.click(container.querySelector('.fr10-control') as HTMLElement);
+ expect(targets).toEqual([trigger, trigger]);
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('opens once per press when a caller onClick does not cancel', () => {
+ const onClick = vi.fn();
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ onClick={onClick}>
+ {content}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Fruit'});
+ fireEvent.click(trigger);
+ expect(onClick).toHaveBeenCalledTimes(1);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('opens from a press on the control box outside the trigger button', () => {
+ const {container} = render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control">
+ {content}
+ </ComplexSelector>,
+ );
+ const controlBox = container.querySelector('.fr10-control') as HTMLElement;
+ fireEvent.click(controlBox);
+ expect(screen.getByRole('button', {name: 'Fruit'})).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ });
+
+ it('keeps the built-in keyboard model and still hands every key to a caller onKeyDown', () => {
+ const keys: string[] = [];
+ const targets: EventTarget[] = [];
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ onKeyDown={event => {
+ keys.push(event.key);
+ targets.push(event.currentTarget);
+ }}>
+ {content}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Fruit'});
+ fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ // The caller still sees the ArrowDown the trigger used to open the popup.
+ expect(keys).toEqual(['ArrowDown']);
+ expect(targets).toEqual([trigger]);
+ });
+});
+
+describe('ComplexSelector FR10 renderTrigger', () => {
+ it('runs a newly forwarded onClick after the built-in toggle, without cancelling it', () => {
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ onClick={event => event.preventDefault()}
+ renderTrigger={props => (
+ <button type="button" {...props}>
+ Open
+ </button>
+ )}>
+ {content}
+ </ComplexSelector>,
+ );
+ const opener = screen.getByRole('button', {name: 'Open'});
+ fireEvent.click(opener);
+ expect(opener).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('forwards base props and the ref to the caller-rendered control', () => {
+ const ref = {current: null as HTMLElement | null};
+ const onClick = vi.fn();
+ render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ ref={ref}
+ data-testid="opener"
+ aria-details="details-id"
+ onClick={onClick}
+ renderTrigger={props => (
+ <button type="button" {...props}>
+ Open
+ </button>
+ )}>
+ {content}
+ </ComplexSelector>,
+ );
+ const opener = screen.getByRole('button', {name: 'Open'});
+ expect(opener).toHaveAttribute('data-testid', 'opener');
+ expect(opener).toHaveAttribute('aria-details', 'details-id');
+ expect(ref.current).toBe(opener);
+ fireEvent.click(opener);
+ expect(onClick).toHaveBeenCalledTimes(1);
+ expect(opener).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('warns that container* and control* have no effect', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <ComplexSelector
+ label="Fruit"
+ value={VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ renderTrigger={props => (
+ <button type="button" {...props}>
+ Open
+ </button>
+ )}>
+ {content}
+ </ComplexSelector>,
+ );
+ expect(container.querySelector('.fr10-control')).toBeNull();
+ expect(
+ warn.mock.calls.some(call =>
+ String(call[0]).startsWith(
+ 'ComplexSelector: `container*` and `control*`',
+ ),
+ ),
+ ).toBe(true);
+ warn.mockRestore();
+ });
+});
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
index e0138e6dc1..eb03226553 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
@@ -255,7 +255,10 @@ describe('ComplexSelector', () => {
'detached',
);
expect(
- screen.getByTestId('view-options').querySelectorAll('svg'),
+ screen
+ .getByTestId('view-options')
+ .closest('.astryx-complex-selector')
+ ?.querySelectorAll('svg'),
).toHaveLength(2);
});
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsx
index b9b2eb3487..abf4a9040c 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.tsx
+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx
@@ -27,7 +27,14 @@ import React, {
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
-import type {BaseProps} from '../BaseProps';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+ type FieldPartStyleProps,
+} from '../Field/fieldParts';
+import {useDevWarning} from '../hooks/useDevWarning';
+import {mergeRefs} from '../utils/mergeRefs';
+import {useMergedRefs} from '../hooks/useMergedRefs';
import {Field, inputWrapperStyles, type FieldStatusVariant} from '../Field';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {Spinner} from '../Spinner';
@@ -199,14 +206,31 @@ export type ComplexSelectorVariant = 'input' | 'ghost';
export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
+const RENDER_TRIGGER_PARTS_MESSAGE =
+ '`container*` and `control*` styling props have no effect with `renderTrigger`: ' +
+ 'no Field box or control box renders. Style the control you render instead.';
+
/**
* Props the `renderTrigger` render prop hands to the control the caller
* renders.
* Spread them onto that control: it becomes the popup's anchor, the element
* focus returns to, and the control that announces the popup's state.
*/
-export interface ComplexSelectorRenderTriggerProps {
- /** Attaches the control as the popup's anchor and focus-return target. */
+export interface ComplexSelectorRenderTriggerProps extends Omit<
+ FieldInputBaseProps,
+ | keyof FieldPartStyleProps
+ | 'id'
+ | 'onClick'
+ | 'onKeyDown'
+ | 'aria-haspopup'
+ | 'aria-expanded'
+ | 'aria-controls'
+ | 'aria-busy'
+> {
+ /**
+ * Attaches the control as the popup's anchor and focus-return target, and
+ * forwards it to the selector's own `ref`.
+ */
ref: (element: HTMLElement | null) => void;
/** The id the field would have given its own button. */
id: string;
@@ -256,11 +280,31 @@ export interface ComplexSelectorStatus {
}
export interface ComplexSelectorProps<Value> extends Omit<
- BaseProps<HTMLDivElement>,
+ FieldInputBaseProps,
'children' | 'onChange'
> {
/** Label text for accessibility and the field label. */
label: string;
+ /**
+ * Ref to the trigger: the button that opens the popup and carries the
+ * accessible name — or, with `renderTrigger`, the caller's control.
+ */
+ ref?: React.Ref<HTMLElement>;
+ /**
+ * Click handler on the trigger. It runs before the popup opens; call
+ * `preventDefault()` to keep the popup closed. A press elsewhere in the
+ * control box goes through the trigger, so it reaches this handler too.
+ * With `renderTrigger` it lands on the caller's control and runs after the
+ * built-in toggle, which it cannot cancel.
+ */
+ onClick?: React.MouseEventHandler<HTMLElement>;
+ /**
+ * Key handler on the trigger. It runs after the built-in handling and
+ * receives every key, including the ArrowDown that opens the popup. With
+ * `renderTrigger` it lands on the caller's control, runs after the built-in
+ * handling, and is skipped for keys that handling cancels.
+ */
+ onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
/** Current controlled value. */
value: Value;
/** Called when custom content commits a new value. */
@@ -358,7 +402,7 @@ export interface ComplexSelectorProps<Value> extends Omit<
onOpenChange?: (isOpen: boolean) => void;
/** StyleX styles for the popup content container. */
contentXstyle?: StyleXStyles;
- /** Test ID for the trigger container. */
+ /** Test ID for the trigger button. */
'data-testid'?: string;
}
@@ -416,13 +460,35 @@ export function ComplexSelector<Value>({
renderTrigger,
onOpenChange,
contentXstyle,
- xstyle,
- className,
- style,
- 'data-testid': testId,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
+ ref,
+ id,
onClick: onClickProp,
- ...props
+ onKeyDown: onKeyDownProp,
+ 'aria-describedby': ariaDescribedByProp,
+ ...restProps
}: ComplexSelectorProps<Value>) {
+ const {rest, container} = useFieldInputStyling('ComplexSelector', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ useDevWarning(
+ 'ComplexSelector',
+ RENDER_TRIGGER_PARTS_MESSAGE,
+ renderTrigger != null &&
+ (containerXstyle != null ||
+ containerClassName != null ||
+ containerStyle != null ||
+ controlXstyle != null ||
+ controlClassName != null ||
+ controlStyle != null),
+ );
const t = useTranslator();
const pressable = usePressFeedback();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
@@ -432,7 +498,9 @@ export function ComplexSelector<Value>({
? 'detached'
: statusVariant;
- const triggerId = useId();
+ const generatedTriggerId = useId();
+ // A caller's `id` lands on the trigger, so the label wiring must use it.
+ const triggerId = id ?? generatedTriggerId;
const labelId = useId();
const contentId = useId();
const descriptionId = useId();
@@ -446,6 +514,7 @@ export function ComplexSelector<Value>({
.join(' ') || undefined;
const triggerRef = useRef<HTMLElement>(null);
+ const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);
const [isPending, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -488,6 +557,44 @@ export function ComplexSelector<Value>({
popover.hide();
}, [popover]);
+ const handleTriggerKeyDown = useCallback(
+ (event: React.KeyboardEvent<HTMLElement>) => {
+ if (event.key === 'ArrowDown' && !isOpen && !isDisabled) {
+ event.preventDefault();
+ popover.show();
+ }
+ },
+ [isDisabled, isOpen, popover],
+ );
+
+ // A caller `onClick` runs first and can cancel opening with
+ // `preventDefault()`, as it always could. It now lands on the trigger, so
+ // the trigger composes it; a press elsewhere in the control box (padding,
+ // start icon, chevron) opens the popup directly.
+ const handleTriggerButtonClick = composeEventHandlers(
+ onClickProp,
+ handleTriggerClick,
+ );
+ // A caller `onKeyDown` sees every key, including the ArrowDown the trigger
+ // has already used to open the popup.
+ const handleTriggerButtonKeyDown = (
+ event: React.KeyboardEvent<HTMLElement>,
+ ) => {
+ handleTriggerKeyDown(event);
+ onKeyDownProp?.(event);
+ };
+ const handleControlBoxClick = useCallback(
+ (event: React.MouseEvent<HTMLDivElement>) => {
+ if (triggerRef.current?.contains(event.target as Node)) {
+ return;
+ }
+ // Route the press through the trigger so it behaves exactly like a
+ // press on the trigger itself, caller `onClick` included.
+ triggerRef.current?.click();
+ },
+ [],
+ );
+
useImperativeHandle(
handleRef,
() => ({
@@ -555,18 +662,19 @@ export function ComplexSelector<Value>({
// on it. No Field, no status, no chevron — the caller owns the control;
// the selector owns the popup, its anchor, and focus return.
const triggerProps: ComplexSelectorRenderTriggerProps = {
- ref: el => {
+ // Base props reach the caller's control, the primary semantic control
+ // in this mode; the selector's own wiring below wins over them.
+ ...rest,
+ 'aria-describedby': ariaDescribedByProp,
+ ref: mergeRefs<HTMLElement>(el => {
popover.triggerRef(el);
triggerRef.current = el;
- },
+ }, ref),
id: triggerId,
- onClick: handleTriggerClick,
- onKeyDown: event => {
- if (event.key === 'ArrowDown' && !isOpen && !isDisabled) {
- event.preventDefault();
- popover.show();
- }
- },
+ // This path never forwarded caller handlers before, so the newly
+ // forwarded ones compose component first and cannot cancel opening.
+ onClick: composeEventHandlers(handleTriggerClick, onClickProp),
+ onKeyDown: composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
'aria-haspopup': 'dialog',
'aria-expanded': isOpen,
'aria-controls': contentId,
@@ -584,10 +692,8 @@ export function ComplexSelector<Value>({
<>
<div
ref={popover.triggerRef}
- data-testid={testId}
{...pressable}
- {...props}
- onClick={composeEventHandlers(onClickProp, handleTriggerClick)}
+ onClick={handleControlBoxClick}
{...mergeProps(
themeProps('complex-selector', {
variant,
@@ -609,31 +715,32 @@ export function ComplexSelector<Value>({
variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
isDisabled && styles.disabled,
triggerLabel == null && styles.placeholder,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{isRenderable(startIconSlot) && startIconSlot}
<button
- ref={triggerRef as React.Ref<HTMLButtonElement>}
+ {...rest}
+ ref={triggerButtonRef}
id={triggerId}
type="button"
aria-haspopup="dialog"
aria-expanded={isOpen}
aria-controls={contentId}
- aria-describedby={ariaDescribedBy}
+ // A caller's description is kept alongside the field's own.
+ aria-describedby={
+ [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
+ undefined
+ }
aria-labelledby={labelId}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
disabled={isDisabled}
- onKeyDown={event => {
- if (event.key === 'ArrowDown' && !isOpen && !isDisabled) {
- event.preventDefault();
- popover.show();
- }
- }}
+ onClick={handleTriggerButtonClick}
+ onKeyDown={handleTriggerButtonKeyDown}
{...stylex.props(styles.trigger)}>
<span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
</button>
@@ -683,7 +790,8 @@ export function ComplexSelector<Value>({
}
statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
- width={width}>
+ width={width}
+ {...container}>
{selectorContent}
</Field>
);
diff --git a/packages/core/src/Field/fieldInputFamily.test.tsx b/packages/core/src/Field/fieldInputFamily.test.tsx
index 4b3f96040d..c0d56014f7 100644
--- a/packages/core/src/Field/fieldInputFamily.test.tsx
+++ b/packages/core/src/Field/fieldInputFamily.test.tsx
@@ -21,9 +21,6 @@ const PENDING_FR10 = new Set([
// text batch
// date/time batch
// selector batch
- 'Selector',
- 'MultiSelector',
- 'ComplexSelector',
// field-root batch
]);
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 912d0e8df6..aa6ce1d5d4 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -406,10 +406,56 @@ export const docs = {
'Called whenever the panel opens or closes, however it happened: the trigger, the keyboard, a light dismiss, Escape, or the handle.',
},
{
- name: 'xstyle',
+ name: 'onClick',
+ type: '(event: MouseEvent) => void',
+ description:
+ 'Click handler on the trigger (or the renderTrigger control). Runs after the built-in toggle and cannot cancel it.',
+ },
+ {
+ name: 'onFocus',
+ type: '(event: FocusEvent) => void',
+ description:
+ "Focus handler on the trigger. Runs before the selector's own focus handling.",
+ },
+ {
+ name: 'onKeyDown',
+ type: '(event: KeyboardEvent) => void',
+ description:
+ 'Key handler on the trigger button. Runs after the built-in keyboard model and is skipped for keys it handles and cancels.',
+ },
+ {
+ name: 'containerXstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ 'StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.',
+ },
+ {
+ name: 'containerClassName',
+ type: 'string',
+ description:
+ 'Class name for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'containerStyle',
+ type: 'CSSProperties',
+ description:
+ 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the element that paints the border and background and holds the value, icons, and end controls. Never the trigger button itself.',
+ },
+ {
+ name: 'controlClassName',
+ type: 'string',
+ description: 'Class name for the visual control box.',
+ },
+ {
+ name: 'controlStyle',
+ type: 'CSSProperties',
+ description: 'Inline styles for the visual control box.',
},
],
},
@@ -523,7 +569,18 @@ export const docsZh = {
onOpenChange: '面板每次打开或关闭时触发,无论由何种方式引起。',
presentation:
'选项列表的呈现方式:锚定弹出框、底部抽屉,或根据紧凑触控屏自适应。',
- xstyle: '布局自定义的 StyleX 样式,必须是 stylex.create() 值。',
+ onClick: '触发器的点击处理函数,在内置开关之后运行,无法取消它。',
+ onFocus: '触发器的焦点处理函数,在选择器自身的焦点处理之前运行。',
+ onKeyDown:
+ '触发器的按键处理函数,在内置键盘模型之后运行;该模型处理并取消的按键不会传给它。',
+ containerXstyle:
+ '字段容器(标签、控件和状态整体)的 StyleX 样式。在 InputGroup 内或 `horizontal-labels` FormLayout 中无效。不接受根级 xstyle、className 和 style。',
+ containerClassName: '字段容器的类名,作用目标同 containerXstyle。',
+ containerStyle: '字段容器的内联样式,作用目标同 containerXstyle。',
+ controlXstyle:
+ '可视控件框的 StyleX 样式:绘制边框和背景并包含值、图标与尾部控件的元素,而非触发按钮本身。',
+ controlClassName: '可视控件框的类名。',
+ controlStyle: '可视控件框的内联样式。',
},
},
],
@@ -671,7 +728,18 @@ export const docsDense = {
onOpenChange: 'fires on every open/close, whatever caused it',
presentation:
'popover, bottom-sheet, or compact-touch adaptive presentation',
- xstyle: 'StyleX layout styles; stylex.create() only',
+ onClick:
+ 'trigger click; runs after the built-in toggle, cannot cancel it',
+ onFocus: 'trigger focus; runs before built-in focus handling',
+ onKeyDown: 'trigger keys; runs after the built-in keyboard model',
+ containerXstyle:
+ 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+ containerClassName: 'Class name for the field container.',
+ containerStyle: 'Inline styles for the field container.',
+ controlXstyle:
+ 'StyleX styles for the visual control box (border, background, icons); not the trigger button.',
+ controlClassName: 'Class name for the visual control box.',
+ controlStyle: 'Inline styles for the visual control box.',
},
},
],
diff --git a/packages/core/src/MultiSelector/MultiSelector.fr10.test.tsx b/packages/core/src/MultiSelector/MultiSelector.fr10.test.tsx
new file mode 100644
index 0000000000..310dca7505
--- /dev/null
+++ b/packages/core/src/MultiSelector/MultiSelector.fr10.test.tsx
@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MultiSelector.fr10.test.tsx
+ * @input Uses vitest, Testing Library, the shared FR10 suites, and MultiSelector
+ * @output Tests that MultiSelector's base props, container*, and control* reach
+ * their family:input-fields FR10 targets
+ * @position Tests; MultiSelector's FR10 conformance alongside MultiSelector.test.tsx
+ */
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+import {MultiSelector, type MultiSelectorProps} from './MultiSelector';
+
+const NO_VALUE: string[] = [];
+
+const OPTIONS = ['Apple', 'Banana'];
+
+// jsdom has no Popover API; reflect open state the way the browser does.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle');
+ 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');
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+});
+
+describe('MultiSelector props type (family:input-fields FR10)', () => {
+ it('accepts container* and control* and no root styling', () => {
+ expectFieldInputProps<MultiSelectorProps>();
+ });
+});
+
+describeFieldInputParts('MultiSelector', {
+ renderMember: props => (
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ {...props}
+ />
+ ),
+ getControl: () => screen.getByRole('combobox'),
+ inGroup: true,
+});
+
+describe('MultiSelector FR10 targets', () => {
+ it('keeps a caller aria-describedby alongside the field description', () => {
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ description="Pick one"
+ aria-describedby="caller-help"
+ />,
+ );
+ const ids = (
+ screen.getByRole('combobox').getAttribute('aria-describedby') ?? ''
+ ).split(' ');
+ expect(ids).toContain('caller-help');
+ expect(
+ ids.map(id => document.getElementById(id)?.textContent ?? '').join(' '),
+ ).toContain('Pick one');
+ });
+
+ it('puts control* on the bordered control box around the trigger, not on the trigger or the popup', () => {
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ containerClassName="fr10-container"
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ const controlBox = document.querySelector('.fr10-control') as HTMLElement;
+ expect(controlBox).toHaveClass('astryx-multi-selector');
+ expect(controlBox).toContainElement(trigger);
+ expect(trigger).not.toHaveClass('fr10-control');
+
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(document.querySelectorAll('.fr10-control')).toHaveLength(1);
+ expect(document.querySelectorAll('.fr10-container')).toHaveLength(1);
+ expect(screen.getByRole('listbox', {hidden: true})).not.toHaveClass(
+ 'fr10-control',
+ );
+ });
+
+ it('runs the built-in toggle before a consumer onClick, once per press', () => {
+ const states: (string | null)[] = [];
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ onClick={event => {
+ states.push(event.currentTarget.getAttribute('role') ?? 'button');
+ // Neither cancelling nor stopping the press undoes the built-in
+ // toggle, which already ran on the trigger button.
+ event.preventDefault();
+ event.stopPropagation();
+ }}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ fireEvent.click(trigger);
+ expect(states).toHaveLength(1);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('opens from a press on the control box outside the trigger button', () => {
+ const {container} = render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ />,
+ );
+ const controlBox = container.querySelector('.fr10-control') as HTMLElement;
+ fireEvent.click(controlBox);
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ });
+
+ it('keeps the built-in keyboard model and composes a consumer onKeyDown after it', () => {
+ const keyTargets: EventTarget[] = [];
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ onKeyDown={event => keyTargets.push(event.currentTarget)}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ fireEvent.keyDown(trigger, {key: 'Tab'});
+ // The consumer handler lands on the trigger itself.
+ expect(keyTargets).toEqual([trigger]);
+ fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+});
+
+describe('MultiSelector FR10 renderTrigger', () => {
+ it('forwards base props and the ref to the caller-rendered control', () => {
+ const ref = {current: null as HTMLElement | null};
+ const onClick = vi.fn();
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ ref={ref}
+ data-testid="opener"
+ aria-details="details-id"
+ onClick={onClick}
+ renderTrigger={props => (
+ <button type="button" {...props}>
+ Open
+ </button>
+ )}
+ />,
+ );
+ const opener = screen.getByRole('button', {name: 'Open'});
+ expect(opener).toHaveAttribute('data-testid', 'opener');
+ expect(opener).toHaveAttribute('aria-details', 'details-id');
+ expect(ref.current).toBe(opener);
+ fireEvent.click(opener);
+ expect(onClick).toHaveBeenCalledTimes(1);
+ expect(opener).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('warns that container* and control* have no effect', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {container} = render(
+ <MultiSelector
+ label="Fruit"
+ options={OPTIONS}
+ value={NO_VALUE}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ renderTrigger={props => (
+ <button type="button" {...props}>
+ Open
+ </button>
+ )}
+ />,
+ );
+ expect(container.querySelector('.fr10-control')).toBeNull();
+ expect(
+ warn.mock.calls.some(call =>
+ String(call[0]).startsWith(
+ 'MultiSelector: `container*` and `control*`',
+ ),
+ ),
+ ).toBe(true);
+ warn.mockRestore();
+ });
+});
diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsx
index 3f6e3e6c93..246bb2e628 100644
--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx
@@ -1853,7 +1853,11 @@ describe('MultiSelector', () => {
/>,
);
- const container = screen.getByTestId('fruit-multi-selector');
+ // data-testid lands on the trigger; the reason tooltip anchors to the
+ // control box around it.
+ const container = screen
+ .getByTestId('fruit-multi-selector')
+ .closest('.astryx-multi-selector') as HTMLElement;
const tooltip = screen.getByRole('tooltip', h);
expect(tooltip).toHaveTextContent('Select a table first');
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index a8c9778c20..65ee97254d 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -78,7 +78,15 @@ import {useAnnounce} from '../hooks/useAnnounce';
import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
-import type {BaseProps} from '../BaseProps';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+ type FieldPartStyleProps,
+} from '../Field/fieldParts';
+import {useDevWarning} from '../hooks/useDevWarning';
+import {composeEventHandlers} from '../utils/composeEventHandlers';
+import {mergeRefs} from '../utils/mergeRefs';
+import {useMergedRefs} from '../hooks/useMergedRefs';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
@@ -459,6 +467,10 @@ const selectAllSizeStyles = stylex.create({
},
});
+const RENDER_TRIGGER_PARTS_MESSAGE =
+ '`container*` and `control*` styling props have no effect with `renderTrigger`: ' +
+ 'no Field box or control box renders. Style the control you render instead.';
+
const STATUS_ICON_MAP: Record<MultiSelectorStatusType, IconName> = {
warning: 'warning',
error: 'error',
@@ -496,8 +508,23 @@ export type {MultiSelectorStatus};
* Spread them onto that control: it becomes the panel's anchor, the element
* focus returns to, and the control that announces the panel's state.
*/
-export interface MultiSelectorRenderTriggerProps {
- /** Attaches the control as the panel's anchor and focus-return target. */
+export interface MultiSelectorRenderTriggerProps extends Omit<
+ FieldInputBaseProps,
+ | keyof FieldPartStyleProps
+ | 'id'
+ | 'onClick'
+ | 'onKeyDown'
+ | 'onFocus'
+ | 'aria-haspopup'
+ | 'aria-expanded'
+ | 'aria-controls'
+ | 'aria-busy'
+ | 'aria-readonly'
+> {
+ /**
+ * Attaches the control as the panel's anchor and focus-return target, and
+ * forwards it to the selector's own `ref`.
+ */
ref: (element: HTMLElement | null) => void;
/** The id the field would have given its own button. */
id: string;
@@ -562,12 +589,37 @@ export interface MultiSelectorSelectedItem {
export interface MultiSelectorProps<
T extends MultiSelectorOptionType = MultiSelectorOptionType,
-> extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
+> extends Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'> {
/**
* Label text for the multi-selector (always rendered for accessibility).
*/
label: string;
+ /**
+ * Ref to the trigger: the button that carries the combobox role, the
+ * accessible name, and the value — or, with `renderTrigger`, the caller's
+ * control.
+ */
+ ref?: React.Ref<HTMLElement>;
+
+ /**
+ * Click handler on the trigger (or, with `renderTrigger`, the caller's
+ * control). It runs after the built-in toggle and cannot cancel it.
+ */
+ onClick?: React.MouseEventHandler<HTMLElement>;
+
+ /**
+ * Focus handler on the trigger. It runs before the selector's own focus
+ * handling.
+ */
+ onFocus?: React.FocusEventHandler<HTMLElement>;
+
+ /**
+ * Key handler on the trigger. It runs after the built-in keyboard model and
+ * is skipped for keys that model handles and cancels.
+ */
+ onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
+
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
@@ -705,7 +757,7 @@ export interface MultiSelectorProps<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `controlXstyle`/`controlClassName`/`controlStyle`.
*/
width?: SizeValue;
/**
@@ -889,7 +941,8 @@ export interface MultiSelectorProps<
onOpenChange?: (isOpen: boolean) => void;
/**
- * Test ID for testing frameworks.
+ * Test ID for testing frameworks, set on the trigger button (or, with
+ * `renderTrigger`, the caller's control).
*/
'data-testid'?: string;
}
@@ -1015,14 +1068,38 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
renderTrigger,
handleRef,
onOpenChange,
- 'data-testid': testId,
htmlName,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
+ ref,
+ id,
+ onClick,
onFocus,
+ onKeyDown: onKeyDownProp,
+ 'aria-describedby': ariaDescribedByProp,
+ ...restProps
}: MultiSelectorProps<T>) {
+ const {rest, container} = useFieldInputStyling('MultiSelector', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
+ useDevWarning(
+ 'MultiSelector',
+ RENDER_TRIGGER_PARTS_MESSAGE,
+ renderTrigger != null &&
+ (containerXstyle != null ||
+ containerClassName != null ||
+ containerStyle != null ||
+ controlXstyle != null ||
+ controlClassName != null ||
+ controlStyle != null),
+ );
const t = useTranslator();
const pressable = usePressFeedback();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
@@ -1042,7 +1119,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
: statusVariant;
const isEffectivelyReadOnly = isReadOnly && !isDisabled;
- const triggerId = useId();
+ const generatedTriggerId = useId();
+ // A caller's `id` lands on the trigger, so the label and listbox wiring
+ // must use that same value.
+ const triggerId = id ?? generatedTriggerId;
const listboxId = useId();
const descriptionId = useId();
const statusMessageId = useId();
@@ -1052,6 +1132,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
// Read by the live region above so it speaks what this element renders.
const emptyStateRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLElement>(null);
+ const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);
const searchRef = useRef<HTMLInputElement>(null);
const listboxRef = useRef<HTMLDivElement>(null);
const inputGroup = useInputGroup();
@@ -1667,6 +1748,24 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
),
});
+ // The trigger button owns its click so a consumer `onClick`, which lands on
+ // the button, composes after the built-in toggle. A press elsewhere in the
+ // control box (padding, start icon, chevron) still opens the panel.
+ const handleTriggerButtonClick = useCallback(() => {
+ onTriggerClick();
+ }, [onTriggerClick]);
+ const handleControlBoxClick = useCallback(
+ (event: React.MouseEvent<HTMLDivElement>) => {
+ if (triggerRef.current?.contains(event.target as Node)) {
+ return;
+ }
+ // Route the press through the trigger so it behaves exactly like a
+ // press on the trigger itself, caller `onClick` included.
+ triggerRef.current?.click();
+ },
+ [],
+ );
+
// Highlight scrolling (and its hover/keyboard split) lives in useMultiCombobox.
// Build trigger display content
@@ -2242,17 +2341,25 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
}
const triggerSharedProps: React.HTMLAttributes<HTMLElement> = {
+ ...rest,
id: triggerId,
- 'aria-describedby': ariaDescribedBy,
+ // A caller's description is kept alongside the field's own.
+ 'aria-describedby':
+ [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
+ undefined,
'aria-labelledby': ariaLabelledBy,
'aria-required': isEffectivelyRequired ? 'true' : undefined,
'aria-invalid': status?.type === 'error' ? 'true' : undefined,
'aria-busy': isBusy || undefined,
- onKeyDown,
+ // Newly forwarded handlers compose component first: the built-in toggle
+ // and keyboard model always run. `onFocus` keeps its existing caller-first
+ // order.
+ onKeyDown: composeEventHandlers(onKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
},
+ onClick: composeEventHandlers(handleTriggerButtonClick, onClick),
tabIndex: isDisabled && !showsDisabledMessage ? -1 : 0,
...stylex.props(
styles.trigger,
@@ -2265,7 +2372,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
// on it. No Field, no status, no clear button — the caller owns the
// control; the selector owns the panel, its anchor, and focus return.
const triggerProps: MultiSelectorRenderTriggerProps = {
- ref: el => {
+ // Base props reach the caller's control, the primary semantic control
+ // in this mode; the selector's own wiring below wins over them.
+ ...rest,
+ 'aria-describedby': ariaDescribedByProp,
+ ref: mergeRefs<HTMLElement>(el => {
popover.triggerRef(el);
triggerRef.current = el;
// A control that takes no focus has nowhere for focus to return to
@@ -2278,10 +2389,14 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
el.tabIndex = -1;
}
- },
+ }, ref),
id: triggerId,
- onClick: isEffectivelyReadOnly ? undefined : onTriggerClick,
- onKeyDown: isEffectivelyReadOnly ? undefined : onKeyDown,
+ onClick: isEffectivelyReadOnly
+ ? onClick
+ : composeEventHandlers(onTriggerClick, onClick),
+ onKeyDown: isEffectivelyReadOnly
+ ? onKeyDownProp
+ : composeEventHandlers(onKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
@@ -2336,8 +2451,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
- onClick={onTriggerClick}
- data-testid={testId}
+ onClick={handleControlBoxClick}
{...pressable}
{...mergeProps(
themeProps('multi-selector', {
@@ -2371,10 +2485,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
!isDisabled &&
inputStatusHoverShadowStyles[status.type],
variant !== 'ghost' && inputGroup && groupStyles.inGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{startIcon &&
renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
@@ -2388,7 +2502,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
)}
<button
{...triggerSharedProps}
- ref={triggerRef as React.Ref<HTMLButtonElement>}
+ ref={triggerButtonRef}
type="button"
// The read-only trigger stays a combobox even when hasSearch is set:
// no search input is rendered in that state, and preserving the role
@@ -2537,7 +2651,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
}
statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
- width={width}>
+ width={width}
+ {...container}>
{multiSelectorContent}
</Field>
);
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index dae7b0889c..b437d950d5 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -354,10 +354,56 @@ export const docs = {
default: 'false',
},
{
- name: 'xstyle',
+ name: 'onClick',
+ type: '(event: MouseEvent) => void',
+ description:
+ 'Click handler on the trigger button. Runs before the selector toggles its surface; preventDefault() does not keep it closed.',
+ },
+ {
+ name: 'onFocus',
+ type: '(event: FocusEvent) => void',
+ description:
+ "Focus handler on the trigger button. Runs before the selector's own focus handling.",
+ },
+ {
+ name: 'onKeyDown',
+ type: '(event: KeyboardEvent) => void',
+ description:
+ 'Key handler on the trigger button. Runs after the built-in keyboard model and is skipped for keys it handles and cancels.',
+ },
+ {
+ name: 'containerXstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+ 'StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.',
+ },
+ {
+ name: 'containerClassName',
+ type: 'string',
+ description:
+ 'Class name for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'containerStyle',
+ type: 'CSSProperties',
+ description:
+ 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+ },
+ {
+ name: 'controlXstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for the visual control box: the element that paints the border and background and holds the value, icons, and end controls. Never the trigger button itself.',
+ },
+ {
+ name: 'controlClassName',
+ type: 'string',
+ description: 'Class name for the visual control box.',
+ },
+ {
+ name: 'controlStyle',
+ type: 'CSSProperties',
+ description: 'Inline styles for the visual control box.',
},
],
components: [{name: 'SelectorOption'}],
diff --git a/packages/core/src/Selector/Selector.fr10.test.tsx b/packages/core/src/Selector/Selector.fr10.test.tsx
new file mode 100644
index 0000000000..b997f169ed
--- /dev/null
+++ b/packages/core/src/Selector/Selector.fr10.test.tsx
@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Selector.fr10.test.tsx
+ * @input Uses vitest, Testing Library, the shared FR10 suites, and Selector
+ * @output Tests that Selector's base props, container*, and control* reach
+ * their family:input-fields FR10 targets
+ * @position Tests; Selector's FR10 conformance alongside Selector.test.tsx
+ */
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {expectFieldInputProps} from '../Field/fieldInputFamily.testing';
+import {describeFieldInputParts} from '../Field/fieldInputFamily.render-testing';
+import {Selector, type SelectorProps} from './Selector';
+
+const OPTIONS = ['Apple', 'Banana'];
+
+// jsdom has no Popover API; reflect open state the way the browser does.
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle');
+ 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');
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+});
+
+describe('Selector props type (family:input-fields FR10)', () => {
+ it('accepts container* and control* and no root styling', () => {
+ expectFieldInputProps<SelectorProps>();
+ });
+});
+
+describeFieldInputParts('Selector', {
+ renderMember: props => (
+ <Selector label="Fruit" options={OPTIONS} onChange={() => {}} {...props} />
+ ),
+ getControl: () => screen.getByRole('combobox'),
+ inGroup: true,
+});
+
+describe('Selector FR10 targets', () => {
+ it('keeps a caller aria-describedby alongside the field description', () => {
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ onChange={() => {}}
+ description="Pick one"
+ aria-describedby="caller-help"
+ />,
+ );
+ const ids = (
+ screen.getByRole('combobox').getAttribute('aria-describedby') ?? ''
+ ).split(' ');
+ expect(ids).toContain('caller-help');
+ expect(
+ ids.map(id => document.getElementById(id)?.textContent ?? '').join(' '),
+ ).toContain('Pick one');
+ });
+
+ it('puts control* on the bordered control box around the trigger, not on the trigger or the popup', () => {
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ containerClassName="fr10-container"
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ const controlBox = document.querySelector('.fr10-control') as HTMLElement;
+ expect(controlBox).toHaveClass('astryx-selector');
+ expect(controlBox).toContainElement(trigger);
+ expect(trigger).not.toHaveClass('fr10-control');
+
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(document.querySelectorAll('.fr10-control')).toHaveLength(1);
+ expect(document.querySelectorAll('.fr10-container')).toHaveLength(1);
+ expect(screen.getByRole('listbox', {hidden: true})).not.toHaveClass(
+ 'fr10-control',
+ );
+ });
+
+ it('keeps a caller onClick on the trigger, where cancelling does not stop the toggle', () => {
+ const targets: EventTarget[] = [];
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ onChange={() => {}}
+ onClick={event => {
+ targets.push(event.currentTarget);
+ event.preventDefault();
+ }}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ fireEvent.click(trigger);
+ // Unchanged order: the caller runs on the trigger, then the press reaches
+ // the control box's toggle, which `preventDefault()` never cancelled.
+ expect(targets).toEqual([trigger]);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('opens from a press on the control box outside the trigger button', () => {
+ const {container} = render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ onChange={() => {}}
+ controlClassName="fr10-control"
+ />,
+ );
+ const controlBox = container.querySelector('.fr10-control') as HTMLElement;
+ fireEvent.click(controlBox);
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ });
+
+ it('keeps the built-in keyboard model and composes a consumer onKeyDown after it', () => {
+ const keyTargets: EventTarget[] = [];
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ onChange={() => {}}
+ onKeyDown={event => keyTargets.push(event.currentTarget)}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ fireEvent.keyDown(trigger, {key: 'Tab'});
+ // The consumer handler lands on the trigger itself.
+ expect(keyTargets).toEqual([trigger]);
+ fireEvent.keyDown(trigger, {key: 'ArrowDown'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+});
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index 5f2a855c0d..f3d12bc767 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -2485,7 +2485,11 @@ describe('Selector', () => {
/>,
);
- const container = screen.getByTestId('fruit-selector');
+ // data-testid lands on the trigger; the reason tooltip anchors to the
+ // control box around it.
+ const container = screen
+ .getByTestId('fruit-selector')
+ .closest('.astryx-selector') as HTMLElement;
const tooltip = screen.getByRole('tooltip', h);
expect(tooltip).toHaveTextContent('You need the Editor role');
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index 0ca3f630c0..df4497d9c9 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -81,7 +81,12 @@ import {SelectorRowLayoutContext} from './SelectorRowLayoutContext';
import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
import {warnOnce} from '../utils/devWarning';
import {useSize} from '../SizeContext/SizeContext';
-import type {BaseProps} from '../BaseProps';
+import {
+ useFieldInputStyling,
+ type FieldInputBaseProps,
+} from '../Field/fieldParts';
+import {composeEventHandlers} from '../utils/composeEventHandlers';
+import {useMergedRefs} from '../hooks/useMergedRefs';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -526,12 +531,37 @@ export interface SelectorStatus {
interface SelectorPropsBase<
T extends SelectorOptionType = SelectorOptionType,
-> extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
+> extends Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'> {
/**
* Label text for the selector (always rendered for accessibility).
*/
label: string;
+ /**
+ * Ref to the trigger button: the element that carries the combobox role,
+ * the accessible name, and the value.
+ */
+ ref?: React.Ref<HTMLButtonElement>;
+
+ /**
+ * Click handler on the trigger button. It runs before the selector toggles
+ * its surface (the press then reaches the control box), and calling
+ * `preventDefault()` does not keep the surface closed.
+ */
+ onClick?: React.MouseEventHandler<HTMLElement>;
+
+ /**
+ * Focus handler on the trigger button. It runs before the selector's own
+ * focus handling.
+ */
+ onFocus?: React.FocusEventHandler<HTMLElement>;
+
+ /**
+ * Key handler on the trigger button. It runs after the built-in keyboard
+ * model and is skipped for keys that model handles and cancels.
+ */
+ onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
+
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
@@ -648,7 +678,7 @@ interface SelectorPropsBase<
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
- * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+ * stay aligned, unlike setting width via `controlXstyle`/`controlClassName`/`controlStyle`.
*/
width?: SizeValue;
/**
@@ -897,16 +927,26 @@ export function Selector<T extends SelectorOptionType>(
placement,
presentation = 'popover',
isDefaultOpen = false,
- 'data-testid': testId,
width,
- xstyle,
- className,
- style,
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ controlXstyle,
+ controlClassName,
+ controlStyle,
+ ref,
onFocus,
+ onKeyDown: onKeyDownProp,
+ 'aria-describedby': ariaDescribedByProp,
hasClear: hasClearProp,
id,
- ...rest
+ ...restProps
} = props as SelectorPropsClearable<T>;
+ const {rest, container} = useFieldInputStyling('Selector', restProps, {
+ containerXstyle,
+ containerClassName,
+ containerStyle,
+ });
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
const searchPlaceholder =
@@ -940,6 +980,10 @@ export function Selector<T extends SelectorOptionType>(
// shorter inner button makes every size's selected row land too low.
const anchorRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLElement>(null);
+ const triggerButtonRef = useMergedRefs<HTMLButtonElement>(
+ triggerRef as React.Ref<HTMLButtonElement>,
+ ref,
+ );
const searchRef = useRef<HTMLInputElement>(null);
const inputGroup = useInputGroup();
@@ -1789,12 +1833,19 @@ export function Selector<T extends SelectorOptionType>(
const triggerSharedProps: React.HTMLAttributes<HTMLElement> = {
...rest,
id: triggerId,
- 'aria-describedby': ariaDescribedBy,
+ // A caller's description is kept alongside the field's own.
+ 'aria-describedby':
+ [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
+ undefined,
'aria-labelledby': ariaLabelledBy,
'aria-required': isEffectivelyRequired ? 'true' : undefined,
'aria-invalid': status?.type === 'error' ? 'true' : undefined,
'aria-busy': isBusy || undefined,
- onKeyDown: handleTriggerKeyDown,
+ // The built-in keyboard model runs first; a caller handler sees the keys
+ // it leaves uncancelled. A caller `onClick` arrives through `rest` and
+ // runs on the trigger before the press bubbles to the control box's
+ // toggle, as it always has.
+ onKeyDown: composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
@@ -1819,7 +1870,6 @@ export function Selector<T extends SelectorOptionType>(
disabledMessageTooltip.ref(el);
}}
onClick={onTriggerClick}
- data-testid={testId}
{...pressable}
{...mergeProps(
themeProps('selector', {
@@ -1854,10 +1904,10 @@ export function Selector<T extends SelectorOptionType>(
inputStatusHoverShadowStyles[status.type],
variant !== 'ghost' && inputGroup && groupStyles.inGroup,
inputGroup && styles.triggerInGroup,
- xstyle,
+ controlXstyle,
),
- className,
- style,
+ controlClassName,
+ controlStyle,
)}>
{startIcon &&
renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
@@ -1871,7 +1921,7 @@ export function Selector<T extends SelectorOptionType>(
)}
<button
{...triggerSharedProps}
- ref={triggerRef as React.Ref<HTMLButtonElement>}
+ ref={triggerButtonRef}
type="button"
// The read-only trigger stays a combobox even when hasSearch is set:
// no search input is rendered in that state, and preserving the role
@@ -2014,7 +2064,8 @@ export function Selector<T extends SelectorOptionType>(
}
statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
- width={width}>
+ width={width}
+ {...container}>
{selectorContent}
</Field>
);
diff --git a/packages/lab/src/TransferList/TransferList.doc.mjs b/packages/lab/src/TransferList/TransferList.doc.mjs
index 466f884083..fb6373d330 100644
--- a/packages/lab/src/TransferList/TransferList.doc.mjs
+++ b/packages/lab/src/TransferList/TransferList.doc.mjs
@@ -239,24 +239,26 @@ export const docs = {
'Optional async action run after each immediate commit or a changed staged Apply; drives optimistic and busy state.',
},
{
- name: 'xstyle',
+ name: 'controlXstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for the external selector field.',
+ description:
+ "StyleX styles for the external selector's bordered control box.",
},
{
- name: 'className',
+ name: 'controlClassName',
type: 'string',
- description: 'Class name applied to the external selector field.',
+ description: "Class name applied to the external selector's control box.",
},
{
- name: 'style',
+ name: 'controlStyle',
type: 'CSSProperties',
- description: 'Inline styles applied to the external selector field.',
+ description:
+ "Inline styles applied to the external selector's control box.",
},
{
name: 'data-testid',
type: 'string',
- description: 'Test ID for the selector trigger container.',
+ description: 'Test ID for the selector trigger button.',
},
],
components: [
diff --git a/packages/lab/src/TransferList/TransferListSelector.test.tsx b/packages/lab/src/TransferList/TransferListSelector.test.tsx
index 96c8d37016..04ed210ea0 100644
--- a/packages/lab/src/TransferList/TransferListSelector.test.tsx
+++ b/packages/lab/src/TransferList/TransferListSelector.test.tsx
@@ -557,10 +557,10 @@ describe('TransferListSelector', () => {
expect(
screen.getByText('Choose the columns shown in the table.'),
).toBeVisible();
- expect(screen.getByTestId('column-selector')).toHaveAttribute(
- 'data-size',
- 'sm',
- );
+ // data-testid lands on the trigger button inside the control box.
+ expect(
+ screen.getByTestId('column-selector').closest('.astryx-complex-selector'),
+ ).toHaveAttribute('data-size', 'sm');
expect(
screen.getByRole('button', {name: 'Table columns'}),
).toHaveTextContent('Customize columns');
diff --git a/packages/lab/src/TransferList/TransferListSelector.tsx b/packages/lab/src/TransferList/TransferListSelector.tsx
index 11af683401..1c19d31ce5 100644
--- a/packages/lab/src/TransferList/TransferListSelector.tsx
+++ b/packages/lab/src/TransferList/TransferListSelector.tsx
@@ -93,9 +93,9 @@ type TransferListSelectorShellProp =
| 'size'
| 'width'
| 'placement'
- | 'xstyle'
- | 'className'
- | 'style'
+ | 'controlXstyle'
+ | 'controlClassName'
+ | 'controlStyle'
| 'data-testid';
type TransferListContentProp =