@estiva-app/ui 0.23.0 → 0.24.1

package/src/Button.mdx

@@ -6,7 +6,7 @@ import * as ButtonStories from './Button.stories'
 # Button
 
 The push-button for an action: a verb, clicked once — "Create", "Save",
-"Delete project". Four variants on one geometry: 32px default / 24px small,
+"Delete". Four variants on one geometry: 32px default / 24px small,
 6px radius, medium weight.
 
 <Canvas of={ButtonStories.AllVariants} />
@@ -27,12 +27,13 @@ The push-button for an action: a verb, clicked once — "Create", "Save",
 ## When not
 
 - An icon with no label → **IconButton**.
-- Going somewhere rather than doing something → **Tabs**, **Breadcrumb**,
-  or a plain link.
+- Going somewhere rather than doing something → **Link**; **Tabs** or
+  **Breadcrumb** when it is a view or a trail.
 - Choosing a value → **Select**. Acting from a popover list → **MenuItem**.
 - A control the person may never be allowed to use is **absent, not
   disabled**. `disabled` is for *momentarily* unavailable — and it says why,
-  with `disabledReason` ("Available after sign-in").
+  with `disabledReason` ("Available after sign-in"). A send button waiting for
+  its fields needs no reason.
 
 ## How
 
@@ -66,7 +67,18 @@ import { IconPlus } from '@tabler/icons-react'
   has the same look.
 - **Placed from outside, never restyled.** `className` takes space, size,
   flex and grid, and position; a colour, a text size, a border, a corner or a
-  shadow is refused by the lint (`estiva/no-restyled-part`, UIG-9).
+  shadow is refused by the lint (`estiva/no-restyled-part`).
+
+## 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 button | `role="button"` | ✓ |
+| Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
+| Presses on Enter and Space, and does nothing while disabled | a key handler |  |
+| Keeps its 32px (24px small) in a scrolling column | `shrink-0` |  |
 
 ## Keys
 

package/src/Button.tsx

@@ -86,8 +86,8 @@ export function Button({
           // this package's own story frames, each of which asks for the top.
           // A control does not get to decide where its caller puts it.
           'inline-flex items-center justify-center gap-1 rounded-md transition-colors font-sans font-medium',
-          size === 'default' && 'h-8 text-btn-default',
-          size === 'small' && 'h-6 text-btn-small',
+          size === 'default' && 'h-8 min-h-8 text-btn-default',
+          size === 'small' && 'h-6 min-h-6 text-btn-small',
           // Extra right padding beside a leading icon, for optical balance.
           size === 'default' && (hasLeadingIcon ? 'pl-2 pr-3' : 'px-2'),
           size === 'small' && (hasLeadingIcon ? 'pl-1.5 pr-2' : 'px-1.5'),

package/src/Card.mdx

@@ -12,6 +12,8 @@ hairline. What goes inside, and the space around it, is yours.
 
 ## When
 
+- **It draws no padding and no layout**: both are yours.
+
 A box is a card when it stands for **one thing you could name**, and there are
 many of it or you treat the whole box as that thing — open it, point at it,
 move it.
@@ -73,9 +75,20 @@ import { Card } from '@estiva-app/ui'
   picture that runs edge to edge. Without it their square corners show.
 - **Placed from outside, never restyled.** `className` takes space, size,
   flex and grid, and position; a colour, a text size, a border, a corner or a
-  shadow is refused by the lint (`estiva/no-restyled-part`, UIG-9). What is inside the card is yours: its padding and its words go on
+  shadow is refused by the lint (`estiva/no-restyled-part`). What is inside the card is yours: its padding and its words go on
   your own element inside.
 
+- **Planned:** the inside layout of a linked object's card, in migration stage 7.
+
+## 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 `href`, becomes a link: Link's anchor, with a real address | an anchor around the card |  |
+| Without `href`, shows it can be clicked when you pass `onClick` | `cursor-pointer` |  |
+
 ## Props
 
 <Controls of={CardStories.Surface} />

package/src/Checkbox.mdx

@@ -79,6 +79,17 @@ import { Checkbox } from '@estiva-app/ui'
 - It does not move when it toggles: the tick is always in the box, hidden
   when unchecked, so both states hang on a line of text the same way.
 
+## 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 checkbox, ticked or not | `role="checkbox"` or `aria-checked` | ✓ |
+| Toggles on Space and on a click; Enter is left to the form | a click or key handler |  |
+| Is one Tab stop, in a `row` too | a `tabIndex` on the row |  |
+| Keeps a `row`'s 40px in a scrolling column | `shrink-0` |  |
+
 ## Keys
 
 | Key | Does |

package/src/Chip.mdx

@@ -38,6 +38,10 @@ import { Chip } from '@estiva-app/ui'
   it never rides the text baseline.
 - A count alone works too — `label="3"`, no icon.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={ChipStories.Neutral} />

package/src/ChipInput.mdx

@@ -66,7 +66,7 @@ import { ChipInput } from '@estiva-app/ui'
 ```
 
 - **`InputChip` on its own** names its ✕ `Remove <label>`. Where the ✕ does
-  something else, say what with `removeLabel` (a scope chip: "Leave Ship").
+  something else, say what with `removeLabel` (a chip for a group you belong to: "Leave Design").
 - To cap a long label, give the chip a `max-w-*` and `truncate`: the label is
   cut and the ✕ keeps its size. `truncate` is off unless asked, because
   cutting clips a letter's soft edge by up to 4px at 1x even when the label
@@ -74,6 +74,18 @@ import { ChipInput } from '@estiva-app/ui'
 
 <Canvas of={ChipInputStories.ALongLabelCut} />
 
+## 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: its suggestions | a portal, or a `z-index` to win | ✓ |
+| Moves through its items with the arrow keys, through the suggestions | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a combobox and its options | `role="combobox"`, `listbox` or `option` | ✓ |
+| Filters as you type; Enter adds the highlighted entry, Backspace on an empty query removes the last chip | a filter, or key handlers |  |
+| Escape clears the query first, and only then lets the surface around it act | an Escape handler |  |
+
 ## Keys
 
 | Input | What happens |

package/src/CollapsibleSection.mdx

@@ -14,11 +14,11 @@ toggle, and the rows under it, sliding shut and open.
 ## When
 
 - A group of rows in a sidebar or a panel that the reader may want out of
-  the way — projects, folders, starred items.
+  the way — starred items, recent places.
 - `defaultOpen={false}` for a group that starts folded.
 - `storageKey` when the section should stay how the reader left it across
   reloads: this browser remembers, under that key. The app prefixes the
-  key (`ship.sidebar.projects`).
+  key (`app.sidebar.starred`).
 - `open` + `onOpenChange` when the app owns the state.
 - `actions` for add, sort, filter beside the title — SectionHeader's,
   revealed on hover or focus.
@@ -41,7 +41,7 @@ composition lives:
 ```tsx
 import { CollapsibleSection, NavItem } from '@estiva-app/ui'
 
-<CollapsibleSection title="Projects" storageKey="app.sidebar.projects" className="mt-2 shrink-0" contentClassName="gap-px">
+<CollapsibleSection title="Starred" storageKey="app.sidebar.starred" className="mt-2 shrink-0" contentClassName="gap-px">
   <NavItem href="/p/1" label="Item one" />
   <NavItem href="/p/2" label="Item two" />
 </CollapsibleSection>
@@ -60,6 +60,15 @@ import { CollapsibleSection, NavItem } from '@estiva-app/ui'
   with `open`.
 - A browser that blocks storage still gets a working section; it forgets.
 
+## 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 |
+|---|---|---|
+| Opens and closes from its title, on a click, Enter or Space | open state, or a key handler |  |
+| Tells assistive technology whether it is open | `aria-expanded` |  |
+
 ## Keys
 
 | Key | Does |

package/src/CommandPalette.mdx

@@ -49,8 +49,8 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
     onQueryChange={setQuery}
     placeholder="Search, or choose a place"
     groups={[
-      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: open, onForget: forget }] },
-      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon, onSelect: goIn, onGoIn: goIn }] },
+      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: openItem, onForget: forget }] },
+      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: goIn, onGoIn: goIn }] },
     ]}
   />
 </CommandPalette>
@@ -102,6 +102,18 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 - **Focus never falls out of a level.** When the element that had it goes — a
   row picked, a level swapped — focus goes to the level's first control.
 
+## 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 | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, or a Tab handler | ✓ |
+| Moves through its items with the arrow keys, through the rows, stopping at the ends | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a list of options you search | `role="combobox"`, `listbox` or `option` | ✓ |
+| Closes on Esc or a click outside; Esc closes an open list first | close handlers |  |
+
 ## Keys
 
 | Where | Input | What happens |

package/src/ConfirmDialog.mdx

@@ -45,7 +45,7 @@ import { ConfirmDialog } from '@estiva-app/ui'
   dialog open — your surface has said why; a resolved `void`/`true`
   closes it.
 - **Escape cancels; a press on the backdrop does not.** This is Base UI's
-  `AlertDialog`, through the shell's `alert` (Katerina, D20, 2026-09-07): a
+  `AlertDialog`, through the shell's `alert`: a
   destructive question is answered rather than clicked away. The backdrop
   used to cancel, and that is the one behaviour stage 3 deliberately changed.
 - It announces itself as an alert (`role="alertdialog"`), so a screen reader
@@ -53,6 +53,17 @@ import { ConfirmDialog } from '@estiva-app/ui'
 - Focus is trapped in the card and returns to whatever opened it, as for
   every dialog since stage 3.
 
+## 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 dialog that must be answered | `role="alertdialog"` | ✓ |
+| Keeps focus inside while open, as DialogShell does, and gives it back to whatever opened it | focus code |  |
+| Ignores a press outside, because the question has to be answered; Escape cancels | a backdrop handler |  |
+
 ## Keys
 
 Different from `DialogShell`'s in one row, and it is the row that matters.
@@ -60,7 +71,7 @@ Different from `DialogShell`'s in one row, and it is the row that matters.
 | Input | What happens |
 |---|---|
 | Escape | cancels |
-| backdrop click | **nothing** — the question has to be answered (D20) |
+| backdrop click | **nothing** — the question has to be answered |
 | close button | cancels |
 | Tab / Shift+Tab | cycles the controls inside the card, and cannot leave it |
 | on close | focus returns to whatever opened it |

package/src/ContainerHeader.mdx

@@ -7,8 +7,7 @@ import * as ContainerHeaderStories from './ContainerHeader.stories'
 
 The bar across the top of a column — a list, a thread, a side panel: its
 title, and the buttons that act on the whole column at the right edge. 48px,
-with a hairline under it. Peek's ContainerHeader, moved into the package as it
-looks (Katerina, 2026-09-18).
+with a hairline under it.
 
 <Canvas of={ContainerHeaderStories.WithActions} />
 
@@ -26,6 +25,11 @@ looks (Katerina, 2026-09-18).
 - The top of the whole app → **TopBar**.
 - A dialog's title → **DialogShell** draws its own.
 
+- A row you draw yourself at the top of a column — your own padding and a line
+  under it → this part. Its numbers are every column's.
+- A whole list column, header and scrolling list → **ListColumn**, which draws
+  this bar at its top.
+
 ## How
 
 ```tsx
@@ -51,6 +55,15 @@ import { ContainerHeader, IconButton } from '@estiva-app/ui'
 - Only offer a button that does something: a button with nothing behind it is
   a promise the column cannot keep.
 
+## 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 |
+|---|---|---|
+| Draws the column's bar: 48px tall, the title 20px in at 14px medium, the actions 16px from the right, a hairline under it | a row of your own with padding and a border |  |
+| Keeps its 48px in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={ContainerHeaderStories.Default} />

package/src/DialogShell.mdx

@@ -28,6 +28,7 @@ footer for the buttons. A dialog is just what goes in the three slots.
   dialog rebuilt by hand, which is the one thing this bullet exists to stop.
   Its canvases and its nine tests are on that page.
 - Telling someone what happened → **Toast**.
+- Searching for something and acting on it → **CommandPalette**.
 
 ## How
 
@@ -70,9 +71,22 @@ import { DialogShell, Button } from '@estiva-app/ui'
   worth setting where typing is the point — the trap decides where focus
   *cannot* go, not where it starts.
 - `alert` for a question that has to be answered: a press on the backdrop
-  stops closing it (Katerina, D20). Escape and the ✕ still do.
+  stops closing it. Escape and the ✕ still do.
   `ConfirmDialog` sets it; a form or a roster should not.
 
+## 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 | ✓ |
+| Closes on a press outside, except with `alert` | a click listener on the page | ✓ |
+| Takes its keys by itself: Escape closes it | a key listener on the page | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, or a Tab handler | ✓ |
+| Stops the page behind it scrolling | `overflow: hidden` on the page | ✓ |
+| Says what it is to assistive technology: a dialog | `role="dialog"` | ✓ |
+
 ## Keys
 
 | Input | What happens |

package/src/Divider.mdx

@@ -16,7 +16,7 @@ orientation for assistive tech.
 
 - Between groups in a **Menu** (`className="my-1"` gives it its breathing
   room there).
-- Between sections of a panel or rail.
+- Between sections of a panel, a rail or a card.
 - Vertical: between clusters in a toolbar or a dense row.
 
 <Canvas of={DividerStories.Vertical} />
@@ -49,6 +49,17 @@ import { Divider } from '@estiva-app/ui'
 - **Inside a `Menu` or a `Popover` it has no inset**: the hairline runs the
   width of the rows. The panel tells it so; nothing is passed in.
 
+- The line is 1px; the room around it is yours (`my-1` in a Menu).
+
+## 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 separator | `role="separator"` | ✓ |
+| Keeps its 1px line in a scrolling column | `shrink-0` |  |
+
 ## Props
 
 <Controls of={DividerStories.Default} />

package/src/EditableText.mdx

@@ -13,6 +13,9 @@ edit is never silently lost.
 
 ## When
 
+- **It has no size of its own.** Give it the size of the text it stands in for —
+  a pane title's `text-body-2-strong` — on your element around it; the text and
+  the field both take it.
 - A title or description edited where it is shown — no dialog, no separate
   form.
 - A reader who cannot write gets `readOnly` — the value without the edit
@@ -23,6 +26,8 @@ edit is never silently lost.
 - A field in a form or dialog → **TextInput** / **Textarea** in a
   **Field**.
 - Composing something new → the field, not an edit-in-place of nothing.
+- An edit that publishes something, like a message → **Textarea** with Save
+  and Cancel. EditableText saves when you leave it.
 
 ## How
 
@@ -53,7 +58,18 @@ import { EditableText } from '@estiva-app/ui'
 - **Its text size is where it sits**, like `Person`'s: put `text-h2` on your own
   element around it, and the text and the field both take it (a field inherits
   the page's font). `className` places it — `-mx-2` to line its text up with
-  a header's inset — and a size passed there is refused by the lint (UIG-9).
+  a header's inset — and a size passed there is refused by the lint.
+
+- **Planned:** rich text edited where it is shown (UIG-30).
+
+## 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 |
+|---|---|---|
+| Opens its field on a click, with the value selected | an edit mode of your own |  |
+| Enter and leaving the field save; Escape cancels and puts the value back (`multiline`: Shift+Enter is a new line) | key or blur handlers |  |
 
 ## Keys
 

package/src/EmptyState.mdx

@@ -36,10 +36,12 @@ need a height from the caller (`className="h-full"`).
 
 ## When not
 
-- Data is still on its way → **Skeleton**; empty and loading are
-  different truths.
-- Something went wrong → say that, in your surface's own error treatment
-  — an empty state that hides a failure misleads.
+- Data is still on its way → **Skeleton**; empty and loading are different
+  truths. When the shape of what arrives is unknown, an EmptyState that says so
+  — "Opening…" — is fine.
+- Something went wrong → say what failed, in words. An EmptyState can carry
+  it, in its usual look — never red. An empty state that hides a failure
+  misleads.
 
 ## How
 
@@ -55,14 +57,14 @@ import { EmptyState } from '@estiva-app/ui'
 
 **When there is one thing to do about it, give it as `action`.** It is drawn
 16px under the line as the package's Button, outlined — the same look wherever
-it appears (Katerina, 2026-09-18). Never put a Button beside an EmptyState in a
+it appears. Never put a Button beside an EmptyState in a
 box of your own: the box places it, and no two boxes place it alike. A `page`
 only; a section's line takes no action.
 
 <Canvas of={EmptyStateStories.WithAction} />
 
 ```tsx
-<EmptyState icon={<IconMessagePlus size={16} stroke={1.5} />} message="No topics yet." action={{ label: 'New topic', onClick: openNewTopic }} />
+<EmptyState icon={<IconMessagePlus size={16} stroke={1.5} />} message="Nothing here yet." action={{ label: 'Create', onClick: create }} />
 ```
 
 **Put a section's empty state inside the box its rows live in, and give it no
@@ -83,6 +85,15 @@ The message is the caller's — a shared component has no words of its own
 for what is missing. A hand-written "Nothing here" paragraph or span in a
 section is the `section` manner, and becomes 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 |
+|---|---|---|
+| As a `page`, fills the room it is given and centres itself in it | centring, or padding around it |  |
+| Draws its one action, an outlined Button, under the line when you pass `action` | a button of your own under the line |  |
+
 ## Props
 
 <Controls of={EmptyStateStories.Page} />

package/src/Field.mdx

@@ -19,7 +19,7 @@ token; `required` marks it with the error-coloured asterisk.
 
 - Displaying a label–value pair → **Property**; Field is for editing.
 - The line belongs to a **group** of controls rather than to one — a value
-  with Save beside it, a row of action controls → **Field line**, the same
+  with Save beside it, a row of action controls → **FieldLine**, the same
   small line on its own.
 
 ## How
@@ -43,18 +43,26 @@ import { Field, TextInput } from '@estiva-app/ui'
   reversed at stage 3: the Field used to win and override it.
 - `helper` is the line under the control — the format, or what happens if
   it is left empty. `error` **replaces** it and marks the control invalid,
-  so you no longer pass `aria-invalid` yourself. Both are announced;
-  Ship and Peek wrote this line by hand six times between them, and none of
-  those was.
+  so you no longer pass `aria-invalid` yourself. Both are announced; a line
+  written by hand beside the control is not.
 - With neither, the control stays a direct child of the field, so nothing
   that predates the two props moved a pixel.
 - **`required` marks the control as well as the label.** The asterisk is a
   picture of the requirement; `aria-required` on the control is the word for
-  it, and the control had neither until 2026-09-08 — measured. Base UI's
+  it. Base UI's
   `Field` has no `required` of its own, so the Field puts it there. A control
   that says so already is left alone, and a `children` of several elements
   keeps the asterisk and owes its own.
 
+## 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 |
+|---|---|---|
+| Ties the label, the description and the error to the control inside it | `aria-label`, an `id` / `htmlFor` pair, or `aria-describedby` |  |
+| Marks the control invalid when it has an `error`, and announces it | `aria-invalid` |  |
+
 ## Props
 
 <Controls of={FieldStories.Default} />

package/src/FieldLine.mdx

@@ -32,7 +32,7 @@ import { FieldLine } from '@estiva-app/ui'
 
 <div className="flex flex-col gap-1.5">
   <div className="flex items-center gap-2">
-    <TextInput value={draft} onChange={…} />
+    <TextInput value={draft} onChange={(e) => setDraft(e.target.value)} />
     <Button variant="primary" size="small">Save</Button>
   </div>
   {outcome && <FieldLine tone={outcome.kind}>{outcome.message}</FieldLine>}
@@ -52,6 +52,14 @@ import { FieldLine } from '@estiva-app/ui'
 - The three tones are the same two classes Field draws, from one map in
   `Field.tsx`, so they cannot drift.
 
+## 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: an alert for an error, a status for the rest | `role="alert"` or `role="status"` | ✓ |
+
 ## Props
 
 <Controls of={FieldLineStories.Helper} />

package/src/FilePicker.mdx

@@ -44,6 +44,14 @@ const picker = useRef<HTMLInputElement>(null)
   nothing to reset afterwards.
 - `data-*` attributes pass on to the input, for a test to find 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 |
+|---|---|---|
+| Opens the system's file picker from its button, and keeps the real file input out of Tab and screen readers | a hidden `<input type="file">` |  |
+
 ## Props
 
 <Controls of={FilePickerStories.Default} />

package/src/Form.mdx

@@ -58,9 +58,19 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
 - `className` places the fields: the form draws no box, and neither does the
   `<fieldset>` inside 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 |
+|---|---|---|
+| Sends on Enter in a one-line field, and on Ctrl+Enter anywhere inside | a key handler that submits |  |
+| Leaves Enter alone where it means something else: a Textarea, a list, a people picker | exceptions of your own |  |
+| Does nothing while it is sending: no second send, and nothing inside takes focus | a busy flag on every control |  |
+
 ## Keys
 
-The same in every form (Katerina, 16 September).
+The same in every form.
 
 | Key | Does |
 |---|---|

package/src/Form.test.tsx

@@ -18,6 +18,7 @@ import { Checkbox } from './Checkbox'
 import { IconButton } from './IconButton'
 import { Field } from './Field'
 import { Form } from './Form'
+import { Popover } from './Popover'
 import { TextInput } from './TextInput'
 import { Textarea } from './Textarea'
 
@@ -46,6 +47,31 @@ describe('Form', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  it('a Form in a Popover inside a Form sends only itself (C1)', async () => {
+    // A link field in a pop-up over a composer: Enter there adds the link, and
+    // must not also send the message around it. React carries the submit
+    // through the Popover's portal to the outer form.
+    const user = userEvent.setup()
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <Form onSubmit={outer}>
+        <TextInput aria-label="Message" />
+        <Popover trigger={<Button>Link</Button>} open ariaLabel="Link">
+          <Form onSubmit={inner}>
+            <TextInput aria-label="Address" />
+          </Form>
+        </Popover>
+      </Form>,
+    )
+    await user.type(screen.getByRole('textbox', { name: 'Address' }), 'example.com{Enter}')
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+    await user.type(screen.getByRole('textbox', { name: 'Message' }), 'hi{Enter}')
+    expect(outer).toHaveBeenCalledTimes(1)
+    expect(inner).toHaveBeenCalledTimes(1)
+  })
+
   it('sends from its submit button', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()

package/src/Form.tsx

@@ -160,6 +160,13 @@ export function Form({ onSubmit, busy: ownBusy = false, enterSends = true, class
       }}
       onKeyDown={onKeyDown}
       onSubmit={(event) => {
+        /*
+          A form's own send only. React carries a submit up the component tree,
+          through a portal too, so a Form in a Popover inside this Form sent both:
+          Enter in a link field sent the whole message around it (UIG-14, C1,
+          Katerina 19 September). The inner Form has already handled its own.
+        */
+        if (event.target !== event.currentTarget) return
         event.preventDefault()
         if (busyNow.current) return
         void onSubmit()

package/src/IconButton.mdx

@@ -22,8 +22,8 @@ variants. For the actions a surface repeats too often to label every time.
 - The action deserves a visible label → **Button** (words are cheaper than
   a guessed icon).
 - Inside a menu → **MenuItem** with `leading`.
-- A strip of these is a toolbar — right; but the moment rows toggle and
-  persist state, see **Checkbox**.
+- A strip of these acting on one thing → **Toolbar**. The moment rows toggle
+  and persist state, see **Checkbox**.
 
 ## How
 
@@ -48,17 +48,31 @@ import { IconPencil } from '@tabler/icons-react'
 - `glow` lights it in Signal — the send arrow while there is something to send.
 - **Placed from outside, never restyled.** `className` takes space, size,
   flex and grid, and position; a colour, a text size, a border, a corner or a
-  shadow is refused by the lint (`estiva/no-restyled-part`, UIG-9).
+  shadow is refused by the lint (`estiva/no-restyled-part`).
 - `type` defaults to `"button"`; it is a native `<button>` on Base UI's
   Button, and every native prop passes through.
 - `disabledReason="Read only"` disables it, keeps it reachable by Tab,
   and shows the reason in place of the tooltip — **on keyboard focus as
   well as on hover**.
+- **`href`** makes it a link that looks like the button: an anchor, so the
+  address stays real for a modified click or a new tab. A router app passes
+  `onClick`, prevents the default and navigates. While it cannot be used it
+  is the button — a link cannot be disabled.
 - `tooltip` costs no wrapper: the button is the tooltip's trigger, so
   this component's root is the `<button>` whether it carries one or not,
   and both sit at the same height. A `Dialog.Close` or a `Menu.Trigger`
   can be an IconButton that has a tooltip.
 
+## 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 button | `role="button"` | ✓ |
+| Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
+| Presses on Enter and Space, and does nothing while disabled | a key handler |  |
+
 ## Keys
 
 | Key | Does |

package/src/IconButton.stories.tsx

@@ -26,6 +26,9 @@ export const WithTooltip: Story = { args: { tooltip: 'Settings', tooltipPlacemen
 /** Disabled with its reason in place of the tooltip; Tab still reaches it. */
 export const WithAReason: Story = { args: { tooltip: 'Settings', disabledReason: 'Sign in to change settings' } }
 
+/** `href`: a link that looks like the button — the same box, an anchor underneath. */
+export const AsALink: Story = { args: { href: '#settings', tooltip: 'Settings' } }
+
 /** Every variant × enabled/disabled. */
 export const AllVariants: Story = {
   // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: