Skip to content

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

TypeScript

feat(core): add XDSPopover component (#298)

Cindy Zhang06f40484d112
diff --git a/apps/storybook/stories/Popover.stories.tsx b/apps/storybook/stories/Popover.stories.tsx
new file mode 100644
index 0000000000..d9cc49ac7f
--- /dev/null
+++ b/apps/storybook/stories/Popover.stories.tsx
@@ -0,0 +1,309 @@
+import React from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSPopover} from '@xds/core/Layer';
+import {XDSButton} from '@xds/core/Button';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSSwitch} from '@xds/core/Switch';
+import {XDSCheckboxInput} from '@xds/core/CheckboxInput';
+import {XDSDivider} from '@xds/core/Divider';
+
+const meta: Meta<typeof XDSPopover> = {
+ title: 'Core/XDSPopover',
+ component: XDSPopover,
+ tags: ['autodocs'],
+ argTypes: {
+ placement: {
+ control: 'select',
+ options: ['above', 'below', 'start', 'end'],
+ description: 'Position relative to trigger',
+ },
+ alignment: {
+ control: 'select',
+ options: ['start', 'center', 'end'],
+ description: 'Alignment on placement axis',
+ },
+ isEnabled: {
+ control: 'boolean',
+ description: 'Enable/disable the popover',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSPopover>;
+
+// =============================================================================
+// Settings Panel
+// =============================================================================
+
+function SettingsContent() {
+ const [notifications, setNotifications] = React.useState(true);
+ const [darkMode, setDarkMode] = React.useState(false);
+ const [sounds, setSounds] = React.useState(true);
+
+ return (
+ <XDSVStack gap="space3">
+ <XDSHeading level={4} tabIndex={-1}>
+ Settings
+ </XDSHeading>
+ <XDSDivider />
+ <XDSSwitch
+ label="Notifications"
+ description="Receive push notifications"
+ value={notifications}
+ onChange={setNotifications}
+ />
+ <XDSSwitch
+ label="Dark mode"
+ description="Use dark color theme"
+ value={darkMode}
+ onChange={setDarkMode}
+ />
+ <XDSSwitch
+ label="Sounds"
+ description="Play sounds for actions"
+ value={sounds}
+ onChange={setSounds}
+ />
+ </XDSVStack>
+ );
+}
+
+export const Default: Story = {
+ args: {
+ placement: 'below',
+ label: 'Settings',
+ width: 280,
+ content: <SettingsContent />,
+ children: <XDSButton label="Settings">Settings</XDSButton>,
+ },
+};
+
+// =============================================================================
+// Filter Panel
+// =============================================================================
+
+function FilterContent({onApply}: {onApply?: () => void}) {
+ const [filters, setFilters] = React.useState({
+ active: true,
+ archived: false,
+ drafts: true,
+ shared: false,
+ });
+
+ const toggle = (key: keyof typeof filters) =>
+ setFilters(prev => ({...prev, [key]: !prev[key]}));
+
+ return (
+ <XDSVStack gap="space3">
+ <XDSHeading level={4} tabIndex={-1}>
+ Filter by status
+ </XDSHeading>
+ <XDSDivider />
+ <XDSCheckboxInput
+ label="Active"
+ value={filters.active}
+ onChange={() => toggle('active')}
+ />
+ <XDSCheckboxInput
+ label="Archived"
+ value={filters.archived}
+ onChange={() => toggle('archived')}
+ />
+ <XDSCheckboxInput
+ label="Drafts"
+ value={filters.drafts}
+ onChange={() => toggle('drafts')}
+ />
+ <XDSCheckboxInput
+ label="Shared with me"
+ value={filters.shared}
+ onChange={() => toggle('shared')}
+ />
+ <XDSDivider />
+ <XDSHStack gap="space2">
+ <XDSButton label="Apply" variant="primary" onClick={onApply}>
+ Apply
+ </XDSButton>
+ <XDSButton
+ label="Reset"
+ variant="ghost"
+ onClick={() =>
+ setFilters({
+ active: true,
+ archived: false,
+ drafts: true,
+ shared: false,
+ })
+ }>
+ Reset
+ </XDSButton>
+ </XDSHStack>
+ </XDSVStack>
+ );
+}
+
+export const FilterPanel: Story = {
+ render: function FilterPanelStory() {
+ const [isShown, setIsShown] = React.useState(false);
+ return (
+ <XDSPopover
+ placement="below"
+ label="Filter"
+ width={240}
+ isShown={isShown}
+ onToggle={setIsShown}
+ content={<FilterContent onApply={() => setIsShown(false)} />}>
+ <XDSButton label="Filter">Filter</XDSButton>
+ </XDSPopover>
+ );
+ },
+};
+
+// =============================================================================
+// Confirmation
+// =============================================================================
+
+function ConfirmContent({
+ onConfirm,
+ onCancel,
+}: {
+ onConfirm?: () => void;
+ onCancel?: () => void;
+}) {
+ return (
+ <XDSVStack gap="space3">
+ <XDSHeading level={4} tabIndex={-1}>
+ Delete project?
+ </XDSHeading>
+ <XDSText type="body">
+ This will permanently delete the project and all its data. This action
+ cannot be undone.
+ </XDSText>
+ <XDSHStack gap="space2">
+ <XDSButton label="Delete" variant="destructive" onClick={onConfirm}>
+ Delete
+ </XDSButton>
+ <XDSButton label="Cancel" variant="ghost" onClick={onCancel}>
+ Cancel
+ </XDSButton>
+ </XDSHStack>
+ </XDSVStack>
+ );
+}
+
+export const Confirmation: Story = {
+ render: function ConfirmationStory() {
+ const [isShown, setIsShown] = React.useState(false);
+ return (
+ <XDSPopover
+ placement="below"
+ label="Confirm deletion"
+ width={300}
+ isShown={isShown}
+ onToggle={setIsShown}
+ content={
+ <ConfirmContent
+ onConfirm={() => setIsShown(false)}
+ onCancel={() => setIsShown(false)}
+ />
+ }>
+ <XDSButton label="Delete project" variant="destructive">
+ Delete project
+ </XDSButton>
+ </XDSPopover>
+ );
+ },
+};
+
+// =============================================================================
+// Sibling Mode (anchorRef)
+// =============================================================================
+
+export const AnchorRef: Story = {
+ render: function AnchorRefStory() {
+ const buttonRef = React.useRef<HTMLButtonElement>(null);
+ return (
+ <>
+ <XDSButton ref={buttonRef} label="Anchor button">
+ Anchor button
+ </XDSButton>
+ <XDSPopover
+ anchorRef={buttonRef as React.RefObject<HTMLElement>}
+ label="Sibling popover"
+ width={260}
+ placement="below"
+ content={
+ <XDSVStack gap="space2">
+ <XDSHeading level={4} tabIndex={-1}>
+ Sibling mode
+ </XDSHeading>
+ <XDSText type="body">
+ This popover uses anchorRef to attach to the button as a
+ sibling, without wrapping it.
+ </XDSText>
+ </XDSVStack>
+ }
+ />
+ </>
+ );
+ },
+};
+
+// =============================================================================
+// Placement: Above
+// =============================================================================
+
+export const Above: Story = {
+ render: () => (
+ <div style={{paddingTop: 200}}>
+ <XDSPopover
+ placement="above"
+ label="Info"
+ width={260}
+ content={
+ <XDSVStack gap="space2">
+ <XDSHeading level={4} tabIndex={-1}>
+ Keyboard shortcuts
+ </XDSHeading>
+ <XDSDivider />
+ <XDSHStack gap="space3">
+ <XDSText type="body" weight="bold">
+ ⌘K
+ </XDSText>
+ <XDSText type="body">Command palette</XDSText>
+ </XDSHStack>
+ <XDSHStack gap="space3">
+ <XDSText type="body" weight="bold">
+ ⌘/
+ </XDSText>
+ <XDSText type="body">Toggle sidebar</XDSText>
+ </XDSHStack>
+ <XDSHStack gap="space3">
+ <XDSText type="body" weight="bold">
+ ⌘.
+ </XDSText>
+ <XDSText type="body">Quick actions</XDSText>
+ </XDSHStack>
+ </XDSVStack>
+ }>
+ <XDSButton label="Shortcuts">Shortcuts</XDSButton>
+ </XDSPopover>
+ </div>
+ ),
+};
+
+// =============================================================================
+// Disabled
+// =============================================================================
+
+export const Disabled: Story = {
+ args: {
+ placement: 'below',
+ label: 'Disabled popover',
+ isEnabled: false,
+ content: <XDSText type="body">This should not appear.</XDSText>,
+ children: <XDSButton label="Disabled popover">Disabled</XDSButton>,
+ },
+};
diff --git a/packages/core/src/Layer/XDSPopover.test.tsx b/packages/core/src/Layer/XDSPopover.test.tsx
new file mode 100644
index 0000000000..2e4a094635
--- /dev/null
+++ b/packages/core/src/Layer/XDSPopover.test.tsx
@@ -0,0 +1,228 @@
+/**
+ * @file XDSPopover.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSPopover component
+ * @output Unit tests for XDSPopover component behavior
+ * @position Testing; validates XDSPopover.tsx implementation
+ *
+ * SYNC: When XDSPopover.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import React from 'react';
+import {XDSPopover} from './XDSPopover';
+
+// Store original matches to restore later
+const originalMatches = HTMLElement.prototype.matches;
+
+// Track popover open state per element
+const popoverOpenState = new WeakMap<HTMLElement, boolean>();
+
+// Mock Popover API for jsdom
+beforeAll(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ popoverOpenState.set(this, true);
+ // Dispatch toggle event
+ const event = new Event('toggle');
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ popoverOpenState.set(this, false);
+ const event = new Event('toggle');
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+
+ HTMLElement.prototype.matches = function (selector: string) {
+ if (selector === ':popover-open') {
+ return popoverOpenState.get(this) ?? false;
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
+afterAll(() => {
+ HTMLElement.prototype.matches = originalMatches;
+});
+
+describe('XDSPopover', () => {
+ it('renders trigger element', () => {
+ render(
+ <XDSPopover content={<span>Popover content</span>} label="Test popover">
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ expect(screen.getByRole('button', {name: 'Open'})).toBeInTheDocument();
+ });
+
+ it('sets aria-haspopup on trigger', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <button>Trigger</button>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ });
+
+ it('sets aria-expanded=false initially', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <button>Trigger</button>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('opens on click and updates aria-expanded', () => {
+ render(
+ <XDSPopover content={<span>Popover content</span>} label="Test">
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Open'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('renders popover content with role=dialog', () => {
+ render(
+ <XDSPopover content={<span>Hello</span>} label="Greeting">
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ // The dialog is inside a popover element — hidden from accessibility tree
+ // until shown, but still present in the DOM
+ const dialog = screen.getByRole('dialog', {hidden: true});
+ expect(dialog).toBeInTheDocument();
+ expect(dialog).toHaveAttribute('aria-label', 'Greeting');
+ });
+
+ it('calls onToggle when opened', () => {
+ const onToggle = vi.fn();
+ render(
+ <XDSPopover
+ content={<span>Content</span>}
+ label="Test"
+ onToggle={onToggle}>
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(onToggle).toHaveBeenCalledWith(true);
+ });
+
+ it('does not open when isEnabled is false', () => {
+ const onToggle = vi.fn();
+ render(
+ <XDSPopover
+ content={<span>Content</span>}
+ label="Test"
+ isEnabled={false}
+ onToggle={onToggle}>
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+ expect(onToggle).not.toHaveBeenCalled();
+ });
+
+ it('renders with data-testid', () => {
+ render(
+ <XDSPopover
+ content={<span>Content</span>}
+ label="Test"
+ data-testid="my-popover">
+ <button>Open</button>
+ </XDSPopover>,
+ );
+ expect(screen.getByTestId('my-popover')).toBeInTheDocument();
+ });
+
+ it('supports anchorRef sibling mode', () => {
+ function AnchorRefTest() {
+ const ref = React.useRef<HTMLButtonElement>(null);
+ return (
+ <>
+ <button ref={ref}>Anchor</button>
+ <XDSPopover
+ anchorRef={ref as React.RefObject<HTMLElement>}
+ content={<span>Sibling content</span>}
+ label="Sibling"
+ />
+ </>
+ );
+ }
+ render(<AnchorRefTest />);
+ const anchor = screen.getByRole('button', {name: 'Anchor'});
+ expect(anchor).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(anchor).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('finds button inside wrapper and attaches ARIA', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <div>
+ <button>Nested button</button>
+ </div>
+ </XDSPopover>,
+ );
+ const button = screen.getByRole('button', {name: 'Nested button'});
+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(button).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('finds role="button" elements and attaches ARIA', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <div role="button" tabIndex={0}>
+ Custom trigger
+ </div>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Custom trigger'});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('opens on click for role="button" elements', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <div role="button" tabIndex={0}>
+ Custom trigger
+ </div>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Custom trigger'});
+ fireEvent.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('opens on Enter/Space for role="button" elements', () => {
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <div role="button" tabIndex={0}>
+ Custom trigger
+ </div>
+ </XDSPopover>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Custom trigger'});
+ fireEvent.keyDown(trigger, {key: 'Enter'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('warns in dev when children have no button', () => {
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ render(
+ <XDSPopover content={<span>Content</span>} label="Test">
+ <span>Not a button</span>
+ </XDSPopover>,
+ );
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.stringContaining('must contain a <button> or [role="button"]'),
+ );
+ warnSpy.mockRestore();
+ });
+});
diff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsx
new file mode 100644
index 0000000000..d20f67d46f
--- /dev/null
+++ b/packages/core/src/Layer/XDSPopover.tsx
@@ -0,0 +1,462 @@
+/**
+ * @file XDSPopover.tsx
+ * @input Uses React, useXDSPopover hook
+ * @output Exports XDSPopover component for click-triggered popovers
+ * @position Layer component; declarative wrapper around useXDSPopover hook
+ *
+ * For hover-triggered overlays, use XDSHoverCard instead.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/XDSPopover.test.tsx
+ * - /packages/core/src/Layer/index.ts
+ * - /apps/storybook/stories/Popover.stories.tsx
+ */
+
+import React, {
+ useCallback,
+ useLayoutEffect,
+ useRef,
+ type ReactElement,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {useXDSPopover} from './useXDSPopover';
+import type {LayerAlignment, LayerPlacement} from './useXDSLayer';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ elevationVars,
+} from '../theme/tokens.stylex';
+import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+
+// =============================================================================
+// Module Augmentation
+// =============================================================================
+
+declare module '../theme/types' {
+ interface ComponentStyles {
+ popover?: {
+ container?: ThemeStyleXStyles;
+ };
+ }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const BUTTON_SELECTOR = 'button, [role="button"]';
+
+/**
+ * Find the trigger button inside a container element.
+ * Looks for `<button>` or `[role="button"]` — either the element itself
+ * or the first matching descendant.
+ */
+function findTriggerButton(el: HTMLElement): HTMLElement | null {
+ if (el.matches(BUTTON_SELECTOR)) return el;
+ return el.querySelector<HTMLElement>(BUTTON_SELECTOR);
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSPopoverProps {
+ /**
+ * The trigger element. Must contain a `<button>` or `[role="button"]`
+ * element — the popover locates it and applies click/keydown handlers
+ * and ARIA attributes (`aria-haspopup`, `aria-expanded`, `aria-controls`).
+ *
+ * The trigger is rendered inside an anchor wrapper used for CSS anchor
+ * positioning. The wrapper is stable (no pressed-state transforms),
+ * preventing popover position jitter.
+ *
+ * When `anchorRef` is provided, children can be omitted and the popover
+ * attaches to the external ref element as a sibling.
+ */
+ children?: ReactNode;
+
+ /**
+ * External ref to use as the popover anchor.
+ * When provided (and no children), the popover attaches to this element
+ * instead of wrapping children. The referenced element must be a
+ * `<button>` or `[role="button"]` — the popover applies click/keydown
+ * handlers and ARIA attributes to it directly.
+ */
+ anchorRef?: React.RefObject<HTMLElement>;
+
+ /**
+ * Content to display inside the popover.
+ */
+ content: ReactNode;
+
+ /**
+ * Position placement relative to the trigger.
+ * Uses CSS anchor positioning via useXDSLayer.
+ * @default 'below'
+ */
+ placement?: LayerPlacement;
+
+ /**
+ * Alignment along the placement axis.
+ * @default 'start'
+ */
+ alignment?: LayerAlignment;
+
+ /**
+ * Whether the popover is shown (controlled mode).
+ * Omit for uncontrolled behavior.
+ */
+ isShown?: boolean;
+
+ /**
+ * Callback fired when the popover visibility changes.
+ */
+ onToggle?: (isShown: boolean) => void;
+
+ /**
+ * Whether the popover is enabled.
+ * When false, trigger interactions are ignored.
+ * @default true
+ */
+ isEnabled?: boolean;
+
+ /**
+ * Width of the popover container.
+ * Numbers are px, strings used as-is.
+ * @default 'auto'
+ */
+ width?: number | string;
+
+ /**
+ * Accessible label for the popover dialog.
+ * Recommended for accessibility (used as aria-label on the dialog).
+ */
+ label?: string;
+
+ /**
+ * Optional StyleX overrides for the popover container.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * Test ID for the popover container.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ // Stable anchor wrapper — uses inline-flex to generate a box for CSS
+ // anchor positioning without affecting layout. The trigger element (e.g.
+ // XDSButton) renders inside this wrapper. Because the wrapper itself is
+ // the anchor, pressed-state transforms on the child (e.g. :active scale)
+ // don't shift the anchor position and cause popover jitter.
+ anchorWrapper: {
+ display: 'inline-flex',
+ },
+ // Animation styles for the popover element (the one with [popover] attribute).
+ // :popover-open only matches the element with the popover attribute,
+ // so these MUST be applied via xstyle to useXDSLayer's render wrapper.
+ popoverAnimation: {
+ opacity: {
+ default: 0,
+ ':popover-open': 1,
+ },
+ transform: {
+ default: 'scale(0.95)',
+ ':popover-open': 'scale(1)',
+ },
+ transitionProperty: 'opacity, transform, overlay, display',
+ transitionDuration: '0.15s',
+ transitionTimingFunction: 'ease',
+ transitionBehavior: 'allow-discrete',
+ '@starting-style': {
+ opacity: 0,
+ transform: 'scale(0.95)',
+ },
+ },
+ // Visual styles for the inner content container
+ container: {
+ backgroundColor: colorVars['--color-surface'],
+ color: colorVars['--color-text-primary'],
+ borderRadius: radiusVars['--radius-element'],
+ boxShadow: elevationVars['--elevation-menu'],
+ },
+ contentPadding: {
+ paddingBlockStart: spacingVars['--spacing-3'],
+ paddingBlockEnd: spacingVars['--spacing-3'],
+ paddingInlineStart: spacingVars['--spacing-3'],
+ paddingInlineEnd: spacingVars['--spacing-3'],
+ },
+ gap: {
+ marginBlockStart: spacingVars['--spacing-1'],
+ marginBlockEnd: spacingVars['--spacing-1'],
+ },
+ customWidth: (width: string | number) => ({
+ width: typeof width === 'number' ? `${width}px` : width,
+ }),
+ matchTrigger: {
+ minWidth: 'anchor-size(width)',
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A click-triggered popover for displaying interactive content anchored to a trigger.
+ *
+ * Implements the button + dialog ARIA pattern. The trigger must contain a
+ * `<button>` or `[role="button"]` element — the popover finds it and applies
+ * click/keydown handlers and ARIA attributes automatically.
+ *
+ * Uses an inline-flex wrapper as the CSS anchor for stable positioning
+ * (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).
+ *
+ * For hover-triggered overlays, use {@link XDSHoverCard} instead.
+ *
+ * @example
+ * ```tsx
+ * // Basic popover
+ * <XDSPopover label="Settings" content={<SettingsPanel />} placement="below">
+ * <XDSButton label="Settings" />
+ * </XDSPopover>
+ *
+ * // Controlled popover
+ * <XDSPopover
+ * isShown={isOpen}
+ * onToggle={setIsOpen}
+ * label="Filter"
+ * content={<FilterForm />}
+ * >
+ * <XDSButton label="Filter" />
+ * </XDSPopover>
+ *
+ * // Sibling mode with anchorRef
+ * <XDSPopover
+ * anchorRef={myButtonRef}
+ * label="Actions"
+ * content={<ActionMenu />}
+ * placement="below"
+ * />
+ * ```
+ */
+export function XDSPopover({
+ children,
+ anchorRef,
+ content,
+ placement = 'below',
+ alignment = 'start',
+ isShown,
+ onToggle,
+ isEnabled = true,
+ width,
+ label,
+ xstyle,
+ 'data-testid': testId,
+}: XDSPopoverProps): ReactElement {
+ const wrapperRef = useRef<HTMLDivElement>(null);
+ const isControlled = isShown !== undefined;
+ // Track when the popover was last hidden by light dismiss to prevent
+ // the trigger click from immediately re-opening it.
+ const lastHideTimeRef = useRef(0);
+
+ const popover = useXDSPopover({
+ dialogLabel: label,
+ hasLightDismiss: true,
+ onShow: () => onToggle?.(true),
+ onHide: () => {
+ lastHideTimeRef.current = Date.now();
+ onToggle?.(false);
+ },
+ });
+
+ // Shared handler for click events on the trigger button.
+ const handleTriggerClick = useCallback(() => {
+ if (!isEnabled) return;
+ // If the popover was just closed by light dismiss (clicking outside),
+ // the trigger click fires in the same event — skip re-opening.
+ if (Date.now() - lastHideTimeRef.current < 50) return;
+ popover.toggle();
+ }, [isEnabled, popover]);
+
+ // Shared handler for keydown events on role="button" elements.
+ // Native <button> synthesizes click on Enter/Space, but role="button"
+ // does not — we need to handle it explicitly.
+ const handleTriggerKeyDown = useCallback(
+ (e: KeyboardEvent) => {
+ if (e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ handleTriggerClick();
+ }
+ },
+ [handleTriggerClick],
+ );
+
+ /**
+ * Attach click/keydown handlers and ARIA attributes to a trigger button.
+ * Used by both sibling mode and children mode.
+ */
+ const attachTrigger = useCallback(
+ (button: HTMLElement) => {
+ // ARIA attributes
+ button.setAttribute(
+ 'aria-haspopup',
+ popover.triggerProps['aria-haspopup'],
+ );
+ button.setAttribute(
+ 'aria-expanded',
+ String(popover.triggerProps['aria-expanded']),
+ );
+ button.setAttribute(
+ 'aria-controls',
+ popover.triggerProps['aria-controls'],
+ );
+
+ // Event handlers
+ button.addEventListener('click', handleTriggerClick);
+ // Only add keydown for role="button" — native <button> already
+ // synthesizes click events for Enter/Space.
+ const needsKeyDown =
+ button.tagName !== 'BUTTON' && button.getAttribute('role') === 'button';
+ if (needsKeyDown) {
+ button.addEventListener('keydown', handleTriggerKeyDown);
+ }
+
+ return () => {
+ button.removeAttribute('aria-haspopup');
+ button.removeAttribute('aria-expanded');
+ button.removeAttribute('aria-controls');
+ button.removeEventListener('click', handleTriggerClick);
+ if (needsKeyDown) {
+ button.removeEventListener('keydown', handleTriggerKeyDown);
+ }
+ };
+ },
+ [popover, handleTriggerClick, handleTriggerKeyDown],
+ );
+
+ // Sibling mode: attach to external anchorRef
+ useLayoutEffect(() => {
+ if (!anchorRef) return;
+
+ const el = anchorRef.current;
+ if (!el) return;
+
+ const button = findTriggerButton(el);
+ if (!button) {
+ console.warn(
+ 'XDSPopover: anchorRef must reference a <button> or [role="button"] element. ' +
+ 'The popover trigger implements the button + dialog ARIA pattern.',
+ );
+ }
+ if (!button) return;
+
+ // Set up anchor positioning on the anchorRef element itself
+ popover.triggerRef(el);
+
+ // Attach handlers + ARIA to the button
+ const detach = attachTrigger(button);
+
+ return () => {
+ popover.triggerRef(null);
+ detach();
+ };
+ }, [anchorRef, popover, attachTrigger]);
+
+ // Children mode: use wrapper as CSS anchor, find button inside for
+ // ARIA + event handlers.
+ useLayoutEffect(() => {
+ if (anchorRef) return; // Skip if using anchorRef mode
+
+ const wrapper = wrapperRef.current;
+ if (!wrapper) return;
+
+ // Use the wrapper as the CSS anchor — it doesn't receive pressed-state
+ // transforms, so the anchor position stays stable.
+ popover.triggerRef(wrapper);
+
+ // Find the button inside the wrapper
+ const button = findTriggerButton(wrapper);
+ if (!button) {
+ console.warn(
+ 'XDSPopover: children must contain a <button> or [role="button"] element. ' +
+ 'The popover trigger implements the button + dialog ARIA pattern.',
+ );
+ }
+ if (!button) return;
+
+ const detach = attachTrigger(button);
+
+ return () => {
+ popover.triggerRef(null);
+ detach();
+ };
+ }, [anchorRef, popover, attachTrigger]);
+
+ // Sync controlled state
+ useLayoutEffect(() => {
+ if (!isControlled) return;
+ if (isShown && !popover.isOpen) {
+ popover.show();
+ } else if (!isShown && popover.isOpen) {
+ popover.hide();
+ }
+ }, [isShown, isControlled, popover]);
+
+ // Determine popover xstyle
+ const popoverXstyle = width ? styles.customWidth(width) : styles.matchTrigger;
+
+ // Sibling mode: render only the popover (no wrapper needed)
+ if (anchorRef && children == null) {
+ return (
+ <>
+ {popover.render(
+ <div
+ data-testid={testId}
+ {...stylex.props(styles.container, styles.contentPadding, xstyle)}>
+ {content}
+ </div>,
+ {
+ placement,
+ alignment,
+ xstyle: [popoverXstyle, styles.gap, styles.popoverAnimation],
+ },
+ )}
+ </>
+ );
+ }
+
+ return (
+ <>
+ <div ref={wrapperRef} {...stylex.props(styles.anchorWrapper)}>
+ {children}
+ </div>
+ {popover.render(
+ <div
+ data-testid={testId}
+ {...stylex.props(styles.container, styles.contentPadding, xstyle)}>
+ {content}
+ </div>,
+ {
+ placement,
+ alignment,
+ xstyle: [popoverXstyle, styles.gap, styles.popoverAnimation],
+ },
+ )}
+ </>
+ );
+}
+
+XDSPopover.displayName = 'XDSPopover';
diff --git a/packages/core/src/Layer/index.ts b/packages/core/src/Layer/index.ts
index 482123e133..34792390bc 100644
--- a/packages/core/src/Layer/index.ts
+++ b/packages/core/src/Layer/index.ts
@@ -48,3 +48,7 @@ export type {
export {XDSTooltip} from './XDSTooltip';
export type {XDSTooltipProps} from './XDSTooltip';
+
+// Popover component
+export {XDSPopover} from './XDSPopover';
+export type {XDSPopoverProps} from './XDSPopover';