An open source design system that's fully customizable and agent ready
TypeScript
feat(core): ComplexSelector reports its open state with onOpenChange (#5211)
Cindy Zhang7a931cfb675a
diff --git a/.changeset/complexselector-onopenchange.md b/.changeset/complexselector-onopenchange.mdnew file mode 100644index 0000000000..53a62a1aa6--- /dev/null+++ b/.changeset/complexselector-onopenchange.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] ComplexSelector: `onOpenChange` reports every open and close of the popup — the trigger, the keyboard, a light dismiss, Escape, content calling `close()`, or the imperative handle. Paired with the existing `handleRef`, a consumer can drive and observe the surface without reading the shell's DOM.++@cixzhangdiff --git a/apps/storybook/stories/ComplexSelector.stories.tsx b/apps/storybook/stories/ComplexSelector.stories.tsxindex ca87baf78c..45dc0bcdc9 100644--- a/apps/storybook/stories/ComplexSelector.stories.tsx+++ b/apps/storybook/stories/ComplexSelector.stories.tsx@@ -764,6 +764,7 @@ export const ControlledToolbarTrigger: Story = {name: 'Controlled toolbar trigger',render: () => {const [density, setDensity] = useState<ViewDensity>('Comfortable');+ const [isOpen, setIsOpen] = useState(false);const selectorRef = useRef<ComplexSelectorHandle>(null);return (@@ -779,6 +780,7 @@ export const ControlledToolbarTrigger: Story = {isLabelHiddenvalue={density}onChange={setDensity}+ onOpenChange={setIsOpen}triggerLabel={`Density: ${density}`}variant="ghost"startIcon="viewColumns"@@ -790,7 +792,8 @@ export const ControlledToolbarTrigger: Story = {<Text type="supporting" color="secondary">The selector owns visibility. An external control drives itimperatively via handleRef; choosing a density commits the value- and closes the surface.+ and closes the surface. onOpenChange reports every open and+ close, including the ones the selector performs itself.</Text><HStack gap={2}>{(['Comfortable', 'Compact'] as const).map(option => (@@ -811,6 +814,9 @@ export const ControlledToolbarTrigger: Story = {</VStack>)}</ComplexSelector>+ <Text type="supporting" color="secondary" data-testid="open-state">+ {isOpen ? 'open' : 'closed'}+ </Text></div>);},diff --git a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjsindex 7e632d4e22..3bac2209eb 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs+++ b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs@@ -143,6 +143,12 @@ export const docs = {description:'Imperative handle for programmatic control. Exposes open(), close(), toggle(), and isOpen().',},+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description:+ 'Called whenever the surface opens or closes, however it happened — trigger, keyboard, light dismiss, Escape, close(), or the imperative handle.',+ },{name: 'contentXstyle',type: 'StyleXStyles',@@ -274,6 +280,7 @@ export const docsDense = {placement: 'Popup placement.',alignment: 'Popup alignment.',handleRef: 'Imperative open/close/toggle handle.',+ onOpenChange: 'Notified on every open and close, whatever caused it.',accessibility:'Custom content must provide its own accessible structure. Use focus hooks and evaluate against WCAG 2.2.',},diff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsxindex 73cf3ec02c..be89e21d93 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx@@ -450,3 +450,154 @@ describe('ComplexSelector popup theme target', () => {expect(trigger).toHaveAttribute('aria-expanded', 'false');});});++describe('ComplexSelector onOpenChange', () => {+ function renderSelector(onOpenChange: (isOpen: boolean) => void) {+ render(+ <ComplexSelector+ label="View options"+ value={[]}+ onOpenChange={onOpenChange}>+ {(_value, _onChange, close) => (+ <button type="button" onClick={close}>+ Apply+ </button>+ )}+ </ComplexSelector>,+ );+ return screen.getByRole('button', {name: 'View options'});+ }++ it('reports the open and the close of a trigger toggle', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ await user.click(trigger);+ expect(onOpenChange.mock.calls).toEqual([[true]]);++ await user.click(trigger);+ expect(onOpenChange.mock.calls).toEqual([[true], [false]]);+ });++ it('reports an open from ArrowDown', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ trigger.focus();+ await user.keyboard('{ArrowDown}');++ expect(onOpenChange.mock.calls).toEqual([[true]]);+ });++ it('reports a close from Escape', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ await user.click(trigger);+ onOpenChange.mockClear();+ await user.keyboard('{Escape}');++ expect(onOpenChange.mock.calls).toEqual([[false]]);+ });++ it('reports a close the browser performed (light dismiss)', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ await user.click(trigger);+ onOpenChange.mockClear();++ const popover = screen+ .getByRole('dialog', {hidden: true})+ .closest('[popover]') as HTMLElement;+ const closeEvent = new Event('toggle');+ Object.defineProperty(closeEvent, 'newState', {value: 'closed'});+ fireEvent(popover, closeEvent);++ expect(onOpenChange.mock.calls).toEqual([[false]]);+ });++ it('reports a gesture light dismiss once without reopening from its click', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ await user.click(trigger);+ onOpenChange.mockClear();++ const popover = screen+ .getByRole('dialog', {hidden: true})+ .closest('[popover]') as HTMLElement;+ fireEvent.pointerDown(trigger);+ fireEvent(+ popover,+ Object.assign(new Event('toggle'), {+ oldState: 'open',+ newState: 'closed',+ }),+ );+ fireEvent.click(trigger);++ expect(onOpenChange.mock.calls).toEqual([[false]]);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('reports a close from content calling close()', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const trigger = renderSelector(onOpenChange);++ await user.click(trigger);+ onOpenChange.mockClear();+ await user.click(screen.getByRole('button', {name: 'Apply', ...h}));++ expect(onOpenChange.mock.calls).toEqual([[false]]);+ });++ it('reports opens and closes driven through the imperative handle', () => {+ const onOpenChange = vi.fn();+ const handleRef = React.createRef<ComplexSelectorHandle>();+ render(+ <ComplexSelector+ label="View options"+ value={[]}+ handleRef={handleRef}+ onOpenChange={onOpenChange}>+ {() => <button type="button">Apply</button>}+ </ComplexSelector>,+ );++ act(() => handleRef.current?.open());+ act(() => handleRef.current?.close());+ act(() => handleRef.current?.toggle());++ expect(onOpenChange.mock.calls).toEqual([[true], [false], [true]]);+ });++ it('does not report a state it is already in', async () => {+ const user = userEvent.setup();+ const onOpenChange = vi.fn();+ const handleRef = React.createRef<ComplexSelectorHandle>();+ render(+ <ComplexSelector+ label="View options"+ value={[]}+ handleRef={handleRef}+ onOpenChange={onOpenChange}>+ {() => <button type="button">Apply</button>}+ </ComplexSelector>,+ );+ const trigger = screen.getByRole('button', {name: 'View options'});++ act(() => handleRef.current?.close());+ expect(onOpenChange).not.toHaveBeenCalled();++ await user.click(trigger);+ act(() => handleRef.current?.open());+ expect(onOpenChange.mock.calls).toEqual([[true]]);+ });+});diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsxindex 2ab4af58d4..c8104e375e 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.tsx+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx@@ -209,7 +209,8 @@ export interface ComplexSelectorRenderState {* they respect focus restoration, light dismiss, and Escape. Prefer these* callbacks over mirroring open state in the parent — the selector owns its* visibility, and imperative calls avoid the focus-management pitfalls of- * syncing an external `isOpen` prop.+ * syncing an external `isOpen` prop. Pair with `onOpenChange` to observe every+ * open and close, including the ones the selector performs itself.*/export interface ComplexSelectorHandle {/** Open the selector surface. No-op when disabled or already open. */@@ -286,6 +287,13 @@ export interface ComplexSelectorProps<Value> extends Omit<* state in the parent — the selector owns its visibility.*/handleRef?: React.Ref<ComplexSelectorHandle>;+ /**+ * Called whenever the selector surface opens or closes, however it happened+ * — the trigger, the keyboard, a light dismiss, Escape, content that calls+ * `close()`, or the imperative handle. Pair it with `handleRef` to drive the+ * surface from outside without mirroring its state.+ */+ onOpenChange?: (isOpen: boolean) => void;/** StyleX styles for the popup content container. */contentXstyle?: StyleXStyles;/** Test ID for the trigger container. */@@ -343,6 +351,7 @@ export function ComplexSelector<Value>({placement = 'below',alignment = 'start',handleRef,+ onOpenChange,contentXstyle,xstyle,className,@@ -378,15 +387,23 @@ export function ComplexSelector<Value>({const [optimisticValue, setOptimisticValue] = useOptimistic(value);const isBusy = isLoading || isPending;+ const handlePopoverShow = useCallback(() => {+ onOpenChange?.(true);+ }, [onOpenChange]);+const handlePopoverHide = useCallback(() => {+ // Focus is restored first so a consumer that moves focus elsewhere from+ // the callback wins, instead of being overwritten a line later.triggerRef.current?.focus();- }, []);+ onOpenChange?.(false);+ }, [onOpenChange]);const popover = usePopover({dialogLabel: label,hasCloseButton: false,hasAutoFocus: true,surfaceTarget: 'complex-selector-popup',+ onShow: handlePopoverShow,onHide: handlePopoverHide,});