@estiva-app/ui 0.53.1 → 0.55.0

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/NavItem.mdx

@@ -41,6 +41,13 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithHintLongLabel} />
 
+- Something new on the row is `unread`: its words and icon brighten, the
+  label is set in medium, and the **UnreadDot** sits at the right.
+  `urgent` with it draws the warning badge in the dot's place. Say "unread"
+  in the row's own accessible name too: a dot reads as nothing.
+
+<Canvas of={NavItemStories.Unread} />
+
 ## When not
 
 - An icon rail's tile → **RailItem**.
@@ -73,9 +80,14 @@ import { NavItem } from '@estiva-app/ui'
   `Hide what is under {label}` or `Show what is under {label}`.
 - `hint` takes room only while it shows, so a label at rest keeps its full
   width.
+- The ⋮ lands on what is at the right: the count, or the dot. With nothing
+  there it keeps no room at rest, so the label has the row's whole width,
+  and takes its 24px slot only while it shows.
+- `active` is `bg-nav-active`, the current row in a sidebar, which each theme
+  sets for itself.
 
 - A row is 32px tall, 8px in on each side, 8px between the icon and the label,
-  the label 14px regular, 6px corners.
+  the label 14px regular (medium when unread), 8px corners as a **MenuItem**'s.
 
 ## What it owns
 
@@ -89,6 +101,7 @@ It does these by itself. Write none of them around it.
 | Turns its icon into the arrow that folds `children` while pointed at or focused, and slides them | a positioned `IconButton` over the icon, open state, `group-hover` reveals, an indented box |  |
 | Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` |  |
 | Shows `hint` only while pointed at or focused, and makes the label give way | a positioned chip over the row, `group-hover` reveals |  |
+| Draws the dot or the badge for `unread` and `urgent`, and brightens the row | an **UnreadDot** placed by hand, a weight or colour passed in |  |
 
 ## Keys
 

package/src/NavItem.stories.tsx

@@ -94,3 +94,18 @@ export const WithRowsUnderClosed: Story = {
     </NavItem>
   ),
 }
+
+/** Something new: the words brighten, the label is medium, and the dot sits at the right. */
+export const Unread: Story = {
+  args: { icon: placeholder, unread: true },
+}
+
+/** Urgent and unread: the warning badge in the dot's place. */
+export const UnreadUrgent: Story = {
+  args: { icon: placeholder, unread: true, urgent: true },
+}
+
+/** Unread, with a menu: point at it and the ⋮ lands on the dot. */
+export const UnreadWithMenu: Story = {
+  args: { icon: placeholder, unread: true, menu: MENU },
+}

package/src/NavItem.test.tsx

@@ -80,3 +80,34 @@ describe('NavItem with a hint', () => {
     expect(container.firstElementChild?.tagName).toBe('A')
   })
 })
+
+describe('NavItem unread', () => {
+  it('draws the dot, and sets the label in medium', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread />)
+    expect(container.querySelector('[data-unread]')).not.toBeNull()
+    expect(screen.getByText('Item one').className).toContain('font-medium')
+  })
+
+  it('urgent draws the badge in the dot’s place', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread urgent />)
+    expect(container.querySelector('[data-urgent]')).not.toBeNull()
+    expect(container.querySelector('[data-unread]')).toBeNull()
+  })
+
+  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', () => {
+    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')
+  })
+
+  it('with a count and a menu, the ⋮ lands on the count', () => {
+    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).toContain('right-1')
+  })
+})

package/src/NavItem.tsx

@@ -1,10 +1,11 @@
 import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from 'react'
 import { Collapsible } from '@base-ui/react/collapsible'
-import { IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
+import { IconAlertSquareRounded, IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
 import { cn } from './cn'
 import { COLLAPSIBLE_PANEL_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
+import { UnreadDot } from './UnreadDot'
 import { WithTooltip } from './Tooltip'
 
 /**
@@ -34,6 +35,15 @@ import { WithTooltip } from './Tooltip'
  * `hint` is shown only while the row is pointed at or focused, left of the
  * count — a neutral `Chip`, typically. It takes its own room while it shows,
  * so the label ends with "…" before it instead of running under it.
+ *
+ * `unread` brightens the row's words and icon, sets the label in medium, and
+ * draws the `UnreadDot` at the right; `urgent` with it draws the warning badge
+ * in the dot's place (Katerina, 2 October: Peek's row, moved in). The ⋮ lands
+ * on whatever is in that place, and with nothing there it takes no room until
+ * the row is pointed at, so a label at rest keeps the row's whole width.
+ *
+ * Active is `bg-nav-active`, the current row in a sidebar, which each theme
+ * sets: the selected tab's neutral fill in most, Signal's blue in Signal.
  */
 export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'children'> {
   label: string
@@ -51,6 +61,10 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
   menuLabel?: string
   /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
   hint?: ReactNode
+  /** Something new here: brighter words, the label in medium, and the `UnreadDot` at the right. Say so in the row's own words for assistive tech too. */
+  unread?: boolean
+  /** With `unread`: the warning badge in the dot's place. */
+  urgent?: boolean
   /** Rows under this one, folding under it: `NavItem`s. While the row is pointed at or focused, its icon becomes the arrow. */
   children?: ReactNode
   /** With `children`: open unless told otherwise. */
@@ -71,6 +85,8 @@ export function NavItem({
   menu,
   menuLabel,
   hint,
+  unread = false,
+  urgent = false,
   children,
   defaultOpen = true,
   open: openProp,
@@ -89,6 +105,10 @@ export function NavItem({
   // The row draws beside it — the ⋮, the arrow — so the pointer can leave the
   // link for them while the row still reads as the one it is on.
   const besides = menu != null || hasRows
+  // 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'
 
   const row = (
     <a
@@ -100,7 +120,7 @@ export function NavItem({
         // shrink-0 family; Katerina, 2026-09-02).
         'flex h-8 min-w-0 shrink-0 items-center gap-2 px-2 text-body-2',
         SIDEBAR_ROW_CLASSES,
-        active ? 'bg-bg-active text-text-primary' : cn(SIDEBAR_ROW_TEXT_CLASSES, 'hover:bg-bg-hover'),
+        active ? 'bg-bg-nav-active text-text-primary' : cn(unread ? 'text-text-primary' : SIDEBAR_ROW_TEXT_CLASSES, 'hover:bg-bg-hover'),
         // With a menu the ⋮ sits beside the link, so the row keeps its hover
         // look while the ⋮ is pointed at and while its menu is open. The same
         // for the arrow.
@@ -121,7 +141,7 @@ export function NavItem({
           {icon}
         </span>
       )}
-      <span className="flex-1 truncate">{label}</span>
+      <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>
@@ -135,17 +155,21 @@ export function NavItem({
           <span
             className={cn(
               'min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted',
-              // With a menu, the ⋮ takes this place while it shows.
-              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',
+              // With a menu and no mark after it, the ⋮ takes this place while it shows.
+              !mark && stepsAside,
             )}
           >
             {count}
           </span>
         </WithTooltip>
-      ) : menu != null ? (
-        // No count, but a menu: the count's place is kept free, so a long
-        // label truncates before the ⋮ instead of running under it.
-        <span aria-hidden="true" className="min-w-4 shrink-0" />
+      ) : null}
+      {mark ? (
+        <span className={cn('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" />
       ) : null}
     </a>
   )
@@ -170,9 +194,11 @@ export function NavItem({
         </div>
       )}
       {menu != null && (
-        // `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.
-        <div data-nav-menu className="absolute inset-y-0 right-1 flex items-center opacity-0 transition-opacity focus-within:opacity-100 group-hover/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100">
+        // 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')}>
           <Menu
             align="right"
             trigger={
@@ -204,3 +230,14 @@ export function NavItem({
     </Collapsible.Root>
   )
 }
+
+/** Urgent and unread: a 12px warning mark on its tint, in the dot's 24px slot. */
+function UrgentMark() {
+  return (
+    <div className="flex h-6 w-6 shrink-0 items-center justify-center" data-urgent>
+      <div className="flex items-center rounded-full bg-warning-muted p-0.5 signal:shadow-glow-warning">
+        <IconAlertSquareRounded size={12} stroke={2.5} className="text-warning-default" />
+      </div>
+    </div>
+  )
+}

package/src/NavTree.mdx

@@ -27,6 +27,30 @@ rows to any depth.
 
 <Canvas of={NavTreeStories.Loading} />
 
+- `titleActions` sit beside the label, always shown ("New"); a group's
+  `actions` beside its title on hover ("Open"), its `trailing` always (an
+  **UnreadDot**). A row's `unread` and `urgent` are **NavItem**'s.
+
+<Canvas of={NavTreeStories.WithActionsAndUnread} />
+
+- 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
+  skeleton under it once open, and `onOpenChange` says when to read them;
+  `childrenMessage` is the line under it. `onIntent` on a group says the
+  pointer rests on it or the keyboard reached it: read it then, so opening
+  it draws rows.
+
+<Canvas of={NavTreeStories.ReadAsItOpens} />
+
+- An app whose groups and rows each read their own data draws the groups
+  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`.
+
+<Canvas of={NavTreeStories.AppDrawnGroups} />
+
 ## When not
 
 - A flat list of places → **NavItem** rows in the **Sidebar**.
@@ -68,6 +92,7 @@ It does these by itself. Write none of them around it.
 | Draws every level from one list, rows under rows | a recursive render of **NavItem**s and **CollapsibleSection**s |  |
 | Opens the group that holds the current row | a search through the list for the current row |  |
 | Says it is loading, or empty, in the rows' place | a skeleton or an **EmptyState** placed by hand |  |
+| Says when the pointer rests on a group, 150ms, and not while it sweeps past | a timer on pointer enter and leave |  |
 
 ## Keys
 

package/src/NavTree.stories.tsx

@@ -1,9 +1,11 @@
 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 { Chip } from './Chip'
+import { UnreadDot } from './UnreadDot'
 import { NavItem } from './NavItem'
-import { NavTree, type NavTreeGroup } from './NavTree'
+import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
 import { Sidebar } from './Sidebar'
 
 const placeholder = <IconSquareRounded size={16} stroke={1.5} />
@@ -82,3 +84,57 @@ export const Empty: Story = { args: { groups: [] } }
 
 /** Close a group and reload the page: still closed. This browser remembers each group, under the key. */
 export const Remembered: Story = { args: { storageKey: 'estiva-ui.stories.nav-tree' } }
+
+/** Actions beside the label and on each group, a group's dot, and unread rows — one urgent. */
+export const WithActionsAndUnread: Story = {
+  args: {
+    titleActions: [{ icon: <IconPlus size={16} stroke={1.5} />, tooltip: 'New', onClick: () => {} }],
+    groups: [
+      { id: 'u1', title: 'Group one', trailing: <UnreadDot />, actions: [{ icon: <IconArrowUpRight size={16} stroke={1.5} />, tooltip: 'Open', onClick: () => {} }], defaultOpen: true, nodes: [
+        { id: 'u1a', label: 'Item two', href: '#', icon: placeholder, unread: true },
+        { id: 'u1b', label: 'Item three', href: '#', icon: placeholder, unread: true, urgent: true },
+        { id: 'u1c', label: 'Item four', href: '#', icon: placeholder },
+      ] },
+      { id: 'u2', title: 'Group two', actions: [{ icon: <IconArrowUpRight size={16} stroke={1.5} />, tooltip: 'Open', onClick: () => {} }], nodes: [{ id: 'u2a', label: 'Item five', href: '#', icon: placeholder }] },
+    ],
+    selected: 'u1c',
+  },
+}
+
+/** 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: {
+    groups: [
+      { id: 'l1', title: 'Being read', defaultOpen: true, nodes: null },
+      { id: 'l2', title: 'Empty', defaultOpen: true, nodes: [], message: 'Nothing in this yet.' },
+      { id: 'l3', title: 'Rows read on open', defaultOpen: true, nodes: [
+        { id: 'l3a', label: 'Item with rows not read yet', href: '#', icon: placeholder, hasChildren: true, defaultOpen: false },
+        { id: 'l3b', label: 'Item whose rows failed', href: '#', icon: placeholder, hasChildren: true, childrenMessage: 'This could not be read.' },
+      ] },
+    ],
+    selected: undefined,
+  },
+}
+
+/** Groups the app draws itself, as `NavTree`'s children: each a `NavTreeSection` with `NavItem` rows — for groups and rows that each read their own data. */
+export const AppDrawnGroups: Story = {
+  args: { groups: undefined },
+  render: function Render(args) {
+    return (
+      <div className="flex h-screen bg-bg-base">
+        <Sidebar>
+          <NavTree title={args.title}>
+            <NavTreeSection title="Group one" trailing={<UnreadDot />}>
+              <NavItem href="#" label="Item one" icon={placeholder} unread />
+              <NavItem href="#" label="Item two" icon={placeholder} active>
+                <NavItem href="#" label="Item three" icon={placeholder} />
+              </NavItem>
+            </NavTreeSection>
+            <NavTreeSection title="Group two" loading />
+            <NavTreeSection title="Group three" message="Nothing in this yet." />
+          </NavTree>
+        </Sidebar>
+      </div>
+    )
+  },
+}

package/src/NavTree.test.tsx

@@ -7,7 +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 { NavTree, type NavTreeGroup } from './NavTree'
+import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
 
 afterEach(cleanup)
 
@@ -52,3 +52,80 @@ describe('NavTree', () => {
     expect(screen.queryAllByRole('link')).toHaveLength(0)
   })
 })
+
+describe('NavTree read as it opens', () => {
+  it('a group being read draws no rows; a group’s message is said in their place', () => {
+    render(
+      <NavTree
+        groups={[
+          { id: 'a', title: 'Group a', defaultOpen: true, nodes: null },
+          { id: 'b', title: 'Group b', defaultOpen: true, nodes: [], message: 'Nothing in this yet.' },
+        ]}
+        emptyMessage="Nothing here yet."
+      />,
+    )
+    expect(screen.queryAllByRole('link')).toHaveLength(0)
+    expect(screen.getByText('Nothing in this yet.')).not.toBeNull()
+  })
+
+  it('a row with hasChildren has its arrow, and says when it opens', async () => {
+    const onOpenChange = vi.fn()
+    render(
+      <NavTree
+        groups={[{ id: 'a', title: 'Group a', defaultOpen: true, nodes: [{ id: 'x', label: 'Item x', href: '#x', hasChildren: true, defaultOpen: false, onOpenChange }] }]}
+        emptyMessage="Nothing here yet."
+      />,
+    )
+    await userEvent.click(screen.getByRole('button', { name: /Show what is under Item x/ }))
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+  })
+
+  it('the label’s and a group’s actions are drawn', () => {
+    render(
+      <NavTree
+        title="Groups"
+        titleActions={[{ icon: <span />, tooltip: 'New', onClick: () => {} }]}
+        groups={[{ id: 'a', title: 'Group a', nodes: [], actions: [{ icon: <span />, tooltip: 'Open', onClick: () => {} }] }]}
+        emptyMessage="Nothing here yet."
+      />,
+    )
+    expect(screen.getByRole('button', { name: 'New' })).not.toBeNull()
+    expect(screen.getByRole('button', { name: 'Open' })).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." />)
+    screen.getByRole('button', { name: 'Group a' }).focus()
+    expect(onIntent).toHaveBeenCalled()
+  })
+})
+
+describe('NavTree drawn by the app', () => {
+  it('draws NavTreeSections given as children, each with its rows, line or skeleton', () => {
+    render(
+      <NavTree title="Groups">
+        <NavTreeSection title="Group a"><a href="#a">Item a</a></NavTreeSection>
+        <NavTreeSection title="Group b" message="Nothing in this yet." />
+        <NavTreeSection title="Group c" loading />
+      </NavTree>,
+    )
+    expect(screen.getByRole('button', { name: 'Group a' })).not.toBeNull()
+    expect(screen.getByText('Item a')).not.toBeNull()
+    expect(screen.getByText('Nothing in this yet.')).not.toBeNull()
+  })
+})
+
+describe('NavTree marks its groups', () => {
+  it('each group box carries data-nav-group with its id', () => {
+    const { container } = render(<NavTree groups={[{ id: 'g1', title: 'Group a', nodes: [] }]} emptyMessage="Nothing here yet." />)
+    expect(container.querySelector('[data-nav-group="g1"]')).not.toBeNull()
+  })
+})
+
+describe('NavTree with no groups and no words', () => {
+  it('draws no line at all', () => {
+    const { container } = render(<NavTree groups={[]} />)
+    expect(container.textContent).toBe('')
+  })
+})