@estiva-app/ui 0.10.1 → 0.12.0

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/Select.tsx

@@ -2,6 +2,7 @@ import { IconCheck, IconChevronDown } from '@tabler/icons-react'
 import { Select as BaseSelect } from '@base-ui/react/select'
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 
 /**
  * Peek's Select (2026-08-28), verbatim, plus what Ship added: an option may
@@ -125,8 +126,13 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
                clamped it — the two numbers `fitMenu` used to compute here. The
                288px is the old `max-h-72`, now a ceiling on that room rather
                than a height applied blind. */
-            className="max-h-[min(288px,var(--available-height))] min-w-[var(--anchor-width)] overflow-y-auto rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
+            className="min-w-[var(--anchor-width)] rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
           >
+            {/* The list scrolls in a ScrollArea: the bar takes no width, so a
+                long list is exactly as wide as a short one (Katerina,
+                2026-09-08). The cap sits on the box that scrolls, less the
+                panel's padding, so 288px stays 288px. */}
+            <ScrollArea viewportClassName="max-h-[calc(min(288px,var(--available-height))_-_0.5rem)]" contentClassName="flex flex-col">
             {options.map((option) => (
               <BaseSelect.Item
                 key={option.value}
@@ -146,6 +152,7 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
                 />
               </BaseSelect.Item>
             ))}
+            </ScrollArea>
           </BaseSelect.Popup>
         </BaseSelect.Positioner>
       </BaseSelect.Portal>

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>
   ),
 }

package/src/Sidebar.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 
 /**
  * The navigation column: 240px, a hairline on its right, the surface
@@ -21,12 +22,14 @@ export function Sidebar({ 'aria-label': ariaLabel = 'Workspace', children, class
   return (
     <nav
       aria-label={ariaLabel}
-      className={cn(
-        'flex w-60 shrink-0 flex-col gap-px overflow-y-auto border-r border-border-default bg-bg-surface px-2.5 py-3',
-        className,
-      )}
+      className={cn('flex w-60 shrink-0 flex-col border-r border-border-default bg-bg-surface', className)}
     >
-      {children}
+      {/* The rows scroll in a ScrollArea: the bar takes no width, so the
+          column's padding reads the same with a long list as with a short
+          one (Katerina, 2026-09-08). The padding and the gap are the box's. */}
+      <ScrollArea className="min-h-0 flex-1" contentClassName="flex flex-col gap-px px-2.5 py-3">
+        {children}
+      </ScrollArea>
     </nav>
   )
 }

package/src/index.ts

@@ -35,6 +35,7 @@ export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
 export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
 export { NavItem, type NavItemProps } from './NavItem'
 export { Popover, type PopoverProps } from './Popover'
+export { ScrollArea, type ScrollAreaProps } from './ScrollArea'
 export { ReactionPicker, type ReactionOption, type ReactionPickerProps } from './ReactionPicker'
 export { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator, type ToolbarProps, type ToolbarButtonProps, type ToolbarInputProps } from './Toolbar'
 export { PreviewCard, type PreviewCardProps } from './PreviewCard'
@@ -48,6 +49,7 @@ export { Property, type PropertyProps } from './Property'
 export { Reaction, type ReactionProps } from './Reaction'
 export { SearchInput, type SearchInputProps } from './SearchInput'
 export { SectionHeader, type SectionAction, type SectionHeaderProps } from './SectionHeader'
+export { CollapsibleSection, type CollapsibleSectionProps } from './CollapsibleSection'
 export { SectionLabel } from './SectionLabel'
 export { Tabs, type TabDef, type TabsProps } from './Tabs'
 export { Toast, ToastProvider, useToast, type ToastOptions, type ToastProps, type ToastType } from './Toast'

package/stories/Choosing.mdx

@@ -68,6 +68,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 |---|---|
 | Label–value rows (a details rail) | **Property** — `row` and `stacked` |
 | A section heading, chevron, hover actions | **SectionHeader** |
+| A group of rows that opens and closes, and stays how you left it | **CollapsibleSection** — `storageKey` remembers |
 | The uppercase micro-label | **SectionLabel** |
 | A hairline | **Divider** |
 | Where am I, and the way back up | **Breadcrumb** |
@@ -78,7 +79,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | You need | Reach for |
 |---|---|
 | Data is on its way | **Skeleton** — shaped like what will arrive |
-| Nothing to show | **EmptyState** — says what would fill it |
+| Nothing to show | **EmptyState** — says what would fill it; `page` when the whole page is empty (icon, centred), `section` when one part of it is (the line alone, left) |
 | It happened, briefly | **Toast**, via `useToast` inside a `ToastProvider` |
 | It happened, and must not be missed | **Toast** with `durationMs: 0` and an action — it floats and stays until dismissed (D21) |
 | The whole surface has something to say | **Banner** — the strip under the top bar, full width; `onDismiss` if the reader closes it rather than the app |