@estiva-app/ui 0.24.0 → 0.24.1

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

@@ -76,6 +76,8 @@ 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.

package/src/MenuItem.mdx

@@ -51,6 +51,8 @@ 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.
@@ -59,6 +61,7 @@ It does these by itself. Write none of them around it.
 |---|---|---|
 | 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
 

package/src/NavItem.mdx

@@ -48,6 +48,9 @@ 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.
@@ -55,6 +58,7 @@ 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
 

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,8 @@ 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.

package/src/PersonTrigger.mdx

@@ -47,7 +47,7 @@ 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
@@ -61,6 +61,7 @@ It does these by itself. Write none of them around it.
 |---|---|---|
 | 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
 

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

@@ -124,6 +124,8 @@ 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.

package/src/Rail.mdx

@@ -52,6 +52,9 @@ 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.

package/src/RailItem.mdx

@@ -45,6 +45,9 @@ 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.
@@ -52,6 +55,7 @@ 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
 

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

@@ -58,6 +58,7 @@ It does these by itself. Write none of them around it.
 |---|---|---|
 | 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
 

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/ScrollArea.mdx

@@ -55,6 +55,9 @@ 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.

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`).
@@ -57,6 +57,9 @@ import { IconPlus } from '@tabler/icons-react'
   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.
@@ -65,6 +68,7 @@ It does these by itself. Write none of them around it.
 |---|---|---|
 | 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
 

package/src/SectionHeader.tsx

@@ -99,7 +99,7 @@ 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).

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,11 @@ 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
 

package/src/Select.mdx

@@ -55,8 +55,7 @@ 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
@@ -64,6 +63,7 @@ import { Select } from '@estiva-app/ui'
 - **`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`.
@@ -81,6 +81,7 @@ It does these by itself. Write none of them around it.
 | 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
 

package/src/Select.test.tsx

@@ -74,6 +74,18 @@ describe('Select', () => {
     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')

package/src/Select.tsx

@@ -56,6 +56,7 @@ export interface SelectProps {
    * looks disabled and will not open, but Tab still reaches it, and the reason
    * shows as its tooltip — a native disabled button cannot be focused, so it
    * could never say why. Takes the place of wrapping it in `WithTooltip`.
+   * Given with `disabled`, the reason wins, as on `Button`.
    */
   disabledReason?: string
   className?: string
@@ -70,7 +71,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
   const selected = options.find((o) => o.value === value)
   // With a reason it is held shut rather than disabled: a disabled trigger is
   // a native `disabled` button, which Tab skips and a tooltip cannot open on.
-  const held = Boolean(disabledReason) && !disabled
+  const held = Boolean(disabledReason)
   const trigger = (
       <BaseSelect.Trigger
         aria-label={ariaLabel}
@@ -96,7 +97,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
           'focus-visible:border-border-focus aria-expanded:border-border-focus',
           'signal:transition-shadow signal:focus-visible:shadow-focus-ring',
           size === 'default' && 'px-3 py-2 text-input-value',
-          size === 'small' && 'h-6 px-2 text-caption',
+          size === 'small' && 'h-6 min-h-6 px-2 text-caption',
           className,
         )}
       >
@@ -116,7 +117,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
         if (!held) onChange(next as string)
       }}
       {...(held ? { open: false, onOpenChange: () => {} } : {})}
-      disabled={disabled}
+      disabled={disabled && !held}
       // Non-modal, as it has always been: the page behind stays scrollable and
       // keeps its scrollbar, so opening a select never shifts the layout.
       modal={false}

package/src/Skeleton.mdx

@@ -40,4 +40,8 @@ import { SkeletonList, SkeletonBar } from '@estiva-app/ui'
 
 ## What it owns
 
-Nothing. It only draws. Clicks and keys are yours.
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Keeps each row's 32px in a scrolling column | `shrink-0` |  |