@estiva-app/ui 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/AppShell.stories.tsx

@@ -59,7 +59,7 @@ const rail = (
 /** The structured frame: solid bar, sidebar, content beside it. */
 export const Solid: Story = {
   render: (args) => (
-    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="⌘ K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
       <div className="flex h-full items-center justify-center">
         <EmptyState message="Nothing here yet." />
       </div>
@@ -86,7 +86,7 @@ export const Floating: Story = {
       variant="floating"
       menu={menuButton}
       logo="Estiva"
-      search={<SearchInput shortcut="⌘ K" className="w-[290px]" />}
+      search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />}
       identity={identity}
       nav={rail}
     >

package/src/AppShell.tsx

@@ -63,7 +63,14 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
   }
 
   return (
-    <div className="flex h-full min-h-0 flex-col bg-bg-base text-text-primary">
+    /* `relative overflow-hidden` is the seal the floating manner already has,
+       and it takes both halves: an absolutely positioned descendant with no
+       positioned ancestor belongs to the *viewport*, so a scroll container
+       never clips it and the document itself gains its position as scroll
+       range — the whole page scrolls, navigation and top bar included.
+       `relative` claims such strays for the shell; `overflow-hidden` clips
+       them at its edge. Either alone seals nothing. */
+    <div className="relative flex h-full min-h-0 flex-col overflow-hidden bg-bg-base text-text-primary">
       {bar}
       <div className="flex min-h-0 flex-1">
         {nav}

package/src/Avatar.tsx

@@ -65,7 +65,20 @@ export function Avatar({ src, name, alt = '', size = 36, className }: AvatarProp
         <img src={picture} alt={alt || name || ''} className="w-full h-full object-cover" onError={() => setBroken(true)} />
       ) : label ? (
         <div
-          className="w-full h-full flex items-center justify-center font-semibold"
+          /*
+            `leading-none` is load-bearing (2026-09-03). Centring a flex child
+            centres its LINE BOX, and a line box reserves room under the
+            baseline for descenders — which capitals never use — so initials
+            floated above the middle of every tile. It also inherited whatever
+            line-height surrounded it, so the same face sat differently in a
+            members pill and in a replies row. Measured over six letter pairs
+            at 18/24/36px: mean 0.64px high before, 0.06px after.
+
+            Per-letter variation stays (a "Y" carries its mass up top, a "ZB"
+            more than an "AJ") — that is the letterform, not the box, and it
+            is not something a rule here can flatten.
+          */
+          className="w-full h-full flex items-center justify-center font-semibold leading-none"
           style={{
             color: '#08121c',
             fontSize: Math.round(size * 0.36),

package/src/AvatarGroup.stories.tsx

@@ -33,6 +33,11 @@ export const OverflowShowsThree: Story = {
   },
 }
 
+/** The smaller face, for a dense row — a reply line's authors, say. */
+export const Small: Story = {
+  args: { size: 18 },
+}
+
 /**
  * Inside a members pill with the total count — the shape a conversation
  * header draws over the stack. The pill is the caller's; this is the group

package/src/AvatarGroup.tsx

@@ -8,10 +8,13 @@ import { Avatar } from './Avatar'
  * wrapper resolves pictures itself; a consumer without such a wrapper could
  * never have shown one.
  *
- * The ring sits on the Avatar itself: the old extra wrapper was a 24px
- * window minus a 2px border with a fixed 24px Avatar inside, so
- * overflow-hidden clipped 4px of face — and the right edge of the initials
- * with it, which is how "CO" rendered as "C(". One box, whole letters.
+ * The ring is drawn OUTSIDE the face, as a shadow (2026-09-03). It was a
+ * `border` before, which box-sizing takes out of the inside: a 24px avatar
+ * showed 20px of face, and at 18px only 14px — noticeably smaller than the
+ * number asked for. A shadow costs the face nothing, so `size` means the
+ * size. It replaced an even older wrapper whose `overflow-hidden` clipped
+ * 4px of face and the right edge of the initials with it ("CO" as "C(") —
+ * hence the rule this file keeps: nothing that clips ever wraps the face.
  */
 export interface AvatarGroupMember {
   name: string
@@ -21,21 +24,41 @@ export interface AvatarGroupMember {
 
 export interface AvatarGroupProps {
   members: AvatarGroupMember[]
+  /**
+   * Face size in pixels; the overlap follows it. 24 is the members pill,
+   * 18 the replies row (Katerina, 2026-09-03) — that row drew its own stack
+   * for two months for want of this one number, and drifted while it did.
+   */
+  size?: number
 }
 
-export function AvatarGroup({ members }: AvatarGroupProps) {
+export function AvatarGroup({ members, size = 24 }: AvatarGroupProps) {
   const visible = members.slice(0, 3)
+  /*
+    A third of the face, so a stack reads the same at any size — which is
+    exactly the ratio both hand-drawn stacks had arrived at independently
+    (8px on 24, 6px on 18). The container gives the last face its overlap
+    back as padding, so the group measures its true width.
+  */
+  const overlap = Math.round(size / 3)
+  // The ring scales with the face — 2px at 24, 1.5px at 18, which is what both
+  // hand-drawn stacks used before this component carried either of them.
+  const ring = size / 12
   return (
-    <div className="flex items-center pr-2">
+    <div className="flex items-center" style={{ paddingRight: overlap }}>
       {visible.map((member, i) => (
-        <Avatar
+        /*
+          The wrapper carries the overlap and the ring; the face carries
+          neither. It must never clip — see the note at the top of the file —
+          so it has the avatar's own radius and no overflow of its own.
+        */
+        <span
           key={i}
-          size={24}
-          name={member.name}
-          src={member.picture}
-          alt={member.name}
-          className="-mr-2 relative border-2 border-bg-surface"
-        />
+          className="relative flex rounded-sm"
+          style={{ marginRight: -overlap, boxShadow: `0 0 0 ${ring}px var(--bg-surface)` }}
+        >
+          <Avatar size={size} name={member.name} src={member.picture} alt={member.name} />
+        </span>
       ))}
     </div>
   )

package/src/ChipInput.tsx

@@ -2,6 +2,7 @@ import { useState, useRef, useMemo, useEffect, useLayoutEffect, type KeyboardEve
 import { createPortal } from 'react-dom'
 import { IconX } from '@tabler/icons-react'
 import { cn } from './cn'
+import { fitMenu } from './fit'
 import { MenuItem } from './Menu'
 
 /**
@@ -216,10 +217,21 @@ export function ChipInput<T extends ChipInputOption = ChipInputOption>({
 
       {showDropdown && anchorRect && createPortal(
         <div
-          className="fixed z-[60] max-h-[240px] overflow-y-auto bg-bg-elevated border border-border-default rounded-lg shadow-lg"
+          className="fixed z-[60] overflow-y-auto bg-bg-elevated border border-border-default rounded-lg shadow-lg"
+          /*
+            Placed by fitMenu (2026-09-03), not hung blindly below: an input
+            low on the screen flips its list upward instead of running the
+            tail past the bottom edge. The rows are a fixed 48px, so the
+            content height is arithmetic and needs no second render pass;
+            the 240px cap is the old max-h-[240px].
+          */
           style={{
-            top: anchorRect.bottom + 4,
-            left: anchorRect.left,
+            ...fitMenu({
+              anchor: { left: anchorRect.left, top: anchorRect.top, bottom: anchorRect.bottom },
+              menu: { width: anchorRect.width, contentHeight: matches.length * 48 },
+              viewport: { width: window.innerWidth, height: window.innerHeight },
+              cap: 240,
+            }),
             width: anchorRect.width,
           }}
         >

package/src/Divider.tsx

@@ -16,7 +16,11 @@ export function Divider({ orientation = 'horizontal', className }: DividerProps)
     <div
       role="separator"
       aria-orientation={orientation}
-      className={cn('bg-border-subtle', orientation === 'horizontal' ? 'h-px mx-3' : 'w-px self-stretch shrink-0', className)}
+      // shrink-0 on both orientations: a 1px flex child in an overflowing
+      // column shrinks to nothing, and a hairline that renders 0px tall is a
+      // hairline nobody can see — Peek's `/` menu had been drawing two of
+      // them, measured 0px, since it was built (2026-09-05).
+      className={cn('shrink-0 bg-border-subtle', orientation === 'horizontal' ? 'h-px mx-3' : 'w-px self-stretch', className)}
     />
   )
 }

package/src/IconButton.tsx

@@ -13,6 +13,9 @@ export type IconButtonVariant = 'muted' | 'outlined' | 'primary'
 export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: IconButtonVariant
   tooltip?: string
+  /** A key hint drawn as the `Kbd` chip inside the tooltip — for a button
+   *  whose only other affordance is a keyboard shortcut. */
+  tooltipShortcut?: string
   tooltipPlacement?: 'top' | 'bottom'
   /** The icon: 16px, stroke 1.5. */
   children: ReactNode
@@ -24,6 +27,7 @@ export function IconButton({
   children,
   disabled,
   tooltip,
+  tooltipShortcut,
   tooltipPlacement,
   type = 'button',
   ...props
@@ -51,7 +55,7 @@ export function IconButton({
 
   if (tooltip) {
     return (
-      <WithTooltip label={tooltip} placement={tooltipPlacement}>
+      <WithTooltip label={tooltip} shortcut={tooltipShortcut} placement={tooltipPlacement}>
         {button}
       </WithTooltip>
     )

package/src/IdentityMenu.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from 'react'
+import { useRef, useState, type ReactNode } from 'react'
 import { cn } from './cn'
 import { Divider } from './Divider'
 import { Menu, MenuItem, MenuRow, MenuSection } from './Menu'
@@ -55,6 +55,11 @@ export interface IdentityMenuProps {
 
 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
 }
@@ -62,14 +67,14 @@ export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact' |
 /** 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, className, children }: IdentityPanelProps) {
+export function IdentityPanel({ me, signedIn, relayUrl, idBase, onCopyKey, onSignOut, onClose, anchor, className, children }: IdentityPanelProps) {
   const act = (action: () => void) => () => {
     onClose()
     action()
   }
   const appRows = typeof children === 'function' ? children(onClose) : children
   return (
-    <Menu onClose={onClose} className={cn('w-72', className)}>
+    <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" />
@@ -117,9 +122,13 @@ export function IdentityPanel({ me, signedIn, relayUrl, idBase, onCopyKey, onSig
 
 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)
 
   return (
-    <div className={cn('relative', className)}>
+    <div ref={anchorRef} className={cn('relative', className)}>
       <PersonTrigger
         name={me.name}
         picture={me.picture}
@@ -146,6 +155,7 @@ export function IdentityMenu({ me, signedIn, relayUrl, idBase, onCopyKey, onSign
           onCopyKey={onCopyKey}
           onSignOut={onSignOut}
           onClose={() => setOpen(false)}
+          anchor={anchorRef.current}
         >
           {children}
         </IdentityPanel>

package/src/Kbd.mdx

@@ -0,0 +1,77 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as KbdStories from './Kbd.stories'
+
+<Meta of={KbdStories} />
+
+# Kbd
+
+The small chip that names the key which does the same thing. A bordered
+`kbd` on the inset fill, `caption` type in secondary ink, sized to its
+content and never shrinking.
+
+<Canvas of={KbdStories.Row} />
+
+## When
+
+- **At the right edge of a menu row** — `MenuItem`'s `shortcut` draws one for
+  you; pass the string, not the element.
+- **Inside a tooltip** — `Tooltip` and `WithTooltip` take a `shortcut` for the
+  same reason: an icon button whose only other affordance is a key.
+  `IconButton` forwards its own `tooltipShortcut` there.
+- **At the right edge of a search field** — `SearchInput`'s `shortcut`, for
+  the key that puts the cursor in it.
+- **In a shortcuts sheet**, where the key is the content rather than a hint.
+
+## Naming the key
+
+The label is a word, never a symbol — `Cmd+K`, `Enter`, `Esc`, `Backspace`.
+Two reasons, and they cost nothing to obey:
+
+1. A symbol is often wrong. `⌘` on a Windows machine names a key that is not
+   there.
+2. **The symbols are not in the font.** Geist Mono has no `⌘`, `⌫` or `↩`, so
+   the browser silently borrows each one from another face — measured at 10px,
+   every character the font owns advances exactly 6px, while `↩` comes back
+   8.63px and `⌫` 12.81px. One borrowed glyph in a row of chips makes that
+   chip wider and its ink a different shape.
+
+**`↑` and `↓` are the exception** — they are in Geist Mono at the same 6px, and
+an arrow is what is printed on the key. Their horizontal partners are not:
+Geist Mono owns `←` and `→` but draws them 10px wide, so a chip holding one
+comes out wider than the chips beside it. Measure before adding a symbol to
+this list; the font's coverage is not uniform.
+
+And a trigger is the character you would actually type. Peek's resolution
+block fires on `->`, so its row says `->` — there is no `→` key to press.
+
+## When not
+
+- A status, count or category → **Chip**. This one means *press this*.
+- A run of code inside prose → the consumer's own `code` styling; a keyboard
+  hint and a code span are different ideas that happen to both be monospace-ish.
+- Anything clickable → **Button**. A key hint is a label, not a control.
+
+## How
+
+```tsx
+import { Kbd } from '@estiva-app/ui'
+
+<Kbd>Cmd+K</Kbd>
+```
+
+Most callers never reach for it directly — they pass a string:
+
+```tsx
+<MenuItem label="Heading" shortcut="#" />
+<Tooltip label="Bold" shortcut="Cmd+B" />
+```
+
+<Canvas of={KbdStories.InContext} />
+
+It renders what it is given and formats nothing. A modifier is called Cmd on
+Apple platforms and Ctrl elsewhere, and only the caller knows which it is
+looking at — so decide there and pass the finished label.
+
+## Props
+
+<Controls of={KbdStories.Default} />

package/src/Kbd.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Kbd } from './Kbd'
+import { Menu, MenuItem, MenuSection } from './Menu'
+import { Tooltip } from './Tooltip'
+
+const meta = {
+  title: 'Primitives/Kbd',
+  component: Kbd,
+  args: { children: 'Cmd+K' },
+  argTypes: { children: { control: 'text' } },
+} satisfies Meta<typeof Kbd>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/** A single trigger character, the way a command menu names its own key. */
+export const TriggerCharacter: Story = { args: { children: '/' } }
+
+/** A chord. Whoever passes it decides the platform's spelling. */
+export const Chord: Story = { args: { children: 'Ctrl+Alt+1' } }
+
+/** A named key. */
+export const NamedKey: Story = { args: { children: 'Esc' } }
+
+/** The four side by side. */
+export const Row: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      {['/', 'Cmd+K', 'Ctrl+Alt+1', 'Esc'].map((k) => (
+        <Kbd key={k}>{k}</Kbd>
+      ))}
+    </div>
+  ),
+}
+
+/** Where it appears on its own: a menu row's `shortcut`, and a tooltip's. */
+export const InContext: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-start gap-6">
+      <Menu onClose={() => {}} className="static w-[220px]">
+        <MenuSection label="Format">
+          <MenuItem label="Heading" shortcut="#" />
+          <MenuItem label="Quote" shortcut=">" />
+          <MenuItem label="Numbered list" shortcut="1." />
+        </MenuSection>
+      </Menu>
+      <div className="flex flex-col gap-2">
+        <Tooltip label="Bold" shortcut="Cmd+B" />
+        <Tooltip label="Italic" shortcut="Ctrl+I" />
+        <Tooltip label="Comment" />
+      </div>
+    </div>
+  ),
+}

package/src/Kbd.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A keyboard hint — the small chip that names the key which does the same thing.
+ *
+ * **The look is SearchInput's shortcut chip** (Katerina, 2026-09-05), which is
+ * the one the apps already show: an inset pill with a hairline border, and under
+ * Signal and Ship the keycap treatment — mono, 10px, a lighter fill and a thicker
+ * bottom edge, so it reads as a key rather than a label.
+ *
+ * It existed before this file did, drawn inline inside `MenuItem` and again
+ * inside `SearchInput`. Extracted when `Tooltip` needed a third copy.
+ *
+ * **Sizes are arbitrary values on purpose.** `text-caption` beside a
+ * `text-{color}` is dropped by tailwind-merge, so the chip silently inherited
+ * whatever size surrounded it — 10px in a composer, something else elsewhere.
+ * `text-[12px]` survives the merge.
+ *
+ * Content is whatever names the key — a trigger character (`/`, `@`), a chord
+ * (`Cmd+B`, `Ctrl+Alt+1`), or a word (`Esc`). It does not format anything: a caller
+ * that knows the platform passes the label it wants.
+ */
+export interface KbdProps {
+  children: ReactNode
+  className?: string
+}
+
+export function Kbd({ children, className }: KbdProps) {
+  return (
+    <kbd
+      className={cn(
+        'inline-flex shrink-0 items-center justify-center whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset px-1 py-px font-sans text-[12px] leading-[120%] font-normal text-text-secondary',
+        'signal:border-b-2 signal:pt-[2px] signal:pb-px signal:bg-[rgba(255,255,255,.05)] signal:font-mono signal:text-[10px]',
+        'ship:border-b-2 ship:pt-[2px] ship:pb-px ship:bg-[rgba(255,255,255,.05)] ship:font-mono ship:text-[10px]',
+        className,
+      )}
+    >
+      {children}
+    </kbd>
+  )
+}

package/src/Menu.fit.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import { clampBox, fitMenu, fitSubmenu } from './fit'
+
+/**
+ * The Menu shell's viewport geometry (Katerina, 2026-09-03): the identity
+ * menu vanished under a z-indexed panel header, and a reply menu's highlight
+ * submenu was cut off by the right screen edge — its hand-rolled flip read a
+ * ref that was never attached, so it measured nothing. The portal fixes the
+ * covering; these pin the pure half of the fitting.
+ */
+const viewport = { width: 1280, height: 800 }
+
+describe('fitMenu without a cap (the Menu shell)', () => {
+  it('lets a tall panel stand at its full height when the room is there — no scrollbar', () => {
+    // The identity panel: ~450px tall on a 900px screen. With Select's 288
+    // cap it grew a scrollbar at full height; without one it just stands.
+    const fit = fitMenu({
+      anchor: { left: 1100, top: 20, bottom: 56 },
+      menu: { width: 288, contentHeight: 450 },
+      viewport: { width: 1440, height: 900 },
+    })
+    expect(fit.maxHeight).toBeGreaterThanOrEqual(450)
+  })
+
+  it('still caps to the room when the screen truly runs out', () => {
+    const fit = fitMenu({
+      anchor: { left: 100, top: 20, bottom: 56 },
+      menu: { width: 288, contentHeight: 1200 },
+      viewport: { width: 1440, height: 900 },
+    })
+    expect(fit.maxHeight).toBe(900 - 56 - 4 - 8)
+  })
+})
+
+describe('clampBox', () => {
+  it('leaves a well-placed box exactly where the caller put it', () => {
+    const fit = clampBox({ box: { left: 100, top: 200, width: 300, height: 400 }, viewport })
+    expect(fit).toEqual({ left: 100, top: 200, maxHeight: 400 })
+  })
+
+  it('slides a box back inside the right edge, margin kept', () => {
+    const fit = clampBox({ box: { left: 1100, top: 200, width: 300, height: 400 }, viewport })
+    expect(fit.left).toBe(1280 - 300 - 8)
+  })
+
+  it('never pushes a box past the left edge either', () => {
+    const fit = clampBox({ box: { left: -40, top: 200, width: 300, height: 400 }, viewport })
+    expect(fit.left).toBe(8)
+  })
+
+  it('slides a box up so its tail stays on screen', () => {
+    const fit = clampBox({ box: { left: 100, top: 700, width: 300, height: 400 }, viewport })
+    expect(fit.top).toBe(800 - 400 - 8)
+  })
+
+  it('caps a box taller than the viewport and pins it to the top margin', () => {
+    const fit = clampBox({ box: { left: 100, top: 100, width: 300, height: 900 }, viewport })
+    expect(fit.maxHeight).toBe(800 - 16)
+    expect(fit.top).toBe(8)
+  })
+
+  it('keeps the 120px floor — scrollable beats invisible', () => {
+    const fit = clampBox({ box: { left: 100, top: 200, width: 300, height: 40 }, viewport })
+    expect(fit.maxHeight).toBeGreaterThanOrEqual(120)
+  })
+})
+
+describe('fitSubmenu', () => {
+  const panel = { width: 160, height: 200 }
+
+  it('opens to the right of a row with room', () => {
+    const fit = fitSubmenu({ row: { left: 500, right: 740, top: 300 }, panel, viewport })
+    expect(fit).toEqual({ left: 744, top: 300 })
+  })
+
+  it('flips to the left at the right screen edge (the highlight submenu cut)', () => {
+    const fit = fitSubmenu({ row: { left: 1000, right: 1240, top: 300 }, panel, viewport })
+    expect(fit.left).toBe(1000 - 4 - 160)
+  })
+
+  it('never lands past the left edge even when flipped from a narrow spot', () => {
+    const fit = fitSubmenu({ row: { left: 60, right: 1240, top: 300 }, panel, viewport })
+    expect(fit.left).toBe(8)
+  })
+
+  it('slides up when the tail would run past the bottom', () => {
+    const fit = fitSubmenu({ row: { left: 500, right: 740, top: 700 }, panel, viewport })
+    expect(fit.top).toBe(800 - 200 - 8)
+  })
+})

package/src/Menu.mdx

@@ -9,9 +9,16 @@ 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" a picker 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.
+
 <Canvas of={MenuStories.Items} />
 
 ## When

package/src/Menu.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconCopy, IconPencil, IconTrash } from '@tabler/icons-react'
+import { IconCopy, IconHighlight, IconPencil, IconTrash } from '@tabler/icons-react'
 import { Divider } from './Divider'
-import { Menu, MenuItem, MenuRow, MenuSection } from './Menu'
+import { Menu, MenuItem, MenuRow, MenuSection, MenuSub } from './Menu'
 import { SectionLabel } from './SectionLabel'
 
 /**
@@ -27,7 +27,7 @@ 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="⌘ C" onClick={() => {}} />
+      <MenuItem label="Copy link" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
       <Divider className="my-1" />
       <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
     </Menu>
@@ -51,6 +51,29 @@ export const Sections: Story = {
   ),
 }
 
+/**
+ * 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.
+ */
+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={() => {}} />
+      </MenuSub>
+      <Divider className="my-1" />
+      <MenuItem label="Delete" destructive onClick={() => {}} />
+    </Menu>
+  ),
+}
+
 /** A non-interactive row at the item's geometry — identity lines, hints. */
 export const WithARow: Story = {
   render: (args) => (