@estiva-app/ui 0.55.0 → 0.57.0

package/src/Menu.tsx

@@ -95,7 +95,8 @@ export function MenuPanel({ children, className, ...props }: MenuPanelProps) {
   return (
     <div
       className={cn(
-        'flex flex-col p-2',
+        // 2px between rows, as a list column's and a sidebar's (Katerina, 5 October).
+        'flex flex-col gap-0.5 p-2',
         FLOATING_SURFACE_CLASSES,
         /*
          * A divider in a menu runs the width of the rows it separates.
@@ -248,7 +249,7 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
              * 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', contentClassName)}>
+            <ScrollArea viewportClassName="max-h-[var(--available-height)]" contentClassName={cn('flex flex-col gap-0.5 p-2', contentClassName)}>
               <MenuContext.Provider value={{ openOnHover }}>
                 <DividerInPanel.Provider value={true}>{children}</DividerInPanel.Provider>
               </MenuContext.Provider>
@@ -578,14 +579,14 @@ export function MenuSection({ label, children, className }: { label: string; chi
   )
   if (!inMenu) {
     return (
-      <div className="flex flex-col">
+      <div className="flex flex-col gap-0.5">
         {heading}
         {children}
       </div>
     )
   }
   return (
-    <BaseMenu.Group className="flex flex-col">
+    <BaseMenu.Group className="flex flex-col gap-0.5">
       <BaseMenu.GroupLabel render={heading} />
       {children}
     </BaseMenu.Group>

package/src/NavItem.mdx

@@ -24,7 +24,9 @@ count — a muted mono number whose tooltip says what it counts.
 
 - A row with things to do to it — move it, rename it — takes them as
   `menu`: pass `MenuItem`s, and the row draws the ⋮, shows it while the row
-  is pointed at or focused, and moves the count aside for it.
+  is pointed at or keyboard-focused, and moves the count aside for it. On a
+  screen with no hover the ⋮ always shows, and the count or dot under it
+  stays aside: the row reads as it does under a pointer.
 
 <Canvas of={NavItemStories.WithMenu} />
 

package/src/NavItem.test.tsx

@@ -94,15 +94,45 @@ describe('NavItem unread', () => {
     expect(container.querySelector('[data-unread]')).toBeNull()
   })
 
+  it('the dot and the badge are pulled 4px right (-mr-1), onto the axis of a count and of the ⋮', () => {
+    const { container } = render(
+      <>
+        <NavItem href="#" label="Item one" unread />
+        <NavItem href="#" label="Item two" unread urgent />
+      </>,
+    )
+    expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('-mr-1')
+    expect(container.querySelector('[data-urgent]')!.parentElement!.className.split(' ')).toContain('-mr-1')
+  })
+
   it('urgent without unread draws nothing', () => {
     const { container } = render(<NavItem href="#" label="Item one" urgent />)
     expect(container.querySelector('[data-urgent], [data-unread]')).toBeNull()
   })
 
-  it('with a menu, the ⋮ sits in the 24px slot over the dot', () => {
+  it('with a menu over the dot, the ⋮ ends where a heading’s ⋮ ends', () => {
     render(<NavItem href="#" label="Item one" unread menu={<span>Action</span>} />)
     const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')
-    expect(menu?.className).toContain('right-2')
+    expect(menu?.className).toContain('right-1')
+  })
+
+  it('on a screen with no hover the ⋮ always shows, and the count steps aside for it', () => {
+    render(<NavItem href="#" label="Item one" count={3} menu={<span>Action</span>} />)
+    const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')!
+    expect(menu.className.split(' ')).toContain('[@media(hover:none)]:opacity-100')
+    expect(screen.getByText('3').className.split(' ')).toContain('[@media(hover:none)]:opacity-0')
+  })
+
+  it('on a screen with no hover, with nothing at the right, the ⋮’s place is kept so the label stops before it', () => {
+    const { container } = render(<NavItem href="#" label="Item one" menu={<span>Action</span>} />)
+    expect(container.querySelector('a > [aria-hidden="true"]')!.className.split(' ')).toContain('[@media(hover:none)]:block')
+  })
+
+  it('with nothing at the right, the ⋮’s kept place is the ⋮’s own, at right-1, so the label loses no more than it covers', () => {
+    const { container } = render(<NavItem href="#" label="Item one" menu={<span>Action</span>} />)
+    // The slot is pulled 4px into the padding, as the ⋮ is (`right-1`): measured, the label then stops 8px before the button, not 12.
+    expect(container.querySelector('a > [aria-hidden="true"]')!.className.split(' ')).toEqual(expect.arrayContaining(['-mr-1', 'w-6']))
+    expect(screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')!.className).toContain('right-1')
   })
 
   it('with a count and a menu, the ⋮ lands on the count', () => {

package/src/NavItem.tsx

@@ -108,7 +108,13 @@ export function NavItem({
   // What sits at the right at rest, after the count: the dot, or the badge.
   const mark = unread ? (urgent ? <UrgentMark /> : <UnreadDot />) : null
   // Under the ⋮ while it shows: the count and the mark step aside for it.
-  const stepsAside = menu != null && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0 group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0'
+  // "While it shows" is the pointer on the row or the keyboard in it
+  // (`:focus-visible`), never any focus: a clicked row keeps its focus, and
+  // with `focus-within` its icon and dot went while the arrow and the ⋮ stayed
+  // hidden (Katerina, 5 October).
+  // A screen with no hover shows the ⋮ always (below), so what it lands on
+  // steps aside always: the row reads as it does under a pointer.
+  const stepsAside = menu != null && 'transition-opacity group-hover/nav:opacity-0 group-has-[:focus-visible]/nav:opacity-0 group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0 [@media(hover:none)]:opacity-0'
 
   const row = (
     <a
@@ -135,7 +141,7 @@ export function NavItem({
           className={cn(
             // With rows under it the slot is kept even with no icon: the arrow lands in it.
             'flex min-w-4 shrink-0 items-center',
-            hasRows && 'transition-opacity group-hover/nav:opacity-0 group-focus-within/nav:opacity-0',
+            hasRows && 'transition-opacity group-hover/nav:opacity-0 group-has-[:focus-visible]/nav:opacity-0',
           )}
         >
           {icon}
@@ -144,7 +150,7 @@ export function NavItem({
       <span className={cn('flex-1 truncate', unread && 'font-medium')}>{label}</span>
       {hint != null && (
         // Takes room only while it shows, so the label gives way to it.
-        <span className="hidden shrink-0 items-center group-hover/nav:flex group-focus-within/nav:flex">{hint}</span>
+        <span className="hidden shrink-0 items-center group-hover/nav:flex group-has-[:focus-visible]/nav:flex">{hint}</span>
       )}
       {count ? (
         <WithTooltip label={countLabel ?? `${count} open`}>
@@ -164,12 +170,18 @@ export function NavItem({
         </WithTooltip>
       ) : null}
       {mark ? (
-        <span className={cn('flex shrink-0', stepsAside)}>{mark}</span>
+        // `-mr-1`: the 24px slot's dot then sits on the axis of a count and
+        // of the ⋮ (8px from the edge to the 16px box), one column with a
+        // folder heading's dot and ⋮ (Katerina, 5 October).
+        <span className={cn('-mr-1 flex shrink-0', stepsAside)}>{mark}</span>
       ) : menu != null && !count ? (
         // Nothing at the right, but a menu: no room is kept at rest, so the
         // label has the row's whole width; while the ⋮ shows, its 24px slot
         // is kept, so a long label ends before it instead of running under it.
-        <span aria-hidden="true" className="hidden w-6 shrink-0 group-hover/nav:block group-focus-within/nav:block group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:block" />
+        // `-mr-1`: the ⋮ sits at `right-1`, 4px into the row's padding, so the
+        // slot does too — at the padding's edge it kept 4px the ⋮ never
+        // covers, and the label stopped 12px short of the button, not 8.
+        <span aria-hidden="true" className="-mr-1 hidden w-6 shrink-0 group-hover/nav:block group-has-[:focus-visible]/nav:block group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:block [@media(hover:none)]:block" />
       ) : null}
     </a>
   )
@@ -181,7 +193,7 @@ export function NavItem({
       {hasRows && (
         // `left-1`: the 24px button's 16px arrow then sits where the icon
         // sits (the row's px-2), so the icon turns into the arrow in place.
-        <div className="absolute inset-y-0 left-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100">
+        <div className="absolute inset-y-0 left-1 flex items-center opacity-0 transition-opacity group-hover/nav:opacity-100 group-has-[:focus-visible]/nav:opacity-100">
           <IconButton
             tooltip={open ? 'Collapse' : 'Expand'}
             aria-label={open ? `Hide what is under ${label}` : `Show what is under ${label}`}
@@ -194,11 +206,15 @@ export function NavItem({
         </div>
       )}
       {menu != null && (
-        // On a count, `right-1`: the 24px button's 16px icon then ends 8px
-        // from the row's edge, where the count ends (px-2), so the ⋮ lands on
-        // the number. On the mark or the empty slot, `right-2`: the button
-        // sits in the 24px slot itself.
-        <div data-nav-menu className={cn('absolute inset-y-0 flex items-center', count && !mark ? 'right-1' : 'right-2', 'opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100')}>
+        // `right-1`: the 24px button's 16px icon ends 8px from the row's
+        // edge, where a count ends (px-2) — and where a SectionHeader's
+        // actions and ⋮ end, so a folder's ⋮ and its rows' ⋮ are one column
+        // (Katerina, 5 October: the rows move to the heading, not the
+        // heading to the rows). Over a dot or the empty slot it sits 4px
+        // right of the slot's centre.
+        // On a screen with no hover it always shows: nothing there can point
+        // at the row, and the menu has no other way in.
+        <div data-nav-menu className={cn('absolute inset-y-0 right-1 flex items-center', 'opacity-0 transition-opacity group-hover/nav:opacity-100 group-has-[:focus-visible]/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100 [@media(hover:none)]:opacity-100')}>
           <Menu
             align="right"
             trigger={
@@ -225,7 +241,7 @@ export function NavItem({
         className={COLLAPSIBLE_PANEL_CLASSES}
       >
         {/* `pl-6`: past the 16px icon and its 8px gap, so the rows' icons start under this row's label. */}
-        <div className="flex flex-col gap-px pl-6">{children}</div>
+        <div className="flex flex-col gap-0.5 pt-0.5 pl-6">{children}</div>
       </Collapsible.Panel>
     </Collapsible.Root>
   )

package/src/NavTree.mdx

@@ -33,6 +33,21 @@ rows to any depth.
 
 <Canvas of={NavTreeStories.WithActionsAndUnread} />
 
+- A group's `menu` is its "More options" ⋮, after its actions and its
+  `trailing`: what acts on the whole group — a folder's Rename, Archive. A
+  row's `menu` acts on that row.
+
+<Canvas of={NavTreeStories.GroupMenus} />
+
+- A group folds with a row's arrow, 16px — every folding heading does — so a
+  group and the rows under it fold with the same arrow; its title starts 8px
+  after it, as a row's label.
+- A group's `icon` sits before its title — a folder's — and the arrow takes
+  its place under the pointer, as a row's icon turns into its arrow. Its rows
+  then start under the title, past the icon.
+
+<Canvas of={NavTreeStories.GroupIcons} />
+
 - Rows can be read as they open. A group's `nodes={null}` is a skeleton in
   its rows' place, and its `message` a line in their place ("Nothing in this
   yet."). A row with `hasChildren` and no `children` has its arrow, a
@@ -47,7 +62,7 @@ rows to any depth.
   itself: leave out `groups` and pass **NavTreeSection**s as children, each
   with **NavItem** rows. A `NavTreeSection` is one group exactly as `groups`
   draws it — the heading, the light indent, `message`, `loading`, `trailing`,
-  `actions`, `onIntent`.
+  `actions`, `menu`, `icon`, `onIntent`.
 
 <Canvas of={NavTreeStories.AppDrawnGroups} />
 

package/src/NavTree.stories.tsx

@@ -1,9 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSquareRounded } from '@tabler/icons-react'
 import { useState } from 'react'
-import { IconArrowUpRight, IconPlus } from '@tabler/icons-react'
+import { IconArrowUpRight, IconFolder, IconPlus } from '@tabler/icons-react'
 import { Chip } from './Chip'
 import { UnreadDot } from './UnreadDot'
+import { MenuItem, MenuSeparator } from './Menu'
 import { NavItem } from './NavItem'
 import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
 import { Sidebar } from './Sidebar'
@@ -101,6 +102,52 @@ export const WithActionsAndUnread: Story = {
   },
 }
 
+const groupMenu = (
+  <>
+    <MenuItem label="Add" />
+    <MenuItem label="Rename" />
+    <MenuItem label="Archive…" />
+    <MenuSeparator />
+    <MenuItem label="Delete" destructive />
+  </>
+)
+const rowMenu = (
+  <>
+    <MenuItem label="Move…" />
+    <MenuItem label="Rename" />
+  </>
+)
+
+/** A group's `menu`: its "More options", after its dot. Each row has its own. Hover a group's title. */
+export const GroupMenus: Story = {
+  args: {
+    groups: [
+      { id: 'm1', title: 'Group one', trailing: <UnreadDot />, menu: groupMenu, defaultOpen: true, nodes: [
+        { id: 'm1a', label: 'Item two', href: '#', icon: placeholder, unread: true, menu: rowMenu },
+        { id: 'm1b', label: 'Item three', href: '#', icon: placeholder, menu: rowMenu },
+      ] },
+      { id: 'm2', title: 'Group two', menu: groupMenu, nodes: [{ id: 'm2a', label: 'Item four', href: '#', icon: placeholder, menu: rowMenu }] },
+    ],
+    selected: 'm1b',
+  },
+}
+
+const folder = <IconFolder size={16} stroke={1.5} />
+
+/** A group's `icon`: a folder before its title, the arrow in its place on hover; its rows start under the title. */
+export const GroupIcons: Story = {
+  args: {
+    groups: [
+      { id: 'i1', title: 'Group one', icon: folder, menu: groupMenu, defaultOpen: true, nodes: [
+        { id: 'i1a', label: 'Item two', href: '#', icon: placeholder, unread: true, menu: rowMenu },
+        { id: 'i1b', label: 'Item three', href: '#', icon: placeholder, menu: rowMenu },
+      ] },
+      { id: 'i2', title: 'Group two', icon: folder, menu: groupMenu, nodes: [{ id: 'i2a', label: 'Item four', href: '#', icon: placeholder }] },
+    ],
+    selected: 'i1b',
+  },
+}
+
 /** Read as it opens: a group still being read, a group with nothing in it, a row whose rows are read when it opens, and one that could not be read. */
 export const ReadAsItOpens: Story = {
   args: {
@@ -124,7 +171,7 @@ export const AppDrawnGroups: Story = {
       <div className="flex h-screen bg-bg-base">
         <Sidebar>
           <NavTree title={args.title}>
-            <NavTreeSection title="Group one" trailing={<UnreadDot />}>
+            <NavTreeSection title="Group one" trailing={<UnreadDot />} menu={groupMenu}>
               <NavItem href="#" label="Item one" icon={placeholder} unread />
               <NavItem href="#" label="Item two" icon={placeholder} active>
                 <NavItem href="#" label="Item three" icon={placeholder} />

package/src/NavTree.test.tsx

@@ -7,6 +7,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
+import { MenuItem } from './Menu'
 import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
 
 afterEach(cleanup)
@@ -93,6 +94,12 @@ describe('NavTree read as it opens', () => {
     expect(screen.getByRole('button', { name: 'Open' })).not.toBeNull()
   })
 
+  it('a group’s menu is a ⋮ named for the group, and opens its items', async () => {
+    render(<NavTree groups={[{ id: 'a', title: 'Group a', nodes: [], menu: <MenuItem label="Rename" /> }]} />)
+    await userEvent.click(screen.getByRole('button', { name: 'More options for Group a' }))
+    expect(await screen.findByRole('menuitem', { name: 'Rename' })).not.toBeNull()
+  })
+
   it('onIntent: the keyboard reaching a group says so at once', () => {
     const onIntent = vi.fn()
     render(<NavTree groups={[{ id: 'a', title: 'Group a', nodes: [], onIntent }]} emptyMessage="Nothing here yet." />)
@@ -123,6 +130,27 @@ describe('NavTree marks its groups', () => {
   })
 })
 
+/**
+ * 4px between groups and none above the first, title or no title. The margin
+ * was `mt-1 first:mt-0`, and the quiet title is drawn before the groups, so
+ * the first group under a title was never the first child and took the 4px
+ * (measured in Chrome: 6px under the title, 2px after).
+ */
+describe('NavTree spaces its groups', () => {
+  it('only a group after a group takes the 4px, so the first sits at the column’s 2px under the title', () => {
+    const { container } = render(<NavTree title="Groups" groups={GROUPS} emptyMessage="Nothing here yet." />)
+    const boxes = [...container.querySelectorAll<HTMLElement>('[data-nav-group]')]
+    for (const box of boxes) {
+      const classes = box.className.split(' ')
+      expect(classes).toContain('[&+&]:mt-1')
+      expect(classes).not.toContain('mt-1')
+    }
+    // The selector's own terms: the first group follows the title, which is no group.
+    expect(boxes[0].previousElementSibling!.className.split(' ')).not.toContain('[&+&]:mt-1')
+    expect(boxes[1].previousElementSibling).toBe(boxes[0])
+  })
+})
+
 describe('NavTree with no groups and no words', () => {
   it('draws no line at all', () => {
     const { container } = render(<NavTree groups={[]} />)

package/src/NavTree.tsx

@@ -50,8 +50,12 @@ export interface NavTreeGroup {
   message?: string
   /** Beside the title, always shown: an `UnreadDot`, typically. */
   trailing?: ReactNode
-  /** Beside the title, shown on hover or focus: "Open", typically. */
+  /** Beside the title, shown while the row is hovered or keyboard-focused: "Open", typically. */
   actions?: SectionAction[]
+  /** The group's "More options" menu, after its actions: `MenuItem`s — a folder's Rename, Archive. */
+  menu?: ReactNode
+  /** 16px, before the title — a folder's; the arrow takes its place on hover. */
+  icon?: ReactNode
   defaultOpen?: boolean
   /** The caller owns whether the group is open. */
   open?: boolean
@@ -146,6 +150,8 @@ function Group({ group, selected, onSelect, storageKey }: { group: NavTreeGroup
       loading={group.nodes === null}
       trailing={group.trailing}
       actions={group.actions}
+      menu={group.menu}
+      icon={group.icon}
       defaultOpen={group.defaultOpen ?? holds(group.nodes, selected)}
       open={group.open}
       onOpenChange={group.onOpenChange}
@@ -165,8 +171,12 @@ export interface NavTreeSectionProps {
   message?: string
   /** Beside the title, always shown: an `UnreadDot`, typically. */
   trailing?: ReactNode
-  /** Beside the title, shown on hover or focus: "Open", typically. */
+  /** Beside the title, shown while the row is hovered or keyboard-focused: "Open", typically. */
   actions?: SectionAction[]
+  /** The group's "More options" menu, after its actions: `MenuItem`s. */
+  menu?: ReactNode
+  /** 16px, before the title; the arrow takes its place on hover. */
+  icon?: ReactNode
   /** Open unless told otherwise. */
   defaultOpen?: boolean
   /** The caller owns whether the group is open. */
@@ -189,13 +199,21 @@ export interface NavTreeSectionProps {
  * `groups`; an app whose groups each read their own data draws them itself,
  * as `NavTree`'s children.
  */
-export function NavTreeSection({ id, title, message, loading = false, trailing, actions, defaultOpen = true, open, onOpenChange, storageKey, onIntent, children }: NavTreeSectionProps) {
+export function NavTreeSection({ id, title, message, loading = false, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, onIntent, children }: NavTreeSectionProps) {
   const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
   useEffect(() => () => clearTimeout(timer.current), [])
   const intent = onIntent
   return (
     <div
-      className="shrink-0"
+      // 4px between groups, none above the first: a folded group's heading
+      // sits 38px from the next (Katerina, 5 October: 42 was too far from rows
+      // 33 apart; halved), and the list starts 16px under its header, as every
+      // list column does (on the first group it read 20, Topics against People).
+      // The margin is on a group that follows a group (`[&+&]`), not "all but
+      // the first child": NavTree draws its quiet title before the groups, so
+      // with `first:mt-0` the first group under a title still took the 4px
+      // (measured 6px under the title, 2px once the margin went).
+      className="shrink-0 [&+&]:mt-1"
       data-nav-group={id}
       onPointerEnter={intent ? () => { clearTimeout(timer.current); timer.current = setTimeout(intent, NAV_TREE_INTENT_MS) } : undefined}
       onPointerLeave={intent ? () => clearTimeout(timer.current) : undefined}
@@ -210,8 +228,11 @@ export function NavTreeSection({ id, title, message, loading = false, trailing,
         storageKey={storageKey}
         trailing={trailing}
         actions={actions}
-        className="mt-2 shrink-0"
-        contentClassName="gap-px"
+        menu={menu}
+        icon={icon}
+        className="shrink-0"
+        // 2px between rows, as a list column's and a menu's (Katerina, 5 October).
+        contentClassName="gap-0.5"
       >
         {message !== undefined ? <Line message={message} /> : loading ? <SkeletonList rows={3} /> : children}
       </CollapsibleSection>

package/src/PersonTrigger.tsx

@@ -2,6 +2,7 @@ import type { ComponentPropsWithRef } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
 import { IconChevronDown } from '@tabler/icons-react'
 import { cn } from './cn'
+import { MENU_TRIGGER_CLASSES } from './looks'
 import { Avatar } from './Avatar'
 import { Person, type PersonProps } from './Person'
 
@@ -66,13 +67,13 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
       aria-haspopup="menu"
       aria-expanded={open}
       className={cn(
-        'flex h-8 min-h-8 cursor-pointer items-center gap-1.5 rounded-md pl-1.5 pr-1.5 text-body-2 text-text-primary transition-colors hover:bg-bg-hover',
+        'flex h-8 min-h-8 items-center gap-1.5 pl-1.5 pr-1.5 text-body-2 text-text-primary',
+        MENU_TRIGGER_CLASSES,
         open && 'bg-bg-hover',
         // Under a `Menu` the open state is Base UI's, not a prop: the trigger
-        // carries `data-popup-open` while its menu is up, and sets its own
-        // `aria-expanded`. Both spellings hold the fill, so this works whether
-        // the caller drives it or the menu does.
-        'data-[popup-open]:bg-bg-hover',
+        // carries `data-popup-open` while its menu is up (MENU_TRIGGER_CLASSES
+        // holds the fill for it), and sets its own `aria-expanded`; `open`
+        // holds it for a caller that drives it.
         className,
       )}
       {...props}

package/src/SectionHeader.mdx

@@ -6,7 +6,8 @@ import * as SectionHeaderStories from './SectionHeader.stories'
 # SectionHeader
 
 The 32px row a section starts with: a SectionLabel, and actions that
-appear on hover or focus as IconButtons with tooltips. It is also the
+appear while the row is hovered or keyboard-focused, as IconButtons with
+tooltips — always, on a screen with no hover. It is also the
 header of a **CollapsibleSection**, which draws the chevron and makes the
 title the toggle — that is where a section folds.
 
@@ -24,6 +25,12 @@ title the toggle — that is where a section folds.
 
 <Canvas of={SectionHeaderStories.PersistentActions} />
 
+- `menu` gives the section a "More options" ⋮ after its actions, with what
+  acts on the whole section — a folder's Rename, Archive. It is **NavItem**'s
+  ⋮, revealed with the actions, and stays while its menu is open.
+
+<Canvas of={SectionHeaderStories.WithMenu} />
+
 - `look="quiet"`: a small grey label over a list whose rows are rows, not
   headings — "Folders" over the folders — with its action held on screen.
   It never lights up under the pointer; its button does.
@@ -80,7 +87,7 @@ 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 |  |
+| Shows its actions while the keyboard is in the row — on the title or on one of them — and always on a screen with no hover | a focus style of your own |  |
 | Keeps its 32px in a scrolling column | `shrink-0` |  |
 
 ## Keys
@@ -88,7 +95,7 @@ It does these by itself. Write none of them around it.
 | Key | Does |
 |---|---|
 | Enter, Space | on the title, with `chevron`: calls `onToggle` |
-| Tab | the title, then each action — the actions show while one has focus |
+| Tab | the title, then each action — the actions show from the title on |
 
 ## Props
 

package/src/SectionHeader.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconPlus, IconSortDescending } from '@tabler/icons-react'
 import { Chip } from './Chip'
+import { MenuItem, MenuSeparator } from './Menu'
 import { SectionHeader } from './SectionHeader'
 
 /** The 32px row a section starts with. Hover it: the row fills, and its actions appear. A section that folds is CollapsibleSection, whose header this is. */
@@ -49,6 +50,23 @@ export const StillOnHover: Story = {
   },
 }
 
+/** `menu`: the section's "More options", after its actions and revealed with them. The row keeps its hover look while the menu is open. */
+export const WithMenu: Story = {
+  args: {
+    chevron: true,
+    isExpanded: true,
+    onToggle: () => {},
+    menu: (
+      <>
+        <MenuItem label="Add" />
+        <MenuItem label="Rename" />
+        <MenuSeparator />
+        <MenuItem label="Delete" destructive />
+      </>
+    ),
+  },
+}
+
 /** A count beside the title, held on screen while the actions come and go. */
 export const WithTrailing: Story = {
   args: {

package/src/SectionHeader.test.tsx

@@ -7,7 +7,10 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
+import { MenuItem } from './Menu'
+import { NavItem } from './NavItem'
 import { SectionHeader } from './SectionHeader'
+import { UnreadDot } from './UnreadDot'
 
 afterEach(cleanup)
 
@@ -48,6 +51,55 @@ describe('SectionHeader', () => {
   })
 })
 
+/**
+ * When the buttons show. The pointer and the menu are Chrome's to prove (the
+ * stories); what is pinned here is which element each reveal asks.
+ */
+describe('SectionHeader, the reveal', () => {
+  const menu = <MenuItem label="Rename" />
+  const actions = [{ icon: <span />, tooltip: 'Add', onClick: () => {} }]
+
+  it('shows the buttons once the title’s toggle has keyboard focus, as a NavItem shows its ⋮ for its link', () => {
+    const { container } = render(<SectionHeader title="Section" chevron onToggle={() => {}} actions={actions} menu={menu} />)
+    const row = container.firstElementChild as HTMLElement
+    const toggle = screen.getByRole('button', { name: 'Section' })
+    const buttons = screen.getByRole('button', { name: 'Add' }).parentElement!
+    // The row is the group, and it holds the toggle: the reveal asks the row, not the buttons' own box.
+    expect(row.className.split(' ')).toContain('group')
+    expect(row.contains(toggle)).toBe(true)
+    expect(buttons.className.split(' ')).toContain('group-has-[:focus-visible]:opacity-100')
+    expect(buttons.className.split(' ')).not.toContain('has-[:focus-visible]:opacity-100')
+    // An open menu holds them, asked of their own box: the toggle's aria-expanded must not.
+    expect(buttons.className.split(' ')).toContain('has-[[aria-expanded=true]]:opacity-100')
+  })
+
+  it('on a screen with no hover the buttons always show, and a dot under them steps aside', () => {
+    const { container } = render(<SectionHeader title="Section" trailing={<UnreadDot />} actions={actions} menu={menu} />)
+    expect(screen.getByRole('button', { name: 'Add' }).parentElement!.className.split(' ')).toContain('[@media(hover:none)]:opacity-100')
+    expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('[@media(hover:none)]:has-[[data-unread]]:opacity-0')
+  })
+
+  it('no reveal answers to any focus (`focus-within`): a clicked row kept its focus and lost its icon and dot (0.56.0)', () => {
+    const { container } = render(
+      <>
+        <SectionHeader title="Section" chevron icon={<span />} onToggle={() => {}} trailing={<UnreadDot />} actions={actions} menu={menu} />
+        <NavItem href="#" label="Item one" icon={<span />} count={2} hint={<span>Label</span>} menu={menu}>
+          <NavItem href="#" label="Item two" unread menu={menu} />
+        </NavItem>
+      </>,
+    )
+    const classes = [...container.querySelectorAll('*')].map((e) => e.getAttribute('class') ?? '').join(' ')
+    expect(classes).not.toContain('focus-within')
+    // The keyboard's reveal is what replaced it.
+    expect(classes).toContain('group-has-[:focus-visible]')
+  })
+
+  it('with showActions="always" there is nothing to reveal', () => {
+    render(<SectionHeader title="Section" actions={actions} showActions="always" />)
+    expect(screen.getByRole('button', { name: 'Add' }).parentElement!.className).not.toContain('opacity-0')
+  })
+})
+
 /**
  * The trailing slot (0.12.2, ADOPTION B23). Peek's Screener header carries its
  * count as a Chip there, and was the last hand-drawn folding header in the app
@@ -71,4 +123,41 @@ describe('SectionHeader, the trailing slot', () => {
     // Not part of the hover reveal either — a count is information, not an affordance.
     expect(count.closest('.opacity-0')).toBe(null)
   })
+
+  it('a dot sits in the last button’s place and steps aside for it; a count stays beside the buttons', () => {
+    const { container } = render(
+      <SectionHeader title="Section" trailing={<UnreadDot />} actions={[{ icon: <span />, tooltip: 'Open', onClick: () => {} }]} menu={<MenuItem label="Rename" />} />,
+    )
+    const slot = container.querySelector('[data-unread]')!.parentElement!
+    // Over the last button, out of the row's flow — not a slot of its own before them — and gone while they show.
+    expect(slot.className.split(' ')).toEqual(expect.arrayContaining(['has-[[data-unread]]:absolute', 'has-[[data-unread]]:right-1', 'has-[[data-unread]]:w-6', 'group-hover:has-[[data-unread]]:opacity-0']))
+    expect(slot.matches(':has([data-unread])')).toBe(true)
+    expect(screen.getByRole('button', { name: 'More options for Section' })).not.toBeNull()
+  })
+
+  it('a dot is found by what it draws, not by its element: one in a wrapper of the app’s own steps aside too', () => {
+    render(
+      <SectionHeader title="Section" trailing={<span data-testid="wrapped"><UnreadDot /></span>} menu={<MenuItem label="Rename" />} />,
+    )
+    const slot = screen.getByTestId('wrapped').parentElement!
+    expect(slot.matches(':has([data-unread])')).toBe(true)
+    expect(slot.className.split(' ')).toContain('has-[[data-unread]]:absolute')
+    // A count holds no dot, so the same slot keeps it beside the buttons.
+    cleanup()
+    render(<SectionHeader title="Section" trailing={<span data-testid="count">2</span>} menu={<MenuItem label="Rename" />} />)
+    expect(screen.getByTestId('count').parentElement!.matches(':has([data-unread])')).toBe(false)
+  })
+
+  it('an icon shows at rest, and folding, the arrow is in its place', () => {
+    const { container } = render(<SectionHeader title="Section" chevron icon={<span data-icon />} onToggle={() => {}} />)
+    const icon = container.querySelector('[data-icon]')!
+    expect(icon.parentElement!.className).toContain('group-hover:opacity-0')
+    // The arrow is the icon's sibling, hidden until the pointer comes.
+    expect(icon.parentElement!.parentElement!.querySelector('svg')!.getAttribute('class')).toContain('group-hover:opacity-100')
+  })
+
+  it('a dot with no buttons sits on their axis all the same', () => {
+    const { container } = render(<SectionHeader title="Section" trailing={<UnreadDot />} />)
+    expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('has-[[data-unread]]:-mr-1')
+  })
 })