@estiva-app/ui 0.12.1 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.12.1",
+  "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/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/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

package/src/Popover.stories.tsx

@@ -220,3 +220,18 @@ export const FlippedForRoom: Story = {
     </div>
   ),
 }
+
+/**
+ * `align="center"` puts the panel's middle over the anchor's, wherever in the
+ * line that is — what a toolbar over a selection wants.
+ */
+export const Centred: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: () => (
+    <div className="flex h-[260px] w-full items-center justify-center">
+      <Popover trigger={<Button variant="outlined">Centred over this</Button>} align="center" ariaLabel="A panel" className="w-[120px]">
+        <span className="text-body-2 text-text-primary">Middle over middle.</span>
+      </Popover>
+    </div>
+  ),
+}

package/src/Popover.test.tsx

@@ -186,3 +186,23 @@ describe('Popover', () => {
     expect(onOpenChange).toHaveBeenCalledWith(false)
   })
 })
+
+/**
+ * `align="center"` (0.12.2, ADOPTION B21). Peek's selection toolbar is centred
+ * over the text you selected, and kept its own placement arithmetic while only
+ * the two edges were mapped.
+ */
+describe('Popover, centred on its anchor', () => {
+  it('asks Base UI for the middle', async () => {
+    render(
+      <Popover trigger={<Button>Open</Button>} align="center" ariaLabel="A panel">
+        <span>Inside</span>
+      </Popover>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const panel = await screen.findByRole('dialog')
+    // Base UI writes the resolved placement on the positioner it owns.
+    const positioner = panel.closest('[data-align]') ?? panel.parentElement
+    expect(positioner?.getAttribute('data-align')).toBe('center')
+  })
+})

package/src/Popover.tsx

@@ -51,8 +51,17 @@ export interface PopoverProps {
    * Render it always and toggle `open`; do not mount it only while it is open.
    */
   anchor?: HTMLElement | DOMRect | null
-  /** Which of the panel's edges hangs from the trigger's. Default left. */
-  align?: 'left' | 'right'
+  /**
+   * Which of the panel's edges hangs from the trigger's, or `center` to put
+   * the panel's middle over the anchor's. Default left.
+   *
+   * **`center` is what a toolbar over a text selection wants** (Katerina,
+   * PEE-19, after Linear): the panel sits over the middle of what you
+   * selected, wherever in the line that is. Until 0.12.2 only the two edges
+   * were mapped, so Peek's selection toolbar kept the placement arithmetic
+   * the move onto this component was meant to delete (ADOPTION B21).
+   */
+  align?: 'left' | 'center' | 'right'
   /**
    * Which side of the trigger, or of the anchor, the panel prefers. Default
    * `bottom`.
@@ -117,7 +126,7 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
         <BasePopover.Positioner
           anchor={anchorTarget}
           side={side}
-          align={align === 'right' ? 'end' : 'start'}
+          align={align === 'right' ? 'end' : align === 'center' ? 'center' : 'start'}
           sideOffset={GAP}
           collisionPadding={VIEWPORT_PAD}
           className="z-50 data-[anchor-hidden]:hidden"

package/src/ScrollArea.mdx

@@ -39,6 +39,11 @@ import { ScrollArea } from '@estiva-app/ui'
 - `className` sizes and places the region; `viewportClassName` styles the
   scrolling box inside it — padding, gap, the layout of the content.
 - The region needs a height (or a `max-h-*`) to have anything to scroll.
+- **`viewportRef` and `onScroll` hand back the box that scrolls**, for a
+  region that reads or drives its own scrolling: a conversation that arrives
+  at its newest message, keeps its place when older ones load above it, and
+  jumps to the bottom when a reply is sent. Nothing else here can do that for
+  the caller, and the caller cannot do it without the box.
 - The native scrollbar is hidden by Base UI; a native `overflow-y-auto` on
   the same element would draw a second one.
 - A region keeps the wheel only in an axis it can actually scroll: a list

package/src/ScrollArea.test.tsx

@@ -5,8 +5,9 @@
  * it shows, is measured in Chrome (2026-09-08: the viewport keeps its full
  * width with 40 rows overflowing; the native bar is hidden).
  */
+import { createRef } from 'react'
 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { ScrollArea } from './ScrollArea'
 
 afterEach(cleanup)
@@ -63,3 +64,28 @@ describe('ScrollArea and the page behind it', () => {
     expect(viewport.className).not.toMatch(/(^|\s)overscroll-contain(\s|$)/)
   })
 })
+
+/**
+ * The viewport is the box a caller reads and drives (0.12.2, ADOPTION B20).
+ * A conversation arrives at its newest message and jumps to the bottom on a
+ * reply; neither is something the region can do for the caller, and neither is
+ * possible without the box.
+ */
+describe('ScrollArea, the viewport it hands back', () => {
+  it('gives the caller the box that scrolls, and reports its scrolling', () => {
+    const ref = createRef<HTMLDivElement>()
+    let scrolled = 0
+    render(
+      <ScrollArea className="h-40" viewportRef={ref} onScroll={() => { scrolled += 1 }}>
+        <p>Inside</p>
+      </ScrollArea>,
+    )
+    // The box the caller gets is the one the content sits in, not the region.
+    expect(ref.current).not.toBe(null)
+    expect(ref.current!.contains(screen.getByText('Inside'))).toBe(true)
+    expect(ref.current!.className).toContain('overflow')
+
+    fireEvent.scroll(ref.current!)
+    expect(scrolled).toBe(1)
+  })
+})