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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsindex 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';