@estiva-app/ui 0.23.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "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,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.23.0",
-    "exports": 82,
-    "typeExports": 92,
+    "packageVersion": "0.24.1",
+    "exports": 84,
+    "typeExports": 94,
     "files": null
   },
   "storybook": {
@@ -397,7 +397,7 @@
       "kind": "component",
       "importPath": "@estiva-app/ui",
       "sourceFile": "src/Button.tsx",
-      "purpose": "The push-button for an action: a verb, clicked once — \"Create\", \"Save\", \"Delete project\".",
+      "purpose": "The push-button for an action: a verb, clicked once — \"Create\", \"Save\", \"Delete\".",
       "purposeFrom": "page",
       "props": [
         {
@@ -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",
@@ -2389,6 +2395,81 @@
       "docPage": "src/Link.mdx",
       "app": null
     },
+    {
+      "name": "ListColumn",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/ListColumn.tsx",
+      "purpose": "The list column of a page: 290px wide with a line on its right, its name in a `ContainerHeader`, and the list under it, which scrolls.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "title",
+          "takes": "anything",
+          "required": true,
+          "note": "The column's name, in its header. A node for a title that is more than words."
+        },
+        {
+          "name": "chevron",
+          "takes": "true/false",
+          "required": false,
+          "note": "A chevron after the title, as `ContainerHeader` draws it."
+        },
+        {
+          "name": "actions",
+          "takes": "anything",
+          "required": false,
+          "note": "The column's own actions, at the header's right — a `Toolbar` of `ToolbarButton`s, or one `IconButton`."
+        },
+        {
+          "name": "above",
+          "takes": "anything",
+          "required": false,
+          "note": "A row between the header and the list that stays put while the list scrolls — a field that adds to the list."
+        },
+        {
+          "name": "spacing",
+          "takes": "rows | sections",
+          "required": false,
+          "note": "The room between rows. `rows` (2px) for a list of one kind of row; `sections` (4px) for groups with labels and dividers of their own."
+        },
+        {
+          "name": "collapsed",
+          "takes": "true/false",
+          "required": false,
+          "note": "Closes the column with the rail: it narrows to nothing and fades."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "The rows."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": "Placement only."
+        }
+      ],
+      "variants": [
+        {
+          "prop": "spacing",
+          "values": [
+            "rows",
+            "sections"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "layout-listcolumn--docs",
+      "storyId": "layout-listcolumn--default",
+      "docPage": "src/ListColumn.mdx",
+      "app": null
+    },
     {
       "name": "Menu",
       "repo": "estiva-ui",
@@ -2477,7 +2558,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3019,7 +3100,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3076,7 +3157,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 +3674,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 +3700,13 @@
             "hover",
             "always"
           ]
+        },
+        {
+          "prop": "hover",
+          "values": [
+            "fill",
+            "none"
+          ]
         }
       ],
       "ownsBehaviours": [],
@@ -3719,6 +3819,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 +3856,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "follow",
@@ -3964,7 +4070,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "walking",
@@ -4204,7 +4310,7 @@
         },
         {
           "id": "page-keys",
-          "behaviour": "Closes on Escape, and takes its keys, by itself"
+          "behaviour": "Takes its keys by itself"
         },
         {
           "id": "walking",
@@ -4279,6 +4385,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",
@@ -4346,6 +4458,91 @@
       "docPage": null,
       "app": null
     },
+    {
+      "name": "ToolbarLink",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/Toolbar.tsx",
+      "purpose": "An `IconButton` that is a link, and an item of a `Toolbar`: the arrow keys reach it like the buttons beside it.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "href",
+          "takes": "text",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "ref",
+          "takes": "Ref<HTMLAnchorElement>",
+          "required": false,
+          "note": null
+        },
+        {
+          "name": "variant",
+          "takes": "muted | outlined | primary | current | resolve",
+          "required": false,
+          "note": "`current` takes the colour of what it sits in — the ✕ on a `Banner` wears the banner's tone."
+        },
+        {
+          "name": "glow",
+          "takes": "true/false",
+          "required": false,
+          "note": "A glow in Signal — the send arrow while there is something to send."
+        },
+        {
+          "name": "tooltip",
+          "takes": "text",
+          "required": false,
+          "note": null
+        },
+        {
+          "name": "tooltipShortcut",
+          "takes": "text",
+          "required": false,
+          "note": "A key hint drawn as the `Kbd` chip inside the tooltip — for a button whose only other affordance is a keyboard shortcut."
+        },
+        {
+          "name": "tooltipPlacement",
+          "takes": "top | bottom",
+          "required": false,
+          "note": null
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "The icon: 16px, stroke 1.5."
+        }
+      ],
+      "variants": [
+        {
+          "prop": "variant",
+          "values": [
+            "muted",
+            "outlined",
+            "primary",
+            "current",
+            "resolve"
+          ]
+        },
+        {
+          "prop": "tooltipPlacement",
+          "values": [
+            "top",
+            "bottom"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-toolbar--docs",
+      "storyId": "primitives-toolbar--default",
+      "docPage": null,
+      "app": null
+    },
     {
       "name": "ToolbarSeparator",
       "repo": "estiva-ui",
@@ -4576,6 +4773,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

@@ -52,7 +52,6 @@ flex column. A page is a flex child of `main`, and says one of two things:
 Never `h-full`: the frame's content box is *at least* the viewport's
 height and grows with a tall page — which is what lets the bar know the
 page changed — so a percentage height has nothing to resolve against.
-Measured on all four of Ship's pages (2026-09-09).
 
 ```tsx
 import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
@@ -75,6 +74,24 @@ 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.
+
+- In the floating manner the bar takes the top 52px; the card sits 16px from
+  the right and the bottom, with 16px corners, beside the 64px rail.
+- In the floating manner the card owns `overflow-hidden`, so anything in it
+  that can grow sits in a **ScrollArea** — a list column most of all, which
+  **ListColumn** draws with its own. Without one it is cut off at the fold.
+- **Planned:** `SplitLayout`, resizable panels, in `@estiva-app/ui/layout`
+  (migration stage 8). It may take the list and side columns' widths.
+
+## 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

@@ -53,10 +53,21 @@ import { AttachmentCard } from '@estiva-app/ui'
 - The name truncates. When it is cut off, the full name is on hover; a name
   that fits, and a size, show nothing extra. `noteHint` is always on hover, since
   it says more than the line.
-- The remove control is Peek's 20px round badge on the card's corner, a button
+- The remove control is a 20px round badge on the card's corner, a button
   on Base UI's `Button` like InputChip's ✕ — not an `IconButton`, the 24px
   square that fills on hover.
 
+- **Planned:** a Lightbox that opens a picture full screen, 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 |
+|---|---|---|
+| 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
@@ -37,7 +39,7 @@ import { Avatar } from '@estiva-app/ui'
   two words, skipping words that open with a symbol. An unnamed person is
   the silhouette, not a `?` — a question mark reads as an error badge.
 - The initials are centred on the capitals themselves — cap height to
-  baseline — not on the line of text around them (D27). A single face can
+  baseline — not on the line of text around them. A single face can
   still sit up to half a pixel off: the screen rounds text to its pixel grid
   wherever the tile lands.
 - The colour behind initials is per person, chosen from the name, the same
@@ -52,7 +54,7 @@ import { Avatar } from '@estiva-app/ui'
 **A face is silent by default**, and that is the important half: almost every
 face in the suite sits beside the name it belongs to — in a `Person`, in a
 `MenuItem`'s `leading`, in a row — and a picture that spoke there would say the
-name twice. It used to. Measured 2026-09-08, before this was true: a `Person`
+name twice. It used to: a `Person`
 inside a button announced **"AD Ana Duarte"** (the initials read as text), and
 with a picture **"Ana Duarte Ana Duarte"**.
 
@@ -66,6 +68,19 @@ a stack of members — and the tile becomes one image with one name.
 
 <Canvas of={AvatarStories.Palette} />
 
+- **Planned:** a Byline part — face · name · time — in migration stage 7.
+
+- `initialsFor(name)` and `hueFor(name)` give the same initials and colour where
+  the part itself cannot be drawn.
+
+## 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,11 +22,12 @@ 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
-  a permanent one (Katerina, D21).
+  a permanent one.
 - A standing property of one thing → **Chip** on that thing.
 - More than one action, or a second line of text — that is a different
   component (not in the package yet).
@@ -44,9 +45,8 @@ import { Banner } from '@estiva-app/ui'
 - One line of text, `body-2`. If it needs a **second line**, it has outgrown
   this component.
 - `icon` puts a 16px icon before the line and `action` one small muted Button
-  at the end of it, both in the tone (Katerina, 2026-09-18: Peek's strip above
-  the composer became a Banner, `info`). With either, the banner is one line
-  and the text truncates. One action at most.
+  at the end of it, both in the tone. With either, the banner is one line and
+  the text truncates. One action at most.
 
 <Canvas of={BannerStories.WithIconAndAction} />
 
@@ -56,11 +56,20 @@ import { Banner } from '@estiva-app/ui'
 </Banner>
 ```
 
-- `onDismiss` adds an ✕ at the right-hand end (Katerina, D21). Use it where
+- `onDismiss` adds an ✕ at the right-hand end. Use it where
   the reader decides the notice is done with, rather than the app. The row
   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,18 @@ 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.
 
+- 6px between each place and its separator.
+
+## 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} />