@charcuterie/ui 4.7.1 → 4.9.0

package/src/Menu/Menu.mdx

@@ -59,6 +59,42 @@ So the rule the other three teach is narrower than it looked:
 A menu has one, so the requirement moves to the trigger — which `Button` and `IconButton`
 already enforce.
 
+## A context menu is this component with no trigger
+
+Press and hold a card on a phone and the menu opens at the finger. That is the same
+component in **anchor mode**: `anchorRef` replaces `trigger`, and the panel hangs off a
+**virtual element** — an object that knows only its own rectangle, which here is the
+zero-sized rect at the point pressed. `flip` and `shift` treat it exactly like a button,
+so a press near the bottom of the window still gets a menu that fits.
+
+`useLongPress` in `@charcuterie/logic` is the other half. It watches the pointer, cancels
+on a 10px drift so a scroll that starts on the card is a scroll, and hands back the point.
+Two details in it are not obvious:
+
+- **The native `contextmenu` is a second trigger, not only something to suppress.** Chrome
+  on Android recognises its own long press at about the same 500ms and fires `pointercancel`
+  at the sequence, which clears the timer a beat before it would have run. Whichever arrives
+  first fires the callback, once.
+- **Touch and pen only, by default.** A mouse already has a context menu, and the browser's
+  own carries "Open link in new tab" and "Copy link address" — taking that over to show four
+  app actions is a loss on a desktop and a gain on a phone. Pass `["mouse"]` deliberately,
+  for a surface that is not a link.
+
+The CSS half belongs to the consumer: `-webkit-touch-callout: none` on the pressed element,
+or iOS shows its link preview sheet over the menu. Safari fires no `contextmenu`, so no
+handler can reach it.
+
+**`label` is required here**, and that is the rule above read from the other side. With the
+trigger gone nothing names the panel, so the prop that was inert in trigger mode becomes the
+only name the menu has. The type enforces it: `anchorRef` and `trigger` are mutually
+exclusive, and `label` belongs to exactly one of them.
+
+Dismissal needs no special case. floating-ui watches `pointerdown` for an outside press, and
+the press that opened a context menu is over before the panel exists — so it cannot close
+itself on the way in.
+
+<Canvas of={MenuStories.ContextMenu} />
+
 ## One kind, and that is the other half of the `Tabs` argument
 
 `Tabs` needed **two** state kinds because a tab is chosen *and* focused, and in `manual`

package/src/Menu/Menu.stories.tsx

@@ -1,8 +1,12 @@
-import { useVisibility } from "@charcuterie/logic"
+import {
+  useLongPress,
+  useVisibility,
+} from "@charcuterie/logic"
 import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { ControlSize } from "@charcuterie/tokens"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
+import { useRef } from "react"
 
 import {
   controlSizeArgType,
@@ -18,6 +22,7 @@ import {
   SettingsIcon,
   UndoIcon,
 } from "../icons.storyHelpers.tsx"
+import type { AnchoredOverlayAnchor } from "../Overlay/useAnchoredOverlay.ts"
 import { Tooltip } from "../Tooltip/Tooltip.tsx"
 import type { MenuEntry, MenuItem } from "./Menu.tsx"
 import { Menu } from "./Menu.tsx"
@@ -148,6 +153,65 @@ const TooltipTriggerHarness = ({
   )
 }
 
+/**
+ * Anchor mode — the same menu with its trigger taken away, opened
+ * by a gesture over a surface and positioned at the point that was
+ * pressed.
+ *
+ * The anchor is a **virtual element**: an object that knows only
+ * its own rectangle, which here is the zero-sized rect at the
+ * finger. `flip` and `shift` treat it exactly like a real one, so
+ * a press near the bottom of the window still gets a menu that
+ * fits.
+ *
+ * `pointerTypes` includes `mouse` here, which the hook's default
+ * deliberately does not: this surface is not a link, so there is
+ * no browser menu worth keeping, and a story nobody can open on a
+ * desktop demonstrates nothing.
+ */
+const ContextMenuHarness = ({
+  surfaceLabel,
+}: {
+  surfaceLabel: string
+}): ReactNode => {
+  const { hide, isVisible, show } = useVisibility()
+
+  const anchorRef = useRef<AnchoredOverlayAnchor | null>(
+    null,
+  )
+
+  const longPressHandlers = useLongPress({
+    onLongPress: ({ clientX, clientY }) => {
+      anchorRef.current = {
+        getBoundingClientRect: () =>
+          new DOMRect(clientX, clientY, 0, 0),
+      }
+
+      show()
+    },
+    pointerTypes: ["mouse", "pen", "touch"],
+  })
+
+  return (
+    <>
+      <div
+        {...longPressHandlers}
+        className="flex h-32 w-64 select-none items-center justify-center rounded-xl border border-border-default bg-surface-raised text-content-secondary text-sm"
+      >
+        {surfaceLabel}
+      </div>
+
+      <Menu
+        anchorRef={anchorRef}
+        isVisible={isVisible}
+        items={BAY_ACTIONS}
+        label={`Actions for ${surfaceLabel}`}
+        onDismiss={hide}
+      />
+    </>
+  )
+}
+
 const meta = {
   title: "Components/Actions/Menu",
   component: Menu,
@@ -273,6 +337,40 @@ export const Interactive: Story = {
   ),
 }
 
+/**
+ * **A context menu is this component with no trigger.** Press and
+ * hold the card — or right-click it, which this story enables on
+ * purpose — and the menu opens at the point that was pressed.
+ *
+ * Two pieces make the gesture. `useLongPress`
+ * (`@charcuterie/logic`) watches the pointer and hands back the
+ * point; `anchorRef` takes a **virtual element** holding that
+ * point, so `flip` and `shift` behave exactly as they do against a
+ * button.
+ *
+ * `label` is **required** in this mode and absent in the other,
+ * which is the one thing that changes with the trigger gone:
+ * nothing is left to name the panel through `aria-labelledby`.
+ *
+ * The hold is 500ms and a 10px drift cancels it, so a scroll that
+ * starts on the card is a scroll. On Android the browser's own
+ * `contextmenu` arrives first and is used as the trigger rather
+ * than fought with — see the hook.
+ */
+export const ContextMenu: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="p-16">
+      <ContextMenuHarness surfaceLabel="Press and hold me" />
+    </div>
+  ),
+}
+
 /**
  * `items` is a union — a `group` (`role="group"`, named by its
  * label) and a `separator` (`role="separator"`) opt in by their

package/src/Menu/Menu.test.tsx

@@ -16,6 +16,7 @@ import * as stories from "./Menu.stories.tsx"
 const {
   AllStates,
   AllVariants,
+  ContextMenu,
   Empty,
   Grouped,
   Interactive,
@@ -551,3 +552,122 @@ test("a long label wraps rather than pushing the panel off screen", async () =>
     await setViewport(DESKTOP)
   }
 })
+
+/**
+ * Anchor mode, driven with the events a finger produces.
+ *
+ * `pointerdown` then `contextmenu` is the **Android** sequence —
+ * Chrome recognises its own long press and fires `contextmenu`
+ * while the finger is still down, which `useLongPress` uses as the
+ * trigger rather than fighting. It is also the sequence a test can
+ * drive without holding a timer open for half a second.
+ */
+const pressAndHold = async (
+  element: HTMLElement,
+  {
+    clientX,
+    clientY,
+  }: { clientX: number; clientY: number },
+) => {
+  element.dispatchEvent(
+    new PointerEvent("pointerdown", {
+      bubbles: true,
+      clientX,
+      clientY,
+      pointerType: "touch",
+    }),
+  )
+
+  element.dispatchEvent(
+    new MouseEvent("contextmenu", {
+      bubbles: true,
+      cancelable: true,
+      clientX,
+      clientY,
+    }),
+  )
+}
+
+test("a press and hold opens the menu at the point pressed", async () => {
+  const { body, canvas } = await mountStory(ContextMenu)
+
+  const surface = canvas.getByText("Press and hold me")
+
+  await pressAndHold(surface, {
+    clientX: 220,
+    clientY: 180,
+  })
+
+  const menu = await waitFor(() =>
+    expectAgentDrivable(body, {
+      // Named by its own `label`, because anchor mode has no
+      // trigger to borrow a name from. A menu that reaches this
+      // assertion through `aria-labelledby` would be pointing at
+      // an id that is on no element in the document.
+      name: "Actions for Press and hold me",
+      role: "menu",
+    }),
+  )
+
+  // The virtual anchor is a zero-sized rect at the finger, and the
+  // placement is `bottom-start` with a 4px offset — so the panel's
+  // own corner lands on the point that was pressed. Anchoring that
+  // silently failed would leave it at the top-left of the viewport,
+  // which is the failure this measurement exists to catch.
+  //
+  // `waitFor`, because floating-ui computes the first position in an
+  // effect of its own: the panel is in the document a tick before it
+  // knows where to be.
+  await waitFor(() => {
+    const panel = menu.getBoundingClientRect()
+
+    expect(Math.round(panel.left)).toBe(220)
+
+    expect(Math.round(panel.top)).toBe(184)
+  })
+
+  await expectNoAxeViolations(menu)
+})
+
+test("the press that opened the menu does not also click through", async () => {
+  const { body, canvas } = await mountStory(ContextMenu)
+
+  const surface = canvas.getByText("Press and hold me")
+
+  await pressAndHold(surface, {
+    clientX: 200,
+    clientY: 200,
+  })
+
+  await waitFor(() => {
+    expect(
+      body.queryAllByRole("menuitem").length,
+    ).toBeGreaterThan(0)
+  })
+
+  // floating-ui watches `pointerdown` for an outside press, and the
+  // press that opened this menu was over before the panel existed —
+  // so the menu cannot dismiss itself on the way in. The finger
+  // lifting is what would prove it.
+  surface.dispatchEvent(
+    new PointerEvent("pointerup", {
+      bubbles: true,
+      clientX: 200,
+      clientY: 200,
+      pointerType: "touch",
+    }),
+  )
+
+  surface.dispatchEvent(
+    new MouseEvent("click", {
+      bubbles: true,
+      cancelable: true,
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      body.queryAllByRole("menuitem").length,
+    ).toBeGreaterThan(0)
+  })
+})

package/src/Menu/Menu.tsx

@@ -9,11 +9,16 @@ import {
   FloatingFocusManager,
   FloatingPortal,
 } from "@floating-ui/react"
-import type { ReactElement, ReactNode } from "react"
+import type {
+  ReactElement,
+  ReactNode,
+  RefObject,
+} from "react"
 import { useEffect, useRef } from "react"
 
 import { PANEL_ITEM_SIZE_CLASS } from "../controlStyles.ts"
 import { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
+import type { AnchoredOverlayAnchor } from "../Overlay/useAnchoredOverlay.ts"
 import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
 import { usePanelItemSize } from "../Overlay/usePanelItemSize.ts"
 import { toClassName } from "../toClassName.ts"
@@ -64,7 +69,48 @@ export type MenuGroup = {
  */
 export type MenuEntry = MenuGroup | MenuItem | MenuSeparator
 
-export type MenuProps = {
+/**
+ * The two ways a menu can be summoned, and they are mutually
+ * exclusive at the type level rather than by a note nobody reads.
+ *
+ * **Trigger mode** is the menu button: the control is cloned, it
+ * gains `aria-haspopup`/`aria-expanded`, and it **names the
+ * panel** through `aria-labelledby` — which is why there is no
+ * `label` prop here and why adding one did nothing (see the
+ * component's own notes).
+ *
+ * **Anchor mode** has no trigger at all. It is the context menu:
+ * summoned by a gesture over a surface, positioned against an
+ * element or a bare point. Nothing names it, so `label` stops
+ * being inert and becomes **required** — a `role="menu"` that no
+ * `aria-labelledby` reaches is an unnamed menu, and a screen
+ * reader announces "menu, 4 items" with no idea what of.
+ */
+type MenuAnchorProps = {
+  /**
+   * What the panel hangs off: the pressed element, or a virtual
+   * element holding the point that was pressed
+   * (`AnchoredOverlayAnchor`). Read when the menu becomes
+   * visible, so the same ref can be re-aimed before each open.
+   */
+  anchorRef: RefObject<AnchoredOverlayAnchor | null>
+  /** Names the panel. Required here; see above. */
+  label: string
+  trigger?: never
+}
+
+type MenuTriggerProps = {
+  anchorRef?: never
+  /**
+   * Absent on purpose. The trigger names the panel, and a `label`
+   * here would be silently discarded by `aria-labelledby`.
+   */
+  label?: never
+  /** The control the menu hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+type MenuBaseProps = {
   className?: string
   /**
    * Shown when there is no item to show — a `group` with no members
@@ -92,10 +138,11 @@ export type MenuProps = {
   /** Outside press, Escape, and choosing an item all land here. */
   onDismiss: () => void
   placement?: Placement
-  /** The control the menu hangs off. **Cloned, not wrapped.** */
-  trigger: ReactElement
 }
 
+export type MenuProps = MenuBaseProps &
+  (MenuAnchorProps | MenuTriggerProps)
+
 /**
  * A group heading is not a row — it has no height of its own to take
  * — so it borrows only the inline padding, which is the one thing it
@@ -188,6 +235,27 @@ const hasAnyItem = (items: MenuEntry[]): boolean =>
  * note has to be one, `aria-disabled` and out of the roving group:
  * announced as "No actions available, dimmed", focusable by nothing.
  *
+ * ### Anchor mode: the same menu, summoned by a gesture
+ *
+ * A context menu is this component with its trigger taken away.
+ * `anchorRef` replaces it — pointing at the pressed element, or at
+ * a **virtual** element that is only a rectangle, which is how the
+ * panel opens at the finger rather than at the corner of the card
+ * underneath. `useLongPress` in `@charcuterie/logic` is the other
+ * half; it hands back the point.
+ *
+ * One thing changes with the trigger gone, and it is the a11y
+ * half: nothing names the panel any more, so `label` becomes
+ * **required** in this mode and inert in the other. That is the
+ * narrowed M3/M4 rule read the other way round — an overlay with
+ * no trigger relationship needs its own name, and this is a menu
+ * that has none.
+ *
+ * Dismissal needs no special case. floating-ui's outside-press
+ * watches `pointerdown`, and the press that opened a context menu
+ * is over before the panel exists, so it cannot close itself on
+ * the way in.
+ *
  * ### No type-ahead, deliberately
  *
  * The APG lists type-ahead as optional for a menu and required for a
@@ -197,11 +265,13 @@ const hasAnyItem = (items: MenuEntry[]): boolean =>
  * a menu you can cross in three arrow presses.
  */
 export const Menu = ({
+  anchorRef,
   className,
   emptyState,
   isVisible,
   items,
   itemSize: requestedItemSize = "lg",
+  label,
   onDismiss,
   placement = "bottom-start",
   trigger,
@@ -227,7 +297,9 @@ export const Menu = ({
     floatingStyles,
     getFloatingProps,
     setFloating,
+    triggerId,
   } = useAnchoredOverlay({
+    anchorRef,
     // A menu had no clamp at all, which was survivable while a row was
     // 32px and is not now: nine `lg` rows are 400px, and on a short
     // window the panel simply ran off the bottom of the screen with no
@@ -387,6 +459,19 @@ export const Menu = ({
           >
             <div
               {...getFloatingProps()}
+              // Anchor mode has no trigger, so `useRole`'s
+              // `aria-labelledby` points at an id that is on no
+              // element in the document — a dangling reference,
+              // which is an **unnamed** menu rather than a
+              // wrongly named one. The `label` this mode
+              // requires takes over, and the dangling attribute
+              // is dropped rather than left beside it: an
+              // `aria-labelledby` that resolves to nothing still
+              // beats `aria-label` in some engines.
+              aria-label={anchorRef ? label : undefined}
+              aria-labelledby={
+                anchorRef ? undefined : triggerId
+              }
               className={toClassName(
                 PANEL_SURFACE_CLASS,
                 // The height is clamped to the space the viewport left,

package/src/Overlay/useAnchoredOverlay.ts

@@ -2,7 +2,10 @@ import {
   useClonedChild,
   useUniqueId,
 } from "@charcuterie/logic"
-import type { Placement } from "@floating-ui/react"
+import type {
+  Placement,
+  VirtualElement,
+} from "@floating-ui/react"
 import {
   autoUpdate,
   flip,
@@ -15,7 +18,7 @@ import {
   useRole,
 } from "@floating-ui/react"
 import type { ReactElement, RefObject } from "react"
-import { createElement, useEffect } from "react"
+import { createElement, useLayoutEffect } from "react"
 
 /**
  * The floating-ui block every anchored overlay — `Popover`, `Menu`,
@@ -67,6 +70,21 @@ export type AnchoredOverlayRole =
   | "listbox"
   | "menu"
 
+/**
+ * What a panel can hang off in anchor mode: a real element, or a
+ * **virtual** one — an object that only knows its own rectangle.
+ *
+ * The virtual half is what a context menu needs. A menu opened by
+ * a press-and-hold belongs at the finger, not at the corner of the
+ * card underneath it, and floating-ui positions against a rect
+ * without caring where the rect came from. `flip` and `shift` work
+ * unchanged, which is the whole reason to express a point this way
+ * rather than with `top`/`left` of our own.
+ */
+export type AnchoredOverlayAnchor =
+  | HTMLElement
+  | VirtualElement
+
 export type UseAnchoredOverlayOptions = {
   /**
    * Anchor the panel to a **pre-existing** element the consumer already
@@ -75,8 +93,11 @@ export type UseAnchoredOverlayOptions = {
    * value and the query) — there is nothing to clone. Supply exactly one
    * of `anchorRef` / `trigger`; with `anchorRef`, `clonedTrigger` is
    * `null`.
+   *
+   * A **virtual** anchor is allowed here too, which is how a context
+   * menu opens at the point that was pressed.
    */
-  anchorRef?: RefObject<HTMLElement | null>
+  anchorRef?: RefObject<AnchoredOverlayAnchor | null>
   /**
    * Both default **on** — Escape and outside-press are what makes an
    * overlay an overlay. Switch one off for the honest exception (a
@@ -289,17 +310,39 @@ export const useAnchoredOverlay = ({
     (referenceProps.id as string | undefined) ??
     generatedTriggerId
 
-  // In anchor mode floating-ui's reference is the consumer's element, set
-  // imperatively — there is no cloned trigger to carry `refs.setReference`.
-  // `setReference` is stable; re-running on `isVisible` re-applies it when
-  // the panel opens (and after the anchor element mounts).
-  useEffect(() => {
-    if (!isAnchored) {
+  /**
+   * In anchor mode floating-ui's reference is the consumer's own
+   * element, set imperatively — there is no cloned trigger to carry
+   * `refs.setReference`.
+   *
+   * ⚠️ **`isVisible` is a dependency, and leaving it out is a bug
+   * that hides.** A `Combobox`'s anchor is mounted before the panel
+   * ever opens, so reading the ref once was enough for the one
+   * consumer this had; a **context menu** aims its anchor at the
+   * point that was just pressed, milliseconds before it opens, and a
+   * read that only happened on mount saw `null`. floating-ui with no
+   * reference positions at the top-left corner of the viewport —
+   * which is the same picture as "the panel is not anchored", and
+   * says nothing about why.
+   *
+   * ⚠️ And it is a **layout** effect. An ordinary effect sets the
+   * reference after the browser has already painted the panel at
+   * `0, 0`, so the menu flashes in the corner on its way to the
+   * finger.
+   *
+   * ⚠️ The `isVisible` guard is what **keeps** the dependency.
+   * Written as a bare re-read it is a dependency the effect never
+   * mentions, and `exhaustive-deps --fix` deletes it — which is
+   * how the bug came back once, silently, between a green test and
+   * a lint pass.
+   */
+  useLayoutEffect(() => {
+    if (!isAnchored || !isVisible) {
       return
     }
 
     refs.setReference(anchorRef.current)
-  }, [isAnchored, anchorRef, refs])
+  }, [isAnchored, anchorRef, isVisible, refs])
 
   const clonedChild = useClonedChild(
     trigger ?? PLACEHOLDER_TRIGGER,

package/src/ProgressBar/ProgressBar.tsx

@@ -35,6 +35,8 @@ export type ProgressBarProps = Omit<
   /** Required. A progressbar with no name is a grey rectangle. */
   label: string
   max?: number
+  /** Content above a full-height, muted track. It stays outside the ARIA widget. */
+  overlay?: ReactNode
   size?: ProgressBarSize
   thresholds?: readonly ProgressThreshold[]
   value?: number
@@ -80,6 +82,7 @@ export const ProgressBar = ({
   isValueShown = false,
   label,
   max = 100,
+  overlay,
   size = "md",
   thresholds,
   value = 0,
@@ -133,38 +136,59 @@ export const ProgressBar = ({
       )}
 
       <div
-        aria-busy={isIndeterminate || undefined}
-        aria-labelledby={labelId}
-        aria-valuemax={max}
-        aria-valuemin={0}
-        aria-valuenow={
-          isIndeterminate ? undefined : clampedValue
+        className={
+          overlay == null
+            ? undefined
+            : "grid overflow-hidden rounded-xl"
         }
-        className={toClassName(
-          "relative w-full overflow-hidden rounded-full bg-surface-sunken",
-          TRACK_SIZE_CLASS[size],
-        )}
-        role="progressbar"
       >
-        {isIndeterminate ? (
-          <span
-            className={toClassName(
-              // The sweep animates `inset-inline-start`, so it runs
-              // the other way in RTL for free — and its
-              // reduced-motion fallback hatches the whole track
-              // rather than parking at one end.
-              "charcuterie-sweep absolute inset-y-0 w-2/5 rounded-full",
-              INTENT_SOLID_FILL_CLASS[fillIntent],
-            )}
-          />
-        ) : (
-          <span
-            className={toClassName(
-              "block h-full rounded-full transition-[inline-size] duration-(--duration-normal) ease-standard",
-              INTENT_SOLID_FILL_CLASS[fillIntent],
-            )}
-            style={{ inlineSize: `${percent}%` }}
-          />
+        <div
+          aria-busy={isIndeterminate || undefined}
+          aria-labelledby={labelId}
+          aria-valuemax={max}
+          aria-valuemin={0}
+          aria-valuenow={
+            isIndeterminate ? undefined : clampedValue
+          }
+          className={toClassName(
+            "relative w-full overflow-hidden rounded-full bg-surface-sunken",
+            overlay == null
+              ? TRACK_SIZE_CLASS[size]
+              : "h-full rounded-xl [grid-area:1/1]",
+          )}
+          role="progressbar"
+        >
+          {isIndeterminate ? (
+            <span
+              className={toClassName(
+                // The sweep animates `inset-inline-start`, so it runs
+                // the other way in RTL for free — and its
+                // reduced-motion fallback hatches the whole track
+                // rather than parking at one end.
+                "charcuterie-sweep absolute inset-y-0 w-2/5 rounded-full",
+                INTENT_SOLID_FILL_CLASS[fillIntent],
+                overlay == null
+                  ? undefined
+                  : "rounded-none opacity-30",
+              )}
+            />
+          ) : (
+            <span
+              className={toClassName(
+                "block h-full rounded-full transition-[inline-size] duration-(--duration-normal) ease-standard",
+                INTENT_SOLID_FILL_CLASS[fillIntent],
+                overlay == null
+                  ? undefined
+                  : "rounded-none opacity-30",
+              )}
+              style={{ inlineSize: `${percent}%` }}
+            />
+          )}
+        </div>
+        {overlay == null ? null : (
+          <div className="relative min-w-0 [grid-area:1/1]">
+            {overlay}
+          </div>
         )}
       </div>
     </div>