@estiva-app/ui 0.22.0 → 0.24.0

package/src/IconButton.tsx

@@ -37,6 +37,14 @@ export interface IconButtonProps extends ComponentPropsWithRef<'button'> {
   /** Why the action cannot succeed right now. Disables the button, keeps it
    *  reachable by keyboard, and shows the reason as the tooltip. */
   disabledReason?: string
+  /**
+   * A link that looks like an icon button: an anchor, so the address stays
+   * real for a modified click or a new tab, as `Link` keeps it. A router app
+   * passes `onClick`, prevents the default and navigates. A link cannot be
+   * disabled, so while it would be — `disabled`, `disabledReason`, a busy
+   * Form — it is the button (UIG-14, Katerina, 18 September).
+   */
+  href?: string
   /** The icon: 16px, stroke 1.5. */
   children: ReactNode
 }
@@ -53,56 +61,63 @@ export function IconButton({
   tooltipShortcut,
   tooltipPlacement,
   type = 'button',
+  href,
   ...props
 }: IconButtonProps) {
   // Inside a busy Form: switched off, and looking it (formBusy.ts).
   const formBusy = useFormBusy()
-  const button = (
-    <BaseButton
-      type={type}
-      disabled={disabled || !!disabledReason || formBusy}
-      focusableWhenDisabled={!!disabledReason}
-      className={(state) =>
-        cn(
-          // `shrink-0` stops a flex parent squashing the button; `self-center`
-          // stops one stretching it. Two different failures, and both have
-          // happened here: a row with no `items-*` drew this 24 wide and 228
-          // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
-          // is the size of its icon and its padding, whatever box it lands in.
-          //
-          // This is the one of the two that needs it: an IconButton states no
-          // height, so its cross size is `auto` and a stretching parent takes
-          // it. Measured in the same 260px row on 2026-09-12: 24px with this
-          // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
-          // stretched and carries no `self-center` — see the note there.
-          'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
-          !state.disabled && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
-          !state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
-          !state.disabled && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
-          !state.disabled && variant === 'current' && 'hover:bg-bg-hover',
-          state.disabled && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
-          state.disabled && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
-          state.disabled && variant === 'outlined' && 'border border-border-default text-text-disabled',
-          // Always, disabled too: the colour of where it sits, and Resolve's green.
-          variant === 'current' && 'text-current',
-          variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
-          pressed && 'bg-bg-active text-text-primary',
-          glow && 'signal:shadow-glow-accent',
-          // `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,
-        )
-      }
-      aria-pressed={pressed}
-      {...props}
-    >
-      {children}
-    </BaseButton>
-  )
+  const unusable = disabled || !!disabledReason || formBusy
+  const look = (off: boolean) =>
+    cn(
+      // `shrink-0` stops a flex parent squashing the button; `self-center`
+      // stops one stretching it. Two different failures, and both have
+      // happened here: a row with no `items-*` drew this 24 wide and 228
+      // tall in Peek's TopicMoreMenu story (Katerina, 2026-09-11). A button
+      // is the size of its icon and its padding, whatever box it lands in.
+      //
+      // This is the one of the two that needs it: an IconButton states no
+      // height, so its cross size is `auto` and a stretching parent takes
+      // it. Measured in the same 260px row on 2026-09-12: 24px with this
+      // class, 226px without. `Button` states `h-8`/`h-6`, so it cannot be
+      // stretched and carries no `self-center` — see the note there.
+      'flex items-center justify-center p-1 rounded-lg transition-colors shrink-0 self-center cursor-pointer',
+      !off && variant === 'primary' && 'bg-accent-primary hover:bg-accent-hover text-text-inverse',
+      !off && (variant === 'muted' || variant === 'resolve') && 'text-text-secondary hover:bg-bg-hover hover:text-text-primary',
+      !off && variant === 'outlined' && 'border border-border-default hover:bg-bg-hover text-text-secondary',
+      !off && variant === 'current' && 'hover:bg-bg-hover',
+      off && variant === 'primary' && 'bg-bg-disabled text-text-disabled',
+      off && (variant === 'muted' || variant === 'resolve') && 'text-text-disabled',
+      off && variant === 'outlined' && 'border border-border-default text-text-disabled',
+      // Always, disabled too: the colour of where it sits, and Resolve's green.
+      variant === 'current' && 'text-current',
+      variant === 'resolve' && 'signal:hover:bg-success-muted signal:hover:text-success-default',
+      pressed && 'bg-bg-active text-text-primary',
+      glow && 'signal:shadow-glow-accent',
+      // `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.
+      off && !disabledReason && 'pointer-events-none',
+      off && 'cursor-not-allowed',
+      className,
+    )
+  const button =
+    href && !unusable ? (
+      <a href={href} className={look(false)} {...(props as unknown as ComponentPropsWithRef<'a'>)}>
+        {children}
+      </a>
+    ) : (
+      <BaseButton
+        type={type}
+        disabled={unusable}
+        focusableWhenDisabled={!!disabledReason}
+        className={(state) => look(state.disabled)}
+        aria-pressed={pressed}
+        {...props}
+      >
+        {children}
+      </BaseButton>
+    )
 
   const label = disabledReason ?? tooltip
   if (label) {

package/src/IdentityMenu.mdx

@@ -62,6 +62,15 @@ import { IdentityMenu } from '@estiva-app/ui'
   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.
 
+## 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 |
+|---|---|---|
+| Everything a Menu owns: it floats, stays attached, closes on a press outside or on Escape, and walks its rows with the arrow keys | a menu of your own around the face |  |
+| Gives focus back to the face when it closes | focus code |  |
+
 ## Keys
 
 Since stage 4 the panel is a Base UI `Menu`, and **the arrow keys walk the

package/src/InlineChip.mdx

@@ -51,6 +51,14 @@ import { InlineChip } from '@estiva-app/ui'
 - A rich-text editor that renders chips from strings cannot use a component.
   `inlineChipClassName(tone)` gives it the same classes.
 
+## 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 |
+|---|---|---|
+| With `href`, keeps a real address, so a modified click or a new tab still works | a `<span>` with a click handler |  |
+
 ## Props
 
 <Controls of={InlineChipStories.Neutral} />

package/src/Kbd.mdx

@@ -72,6 +72,10 @@ It renders what it is given and formats nothing. A modifier is called Cmd on
 Apple platforms and Ctrl elsewhere, and only the caller knows which it is
 looking at — so decide there and pass the finished label.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={KbdStories.Default} />

package/src/Link.mdx

@@ -28,6 +28,7 @@ the app decides how it navigates.
 - An action — something happens, nothing is navigated to → **Button**.
 - A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
 - The trail back up → **Breadcrumb**.
+- A link that looks like an icon button → **IconButton** with `href`.
 - A word standing for a person or a thing, drawn in a small box → **InlineChip**
   with `href`.
 
@@ -60,6 +61,15 @@ import { Link } from '@estiva-app/ui'
   sit, so put those on your own element around the link, not on the link —
   the lint refuses a look passed in `className` (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 |
+|---|---|---|
+| Says what it is to assistive technology: a link | `role="link"` | ✓ |
+| Is reachable with Tab | a `tabIndex` | ✓ |
+
 ## Props
 
 <Controls of={LinkStories.Text} />

package/src/Menu.mdx

@@ -41,7 +41,7 @@ definition either way.
 - Picking one value for a form field → **Select**.
 - Rows that toggle and stay open → that is a listbox, not a menu; a Checkbox
   inside a `menuitem` is invalid. Build it as a list in a **DialogShell**.
-- A strip of icon actions → a toolbar of **IconButton**s.
+- A strip of icon actions → **Toolbar**.
 - Who-you-are and where-you-are → **IdentityMenu**, already built on this.
 
 ## How
@@ -76,6 +76,21 @@ the trigger as "close" rather than as a press outside.
 
 <Canvas of={MenuStories.OnACard} />
 
+## 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 | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Enter and Space choose a row, Escape closes it | a key listener on the page | ✓ |
+| Moves through its items with the arrow keys, and jumps to a row by its first letters | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a menu, and each row a menu item | `role="menu"` or `role="menuitem"` | ✓ |
+| Keeps its own open state, and closes when a row is chosen | `useState` for open |  |
+| Gives focus back to the trigger when it closes | focus code |  |
+
 ## Keys
 
 | Input | What happens |

package/src/MenuItem.mdx

@@ -25,8 +25,9 @@ other two), `destructive` in the error colour, `selected` as the fill.
 
 ## When not
 
-- Outside a menu — it renders `role="menuitem"` and belongs inside a
-  `role="menu"` container.
+- A single action that is not a row in a list → **Button**. Outside a
+  **Menu**, MenuItem is a plain button with a row's look, so a row-shaped
+  action at the top of a list — "Add members" — is fine.
 - Picking a form value → **Select**'s own options.
 - A row that toggles a checkbox → not a menu at all; see the Menu page.
 
@@ -50,6 +51,15 @@ import { IconPencil } from '@tabler/icons-react'
 - A destructive row's `leading` icon takes the error colour itself
   (`text-error-default`) — the row colours only its label.
 
+## 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 |
+|---|---|---|
+| Is a row of its Menu: the Menu highlights it, walks to it with the arrow keys, and closes when it is chosen | a highlight or a key handler on the row |  |
+| Opens its `submenu` with → and closes it with ← | a submenu of your own |  |
+
 ## Props
 
 <Controls of={MenuItemStories.Default} />

package/src/NavItem.mdx

@@ -48,6 +48,14 @@ import { NavItem } from '@estiva-app/ui'
   anchor prop passes through.
 - The label truncates; the count never gives up its width.
 
+## 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 |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+
 ## Props
 
 <Controls of={NavItemStories.Default} />

package/src/Person.mdx

@@ -39,6 +39,10 @@ import { Person } from '@estiva-app/ui'
   and words are always set together (the Sizes story shows the pairings).
 - The name truncates; give the container `min-w-0` room to let it.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PersonStories.Named} />

package/src/PersonTrigger.mdx

@@ -53,6 +53,15 @@ import { Menu, PersonTrigger } from '@estiva-app/ui'
 - It is a native `<button>` on Base UI's Button: it takes a `ref` and every
   native button prop.
 
+## 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 |
+|---|---|---|
+| Is a button: Tab reaches it, Enter and Space call your `onClick` | a clickable `<div>` |  |
+| Names itself from the person's name, and says whether what it opens is open (`open`) | `aria-label` or `aria-expanded` |  |
+
 ## Keys
 
 | Key | Does |

package/src/Popover.mdx

@@ -83,7 +83,15 @@ so it is the one case the caller drives:
   open={selectionRect !== null}
   onOpenChange={(open) => !open && setSelectionRect(null)}
   ariaLabel="Formatting"
+  side="top"
+  contentClassName="p-1"
 >
+  <Toolbar aria-label="Formatting">
+    <ToolbarButton aria-label="Bold" tooltip="Bold" onClick={bold}>
+      <IconBold size={16} stroke={1.5} />
+    </ToolbarButton>
+  </Toolbar>
+</Popover>
 ```
 
 - **`anchor`** takes an element or a rect. A new rect moves the panel, so
@@ -116,6 +124,19 @@ something belongs on a `trigger`.
 
 <Canvas of={PopoverStories.FlippedForRoom} />
 
+## 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 | ✓ |
+| Stays attached to its anchor on scroll and resize, and flips side when there is no room | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Takes its keys by itself: Escape closes it | a key listener on the page | ✓ |
+| Moves focus in when it opens, and back to the trigger when it closes | focus code |  |
+| Keeps its own open state | `useState` for open — unless you must know it (`open` / `onOpenChange`) |  |
+
 ## Keys
 
 | Input | What happens |

package/src/PreviewCard.mdx

@@ -45,7 +45,7 @@ pointer never sees it.
 import { PreviewCard } from '@estiva-app/ui'
 
 <PreviewCard content={<ItemDetail id={row.id} />} wrapperClassName="block w-full">
-  <ListRow …/>
+  <ListRow item={row} />
 </PreviewCard>
 ```
 
@@ -57,9 +57,12 @@ import { PreviewCard } from '@estiva-app/ui'
 - **It prefers the right of the trigger and flips** when that side has no room,
   staying 12px from the trigger and 8px clear of every screen edge. `side`
   changes the preference, not the promise.
-- **Width, padding and height are yours** through `className`. The default is
-  360px wide, capped at 300px or the room available, whichever is smaller — a
-  preview of one kind of thing is not the size of a preview of another.
+- **Width is yours** through `className`; **padding and rhythm** through
+  `contentClassName`. The default is 360px wide, 12px of padding, capped at
+  300px or the room available, whichever is smaller — a preview of one kind of
+  thing is not the size of a preview of another.
+- The padding sits inside the scrolling box, as in `Popover`, so the
+  scrollbar hugs the card's edge: its thumb 3px from it, like every panel's.
 - The trigger wrapper is `inline-flex`; a full-width row wants
   `wrapperClassName="block w-full"`.
 
@@ -82,6 +85,18 @@ lands.
 
 <Canvas of={PreviewCardStories.Loading} />
 
+## 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 | ✓ |
+| Stays attached to its anchor on scroll and resize | a scroll or resize listener, or placement arithmetic | ✓ |
+| Closes on a press outside | a click listener on the page | ✓ |
+| Opens after the pointer rests, and stays up while the pointer moves into it | a hover timer |  |
+| Closes on Escape | a key handler |  |
+
 ## Keys
 
 There is no keyboard trigger, by design — see above.

package/src/PreviewCard.tsx

@@ -35,8 +35,15 @@ export interface PreviewCardProps {
   delay?: number
   /** After the pointer leaves, in ms — the grace that lets you cross the gap into the card. */
   closeDelay?: number
-  /** On the card's surface: its width, its padding, a max height. */
+  /** On the card's surface: its width. */
   className?: string
+  /**
+   * On the scrolling content: its padding (default 12px) and rhythm. The
+   * padding sits inside the scrolling box, as in `Popover`, so the scrollbar
+   * hugs the card's edge — its thumb 3px from it, like every panel's
+   * (Katerina, 19 September; it sat 12px in, behind the card's padding).
+   */
+  contentClassName?: string
   /** Extra classes on the trigger wrapper — e.g. `block w-full` for a row. */
   wrapperClassName?: string
 }
@@ -58,7 +65,7 @@ const OPEN_DELAY = 350
  *  here the card can be reached, so it can. */
 const CLOSE_DELAY = 200
 
-export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, wrapperClassName }: PreviewCardProps) {
+export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, contentClassName, wrapperClassName }: PreviewCardProps) {
   return (
     <BasePreviewCard.Root>
       {/* The part renders an `<a>` by default, which a row is not; `render`
@@ -80,10 +87,10 @@ export function PreviewCard({ content, children, side = 'right', delay = OPEN_DE
           className="z-50 data-[anchor-hidden]:hidden"
         >
           <BasePreviewCard.Popup
-            className={cn('w-[360px] p-3 outline-none', className)}
+            className={cn('w-[360px] p-0 outline-none', className)}
             render={<MenuPanel />}
           >
-            <ScrollArea viewportClassName="max-h-[calc(min(300px,var(--available-height))_-_1.5rem)]" contentClassName="flex flex-col gap-3">
+            <ScrollArea viewportClassName="max-h-[min(300px,var(--available-height))]" contentClassName={cn('flex flex-col gap-3 p-3', contentClassName)}>
               {content}
             </ScrollArea>
           </BasePreviewCard.Popup>

package/src/ProgressBar.mdx

@@ -42,6 +42,14 @@ import { ProgressBar } from '@estiva-app/ui'
   of the button's.
 - `className` is for placement: a width, a margin, `flex-1` in a row.
 
+## 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 progress bar, with its value | `role="progressbar"` or `aria-valuenow` | ✓ |
+
 ## Props
 
 <Controls of={ProgressBarStories.Default} />

package/src/Property.mdx

@@ -54,6 +54,10 @@ WithControls story shows the pairings).
   a child of the row or the column: a control with `flex-1` still fills the
   row, and two values still sit the row's gap apart.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={PropertyStories.Row} />

package/src/Rail.mdx

@@ -25,7 +25,7 @@ nothing else: **RailItem** is the tile, and where a tile goes is the app's.
   needs more than a word needs a row.
 - More entries than fit down a screen → fewer entries. The rail does not
   scroll, on purpose.
-- A strip of *actions* rather than places → a toolbar of **IconButton**s.
+- A strip of *actions* rather than places → **Toolbar**.
 
 <Canvas of={RailStories.ManyItems} />
 
@@ -52,6 +52,14 @@ import { Rail, RailItem } from '@estiva-app/ui'
 
 <Canvas of={RailStories.OneItem} />
 
+## 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 |
+|---|---|---|
+| Is a navigation, named "Navigation" unless you name it | `<nav>` or `aria-label` |  |
+
 ## Keys
 
 The rail has no keyboard of its own: its tiles are links, and Tab walks them in

package/src/RailItem.mdx

@@ -45,6 +45,14 @@ import { Rail, RailItem } from '@estiva-app/ui'
   click, navigate.
 - Icons are 16px at stroke 1.5.
 
+## 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 |
+|---|---|---|
+| Marks the current place for assistive technology when `active` | `aria-current` |  |
+
 ## Props
 
 <Controls of={RailItemStories.Default} />

package/src/Reaction.mdx

@@ -50,6 +50,15 @@ import { Reaction } from '@estiva-app/ui'
   another client can change the count.
 - `disabled` takes it out of the Tab order and ignores presses.
 
+## 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 |
+|---|---|---|
+| Is a toggle: pressed or not, and says so to assistive technology | `aria-pressed` |  |
+| Presses on Enter and Space; Tab skips it while disabled | a key handler |  |
+
 ## Keys
 
 | Key | What happens |

package/src/ReactionPicker.mdx

@@ -68,6 +68,14 @@ and, when it is yours, the accent fill. The picker asks; the pill answers.
 
 <Canvas of={ReactionPickerStories.AndWhatItProduces} />
 
+## 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 |
+|---|---|---|
+| Everything a Toolbar owns: one Tab stop, arrow keys between the reactions, wrapping at the ends | a key handler, or `tabIndex` on each reaction |  |
+
 ## Keys
 
 | Input | What happens |

package/src/ScrollArea.mdx

@@ -13,8 +13,10 @@ the content is moving; nothing moves when it appears.
 
 ## When
 
-- Any box that can hold more than fits: a menu or a dropdown list, a panel,
-  a sidebar, the page's content column, a rail.
+- Any box that can hold more than fits — **a list that grows with its data
+  counts, even when today's data fits**: a menu or a dropdown list, a panel, a
+  sidebar, the page's content column. Not a rail: a rail does not scroll, on
+  purpose.
 - `orientation="horizontal"` for a row wider than its box — a table, a
   board; `"both"` when a thing can run over either way.
 
@@ -53,6 +55,15 @@ import { ScrollArea } from '@estiva-app/ui'
   Chrome: wheel down over a sideways region inside a page, the page moves
   and the region does not; a sideways swipe, the other way round.
 
+## 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 |
+|---|---|---|
+| Scrolls with our scrollbar | `overflow-auto` or `overflow-scroll` | ✓ |
+| Scrolls with the keyboard when it has focus, like any scrolling box | key handlers |  |
+
 ## Keys
 
 | Key | Does |

package/src/SearchInput.mdx

@@ -38,6 +38,15 @@ import { SearchInput } from '@estiva-app/ui'
   and this usually stands alone in a top bar rather than in a `Field`.
   Inside one, the label names it and you add nothing.
 
+## 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 |
+|---|---|---|
+| Inside a `Field`, takes its name from the Field's label | an `id` / `htmlFor` pair |  |
+| Shows its focus ring while anything inside it has focus | a focus style of your own |  |
+
 ## Props
 
 <Controls of={SearchInputStories.Default} />

package/src/SectionHeader.mdx

@@ -53,6 +53,19 @@ import { IconPlus } from '@tabler/icons-react'
 - `render` swaps the title's element in Base UI's manner; it is how
   CollapsibleSection makes the title a `Collapsible.Trigger`.
 
+- `hover="none"` keeps the row still under the pointer: for a heading whose
+  actions are always shown (`showActions="always"`), where the buttons light up
+  on their own. The default, `fill`, lights a row that toggles or has actions.
+
+## 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 |
+|---|---|---|
+| With `chevron`, its title is a button that calls `onToggle` on a click, Enter or Space, and says whether it is open | a button of your own, or `aria-expanded` |  |
+| Shows its actions while one of them has focus | a focus style of your own |  |
+
 ## Keys
 
 | Key | Does |

package/src/SectionHeader.stories.tsx

@@ -35,6 +35,15 @@ export const PersistentActions: Story = {
   },
 }
 
+/** `hover="none"`: actions always shown, and the row stays still under the pointer — only the buttons light up. */
+export const StillOnHover: Story = {
+  args: {
+    showActions: 'always',
+    hover: 'none',
+    actions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'Add', onClick: () => {} }],
+  },
+}
+
 /** A count beside the title, held on screen while the actions come and go. */
 export const WithTrailing: Story = {
   args: {

package/src/SectionHeader.test.tsx

@@ -23,6 +23,15 @@ describe('SectionHeader', () => {
     expect(onToggle).toHaveBeenCalledTimes(2)
   })
 
+  it('fills under the pointer when it does something, and hover="none" keeps it still', () => {
+    const actions = [{ icon: <i />, tooltip: 'Add', onClick: () => {} }]
+    const lit = render(<SectionHeader title="Section" actions={actions} />)
+    expect((lit.container.firstElementChild as HTMLElement).className).toContain('hover:bg-bg-hover')
+    cleanup()
+    const still = render(<SectionHeader title="Section" actions={actions} hover="none" />)
+    expect((still.container.firstElementChild as HTMLElement).className).not.toContain('hover:bg-bg-hover')
+  })
+
   it('an action beside the title acts, and never toggles', async () => {
     const onToggle = vi.fn()
     const add = vi.fn()