@estiva-app/ui 0.22.0 → 0.24.0

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 |

package/src/Tooltip.stories.tsx

@@ -31,6 +31,32 @@ export const ShortcutComparison: Story = {
   ),
 }
 
+/** A label longer than 320px wraps onto more lines, rather than running off the screen. A short one stays one line at 30px. */
+export const LongLabel: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-2">
+      <Tooltip label="Comment" />
+      <Tooltip label="naddr1qvzqqqr4gupzq9h35qgq6n8ll0xyyv8gurjzjrx9sjwp4hry6ejnlks8cqcmzp6tqyfhwumn8ghj7mmxve3ksctfdch8qatz9uq3wamnwvaz7tmjv4kxz7fwwpexjmtpdshxuet59uq3qamnwvaz7tm99ehx2aqqz9mhxue69uhkummnw3ez6un9d3shjtnwda4k7tnr" />
+      <Tooltip label="Item one, with a title long enough that it no longer fits on one line of a tooltip" />
+    </div>
+  ),
+}
+
+/** `inline`: a tooltip on a word inside a sentence. The wrapper is a span, so the paragraph stays valid HTML. Hover the word. */
+export const InsideText: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <p className="max-w-sm text-body-2 text-text-primary">
+      The plan is in{' '}
+      <WithTooltip inline label="Item one, with a title long enough that it no longer fits on one line of a tooltip">
+        <span className="font-semibold">Item one</span>
+      </WithTooltip>
+      , and the rest follows.
+    </p>
+  ),
+}
+
 /** Hover the button — WithTooltip portals the tooltip above the trigger. */
 export const OnHoverTop: Story = {
   parameters: { controls: { disable: true } },

package/src/Tooltip.test.tsx

@@ -27,6 +27,14 @@ describe('Tooltip, the surface', () => {
     expect(tip.textContent).toBe('BoldCmd+B')
   })
 
+  it('wraps a long label at 320px instead of running it off the screen, and stays 30px on one line', () => {
+    render(<Tooltip label="A label long enough to wrap onto a second line of the tooltip" />)
+    const pill = screen.getByRole('tooltip')
+    expect(pill.className).toContain('max-w-80')
+    expect(pill.className).toContain('min-h-[30px]')
+    expect(pill.querySelector('span')?.className).not.toContain('whitespace-nowrap')
+  })
+
   it('takes a caller class without losing its own', () => {
     render(<Tooltip label="Bold" className="w-40" />)
     const tip = screen.getByRole('tooltip')
@@ -49,6 +57,27 @@ describe('WithTooltip', () => {
     expect(wrapper.firstElementChild?.tagName).toBe('BUTTON')
   })
 
+  it('inline: a span wrapper, so it can sit inside a paragraph without React warning', () => {
+    const errors: unknown[] = []
+    const original = console.error
+    console.error = (...args: unknown[]) => { errors.push(args) }
+    try {
+      render(
+        <p>
+          The plan is in{' '}
+          <WithTooltip inline label="Item one">
+            <span>Item one</span>
+          </WithTooltip>
+          .
+        </p>,
+      )
+    } finally {
+      console.error = original
+    }
+    expect(screen.getByText('Item one').parentElement?.tagName).toBe('SPAN')
+    expect(errors).toEqual([])
+  })
+
   it('takes wrapperClassName, which is what keeps a truncating label truncating', () => {
     const { container } = render(
       <WithTooltip label="A long name" wrapperClassName="min-w-0 shrink">

package/src/Tooltip.tsx

@@ -64,10 +64,16 @@ export interface TooltipProps extends Omit<ComponentPropsWithRef<'div'>, 'childr
   shortcut?: string
 }
 
+/**
+ * One line at 30px, as it has always been; a label longer than 320px wraps
+ * onto more lines rather than running off the screen (Katerina, 19 September:
+ * a reference's full address drew a pill 950px wide). `py-1` only shows once
+ * it wraps: a single line is centred in the 30px.
+ */
 export function Tooltip({ label, shortcut, className, ...props }: TooltipProps) {
   return (
-    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg h-[30px] flex items-center justify-center gap-1.5 px-2 shadow-lg', className)} {...props}>
-      <span className="text-caption text-text-primary whitespace-nowrap">{label}</span>
+    <div role="tooltip" className={cn('bg-bg-elevated border border-border-default rounded-lg min-h-[30px] max-w-80 flex items-center justify-center gap-1.5 px-2 py-1 shadow-lg', className)} {...props}>
+      <span className="min-w-0 text-caption text-text-primary break-words">{label}</span>
       {shortcut && <Kbd>{shortcut}</Kbd>}
     </div>
   )
@@ -80,6 +86,12 @@ export interface WithTooltipProps {
   placement?: 'top' | 'bottom'
   /** Extra classes on the wrapper — e.g. `min-w-0 shrink` so a truncating label keeps truncating inside it. */
   wrapperClassName?: string
+  /**
+   * 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 (UIG-14, Katerina, 19 September).
+   */
+  inline?: boolean
   children: ReactNode
 }
 
@@ -150,7 +162,8 @@ function TooltipSurface({ label, shortcut, placement }: { label: string; shortcu
  *  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) {
+export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, inline = false, children }: WithTooltipProps) {
+  const Wrapper = inline ? 'span' : 'div'
   return (
     <BaseTooltip.Root disableHoverablePopup>
       {/* The wrapper stays the trigger: `WithTooltip` wraps whatever it is
@@ -158,7 +171,7 @@ export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassNa
           can carry the handlers for all of them. A control that IS the trigger
           (Button, IconButton) composes the part onto itself instead, which is
           what lets a `Dialog.Close` or a `Menu.Trigger` be one of those. */}
-      <BaseTooltip.Trigger delay={OPEN_DELAY} render={<div className={cn('inline-flex shrink-0', wrapperClassName)} />}>
+      <BaseTooltip.Trigger delay={OPEN_DELAY} render={<Wrapper className={cn('inline-flex shrink-0', wrapperClassName)} />}>
         {children}
       </BaseTooltip.Trigger>
       <TooltipSurface label={label} shortcut={shortcut} placement={placement} />

package/src/TopBar.mdx

@@ -57,6 +57,10 @@ import { TopBar, IdentityMenu, SearchInput } from '@estiva-app/ui'
 - The frame is desktop-only for now — there is no narrow-screen
   behaviour; the menu button collapses panels, it does not open a drawer.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={TopBarStories.Solid} />

package/src/eslint/no-rebuilt-behaviour.ts

@@ -202,7 +202,7 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
   },
   {
     id: 'page-keys',
-    behaviour: 'Closes on Escape, and takes its keys, by itself',
+    behaviour: 'Takes its keys by itself',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Tooltip', 'PreviewCard', 'Toast'],
     owners: ['DialogShell', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
     reads: 'a keydown, keyup or keypress listener on window or document',

package/src/eslint/no-restyled-part.ts

@@ -118,6 +118,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   RailItem: ['active'],
   Reaction: ['pressed'],
   ReactionPicker: ['surface'],
+  SectionHeader: ['hover'],
   SectionLabel: ['tone'],
   Select: ['size'],
   Tabs: ['size'],

package/src/gates/app-checks.ts

@@ -43,6 +43,7 @@ export const APP_TICKET_TITLES: Record<string, string> = {
   'UIG-7': 'Lint rule — every remaining raw element',
   'UIG-8': 'Lint rule — forbid the reach',
   'UIG-9': 'Lint rule — the className allow-list',
+  'UIG-10': 'create-app — a command that makes a new Estiva app that runs',
   'UIG-13': "The registry widens to Peek's 115 and Ship's 74, with classification",
   'UIG-19': 'Lock the contract in CI, and make the three Storybooks one search',
   'UIG-20': 'The Claude skill, reading the registry',
@@ -164,8 +165,29 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       } },
       { what: 'a real page gets no error', run: realPage },
     ]),
+    // UIG-10, reopened 18 September: a tab holds one relay client, the way Peek and Ship hold
+    // theirs and a made app is written to. Measured on both mains that day: one each, and no
+    // socket opened any other way. A second holder, or a socket of the app's own, is a second
+    // connection the relay signs in and budgets separately.
+    ticket('UIG-10', [
+      { what: 'the app holds one relay client, at module level, and opens no socket of its own', run: () => {
+        const sources = h.listFiles(at('src'), (n) => /\.tsx?$/.test(n) && !/\.(test|stories)\.tsx?$/.test(n))
+        const own = sources.filter((f) => /\bcreateLiveClient\(|\bcreateLiveRelay\(|\bnew WebSocket\(/.test(h.read(f)))
+        if (own.length) return h.FAIL(`opens a socket of its own (${own.join(', ')}): hold one client from createLiveClientHolder()`)
+        const holders = sources.filter((f) => /^\s*(?:export\s+)?const\s+\w+\s*=\s*createLiveClientHolder\(\)/m.test(h.read(f)))
+        if (holders.length !== 1) return h.FAIL(holders.length ? `${holders.length} client holders (${holders.join(', ')}): a tab holds one` : 'no module-level createLiveClientHolder(): the app has no relay client')
+        return h.PASS(`one client for the tab, held in ${holders[0]}`)
+      } },
+    ]),
+    // Built by UIG-13, 18 September. An app's catalogue is built fresh from its code
+    // and never committed: the package is public and the apps are private (Katerina).
     ticket('UIG-13', [
-      { what: 'registry.json is committed and has entries', run: () => h.json(h.exists('registry.json') ? 'registry.json' : at('registry.json'), (d) => ((d as { entries?: unknown[]; components?: unknown[] }).entries ?? (d as { components?: unknown[] }).components ?? []).length > 0, 'registry.json has entries') },
+      { what: "npm run ui:find is the package's search, over the package and this app", run: () => h.contains(at('package.json'), /"ui:find":\s*"estiva-ui find\b/, "ui:find runs the package's estiva-ui find") },
+      { what: "npm run registry:check is the package's check", run: () => h.contains(at('package.json'), /"registry:check":\s*"estiva-ui check\b/, 'registry:check runs estiva-ui check') },
+      { what: "CI's job gate refuses a part with no description", run: () => h.ciJob('gate', 'registry:check') },
+      // In the .gitignore of the app's own folder, where `estiva-ui build` would write it.
+      { what: 'the catalogue is never committed: git ignores registry.json', run: () => h.contains(at('.gitignore'), /^\/?registry\.json\r?$/m, `${at('.gitignore')} ignores registry.json`) },
+      { what: 'every part is described and sorted, and every file is accounted for', run: () => h.catalogue(at('.')) },
     ]),
     ticket('UIG-19', [
       { what: 'the usage-page contract runs in CI', run: () => h.ci(/[\w:-]*contract[\w:-]*/) },