@helloimjolopez-pathway/pathway-components 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helloimjolopez-pathway/pathway-components",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Pathway Design System components for Ministry Brands products: web components (pathway-nav-shell, pathway-top-nav, pathway-sidenav, pathway-accounting-sidenav and more) and React source.",
   "homepage": "https://potential-bassoon-voz982n.pages.github.io/storybook/",
   "repository": {
@@ -31,7 +31,7 @@
     "./badge": "./components/badge/badge.jsx",
     "./scroll-to-enable": "./components/scroll-to-enable/scroll-to-enable.jsx",
     "./bottom-sheet": "./components/bottom-sheet/bottom-sheet.jsx",
-    "./dropdown": "./components/dropdown/dropdown.jsx",
+    "./popover-menu": "./components/popover-menu/popover-menu.jsx",
     "./toggle-button": "./components/toggle-button/toggle-button.jsx",
     "./radio": "./components/radio/radio.jsx",
     "./avatar": "./components/avatar/avatar.jsx",
@@ -51,6 +51,7 @@
   "jsdelivr": "./dist/pathway-components.js",
   "unpkg": "./dist/pathway-components.js",
   "dependencies": {
-    "react-aria-components": "^1.22.1"
+    "react-aria-components": "^1.22.1",
+    "react-stately": "^3.51.0"
   }
 }

package/components/dropdown/dropdown.jsx

@@ -1,482 +0,0 @@
-/**
- * Dropdown: a trigger and the menu it opens.
- *
- * WHY THIS EXISTS. The KPI Tiles set nests a FOREIGN component here:
- * `Dropdown` 40003188:9930, a remote library component, eighteen instances
- * inside a Pathway component. Like the Featured icon it is from the same
- * third-party library and cannot be Code Connected from this repo, because a
- * mapping publishes into the file that owns the component.
- *
- * WHAT THE FOREIGN COMPONENT ACTUALLY IS, measured 2026-10-08. Six variants on
- * two axes, `Type` (Button | Icon | Avatar) and `Open` (False | True). The one
- * the KPI Tile uses, `Type=Icon, Open=False`, walks to:
- *
- *   Type=Icon, Open=False [COMPONENT 20x20]
- *     dots-vertical [INSTANCE 20x20]
- *
- * That is all of it. No box, no fill, no border, no radius: a bare 20px glyph.
- * So eighteen instances of a foreign component were carrying a single icon.
- *
- * WHICH MEANS THE TRIGGER WAS NEVER THE HARD PART. Pathway already has the
- * icon-button primitive in `ActionIcon`, and what the system was missing is the
- * MENU: the `Open=True` half, which nothing in this repo had as a reusable
- * piece. `dashboard.jsx` grew a private `WidgetMenu` for exactly this and it
- * could not be reused.
- *
- * So this component is the pairing. The trigger is whichever of the three
- * types the caller asks for, the menu is one implementation, and `open` is the
- * Figma axis.
- *
- * THE PANEL IS PATHWAY'S OWN `PopoverMenu`, WHICH ALREADY EXISTED.
- *
- * This is the part worth reading. The foreign Dropdown's `Open=True` variants
- * are that library's menu, so copying them would import a second system's
- * panel, and the first version of this file invented a third. Neither was
- * necessary: the `↳ ❇️ Menu` page has had a complete Pathway menu all along and
- * nothing in this repo had ever implemented it.
- *
- *   PopoverMenu              40005568:4207   the panel
- *   PopoverMenu.Item         40005568:4191   3 variants on State
- *   PopoverMenu.SectionLabel 40005748:20503
- *   Menu.Divider             40006377:69269
- *
- * So `dashboard.jsx`'s private `WidgetMenu` and this file's first panel were
- * both reinventing a component the design system already had. The measurements
- * below are that component's, read on 2026-10-08:
- *
- *   PopoverMenu   212 wide, VERTICAL, pad 8, r=8, Fill/Surface/Elevated,
- *                 Stroke/Static/Neutral/Base, shadow 0 4 16 -2 at a0.08.
- *                 Its inner Menu slot is VERTICAL, gap 8, pad 6.
- *   Item          200x40, HORIZONTAL, pad 6,14,6,14, r=8, label fs 14.
- *                 Base  fill Fill/Surface/Elevated,
- *                       label Foreground/Action/Secondary/Rest
- *                 Hover fill Fill/Action/Selection/Hover,
- *                       label Foreground/Action/Secondary/Hover
- *                 Label Wrapper gap 4 pad 0,0,0,8; leading icon 20 box / 14 glyph.
- *   Divider       VERTICAL pad 6,0,6,0, a line on Stroke/Static/Neutral/Base.
- *
- * ONE GAP: the panel's shadow is 0 4 16 -2 and Pathway's nearest token is
- * --elevation-sheet, 0 4 32 -8. Same offset, different blur, and there is no
- * exact token. Used the nearest rather than inventing one; recorded in the spec.
- */
-import React, { createContext, useContext, useEffect, useId, useRef, useState } from "react";
-import { Icon } from "../icon/icon.jsx";
-import { ActionIcon } from "../icon/action-icon.jsx";
-import { useReducedMotion } from "../_shared/use-reduced-motion.jsx";
-
-const C = (n) => `var(--semantic-color-${n})`;
-const U = (n) => `var(--semantic-layout-units-${n})`;
-const Y = (n) => `var(--semantic-type-${n})`;
-const M = (n) => `var(--motion-${n})`;
-
-export const DROPDOWN_TYPES = ["icon", "button", "avatar"];
-
-export const T = {
-  panel:        C("fill-surface-elevated"),
-  panelBorder:  C("stroke-static-neutral-base"),
-  // Menu.Divider strokes with the BASE neutral, not the faint one.
-  divider:      C("stroke-static-neutral-base"),
-  // PopoverMenu.Item's label is an ACTION foreground, not a static one: the
-  // item is interactive, and State=Hover moves it from Rest to Hover.
-  item:         C("foreground-action-secondary-rest"),
-  itemFgHover:  C("foreground-action-secondary-hover"),
-  // State=Hover fills with Action/SELECTION/Hover, which is the selection
-  // family rather than the secondary one. Measured.
-  itemHover:    C("fill-action-selection-hover"),
-  danger:       C("foreground-static-negative-on-subtle"),
-  subtle:       C("foreground-static-neutral-subtle"),
-  // The Icon type is a bare 20px glyph in Figma, so its colour is inherited
-  // rather than set: it takes whatever the tile around it is using.
-  trigger:      C("foreground-action-secondary-rest"),
-  triggerHover: C("foreground-action-secondary-hover"),
-  buttonFill:   C("fill-surface-elevated"),
-  buttonBorder: C("stroke-action-secondary-rest"),
-  avatarFill:   C("fill-action-primary-subtle-rest"),
-  avatarText:   C("foreground-action-primary-on-subtle-rest"),
-};
-
-export const L = {
-  // Figma: the Icon trigger is 20x20 with a 20x20 glyph and nothing around it.
-  iconBox:     20,
-  iconGlyph:   20,
-  // PopoverMenu: 212 wide, pad 8, r=8. Its inner slot is gap 8, pad 6.
-  panelMinW:   212,
-  radius:      U("cornerradius-base"),
-  border:      "var(--semantic-layout-units-borderwidth-base)",
-  panelPad:    U("padding-xtight"),
-  slotPad:     U("padding-xxtight"),
-  slotGap:     U("gap-xtight"),
-  // PopoverMenu.Item: 40 tall, pad 6,14,6,14, label gap 4 with an 8 inset.
-  itemH:       40,
-  itemPadV:    U("padding-xxtight"),
-  // Figma's item pad is 6,14,6,14, and 14 IS a rung: Padding/Medium. This read
-  // Padding/Tight, 12, under a comment asserting the ladder went 12 then 16,
-  // which is the gap ladder and not the padding ladder. Corrected 2026-10-08.
-  itemPadH:    U("padding-medium"),
-  itemInset:   U("padding-xtight"),
-  gap:         U("gap-xxtight"),
-  // Menu.Divider: pad 6,0,6,0.
-  dividerPadV: U("padding-xxtight"),
-  // Leading icon: a 20 box holding a 14 glyph.
-  leadingBox:  20,
-  leadingGlyph: 14,
-  offset:      4,
-  buttonPadV:  U("padding-xtight"),
-  buttonPadH:  U("padding-tight"),
-  avatarBox:   28,
-};
-
-/**
- * One menu entry.
- *
- * @param {string} label
- * @param {func} onSelect
- * @param {boolean} danger   Destructive, so it takes the negative foreground.
- * @param {boolean} checked  Draws a leading check. Used for a current value.
- * @param {string} icon      Figma's `Leading.Icon` swap, a Material ligature.
- * @param {boolean} disabled
- */
-/**
- * Lets an item close the menu it sits in.
- *
- * WHY A CONTEXT and not a prop: the items are passed in as `children`, so the
- * Dropdown cannot reach their handlers without cloning the tree, and every call
- * site would otherwise have to thread a close function through its own JSX.
- * Found 2026-10-12: choosing an item ran its `onSelect` and left the panel
- * open, so the Widget's menu stayed over the content after Refresh had already
- * fired. Every menu in the system had it, because none of them closed.
- */
-export const DropdownClose = createContext(null);
-/* Exported so a BottomSheet holding DropdownItems can close itself the same
-   way when an item is chosen (bottom-sheet.jsx). */
-
-export function DropdownItem({ label, onSelect, danger, checked, disabled, note, icon }) {
-  const noMotion = useReducedMotion();
-  const close = useContext(DropdownClose);
-  const [hov, setHov] = useState(false);
-  return (
-    <button
-      type="button"
-      role="menuitem"
-      disabled={disabled}
-      aria-checked={checked === undefined ? undefined : !!checked}
-      onClick={(e) => { onSelect?.(e); close?.(); }}
-      onMouseEnter={() => setHov(true)}
-      onMouseLeave={() => setHov(false)}
-      style={{
-        display: "flex", alignItems: "center", gap: L.gap, width: "100%",
-        minHeight: L.itemH, boxSizing: "border-box",
-        textAlign: "left", padding: `${L.itemPadV} ${L.itemPadH}`,
-        borderRadius: L.radius,
-        background: hov && !disabled ? T.itemHover : "transparent",
-        border: "none", cursor: disabled ? "default" : "pointer",
-        opacity: disabled ? 0.5 : 1,
-        // The label follows State, Rest to Hover, which is why it is an action
-        // foreground rather than a static one.
-        color: danger ? T.danger : (hov && !disabled ? T.itemFgHover : T.item),
-        fontFamily: "inherit",
-        fontSize: Y("font-size-s"), lineHeight: Y("line-height-s-single"),
-        letterSpacing: Y("letter-spacing-spacious"),
-        transition: noMotion ? "none" : `background ${M("duration-2")} ${M("easing-standard")}, color ${M("duration-2")} ${M("easing-standard")}`,
-      }}
-    >
-      {/* Container.LeadingIcon: a 20 box holding a 14 glyph. Figma gates it
-          with `Show Leading Icon`, which is `icon` or `checked` here. */}
-      {(icon || checked !== undefined) && (
-        <span style={{ display: "inline-flex", alignItems: "center", justifyContent: "center",
-          width: L.leadingBox, height: L.leadingBox, flexShrink: 0 }}>
-          <Icon name={icon || (checked ? "check" : "")} size={L.leadingGlyph}
-            style={{ opacity: icon || checked ? 1 : 0 }} />
-        </span>
-      )}
-      <span style={{ flex: 1, minWidth: 0, paddingLeft: icon || checked !== undefined ? 0 : L.itemInset }}>{label}</span>
-      {note && <span style={{ color: T.subtle, fontSize: Y("font-size-xxs") }}>{note}</span>}
-    </button>
-  );
-}
-
-/** A rule between groups of items. */
-/** Figma `Menu.Divider` 40006377:69269: a line with 6px above and below. */
-export const DropdownDivider = () => (
-  <hr aria-hidden="true" style={{
-    border: 0, borderTop: `${L.border} solid ${T.divider}`,
-    margin: `${L.dividerPadV} 0`,
-  }} />
-);
-
-/**
- * @param {"icon"|"button"|"avatar"} type  Figma's Type axis.
- * @param {boolean} open     Figma's Open axis. Controlled when given, internal
- *                           when not, so a story can show the open state and a
- *                           product can own it.
- * @param {node} children    `DropdownItem`s and `DropdownDivider`s.
- * @param {string} label     The trigger's accessible name. Required for `icon`
- *                           and `avatar`, which have no visible text.
- * @param {string} text      The `button` type's visible label.
- * @param {string} initials  The `avatar` type's initials.
- * @param {string} icon      The `icon` type's ligature. Figma draws
- *                           dots-vertical, which is `more_vert`.
- * @param {"start"|"end"} align  Which edge of the trigger the panel lines up
- *                           with. `end` by default: a trigger at the top-right
- *                           of a card opens leftward or the panel leaves the
- *                           card.
- */
-export function Dropdown({
-  type = "icon",
-  open: openProp,
-  onOpenChange,
-  children,
-  label,
-  text,
-  initials,
-  icon = "more_vert",
-  /* The Icon trigger's HIT AREA, which is not its glyph. Figma draws a bare
-     20px glyph and puts a 44x44 `TouchTarget` frame around it; the frame is
-     there to be the target. Rendering only the glyph gave a 20x20 button,
-     under both Figma's 44 and WCAG 2.5.8's 24 floor, and the 44x44 wrapper the
-     KPI Tile drew around it was a plain span that swallowed nothing.
-     Found 2026-10-08 by measuring the rendered button. */
-  targetSize = 44,
-  /* HOW THE ICON TRIGGER IS DRAWN, which is not the same question as how big
-     its target is. Figma uses two different triggers for the same menu:
-
-       "bare"    a 20px glyph, no box, no fill. The KPI tile's corner control.
-       "action"  an Action Icon at Size=Base: 44 target, 28 state layer, 16
-                 glyph, with the hover and pressed fills on the layer. The
-                 Widget header's three controls are these.
-
-     Wiring the Widget's ellipsis to this component without the distinction
-     swapped a 16px glyph with a state layer for a bare 20px one, which is
-     visibly wrong in the header row next to Refresh and Open. */
-  iconStyle = "bare",
-  /* A caller-supplied trigger, for a control whose trigger is neither an icon,
-     a button nor an avatar. Called with the props it must spread onto whatever
-     element it renders, so the aria wiring and the open/close handling stay
-     here instead of being reimplemented per component. Trend's comparison
-     control is the first: its trigger is a 10px label plus a 12px chevron. */
-  renderTrigger,
-  align = "end",
-  className = "",
-  style,
-}) {
-  const noMotion = useReducedMotion();
-  const controlled = openProp !== undefined;
-  const [openState, setOpenState] = useState(false);
-  const open = controlled ? openProp : openState;
-  const setOpen = (v) => { if (!controlled) setOpenState(v); onOpenChange?.(v); };
-
-  const wrap = useRef(null);
-  const panel = useRef(null);
-  const panelId = `pwdd${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
-  const [hov, setHov] = useState(false);
-
-  /* ARROW KEYS, because `role="menu"` promises them.
-     A `menu` whose children are `menuitem` tells a screen reader user that Up
-     and Down move between the items. Until 2026-10-13 they did not: the panel
-     handled Escape and nothing else, so the roles were a promise the component
-     did not keep, and the spec that said so was marked REVIEWED. Tab worked,
-     which is why it never looked broken to a mouse user.
-
-     Focus is moved rather than tracked in state: the items are real buttons, so
-     the browser's own focus is the single source of truth and there is no
-     `aria-activedescendant` to keep in sync. */
-  /* FOCUS RETURN. Once the arrow keys worked, focus lived on a menu item rather
-     than on the trigger, so unmounting the panel dropped focus to <body> and a
-     keyboard user was thrown to the top of the page. Verified in headless
-     Chrome on 2026-10-13: before this, Escape reported `focus: BODY`.
-     WCAG 2.4.3 and the APG menu-button pattern both want focus back on the
-     trigger. rAF rather than a bare call because the panel is still mounted at
-     the moment the handler runs. */
-  const wantFocusBack = useRef(false);
-  const enterFrom = useRef(null);
-
-  const closeAndReturnFocus = () => {
-    wantFocusBack.current =
-      !!panel.current?.contains(document.activeElement) ||
-      document.activeElement === document.body;
-    setOpen(false);
-  };
-
-  /* Restore in an EFFECT, not in the handler. The first attempt called
-     `trigger.focus()` from a requestAnimationFrame inside the close handler and
-     focus still landed on <body>: rAF runs before React has committed the
-     closed state, so the trigger node focus() touched was then reconciled and
-     the focus went with it. An effect keyed on `open` runs after the commit,
-     when the trigger node is the final one. */
-  useEffect(() => {
-    if (open || !wantFocusBack.current) return;
-    wantFocusBack.current = false;
-    wrap.current?.querySelector('[aria-haspopup="menu"]')?.focus();
-  }, [open]);
-
-  /* Opening by key lands on an item; opening by click leaves focus on the
-     trigger, because a mouse user has not asked to be moved. */
-  useEffect(() => {
-    if (!open || !enterFrom.current) return;
-    const at = enterFrom.current;
-    enterFrom.current = null;
-    moveFocus(0, at);
-  }, [open]);
-
-  const items = () =>
-    panel.current
-      ? [...panel.current.querySelectorAll('[role="menuitem"]:not([disabled])')]
-      : [];
-
-  const moveFocus = (delta, absolute) => {
-    const list = items();
-    if (!list.length) return;
-    const here = list.indexOf(document.activeElement);
-    let next;
-    if (absolute === "first") next = 0;
-    else if (absolute === "last") next = list.length - 1;
-    else if (here === -1) next = delta > 0 ? 0 : list.length - 1;
-    else next = (here + delta + list.length) % list.length;   // wraps, as menus do
-    list[next].focus();
-  };
-
-  useEffect(() => {
-    if (!open) return;
-    const onKey = (e) => {
-      if (e.key === "Escape") { closeAndReturnFocus(); return; }
-      if (!panel.current || !panel.current.contains(document.activeElement)) {
-        /* Down from the trigger itself enters the menu at the first item, which
-           is the behaviour the APG menu-button pattern describes. */
-        if (e.key === "ArrowDown" && wrap.current?.contains(document.activeElement)) {
-          e.preventDefault(); moveFocus(1, "first");
-        }
-        return;
-      }
-      if (e.key === "ArrowDown") { e.preventDefault(); moveFocus(1); }
-      else if (e.key === "ArrowUp") { e.preventDefault(); moveFocus(-1); }
-      else if (e.key === "Home") { e.preventDefault(); moveFocus(0, "first"); }
-      else if (e.key === "End") { e.preventDefault(); moveFocus(0, "last"); }
-    };
-    const onDown = (e) => { if (wrap.current && !wrap.current.contains(e.target)) setOpen(false); };
-    document.addEventListener("keydown", onKey);
-    document.addEventListener("mousedown", onDown);
-    return () => {
-      document.removeEventListener("keydown", onKey);
-      document.removeEventListener("mousedown", onDown);
-    };
-  }, [open]);
-
-  const shared = {
-    "aria-haspopup": "menu",
-    "aria-expanded": open,
-    "aria-controls": open ? panelId : undefined,
-    onClick: () => setOpen(!open),
-    /* Down and Up OPEN the menu from a closed trigger, which is what the APG
-       menu-button pattern describes and what a keyboard user tries first.
-       Enter and Space already worked, being a native button. This lives on the
-       trigger rather than in the document listener because that listener is
-       only registered while the panel is open. `enterFrom` tells the open
-       effect which end to land on. */
-    onKeyDown: (e) => {
-      if (open) return;
-      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
-        e.preventDefault();
-        enterFrom.current = e.key === "ArrowDown" ? "first" : "last";
-        setOpen(true);
-      }
-    },
-  };
-
-  let trigger;
-  if (renderTrigger) {
-    trigger = renderTrigger({ ...shared, "aria-label": label, title: label });
-  } else if (type === "button") {
-    trigger = (
-      <button type="button" {...shared} aria-label={label}
-        onMouseEnter={() => setHov(true)} onMouseLeave={() => setHov(false)}
-        style={{
-          display: "inline-flex", alignItems: "center", gap: L.gap,
-          padding: `${L.buttonPadV} ${L.buttonPadH}`, cursor: "pointer",
-          background: hov ? T.itemHover : T.buttonFill,
-          border: `${L.border} solid ${T.buttonBorder}`, borderRadius: L.radius,
-          color: T.trigger, fontFamily: "inherit",
-          fontSize: Y("font-size-s"), lineHeight: Y("line-height-s-single"),
-          letterSpacing: Y("letter-spacing-spacious"), whiteSpace: "nowrap",
-          transition: noMotion ? "none" : `background ${M("duration-2")} ${M("easing-standard")}`,
-        }}>
-        {text}
-        <Icon name={open ? "expand_less" : "expand_more"} size={16} />
-      </button>
-    );
-  } else if (type === "avatar") {
-    trigger = (
-      <button type="button" {...shared} aria-label={label}
-        onMouseEnter={() => setHov(true)} onMouseLeave={() => setHov(false)}
-        style={{
-          display: "inline-flex", alignItems: "center", justifyContent: "center",
-          width: L.avatarBox, height: L.avatarBox, borderRadius: L.radius,
-          background: T.avatarFill, color: T.avatarText, border: "none",
-          cursor: "pointer", fontFamily: "inherit", flexShrink: 0,
-          fontSize: Y("font-size-xxs"), fontWeight: Y("weight-semibold"),
-          letterSpacing: Y("letter-spacing-spacious"),
-          filter: hov ? "brightness(0.97)" : "none",
-          transition: noMotion ? "none" : `filter ${M("duration-2")} ${M("easing-standard")}`,
-        }}>
-        {initials}
-      </button>
-    );
-  } else {
-    /* Figma's Icon type DRAWS a bare 20px glyph: no box, no fill, no border.
-       So this is not an ActionIcon, which carries a visible state layer. But
-       the drawing and the target are different things: the glyph stays 20 and
-       the button is `targetSize`, which is the 44x44 TouchTarget every KPI
-       tile variant carries around it. */
-    trigger = iconStyle === "action" ? (
-      /* The real ActionIcon, so the state layer, its fills and the glyph size
-         come from that component rather than being reproduced here. */
-      <ActionIcon name={icon} size="Base" label={label}
-        onClick={shared.onClick}
-        aria-haspopup={shared["aria-haspopup"]}
-        aria-expanded={shared["aria-expanded"]}
-        aria-controls={shared["aria-controls"]} />
-    ) : (
-      <button type="button" {...shared} aria-label={label} title={label}
-        onMouseEnter={() => setHov(true)} onMouseLeave={() => setHov(false)}
-        style={{
-          display: "inline-flex", alignItems: "center", justifyContent: "center",
-          width: targetSize, height: targetSize, padding: 0, flexShrink: 0,
-          background: "transparent", border: "none", cursor: "pointer",
-          color: hov || open ? T.triggerHover : T.trigger,
-          transition: noMotion ? "none" : `color ${M("duration-2")} ${M("easing-standard")}`,
-        }}>
-        <Icon name={icon} size={L.iconGlyph} />
-      </button>
-    );
-  }
-
-  return (
-    <span ref={wrap} className={`pw-dropdown ${className}`} data-type={type}
-      data-open={open || undefined}
-      style={{ position: "relative", display: "inline-flex", ...style }}>
-      {trigger}
-      {open && (
-        <div id={panelId} ref={panel} role="menu" aria-label={label || text}
-          style={{
-            position: "absolute", top: `calc(100% + ${L.offset}px)`, zIndex: 30,
-            [align === "end" ? "right" : "left"]: 0,
-            minWidth: L.panelMinW, boxSizing: "border-box",
-            // PopoverMenu pad 8, with its inner Menu slot at pad 6 and gap 8.
-            padding: L.panelPad,
-            background: T.panel, border: `${L.border} solid ${T.panelBorder}`,
-            borderRadius: L.radius,
-            /* Figma's shadow is 0 4 16 -2 at a0.08. --elevation-sheet is
-               0 4 32 -8: the same offset, a softer blur, and the nearest token
-               that exists. Recorded in the spec rather than inventing one. */
-            boxShadow: "var(--elevation-sheet)",
-          }}>
-          <div style={{ display: "flex", flexDirection: "column",
-            gap: L.slotGap, padding: L.slotPad }}>
-            <DropdownClose.Provider value={closeAndReturnFocus}>{children}</DropdownClose.Provider>
-          </div>
-        </div>
-      )}
-    </span>
-  );
-}
-
-export default Dropdown;