@estiva-app/ui 0.21.1 → 0.23.0

package/src/Avatar.tsx

@@ -29,6 +29,9 @@ import { cn } from './cn'
  */
 const HUES = ['#56c8ff', '#ff8f6b', '#4ade8c', '#b18cff', '#ffc94d', '#ff7eb0', '#7ea8ff', '#5fdfd6']
 
+/** The colour a person's initials sit on, chosen from a key: the same key
+ *  always gives the same hue, so a face reads as theirs in every app. The
+ *  eight are a fallback palette, not tokens — see the note above `HUES`. */
 export const hueFor = (key: string) => {
   let h = 0
   for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) | 0

package/src/Banner.mdx

@@ -28,8 +28,8 @@ line, one of four tones, gone when there is nothing to say.
   under the header at the app's full width; a floating pill is not one, even
   a permanent one (Katerina, D21).
 - A standing property of one thing → **Chip** on that thing.
-- A notice inside the content flow with its own action — that is a
-  different component (not in the package yet).
+- More than one action, or a second line of text — that is a different
+  component (not in the package yet).
 
 ## How
 
@@ -41,8 +41,21 @@ import { Banner } from '@estiva-app/ui'
 
 - Render it only while there is something to say — an empty strip is not
   a state.
-- One line of plain text, `body-2`. If it needs a **second line or an
-  action of its own**, it has outgrown this component.
+- One line of text, `body-2`. If it needs a **second line**, it has outgrown
+  this component.
+- `icon` puts a 16px icon before the line and `action` one small muted Button
+  at the end of it, both in the tone (Katerina, 2026-09-18: Peek's strip above
+  the composer became a Banner, `info`). With either, the banner is one line
+  and the text truncates. One action at most.
+
+<Canvas of={BannerStories.WithIconAndAction} />
+
+```tsx
+<Banner tone="info" icon={<IconUserPlus size={16} stroke={1.5} />} action={{ label: 'Join', onClick: join }}>
+  You are not in <span className="font-medium">{title}</span> yet
+</Banner>
+```
+
 - `onDismiss` adds an ✕ at the right-hand end (Katerina, D21). Use it where
   the reader decides the notice is done with, rather than the app. The row
   is 40px rather than 36px with it, because the button is taller than the

package/src/Banner.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconPencilMinus, IconUserPlus } from '@tabler/icons-react'
 import { Banner } from './Banner'
 
 const meta = {
@@ -34,6 +35,27 @@ export const Dismissible: Story = {
   args: { tone: 'warning', children: 'This workspace is read-only until sign-in.', onDismiss: () => {} },
 }
 
+/**
+ * With an icon and one action (Katerina, 2026-09-18). One line: the text
+ * truncates, and the Button stays at the end.
+ */
+export const WithIconAndAction: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-full max-w-xl flex-col gap-2">
+      <Banner tone="info" icon={<IconPencilMinus size={16} stroke={1.5} />} action={{ label: 'Invite people', onClick: () => {} }}>
+        This is the start of the conversation in <span className="font-medium">Project Alpha</span>
+      </Banner>
+      <Banner tone="info" icon={<IconPencilMinus size={16} stroke={1.5} />}>
+        This is the start of your conversation with <span className="font-medium">Sam Lee</span>
+      </Banner>
+      <Banner tone="info" icon={<IconUserPlus size={16} stroke={1.5} />} action={{ label: 'Join', onClick: () => {} }}>
+        You are not in <span className="font-medium">Project Alpha</span> yet — join to take part in the conversation
+      </Banner>
+    </div>
+  ),
+}
+
 /** All four tones, stacked. */
 export const AllTones: Story = {
   parameters: { controls: { disable: true } },

package/src/Banner.test.tsx

@@ -57,4 +57,39 @@ describe('Banner', () => {
     )
     expect(container.firstElementChild!.getAttribute('role')).toBe('alert')
   })
+
+  it('puts an icon before the line and one small muted action after it, on one line (Katerina, 2026-09-18)', async () => {
+    const onClick = vi.fn()
+    const { container } = render(
+      <Banner tone="info" icon={<svg data-testid="icon" />} action={{ label: 'Join', onClick }}>
+        You are not in <b>Alpha</b> yet
+      </Banner>,
+    )
+    const row = container.firstElementChild!
+    expect(row.getAttribute('role')).toBe('status')
+    expect(row.firstElementChild!.querySelector('[data-testid="icon"]')).not.toBeNull()
+    const line = screen.getByText(/You are not in/)
+    expect(line.className).toContain('truncate')
+    const button = screen.getByRole('button', { name: 'Join' })
+    expect(line.nextElementSibling).toBe(button)
+    await userEvent.click(button)
+    expect(onClick).toHaveBeenCalledOnce()
+    // No dismiss unless asked for.
+    expect(screen.queryByRole('button', { name: 'Dismiss' })).toBeNull()
+  })
+
+  it('an icon alone still keeps the line on one line, and a dismiss alone still wraps', () => {
+    const { rerender } = render(
+      <Banner tone="info" icon={<svg />}>
+        One line
+      </Banner>,
+    )
+    expect(screen.getByText('One line').className).toContain('truncate')
+    rerender(
+      <Banner tone="info" onDismiss={() => {}}>
+        One line
+      </Banner>,
+    )
+    expect(screen.getByText('One line').className).not.toContain('truncate')
+  })
 })

package/src/Banner.tsx

@@ -1,4 +1,6 @@
+import type { ReactNode } from 'react'
 import { IconX } from '@tabler/icons-react'
+import { Button } from './Button'
 import { cn } from './cn'
 import { IconButton } from './IconButton'
 
@@ -13,6 +15,11 @@ import { IconButton } from './IconButton'
  * An `error` announces itself (`role="alert"`); the other tones are
  * polite (`role="status"`).
  *
+ * `icon` and `action` put a 16px icon before the line and one small muted
+ * Button after it (Katerina, 2026-09-18, UIG-13: Peek's composer strip became
+ * a Banner in the `info` tone). With either, the banner is one line and the
+ * text truncates.
+ *
  * `onDismiss` adds an `✕` at the right-hand end (Katerina, D21,
  * 2026-09-07). Without it the strip is exactly what it was — a banner an
  * app removes by not rendering it. With it the row is 40px rather than
@@ -28,7 +35,16 @@ export type BannerTone = 'ok' | 'error' | 'info' | 'warning'
 
 export interface BannerProps {
   tone: BannerTone
-  children: string
+  /** The one line. Text, or text with a name in `font-medium`. */
+  children: ReactNode
+  /**
+   * A 16px icon before the line, in the tone's colour (Katerina, 2026-09-18:
+   * Peek's composer strip became a Banner). With an icon or an action the
+   * banner is one line, and the text truncates.
+   */
+  icon?: ReactNode
+  /** The one thing to do: the package's Button, muted and small, at the end of the line. */
+  action?: { label: string; onClick?: () => void }
   /** Adds an `✕` at the right-hand end. Absent: the app removes the banner. */
   onDismiss?: () => void
   /** The dismiss button's accessible name. Defaults to "Dismiss". */
@@ -43,25 +59,34 @@ const TONE_STYLES: Record<BannerTone, string> = {
   warning: 'bg-warning-muted text-warning-default',
 }
 
-export function Banner({ tone, children, onDismiss, dismissLabel = 'Dismiss', className }: BannerProps) {
+export function Banner({ tone, children, icon, action, onDismiss, dismissLabel = 'Dismiss', className }: BannerProps) {
   const role = tone === 'error' ? 'alert' : 'status'
-  // No dismiss, no row: every banner that predates the prop keeps the DOM and
-  // the height it had.
-  if (!onDismiss) {
+  // Nothing beside the line, no row: every banner that predates the props keeps
+  // the DOM and the height it had.
+  if (!onDismiss && !icon && !action) {
     return (
       <div role={role} className={cn('px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
         {children}
       </div>
     )
   }
+  const oneLine = Boolean(icon || action)
   return (
     <div role={role} className={cn('flex items-center gap-3 px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
-      <span className="min-w-0 flex-1">{children}</span>
+      {icon && <span className="flex shrink-0">{icon}</span>}
+      <span className={cn('min-w-0 flex-1', oneLine && 'truncate')}>{children}</span>
+      {action && (
+        <Button variant="muted" size="small" className="shrink-0" onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
       {/* `current` so the ✕ takes the tone's colour rather than the
           muted grey an IconButton wears on a neutral surface. */}
-      <IconButton variant="current" aria-label={dismissLabel} onClick={onDismiss} className="-mr-1 shrink-0">
-        <IconX size={16} stroke={1.5} />
-      </IconButton>
+      {onDismiss && (
+        <IconButton variant="current" aria-label={dismissLabel} onClick={onDismiss} className="-mr-1 shrink-0">
+          <IconX size={16} stroke={1.5} />
+        </IconButton>
+      )}
     </div>
   )
 }

package/src/ChipInput.tsx

@@ -54,6 +54,9 @@ export interface InputChipProps {
   className?: string
 }
 
+/** A chip standing on its own: a label, an optional leading icon, an optional
+ *  ✕. For a caller that keeps its own list. Inside a `ChipInput` the same look
+ *  goes onto Base UI's `Combobox.Chip`, which joins the field's keyboard. */
 export function InputChip({ label, leading, onRemove, removeLabel, truncate, className }: InputChipProps) {
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>

package/src/CommandPalette.tsx

@@ -237,6 +237,9 @@ export interface CommandPaletteSearchProps {
 
 type ListGroup = { value: string; items: CommandPaletteRow[] }
 
+/** The palette as a search: a query field, rows in labelled groups walked with
+ *  the arrow keys, and what to show while nothing has arrived and when nothing
+ *  matches. */
 export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, notes = [], empty, children }: CommandPaletteSearchProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteSearch')
   const back = useBack(chip, popupRef)
@@ -478,6 +481,9 @@ function isTextField(el: Element | null): el is HTMLInputElement | HTMLTextAreaE
   return el instanceof HTMLInputElement && TEXT_TYPES.has(el.getAttribute('type') ?? '') && el.getAttribute('role') !== 'combobox' && el.tabIndex >= 0
 }
 
+/** The palette as a form: fields, one submit button, and Ctrl+Enter — both ways
+ *  in run Base UI's field check. It shows what it is working on and what failed,
+ *  and sends focus to the first field that needs something. */
 export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWaits, working, error, children }: CommandPaletteFormProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteForm')
   const back = useBack(chip, popupRef)

package/src/ContainerHeader.mdx

@@ -0,0 +1,56 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ContainerHeaderStories from './ContainerHeader.stories'
+
+<Meta of={ContainerHeaderStories} />
+
+# ContainerHeader
+
+The bar across the top of a column — a list, a thread, a side panel: its
+title, and the buttons that act on the whole column at the right edge. 48px,
+with a hairline under it. Peek's ContainerHeader, moved into the package as it
+looks (Katerina, 2026-09-18).
+
+<Canvas of={ContainerHeaderStories.WithActions} />
+
+## When
+
+- The top of a column in a frame: the list beside the conversation, the
+  thread, a side panel. One per column.
+- The column's own actions — new, sort, close — as IconButtons with tooltips
+  in `actions`.
+
+## When not
+
+- One section inside a column → **SectionHeader**, the 32px row with a
+  SectionLabel.
+- The top of the whole app → **TopBar**.
+- A dialog's title → **DialogShell** draws its own.
+
+## How
+
+```tsx
+import { ContainerHeader, IconButton } from '@estiva-app/ui'
+
+<ContainerHeader
+  title="All items"
+  chevron
+  actions={
+    <IconButton tooltip="New item" aria-label="New item" onClick={openNew}>
+      <IconEdit size={16} stroke={1.5} />
+    </IconButton>
+  }
+/>
+```
+
+- A string title is one line in `body-2-strong` and keeps its width. Anything
+  else — an EditableText, a title over a caption — takes the room left and is
+  drawn as given.
+
+<Canvas of={ContainerHeaderStories.WithRichTitle} />
+
+- Only offer a button that does something: a button with nothing behind it is
+  a promise the column cannot keep.
+
+## Props
+
+<Controls of={ContainerHeaderStories.Default} />

package/src/ContainerHeader.stories.tsx

@@ -0,0 +1,62 @@
+import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
+import { IconEdit, IconSortDescending, IconX } from '@tabler/icons-react'
+import { ContainerHeader } from './ContainerHeader'
+import { IconButton } from './IconButton'
+
+// The top of a column: a surface with a hairline, so the bar's own hairline and height can be seen.
+const inColumn: Decorator = (Story) => <div className="w-96 overflow-hidden rounded-lg border border-border-default bg-bg-surface">{Story()}</div>
+
+const meta = {
+  title: 'Navigation/ContainerHeader',
+  component: ContainerHeader,
+  args: { title: 'Items' },
+  argTypes: { actions: { control: false } },
+  decorators: [inColumn],
+} satisfies Meta<typeof ContainerHeader>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A string title, one line, alone. */
+export const Default: Story = {}
+
+/** A chevron after the title, for a title that opens something. */
+export const WithChevron: Story = { args: { title: 'All items', chevron: true } }
+
+/** The column's own buttons at the right edge: IconButtons with tooltips. */
+export const WithActions: Story = {
+  args: {
+    title: 'All items',
+    chevron: true,
+    actions: (
+      <>
+        <IconButton tooltip="Sort by" aria-label="Sort by">
+          <IconSortDescending size={16} stroke={1.5} />
+        </IconButton>
+        <IconButton tooltip="New item" aria-label="New item">
+          <IconEdit size={16} stroke={1.5} />
+        </IconButton>
+      </>
+    ),
+  },
+}
+
+/** A title that is not a string — a name over its caption — takes the room left and is drawn as given. */
+export const WithRichTitle: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the caption
+  // is muted text, 3.94:1 in signal (AA 4.5:1) — as Peek's file page draws it.
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+  args: {
+    title: (
+      <div className="min-w-0">
+        <p className="truncate text-body-2-strong text-text-primary">Quarterly plan</p>
+        <p className="truncate text-caption text-text-muted">In Project Alpha</p>
+      </div>
+    ),
+    actions: (
+      <IconButton tooltip="Close" aria-label="Close">
+        <IconX size={16} stroke={1.5} />
+      </IconButton>
+    ),
+  },
+}

package/src/ContainerHeader.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+/**
+ * What `ContainerHeader.mdx` claims: a string title is one line that keeps its
+ * width, a node is drawn as given and takes the room left, and the column's
+ * buttons sit at the right edge. The pixels are proved against Peek's own
+ * (docs/GATES.md, UIG-13: A).
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ContainerHeader } from './ContainerHeader'
+
+afterEach(cleanup)
+
+describe('ContainerHeader', () => {
+  it('is the 48px bar with a hairline under it', () => {
+    const { container } = render(<ContainerHeader title="Items" />)
+    const bar = container.firstElementChild!.className.split(' ')
+    expect(bar).toContain('h-12')
+    expect(bar).toContain('border-b')
+    expect(bar).toContain('border-border-subtle')
+  })
+
+  it('a string title is one line in body-2-strong, and keeps its width', () => {
+    render(<ContainerHeader title="Items" />)
+    const title = screen.getByText('Items')
+    expect(title.className).toContain('text-body-2-strong')
+    expect(title.className).toContain('whitespace-nowrap')
+    expect(title.parentElement!.className).toContain('shrink-0')
+  })
+
+  it('a node title is drawn as given and takes the room left', () => {
+    render(<ContainerHeader title={<em>Plan</em>} />)
+    const holder = screen.getByText('Plan').parentElement!
+    expect(holder.className).toContain('flex-1')
+    expect(holder.className).toContain('min-w-0')
+  })
+
+  it('draws a chevron only when asked, and the buttons at the right edge', () => {
+    const { container, rerender } = render(<ContainerHeader title="Items" />)
+    expect(container.querySelector('svg')).toBeNull()
+    expect(container.firstElementChild!.children).toHaveLength(1)
+    rerender(<ContainerHeader title="Items" chevron actions={<button type="button">New</button>} />)
+    expect(container.querySelector('svg')).not.toBeNull()
+    expect(container.firstElementChild!.children).toHaveLength(2)
+    expect(screen.getByRole('button', { name: 'New' }).closest('div')!.className).toContain('gap-1')
+  })
+})

package/src/ContainerHeader.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react'
+import { IconChevronDown } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * The bar across the top of a column — a list, a thread, a side panel: its
+ * title, and the buttons that act on the whole column at the right edge.
+ * Peek's ContainerHeader, moved into the package exactly as it looks
+ * (Katerina, 2026-09-18, UIG-13).
+ *
+ * 48px tall, a hairline under it. A string title is one line in
+ * `body-2-strong` and keeps its width; anything else — an EditableText, a
+ * title over a caption — takes the room that is left and is drawn as given.
+ *
+ * Not a SectionHeader: that is the 32px row one section of a column starts
+ * with. This is the column's own bar, one per column.
+ */
+export interface ContainerHeaderProps {
+  /** A string keeps the one-line treatment; a node is drawn as given. */
+  title: ReactNode
+  /** A chevron after the title, for a title that opens something. */
+  chevron?: boolean
+  /** The column's own buttons, at the right edge: IconButtons with tooltips, 4px apart. */
+  actions?: ReactNode
+  className?: string
+}
+
+export function ContainerHeader({ title, chevron = false, actions, className }: ContainerHeaderProps) {
+  const text = typeof title === 'string'
+  return (
+    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4 pl-5', className)}>
+      <div className={cn('flex items-center gap-2 overflow-hidden', text ? 'shrink-0' : 'min-w-0 flex-1')}>
+        <div className={cn('flex items-center gap-1', text ? 'shrink-0' : 'min-w-0 flex-1')}>
+          {text ? <span className="whitespace-nowrap text-body-2-strong text-text-primary">{title}</span> : <div className="min-w-0 flex-1">{title}</div>}
+          {chevron && <IconChevronDown size={12} stroke={1.5} className="shrink-0 text-text-secondary" />}
+        </div>
+      </div>
+      {actions && (
+        <div className="flex shrink-0 items-center justify-end gap-3">
+          <div className="flex shrink-0 items-center gap-1">{actions}</div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/EmptyState.mdx

@@ -53,6 +53,18 @@ import { EmptyState } from '@estiva-app/ui'
 <EmptyState scope="section" message="No comments yet." />
 ```
 
+**When there is one thing to do about it, give it as `action`.** It is drawn
+16px under the line as the package's Button, outlined — the same look wherever
+it appears (Katerina, 2026-09-18). Never put a Button beside an EmptyState in a
+box of your own: the box places it, and no two boxes place it alike. A `page`
+only; a section's line takes no action.
+
+<Canvas of={EmptyStateStories.WithAction} />
+
+```tsx
+<EmptyState icon={<IconMessagePlus size={16} stroke={1.5} />} message="No topics yet." action={{ label: 'New topic', onClick: openNewTopic }} />
+```
+
 **Put a section's empty state inside the box its rows live in, and give it no
 padding.** Write the box once; inside it goes either the rows or the empty
 state. The box's padding then places both, and the line starts where the first

package/src/EmptyState.stories.tsx

@@ -1,5 +1,5 @@
 import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
-import { IconLock } from '@tabler/icons-react'
+import { IconLock, IconMessagePlus } from '@tabler/icons-react'
 import { EmptyState } from './EmptyState'
 
 // 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.
@@ -25,6 +25,11 @@ const sectionContrastDeferred = { a11y: { config: { rules: [{ id: 'color-contras
 export const Section: Story = { args: { scope: 'section' }, decorators: [inBox], parameters: sectionContrastDeferred }
 export const LongerMessage: Story = { args: { message: 'No items yet. Add one from any list.' }, decorators: [inBox] }
 export const CustomIcon: Story = { args: { icon: <IconLock size={16} stroke={1.5} />, message: 'Nothing you can read here yet.' }, decorators: [inBox] }
+/** The one thing to do about it, under the line: the package's Button, outlined. */
+export const WithAction: Story = {
+  args: { icon: <IconMessagePlus size={16} stroke={1.5} />, message: 'No topics yet.', action: { label: 'New topic', onClick: () => {} } },
+  decorators: [inBox],
+}
 
 /** One box, written once, holding the rows or the empty state: its padding places both, so the line starts where the first row does. */
 export const InsideTheRowsBox: Story = {

package/src/EmptyState.test.tsx

@@ -6,7 +6,7 @@
  * structure.
  */
 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { EmptyState } from './EmptyState'
 
 afterEach(cleanup)
@@ -59,4 +59,21 @@ describe('EmptyState', () => {
     expect(container.querySelector('[data-testid="own"]')).not.toBeNull()
     expect(container.querySelector('svg')).toBeNull()
   })
+
+  it('draws its action under the line as the package Button, outlined (Katerina, 2026-09-18)', () => {
+    let clicked = 0
+    render(<EmptyState message="No topics yet." action={{ label: 'New topic', onClick: () => (clicked += 1) }} />)
+    const button = screen.getByRole('button', { name: 'New topic' })
+    expect(button.className).toContain('border-border-default')
+    expect(button.className).toContain('mt-2')
+    // Under the line, in the same column.
+    expect(screen.getByText('No topics yet.').nextElementSibling).toBe(button)
+    fireEvent.click(button)
+    expect(clicked).toBe(1)
+  })
+
+  it('a section takes no action', () => {
+    render(<EmptyState scope="section" message="Nothing here yet." action={{ label: 'Add', onClick: () => {} }} />)
+    expect(screen.queryByRole('button')).toBeNull()
+  })
 })

package/src/EmptyState.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { IconMessage2 } from '@tabler/icons-react'
+import { Button } from './Button'
 import { cn } from './cn'
 
 /**
@@ -28,10 +29,16 @@ export interface EmptyStateProps {
   message: string
   /** `page` when the whole page is empty; `section` when one part of it is. */
   scope?: 'page' | 'section'
+  /**
+   * The one thing to do about it — "New topic", "Try again" — drawn 16px under
+   * the line as the package's Button, outlined (Katerina, 2026-09-18). A `page`
+   * only: a section's empty line is one line among others, not a stage.
+   */
+  action?: { label: string; onClick: () => void }
   className?: string
 }
 
-export function EmptyState({ icon, message, scope = 'page', className }: EmptyStateProps) {
+export function EmptyState({ icon, message, scope = 'page', action, className }: EmptyStateProps) {
   if (scope === 'section') {
     return <p className={cn('text-caption text-text-muted', className)}>{message}</p>
   }
@@ -39,6 +46,12 @@ export function EmptyState({ icon, message, scope = 'page', className }: EmptySt
     <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>
+      {/* 8px of the column's gap and 8px of its own: 16px under the line, as Peek had it. */}
+      {action && (
+        <Button variant="outlined" className="mt-2" onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
     </div>
   )
 }

package/src/IdentityMenu.tsx

@@ -62,6 +62,9 @@ export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact'> {
   onClose?: () => void
 }
 
+/** The identity rows on a panel of their own, with no menu around them — for a
+ *  docs page, or anywhere the panel is already placed. `IdentityMenu` is the
+ *  same rows inside a real menu. */
 export function IdentityPanel({ className, onClose = () => {}, ...rest }: IdentityPanelProps) {
   return (
     <MenuPanel className={cn('w-72', className)}>

package/src/Menu.tsx

@@ -86,6 +86,10 @@ export interface MenuPanelProps extends Omit<ComponentPropsWithRef<'div'>, 'chil
   children?: ReactNode
 }
 
+/** The menu's surface without the menu: the elevated box, the rows' padding,
+ *  and a divider that runs the full width of what it separates. `Menu` renders
+ *  its popup as one. On its own it is for the places that draw a menu's look
+ *  but not its behaviour — a docs page, Peek's `@`, `/` and `[` pickers. */
 export function MenuPanel({ children, className, ...props }: MenuPanelProps) {
   return (
     <div
@@ -277,6 +281,9 @@ export interface MenuSubProps {
   className?: string
 }
 
+/** A row that opens another menu beside it; its rows are this row's children.
+ *  Never inside a menu opened on hover — leaving the submenu strands both open,
+ *  measured below. */
 export function MenuSub({ label, leading, selected, children, className }: MenuSubProps) {
   /*
    * A submenu inside a hover-opened menu strands it.

package/src/Skeleton.tsx

@@ -10,6 +10,8 @@ import { cn } from './cn'
  * A list reveals after 150ms (`animate-skeleton-in`, in the preset) so a
  * fast load never flashes a skeleton — Peek's rule.
  */
+/** One pulsing bar at the inset colour: the piece every placeholder here is
+ *  built from. It draws nothing of its own — give it a width and a height. */
 export function SkeletonBar({ className, style }: { className?: string; style?: CSSProperties }) {
   return <div className={cn('bg-bg-inset rounded-sm animate-pulse', className)} style={style} />
 }

package/src/Toast.tsx

@@ -153,6 +153,9 @@ const ToastContext = createContext<ToastValue | null>(null)
 /** D7: three on screen at once. */
 const VISIBLE_TOASTS = 3
 
+/** Mount once, near the top of an app. It owns the stack, the timers and the
+ *  portal every toast goes through, and it is what `useToast` talks to. Three
+ *  show at once; a fourth waits for one of them to close. */
 export function ToastProvider({ children }: { children: ReactNode }) {
   // One manager per provider, so `useToast` can add and close without
   // re-rendering every caller each time the list changes.
@@ -227,6 +230,8 @@ function ToastList() {
   })
 }
 
+/** How anything under a `ToastProvider` raises a toast (`showToast`) or takes
+ *  one away (`dismissToast`). Throws outside a provider. */
 export function useToast(): ToastValue {
   const ctx = useContext(ToastContext)
   if (!ctx) throw new Error('useToast must be used within ToastProvider')

package/src/Toolbar.tsx

@@ -104,6 +104,8 @@ export interface ToolbarButtonProps extends IconButtonProps {
   ref?: Ref<HTMLButtonElement>
 }
 
+/** An `IconButton` that is an item of a `Toolbar`: the arrow keys reach it, and
+ *  a disabled one stays in the walk so its reason can still be read. */
 export function ToolbarButton({ ref, disabled, disabledReason, ...props }: ToolbarButtonProps) {
   return (
     <BaseToolbar.Button
@@ -137,6 +139,8 @@ export function ToolbarButton({ ref, disabled, disabledReason, ...props }: Toolb
  */
 export type ToolbarInputProps = TextInputProps
 
+/** A `TextInput` that is an item of a `Toolbar`, so the arrow keys walk into the
+ *  field and out of it again. */
 export function ToolbarInput({ size, ...props }: ToolbarInputProps) {
   // `size` is TextInput's own (default or small), not the native attribute
   // Base UI's part would take, so it goes to the field it draws.

package/src/Tooltip.tsx

@@ -146,6 +146,10 @@ function TooltipSurface({ label, shortcut, placement }: { label: string; shortcu
   )
 }
 
+/** A tooltip on something that cannot be its own trigger — a span, a `Chip`,
+ *  an icon. It wraps what it is given in an element that carries the handlers.
+ *  A control that can be the trigger does it itself: `IconButton` takes a
+ *  `tooltip` prop, and `Button` shows a `disabledReason` the same way. */
 export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
   return (
     <BaseTooltip.Root disableHoverablePopup>