@estiva-app/ui 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,7 +4,7 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.23.0",
+    "packageVersion": "0.24.0",
     "exports": 82,
     "typeExports": 92,
     "files": null
@@ -1436,7 +1436,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "focus",
@@ -1927,6 +1927,12 @@
           "required": false,
           "note": "Why the action cannot succeed right now."
         },
+        {
+          "name": "href",
+          "takes": "text",
+          "required": false,
+          "note": "A link that looks like an icon button: an anchor, so the address stays real for a modified click or a new tab, as `Link` keeps it."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -2477,7 +2483,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3019,7 +3025,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3076,7 +3082,13 @@
           "name": "className",
           "takes": "text",
           "required": false,
-          "note": "On the card's surface: its width, its padding, a max height."
+          "note": "On the card's surface: its width."
+        },
+        {
+          "name": "contentClassName",
+          "takes": "text",
+          "required": false,
+          "note": "On the scrolling content: its padding (default 12px) and rhythm."
         },
         {
           "name": "wrapperClassName",
@@ -3587,6 +3599,12 @@
           "required": false,
           "note": "`hover` reveals the actions while the row is hovered or focused; `always` keeps them."
         },
+        {
+          "name": "hover",
+          "takes": "fill | none",
+          "required": false,
+          "note": "`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)."
+        },
         {
           "name": "render",
           "takes": "useRender.RenderProp",
@@ -3607,6 +3625,13 @@
             "hover",
             "always"
           ]
+        },
+        {
+          "prop": "hover",
+          "values": [
+            "fill",
+            "none"
+          ]
         }
       ],
       "ownsBehaviours": [],
@@ -3719,6 +3744,12 @@
           "required": false,
           "note": null
         },
+        {
+          "name": "disabledReason",
+          "takes": "text",
+          "required": false,
+          "note": "Why it cannot be changed right now (UIG-14, Katerina, 19 September)."
+        },
         {
           "name": "className",
           "takes": "text",
@@ -3750,7 +3781,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3964,7 +3995,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "walking",
@@ -4204,7 +4235,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "walking",
@@ -4279,6 +4310,12 @@
           "required": false,
           "note": "Why the action cannot succeed right now."
         },
+        {
+          "name": "href",
+          "takes": "text",
+          "required": false,
+          "note": "A link that looks like an icon button: an anchor, so the address stays real for a modified click or a new tab, as `Link` keeps it."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -4576,6 +4613,12 @@
           "required": false,
           "note": "Extra classes on the wrapper — e.g. `min-w-0 shrink` so a truncating label keeps truncating inside it."
         },
+        {
+          "name": "inline",
+          "takes": "true/false",
+          "required": false,
+          "note": "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)."
+        },
         {
           "name": "children",
           "takes": "anything",

package/src/AppShell.mdx

@@ -75,6 +75,16 @@ import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
 - In the floating manner the card owns `overflow-hidden` — your content
   manages its own scrolling inside it.
 - Desktop only for now — no narrow-screen behaviour is provided.
+- In the Signal theme the floating frame draws the control-room dot grid on
+  its ground, behind the card. Nothing to add: the preset makes 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 |
+|---|---|---|
+| Scrolls the page's content column, in a ScrollArea | `overflow-auto` on the page or on `main` |  |
 
 ## Props
 

package/src/AppShell.test.tsx

@@ -36,4 +36,20 @@ describe('AppShell', () => {
     expect(main.className).toContain('overflow-hidden')
     expect(main.closest('[style*="overflow: scroll"]')).toBeNull()
   })
+
+  it('carries the Signal canvas on the floating frame, and only there', () => {
+    const { container, unmount } = render(
+      <AppShell variant="floating" nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    expect((container.firstElementChild as HTMLElement).className).toContain('signal-canvas')
+    unmount()
+    const solid = render(
+      <AppShell nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    expect(solid.container.querySelector('.signal-canvas')).toBeNull()
+  })
 })

package/src/AppShell.tsx

@@ -45,7 +45,10 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
 
   if (variant === 'floating') {
     return (
-      <div className="relative h-full min-h-0 overflow-hidden bg-bg-base">
+      // `signal-canvas`: in the Signal theme, the preset draws the control-room dot
+      // grid behind everything in the frame (Peek's, moved here with the frame:
+      // UIG-14, Katerina, 19 September — the canvas is the theme's, not an app's).
+      <div className="signal-canvas relative h-full min-h-0 overflow-hidden bg-bg-base">
         {bar}
         <div className="flex h-full pb-4 pr-4 pt-[52px]">
           {nav}

package/src/AttachmentCard.mdx

@@ -57,6 +57,15 @@ import { AttachmentCard } from '@estiva-app/ui'
   on Base UI's `Button` like InputChip's ✕ — not an `IconButton`, the 24px
   square that fills on hover.
 
+## 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 |
+|---|---|---|
+| Stops the clicks on its picture, its download and its remove control, so they never also click the card or row around it | `stopPropagation` |  |
+| Shows the full name on hover when the name is cut off | a tooltip of your own |  |
+
 ## Props
 
 <Controls of={AttachmentCardStories.Document} />

package/src/AttachmentCard.test.tsx

@@ -169,4 +169,14 @@ describe('AttachmentCard', () => {
     expect(onRemove).toHaveBeenCalledTimes(1)
     expect(outside).not.toHaveBeenCalled()
   })
+
+  it('the ✕ shows when the keyboard reaches it, not only on hover (C4)', async () => {
+    render(<AttachmentCard pending name="a.png" size={1} onRemove={() => {}} />)
+    const remove = screen.getByRole('button', { name: 'Remove a.png' })
+    // Hidden at rest; each of these reveals it. jsdom draws nothing, so the classes are the contract.
+    expect(remove.className).toContain('opacity-0')
+    for (const reveal of ['group-hover:opacity-100', 'group-focus-within:opacity-100', 'focus-visible:opacity-100']) expect(remove.className).toContain(reveal)
+    await userEvent.tab()
+    expect(document.activeElement).toBe(remove)
+  })
 })

package/src/AttachmentCard.tsx

@@ -20,7 +20,7 @@ import {
 import { Card } from './Card'
 import { IconButton } from './IconButton'
 import { Link } from './Link'
-import { WithTooltip } from './Tooltip'
+import { WithTooltip, type WithTooltipProps } from './Tooltip'
 import { cn } from './cn'
 
 /**
@@ -98,7 +98,7 @@ function TypeIcon({ name }: { name: string }) {
  * the fallback face can fit and then not, in a line whose box never changes. The wrapper is `flex-col` so the
  * text stretches across it, as wide as it is without one.
  */
-function Truncating({ text, hint, className, wrapperClassName }: { text: string; hint?: string; className: string; wrapperClassName?: string }) {
+function Truncating({ text, hint, className, wrapperClassName, placement }: { text: string; hint?: string; className: string; wrapperClassName?: string; placement?: WithTooltipProps['placement'] }) {
   const ref = useRef<HTMLSpanElement>(null)
   const [cut, setCut] = useState(false)
   useLayoutEffect(() => {
@@ -127,7 +127,7 @@ function Truncating({ text, hint, className, wrapperClassName }: { text: string;
   )
   if (!hint && !cut) return line
   return (
-    <WithTooltip label={hint ?? text} wrapperClassName={cn('min-w-0 flex-col', wrapperClassName)}>
+    <WithTooltip label={hint ?? text} placement={placement} wrapperClassName={cn('min-w-0 flex-col', wrapperClassName)}>
       {line}
     </WithTooltip>
   )
@@ -206,7 +206,8 @@ export function AttachmentCard({
           )}
         </div>
         <div className="flex flex-col gap-[1px] min-w-0">
-          <Truncating text={name} className={NAME_CLASSES} />
+          {/* Below, not above: above, a cut name's tooltip covered the ✕ on the corner (UIG-14, C4). */}
+          <Truncating text={name} className={NAME_CLASSES} placement={onRemove ? 'bottom' : undefined} />
           <Truncating
             text={(failed || warning ? note : state === 'uploading' ? (note ?? 'Uploading…') : (note ?? sizeText)) ?? ''}
             hint={noteHint}
@@ -219,7 +220,9 @@ export function AttachmentCard({
           <BaseButton
             type="button"
             aria-label={`Remove ${name}`}
-            className="absolute -top-1.5 -right-1.5 size-5 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary opacity-0 group-hover:opacity-100 transition-opacity"
+            // Shows with the card's hover and with keyboard focus, as Download does: hover-only left it invisible to
+            // the keyboard that had reached it (UIG-14, C4, Katerina 19 September).
+            className="absolute -top-1.5 -right-1.5 size-5 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100 transition-opacity"
             onClick={(event) => {
               event.stopPropagation()
               onRemove()

package/src/Avatar.mdx

@@ -13,13 +13,15 @@ theirs, or — when there is no name to take initials from — a silhouette.
 ## When
 
 - Anywhere a person appears at a glance: a row, a card, a picker, a byline.
-- The scale is 16 · 24 · 32 · 36 (default) — pick from it rather than
-  inventing sizes.
+- The scale is 16 · 18 · 20 · 24 · 32 · 36 (default): 18 in a group's reply
+  row, 20 in a **Person**. Pick from it rather than inventing sizes.
 
 ## When not
 
 - Several people at once → **AvatarGroup**.
-- The face beside the name → **Person**.
+- The face beside a name, with nothing else on the line → **Person**. A byline
+  that sets the name its own way — bold, with a time — is an Avatar beside its
+  own text.
 - The face as a button that opens a menu → **PersonTrigger**.
 
 ## How
@@ -66,6 +68,14 @@ a stack of members — and the tile becomes one image with one name.
 
 <Canvas of={AvatarStories.Palette} />
 
+## 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 |
+|---|---|---|
+| Shows initials from the name when there is no picture, or when it fails to load | an `onError`, or initials of your own |  |
+
 ## Props
 
 <Controls of={AvatarStories.Initials} />

package/src/AvatarGroup.mdx

@@ -34,6 +34,10 @@ import { AvatarGroup } from '@estiva-app/ui'
 - The ring rides on the Avatar itself (one box); don't wrap each face in a
   clipping window — a window minus a border crops the initials.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={AvatarGroupStories.ThreeMembers} />

package/src/Banner.mdx

@@ -12,8 +12,8 @@ line, one of four tones, gone when there is nothing to say.
 
 ## When
 
-- The outcome or state of the whole surface: "Public key copied.", the
-  reason the last read failed, a read-only notice.
+- The state of the whole surface: the reason the last read failed, a read-only
+  notice.
 - **`ok`** confirms, **`info`** informs, **`warning`** cautions,
   **`error`** reports a failure — and only `error` announces itself
   (`role="alert"`); the others are polite (`role="status"`).
@@ -22,7 +22,8 @@ line, one of four tones, gone when there is nothing to say.
 
 ## When not
 
-- Feedback about one action, briefly → **Toast**.
+- Feedback about one action, briefly → **Toast**. A failure is the exception:
+  it stays, in the Banner, until the person acts on it.
 - Something that floats over the page and must **not** fade → still
   **Toast**, with `durationMs: 0` and an action. A banner is the strip
   under the header at the app's full width; a floating pill is not one, even
@@ -61,6 +62,15 @@ import { Banner } from '@estiva-app/ui'
   is 40px rather than 36px with it, because the button is taller than the
   line of text; without it, nothing about the strip changes.
 
+## 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"` | ✓ |
+| Draws its own ✕ when you pass `onDismiss`, and its one small action when you pass `action` | a close button or an action button of your own |  |
+
 ## Props
 
 <Controls of={BannerStories.Ok} />

package/src/Breadcrumb.mdx

@@ -56,6 +56,16 @@ import { Breadcrumb } from '@estiva-app/ui'
   `min-w-0` container so it can truncate at all.
 - The separators are `aria-hidden` — the trail reads as its places.
 
+## 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 |
+|---|---|---|
+| Shortens a trail that does not fit, and shows a cut crumb in full on hover | truncation code, or a tooltip |  |
+| Names itself as a navigation, and marks the last crumb as the current page | `<nav>`, `aria-label` or `aria-current` |  |
+| Hides the separators from screen readers, so the trail reads as its places | `aria-hidden` on each separator |  |
+
 ## Props
 
 <Controls of={BreadcrumbStories.OnAnItem} />

package/src/Button.mdx

@@ -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
 
@@ -68,6 +69,16 @@ import { IconPlus } from '@tabler/icons-react'
   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 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/Card.mdx

@@ -76,6 +76,15 @@ import { Card } from '@estiva-app/ui'
   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
   your own element inside.
 
+## 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,16 @@ 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 |  |
+
 ## 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

@@ -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

@@ -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

@@ -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.

package/src/ContainerHeader.mdx

@@ -51,6 +51,10 @@ 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
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## 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
 
@@ -73,6 +74,19 @@ import { DialogShell, Button } from '@estiva-app/ui'
   stops closing it (Katerina, D20). 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,14 @@ 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.
 
+## 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"` | ✓ |
+
 ## Props
 
 <Controls of={DividerStories.Default} />

package/src/EditableText.mdx

@@ -23,6 +23,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
 
@@ -55,6 +57,15 @@ import { EditableText } from '@estiva-app/ui'
   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).
 
+## 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
 
 | Input | What happens |