Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/storybook/stories/ComplexSelector.stories.tsx b/apps/storybook/stories/ComplexSelector.stories.tsx
index 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 = {
isLabelHidden
value={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 it
imperatively 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.mjs
index 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.tsx
index 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.tsx
index 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,
});