@estiva-app/ui 0.9.0 → 0.10.0

package/src/Field.test.tsx

@@ -14,12 +14,20 @@
  * associated to that label". That message is the bug stated precisely, and the
  * consumer worked around it by querying by role. The guard belongs here, where
  * the next primitive added under Field will meet it.
+ *
+ * **Stage 3 (2026-09-07) moved the association to Base UI's `Field`**, so the
+ * context and the `useFieldControlId` opt-in are gone. The guard is the same
+ * and matters more, because the mechanism is no longer ours to read.
  */
 import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import { Field } from './Field'
 import { TextInput } from './TextInput'
 import { Textarea } from './Textarea'
+import { Select } from './Select'
+import { SearchInput } from './SearchInput'
+import { ChipInput } from './ChipInput'
+import { Checkbox } from './Checkbox'
 
 // Testing Library registers its own cleanup only when vitest runs with
 // `globals: true`, and this package does not — so the first two tests passed,
@@ -47,9 +55,9 @@ describe('Field', () => {
   })
 
   it('points the label at the control it wraps, not at some other field', () => {
-    // Two Fields on one form is the case a single hardcoded id gets wrong, and
-    // `useId` is what makes it right. Asserted because "it works with one
-    // field" is the version of this that ships broken.
+    // Two Fields on one form is the case a single hardcoded id gets wrong.
+    // Asserted because "it works with one field" is the version of this that
+    // ships broken.
     const { container } = render(
       <form>
         <Field label="Title">
@@ -68,16 +76,13 @@ describe('Field', () => {
     expect(screen.getByLabelText('Description')).toBe(container.querySelector(`#${CSS.escape(ids[1]!)}`))
   })
 
-  it('wins over an id the caller put on the control, rather than breaking the pair', () => {
-    // The first version of this asserted the opposite — that a control keeps
-    // its own id inside a Field — and it failed with this ticket's own error
-    // message, because the label went on pointing at the generated id. Two
-    // halves of one association cannot be set from two places.
-    //
-    // So the Field wins, and `htmlFor` below is how a caller chooses. Silently
-    // overriding an id is a smaller surprise than silently unlabelling a
-    // control, and only one of the two is invisible until somebody uses a
-    // screen reader.
+  it('keeps the pair when the caller names the control itself', () => {
+    // This reverses on Base UI, and the new behaviour is the better one. Ours
+    // made the *Field* win — the control's own id was overridden — because two
+    // halves of one association cannot be set from two places and only the
+    // Field could set both. Base UI sets both from the control's id instead,
+    // so a caller who needs a particular id keeps it and the label follows.
+    // What the test guards is unchanged: the pair holds either way.
     render(
       <Field label="Title">
         <TextInput id="chosen-by-the-caller" defaultValue="" />
@@ -85,33 +90,118 @@ describe('Field', () => {
     )
     const input = screen.getByLabelText('Title')
     expect(input.tagName).toBe('INPUT')
-    expect(input.id).not.toBe('chosen-by-the-caller')
+    expect(input.id).toBe('chosen-by-the-caller')
   })
 
-  it('lets the Field be told the id instead, for the same reason', () => {
+  it('gives a control outside a Field an id of its own, and nothing else', () => {
+    // Also reversed, and worth stating rather than deleting. Ours left a lone
+    // control untouched; Base UI's `Input` always generates an id, because it
+    // cannot know whether a `Field` will describe it. The id is inert — no
+    // label, no `aria-describedby` points at it — so nothing reads differently;
+    // an app that asserted on the absence of `id` is the only thing this
+    // reaches, and neither app does.
+    const { container } = render(<TextInput defaultValue="" />)
+    const input = container.querySelector('input')!
+    expect(input.getAttribute('id')).toBeTruthy()
+    expect(input.getAttribute('aria-labelledby')).toBeNull()
+    expect(input.getAttribute('aria-describedby')).toBeNull()
+  })
+
+  /**
+   * The asterisk is a picture of `required`; `aria-required` is the word for
+   * it. Drawing the mark and telling nobody was all this prop did until
+   * 2026-09-08 — measured, the control carried neither attribute.
+   */
+  it('marks a required field, in the mark and in the control', () => {
     render(
-      <Field label="Title" htmlFor="named-outside">
+      <Field label="Title" required>
         <TextInput defaultValue="" />
       </Field>,
     )
-    expect(screen.getByLabelText('Title').id).toBe('named-outside')
+    expect(screen.getByText('*')).toBeTruthy()
+    const control = screen.getByLabelText(/Title/)
+    expect(control.tagName).toBe('INPUT')
+    expect(control.getAttribute('aria-required')).toBe('true')
   })
 
-  it('leaves a control outside a Field alone', () => {
-    // `useFieldControlId` returns undefined outside a provider, so nothing
-    // acquires a stray id — a control with an id it did not ask for is its own
-    // small bug.
-    const { container } = render(<TextInput defaultValue="" />)
-    expect(container.querySelector('input')?.getAttribute('id')).toBeNull()
+  it('leaves a control that already says so alone', () => {
+    render(
+      <Field label="Title" required>
+        <TextInput defaultValue="" aria-required={false} />
+      </Field>,
+    )
+    expect(screen.getByLabelText(/Title/).getAttribute('aria-required')).toBe('false')
   })
 
-  it('still marks a required field, which was the only thing it did before', () => {
-    render(
+  /**
+   * Every control the package offers, because a promise that holds for two of
+   * them is not a promise. `Select`, `ChipInput` and `Checkbox` take fixed
+   * prop lists rather than spreading what they are given, so each had to be
+   * told — measured 2026-09-08: all three dropped it silently.
+   */
+  it.each([
+    ['TextInput', <TextInput key="t" defaultValue="" />, 'input'],
+    ['Textarea', <Textarea key="a" defaultValue="" />, 'textarea'],
+    ['SearchInput', <SearchInput key="s" />, 'input'],
+    ['Select', <Select key="e" value="a" onChange={() => {}} options={[{ value: 'a', label: 'A' }]} />, '[role="combobox"]'],
+    ['ChipInput', <ChipInput key="c" value={[]} onChange={() => {}} options={[]} />, 'input'],
+    ['Checkbox', <Checkbox key="k" checked={false} onChange={() => {}} />, '[role="checkbox"]'],
+  ])('marks a required %s', (_name, control, selector) => {
+    const { container } = render(
       <Field label="Title" required>
+        {control}
+      </Field>,
+    )
+    expect(container.querySelector(selector)?.getAttribute('aria-required')).toBe('true')
+  })
+
+  it('does not mark a field that is not required', () => {
+    render(
+      <Field label="Title">
         <TextInput defaultValue="" />
       </Field>,
     )
-    expect(screen.getByText('*')).toBeTruthy()
-    expect(screen.getByLabelText(/Title/).tagName).toBe('INPUT')
+    expect(screen.getByLabelText(/Title/).hasAttribute('aria-required')).toBe(false)
+  })
+
+  it('announces the helper line, which the hand-built spans never did', () => {
+    render(
+      <Field label="Folder link" helper="Leave empty and the project gets a Folder of its own.">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    const input = screen.getByLabelText('Folder link')
+    const describedBy = input.getAttribute('aria-describedby')
+    expect(describedBy).toBeTruthy()
+    expect(document.getElementById(describedBy!)?.textContent).toBe('Leave empty and the project gets a Folder of its own.')
+  })
+
+  it('replaces the helper with the error, and marks the control invalid', () => {
+    // Both at once asks the reader to work out which one is live, and the two
+    // callers this prop came from both wrote `error ?? helper`. `aria-invalid`
+    // is Base UI's now — Ship passed it by hand beside every one of these.
+    render(
+      <Field label="Folder link" helper="Leave empty and the project gets a Folder of its own." error="That is not a Folder link.">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    const input = screen.getByLabelText('Folder link')
+    expect(input.getAttribute('aria-invalid')).toBe('true')
+    expect(screen.queryByText('Leave empty and the project gets a Folder of its own.')).toBeNull()
+    const describedBy = input.getAttribute('aria-describedby')
+    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">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    const root = container.firstElementChild!
+    expect(root.children).toHaveLength(2)
+    expect(root.children[1].tagName).toBe('INPUT')
   })
 })

package/src/Field.tsx

@@ -1,78 +1,106 @@
-import { createContext, useContext, useId, type ReactNode } from 'react'
-
-/**
- * The id of the control this Field labels.
- *
- * **A control has to opt in by calling `useFieldControlId`.** The automatic
- * alternative is nesting the control inside the `<label>`, which associates
- * anything by construction and needs no cooperation — and it is not used here,
- * because a control that is *both* nested in a label and named by its `htmlFor`
- * can receive two activations from one click. That is a real hazard for a
- * checkbox and a latent one for everything else, and this library has a
- * `Checkbox`.
- *
- * So: one explicit mechanism, and a test that pins it for every primitive that
- * uses it (`Field.test.tsx`). A new primitive that renders a labelable element
- * calls this hook and spreads the result; one that does not is unlabelled, and
- * the test is where that gets noticed.
- */
-const FieldControlIdContext = createContext<string | undefined>(undefined)
-
-/**
- * The id a surrounding `Field` wants this control to have, falling back to the
- * caller's own outside one.
- *
- * **Inside a Field, the Field wins**, which is the opposite of what I wrote
- * first and the test caught within the minute. Letting a control's own `id`
- * take precedence leaves the label's `htmlFor` pointing at the id the Field
- * generated and the control answering to a different one — which is this
- * ticket's defect exactly, reproduced by the fix for it, and it fails with the
- * same message: *"Found a label with the text of: Title, however no form
- * control was found associated to that label."*
- *
- * A caller who needs to choose the id names it on the Field (`htmlFor`), which
- * is the one place that can set both halves. Outside a Field there is nothing
- * to disagree with, so the caller's id is used.
- */
-export function useFieldControlId(ownId?: string): string | undefined {
-  const fromField = useContext(FieldControlIdContext)
-  return fromField ?? ownId
-}
+import { cloneElement, isValidElement, type ReactElement, type ReactNode } from 'react'
+import { Field as BaseField } from '@base-ui/react/field'
+import { cn } from './cn'
 
 /**
  * Peek's Field (2026-08-28): a label over a control, 8px apart, with a red
- * asterisk when required. The label is the `input-label` type token as a plain
- * class, never merged.
+ * asterisk when required. The label is the `input-label` type token, merged
+ * with `cn()` like every other class list here. On Base UI's `Field` since
+ * stage 3 of the migration (2026-09-07).
  *
- * The label names its control (SHA-17). It did not, and the control was a
+ * The label names its control. It did not once, and the control was a
  * *sibling* of the label with no `htmlFor`, so there was neither an explicit
  * nor an implicit association: a screen reader announced an unlabelled edit
- * box and clicking the label focused nothing.
+ * box and clicking the label focused nothing (SHA-17). That fix used to be
+ * ours — a context carrying a generated id, which every control had to opt
+ * into by calling `useFieldControlId`. **Base UI does it now**, for its own
+ * `Input`, `Checkbox`, `Select` and anything rendered through `Field.Control`,
+ * so a new control is labelled by construction rather than by remembering.
+ *
+ * `helper` and `error` are the line under the control, which Ship built by
+ * hand in two dialogs (`COMPONENTS-SHIP.md` F14) and Peek in four
+ * (`COMPONENTS-PEEK.md` F14), always the same two class lists. **An error
+ * replaces the helper rather than joining it** — that is what those callers
+ * did (`pairError ?? 'Leave empty and…'`), and a field that says both at once
+ * is asking the reader to work out which one is live.
+ *
+ * The line is announced: Base UI wires `aria-describedby` for the helper and
+ * `aria-invalid` + the error's id for the error, which the hand-built spans
+ * never did.
+ *
+ * `required` is announced too, since 2026-09-08. It drew the asterisk and
+ * nothing else — measured, the control carried neither `required` nor
+ * `aria-required`, so the one thing the mark means never reached anybody who
+ * could not see it. Base UI's `Field` has no `required` of its own, so this
+ * puts `aria-required` on the control itself.
  */
 export interface FieldProps {
   label: string
+  /**
+   * Draws the asterisk **and** marks the control `aria-required`, so the mark
+   * means something to a reader who cannot see it. It reaches a single control
+   * element; a `children` of several elements keeps the asterisk and owes its
+   * own `aria-required`.
+   */
   required?: boolean
   /**
-   * Override the generated id. Only needed when something outside has to name
-   * the control — an `aria-describedby` elsewhere, or a form library.
+   * A hint under the control — what the format is, what happens if it is left
+   * empty. `caption`, muted. Hidden while `error` is set.
+   */
+  helper?: string
+  /**
+   * What is wrong, in the same place as the helper and in the error colour.
+   * Setting it also marks the control invalid, so the caller no longer passes
+   * `aria-invalid` itself.
    */
-  htmlFor?: string
+  error?: string
   children: ReactNode
 }
 
-export function Field({ label, required = false, htmlFor, children }: FieldProps) {
-  const generated = useId()
-  const id = htmlFor ?? generated
+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 —
+    `aria-required` rather than the native attribute, because the native one
+    also switches on the browser's own validation bubble, which no field in
+    either app uses. A control that already says so keeps what it says.
+  */
+  const control =
+    required && isValidElement(children)
+      ? cloneElement(children as ReactElement<{ 'aria-required'?: boolean | 'true' | 'false' }>, {
+          'aria-required': (children as ReactElement<{ 'aria-required'?: boolean | 'true' | 'false' }>).props['aria-required'] ?? true,
+        })
+      : children
   return (
-    <div className="flex flex-col gap-2">
-      <label
-        htmlFor={id}
-        className={`text-input-label text-text-primary${required ? ' flex items-center' : ''}`}
-      >
+    <BaseField.Root invalid={!!error} className="flex flex-col gap-2">
+      {/* `cn`, like everywhere else. It was a template literal, with a comment
+          saying the type token must never be merged — which stopped being true
+          when `cn()` was taught the ramp: `input-label` is in it, and
+          `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>}
-      </label>
-      <FieldControlIdContext.Provider value={id}>{children}</FieldControlIdContext.Provider>
-    </div>
+      </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.
+      */}
+      {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>
+      )}
+    </BaseField.Root>
   )
 }

package/src/IconButton.mdx

@@ -43,8 +43,12 @@ import { IconPencil } from '@tabler/icons-react'
 - `type` defaults to `"button"`; it is a native `<button>` on Base UI's
   Button, and every native prop passes through.
 - `disabledReason="Read only"` disables it, keeps it reachable by Tab,
-  and shows the reason in place of the tooltip (on hover for now; on
-  keyboard focus too once Tooltip moves onto Base UI, stage 4).
+  and shows the reason in place of the tooltip — **on keyboard focus as
+  well as on hover**.
+- `tooltip` costs no wrapper: the button is the tooltip's trigger, so
+  this component's root is the `<button>` whether it carries one or not,
+  and both sit at the same height. A `Dialog.Close` or a `Menu.Trigger`
+  can be an IconButton that has a tooltip.
 
 ## Keys
 

package/src/IconButton.test.tsx

@@ -37,7 +37,8 @@ describe('IconButton', () => {
     )
     expect(screen.queryByRole('tooltip')).toBeNull()
     await user.hover(screen.getByRole('button', { name: 'Edit' }))
-    expect(screen.getByRole('tooltip').textContent).toBe('EditE')
+    // 300ms before it opens (D23) - it used to be instant.
+    expect((await screen.findByRole('tooltip')).textContent).toBe('EditE')
   })
 
   it('disabledReason: disabled, reachable by Tab, the reason replaces the tooltip', async () => {
@@ -55,8 +56,10 @@ describe('IconButton', () => {
     expect(onClick).not.toHaveBeenCalled()
     await user.tab()
     expect(document.activeElement).toBe(button)
+    // Already open, in fact: the Tab above focused it, and focus opens
+    // with no delay at all.
     await user.hover(button)
-    expect(screen.getByRole('tooltip').textContent).toBe('Read only')
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Read only')
   })
 
   it('Space and Enter are the action, and nothing while disabled with a reason', async () => {

package/src/IconButton.tsx

@@ -1,7 +1,7 @@
-import type { ButtonHTMLAttributes, ReactNode } from 'react'
+import type { ComponentPropsWithRef, ReactNode } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
 import { cn } from './cn'
-import { WithTooltip } from './Tooltip'
+import { TooltipTrigger } from './Tooltip'
 
 /**
  * Peek's IconButton (2026-08-28), verbatim: a square 4px-padded button
@@ -15,7 +15,8 @@ import { WithTooltip } from './Tooltip'
  */
 export type IconButtonVariant = 'muted' | 'outlined' | 'primary'
 
-export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+/** `ComponentPropsWithRef` so a `ref` reaches the element — see Button. */
+export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
   variant?: IconButtonVariant
   tooltip?: string
   /** A key hint drawn as the `Kbd` chip inside the tooltip — for a button
@@ -55,7 +56,12 @@ export function IconButton({
           state.disabled && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
           state.disabled && variant === 'muted' && 'text-text-disabled',
           state.disabled && variant === 'outlined' && 'border border-border-default text-text-disabled',
-          state.disabled && 'pointer-events-none cursor-not-allowed',
+          // `pointer-events-none` only where the button is truly out of reach:
+          // with a `disabledReason` the button IS the tooltip's trigger, and a
+          // trigger the pointer cannot land on never opens one. Base UI already
+          // swallows the click.
+          state.disabled && !disabledReason && 'pointer-events-none',
+          state.disabled && 'cursor-not-allowed',
           className,
         )
       }
@@ -68,9 +74,9 @@ export function IconButton({
   const label = disabledReason ?? tooltip
   if (label) {
     return (
-      <WithTooltip label={label} shortcut={disabledReason ? undefined : tooltipShortcut} placement={tooltipPlacement}>
+      <TooltipTrigger label={label} shortcut={disabledReason ? undefined : tooltipShortcut} placement={tooltipPlacement}>
         {button}
-      </WithTooltip>
+      </TooltipTrigger>
     )
   }
   return button

package/src/IdentityMenu.mdx

@@ -50,12 +50,35 @@ import { IdentityMenu } from '@estiva-app/ui'
   receive `close`, so a row can shut the menu before opening what it
   opens.
 - Items are text only — no icons in this menu, by ruling.
-- **IdentityPanel** is exported alone for a surface that wants the panel
-  without the trigger; the stories render it, so the designed artifact is
-  what you review.
-- The trigger's toggle, `aria-expanded`, and the accessible-name rules
-  (the row is named by the person; only the bare compact face takes an
-  `aria-label`) are wired inside — bring nothing.
+- **IdentityPanel** draws the same rows as a plain surface, without the menu
+  around them — for a docs canvas, or a surface that wants the panel and not
+  the trigger.
+- The trigger's toggle, its `aria-expanded`, the placement, the focus return
+  and the accessible-name rules (the row is named by the person; only the bare
+  compact face takes an `aria-label`) are all wired inside — bring nothing.
+- **The panel hangs from the face, not from the wrapper around it** (stage 4).
+  It used to hang from the wrapper, whose box belongs to the app's layout: in
+  a flex row with the default `align-items: stretch` the wrapper takes the
+  row's full height, and the panel hung from the bottom of *that* — measured
+  360px below the face, with a scrollbar it should not have had.
+
+## Keys
+
+Since stage 4 the panel is a Base UI `Menu`, and **the arrow keys walk the
+actions only** (Katerina, D22): they step over the identity block, the
+workspace line and the notes, because those are not things you can do.
+
+| Input | What happens |
+|---|---|
+| click / Enter / Space on the face | opens the menu |
+| ↑ / ↓ | move between the actions — Edit your profile, Copy public key, Sign out, and any row the app adds — and wrap |
+| Enter on an action | runs it, and closes the menu |
+| Escape | closes, and gives focus back to the face |
+| a press on the face while open | closes it |
+
+The identity and workspace sections are `Menu.Group`s labelled by their
+headings, so a screen reader announces them as named groups rather than as
+menu items that are not items.
 
 ## Props
 

package/src/IdentityMenu.stories.tsx

@@ -1,15 +1,25 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IdentityPanel } from './IdentityMenu'
+import { IdentityMenu, IdentityPanelSurface } from './IdentityMenu'
 
 /**
- * The menu itself, standing in flow (`static` beats the anchoring, as the
- * Menu stories do it) — no trigger, no bar chrome: the trigger's shapes are
+ * The panel itself — no trigger, no bar chrome: the trigger's shapes are
  * PersonTrigger's own stories. In an app, `IdentityMenu` bundles that
  * trigger with this panel.
+ *
+ * Drawn here on a `MenuPanel`, the menu's surface without its behaviour: a
+ * real menu portals and places itself against a trigger, so it cannot stand
+ * in a docs page, and the canvas must still show the artifact (Katerina,
+ * D25). The rows are the same ones the app gets.
+ *
+ * Since stage 4 the live panel is a Base UI `Menu`: **the arrow keys walk
+ * the actions and step over the identity block, the workspace line and the
+ * notes** (Katerina, D22). Those sections are `Menu.Group`s with the heading
+ * as their label, so they are announced as named groups rather than as menu
+ * items that are not items.
  */
 const meta = {
   title: 'Navigation/IdentityMenu',
-  component: IdentityPanel,
+  component: IdentityPanelSurface,
   args: {
     me: {},
     signedIn: false,
@@ -17,10 +27,9 @@ const meta = {
     onCopyKey: () => {},
     onSignOut: () => {},
     onClose: () => {},
-    className: 'static',
   },
   argTypes: { onClose: { control: false }, className: { control: false } },
-} satisfies Meta<typeof IdentityPanel>
+} satisfies Meta<typeof IdentityPanelSurface>
 
 export default meta
 type Story = StoryObj<typeof meta>
@@ -54,3 +63,29 @@ export const MinimalApp: Story = {
     onCopyKey: undefined,
   },
 }
+
+/**
+ * The whole thing, live: the trigger in the top bar and the menu it opens.
+ * Click the face, then try the keyboard — ↑ and ↓ walk **the actions only**,
+ * stepping over the identity block, the workspace line and the notes (D22);
+ * Escape closes it and gives focus back to the trigger.
+ */
+export const FromItsTrigger: Story = {
+  parameters: { controls: { disable: true }, layout: 'padded' },
+  render: () => (
+    /* A top bar, and room under it for the panel: 288 x ~380. `items-center`
+       is how both apps lay their bar out. */
+    <div className="h-[560px] w-full">
+      <div className="flex h-12 items-center justify-end border-b border-border-subtle px-4">
+      <IdentityMenu
+        me={{ name: 'Ana Duarte', email: 'ana@example.com' }}
+        signedIn
+        idBase="https://id.estiva.app"
+        relayUrl="http://localhost:3000"
+        onCopyKey={() => {}}
+        onSignOut={() => {}}
+      />
+      </div>
+    </div>
+  ),
+}