@estiva-app/ui 0.11.0 → 0.12.1

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

@@ -41,6 +41,12 @@ import { ScrollArea } from '@estiva-app/ui'
 - 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
 

package/src/ScrollArea.stories.tsx

@@ -73,3 +73,32 @@ export const Both: Story = {
     </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

@@ -48,3 +48,18 @@ describe('ScrollArea', () => {
     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

@@ -54,10 +54,23 @@ export function ScrollArea({ orientation = 'vertical', className, viewportClassN
   const horizontal = orientation !== 'vertical'
   return (
     <BaseScrollArea.Root className={cn('relative min-h-0 min-w-0', className)}>
-      {/* `overscroll-contain`: a list that reaches its end does not hand the
-          wheel to the page behind it, which is the rule every popup here has
-          kept since Peek. */}
-      <BaseScrollArea.Viewport className={cn('h-full w-full overscroll-contain outline-none', viewportClassName)}>
+      {/* `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. */}

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
 

package/src/SectionHeader.stories.tsx

@@ -1,15 +1,14 @@
-import { useState } from 'react'
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconPlus, IconSortDescending } from '@tabler/icons-react'
 import { SectionHeader } from './SectionHeader'
 
-/** The 32px row a section starts with. Hover it: the row fills, and its actions appear. */
+/** The 32px row a section starts with. Hover it: the row fills, and its actions appear. A section that folds is CollapsibleSection, whose header this is. */
 const meta = {
   title: 'Navigation/SectionHeader',
   component: SectionHeader,
   decorators: [(Story) => <div className="w-[280px]"><Story /></div>],
-  args: { title: 'Starred', showActions: 'hover' },
-  argTypes: { showActions: { control: 'inline-radio', options: ['hover', 'always'] } },
+  args: { title: 'Section', showActions: 'hover' },
+  argTypes: { showActions: { control: 'inline-radio', options: ['hover', 'always'] }, chevron: { control: false }, isExpanded: { control: false } },
 } satisfies Meta<typeof SectionHeader>
 
 export default meta
@@ -17,30 +16,9 @@ type Story = StoryObj<typeof meta>
 
 export const Plain: Story = {}
 
-/** The chevron makes the whole row the toggle; click it. */
-export const Collapsible: Story = {
-  args: { title: 'Your documents', chevron: true },
-  render: (args) => {
-    const [expanded, setExpanded] = useState(true)
-    return (
-      <div className="flex flex-col gap-1">
-        <SectionHeader {...args} isExpanded={expanded} onToggle={() => setExpanded((v) => !v)} />
-        {expanded &&
-          ['Quarterly plan', 'Reading list'].map((row) => (
-            <div key={row} className="rounded-lg px-2 py-1.5 text-[14px] leading-[140%] text-text-primary hover:bg-bg-hover">
-              {row}
-            </div>
-          ))}
-      </div>
-    )
-  },
-}
-
-/** Peek's add/sort pair, in its original order — revealed on hover, and a click on one never toggles the section. */
+/** Actions beside the title, in the order given — revealed on hover or focus. */
 export const WithActions: Story = {
   args: {
-    title: 'Sections',
-    chevron: true,
     actions: [
       { icon: <IconSortDescending size={16} stroke={1.5} />, tooltip: 'Sort by', onClick: () => {} },
       { icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} },
@@ -48,18 +26,9 @@ export const WithActions: Story = {
   },
 }
 
-/** Actions without the collapse — a fixed section that still offers Add on hover. */
-export const ActionsOnly: Story = {
-  args: {
-    title: 'Pinned',
-    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
-  },
-}
-
 /** The actions held on screen — `showActions="always"` — for a section whose affordance should not hide. */
 export const PersistentActions: Story = {
   args: {
-    title: 'Pinned',
     showActions: 'always',
     actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
   },

package/src/SectionHeader.test.tsx

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+/**
+ * The page's claims: with `chevron` the title is a button that toggles by
+ * click and by key and says its state; an action beside it acts without
+ * toggling; without `chevron` there is no button to find.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { SectionHeader } from './SectionHeader'
+
+afterEach(cleanup)
+
+describe('SectionHeader', () => {
+  it('with a chevron the title is a button that toggles, by click and by key', async () => {
+    const onToggle = vi.fn()
+    render(<SectionHeader title="Section" chevron isExpanded onToggle={onToggle} />)
+    const title = screen.getByRole('button', { name: 'Section' })
+    expect(title.getAttribute('aria-expanded')).toBe('true')
+    await userEvent.click(title)
+    title.focus()
+    await userEvent.keyboard('{Enter}')
+    expect(onToggle).toHaveBeenCalledTimes(2)
+  })
+
+  it('an action beside the title acts, and never toggles', async () => {
+    const onToggle = vi.fn()
+    const add = vi.fn()
+    render(<SectionHeader title="Section" chevron onToggle={onToggle} actions={[{ icon: <i />, tooltip: 'Add', onClick: add }]} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Add' }))
+    expect(add).toHaveBeenCalledTimes(1)
+    expect(onToggle).not.toHaveBeenCalled()
+  })
+
+  it('without a chevron there is no button', () => {
+    render(<SectionHeader title="Section" />)
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByText('Section')).not.toBeNull()
+  })
+})

package/src/SectionHeader.tsx

@@ -1,21 +1,37 @@
-import { useState, type ReactNode } from 'react'
+import type { ReactNode } from 'react'
 import { IconChevronRight } from '@tabler/icons-react'
+import { useRender } from '@base-ui/react/use-render'
 import { cn } from './cn'
 import { IconButton } from './IconButton'
 import { SectionLabel } from './SectionLabel'
 
 /**
  * The 32px row a section starts with (Peek's SectionHeader, 2026-09-01):
- * a SectionLabel, an optional collapse chevron that makes the whole row the
- * toggle, and actions that appear only while the row is hovered, as
+ * a SectionLabel, an optional collapse chevron that makes the title the
+ * toggle, and actions that appear while the row is hovered or focused, as
  * IconButtons with tooltips.
  *
+ * Three things changed on 2026-09-09, for `CollapsibleSection`:
+ *
+ * - **The title is a button when it toggles.** It was a `div` with an
+ *   `onClick`, so the keyboard could not open or close a section at all.
+ *   The button fills the row up to the actions, so the whole row is still
+ *   the hit target; the actions sit beside it rather than inside it,
+ *   because a button inside a button is invalid HTML — and was why every
+ *   action had to stop its click from also toggling.
+ * - **The hover is CSS.** The fill and the actions' reveal were React
+ *   state (`isHovered`), which the README forbids — a mount cannot stay in
+ *   step with a transition. `group-hover` now; the actions are in the row
+ *   at `opacity-0` until hovered or focused, so a keyboard user reaches
+ *   them too.
+ * - **`render`** lets `CollapsibleSection` hand in Base UI's
+ *   `Collapsible.Trigger` as the title button — one header for the
+ *   hand-held section (`isExpanded` / `onToggle`) and the Base UI one,
+ *   with no second click handler.
+ *
  * One API change from Peek's original, safe because no call site used the
  * old shape yet: the two hard-wired action slots (add, sort) became
- * `actions` — the caller brings the icon, the tooltip and the handler; the
- * header owns the hover reveal and stops the click from also toggling the
- * section. Peek's add/sort pair is the WithActions story, in its original
- * order.
+ * `actions` — the caller brings the icon, the tooltip and the handler.
  */
 export interface SectionAction {
   /** 16px, stroke 1.5. */
@@ -26,55 +42,70 @@ export interface SectionAction {
 
 export interface SectionHeaderProps {
   title: string
-  /** Collapsible: draws the chevron and makes the whole row the toggle. */
+  /** Collapsible: draws the chevron and makes the title a button that toggles. */
   chevron?: boolean
   isExpanded?: boolean
   onToggle?: () => void
   /** Right-aligned, in the order given. */
   actions?: SectionAction[]
-  /** `hover` reveals the actions only while the row is hovered; `always` keeps them. */
+  /** `hover` reveals the actions while the row is hovered or focused; `always` keeps them. */
   showActions?: 'hover' | 'always'
+  /**
+   * What the title renders as, in Base UI's manner. A plain button with
+   * `onToggle` by default; `CollapsibleSection` hands in `Collapsible.Trigger`.
+   */
+  render?: useRender.RenderProp
   className?: string
 }
 
-export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, actions, showActions = 'hover', className }: SectionHeaderProps) {
-  const [isHovered, setIsHovered] = useState(false)
+export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, actions, showActions = 'hover', render, className }: SectionHeaderProps) {
+  const titleElement = useRender({
+    render: render ?? (chevron ? <button type="button" onClick={onToggle} aria-expanded={isExpanded} /> : <span />),
+    props: {
+      // `text-left`: a button centres its text. `h-full` and `flex-1`: the
+      // whole row up to the actions is the hit target, as it was when the
+      // row itself carried the click.
+      className: 'flex h-full min-w-0 flex-1 items-center gap-1 text-left',
+      children: (
+        <>
+          {chevron && (
+            <IconChevronRight
+              size={12}
+              stroke={1.5}
+              className={cn('shrink-0 text-text-secondary transition-transform duration-150', isExpanded && 'rotate-90')}
+            />
+          )}
+          <SectionLabel>{title}</SectionLabel>
+        </>
+      ),
+    },
+  })
 
   return (
     <div
       className={cn(
-        'flex h-[32px] items-center justify-between rounded-lg px-2 transition-colors',
-        isHovered && 'bg-bg-hover',
-        chevron && 'cursor-pointer',
+        'group flex h-[32px] 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',
         className,
       )}
-      onClick={chevron ? onToggle : undefined}
-      onMouseEnter={() => setIsHovered(true)}
-      onMouseLeave={() => setIsHovered(false)}
     >
-      <div className="flex shrink-0 items-center gap-1">
-        {chevron && (
-          <IconChevronRight
-            size={12}
-            stroke={1.5}
-            className={cn('text-text-secondary transition-transform duration-150', isExpanded && 'rotate-90')}
-          />
-        )}
-        <SectionLabel>{title}</SectionLabel>
-      </div>
-
-      {(showActions === 'always' || isHovered) && actions && actions.length > 0 && (
-        <div className="flex items-center gap-1">
+      {titleElement}
+      {actions && actions.length > 0 && (
+        <div
+          // `-mr-1`: an IconButton is 24px around a 16px icon, so at the row's
+          // `px-2` its icon ended 12px from the edge while a NavItem's number
+          // ends 8px from it; pulled 4px, the icon and the number share a
+          // right edge (Katerina, 2026-09-09; measured 4px off, then 0).
+          className={cn(
+            '-mr-1 flex shrink-0 items-center gap-1',
+            showActions === 'hover' && 'opacity-0 transition-opacity focus-within:opacity-100 group-hover:opacity-100',
+          )}
+        >
           {actions.map((action) => (
-            <IconButton
-              key={action.tooltip}
-              tooltip={action.tooltip}
-              aria-label={action.tooltip}
-              onClick={(event) => {
-                event.stopPropagation()
-                action.onClick()
-              }}
-            >
+            <IconButton key={action.tooltip} tooltip={action.tooltip} aria-label={action.tooltip} onClick={action.onClick}>
               {action.icon}
             </IconButton>
           ))}

package/src/Sidebar.mdx

@@ -16,8 +16,10 @@ the caller's — this is the shell.
 - The structured frame's navigation (AppShell's `solid` variant), filled
   with **NavItem** rows — the sidebar pairs with the solid TopBar, as the
   Rail pairs with the floating one.
-- A labelled group inside it: a **SectionLabel** in a 32px `px-2` row
-  above its rows (the Composed story shows the idiom).
+- A labelled group inside it, of two kinds (the Composed story shows
+  both): one the reader can fold away and that stays how they left it —
+  a **CollapsibleSection** — and one that stays open, a **SectionHeader**
+  over its rows.
 - It scrolls on its own — a long list never scrolls the frame away.
 
 <Canvas of={SidebarStories.Scrolls} />
@@ -33,14 +35,15 @@ the caller's — this is the shell.
 ## How
 
 ```tsx
-import { Sidebar, NavItem, SectionLabel } from '@estiva-app/ui'
+import { Sidebar, NavItem, CollapsibleSection, SectionHeader } from '@estiva-app/ui'
 
 <Sidebar>
   <NavItem href="/documents" label="Documents" active />
-  <div className="mt-2 flex h-8 shrink-0 items-center px-2">
-    <SectionLabel>Collections</SectionLabel>
-  </div>
-  <NavItem href="/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
+  <CollapsibleSection title="Collections" storageKey="app.sidebar.collections" className="mt-2 shrink-0" contentClassName="gap-px">
+    <NavItem href="/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
+  </CollapsibleSection>
+  <SectionHeader title="Pinned" className="mt-2 shrink-0" />
+  <NavItem href="/documents/3" label="Reading list" />
 </Sidebar>
 ```
 
@@ -48,9 +51,10 @@ import { Sidebar, NavItem, SectionLabel } from '@estiva-app/ui'
 the page.** Keep NavItem's rule: a thin wrapper computes `active` from the
 location, intercepts the click and navigates in place — see **NavItem**.
 
-Anything you place directly in the column needs `shrink-0` (the heading
-row above carries it): the column scrolls on overflow, and a flex child
-without it gets compressed instead — rows must keep their height.
+Anything you place directly in the column needs `shrink-0` (both headings
+above take it in `className`):
+the column scrolls on overflow, and a flex child without it gets
+compressed instead — rows must keep their height.
 
 It is a `nav` region — pass `aria-label` when "Workspace" is not the
 right name for what it navigates.

package/src/Sidebar.stories.tsx

@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSquareRounded } from '@tabler/icons-react'
+import { CollapsibleSection } from './CollapsibleSection'
 import { NavItem } from './NavItem'
-import { SectionLabel } from './SectionLabel'
+import { SectionHeader } from './SectionHeader'
 import { Sidebar } from './Sidebar'
 
 const placeholder = <IconSquareRounded size={16} stroke={1.5} />
@@ -18,7 +19,7 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-/** Entries, then a labelled group — the heading is a SectionLabel in a 32px row. */
+/** Entries, then two kinds of group: one that folds (a CollapsibleSection) and one that stays open (a SectionHeader over its rows). `mt-2` between groups, `shrink-0` so the column scrolls rather than squashes. */
 export const Composed: Story = {
   // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
   // the count chip is muted text, 3.06:1 on the active row in signal (AA 4.5:1).
@@ -27,17 +28,19 @@ export const Composed: Story = {
     <Sidebar {...args}>
       <NavItem href="#" label="Item one" icon={placeholder} count={18} countLabel="18 open" active />
       <NavItem href="#" label="Item two" icon={placeholder} count={5} countLabel="5 active" />
-      <div className="mt-2 flex h-8 shrink-0 items-center px-2">
-        <SectionLabel>Group</SectionLabel>
-      </div>
-      <NavItem href="#" label="Item three" count={7} countLabel="7 open" />
-      <NavItem href="#" label="Item four" count={2} countLabel="2 open" />
-      <NavItem href="#" label="Item five" />
+      <CollapsibleSection title="Group one" className="mt-2 shrink-0" contentClassName="gap-px">
+        <NavItem href="#" label="Item three" count={7} countLabel="7 open" />
+        <NavItem href="#" label="Item four" count={2} countLabel="2 open" />
+        <NavItem href="#" label="Item five" />
+      </CollapsibleSection>
+      <SectionHeader title="Group two" className="mt-2 shrink-0" />
+      <NavItem href="#" label="Item six" icon={placeholder} />
+      <NavItem href="#" label="Item seven" icon={placeholder} />
     </Sidebar>
   ),
 }
 
-/** The column scrolls on its own — a long list never scrolls the frame away. */
+/** The column scrolls on its own — a long group never scrolls the frame away. */
 export const Scrolls: Story = {
   // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
   // the count chips are muted text, 3.78:1 on --bg-surface in signal (AA 4.5:1).
@@ -45,12 +48,11 @@ export const Scrolls: Story = {
   render: (args) => (
     <Sidebar {...args}>
       <NavItem href="#" label="Item one" icon={placeholder} count={18} countLabel="18 open" />
-      <div className="mt-2 flex h-8 shrink-0 items-center px-2">
-        <SectionLabel>Group</SectionLabel>
-      </div>
-      {Array.from({ length: 40 }, (_, i) => (
-        <NavItem key={i} href="#" label={`Item ${i + 2}`} active={i === 2} count={((i * 7) % 9) + 1} countLabel={`${((i * 7) % 9) + 1} open`} />
-      ))}
+      <CollapsibleSection title="Group" className="mt-2 shrink-0" contentClassName="gap-px">
+        {Array.from({ length: 40 }, (_, i) => (
+          <NavItem key={i} href="#" label={`Item ${i + 2}`} active={i === 2} count={((i * 7) % 9) + 1} countLabel={`${((i * 7) % 9) + 1} open`} />
+        ))}
+      </CollapsibleSection>
     </Sidebar>
   ),
 }