npm - @lovett/ui - Versions diffs - 0.0.10 → 0.1.0 - Mend

@lovett/ui 0.0.10 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (158) hide show

package/dist/chunk-RBYWGBQ2.js +2752 -0
package/dist/chunk-RBYWGBQ2.js.map +1 -0
package/dist/index.d.ts +6064 -80
package/dist/index.js +21561 -9696
package/dist/index.js.map +1 -1
package/dist/rich-composer-impl-5NO443A6.js +1859 -0
package/dist/rich-composer-impl-5NO443A6.js.map +1 -0
package/dist/styles.css +1586 -2
package/dist/theme-v2.css +228 -0
package/dist/tokens.css +121 -0
package/package.json +8 -1
package/src/__tests__/anchor.test.tsx +422 -0
package/src/__tests__/avatar.test.tsx +272 -0
package/src/__tests__/bar-chart.test.tsx +809 -0
package/src/__tests__/board.test.tsx +420 -0
package/src/__tests__/chart-math.test.ts +922 -0
package/src/__tests__/chart-series.test.ts +339 -0
package/src/__tests__/code-block.test.tsx +134 -0
package/src/__tests__/combobox.test.tsx +677 -0
package/src/__tests__/display-popover.test.tsx +195 -0
package/src/__tests__/display-store.test.tsx +208 -0
package/src/__tests__/donut-chart.test.tsx +397 -0
package/src/__tests__/dropdown-menu.test.tsx +572 -0
package/src/__tests__/filter-menu.test.tsx +175 -0
package/src/__tests__/gauge-ring.test.tsx +233 -0
package/src/__tests__/helpers/geometry.ts +58 -0
package/src/__tests__/layer-stack.test.tsx +228 -0
package/src/__tests__/line-chart.test.tsx +612 -0
package/src/__tests__/popover.test.tsx +460 -0
package/src/__tests__/ranked-bars.test.tsx +343 -0
package/src/__tests__/remark-underline.test.ts +194 -0
package/src/__tests__/select.test.tsx +543 -0
package/src/__tests__/sparkline.test.tsx +368 -0
package/src/__tests__/stat-layer.test.tsx +271 -0
package/src/__tests__/stat-strip.test.tsx +175 -0
package/src/__tests__/status.test.tsx +293 -0
package/src/__tests__/tabs.test.tsx +303 -0
package/src/__tests__/token-shape.test.ts +132 -2
package/src/__tests__/tooltip.test.tsx +355 -0
package/src/avatar.tsx +352 -0
package/src/bar-chart.tsx +1214 -0
package/src/board.tsx +658 -0
package/src/calculator-shell-v2.tsx +19 -39
package/src/chart-frame.tsx +960 -0
package/src/chart-legend.tsx +304 -0
package/src/chart-tooltip.tsx +267 -0
package/src/code-block.tsx +62 -8
package/src/combobox.tsx +796 -0
package/src/delta-chip.tsx +263 -0
package/src/detail/__tests__/activity-pane.test.tsx +186 -0
package/src/detail/__tests__/detail-chrome.test.tsx +134 -0
package/src/detail/__tests__/detail-surface.test.tsx +529 -0
package/src/detail/__tests__/field-row.test.tsx +357 -0
package/src/detail/activity-pane.tsx +507 -0
package/src/detail/calendar.tsx +355 -0
package/src/detail/detail-divider.tsx +261 -0
package/src/detail/detail-header.tsx +287 -0
package/src/detail/detail-menu.tsx +254 -0
package/src/detail/detail-surface.tsx +1110 -0
package/src/detail/field-list.tsx +196 -0
package/src/detail/field-row.tsx +1131 -0
package/src/detail/index.ts +58 -0
package/src/detail/segmented-choice.tsx +94 -0
package/src/detail/types.ts +129 -0
package/src/display-popover.tsx +487 -0
package/src/display-store.tsx +242 -0
package/src/donut-chart.tsx +988 -0
package/src/dropdown-menu.tsx +412 -151
package/src/filter-core/EXPORTS.md +85 -0
package/src/filter-core/__tests__/columns.test.ts +159 -0
package/src/filter-core/__tests__/faceting.test.ts +193 -0
package/src/filter-core/__tests__/filter-fns.test.ts +519 -0
package/src/filter-core/__tests__/operators.test.ts +235 -0
package/src/filter-core/__tests__/state.test.ts +268 -0
package/src/filter-core/__tests__/url.test.ts +350 -0
package/src/filter-core/columns.ts +134 -0
package/src/filter-core/date-utils.ts +38 -0
package/src/filter-core/examples/task-filter-columns.ts +121 -0
package/src/filter-core/faceting.ts +120 -0
package/src/filter-core/filter-fns.ts +335 -0
package/src/filter-core/index.ts +105 -0
package/src/filter-core/operators.ts +433 -0
package/src/filter-core/state.ts +280 -0
package/src/filter-core/types.ts +247 -0
package/src/filter-core/url.ts +261 -0
package/src/filter-dropdown.tsx +12 -0
package/src/filter-menu.tsx +649 -0
package/src/floating-drawer.tsx +19 -1
package/src/gauge-ring.tsx +435 -0
package/src/hue.ts +52 -0
package/src/index.ts +402 -0
package/src/kbd.tsx +27 -4
package/src/lib/anchor.ts +427 -0
package/src/lib/chart.ts +866 -0
package/src/lib/focus.ts +74 -0
package/src/lib/layer-stack.ts +215 -0
package/src/lib/refs.ts +31 -0
package/src/lib/remark-underline.ts +443 -0
package/src/lib/series.ts +169 -0
package/src/line-chart.tsx +1176 -0
package/src/markdown.tsx +26 -7
package/src/metric-card.tsx +57 -22
package/src/modal.tsx +73 -66
package/src/popover.tsx +407 -0
package/src/progress-ledger.tsx +304 -0
package/src/ranked-bars.tsx +386 -0
package/src/segmented-pill.tsx +32 -9
package/src/select.tsx +646 -0
package/src/sortable.tsx +315 -1
package/src/sparkline.tsx +416 -0
package/src/stat-card.tsx +376 -0
package/src/stat-row.tsx +108 -70
package/src/stat-strip.tsx +327 -0
package/src/status.tsx +215 -0
package/src/styles.css +1586 -2
package/src/tabs.tsx +206 -25
package/src/task-card.tsx +610 -0
package/src/thread/__tests__/comment-body-hostile.test.tsx +331 -0
package/src/thread/__tests__/comment-tree.test.ts +151 -0
package/src/thread/__tests__/emoji.test.ts +187 -0
package/src/thread/__tests__/fixtures/thread-fixture.ts +235 -0
package/src/thread/__tests__/link-preview-source.test.ts +120 -0
package/src/thread/__tests__/link-preview.test.tsx +600 -0
package/src/thread/__tests__/markdown-format.test.ts +82 -0
package/src/thread/__tests__/markdown-spec.test.ts +469 -0
package/src/thread/__tests__/relative-time.test.ts +71 -0
package/src/thread/__tests__/rich-composer.test.tsx +799 -0
package/src/thread/__tests__/scroll-caret.test.ts +58 -0
package/src/thread/__tests__/suggestion-list.test.tsx +648 -0
package/src/thread/__tests__/thread-scroll-ownership.test.tsx +88 -0
package/src/thread/__tests__/thread.test.tsx +662 -0
package/src/thread/__tests__/use-attachments.test.tsx +679 -0
package/src/thread/actions.tsx +196 -0
package/src/thread/attachments.tsx +1071 -0
package/src/thread/comment-body.tsx +148 -0
package/src/thread/comment-tree.ts +182 -0
package/src/thread/comment.tsx +915 -0
package/src/thread/composer-footer.tsx +125 -0
package/src/thread/composer.tsx +319 -0
package/src/thread/emoji.ts +283 -0
package/src/thread/index.ts +153 -0
package/src/thread/link-preview.tsx +341 -0
package/src/thread/markdown-format.ts +155 -0
package/src/thread/markdown-spec.ts +754 -0
package/src/thread/rail.tsx +372 -0
package/src/thread/reactions.tsx +415 -0
package/src/thread/relative-time.tsx +94 -0
package/src/thread/rich-composer-impl.tsx +1601 -0
package/src/thread/rich-composer.tsx +195 -0
package/src/thread/scroll-caret.ts +37 -0
package/src/thread/suggestion-list.tsx +182 -0
package/src/thread/thread.tsx +718 -0
package/src/thread/types.ts +218 -0
package/src/thread/use-attachments.ts +598 -0
package/src/thread/use-now.ts +73 -0
package/src/thread/use-thread.ts +316 -0
package/src/tokens.css +121 -0
package/src/tooltip.tsx +297 -0

package/src/dropdown-menu.tsx CHANGED Viewed

@@ -8,46 +8,172 @@
  * BUILD_FRESH per ADR-025 DEVIATION-3: source ships on
  * `@base-ui/react/menu`, which is NOT in CLAUDE.md §1 allowed deps.
  * The compound-component surface (Root / Trigger / Content / Item /
- * CheckboxItem / Separator / Label / Group) carries over; the
- * implementation is a lightweight React Context + Portal + outside-
- * click + Escape handler.
+ * CheckboxItem / Separator / Label / Group) carries over.
  *
- * Trigger styling per ADR-026 D4 (DQ-4 LIFT): the default trigger
- * inherits the secondary Button visual (rounded-xl, `--bg-card` fill,
- * 1px `--border`). Consumers can pass `asChild`-equivalent custom
- * trigger content; the wrapper applies the button-style classes
- * unless `unstyled` is set.
+ * Rebuilt on the shared anchored-positioning kit per ADR-0030 Decision G
+ * (meta-ads-audit-dashboard task manager; the workspace app's 137 call
+ * sites are the other consumer). Same public API, same DOM roles and
+ * `data-slot`s; what changed underneath:
+ *   • Positioning is `useAnchoredPosition` (lib/anchor.ts) — the menu now
+ *     FLIPS to the other side when it cannot fit, instead of being clamped
+ *     over its own trigger; `side` accepts `left` / `right` too.
+ *   • Escape goes through the shared dismiss-layer stack (lib/layer-stack.ts)
+ *     that Modal uses: a menu opened inside a Modal now closes on its own,
+ *     leaving the Modal open. Before, both closed on one keypress.
+ *   • Outside-click is `useOutsideClick`, layer-aware — a Select or Popover
+ *     opened from a menu item is not "outside".
+ *   • Trigger, Content, Item and CheckboxItem forward refs.
+ *
+ * Trigger styling per ADR-026 D4 (DQ-4 LIFT): the default trigger inherits
+ * the secondary Button visual (rounded-xl, `--bg-card` fill, 1px
+ * `--border`). Consumers can pass custom trigger content; the wrapper
+ * applies the button-style classes unless `unstyled` is set.
+ *
+ * Keyboard model (ARIA APG "menu button", added 2026-09-06 — before this
+ * the menu had NO keyboard model at all: opening it left focus on the
+ * trigger, ArrowDown did nothing, and Tab walked off into the page behind
+ * while the menu stayed open):
+ *   • Opening moves focus INTO the menu — the first item, or the last when
+ *     the menu was opened with ArrowUp. A menu whose content is a small
+ *     form rather than a list of items (the keywords range-filter chip)
+ *     focuses its first focusable field instead, and the bare surface when
+ *     it has none.
+ *   • Up / Down / Home / End move between items on a ROVING TABINDEX — the
+ *     focused item is `0`, every other item `-1`, so the menu is one tab
+ *     stop. Movement wraps at both ends.
+ *   • Tab from an item closes the menu and hands focus back to the trigger,
+ *     so the browser's own sequential navigation continues from there.
+ *     Tab inside a form-shaped menu is left alone.
+ *   • Escape, item activation and outside-click all CLOSE and RESTORE focus
+ *     to the trigger (outside-click only when focus was still inside the
+ *     menu — otherwise the element you clicked keeps it). Dropping focus to
+ *     <body> here also broke Modal, which captures `document.activeElement`
+ *     as its restore target; a dialog opened from a menu item now restores
+ *     correctly because the trigger is focused before it mounts.
+ *   • Typeahead (jump to the item starting with a typed letter) is NOT
+ *     implemented — printable keys are left to the content, because menus
+ *     here legitimately host text inputs.
+ * Arrow keys are yielded to any target that owns them: text-entry fields
+ * and dnd-kit sortable handles (`aria-roledescription="sortable"`, the
+ * DataGrid column reorder handles).
+ *
+ * Token discipline: surface chrome is `POPOVER_SURFACE_STYLE` (shared with
+ * Popover — internal `--popover` tokens are allowed inside packages/ui);
+ * item hover / focus use public `--surface-overlay`; motion is
+ * `.ds-enter-pop`, gated on `positioned` so it never plays from the parked
+ * off-screen frame.
  *
  * Workspace ADR: ADR-025 (port) + ADR-026 D4 (trigger spec)
- * Ported 2026-05-18
+ * Ported 2026-05-18 · Rebuilt on lib/anchor 2026-09-05
  */
 import {
   createContext,
+  forwardRef,
   useCallback,
   useContext,
   useEffect,
   useId,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type ButtonHTMLAttributes,
+  type FocusEvent as ReactFocusEvent,
   type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
   type ReactNode,
+  type RefObject,
 } from 'react'
 import { createPortal } from 'react-dom'
 import { Check } from 'lucide-react'
 import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import {
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorSide,
+} from './lib/anchor'
+import { POPOVER_SURFACE_STYLE } from './popover'
+type Align = AnchorAlign
+type Side = AnchorSide
-type Align = 'start' | 'center' | 'end'
-type Side = 'top' | 'bottom'
+/** Where focus lands when the menu opens. */
+type InitialFocus = 'first' | 'last'
 interface DropdownMenuContextValue {
   open: boolean
   setOpen: (next: boolean) => void
-  triggerRef: React.RefObject<HTMLButtonElement | null>
+  /** Open (or, when already open, move focus into) the menu. */
+  openMenu: (initialFocus: InitialFocus) => void
+  /** Close, restoring focus to the trigger unless told not to. */
+  closeMenu: (options?: { restoreFocus?: boolean }) => void
+  triggerRef: RefObject<HTMLButtonElement | null>
   contentId: string
+  initialFocusRef: RefObject<InitialFocus>
+  /** Content registers its edge-focus fn here so the trigger can reach it. */
+  focusEdgeRef: RefObject<((where: InitialFocus) => void) | null>
+}
+/* --------------------------------------------------------------------- *
+ * Roving-tabindex helpers. DOM-driven rather than a registration context:
+ * items arrive through Groups, through consumer wrappers (the DataGrid's
+ * sortable column rows), and through `children` this file never sees, so
+ * querying the live subtree is the only ordering that is always right.
+ * --------------------------------------------------------------------- */
+const MENU_ITEM_SELECTOR =
+  '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]'
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+function isEnabledItem(el: HTMLElement): boolean {
+  return (
+    !el.hasAttribute('disabled') &&
+    el.getAttribute('aria-disabled') !== 'true' &&
+    !el.hidden
+  )
+}
+function menuItemsIn(container: HTMLElement | null): HTMLElement[] {
+  if (!container) return []
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
+  ).filter(isEnabledItem)
+}
+/** Active item is the ONE tab stop; the rest are -1. Never a positive value. */
+function applyRoving(items: readonly HTMLElement[], activeIndex: number): void {
+  items.forEach((item, index) => {
+    item.tabIndex = index === activeIndex ? 0 : -1
+  })
+}
+/**
+ * Targets that own the arrow keys themselves — text entry (a menu is
+ * allowed to host a small form) and dnd-kit sortable handles, whose
+ * keyboard drag IS arrow keys.
+ */
+function ownsArrowKeys(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.closest('[aria-roledescription="sortable"]')) return true
+  if (target.isContentEditable) return true
+  const tag = target.tagName
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return true
+  if (tag === 'INPUT') {
+    const type = (target as HTMLInputElement).type
+    return type !== 'checkbox' && type !== 'radio' && type !== 'button'
+  }
+  return false
 }
 const DropdownMenuCtx = createContext<DropdownMenuContextValue | null>(null)
@@ -87,6 +213,9 @@ export function DropdownMenu({
   const generatedId = useId()
   const contentId = `dropdown-${generatedId.replace(/:/g, '')}`
+  const initialFocusRef = useRef<InitialFocus>('first')
+  const focusEdgeRef = useRef<((where: InitialFocus) => void) | null>(null)
   const setOpen = useCallback(
     (next: boolean) => {
       if (!isControlled) setUncontrolledOpen(next)
@@ -95,9 +224,40 @@ export function DropdownMenu({
     [isControlled, onOpenChange],
   )
+  const openMenu = useCallback(
+    (initialFocus: InitialFocus) => {
+      initialFocusRef.current = initialFocus
+      // Already open (ArrowDown on the trigger of an open menu): jump
+      // straight in, since the open effect will not fire again.
+      if (open) {
+        focusEdgeRef.current?.(initialFocus)
+        return
+      }
+      setOpen(true)
+    },
+    [open, setOpen],
+  )
+  const closeMenu = useCallback(
+    (options?: { restoreFocus?: boolean }) => {
+      setOpen(false)
+      if (options?.restoreFocus !== false) triggerRef.current?.focus()
+    },
+    [setOpen],
+  )
   const value = useMemo<DropdownMenuContextValue>(
-    () => ({ open, setOpen, triggerRef, contentId }),
-    [open, setOpen, contentId],
+    () => ({
+      open,
+      setOpen,
+      openMenu,
+      closeMenu,
+      triggerRef,
+      contentId,
+      initialFocusRef,
+      focusEdgeRef,
+    }),
+    [open, setOpen, openMenu, closeMenu, contentId],
   )
   return (
@@ -119,37 +279,56 @@ export interface DropdownMenuTriggerProps
  * secondary Button visual (rounded-xl + `--bg-card` fill + 1px
  * `--border`). Set `unstyled` to wrap your own button shape.
  */
-export function DropdownMenuTrigger({
-  unstyled,
-  className,
-  onClick,
-  children,
-  ...rest
-}: DropdownMenuTriggerProps) {
-  const { open, setOpen, triggerRef, contentId } =
+export const DropdownMenuTrigger = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuTriggerProps
+>(function DropdownMenuTrigger(
+  { unstyled, className, onClick, onKeyDown, children, ...rest },
+  forwardedRef,
+) {
+  const { open, openMenu, closeMenu, triggerRef, contentId } =
     useDropdownMenuCtx('DropdownMenuTrigger')
+  const ref = useMemo(
+    () => composeRefs<HTMLButtonElement>(forwardedRef, triggerRef),
+    [forwardedRef, triggerRef],
+  )
   return (
     <button
-      ref={triggerRef}
+      ref={ref}
       type="button"
       aria-haspopup="menu"
       aria-expanded={open}
       aria-controls={open ? contentId : undefined}
+      data-state={open ? 'open' : 'closed'}
       className={cn(
         !unstyled && 'btn btn-secondary',
         className,
       )}
       onClick={(event) => {
         onClick?.(event)
-        if (!event.defaultPrevented) setOpen(!open)
+        if (event.defaultPrevented) return
+        if (open) closeMenu()
+        else openMenu('first')
+      }}
+      onKeyDown={(event) => {
+        onKeyDown?.(event)
+        if (event.defaultPrevented) return
+        // APG menu button: Down opens onto the first item, Up onto the last.
+        if (event.key === 'ArrowDown') {
+          event.preventDefault()
+          openMenu('first')
+        } else if (event.key === 'ArrowUp') {
+          event.preventDefault()
+          openMenu('last')
+        }
       }}
       {...rest}
     >
       {children}
     </button>
   )
-}
+})
 export interface DropdownMenuContentProps
   extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
@@ -158,142 +337,222 @@ export interface DropdownMenuContentProps
   align?: Align
   /** Pixel offset along the alignment axis. Default 0. */
   alignOffset?: number
-  /** Place above (`top`) or below (`bottom`) the trigger. Default `bottom`. */
+  /**
+   * Preferred side of the trigger. Default `bottom`. Flips to the opposite
+   * side when it cannot fit (before the 2026-09-05 rebuild it was clamped
+   * over its own trigger instead; only that no-room case differs).
+   */
   side?: Side
   /** Pixel offset along the side axis. Default 6. */
   sideOffset?: number
 }
-export function DropdownMenuContent({
-  children,
-  align = 'start',
-  alignOffset = 0,
-  side = 'bottom',
-  sideOffset = 6,
-  className,
-  style,
-  ...rest
-}: DropdownMenuContentProps) {
-  const { open, setOpen, triggerRef, contentId } =
+export const DropdownMenuContent = forwardRef<
+  HTMLDivElement,
+  DropdownMenuContentProps
+>(function DropdownMenuContent(
+  {
+    children,
+    align = 'start',
+    alignOffset = 0,
+    side = 'bottom',
+    sideOffset = 6,
+    className,
+    style,
+    onKeyDown,
+    onFocus,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const { open, closeMenu, triggerRef, contentId, initialFocusRef, focusEdgeRef } =
     useDropdownMenuCtx('DropdownMenuContent')
   const contentRef = useRef<HTMLDivElement | null>(null)
-  const [position, setPosition] = useState<{ left: number; top: number } | null>(
-    null,
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: triggerRef,
+    side,
+    align,
+    offset: sideOffset,
+    alignOffset,
+    enabled: open,
+  })
+  // Topmost-wins Escape, shared with Modal and Popover.
+  const layer = useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: contentRef,
+    onEscape: () => closeMenu(),
+  })
+  useOutsideClick(
+    [triggerRef, contentRef],
+    () => {
+      // Restore only when focus is still ours to give back. If the pointer
+      // landed on another focusable control, the browser's own mousedown
+      // focus (which runs after this pointerdown) must win.
+      const active = document.activeElement
+      const inside =
+        active instanceof HTMLElement && Boolean(contentRef.current?.contains(active))
+      closeMenu({ restoreFocus: inside })
+    },
+    { enabled: open, layer },
   )
-  // Position relative to the trigger viewport rect. We measure on
-  // open + on layout changes (scroll / resize) so the panel tracks.
-  useLayoutEffect(() => {
-    if (!open) {
-      setPosition(null)
-      return
-    }
-    const measure = () => {
-      const triggerEl = triggerRef.current
-      const contentEl = contentRef.current
-      if (!triggerEl || !contentEl) return
-      const triggerRect = triggerEl.getBoundingClientRect()
-      const contentRect = contentEl.getBoundingClientRect()
-      let left = triggerRect.left + alignOffset
-      if (align === 'end') left = triggerRect.right - contentRect.width - alignOffset
-      else if (align === 'center')
-        left =
-          triggerRect.left +
-          triggerRect.width / 2 -
-          contentRect.width / 2 +
-          alignOffset
-      let top =
-        side === 'bottom'
-          ? triggerRect.bottom + sideOffset
-          : triggerRect.top - contentRect.height - sideOffset
-      // Keep on-screen — clamp to viewport with an 8px gutter.
-      const gutter = 8
-      const maxLeft = window.innerWidth - contentRect.width - gutter
-      const maxTop = window.innerHeight - contentRect.height - gutter
-      left = Math.max(gutter, Math.min(left, maxLeft))
-      top = Math.max(gutter, Math.min(top, maxTop))
-      setPosition({ left, top })
-    }
+  const ref = useMemo(
+    () => composeRefs<HTMLDivElement>(forwardedRef, contentRef, positionRef),
+    [forwardedRef, positionRef],
+  )
+  /** Focus item `index`, wrapping, and rove the tab stop onto it. */
+  const focusIndex = useCallback((index: number) => {
+    const items = menuItemsIn(contentRef.current)
+    if (items.length === 0) return
+    const wrapped = ((index % items.length) + items.length) % items.length
+    applyRoving(items, wrapped)
+    items[wrapped]?.focus()
+  }, [])
+  /**
+   * Entry point for "put focus in the menu". Items first; a menu that is
+   * really a small form (range-filter chip) falls back to its first field,
+   * and a menu with nothing focusable to the surface itself — anything but
+   * leaving focus behind on the trigger with the menu open.
+   */
+  const focusEdge = useCallback(
+    (where: InitialFocus) => {
+      const content = contentRef.current
+      if (!content) return
+      const items = menuItemsIn(content)
+      if (items.length > 0) {
+        focusIndex(where === 'last' ? items.length - 1 : 0)
+        return
+      }
+      const focusable = Array.from(
+        content.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      )
+      const fallback =
+        where === 'last' ? focusable[focusable.length - 1] : focusable[0]
+      ;(fallback ?? content).focus()
+    },
+    [focusIndex],
+  )
-    measure()
-    window.addEventListener('resize', measure)
-    window.addEventListener('scroll', measure, true)
+  // The trigger reaches back in here for ArrowDown on an already-open menu.
+  useEffect(() => {
+    focusEdgeRef.current = focusEdge
     return () => {
-      window.removeEventListener('resize', measure)
-      window.removeEventListener('scroll', measure, true)
+      if (focusEdgeRef.current === focusEdge) focusEdgeRef.current = null
     }
-  }, [open, align, alignOffset, side, sideOffset, triggerRef])
+  }, [focusEdge, focusEdgeRef])
-  // Outside-click + Escape dismissal.
+  // Focus on open — gated on `positioned` because the first paint is parked
+  // off-screen with `visibility: hidden`, and a hidden element cannot take
+  // focus. Once per open.
+  const didFocusRef = useRef(false)
   useEffect(() => {
-    if (!open) return
-    const onPointerDown = (event: PointerEvent) => {
-      const target = event.target as Node | null
-      if (!target) return
-      if (contentRef.current?.contains(target)) return
-      if (triggerRef.current?.contains(target)) return
-      setOpen(false)
+    if (!open) {
+      didFocusRef.current = false
+      return
     }
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        event.stopPropagation()
-        setOpen(false)
-        triggerRef.current?.focus()
-      }
+    if (!positioned || didFocusRef.current) return
+    didFocusRef.current = true
+    focusEdge(initialFocusRef.current)
+  }, [open, positioned, focusEdge, initialFocusRef])
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event)
+    if (event.defaultPrevented) return
+    const { key } = event
+    if (
+      key !== 'ArrowDown' &&
+      key !== 'ArrowUp' &&
+      key !== 'Home' &&
+      key !== 'End' &&
+      key !== 'Tab'
+    ) {
+      return
     }
-    document.addEventListener('pointerdown', onPointerDown)
-    document.addEventListener('keydown', onKeyDown)
-    return () => {
-      document.removeEventListener('pointerdown', onPointerDown)
-      document.removeEventListener('keydown', onKeyDown)
+    const target = event.target
+    const current =
+      target instanceof HTMLElement
+        ? target.closest<HTMLElement>(MENU_ITEM_SELECTOR)
+        : null
+    if (key === 'Tab') {
+      // APG: Tab closes the menu. Only from an item — a form-shaped menu
+      // must keep ordinary tabbing between its own fields.
+      if (!current) return
+      // Land on the trigger rather than letting the default action continue:
+      // the content is portaled to the END of <body>, so the "next element
+      // after it" is nothing at all — the tab sequence falls off the
+      // document. One extra Tab from the trigger then moves on normally.
+      event.preventDefault()
+      closeMenu()
+      return
     }
-  }, [open, setOpen, triggerRef])
-  if (!open || typeof document === 'undefined') return null
+    if (ownsArrowKeys(target)) return
+    const items = menuItemsIn(contentRef.current)
+    if (items.length === 0) return
+    event.preventDefault()
+    const index = current ? items.indexOf(current) : -1
+    if (key === 'Home') focusIndex(0)
+    else if (key === 'End') focusIndex(items.length - 1)
+    else if (key === 'ArrowDown') focusIndex(index + 1)
+    else focusIndex(index <= 0 ? items.length - 1 : index - 1)
+  }
-  // Two-phase render: first paint measures the content invisibly at
-  // (0,0) with opacity:0, useLayoutEffect computes the real position,
-  // and the second paint applies the correct coords + entrance animation.
-  // The animation classes are gated behind `isPositioned` so the
-  // entrance never fires from the unpositioned location — that's what
-  // caused the "flash at top of viewport then jump under the trigger"
-  // glitch.
-  const isPositioned = position !== null
+  const handleFocus = (event: ReactFocusEvent<HTMLDivElement>) => {
+    onFocus?.(event)
+    // Keep the single tab stop on whatever actually holds focus, including
+    // focus arriving by pointer.
+    const item = event.target.closest<HTMLElement>(MENU_ITEM_SELECTOR)
+    if (!item) return
+    const items = menuItemsIn(contentRef.current)
+    const index = items.indexOf(item)
+    if (index >= 0) applyRoving(items, index)
+  }
+  if (!open || typeof document === 'undefined') return null
+  // Two-phase render (see lib/anchor.ts): the hook parks the first paint
+  // off-screen and hidden, measures, then applies real coordinates. The
+  // entrance animation is gated on `positioned` so it never fires from the
+  // parked location — that was the "flash at top of viewport then jump
+  // under the trigger" glitch.
   return createPortal(
     <div
-      ref={contentRef}
+      ref={ref}
       id={contentId}
       role="menu"
+      aria-orientation="vertical"
+      // Focusable surface, so a menu with nothing focusable inside still
+      // has somewhere to put focus instead of dropping it to <body>.
+      tabIndex={-1}
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
       data-slot="dropdown-menu-content"
       data-state="open"
-      data-positioned={isPositioned ? 'true' : 'false'}
+      data-side={placement?.side}
+      data-align={placement?.align}
+      data-positioned={positioned ? 'true' : 'false'}
       className={cn(
         'fixed z-[100] min-w-48 max-w-[min(28rem,calc(100vw-16px))]',
         'p-1.5 overflow-y-auto',
         'rounded-[var(--radius-lg)]',
-        isPositioned && 'ds-enter-pop',
+        positioned && 'ds-enter-pop',
         className,
       )}
       style={{
-        // Anchor the unpositioned phase WAY off-screen as a defense
-        // against any browser/renderer that doesn't fully respect
-        // visibility:hidden during a same-frame double-render. If the
-        // first paint slips through, it's at (-99999, -99999), not at
-        // viewport (0, 0) where a left-edge flash would be visible.
-        left: position?.left ?? -99999,
-        top: position?.top ?? -99999,
-        opacity: isPositioned ? undefined : 0,
-        pointerEvents: isPositioned ? undefined : 'none',
-        visibility: isPositioned ? 'visible' : 'hidden',
-        background: 'rgb(var(--popover))',
-        color: 'rgb(var(--popover-foreground))',
-        border: '1px solid rgb(var(--border))',
-        boxShadow: 'var(--shadow-lg, 0 10px 32px rgba(0,0,0,0.18))',
+        ...positionStyle,
+        ...POPOVER_SURFACE_STYLE,
         ...style,
       }}
       {...rest}
@@ -302,7 +561,7 @@ export function DropdownMenuContent({
     </div>,
     document.body,
   )
-}
+})
 export interface DropdownMenuItemProps
   extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -312,17 +571,17 @@ export interface DropdownMenuItemProps
   inset?: boolean
 }
-export function DropdownMenuItem({
-  variant = 'default',
-  inset,
-  className,
-  onClick,
-  children,
-  ...rest
-}: DropdownMenuItemProps) {
-  const { setOpen } = useDropdownMenuCtx('DropdownMenuItem')
+export const DropdownMenuItem = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuItemProps
+>(function DropdownMenuItem(
+  { variant = 'default', inset, className, onClick, children, ...rest },
+  forwardedRef,
+) {
+  const { closeMenu } = useDropdownMenuCtx('DropdownMenuItem')
   return (
     <button
+      ref={forwardedRef}
       role="menuitem"
       type="button"
       data-slot="dropdown-menu-item"
@@ -341,14 +600,17 @@ export function DropdownMenuItem({
       )}
       onClick={(event) => {
         onClick?.(event)
-        if (!event.defaultPrevented) setOpen(false)
+        // Activation closes AND hands focus back to the trigger. Without the
+        // restore, a dialog opened from here has no `activeElement` to
+        // capture and its own close drops focus to <body>.
+        if (!event.defaultPrevented) closeMenu()
       }}
       {...rest}
     >
       {children}
     </button>
   )
-}
+})
 export interface DropdownMenuCheckboxItemProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
@@ -356,17 +618,16 @@ export interface DropdownMenuCheckboxItemProps
   onCheckedChange?: (checked: boolean) => void
 }
-export function DropdownMenuCheckboxItem({
-  checked,
-  onCheckedChange,
-  className,
-  children,
-  onClick,
-  disabled,
-  ...rest
-}: DropdownMenuCheckboxItemProps) {
+export const DropdownMenuCheckboxItem = forwardRef<
+  HTMLButtonElement,
+  DropdownMenuCheckboxItemProps
+>(function DropdownMenuCheckboxItem(
+  { checked, onCheckedChange, className, children, onClick, disabled, ...rest },
+  forwardedRef,
+) {
   return (
     <button
+      ref={forwardedRef}
       role="menuitemcheckbox"
       type="button"
       data-slot="dropdown-menu-checkbox-item"
@@ -399,7 +660,7 @@ export function DropdownMenuCheckboxItem({
       ) : null}
     </button>
   )
-}
+})
 export function DropdownMenuSeparator({
   className,