@estiva-app/ui 0.9.0 → 0.10.0

package/src/IdentityMenu.tsx

@@ -1,7 +1,7 @@
-import { useRef, useState, type ReactNode } from 'react'
+import { useCallback, useRef, type ReactNode } from 'react'
 import { cn } from './cn'
 import { Divider } from './Divider'
-import { Menu, MenuItem, MenuRow, MenuSection } from './Menu'
+import { Menu, MenuItem, MenuPanel, MenuRow, MenuSection } from './Menu'
 import { Person } from './Person'
 import { PersonTrigger } from './PersonTrigger'
 
@@ -53,28 +53,46 @@ export interface IdentityMenuProps {
   children?: ReactNode | ((close: () => void) => ReactNode)
 }
 
-export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact' | 'className'> {
-  onClose: () => void
-  /** The trigger to hang from — the panel portals to the body and fits the
-   *  viewport, so no header, sidebar or scroll container can cover it (the
-   *  z-10 floating top bar trapped the old in-flow panel under a z-20 panel
-   *  header, 2026-09-03). Absent, the panel stands in flow — the stories. */
-  anchor?: HTMLElement | null
-  /** On the Menu surface — the stories pass `static` to stand it in flow. */
-  className?: string
+/**
+ * The menu alone, as a plain surface — what the docs canvases draw, and what
+ * a surface that wants the rows without the menu can use.
+ */
+export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact'> {
+  /** Called when a row asks the menu to close. */
+  onClose?: () => void
+}
+
+export function IdentityPanel({ className, onClose = () => {}, ...rest }: IdentityPanelProps) {
+  return (
+    <MenuPanel className={cn('w-72', className)}>
+      <IdentityRows {...rest} onClose={onClose} />
+    </MenuPanel>
+  )
 }
 
-/** The menu alone — what `IdentityMenu` opens. Exported so the stories show
- *  the designed artifact rather than a closed trigger, and for any surface
- *  that wants the panel without the trigger. */
-export function IdentityPanel({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, onClose, anchor, className, children }: IdentityPanelProps) {
+/** The old name for the same thing. */
+export const IdentityPanelSurface = IdentityPanel
+
+/**
+ * The panel's contents, without the menu around them.
+ *
+ * Split out at stage 4 for the same reason `MenuPanel` was split out of
+ * `Menu`: a real menu portals and places itself against a trigger, so it
+ * cannot stand in a docs page, and the canvases must still show the artifact
+ * (Katerina, D25). The stories draw these rows on a `MenuPanel`; the app gets
+ * them inside a `Menu`. One definition either way.
+ *
+ * Not exported from the package — `IdentityMenu` and `IdentityPanel` are the
+ * API; this is how they are built.
+ */
+export function IdentityRows({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, onClose, children }: Omit<IdentityPanelProps, 'className'> & { onClose: () => void }) {
   const act = (action: () => void) => () => {
     onClose()
     action()
   }
   const appRows = typeof children === 'function' ? children(onClose) : children
   return (
-    <Menu onClose={onClose} anchor={anchor} align="right" className={cn('w-72', className)}>
+    <>
       <MenuSection label={signedIn ? 'Signed in as' : 'Acting as'}>
         <MenuRow>
           <Person name={me.name} picture={me.picture} fallback="Anonymous" size={28} className="text-body-2-strong" />
@@ -116,50 +134,59 @@ export function IdentityPanel({ me, signedIn, relayUrl, idBase, onCopyKey, onSig
       )}
       {onCopyKey && <MenuItem label="Copy public key" onClick={act(onCopyKey)} />}
       {idBase && onSignOut && <MenuItem label="Sign out" onClick={act(onSignOut)} />}
-    </Menu>
+    </>
   )
 }
 
 export function IdentityMenu({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, compact = false, className, children }: IdentityMenuProps) {
-  const [open, setOpen] = useState(false)
-  /* The wrapper is the anchor: the panel hangs its right edge from this
-     div's, exactly where the old in-flow `absolute right-0` put it — but
-     portalled, so nothing z-indexed in the app can cover it. */
-  const anchorRef = useRef<HTMLDivElement>(null)
-
+  /*
+   * The menu owns the trigger (stage 4, 2026-09-08). It used to be the other
+   * way round — this component held `open`, and the panel hung from a ref to
+   * the wrapper — and four separate defects came from Base UI not knowing
+   * which element opened it: the face stopped closing its own menu, opening
+   * from the keyboard highlighted nothing, a hovered submenu row unmounted
+   * the panel, and the panel hung from a wrapper the app's layout could
+   * stretch. `PLAN.md` §6.2 has the measurements.
+   */
+  const actions = useRef<{ close: () => void; unmount: () => void } | null>(null)
+  const close = useCallback(() => actions.current?.close(), [])
   return (
-    <div ref={anchorRef} className={cn('relative', className)}>
-      <PersonTrigger
-        name={me.name}
-        picture={me.picture}
-        fallback="Anonymous"
-        compact={compact}
-        size={compact ? 36 : undefined}
-        open={open}
-        // Swallowed so the menu's outside-mousedown dismiss does not fire
-        // first and turn the toggle into a close-then-reopen flicker.
-        onMouseDown={(event) => event.stopPropagation()}
-        onClick={() => setOpen((value) => !value)}
-        // The row shape is named by its own text — the person. Only the bare
-        // face needs a label; naming the row would override the person's name
-        // as the accessible name (Ship's tests find the trigger by it).
-        aria-label={compact ? 'Account menu' : undefined}
-      />
-
-      {open && (
-        <IdentityPanel
+    /* The wrapper carries the caller's `className` and nothing else. It used
+       to be `relative`, because the panel was positioned against it; the panel
+       hangs from the trigger and portals now, so a positioning context here
+       would only be a lie about what this box does. */
+    <div className={className}>
+      <Menu
+        align="right"
+        actionsRef={actions}
+        className="w-72"
+        trigger={
+          <PersonTrigger
+            name={me.name}
+            picture={me.picture}
+            fallback="Anonymous"
+            compact={compact}
+            size={compact ? 36 : undefined}
+            /* The row shape is named by its own text — the person. Only the
+               bare face needs a label; naming the row would override the
+               person's name as the accessible name (Ship's tests find the
+               trigger by it). */
+            aria-label={compact ? 'Account menu' : undefined}
+          />
+        }
+      >
+        <IdentityRows
           me={me}
           signedIn={signedIn}
           relayUrl={relayUrl}
           idBase={idBase}
           onCopyKey={onCopyKey}
           onSignOut={onSignOut}
-          onClose={() => setOpen(false)}
-          anchor={anchorRef.current}
+          onClose={close}
         >
           {children}
-        </IdentityPanel>
-      )}
+        </IdentityRows>
+      </Menu>
     </div>
   )
 }

package/src/Kbd.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { Kbd } from './Kbd'
-import { Menu, MenuItem, MenuSection } from './Menu'
+import { MenuItem, MenuPanel, MenuSection } from './Menu'
 import { Tooltip } from './Tooltip'
 
 const meta = {
@@ -41,13 +41,13 @@ export const InContext: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex items-start gap-6">
-      <Menu onClose={() => {}} className="static w-[220px]">
+      <MenuPanel className="w-[220px]">
         <MenuSection label="Format">
           <MenuItem label="Heading" shortcut="#" />
           <MenuItem label="Quote" shortcut=">" />
           <MenuItem label="Numbered list" shortcut="1." />
         </MenuSection>
-      </Menu>
+      </MenuPanel>
       <div className="flex flex-col gap-2">
         <Tooltip label="Bold" shortcut="Cmd+B" />
         <Tooltip label="Italic" shortcut="Ctrl+I" />

package/src/Menu.mdx

@@ -5,32 +5,29 @@ import * as MenuStories from './Menu.stories'
 
 # Menu
 
-The shell every menu shares: an elevated container — hairline border, 8px
-radius, 8px padding, the large shadow — and the two exits every menu owes,
-**Escape and a click outside, owned here and never by the caller**. Rows are
-**MenuItem**, headings are **MenuSection**, a non-interactive line at row
-geometry is **MenuRow**, and **EnterHint** is the `↩ Enter` chip a picker row
-shows while highlighted.
-
-**MenuPanel** is the container on its own, without the behaviour — for the
-one case that cannot have it: a type-ahead popup inside a text editor, where
-the editor's own plugin already owns the keyboard and the placement, and a
-second Escape handler fights it. `Menu` renders `MenuPanel`, so the surface
-has one definition either way. If your surface opens from a trigger, you want
-`Menu`; reach for `MenuPanel` only when something else is already driving.
+A list of actions from a trigger. **The menu owns the trigger**, so a caller
+writes no open state, no placement and no dismiss — it hands over the control
+and the rows, and everything else is Base UI's.
+
+Rows are **MenuItem**, headings are **MenuSection**, a non-interactive line at
+row geometry is **MenuRow**, a row that opens another menu is **MenuSub**, and
+**EnterHint** is the `↩ Enter` chip a picker row shows while highlighted.
+
+**MenuPanel** is the container on its own, without the behaviour — for the one
+case that cannot have it: a type-ahead popup inside a text editor, where the
+editor's own plugin already owns the keyboard and a menu's roving focus would
+take focus out of the text. `Menu` renders `MenuPanel`, so the surface has one
+definition either way.
 
 <Canvas of={MenuStories.Items} />
 
 ## When
 
-- A click-opened list of actions: a `…` more-menu, an account menu, a
-  right-click's worth of verbs. Rows are the default `MenuItem` — 14px
-  label, optional `leading` icon, `shortcut` kbd chip, `destructive` in the
-  error colour.
-- A picker fed by typing: @-mentions, a people picker, a command list.
-  Those rows are `MenuItem size="tall"` — content height with a 40px floor,
-  room for a 32px face via `leading` and a `description` line — with an
-  `EnterHint` on the highlighted row.
+- A click-opened list of actions: a `⋮` more-menu, an account menu, a
+  right-click's worth of verbs.
+- A picker fed by typing: rows are `MenuItem size="tall"` — content height
+  with a 40px floor, room for a 32px face via `leading` and a `description`
+  line — with an `EnterHint` on the highlighted row.
 - Grouped choices where one is current: `MenuSection` over rows, `selected`
   on the chosen one.
 
@@ -38,81 +35,97 @@ has one definition either way. If your surface opens from a trigger, you want
 
 ## When not
 
-- Picking one value for a form field → **Select**. It is the same shell
-  behaviour plus a trigger that shows the value.
-- Rows that toggle checkboxes and stay open → that is a **listbox**, not a
-  menu; a Checkbox inside a `menuitem` button is invalid HTML. Build it as
-  a list in a DialogShell.
-- A strip of icon actions (reactions, formatting) → a toolbar of
-  **IconButton**s.
-- Anything with a title and a footer → **DialogShell**.
-- Who-you-are and where-you-are (the avatar in the top bar) →
-  **IdentityMenu**, already built on this shell.
+- **A panel of content — a field, a form, a row of controls** → **Popover**.
+  It is this surface with none of a menu's keyboard, which is what content
+  needs: a menu's typeahead would fight a text field.
+- Picking one value for a form field → **Select**.
+- Rows that toggle and stay open → that is a listbox, not a menu; a Checkbox
+  inside a `menuitem` is invalid. Build it as a list in a **DialogShell**.
+- A strip of icon actions → a toolbar of **IconButton**s.
+- Who-you-are and where-you-are → **IdentityMenu**, already built on this.
 
 ## How
 
-Menus are controlled: the caller keeps `open` state, renders the menu only
-while true, and hands it `onClose`. Escape and outside-click then work
-without the caller writing either.
-
 ```tsx
 import { Menu, MenuItem } from '@estiva-app/ui'
 
-{open && (
-  <Menu onClose={() => setOpen(false)}>
-    <MenuItem label="Rename" onClick={rename} />
-    <MenuItem label="Delete" destructive onClick={confirmDelete} />
-  </Menu>
-)}
+<Menu trigger={<IconButton aria-label="More" tooltip="More"><IconDots /></IconButton>}>
+  <MenuItem label="Rename" onClick={rename} />
+  <MenuItem label="Delete" destructive onClick={confirmDelete} />
+</Menu>
 ```
 
-Two anchorings:
-
-- **Default** — the menu hangs below its trigger, right-aligned; the
-  wrapper around trigger and menu must be `relative`.
-- **`position={{ top, left }}` or `{ top, right }`** — the menu portals to
-  the body at fixed viewport coordinates, for triggers inside containers
-  that scroll or clip.
+That is the whole of it. **No `open` state, no anchor, no `onClose`** — the
+menu is always mounted and Base UI decides when it is shown, which is what
+lets it place itself against the trigger, return focus to it, highlight the
+first row when it was opened from the keyboard, and treat a second press of
+the trigger as "close" rather than as a press outside.
+
+- **`trigger`** is any element that forwards its ref and spreads its props —
+  this package's `Button`, `IconButton` and `PersonTrigger` all do. An
+  icon-only trigger owes a `tooltip` and an `aria-label`.
+- **`align="right"`** hangs the menu's right edge from the trigger's, for a
+  control at the right of a row or a bar.
+- **`open` / `onOpenChange`** are there for a caller that must know or must
+  force it. Leave them off and the menu keeps its own state.
+- **`actionsRef`** gives `close()`, for content that is not a `MenuItem` and
+  so does not close the menu by being chosen.
+- A menu stands as tall as the room it opens into and scrolls only when the
+  screen has none; it flips above the trigger when the room below is worse,
+  and never leaves the screen.
+
+<Canvas of={MenuStories.OnACard} />
 
 ## Keys
 
 | Input | What happens |
 |---|---|
-| Escape | closes — the shell's listener, not the caller's |
-| `mousedown` outside | closes; the trigger swallows its own (see below) |
-| click inside the menu | stays open — the shell stops propagation |
-| Tab / Shift-Tab | moves focus through the rows (native buttons) |
-| Enter / Space on a focused row | activates it |
-| Arrow keys | nothing — a typeahead picker owns its own highlight |
+| click / Enter / Space on the trigger | opens; from the keyboard, the first row is highlighted |
+| ↑ / ↓ | move between rows, and wrap at the ends |
+| Home / End | first row / last row |
+| typing a row's first letters | jumps to that row |
+| Enter / Space on the highlighted row | activates it, and closes the menu |
+| → on a submenu row | opens the submenu **and highlights its first row**; ← closes it and comes back to the row |
+| Escape | closes, and gives focus back to the trigger |
+| a press outside, or a second press of the trigger | closes |
 
-### The trigger trap
+Focus moves into the menu when it opens and returns to the trigger when it
+closes. None of that existed before stage 4: a menu was a portalled box of
+buttons you tabbed through, and this page said the arrow keys did nothing.
 
-The outside-click exit listens on `mousedown`. A trigger that toggles on
-`click` will therefore see its own press close the menu and the click
-reopen it — a flicker that reads as "the menu ignores me". The trigger
-swallows the mousedown, exactly as IdentityMenu's does:
+### Hover-opened menus
 
-```tsx
-<button
-  onMouseDown={(event) => event.stopPropagation()}
-  onClick={() => setOpen((value) => !value)}
-/>
-```
+`openOnHover` opens the menu on hover and closes it shortly after the pointer
+leaves — for a control that only appears while the pointer is on a card.
+
+**Never use it on a menu that has a `MenuSub`** — the two together strand the
+menu open, and the component says so in the console if you try.
+
+Measured: enter the submenu's panel, then leave in any direction that does not
+cross back over the parent, and neither the submenu nor the menu ever closes
+again — at 200ms, 500ms, 1s and 2s. Leaving by a path that crosses the parent
+closes correctly, which is why it is easy to miss. Both triggers hard-code
+Floating UI's `safePolygon({ blockPointerEvents: true })`, which blocks pointer
+events while the path from a row to its panel is live; leaving that way never
+resolves the polygon, and Base UI exposes no prop for it.
+
+Without a submenu it is exact: opens on hover, closes ~200ms after the pointer
+leaves. `PLAN.md` §6.2 carries the measurements.
 
-### What stays the caller's
+### Rows without a menu
 
-Hover-opening, and submenus. A hover-opened menu owes the five popover
-rules (see the README — stay open over the menu, close on leave, guard the
-parent's hover); the shell gives only the two click-opened exits, so the
-hover choreography is the caller's. Submenus likewise stay caller-owned —
-if a second menu needs one, the shell learns it then.
+`MenuItem` and `MenuSection` work on a bare `MenuPanel`, and there they are
+plain buttons: no `role="menuitem"`, because ARIA requires a menu item to sit
+inside a `menu` or a `menubar` and a `MenuPanel` is a `<div>` with no role.
+Four surfaces used to claim menu items of nothing.
 
 ### Alignment
 
-A menu whose rows are `px-3` (tall picker rows) aligns its headings by
-passing `className="px-3"` to `MenuSection` — the heading row is `px-2` by
-default, matching the default rows.
+A menu whose rows are `px-3` (tall picker rows) aligns its headings by passing
+`className="px-3"` to `MenuSection` — the heading row is `px-2` by default,
+matching the default rows. A `Divider` inside a menu needs nothing: the panel
+already runs it the width of the rows it separates.
 
 ## Props
 
-<Controls of={MenuStories.Items} />
+<Controls of={MenuStories.FromATrigger} />

package/src/Menu.stories.tsx

@@ -1,89 +1,157 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconCopy, IconHighlight, IconPencil, IconTrash } from '@tabler/icons-react'
+import { IconCopy, IconDots, IconPencil, IconSquareRounded, IconTrash } from '@tabler/icons-react'
+import { Button } from './Button'
 import { Divider } from './Divider'
-import { Menu, MenuItem, MenuRow, MenuSection, MenuSub } from './Menu'
+import { IconButton } from './IconButton'
+import { Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSub } from './Menu'
 import { SectionLabel } from './SectionLabel'
 
 /**
- * The shell every menu shares — container, rows, headings, and the two exits
- * (Escape and a click outside) owned here, never by the caller. In an app
- * the menu hangs from its trigger or a portal position; stories pin it open
- * in-flow (`className="static"` wins over the anchoring) and centre it, so
- * the docs page shows each one inside its own frame.
+ * The shell every menu shares: an elevated container, rows, headings — and all
+ * of a menu's behaviour, which is Base UI's. **The menu owns its trigger**, so
+ * a caller writes no open state, no placement and no dismiss.
+ *
+ * ↑ ↓ walk the rows and wrap, Home and End jump, typing a row's first letters
+ * goes to it, → opens a submenu and ← closes it, Escape closes and gives focus
+ * back to the trigger.
+ *
+ * A live menu portals and places itself against its trigger, so it cannot
+ * stand in a docs canvas: **`Items` and `Sections` draw the surface** with
+ * `MenuPanel` — which is what a menu *is*, and what `Menu` renders — and every
+ * story below them is live (Katerina, D25).
  */
 const meta = {
   title: 'Overlays/Menu',
   component: Menu,
-  decorators: [(Story) => <div className="flex min-h-[240px] w-full items-center justify-center"><Story /></div>],
-  args: { onClose: () => {}, children: null, className: 'static' },
-  argTypes: { position: { control: false }, onClose: { control: false }, children: { control: false } },
+  decorators: [(Story) => <div className="flex min-h-[260px] w-full items-start justify-center pt-6"><Story /></div>],
+  args: { trigger: <Button variant="outlined">Open the menu</Button>, children: null },
+  argTypes: { trigger: { control: false }, children: { control: false }, onOpenChange: { control: false }, actionsRef: { control: false } },
 } satisfies Meta<typeof Menu>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-/** Rows with a leading icon, a shortcut, and the destructive colour for the one that deletes. */
+const icon = (Icon: typeof IconPencil) => <Icon size={16} stroke={1.5} className="text-text-secondary" />
+
+/** The anatomy at rest: rows with a leading icon, a shortcut, and the
+ *  destructive colour for the one that deletes. */
 export const Items: Story = {
-  render: (args) => (
-    <Menu {...args}>
-      <MenuItem label="Rename" leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="Copy link" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="min-w-[180px]">
+      <MenuItem label="Rename" leading={icon(IconPencil)} onClick={() => {}} />
+      <MenuItem label="Duplicate" leading={icon(IconCopy)} shortcut="Ctrl+D" onClick={() => {}} />
       <Divider className="my-1" />
       <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
-    </Menu>
+    </MenuPanel>
   ),
 }
 
-/** Groups under SectionLabel headings, with a Divider between them; `selected` marks the chosen value. */
+/** Groups under headings, with a divider between them. The divider runs the
+ *  width of the rows it separates, not the width of the panel's text. */
 export const Sections: Story = {
-  render: (args) => (
-    <Menu {...args}>
-      <MenuSection label="Sort by">
-        <MenuItem label="Newest first" selected onClick={() => {}} />
-        <MenuItem label="Oldest first" onClick={() => {}} />
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="min-w-[180px]">
+      <MenuSection label="Section">
+        <MenuItem label="Item one" selected onClick={() => {}} />
+        <MenuItem label="Item two" onClick={() => {}} />
       </MenuSection>
       <Divider className="my-1" />
-      <MenuSection label="Show">
-        <MenuItem label="Everything" onClick={() => {}} />
-        <MenuItem label="Unread only" onClick={() => {}} />
+      <MenuSection label="Another section">
+        <MenuItem label="Option one" onClick={() => {}} />
+        <MenuItem label="Option two" onClick={() => {}} />
       </MenuSection>
-    </Menu>
+    </MenuPanel>
+  ),
+}
+
+/** A non-interactive line at row geometry — a value, a note. */
+export const WithARow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="w-64">
+      <MenuRow>
+        <span className="min-w-0 flex-1 truncate text-[14px] leading-[140%] text-text-primary">Item one</span>
+        <SectionLabel className="text-text-secondary">Label</SectionLabel>
+      </MenuRow>
+      <Divider className="my-1" />
+      <MenuItem label="An action" onClick={() => {}} />
+    </MenuPanel>
   ),
 }
 
 /**
- * A row that opens another menu beside it — hover it. The panel portals to
- * the body and fits the viewport: right of the row with room, flipped left
- * at the screen edge, never cut off. Live rather than pinned, because the
- * placement IS the designed behaviour.
+ * Live. Click the button, then use only the keyboard: ↑ ↓ walk the rows and
+ * wrap, Home and End jump, typing "de" goes to Delete, Escape closes and puts
+ * focus back on the button.
+ *
+ * The trigger belongs to the menu, so nothing here keeps open state.
  */
-export const WithASubmenu: Story = {
-  render: (args) => (
-    <Menu {...args}>
-      <MenuItem label="Rename" leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuSub label="Mark as Highlight" leading={<IconHighlight size={16} stroke={1.5} className="text-text-secondary" />}>
-        <MenuItem label="Insight" onClick={() => {}} />
-        <MenuItem label="Concern" onClick={() => {}} />
-        <MenuItem label="Conclusion" onClick={() => {}} />
-        <MenuItem label="Question" onClick={() => {}} />
-        <MenuItem label="Summary" onClick={() => {}} />
+export const FromATrigger: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
+      <MenuItem label="Rename" leading={icon(IconPencil)} onClick={() => {}} />
+      <MenuItem label="Duplicate" leading={icon(IconCopy)} shortcut="Ctrl+D" onClick={() => {}} />
+      <MenuSub label="Move to…" leading={icon(IconSquareRounded)}>
+        <MenuItem label="Item one" onClick={() => {}} />
+        <MenuItem label="Item two" onClick={() => {}} />
+        <MenuItem label="Item three" onClick={() => {}} />
       </MenuSub>
       <Divider className="my-1" />
-      <MenuItem label="Delete" destructive onClick={() => {}} />
+      <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
     </Menu>
   ),
 }
 
-/** A non-interactive row at the item's geometry — identity lines, hints. */
-export const WithARow: Story = {
-  render: (args) => (
-    <Menu {...args} className="static w-64">
-      <MenuRow>
-        <span className="min-w-0 flex-1 truncate text-[14px] leading-[140%] text-text-primary">Ana Duarte</span>
-        <SectionLabel className="text-text-secondary">Owner</SectionLabel>
-      </MenuRow>
-      <Divider className="my-1" />
-      <MenuItem label="Sign out" onClick={() => {}} />
-    </Menu>
+/** The menu's right edge hangs from the trigger's, for a control at the right
+ *  of a bar. */
+export const RightAligned: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: () => (
+    /* `items-start`: a flex row stretches its children by default, and an
+       IconButton has no height of its own — without it the 24px square grew to
+       the row's 300px and wore a 300px hover fill (measured 24x268 before). */
+    <div className="flex h-[300px] w-full items-start justify-end p-4">
+      <Menu align="right" trigger={<IconButton aria-label="More" tooltip="More"><IconDots size={16} stroke={1.5} /></IconButton>}>
+        <MenuItem label="Rename" onClick={() => {}} />
+        <MenuItem label="Delete" destructive onClick={() => {}} />
+      </Menu>
+    </div>
+  ),
+}
+
+/**
+ * The shape a card uses: a `⋮` at the end of the row, named by its tooltip,
+ * opening a right-aligned menu on **click**.
+ *
+ * Walk down the rows, out to the submenu and back — it stays open the whole
+ * way, including the diagonal from a row to its panel, and closes on Escape,
+ * on a press outside, or on a second press of the `⋮`.
+ */
+export const OnACard: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-[420px] items-start gap-3 rounded-lg border border-border-default p-3">
+      <span className="min-w-0 flex-1 text-[14px] leading-[140%] text-text-primary">
+        A card. Press the control at the end of the row, then walk down the rows and out to the submenu.
+      </span>
+      <Menu
+        align="right"
+        trigger={<IconButton aria-label="More" tooltip="More"><IconDots size={16} stroke={1.5} /></IconButton>}
+        className="w-[244px] gap-2"
+      >
+        <MenuSection label="Section">
+          <MenuItem label="Duplicate" leading={icon(IconCopy)} onClick={() => {}} />
+          <MenuSub label="Move to…" leading={icon(IconSquareRounded)}>
+            <MenuItem label="Item one" onClick={() => {}} />
+            <MenuItem label="Item two" onClick={() => {}} />
+          </MenuSub>
+        </MenuSection>
+        <Divider className="my-1" />
+        <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+      </Menu>
+    </div>
   ),
 }