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.mdnew file mode 100644index 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)+@arham766diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjsindex 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.tsxindex 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 laterconst 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.tsxindex 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.mjsindex 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.tsxindex 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 triggerconst 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,};