@astryxdesign/core 0.5.0 → 0.5.1-canary.f64186a

package/src/Carousel/Carousel.tsx

@@ -176,12 +176,6 @@ const styles = stylex.create({
     },
     scrollbarWidth: 'none',
     maskImage: 'none',
-    transitionProperty: 'mask-image',
-    transitionDuration: {
-      default: durationVars['--duration-medium'],
-      '@media (prefers-reduced-motion: reduce)': '0ms',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
   },
   fadeStart: {
     maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
@@ -341,6 +335,13 @@ export function Carousel({
   const t = useTranslator();
   const ariaLabel = ariaLabelFromProps ?? t('@astryx.carousel.label');
   const scrollElRef = useRef<HTMLElement | null>(null);
+  const startButtonRef = useRef<HTMLButtonElement>(null);
+  const endButtonRef = useRef<HTMLButtonElement>(null);
+  // Which nav button last held focus, and what the overflow state was on the
+  // previous render. Together they are how the Effect below recognises the one
+  // transition it is allowed to act on.
+  const focusedNavRef = useRef<'start' | 'end' | null>(null);
+  const prevCanScrollRef = useRef<{start: boolean; end: boolean} | null>(null);
   const {scrollRef, overflowStart, overflowEnd, hasOverflow} =
     useScrollOverflow();
 
@@ -487,6 +488,76 @@ export function Carousel({
   const canScrollStart = hasLoop && hasOverflow ? true : overflowStart;
   const canScrollEnd = hasLoop && hasOverflow ? true : overflowEnd;
 
+  // Keep the keyboard user where they are when a nav button disables under
+  // them. The browser drops focus off a control it disables, so reaching an
+  // edge used to land the user on <body> and cost them their place in the page.
+  //
+  // This is an Effect on purpose, and the exception is narrow. The thing that
+  // disables the button IS this state transition, so it is the only correct
+  // trigger: three attempts to predict it from the press -- the position after
+  // the scroll, the position before it plus the step, and the settled position
+  // reported by `scrollend` -- were each wrong somewhere, under reduced motion,
+  // under mandatory scroll-snap, and on a browser that never fires the event.
+  // Running after the commit also makes the opposite button a valid receiver,
+  // which it is not during the press: at that moment it is still disabled and
+  // focus() on a disabled control does nothing. Ruled acceptable by the
+  // maintainer, 2026-08-27, on the conditions encoded below: it acts only on
+  // the transition that newly disables the focused button, it moves focus and
+  // nothing else, and it cannot fire twice for one transition.
+  //
+  // Which button the person is on is tracked by the buttons' own focus and blur
+  // handlers, and the blur has to ignore the one the commit itself causes: a
+  // tracker that outlived the person let a later edge -- a swipe, a resize, no
+  // press at all -- pull their focus back onto a control they never chose.
+  useEffect(() => {
+    const previous = prevCanScrollRef.current;
+    prevCanScrollRef.current = {start: canScrollStart, end: canScrollEnd};
+    const side = focusedNavRef.current;
+    if (previous == null || side == null) {
+      return;
+    }
+
+    // Only the edge that just ran out, and only while it held focus. An edge
+    // that was already disabled, or one the user was not on, is not ours.
+    const wasEnabled = side === 'start' ? previous.start : previous.end;
+    const isEnabled = side === 'start' ? canScrollStart : canScrollEnd;
+    if (!wasEnabled || isEnabled) {
+      return;
+    }
+
+    const pressed =
+      side === 'start' ? startButtonRef.current : endButtonRef.current;
+    if (pressed == null) {
+      return;
+    }
+    // The browser has already blurred it, so focus reads as the body. Anything
+    // else means the user moved on themselves and this is not ours to redirect.
+    const active = pressed.ownerDocument.activeElement;
+    if (active !== pressed && active !== pressed.ownerDocument.body) {
+      return;
+    }
+
+    const opposite =
+      side === 'start' ? endButtonRef.current : startButtonRef.current;
+    // The opposite button is the receiver. It is disabled only when the
+    // carousel stopped overflowing entirely, which happens when its content
+    // shrinks; the scroll container is then the nearest tab stop still inside
+    // the labelled region.
+    const receiver =
+      opposite != null && !opposite.disabled ? opposite : scrollElRef.current;
+    if (receiver == null) {
+      return;
+    }
+
+    // One move per transition: clearing the tracker first means a re-render or
+    // a StrictMode double-invoke re-runs this and returns at the `side == null`
+    // guard above. Focusing the receiver sets it again, to the other side.
+    focusedNavRef.current = null;
+    // preventScroll: a plain focus() scrolls its element into view, which on
+    // the scroll container cancels the scroll the press just started.
+    receiver.focus({preventScroll: true});
+  }, [canScrollStart, canScrollEnd]);
+
   const fadeStyle = hasEdgeFade
     ? (hasLoop && hasOverflow) || (overflowStart && overflowEnd)
       ? styles.fadeBoth
@@ -523,12 +594,20 @@ export function Carousel({
         ref={composedRef}
         tabIndex={0}
         onWheel={handleWheel}
-        {...stylex.props(
-          styles.scroller,
-          gapStyles[gap],
-          padding != null && paddingStyles[padding],
-          hasSnap && styles.snap,
-          fadeStyle,
+        {...mergeProps(
+          themeProps('carousel-scroller', {
+            gap,
+            padding,
+            snap: hasSnap ? 'snap' : null,
+            edgeFade: hasEdgeFade ? 'edge-fade' : null,
+          }),
+          stylex.props(
+            styles.scroller,
+            gapStyles[gap],
+            padding != null && paddingStyles[padding],
+            hasSnap && styles.snap,
+            fadeStyle,
+          ),
         )}>
         {slides.map((child, index) => (
           // APG carousel pattern: each slide container is a group with
@@ -560,6 +639,7 @@ export function Carousel({
                 !canScrollStart && styles.buttonHidden,
               )}>
               <Button
+                ref={startButtonRef}
                 icon={
                   <Icon
                     icon="chevronLeft"
@@ -572,10 +652,21 @@ export function Carousel({
                 size="sm"
                 isIconOnly
                 // Disabled when there's nothing to scroll toward. Keeps the
-                // button mounted (stable layout/focus) but removes it from the
-                // tab order and a11y tree while it's visually hidden, so
-                // keyboard users don't land on an invisible control.
+                // button mounted (stable layout) but removes it from the tab
+                // order and a11y tree while it's visually hidden, so keyboard
+                // users don't land on an invisible control. The Effect above
+                // hands focus to the other button when the state behind this
+                // one flips it disabled.
                 isDisabled={!canScrollStart}
+                onFocus={() => {
+                  focusedNavRef.current = 'start';
+                }}
+                onBlur={event => {
+                  // A disabled button was blurred by the commit, not the person.
+                  if (!event.currentTarget.disabled) {
+                    focusedNavRef.current = null;
+                  }
+                }}
                 onClick={() => scrollBy(-1)}
                 xstyle={styles.buttonRadiusOverride}
               />
@@ -587,6 +678,7 @@ export function Carousel({
                 !canScrollEnd && styles.buttonHidden,
               )}>
               <Button
+                ref={endButtonRef}
                 icon={
                   <Icon
                     icon="chevronRight"
@@ -601,6 +693,15 @@ export function Carousel({
                 // See "Scroll left" — disabled while visually hidden so the
                 // button stays mounted but out of the tab order / a11y tree.
                 isDisabled={!canScrollEnd}
+                onFocus={() => {
+                  focusedNavRef.current = 'end';
+                }}
+                onBlur={event => {
+                  // A disabled button was blurred by the commit, not the person.
+                  if (!event.currentTarget.disabled) {
+                    focusedNavRef.current = null;
+                  }
+                }}
                 onClick={() => scrollBy(1)}
                 xstyle={styles.buttonRadiusOverride}
               />

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -133,6 +133,7 @@ export const docs = {
       {className: 'astryx-checkbox-input', visualProps: ['size']},
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
   usage: {
@@ -209,6 +210,7 @@ export const docsZh = {
       },
       {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},
       {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},
+      {className: 'astryx-checkbox-label'},
     ],
   },
 };

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -719,3 +719,18 @@ describe('focus ring ownership (WCAG 2.4.7)', () => {
     expect(indicatorOf(container).style.outlineStyle).toBe('');
   });
 });
+
+describe('label theme target', () => {
+  it('names its own label so a theme can style it apart from a field label', () => {
+    // The control knows this label shares a row with it; the label does not.
+    // Both classes land on the one element, so a theme reaches every label
+    // through `astryx-field-label` and only this kind through
+    // `astryx-checkbox-label`.
+    render(
+      <CheckboxInput label="Notify me" value={false} onChange={() => {}} />,
+    );
+    const label = screen.getByText('Notify me').closest('label');
+    expect(label).toHaveClass('astryx-field-label');
+    expect(label).toHaveClass('astryx-checkbox-label');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -478,6 +478,11 @@ export function CheckboxInput({
         </div>
         <div {...stylex.props(styles.labelWrapper)}>
           <FieldLabel
+            // A checkbox's label shares a row with its control, unlike a form
+            // field's label above its input. Naming the label rather than the
+            // arrangement means a theme asks for the thing it wants, and the
+            // component that actually knows what this is says so.
+            {...themeProps('checkbox-label')}
             label={label}
             inputID={id}
             isLabelHidden={isLabelHidden}

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -147,10 +147,16 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-code', visualProps: ['color']},
-      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container']},
-      {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
-      {className: 'astryx-codeblock-copy-button'},
+      {className: 'astryx-code-block', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-header', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-code-block-title', visualProps: ['size', 'language']},
+      {className: 'astryx-code-block-copy-button'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block'},
+      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block-header'},
+      {className: 'astryx-codeblock-title', visualProps: ['size', 'language'], deprecatedFor: 'code-block-title'},
+      {className: 'astryx-codeblock-copy-button', deprecatedFor: 'code-block-copy-button'},
     ],
     vars: [
       {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},

package/src/CodeBlock/CodeBlock.test.tsx

@@ -396,3 +396,40 @@ describe('CodeBlock', () => {
     });
   });
 });
+
+describe('CodeBlock theme target names', () => {
+  it('renders the deprecated classes beside the current ones', () => {
+    const {container} = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        title="example.js"
+      />,
+    );
+    expect(container.querySelector('.astryx-code-block')).toHaveClass(
+      'astryx-codeblock',
+    );
+    expect(container.querySelector('.astryx-code-block-header')).toHaveClass(
+      'astryx-codeblock-header',
+    );
+    expect(container.querySelector('.astryx-code-block-title')).toHaveClass(
+      'astryx-codeblock-title',
+    );
+    expect(screen.getByRole('button', {name: 'Copy code'})).toHaveClass(
+      'astryx-code-block-copy-button',
+    );
+  });
+
+  it('reaches the header and title through the current defineTheme keys', () => {
+    const theme = defineTheme({
+      name: 'code-block-header-target-test',
+      components: {
+        'code-block-header': {base: {paddingBlock: 'var(--spacing-1)'}},
+        'code-block-title': {base: {fontSize: 'var(--text-body-size)'}},
+      },
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('.astryx-code-block-header');
+    expect(css).toContain('.astryx-code-block-title');
+  });
+});

package/src/CodeBlock/CodeBlock.tsx

@@ -810,14 +810,20 @@ export function CodeBlock({
         void handleCopy();
       }}
       xstyle={[styles.copyButton, !showHeader && styles.copyButtonAbsolute]}
-      {...themeProps('codeblock-copy-button')}
+      {...themeProps('code-block-copy-button', undefined, {
+        legacyNames: ['codeblock-copy-button'],
+      })}
     />
   ) : null;
 
   const headerEl = showHeader ? (
     <div
       {...mergeProps(
-        themeProps('codeblock-header', {size, language, container}),
+        themeProps(
+          'code-block-header',
+          {size, language, container},
+          {legacyNames: ['codeblock-header']},
+        ),
         stylex.props(
           styles.headerRow,
           hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
@@ -845,7 +851,11 @@ export function CodeBlock({
         )}>
         <span
           {...mergeProps(
-            themeProps('codeblock-title', {size, language}),
+            themeProps(
+              'code-block-title',
+              {size, language},
+              {legacyNames: ['codeblock-title']},
+            ),
             stylex.props(styles.headerTitle),
           )}>
           {canCollapse && (
@@ -917,7 +927,13 @@ export function CodeBlock({
     <pre
       ref={ref}
       {...mergeProps(
-        themeProps('codeblock', {size, language, container}),
+        themeProps(
+          'code-block',
+          {size, language, container},
+          // `codeblock` ran the compound name together; themes styling it keep
+          // working until the next major.
+          {legacyNames: ['codeblock']},
+        ),
         stylex.props(
           styles.root,
           dynamicStyles.width(widthProp),

package/src/CodeBlock/highlightRanges.ts

@@ -67,7 +67,7 @@ function ensureDynamicHighlightType(tokenType: string): void {
   const name = `astryx-${tokenType}`;
   const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;
   dynamicStyleSheet.insertRule(
-    `.astryx-codeblock code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
+    `.astryx-code-block code::highlight(${name}), .astryx-codeeditor code::highlight(${name}) { color: ${colorVar}; }`,
   );
 }
 

package/src/CodeBlock/highlightStyles.ts

@@ -30,31 +30,31 @@ const FALLBACK_TOKENS = `:root {\n${Object.entries(syntaxTokenDefaults)
 const HIGHLIGHT_STYLES = `
 ${FALLBACK_TOKENS}
 
-.astryx-codeblock code::highlight(astryx-keyword),
+.astryx-code-block code::highlight(astryx-keyword),
 .astryx-codeeditor code::highlight(astryx-keyword) { color: var(--color-syntax-keyword); }
-.astryx-codeblock code::highlight(astryx-string),
+.astryx-code-block code::highlight(astryx-string),
 .astryx-codeeditor code::highlight(astryx-string) { color: var(--color-syntax-string); }
-.astryx-codeblock code::highlight(astryx-comment),
+.astryx-code-block code::highlight(astryx-comment),
 .astryx-codeeditor code::highlight(astryx-comment) { color: var(--color-syntax-comment); }
-.astryx-codeblock code::highlight(astryx-number),
+.astryx-code-block code::highlight(astryx-number),
 .astryx-codeeditor code::highlight(astryx-number) { color: var(--color-syntax-number); }
-.astryx-codeblock code::highlight(astryx-function),
+.astryx-code-block code::highlight(astryx-function),
 .astryx-codeeditor code::highlight(astryx-function) { color: var(--color-syntax-function); }
-.astryx-codeblock code::highlight(astryx-type),
+.astryx-code-block code::highlight(astryx-type),
 .astryx-codeeditor code::highlight(astryx-type) { color: var(--color-syntax-type); }
-.astryx-codeblock code::highlight(astryx-tag),
+.astryx-code-block code::highlight(astryx-tag),
 .astryx-codeeditor code::highlight(astryx-tag) { color: var(--color-syntax-tag); }
-.astryx-codeblock code::highlight(astryx-attribute),
+.astryx-code-block code::highlight(astryx-attribute),
 .astryx-codeeditor code::highlight(astryx-attribute) { color: var(--color-syntax-attribute); }
-.astryx-codeblock code::highlight(astryx-property),
+.astryx-code-block code::highlight(astryx-property),
 .astryx-codeeditor code::highlight(astryx-property) { color: var(--color-syntax-property); }
-.astryx-codeblock code::highlight(astryx-operator),
+.astryx-code-block code::highlight(astryx-operator),
 .astryx-codeeditor code::highlight(astryx-operator) { color: var(--color-syntax-operator); }
-.astryx-codeblock code::highlight(astryx-constant),
+.astryx-code-block code::highlight(astryx-constant),
 .astryx-codeeditor code::highlight(astryx-constant) { color: var(--color-syntax-constant); }
-.astryx-codeblock code::highlight(astryx-punctuation),
+.astryx-code-block code::highlight(astryx-punctuation),
 .astryx-codeeditor code::highlight(astryx-punctuation) { color: var(--color-syntax-punctuation); }
-.astryx-codeblock code::highlight(astryx-variable),
+.astryx-code-block code::highlight(astryx-variable),
 .astryx-codeeditor code::highlight(astryx-variable) { color: var(--color-syntax-variable); }
 
 /* Span-based fallback classes — used when highlightMode='spans' or

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -26,9 +26,9 @@ import {
 import {useCommandPaletteContext} from './CommandPaletteContext';
 import {useDialogContext} from '../Dialog/DialogContext';
 import {themeProps} from '../utils/themeProps';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
-const HOVER_HOVER = '@media (hover: hover)';
 
 const styles = stylex.create({
   item: {
@@ -52,16 +52,6 @@ const styles = stylex.create({
     outline: 'none',
     userSelect: 'none',
   },
-  itemHover: {
-    ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-      [HOVER_HOVER]: {
-        backgroundColor: colorVars['--color-overlay-hover'],
-      },
-    },
-    ':active': {
-      backgroundColor: colorVars['--color-overlay-pressed'],
-    },
-  },
   itemHighlighted: {
     backgroundColor: colorVars['--color-overlay-hover'],
   },
@@ -205,7 +195,7 @@ export function CommandPaletteItem({
         themeProps('command-palette-item'),
         stylex.props(
           styles.item,
-          !isDisabled && styles.itemHover,
+          !isDisabled && interactionOverlayStyles.backgroundColor,
           isHighlighted && styles.itemHighlighted,
           isSelected && styles.itemSelected,
           isDisabled && styles.itemDisabled,

package/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.',
   },

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -353,6 +353,7 @@ describe('ComplexSelector', () => {
       .closest('[popover]');
     expect(popover).not.toBeNull();
 
+    fireEvent.pointerDown(trigger);
     const closeEvent = new Event('toggle');
     Object.defineProperty(closeEvent, 'newState', {value: 'closed'});
     fireEvent(popover as HTMLElement, closeEvent);
@@ -417,4 +418,186 @@ describe('ComplexSelector popup theme target', () => {
       document.querySelector('.astryx-complex-selector-popup'),
     ).not.toBeNull();
   });
+
+  it('stays closed when the trigger click follows its own light dismiss (#5004)', async () => {
+    const user = userEvent.setup();
+    render(
+      <ComplexSelector label="Fruit blend" value="Apple" triggerLabel="Apple">
+        {() => <button type="button">Done</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    // The browser dismissed the popup on pointerup and queued the toggle. When
+    // that event lands before the click — WebKit, or any engine under load —
+    // the click used to read a closed popup and reopen it.
+    fireEvent.pointerDown(trigger);
+    const popover = document.querySelector('[popover]') as HTMLElement;
+    act(() => {
+      popover.dispatchEvent(
+        Object.assign(new Event('toggle'), {
+          oldState: 'open',
+          newState: 'closed',
+        }),
+      );
+    });
+    // Synchronously: the click falls inside the one gesture the guard covers,
+    // as it does in a browser a few milliseconds behind the dismissal.
+    fireEvent.click(trigger);
+
+    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]]);
+  });
 });