@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/PillMenu/PillMenu.tsx

@@ -0,0 +1,324 @@
+import {
+  forwardRef,
+  useEffect,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import clsx from 'clsx';
+import { DropdownMenu } from '../DropdownMenu';
+import { paletteTokens, type PaletteColor } from '../../palette';
+import { useTranslation } from '../../i18n/useTranslation';
+import { resolveStatusColor, type StatusCategory } from '../_internal/statusColor';
+import styles from './PillMenu.module.scss';
+
+/** Workflow category — maps to a default palette color. */
+export type PillMenuCategory = StatusCategory;
+
+/** One value (a status, a task type, a priority…): the current one or a menu option. */
+export interface PillMenuOption {
+  /** Stable id — passed to `onSelect` when this option is chosen. */
+  id: string | number;
+  /** Visible name. */
+  name: string;
+  /**
+   * Optional glyph rendered before the name — in the pill and in its menu
+   * row (e.g. a task-type or priority icon). Decorative: wrapped
+   * `aria-hidden`, so the name alone is announced. Size it to the text
+   * (~14px lucide icon), at most 16px: menu rows place it in DropdownMenu's
+   * fixed 16px icon slot.
+   */
+  icon?: ReactNode;
+  /** Semantic category → default color: to_do slate / in_progress blue / open violet / done green / won green / lost red. */
+  category?: PillMenuCategory;
+  /** Explicit palette color — wins over `category` (per-state custom colors). */
+  color?: PaletteColor;
+  /**
+   * Extra `data-*` attributes spread onto this value's interactive element:
+   * the trigger button (or the read-only chip) when it is `current`, its menu
+   * row when it is one of `options` (e.g. `{ 'data-tour': 'status-pill' }` to
+   * target it from a `Tour`, or a test/analytics id). Spread first, so a key
+   * here can't override the `id` / `role` / `aria-*` / handlers the component
+   * owns; on a menu row it also can't override the row's own `data-tone`.
+   * A `data-*` passed on `<PillMenu>` itself (via `{...rest}`) beats
+   * `current.attrs`.
+   *
+   * Anti-pattern: when `current` is the same object as an entry in `options`
+   * (`current={options.find(...)}`), its attrs land on BOTH the pill and that
+   * menu row (duplicate `data-tour` / `data-testid` while open). Give
+   * `current` its own attrs: `current={{ ...opt, attrs: { 'data-tour': 'stage-pill' } }}`.
+   */
+  attrs?: Record<`data-${string}`, string>;
+}
+
+// `aria-labelledby` is omitted: the trigger's name is component-owned (see
+// `label`), and aria-labelledby would override it. TS doesn't excess-check
+// hyphenated JSX attributes, so this is documentation — it's also stripped
+// at runtime.
+export interface PillMenuProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'onSelect' | 'aria-labelledby'
+> {
+  /** The value currently shown on the trigger (or the read-only chip). */
+  current: PillMenuOption;
+  /**
+   * What the value IS, for the trigger's accessible name: `label="type"` →
+   * "Change type: Bug". Default: a string `caption` ("Change Pipeline: …"),
+   * else the localized "status" ("Change status: …").
+   * Pass it as it reads right after "Change" / "Изменить", lower-case, in the
+   * UI's language — it is data, not a translatable string. In ru that is the
+   * accusative: `label="категорию"`, not "категория".
+   *
+   * Inside a `<Field>`, pass the field's label here (`label="priority"` under
+   * "Priority"): the trigger keeps its own name, so the visible field label
+   * reaches AT only through this (WCAG 2.5.3). A dev warning fires if it's
+   * missing there.
+   */
+  label?: string;
+  /**
+   * Visible caption rendered inside the pill before the value, separated by a
+   * middle dot: `caption="Pipeline"` → "Pipeline · Faeton". For a trigger
+   * that must say both what it picks and the current value.
+   *
+   * Names the trigger only as a fallback: `label` wins ("Change pipeline:
+   * Faeton"); with no `label`, a non-blank string caption is used ("Change Pipeline:
+   * Faeton") so the visible words stay in the accessible name (WCAG 2.5.3
+   * label-in-name). A non-string caption never names it — pass `label` then,
+   * containing the caption's words. In the read-only chip (no accessible
+   * name override) the caption text is read along with the value; the dot is
+   * `aria-hidden` in both. Muted by weight (regular vs the value's medium),
+   * not colour: the palette fills leave no contrast headroom for a dimmer
+   * foreground. Omitted or blank → no caption, no dot.
+   */
+  caption?: ReactNode;
+  /**
+   * Transition targets, offered in the dropdown. Omitted or empty renders
+   * read-only mode: a static colored chip with no button, no menu, no
+   * aria-haspopup.
+   */
+  options?: PillMenuOption[];
+  /** Fired with the chosen option's `id` when a transition target is picked. */
+  onSelect?: (id: string | number) => void;
+  /** Disables the trigger. Stays colored, dims via opacity. */
+  disabled?: boolean;
+  /**
+   * Transition in flight: the trigger is non-interactive and keeps its color.
+   * Announced from a polite live region the component owns — `aria-busy` is
+   * also set but reaches no screen reader on its own. The trigger's accessible
+   * name does not change (contrast `EntityChip`): you activated this control,
+   * so the change is announced rather than folded into the name.
+   *
+   * No effect in read-only mode (no `options`), which renders no trigger and
+   * so has nothing to mark busy.
+   */
+  busy?: boolean;
+  /**
+   * Stretch the trigger (or read-only chip) to its container's width, for a
+   * form column of full-width controls (`Input`, `Select`, `DatePicker` in
+   * vertical `Field`s). Icon + name stay at the start, the chevron moves to
+   * the end edge like a `Select` trigger, and the menu is at least as wide as
+   * the trigger. Keeps the full-colour fill. Defaults to `false`
+   * (content-width pill).
+   */
+  fullWidth?: boolean;
+  /**
+   * Error state — sets `aria-invalid` on the trigger. `<Field error>` injects
+   * it for you. No visual change: the fill IS the value's colour, and the
+   * Field's error text carries the error. The read-only chip ignores it (a
+   * non-focusable chip isn't a control AT can report invalid).
+   */
+  invalid?: boolean;
+}
+
+/** Injectable custom-property pair for a value's resolved color. */
+function statusColorStyle(status: PillMenuOption): CSSProperties {
+  const { bg, fg } = paletteTokens(resolveStatusColor(status));
+  return { '--pill-menu-bg': bg, '--pill-menu-fg': fg } as CSSProperties;
+}
+
+/** Renders the optional caption + icon + name, shared by the pill and the read-only chip (rows use Item's icon slot). */
+function OptionContent({ option, caption }: { option: PillMenuOption; caption?: ReactNode }) {
+  return (
+    <>
+      {caption != null &&
+        caption !== false &&
+        !(typeof caption === 'string' && !caption.trim()) && (
+          <>
+            <span className={styles.caption}>{caption}</span>
+            <span className={styles.caption} aria-hidden="true">
+              ·
+            </span>
+          </>
+        )}
+      {option.icon != null && (
+        <span className={styles.icon} aria-hidden="true">
+          {option.icon}
+        </span>
+      )}
+      {option.name}
+    </>
+  );
+}
+
+/**
+ * Coloured value menu: a coloured pill trigger opening a menu of values (status, type, priority); read-only chip when `options` is omitted.
+ * @see docs/components/PillMenu.md
+ */
+export const PillMenu = forwardRef<HTMLElement, PillMenuProps>(function PillMenu(
+  {
+    current,
+    options,
+    onSelect,
+    label,
+    caption,
+    disabled = false,
+    busy = false,
+    fullWidth = false,
+    invalid = false,
+    className,
+    style,
+    ...props
+  },
+  ref,
+) {
+  // Inside a <Field>, auto-wiring also injects `required` (not valid on a
+  // button — there's no aria-required for it) and `aria-labelledby`, which
+  // would OVERRIDE the component-owned name: "Change type: Bug" would read
+  // as the bare field label "Type", dropping the current value. Neither
+  // reaches the DOM; `label` names the value instead. `id` and
+  // `aria-describedby` (the error/help text) do pass through.
+  const {
+    required: _required,
+    'aria-labelledby': fieldLabelledBy,
+    ...rest
+  } = props as typeof props & { required?: boolean; 'aria-labelledby'?: string };
+  const t = useTranslation();
+  // Trigger mode only: the read-only chip has no name for `label` to fix.
+  // A boolean dep, not `options` — callers pass a fresh array every render.
+  const hasTrigger = options != null && options.length > 0;
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'production' && hasTrigger && fieldLabelledBy && !label) {
+      console.warn(
+        '<PillMenu> received `aria-labelledby` (e.g. inside a <Field>) but no `label`. `aria-labelledby` is ignored — the trigger keeps its own name ("Change <string caption, or status>: …") — so the field label doesn\'t reach assistive tech unless it matches. Pass `label` (e.g. label="priority").',
+      );
+    }
+  }, [fieldLabelledBy, label, hasTrigger]);
+  // Deferred for the same reason as Switch: a PillMenu that mounts already
+  // busy would otherwise mount its region and text together and announce
+  // nothing. See CLAUDE.md Hard rule 10.
+  const [busyText, setBusyText] = useState('');
+  useEffect(() => {
+    setBusyText(busy ? t('pillMenu.busy') : '');
+  }, [busy, t]);
+  // Component color wins over any consumer `style` — merged AFTER so its
+  // `--pill-menu-*` custom properties can't be shadowed by a consumer's
+  // own inline style object.
+  const mergedStyle: CSSProperties = { ...style, ...statusColorStyle(current) };
+  const isBlocked = disabled || busy;
+
+  // DropdownMenu.Trigger clones an unconditional pointerdown/keydown toggle
+  // onto the button — a native `disabled` attribute doesn't stop those
+  // handlers from running (jsdom, and some browsers, still deliver
+  // pointerdown to disabled buttons). Drive `open` explicitly so it's
+  // pinned closed while blocked, regardless of what the trigger's own
+  // handlers try to do.
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
+
+  // If the menu is open and a parent re-render flips busy/disabled true,
+  // DropdownMenu never fires onOpenChange for that externally-forced close
+  // (the `open` prop just renders false) — so uncontrolledOpen would stay
+  // stale-true, and the menu would pop back open with no user action once
+  // busy/disabled flips off again. React-sanctioned adjust-state-during-
+  // render: reset synchronously, before paint.
+  if (isBlocked && uncontrolledOpen) setUncontrolledOpen(false);
+
+  if (!hasTrigger) {
+    return (
+      // Spread order: current.attrs, then {...rest} (an instance data-* wins),
+      // then the chip's own ref/className/style resolution.
+      <span
+        {...current.attrs}
+        {...rest}
+        ref={ref as Ref<HTMLSpanElement>}
+        className={clsx(styles.chip, fullWidth && styles.fullWidth, className)}
+        style={mergedStyle}
+      >
+        <OptionContent option={current} caption={caption} />
+      </span>
+    );
+  }
+
+  return (
+    <DropdownMenu
+      open={isBlocked ? false : uncontrolledOpen}
+      onOpenChange={(next) => {
+        if (!isBlocked) setUncontrolledOpen(next);
+      }}
+    >
+      <DropdownMenu.Trigger>
+        {/* Spread order: current.attrs, then {...rest} (an instance data-*
+            wins), then the trigger's aria-label / disabled / aria-busy contract. */}
+        <button
+          {...current.attrs}
+          {...rest}
+          ref={ref as Ref<HTMLButtonElement>}
+          type="button"
+          className={clsx(styles.trigger, fullWidth && styles.fullWidth, className)}
+          style={mergedStyle}
+          disabled={isBlocked}
+          aria-busy={busy || undefined}
+          aria-invalid={invalid || undefined}
+          aria-label={t('pillMenu.change', {
+            label:
+              label ||
+              (typeof caption === 'string' && caption.trim() ? caption : undefined) ||
+              t('pillMenu.defaultLabel'),
+            name: current.name,
+          })}
+        >
+          <OptionContent option={current} caption={caption} />
+          <svg
+            width="10"
+            height="6"
+            viewBox="0 0 10 6"
+            aria-hidden="true"
+            className={styles.chevron}
+          >
+            <path d="M1 1 L5 5 L9 1" stroke="currentColor" strokeWidth="1.5" fill="none" />
+          </svg>
+        </button>
+      </DropdownMenu.Trigger>
+      {/* OUTSIDE the <button> on purpose. `button` is Children Presentational
+          in ARIA, so a live region nested inside it is spec'd to be pruned —
+          the same argument #496 makes about the Retry button inside
+          role="img". Chrome happens to expose it, but relying on that is
+          exactly the reasoning that left `aria-busy` shipping for years. The
+          trigger also goes `disabled` while busy, which is when this needs to
+          speak. */}
+      <span role="status" aria-live="polite" className={styles.srOnly}>
+        {busyText}
+      </span>
+      <DropdownMenu.Content className={styles.menu}>
+        {options.map((option) => (
+          <DropdownMenu.Item
+            key={option.id}
+            // attrs first so they cannot override the row handlers or data-tone
+            {...option.attrs}
+            onSelect={() => onSelect?.(option.id)}
+            className={styles.option}
+            style={statusColorStyle(option)}
+            // The name stays a plain string child: DropdownMenu's typeahead
+            // only reads string children, so wrapping it broke type-to-select.
+            // The glyph goes in Item's own fixed-size icon slot (aligned rows,
+            // item gap) instead.
+            icon={option.icon != null ? <span aria-hidden="true">{option.icon}</span> : undefined}
+          >
+            {option.name}
+          </DropdownMenu.Item>
+        ))}
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  );
+});

package/src/components/PillMenu/index.ts

@@ -0,0 +1,2 @@
+export { PillMenu } from './PillMenu';
+export type { PillMenuProps, PillMenuOption, PillMenuCategory } from './PillMenu';

package/src/components/Popover/Anchor.tsx

@@ -0,0 +1,37 @@
+import { cloneElement, isValidElement, type ReactElement, type Ref } from 'react';
+import { usePopoverContext } from './context';
+import { mergeRefs } from '../_internal/refs';
+
+export interface PopoverAnchorProps {
+  /**
+   * Exactly one React element that accepts a ref. Unlike `Popover.Trigger`,
+   * Anchor injects ONLY the floating-positioning ref — no `onClick`, no keyboard
+   * handler, and no `aria-haspopup` / `aria-expanded` / `aria-controls`. Use it
+   * when the anchor element already owns its open-toggle and ARIA (e.g. an
+   * interactive `FilterChip` whose body `<button>` self-manages
+   * `aria-haspopup`/`aria-expanded`), and you drive the popover's open state
+   * yourself (controlled `open` + `onOpenChange`). The child must accept a ref
+   * (`forwardRef`); raw DOM elements and this library's components qualify, and
+   * it should be focusable (a `<button>` or `tabIndex` host) so Escape can
+   * return focus to it on close. Wrapping such a chip in `Popover.Trigger`
+   * instead would stamp that ARIA onto its `role="group"` root, not the body
+   * button.
+   */
+  children: ReactElement;
+}
+
+/**
+ * Positions `Popover.Content` against its child, injecting only the floating ref and no interaction or ARIA (`Popover.Anchor`).
+ * @see docs/components/Popover.md
+ */
+export function Anchor({ children }: PopoverAnchorProps) {
+  const ctx = usePopoverContext('Anchor');
+  if (!isValidElement(children)) {
+    throw new Error('<Popover.Anchor> requires exactly one React element child.');
+  }
+  const childProps = children.props as { ref?: Ref<HTMLElement> };
+  // Ref only — NO aria/onClick/onKeyDown. The anchor owns its own toggle + ARIA.
+  return cloneElement(children, {
+    ref: mergeRefs(ctx.triggerRef, childProps.ref),
+  } as object);
+}

package/src/components/Popover/Close.tsx

@@ -0,0 +1,45 @@
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  type MouseEvent as ReactMouseEvent,
+  type ReactElement,
+} from 'react';
+import { usePopoverContext } from './context';
+import { chain } from '../_internal/refs';
+
+export interface PopoverCloseProps {
+  /**
+   * Exactly one React element. The Close clones this element to inject an
+   * `onClick` that closes the popover, chained with the child's existing
+   * `onClick` (consumer runs first).
+   */
+  children: ReactElement;
+}
+
+/**
+ * Wraps a single element so activating it closes the popover (`Popover.Close`).
+ * @see docs/components/Popover.md
+ */
+export function Close({ children }: PopoverCloseProps) {
+  const ctx = usePopoverContext('Close');
+
+  if (!isValidElement(children)) {
+    throw new Error('<Popover.Close> requires exactly one React element child.');
+  }
+
+  const childProps = children.props as {
+    onClick?: (e: ReactMouseEvent<HTMLElement>) => void;
+  };
+
+  const handleClick = useCallback(
+    (_e: ReactMouseEvent<HTMLElement>) => {
+      ctx.closeAll();
+    },
+    [ctx],
+  );
+
+  return cloneElement(children, {
+    onClick: chain(childProps.onClick, handleClick),
+  } as object);
+}

package/src/components/Popover/Content.tsx

@@ -0,0 +1,213 @@
+import { forwardRef, useEffect, useLayoutEffect, useRef, type HTMLAttributes } from 'react';
+import { createPortal } from 'react-dom';
+import {
+  arrow,
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  size,
+  useFloating,
+  type Placement,
+} from '@floating-ui/react-dom';
+import clsx from 'clsx';
+import { usePopoverContext } from './context';
+import { mergeRefs } from '../_internal/refs';
+import { isTourHeld, overlayStack, useFloatingSurface, useInOverlay } from '../_internal/overlay';
+import styles from './Popover.module.scss';
+
+/** Which side of the trigger the popover prefers. Floating UI auto-flips if it doesn't fit. */
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
+/** Which edge of the popover aligns to the corresponding trigger edge. */
+export type PopoverAlign = 'start' | 'center' | 'end';
+
+export interface PopoverContentProps extends HTMLAttributes<HTMLDivElement> {
+  /** Preferred side. Default `'bottom'`. Auto-flips on collision via Floating UI. */
+  side?: PopoverSide;
+  /** Edge alignment. Default `'center'`. */
+  align?: PopoverAlign;
+  /** Gap in px between trigger and panel. Default `10` (room for the arrow). */
+  sideOffset?: number;
+  /**
+   * Minimum width in px or any CSS length. Defaults to the token
+   * `--size-popover-min-width` (220px) applied via SCSS.
+   */
+  minWidth?: number | string;
+  /**
+   * Maximum width in px or any CSS length, overriding the default cap
+   * (`--popover-max-width`, 360px). Use for wide content — calendars, tables —
+   * that would otherwise overflow the panel. Accepts a number (px),
+   * `'fit-content'`, `'none'` to remove the cap, or any CSS length.
+   */
+  maxWidth?: number | string;
+}
+
+/**
+ * The floating panel: portaled, auto-flipping, `role="dialog"` with an aria-hidden arrow (`Popover.Content`).
+ * @see docs/components/Popover.md
+ */
+export const Content = forwardRef<HTMLDivElement, PopoverContentProps>(function Content(
+  {
+    side = 'bottom',
+    align = 'center',
+    sideOffset = 10,
+    minWidth,
+    maxWidth,
+    className,
+    children,
+    'aria-labelledby': ariaLabelledBy,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const ctx = usePopoverContext('Content');
+  const { closeAll, setOpen } = ctx;
+  const inOverlay = useInOverlay(ctx.triggerRef, ctx.open);
+  // #274: hosts yield Escape while we're open — our capture listener
+  // closes us (or one menu level) on the same press instead.
+  const floatingId = useFloatingSurface(ctx.open);
+  const arrowRef = useRef<HTMLSpanElement | null>(null);
+
+  const placement: Placement = (align === 'center' ? side : `${side}-${align}`) as Placement;
+
+  const {
+    refs,
+    floatingStyles,
+    placement: resolvedPlacement,
+    middlewareData,
+  } = useFloating({
+    open: ctx.open,
+    placement,
+    transform: false,
+    middleware: [
+      offset(sideOffset),
+      flip(),
+      shift({ padding: 8 }),
+      // #598: expose the room left in the viewport. Only a popover holding a
+      // <ScrollArea> as a direct child, or inside one wrapper element that is
+      // a direct child, uses it (Popover.module.scss
+      // `:has(> [data-scroll-area], …)`): it caps there and the ScrollArea
+      // shrinks, so the header stays put.
+      // A CSS variable rather than inline max-height, so popovers without a
+      // ScrollArea keep today's layout (and the arrow is never clipped).
+      size({
+        padding: 8,
+        apply({ availableHeight, elements }) {
+          elements.floating.style.setProperty(
+            '--popover-available-height',
+            `${Math.max(0, availableHeight)}px`,
+          );
+        },
+      }),
+      arrow({ element: arrowRef }),
+    ],
+    whileElementsMounted: autoUpdate,
+    elements: { reference: ctx.triggerRef.current },
+  });
+
+  const [resolvedSide, resolvedAlign = 'center'] = resolvedPlacement.split('-') as [
+    PopoverSide,
+    PopoverAlign?,
+  ];
+  const staticSide = ({ top: 'bottom', bottom: 'top', left: 'right', right: 'left' } as const)[
+    resolvedSide
+  ];
+
+  // Focus the panel on open. preventScroll matches DropdownMenu/Tooltip.
+  useLayoutEffect(() => {
+    if (!ctx.open) return;
+    queueMicrotask(() => ctx.contentRef.current?.focus({ preventScroll: true }));
+  }, [ctx.open, ctx.contentRef]);
+
+  // Escape closes; capture phase fires before focused widgets that may
+  // stopPropagation.
+  useEffect(() => {
+    if (!ctx.open) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        // #280: defer to a DEEPER floating surface (e.g. a Select open inside
+        // this popover) — only the innermost closes on this press.
+        if (!overlayStack.isTopFloating(floatingId)) return;
+        e.preventDefault();
+        overlayStack.consumeEscape(e); // hosts yield even if we ran first (#274)
+        closeAll();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [ctx.open, closeAll, floatingId]);
+
+  // Outside-click closes.
+  useEffect(() => {
+    if (!ctx.open) return;
+    const onPointerDown = (e: PointerEvent) => {
+      const target = e.target as Node | null;
+      if (!target) return;
+      const panel = ctx.contentRef.current;
+      const trigger = ctx.triggerRef.current;
+      if (panel && panel.contains(target)) return;
+      if (trigger && trigger.contains(target)) return;
+      // #684: a tour pointing into this popover doesn't dismiss it.
+      if (isTourHeld(target, panel, trigger)) return;
+      // A floating surface (DropdownMenu / nested Popover / ConfirmationPopover)
+      // opened from WITHIN this popover portals to document.body, so it is not a
+      // DOM descendant of `panel` — without this a pointerdown inside it would
+      // read as "outside" and dismiss this popover before the user can use the
+      // nested surface (e.g. clicking a kebab menu item or its confirm dialog).
+      // Treat clicks inside any dropdown-menu / popover surface as inside, mirroring
+      // DropdownMenu's own outside-click exemption.
+      const el = target instanceof Element ? target : target.parentElement;
+      if (el?.closest('[data-dropdown-menu-content], [data-popover-content]')) return;
+      setOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown, true);
+    return () => document.removeEventListener('pointerdown', onPointerDown, true);
+  }, [ctx.open, ctx.contentRef, ctx.triggerRef, setOpen]);
+
+  if (!ctx.open) return null;
+
+  const arrowXY = middlewareData.arrow;
+  const minWidthStyle =
+    minWidth !== undefined
+      ? typeof minWidth === 'number'
+        ? `${minWidth}px`
+        : minWidth
+      : undefined;
+  const maxWidthStyle =
+    maxWidth !== undefined
+      ? typeof maxWidth === 'number'
+        ? `${maxWidth}px`
+        : maxWidth
+      : undefined;
+
+  return createPortal(
+    <div
+      {...rest}
+      ref={mergeRefs<HTMLDivElement>(ctx.contentRef, refs.setFloating, forwardedRef)}
+      id={ctx.contentId}
+      role="dialog"
+      aria-modal="false"
+      aria-labelledby={ctx.headingId ?? ariaLabelledBy}
+      tabIndex={-1}
+      data-side={resolvedSide}
+      data-align={resolvedAlign}
+      data-popover-content=""
+      data-in-overlay={inOverlay ? '' : undefined}
+      style={{ ...floatingStyles, minWidth: minWidthStyle, maxWidth: maxWidthStyle }}
+      className={clsx(styles.content, className)}
+    >
+      {children}
+      <span
+        ref={arrowRef}
+        aria-hidden="true"
+        className={styles.arrow}
+        style={{
+          left: typeof arrowXY?.x === 'number' ? `${arrowXY.x}px` : undefined,
+          top: typeof arrowXY?.y === 'number' ? `${arrowXY.y}px` : undefined,
+          [staticSide]: '-6px',
+        }}
+      />
+    </div>,
+    document.body,
+  );
+});

package/src/components/Popover/Heading.tsx

@@ -0,0 +1,33 @@
+import { createElement, useId, useLayoutEffect, type HTMLAttributes } from 'react';
+import { usePopoverContext } from './context';
+import { sanitizeId } from '../_internal/refs';
+
+export interface PopoverHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * Heading level. Defaults to `'h3'`. Pick the level that fits the
+   * surrounding document outline (Popover content is usually a level 3
+   * inside a level 2 section).
+   */
+  as?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+}
+
+/**
+ * Semantic heading (default `h3`) that names the popover via `aria-labelledby` (`Popover.Heading`).
+ * @see docs/components/Popover.md
+ */
+export function Heading({ as = 'h3', id: idProp, children, ...rest }: PopoverHeadingProps) {
+  const { setHeadingId } = usePopoverContext('Heading');
+  const reactId = useId();
+  const id = idProp ?? `popover-heading-${sanitizeId(reactId)}`;
+
+  useLayoutEffect(() => {
+    setHeadingId(id);
+    return () => setHeadingId(null);
+    // setHeadingId is stable per Popover instance; id changes only if
+    // consumer provides one — re-fire is correct in that case.
+  }, [setHeadingId, id]);
+
+  // `createElement` keeps the dynamic tag type-safe across h2–h6 without
+  // tripping JSX.IntrinsicElements' SVG-tag variance issue.
+  return createElement(as, { id, ...rest }, children);
+}