@estiva-app/ui 0.10.1 → 0.12.0

package/src/EmptyState.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+/**
+ * The two manners the page claims (Katerina, 2026-09-09): `page` draws an
+ * icon over the line, `section` draws the line alone. Where each is
+ * aligned is a class the page names and Chrome shows; jsdom pins the
+ * structure.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { EmptyState } from './EmptyState'
+
+afterEach(cleanup)
+
+describe('EmptyState', () => {
+  it('draws an icon over the line for a page, centred', () => {
+    const { container } = render(<EmptyState message="Nothing here yet." />)
+    expect(container.querySelector('svg')).not.toBeNull()
+    expect(screen.getByText('Nothing here yet.').className).toContain('text-center')
+    // In the middle of its box both ways: it takes a flex column's room and centres in it.
+    expect(container.firstElementChild!.className).toContain('items-center')
+    expect(container.firstElementChild!.className).toContain('justify-center')
+    expect(container.firstElementChild!.className).toContain('flex-1')
+  })
+
+  it('draws the line alone for a section, and nothing else', () => {
+    const { container } = render(<EmptyState scope="section" message="Nothing here yet." />)
+    expect(container.querySelector('svg')).toBeNull()
+    const line = screen.getByText('Nothing here yet.')
+    expect(container.firstElementChild).toBe(line)
+    expect(line.tagName).toBe('P')
+    expect(line.className).not.toContain('text-center')
+  })
+
+  it('keeps the caller icon for a page', () => {
+    const { container } = render(<EmptyState icon={<i data-testid="own" />} message="Nothing here yet." />)
+    expect(container.querySelector('[data-testid="own"]')).not.toBeNull()
+    expect(container.querySelector('svg')).toBeNull()
+  })
+})

package/src/EmptyState.tsx

@@ -3,20 +3,37 @@ import { IconMessage2 } from '@tabler/icons-react'
 import { cn } from './cn'
 
 /**
- * Peek's EmptyState (2026-08-28), verbatim: a 16px icon over a centred line
- * of secondary text. The message is the caller's — a shared component has no
- * words of its own for what is missing.
+ * The place where content will be once there is some, in two manners
+ * (Katerina, 2026-09-09):
+ *
+ * - `page` — the whole page is empty: a 16px icon over a centred line of
+ *   secondary text, **in the middle of its box both ways** (Katerina,
+ *   2026-09-09: it sat near the top). It grows to the room a flex column
+ *   gives it (`flex-1`) and centres inside that; a caller that draws it
+ *   straight into a page hands it the height (`className="h-full"`).
+ *   Peek's EmptyState (2026-08-28) otherwise; the default.
+ * - `section` — one section of a page is empty, and the page has other
+ *   things on it: the line alone, left-aligned, no icon. A section's
+ *   emptiness is a line among the page's content, not a stage of its own.
+ *
+ * The message is the caller's — a shared component has no words of its own
+ * for what is missing.
  */
 export interface EmptyStateProps {
-  /** 16px, stroke 1.5. A speech bubble when absent. */
+  /** 16px, stroke 1.5. A speech bubble when absent. Drawn for a `page` only. */
   icon?: ReactNode
   message: string
+  /** `page` when the whole page is empty; `section` when one part of it is. */
+  scope?: 'page' | 'section'
   className?: string
 }
 
-export function EmptyState({ icon, message, className }: EmptyStateProps) {
+export function EmptyState({ icon, message, scope = 'page', className }: EmptyStateProps) {
+  if (scope === 'section') {
+    return <p className={cn('text-body-2 text-text-secondary', className)}>{message}</p>
+  }
   return (
-    <div className={cn('flex flex-col gap-2 items-center', className)}>
+    <div className={cn('flex flex-1 flex-col items-center justify-center gap-2', className)}>
       <span className="text-text-secondary">{icon ?? <IconMessage2 size={16} stroke={1.5} />}</span>
       <p className="text-body-2 text-text-secondary text-center">{message}</p>
     </div>

package/src/Menu.tsx

@@ -3,6 +3,7 @@ import { IconChevronRight } from '@tabler/icons-react'
 import { Menu as BaseMenu } from '@base-ui/react/menu'
 import { cn } from './cn'
 import { triggerDisabled } from './triggerDisabled'
+import { ScrollArea } from './ScrollArea'
 import { Kbd } from './Kbd'
 import { SectionLabel } from './SectionLabel'
 
@@ -207,10 +208,18 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
                room. Select's 288 was never this component's — the identity
                panel got it by accident once and grew a scrollbar at full
                height. */
-            className={cn('min-w-[180px] max-h-[var(--available-height)] overflow-y-auto outline-none', className)}
+            className={cn('min-w-[180px] outline-none', className)}
             render={<MenuPanel />}
           >
-            <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
+            {/* The height cap sits on the box that scrolls — on the panel it
+                let the box grow to its content and nothing scrolled (measured,
+                2026-09-08) — less the panel's own padding, so the panel still
+                stops where Floating UI said. The padding stays on the panel,
+                where a caller's `className` can change it; the divider rule
+                moves with the rows. A menu that fits draws exactly as before. */}
+            <ScrollArea viewportClassName="max-h-[calc(var(--available-height)_-_1rem)]" contentClassName="flex flex-col [&>[role=separator]]:mx-0">
+              <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
+            </ScrollArea>
           </BaseMenu.Popup>
         </BaseMenu.Positioner>
       </BaseMenu.Portal>

package/src/NavItem.tsx

@@ -45,7 +45,11 @@ export function NavItem({ label, href, count, countLabel, active = false, icon,
       <span className="flex-1 truncate">{label}</span>
       {count ? (
         <WithTooltip label={countLabel ?? `${count} open`}>
-          <span className="shrink-0 font-mono text-caption tabular-nums text-text-muted">{count}</span>
+          {/* A 16px box, centred: the slot is an icon's width, so a number
+              here sits on the same axis as a SectionHeader's action above it
+              — right edges alone left a digit 4px off a 16px icon (Katerina,
+              2026-09-09). A three-digit count grows the box leftwards. */}
+          <span className="min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted">{count}</span>
         </WithTooltip>
       ) : null}
     </a>

package/src/Popover.tsx

@@ -2,6 +2,7 @@ import { useMemo, type ReactElement, type ReactNode, type RefObject } from 'reac
 import { Popover as BasePopover } from '@base-ui/react/popover'
 import { cn } from './cn'
 import { triggerDisabled } from './triggerDisabled'
+import { ScrollArea } from './ScrollArea'
 import { MenuPanel } from './Menu'
 
 /**
@@ -144,10 +145,13 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
              */
             initialFocus={trigger ? undefined : false}
             finalFocus={finalFocus}
-            className={cn('min-w-[180px] max-h-[var(--available-height)] overflow-y-auto outline-none', className)}
+            className={cn('min-w-[180px] outline-none', className)}
             render={<MenuPanel />}
           >
-            {children}
+            {/* As in Menu: the cap on the scrolling box, less the panel's padding; the padding stays on the panel. */}
+            <ScrollArea viewportClassName="max-h-[calc(var(--available-height)_-_1rem)]" contentClassName="flex flex-col [&>[role=separator]]:mx-0">
+              {children}
+            </ScrollArea>
           </BasePopover.Popup>
         </BasePopover.Positioner>
       </BasePopover.Portal>

package/src/PreviewCard.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { PreviewCard as BasePreviewCard } from '@base-ui/react/preview-card'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 import { MenuPanel } from './Menu'
 
 /**
@@ -79,10 +80,12 @@ export function PreviewCard({ content, children, side = 'right', delay = OPEN_DE
           className="z-50 data-[anchor-hidden]:hidden"
         >
           <BasePreviewCard.Popup
-            className={cn('w-[360px] max-h-[min(300px,var(--available-height))] gap-3 overflow-y-auto p-3 outline-none [&>*]:shrink-0', className)}
+            className={cn('w-[360px] p-3 outline-none', className)}
             render={<MenuPanel />}
           >
-            {content}
+            <ScrollArea viewportClassName="max-h-[calc(min(300px,var(--available-height))_-_1.5rem)]" contentClassName="flex flex-col gap-3 [&>*]:shrink-0">
+              {content}
+            </ScrollArea>
           </BasePreviewCard.Popup>
         </BasePreviewCard.Positioner>
       </BasePreviewCard.Portal>

package/src/Reaction.tsx

@@ -65,7 +65,12 @@ export function Reaction({ emoji, count, pressed = false, className, type, ...pr
         'border transition-colors',
         'disabled:cursor-not-allowed disabled:opacity-50',
         pressed
-          ? 'border-accent-primary bg-accent-muted text-accent-primary hover:border-accent-hover'
+          ? /* In the ship theme the accent on its own wash measures 2.70:1
+               (Finding 4), and the count was the thing that vanished
+               (Katerina, 2026-09-08). The number reads in the text colour
+               there; the accent keeps the edge and the fill. Signal keeps
+               Peek's blue-on-wash, which reads. */
+            'border-accent-primary bg-accent-muted text-accent-primary hover:border-accent-hover ship:text-text-primary'
           : 'border-border-default bg-bg-inset text-text-primary hover:border-border-strong hover:bg-bg-hover',
         className,
       )}

package/src/ScrollArea.mdx

@@ -0,0 +1,65 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ScrollAreaStories from './ScrollArea.stories'
+
+<Meta of={ScrollAreaStories} />
+
+# ScrollArea
+
+A region that scrolls without taking width for its scrollbar. The bar is
+drawn over the content and shows while the pointer is over the region or
+the content is moving; nothing moves when it appears.
+
+<Canvas of={ScrollAreaStories.Default} />
+
+## 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.
+- `orientation="horizontal"` for a row wider than its box — a table, a
+  board; `"both"` when a thing can run over either way.
+
+<Canvas of={ScrollAreaStories.Horizontal} />
+
+## When not
+
+- A box that never overflows. A ScrollArea around it changes nothing, and
+  is one more element.
+- The page itself. The browser owns that bar.
+
+## How
+
+```tsx
+import { ScrollArea } from '@estiva-app/ui'
+
+<ScrollArea className="h-[240px]" viewportClassName="p-2">
+  {rows}
+</ScrollArea>
+```
+
+- `className` sizes and places the region; `viewportClassName` styles the
+  scrolling box inside it — padding, gap, the layout of the content.
+- The region needs a height (or a `max-h-*`) to have anything to scroll.
+- The native scrollbar is hidden by Base UI; a native `overflow-y-auto` on
+  the same element would draw a second one.
+- A region keeps the wheel only in an axis it can actually scroll: a list
+  that reaches its end does not hand the wheel to the page behind it, but a
+  sideways table inside a scrolling page passes a wheel *down* through to
+  the page, and a region whose content fits passes everything. Measured in
+  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.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| ↑ ↓ | scroll the viewport when it has focus, as any scrolling box |
+| Page Up / Down, Home, End | as any scrolling box |
+
+## Gaps, stated
+
+- The bar has no arrows and no click-on-track paging; the wheel, the keys
+  and dragging the thumb are the ways to move.
+
+## Props
+
+<Controls of={ScrollAreaStories.Default} />

package/src/ScrollArea.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { ScrollArea } from './ScrollArea'
+
+/** A region that scrolls without taking width for its scrollbar. */
+const meta = {
+  title: 'Layout/ScrollArea',
+  component: ScrollArea,
+  parameters: { controls: { disable: true } },
+  args: { children: null },
+} satisfies Meta<typeof ScrollArea>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const rows = Array.from({ length: 40 }, (_, i) => `Row ${i + 1}`)
+
+/** A list taller than its box. The bar shows while the pointer is over it or the list is moving. */
+export const Default: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <ul className="flex flex-col gap-px">
+        {rows.map((row) => (
+          <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </li>
+        ))}
+      </ul>
+    </ScrollArea>
+  ),
+}
+
+/** Nothing to scroll: the region draws exactly as a plain box would, and no bar. */
+export const Fits: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <ul className="flex flex-col gap-px">
+        {rows.slice(0, 4).map((row) => (
+          <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </li>
+        ))}
+      </ul>
+    </ScrollArea>
+  ),
+}
+
+/** A row wider than its box — a table, a board. */
+export const Horizontal: Story = {
+  render: () => (
+    <ScrollArea orientation="horizontal" className="w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <div className="flex w-max gap-2">
+        {rows.slice(0, 12).map((row) => (
+          <div key={row} className="w-[120px] shrink-0 rounded-md bg-bg-inset px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+}
+
+/** Both ways, with the corner where the two bars would meet. */
+export const Both: Story = {
+  render: () => (
+    <ScrollArea orientation="both" className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <div className="flex w-max flex-col gap-px">
+        {rows.map((row) => (
+          <div key={row} className="w-[480px] rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row} — a line long enough to run past the box
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+}
+
+/** A sideways region inside a scrolling page — a table in a content column. A wheel down over it moves the page; a swipe sideways moves the region. */
+export const SidewaysInsideAPage: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <div className="flex flex-col gap-px">
+        {rows.slice(0, 3).map((row) => (
+          <p key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </p>
+        ))}
+        <ScrollArea orientation="horizontal" className="my-1 rounded-md border border-border-default" viewportClassName="p-2">
+          <div className="flex w-max gap-2">
+            {rows.slice(0, 12).map((row) => (
+              <div key={row} className="w-[120px] shrink-0 rounded-md bg-bg-inset px-2 py-1.5 text-body-2 text-text-primary">
+                {row}
+              </div>
+            ))}
+          </div>
+        </ScrollArea>
+        {rows.slice(3).map((row) => (
+          <p key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </p>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+}

package/src/ScrollArea.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/**
+ * What jsdom can see of the ScrollArea page: the content renders inside the
+ * region, and the region is Base UI's. Whether the bar takes width, and when
+ * it shows, is measured in Chrome (2026-09-08: the viewport keeps its full
+ * width with 40 rows overflowing; the native bar is hidden).
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ScrollArea } from './ScrollArea'
+
+afterEach(cleanup)
+
+describe('ScrollArea', () => {
+  it('draws the content inside a viewport of its own', () => {
+    const { container } = render(
+      <ScrollArea className="h-40">
+        <p>Inside</p>
+      </ScrollArea>,
+    )
+    const inside = screen.getByText('Inside')
+    expect(container.firstElementChild).not.toBe(inside)
+    expect(container.firstElementChild!.contains(inside)).toBe(true)
+    expect(container.firstElementChild!.className).toContain('h-40')
+  })
+
+  it('puts each class prop on its own box: the region, the viewport, the content', () => {
+    const { container } = render(
+      <ScrollArea className="h-40" viewportClassName="max-h-20" contentClassName="p-2">
+        <p>Inside</p>
+      </ScrollArea>,
+    )
+    const region = container.firstElementChild!
+    const content = screen.getByText('Inside').parentElement!
+    const viewport = content.parentElement!
+    expect(region.className).toContain('h-40')
+    expect(viewport.className).toContain('max-h-20')
+    expect(content.className).toContain('p-2')
+    expect(viewport.parentElement).toBe(region)
+  })
+
+  it('keeps a vertical region no wider than itself, and lets a sideways one grow', () => {
+    const v = render(<ScrollArea><p>Inside</p></ScrollArea>)
+    expect((screen.getByText('Inside').parentElement as HTMLElement).style.minWidth).toBe('0px')
+    cleanup()
+    render(<ScrollArea orientation="horizontal"><p>Inside</p></ScrollArea>)
+    expect((screen.getByText('Inside').parentElement as HTMLElement).style.minWidth).toBe('fit-content')
+    void v
+  })
+})
+
+describe('ScrollArea and the page behind it', () => {
+  // Measured in Chrome (2026-09-09, PLAN Finding 40): with an unconditional
+  // `overscroll-contain` the page under a sideways table moved 0px on a
+  // wheel down, 446px without it; with these two classes 400px, and the
+  // table 0. jsdom cannot scroll; it pins that the contain is per axis and
+  // waits for Base UI's overflow attribute rather than being unconditional.
+  it('contains the wheel per axis, and only while that axis overflows', () => {
+    render(<ScrollArea orientation="horizontal"><p>Inside</p></ScrollArea>)
+    const viewport = screen.getByText('Inside').parentElement!.parentElement!
+    expect(viewport.className).toContain('data-[has-overflow-x]:overscroll-x-contain')
+    expect(viewport.className).toContain('data-[has-overflow-y]:overscroll-y-contain')
+    expect(viewport.className).not.toMatch(/(^|\s)overscroll-contain(\s|$)/)
+  })
+})

package/src/ScrollArea.tsx

@@ -0,0 +1,94 @@
+import type { ReactNode } from 'react'
+import { ScrollArea as BaseScrollArea } from '@base-ui/react/scroll-area'
+import { cn } from './cn'
+
+/**
+ * A region that scrolls without taking width for its scrollbar.
+ *
+ * A native scrollbar is part of the layout: the moment content overflows, the
+ * bar takes its width from the content, the text column narrows, and the
+ * right-hand padding looks wider than the left. Katerina saw it in every
+ * scrolling surface of both apps (2026-09-08). Base UI's `ScrollArea` hides
+ * the native bar and draws its own over the content, so nothing moves when
+ * it appears; the bar shows while the pointer is over the region or the
+ * content is moving, and fades otherwise.
+ *
+ * Three boxes, and each class prop lands on one:
+ *
+ * - the **region** (`className`): its size and placement — `h-[240px]`, a
+ *   grid cell, `flex-1 min-h-0`;
+ * - the **viewport** (`viewportClassName`): the box that scrolls — a
+ *   `max-h-*` cap goes here, and nowhere else, because a cap on the region
+ *   lets the viewport grow to its content and nothing scrolls (measured,
+ *   2026-09-08);
+ * - the **content** (`contentClassName`): the box the children sit in — the
+ *   padding, the gap, `flex flex-col`. Base UI watches this box for size
+ *   changes; without it the bar kept showing on Ship's page for overflow that
+ *   was no longer there (measured, 2026-09-09).
+ *
+ * The bar is `border-strong` on nothing, 6px wide, inset 2px from the edge —
+ * the thin scrollbar both apps had styled by hand in their `index.css`, drawn
+ * once here instead.
+ *
+ * `orientation` says which way the region scrolls; a table that is wider
+ * than its box scrolls `horizontal`, a list `vertical` (the default), a board
+ * `both`. A vertical region keeps its content no wider than itself, so a
+ * long label still truncates.
+ */
+export interface ScrollAreaProps {
+  orientation?: 'vertical' | 'horizontal' | 'both'
+  /** On the region: its size and placement. */
+  className?: string
+  /** On the viewport, the box that scrolls: a `max-h-*` cap. */
+  viewportClassName?: string
+  /** On the content, the box the children sit in: padding, gap, layout. */
+  contentClassName?: string
+  children: ReactNode
+}
+
+const BAR = 'flex touch-none select-none rounded-full opacity-0 transition-opacity delay-300 data-[hovering]:opacity-100 data-[hovering]:delay-0 data-[scrolling]:opacity-100 data-[scrolling]:delay-0'
+const THUMB = 'rounded-full bg-border-strong'
+
+export function ScrollArea({ orientation = 'vertical', className, viewportClassName, contentClassName, children }: ScrollAreaProps) {
+  const vertical = orientation !== 'horizontal'
+  const horizontal = orientation !== 'vertical'
+  return (
+    <BaseScrollArea.Root className={cn('relative min-h-0 min-w-0', className)}>
+      {/* `overscroll-contain`, per axis and only while that axis has more to
+          show: a list that reaches its end does not hand the wheel to the page
+          behind it — the rule every popup here has kept since Peek — but a
+          region with nothing to scroll one way passes that way's wheel through.
+          Base UI's viewport is `overflow: scroll` on both axes whatever
+          `orientation` says, so a sideways table is also a vertical scroll box
+          with no room in it, and an unconditional `contain` stopped the page
+          under every table and board (Katerina, 2026-09-09: 0px of page scroll
+          with the pointer over Ship's table, 446px without the line; PLAN
+          Finding 40). `data-has-overflow-x` / `-y` are Base UI's word for
+          "this axis really overflows", written on the viewport as it changes. */}
+      <BaseScrollArea.Viewport
+        className={cn(
+          'h-full w-full outline-none data-[has-overflow-x]:overscroll-x-contain data-[has-overflow-y]:overscroll-y-contain',
+          viewportClassName,
+        )}
+      >
+        {/* Base UI gives the content box `min-width: fit-content`, which is
+            right when the region scrolls sideways and wrong when it does not:
+            a row's `truncate` needs a box no wider than the viewport. */}
+        <BaseScrollArea.Content className={contentClassName} style={horizontal ? undefined : { minWidth: 0 }}>
+          {children}
+        </BaseScrollArea.Content>
+      </BaseScrollArea.Viewport>
+      {vertical && (
+        <BaseScrollArea.Scrollbar orientation="vertical" className={cn(BAR, 'w-1.5 justify-center py-0.5 pr-0.5')}>
+          <BaseScrollArea.Thumb className={cn(THUMB, 'w-full')} />
+        </BaseScrollArea.Scrollbar>
+      )}
+      {horizontal && (
+        <BaseScrollArea.Scrollbar orientation="horizontal" className={cn(BAR, 'h-1.5 flex-col justify-center px-0.5 pb-0.5')}>
+          <BaseScrollArea.Thumb className={cn(THUMB, 'h-full')} />
+        </BaseScrollArea.Scrollbar>
+      )}
+      {vertical && horizontal && <BaseScrollArea.Corner />}
+    </BaseScrollArea.Root>
+  )
+}

package/src/SectionHeader.mdx

@@ -5,23 +5,26 @@ import * as SectionHeaderStories from './SectionHeader.stories'
 
 # SectionHeader
 
-The 32px row a section starts with: a SectionLabel, an optional collapse
-chevron that makes the whole row the toggle, and actions that appear on
-hover as IconButtons with tooltips.
+The 32px row a section starts with: a SectionLabel, and actions that
+appear on hover or focus as IconButtons with tooltips. It is also the
+header of a **CollapsibleSection**, which draws the chevron and makes the
+title the toggle — that is where a section folds.
 
 <Canvas of={SectionHeaderStories.WithActions} />
 
 ## When
 
-- A sidebar or panel section that collapses, or that carries its own
-  actions — add, sort, filter.
+- A sidebar or panel section that carries its own actions — add, sort,
+  filter.
 - `showActions="always"` keeps the actions visible — for touch, or for a
   section whose actions are the point.
 
-<Canvas of={SectionHeaderStories.Collapsible} />
+<Canvas of={SectionHeaderStories.PersistentActions} />
 
 ## When not
 
+- A section that opens and closes → **CollapsibleSection**: the header,
+  the rows, the slide, and a `storageKey` that remembers.
 - A title with no chevron and no actions → **SectionLabel** alone.
 - A heading inside a menu → **MenuSection**.
 - Page-level headings → the `h*` type tokens.
@@ -32,20 +35,26 @@ hover as IconButtons with tooltips.
 import { SectionHeader } from '@estiva-app/ui'
 import { IconPlus } from '@tabler/icons-react'
 
-<SectionHeader
-  title="Sections"
-  chevron
-  isExpanded={expanded}
-  onToggle={() => setExpanded((v) => !v)}
-  actions={[{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: add }]}
-/>
+<SectionHeader title="Sections" actions={[{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: add }]} />
 ```
 
+- `chevron`, `isExpanded` and `onToggle` are CollapsibleSection's to set
+  (decided 2026-09-09: 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`).
 - An action is `{ icon, tooltip, onClick }` — the tooltip doubles as the
-  action's accessible name, and an action's click never also toggles the
-  section.
-- With `chevron`, the whole row is the toggle — no separate hit target to
-  find.
+  action's accessible name. The actions sit beside the title button, not
+  inside it, so a click on one never also toggles the section.
+- `render` swaps the title's element in Base UI's manner; it is how
+  CollapsibleSection makes the title a `Collapsible.Trigger`.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Enter, Space | on the title, with `chevron`: calls `onToggle` |
+| Tab | the title, then each action — the actions show while one has focus |
 
 ## Props