An open source design system that's fully customizable and agent ready
TypeScript
feat(selector): configurable indicator position for Selector and MultiSelector (#4993)
Cindy Zhange144ea7b4814
diff --git a/.changeset/selector-indicator-position.md b/.changeset/selector-indicator-position.mdnew file mode 100644index 0000000000..b4ebdbdcfd--- /dev/null+++ b/.changeset/selector-indicator-position.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Selector and MultiSelector: `indicatorPosition` places the selection indicator on either edge of the option row — `start` or `end`, logical, so it follows RTL. Defaults keep today's rendering (`end` for Selector's check, `start` for MultiSelector's checkbox); a start-positioned check reserves its column on every row so labels stay aligned.++@cixzhangdiff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsxindex ebf092907d..150edd5f7c 100644--- a/apps/storybook/stories/MultiSelector.stories.tsx+++ b/apps/storybook/stories/MultiSelector.stories.tsx@@ -577,3 +577,26 @@ export const ThemedIcons: Story = {);},};++/**+ * `indicatorPosition="end"` moves the checkbox to the trailing edge of each+ * row. The default is `start`, where the checkbox leads the label as it does in+ * CheckboxList.+ */+export const EndIndicatorPosition: Story = {+ render: () => {+ const [value, setValue] = useState<string[]>(['Name', 'Email']);+ return (+ // No hasSelectAll: its divider is an unallowed listbox child and fails+ // the a11y audit as soon as a story opens the popup (#4994).+ <MultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role', 'Status']}+ value={value}+ onChange={setValue}+ indicatorPosition="end"+ isDefaultOpen+ />+ );+ },+};diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsxindex a81362a6b4..3717832fe1 100644--- a/apps/storybook/stories/Selector.stories.tsx+++ b/apps/storybook/stories/Selector.stories.tsx@@ -924,3 +924,27 @@ export const DefaultSelectionIndicator: Story = {);},};++/**+ * `indicatorPosition="start"` moves the mark to the leading edge, the way a+ * native menu marks its chosen row.+ *+ * The column is reserved on every row, not just the chosen one, so the labels+ * stay on one line — the default check draws nothing when unchecked, and+ * without the column only the chosen label would be indented.+ */+export const StartIndicatorPosition: Story = {+ render: () => {+ const [value, setValue] = useState<string | undefined>('Banana');+ return (+ <Selector+ label="Mark at the start"+ options={['Apple', 'Banana', 'Cherry']}+ value={value}+ onChange={setValue}+ indicatorPosition="start"+ isDefaultOpen+ />+ );+ },+};diff --git a/packages/core/src/Indicator/index.ts b/packages/core/src/Indicator/index.tsindex 4787f3fea5..5bb4dc05b3 100644--- a/packages/core/src/Indicator/index.ts+++ b/packages/core/src/Indicator/index.ts@@ -38,6 +38,7 @@ export type {IndicatorMap,IndicatorName,IndicatorNameOfFamily,+ IndicatorPosition,IndicatorProps,IndicatorRegistry,IndicatorSize,diff --git a/packages/core/src/Indicator/types.ts b/packages/core/src/Indicator/types.tsindex f76ebcab9f..cb3b3ff44b 100644--- a/packages/core/src/Indicator/types.ts+++ b/packages/core/src/Indicator/types.ts@@ -67,6 +67,17 @@ export type IndicatorState<F extends IndicatorFamily = IndicatorFamily> =/** Indicator size scale — matches the control sizes of the owning inputs. */export type IndicatorSize = 'sm' | 'md';+/**+ * Which edge of its row an indicator sits on.+ *+ * Logical, not physical: `start` is the left edge in LTR and the right edge in+ * RTL. Owned by the host component, not by the indicator — an indicator draws a+ * picture and has no say in where the row puts it — which is why this is a prop+ * on the components that lay out rows rather than part of+ * {@link IndicatorProps}.+ */+export type IndicatorPosition = 'start' | 'end';+/*** Props every indicator accepts.*diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex 61bd33476b..ad76fc74ab 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -192,6 +192,13 @@ export const docs = {description:'Custom render function for each selectable option in the dropdown. Not called for dividers, sections, or the select-all row.',},+ {+ name: 'indicatorPosition',+ type: "'start' | 'end'",+ description:+ 'Which edge of the option row carries the checkbox. end pushes it to the far edge of the row, including on the select-all row.',+ default: "'start'",+ },{name: 'width',type: 'SizeValue',diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsxindex 0f809e79fc..0fceec724d 100644--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx@@ -2110,3 +2110,72 @@ describe('MultiSelector popup theme target', () => {expect(popup.querySelector('[role="listbox"]')).not.toBeNull();});});++describe('MultiSelector indicatorPosition', () => {+ const OPTIONS = ['Apple', 'Banana', 'Cherry'];+ const rowFor = (label: string): HTMLElement =>+ screen+ .getAllByRole('option', {hidden: true})+ .find(row => row.textContent?.includes(label))!;++ it('draws the checkbox before the label by default', () => {+ render(+ <MultiSelector+ label="Fruit"+ options={OPTIONS}+ value={['Banana']}+ onChange={() => {}}+ isDefaultOpen+ />,+ );+ const row = rowFor('Banana');+ const checkbox = row.querySelector('.astryx-checkbox')!;+ const label = row.lastElementChild!;+ expect(label).toHaveTextContent('Banana');+ expect(+ label.compareDocumentPosition(checkbox) &+ Node.DOCUMENT_POSITION_PRECEDING,+ ).toBeTruthy();+ });++ it('draws the checkbox after the label when set to end', () => {+ render(+ <MultiSelector+ label="Fruit"+ options={OPTIONS}+ value={['Banana']}+ onChange={() => {}}+ indicatorPosition="end"+ isDefaultOpen+ />,+ );+ const row = rowFor('Banana');+ const checkbox = row.querySelector('.astryx-checkbox')!;+ const label = row.firstElementChild!;+ expect(label).toHaveTextContent('Banana');+ expect(+ label.compareDocumentPosition(checkbox) &+ Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ });++ it('keeps the select-all row on the same edge as the options', () => {+ render(+ <MultiSelector+ label="Fruit"+ options={OPTIONS}+ value={['Banana']}+ onChange={() => {}}+ hasSelectAll+ indicatorPosition="end"+ isDefaultOpen+ />,+ );+ const row = rowFor('Select all');+ expect(+ row.firstElementChild!.compareDocumentPosition(+ row.querySelector('.astryx-checkbox')!,+ ) & Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ });+});diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsxindex f59572e98f..4c60847176 100644--- a/packages/core/src/MultiSelector/MultiSelector.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.tsx@@ -44,6 +44,7 @@ import {Divider} from '../Divider';import {Spinner} from '../Spinner';import {TextInput} from '../TextInput';import {CheckboxInput} from '../CheckboxInput';+import type {IndicatorPosition} from '../Indicator';import {Badge} from '../Badge';import {colorVars,@@ -308,6 +309,14 @@ const styles = stylex.create({display: 'flex',flexShrink: 0,},+ // Pushed to the row's far edge rather than sitting against the label, which+ // is what an end-positioned control means here. The row is not+ // `space-between` (a truncating label plus a trailing control is what wants+ // the auto margin), and `renderOption` content is not wrapped in a growing+ // span, so the margin has to live on the checkbox itself.+ checkboxDecorativeEnd: {+ marginInlineStart: 'auto',+ },// Label text for items (rendered outside checkbox for correct click// behavior). Typography is inherited from the row; this only handles@@ -595,6 +604,13 @@ export interface MultiSelectorProps<*/renderOption?: (option: MultiSelectorOptionData) => ReactNode;+ /**+ * Which edge of the option row carries the checkbox.+ *+ * @default 'start'+ */+ indicatorPosition?: IndicatorPosition;+/*** Whether the dropdown starts open on mount.* Useful for showcases and previews.@@ -680,6 +696,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({triggerDisplay = 'count',maxBadges = 3,renderOption,+ indicatorPosition = 'start',isDefaultOpen = false,'data-testid': testId,htmlName,@@ -1222,6 +1239,24 @@ export function MultiSelector<T extends MultiSelectorOptionType>({const isPartiallySelected =isSelectAll && selectAllState === 'indeterminate';+ const checkbox = (+ <div+ inert+ {...stylex.props(+ styles.checkboxDecorative,+ indicatorPosition === 'end' && styles.checkboxDecorativeEnd,+ )}>+ <CheckboxInput+ label=""+ isLabelHidden+ value={checkboxValue}+ onChange={() => {}}+ isDisabled={item.disabled}+ size={size === 'lg' ? 'md' : size}+ />+ </div>+ );+return (<divkey={item.value}@@ -1261,16 +1296,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({item.disabled && styles.itemDisabled,),)}>- <div inert {...stylex.props(styles.checkboxDecorative)}>- <CheckboxInput- label=""- isLabelHidden- value={checkboxValue}- onChange={() => {}}- isDisabled={item.disabled}- size={size === 'lg' ? 'md' : size}- />- </div>+ {indicatorPosition === 'start' && checkbox}{renderOption && !isSelectAll ? (renderOption(item)) : (@@ -1278,11 +1304,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({{item.label ?? item.value}</span>)}+ {indicatorPosition === 'end' && checkbox}</div>);},[renderOption,+ indicatorPosition,highlightedIndex,optimisticValue,allEnabledSelected,diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex ebdeccbae3..26539b5f9e 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -156,6 +156,13 @@ export const docs = {description:'Custom render function for each selectable option in the dropdown. Use this instead of JSX children; dividers and sections are rendered by the selector.',},+ {+ name: 'indicatorPosition',+ type: "'start' | 'end'",+ description:+ 'Which edge of the option row carries the selected mark. start reserves a mark column ahead of every label so they stay aligned, the way a native menu does; end is the house convention shared with Typeahead and CommandPalette.',+ default: "'end'",+ },{name: 'width',type: 'SizeValue',diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsxindex 68ea918b04..7bea620380 100644--- a/packages/core/src/Selector/Selector.test.tsx+++ b/packages/core/src/Selector/Selector.test.tsx@@ -2634,3 +2634,108 @@ describe('Selector disabled state theme target', () => {expect(css).toContain('opacity: 0.4');});});++describe('Selector indicatorPosition', () => {+ const openRows = (): HTMLElement[] => screen.getAllByRole('option', h);+ const rowFor = (label: string): HTMLElement =>+ openRows().find(row => row.textContent?.includes(label))!;++ it('draws the mark after the option content by default', () => {+ render(+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ isDefaultOpen+ />,+ );+ const row = rowFor('Banana');+ const mark = row.querySelector('.astryx-selector-check')!;+ const content = row.querySelector('.astryx-selector-option')!;+ expect(+ content.compareDocumentPosition(mark) & Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ });++ it('draws the mark before the option content when set to start', () => {+ render(+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ indicatorPosition="start"+ isDefaultOpen+ />,+ );+ const row = rowFor('Banana');+ const mark = row.querySelector('.astryx-selector-check')!;+ const content = row.querySelector('.astryx-selector-option')!;+ expect(+ content.compareDocumentPosition(mark) & Node.DOCUMENT_POSITION_PRECEDING,+ ).toBeTruthy();+ });++ it('reserves the mark column on every row, at either position', () => {+ // The default check draws nothing when unchecked, so without a reserved+ // column the chosen row would be laid out differently from the rest —+ // indented at the start, truncating earlier at the end. Every row is two+ // children wide either way, so a row's geometry does not depend on whether+ // it happens to be the chosen one.+ const {unmount} = render(+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ indicatorPosition="start"+ isDefaultOpen+ />,+ );+ for (const row of openRows()) {+ expect(row.children).toHaveLength(2);+ }+ unmount();++ render(+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ isDefaultOpen+ />,+ );+ for (const row of openRows()) {+ expect(row.children).toHaveLength(2);+ }+ });++ it('positions a themed replacement indicator the same way', () => {+ const theme = defineTheme({+ name: 'selector-start-radio-mark-test',+ indicators: {check: RadioIndicator},+ });+ render(+ <Theme theme={theme}>+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ indicatorPosition="start"+ isDefaultOpen+ />+ </Theme>,+ );+ for (const row of openRows()) {+ const radio = row.querySelector('.astryx-radio')!;+ const content = row.querySelector('.astryx-selector-option')!;+ expect(+ content.compareDocumentPosition(radio) &+ Node.DOCUMENT_POSITION_PRECEDING,+ ).toBeTruthy();+ }+ });+});diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsxindex 0546b8185e..1d50dd1255 100644--- a/packages/core/src/Selector/Selector.tsx+++ b/packages/core/src/Selector/Selector.tsx@@ -33,6 +33,7 @@ import {usePopover} from '../Popover/usePopover';import {useTooltip} from '../Tooltip';import {Icon, renderIconSlot, type IconType} from '../Icon';import {useIndicator} from '../Indicator';+import type {IndicatorPosition} from '../Indicator';import type {IconName} from '../Icon';import {Field,@@ -289,6 +290,19 @@ const styles = stylex.create({flex: 1,minWidth: 0,},+ // The mark's column, reserved on every row and at either position, so a row+ // occupies the same geometry whether or not it is the chosen one — the+ // default check draws nothing when unchecked, and without the column a list+ // would indent (or truncate) its chosen row differently from the rest.+ // `minWidth` rather than `width`: a theme can replace `check` with a larger+ // indicator (a radio is 20px at `sm`), and the column has to grow with it.+ itemMarkColumn: {+ display: 'inline-flex',+ alignItems: 'center',+ justifyContent: 'center',+ flexShrink: 0,+ minWidth: '1rem',+ },itemCheckmark: {flexShrink: 0,width: 16,@@ -506,6 +520,16 @@ interface SelectorPropsBase<*/renderOption?: (option: SelectorOptionData) => ReactNode;+ /**+ * Which edge of the option row carries the selected mark. `start` reserves a+ * mark column ahead of every label so they stay aligned, the way a native+ * menu does; `end` is the house convention shared with Typeahead and+ * CommandPalette.+ *+ * @default 'end'+ */+ indicatorPosition?: IndicatorPosition;+/*** Whether to show a search input for filtering options.* @default false@@ -656,6 +680,7 @@ export function Selector<T extends SelectorOptionType>(startIcon,htmlName,renderOption,+ indicatorPosition = 'end',hasSearch = false,searchPlaceholder: searchPlaceholderFromProps,placement,@@ -1076,6 +1101,45 @@ export function Selector<T extends SelectorOptionType>(const isHighlighted = flatIndex === highlightedIndex;const isSelected = item.value === normalizedValue;+ /*+ * Rendered UNCONDITIONALLY, with the state passed down: the default+ * check draws nothing when unchecked, but a theme that replaces the+ * `check` indicator with a radio needs the unselected state to draw+ * its empty circle. `{isSelected && …}` would make that impossible.+ *+ * `selector-check` stays the stable target for the mark's position+ * in the row; the indicator owns what the mark looks like.+ */+ const mark = (+ <span {...stylex.props(styles.itemMarkColumn)}>+ <SelectionMark+ state={isSelected ? 'checked' : 'unchecked'}+ size="sm"+ isDisabled={item.disabled ?? false}+ {...themeProps('selector-check')}+ />+ </span>+ );++ const optionContent = (+ <span {...stylex.props(styles.itemContent)}>+ {renderOption ? renderOption(item) : <DefaultOption option={item} />}+ </span>+ );++ const content =+ indicatorPosition === 'start' ? (+ <>+ {mark}+ {optionContent}+ </>+ ) : (+ <>+ {optionContent}+ {mark}+ </>+ );+return (<divkey={item.value}@@ -1092,33 +1156,13 @@ export function Selector<T extends SelectorOptionType>(isSelected && styles.itemSelected,item.disabled && styles.itemDisabled,)}>- <span {...stylex.props(styles.itemContent)}>- {renderOption ? (- renderOption(item)- ) : (- <DefaultOption option={item} />- )}- </span>- {/*- * Rendered UNCONDITIONALLY, with the state passed down: the default- * check draws nothing when unchecked, but a theme that replaces the- * `check` indicator with a radio needs the unselected state to draw- * its empty circle. `{isSelected && …}` would make that impossible.- *- * `selector-check` stays the stable target for the mark's position- * in the row; the indicator owns what the mark looks like.- */}- <SelectionMark- state={isSelected ? 'checked' : 'unchecked'}- size="sm"- isDisabled={item.disabled ?? false}- {...themeProps('selector-check')}- />+ {content}</div>);},[renderOption,+ indicatorPosition,highlightedIndex,size,normalizedValue,