@estiva-app/ui 0.23.0 → 0.24.1

package/src/MenuItem.mdx

@@ -25,8 +25,9 @@ other two), `destructive` in the error colour, `selected` as the fill.
 
 ## When not
 
-- Outside a menu — it renders `role="menuitem"` and belongs inside a
-  `role="menu"` container.
+- A single action that is not a row in a list → **Button**. Outside a
+  **Menu**, MenuItem is a plain button with a row's look, so a row-shaped
+  action at the top of a list — "Add members" — is fine.
 - Picking a form value → **Select**'s own options.
 - A row that toggles a checkbox → not a menu at all; see the Menu page.
 
@@ -50,6 +51,18 @@ import { IconPencil } from '@tabler/icons-react'
 - A destructive row's `leading` icon takes the error colour itself
   (`text-error-default`) — the row colours only its label.
 
+- **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 |
+|---|---|---|
+| Is a row of its Menu: the Menu highlights it, walks to it with the arrow keys, and closes when it is chosen | a highlight or a key handler on the row |  |
+| Opens its `submenu` with → and closes it with ← | a submenu of your own |  |
+| Keeps its row's height in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={MenuItemStories.Default} />

package/src/NavItem.mdx

@@ -48,6 +48,18 @@ import { NavItem } from '@estiva-app/ui'
   anchor prop passes through.
 - The label truncates; the count never gives up its width.
 
+- A row is 32px tall, 8px in on each side, 8px between the icon and the label,
+  the label 14px regular, 6px corners.
+
+## 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 |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+| Keeps its 32px in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={NavItemStories.Default} />

package/src/Person.mdx

@@ -12,6 +12,7 @@ and name is one rule, 8px, wherever a person appears.
 
 ## When
 
+- **The name takes the size of the text around it**; `size` sets the face.
 - A person named inline: an assignee, an author, a participant, a value in
   a property row.
 - Someone with no published name shows the `fallback` — an em dash by
@@ -39,6 +40,12 @@ import { Person } from '@estiva-app/ui'
   and words are always set together (the Sizes story shows the pairings).
 - The name truncates; give the container `min-w-0` room to let it.
 
+- **Planned:** a Byline part — face · name · time — in migration stage 7.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PersonStories.Named} />

package/src/PersonTrigger.mdx

@@ -47,12 +47,22 @@ import { Menu, PersonTrigger } from '@estiva-app/ui'
 - **The accessible name comes from the person, in both shapes.** The row is
   named by its visible name, and the `compact` face — which has no visible
   text — takes the same name through an `aria-label` of its own, so nothing
-  is owed. Until 2026-09-08 that face announced **"AD"**: the initials, read
+  is owed. Without it that face would announce **"AD"**: the initials, read
   as text. Pass an `aria-label` only to name what it *opens* rather than who
   it shows; `IdentityMenu`'s compact shape says "Account menu".
 - It is a native `<button>` on Base UI's Button: it takes a `ref` and every
   native button prop.
 
+## 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 |
+|---|---|---|
+| Is a button: Tab reaches it, Enter and Space call your `onClick` | a clickable `<div>` |  |
+| Names itself from the person's name, and says whether what it opens is open (`open`) | `aria-label` or `aria-expanded` |  |
+| Keeps its 32px in a scrolling column | `shrink-0` |  |
+
 ## Keys
 
 | Key | Does |

package/src/PersonTrigger.tsx

@@ -65,7 +65,7 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
       aria-haspopup="menu"
       aria-expanded={open}
       className={cn(
-        'flex h-8 cursor-pointer items-center gap-1.5 rounded-md pl-1.5 pr-1.5 text-body-2 text-text-primary transition-colors hover:bg-bg-hover',
+        'flex h-8 min-h-8 cursor-pointer items-center gap-1.5 rounded-md pl-1.5 pr-1.5 text-body-2 text-text-primary transition-colors hover:bg-bg-hover',
         open && 'bg-bg-hover',
         // Under a `Menu` the open state is Base UI's, not a prop: the trigger
         // carries `data-popup-open` while its menu is up, and sets its own

package/src/Popover.mdx

@@ -83,7 +83,15 @@ so it is the one case the caller drives:
   open={selectionRect !== null}
   onOpenChange={(open) => !open && setSelectionRect(null)}
   ariaLabel="Formatting"
+  side="top"
+  contentClassName="p-1"
 >
+  <Toolbar aria-label="Formatting">
+    <ToolbarButton aria-label="Bold" tooltip="Bold" onClick={bold}>
+      <IconBold size={16} stroke={1.5} />
+    </ToolbarButton>
+  </Toolbar>
+</Popover>
 ```
 
 - **`anchor`** takes an element or a rect. A new rect moves the panel, so
@@ -116,6 +124,21 @@ something belongs on a `trigger`.
 
 <Canvas of={PopoverStories.FlippedForRoom} />
 
+- **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, and flips side when there is no room | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Escape closes it | a key listener on the page | ✓ |
+| Moves focus in when it opens, and back to the trigger when it closes | focus code |  |
+| Keeps its own open state | `useState` for open — unless you must know it (`open` / `onOpenChange`) |  |
+
 ## Keys
 
 | Input | What happens |

package/src/PreviewCard.mdx

@@ -45,7 +45,7 @@ pointer never sees it.
 import { PreviewCard } from '@estiva-app/ui'
 
 <PreviewCard content={<ItemDetail id={row.id} />} wrapperClassName="block w-full">
-  <ListRow …/>
+  <ListRow item={row} />
 </PreviewCard>
 ```
 
@@ -57,9 +57,12 @@ import { PreviewCard } from '@estiva-app/ui'
 - **It prefers the right of the trigger and flips** when that side has no room,
   staying 12px from the trigger and 8px clear of every screen edge. `side`
   changes the preference, not the promise.
-- **Width, padding and height are yours** through `className`. The default is
-  360px wide, capped at 300px or the room available, whichever is smaller — a
-  preview of one kind of thing is not the size of a preview of another.
+- **Width is yours** through `className`; **padding and rhythm** through
+  `contentClassName`. The default is 360px wide, 12px of padding, capped at
+  300px or the room available, whichever is smaller — a preview of one kind of
+  thing is not the size of a preview of another.
+- The padding sits inside the scrolling box, as in `Popover`, so the
+  scrollbar hugs the card's edge: its thumb 3px from it, like every panel's.
 - The trigger wrapper is `inline-flex`; a full-width row wants
   `wrapperClassName="block w-full"`.
 
@@ -82,6 +85,18 @@ lands.
 
 <Canvas of={PreviewCardStories.Loading} />
 
+## 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 | ✓ |
+| Opens after the pointer rests, and stays up while the pointer moves into it | a hover timer |  |
+| Closes on Escape | a key handler |  |
+
 ## Keys
 
 There is no keyboard trigger, by design — see above.

package/src/PreviewCard.tsx

@@ -35,8 +35,15 @@ export interface PreviewCardProps {
   delay?: number
   /** After the pointer leaves, in ms — the grace that lets you cross the gap into the card. */
   closeDelay?: number
-  /** On the card's surface: its width, its padding, a max height. */
+  /** On the card's surface: its width. */
   className?: string
+  /**
+   * On the scrolling content: its padding (default 12px) and rhythm. The
+   * padding sits inside the scrolling box, as in `Popover`, so the scrollbar
+   * hugs the card's edge — its thumb 3px from it, like every panel's
+   * (Katerina, 19 September; it sat 12px in, behind the card's padding).
+   */
+  contentClassName?: string
   /** Extra classes on the trigger wrapper — e.g. `block w-full` for a row. */
   wrapperClassName?: string
 }
@@ -58,7 +65,7 @@ const OPEN_DELAY = 350
  *  here the card can be reached, so it can. */
 const CLOSE_DELAY = 200
 
-export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, wrapperClassName }: PreviewCardProps) {
+export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, contentClassName, wrapperClassName }: PreviewCardProps) {
   return (
     <BasePreviewCard.Root>
       {/* The part renders an `<a>` by default, which a row is not; `render`
@@ -80,10 +87,10 @@ export function PreviewCard({ content, children, side = 'right', delay = OPEN_DE
           className="z-50 data-[anchor-hidden]:hidden"
         >
           <BasePreviewCard.Popup
-            className={cn('w-[360px] p-3 outline-none', className)}
+            className={cn('w-[360px] p-0 outline-none', className)}
             render={<MenuPanel />}
           >
-            <ScrollArea viewportClassName="max-h-[calc(min(300px,var(--available-height))_-_1.5rem)]" contentClassName="flex flex-col gap-3">
+            <ScrollArea viewportClassName="max-h-[min(300px,var(--available-height))]" contentClassName={cn('flex flex-col gap-3 p-3', contentClassName)}>
               {content}
             </ScrollArea>
           </BasePreviewCard.Popup>

package/src/ProgressBar.mdx

@@ -42,6 +42,14 @@ import { ProgressBar } from '@estiva-app/ui'
   of the button's.
 - `className` is for placement: a width, a margin, `flex-1` in a row.
 
+## 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 progress bar, with its value | `role="progressbar"` or `aria-valuenow` | ✓ |
+
 ## Props
 
 <Controls of={ProgressBarStories.Default} />

package/src/Property.mdx

@@ -54,6 +54,10 @@ WithControls story shows the pairings).
   a child of the row or the column: a control with `flex-1` still fills the
   row, and two values still sit the row's gap apart.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PropertyStories.Row} />

package/src/Rail.mdx

@@ -25,7 +25,7 @@ nothing else: **RailItem** is the tile, and where a tile goes is the app's.
   needs more than a word needs a row.
 - More entries than fit down a screen → fewer entries. The rail does not
   scroll, on purpose.
-- A strip of *actions* rather than places → a toolbar of **IconButton**s.
+- A strip of *actions* rather than places → **Toolbar**.
 
 <Canvas of={RailStories.ManyItems} />
 
@@ -52,6 +52,17 @@ import { Rail, RailItem } from '@estiva-app/ui'
 
 <Canvas of={RailStories.OneItem} />
 
+- The column is 64px wide, 12px from the top and bottom, 8px at the sides,
+  8px between tiles.
+
+## 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 |
+|---|---|---|
+| Is a navigation, named "Navigation" unless you name it | `<nav>` or `aria-label` |  |
+
 ## Keys
 
 The rail has no keyboard of its own: its tiles are links, and Tab walks them in

package/src/RailItem.mdx

@@ -45,6 +45,18 @@ import { Rail, RailItem } from '@estiva-app/ui'
   click, navigate.
 - Icons are 16px at stroke 1.5.
 
+- A tile is 64px wide and 48px tall: the 16px icon in its 32px square, over its
+  9px label.
+
+## 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 |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+| Keeps its 48px in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={RailItemStories.Default} />

package/src/RailItem.tsx

@@ -27,7 +27,7 @@ export function RailItem({ href, icon, label, active = false, className, ...prop
     <a
       href={href}
       aria-current={active ? 'page' : undefined}
-      className={cn('group flex w-full shrink-0 flex-col items-center gap-0.5 px-2 py-0.5', className)}
+      className={cn('group flex h-12 w-full shrink-0 flex-col items-center gap-0.5 px-2 py-0.5', className)}
       {...props}
     >
       <div

package/src/Reaction.mdx

@@ -50,6 +50,16 @@ import { Reaction } from '@estiva-app/ui'
   another client can change the count.
 - `disabled` takes it out of the Tab order and ignores presses.
 
+## 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 |
+|---|---|---|
+| Is a toggle: pressed or not, and says so to assistive technology | `aria-pressed` |  |
+| Presses on Enter and Space; Tab skips it while disabled | a key handler |  |
+| Keeps its 24px in a scrolling column | `shrink-0` |  |
+
 ## Keys
 
 | Key | What happens |

package/src/Reaction.tsx

@@ -70,7 +70,7 @@ export function Reaction({ emoji, count, pressed = false, className, ...props }:
       className={cn(
         // Chip's pill at a control's height, so a reaction and a status chip
         // read as the same family — 24px matches Button `small`.
-        'inline-flex h-6 items-center justify-center gap-1.5 rounded-full px-2',
+        'inline-flex h-6 min-h-6 items-center justify-center gap-1.5 rounded-full px-2',
         'border transition-colors',
         'disabled:cursor-not-allowed disabled:opacity-50',
         pressed

package/src/ReactionPicker.mdx

@@ -68,6 +68,14 @@ and, when it is yours, the accent fill. The picker asks; the pill answers.
 
 <Canvas of={ReactionPickerStories.AndWhatItProduces} />
 
+## 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 Toolbar owns: one Tab stop, arrow keys between the reactions, wrapping at the ends | a key handler, or `tabIndex` on each reaction |  |
+
 ## Keys
 
 | Input | What happens |

package/src/ScrollArea.mdx

@@ -13,8 +13,10 @@ the content is moving; nothing moves when it appears.
 
 ## When
 
-- Any box that can hold more than fits: a menu or a dropdown list, a panel,
-  a sidebar, the page's content column, a rail.
+- Any box that can hold more than fits — **a list that grows with its data
+  counts, even when today's data fits**: a menu or a dropdown list, a panel, a
+  sidebar, the page's content column. Not a rail: a rail does not scroll, on
+  purpose.
 - `orientation="horizontal"` for a row wider than its box — a table, a
   board; `"both"` when a thing can run over either way.
 
@@ -53,6 +55,18 @@ import { ScrollArea } from '@estiva-app/ui'
   Chrome: wheel down over a sideways region inside a page, the page moves
   and the region does not; a sideways swipe, the other way round.
 
+- Text inside can look a touch lighter than outside: that is Chrome drawing a
+  scrolling layer, not a colour. Nothing to fix.
+
+## 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 |
+|---|---|---|
+| Scrolls with our scrollbar | `overflow-auto` or `overflow-scroll` | ✓ |
+| Scrolls with the keyboard when it has focus, like any scrolling box | key handlers |  |
+
 ## Keys
 
 | Key | Does |

package/src/SearchInput.mdx

@@ -38,6 +38,15 @@ import { SearchInput } from '@estiva-app/ui'
   and this usually stands alone in a top bar rather than in a `Field`.
   Inside one, the label names it and you add nothing.
 
+## 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 |
+|---|---|---|
+| Inside a `Field`, takes its name from the Field's label | an `id` / `htmlFor` pair |  |
+| Shows its focus ring while anything inside it has focus | a focus style of your own |  |
+
 ## Props
 
 <Controls of={SearchInputStories.Default} />

package/src/SectionHeader.mdx

@@ -39,7 +39,7 @@ import { IconPlus } from '@tabler/icons-react'
 ```
 
 - `chevron`, `isExpanded` and `onToggle` are CollapsibleSection's to set
-  (decided 2026-09-09: one component folds, and it is that one). With
+  (one component folds, and it is that one). With
   them, the title is a button that fills the row up to the actions — the
   whole row is the hit target, the keyboard can toggle it, and it says its
   state (`aria-expanded`).
@@ -53,6 +53,23 @@ import { IconPlus } from '@tabler/icons-react'
 - `render` swaps the title's element in Base UI's manner; it is how
   CollapsibleSection makes the title a `Collapsible.Trigger`.
 
+- `hover="none"` keeps the row still under the pointer: for a heading whose
+  actions are always shown (`showActions="always"`), where the buttons light up
+  on their own. The default, `fill`, lights a row that toggles or has actions.
+
+- The row is 32px tall, 8px in on each side, 4px between the title and the
+  actions, with 8px corners.
+
+## 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 `chevron`, its title is a button that calls `onToggle` on a click, Enter or Space, and says whether it is open | a button of your own, or `aria-expanded` |  |
+| Shows its actions while one of them has focus | a focus style of your own |  |
+| Keeps its 32px in a scrolling column | `shrink-0` |  |
+
 ## Keys
 
 | Key | Does |

package/src/SectionHeader.stories.tsx

@@ -35,6 +35,15 @@ export const PersistentActions: Story = {
   },
 }
 
+/** `hover="none"`: actions always shown, and the row stays still under the pointer — only the buttons light up. */
+export const StillOnHover: Story = {
+  args: {
+    showActions: 'always',
+    hover: 'none',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
+  },
+}
+
 /** A count beside the title, held on screen while the actions come and go. */
 export const WithTrailing: Story = {
   args: {

package/src/SectionHeader.test.tsx

@@ -23,6 +23,15 @@ describe('SectionHeader', () => {
     expect(onToggle).toHaveBeenCalledTimes(2)
   })
 
+  it('fills under the pointer when it does something, and hover="none" keeps it still', () => {
+    const actions = [{ icon: <i />, tooltip: 'Add', onClick: () => {} }]
+    const lit = render(<SectionHeader title="Section" actions={actions} />)
+    expect((lit.container.firstElementChild as HTMLElement).className).toContain('hover:bg-bg-hover')
+    cleanup()
+    const still = render(<SectionHeader title="Section" actions={actions} hover="none" />)
+    expect((still.container.firstElementChild as HTMLElement).className).not.toContain('hover:bg-bg-hover')
+  })
+
   it('an action beside the title acts, and never toggles', async () => {
     const onToggle = vi.fn()
     const add = vi.fn()

package/src/SectionHeader.tsx

@@ -59,6 +59,12 @@ export interface SectionHeaderProps {
   actions?: SectionAction[]
   /** `hover` reveals the actions while the row is hovered or focused; `always` keeps them. */
   showActions?: 'hover' | 'always'
+  /**
+   * `fill` lights the row under the pointer when it does something (a toggle,
+   * actions); `none` keeps it still — a heading whose actions are always shown,
+   * where the buttons light up on their own (UIG-14, Katerina, 19 September).
+   */
+  hover?: 'fill' | 'none'
   /**
    * What the title renders as, in Base UI's manner. A plain button with
    * `onToggle` by default; `CollapsibleSection` hands in `Collapsible.Trigger`.
@@ -67,7 +73,7 @@ export interface SectionHeaderProps {
   className?: string
 }
 
-export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', render, className }: SectionHeaderProps) {
+export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', hover = 'fill', render, className }: SectionHeaderProps) {
   const titleElement = useRender({
     render: render ?? (chevron ? <button type="button" onClick={onToggle} aria-expanded={isExpanded} /> : <span />),
     props: {
@@ -93,11 +99,11 @@ export function SectionHeader({ title, chevron = false, isExpanded = true, onTog
   return (
     <div
       className={cn(
-        'group flex h-[32px] items-center gap-1 rounded-lg px-2 transition-colors',
+        'group flex h-[32px] shrink-0 items-center gap-1 rounded-lg px-2 transition-colors',
         // The fill says "this does something": a row with a toggle or actions
         // lights up, a fixed heading over rows does not (2026-09-09, the
         // Sidebar's fixed group).
-        (chevron || (actions && actions.length > 0)) && 'hover:bg-bg-hover',
+        hover === 'fill' && (chevron || (actions && actions.length > 0)) && 'hover:bg-bg-hover',
         className,
       )}
     >

package/src/SectionLabel.mdx

@@ -14,6 +14,7 @@ how).
 
 ## When
 
+- **It is a bare label**: the row it sits in, and the room around it, are yours.
 - Titling a group of rows in a sidebar, a panel, a rail.
 - Inside a menu it arrives via **MenuSection** — don't place it there by
   hand.
@@ -35,8 +36,15 @@ import { SectionLabel } from '@estiva-app/ui'
 
 It is a bare span: the caller owns the row it sits in and the spacing
 around it. Read it `tone="secondary"` where it labels rather than leads — menu
-headings and the command palette's groups do (Katerina, 2026-09-01). A colour
-passed in `className` is refused by the lint (UIG-9).
+headings and the command palette's groups do. A colour
+passed in `className` is refused by the lint.
+
+- Import it — never copy its classes. A copied class list drifts the first time
+  the label changes.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
 
 ## Props
 

package/src/Select.mdx

@@ -29,8 +29,10 @@ corners and scrolling panels.
   things.
 - Several values → **ChipInput**.
 - Switching views of one thing → **Tabs**.
-- `disabled` explains nothing by itself — wrap it in a **WithTooltip**
-  that gives the reason.
+- `disabled` explains nothing by itself — give it `disabledReason`, which says
+  why and keeps it reachable by Tab. Busy for a moment while an action runs
+  needs no reason.
+- Ticking several on and off in a list → **Checkbox** with `row`.
 
 ## How
 
@@ -53,16 +55,34 @@ import { Select } from '@estiva-app/ui'
 - **The list hangs under the trigger**, 4px below it, and flips above when
   the room below is worse. Base UI would rather lay it *over* the trigger
   with the chosen option covering the trigger's own text, the way macOS
-  does; that is off (Katerina, D24) because every Select in both apps opens
-  below one today.
+  does; that is off, so every Select opens below its trigger.
 - It caps at 288px, or at the room the screen actually has, whichever is
   smaller — and scrolls inside that. Measured in a bottom-right corner:
   the list flips above the trigger, slides left to stay on screen, and
   stands at its full 288.
+- **`disabledReason="Read only"`** holds it shut and keeps it reachable by Tab,
+  showing the reason on hover and on keyboard focus — as `Button` does. Plain
+  `disabled` is a native disabled control: Tab skips it, so it cannot say why.
+  Given both, the reason wins, as on `Button`.
 - **The trigger is a `combobox`, not a `button`.** That is the ARIA pattern
   for this control and Base UI's doing; a test looking for it by role has
   to ask for `combobox`.
 
+## 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, and hides when its trigger scrolls out of sight | 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 pick, Escape and Tab close | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and jumps to an option by its first letters | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a list of options | `role="listbox"` or `role="option"` | ✓ |
+| Keeps the highlighted option in view, and gives focus back to the trigger | scroll or focus code |  |
+| Keeps its height in a scrolling column | `shrink-0` |  |
+
 ## Keys
 
 | Input | What happens |

package/src/Select.stories.tsx

@@ -89,9 +89,12 @@ export const InAField: Story = {
   ),
 }
 
-/** Unavailable — the same disabled treatment as every other control. Say why, with a tooltip around it. */
+/** Unavailable — the same disabled treatment as every other control. To say why, `WithAReason`. */
 export const Disabled: Story = { render: (args) => <Demo {...args} initial="done" disabled /> }
 
+/** `disabledReason`: it looks disabled and will not open, but Tab reaches it and the reason shows on hover and on focus. */
+export const WithAReason: Story = { render: (args) => <Demo {...args} initial="done" disabledReason="Read only: you are a guest here" /> }
+
 /** Longer labels than the trigger is wide: the trigger truncates rather than growing; the menu takes the trigger's width as a minimum and grows past it. */
 export const LongLabels: Story = {
   render: (args) => (

package/src/Select.test.tsx

@@ -57,6 +57,35 @@ describe('Select', () => {
     expect(trigger.getAttribute('aria-expanded')).toBe('false')
   })
 
+  it('disabledReason: held shut, reachable by Tab, and it says why', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Select value="todo" onChange={onChange} options={STATUSES} ariaLabel="Status" disabledReason="Read only: you are a guest" />)
+    const trigger = screen.getByRole('combobox', { name: 'Status' })
+    expect(trigger.getAttribute('aria-disabled')).toBe('true')
+    expect(trigger.hasAttribute('disabled')).toBe(false)
+    await user.click(trigger)
+    await user.keyboard('{ArrowDown}{Enter}')
+    expect(screen.queryByRole('listbox')).toBeNull()
+    expect(onChange).not.toHaveBeenCalled()
+    await user.tab()
+    await user.tab({ shift: true })
+    expect(document.activeElement).toBe(trigger)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Read only: you are a guest')
+  })
+
+  // F2: as on Button, a reason wins over plain `disabled` — or the reason is never seen.
+  it('disabled with a reason: the reason wins', async () => {
+    const user = userEvent.setup()
+    render(<Select value="todo" onChange={vi.fn()} options={STATUSES} ariaLabel="Status" disabled disabledReason="Read only: you are a guest" />)
+    const trigger = screen.getByRole('combobox', { name: 'Status' })
+    expect(trigger.getAttribute('aria-disabled')).toBe('true')
+    expect(trigger.hasAttribute('disabled')).toBe(false)
+    await user.tab()
+    expect(document.activeElement).toBe(trigger)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Read only: you are a guest')
+  })
+
   it('shows the placeholder when nothing matches', () => {
     render(<Controlled initial="" placeholder="Choose" />)
     expect(screen.getByRole('combobox', { name: 'Status' }).textContent).toContain('Choose')