@estiva-app/ui 0.12.0 → 0.12.2

package/package.json

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

package/src/AppShell.mdx

@@ -39,6 +39,21 @@ Layout only: no data, no routes.
 
 ## How
 
+**The page contract, in the solid manner.** The frame owns the page's
+scrollbar: the content column is a ScrollArea, and `main` inside it is a
+flex column. A page is a flex child of `main`, and says one of two things:
+
+- `flex-1` — it fills the frame and, when taller, scrolls in the frame's
+  bar. A list page. (Its empty state centres on its own.)
+- `flex-1 min-h-0 [contain:size]` — it takes exactly the frame's height
+  and scrolls inside itself, in regions of its own. A detail page with a
+  content column and a rail.
+
+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'
 

package/src/AppShell.stories.tsx

@@ -74,6 +74,21 @@ export const Solid: Story = {
 }
 
 /** The banner belongs to the content area — at its top, never across the navigation. */
+/** A page taller than the frame: it scrolls in the frame's own bar — the region every page passes through — never a native one. */
+export const SolidScrolls: Story = {
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+      <div className="flex flex-col gap-px px-6 py-5">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            Row {i + 1}
+          </p>
+        ))}
+      </div>
+    </AppShell>
+  ),
+}
+
 export const SolidWithBanner: Story = {
   render: (args) => (
     <AppShell {...args} logo="Estiva" identity={identity} nav={sidebar} banner={<Banner tone="ok">Public key copied.</Banner>}>

package/src/AppShell.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+/**
+ * The frame owns the page's scrollbar (2026-09-09): in the solid manner the
+ * page lands inside a ScrollArea's viewport — Base UI's `overflow: scroll`
+ * box — so no page can scroll in a native bar. Whether the bar takes width,
+ * and whether an inner region still scrolls on its own, is measured in
+ * Chrome on Ship's four pages.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { AppShell } from './AppShell'
+
+afterEach(cleanup)
+
+describe('AppShell', () => {
+  it('puts the page inside the frame’s scrolling region in the solid manner', () => {
+    render(
+      <AppShell nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    const main = screen.getByRole('main')
+    const viewport = main.closest('[style*="overflow: scroll"]') as HTMLElement | null
+    expect(viewport).not.toBeNull()
+    expect(viewport!.contains(screen.getByText('Page'))).toBe(true)
+    expect(main.className).not.toContain('overflow-y-auto')
+  })
+
+  it('leaves the floating manner’s card as it was', () => {
+    render(
+      <AppShell variant="floating" nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    const main = screen.getByRole('main')
+    expect(main.className).toContain('overflow-hidden')
+    expect(main.closest('[style*="overflow: scroll"]')).toBeNull()
+  })
+})

package/src/AppShell.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 import { TopBar } from './TopBar'
 
 /**
@@ -63,7 +64,9 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
   }
 
   return (
-    /* `relative overflow-hidden` is the seal the floating manner already has,
+    /* `relative overflow-hidden` is the seal the floating manner already has
+       (and the ScrollArea's own root is `relative`, so an absolutely placed
+       stray inside a page now belongs to the region and scrolls with it),
        and it takes both halves: an absolutely positioned descendant with no
        positioned ancestor belongs to the *viewport*, so a scroll container
        never clips it and the document itself gains its position as scroll
@@ -76,12 +79,24 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
         {nav}
         <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           {banner}
-          {/* Not a ScrollArea: the apps' pages scroll inside themselves (Ship's
-              detail columns are `h-full` grids with their own regions), and a
-              region here kept a bar on Ship's page for overflow that was not
-              there (2026-09-09). A page that does scroll here gets its region
-              where it scrolls. */}
-          <main className="min-w-0 flex-1 overflow-y-auto">{children}</main>
+          {/* The frame owns the page's scrollbar (Katerina, 2026-09-09: the
+              Issues page still had a native bar — D40 said everywhere, and the
+              one place every page passes through had been left out). A
+              `ScrollArea` here means no page can forget it. The content box is
+              at least the viewport's height and grows with a tall page, so Base
+              UI sees its size change (the morning's phantom bar was a content
+              box it could not watch); `main` fills it as a flex column. The
+              page contract (the AppShell page says it): a page is a flex
+              child of `main` — `flex-1` to fill and scroll here; `flex-1
+              min-h-0 [contain:size]` to take exactly the frame's height and
+              scroll inside itself, as Ship's detail grids do — and the outer
+              region, with nothing to scroll, passes the wheel through. Never
+              `h-full`: a box that is *at least* the viewport's height gives a
+              percentage nothing to resolve against — measured, all four Ship
+              pages, 2026-09-09. */}
+          <ScrollArea className="min-h-0 flex-1" contentClassName="flex min-h-full flex-col">
+            <main className="flex min-w-0 flex-1 flex-col">{children}</main>
+          </ScrollArea>
         </div>
       </div>
     </div>

package/src/CollapsibleSection.tsx

@@ -31,6 +31,8 @@ export interface CollapsibleSectionProps {
   onOpenChange?: (open: boolean) => void
   /** Remember open or closed in this browser, under this key. The app prefixes it. */
   storageKey?: string
+  /** Beside the title and always visible, before the actions — a count. `SectionHeader`'s. */
+  trailing?: ReactNode
   /** Beside the title, revealed on hover or focus — `SectionHeader`'s. */
   actions?: SectionAction[]
   showActions?: 'hover' | 'always'
@@ -64,7 +66,7 @@ function writeStored(key: string | undefined, open: boolean) {
   }
 }
 
-export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, storageKey, actions, showActions, children, className, contentClassName }: CollapsibleSectionProps) {
+export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, storageKey, trailing, actions, showActions, children, className, contentClassName }: CollapsibleSectionProps) {
   const [openState, setOpenState] = useState(() => readStored(storageKey) ?? defaultOpen)
   const open = openProp ?? openState
   const setOpen = (next: boolean) => {
@@ -74,7 +76,7 @@ export function CollapsibleSection({ title, defaultOpen = true, open: openProp,
   }
   return (
     <Collapsible.Root open={open} onOpenChange={setOpen} className={cn('flex flex-col', className)}>
-      <SectionHeader title={title} chevron isExpanded={open} actions={actions} showActions={showActions} className="shrink-0" render={<Collapsible.Trigger />} />
+      <SectionHeader title={title} chevron isExpanded={open} trailing={trailing} actions={actions} showActions={showActions} className="shrink-0" render={<Collapsible.Trigger />} />
       {/* The slide: Base UI measures the panel and writes its height to a
           variable — `auto` again once the slide ends, so rows that arrive
           later are not clipped — and the panel is 0 high on its opening frame

package/src/DialogShell.mdx

@@ -51,9 +51,15 @@ import { DialogShell, Button } from '@estiva-app/ui'
 ```
 
 - Render it only while open — mounting is opening.
-- `bodyClassName` shapes the body (`flex flex-col gap-6`, or a max height
-  with `overflow-y-auto` for long lists). Rows in a height-capped flex
-  body need `shrink-0`, or overflow crushes them.
+- `bodyClassName` shapes the body — its layout and any padding override
+  (`flex flex-col gap-6`, `p-0 py-2`).
+- **`bodyMaxHeight` makes the body scroll in the package's bar**: give it
+  the cap (`max-h-[400px]`, `max-h-[70vh]`) and the body becomes a
+  `ScrollArea`, so a long roster keeps its text column when it overflows.
+  Without it the body grows to its content, as it always did. A
+  `bodyClassName` carrying `overflow-y-auto` and no cap never scrolled
+  anything — the box grew — and is what this replaces. Rows in a capped
+  flex body still need `shrink-0`, or overflow crushes them.
 - The card names itself to assistive tech (`role="dialog"`, labelled by
   its header — or by `title` when `headerContent` replaces that text).
 - **Focus is trapped and returned.** Tab cannot leave the card, and closing

package/src/DialogShell.stories.tsx

@@ -145,3 +145,32 @@ export const OpenAndClose: Story = {
     )
   },
 }
+
+/**
+ * **A body that scrolls in the package's bar.** `bodyMaxHeight` is the cap;
+ * without it the body grows to its content, as every dialog written before
+ * 0.12.2 does. The bar is drawn over the padding rather than beside it, so the
+ * text column keeps its width when the content overflows.
+ */
+export const ScrollingBody: Story = {
+  args: {
+    title: 'A long list',
+    bodyMaxHeight: 'max-h-[240px]',
+    bodyClassName: 'flex flex-col gap-2',
+    footer: (
+      <>
+        <Button variant="muted">Cancel</Button>
+        <Button variant="primary">Confirm</Button>
+      </>
+    ),
+    children: (
+      <>
+        {Array.from({ length: 16 }, (_, i) => (
+          <span key={i} className="text-body-2 text-text-primary">
+            Item {i + 1}
+          </span>
+        ))}
+      </>
+    ),
+  },
+}

package/src/DialogShell.test.tsx

@@ -182,3 +182,38 @@ describe('ConfirmDialog', () => {
     expect(screen.getByRole('alertdialog')).toBeTruthy()
   })
 })
+
+/**
+ * `bodyMaxHeight` makes the body scroll in the package's bar (0.12.2,
+ * ADOPTION B19). Peek's five dialogs passed `overflow-y-auto` on the body, so
+ * a long roster drew the native bar D40 removed everywhere else — and two of
+ * the five passed it with no cap at all, which never scrolled anything.
+ */
+describe('DialogShell, a body that scrolls', () => {
+  it('leaves the body alone without a cap, and wraps it in a scroll region with one', () => {
+    const { container, unmount } = render(
+      <DialogShell title="T" onClose={() => {}} bodyClassName="flex flex-col gap-6">
+        <p>Inside</p>
+      </DialogShell>,
+    )
+    const plain = screen.getByText('Inside').parentElement!
+    expect(plain.className).toContain('flex flex-col gap-6')
+    expect(plain.className).toContain('pl-5')
+    unmount()
+
+    render(
+      <DialogShell title="T" onClose={() => {}} bodyMaxHeight="max-h-[240px]" bodyClassName="flex flex-col gap-6">
+        <p>Inside</p>
+      </DialogShell>,
+    )
+    const content = screen.getByText('Inside').parentElement!
+    // The padding and the layout stay on the box the children are in…
+    expect(content.className).toContain('flex flex-col gap-6')
+    expect(content.className).toContain('pl-5')
+    // …and the cap is on the scrolling box above it, never on the region.
+    const viewport = content.closest('[class*="max-h-"]')
+    expect(viewport).not.toBe(null)
+    expect(viewport).not.toBe(content)
+    expect(viewport!.className).toContain('overflow')
+  })
+})

package/src/DialogShell.tsx

@@ -4,6 +4,7 @@ import { AlertDialog } from '@base-ui/react/alert-dialog'
 import { IconX } from '@tabler/icons-react'
 import { cn } from './cn'
 import { IconButton } from './IconButton'
+import { ScrollArea } from './ScrollArea'
 
 /**
  * Peek's DialogShell (2026-08-28), verbatim: the portal, the backdrop, the
@@ -41,8 +42,20 @@ export interface DialogShellProps {
    *  (a roster that simply ends). */
   footer?: ReactNode
   children: ReactNode
-  /** Extra classes on the body (e.g. `flex flex-col gap-6`, or a max height with `overflow-y-auto`). */
+  /** Extra classes on the body: its layout and any padding override (`flex flex-col gap-6`, `p-0 py-2`). */
   bodyClassName?: string
+  /**
+   * How tall the body may get before it scrolls, as the cap class —
+   * `max-h-[400px]`, `max-h-[70vh]`. Setting it makes the body a `ScrollArea`,
+   * so a long roster or a tall form scrolls in the package's bar rather than
+   * the browser's (D40, ADOPTION B19).
+   *
+   * Without it the body is what it always was and grows to its content, so no
+   * dialog written before 0.12.2 moves a pixel. A `bodyClassName` carrying
+   * `overflow-y-auto` and no cap never scrolled anything — the box grew — and
+   * is the case this replaces.
+   */
+  bodyMaxHeight?: string
   width?: number
   /**
    * A question that has to be answered rather than clicked away: a press on
@@ -53,7 +66,7 @@ export interface DialogShellProps {
   alert?: boolean
 }
 
-export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, width = 502, alert = false }: DialogShellProps) {
+export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, bodyMaxHeight, width = 502, alert = false }: DialogShellProps) {
   // The two families are the same parts with different dismiss rules, so the
   // chrome below is written once. AlertDialog re-exports Dialog's Backdrop,
   // Popup, Portal and Title types, which is why this substitutes cleanly.
@@ -128,8 +141,22 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
               />
             </div>
 
-            {/* Body */}
-            <div className={cn('pl-5 pr-4 py-4', footer != null && 'border-b border-border-subtle', bodyClassName)}>{children}</div>
+            {/* Body. With a cap it scrolls in the package's bar: the cap goes
+                on the viewport (ScrollArea's rule — on the region the viewport
+                grows to its content and nothing scrolls), and the padding and
+                the caller's layout go on the content, so the bar is drawn over
+                the padding rather than beside it. */}
+            {bodyMaxHeight ? (
+              <ScrollArea
+                className={cn(footer != null && 'border-b border-border-subtle')}
+                viewportClassName={bodyMaxHeight}
+                contentClassName={cn('pl-5 pr-4 py-4', bodyClassName)}
+              >
+                {children}
+              </ScrollArea>
+            ) : (
+              <div className={cn('pl-5 pr-4 py-4', footer != null && 'border-b border-border-subtle', bodyClassName)}>{children}</div>
+            )}
 
             {/* Footer */}
             {footer != null && <div className="h-12 flex items-center justify-end gap-2 pl-5 pr-4 shrink-0">{footer}</div>}

package/src/EmptyState.mdx

@@ -29,8 +29,9 @@ message is still a `page`; a tall section with nothing in it is still a
 Start the thread." — not just that it is empty.
 
 A `page` sits in the middle of its box both ways. Inside a flex column
-it takes the room left (`flex-1`) and centres in it; drawn straight into
-a page, give it the height — `className="h-full"`.
+— the frame's `main` is one — it takes the room left (`flex-1`) and
+centres in it, with nothing to add; only outside a flex column does it
+need a height from the caller (`className="h-full"`).
 
 ## When not
 
@@ -44,8 +45,8 @@ a page, give it the height — `className="h-full"`.
 ```tsx
 import { EmptyState } from '@estiva-app/ui'
 
-// the whole page, drawn straight into it
-<EmptyState className="h-full" message="No documents yet. Create the first one." />
+// the whole page, in the frame: it fills and centres on its own
+<EmptyState message="No documents yet. Create the first one." />
 
 // one section of a page
 <EmptyState scope="section" message="No comments yet." />

package/src/Field.mdx

@@ -18,8 +18,9 @@ token; `required` marks it with the error-coloured asterisk.
 ## When not
 
 - Displaying a label–value pair → **Property**; Field is for editing.
-- It carries no helper or error text of its own — validation display is
-  the caller's, under the control.
+- 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
+  small line on its own.
 
 ## How
 

package/src/Field.tsx

@@ -57,6 +57,16 @@ export interface FieldProps {
   children: ReactNode
 }
 
+/**
+ * The two looks the line under a control wears, in one place so `Field` and
+ * `FieldLine` cannot drift apart. `warning` is `FieldLine`'s alone — see there.
+ */
+const LINE_STYLES = {
+  helper: 'text-caption text-text-muted',
+  warning: 'text-caption text-warning-default',
+  error: 'text-caption text-error-default',
+} as const
+
 export function Field({ label, required = false, helper, error, children }: FieldProps) {
 
   /*
@@ -101,13 +111,58 @@ export function Field({ label, required = false, helper, error, children }: Fiel
       <div className="flex flex-col gap-1.5">
         {control}
         {error != null ? (
-          <BaseField.Error match className="text-caption text-error-default">
+          <BaseField.Error match className={LINE_STYLES.error}>
             {error}
           </BaseField.Error>
         ) : helper != null ? (
-          <BaseField.Description className="text-caption text-text-muted">{helper}</BaseField.Description>
+          <BaseField.Description className={LINE_STYLES.helper}>{helper}</BaseField.Description>
         ) : null}
       </div>
     </BaseField.Root>
   )
 }
+
+/**
+ * The line on its own — the same small line `Field` draws under a control,
+ * for the places where there is no single control to draw it under.
+ *
+ * **Why it is not a `Field`.** Three surfaces in Peek put this line under a
+ * *group*: the rename row (a field and two buttons), a Folder's action
+ * controls, another app's action controls. Each already has a section heading
+ * above it, and `Field` comes with a label of its own — so wrapping the group
+ * in one would either say the heading twice or restyle it. Found at step 4 of
+ * Peek's adoption (`ADOPTION.md` B24); until this existed, all three spelled
+ * `text-xs text-error-default` by hand.
+ *
+ * **It announces itself**, which is the half the hand-written spans never had.
+ * These lines appear *after* something was done — a rename that the relay
+ * refused, an action that failed — so a reader who cannot see them is told:
+ * `role="alert"` for an error, `role="status"` for the rest. That is `Banner`'s
+ * rule (2026-09-02), kept here so the two agree.
+ *
+ * **`warning` is the tone `Field` has not got**, and deliberately: `Field`'s
+ * `error` also marks its control invalid, and a warning is not invalid — the
+ * rename went through, and something about it needs saying. A group has no
+ * single control to mark, so the distinction is free here and would not be
+ * there.
+ *
+ * When the line belongs to one control, it is `Field`'s `helper` or `error`:
+ * those are wired to the control with `aria-describedby` and `aria-invalid`,
+ * which this cannot be.
+ */
+export type FieldLineTone = 'helper' | 'warning' | 'error'
+
+export interface FieldLineProps {
+  /** `helper` (muted) is a hint; `warning` (amber) and `error` (red) are outcomes. Default `helper`. */
+  tone?: FieldLineTone
+  children: ReactNode
+  className?: string
+}
+
+export function FieldLine({ tone = 'helper', children, className }: FieldLineProps) {
+  return (
+    <p role={tone === 'error' ? 'alert' : 'status'} className={cn(LINE_STYLES[tone], className)}>
+      {children}
+    </p>
+  )
+}

package/src/FieldLine.mdx

@@ -0,0 +1,57 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as FieldLineStories from './FieldLine.stories'
+
+<Meta of={FieldLineStories} />
+
+# Field line
+
+The small line a **Field** draws under a control — on its own, for the
+places where there is no single control to draw it under.
+
+<Canvas of={FieldLineStories.UnderAGroup} />
+
+## When
+
+- A line under a **group** of controls: a value with Save and Cancel beside
+  it, a row of action controls. The group already has a heading above it.
+- `helper` is a hint. `warning` and `error` are outcomes: what happened when
+  the person did something.
+
+## When not
+
+- The line belongs to **one control** → **Field**'s `helper` and `error`.
+  Those are wired to the control with `aria-describedby` and `aria-invalid`,
+  which this cannot be, and Field draws the label too.
+- A strip under the app's header → **Banner**.
+- Something that floats over the page and goes away → **Toast**.
+
+## How
+
+```tsx
+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={…} />
+    <Button variant="primary" size="small">Save</Button>
+  </div>
+  {outcome && <FieldLine tone={outcome.kind}>{outcome.message}</FieldLine>}
+</div>
+```
+
+- **The 6px above it is the caller's.** Field puts the control and its line
+  in a `flex flex-col gap-1.5`; a group does the same around its own row, so
+  the line sits where a field's line sits.
+- **It announces itself.** An `error` is `role="alert"`, the other two are
+  `role="status"` — Banner's rule, so the two agree. These lines appear
+  *after* something was done, and a reader who cannot see them is told.
+- **`warning` is the tone Field has not got**, and deliberately: Field's
+  `error` also marks its control invalid, and a warning is not invalid — it
+  went through, and something about it needs saying. A group has no single
+  control to mark, so the distinction is free here.
+- The three tones are the same two classes Field draws, from one map in
+  `Field.tsx`, so they cannot drift.
+
+## Props
+
+<Controls of={FieldLineStories.Helper} />

package/src/FieldLine.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { FieldLine } from './Field'
+import { Select } from './Select'
+import { Button } from './Button'
+import { SectionLabel } from './SectionLabel'
+import { TextInput } from './TextInput'
+
+/** The small line a Field draws under a control, on its own — for a group of controls. */
+const meta = {
+  title: 'Inputs/Field line',
+  component: FieldLine,
+  parameters: { layout: 'padded' },
+  args: { tone: 'helper', children: 'Leave this empty and one is made for you.' },
+  argTypes: { tone: { control: 'inline-radio', options: ['helper', 'warning', 'error'] } },
+  decorators: [(Story) => <div className="w-[360px]"><Story /></div>],
+} satisfies Meta<typeof FieldLine>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A hint: what the format is, or what happens if it is left empty. */
+export const Helper: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
+  // the helper is muted caption text, 3.93:1 on --bg-base in signal (AA 4.5:1).
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+}
+
+/** It went through, and something about it needs saying. */
+export const Warning: Story = {
+  args: { tone: 'warning', children: 'Saved, with one thing left undone.' },
+}
+
+/** It did not go through. This one announces itself. */
+export const Error: Story = {
+  args: { tone: 'error', children: 'That could not be saved.' },
+}
+
+/** Under a row of controls, which is what it is for: one line for the group. */
+export const UnderAGroup: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <SectionLabel>Label</SectionLabel>
+      <div className="flex flex-col gap-1.5">
+        <div className="flex items-center gap-2">
+          {/* A section heading is not a label: the control still owes its own
+              name, which is half of why this group cannot simply be a Field. */}
+          <TextInput defaultValue="Value" aria-label="Label" className="flex-1" />
+          <Button variant="primary" size="small">Save</Button>
+          <Button variant="outlined" size="small">Cancel</Button>
+        </div>
+        <FieldLine tone="warning">Saved, with one thing left undone.</FieldLine>
+      </div>
+    </div>
+  ),
+}
+
+/** The three tones together. */
+export const AllTones: Story = {
+  parameters: {
+    controls: { disable: true },
+    a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } },
+  },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-col gap-1.5">
+        <Select value="one" onChange={() => {}} options={[{ value: 'one', label: 'Item one' }]} ariaLabel="Item" />
+        <FieldLine>Leave this empty and one is made for you.</FieldLine>
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <Select value="one" onChange={() => {}} options={[{ value: 'one', label: 'Item one' }]} ariaLabel="Item" />
+        <FieldLine tone="warning">Saved, with one thing left undone.</FieldLine>
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <Select value="one" onChange={() => {}} options={[{ value: 'one', label: 'Item one' }]} ariaLabel="Item" />
+        <FieldLine tone="error">That could not be saved.</FieldLine>
+      </div>
+    </div>
+  ),
+}

package/src/FieldLine.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+/**
+ * What the Field line page claims (0.12.2, ADOPTION B24).
+ *
+ * The line exists because three surfaces in Peek put one under a *group* of
+ * controls and had to spell `text-xs text-error-default` by hand — and none of
+ * those hand-written spans was announced. Both halves are pinned here: the
+ * role, and that the tones are the same classes `Field` draws.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { Field, FieldLine } from './Field'
+import { TextInput } from './TextInput'
+
+afterEach(cleanup)
+
+describe('FieldLine', () => {
+  it('announces an error, and is polite otherwise', () => {
+    const { unmount } = render(<FieldLine tone="error">That could not be saved.</FieldLine>)
+    expect(screen.getByRole('alert').textContent).toBe('That could not be saved.')
+    unmount()
+
+    render(
+      <>
+        <FieldLine tone="warning">Saved, not announced.</FieldLine>
+        <FieldLine>A hint.</FieldLine>
+      </>,
+    )
+    const polite = screen.getAllByRole('status')
+    expect(polite.map((el) => el.textContent)).toEqual(['Saved, not announced.', 'A hint.'])
+    expect(screen.queryByRole('alert')).toBe(null)
+  })
+
+  it('wears the same classes as the line a Field draws', () => {
+    // The point of one map: a caller who moves a line out of a Field, or into
+    // one, must not see the line change.
+    render(
+      <>
+        <Field label="Label" helper="A hint." error="That could not be saved.">
+          <TextInput />
+        </Field>
+        <FieldLine tone="error">That could not be saved.</FieldLine>
+      </>,
+    )
+    const inField = screen.getAllByText('That could not be saved.')[0]
+    const alone = screen.getByRole('alert')
+    expect(alone.className).toBe(inField.className)
+  })
+
+  it('takes extra classes without losing its tone', () => {
+    render(<FieldLine tone="error" className="mt-1">Nope.</FieldLine>)
+    const line = screen.getByRole('alert')
+    expect(line.className).toContain('mt-1')
+    expect(line.className).toContain('text-error-default')
+  })
+})

package/src/Popover.mdx

@@ -52,7 +52,9 @@ import { Popover } from '@estiva-app/ui'
 - **`actionsRef`** gives `close()`, for the Cancel and Save a form panel ends
   with. Unlike a menu row, a control inside a panel does not close it by being
   pressed: it is content, and content may be used more than once.
-- **`align="right"`** hangs the panel's right edge from the trigger's.
+- **`align="right"`** hangs the panel's right edge from the trigger's;
+  **`align="center"`** puts the panel's middle over the anchor's, wherever
+  in the line that is — what a toolbar over a text selection wants.
 - **`side` is a preference, not a promise.** It says which side to try; Base UI
   measures the room and flips when there is none — which is the reason the
   placement is its job rather than arithmetic of ours. **A panel holding a