@estiva-app/ui 0.12.8 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "test:a11y": "vitest run --project storybook-signal --project storybook-ship",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "gates:status": "node scripts/gates-status.mjs",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/src/ChipInput.mdx

@@ -55,6 +55,15 @@ import { ChipInput } from '@estiva-app/ui'
   arrow keys move through the suggestions, and a screen reader is told which
   one is highlighted. The list is as wide as the field and hangs below it,
   or above when there is no room.
+- **The field's name.** Inside a `Field`, the label names it — pass nothing.
+  Anywhere else, pass `aria-label`, or `aria-labelledby` pointing at a
+  visible label such as a "To:". With neither, the placeholder is the name,
+  and it stays the name after the first chip stops it being drawn.
+
+```tsx
+<span id="to-label">To:</span>
+<ChipInput aria-labelledby="to-label" value={chosen} onChange={setChosen} options={directory} />
+```
 
 ## Keys
 

package/src/ChipInput.stories.tsx

@@ -29,10 +29,6 @@ const meta = {
   title: 'Inputs/ChipInput',
   component: ChipInput,
   parameters: {
-    // axe label is off here: once a chip is in the field the input drops its placeholder
-    // and has no name of its own, and no prop lets the caller give it one. Settled at the
-    // Combobox port (PLAN.md stage 5).
-    a11y: { config: { rules: [{ id: 'label', enabled: false }] } },
     // The suggestion list portals to document.body at fixed coordinates —
     // render docs usage in an iframe so it lands where the field is.
     docs: { story: { inline: false, height: '320px' } },

package/src/ChipInput.test.tsx

@@ -13,7 +13,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { useState } from 'react'
-import { ChipInput, type ChipInputOption } from './ChipInput'
+import { ChipInput, InputChip, type ChipInputOption } from './ChipInput'
+import { Field } from './Field'
 
 afterEach(cleanup)
 
@@ -23,7 +24,17 @@ const PEOPLE: ChipInputOption[] = [
   { id: 'alan', label: 'Alan Turing', description: 'Mathematician' },
 ]
 
-function Harness({ initial = [], excludeIds, onChange }: { initial?: ChipInputOption[]; excludeIds?: string[]; onChange?: (v: ChipInputOption[]) => void }) {
+function Harness({
+  initial = [],
+  excludeIds,
+  onChange,
+  naming,
+}: {
+  initial?: ChipInputOption[]
+  excludeIds?: string[]
+  onChange?: (v: ChipInputOption[]) => void
+  naming?: { 'aria-label'?: string; 'aria-labelledby'?: string }
+}) {
   const [value, setValue] = useState(initial)
   return (
     <ChipInput
@@ -35,6 +46,7 @@ function Harness({ initial = [], excludeIds, onChange }: { initial?: ChipInputOp
       options={PEOPLE}
       excludeIds={excludeIds}
       placeholder="Search people"
+      {...naming}
     />
   )
 }
@@ -139,4 +151,68 @@ describe('ChipInput', () => {
     await user.keyboard('{Escape}')
     expect(reachedOutside).toHaveBeenCalledTimes(1)
   })
+
+  describe('the field’s name (PLAN Finding 6)', () => {
+    /* Chrome names an empty field by its placeholder, and the first chip takes
+       the placeholder away. Measured in Chrome's accessibility tree before this
+       was fixed: with a chip in, the name was "". */
+    it('keeps the placeholder as its name once a chip takes the placeholder away', () => {
+      render(<Harness initial={[PEOPLE[0]]} />)
+      const input = screen.getByRole('combobox', { name: 'Search people' })
+      expect(input.getAttribute('placeholder')).toBe('')
+    })
+
+    it('adds no name of its own while the placeholder is still drawn', () => {
+      render(<Harness />)
+      expect(screen.getByRole('combobox').getAttribute('aria-label')).toBeNull()
+    })
+
+    it('takes a caller’s aria-label over the placeholder', () => {
+      render(<Harness initial={[PEOPLE[0]]} naming={{ 'aria-label': 'To' }} />)
+      expect(screen.getByRole('combobox', { name: 'To' })).toBeTruthy()
+    })
+
+    it('takes a caller’s aria-labelledby — a visible “To:”', () => {
+      render(
+        <div>
+          <span id="to">To:</span>
+          <Harness initial={[PEOPLE[0]]} naming={{ 'aria-labelledby': 'to' }} />
+        </div>,
+      )
+      expect(screen.getByRole('combobox', { name: 'To:' })).toBeTruthy()
+    })
+
+    /* The trap this pins: Base UI copies a caller's prop over its own even when
+       it is `undefined`, so an `aria-labelledby` passed through empty would wipe
+       the `Field`'s and the placeholder would name the field instead. */
+    it('inside a Field, is named by the Field’s label, chip or no chip', () => {
+      render(
+        <>
+          <Field label="Invite people">
+            <Harness />
+          </Field>
+          <Field label="Reviewers">
+            <Harness initial={[PEOPLE[0]]} />
+          </Field>
+        </>,
+      )
+      expect(screen.getByRole('combobox', { name: 'Invite people' })).toBeTruthy()
+      expect(screen.getByRole('combobox', { name: 'Reviewers' })).toBeTruthy()
+    })
+  })
+})
+
+describe('InputChip', () => {
+  it('its ✕ is a button named for the chip, and removes it', async () => {
+    const user = userEvent.setup()
+    const onRemove = vi.fn()
+    render(<InputChip label="Label" onRemove={onRemove} />)
+    await user.click(screen.getByRole('button', { name: 'Remove Label' }))
+    expect(onRemove).toHaveBeenCalledTimes(1)
+  })
+
+  it('draws no ✕ without onRemove', () => {
+    render(<InputChip label="Label" />)
+    expect(screen.queryByRole('button')).toBeNull()
+  })
 })

package/src/ChipInput.tsx

@@ -1,4 +1,5 @@
 import { useMemo, useState, type KeyboardEvent, type ReactNode } from 'react'
+import { Button as BaseButton } from '@base-ui/react/button'
 import { Combobox } from '@base-ui/react/combobox'
 import { IconX } from '@tabler/icons-react'
 import { cn } from './cn'
@@ -45,8 +46,12 @@ export function InputChip({ label, leading, onRemove, className }: InputChipProp
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>
       {leading && <span className="flex shrink-0 items-center">{leading}</span>}
       <span className={CHIP_LABEL}>{label}</span>
+      {/* Base UI's `Button`, as every button in the package is (D6). Base UI
+          has no chip of its own — its only chips are `Combobox.Chip` and
+          `ChipRemove`, which throw outside a combobox — so the ✕ is the one
+          part of a chip standing alone that it has a counterpart for. */}
       {onRemove && (
-        <button
+        <BaseButton
           type="button"
           onClick={(e) => {
             e.stopPropagation()
@@ -56,7 +61,7 @@ export function InputChip({ label, leading, onRemove, className }: InputChipProp
           aria-label={`Remove ${label}`}
         >
           <IconX size={10} stroke={1.5} />
-        </button>
+        </BaseButton>
       )}
     </div>
   )
@@ -112,6 +117,14 @@ export interface ChipInputProps<T extends ChipInputOption = ChipInputOption> {
   rowLeading?: (option: T) => ReactNode
   /** Set by a `Field` with `required`; a caller inside one owes nothing. */
   'aria-required'?: boolean | 'true' | 'false'
+  /**
+   * The field's name, for a caller that is not inside a `Field` — a `Field`'s
+   * label names it already. With neither this nor `aria-labelledby`, the
+   * placeholder is the name, and it stays the name once a chip is in.
+   */
+  'aria-label'?: string
+  /** The id of what names the field on the page — a visible "To:", say. */
+  'aria-labelledby'?: string
 }
 
 export function ChipInput<T extends ChipInputOption = ChipInputOption>({
@@ -158,6 +171,21 @@ export function ChipInput<T extends ChipInputOption = ChipInputOption>({
      the open state is this component's and not the part's. */
   const open = query.trim().length > 0
 
+  /* The field's name (PLAN Finding 6). With no chip, Chrome names the field
+     by its placeholder; the first chip takes the placeholder away, and the
+     field was left with no name at all (measured: ""). So the placeholder
+     stays on as the name once it is no longer drawn. A caller's own name
+     wins, and so does a `Field`'s label: Base UI points `aria-labelledby` at
+     it, and a label by reference outranks `aria-label`.
+     Only a name that exists is passed. Base UI copies a caller's prop over its
+     own even when the value is `undefined`, so an `aria-labelledby` written
+     out empty would wipe the `Field`'s. */
+  const ariaLabel = aria['aria-label'] ?? (value.length > 0 ? placeholder : undefined)
+  const naming = {
+    ...(ariaLabel !== undefined && { 'aria-label': ariaLabel }),
+    ...(aria['aria-labelledby'] !== undefined && { 'aria-labelledby': aria['aria-labelledby'] }),
+  }
+
   function removeLast() {
     if (value.length > 0) onChange(value.slice(0, -1))
   }
@@ -213,6 +241,7 @@ export function ChipInput<T extends ChipInputOption = ChipInputOption>({
           autoFocus={autoFocus}
           placeholder={value.length === 0 ? placeholder : ''}
           aria-required={aria['aria-required']}
+          {...naming}
           onKeyDown={onInputKeyDown}
           className="flex-1 min-w-[120px] bg-transparent text-body-2 text-text-primary placeholder:text-text-muted outline-none border-none"
         />

package/src/Menu.test.tsx

@@ -326,3 +326,23 @@ describe('rows on a bare MenuPanel', () => {
     expect(screen.queryByRole('group')).toBeNull()
   })
 })
+
+/** As `Popover`: the padding is the content's, and a caller sets it there
+ *  (PLAN Finding 60 — Peek's Later menu asked for `p-1` on `className` and got
+ *  12px from 0.12.6 on). */
+describe('Menu, padding', () => {
+  it('takes a caller’s padding on contentClassName, instead of the 8px', async () => {
+    render(
+      <Menu trigger={<Button>Open</Button>} contentClassName="p-1">
+        <MenuItem label="Item one" onClick={() => {}} />
+      </Menu>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const row = await screen.findByRole('menuitem', { name: 'Item one' })
+    // The scrolling content is the box that carries the separator rule.
+    const content = row.closest('[class*="role=separator"]') as HTMLElement
+    const classes = content.className.split(/\s+/)
+    expect(classes).toContain('p-1')
+    expect(classes).not.toContain('p-2')
+  })
+})

package/src/Menu.tsx

@@ -142,8 +142,18 @@ export interface MenuProps {
    *  closes the menu by itself, so this is only for content that is not one. */
   actionsRef?: RefObject<{ close: () => void; unmount: () => void } | null>
   children: ReactNode
-  /** On the menu's surface — its width, its internal rhythm. */
+  /** On the menu's surface — its width. **Not its padding**: see
+   *  `contentClassName`. */
   className?: string
+  /**
+   * The padding around the rows, as a class. Default `p-2`, 8px.
+   *
+   * It is on the scrolling content, not on the panel, so the scrollbar hugs the
+   * panel's edge (D63) — and so a padding class on `className` adds to it
+   * rather than replacing it. Peek's Later menu asked for `p-1` there and got
+   * 12px from `0.12.6` on (PLAN Finding 60). Set it here.
+   */
+  contentClassName?: string
 }
 
 /**
@@ -163,7 +173,7 @@ const VIEWPORT_PAD = 8
 const HOVER_OPEN_DELAY = 0
 const HOVER_CLOSE_DELAY = 150
 
-export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpenChange, actionsRef, children, className }: MenuProps) {
+export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpenChange, actionsRef, children, className, contentClassName }: MenuProps) {
   return (
     <BaseMenu.Root
       open={open}
@@ -227,9 +237,11 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
              * as tall as Floating UI allowed.
              *
              * A caller's `className` still lands on the panel, so a caller
-             * asking for different padding needs `contentClassName` — which is
-             * what `MenuPanel` is for when one is used on its own. */}
-            <ScrollArea viewportClassName="max-h-[var(--available-height)]" contentClassName="flex flex-col p-2 [&>[role=separator]]:mx-0">
+             * asking for different padding needs `contentClassName`. That
+             * sentence was written at 0.12.6 and the prop was not: a `p-1` on
+             * `className` added 4px to these 8px instead of replacing them
+             * (PLAN Finding 60). The prop exists now. */}
+            <ScrollArea viewportClassName="max-h-[var(--available-height)]" contentClassName={cn('flex flex-col p-2 [&>[role=separator]]:mx-0', contentClassName)}>
               <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
             </ScrollArea>
           </BaseMenu.Popup>

package/src/Popover.mdx

@@ -64,8 +64,10 @@ import { Popover } from '@estiva-app/ui'
   force it. Leave them off and the panel keeps its own state.
 - `ariaLabel` names the panel. A panel with a visible heading can point at it
   with `aria-labelledby` instead.
-- Width, padding and internal rhythm are yours, through `className` — the
-  panel is a surface, not a layout.
+- **Width goes on `className`, padding on `contentClassName`.** The padding
+  sits on the scrolling content so the scrollbar hugs the panel's edge, and a
+  padding class on `className` adds to it rather than replacing it. Default
+  8px; **a toolbar asks for `contentClassName="p-1"`**.
 
 <Canvas of={PopoverStories.FromATrigger} />
 

package/src/Popover.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconBold, IconItalic, IconLink } from '@tabler/icons-react'
-import { useRef, useState, type KeyboardEvent, useCallback } from 'react'
+import { useRef, useState, type KeyboardEvent } from 'react'
 import { Button } from './Button'
 import { MenuPanel } from './Menu'
 import { Popover } from './Popover'
@@ -105,7 +105,8 @@ export const AToolbar: Story = {
            when there is no room, which is the reason the placement is its job
            and not ours. */
         side="top"
-        className="w-auto min-w-0 p-1"
+        className="w-auto min-w-0"
+        contentClassName="p-1"
       >
         {/* The strip is a `Toolbar`, so the whole row is ONE Tab stop and the
             arrow keys walk it — four stops before, one after. */}
@@ -234,17 +235,18 @@ export const Capped: Story = {
   parameters: { controls: { disable: true }, layout: 'fullscreen' },
   render: function Capped() {
     /* Anchored and open, so the cap is the thing you see rather than a button
-       you have to press first. A rect is all an anchor needs. */
-    const [rect, setRect] = useState<DOMRect | null>(null)
-    const mark = useCallback((el: HTMLDivElement | null) => {
-      setRect(el ? el.getBoundingClientRect() : null)
-    }, [])
+       you have to press first. Anchored on the ELEMENT, held in state from a
+       callback ref: an element is re-measured. It used to be a rect read once
+       in the ref, and arriving at this story from another one read it before
+       the canvas was laid out — 0 × 0 at the corner, a 0px panel, only the
+       line of text showing (PLAN Finding 61). */
+    const [marker, setMarker] = useState<HTMLDivElement | null>(null)
     return (
       <div className="flex h-[420px] w-full items-center justify-center">
-        <div ref={mark} className="text-body-2 text-text-secondary">
+        <div ref={setMarker} className="text-body-2 text-text-secondary">
           twenty rows, capped at 160px
         </div>
-        <Popover anchor={rect} open ariaLabel="A long panel" className="w-[240px]" maxHeight="max-h-[160px]">
+        <Popover anchor={marker} open ariaLabel="A long panel" className="w-[240px]" maxHeight="max-h-[160px]">
           {Array.from({ length: 20 }, (_, i) => (
             <span key={i} className="text-body-2 text-text-primary py-1">
               Row {i + 1}

package/src/Popover.test.tsx

@@ -223,3 +223,41 @@ describe('Popover, centred on its anchor', () => {
     expect(positioner?.getAttribute('data-align')).toBe('center')
   })
 })
+
+/**
+ * The padding lives on the scrolling content, so the scrollbar hugs the panel
+ * (D63) — and a caller's padding has to land there too. At 0.12.6 a toolbar's
+ * `p-1` on `className` was added to the content's `p-2` instead of replacing
+ * it, and every toolbar in a Popover grew 8px a side (PLAN Finding 60).
+ * Measured in Chrome after the fix: the toolbar 5px inside the panel's edge,
+ * as on 0.12.5.
+ */
+describe('Popover, padding', () => {
+  // The scrolling content is the box that carries the separator rule.
+  const contentOf = (child: HTMLElement) => child.closest('[class*="role=separator"]') as HTMLElement
+
+  it('pads its content 8px by default', async () => {
+    render(
+      <Popover trigger={<Button>Open</Button>} ariaLabel="A panel">
+        <span>Inside</span>
+      </Popover>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const content = contentOf(await screen.findByText('Inside'))
+    expect(content.className).toContain('p-2')
+  })
+
+  it('takes a caller’s padding on contentClassName, instead of the 8px', async () => {
+    render(
+      <Popover trigger={<Button>Open</Button>} ariaLabel="A toolbar" className="w-auto" contentClassName="p-1">
+        <span>Inside</span>
+      </Popover>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const content = contentOf(await screen.findByText('Inside'))
+    expect(content.className.split(/\s+/)).toContain('p-1')
+    expect(content.className.split(/\s+/)).not.toContain('p-2')
+    // And the panel carries none of it.
+    expect((await screen.findByRole('dialog')).className.split(/\s+/)).not.toContain('p-1')
+  })
+})

package/src/Popover.tsx

@@ -91,8 +91,23 @@ export interface PopoverProps {
    *  point at it instead, with `aria-labelledby`. */
   ariaLabel?: string
   children: ReactNode
-  /** On the panel's surface — its width, its internal rhythm. */
+  /**
+   * On the panel's surface — its width. **Not its padding**: see
+   * `contentClassName`.
+   */
   className?: string
+  /**
+   * The padding around the children, as a class. Default `p-2`, 8px — what a
+   * panel of rows or a small form wants. **A toolbar wants `p-1`.**
+   *
+   * The padding is on the scrolling content, not on the panel, so a scrollbar
+   * is drawn over it and hugs the panel's edge (D63). A padding class on
+   * `className` therefore does not replace this one — it adds to it: that is
+   * how every toolbar in a `Popover` grew 8px a side at `0.12.6`, measured 13px
+   * from the panel's edge to the toolbar where it had been 5px (PLAN Finding
+   * 60). Set it here.
+   */
+  contentClassName?: string
   /**
    * A cap on the scrolling box, as a class — `max-h-[360px]`. Without one the
    * panel grows to the room the positioner has, which is the right default for
@@ -121,7 +136,7 @@ export interface PopoverProps {
 const GAP = 4
 const VIEWPORT_PAD = 8
 
-export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open, onOpenChange, finalFocus, actionsRef, ariaLabel, children, className, maxHeight }: PopoverProps) {
+export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open, onOpenChange, finalFocus, actionsRef, ariaLabel, children, className, contentClassName, maxHeight }: PopoverProps) {
   /* A rect is not an element, so it becomes a virtual anchor — the one shape
      Floating UI takes besides an element. */
   const anchorTarget = useMemo(() => {
@@ -181,10 +196,11 @@ export function Popover({ trigger, anchor, align = 'left', side = 'bottom', open
             {/* As in Menu: the cap on the scrolling box, and the padding on the
                 content rather than the panel, so the bar is drawn over the
                 padding instead of 9px inside it (D63). A caller's `maxHeight`
-                replaces the cap — see the prop. */}
+                replaces the cap, and a caller's `contentClassName` the padding
+                — see the props. */}
             <ScrollArea
               viewportClassName={maxHeight ?? 'max-h-[var(--available-height)]'}
-              contentClassName="flex flex-col p-2 [&>[role=separator]]:mx-0"
+              contentClassName={cn('flex flex-col p-2 [&>[role=separator]]:mx-0', contentClassName)}
             >
               {children}
             </ScrollArea>

package/src/ReactionPicker.mdx

@@ -32,7 +32,7 @@ The reactions on offer, to choose one from — icon buttons holding emoji, on a
 ```tsx
 import { ReactionPicker } from '@estiva-app/ui'
 
-<Popover side="top" align="right" trigger={reactButton} ariaLabel="Reactions" className="w-auto p-1">
+<Popover side="top" align="right" trigger={reactButton} ariaLabel="Reactions" className="w-auto" contentClassName="p-1">
   <ReactionPicker
     surface={false}
     options={[

package/src/ReactionPicker.stories.tsx

@@ -62,7 +62,8 @@ export const FromATrigger: Story = {
             side="top"
             align="right"
             ariaLabel="Reactions"
-            className="w-auto min-w-0 p-1"
+            className="w-auto min-w-0"
+            contentClassName="p-1"
             trigger={
               <ToolbarButton aria-label="React" tooltip="React">
                 <IconMoodPlus size={16} stroke={1.5} />

package/src/Toolbar.stories.tsx

@@ -129,7 +129,8 @@ export const OnAnExistingSurface: Story = {
       /* Above the control that opened it: a strip acts on what is under it.
          `side` is the preference; Base UI flips it when there is no room. */
       side="top"
-      className="w-auto min-w-0 p-1"
+      className="w-auto min-w-0"
+      contentClassName="p-1"
     >
       <Toolbar aria-label="Formatting" surface={false}>
         <ToolbarButton aria-label="Item one" tooltip="Item one">{icon}</ToolbarButton>