@estiva-app/ui 0.54.0 → 0.56.0

package/src/EditorBlockHandle.mdx

@@ -0,0 +1,65 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as EditorBlockHandleStories from './EditorBlockHandle.stories'
+
+<Meta of={EditorBlockHandleStories} />
+
+# EditorBlockHandle
+
+`BlockHandle` in a Tiptap editor: drag the handle to move the block, press it
+for Turn into, Duplicate and Delete, then the app's rows.
+
+<Canvas of={EditorBlockHandleStories.Default} />
+
+## When
+
+- **An editor of a block document** (SPEC §13.3) that someone reorganises —
+  with `BlockNodes`' `BlockId` in its extensions, so every block has an id.
+- **Not editable**: the same handle reads — no drag, the app's rows only.
+
+## When not
+
+- The document being read, with no editor → **BlockHandle**, from the main
+  entry, which loads no Tiptap.
+- Formatting a few words inside a block → **SelectionToolbar**. This acts on
+  whole blocks.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, EditorBlockHandle, type BlockTurnInto } from '@estiva-app/ui/editor'
+import { MenuItem, type HandleBlock } from '@estiva-app/ui'
+
+const turnInto: BlockTurnInto[] = [
+  { label: 'Text', run: (editor) => editor.chain().setParagraph().run(), active: (node) => node.type.name === 'paragraph' },
+  { label: 'Heading', run: (editor) => editor.chain().setHeading({ level: 1 }).run() },
+]
+const rows = (block: HandleBlock) => <MenuItem label="Copy link" onClick={() => navigator.clipboard.writeText(`#${block.id}`)} />
+
+const editor = useEditor({ extensions: [StarterKit, BlockId] })
+
+<EditorBlockHandle editor={editor} turnInto={turnInto} actions={rows}>
+  <EditorContent editor={editor} />
+</EditorBlockHandle>
+```
+
+- `turnInto`'s `run` gets the editor with the caret already in the block, and
+  is offered only for a block of text: a paragraph, a heading, code.
+- **Every row leaves the editor focused**, as a drop does: Turn into in the
+  block, Duplicate in the copy, Delete where the block was. An editor that
+  saves when the person leaves it saves these the same way.
+- `duplicateBlock`, `deleteBlock` and `startBlockDrag` are the rows' own
+  actions, for a caller that offers them elsewhere (a shortcut, a test).
+
+<Canvas of={EditorBlockHandleStories.NotEditable} />
+
+## 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 |
+|---|---|---|
+| Moves the block through ProseMirror's own drop, so it arrives with its id and its anchored comments still find it | a drop handler, or a delete and an insert | |
+| Duplicates a block under a fresh id, the original keeping its own (`BlockId` decides) | an id for the copy | |
+| Puts the caret in the block before a Turn into row runs | a selection before your `run` | |

package/src/EditorBlockHandle.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { IconLink, IconMessage } from '@tabler/icons-react'
+import type { HandleBlock } from './BlockHandle'
+import { BlockId } from './BlockNodes'
+import { EditorBlockHandle, blockDropCursor, type BlockTurnInto } from './EditorBlockHandle'
+import { MenuItem } from './Menu'
+import { richTextClassName } from './RichText'
+
+/**
+ * `BlockHandle` in an editor. Drag the handle to move a block; press it for
+ * Turn into, Duplicate, Delete, then the app's rows.
+ */
+const meta = {
+  title: 'Primitives/EditorBlockHandle',
+  // The handle sits 28px left of the content, in the page's margin.
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'heading', attrs: { level: 1, blockId: 'b1' }, content: [{ type: 'text', text: 'A heading' }] },
+    { type: 'paragraph', attrs: { blockId: 'b2' }, content: [{ type: 'text', text: 'The first paragraph. Drag its handle below the list.' }] },
+    { type: 'paragraph', attrs: { blockId: 'b3' }, content: [{ type: 'text', text: 'The second paragraph.' }] },
+    {
+      type: 'bulletList',
+      attrs: { blockId: 'b4' },
+      content: [
+        { type: 'listItem', attrs: { blockId: 'b5' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item one' }] }] },
+        { type: 'listItem', attrs: { blockId: 'b6' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item two' }] }] },
+      ],
+    },
+    { type: 'paragraph', attrs: { blockId: 'b7' }, content: [{ type: 'text', text: 'The last paragraph.' }] },
+  ],
+}
+
+const TURN_INTO: BlockTurnInto[] = [
+  { label: 'Text', run: (editor) => editor.chain().setParagraph().run(), active: (node) => node.type.name === 'paragraph' },
+  { label: 'Heading', run: (editor) => editor.chain().setHeading({ level: 1 }).run(), active: (node) => node.type.name === 'heading' && node.attrs.level === 1 },
+  { label: 'Subheading', run: (editor) => editor.chain().setHeading({ level: 2 }).run(), active: (node) => node.type.name === 'heading' && node.attrs.level === 2 },
+  { label: 'Code', run: (editor) => editor.chain().setCodeBlock().run(), active: (node) => node.type.name === 'codeBlock' },
+]
+
+/** The rows an app adds: here they only say which block they were pressed on. */
+function rows(block: HandleBlock) {
+  return (
+    <>
+      <MenuItem label="Copy link" leading={<IconLink size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('copy link', block.id)} />
+      <MenuItem label="Comment" leading={<IconMessage size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('comment', block.id)} />
+    </>
+  )
+}
+
+function Editing({ editable }: { editable: boolean }) {
+  const editor = useEditor({
+    extensions: [StarterKit.configure({ dropcursor: blockDropCursor }), BlockId],
+    content: DOCUMENT,
+    editable,
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <EditorBlockHandle editor={editor} turnInto={TURN_INTO} actions={rows} className="ml-8 max-w-[560px]">
+      <EditorContent editor={editor} />
+    </EditorBlockHandle>
+  )
+}
+
+/** Drag to move; Turn into, Duplicate and Delete; then the app's rows. */
+export const Default: Story = {
+  render: () => <Editing editable />,
+}
+
+/** An editor that is not editable: no drag, and only the app's rows. */
+export const NotEditable: Story = {
+  render: () => <Editing editable={false} />,
+}

package/src/EditorBlockHandle.tsx

@@ -0,0 +1,181 @@
+import { useMemo, type ReactNode } from 'react'
+import type { Editor } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import type { EditorView } from '@tiptap/pm/view'
+import { IconCopy, IconTrash } from '@tabler/icons-react'
+import { BlockHandle, blockAtY, type BlockHandleEditing, type HandleBlock } from './BlockHandle'
+import { MenuItem, MenuSub } from './Menu'
+
+/** A row of the block menu's Turn into: what the block becomes. */
+export interface BlockTurnInto {
+  label: string
+  /** Turns the block the caret is in. The handle puts the caret there first. */
+  run: (editor: Editor) => void
+  /** Whether the block already is this — drawn as the selected row. */
+  active?: (node: ProseMirrorNode) => boolean
+}
+
+export interface EditorBlockHandleProps {
+  /** The editor. Not editable, or not there yet, and the handle reads: the caller's rows only. */
+  editor: Editor | null
+  /** Turn into's rows. Offered for a block of text — a paragraph, a heading, code. */
+  turnInto?: readonly BlockTurnInto[]
+  /** The caller's own rows, after the editing ones. */
+  actions?: (block: HandleBlock) => ReactNode
+  /** The `EditorContent`. */
+  children: ReactNode
+  className?: string
+}
+
+/** The editor's top-level blocks, where each starts and what it is. */
+function editorBlocks(view: EditorView): HandleBlock[] {
+  const out: HandleBlock[] = []
+  view.state.doc.forEach((node, pos) => {
+    const element = view.nodeDOM(pos)
+    if (element instanceof HTMLElement) out.push({ id: (node.attrs.blockId as string | null) || undefined, element, pos })
+  })
+  return out
+}
+
+/*
+  Duplicate and Delete leave the editor focused, as Turn into and a drop do: the
+  person is still in the field, so an editor that saves when they leave it saves
+  these too — and one that loads someone else's edit while unfocused does not
+  load it over them.
+*/
+
+/** A copy of the block straight after it, the caret in the copy. `BlockId` gives the copy a fresh id; the original keeps its own. */
+export function duplicateBlock(editor: Editor, pos: number): boolean {
+  const node = editor.state.doc.nodeAt(pos)
+  if (!node) return false
+  editor.view.dispatch(editor.state.tr.insert(pos + node.nodeSize, node).scrollIntoView())
+  editor.commands.focus(pos + node.nodeSize + 1)
+  return true
+}
+
+/** Removes the block, the caret where it was. The last block of a document becomes an empty paragraph, since a document holds at least one. */
+export function deleteBlock(editor: Editor, pos: number): boolean {
+  const { state } = editor
+  const node = state.doc.nodeAt(pos)
+  if (!node) return false
+  const tr = state.doc.childCount === 1 ? state.tr.replaceWith(pos, pos + node.nodeSize, state.schema.nodes.paragraph.create()) : state.tr.delete(pos, pos + node.nodeSize)
+  editor.view.dispatch(tr)
+  editor.commands.focus(Math.min(pos + 1, editor.state.doc.content.size))
+  return true
+}
+
+/**
+ * Moves the block at `from` to `to` (a position between top-level blocks), the
+ * caret in it: what a drop in the gutter does, where the editor has no drop of
+ * its own. The node moves whole, attributes and all, so it keeps its id, as
+ * ProseMirror's drop keeps it.
+ */
+export function moveBlock(editor: Editor, from: number, to: number): boolean {
+  const node = editor.state.doc.nodeAt(from)
+  if (!node || (to >= from && to <= from + node.nodeSize)) return false
+  const tr = editor.state.tr.delete(from, from + node.nodeSize)
+  const at = tr.mapping.map(to)
+  editor.view.dispatch(tr.insert(at, node).scrollIntoView())
+  editor.commands.focus(at + 1)
+  return true
+}
+
+/**
+ * Starts the browser's own drag of the block, as ProseMirror starts one of a
+ * selected node: the block selected, its slice on `view.dragging` with `move`,
+ * and its HTML on the transfer. ProseMirror's drop then deletes the selection
+ * and inserts the slice with its attributes — so the block arrives with the
+ * id it left with, and every comment anchored to it still finds it.
+ */
+export function startBlockDrag(editor: Editor, pos: number, event: Pick<globalThis.DragEvent, 'dataTransfer'>, image?: Element) {
+  editor.commands.setNodeSelection(pos)
+  const { view } = editor
+  const slice = view.state.selection.content()
+  const { dom, text } = view.serializeForClipboard(slice)
+  const transfer = event.dataTransfer
+  if (transfer) {
+    transfer.clearData()
+    transfer.setData('text/html', dom.innerHTML)
+    transfer.setData('text/plain', text)
+    transfer.effectAllowed = 'copyMove'
+    if (image) transfer.setDragImage(image, 0, 0)
+  }
+  view.dragging = { slice, move: true }
+}
+
+/**
+ * The drop line a dragged block shows, in the package's accent instead of the
+ * editor's default (the text's colour). Give it to the editor's StarterKit:
+ * `StarterKit.configure({ dropcursor: blockDropCursor })`.
+ */
+export const blockDropCursor = { color: false, class: 'bg-accent-primary' } as const
+
+const NOTHING_YET: BlockHandleEditing = { find: () => null, rows: () => null, startDrag: () => {}, drop: () => {}, endDrag: () => {}, onChange: () => () => {} }
+
+/**
+ * `BlockHandle` in an editor: drag the handle to move the block, and the menu
+ * gains Turn into, Duplicate and Delete before the caller's rows.
+ */
+export function EditorBlockHandle({ editor, turnInto = [], actions, children, className }: EditorBlockHandleProps) {
+  const editing = useMemo<BlockHandleEditing>(() => {
+    // Before the editor exists there is no block to find — not the editor's whole element read as one.
+    if (!editor) return NOTHING_YET
+    // Where the block being dragged starts.
+    let dragged: number | undefined
+    return {
+      find: (y) => blockAtY(editorBlocks(editor.view), y),
+      rows: (block) => {
+        const pos = block.pos
+        // Not editable: the caller's rows only, and no drag.
+        if (!editor.isEditable) return null
+        const node = pos === undefined ? null : editor.state.doc.nodeAt(pos)
+        if (pos === undefined || !node) return null
+        return (
+          <>
+            {node.isTextblock && turnInto.length > 0 && (
+              <MenuSub label="Turn into">
+                {turnInto.map((row) => (
+                  <MenuItem
+                    key={row.label}
+                    label={row.label}
+                    selected={row.active?.(node) ?? false}
+                    onClick={() => {
+                      // Inside the block's text, so the row's command turns this block and no other.
+                      editor.chain().focus().setTextSelection(pos + 1).run()
+                      row.run(editor)
+                    }}
+                  />
+                ))}
+              </MenuSub>
+            )}
+            <MenuItem label="Duplicate" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => duplicateBlock(editor, pos)} />
+            <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => deleteBlock(editor, pos)} />
+          </>
+        )
+      },
+      startDrag: (block, event) => {
+        dragged = block.pos
+        if (block.pos !== undefined) startBlockDrag(editor, block.pos, event, block.element)
+      },
+      drop: (target, after) => {
+        const node = target.pos === undefined ? null : editor.state.doc.nodeAt(target.pos)
+        if (dragged === undefined || target.pos === undefined || !node) return
+        moveBlock(editor, dragged, after ? target.pos + node.nodeSize : target.pos)
+      },
+      // ProseMirror clears `dragging` on its own dragend, which a drag started outside its element never reaches.
+      endDrag: () => setTimeout(() => (editor.view.dragging = null), 50),
+      onChange: (changed) => {
+        editor.on('update', changed)
+        return () => {
+          editor.off('update', changed)
+        }
+      },
+    }
+  }, [editor, turnInto])
+
+  return (
+    <BlockHandle editing={editing} actions={actions} className={className}>
+      {children}
+    </BlockHandle>
+  )
+}

package/src/IconButton.tsx

@@ -1,6 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
 import { cn } from './cn'
+import { MUTED_CONTROL_CLASSES } from './looks'
 import { useFormBusy } from './formBusy'
 import { TooltipTrigger } from './Tooltip'
 
@@ -82,7 +83,7 @@ export function IconButton({
       // 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 === 'muted' || variant === 'resolve') && MUTED_CONTROL_CLASSES,
       !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',

package/src/ListColumn.tsx

@@ -32,6 +32,8 @@ export interface ListColumnProps {
   title: ReactNode
   /** A chevron after the title, as `ContainerHeader` draws it. */
   chevron?: boolean
+  /** The menu the title opens — `ContainerHeader`'s: the column's views. */
+  titleMenu?: ReactNode
   /** The column's own actions, at the header's right — a `Toolbar` of `ToolbarButton`s, or one `IconButton`. */
   actions?: ReactNode
   /** A row between the header and the list that stays put while the list scrolls — a field that adds to the list. */
@@ -44,7 +46,7 @@ export interface ListColumnProps {
   className?: string
 }
 
-function Column({ title, chevron = false, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
+function Column({ title, chevron = false, titleMenu, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
   return (
     <div
       className={cn(
@@ -55,7 +57,7 @@ function Column({ title, chevron = false, actions, above, collapsed = false, chi
       )}
       data-collapsed={collapsed || undefined}
     >
-      <ContainerHeader title={title} chevron={chevron} actions={actions} />
+      <ContainerHeader title={title} chevron={chevron} titleMenu={titleMenu} actions={actions} />
       {above}
       {broken ? (
         // The message takes the room the list had and centres itself in it (Katerina, 19 September).

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.test.tsx

@@ -99,10 +99,10 @@ describe('NavItem unread', () => {
     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('with a count and a menu, the ⋮ lands on the count', () => {

package/src/NavItem.tsx

@@ -108,7 +108,11 @@ 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).
+  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'
 
   const row = (
     <a
@@ -135,7 +139,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 +148,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 +168,15 @@ 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" />
+        <span aria-hidden="true" className="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" />
       ) : null}
     </a>
   )
@@ -181,7 +188,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 +201,13 @@ 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.
+        <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')}>
           <Menu
             align="right"
             trigger={
@@ -225,7 +234,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." />)