@estiva-app/ui 0.10.1 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/AppShell.tsx

@@ -76,6 +76,11 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
         {nav}
         <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           {banner}
+          {/* Not a ScrollArea: the apps' pages scroll inside themselves (Ship's
+              detail columns are `h-full` grids with their own regions), and a
+              region here kept a bar on Ship's page for overflow that was not
+              there (2026-09-09). A page that does scroll here gets its region
+              where it scrolls. */}
           <main className="min-w-0 flex-1 overflow-y-auto">{children}</main>
         </div>
       </div>

package/src/Breadcrumb.mdx

@@ -22,6 +22,12 @@ between them, and a tooltip on any crumb that has had to truncate.
 
 <Canvas of={BreadcrumbStories.LongName} />
 
+- `icon` draws a 16px icon before a crumb — what kind of place it is, so
+  a container's name is not read as an item's. Decorative: the trail is
+  still read as its labels.
+
+<Canvas of={BreadcrumbStories.WithAnIcon} />
+
 ## When not
 
 - Switching between sibling views of one thing → **Tabs**.

package/src/Breadcrumb.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
 import { Breadcrumb } from './Breadcrumb'
 
 /** A trail of places, ending where you are — or on a mono ref. */
@@ -43,3 +44,14 @@ export const LongName: Story = {
     ],
   },
 }
+
+/** An icon before a crumb says what kind of place it is — a container, not an item. */
+export const WithAnIcon: Story = {
+  args: {
+    items: [
+      { label: 'Documents', href: '#' },
+      { label: 'Quarterly plan', href: '#', icon: <IconSquareRounded size={16} stroke={1.5} /> },
+      { label: 'DOC-12', mono: true },
+    ],
+  },
+}

package/src/Breadcrumb.test.tsx

@@ -42,3 +42,13 @@ describe('Breadcrumb', () => {
     expect(screen.queryByText('/', { ignore: '[aria-hidden="true"]' })).toBeNull()
   })
 })
+
+describe('Breadcrumb with an icon', () => {
+  it('draws the icon before the crumb, and the trail still reads as its labels', () => {
+    render(<Breadcrumb items={[{ label: 'Documents', href: '#' }, { label: 'Quarterly plan', icon: <i data-testid="kind" /> }]} />)
+    const icon = screen.getByTestId('kind').parentElement!
+    expect(icon.getAttribute('aria-hidden')).toBe('true')
+    expect(icon.nextElementSibling).toBe(screen.getByText('Quarterly plan'))
+    expect(screen.getByRole('navigation', { name: 'Breadcrumb' }).textContent).toBe('Documents/Quarterly plan')
+  })
+})

package/src/Breadcrumb.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useCallback, useLayoutEffect, useRef, useState, type MouseEventHandler } from 'react'
+import { Fragment, useCallback, useLayoutEffect, useRef, useState, type MouseEventHandler, type ReactNode } from 'react'
 import { cn } from './cn'
 import { WithTooltip } from './Tooltip'
 
@@ -29,6 +29,12 @@ export interface Crumb {
   onClick?: MouseEventHandler<HTMLAnchorElement>
   /** Set the item in the mono face — a ref, an id. */
   mono?: boolean
+  /**
+   * 16px, stroke 1.5, before the label — what kind of place this is, so a
+   * container's name is not mistaken for an item's (Katerina, 2026-09-09).
+   * Decorative: the label says where you are; the icon says what it is.
+   */
+  icon?: ReactNode
   /** Quieter — a label that is not a place. */
   muted?: boolean
 }
@@ -69,13 +75,14 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
         // The mono size is an arbitrary value (the caption token) because this
         // string goes through cn() and a token size before a colour class is
         // dropped (the tailwind-merge pitfall).
+        const tone = item.muted || (last && item.mono) ? 'text-text-muted' : last ? 'text-text-primary' : 'text-text-secondary'
         const text = cn(
           'truncate',
           // A mono crumb is a ref — the identity. It never gives up width to a
           // long name beside it (the LongName story always claimed "the ref
           // stays"; flexbox was squeezing it anyway until this line).
           item.mono && 'shrink-0 font-mono text-[12px] leading-[120%]',
-          item.muted || (last && item.mono) ? 'text-text-muted' : last ? 'text-text-primary' : 'text-text-secondary',
+          tone,
         )
         const setLabelRef = (el: HTMLElement | null) => {
           labelRefs.current[index] = el
@@ -96,6 +103,14 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
                 /
               </span>
             )}
+            {/* Beside the crumb, not inside it: the crumb stays the one element
+                that truncates and is measured, and the trail's own gap — 6px —
+                is the distance between an icon and its name everywhere here. */}
+            {item.icon && (
+              <span aria-hidden="true" className={cn('flex shrink-0', tone)}>
+                {item.icon}
+              </span>
+            )}
             {truncated.has(index) ? (
               // `min-w-0 shrink` undoes the wrapper's own shrink-0 — the crumb
               // must keep truncating inside it, or wrapping it would widen the

package/src/Chip.tsx

@@ -33,10 +33,18 @@ const typeStyles: Record<ChipType, string> = {
 
 export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, className }: ChipProps) {
   return (
-    <div className={cn('inline-flex items-center justify-center gap-1.5 rounded-full max-h-[20px] min-w-[16px] px-2 py-1', typeStyles[type], className)}>
+    <div className={cn('inline-flex min-w-0 items-center justify-center gap-1.5 rounded-full max-h-[20px] px-2 py-1', typeStyles[type], className)}>
       {leadingIcon && <span className="flex size-3 shrink-0 items-center justify-center">{leadingIcon}</span>}
       {label && (
-        <span className="text-chip whitespace-nowrap signal:font-mono signal:text-[10px] signal:font-semibold signal:tracking-[0.02em] signal:tabular-nums">{label}</span>
+        // A chip given a `max-w-*` cuts a long label with an ellipsis instead
+        // of growing past it — Ship's project chip on an issue row
+        // (2026-09-09). Clipped sideways only: `overflow-x-clip`, not
+        // `truncate`, because `truncate` is `overflow: hidden` on both axes and
+        // the label's line box (11px under Signal) is tighter than its glyphs —
+        // the screenshot diff caught every descender cut off. `clip` is the
+        // one overflow that leaves the other axis visible. A chip with no cap
+        // draws exactly as before.
+        <span className="min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap text-chip signal:font-mono signal:text-[10px] signal:font-semibold signal:tracking-[0.02em] signal:tabular-nums">{label}</span>
       )}
       {trailingIcon && <span className="flex size-3 shrink-0 items-center justify-center">{trailingIcon}</span>}
     </div>

package/src/CollapsibleSection.mdx

@@ -0,0 +1,72 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as CollapsibleSectionStories from './CollapsibleSection.stories'
+import * as SidebarStories from './Sidebar.stories'
+
+<Meta of={CollapsibleSectionStories} />
+
+# CollapsibleSection
+
+A section that opens and closes: a SectionHeader whose title is the
+toggle, and the rows under it, sliding shut and open.
+
+<Canvas of={CollapsibleSectionStories.Default} />
+
+## When
+
+- A group of rows in a sidebar or a panel that the reader may want out of
+  the way — projects, folders, starred items.
+- `defaultOpen={false}` for a group that starts folded.
+- `storageKey` when the section should stay how the reader left it across
+  reloads: this browser remembers, under that key. The app prefixes the
+  key (`ship.sidebar.projects`).
+- `open` + `onOpenChange` when the app owns the state.
+- `actions` for add, sort, filter beside the title — SectionHeader's,
+  revealed on hover or focus.
+
+In a sidebar — the Sidebar's own Composed canvas, which is where that
+composition lives:
+
+<Canvas of={SidebarStories.Composed} />
+
+## When not
+
+- A heading over rows that never fold → **SectionHeader** without
+  `chevron`, or **SectionLabel** in a 32px row.
+- Several panels where opening one closes the others → not here; that is
+  an accordion, and no app has asked for one.
+- Content that appears on demand from a control elsewhere → **Popover**.
+
+## How
+
+```tsx
+import { CollapsibleSection, NavItem } from '@estiva-app/ui'
+
+<CollapsibleSection title="Projects" storageKey="app.sidebar.projects" className="mt-2 shrink-0" contentClassName="gap-px">
+  <NavItem href="/p/1" label="Item one" />
+  <NavItem href="/p/2" label="Item two" />
+</CollapsibleSection>
+```
+
+- On Base UI's `Collapsible`: the state, the title button's
+  `aria-expanded` and `aria-controls`, the keys, the panel's height for
+  the slide (150ms; none under `prefers-reduced-motion`), and
+  `hiddenUntilFound` — the browser's find-in-page can find a row inside a
+  closed section and open it. The rows stay in the DOM while closed.
+- `className` is the section's box: `mt-2` between groups, `shrink-0` in
+  a scrolling column — the missing-`shrink-0` family. `contentClassName`
+  is the box the rows sit in: the gap between them.
+- A closed section stays closed whatever is selected inside it — the
+  reader closed it. An app that wants it to spring open owns the state
+  with `open`.
+- A browser that blocks storage still gets a working section; it forgets.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Enter, Space | on the title: opens or closes |
+| Tab | the title, then each action, then the rows when open |
+
+## Props
+
+<Controls of={CollapsibleSectionStories.Default} />

package/src/CollapsibleSection.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconPlus } from '@tabler/icons-react'
+import { CollapsibleSection } from './CollapsibleSection'
+import { NavItem } from './NavItem'
+
+/** A section that opens and closes: the header's title is the toggle, and the rows slide. */
+const meta = {
+  title: 'Navigation/CollapsibleSection',
+  component: CollapsibleSection,
+  decorators: [(Story) => <div className="w-[280px]"><Story /></div>],
+  args: { title: 'Section', contentClassName: 'gap-px', children: null },
+  argTypes: { children: { control: false }, actions: { control: false } },
+  render: (args) => (
+    <CollapsibleSection {...args}>
+      <NavItem href="#" label="Item one" count={7} countLabel="7 open" />
+      <NavItem href="#" label="Item two" count={2} countLabel="2 open" />
+      <NavItem href="#" label="Item three" />
+    </CollapsibleSection>
+  ),
+} satisfies Meta<typeof CollapsibleSection>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Open, as a section is unless told otherwise. Click the title, or focus it and press Enter or Space. */
+export const Default: Story = {}
+
+/** Starts closed. Ctrl+F for "Item two" opens it: the rows are hidden until found, not gone. */
+export const Closed: Story = { args: { defaultOpen: false } }
+
+/** Actions beside the title, revealed on hover or focus; a click on one never toggles the section. */
+export const WithActions: Story = {
+  args: { actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }] },
+}
+
+/** Close it and reload the page: still closed. This browser remembers, under the key. */
+export const Remembered: Story = { args: { storageKey: 'estiva-ui.stories.collapsible-section' } }
+

package/src/CollapsibleSection.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+/**
+ * What the page claims: the title toggles by click and by key and says its
+ * state; the rows are hidden, not removed, while closed; a `storageKey` is
+ * read on mount and written on change. The slide is Chrome's to show
+ * (measured 2026-09-09).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { CollapsibleSection } from './CollapsibleSection'
+
+afterEach(cleanup)
+beforeEach(() => window.localStorage.clear())
+
+const rows = (
+  <>
+    <a href="#">Item one</a>
+    <a href="#">Item two</a>
+  </>
+)
+
+const title = () => screen.getByRole('button', { name: 'Section' })
+
+describe('CollapsibleSection', () => {
+  it('is open by default: the title says so, and the rows are there', () => {
+    render(<CollapsibleSection title="Section">{rows}</CollapsibleSection>)
+    expect(title().getAttribute('aria-expanded')).toBe('true')
+    expect(screen.getByText('Item one').closest('[hidden]')).toBeNull()
+  })
+
+  it('a click on the title closes it, and the rows are hidden rather than gone', async () => {
+    render(<CollapsibleSection title="Section">{rows}</CollapsibleSection>)
+    await userEvent.click(title())
+    expect(title().getAttribute('aria-expanded')).toBe('false')
+    expect(screen.getByText('Item one').closest('[hidden]')).not.toBeNull()
+  })
+
+  it('Enter and Space on the title toggle it', async () => {
+    render(<CollapsibleSection title="Section">{rows}</CollapsibleSection>)
+    title().focus()
+    await userEvent.keyboard('{Enter}')
+    expect(title().getAttribute('aria-expanded')).toBe('false')
+    await userEvent.keyboard(' ')
+    expect(title().getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('starts closed with defaultOpen false', () => {
+    render(<CollapsibleSection title="Section" defaultOpen={false}>{rows}</CollapsibleSection>)
+    expect(title().getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('an action beside the title acts without toggling', async () => {
+    const add = vi.fn()
+    render(
+      <CollapsibleSection title="Section" actions={[{ icon: <i />, tooltip: 'Add', onClick: add }]}>
+        {rows}
+      </CollapsibleSection>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Add' }))
+    expect(add).toHaveBeenCalledTimes(1)
+    expect(title().getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('remembers under storageKey: written on change, read on mount', async () => {
+    const { unmount } = render(<CollapsibleSection title="Section" storageKey="test.section">{rows}</CollapsibleSection>)
+    await userEvent.click(title())
+    expect(window.localStorage.getItem('test.section')).toBe('closed')
+    unmount()
+    render(<CollapsibleSection title="Section" storageKey="test.section">{rows}</CollapsibleSection>)
+    expect(title().getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('the caller can own the state', async () => {
+    const onOpenChange = vi.fn()
+    render(<CollapsibleSection title="Section" open={false} onOpenChange={onOpenChange}>{rows}</CollapsibleSection>)
+    await userEvent.click(title())
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+    expect(title().getAttribute('aria-expanded')).toBe('false')
+  })
+})

package/src/CollapsibleSection.tsx

@@ -0,0 +1,92 @@
+import { useState, type ReactNode } from 'react'
+import { Collapsible } from '@base-ui/react/collapsible'
+import { cn } from './cn'
+import { SectionHeader, type SectionAction } from './SectionHeader'
+
+/**
+ * A section that opens and closes: a `SectionHeader` whose title is the
+ * toggle, and the rows under it, sliding shut and open (Katerina,
+ * 2026-09-09, for the sidebars of both apps). On Base UI's `Collapsible`
+ * (D6): the state, the title button's `aria-expanded` and `aria-controls`,
+ * Enter and Space, the panel's height for the slide, and `hiddenUntilFound`
+ * — the browser's find-in-page can find a row inside a closed section and
+ * open it, because the rows stay in the DOM while closed.
+ *
+ * Three ways to hold the state, from least to most work for the caller:
+ *
+ * - none: `defaultOpen` (open unless told otherwise), kept while mounted;
+ * - `storageKey`: the same, and this browser remembers it under that key
+ *   across reloads — one prop for a sidebar that stays how you left it;
+ * - `open` + `onOpenChange`: the caller owns it.
+ *
+ * A closed section stays closed whatever is selected inside it (her
+ * ruling, 2026-09-09) — the reader closed it.
+ */
+export interface CollapsibleSectionProps {
+  title: string
+  /** Open unless told otherwise. */
+  defaultOpen?: boolean
+  /** The caller owns the state. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Remember open or closed in this browser, under this key. The app prefixes it. */
+  storageKey?: string
+  /** Beside the title, revealed on hover or focus — `SectionHeader`'s. */
+  actions?: SectionAction[]
+  showActions?: 'hover' | 'always'
+  /** The rows. */
+  children: ReactNode
+  /** On the section's box: `mt-2` between groups, `shrink-0` in a scrolling column. */
+  className?: string
+  /** On the box the rows sit in: the gap between them. */
+  contentClassName?: string
+}
+
+const OPEN = 'open'
+const CLOSED = 'closed'
+
+function readStored(key: string | undefined): boolean | undefined {
+  if (!key) return undefined
+  try {
+    const value = window.localStorage.getItem(key)
+    return value === OPEN ? true : value === CLOSED ? false : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function writeStored(key: string | undefined, open: boolean) {
+  if (!key) return
+  try {
+    window.localStorage.setItem(key, open ? OPEN : CLOSED)
+  } catch {
+    // A browser that blocks storage still gets a working section; it forgets.
+  }
+}
+
+export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, storageKey, actions, showActions, children, className, contentClassName }: CollapsibleSectionProps) {
+  const [openState, setOpenState] = useState(() => readStored(storageKey) ?? defaultOpen)
+  const open = openProp ?? openState
+  const setOpen = (next: boolean) => {
+    setOpenState(next)
+    writeStored(storageKey, next)
+    onOpenChange?.(next)
+  }
+  return (
+    <Collapsible.Root open={open} onOpenChange={setOpen} className={cn('flex flex-col', className)}>
+      <SectionHeader title={title} chevron isExpanded={open} actions={actions} showActions={showActions} className="shrink-0" render={<Collapsible.Trigger />} />
+      {/* The slide: Base UI measures the panel and writes its height to a
+          variable — `auto` again once the slide ends, so rows that arrive
+          later are not clipped — and the panel is 0 high on its opening frame
+          and its closing frame. The Tooltip's idiom (D26): the data attributes
+          are Base UI's, the transition is ours, and none under
+          prefers-reduced-motion. */}
+      <Collapsible.Panel
+        hiddenUntilFound
+        className="h-[var(--collapsible-panel-height)] overflow-hidden transition-[height] duration-150 ease-out motion-reduce:transition-none data-[starting-style]:h-0 data-[ending-style]:h-0"
+      >
+        <div className={cn('flex flex-col', contentClassName)}>{children}</div>
+      </Collapsible.Panel>
+    </Collapsible.Root>
+  )
+}

package/src/Divider.mdx

@@ -20,6 +20,13 @@ carries the `separator` role for assistive tech.
 
 <Canvas of={DividerStories.Vertical} />
 
+- With a `label`, words sit in the middle of the line — a date between two
+  days of messages, or where "new since you last read this" begins.
+  `tone="warning"` for the second: the label in the warning colour, the
+  lines in its wash. The line is named by its label for assistive tech.
+
+<Canvas of={DividerStories.Warning} />
+
 ## When not
 
 - Between every row of a list — spacing does that; a hairline per row is
@@ -34,6 +41,8 @@ import { Divider } from '@estiva-app/ui'
 
 <Divider />
 <Divider orientation="vertical" />
+<Divider label="Today" />
+<Divider label="New since you last read this" tone="warning" />
 ```
 
 ## Props

package/src/Divider.stories.tsx

@@ -42,3 +42,28 @@ export const Vertical: Story = {
     </div>
   ),
 }
+
+/** Words in the middle of the line — a date between two days of messages. */
+export const WithALabel: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
+  // the label is muted caption text, 3.78:1 on --bg-surface in signal (AA 4.5:1).
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+  render: () => (
+    <div className="w-96 rounded-lg border border-border-default bg-bg-surface py-3 text-body-2 text-text-primary">
+      <p className="px-3 pb-2">Yesterday's last message</p>
+      <Divider label="Today" />
+      <p className="px-3 pt-2">Today's first</p>
+    </div>
+  ),
+}
+
+/** Asking for attention: where "new since you last read this" begins. The warning colour, because the accent could not be read on Ship's background. */
+export const Warning: Story = {
+  render: () => (
+    <div className="w-96 rounded-lg border border-border-default bg-bg-surface py-3 text-body-2 text-text-primary">
+      <p className="px-3 pb-2">Yes — it re-reads the folder union and the archived one lands last.</p>
+      <Divider label="New since you last read this" tone="warning" />
+      <p className="px-3 pt-2">Same here, from Peek.</p>
+    </div>
+  ),
+}

package/src/Divider.test.tsx

@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+/** What the Divider page claims, pinned: the role, and a label that names the line. */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { Divider } from './Divider'
+
+afterEach(cleanup)
+
+describe('Divider', () => {
+  it('is a separator, horizontal by default', () => {
+    render(<Divider />)
+    expect(screen.getByRole('separator').getAttribute('aria-orientation')).toBe('horizontal')
+  })
+
+  it('with a label, the separator is named by it and the words are drawn once', () => {
+    render(<Divider label="New since you last read this" tone="warning" />)
+    const rule = screen.getByRole('separator', { name: 'New since you last read this' })
+    expect(rule.textContent).toBe('New since you last read this')
+    expect(rule.querySelectorAll('[aria-hidden="true"]')).toHaveLength(2)
+  })
+
+  it('vertical ignores a label — there is no middle to put it in', () => {
+    render(<Divider orientation="vertical" label="Nope" />)
+    expect(screen.getByRole('separator').textContent).toBe('')
+  })
+})

package/src/Divider.tsx

@@ -8,10 +8,39 @@ import { cn } from './cn'
  */
 export interface DividerProps {
   orientation?: 'horizontal' | 'vertical'
+  /**
+   * Words in the middle of the line — "New since you last read this", a
+   * date. Horizontal only; the line splits around the label.
+   */
+  label?: string
+  /**
+   * `warning` for a line that asks for attention: the label in the warning
+   * colour, the lines in its wash. Peek and Ship both drew their "new since
+   * you last read" rule in the accent, which measures 3.3:1 on Ship's
+   * background and could not be read (Katerina, 2026-09-08); the warning
+   * colour measures 9.6:1 there. Default: the muted text, `border-subtle`
+   * lines, for a date.
+   */
+  tone?: 'default' | 'warning'
   className?: string
 }
 
-export function Divider({ orientation = 'horizontal', className }: DividerProps) {
+export function Divider({ orientation = 'horizontal', label, tone = 'default', className }: DividerProps) {
+  if (label && orientation === 'horizontal') {
+    const line = tone === 'warning' ? 'bg-warning-muted' : 'bg-border-subtle'
+    return (
+      <div
+        role="separator"
+        aria-orientation="horizontal"
+        aria-label={label}
+        className={cn('flex shrink-0 items-center gap-2 mx-3', className)}
+      >
+        <span aria-hidden="true" className={cn('h-px flex-1', line)} />
+        <span className={cn('shrink-0 text-caption', tone === 'warning' ? 'text-warning-default' : 'text-text-muted')}>{label}</span>
+        <span aria-hidden="true" className={cn('h-px flex-1', line)} />
+      </div>
+    )
+  }
   return (
     <div
       role="separator"

package/src/EmptyState.mdx

@@ -5,18 +5,32 @@ import * as EmptyStateStories from './EmptyState.stories'
 
 # EmptyState
 
-A 16px icon over a centred line of secondary text, for the place where
-content will be once there is some.
+The place where content will be once there is some, in two manners: a
+16px icon over a centred line when the whole page is empty, the line
+alone and left-aligned when one section of a page is.
 
-<Canvas of={EmptyStateStories.Default} />
+<Canvas of={EmptyStateStories.Page} />
 
 ## When
 
-- A list, panel or view with nothing in it yet. The message says **what
-  would fill it** — "No comments yet. Start the thread." — not just that
-  it is empty.
-- `icon` swaps the default speech bubble for one that matches the
-  subject.
+- **`page`** — the whole page is empty: no items yet, a link that leads to
+  nothing. The icon over a centred line; `icon` swaps the default speech
+  bubble for one that matches the subject.
+- **`section`** — one section of a page is empty and the page has other
+  things on it: no replies under an item, a search with no results. The
+  line alone, left-aligned, no icon. A section's emptiness is one line
+  among the page's content, not a stage of its own.
+
+<Canvas of={EmptyStateStories.Section} />
+
+The page decides, not the size of the box: a whole page with one short
+message is still a `page`; a tall section with nothing in it is still a
+`section`. The message says **what would fill it** — "No comments yet.
+Start the thread." — not just that it is empty.
+
+A `page` sits in the middle of its box both ways. Inside a flex column
+it takes the room left (`flex-1`) and centres in it; drawn straight into
+a page, give it the height — `className="h-full"`.
 
 ## When not
 
@@ -30,12 +44,17 @@ content will be once there is some.
 ```tsx
 import { EmptyState } from '@estiva-app/ui'
 
-<EmptyState message="No documents yet. Create the first one." />
+// the whole page, drawn straight into it
+<EmptyState className="h-full" message="No documents yet. Create the first one." />
+
+// one section of a page
+<EmptyState scope="section" message="No comments yet." />
 ```
 
 The message is the caller's — a shared component has no words of its own
-for what is missing.
+for what is missing. A hand-written "Nothing here" paragraph or span in a
+section is the `section` manner, and becomes it.
 
 ## Props
 
-<Controls of={EmptyStateStories.Default} />
+<Controls of={EmptyStateStories.Page} />

package/src/EmptyState.stories.tsx

@@ -7,12 +7,16 @@ const meta = {
   component: EmptyState,
   args: { message: 'Nothing here yet.' },
   argTypes: { icon: { control: false } },
+  // A box with a hairline, so where the state sits inside its room can be seen: a page's in the middle both ways, a section's at the top left.
+  decorators: [(Story) => <div className="flex h-[280px] w-[480px] flex-col rounded-lg border border-border-default p-4">{Story()}</div>],
 } satisfies Meta<typeof EmptyState>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-/** The default icon with the caller's words. */
-export const Default: Story = {}
-export const LongerMessage: Story = { args: { message: 'No topics yet. Start one from any conversation.' } }
+/** The `page` manner: the default icon over the caller's words, in the middle of its box both ways. */
+export const Page: Story = {}
+/** The `section` manner: the words alone, left-aligned — one line in a page that has other things on it. */
+export const Section: Story = { args: { scope: 'section' } }
+export const LongerMessage: Story = { args: { message: 'No items yet. Add one from any list.' } }
 export const CustomIcon: Story = { args: { icon: <IconLock size={16} stroke={1.5} />, message: 'Nothing you can read here yet.' } }