@estiva-app/ui 0.10.0 → 0.11.0

package/dist/triggerDisabled.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+/**
+ * Whether the element a `Menu` or `Popover` was handed as its trigger is
+ * disabled — by `disabled`, or by a `disabledReason` (which disables the
+ * button and keeps it reachable). Base UI's trigger parts keep a disabled
+ * state of their own and write it over the rendered button's, so they have to
+ * be told (Finding 39, 2026-09-08).
+ */
+export declare function triggerDisabled(trigger: ReactElement): boolean;
+//# sourceMappingURL=triggerDisabled.d.ts.map

package/dist/triggerDisabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggerDisabled.d.ts","sourceRoot":"","sources":["../src/triggerDisabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAEzC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAG9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.10.0",
+  "version": "0.11.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/src/AppShell.tsx

@@ -76,6 +76,11 @@ 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>
         </div>
       </div>

package/src/Divider.mdx

@@ -20,6 +20,13 @@ carries the `separator` role for assistive tech.
 
 <Canvas of={DividerStories.Vertical} />
 
+- With a `label`, words sit in the middle of the line — a date between two
+  days of messages, or where "new since you last read this" begins.
+  `tone="warning"` for the second: the label in the warning colour, the
+  lines in its wash. The line is named by its label for assistive tech.
+
+<Canvas of={DividerStories.Warning} />
+
 ## When not
 
 - Between every row of a list — spacing does that; a hairline per row is
@@ -34,6 +41,8 @@ import { Divider } from '@estiva-app/ui'
 
 <Divider />
 <Divider orientation="vertical" />
+<Divider label="Today" />
+<Divider label="New since you last read this" tone="warning" />
 ```
 
 ## Props

package/src/Divider.stories.tsx

@@ -42,3 +42,28 @@ export const Vertical: Story = {
     </div>
   ),
 }
+
+/** Words in the middle of the line — a date between two days of messages. */
+export const WithALabel: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
+  // the label is muted caption text, 3.78:1 on --bg-surface in signal (AA 4.5:1).
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+  render: () => (
+    <div className="w-96 rounded-lg border border-border-default bg-bg-surface py-3 text-body-2 text-text-primary">
+      <p className="px-3 pb-2">Yesterday's last message</p>
+      <Divider label="Today" />
+      <p className="px-3 pt-2">Today's first</p>
+    </div>
+  ),
+}
+
+/** Asking for attention: where "new since you last read this" begins. The warning colour, because the accent could not be read on Ship's background. */
+export const Warning: Story = {
+  render: () => (
+    <div className="w-96 rounded-lg border border-border-default bg-bg-surface py-3 text-body-2 text-text-primary">
+      <p className="px-3 pb-2">Yes — it re-reads the folder union and the archived one lands last.</p>
+      <Divider label="New since you last read this" tone="warning" />
+      <p className="px-3 pt-2">Same here, from Peek.</p>
+    </div>
+  ),
+}

package/src/Divider.test.tsx

@@ -0,0 +1,26 @@
+// @vitest-environment jsdom
+/** What the Divider page claims, pinned: the role, and a label that names the line. */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { Divider } from './Divider'
+
+afterEach(cleanup)
+
+describe('Divider', () => {
+  it('is a separator, horizontal by default', () => {
+    render(<Divider />)
+    expect(screen.getByRole('separator').getAttribute('aria-orientation')).toBe('horizontal')
+  })
+
+  it('with a label, the separator is named by it and the words are drawn once', () => {
+    render(<Divider label="New since you last read this" tone="warning" />)
+    const rule = screen.getByRole('separator', { name: 'New since you last read this' })
+    expect(rule.textContent).toBe('New since you last read this')
+    expect(rule.querySelectorAll('[aria-hidden="true"]')).toHaveLength(2)
+  })
+
+  it('vertical ignores a label — there is no middle to put it in', () => {
+    render(<Divider orientation="vertical" label="Nope" />)
+    expect(screen.getByRole('separator').textContent).toBe('')
+  })
+})

package/src/Divider.tsx

@@ -8,10 +8,39 @@ import { cn } from './cn'
  */
 export interface DividerProps {
   orientation?: 'horizontal' | 'vertical'
+  /**
+   * Words in the middle of the line — "New since you last read this", a
+   * date. Horizontal only; the line splits around the label.
+   */
+  label?: string
+  /**
+   * `warning` for a line that asks for attention: the label in the warning
+   * colour, the lines in its wash. Peek and Ship both drew their "new since
+   * you last read" rule in the accent, which measures 3.3:1 on Ship's
+   * background and could not be read (Katerina, 2026-09-08); the warning
+   * colour measures 9.6:1 there. Default: the muted text, `border-subtle`
+   * lines, for a date.
+   */
+  tone?: 'default' | 'warning'
   className?: string
 }
 
-export function Divider({ orientation = 'horizontal', className }: DividerProps) {
+export function Divider({ orientation = 'horizontal', label, tone = 'default', className }: DividerProps) {
+  if (label && orientation === 'horizontal') {
+    const line = tone === 'warning' ? 'bg-warning-muted' : 'bg-border-subtle'
+    return (
+      <div
+        role="separator"
+        aria-orientation="horizontal"
+        aria-label={label}
+        className={cn('flex shrink-0 items-center gap-2 mx-3', className)}
+      >
+        <span aria-hidden="true" className={cn('h-px flex-1', line)} />
+        <span className={cn('shrink-0 text-caption', tone === 'warning' ? 'text-warning-default' : 'text-text-muted')}>{label}</span>
+        <span aria-hidden="true" className={cn('h-px flex-1', line)} />
+      </div>
+    )
+  }
   return (
     <div
       role="separator"

package/src/Field.test.tsx

@@ -192,16 +192,44 @@ describe('Field', () => {
     expect(document.getElementById(describedBy!)?.textContent).toBe('That is not a Folder link.')
   })
 
-  it('renders no line, and no wrapper, when there is neither', () => {
-    // The port must not move a pixel for the callers that predate these props,
-    // so the control stays a direct child of the Field exactly as before.
-    const { container } = render(
-      <Field label="Title">
+  it('keeps the same control, and its focus, when an error appears and clears', () => {
+    // Finding 38 (Ship's adoption, 2026-09-08): the control used to be wrapped
+    // only when there was a line under it, so React re-created it the moment
+    // an error appeared or cleared — and a person typing into a field whose
+    // error clears on input lost focus after the first keystroke. The control
+    // sits in the same place now whatever is under it.
+    const { rerender } = render(
+      <Field label="Folder link">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    const input = screen.getByLabelText('Folder link')
+    input.focus()
+    rerender(
+      <Field label="Folder link" error="That is not a Folder link.">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByLabelText('Folder link')).toBe(input)
+    expect(document.activeElement).toBe(input)
+    rerender(
+      <Field label="Folder link">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByLabelText('Folder link')).toBe(input)
+    expect(document.activeElement).toBe(input)
+  })
+
+  it('keeps the required asterisk out of the accessible name', () => {
+    // Ship's test asked for a combobox named "Project" and found "Project*"
+    // (Finding 38). The asterisk is a picture; `aria-required` is the word.
+    render(
+      <Field label="Title" required>
         <TextInput defaultValue="" />
       </Field>,
     )
-    const root = container.firstElementChild!
-    expect(root.children).toHaveLength(2)
-    expect(root.children[1].tagName).toBe('INPUT')
+    expect(screen.getByRole('textbox', { name: 'Title' })).toBeTruthy()
+    expect(screen.getByText('*').getAttribute('aria-hidden')).toBe('true')
   })
 })

package/src/Field.tsx

@@ -58,7 +58,7 @@ export interface FieldProps {
 }
 
 export function Field({ label, required = false, helper, error, children }: FieldProps) {
-  const line = error ?? helper
+
   /*
     The asterisk is a picture of `required`; this is the word for it. Base UI's
     `Field` has no `required` to propagate, so the control is marked here —
@@ -80,27 +80,34 @@ export function Field({ label, required = false, helper, error, children }: Fiel
           `cn.test.ts` pins that. */}
       <BaseField.Label className={cn('text-input-label text-text-primary', required && 'flex items-center')}>
         {label}
-        {required && <span className="text-error-default ml-0.5">*</span>}
+        {/* A picture, not a word: `aria-required` on the control says it, and
+            without this the control was named "Title*" (Finding 38). */}
+        {required && (
+          <span aria-hidden="true" className="text-error-default ml-0.5">
+            *
+          </span>
+        )}
       </BaseField.Label>
       {/*
-        No line, no wrapper: every caller that predates `helper` and `error`
-        keeps the exact DOM it had, so the port cannot move a pixel. With a
-        line, this is the 6px stack Ship and Peek were both writing by hand.
+        The control sits in the same place whether or not there is a line
+        under it. It used to be wrapped only when there was one, and React
+        then re-created the control the moment an error appeared or cleared —
+        so a person typing into a field whose error clears on input lost
+        focus after the first keystroke (found by Ship's adoption, 2026-09-08,
+        Finding 38). A one-child flex column draws exactly as the bare control
+        did; the 6px stack Ship and Peek both wrote by hand appears only with a
+        line.
       */}
-      {line == null ? (
-        control
-      ) : (
-        <div className="flex flex-col gap-1.5">
-          {control}
-          {error != null ? (
-            <BaseField.Error match className="text-caption text-error-default">
-              {error}
-            </BaseField.Error>
-          ) : (
-            <BaseField.Description className="text-caption text-text-muted">{helper}</BaseField.Description>
-          )}
-        </div>
-      )}
+      <div className="flex flex-col gap-1.5">
+        {control}
+        {error != null ? (
+          <BaseField.Error match className="text-caption text-error-default">
+            {error}
+          </BaseField.Error>
+        ) : helper != null ? (
+          <BaseField.Description className="text-caption text-text-muted">{helper}</BaseField.Description>
+        ) : null}
+      </div>
     </BaseField.Root>
   )
 }

package/src/Menu.tsx

@@ -2,6 +2,8 @@ import { createContext, useContext, type ComponentPropsWithRef, type ReactElemen
 import { IconChevronRight } from '@tabler/icons-react'
 import { Menu as BaseMenu } from '@base-ui/react/menu'
 import { cn } from './cn'
+import { triggerDisabled } from './triggerDisabled'
+import { ScrollArea } from './ScrollArea'
 import { Kbd } from './Kbd'
 import { SectionLabel } from './SectionLabel'
 
@@ -173,6 +175,11 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
     >
       <BaseMenu.Trigger
         render={trigger}
+        /* The part writes its own disabled state over the button's, so a
+           disabled trigger came out `aria-disabled="false"` and opened
+           (Finding 39, Ship's adoption, 2026-09-08). It is told what the
+           button already knows. */
+        disabled={triggerDisabled(trigger)}
         openOnHover={openOnHover}
         delay={HOVER_OPEN_DELAY}
         closeDelay={HOVER_CLOSE_DELAY}
@@ -201,10 +208,18 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
                room. Select's 288 was never this component's — the identity
                panel got it by accident once and grew a scrollbar at full
                height. */
-            className={cn('min-w-[180px] max-h-[var(--available-height)] overflow-y-auto outline-none', className)}
+            className={cn('min-w-[180px] outline-none', className)}
             render={<MenuPanel />}
           >
-            <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
+            {/* The height cap sits on the box that scrolls — on the panel it
+                let the box grow to its content and nothing scrolled (measured,
+                2026-09-08) — less the panel's own padding, so the panel still
+                stops where Floating UI said. The padding stays on the panel,
+                where a caller's `className` can change it; the divider rule
+                moves with the rows. A menu that fits draws exactly as before. */}
+            <ScrollArea viewportClassName="max-h-[calc(var(--available-height)_-_1rem)]" contentClassName="flex flex-col [&>[role=separator]]:mx-0">
+              <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
+            </ScrollArea>
           </BaseMenu.Popup>
         </BaseMenu.Positioner>
       </BaseMenu.Portal>

package/src/Popover.tsx

@@ -1,6 +1,8 @@
 import { useMemo, type ReactElement, type ReactNode, type RefObject } from 'react'
 import { Popover as BasePopover } from '@base-ui/react/popover'
 import { cn } from './cn'
+import { triggerDisabled } from './triggerDisabled'
+import { ScrollArea } from './ScrollArea'
 import { MenuPanel } from './Menu'
 
 /**
@@ -108,7 +110,9 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
          take the page away from the person using it. */
       modal={false}
     >
-      {trigger && <BasePopover.Trigger render={trigger} />}
+      {/* Told the button's disabled state, or it writes `aria-disabled="false"`
+          over it and opens anyway (Finding 39). */}
+      {trigger && <BasePopover.Trigger render={trigger} disabled={triggerDisabled(trigger)} />}
       <BasePopover.Portal>
         <BasePopover.Positioner
           anchor={anchorTarget}
@@ -141,10 +145,13 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
              */
             initialFocus={trigger ? undefined : false}
             finalFocus={finalFocus}
-            className={cn('min-w-[180px] max-h-[var(--available-height)] overflow-y-auto outline-none', className)}
+            className={cn('min-w-[180px] outline-none', className)}
             render={<MenuPanel />}
           >
-            {children}
+            {/* As in Menu: the cap on the scrolling box, less the panel's padding; the padding stays on the panel. */}
+            <ScrollArea viewportClassName="max-h-[calc(var(--available-height)_-_1rem)]" contentClassName="flex flex-col [&>[role=separator]]:mx-0">
+              {children}
+            </ScrollArea>
           </BasePopover.Popup>
         </BasePopover.Positioner>
       </BasePopover.Portal>

package/src/PreviewCard.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { PreviewCard as BasePreviewCard } from '@base-ui/react/preview-card'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 import { MenuPanel } from './Menu'
 
 /**
@@ -79,10 +80,12 @@ export function PreviewCard({ content, children, side = 'right', delay = OPEN_DE
           className="z-50 data-[anchor-hidden]:hidden"
         >
           <BasePreviewCard.Popup
-            className={cn('w-[360px] max-h-[min(300px,var(--available-height))] gap-3 overflow-y-auto p-3 outline-none [&>*]:shrink-0', className)}
+            className={cn('w-[360px] p-3 outline-none', className)}
             render={<MenuPanel />}
           >
-            {content}
+            <ScrollArea viewportClassName="max-h-[calc(min(300px,var(--available-height))_-_1.5rem)]" contentClassName="flex flex-col gap-3 [&>*]:shrink-0">
+              {content}
+            </ScrollArea>
           </BasePreviewCard.Popup>
         </BasePreviewCard.Positioner>
       </BasePreviewCard.Portal>

package/src/Reaction.tsx

@@ -65,7 +65,12 @@ export function Reaction({ emoji, count, pressed = false, className, type, ...pr
         'border transition-colors',
         'disabled:cursor-not-allowed disabled:opacity-50',
         pressed
-          ? 'border-accent-primary bg-accent-muted text-accent-primary hover:border-accent-hover'
+          ? /* In the ship theme the accent on its own wash measures 2.70:1
+               (Finding 4), and the count was the thing that vanished
+               (Katerina, 2026-09-08). The number reads in the text colour
+               there; the accent keeps the edge and the fill. Signal keeps
+               Peek's blue-on-wash, which reads. */
+            'border-accent-primary bg-accent-muted text-accent-primary hover:border-accent-hover ship:text-text-primary'
           : 'border-border-default bg-bg-inset text-text-primary hover:border-border-strong hover:bg-bg-hover',
         className,
       )}

package/src/ScrollArea.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ScrollAreaStories from './ScrollArea.stories'
+
+<Meta of={ScrollAreaStories} />
+
+# ScrollArea
+
+A region that scrolls without taking width for its scrollbar. The bar is
+drawn over the content and shows while the pointer is over the region or
+the content is moving; nothing moves when it appears.
+
+<Canvas of={ScrollAreaStories.Default} />
+
+## When
+
+- Any box that can hold more than fits: a menu or a dropdown list, a panel,
+  a sidebar, the page's content column, a rail.
+- `orientation="horizontal"` for a row wider than its box — a table, a
+  board; `"both"` when a thing can run over either way.
+
+<Canvas of={ScrollAreaStories.Horizontal} />
+
+## When not
+
+- A box that never overflows. A ScrollArea around it changes nothing, and
+  is one more element.
+- The page itself. The browser owns that bar.
+
+## How
+
+```tsx
+import { ScrollArea } from '@estiva-app/ui'
+
+<ScrollArea className="h-[240px]" viewportClassName="p-2">
+  {rows}
+</ScrollArea>
+```
+
+- `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.
+- The native scrollbar is hidden by Base UI; a native `overflow-y-auto` on
+  the same element would draw a second one.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| ↑ ↓ | scroll the viewport when it has focus, as any scrolling box |
+| Page Up / Down, Home, End | as any scrolling box |
+
+## Gaps, stated
+
+- The bar has no arrows and no click-on-track paging; the wheel, the keys
+  and dragging the thumb are the ways to move.
+
+## Props
+
+<Controls of={ScrollAreaStories.Default} />

package/src/ScrollArea.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { ScrollArea } from './ScrollArea'
+
+/** A region that scrolls without taking width for its scrollbar. */
+const meta = {
+  title: 'Layout/ScrollArea',
+  component: ScrollArea,
+  parameters: { controls: { disable: true } },
+  args: { children: null },
+} satisfies Meta<typeof ScrollArea>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const rows = Array.from({ length: 40 }, (_, i) => `Row ${i + 1}`)
+
+/** A list taller than its box. The bar shows while the pointer is over it or the list is moving. */
+export const Default: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <ul className="flex flex-col gap-px">
+        {rows.map((row) => (
+          <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </li>
+        ))}
+      </ul>
+    </ScrollArea>
+  ),
+}
+
+/** Nothing to scroll: the region draws exactly as a plain box would, and no bar. */
+export const Fits: Story = {
+  render: () => (
+    <ScrollArea className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <ul className="flex flex-col gap-px">
+        {rows.slice(0, 4).map((row) => (
+          <li key={row} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </li>
+        ))}
+      </ul>
+    </ScrollArea>
+  ),
+}
+
+/** A row wider than its box — a table, a board. */
+export const Horizontal: Story = {
+  render: () => (
+    <ScrollArea orientation="horizontal" className="w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <div className="flex w-max gap-2">
+        {rows.slice(0, 12).map((row) => (
+          <div key={row} className="w-[120px] shrink-0 rounded-md bg-bg-inset px-2 py-1.5 text-body-2 text-text-primary">
+            {row}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+}
+
+/** Both ways, with the corner where the two bars would meet. */
+export const Both: Story = {
+  render: () => (
+    <ScrollArea orientation="both" className="h-[240px] w-[280px] rounded-lg border border-border-default bg-bg-surface" viewportClassName="p-2">
+      <div className="flex w-max flex-col gap-px">
+        {rows.map((row) => (
+          <div key={row} className="w-[480px] rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            {row} — a line long enough to run past the box
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+}

package/src/ScrollArea.test.tsx

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+/**
+ * What jsdom can see of the ScrollArea page: the content renders inside the
+ * region, and the region is Base UI's. Whether the bar takes width, and when
+ * 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 { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ScrollArea } from './ScrollArea'
+
+afterEach(cleanup)
+
+describe('ScrollArea', () => {
+  it('draws the content inside a viewport of its own', () => {
+    const { container } = render(
+      <ScrollArea className="h-40">
+        <p>Inside</p>
+      </ScrollArea>,
+    )
+    const inside = screen.getByText('Inside')
+    expect(container.firstElementChild).not.toBe(inside)
+    expect(container.firstElementChild!.contains(inside)).toBe(true)
+    expect(container.firstElementChild!.className).toContain('h-40')
+  })
+
+  it('puts each class prop on its own box: the region, the viewport, the content', () => {
+    const { container } = render(
+      <ScrollArea className="h-40" viewportClassName="max-h-20" contentClassName="p-2">
+        <p>Inside</p>
+      </ScrollArea>,
+    )
+    const region = container.firstElementChild!
+    const content = screen.getByText('Inside').parentElement!
+    const viewport = content.parentElement!
+    expect(region.className).toContain('h-40')
+    expect(viewport.className).toContain('max-h-20')
+    expect(content.className).toContain('p-2')
+    expect(viewport.parentElement).toBe(region)
+  })
+
+  it('keeps a vertical region no wider than itself, and lets a sideways one grow', () => {
+    const v = render(<ScrollArea><p>Inside</p></ScrollArea>)
+    expect((screen.getByText('Inside').parentElement as HTMLElement).style.minWidth).toBe('0px')
+    cleanup()
+    render(<ScrollArea orientation="horizontal"><p>Inside</p></ScrollArea>)
+    expect((screen.getByText('Inside').parentElement as HTMLElement).style.minWidth).toBe('fit-content')
+    void v
+  })
+})