@estiva-app/ui 0.8.0 → 0.10.0

package/src/Select.tsx

@@ -1,24 +1,34 @@
 import { IconCheck, IconChevronDown } from '@tabler/icons-react'
-import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
-import { createPortal } from 'react-dom'
+import { Select as BaseSelect } from '@base-ui/react/select'
+import type { ReactNode } from 'react'
 import { cn } from './cn'
 
 /**
  * Peek's Select (2026-08-28), verbatim, plus what Ship added: an option may
  * carry a `leading` node — an avatar beside a person's name — shown in the
- * trigger and in the list.
+ * trigger and in the list. On Base UI's `Select` since stage 4 of the
+ * migration (2026-09-07).
  *
- * A button that opens a portalled listbox under itself: arrows move (and keep
- * the active option scrolled into view), Home and End jump, Enter and Space
- * pick, Escape closes and returns focus to the trigger, Tab closes, a click
- * outside closes, a PAGE scroll or resize closes (the list is fixed to where
- * the trigger was) — a scroll *inside* the list is the list's own business
- * and must not dismiss it. The menu keeps itself on screen: clamped to the
- * viewport's sides, height capped to the space it actually has, opening
- * upward when the room below is worse than the room above (Katerina,
- * 2026-09-01 — the files-panel picker was cut right and bottom, and its own
- * scroll closed it). Two sizes; `disabled` explains nothing by itself — wrap
- * it in a tooltip that does.
+ * A button that shows the choice and opens a listbox under it. **Under it:
+ * Base UI would rather lay the list over the trigger so the chosen option's
+ * text covers the trigger's, the way macOS does — `alignItemWithTrigger` is
+ * off, because every Select in both apps opens below one today (Katerina,
+ * D24).**
+ *
+ * What the port deleted: `createPortal`, the whole `onKeyDown` switch, the
+ * outside-click, resize and scroll listeners, the `aria-activedescendant`
+ * bookkeeping, the `scrollIntoView` that kept the highlight visible, and
+ * `fit.ts` — the pure geometry this component grew and then shared with the
+ * Menu shell. Floating UI does the fitting; `--available-height` is where the
+ * old 288px cap now meets the room the screen actually has.
+ *
+ * What it gained, and none of it was written here: **typeahead** — type the
+ * first letters of an option and the list jumps to it — a listbox whose
+ * 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.
  */
 export interface SelectOption {
   value: string
@@ -33,171 +43,32 @@ export interface SelectProps {
   options: SelectOption[]
   size?: 'default' | 'small'
   ariaLabel?: string
+  /** Set by a `Field` with `required`; a caller inside one owes nothing. */
+  'aria-required'?: boolean | 'true' | 'false'
   placeholder?: string
   disabled?: boolean
   className?: string
 }
 
-// The geometry lives in fit.ts now (2026-09-03) — shared with the Menu
-// shell, so a cut-off surface is fixed once. Re-exported because this is
-// where it grew up and its test still names it by this address.
-import { fitMenu } from './fit'
-export { fitMenu }
-
-export function Select({ value, onChange, options, size = 'default', ariaLabel, placeholder = 'Select…', disabled, className }: SelectProps) {
-  const id = useId()
-  const triggerRef = useRef<HTMLButtonElement>(null)
-  const menuRef = useRef<HTMLDivElement>(null)
-  const [rect, setRect] = useState<DOMRect | null>(null)
-  /** Where the menu actually goes — measured against the viewport after the
-   *  provisional render, so it is never cut off by an edge. */
-  const [placement, setPlacement] = useState<{
-    left: number
-    top?: number
-    bottom?: number
-    maxHeight: number
-  } | null>(null)
-  const open = rect !== null
-
-  const selectedIndex = useMemo(() => Math.max(0, options.findIndex((o) => o.value === value)), [options, value])
-  const [activeIndex, setActiveIndex] = useState(selectedIndex)
-
-  const close = useCallback((refocus: boolean) => {
-    setRect(null)
-    if (refocus) triggerRef.current?.focus()
-  }, [])
-
-  const openMenu = useCallback(() => {
-    setActiveIndex(selectedIndex)
-    setRect(triggerRef.current?.getBoundingClientRect() ?? null)
-  }, [selectedIndex])
-
-  /*
-   * Fit the menu to the viewport, before paint.
-   *
-   * The provisional render sits at the trigger's corner and is invisible;
-   * this measures it and decides the real box: left clamped inside the
-   * viewport, height capped to the space available, and the whole thing
-   * opening UPWARD when the room below is smaller than both the content and
-   * the room above. A menu that is always fully on screen is also the only
-   * kind whose scrollbar can actually be used.
-   */
-  useLayoutEffect(() => {
-    if (!rect || !menuRef.current) {
-      setPlacement(null)
-      return
-    }
-    setPlacement(
-      fitMenu({
-        anchor: { left: rect.left, top: rect.top, bottom: rect.bottom },
-        menu: { width: menuRef.current.offsetWidth, contentHeight: menuRef.current.scrollHeight },
-        viewport: { width: window.innerWidth, height: window.innerHeight },
-        // The option list keeps its classic height (the old max-h-72); a menu
-        // panel passes no cap and stands as tall as the room it opens into.
-        cap: 288,
-      }),
-    )
-  }, [rect, options.length])
-
-  // Keyboard follows the highlight: without this, arrowing past the fold
-  // moved `activeIndex` into rows the capped menu never showed.
-  useEffect(() => {
-    if (!open) return
-    // Optional call: jsdom implements neither scrolling nor this method, and
-    // a consumer's component tests should not crash for a scroll nicety.
-    document.getElementById(`${id}-${activeIndex}`)?.scrollIntoView?.({ block: 'nearest' })
-  }, [open, activeIndex, id])
-
-  // Outside click and Escape — the two exits every menu has. `mousedown`
-  // rather than `click`, so a press that starts outside dismisses at once.
-  useEffect(() => {
-    if (!open) return
-    const onDown = (e: MouseEvent) => {
-      if (menuRef.current?.contains(e.target as Node)) return
-      if (triggerRef.current?.contains(e.target as Node)) return
-      setRect(null)
-    }
-    const onResize = () => setRect(null)
-    /*
-     * A PAGE scroll moves the anchor out from under the fixed menu, so it
-     * closes. A scroll INSIDE the menu is the menu working as designed —
-     * capture phase sees those too, and closing on them made the list
-     * impossible to scroll at all (the bug this comment survives to prevent).
-     */
-    const onScroll = (e: Event) => {
-      if (e.target instanceof Node && menuRef.current?.contains(e.target)) return
-      setRect(null)
-    }
-    document.addEventListener('mousedown', onDown)
-    window.addEventListener('resize', onResize)
-    window.addEventListener('scroll', onScroll, true)
-    return () => {
-      document.removeEventListener('mousedown', onDown)
-      window.removeEventListener('resize', onResize)
-      window.removeEventListener('scroll', onScroll, true)
-    }
-  }, [open])
-
-  const pick = (index: number) => {
-    const option = options[index]
-    if (!option) return
-    onChange(option.value)
-    close(true)
-  }
-
-  const onKeyDown = (e: KeyboardEvent) => {
-    if (!open) {
-      if (['ArrowDown', 'ArrowUp', 'Enter', ' '].includes(e.key)) {
-        e.preventDefault()
-        openMenu()
-      }
-      return
-    }
-    switch (e.key) {
-      case 'Escape':
-        e.preventDefault()
-        close(true)
-        break
-      case 'ArrowDown':
-        e.preventDefault()
-        setActiveIndex((i) => Math.min(options.length - 1, i + 1))
-        break
-      case 'ArrowUp':
-        e.preventDefault()
-        setActiveIndex((i) => Math.max(0, i - 1))
-        break
-      case 'Home':
-        e.preventDefault()
-        setActiveIndex(0)
-        break
-      case 'End':
-        e.preventDefault()
-        setActiveIndex(options.length - 1)
-        break
-      case 'Enter':
-      case ' ':
-        e.preventDefault()
-        pick(activeIndex)
-        break
-      case 'Tab':
-        close(false)
-        break
-    }
-  }
+/** The 4px between the trigger and the list, and the 8px the list keeps clear
+ *  of every screen edge — the two numbers `fitMenu` used. */
+const GAP = 4
+const VIEWPORT_PAD = 8
 
+export function Select({ value, onChange, options, size = 'default', ariaLabel, placeholder = 'Select…', disabled, className, ...aria }: SelectProps) {
   const selected = options.find((o) => o.value === value)
-
   return (
-    <>
-      <button
-        ref={triggerRef}
-        type="button"
-        disabled={disabled}
-        aria-haspopup="listbox"
-        aria-expanded={open}
+    <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}
+    >
+      <BaseSelect.Trigger
         aria-label={ariaLabel}
-        onClick={() => (open ? close(false) : openMenu())}
-        onKeyDown={onKeyDown}
+        aria-required={aria['aria-required']}
         className={cn(
           /*
            * `min-w-0 max-w-full`: a trigger must never outgrow its container
@@ -222,58 +93,62 @@ export function Select({ value, onChange, options, size = 'default', ariaLabel,
       >
         <span className={cn('flex min-w-0 items-center gap-2', !selected && 'text-text-muted')}>
           {selected?.leading && <span className="flex shrink-0 items-center">{selected.leading}</span>}
-          <span className="truncate">{selected?.label ?? placeholder}</span>
+          <BaseSelect.Value className="truncate">{() => selected?.label ?? placeholder}</BaseSelect.Value>
         </span>
-        <IconChevronDown size={size === 'small' ? 14 : 16} stroke={1.5} className="shrink-0 text-text-secondary" />
-      </button>
+        <BaseSelect.Icon
+          render={<IconChevronDown size={size === 'small' ? 14 : 16} stroke={1.5} className="shrink-0 text-text-secondary" />}
+        />
+      </BaseSelect.Trigger>
 
-      {open &&
-        rect &&
-        createPortal(
-          <div
-            ref={menuRef}
-            role="listbox"
-            aria-activedescendant={`${id}-${activeIndex}`}
-            tabIndex={-1}
-            style={
-              placement
-                ? { ...placement, minWidth: rect.width }
-                : // Provisional frame: measured by the layout effect above,
-                  // replaced before paint. Hidden so a cut-off position is
-                  // never visible, not even for a frame.
-                  { top: rect.bottom + 4, left: rect.left, minWidth: rect.width, visibility: 'hidden' }
-            }
-            className="fixed z-50 overflow-y-auto rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
+      <BaseSelect.Portal>
+        <BaseSelect.Positioner
+          side="bottom"
+          align="start"
+          sideOffset={GAP}
+          collisionPadding={VIEWPORT_PAD}
+          /* D24: hang the list under the trigger, as it always has, rather
+             than laying it over the trigger with the chosen option on top. */
+          alignItemWithTrigger={false}
+          /*
+           * The list follows its trigger now rather than closing when the page
+           * scrolls — it was `fixed` to where the trigger had been, so closing
+           * was the only way it could avoid being left behind. `anchor-hidden`
+           * is the other half of that: when the trigger scrolls out of view
+           * entirely the list goes with it, instead of floating over whatever
+           * has scrolled into its place.
+           */
+          className="z-50 data-[anchor-hidden]:hidden"
+        >
+          <BaseSelect.Popup
+            /* `--anchor-width` is the trigger's width and `--available-height`
+               the room the list actually has after Floating UI has flipped and
+               clamped it — the two numbers `fitMenu` used to compute here. The
+               288px is the old `max-h-72`, now a ceiling on that room rather
+               than a height applied blind. */
+            className="max-h-[min(288px,var(--available-height))] min-w-[var(--anchor-width)] overflow-y-auto rounded-lg border border-border-default bg-bg-elevated p-1 shadow-lg"
           >
-            {options.map((option, index) => (
-              <div
+            {options.map((option) => (
+              <BaseSelect.Item
                 key={option.value}
-                id={`${id}-${index}`}
-                role="option"
-                aria-selected={option.value === value}
-                onMouseEnter={() => setActiveIndex(index)}
-                onMouseDown={(e) => {
-                  // The document-level dismiss also listens on mousedown.
-                  e.preventDefault()
-                  pick(index)
-                }}
-                className={cn(
-                  'flex h-9 cursor-pointer items-center justify-between gap-2 rounded-lg px-3 transition-colors',
-                  'text-[14px] font-normal leading-[1.4] text-text-primary',
-                  index === activeIndex && 'bg-bg-hover',
-                  option.value === value && 'font-medium',
-                )}
+                value={option.value}
+                /* The highlight is Base UI's `data-highlighted` — pointer and
+                   keyboard set the same attribute, so what the DOM says and
+                   what the row looks like cannot disagree. It used to be an
+                   index this component counted. */
+                className="flex h-9 cursor-pointer items-center justify-between gap-2 rounded-lg px-3 text-[14px] font-normal leading-[1.4] text-text-primary transition-colors data-[highlighted]:bg-bg-hover data-[selected]:font-medium"
               >
                 <span className="flex min-w-0 items-center gap-2">
                   {option.leading && <span className="flex shrink-0 items-center">{option.leading}</span>}
-                  <span className="truncate">{option.label}</span>
+                  <BaseSelect.ItemText className="truncate">{option.label}</BaseSelect.ItemText>
                 </span>
-                {option.value === value && <IconCheck size={16} stroke={1.5} className="shrink-0 text-text-secondary" />}
-              </div>
+                <BaseSelect.ItemIndicator
+                  render={<IconCheck size={16} stroke={1.5} className="shrink-0 text-text-secondary" />}
+                />
+              </BaseSelect.Item>
             ))}
-          </div>,
-          document.body,
-        )}
-    </>
+          </BaseSelect.Popup>
+        </BaseSelect.Positioner>
+      </BaseSelect.Portal>
+    </BaseSelect.Root>
   )
 }

package/src/Sidebar.mdx

@@ -36,14 +36,18 @@ the caller's — this is the shell.
 import { Sidebar, NavItem, SectionLabel } from '@estiva-app/ui'
 
 <Sidebar>
-  <NavItem href="#/documents" label="Documents" active />
+  <NavItem href="/documents" label="Documents" active />
   <div className="mt-2 flex h-8 shrink-0 items-center px-2">
     <SectionLabel>Collections</SectionLabel>
   </div>
-  <NavItem href="#/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
+  <NavItem href="/collections/12" label="Quarterly plan" count={7} countLabel="7 open" />
 </Sidebar>
 ```
 
+**Every row is a plain anchor, so in a router app each click would reload
+the page.** Keep NavItem's rule: a thin wrapper computes `active` from the
+location, intercepts the click and navigates in place — see **NavItem**.
+
 Anything you place directly in the column needs `shrink-0` (the heading
 row above carries it): the column scrolls on overflow, and a flex child
 without it gets compressed instead — rows must keep their height.

package/src/Tabs.mdx

@@ -49,6 +49,11 @@ import { Tabs } from '@estiva-app/ui'
   Wiring the panels — what shows for the active tab — is the caller's.
 - `className` lands on the outer box, around the row.
 
+- **Name the row** with `aria-label` where an app has more than one, or where
+  a screen reader would otherwise announce two "tab lists". A visible heading
+  that already names it takes `aria-labelledby` instead. Unnamed is fine for
+  the only tab row on a page.
+
 ## Keys
 
 | Key | Does |

package/src/Tabs.test.tsx

@@ -108,6 +108,21 @@ describe('Tabs', () => {
     expect(screen.getAllByRole('tab').map((t) => t.getAttribute('aria-selected'))).toEqual(['false', 'false', 'false'])
   })
 
+  /** A `tablist` with no name is announced as a bare "tab list" — and says the
+   *  same nothing twice on a page with two of them. There was no way to give
+   *  one until 2026-09-08. */
+  it('names the row when the caller gives it a name', () => {
+    render(<Tabs tabs={THREE} active="one" onChange={() => {}} aria-label="Views" />)
+    expect(screen.getByRole('tablist', { name: 'Views' })).toBeTruthy()
+  })
+
+  it('and has no name when nobody gives it one, rather than a wrong one', () => {
+    render(<Tabs tabs={THREE} active="one" onChange={() => {}} />)
+    const list = screen.getByRole('tablist')
+    expect(list.getAttribute('aria-label')).toBeNull()
+    expect(list.getAttribute('aria-labelledby')).toBeNull()
+  })
+
   it('puts className on the outer box, around the row', () => {
     const { container } = render(<Tabs tabs={THREE} active="one" onChange={() => {}} className="mt-4" />)
     const outer = container.firstElementChild as HTMLElement

package/src/Tabs.tsx

@@ -34,11 +34,21 @@ export interface TabsProps<T extends string> {
   onChange: (id: T) => void
   /** `default` 14px; `small` 12px, the denser geometry. */
   size?: 'default' | 'small'
+  /**
+   * Names the row for assistive tech — "Views", "Filters".
+   *
+   * A `tablist` with no name is announced as a bare "tab list", which says
+   * nothing and says the same nothing twice on a page with two of them
+   * (measured 2026-09-08: no name, and no way to give one). Where a visible
+   * heading already names it, point at that with `aria-labelledby` instead.
+   */
+  'aria-label'?: string
+  'aria-labelledby'?: string
   /** Lands on the outer box, around the row. */
   className?: string
 }
 
-export function Tabs<T extends string>({ tabs, active, onChange, size = 'default', className }: TabsProps<T>) {
+export function Tabs<T extends string>({ tabs, active, onChange, size = 'default', className, ...aria }: TabsProps<T>) {
   return (
     <BaseTabs.Root
       value={active}
@@ -50,7 +60,12 @@ export function Tabs<T extends string>({ tabs, active, onChange, size = 'default
       }}
       className={className}
     >
-      <BaseTabs.List activateOnFocus className="flex items-center gap-2">
+      <BaseTabs.List
+        activateOnFocus
+        aria-label={aria['aria-label']}
+        aria-labelledby={aria['aria-labelledby']}
+        className="flex items-center gap-2"
+      >
         {tabs.map((tab) => (
           <BaseTabs.Tab
             key={tab.id}

package/src/TextInput.mdx

@@ -30,8 +30,14 @@ import { TextInput } from '@estiva-app/ui'
 ```
 
 - It is a native `<input>` with a ref — every native prop passes through.
-- Name it: a Field's label is visual, so give the input an `aria-label`
-  too.
+  Base UI's `Input` since stage 3, which is what finds a surrounding
+  `Field`.
+- **Inside a `Field`, the label names it. Add nothing.** This page said the
+  opposite until stage 3 — "a Field's label is visual, so give the input an
+  `aria-label` too" — and that advice was already stale at SHA-17. An
+  `aria-label` there is now ignored, because the label wins.
+- **Outside a `Field`, name it yourself** with `aria-label`: a placeholder
+  is not a name.
 - `disabled` gets the disabled surface and text; say why with a tooltip.
 
 ## Props

package/src/TextInput.tsx

@@ -1,23 +1,26 @@
 import { forwardRef, type InputHTMLAttributes } from 'react'
+import { Input } from '@base-ui/react/input'
 import { cn } from './cn'
-import { useFieldControlId } from './Field'
 
 /**
  * Peek's TextInput (2026-08-28): the inset field with a 8px radius, 14px
  * text, the focus border in every theme (Katerina, 2026-08-28: Ship's inputs
  * focus like Signal's) — and Signal's glow on top.
  * Plus a disabled look (Ship's addition): the disabled surface and text,
- * no pointer.
+ * no pointer. On Base UI's `Input` since stage 3 of the migration
+ * (2026-09-07).
+ *
+ * Base UI's `Input` is a native `<input>` that finds a surrounding `Field` on
+ * its own, so the id plumbing this used to do — `useFieldControlId`, and the
+ * context behind it — is gone. Outside a `Field` it behaves as before: the
+ * field context has a default, so nothing has to be wrapped.
  */
 export type TextInputProps = InputHTMLAttributes<HTMLInputElement>
 
-export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(function TextInput({ className, type = 'text', id, ...props }, ref) {
-  // A surrounding Field names this control (SHA-17); an explicit id still wins.
-  const controlId = useFieldControlId(id)
+export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(function TextInput({ className, type = 'text', ...props }, ref) {
   return (
-    <input
+    <Input
       ref={ref}
-      id={controlId}
       type={type}
       className={cn(
         'bg-bg-inset border border-border-default focus:border-border-focus rounded-lg px-3 py-2',

package/src/Textarea.mdx

@@ -28,8 +28,12 @@ import { Textarea } from '@estiva-app/ui'
 ```
 
 - Resizing is off by design — size it with `rows` or your layout.
-- Native `<textarea>` with a ref; every native prop passes through; give
-  it an accessible name.
+- Native `<textarea>` with a ref; every native prop passes through. It is
+  Base UI's `Field.Control` told to render a textarea since stage 3 — the
+  part `Input` is built on — because Base UI has an `Input` and no
+  textarea.
+- **Inside a `Field`, the label names it. Add nothing.** Outside one, give
+  it an `aria-label`.
 
 ## Props
 

package/src/Textarea.tsx

@@ -1,20 +1,25 @@
 import { forwardRef, type TextareaHTMLAttributes } from 'react'
+import { Field as BaseField } from '@base-ui/react/field'
 import { cn } from './cn'
-import { useFieldControlId } from './Field'
 
 /**
  * Peek's Textarea (2026-08-28), verbatim: TextInput's look on a textarea
- * that does not resize. Plus a disabled look (Ship's addition).
+ * that does not resize. Plus a disabled look (Ship's addition). On Base UI's
+ * `Field.Control` since stage 3 of the migration (2026-09-07).
+ *
+ * Base UI has an `Input` part but no textarea, so this is `Field.Control`
+ * rendering a `<textarea>` — the same part `Input` is built on, told which
+ * element to be. It finds a surrounding `Field` on its own, which is what
+ * retired `useFieldControlId`; outside one it renders a plain textarea, as
+ * before.
  */
 export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>
 
-export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea({ className, id, ...props }, ref) {
-  // A surrounding Field names this control (SHA-17); an explicit id still wins.
-  const controlId = useFieldControlId(id)
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea({ className, ...props }, ref) {
   return (
-    <textarea
-      ref={ref}
-      id={controlId}
+    <BaseField.Control
+      ref={ref as React.Ref<HTMLElement>}
+      render={<textarea />}
       className={cn(
         'bg-bg-inset border border-border-default focus:border-border-focus rounded-lg px-3 py-2',
         'text-[14px] leading-[1.4] font-normal text-text-primary placeholder:text-text-muted',
@@ -23,7 +28,7 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
         'signal:transition-shadow signal:focus:shadow-focus-ring',
         className,
       )}
-      {...props}
+      {...(props as object)}
     />
   )
 })

package/src/Toolbar.mdx

@@ -0,0 +1,104 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ToolbarStories from './Toolbar.stories'
+
+<Meta of={ToolbarStories} />
+
+# Toolbar
+
+A strip of controls that behaves as **one** control: Tab in, arrow keys along,
+Tab out — on the elevated box a floating strip needs.
+
+<Canvas of={ToolbarStories.Default} />
+
+## When
+
+- **Any row of icon buttons that act on the same thing** — a formatting strip,
+  a card's actions, a set of view switches. This is the case it exists for.
+- A row that mixes buttons with a field, like a link editor: the field is
+  **ToolbarInput** and keeps the arrow keys for its caret.
+- Groups of those, divided by **ToolbarSeparator**.
+
+<Canvas of={ToolbarStories.Grouped} />
+
+## When not
+
+- A list of verbs you open, choose from, and close → **Menu**.
+- Two answers to a question — Cancel and Save — → plain **Button**s. They are
+  separate answers and each deserves its own Tab stop.
+- Reactions to choose from → **ReactionPicker**, which is this with the
+  emoji row already drawn.
+- One value from a set → **Select**.
+
+## How
+
+```tsx
+import { Toolbar, ToolbarButton, ToolbarSeparator } from '@estiva-app/ui'
+
+<Toolbar aria-label="Formatting">
+  <ToolbarButton aria-label="Bold" tooltip="Bold" tooltipShortcut="Cmd+B" onClick={bold}>
+    <IconBold size={16} stroke={1.5} />
+  </ToolbarButton>
+  <ToolbarSeparator />
+  <ToolbarButton aria-label="Link" tooltip="Link" onClick={link}>
+    <IconLink size={16} stroke={1.5} />
+  </ToolbarButton>
+</Toolbar>
+```
+
+- **`aria-label` is required.** A toolbar with no name is announced as a bare
+  "toolbar", which says nothing — and says the same nothing twice on a page
+  with two.
+- **`ToolbarButton` is this package's `IconButton`**, joined to the walk: the
+  same square, the same variants, the same `tooltip`, `tooltipShortcut` and
+  `disabledReason`. It still owes an `aria-label`, because it is still an
+  icon-only control. **It must be inside a `Toolbar`** — Base UI throws
+  otherwise, since a part with no strip has no walk to join. A control *beside*
+  a strip is an `IconButton`.
+- **It draws the box** — see below — and `surface={false}` drops it.
+- **A disabled control keeps its place in the walk.** A strip whose controls
+  come and go from the arrow keys as their state changes is a strip you cannot
+  learn, and a `disabledReason` you cannot reach is a reason nobody reads.
+- **`orientation="vertical"`** walks with ↑ and ↓ instead.
+
+<Canvas of={ToolbarStories.WithAField} />
+
+<Canvas of={ToolbarStories.WithADisabledControl} />
+
+### The box
+
+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`.
+
+`surface={false}` for a strip inside something that draws that box already — a
+`Popover`, a dialog, a card's own panel.
+
+**A `Popover` holding a toolbar asks for `side="top"`.** A strip acts on what
+is under it, so it stands over that rather than on top of it. That is a
+preference: Base UI measures the room and flips when there is none, which is
+why the placement is its job and not arithmetic of ours.
+
+<Canvas of={ToolbarStories.OnAnExistingSurface} />
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Tab | onto the strip — once, wherever the walk left it |
+| ← / → | move between controls, and wrap at the ends (↑ / ↓ when vertical) |
+| Enter / Space | the focused control's own action |
+| Tab again | leaves the strip entirely |
+| ← / → **inside a `ToolbarInput`** | the caret's, not the strip's — Tab resumes the walk |
+
+**Home and End do nothing**, and that is Base UI's choice rather than an
+oversight: its composite implements them behind a flag `Toolbar.Root` does not
+pass. The arrows wrap, which reaches both ends in one press of a strip this
+size. A test pins it, so the day it changes this page is wrong on purpose.
+
+<Canvas of={ToolbarStories.Vertical} />
+
+## Props
+
+<Controls of={ToolbarStories.Default} />