@estiva-app/ui 0.23.0 → 0.24.0

package/src/PreviewCard.tsx

@@ -35,8 +35,15 @@ export interface PreviewCardProps {
   delay?: number
   /** After the pointer leaves, in ms — the grace that lets you cross the gap into the card. */
   closeDelay?: number
-  /** On the card's surface: its width, its padding, a max height. */
+  /** On the card's surface: its width. */
   className?: string
+  /**
+   * On the scrolling content: its padding (default 12px) and rhythm. The
+   * padding sits inside the scrolling box, as in `Popover`, so the scrollbar
+   * hugs the card's edge — its thumb 3px from it, like every panel's
+   * (Katerina, 19 September; it sat 12px in, behind the card's padding).
+   */
+  contentClassName?: string
   /** Extra classes on the trigger wrapper — e.g. `block w-full` for a row. */
   wrapperClassName?: string
 }
@@ -58,7 +65,7 @@ const OPEN_DELAY = 350
  *  here the card can be reached, so it can. */
 const CLOSE_DELAY = 200
 
-export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, wrapperClassName }: PreviewCardProps) {
+export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, contentClassName, wrapperClassName }: PreviewCardProps) {
   return (
     <BasePreviewCard.Root>
       {/* The part renders an `<a>` by default, which a row is not; `render`
@@ -80,10 +87,10 @@ export function PreviewCard({ content, children, side = 'right', delay = OPEN_DE
           className="z-50 data-[anchor-hidden]:hidden"
         >
           <BasePreviewCard.Popup
-            className={cn('w-[360px] p-3 outline-none', className)}
+            className={cn('w-[360px] p-0 outline-none', className)}
             render={<MenuPanel />}
           >
-            <ScrollArea viewportClassName="max-h-[calc(min(300px,var(--available-height))_-_1.5rem)]" contentClassName="flex flex-col gap-3">
+            <ScrollArea viewportClassName="max-h-[min(300px,var(--available-height))]" contentClassName={cn('flex flex-col gap-3 p-3', contentClassName)}>
               {content}
             </ScrollArea>
           </BasePreviewCard.Popup>

package/src/ProgressBar.mdx

@@ -42,6 +42,14 @@ import { ProgressBar } from '@estiva-app/ui'
   of the button's.
 - `className` is for placement: a width, a margin, `flex-1` in a row.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a progress bar, with its value | `role="progressbar"` or `aria-valuenow` | ✓ |
+
 ## Props
 
 <Controls of={ProgressBarStories.Default} />

package/src/Property.mdx

@@ -54,6 +54,10 @@ WithControls story shows the pairings).
   a child of the row or the column: a control with `flex-1` still fills the
   row, and two values still sit the row's gap apart.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PropertyStories.Row} />

package/src/Rail.mdx

@@ -25,7 +25,7 @@ nothing else: **RailItem** is the tile, and where a tile goes is the app's.
   needs more than a word needs a row.
 - More entries than fit down a screen → fewer entries. The rail does not
   scroll, on purpose.
-- A strip of *actions* rather than places → a toolbar of **IconButton**s.
+- A strip of *actions* rather than places → **Toolbar**.
 
 <Canvas of={RailStories.ManyItems} />
 
@@ -52,6 +52,14 @@ import { Rail, RailItem } from '@estiva-app/ui'
 
 <Canvas of={RailStories.OneItem} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Is a navigation, named "Navigation" unless you name it | `<nav>` or `aria-label` |  |
+
 ## Keys
 
 The rail has no keyboard of its own: its tiles are links, and Tab walks them in

package/src/RailItem.mdx

@@ -45,6 +45,14 @@ import { Rail, RailItem } from '@estiva-app/ui'
   click, navigate.
 - Icons are 16px at stroke 1.5.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+
 ## Props
 
 <Controls of={RailItemStories.Default} />

package/src/Reaction.mdx

@@ -50,6 +50,15 @@ import { Reaction } from '@estiva-app/ui'
   another client can change the count.
 - `disabled` takes it out of the Tab order and ignores presses.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Is a toggle: pressed or not, and says so to assistive technology | `aria-pressed` |  |
+| Presses on Enter and Space; Tab skips it while disabled | a key handler |  |
+
 ## Keys
 
 | Key | What happens |

package/src/ReactionPicker.mdx

@@ -68,6 +68,14 @@ and, when it is yours, the accent fill. The picker asks; the pill answers.
 
 <Canvas of={ReactionPickerStories.AndWhatItProduces} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Everything a Toolbar owns: one Tab stop, arrow keys between the reactions, wrapping at the ends | a key handler, or `tabIndex` on each reaction |  |
+
 ## Keys
 
 | Input | What happens |

package/src/ScrollArea.mdx

@@ -13,8 +13,10 @@ the content is moving; nothing moves when it appears.
 
 ## When
 
-- Any box that can hold more than fits: a menu or a dropdown list, a panel,
-  a sidebar, the page's content column, a rail.
+- Any box that can hold more than fits — **a list that grows with its data
+  counts, even when today's data fits**: a menu or a dropdown list, a panel, a
+  sidebar, the page's content column. Not a rail: a rail does not scroll, on
+  purpose.
 - `orientation="horizontal"` for a row wider than its box — a table, a
   board; `"both"` when a thing can run over either way.
 
@@ -53,6 +55,15 @@ import { ScrollArea } from '@estiva-app/ui'
   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.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Scrolls with our scrollbar | `overflow-auto` or `overflow-scroll` | ✓ |
+| Scrolls with the keyboard when it has focus, like any scrolling box | key handlers |  |
+
 ## Keys
 
 | Key | Does |

package/src/SearchInput.mdx

@@ -38,6 +38,15 @@ import { SearchInput } from '@estiva-app/ui'
   and this usually stands alone in a top bar rather than in a `Field`.
   Inside one, the label names it and you add nothing.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Inside a `Field`, takes its name from the Field's label | an `id` / `htmlFor` pair |  |
+| Shows its focus ring while anything inside it has focus | a focus style of your own |  |
+
 ## Props
 
 <Controls of={SearchInputStories.Default} />

package/src/SectionHeader.mdx

@@ -53,6 +53,19 @@ import { IconPlus } from '@tabler/icons-react'
 - `render` swaps the title's element in Base UI's manner; it is how
   CollapsibleSection makes the title a `Collapsible.Trigger`.
 
+- `hover="none"` keeps the row still under the pointer: for a heading whose
+  actions are always shown (`showActions="always"`), where the buttons light up
+  on their own. The default, `fill`, lights a row that toggles or has actions.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| With `chevron`, its title is a button that calls `onToggle` on a click, Enter or Space, and says whether it is open | a button of your own, or `aria-expanded` |  |
+| Shows its actions while one of them has focus | a focus style of your own |  |
+
 ## Keys
 
 | Key | Does |

package/src/SectionHeader.stories.tsx

@@ -35,6 +35,15 @@ export const PersistentActions: Story = {
   },
 }
 
+/** `hover="none"`: actions always shown, and the row stays still under the pointer — only the buttons light up. */
+export const StillOnHover: Story = {
+  args: {
+    showActions: 'always',
+    hover: 'none',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
+  },
+}
+
 /** A count beside the title, held on screen while the actions come and go. */
 export const WithTrailing: Story = {
   args: {

package/src/SectionHeader.test.tsx

@@ -23,6 +23,15 @@ describe('SectionHeader', () => {
     expect(onToggle).toHaveBeenCalledTimes(2)
   })
 
+  it('fills under the pointer when it does something, and hover="none" keeps it still', () => {
+    const actions = [{ icon: <i />, tooltip: 'Add', onClick: () => {} }]
+    const lit = render(<SectionHeader title="Section" actions={actions} />)
+    expect((lit.container.firstElementChild as HTMLElement).className).toContain('hover:bg-bg-hover')
+    cleanup()
+    const still = render(<SectionHeader title="Section" actions={actions} hover="none" />)
+    expect((still.container.firstElementChild as HTMLElement).className).not.toContain('hover:bg-bg-hover')
+  })
+
   it('an action beside the title acts, and never toggles', async () => {
     const onToggle = vi.fn()
     const add = vi.fn()

package/src/SectionHeader.tsx

@@ -59,6 +59,12 @@ export interface SectionHeaderProps {
   actions?: SectionAction[]
   /** `hover` reveals the actions while the row is hovered or focused; `always` keeps them. */
   showActions?: 'hover' | 'always'
+  /**
+   * `fill` lights the row under the pointer when it does something (a toggle,
+   * actions); `none` keeps it still — a heading whose actions are always shown,
+   * where the buttons light up on their own (UIG-14, Katerina, 19 September).
+   */
+  hover?: 'fill' | 'none'
   /**
    * What the title renders as, in Base UI's manner. A plain button with
    * `onToggle` by default; `CollapsibleSection` hands in `Collapsible.Trigger`.
@@ -67,7 +73,7 @@ export interface SectionHeaderProps {
   className?: string
 }
 
-export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', render, className }: SectionHeaderProps) {
+export function SectionHeader({ title, chevron = false, isExpanded = true, onToggle, trailing, actions, showActions = 'hover', hover = 'fill', render, className }: SectionHeaderProps) {
   const titleElement = useRender({
     render: render ?? (chevron ? <button type="button" onClick={onToggle} aria-expanded={isExpanded} /> : <span />),
     props: {
@@ -97,7 +103,7 @@ export function SectionHeader({ title, chevron = false, isExpanded = true, onTog
         // 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',
+        hover === 'fill' && (chevron || (actions && actions.length > 0)) && 'hover:bg-bg-hover',
         className,
       )}
     >

package/src/SectionLabel.mdx

@@ -38,6 +38,10 @@ around it. Read it `tone="secondary"` where it labels rather than leads — menu
 headings and the command palette's groups do (Katerina, 2026-09-01). A colour
 passed in `className` is refused by the lint (UIG-9).
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={SectionLabelStories.Default} />

package/src/Select.mdx

@@ -29,8 +29,10 @@ corners and scrolling panels.
   things.
 - Several values → **ChipInput**.
 - Switching views of one thing → **Tabs**.
-- `disabled` explains nothing by itself — wrap it in a **WithTooltip**
-  that gives the reason.
+- `disabled` explains nothing by itself — give it `disabledReason`, which says
+  why and keeps it reachable by Tab. Busy for a moment while an action runs
+  needs no reason.
+- Ticking several on and off in a list → **Checkbox** with `row`.
 
 ## How
 
@@ -59,10 +61,27 @@ import { Select } from '@estiva-app/ui'
   smaller — and scrolls inside that. Measured in a bottom-right corner:
   the list flips above the trigger, slides left to stay on screen, and
   stands at its full 288.
+- **`disabledReason="Read only"`** holds it shut and keeps it reachable by Tab,
+  showing the reason on hover and on keyboard focus — as `Button` does. Plain
+  `disabled` is a native disabled control: Tab skips it, so it cannot say why.
 - **The trigger is a `combobox`, not a `button`.** That is the ARIA pattern
   for this control and Base UI's doing; a test looking for it by role has
   to ask for `combobox`.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize, and hides when its trigger scrolls out of sight | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Enter and Space pick, Escape and Tab close | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and jumps to an option by its first letters | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a list of options | `role="listbox"` or `role="option"` | ✓ |
+| Keeps the highlighted option in view, and gives focus back to the trigger | scroll or focus code |  |
+
 ## Keys
 
 | Input | What happens |

package/src/Select.stories.tsx

@@ -89,9 +89,12 @@ export const InAField: Story = {
   ),
 }
 
-/** Unavailable — the same disabled treatment as every other control. Say why, with a tooltip around it. */
+/** Unavailable — the same disabled treatment as every other control. To say why, `WithAReason`. */
 export const Disabled: Story = { render: (args) => <Demo {...args} initial="done" disabled /> }
 
+/** `disabledReason`: it looks disabled and will not open, but Tab reaches it and the reason shows on hover and on focus. */
+export const WithAReason: Story = { render: (args) => <Demo {...args} initial="done" disabledReason="Read only: you are a guest here" /> }
+
 /** Longer labels than the trigger is wide: the trigger truncates rather than growing; the menu takes the trigger's width as a minimum and grows past it. */
 export const LongLabels: Story = {
   render: (args) => (

package/src/Select.test.tsx

@@ -57,6 +57,23 @@ describe('Select', () => {
     expect(trigger.getAttribute('aria-expanded')).toBe('false')
   })
 
+  it('disabledReason: held shut, reachable by Tab, and it says why', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Select value="todo" onChange={onChange} options={STATUSES} ariaLabel="Status" disabledReason="Read only: you are a guest" />)
+    const trigger = screen.getByRole('combobox', { name: 'Status' })
+    expect(trigger.getAttribute('aria-disabled')).toBe('true')
+    expect(trigger.hasAttribute('disabled')).toBe(false)
+    await user.click(trigger)
+    await user.keyboard('{ArrowDown}{Enter}')
+    expect(screen.queryByRole('listbox')).toBeNull()
+    expect(onChange).not.toHaveBeenCalled()
+    await user.tab()
+    await user.tab({ shift: true })
+    expect(document.activeElement).toBe(trigger)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Read only: you are a guest')
+  })
+
   it('shows the placeholder when nothing matches', () => {
     render(<Controlled initial="" placeholder="Choose" />)
     expect(screen.getByRole('combobox', { name: 'Status' }).textContent).toContain('Choose')

package/src/Select.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from 'react'
 import { cn } from './cn'
 import { ScrollArea } from './ScrollArea'
 import { MenuPanel, menuItemClassName } from './Menu'
+import { TooltipTrigger } from './Tooltip'
 
 /**
  * Peek's Select (2026-08-28), verbatim, plus what Ship added: an option may
@@ -29,8 +30,9 @@ import { MenuPanel, menuItemClassName } from './Menu'
  * highlight is managed rather than counted, and a value that can be part of a
  * form.
  *
- * Two sizes; `disabled` explains nothing by itself — wrap it in a tooltip
- * that does.
+ * Two sizes. `disabled` explains nothing by itself; `disabledReason` says
+ * why, as Button's does: the select looks disabled, will not open, stays
+ * reachable by Tab, and shows the reason on hover and on keyboard focus.
  */
 export interface SelectOption {
   value: string
@@ -49,6 +51,13 @@ export interface SelectProps {
   'aria-required'?: boolean | 'true' | 'false'
   placeholder?: string
   disabled?: boolean
+  /**
+   * Why it cannot be changed right now (UIG-14, Katerina, 19 September). It
+   * looks disabled and will not open, but Tab still reaches it, and the reason
+   * shows as its tooltip — a native disabled button cannot be focused, so it
+   * could never say why. Takes the place of wrapping it in `WithTooltip`.
+   */
+  disabledReason?: string
   className?: string
 }
 
@@ -57,20 +66,16 @@ export interface SelectProps {
 const GAP = 4
 const VIEWPORT_PAD = 8
 
-export function Select({ value, onChange, options, size = 'default', ariaLabel, placeholder = 'Select…', disabled, className, ...aria }: SelectProps) {
+export function Select({ value, onChange, options, size = 'default', ariaLabel, placeholder = 'Select…', disabled, disabledReason, className, ...aria }: SelectProps) {
   const selected = options.find((o) => o.value === value)
-  return (
-    <BaseSelect.Root
-      value={value}
-      onValueChange={(next) => onChange(next as string)}
-      disabled={disabled}
-      // Non-modal, as it has always been: the page behind stays scrollable and
-      // keeps its scrollbar, so opening a select never shifts the layout.
-      modal={false}
-    >
+  // With a reason it is held shut rather than disabled: a disabled trigger is
+  // a native `disabled` button, which Tab skips and a tooltip cannot open on.
+  const held = Boolean(disabledReason) && !disabled
+  const trigger = (
       <BaseSelect.Trigger
         aria-label={ariaLabel}
         aria-required={aria['aria-required']}
+        aria-disabled={held || undefined}
         className={cn(
           /*
            * `min-w-0 max-w-full`: a trigger must never outgrow its container
@@ -85,7 +90,9 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
           // The focused border survives a hover: hover alone strengthens the
           // hairline, but hover while focused must not grey the focus colour —
           // the stacked variant outranks plain hover by specificity.
-          'hover:border-border-strong focus-visible:hover:border-border-focus aria-expanded:hover:border-border-focus disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled',
+          !held && 'hover:border-border-strong focus-visible:hover:border-border-focus aria-expanded:hover:border-border-focus',
+          'disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled',
+          held && 'cursor-not-allowed bg-bg-disabled text-text-disabled',
           'focus-visible:border-border-focus aria-expanded:border-border-focus',
           'signal:transition-shadow signal:focus-visible:shadow-focus-ring',
           size === 'default' && 'px-3 py-2 text-input-value',
@@ -101,6 +108,20 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
           render={<IconChevronDown size={size === 'small' ? 14 : 16} stroke={1.5} className="shrink-0 text-text-secondary" />}
         />
       </BaseSelect.Trigger>
+  )
+  return (
+    <BaseSelect.Root
+      value={value}
+      onValueChange={(next) => {
+        if (!held) onChange(next as string)
+      }}
+      {...(held ? { open: false, onOpenChange: () => {} } : {})}
+      disabled={disabled}
+      // Non-modal, as it has always been: the page behind stays scrollable and
+      // keeps its scrollbar, so opening a select never shifts the layout.
+      modal={false}
+    >
+      {held ? <TooltipTrigger label={disabledReason ?? ''}>{trigger}</TooltipTrigger> : trigger}
 
       <BaseSelect.Portal>
         <BaseSelect.Positioner

package/src/Sidebar.mdx

@@ -59,6 +59,14 @@ 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.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Scrolls its rows in a ScrollArea when they overflow | `overflow-auto` on the column |  |
+
 ## Props
 
 <Controls of={SidebarStories.Composed} />

package/src/Skeleton.mdx

@@ -37,3 +37,7 @@ import { SkeletonList, SkeletonBar } from '@estiva-app/ui'
   load never flashes a skeleton. Building your own placeholder from the
   bar? Put that class on its container for the same manner.
 - The list is `aria-hidden` — a placeholder has nothing to read.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.

package/src/Tabs.mdx

@@ -23,7 +23,7 @@ is a neutral fill, not the accent — selection is a place, not a highlight.
 
 ## When not
 
-- Going to a different place → links and **Breadcrumb**.
+- Going to a different place → **Link**, **NavItem** or **Breadcrumb**.
 - Choosing a value that gets saved → **Select**.
 - Actions → **Button**s; a tab never *does*, it *shows*.
 
@@ -54,6 +54,17 @@ import { Tabs } from '@estiva-app/ui'
   that already names it takes `aria-labelledby` instead. Unnamed is fine for
   the only tab row on a page.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Takes its keys by itself: Home and End select the first and last tab | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys: ← → select the next tab, and wrap at the ends | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a set of tabs and their panels | `role="tablist"`, `tab` or `tabpanel` | ✓ |
+| Is one Tab stop: Tab lands on the selected tab | a `tabIndex` on each tab |  |
+
 ## Keys
 
 | Key | Does |

package/src/TextInput.mdx

@@ -46,6 +46,14 @@ import { TextInput } from '@estiva-app/ui'
 - `size` is this component's (`default` or `small`), not the native attribute
   that counts characters. Set a width with the layout around it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Inside a `Field`, takes its name from the Field's label, and its error state | an `id` / `htmlFor` pair, or `aria-invalid` |  |
+
 ## Props
 
 <Controls of={TextInputStories.Empty} />

package/src/Textarea.mdx

@@ -35,6 +35,14 @@ import { Textarea } from '@estiva-app/ui'
 - **Inside a `Field`, the label names it. Add nothing.** Outside one, give
   it an `aria-label`.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Inside a `Field`, takes its name from the Field's label, and its error state | an `id` / `htmlFor` pair, or `aria-invalid` |  |
+
 ## Props
 
 <Controls of={TextareaStories.Empty} />

package/src/Toast.mdx

@@ -33,7 +33,7 @@ the positioning (bottom-left), the portal, and the auto-dismiss.
 - Something the person must read or act on → put it in the surface; a
   toast dismisses itself.
 - A question before the action → **ConfirmDialog**.
-- Standing status → a Chip or your surface's own chrome.
+- Standing status → **Chip**, or your surface's own chrome.
 
 ## How
 
@@ -70,6 +70,17 @@ showToast({ label: 'Link copied', type: 'success' })
 - `useToast` outside a provider throws — mount the provider at the root,
   once.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Says what it is to assistive technology: a message, announced as it arrives | `role="status"` or `aria-live` | ✓ |
+| F6 moves focus to the toasts from anywhere; Escape closes one | a key listener |  |
+| Leaves by itself after a while | a timer |  |
+
 ## Keys
 
 | Key | What happens |

package/src/Toolbar.mdx

@@ -82,6 +82,17 @@ why the placement is its job and not arithmetic of ours.
 
 <Canvas of={ToolbarStories.OnAnExistingSurface} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Takes its keys by itself: Enter and Space press the focused control | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and wraps at the ends | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a toolbar | `role="toolbar"` | ✓ |
+| Is one Tab stop, and remembers where the walk left off | `tabIndex` on each control |  |
+
 ## Keys
 
 | Input | What happens |

package/src/Tooltip.mdx

@@ -21,6 +21,7 @@ shows it beside a trigger — on hover, and on keyboard focus.
 - **The key that does the same thing** — pass `shortcut` and it is drawn as
   the `Kbd` chip after the label. For an icon-only control whose only other
   affordance is a keyboard shortcut, the tooltip is the only place to say so.
+- A detail behind a short word in running text — the time behind "edited".
 
 <Canvas of={TooltipStories.ShortcutComparison} />
 
@@ -30,8 +31,10 @@ shows it beside a trigger — on hover, and on keyboard focus.
 
 - Anything the person must read to proceed → put it in the surface, not
   behind a hover.
-- Anything interactive inside → **Menu** or **DialogShell**; a tooltip is
-  `pointer-events: none` by design and cannot be pointed at.
+- Anything with controls inside → **Popover**, opened by a click. A list of
+  actions → **Menu**. A tooltip disappears as the pointer moves onto it, so
+  nothing inside it can be clicked.
+- Something worth reading, scrolling or copying on hover → **PreviewCard**.
 
 ## How
 
@@ -47,6 +50,11 @@ import { WithTooltip } from '@estiva-app/ui'
   shrinks nothing, so a wrapped block collapses to its content width.
 - A truncating label keeps truncating if you pass
   `wrapperClassName="min-w-0 shrink"`.
+- **`inline`** for a trigger inside a line of text — a reference, a name in a
+  sentence: the wrapper is a `<span>`, because a `<div>` is not allowed inside
+  a paragraph.
+- A label longer than 320px wraps onto more lines rather than running off the
+  screen; a short one stays one line at 30px.
 - **`Button` and `IconButton` need no wrapper**: pass `tooltip` (or
   `disabledReason`) and the button itself becomes the trigger. That is what
   lets a `Dialog.Close` or a `Menu.Trigger` be one of them — the component's
@@ -56,6 +64,10 @@ import { WithTooltip } from '@estiva-app/ui'
   looking at — so pass the finished label. `IconButton` forwards its own
   `tooltipShortcut` here.
 
+<Canvas of={TooltipStories.InsideText} />
+
+<Canvas of={TooltipStories.LongLabel} />
+
 ### The delay, and why a toolbar only pauses once
 
 A tooltip waits **300ms** before it opens. Mount **one `TooltipProvider` at
@@ -82,6 +94,18 @@ beneath one — and fades out over **80ms**. Moving between triggers inside a
 warm group skips the animation entirely, so a toolbar sweep does not flicker.
 `prefers-reduced-motion` removes it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Says what it is to assistive technology: a tooltip | `role="tooltip"` | ✓ |
+| Opens after the pointer rests, and at once on keyboard focus | a timer, or hover and focus handlers |  |
+| Closes on Escape, on a click of its control, and when the pointer leaves | close handlers |  |
+
 ## Keys
 
 | Input | What happens |