@helloimjolopez-pathway/pathway-components 0.10.0 → 0.10.2

package/components/popover-menu/popover-menu.jsx

@@ -0,0 +1,747 @@
+/**
+ * PopoverMenu, Pathway Design System
+ *
+ * Importable React component module. Source of truth for the Menu
+ * implementation (Figma calls it PopoverMenu); the standalone demo
+ * (popover-menu.html), the Storybook stories and every component that opens a
+ * menu consume this. It replaces components/dropdown/ (Dropdown, DropdownItem,
+ * DropdownDivider), which drew the 2026-10-08 PopoverMenu look by hand.
+ *
+ * The floating list Pathway shows when actions or choices appear on demand:
+ * a row's More menu, a widget's actions, a picker opened from a pill, the
+ * panel a Select or an Input opens. Two modes on one anatomy:
+ *   actions  React Aria Menu: menu, menuitem / menuitemradio / menuitemcheckbox
+ *   options  React Aria ListBox: listbox, option (the Select and Input panel)
+ * Not page navigation (SideNav, Tabs), not a form (Dialog, Sheet), not a few
+ * choices that should stay visible (Radio, Toggle Button).
+ *
+ * Built on React Aria Components, the same primitives as the approved Menu
+ * demo (pathway-family-demo/menu), so arrows, Home and End, typeahead,
+ * submenus, Esc, focus return and the roles all come from one tested source.
+ *
+ * Figma properties to props:
+ *   PopoverMenu        Show Header, Header     `header`
+ *                      Show Footer, Footer     `footer`
+ *                      Items slot              children (items, sections, separators)
+ *   PopoverMenu.Item   State                   runtime (hover, focus, pressed); Disabled is `disabled`
+ *                      Selected                from the menu's selection (`selectedKeys`), or `selected` on a static list
+ *                      Tone (Default, Destructive)  `tone`
+ *                      Label                   `label`
+ *                      Show Description, Description  `description`
+ *                      Show Inline Text, Inline Text  `inlineText`
+ *                      Show Reason, Reason     `reason` (makes the item unavailable)
+ *                      Show Indicator + Leading Type (Check / Radio / Checkbox)  `indicator`
+ *                      Show Stripe             `indicator="stripe"`
+ *                      Show Visual + Leading Type (Icon, Avatar, Dot, Swatch, Spinner)  `leading`, `loading`
+ *                      Show Trailing + Trailing Type  `trailing`
+ *                      Show Badges             `badges`
+ *   PopoverMenu.SectionHeader  Title, Position  `PopoverMenuSection title`; Position is worked out from where the section sits
+ *   PopoverMenu.Separator                      `PopoverMenuSeparator`
+ *   PopoverMenu.Status Type                    `PopoverMenuStatus type`
+ *
+ * Spec:  components/popover-menu/popover-menu-spec.md
+ * Figma: https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40005568-4207 (PopoverMenu)
+ *        https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40005568-4191 (PopoverMenu.Item)
+ */
+
+import React, { createContext, useContext, useEffect, useId, useRef, useState } from "react";
+import {
+  Menu as RACMenu, MenuItem as RACMenuItem, MenuSection, SubmenuTrigger,
+  ListBox, ListBoxItem, ListBoxSection, Header, Separator, Popover, Keyboard,
+  MenuContext, PopoverContext, OverlayTriggerStateContext, RootMenuTriggerStateContext,
+  Provider,
+} from "react-aria-components";
+import { useMenuTriggerState } from "react-stately";
+import { Icon } from "../icon/icon.jsx";
+import { ActionIcon } from "../icon/action-icon.jsx";
+import { Checkbox } from "../checkbox/checkbox.jsx";
+import { RadioMark } from "../radio/radio.jsx";
+import { Spinner } from "../spinner/spinner.jsx";
+import { Badge } from "../badge/badge.jsx";
+import { Avatar, initialsFrom } from "../avatar/avatar.jsx";
+import { Button } from "../button/button.jsx";
+
+// ─── TOKEN HELPERS ────────────────────────────────────────────────────────────
+// SC = semantic-color (themes/*.css), SL = semantic-layout-units (layout.css),
+// CL = contextual-layout-units (layout-contextual.css), ST = semantic-type
+// (type.css), M = motion (motion.css). Modeless names only.
+const SC = (p) => `var(--semantic-color-${p})`;
+const SL = (p) => `var(--semantic-layout-units-${p})`;
+const CL = (p) => `var(--contextual-layout-units-${p})`;
+const ST = (p) => `var(--semantic-type-${p})`;
+const M = (p) => `var(--motion-${p})`;
+
+export const INDICATORS = ["none", "check", "check-start", "radio", "checkbox", "stripe"];
+export const LEADING_TYPES = ["icon", "avatar", "dot", "swatch"];
+export const TRAILING_TYPES = ["shortcut", "text", "count", "chevron", "icon"];
+export const TONES = ["Default", "Destructive"];
+export const DOT_TONES = ["positive", "attention", "negative", "neutral"];
+export const STATUS_TYPES = ["Loading", "Empty", "No Matches", "Error"];
+export const TRIGGER_TYPES = ["icon", "button", "avatar"];
+
+// ─── COLOUR TOKENS ────────────────────────────────────────────────────────────
+// Per state, exactly as Figma binds them (spec §5).
+export const T = {
+  panel:          SC("fill-surface-elevated"),
+  panelBorder:    SC("stroke-static-neutral-faint"),
+  slotDivider:    SC("stroke-static-neutral-base"),
+  separator:      SC("stroke-static-neutral-base"),
+  fillHover:      SC("fill-static-neutral-subtle"),
+  fillPressed:    SC("fill-static-neutral-base"),
+  fillSelected:   SC("fill-action-selection-selected"),
+  fillDangerHover:   SC("fill-action-status-negative-subtle-hover"),
+  fillDangerPressed: SC("fill-action-status-negative-subtle-pressed"),
+  stripe:         SC("fill-action-primary-strong-pressed"),
+  label:          SC("foreground-static-neutral-strong"),
+  labelHover:     SC("foreground-static-neutral-bold"),
+  labelDanger:        SC("foreground-action-status-negative-on-subtle-rest"),
+  labelDangerHover:   SC("foreground-action-status-negative-on-subtle-hover"),
+  labelDangerPressed: SC("foreground-action-status-negative-on-subtle-pressed"),
+  disabled:       SC("foreground-action-disabled"),
+  secondary:      SC("foreground-static-neutral-subtle"),
+  reason:         SC("foreground-static-neutral-base"),
+  check:          SC("foreground-action-primary-on-subtle-rest"),
+  countFill:      SC("fill-static-neutral-base"),
+  countText:      SC("foreground-static-neutral-bold"),
+  countFillDisabled: SC("fill-action-disabled"),
+  swatchEdge:     SC("stroke-static-neutral-base"),
+  dot: {
+    positive:  SC("fill-static-positive-strong"),
+    attention: SC("fill-static-attention-strong"),
+    negative:  SC("fill-static-negative-strong"),
+    neutral:   SC("fill-static-neutral-strong"),
+  },
+  statusTitle:    SC("foreground-static-neutral-bold"),
+  statusBody:     SC("foreground-static-neutral-base"),
+  focusRing:      SC("stroke-focusring-base"),
+  // The Icon trigger is a bare glyph in Figma; its colour follows the host.
+  trigger:        SC("foreground-action-secondary-rest"),
+  triggerHover:   SC("foreground-action-secondary-hover"),
+  buttonFill:     SC("fill-surface-elevated"),
+  buttonFillHover: SC("fill-action-selection-hover"),
+  buttonBorder:   SC("stroke-action-secondary-rest"),
+  avatarFill:     SC("fill-action-primary-subtle-rest"),
+  avatarText:     SC("foreground-action-primary-on-subtle-rest"),
+};
+
+// ─── LAYOUT ───────────────────────────────────────────────────────────────────
+// Widths, heights and glyph sizes are measurements, not tokens (CLAUDE.md §5).
+export const L = {
+  panelRadius:  SL("cornerradius-large"),
+  panelBorder:  SL("borderwidth-xthin"),
+  shadow:       "var(--elevation-lift)",
+  listPadV:     SL("padding-xtight"),
+  listPadH:     SL("padding-xxtight"),
+  itemGap:      SL("gap-xxxtight"),
+  slotPad:      SL("padding-xtight"),
+  footerPad:    SL("padding-tight"),
+  footerGap:    SL("gap-tight"),
+  itemMinH:     SL("accessibility-touch-target-aa-height"),   // 44, Touch Target/AA
+  itemPad:      SL("padding-tight"),
+  itemContentGap: SL("gap-medium"),
+  leadGroupGap: SL("gap-tight"),     // indicator to leading visual
+  textGap:      SL("gap-xxxtight"),  // label to description
+  inlineGap:    SL("gap-tight"),     // label to inline text
+  badgeGap:     SL("gap-xxtight"),   // label to badges (G13)
+  reasonGap:    SL("gap-xxtight"),
+  trailGap:     SL("gap-xxtight"),
+  itemRadius:   SL("cornerradius-base"),
+  fullRadius:   SL("cornerradius-full"),
+  swatchRadius: SL("cornerradius-small"),
+  headerPadTop: { First: SL("padding-xxtight"), "After Separator": SL("padding-xtight"), Default: SL("padding-base") },
+  headerPadL:   SL("padding-tight"),
+  headerPadR:   SL("padding-xtight"),
+  headerPadB:   SL("padding-xxtight"),
+  separatorMargin: SL("padding-xtight"),
+  stripeW:      SL("borderwidth-xthick"),
+  stripeInset:  SL("padding-xtight"),
+  countPadH:    SL("padding-xtight"),
+  statusPadV:   SL("padding-base"),
+  statusPadH:   SL("padding-tight"),
+  statusGap:    SL("gap-xxtight"),
+  offset:       8,                   // Gap/Tight, a number because React Aria takes px
+  width:        280,
+  minWidth:     220,
+  maxWidth:     360,
+  maxHeight:    440,
+  searchHeight: 360,
+  leadBox:      20,
+  glyph:        18,
+  dot:          8,
+  swatch:       16,
+  spinner:      16,
+  countMin:     24,
+  focusWidth:   CL("focusring-width"),
+  // Triggers carried over from Dropdown (Widget, KPI Tile, Toggle Button).
+  triggerTarget: SL("accessibility-touch-target-aa-width"),
+  triggerTargetH: SL("accessibility-touch-target-aa-height"),
+  triggerGlyph: 20,
+  avatarBox:    28,
+  buttonPadV:   SL("padding-xtight"),
+  buttonPadH:   SL("padding-tight"),
+  buttonBorder: SL("borderwidth-base"),
+};
+
+// ─── TYPE ─────────────────────────────────────────────────────────────────────
+// Label/Menu/Base/Medium, Text/Supporting/Base/Regular and /Semibold. Letter
+// spacing is normal for the label and supporting text (G9).
+export const TYPE = {
+  label:   { fontSize: ST("font-size-s"), lineHeight: ST("line-height-s-single"), fontWeight: ST("weight-medium") },
+  support: { fontSize: ST("font-size-xs"), lineHeight: ST("line-height-xs-single"), fontWeight: ST("weight-regular") },
+  header:  { fontSize: ST("font-size-xs"), lineHeight: ST("line-height-xs-single"), fontWeight: ST("weight-semibold"), letterSpacing: ST("letter-spacing-wide") },
+};
+
+const ITEM = ".pw-menu-item";
+const live = (s) => `${ITEM}:not([data-disabled]):is(${s})`;
+const HOVER = "[data-hovered],[data-focused],[data-open],[data-force=Hover],[data-force=Focus]";
+const PRESS = "[data-pressed],[data-force=Pressed]";
+
+/* --trigger-width and --visual-viewport-height are set inline by React Aria's
+   Popover; the defaults here only apply before it measures. */
+const CSS = `
+.pw-menu-panel{--trigger-width:0px;--visual-viewport-height:100vh;box-sizing:border-box;display:flex;flex-direction:column;overflow:hidden;outline:none;
+  width:clamp(${L.minWidth}px,max(${L.width}px,var(--trigger-width,0px)),${L.maxWidth}px);
+  max-width:min(${L.maxWidth}px,calc(100vw - 2 * ${SL("padding-tight")}));
+  max-height:min(${L.maxHeight}px,var(--visual-viewport-height,100vh));
+  background:${T.panel};border:${L.panelBorder} solid ${T.panelBorder};border-radius:${L.panelRadius};box-shadow:${L.shadow};
+  font-family:${ST("family-brand")},sans-serif}
+.pw-menu-panel[data-searchable]{height:${L.searchHeight}px}
+.pw-menu-panel[data-entering]{animation:pw-menu-in ${M("duration-4")} ${M("easing-decelerate")} both}
+.pw-menu-panel[data-placement=top][data-entering]{animation-name:pw-menu-in-up}
+.pw-menu-panel[data-exiting]{animation:pw-menu-out ${M("duration-2")} ${M("easing-standard")} both}
+@keyframes pw-menu-in{from{opacity:0;transform:translateY(-4px)}to{opacity:1;transform:none}}
+@keyframes pw-menu-in-up{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}
+@keyframes pw-menu-out{from{opacity:1}to{opacity:0}}
+
+.pw-menu{display:flex;flex-direction:column;min-height:0;flex:1 1 auto;font-family:${ST("family-brand")},sans-serif}
+.pw-menu--static{box-sizing:border-box;width:${L.width}px;max-width:100%;background:${T.panel};
+  border:${L.panelBorder} solid ${T.panelBorder};border-radius:${L.panelRadius};box-shadow:${L.shadow};overflow:hidden}
+.pw-menu--bare{width:100%}
+.pw-menu__header{flex:none;padding:${L.slotPad};border-bottom:${L.panelBorder} solid ${T.slotDivider}}
+.pw-menu__footer{flex:none;display:flex;justify-content:flex-end;gap:${L.footerGap};
+  padding:${L.slotPad} ${L.footerPad} ${L.footerPad};border-top:${L.panelBorder} solid ${T.slotDivider}}
+.pw-menu__scroll{flex:1 1 auto;min-height:0;overflow-y:auto;overscroll-behavior:contain}
+.pw-menu__list{display:flex;flex-direction:column;gap:${L.itemGap};padding:${L.listPadV} ${L.listPadH};outline:none}
+.pw-menu--bare .pw-menu__list{padding:0}
+.pw-menu__list[data-empty]:focus-visible{outline:${L.focusWidth} solid ${T.focusRing};outline-offset:calc(-1 * ${L.focusWidth});border-radius:${L.panelRadius}}
+
+${ITEM}{position:relative;display:flex;align-items:flex-start;gap:${L.itemContentGap};box-sizing:border-box;
+  min-height:${L.itemMinH};padding:${L.itemPad};border-radius:${L.itemRadius};
+  color:${T.label};font-size:${TYPE.label.fontSize};line-height:${TYPE.label.lineHeight};font-weight:${TYPE.label.fontWeight};letter-spacing:normal;
+  cursor:pointer;outline:none;text-decoration:none;-webkit-tap-highlight-color:transparent;
+  transition:background-color ${M("duration-2")} ${M("easing-standard")},color ${M("duration-2")} ${M("easing-standard")}}
+${live(HOVER)}{background:${T.fillHover};color:${T.labelHover}}
+${live(PRESS)}{background:${T.fillPressed};color:${T.label}}
+${ITEM}:not([data-disabled]):is([data-selected],[data-current]){background:${T.fillSelected};color:${T.label}}
+${ITEM}:is([data-focus-visible],[data-force=Focus]){outline:${L.focusWidth} solid ${T.focusRing};outline-offset:calc(-1 * ${L.focusWidth})}
+${ITEM}[role=option][data-focused][data-hovered]:not([data-focus-visible]){outline:none}
+${ITEM}[data-tone=Destructive]{color:${T.labelDanger}}
+${ITEM}[data-tone=Destructive]:not([data-disabled]):is(${HOVER}){background:${T.fillDangerHover};color:${T.labelDangerHover}}
+${ITEM}[data-tone=Destructive]:not([data-disabled]):is(${PRESS}){background:${T.fillDangerPressed};color:${T.labelDangerPressed}}
+${ITEM}[data-disabled]{color:${T.disabled};background:transparent;cursor:default}
+
+.pw-menu-item__lead-group{flex:none;display:inline-flex;align-items:center;gap:${L.leadGroupGap};min-height:${TYPE.label.lineHeight}}
+.pw-menu-item__lead{flex:none;width:${L.leadBox}px;height:${L.leadBox}px;display:inline-flex;align-items:center;justify-content:center}
+.pw-menu-item__lead .material-symbols-rounded,.pw-menu-item__trail .material-symbols-rounded{font-size:${L.glyph}px}
+.pw-menu-item__check{color:${T.check}}
+${ITEM}[data-disabled] .pw-menu-item__check{color:${T.disabled}}
+.pw-menu-item__lead--hidden{visibility:hidden}
+.pw-menu-item__control{overflow:hidden}
+.pw-menu-item__control > *{flex:none;pointer-events:none}
+.pw-menu-item__lead--avatar{width:auto;height:auto}
+.pw-menu-item__dot{width:${L.dot}px;height:${L.dot}px;border-radius:${L.fullRadius}}
+.pw-menu-item__swatch{box-sizing:border-box;width:${L.swatch}px;height:${L.swatch}px;border-radius:${L.swatchRadius};border:${L.panelBorder} solid ${T.swatchEdge}}
+
+.pw-menu-item__text{flex:1 1 auto;min-width:0;display:flex;flex-direction:column;gap:${L.textGap}}
+.pw-menu-item__text[data-inline]{flex-direction:row;align-items:baseline;gap:${L.inlineGap}}
+.pw-menu-item__label-row{display:flex;align-items:center;gap:${L.badgeGap};min-width:0}
+.pw-menu-item__label{display:block;flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.pw-menu-item__label-row > :not(.pw-menu-item__label){flex:none}
+.pw-menu-item__desc{font-size:${TYPE.support.fontSize};line-height:${TYPE.support.lineHeight};font-weight:${TYPE.support.fontWeight};
+  color:${T.secondary};overflow-wrap:anywhere;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+.pw-menu-item__text[data-inline] .pw-menu-item__desc{flex:0 1 auto;display:block;white-space:nowrap;text-overflow:ellipsis}
+.pw-menu-item__reason{display:flex;align-items:center;gap:${L.reasonGap};color:${T.reason};
+  font-size:${TYPE.support.fontSize};line-height:${TYPE.support.lineHeight};font-weight:${TYPE.support.fontWeight}}
+.pw-menu-item__reason .material-symbols-rounded{font-size:${L.spinner}px}
+${ITEM}[data-disabled] .pw-menu-item__desc{color:${T.disabled}}
+
+.pw-menu-item__trail{flex:none;display:inline-flex;align-items:center;gap:${L.trailGap};margin-left:auto;min-height:${TYPE.label.lineHeight};
+  color:${T.secondary};font-size:${TYPE.support.fontSize};line-height:${TYPE.support.lineHeight};font-weight:${TYPE.support.fontWeight};font-variant-numeric:tabular-nums}
+.pw-menu-item__kbd{font-family:inherit;font-size:inherit}
+.pw-menu-item__count{box-sizing:border-box;min-width:${L.countMin}px;text-align:center;padding:0 ${L.countPadH};border-radius:${L.fullRadius};
+  background:${T.countFill};color:${T.countText}}
+${ITEM}[data-selected] .pw-menu-item__count{background:${T.panel}}
+${ITEM}[data-disabled] .pw-menu-item__trail{color:${T.disabled}}
+${ITEM}[data-disabled] .pw-menu-item__count{background:${T.countFillDisabled};color:${T.disabled}}
+
+.pw-menu-item__stripe{position:absolute;left:0;top:${L.stripeInset};bottom:${L.stripeInset};width:${L.stripeW};
+  border-radius:0 ${L.itemRadius} ${L.itemRadius} 0;background:transparent}
+${ITEM}:is([data-selected],[data-current]) .pw-menu-item__stripe{background:${T.stripe}}
+
+.pw-menu-section{display:flex;flex-direction:column;gap:${L.itemGap}}
+.pw-menu-section__header{padding:${L.headerPadTop.Default} ${L.headerPadR} ${L.headerPadB} ${L.headerPadL};color:${T.secondary};
+  font-size:${TYPE.header.fontSize};line-height:${TYPE.header.lineHeight};font-weight:${TYPE.header.fontWeight};letter-spacing:${TYPE.header.letterSpacing}}
+.pw-menu__list > .pw-menu-section:first-child > .pw-menu-section__header,.pw-menu-section__header[data-position=First]{padding-top:${L.headerPadTop.First}}
+.pw-menu-separator + .pw-menu-section > .pw-menu-section__header,.pw-menu-section__header[data-position="After Separator"]{padding-top:${L.headerPadTop["After Separator"]}}
+.pw-menu-separator{height:0;border:0;border-top:${L.panelBorder} solid ${T.separator};margin:${L.separatorMargin}}
+
+.pw-menu-status{display:flex;flex-direction:column;align-items:flex-start;gap:${L.statusGap};padding:${L.statusPadV} ${L.statusPadH};
+  color:${T.statusBody};font-size:${TYPE.label.fontSize};line-height:${TYPE.label.lineHeight};font-weight:${ST("weight-regular")}}
+.pw-menu-status__row{display:flex;align-items:center;gap:${L.leadGroupGap}}
+.pw-menu-status__title{color:${T.statusTitle};font-weight:${TYPE.label.fontWeight}}
+.pw-menu-status__body{font-size:${TYPE.support.fontSize};line-height:${TYPE.support.lineHeight}}
+
+.pw-menu-trigger{position:relative;display:inline-flex}
+.pw-menu-trigger__icon,.pw-menu-trigger__button,.pw-menu-trigger__avatar{font-family:inherit;cursor:pointer;outline:none;-webkit-tap-highlight-color:transparent;
+  transition:color ${M("duration-2")} ${M("easing-standard")},background-color ${M("duration-2")} ${M("easing-standard")}}
+.pw-menu-trigger__icon{display:inline-flex;align-items:center;justify-content:center;flex:none;padding:0;border:0;background:transparent;color:${T.trigger}}
+.pw-menu-trigger__icon:is(:hover,[aria-expanded=true]){color:${T.triggerHover}}
+.pw-menu-trigger__button{display:inline-flex;align-items:center;gap:${L.badgeGap};white-space:nowrap;box-sizing:border-box;min-height:${L.triggerTargetH};padding:${L.buttonPadV} ${L.buttonPadH};
+  background:${T.buttonFill};border:${L.buttonBorder} solid ${T.buttonBorder};border-radius:${L.itemRadius};color:${T.trigger};
+  font-size:${TYPE.label.fontSize};line-height:${TYPE.label.lineHeight}}
+.pw-menu-trigger__button:hover{background:${T.buttonFillHover}}
+.pw-menu-trigger__avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:${L.avatarBox}px;height:${L.avatarBox}px;
+  border:0;border-radius:${L.itemRadius};background:${T.avatarFill};color:${T.avatarText};font-size:${ST("font-size-xxs")};font-weight:${ST("weight-semibold")}}
+.pw-menu-trigger :is(.pw-menu-trigger__icon,.pw-menu-trigger__button,.pw-menu-trigger__avatar):focus-visible{outline:${L.focusWidth} solid ${T.focusRing}}
+
+@media (prefers-reduced-motion: reduce){
+  .pw-menu-panel[data-entering],.pw-menu-panel[data-placement=top][data-entering]{animation:pw-menu-fade ${M("duration-2")} ${M("easing-standard")} both}
+  .pw-menu-panel[data-exiting]{animation:pw-menu-out ${M("duration-2")} ${M("easing-standard")} both}
+  @keyframes pw-menu-fade{from{opacity:0}to{opacity:1}}
+}
+`;
+
+let injected = false;
+function useStyles() {
+  useEffect(() => {
+    if (injected || typeof document === "undefined" || document.getElementById("pw-popover-menu-css")) { injected = true; return; }
+    const el = document.createElement("style");
+    el.id = "pw-popover-menu-css";
+    el.textContent = CSS;
+    document.head.appendChild(el);
+    injected = true;
+  }, []);
+}
+
+/* Picks are seen before the panel goes: the row shows its new state for
+   Duration/3, then the panel fades (approved demo). */
+const pickDelay = () => (typeof document !== "undefined"
+  && parseFloat(getComputedStyle(document.documentElement).getPropertyValue("--motion-duration-3"))) || 200;
+
+// ─── CONTEXTS ─────────────────────────────────────────────────────────────────
+
+/* Which collection the items sit in, so one PopoverMenuItem renders a React
+   Aria MenuItem in actions mode and a ListBoxItem in options mode. */
+const ModeContext = createContext("actions");
+
+/**
+ * Lets a host that is not a PopoverMenu close itself when an item is chosen,
+ * the way a PopoverMenu does. BottomSheet provides it around its Body, so a
+ * sheet of PopoverMenuItems closes on a pick. An item with
+ * `closeOnAction={false}` keeps it open (a row that swaps the sheet's Body).
+ */
+export const PopoverMenuClose = createContext(null);
+
+// ─── ITEM PARTS ───────────────────────────────────────────────────────────────
+
+function Leading({ leading, loading, disabled }) {
+  if (loading) return <span className="pw-menu-item__lead"><Spinner size={L.spinner} label="Loading" /></span>;
+  if (!leading) return null;
+  const l = typeof leading === "string" ? { type: "icon", name: leading } : leading;
+  if (l.type === "icon") return <span className="pw-menu-item__lead"><Icon name={l.name} size={L.glyph} /></span>;
+  if (l.type === "dot") {
+    return <span className="pw-menu-item__lead"><span className="pw-menu-item__dot" style={{ background: disabled ? T.disabled : (T.dot[l.tone] || T.dot.neutral) }} /></span>;
+  }
+  /* The real Avatar: 40 (M) for people rows, XS (24) for one-line rows. It
+     stays aria-hidden: the label beside it already names the person. */
+  if (l.type === "avatar") {
+    return (
+      <span className="pw-menu-item__lead pw-menu-item__lead--avatar" aria-hidden="true">
+        <Avatar size={l.size || "M"} shape="Circle" src={l.src} text={l.initials || initialsFrom(l.name || "")} />
+      </span>
+    );
+  }
+  if (l.type === "swatch") return <span className="pw-menu-item__lead"><span className="pw-menu-item__swatch" style={{ background: l.color }} /></span>;
+  return null;
+}
+
+const cap = (n, max = 99) => (n > max ? `${max}+` : String(n));
+
+function Trailing({ trailing, hasSubmenu }) {
+  if (hasSubmenu) return <span className="pw-menu-item__trail"><Icon name="chevron_right" size={L.glyph} /></span>;
+  if (!trailing) return null;
+  const t = trailing;
+  if (t.type === "shortcut") return <span className="pw-menu-item__trail"><Keyboard className="pw-menu-item__kbd">{t.keys}</Keyboard></span>;
+  if (t.type === "text") return <span className="pw-menu-item__trail">{t.text}</span>;
+  if (t.type === "count") return <span className="pw-menu-item__trail"><span className="pw-menu-item__count">{cap(t.count)}</span></span>;
+  if (t.type === "chevron") return <span className="pw-menu-item__trail"><Icon name="chevron_right" size={L.glyph} /></span>;
+  if (t.type === "icon") return <span className="pw-menu-item__trail"><Icon name={t.name} size={L.glyph} /></span>;
+  return null;
+}
+
+/* The one item anatomy: [stripe] [indicator + visual] [label, description or
+   reason] [trailing]. The indicator is the real Checkbox or Radio, visual
+   only: the item is the control and owns the role, the state and the target. */
+function ItemContent({ p, s }) {
+  const ind = p.indicator || "none";
+  const sel = !!s.isSelected;
+  const disabled = !!s.isDisabled;
+  const inline = !!p.inlineText;
+  return (
+    <>
+      {ind === "stripe" && <span className="pw-menu-item__stripe" aria-hidden="true" />}
+      {(ind === "check-start" || ind === "radio" || ind === "checkbox" || p.leading || p.loading) && (
+        <span className="pw-menu-item__lead-group">
+          {ind === "check-start" && (
+            <span className={`pw-menu-item__lead${sel ? "" : " pw-menu-item__lead--hidden"}`}>
+              <Icon name="check" size={L.glyph} className="pw-menu-item__check" />
+            </span>
+          )}
+          {ind === "radio" && (
+            <span className="pw-menu-item__lead pw-menu-item__control" inert="" aria-hidden="true">
+              <RadioMark selected={sel} disabled={disabled} />
+            </span>
+          )}
+          {ind === "checkbox" && (
+            <span className="pw-menu-item__lead pw-menu-item__control" inert="" aria-hidden="true">
+              <Checkbox checked={sel} indeterminate={!!p.mixed} disabled={disabled} size="s" />
+            </span>
+          )}
+          <Leading leading={p.leading} loading={p.loading} disabled={disabled} />
+        </span>
+      )}
+      <span className="pw-menu-item__text" data-inline={inline || undefined}>
+        {p.badges && p.badges.length ? (
+          <span className="pw-menu-item__label-row">
+            <span className="pw-menu-item__label">{p.label}</span>
+            {p.badges.map((b) => <Badge key={b.label} label={b.label} status={b.status || "Neutral"} size="Medium" badgeStyle="Outline & Fill" />)}
+          </span>
+        ) : <span className="pw-menu-item__label">{p.label}</span>}
+        {inline ? <span className="pw-menu-item__desc">{p.inlineText}</span>
+          : p.description ? <span className="pw-menu-item__desc">{p.description}</span> : null}
+        {p.reason && (
+          <span className="pw-menu-item__reason"><Icon name="info" size={L.spinner} />{p.reason}</span>
+        )}
+      </span>
+      <Trailing trailing={p.trailing} hasSubmenu={s.hasSubmenu} />
+      {ind === "check" && sel && <span className="pw-menu-item__trail"><Icon name="check" size={L.glyph} className="pw-menu-item__check" /></span>}
+    </>
+  );
+}
+
+// ─── ITEM ─────────────────────────────────────────────────────────────────────
+
+/**
+ * PopoverMenuItem: one action or option. Must sit inside a PopoverMenu or a
+ * PopoverMenuList.
+ *
+ * @param {string}  id           Key for selection and onAction. Defaults to the label
+ * @param {string}  label        Figma Label. Truncates to one line
+ * @param {string}  description  Figma Description. Stacked under the label, wraps to two lines
+ * @param {string}  inlineText   Figma Inline Text. On the label line, after it
+ * @param {string}  reason       Figma Reason. Why the item is unavailable; makes it disabled
+ * @param {"none"|"check"|"check-start"|"radio"|"checkbox"|"stripe"} indicator  How Selected shows
+ * @param {string|{type:"icon",name}|{type:"avatar",src,name,size}|{type:"dot",tone}|{type:"swatch",color}} leading  Figma Leading (visual)
+ * @param {{type:"shortcut",keys}|{type:"text",text}|{type:"count",count}|{type:"chevron"}|{type:"icon",name}} trailing  Figma Trailing
+ * @param {Array<{label,status}>} badges  Figma Show Badges. Real Badges after the label
+ * @param {"Default"|"Destructive"} tone  Figma Tone. Destructive goes last, after a separator
+ * @param {boolean} disabled     Figma State=Disabled. Stays reachable by keyboard
+ * @param {boolean} loading      A spinner replaces the leading visual while the action runs
+ * @param {boolean} mixed        Checkbox indicator only: the partly-picked state
+ * @param {boolean} current      Navigation popovers: the current page (stripe and selected fill)
+ * @param {boolean} selected     Static lists only (StateMatrix); a live menu takes selection from `selectedKeys`
+ * @param {boolean} closeOnAction  false keeps the menu open after this item runs
+ * @param {Function} onAction    () => void
+ * @param {string}  href         Makes the item a link
+ * @param {"Hover"|"Focus"|"Pressed"} forceState  Documentation only: hold a state for state matrices
+ */
+export function PopoverMenuItem({
+  id, label, description, inlineText, reason, indicator = "none", leading, trailing, badges,
+  tone = "Default", disabled = false, loading = false, mixed = false, current = false, selected = false,
+  closeOnAction, onAction, href, textValue, forceState,
+}) {
+  useStyles();
+  const mode = useContext(ModeContext);
+  const close = useContext(PopoverMenuClose);
+  const p = { label, description, inlineText, reason, indicator, leading, trailing, badges, loading, mixed, selected };
+  const key = id ?? label;
+  const common = {
+    id: key,
+    textValue: textValue || label,
+    isDisabled: !!(disabled || reason),
+    className: "pw-menu-item",
+    "data-tone": tone,
+    "data-current": current || p.selected || undefined,
+    "data-force": forceState,
+    "aria-current": current ? "page" : undefined,
+  };
+  const body = (s) => <ItemContent p={p} s={{ ...s, isSelected: s.isSelected || !!p.selected }} />;
+  if (mode === "options") {
+    return <ListBoxItem {...common} href={href}>{body}</ListBoxItem>;
+  }
+  return (
+    <RACMenuItem {...common} href={href}
+      target={href && /^https?:/.test(href) ? "_blank" : undefined}
+      shouldCloseOnSelect={closeOnAction}
+      onAction={() => { onAction?.(); if (closeOnAction !== false) close?.(); }}>
+      {body}
+    </RACMenuItem>
+  );
+}
+
+/**
+ * PopoverMenuSubmenu: one level of submenu (two at most). Right Arrow, a tap
+ * or a hover opens it; Left Arrow and Esc close it.
+ *
+ * @param {ReactElement} item  The PopoverMenuItem that opens it; it takes the chevron
+ * @param {string} label       The submenu's accessible name
+ * @param {node} children      Its items
+ */
+export function PopoverMenuSubmenu({ item, label, children, ...rest }) {
+  useStyles();
+  return (
+    <SubmenuTrigger {...rest}>
+      {item}
+      <Popover className="pw-menu-panel" placement="end top" offset={-4}>
+        <PopoverMenuList label={label}>{children}</PopoverMenuList>
+      </Popover>
+    </SubmenuTrigger>
+  );
+}
+
+/** Figma PopoverMenu.Separator: a rule between groups. Destructive actions go after one. */
+export function PopoverMenuSeparator() {
+  useStyles();
+  return <Separator className="pw-menu-separator" />;
+}
+
+/**
+ * PopoverMenuSection: a group of items under an optional PopoverMenu.SectionHeader.
+ *
+ * @param {string} title        Figma Title. Sentence case
+ * @param {"Default"|"First"|"After Separator"} position  Figma Position. Worked out from the section's place when omitted
+ * @param {"none"|"single"|"multiple"} selectionMode  A settings group inside an actions menu (Sort by, Show)
+ */
+export function PopoverMenuSection({ title, position, children, ...rest }) {
+  useStyles();
+  const mode = useContext(ModeContext);
+  const S = mode === "options" ? ListBoxSection : MenuSection;
+  return (
+    <S className="pw-menu-section" aria-label={title ? undefined : rest["aria-label"]} {...rest}>
+      {title && <Header className="pw-menu-section__header" data-position={position}>{title}</Header>}
+      {children}
+    </S>
+  );
+}
+
+// ─── STATUS ───────────────────────────────────────────────────────────────────
+
+/**
+ * PopoverMenuStatus: Figma PopoverMenu.Status. Pass it as `emptyState`, or
+ * render it in place of the items while they load.
+ *
+ * @param {"Loading"|"Empty"|"No Matches"|"Error"} type
+ * @param {string}   title     Empty and Error: the first line
+ * @param {string}   message   Loading and No Matches: the one line; Empty and Error: the second line
+ * @param {Function} onRetry   Error: shows Try again
+ */
+export function PopoverMenuStatus({ type = "Empty", title, message, onRetry, retryLabel = "Try again" }) {
+  useStyles();
+  const busy = type === "Loading";
+  return (
+    <div className="pw-menu-status" role={type === "Error" ? "alert" : "status"} aria-busy={busy || undefined} data-type={type}>
+      {busy ? (
+        <span className="pw-menu-status__row"><Spinner size={L.spinner} label="" /><span>{message || "Loading"}</span></span>
+      ) : (
+        <>
+          {title && <span className="pw-menu-status__title">{title}</span>}
+          {message && <span className={title ? "pw-menu-status__body" : undefined}>{message}</span>}
+          {type === "Error" && onRetry && <Button size="S" buttonStyle="Outlined" type="Secondary" text={retryLabel} onClick={onRetry} />}
+        </>
+      )}
+    </div>
+  );
+}
+
+// ─── LIST ─────────────────────────────────────────────────────────────────────
+
+/**
+ * PopoverMenuList: the list with its Header and Footer slots, without a
+ * trigger. PopoverMenu renders one inside its floating panel; a BottomSheet,
+ * a Select or an Input renders one in its own surface, and the docs render one
+ * open on the page.
+ *
+ * @param {"actions"|"options"} mode  actions: role menu; options: role listbox
+ * @param {string}  label             Accessible name. Always required
+ * @param {"none"|"single"|"multiple"} selectionMode
+ * @param {Iterable} selectedKeys / defaultSelectedKeys
+ * @param {Function} onSelectionChange (keys: Set) => void
+ * @param {Function} onAction          (key) => void, actions mode
+ * @param {ReactNode} header           Figma Header slot. The search row is the Input, Look = Embedded
+ * @param {ReactNode} footer           Figma Footer slot. Buttons, end-aligned
+ * @param {ReactNode} emptyState       Shown when there are no items (a PopoverMenuStatus)
+ * @param {boolean} framed             Draw the panel surface (docs and static examples)
+ */
+export function PopoverMenuList({
+  mode = "actions",
+  label,
+  header,
+  footer,
+  emptyState,
+  maxHeight,
+  framed = false,
+  bare = false,
+  className = "",
+  children,
+  ...rest
+}) {
+  useStyles();
+  const List = mode === "options" ? ListBox : RACMenu;
+  /* Esc closes the panel and returns focus. React Aria's default would clear
+     every pick in a multiple selection and leave the panel open. */
+  const listProps = { ...rest, escapeKeyBehavior: rest.escapeKeyBehavior ?? "none" };
+  return (
+    <ModeContext.Provider value={mode}>
+      <div className={`pw-menu${framed ? " pw-menu--static" : ""}${bare ? " pw-menu--bare" : ""}${className ? ` ${className}` : ""}`}>
+        {header && <div className="pw-menu__header">{header}</div>}
+        <div className="pw-menu__scroll" style={maxHeight ? { maxHeight } : undefined}>
+          <List aria-label={label} className="pw-menu__list"
+            renderEmptyState={emptyState ? () => emptyState : undefined} {...listProps}>
+            {children}
+          </List>
+        </div>
+        {footer && <div className="pw-menu__footer">{footer}</div>}
+      </div>
+    </ModeContext.Provider>
+  );
+}
+
+// ─── POPOVER MENU (trigger + panel) ───────────────────────────────────────────
+
+/**
+ * PopoverMenu: a trigger and the floating menu it opens.
+ *
+ * @param {"icon"|"button"|"avatar"} type  The trigger drawn when `renderTrigger` is not given
+ * @param {string}  label        The menu's and the trigger's accessible name. Required
+ * @param {string}  text         The `button` trigger's visible label
+ * @param {string}  initials     The `avatar` trigger's initials
+ * @param {string}  icon         The `icon` trigger's ligature (more_vert)
+ * @param {"bare"|"action"} iconStyle  bare: a 20 glyph in a 44 target (KPI Tile corner); action: the real ActionIcon (Widget header)
+ * @param {Function} renderTrigger  (props) => element; spread props onto one button (aria and handlers are wired here)
+ * @param {"start"|"end"} align  Which trigger edge the panel lines up with. Flips when there is no room
+ * @param {boolean} open / onOpenChange  Controlled open state
+ * @param {"actions"|"options"} mode
+ * @param {"none"|"single"|"multiple"} selectionMode, selectedKeys, onSelectionChange, onAction
+ * @param {ReactNode} header, footer, emptyState  See PopoverMenuList
+ * @param {boolean} searchable   The panel opens at the fixed 360 height and keeps it while the list filters
+ */
+export function PopoverMenu({
+  type = "icon",
+  label,
+  text,
+  initials,
+  icon = "more_vert",
+  iconStyle = "bare",
+  renderTrigger,
+  align = "end",
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  mode = "actions",
+  selectionMode,
+  selectedKeys,
+  defaultSelectedKeys,
+  onSelectionChange,
+  onAction,
+  header,
+  footer,
+  emptyState,
+  searchable = false,
+  maxHeight,
+  className = "",
+  style,
+  children,
+}) {
+  useStyles();
+  const state = useMenuTriggerState({ isOpen: openProp, defaultOpen, onOpenChange });
+  const wrap = useRef(null);
+  const triggerId = `pwmenu${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+  const [hov, setHov] = useState(false);
+
+  /* Single picks and plain actions close after the pick delay; picking many
+     keeps the menu open so more can be changed. */
+  const closeSoon = () => setTimeout(() => state.close(), pickDelay());
+  const handleAction = (key) => { onAction?.(key); if (selectionMode !== "multiple") closeSoon(); };
+  const handleSelection = (keys) => { onSelectionChange?.(keys); if (selectionMode !== "multiple" && mode === "options") closeSoon(); };
+
+  const triggerProps = {
+    id: triggerId,
+    "aria-haspopup": mode === "options" ? "listbox" : "menu",
+    "aria-expanded": state.isOpen,
+    onClick: () => state.toggle(null),
+    /* Arrow Down and Up open from a closed trigger and land on the first or
+       last item (APG menu button). Enter and Space are the native click. */
+    onKeyDown: (e) => {
+      if (state.isOpen) return;
+      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+        e.preventDefault();
+        state.open(e.key === "ArrowDown" ? "first" : "last");
+      }
+    },
+  };
+
+  let trigger;
+  if (renderTrigger) {
+    trigger = renderTrigger({ ...triggerProps, "aria-label": label, title: label });
+  } else if (type === "button") {
+    trigger = (
+      <button type="button" className="pw-menu-trigger__button" {...triggerProps} aria-label={text ? undefined : label}>
+        {text}
+        <Icon name={state.isOpen ? "expand_less" : "expand_more"} size={16} />
+      </button>
+    );
+  } else if (type === "avatar") {
+    trigger = <button type="button" className="pw-menu-trigger__avatar" {...triggerProps} aria-label={label}>{initials}</button>;
+  } else if (iconStyle === "action") {
+    trigger = <ActionIcon name={icon} size="Base" label={label} {...triggerProps} />;
+  } else {
+    trigger = (
+      <button type="button" className="pw-menu-trigger__icon" {...triggerProps} aria-label={label} title={label}
+        style={{ width: L.triggerTarget, height: L.triggerTarget }}>
+        <Icon name={icon} size={L.triggerGlyph} />
+      </button>
+    );
+  }
+
+  const list = (
+    <PopoverMenuList mode={mode} label={label}
+      selectionMode={selectionMode} selectedKeys={selectedKeys} defaultSelectedKeys={defaultSelectedKeys}
+      onSelectionChange={handleSelection} onAction={mode === "options" ? undefined : handleAction}
+      /* A ListBox takes no focus from MenuContext, so options mode focuses
+         itself: `true` lands on the picked option, else the first. */
+      autoFocus={mode === "options" ? (state.focusStrategy === "last" ? "last" : true) : undefined}
+      shouldFocusWrap
+      header={header} footer={footer} emptyState={emptyState} maxHeight={maxHeight}>
+      {children}
+    </PopoverMenuList>
+  );
+
+  return (
+    <span ref={wrap} className={`pw-menu-trigger ${className}`} data-open={state.isOpen || undefined}
+      onMouseEnter={() => setHov(true)} onMouseLeave={() => setHov(false)} data-hovered={hov || undefined} style={style}>
+      {trigger}
+      <Provider values={[
+        [MenuContext, { "aria-labelledby": label ? undefined : triggerId, autoFocus: state.focusStrategy || true, onClose: state.close, shouldCloseOnSelect: false }],
+        [OverlayTriggerStateContext, state],
+        [RootMenuTriggerStateContext, state],
+        [PopoverContext, { trigger: "MenuTrigger", triggerRef: wrap, placement: `bottom ${align}` }],
+      ]}>
+        <Popover className="pw-menu-panel" offset={L.offset} data-searchable={searchable || undefined}>
+          {list}
+        </Popover>
+      </Provider>
+    </span>
+  );
+}
+
+export default PopoverMenu;