@estiva-app/ui 0.23.0 → 0.24.1

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,14 @@ 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`.
+   * Given with `disabled`, the reason wins, as on `Button`.
+   */
+  disabledReason?: string
   className?: string
 }
 
@@ -57,20 +67,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)
+  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,11 +91,13 @@ 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',
-          size === 'small' && 'h-6 px-2 text-caption',
+          size === 'small' && 'h-6 min-h-6 px-2 text-caption',
           className,
         )}
       >
@@ -101,6 +109,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 && !held}
+      // 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,11 @@ 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
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Keeps each row's 32px in a scrolling column | `shrink-0` |  |

package/src/Skeleton.tsx

@@ -21,7 +21,7 @@ const ROW_BAR_WIDTHS = [150, 100, 170, 120, 90, 140, 110, 160]
 /** A 32px row: a 16px square and a bar, like a row with a face and a name. */
 export function SkeletonRow({ barWidth = 130 }: { barWidth?: number }) {
   return (
-    <div className="flex items-center gap-2 px-2 h-[32px] rounded-lg">
+    <div className="flex shrink-0 items-center gap-2 px-2 h-[32px] rounded-lg">
       <SkeletonBar className="w-4 h-4 shrink-0" />
       <SkeletonBar className="h-3.5" style={{ width: barWidth }} />
     </div>

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,15 @@ 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` |  |
+| Keeps its height in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={TextInputStories.Empty} />

package/src/TextInput.tsx

@@ -38,7 +38,7 @@ export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(function T
         'bg-bg-inset border border-border-default hover:border-border-strong focus:border-border-focus rounded-lg',
         // The small size is the small Select's trigger, class for class.
         size === 'default' && 'px-3 py-2 text-input-value',
-        size === 'small' && 'h-6 px-2 text-caption',
+        size === 'small' && 'h-6 min-h-6 px-2 text-caption',
         'text-text-primary placeholder:text-text-muted',
         'outline-none transition-colors',
         'disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled',

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

@@ -69,8 +69,8 @@ import { Toolbar, ToolbarButton, ToolbarSeparator } from '@estiva-app/ui'
 A toolbar floats over what it acts on — a card, a paragraph, an image — so it
 draws the elevated surface that separates it from that: **the same `MenuPanel`
 a `Menu` draws**, because a floating strip and a floating list are the same
-box. Peek had built this twice and the two had already drifted: one
-`rounded-sm` with `shadow-sm`, the other `rounded-lg` with `shadow-lg`.
+box. Built twice by hand, the two drift: one `rounded-sm` with `shadow-sm`,
+the other `rounded-lg` with `shadow-lg`.
 
 `surface={false}` for a strip inside something that draws that box already — a
 `Popover`, a dialog, a card's own panel.
@@ -82,6 +82,24 @@ why the placement is its job and not arithmetic of ours.
 
 <Canvas of={ToolbarStories.OnAnExistingSurface} />
 
+**A control that goes somewhere is a `ToolbarLink`** with an `href`: the
+strip's look, in the same walk, with a real address, so a Ctrl+click opens a
+new tab. A `ToolbarButton` cannot be a link. A place you cannot go is left out
+of the strip rather than disabled.
+
+<Canvas of={ToolbarStories.WithALink} />
+
+## 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/Toolbar.stories.tsx

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconArrowBackUp, IconArrowForwardUp, IconBold, IconItalic, IconLink, IconSquareRounded, IconUnderline } from '@tabler/icons-react'
+import { IconArrowBackUp, IconArrowForwardUp, IconArrowUpRight, IconBold, IconItalic, IconLink, IconSquareRounded, IconUnderline } from '@tabler/icons-react'
 import { useState } from 'react'
 import { IconButton } from './IconButton'
 import { Popover } from './Popover'
-import { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from './Toolbar'
+import { Toolbar, ToolbarButton, ToolbarInput, ToolbarLink, ToolbarSeparator } from './Toolbar'
 
 /**
  * A strip of controls that behaves as **one** control: Tab in, arrow keys
@@ -100,6 +100,23 @@ export const WithADisabledControl: Story = {
   ),
 }
 
+/**
+ * A control that goes somewhere, beside controls that do something. The link
+ * has the buttons' look and joins the same walk; it has a real address, so a
+ * Ctrl+click opens a new tab.
+ */
+export const WithALink: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Toolbar aria-label="Item actions" surface={false}>
+      <ToolbarButton aria-label="Item one" tooltip="Item one">{icon}</ToolbarButton>
+      <ToolbarLink href="#item" aria-label="Open the item" tooltip="Open">
+        <IconArrowUpRight size={16} stroke={1.5} />
+      </ToolbarLink>
+    </Toolbar>
+  ),
+}
+
 /** Down rather than across: ↑ and ↓ walk it. */
 export const Vertical: Story = {
   parameters: { controls: { disable: true } },

package/src/Toolbar.test.tsx

@@ -7,7 +7,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { IconButton } from './IconButton'
-import { Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from './Toolbar'
+import { Toolbar, ToolbarButton, ToolbarInput, ToolbarLink, ToolbarSeparator } from './Toolbar'
 import { Menu, MenuItem } from './Menu'
 import { Popover } from './Popover'
 
@@ -176,6 +176,29 @@ describe('Toolbar', () => {
   })
 })
 
+describe('a link in the strip (F3)', () => {
+  it('is a real link, in the walk with the buttons beside it', async () => {
+    const user = userEvent.setup()
+    render(
+      <>
+        <button type="button">Before</button>
+        <Toolbar aria-label="Item actions">
+          <ToolbarButton aria-label="One">{dot}</ToolbarButton>
+          <ToolbarLink href="/somewhere" aria-label="Open" tooltip="Open">{dot}</ToolbarLink>
+        </Toolbar>
+      </>,
+    )
+    const link = screen.getByRole('link', { name: 'Open' })
+    expect(link.getAttribute('href')).toBe('/somewhere')
+    await user.click(screen.getByRole('button', { name: 'Before' }))
+    await user.tab()
+    expect(focused()).toBe('One')
+    await user.keyboard('{ArrowRight}')
+    expect(document.activeElement).toBe(link)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Open')
+  })
+})
+
 describe('a loose row, for comparison', () => {
   /** The measurement the component exists to change: the same three buttons
    *  outside a toolbar are three Tab stops. */

package/src/Toolbar.tsx

@@ -129,6 +129,28 @@ export function ToolbarButton({ ref, disabled, disabledReason, ...props }: Toolb
   )
 }
 
+/**
+ * A link in the strip: the strip's own look, and it goes somewhere. It has a
+ * real address, so a Ctrl+click or a middle click opens a new tab, which a
+ * button that navigates cannot do.
+ *
+ * It is `IconButton`'s `href` joined to the toolbar's walk: Base UI's
+ * `Toolbar.Link`. A `ToolbarButton` cannot be a link — Base UI expects a real
+ * button there and warns when it gets an anchor (UIG-14, finding F3).
+ *
+ * A link is never disabled: a place you cannot go is left out of the strip.
+ */
+export interface ToolbarLinkProps extends Omit<IconButtonProps, 'href' | 'disabled' | 'disabledReason' | 'pressed' | 'type' | 'ref'> {
+  href: string
+  ref?: Ref<HTMLAnchorElement>
+}
+
+/** An `IconButton` that is a link, and an item of a `Toolbar`: the arrow keys
+ *  reach it like the buttons beside it. */
+export function ToolbarLink({ ref, href, ...props }: ToolbarLinkProps) {
+  return <BaseToolbar.Link ref={ref} render={<IconButton href={href} {...props} />} />
+}
+
 /**
  * A text field inside the strip — the link editor in a selection toolbar.
  *

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,12 @@ 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. It sits at the top of the line by itself, so the line keeps its
+  height; add no wrapper of your own around it.
+- 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 +65,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 +95,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,49 @@ 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([])
+  })
+
+  // F1: without `align-top` a chip in the wrapper drops 0.2px and its line grows
+  // from 19.6 to 20px; the apps may not add the class to the part, so it carries it.
+  it('inline: the wrapper sits at the top of the line by itself', () => {
+    render(
+      <p>
+        <WithTooltip inline label="Item one">
+          <span>Item one</span>
+        </WithTooltip>
+      </p>,
+    )
+    expect(screen.getByText('Item one').parentElement?.className.split(' ')).toContain('align-top')
+  })
+
+  it('a block wrapper is not moved', () => {
+    render(
+      <WithTooltip label="Item one">
+        <span>Item one</span>
+      </WithTooltip>,
+    )
+    expect(screen.getByText('Item one').parentElement?.className.split(' ')).not.toContain('align-top')
+  })
+
   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', inline && 'align-top', wrapperClassName)} />}>
         {children}
       </BaseTooltip.Trigger>
       <TooltipSurface label={label} shortcut={shortcut} placement={placement} />

package/src/TopBar.mdx

@@ -57,6 +57,17 @@ 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.
 
+- The bar is 52px tall, 20px in on the left and 26px on the right, 16px between
+  its slots.
+
+## 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 |
+|---|---|---|
+| Keeps its 52px in a scrolling column | `shrink-0` |  |
+
 ## 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'],