@estiva-app/ui 0.23.0 → 0.24.1

package/src/IconButton.test.tsx

@@ -28,6 +28,31 @@ describe('IconButton', () => {
     expect(onClick).toHaveBeenCalledTimes(1)
   })
 
+  it('href: a link that looks like the button, with its tooltip', async () => {
+    const user = userEvent.setup()
+    render(
+      <IconButton href="/documents/12" aria-label="Open" tooltip="Open">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('button')).toBeNull()
+    const link = screen.getByRole('link', { name: 'Open' })
+    expect(link.getAttribute('href')).toBe('/documents/12')
+    expect(link.className).toContain('rounded-lg')
+    await user.hover(link)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Open')
+  })
+
+  it('href while it cannot be used: the button, since a link cannot be disabled', () => {
+    render(
+      <IconButton href="/documents/12" aria-label="Open" disabledReason="Read only">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('link')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Open' }).getAttribute('aria-disabled')).toBe('true')
+  })
+
   it('shows the tooltip on hover, with its shortcut', async () => {
     const user = userEvent.setup()
     render(

package/src/IconButton.tsx

@@ -37,6 +37,14 @@ export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
   /** Why the action cannot succeed right now. Disables the button, keeps it
    *  reachable by keyboard, and shows the reason as the tooltip. */
   disabledReason?: string
+  /**
+   * A link that looks like an icon button: an anchor, so the address stays
+   * real for a modified click or a new tab, as `Link` keeps it. A router app
+   * passes `onClick`, prevents the default and navigates. A link cannot be
+   * disabled, so while it would be — `disabled`, `disabledReason`, a busy
+   * Form — it is the button (UIG-14, Katerina, 18 September).
+   */
+  href?: string
   /** The icon: 16px, stroke 1.5. */
   children: ReactNode
 }
@@ -53,56 +61,63 @@ export function IconButton({
   tooltipShortcut,
   tooltipPlacement,
   type = 'button',
+  href,
   ...props
 }: IconButtonProps) {
   // Inside a busy Form: switched off, and looking it (formBusy.ts).
   const formBusy = useFormBusy()
-  const button = (
-    <BaseButton
-      type={type}
-      disabled={disabled || !!disabledReason || formBusy}
-      focusableWhenDisabled={!!disabledReason}
-      className={(state) =>
-        cn(
-          // `shrink-0` stops a flex parent squashing the button; `self-center`
-          // stops one stretching it. Two different failures, and both have
-          // happened here: a row with no `items-*` drew this 24 wide and 228
-          // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
-          // is the size of its icon and its padding, whatever box it lands in.
-          //
-          // This is the one of the two that needs it: an IconButton states no
-          // height, so its cross size is `auto` and a stretching parent takes
-          // it. Measured in the same 260px row on 2026-09-12: 24px with this
-          // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
-          // stretched and carries no `self-center` — see the note there.
-          'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
-          !state.disabled && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
-          !state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
-          !state.disabled && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
-          !state.disabled && variant === 'current' && 'hover:bg-bg-hover',
-          state.disabled && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
-          state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
-          state.disabled && variant === 'outlined' && 'border border-border-default text-text-disabled',
-          // Always, disabled too: the colour of where it sits, and Resolve's green.
-          variant === 'current' && 'text-current',
-          variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
-          pressed && 'bg-bg-active text-text-primary',
-          glow && 'signal:shadow-glow-accent',
-          // `pointer-events-none` only where the button is truly out of reach:
-          // with a `disabledReason` the button IS the tooltip's trigger, and a
-          // trigger the pointer cannot land on never opens one. Base UI already
-          // swallows the click.
-          state.disabled && !disabledReason && 'pointer-events-none',
-          state.disabled && 'cursor-not-allowed',
-          className,
-        )
-      }
-      aria-pressed={pressed}
-      {...props}
-    >
-      {children}
-    </BaseButton>
-  )
+  const unusable = disabled || !!disabledReason || formBusy
+  const look = (off: boolean) =>
+    cn(
+      // `shrink-0` stops a flex parent squashing the button; `self-center`
+      // stops one stretching it. Two different failures, and both have
+      // happened here: a row with no `items-*` drew this 24 wide and 228
+      // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
+      // is the size of its icon and its padding, whatever box it lands in.
+      //
+      // This is the one of the two that needs it: an IconButton states no
+      // height, so its cross size is `auto` and a stretching parent takes
+      // it. Measured in the same 260px row on 2026-09-12: 24px with this
+      // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
+      // stretched and carries no `self-center` — see the note there.
+      'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
+      !off && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
+      !off && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
+      !off && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
+      !off && variant === 'current' && 'hover:bg-bg-hover',
+      off && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
+      off && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
+      off && variant === 'outlined' && 'border border-border-default text-text-disabled',
+      // Always, disabled too: the colour of where it sits, and Resolve's green.
+      variant === 'current' && 'text-current',
+      variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
+      pressed && 'bg-bg-active text-text-primary',
+      glow && 'signal:shadow-glow-accent',
+      // `pointer-events-none` only where the button is truly out of reach:
+      // with a `disabledReason` the button IS the tooltip's trigger, and a
+      // trigger the pointer cannot land on never opens one. Base UI already
+      // swallows the click.
+      off && !disabledReason && 'pointer-events-none',
+      off && 'cursor-not-allowed',
+      className,
+    )
+  const button =
+    href && !unusable ? (
+      <a href={href} className={look(false)} {...(props as unknown as ComponentPropsWithRef<'a'>)}>
+        {children}
+      </a>
+    ) : (
+      <BaseButton
+        type={type}
+        disabled={unusable}
+        focusableWhenDisabled={!!disabledReason}
+        className={(state) => look(state.disabled)}
+        aria-pressed={pressed}
+        {...props}
+      >
+        {children}
+      </BaseButton>
+    )
 
   const label = disabledReason ?? tooltip
   if (label) {

package/src/IdentityMenu.mdx

@@ -62,10 +62,19 @@ import { IdentityMenu } from '@estiva-app/ui'
   row's full height, and the panel hung from the bottom of *that* — measured
   360px below the face, with a scrollbar it should not have had.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Everything a Menu owns: it floats, stays attached, closes on a press outside or on Escape, and walks its rows with the arrow keys | a menu of your own around the face |  |
+| Gives focus back to the face when it closes | focus code |  |
+
 ## Keys
 
 Since stage 4 the panel is a Base UI `Menu`, and **the arrow keys walk the
-actions only** (Katerina, D22): they step over the identity block, the
+actions only**: they step over the identity block, the
 workspace line and the notes, because those are not things you can do.
 
 | Input | What happens |

package/src/InlineChip.mdx

@@ -51,6 +51,17 @@ import { InlineChip } from '@estiva-app/ui'
 - A rich-text editor that renders chips from strings cannot use a component.
   `inlineChipClassName(tone)` gives it the same classes.
 
+- `INLINE_CHIP_CLASSES` and `INLINE_CHIP_TONE_CLASSES` give the same look where
+  only classes can go — inside an editor.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| With `href`, keeps a real address, so a modified click or a new tab still works | a `<span>` with a click handler |  |
+
 ## Props
 
 <Controls of={InlineChipStories.Neutral} />

package/src/Kbd.mdx

@@ -41,8 +41,8 @@ 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.
+And a trigger is the character you would actually type. A shortcut that fires
+on `->` shows `->` — there is no `→` key to press.
 
 ## When not
 
@@ -72,6 +72,10 @@ 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.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={KbdStories.Default} />

package/src/Link.mdx

@@ -12,6 +12,8 @@ the app decides how it navigates.
 
 ## When
 
+- **It takes the size and colour of the text around it**: put it inside that
+  text.
 - **`text`** — a link written inside text: the info colour, always
   underlined, dimming on hover.
 - **`quiet`** — a title or a time that is also a link. It takes the colour and
@@ -28,6 +30,7 @@ the app decides how it navigates.
 - An action — something happens, nothing is navigated to → **Button**.
 - A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
 - The trail back up → **Breadcrumb**.
+- A link that looks like an icon button → **IconButton** with `href`.
 - A word standing for a person or a thing, drawn in a small box → **InlineChip**
   with `href`.
 
@@ -58,7 +61,16 @@ import { Link } from '@estiva-app/ui'
   Its size and colour still come from the text around it.
 - `quiet`, `underlined` and `plain` take their size and colour from where they
   sit, so put those on your own element around the link, not on the link —
-  the lint refuses a look passed in `className` (UIG-9).
+  the lint refuses a look passed in `className`.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a link | `role="link"` | ✓ |
+| Is reachable with Tab | a `tabIndex` | ✓ |
 
 ## Props
 

package/src/ListColumn.mdx

@@ -0,0 +1,87 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ListColumnStories from './ListColumn.stories'
+
+<Meta of={ListColumnStories} />
+
+# ListColumn
+
+The list column of a page: 290px wide with a line on its right, its name in a
+`ContainerHeader`, and the list under it, which scrolls.
+
+<Canvas of={ListColumnStories.Default} />
+
+## When
+
+- **Its size is its own**: 290px wide and the full height of where it sits.
+  Nothing around it sets its width, and nothing squeezes it.
+- A page that lists things beside the one that is open: the list on the left,
+  the chosen thing to its right.
+- `spacing="rows"` (the default, 2px between rows) for a list of one kind of
+  row. `spacing="sections"` (4px) for groups with labels and dividers of their
+  own.
+- `above` for a row that stays put while the list scrolls: a field that adds
+  to the list.
+- `collapsed` closes it with the rail: it narrows to nothing and fades, in
+  300ms. What opens and closes the rail is yours.
+
+<Canvas of={ListColumnStories.Sections} />
+
+<Canvas of={ListColumnStories.WithARowAbove} />
+
+## When not
+
+- The app's own places, as the frame's column → **Sidebar**, in AppShell's
+  solid frame.
+- A short list inside a panel or a card → your rows in a **ScrollArea**.
+- A bar over something that is not a list → **ContainerHeader** on its own.
+
+## How
+
+```tsx
+import { ListColumn, Toolbar, ToolbarButton } from '@estiva-app/ui'
+
+<ListColumn
+  title="Items"
+  actions={
+    <Toolbar aria-label="Item list actions" surface={false}>
+      <ToolbarButton tooltip="New item" aria-label="New item" onClick={create}>
+        <IconEdit size={16} stroke={1.5} />
+      </ToolbarButton>
+    </Toolbar>
+  }
+  collapsed={railClosed}
+>
+  {items.map((item) => (
+    <ItemRow key={item.id} item={item} />
+  ))}
+</ListColumn>
+```
+
+- It sits beside the page's main area, inside AppShell's card: put both in a
+  flex row, the main area `flex-1`.
+- The numbers: 290px wide, a 1px line on the right. The header is
+  ContainerHeader's: 48px, the title 20px in. The list starts 16px under the
+  header and ends 12px above the bottom, and its rows sit 12px in from each
+  side.
+- The rows are yours. It scrolls them, so a list that grows with its data is
+  never cut off at the fold, even when today's data fits.
+- **Planned:** dragging its edge to resize it, with `SplitLayout` in
+  `@estiva-app/ui/layout` (migration stage 8). The 380px column beside a
+  conversation gets the same treatment then.
+
+<Canvas of={ListColumnStories.ManyRows} />
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Draws the column: 290px, a line on its right, and a ContainerHeader on top | a width, a border and a header row of your own |  |
+| Scrolls its rows in a ScrollArea, 16px under the header, 12px in from each side | `overflow-auto`, or padding of your own around the rows |  |
+| Closes with the rail when `collapsed`: narrows to nothing and fades | a width transition of your own |  |
+| Keeps its 290px beside a main area that grows | `shrink-0` |  |
+
+## Props
+
+<Controls of={ListColumnStories.Default} />

package/src/ListColumn.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSortDescending, IconSquareRounded } from '@tabler/icons-react'
+import { useState } from 'react'
+import { Button } from './Button'
+import { Divider } from './Divider'
+import { Form } from './Form'
+import { ListColumn } from './ListColumn'
+import { NavItem } from './NavItem'
+import { SectionLabel } from './SectionLabel'
+import { SkeletonList } from './Skeleton'
+import { TextInput } from './TextInput'
+import { Toolbar, ToolbarButton } from './Toolbar'
+
+/**
+ * The list column of a page: 290px, a line on its right, a header, and a list
+ * that scrolls. The rows are the app's own; these stories draw `NavItem`s as
+ * stand-ins.
+ */
+const meta = {
+  title: 'Layout/ListColumn',
+  component: ListColumn,
+  parameters: { layout: 'fullscreen' },
+  args: { title: 'Items', children: null },
+  argTypes: { children: { control: false }, actions: { control: false }, above: { control: false } },
+  // The column beside a main area, inside a surface — where it sits in the frame's card.
+  decorators: [
+    (Story) => (
+      <div className="flex h-screen bg-bg-surface">
+        {Story()}
+        <div className="min-w-0 flex-1" />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof ListColumn>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const icon = <IconSquareRounded size={16} stroke={1.5} />
+const names = ['one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight']
+const rows = (n: number) =>
+  Array.from({ length: n }, (_, i) => <NavItem key={i} href="#" label={`Item ${names[i] ?? i + 1}`} icon={icon} active={i === 1} />)
+
+const actions = (
+  <Toolbar aria-label="Item list actions" surface={false}>
+    <ToolbarButton tooltip="Sort by" aria-label="Sort by">
+      <IconSortDescending size={16} stroke={1.5} />
+    </ToolbarButton>
+    <ToolbarButton tooltip="New item" aria-label="New item">
+      {icon}
+    </ToolbarButton>
+  </Toolbar>
+)
+
+/** A list of one kind of row, 2px apart, with the column's actions in its header. */
+export const Default: Story = {
+  args: { title: 'Items', actions },
+  render: (args) => <ListColumn {...args}>{rows(6)}</ListColumn>,
+}
+
+/** Groups with labels and a divider of their own: 4px between rows. */
+export const Sections: Story = {
+  args: { title: 'Items', spacing: 'sections' },
+  render: (args) => (
+    <ListColumn {...args}>
+      <div className="flex h-8 shrink-0 items-center px-2">
+        <SectionLabel>Group one</SectionLabel>
+      </div>
+      {rows(3)}
+      <Divider className="my-2" />
+      <div className="flex h-8 shrink-0 items-center px-2">
+        <SectionLabel>Group two</SectionLabel>
+      </div>
+      {rows(4)}
+    </ListColumn>
+  ),
+}
+
+/** A row under the header that stays put while the list scrolls: a field that adds to the list. */
+export const WithARowAbove: Story = {
+  parameters: { controls: { disable: true } },
+  render: function RowAbove() {
+    const [name, setName] = useState('')
+    return (
+      <ListColumn
+        title="Items"
+        above={
+          <Form onSubmit={() => setName('')} className="flex items-center gap-2 px-3 pt-3 pb-1">
+            <TextInput className="min-w-0 flex-1" value={name} onChange={(e) => setName(e.target.value)} placeholder="New item name" aria-label="New item name" />
+            <Button className="shrink-0" type="submit" disabled={!name.trim()}>
+              Create
+            </Button>
+          </Form>
+        }
+      >
+        {rows(5)}
+      </ListColumn>
+    )
+  },
+}
+
+/** More rows than fit: the list scrolls under a header that stays. */
+export const ManyRows: Story = {
+  args: { title: 'Items', actions },
+  render: (args) => <ListColumn {...args}>{rows(80)}</ListColumn>,
+}
+
+/** While the list is on its way: a skeleton shaped like the rows. */
+export const Loading: Story = {
+  args: { title: 'Items' },
+  render: (args) => (
+    <ListColumn {...args}>
+      <SkeletonList rows={8} />
+    </ListColumn>
+  ),
+}
+
+/** Closed with the rail: it narrows to nothing and fades. Press the button to watch it. */
+export const Collapsing: Story = {
+  parameters: { controls: { disable: true } },
+  render: function Collapsing() {
+    const [collapsed, setCollapsed] = useState(false)
+    return (
+      <>
+        <ListColumn title="Items" collapsed={collapsed}>
+          {rows(6)}
+        </ListColumn>
+        <div className="p-4">
+          <Button variant="outlined" onClick={() => setCollapsed((c) => !c)}>
+            {collapsed ? 'Open the column' : 'Close the column'}
+          </Button>
+        </div>
+      </>
+    )
+  },
+}

package/src/ListColumn.test.tsx

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+/** What the ListColumn page claims, pinned. Sizes are measured in the browser; these pin the parts. */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ListColumn } from './ListColumn'
+
+afterEach(cleanup)
+
+describe('ListColumn', () => {
+  it('is headed by its title', () => {
+    render(<ListColumn title="Items">{null}</ListColumn>)
+    expect(screen.getByText('Items')).toBeTruthy()
+  })
+
+  it('is 290px wide with a line on its right, and keeps its width', () => {
+    const { container } = render(<ListColumn title="Items">{null}</ListColumn>)
+    const classes = (container.firstElementChild as HTMLElement).className.split(' ')
+    expect(classes).toContain('w-[290px]')
+    expect(classes).toContain('border-r')
+    expect(classes).toContain('shrink-0')
+  })
+
+  it('collapsed: narrows to nothing, loses its line, and fades', () => {
+    const { container } = render(<ListColumn title="Items" collapsed>{null}</ListColumn>)
+    const classes = (container.firstElementChild as HTMLElement).className.split(' ')
+    expect(classes).toContain('w-0')
+    expect(classes).toContain('border-r-0')
+    expect(classes).toContain('opacity-0')
+  })
+
+  it('draws its rows in the list, and a row above the list outside it', () => {
+    render(
+      <ListColumn title="Items" above={<p>Above</p>}>
+        <p>Row</p>
+      </ListColumn>,
+    )
+    const list = screen.getByText('Row').parentElement as HTMLElement
+    expect(list.className.split(' ')).toEqual(expect.arrayContaining(['px-3', 'pt-4', 'pb-3', 'gap-0.5']))
+    expect(list.contains(screen.getByText('Above'))).toBe(false)
+  })
+
+  it('sections: 4px between rows', () => {
+    render(
+      <ListColumn title="Items" spacing="sections">
+        <p>Row</p>
+      </ListColumn>,
+    )
+    expect((screen.getByText('Row').parentElement as HTMLElement).className.split(' ')).toContain('gap-1')
+  })
+})

package/src/ListColumn.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+import { ContainerHeader } from './ContainerHeader'
+import { ScrollArea } from './ScrollArea'
+
+/**
+ * The list column of a page: the column beside the page's main area that lists
+ * what it can open — 290px wide, a line on its right, its name in a
+ * `ContainerHeader`, and a list under it that scrolls.
+ *
+ * Moved in from Peek as it looks (UIG-14, N9), where five pages drew it by
+ * hand and each carried the same numbers: the frame's 290px and its line, and
+ * the list's steps — 16px under the header, 12px above the bottom, rows 12px
+ * in from each side. The numbers live here now, once.
+ *
+ * It scrolls its rows itself. A list column that did not was the first of the
+ * eight mistakes on the page that led to UIG-15: the frame's card clips, so a
+ * list that grew past the fold was simply cut off, with nothing to scroll.
+ *
+ * `collapsed` closes it with the rail, as Peek's did: it narrows to nothing
+ * and fades, in 300ms. What opens and closes the rail stays the app's.
+ */
+export interface ListColumnProps {
+  /** The column's name, in its header. A node for a title that is more than words. */
+  title: ReactNode
+  /** A chevron after the title, as `ContainerHeader` draws it. */
+  chevron?: boolean
+  /** The column's own actions, at the header's right — a `Toolbar` of `ToolbarButton`s, or one `IconButton`. */
+  actions?: ReactNode
+  /** A row between the header and the list that stays put while the list scrolls — a field that adds to the list. */
+  above?: ReactNode
+  /**
+   * The room between rows. `rows` (2px) for a list of one kind of row;
+   * `sections` (4px) for groups with labels and dividers of their own.
+   */
+  spacing?: 'rows' | 'sections'
+  /** Closes the column with the rail: it narrows to nothing and fades. */
+  collapsed?: boolean
+  /** The rows. */
+  children: ReactNode
+  /** Placement only. */
+  className?: string
+}
+
+export function ListColumn({ title, chevron = false, actions, above, spacing = 'rows', collapsed = false, children, className }: ListColumnProps) {
+  return (
+    <div
+      className={cn(
+        // `shrink-0`: the column keeps its 290px beside a main area that grows.
+        'flex shrink-0 flex-col overflow-hidden border-r border-border-subtle transition-[width,opacity] duration-300 ease-in-out',
+        collapsed ? 'w-0 border-r-0 opacity-0' : 'w-[290px] opacity-100',
+        className,
+      )}
+      data-collapsed={collapsed || undefined}
+    >
+      <ContainerHeader title={title} chevron={chevron} actions={actions} />
+      {above}
+      <ScrollArea className="flex-1" contentClassName={cn('flex flex-col px-3 pt-4 pb-3', spacing === 'rows' ? 'gap-0.5' : 'gap-1')}>
+        {children}
+      </ScrollArea>
+    </div>
+  )
+}

package/src/Menu.mdx

@@ -41,7 +41,7 @@ definition either way.
 - 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.
+- A strip of icon actions → **Toolbar**.
 - Who-you-are and where-you-are → **IdentityMenu**, already built on this.
 
 ## How
@@ -76,6 +76,23 @@ the trigger as "close" rather than as a press outside.
 
 <Canvas of={MenuStories.OnACard} />
 
+- **Planned:** one part for the pop-up lists while typing in an editor (UIG-31).
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Enter and Space choose a row, Escape closes it | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and jumps to a row by its first letters | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a menu, and each row a menu item | `role="menu"` or `role="menuitem"` | ✓ |
+| Keeps its own open state, and closes when a row is chosen | `useState` for open |  |
+| Gives focus back to the trigger when it closes | focus code |  |
+
 ## Keys
 
 | Input | What happens |