@estiva-app/ui 0.9.0 → 0.10.0

package/src/DialogShell.tsx

@@ -1,5 +1,6 @@
-import { useEffect, type ReactNode } from 'react'
-import { createPortal } from 'react-dom'
+import { useRef, type ReactNode } from 'react'
+import { Dialog } from '@base-ui/react/dialog'
+import { AlertDialog } from '@base-ui/react/alert-dialog'
 import { IconX } from '@tabler/icons-react'
 import { cn } from './cn'
 import { IconButton } from './IconButton'
@@ -8,8 +9,25 @@ import { IconButton } from './IconButton'
  * Peek's DialogShell (2026-08-28), verbatim: the portal, the backdrop, the
  * 502px card and its chrome — a 48px header with the title and a close
  * button, a body, a 48px footer for the buttons. A dialog is just what goes
- * in the three slots. Plus what Ship added: Escape closes it, and the card
- * says what it is to assistive tech.
+ * in the three slots. On Base UI's `Dialog` since stage 3 of the migration
+ * (2026-09-07).
+ *
+ * **What that fixed, and this page used to say it did not:** focus is trapped
+ * inside the card, so Tab cannot walk out into the page behind it, and it
+ * returns to whatever opened the dialog when it closes. Both were missing and
+ * both were written down as missing. The portal, the outside press and the
+ * Escape key are Base UI's too — the `keydown` listener this file kept on
+ * `document` is gone, and with it the bug where two open dialogs both closed
+ * on one Escape.
+ *
+ * The card is mounted only while it is open, as before: this component has no
+ * `open` prop, and a caller renders it or does not. So `open` is `true` and
+ * `onOpenChange` reports the ways Base UI closes it — Escape, a press outside,
+ * the close button — through the one `onClose` the callers already pass.
+ *
+ * The DOM is the same shape it was, deliberately: a backdrop, then a
+ * full-screen flex layer that centres the card. Base UI positions nothing for
+ * a dialog, so keeping the layer is what keeps the pixels.
  */
 export interface DialogShellProps {
   /** Labels the dialog for assistive tech, and renders as the header text
@@ -26,47 +44,98 @@ export interface DialogShellProps {
   /** Extra classes on the body (e.g. `flex flex-col gap-6`, or a max height with `overflow-y-auto`). */
   bodyClassName?: string
   width?: number
+  /**
+   * A question that has to be answered rather than clicked away: a press on
+   * the backdrop no longer closes it, and it announces itself as an alert.
+   * Escape and the close button still work. `ConfirmDialog` is this
+   * (Katerina, D20, 2026-09-07); a form or a roster is not.
+   */
+  alert?: boolean
 }
 
-export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, width = 502 }: DialogShellProps) {
-  useEffect(() => {
-    const onKey = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') onClose()
-    }
-    document.addEventListener('keydown', onKey)
-    return () => document.removeEventListener('keydown', onKey)
-  }, [onClose])
+export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, 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.
+  const Parts = alert ? AlertDialog : Dialog
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <Parts.Root
+      open
+      onOpenChange={(open) => {
+        if (!open) onClose()
+      }}
+    >
+      <Parts.Portal>
+        {/* Backdrop */}
+        <Parts.Backdrop className="fixed inset-0 z-40 bg-scrim" />
 
-  return createPortal(
-    <>
-      {/* Backdrop */}
-      <div className="fixed inset-0 z-40 bg-scrim" onClick={onClose} />
+        {/* Dialog */}
+        <div className="fixed inset-0 z-50 flex items-center justify-center pointer-events-none">
+          <Parts.Popup
+            ref={popupRef}
+            /*
+              Focus the card, not the first control in it.
 
-      {/* Dialog */}
-      <div className="fixed inset-0 z-50 flex items-center justify-center pointer-events-none">
-        <div
-          role="dialog"
-          aria-modal="true"
-          aria-label={title}
-          className="bg-bg-elevated border border-border-subtle rounded-lg shadow-lg pointer-events-auto flex flex-col overflow-hidden"
-          style={{ width }}
-        >
-          {/* Header */}
-          <div className="h-12 flex items-center justify-between pl-5 pr-4 border-b border-border-subtle shrink-0">
-            {headerContent ?? <span className="text-h4 text-text-primary">{title}</span>}
-            <IconButton tooltip="Close" aria-label="Close" onClick={onClose}>
-              <IconX size={16} stroke={1.5} />
-            </IconButton>
-          </div>
+              Base UI's default is the first tabbable element, which here is the
+              ✕ in the header — so every dialog opened with a visible ring on
+              its close button, which the screenshot diff caught as a 28px
+              square nobody had asked for. Focusing the card arms the trap and
+              lets a screen reader read the dialog, with no control lit up.
 
-          {/* Body */}
-          <div className={cn('pl-5 pr-4 py-4', footer != null && 'border-b border-border-subtle', bodyClassName)}>{children}</div>
+              A field with `autoFocus` still wins: React focuses it while the
+              popup mounts, and Base UI does not move focus that has already
+              landed inside. Both dialogs in Ship rely on that.
+            */
+            initialFocus={popupRef}
+            /* The header names it when the header is the title. When
+               `headerContent` replaces that text there is nothing to point at,
+               so the name is spelled instead — as this component always did. */
+            aria-label={headerContent != null ? title : undefined}
+            /* `outline-none` because the card is a programmatic focus target,
+               not something a keyboard user tabs to: without it Chrome rings
+               the whole 502px card on open, which the diff caught the moment
+               `initialFocus` moved off the ✕. The controls inside keep their
+               own focus styling. */
+            className="bg-bg-elevated border border-border-subtle rounded-lg shadow-lg pointer-events-auto flex flex-col overflow-hidden outline-none"
+            style={{ width }}
+          >
+            {/* Header */}
+            <div className="h-12 flex items-center justify-between pl-5 pr-4 border-b border-border-subtle shrink-0">
+              {headerContent ?? (
+                <Parts.Title className="text-h4 text-text-primary" render={<span />}>
+                  {title}
+                </Parts.Title>
+              )}
+              {/*
+                The ✕ IS the `Close` part now, rather than a button that calls
+                `onClose` beside one (stage 4, 2026-09-07). Stage 3 could not do
+                this: an `IconButton` carrying a `tooltip` returned the tooltip
+                wrapper `<div>` as its root, so the part composed onto the
+                wrapper and not the button. Porting Tooltip removed the wrapper
+                — the trigger is the button itself — and the composition works.
 
-          {/* Footer */}
-          {footer != null && <div className="h-12 flex items-center justify-end gap-2 pl-5 pr-4 shrink-0">{footer}</div>}
+                What it buys: the dialog closes through its own state machine,
+                so the ✕, Escape and the outside press are one path with one
+                reason attached, instead of one of the three going around.
+              */}
+              <Parts.Close
+                render={
+                  <IconButton tooltip="Close" aria-label="Close">
+                    <IconX size={16} stroke={1.5} />
+                  </IconButton>
+                }
+              />
+            </div>
+
+            {/* Body */}
+            <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>}
+          </Parts.Popup>
         </div>
-      </div>
-    </>,
-    document.body,
+      </Parts.Portal>
+    </Parts.Root>
   )
 }

package/src/EditableText.mdx

@@ -40,7 +40,12 @@ import { EditableText } from '@estiva-app/ui'
 - `onCommit` resolves `true` to close; `false` (or a throw) keeps the
   field open — you have already told the person why. An unchanged value is
   not committed at all.
-- `label` is required — it is the field's accessible name.
+- `label` is required — it is the field's accessible name. This one is
+  spelled rather than taken from a `Field`: the component is a line of text
+  that becomes a field, and it is used where there is no label to read.
+- The editing state is Base UI's `Input` since stage 3, or `Field.Control`
+  as a `<textarea>` when `multiline`. **Everything below is ours**, because
+  Base UI has no inline-edit part and no opinion about what an edit means.
 - `display` shows something other than what is edited (a value carrying
   raw references, rendered richer when read) without losing the original
   on commit.

package/src/EditableText.test.tsx

@@ -0,0 +1,156 @@
+// @vitest-environment jsdom
+/**
+ * What the EditableText page claims, pinned.
+ *
+ * It had no test file, and it is the component in the package with the most
+ * rules of its own: Base UI supplies the field and nothing else, so *every*
+ * sentence on its page — Enter commits, Escape cancels, blur commits, an
+ * unchanged value is not committed, a refused commit keeps the text — is this
+ * file's code and was held by nothing.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { EditableText } from './EditableText'
+
+afterEach(cleanup)
+
+const read = () => screen.getByRole('button', { name: 'Edit title' })
+const field = () => screen.getByRole('textbox', { name: 'Title' })
+
+describe('EditableText: reading', () => {
+  it('reads as a button named for what it edits', () => {
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={() => true} />)
+    expect(read().textContent).toBe('Item one')
+  })
+
+  it('shows the placeholder when there is nothing yet', () => {
+    render(<EditableText value="" placeholder="Untitled" label="Title" onCommit={() => true} />)
+    expect(read().textContent).toBe('Untitled')
+  })
+
+  it('`display` changes what is shown, never what is edited', async () => {
+    const user = userEvent.setup()
+    render(<EditableText value="Item one [ref]" display="Item one" placeholder="Untitled" label="Title" onCommit={() => true} />)
+    expect(read().textContent).toBe('Item one')
+    await user.click(read())
+    expect((field() as HTMLInputElement).value).toBe('Item one [ref]')
+  })
+
+  it('read-only shows the value and offers no way in', () => {
+    render(<EditableText readOnly value="Item one" placeholder="Untitled" label="Title" onCommit={() => true} />)
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByText('Item one')).toBeTruthy()
+  })
+})
+
+describe('EditableText: editing', () => {
+  it('a click opens the field with the value in it, selected', async () => {
+    const user = userEvent.setup()
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={() => true} />)
+    await user.click(read())
+    const input = field() as HTMLInputElement
+    expect(input.value).toBe('Item one')
+    // Selected, so typing replaces rather than appends — what a rename is.
+    expect([input.selectionStart, input.selectionEnd]).toEqual([0, 'Item one'.length])
+  })
+
+  it('Enter commits the trimmed value and closes', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={onCommit} />)
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}  Item two  {Enter}')
+    expect(onCommit).toHaveBeenCalledWith('Item two')
+  })
+
+  it('Escape restores the value and closes without committing', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={onCommit} />)
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}Item two{Escape}')
+    expect(onCommit).not.toHaveBeenCalled()
+    expect(read().textContent).toBe('Item one')
+  })
+
+  it('blur commits, because leaving a field is not cancelling', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(
+      <>
+        <EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={onCommit} />
+        <button type="button">Elsewhere</button>
+      </>,
+    )
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}Item two')
+    await user.click(screen.getByRole('button', { name: 'Elsewhere' }))
+    expect(onCommit).toHaveBeenCalledWith('Item two')
+  })
+
+  /** Nothing changed, so there is nothing to save — and a caller that writes
+   *  on every commit would otherwise write on every glance. */
+  it('an unchanged value is not committed', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={onCommit} />)
+    await user.click(read())
+    await user.keyboard('{Enter}')
+    expect(onCommit).not.toHaveBeenCalled()
+    expect(read()).toBeTruthy()
+  })
+
+  /** The caller has already said why, in its own banner. Closing the field
+   *  here would throw the edit away on top of that. */
+  it('a refused commit keeps the field open with the text still in it', async () => {
+    const user = userEvent.setup()
+    render(<EditableText value="Item one" placeholder="Untitled" label="Title" onCommit={() => false} />)
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}Item two{Enter}')
+    expect((field() as HTMLInputElement).value).toBe('Item two')
+  })
+
+  it('a commit that throws does the same', async () => {
+    const user = userEvent.setup()
+    render(
+      <EditableText
+        value="Item one"
+        placeholder="Untitled"
+        label="Title"
+        onCommit={() => {
+          throw new Error('the caller has shown why')
+        }}
+      />,
+    )
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}Item two{Enter}')
+    expect((field() as HTMLInputElement).value).toBe('Item two')
+  })
+})
+
+describe('EditableText: multiline', () => {
+  it('edits in a textarea, and Shift+Enter is a new line rather than a commit', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(<EditableText multiline value="Line one" placeholder="Untitled" label="Title" onCommit={onCommit} />)
+    await user.click(read())
+    const area = screen.getByRole('textbox', { name: 'Title' }) as HTMLTextAreaElement
+    expect(area.tagName).toBe('TEXTAREA')
+    await user.keyboard('{Shift>}{Enter}{/Shift}Line two')
+    expect(onCommit).not.toHaveBeenCalled()
+    // The value opens SELECTED, here as everywhere, so the first keystroke
+    // replaces it — the newline included. Worth knowing for a multiline field:
+    // one key on an opened description replaces the whole body.
+    expect(area.value).toBe('\nLine two')
+  })
+
+  it('and plain Enter still commits', async () => {
+    const user = userEvent.setup()
+    const onCommit = vi.fn(() => true)
+    render(<EditableText multiline value="Line one" placeholder="Untitled" label="Title" onCommit={onCommit} />)
+    await user.click(read())
+    await user.keyboard('{Control>}a{/Control}Line two{Enter}')
+    expect(onCommit).toHaveBeenCalledWith('Line two')
+  })
+})

package/src/EditableText.tsx

@@ -1,4 +1,6 @@
 import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode, type RefObject } from 'react'
+import { Field as BaseField } from '@base-ui/react/field'
+import { Input } from '@base-ui/react/input'
 import { cn } from './cn'
 
 /**
@@ -6,6 +8,12 @@ import { cn } from './cn'
  * own comment always called it a package candidate: nothing here knows what
  * is being edited.
  *
+ * The editing state is Base UI's `Input` — or `Field.Control` as a
+ * `<textarea>` when multiline — since stage 3 of the migration (2026-09-07).
+ * The read state, the draft, and every rule about committing stay here:
+ * Base UI has no opinion about what an edit means, and this component is
+ * nothing but that opinion.
+ *
  * Reads as text until clicked; then it is a field. Enter commits (Shift+Enter
  * is a new line when multiline), Escape cancels, blur commits. A commit that
  * fails keeps the field open with the text in it, so an edit is never
@@ -114,8 +122,13 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
 
   if (readOnly) {
     return (
+      /*
+        No `aria-label` here. It sat on a bare `<div>`, which has no role, and
+        ARIA does not let an author name a generic element — so the name was
+        written and never read. Read-only, this is a line of text: whatever
+        names the region around it (a `Field`, a `Property`) names this too.
+      */
       <div
-        aria-label={label}
         className={cn('w-full px-2 py-1', multiline && !displayNode && 'whitespace-pre-wrap', (display ?? value) ? 'text-text-primary' : 'text-text-muted', className)}
       >
         {(display ?? value) ? (displayNode ?? (display ?? value)) : placeholder}
@@ -125,11 +138,11 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
 
   if (editing) {
     return multiline ? (
-      <textarea
+      <BaseField.Control
         ref={fieldRef as RefObject<HTMLTextAreaElement>}
+        render={<textarea rows={4} />}
         aria-label={label}
         value={draft}
-        rows={4}
         disabled={busy}
         onChange={(event) => setDraft(event.target.value)}
         onKeyDown={onKeyDown}
@@ -137,7 +150,7 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
         className={fieldClass}
       />
     ) : (
-      <input
+      <Input
         ref={fieldRef as RefObject<HTMLInputElement>}
         aria-label={label}
         value={draft}
@@ -154,7 +167,12 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
     <button
       type="button"
       onClick={open}
-      title="Click to edit"
+      /*
+        No `title`. It was the one native browser tooltip left in the package —
+        its own timing, its own look, no theme — saying "Click to edit" beside
+        an `aria-label` that already says it. The hover border is the
+        affordance, and anything that needs a designed hint uses `WithTooltip`.
+      */
       aria-label={`Edit ${label.toLowerCase()}`}
       className={cn(
         'w-full rounded-md border border-transparent px-2 py-1 text-left transition-colors hover:border-border-default',

package/src/Field.mdx

@@ -26,13 +26,33 @@ token; `required` marks it with the error-coloured asterisk.
 ```tsx
 import { Field, TextInput } from '@estiva-app/ui'
 
-<Field label="Name" required>
+<Field label="Name" required helper="One line, and it can be changed later.">
   <TextInput value={name} onChange={(e) => setName(e.target.value)} />
 </Field>
 ```
 
-The label is visual, not wired: also give the control its accessible name
-(`aria-label`, or an `id`/`htmlFor` pair of your own) so the two agree.
+- **The label names the control. Add nothing.** No `aria-label`, no
+  `id`/`htmlFor` pair — this page asked for both until stage 3 and the
+  advice was already stale. Base UI's `Field` associates the pair, for its
+  own `Input` and `Checkbox`, for `TextInput`, `Textarea` and
+  `SearchInput`, and for anything else rendered through `Field.Control`. A
+  control you write yourself is the one case that still has to opt in, by
+  being one of those.
+- An `id` you set on the control is kept, and the label follows it. That
+  reversed at stage 3: the Field used to win and override it.
+- `helper` is the line under the control — the format, or what happens if
+  it is left empty. `error` **replaces** it and marks the control invalid,
+  so you no longer pass `aria-invalid` yourself. Both are announced;
+  Ship and Peek wrote this line by hand six times between them, and none of
+  those was.
+- With neither, the control stays a direct child of the field, so nothing
+  that predates the two props moved a pixel.
+- **`required` marks the control as well as the label.** The asterisk is a
+  picture of the requirement; `aria-required` on the control is the word for
+  it, and the control had neither until 2026-09-08 — measured. Base UI's
+  `Field` has no `required` of its own, so the Field puts it there. A control
+  that says so already is left alone, and a `children` of several elements
+  keeps the asterisk and owes its own.
 
 ## Props
 

package/src/Field.stories.tsx

@@ -20,3 +20,38 @@ export const Required: Story = { args: { label: 'Title', required: true, childre
 export const WithTextarea: Story = {
   args: { label: 'Resolution message (optional)', children: <Textarea placeholder="Summarise the outcome…" className="h-[109px]" /> },
 }
+
+/** A hint under the control: what the format is, or what happens if it is left empty. */
+export const WithHelper: 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 }] } } },
+  args: {
+    label: 'Label',
+    helper: 'Leave this empty and one is made for you.',
+    children: <TextInput placeholder="Placeholder" />,
+  },
+}
+
+/** The error takes the helper's place rather than joining it, and marks the control invalid. */
+export const WithError: Story = {
+  args: {
+    label: 'Label',
+    helper: 'Leave this empty and one is made for you.',
+    error: 'That is not a valid value.',
+    children: <TextInput defaultValue="Not a valid value" />,
+  },
+}
+
+/** Required, with a helper — the three parts of a field at once. */
+export const RequiredWithHelper: 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 }] } } },
+  args: {
+    label: 'Label',
+    required: true,
+    helper: 'One line, and it can be changed later.',
+    children: <TextInput placeholder="Placeholder" />,
+  },
+}