Skip to content

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

TypeScript

feat(core): Popover hasLightDismiss and hasEscapeDismiss props (#3526)

Md Shahrier Islam Arham9842da9d85b6
diff --git a/.changeset/popover-dismiss-controls.md b/.changeset/popover-dismiss-controls.md
new file mode 100644
index 0000000000..4eac02efe7
--- /dev/null
+++ b/.changeset/popover-dismiss-controls.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Popover: expose hasLightDismiss and add hasEscapeDismiss so consumers can opt out of outside-click and Escape dismissal for explicit-dismiss surfaces like onboarding coachmarks. usePopover accepts the same new hasEscapeDismiss option; with it off, no handler is registered on the shared Escape stack so the key falls through untouched (#3287)
+@arham766
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index c892952d31..10f3a3bd55 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -90,6 +90,18 @@ export const docs = {
description: 'Whether to auto-focus the first focusable element when the popover opens. Set to false for inline showcases or documentation previews.',
default: 'true',
},
+ {
+ name: 'hasLightDismiss',
+ type: 'boolean',
+ description: 'Whether clicking outside dismisses the popover. Set to false for surfaces that stay open until explicitly dismissed, like onboarding coachmarks.',
+ default: 'true',
+ },
+ {
+ name: 'hasEscapeDismiss',
+ type: 'boolean',
+ description: 'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss={false}, since native light dismiss also closes on Escape.',
+ default: 'true',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -219,6 +231,18 @@ export const docsZh = {
description: '弹出框打开时是否自动聚焦第一个可聚焦元素。内联展示或文档预览设为 false。',
default: 'true',
},
+ {
+ name: 'hasLightDismiss',
+ type: 'boolean',
+ description: '点击外部是否关闭弹出框。需要显式关闭的界面(如新手引导提示)设为 false。',
+ default: 'true',
+ },
+ {
+ name: 'hasEscapeDismiss',
+ type: 'boolean',
+ description: '按 Escape 是否关闭弹出框。仅在 hasLightDismiss={false} 时生效,因为原生 light dismiss 行为同样响应 Escape。',
+ default: 'true',
+ },
],
},
],
@@ -291,6 +315,8 @@ export const docsDense = {
hasCloseButton: 'Whether to include hidden close button for accessibility.',
closeButtonLabel: 'Label for hidden close button.',
hasAutoFocus: 'Auto-focus first element on open; false for showcases.',
+ hasLightDismiss: 'Outside click dismisses; false for explicit-dismiss surfaces (coachmarks).',
+ hasEscapeDismiss: 'Escape dismisses; full effect only with hasLightDismiss=false.',
},
},
],
diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsx
index d50d085fd5..3fd0837745 100644
--- a/packages/core/src/Popover/Popover.test.tsx
+++ b/packages/core/src/Popover/Popover.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import React, {useRef} from 'react';
import {Popover} from './Popover';
+import {Dialog} from '../Dialog';
// Store original matches to restore later
const originalMatches = HTMLElement.prototype.matches;
@@ -233,4 +234,124 @@ describe('Popover', () => {
);
warnSpy.mockRestore();
});
+
+ describe('dismiss controls', () => {
+ // jsdom does not implement <dialog> showModal/close, needed by the
+ // host-Dialog fall-through test below.
+ beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.setAttribute('open', '');
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.removeAttribute('open');
+ });
+ });
+
+ it('dismisses on Escape by default', () => {
+ render(
+ <Popover content={<span>Content</span>} label="Test">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Open'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.keyDown(document, {key: 'Escape'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('stays open on Escape when hasEscapeDismiss is false', () => {
+ render(
+ <Popover
+ content={<span>Content</span>}
+ label="Test"
+ hasLightDismiss={false}
+ hasEscapeDismiss={false}>
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Open'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.keyDown(document, {key: 'Escape'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('still dismisses on Escape when only light dismiss is off', () => {
+ render(
+ <Popover
+ content={<span>Content</span>}
+ label="Test"
+ hasLightDismiss={false}>
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Open'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.keyDown(document, {key: 'Escape'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('switches to popover="manual" when hasLightDismiss is false', () => {
+ const {unmount} = render(
+ <Popover content={<span>Content</span>} label="Test">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(document.querySelector('[popover]')).toHaveAttribute(
+ 'popover',
+ 'auto',
+ );
+ unmount();
+
+ render(
+ <Popover
+ content={<span>Content</span>}
+ label="Test"
+ hasLightDismiss={false}>
+ <button type="button">Open</button>
+ </Popover>,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(document.querySelector('[popover]')).toHaveAttribute(
+ 'popover',
+ 'manual',
+ );
+ });
+
+ it('lets Escape fall through to a host Dialog when fully opted out', () => {
+ const onDialogOpenChange = vi.fn();
+ render(
+ <Dialog isOpen={true} onOpenChange={onDialogOpenChange} purpose="info">
+ <Popover
+ content={<span>Coachmark</span>}
+ label="Tip"
+ hasLightDismiss={false}
+ hasEscapeDismiss={false}>
+ <button type="button">Open tip</button>
+ </Popover>
+ </Dialog>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Open tip'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ // The Dialog listens for Escape on the dialog element, so fire from a
+ // node inside it. The popover registers no Escape handler, so
+ // hasActiveFocusTrapEscape() is false and the Dialog handles the press
+ // while the popover itself stays open.
+ fireEvent.keyDown(trigger, {key: 'Escape'});
+ expect(onDialogOpenChange).toHaveBeenCalledWith(false);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+ });
});
diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsx
index 0dd027859b..b4cfff6d55 100644
--- a/packages/core/src/Popover/Popover.tsx
+++ b/packages/core/src/Popover/Popover.tsx
@@ -186,6 +186,24 @@ export interface PopoverProps extends Pick<
*/
hasAutoFocus?: boolean;
+ /**
+ * Whether clicking outside dismisses the popover.
+ * Set to `false` for surfaces that should stay open until explicitly
+ * dismissed, like onboarding coachmarks or multi-step flows.
+ * @default true
+ */
+ hasLightDismiss?: boolean;
+
+ /**
+ * Whether pressing Escape dismisses the popover.
+ *
+ * Only takes full effect together with `hasLightDismiss={false}`: with
+ * light dismiss on, the browser's native light dismiss also closes on
+ * Escape. Set both to `false` for explicit-dismiss-only surfaces.
+ * @default true
+ */
+ hasEscapeDismiss?: boolean;
+
/**
* Test ID for the popover container.
*/
@@ -239,7 +257,7 @@ const styles = stylex.create({
* (immune to pressed-state transforms like `:active { scale(0.98) }`).
*
* Focus is trapped inside the popover when open.
- * Supports light dismiss (click outside or Escape to close).
+ * Supports light dismiss by default (click outside or Escape to close).
*
* For hover-triggered overlays, use {@link HoverCard} instead.
*
@@ -277,6 +295,8 @@ export function Popover({
hasCloseButton,
closeButtonLabel,
hasAutoFocus,
+ hasLightDismiss = true,
+ hasEscapeDismiss = true,
xstyle,
className,
style,
@@ -299,7 +319,8 @@ export function Popover({
const popover = usePopover({
dialogLabel: label,
- hasLightDismiss: true,
+ hasLightDismiss,
+ hasEscapeDismiss,
hasCloseButton,
closeButtonLabel,
hasAutoFocus,
diff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjs
index 684f7d01c3..0368ca1964 100644
--- a/packages/core/src/Popover/usePopover.doc.mjs
+++ b/packages/core/src/Popover/usePopover.doc.mjs
@@ -11,6 +11,7 @@ export const docs = {
{name: 'onHide', type: '() => void', description: 'Callback fired when the popover is hidden. Use this to return focus to the trigger when needed.'},
{name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles applied to the popover content wrapper, after the default surface styles.'},
{name: 'hasLightDismiss', type: 'boolean', description: 'Whether clicking outside dismisses the popover.', default: 'true'},
+ {name: 'hasEscapeDismiss', type: 'boolean', description: 'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss: false, since native light dismiss also closes on Escape.', default: 'true'},
{name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},
{name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},
{name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},
@@ -53,6 +54,7 @@ export const docsDense = {
onHide: 'fires when popover hides; use to return focus when needed.',
xstyle: 'StyleX styles for content wrapper, after default surface.',
hasLightDismiss: 'whether outside click dismisses popover.',
+ hasEscapeDismiss: 'whether Escape dismisses; full effect only w/ hasLightDismiss false.',
hasAutoFocus: 'whether first focusable element receives focus on open.',
hasCloseButton: 'whether hidden keyboard close button is included.',
closeButtonLabel: 'label for hidden close button.',
diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsx
index d0ffd2b668..9f99588d22 100644
--- a/packages/core/src/Popover/usePopover.tsx
+++ b/packages/core/src/Popover/usePopover.tsx
@@ -109,6 +109,19 @@ export interface UsePopoverOptions {
*/
hasLightDismiss?: boolean;
+ /**
+ * Whether pressing Escape dismisses the popover.
+ *
+ * Takes effect together with `hasLightDismiss: false`: with light dismiss
+ * on, the native popover uses `popover="auto"`, whose browser-level light
+ * dismiss also closes on Escape, so Escape handling stays registered to
+ * keep topmost-only dismissal intact. Set both to `false` for
+ * explicit-dismiss-only surfaces like onboarding coachmarks.
+ *
+ * @default true
+ */
+ hasEscapeDismiss?: boolean;
+
/**
* Whether to automatically focus the first focusable element when opened.
* @default true
@@ -253,7 +266,7 @@ export interface UsePopoverReturn {
* - `useLayer` for popover positioning using CSS anchor positioning
* - `useFocusTrap` for trapping focus within the popover content
* - Auto-focus first element on open
- * - Escape key to close
+ * - Escape key to close (configurable via hasEscapeDismiss)
* - Hidden close button that reveals on focus for accessibility
*
* The render function automatically wraps your content in a focus trap container
@@ -286,14 +299,13 @@ export interface UsePopoverReturn {
* }
* ```
*/
-export function usePopover(
- options: UsePopoverOptions = {},
-): UsePopoverReturn {
+export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
const {
onShow,
onHide,
xstyle,
hasLightDismiss = true,
+ hasEscapeDismiss = true,
hasAutoFocus = true,
hasSurface = true,
hasCloseButton = true,
@@ -317,10 +329,12 @@ export function usePopover(
onHide,
});
- // Focus trap for the popover content
+ // Focus trap for the popover content. Escape stays registered while light
+ // dismiss is on (native popover="auto" closes on Escape regardless), so a
+ // host Dialog keeps deferring to this trap instead of double-dismissing.
const {containerRef: contentRef, focusFirst} = useFocusTrap<HTMLDivElement>({
isActive: layer.isOpen,
- onEscape: layer.hide,
+ onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
});
// Auto-focus first element when popover opens (unless skipped)
@@ -366,7 +380,8 @@ export function usePopover(
// ARIA attributes for the trigger
const triggerProps = {
- 'aria-haspopup': role === 'dialog' ? ('dialog' as const) : ('true' as const),
+ 'aria-haspopup':
+ role === 'dialog' ? ('dialog' as const) : ('true' as const),
'aria-expanded': layer.isOpen,
'aria-controls': layer.id,
};