@estiva-app/ui 0.22.0 → 0.24.0

package/src/ContainerHeader.stories.tsx

@@ -0,0 +1,62 @@
+import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
+import { IconEdit, IconSortDescending, IconX } from '@tabler/icons-react'
+import { ContainerHeader } from './ContainerHeader'
+import { IconButton } from './IconButton'
+
+// The top of a column: a surface with a hairline, so the bar's own hairline and height can be seen.
+const inColumn: Decorator = (Story) => <div className="w-96 overflow-hidden rounded-lg border border-border-default bg-bg-surface">{Story()}</div>
+
+const meta = {
+  title: 'Navigation/ContainerHeader',
+  component: ContainerHeader,
+  args: { title: 'Items' },
+  argTypes: { actions: { control: false } },
+  decorators: [inColumn],
+} satisfies Meta<typeof ContainerHeader>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A string title, one line, alone. */
+export const Default: Story = {}
+
+/** A chevron after the title, for a title that opens something. */
+export const WithChevron: Story = { args: { title: 'All items', chevron: true } }
+
+/** The column's own buttons at the right edge: IconButtons with tooltips. */
+export const WithActions: Story = {
+  args: {
+    title: 'All items',
+    chevron: true,
+    actions: (
+      <>
+        <IconButton tooltip="Sort by" aria-label="Sort by">
+          <IconSortDescending size={16} stroke={1.5} />
+        </IconButton>
+        <IconButton tooltip="New item" aria-label="New item">
+          <IconEdit size={16} stroke={1.5} />
+        </IconButton>
+      </>
+    ),
+  },
+}
+
+/** A title that is not a string — a name over its caption — takes the room left and is drawn as given. */
+export const WithRichTitle: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the caption
+  // is muted text, 3.94:1 in signal (AA 4.5:1) — as Peek's file page draws it.
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+  args: {
+    title: (
+      <div className="min-w-0">
+        <p className="truncate text-body-2-strong text-text-primary">Quarterly plan</p>
+        <p className="truncate text-caption text-text-muted">In Project Alpha</p>
+      </div>
+    ),
+    actions: (
+      <IconButton tooltip="Close" aria-label="Close">
+        <IconX size={16} stroke={1.5} />
+      </IconButton>
+    ),
+  },
+}

package/src/ContainerHeader.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+/**
+ * What `ContainerHeader.mdx` claims: a string title is one line that keeps its
+ * width, a node is drawn as given and takes the room left, and the column's
+ * buttons sit at the right edge. The pixels are proved against Peek's own
+ * (docs/GATES.md, UIG-13: A).
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { ContainerHeader } from './ContainerHeader'
+
+afterEach(cleanup)
+
+describe('ContainerHeader', () => {
+  it('is the 48px bar with a hairline under it', () => {
+    const { container } = render(<ContainerHeader title="Items" />)
+    const bar = container.firstElementChild!.className.split(' ')
+    expect(bar).toContain('h-12')
+    expect(bar).toContain('border-b')
+    expect(bar).toContain('border-border-subtle')
+  })
+
+  it('a string title is one line in body-2-strong, and keeps its width', () => {
+    render(<ContainerHeader title="Items" />)
+    const title = screen.getByText('Items')
+    expect(title.className).toContain('text-body-2-strong')
+    expect(title.className).toContain('whitespace-nowrap')
+    expect(title.parentElement!.className).toContain('shrink-0')
+  })
+
+  it('a node title is drawn as given and takes the room left', () => {
+    render(<ContainerHeader title={<em>Plan</em>} />)
+    const holder = screen.getByText('Plan').parentElement!
+    expect(holder.className).toContain('flex-1')
+    expect(holder.className).toContain('min-w-0')
+  })
+
+  it('draws a chevron only when asked, and the buttons at the right edge', () => {
+    const { container, rerender } = render(<ContainerHeader title="Items" />)
+    expect(container.querySelector('svg')).toBeNull()
+    expect(container.firstElementChild!.children).toHaveLength(1)
+    rerender(<ContainerHeader title="Items" chevron actions={<button type="button">New</button>} />)
+    expect(container.querySelector('svg')).not.toBeNull()
+    expect(container.firstElementChild!.children).toHaveLength(2)
+    expect(screen.getByRole('button', { name: 'New' }).closest('div')!.className).toContain('gap-1')
+  })
+})

package/src/ContainerHeader.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react'
+import { IconChevronDown } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * The bar across the top of a column — a list, a thread, a side panel: its
+ * title, and the buttons that act on the whole column at the right edge.
+ * Peek's ContainerHeader, moved into the package exactly as it looks
+ * (Katerina, 2026-09-18, UIG-13).
+ *
+ * 48px tall, a hairline under it. A string title is one line in
+ * `body-2-strong` and keeps its width; anything else — an EditableText, a
+ * title over a caption — takes the room that is left and is drawn as given.
+ *
+ * Not a SectionHeader: that is the 32px row one section of a column starts
+ * with. This is the column's own bar, one per column.
+ */
+export interface ContainerHeaderProps {
+  /** A string keeps the one-line treatment; a node is drawn as given. */
+  title: ReactNode
+  /** A chevron after the title, for a title that opens something. */
+  chevron?: boolean
+  /** The column's own buttons, at the right edge: IconButtons with tooltips, 4px apart. */
+  actions?: ReactNode
+  className?: string
+}
+
+export function ContainerHeader({ title, chevron = false, actions, className }: ContainerHeaderProps) {
+  const text = typeof title === 'string'
+  return (
+    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4 pl-5', className)}>
+      <div className={cn('flex items-center gap-2 overflow-hidden', text ? 'shrink-0' : 'min-w-0 flex-1')}>
+        <div className={cn('flex items-center gap-1', text ? 'shrink-0' : 'min-w-0 flex-1')}>
+          {text ? <span className="whitespace-nowrap text-body-2-strong text-text-primary">{title}</span> : <div className="min-w-0 flex-1">{title}</div>}
+          {chevron && <IconChevronDown size={12} stroke={1.5} className="shrink-0 text-text-secondary" />}
+        </div>
+      </div>
+      {actions && (
+        <div className="flex shrink-0 items-center justify-end gap-3">
+          <div className="flex shrink-0 items-center gap-1">{actions}</div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/DialogShell.mdx

@@ -28,6 +28,7 @@ footer for the buttons. A dialog is just what goes in the three slots.
   dialog rebuilt by hand, which is the one thing this bullet exists to stop.
   Its canvases and its nine tests are on that page.
 - Telling someone what happened → **Toast**.
+- Searching for something and acting on it → **CommandPalette**.
 
 ## How
 
@@ -73,6 +74,19 @@ import { DialogShell, Button } from '@estiva-app/ui'
   stops closing it (Katerina, D20). Escape and the ✕ still do.
   `ConfirmDialog` sets it; a form or a roster should not.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Closes on a press outside, except with `alert` | a click listener on the page | ✓ |
+| Takes its keys by itself: Escape closes it | a key listener on the page | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, or a Tab handler | ✓ |
+| Stops the page behind it scrolling | `overflow: hidden` on the page | ✓ |
+| Says what it is to assistive technology: a dialog | `role="dialog"` | ✓ |
+
 ## Keys
 
 | Input | What happens |

package/src/Divider.mdx

@@ -16,7 +16,7 @@ orientation for assistive tech.
 
 - Between groups in a **Menu** (`className="my-1"` gives it its breathing
   room there).
-- Between sections of a panel or rail.
+- Between sections of a panel, a rail or a card.
 - Vertical: between clusters in a toolbar or a dense row.
 
 <Canvas of={DividerStories.Vertical} />
@@ -49,6 +49,14 @@ import { Divider } from '@estiva-app/ui'
 - **Inside a `Menu` or a `Popover` it has no inset**: the hairline runs the
   width of the rows. The panel tells it so; nothing is passed in.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a separator | `role="separator"` | ✓ |
+
 ## Props
 
 <Controls of={DividerStories.Default} />

package/src/EditableText.mdx

@@ -23,6 +23,8 @@ edit is never silently lost.
 - A field in a form or dialog → **TextInput** / **Textarea** in a
   **Field**.
 - Composing something new → the field, not an edit-in-place of nothing.
+- An edit that publishes something, like a message → **Textarea** with Save
+  and Cancel. EditableText saves when you leave it.
 
 ## How
 
@@ -55,6 +57,15 @@ import { EditableText } from '@estiva-app/ui'
   the page's font). `className` places it — `-mx-2` to line its text up with
   a header's inset — and a size passed there is refused by the lint (UIG-9).
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Opens its field on a click, with the value selected | an edit mode of your own |  |
+| Enter and leaving the field save; Escape cancels and puts the value back (`multiline`: Shift+Enter is a new line) | key or blur handlers |  |
+
 ## Keys
 
 | Input | What happens |

package/src/EmptyState.mdx

@@ -36,10 +36,12 @@ need a height from the caller (`className="h-full"`).
 
 ## When not
 
-- Data is still on its way → **Skeleton**; empty and loading are
-  different truths.
-- Something went wrong → say that, in your surface's own error treatment
-  — an empty state that hides a failure misleads.
+- Data is still on its way → **Skeleton**; empty and loading are different
+  truths. When the shape of what arrives is unknown, an EmptyState that says so
+  — "Opening…" — is fine.
+- Something went wrong → say what failed, in words. An EmptyState can carry
+  it, in its usual look — never red. An empty state that hides a failure
+  misleads.
 
 ## How
 
@@ -53,6 +55,18 @@ import { EmptyState } from '@estiva-app/ui'
 <EmptyState scope="section" message="No comments yet." />
 ```
 
+**When there is one thing to do about it, give it as `action`.** It is drawn
+16px under the line as the package's Button, outlined — the same look wherever
+it appears (Katerina, 2026-09-18). Never put a Button beside an EmptyState in a
+box of your own: the box places it, and no two boxes place it alike. A `page`
+only; a section's line takes no action.
+
+<Canvas of={EmptyStateStories.WithAction} />
+
+```tsx
+<EmptyState icon={<IconMessagePlus size={16} stroke={1.5} />} message="No topics yet." action={{ label: 'New topic', onClick: openNewTopic }} />
+```
+
 **Put a section's empty state inside the box its rows live in, and give it no
 padding.** Write the box once; inside it goes either the rows or the empty
 state. The box's padding then places both, and the line starts where the first
@@ -71,6 +85,15 @@ The message is the caller's — a shared component has no words of its own
 for what is missing. A hand-written "Nothing here" paragraph or span in a
 section is the `section` manner, and becomes it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| As a `page`, fills the room it is given and centres itself in it | centring, or padding around it |  |
+| Draws its one action, an outlined Button, under the line when you pass `action` | a button of your own under the line |  |
+
 ## Props
 
 <Controls of={EmptyStateStories.Page} />

package/src/EmptyState.stories.tsx

@@ -1,5 +1,5 @@
 import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
-import { IconLock } from '@tabler/icons-react'
+import { IconLock, IconMessagePlus } from '@tabler/icons-react'
 import { EmptyState } from './EmptyState'
 
 // A box with a hairline, so where the state sits inside its room can be seen: a page's in the middle both ways, a section's at the top left.
@@ -25,6 +25,11 @@ const sectionContrastDeferred = { a11y: { config: { rules: [{ id: 'color-contras
 export const Section: Story = { args: { scope: 'section' }, decorators: [inBox], parameters: sectionContrastDeferred }
 export const LongerMessage: Story = { args: { message: 'No items yet. Add one from any list.' }, decorators: [inBox] }
 export const CustomIcon: Story = { args: { icon: <IconLock size={16} stroke={1.5} />, message: 'Nothing you can read here yet.' }, decorators: [inBox] }
+/** The one thing to do about it, under the line: the package's Button, outlined. */
+export const WithAction: Story = {
+  args: { icon: <IconMessagePlus size={16} stroke={1.5} />, message: 'No topics yet.', action: { label: 'New topic', onClick: () => {} } },
+  decorators: [inBox],
+}
 
 /** One box, written once, holding the rows or the empty state: its padding places both, so the line starts where the first row does. */
 export const InsideTheRowsBox: Story = {

package/src/EmptyState.test.tsx

@@ -6,7 +6,7 @@
  * structure.
  */
 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, render, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { EmptyState } from './EmptyState'
 
 afterEach(cleanup)
@@ -59,4 +59,21 @@ describe('EmptyState', () => {
     expect(container.querySelector('[data-testid="own"]')).not.toBeNull()
     expect(container.querySelector('svg')).toBeNull()
   })
+
+  it('draws its action under the line as the package Button, outlined (Katerina, 2026-09-18)', () => {
+    let clicked = 0
+    render(<EmptyState message="No topics yet." action={{ label: 'New topic', onClick: () => (clicked += 1) }} />)
+    const button = screen.getByRole('button', { name: 'New topic' })
+    expect(button.className).toContain('border-border-default')
+    expect(button.className).toContain('mt-2')
+    // Under the line, in the same column.
+    expect(screen.getByText('No topics yet.').nextElementSibling).toBe(button)
+    fireEvent.click(button)
+    expect(clicked).toBe(1)
+  })
+
+  it('a section takes no action', () => {
+    render(<EmptyState scope="section" message="Nothing here yet." action={{ label: 'Add', onClick: () => {} }} />)
+    expect(screen.queryByRole('button')).toBeNull()
+  })
 })

package/src/EmptyState.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { IconMessage2 } from '@tabler/icons-react'
+import { Button } from './Button'
 import { cn } from './cn'
 
 /**
@@ -28,10 +29,16 @@ export interface EmptyStateProps {
   message: string
   /** `page` when the whole page is empty; `section` when one part of it is. */
   scope?: 'page' | 'section'
+  /**
+   * The one thing to do about it — "New topic", "Try again" — drawn 16px under
+   * the line as the package's Button, outlined (Katerina, 2026-09-18). A `page`
+   * only: a section's empty line is one line among others, not a stage.
+   */
+  action?: { label: string; onClick: () => void }
   className?: string
 }
 
-export function EmptyState({ icon, message, scope = 'page', className }: EmptyStateProps) {
+export function EmptyState({ icon, message, scope = 'page', action, className }: EmptyStateProps) {
   if (scope === 'section') {
     return <p className={cn('text-caption text-text-muted', className)}>{message}</p>
   }
@@ -39,6 +46,12 @@ export function EmptyState({ icon, message, scope = 'page', className }: EmptySt
     <div className={cn('flex flex-1 flex-col items-center justify-center gap-2', className)}>
       <span className="text-text-secondary">{icon ?? <IconMessage2 size={16} stroke={1.5} />}</span>
       <p className="text-body-2 text-text-secondary text-center">{message}</p>
+      {/* 8px of the column's gap and 8px of its own: 16px under the line, as Peek had it. */}
+      {action && (
+        <Button variant="outlined" className="mt-2" onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
     </div>
   )
 }

package/src/Field.mdx

@@ -19,7 +19,7 @@ token; `required` marks it with the error-coloured asterisk.
 
 - Displaying a label–value pair → **Property**; Field is for editing.
 - The line belongs to a **group** of controls rather than to one — a value
-  with Save beside it, a row of action controls → **Field line**, the same
+  with Save beside it, a row of action controls → **FieldLine**, the same
   small line on its own.
 
 ## How
@@ -55,6 +55,15 @@ import { Field, TextInput } from '@estiva-app/ui'
   that says so already is left alone, and a `children` of several elements
   keeps the asterisk and owes its own.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Ties the label, the description and the error to the control inside it | `aria-label`, an `id` / `htmlFor` pair, or `aria-describedby` |  |
+| Marks the control invalid when it has an `error`, and announces it | `aria-invalid` |  |
+
 ## Props
 
 <Controls of={FieldStories.Default} />

package/src/FieldLine.mdx

@@ -32,7 +32,7 @@ import { FieldLine } from '@estiva-app/ui'
 
 <div className="flex flex-col gap-1.5">
   <div className="flex items-center gap-2">
-    <TextInput value={draft} onChange={…} />
+    <TextInput value={draft} onChange={(e) => setDraft(e.target.value)} />
     <Button variant="primary" size="small">Save</Button>
   </div>
   {outcome && <FieldLine tone={outcome.kind}>{outcome.message}</FieldLine>}
@@ -52,6 +52,14 @@ import { FieldLine } from '@estiva-app/ui'
 - The three tones are the same two classes Field draws, from one map in
   `Field.tsx`, so they cannot drift.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: an alert for an error, a status for the rest | `role="alert"` or `role="status"` | ✓ |
+
 ## Props
 
 <Controls of={FieldLineStories.Helper} />

package/src/FilePicker.mdx

@@ -44,6 +44,14 @@ const picker = useRef<HTMLInputElement>(null)
   nothing to reset afterwards.
 - `data-*` attributes pass on to the input, for a test to find it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Opens the system's file picker from its button, and keeps the real file input out of Tab and screen readers | a hidden `<input type="file">` |  |
+
 ## Props
 
 <Controls of={FilePickerStories.Default} />

package/src/Form.mdx

@@ -58,6 +58,16 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
 - `className` places the fields: the form draws no box, and neither does the
   `<fieldset>` inside it.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Sends on Enter in a one-line field, and on Ctrl+Enter anywhere inside | a key handler that submits |  |
+| Leaves Enter alone where it means something else: a Textarea, a list, a people picker | exceptions of your own |  |
+| Does nothing while it is sending: no second send, and nothing inside takes focus | a busy flag on every control |  |
+
 ## Keys
 
 The same in every form (Katerina, 16 September).

package/src/Form.test.tsx

@@ -18,6 +18,7 @@ import { Checkbox } from './Checkbox'
 import { IconButton } from './IconButton'
 import { Field } from './Field'
 import { Form } from './Form'
+import { Popover } from './Popover'
 import { TextInput } from './TextInput'
 import { Textarea } from './Textarea'
 
@@ -46,6 +47,31 @@ describe('Form', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  it('a Form in a Popover inside a Form sends only itself (C1)', async () => {
+    // A link field in a pop-up over a composer: Enter there adds the link, and
+    // must not also send the message around it. React carries the submit
+    // through the Popover's portal to the outer form.
+    const user = userEvent.setup()
+    const outer = vi.fn()
+    const inner = vi.fn()
+    render(
+      <Form onSubmit={outer}>
+        <TextInput aria-label="Message" />
+        <Popover trigger={<Button>Link</Button>} open ariaLabel="Link">
+          <Form onSubmit={inner}>
+            <TextInput aria-label="Address" />
+          </Form>
+        </Popover>
+      </Form>,
+    )
+    await user.type(screen.getByRole('textbox', { name: 'Address' }), 'example.com{Enter}')
+    expect(inner).toHaveBeenCalledTimes(1)
+    expect(outer).not.toHaveBeenCalled()
+    await user.type(screen.getByRole('textbox', { name: 'Message' }), 'hi{Enter}')
+    expect(outer).toHaveBeenCalledTimes(1)
+    expect(inner).toHaveBeenCalledTimes(1)
+  })
+
   it('sends from its submit button', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()

package/src/Form.tsx

@@ -160,6 +160,13 @@ export function Form({ onSubmit, busy: ownBusy = false, enterSends = true, class
       }}
       onKeyDown={onKeyDown}
       onSubmit={(event) => {
+        /*
+          A form's own send only. React carries a submit up the component tree,
+          through a portal too, so a Form in a Popover inside this Form sent both:
+          Enter in a link field sent the whole message around it (UIG-14, C1,
+          Katerina 19 September). The inner Form has already handled its own.
+        */
+        if (event.target !== event.currentTarget) return
         event.preventDefault()
         if (busyNow.current) return
         void onSubmit()

package/src/IconButton.mdx

@@ -22,8 +22,8 @@ variants. For the actions a surface repeats too often to label every time.
 - The action deserves a visible label → **Button** (words are cheaper than
   a guessed icon).
 - Inside a menu → **MenuItem** with `leading`.
-- A strip of these is a toolbar — right; but the moment rows toggle and
-  persist state, see **Checkbox**.
+- A strip of these acting on one thing → **Toolbar**. The moment rows toggle
+  and persist state, see **Checkbox**.
 
 ## How
 
@@ -54,11 +54,25 @@ import { IconPencil } from '@tabler/icons-react'
 - `disabledReason="Read only"` disables it, keeps it reachable by Tab,
   and shows the reason in place of the tooltip — **on keyboard focus as
   well as on hover**.
+- **`href`** makes it a link that looks like the button: an anchor, so the
+  address stays real for a modified click or a new tab. A router app passes
+  `onClick`, prevents the default and navigates. While it cannot be used it
+  is the button — a link cannot be disabled.
 - `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.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a button | `role="button"` | ✓ |
+| Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
+| Presses on Enter and Space, and does nothing while disabled | a key handler |  |
+
 ## Keys
 
 | Key | Does |

package/src/IconButton.stories.tsx

@@ -26,6 +26,9 @@ export const WithTooltip: Story = { args: { tooltip: 'Settings', tooltipPlacemen
 /** Disabled with its reason in place of the tooltip; Tab still reaches it. */
 export const WithAReason: Story = { args: { tooltip: 'Settings', disabledReason: 'Sign in to change settings' } }
 
+/** `href`: a link that looks like the button — the same box, an anchor underneath. */
+export const AsALink: Story = { args: { href: '#settings', tooltip: 'Settings' } }
+
 /** Every variant × enabled/disabled. */
 export const AllVariants: Story = {
   // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:

package/src/IconButton.test.tsx

@@ -28,6 +28,31 @@ describe('IconButton', () => {
     expect(onClick).toHaveBeenCalledTimes(1)
   })
 
+  it('href: a link that looks like the button, with its tooltip', async () => {
+    const user = userEvent.setup()
+    render(
+      <IconButton href="/documents/12" aria-label="Open" tooltip="Open">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('button')).toBeNull()
+    const link = screen.getByRole('link', { name: 'Open' })
+    expect(link.getAttribute('href')).toBe('/documents/12')
+    expect(link.className).toContain('rounded-lg')
+    await user.hover(link)
+    expect((await screen.findByRole('tooltip')).textContent).toBe('Open')
+  })
+
+  it('href while it cannot be used: the button, since a link cannot be disabled', () => {
+    render(
+      <IconButton href="/documents/12" aria-label="Open" disabledReason="Read only">
+        {icon}
+      </IconButton>,
+    )
+    expect(screen.queryByRole('link')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Open' }).getAttribute('aria-disabled')).toBe('true')
+  })
+
   it('shows the tooltip on hover, with its shortcut', async () => {
     const user = userEvent.setup()
     render(