@estiva-app/ui 0.50.4 → 0.52.0

package/src/ComposerTriggers.tsx

@@ -0,0 +1,507 @@
+import type { ReactNode } from 'react'
+import { Extension, type Editor } from '@tiptap/core'
+import { PluginKey } from '@tiptap/pm/state'
+import Mention, { type MentionOptions } from '@tiptap/extension-mention'
+import Suggestion from '@tiptap/suggestion'
+import { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from '@tiptap/react'
+import { Avatar } from './Avatar'
+import { EnterHint } from './Menu'
+import { inlineChipClassName } from './InlineChip'
+import type { SuggestionMenuRow } from './SuggestionMenu'
+import { suggestionPopup, type SuggestionPopupOptions } from './suggestionPopup'
+
+/*
+ * The four composer triggers every Estiva app shares — `@`, `!@`, `[` and `/`
+ * (CON-26, Miky 2026-10-02). Peek built them first and they move here unchanged
+ * (CON-27); an app passes in only its own data: its people, the things `[` can
+ * reference, and the `/` rows it can perform beside the shared Format section.
+ *
+ * **What a pick writes is not here.** The text a chip becomes in the body and
+ * the tags it earns are `@estiva-app/conversation`'s (`mentionText`,
+ * `messageReference`, `urgentTagsFor`), so a client without React writes the
+ * same bytes. A chip here carries what that needs: a person's `pubkey`, a
+ * reference's `uri`.
+ */
+
+// ─── @ and !@ ───
+
+/** A person `@` and `!@` offer. */
+export interface MentionPerson {
+  /** The app's own key for the person — the row's key and the chip's `id`. */
+  id: string
+  name: string
+  /** The second line of the row: a role, a team. */
+  description?: string
+  /** Their Nostr key, when they have one — what the body is written with (SPEC §13.1). */
+  pubkey?: string | null
+  /** The face at the row's start. Default: the package `Avatar` for the name. */
+  avatar?: ReactNode
+}
+
+/** How many people the list shows. */
+export const PEOPLE_LIMIT = 6
+
+/** The people whose name holds the query, the first {@link PEOPLE_LIMIT} of them. */
+export function filterPeople(people: readonly MentionPerson[], query: string): MentionPerson[] {
+  const q = query.toLowerCase()
+  return people.filter((person) => q === '' || person.name.toLowerCase().includes(q)).slice(0, PEOPLE_LIMIT)
+}
+
+/**
+ * The people list `@` and `!@` open: the face, the name, the second line, and
+ * the Enter hint while highlighted — `MenuItem` at its tall size.
+ */
+export function peopleMenu(urgent: boolean): SuggestionPopupOptions<MentionPerson> {
+  const section = urgent ? 'Urgent mention' : 'People'
+  return {
+    ariaLabel: section,
+    // The people and the reference lists are the same box: 658px, capped at 360.
+    width: 'w-[658px]',
+    maxHeight: 'max-h-[360px]',
+    sections: (people) => [{ label: section, items: people, className: 'px-3 py-1' }],
+    itemKey: (person) => person.id,
+    row: (person) => ({
+      label: person.name,
+      description: person.description,
+      leading: person.avatar ?? <Avatar size={32} alt={person.name} />,
+      hint: <EnterHint />,
+      size: 'tall',
+    }),
+  }
+}
+
+export interface PersonMentionOptions {
+  /** Everyone the list can offer, asked each time the query changes. */
+  people: () => readonly MentionPerson[]
+}
+
+type Doc = { descendants: (cb: (node: { type: { name: string }; attrs: Record<string, unknown> }) => boolean | void) => void }
+
+function optionsOf<T>(editor: Editor, name: string): T | undefined {
+  return editor.extensionManager.extensions.find((one) => one.name === name)?.options as T | undefined
+}
+
+/** `@`'s list and pick, or `!@`'s, for the node `name` — the extension's own, so a renamed one still finds its people. */
+function personSuggestion(urgent: boolean, name: string) {
+  return {
+    ...(urgent ? { char: '!@' } : {}),
+    items: ({ query, editor }: { query: string; editor: Editor }) => filterPeople(optionsOf<PersonMentionOptions>(editor, name)?.people() ?? [], query),
+    render: suggestionPopup(peopleMenu(urgent)),
+    command: ({ editor, range, props: person }: { editor: Editor; range: { from: number; to: number }; props: MentionPerson }) => {
+      editor
+        .chain()
+        .focus()
+        .insertContentAt(range, [
+          { type: name, attrs: { id: person.id, label: person.name, pubkey: person.pubkey ?? null } },
+          { type: 'text', text: ' ' },
+        ])
+        .run()
+    },
+  }
+}
+
+/*
+  What a chip keeps through HTML — a copy and paste, inside an editor or
+  between two. The chip's own `renderHTML` writes each as a `data-*` attribute
+  and these read them back. Until CON-27 none was written, so a pasted chip
+  came back with every value null and was sent as `@null`. What is read is
+  checked: a crafted `data-pubkey` that is not a key, or a `data-uri` that is
+  not a `nostr:` reference, is dropped rather than written into the body.
+*/
+const HEX_KEY = /^[0-9a-f]{64}$/
+const NOSTR_URI = /^nostr:[a-z0-9]+$/i
+const fromData = (name: string, valid?: RegExp) => ({
+  parseHTML: (element: HTMLElement) => {
+    const value = element.getAttribute(`data-${name}`)
+    return value !== null && (!valid || valid.test(value)) ? value : null
+  },
+  // The node's own `renderHTML` writes it.
+  renderHTML: () => ({}),
+})
+
+const personAttributes = () => ({
+  id: { default: null, ...fromData('id') },
+  label: { default: null, ...fromData('label') },
+  /**
+   * The person's Nostr key, when they have one — SPEC §13.1. `id` is the app's
+   * own and means nothing to another app; this is what the body is written
+   * with, so a mention survives a rename.
+   */
+  pubkey: { default: null, ...fromData('pubkey', HEX_KEY) },
+})
+
+/** The `data-*` a person chip is written with, so a paste reads it back. */
+function personData(attrs: Record<string, unknown>): Record<string, string> {
+  return {
+    'data-id': String(attrs.id ?? ''),
+    'data-label': String(attrs.label ?? ''),
+    ...(typeof attrs.pubkey === 'string' && attrs.pubkey ? { 'data-pubkey': attrs.pubkey } : {}),
+  }
+}
+
+/**
+ * `@` — a person, as a chip that writes their key (SPEC §13.1).
+ *
+ *     PersonMention.configure({ people: () => directory })
+ *
+ * Its `pubkey` and `label` are what `mentionText` takes.
+ */
+export const PersonMention = Mention.extend<MentionOptions<MentionPerson, MentionPerson> & PersonMentionOptions>({
+  name: 'mention',
+  addOptions() {
+    return { ...this.parent!(), HTMLAttributes: {}, people: () => [], suggestion: personSuggestion(false, this.name) }
+  },
+  addAttributes: personAttributes,
+  renderHTML({ node }) {
+    // No node view, so this spec is what the editor draws: the one chip.
+    return ['span', { 'data-mention': 'true', ...personData(node.attrs), class: inlineChipClassName('person', 'cursor-default') }, `@${node.attrs.label}`]
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-mention]' }]
+  },
+})
+
+/**
+ * `!@` — a person, urgently: the same chip in the urgent tone. Its text is an
+ * ordinary mention; the urgency travels as a tag (`urgentTagsFor`), so hand the
+ * write {@link urgentPubkeys}.
+ */
+export const UrgentPersonMention = Mention.extend<MentionOptions<MentionPerson, MentionPerson> & PersonMentionOptions>({
+  name: 'urgentMention',
+  addOptions() {
+    return { ...this.parent!(), HTMLAttributes: {}, people: () => [], suggestion: personSuggestion(true, this.name) }
+  },
+  addAttributes: personAttributes,
+  renderHTML({ node }) {
+    return [
+      'span',
+      { 'data-urgent-mention': 'true', ...personData(node.attrs), class: inlineChipClassName('urgent', 'cursor-default') },
+      `@${node.attrs.label}`,
+    ]
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-urgent-mention]' }]
+  },
+})
+
+/**
+ * The keys the document's urgent mentions name — what the write turns into
+ * `["urgent", <pubkey>]` tags. A chip with no key has no tag to carry; its text
+ * is the old `!@Name`.
+ */
+export function urgentPubkeys(editor: { state: { doc: Doc } }): string[] | undefined {
+  const urgent: string[] = []
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'urgentMention' && typeof node.attrs.pubkey === 'string' && node.attrs.pubkey) urgent.push(node.attrs.pubkey)
+  })
+  return urgent.length > 0 ? urgent : undefined
+}
+
+// ─── [ ───
+
+/** Something `[` offers: a reference drawn as who said it and how it opens. */
+export interface CaptionedItem {
+  /** The referenced thing's id — the row's key and the chip's `id`. */
+  id: string
+  /** Who, as the list shows them. */
+  label: string
+  /** The opening words, marks stripped: the caption the row and the chip wear. */
+  snippet: string
+  /** `nostr:…`, exactly as the body will carry it (`messageReference`). */
+  uri: string
+  /** What the query is matched against beside `label`. Default: `snippet`. */
+  search?: string
+}
+
+/** How many references the list shows. */
+export const REFERENCE_LIMIT = 6
+
+/**
+ * The references whose label or text holds the query — the last
+ * {@link REFERENCE_LIMIT}, in the order given: a thread is unbounded, and a
+ * list that grew with it would be a hundred rows of prose.
+ */
+export function filterReferences(items: readonly CaptionedItem[], query: string): CaptionedItem[] {
+  const q = query.toLowerCase()
+  const shown = q ? items.filter((item) => (item.search ?? item.snippet).toLowerCase().includes(q) || item.label.toLowerCase().includes(q)) : [...items]
+  return shown.slice(-REFERENCE_LIMIT)
+}
+
+const captionOf = (label: string, snippet: string) => (snippet ? `${label}: ${snippet}` : label)
+
+export interface CaptionedReferenceOptions {
+  /** Drawn before the caption: a 14px icon. */
+  icon: ReactNode
+}
+
+/**
+ * A reference mid-sentence, drawn as `label: snippet` and written as its `uri`
+ * verbatim (SPEC §13.1). The caption is the snapshot it was picked with — a
+ * caption, never parsed. Inserted by {@link ReferenceTrigger}, a paste or a
+ * draft; it opens no list of its own.
+ */
+export const CaptionedReference = Mention.extend<MentionOptions & CaptionedReferenceOptions>({
+  name: 'captionedReference',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  addOptions() {
+    return { ...this.parent!(), HTMLAttributes: {}, icon: null, suggestion: { char: '\0', items: () => [] } }
+  },
+  addAttributes() {
+    return {
+      id: { default: null, ...fromData('id') },
+      label: { default: null, ...fromData('label') },
+      snippet: { default: '', parseHTML: (element: HTMLElement) => element.getAttribute('data-snippet') ?? '', renderHTML: () => ({}) },
+      uri: { default: null, ...fromData('uri', NOSTR_URI) },
+    }
+  },
+  renderHTML({ node }) {
+    return [
+      'span',
+      { [`data-${this.name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`]: 'true', 'data-id': String(node.attrs.id ?? ''), 'data-label': String(node.attrs.label ?? ''), 'data-snippet': String(node.attrs.snippet ?? ''), ...(node.attrs.uri ? { 'data-uri': String(node.attrs.uri) } : {}), class: inlineChipClassName('neutral', 'cursor-default') },
+      captionOf(node.attrs.label, node.attrs.snippet),
+    ]
+  },
+  parseHTML() {
+    return [{ tag: `span[data-${this.name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}]` }]
+  },
+  addNodeView() {
+    const icon = this.options.icon
+    return ReactNodeViewRenderer(
+      ({ node }: ReactNodeViewProps) => (
+        <NodeViewWrapper as="span" className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
+          <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{icon}</span>
+          <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
+        </NodeViewWrapper>
+      ),
+      { as: 'span' },
+    )
+  },
+})
+
+export interface ReferenceMenuOptions {
+  /** Names the list, e.g. what can be referenced. */
+  ariaLabel: string
+  /** The section's heading. */
+  sectionLabel: string
+  /** At each row's start: a 16px icon. */
+  icon: ReactNode
+}
+
+/** The list `[` opens: one section of `label: snippet` rows, the same box as the people list. */
+export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
+  return {
+    ariaLabel,
+    width: 'w-[658px]',
+    maxHeight: 'max-h-[360px]',
+    sections: (items) => [{ label: sectionLabel, items, className: 'px-2' }],
+    itemKey: (item) => `reference-${item.id}`,
+    row: (item) => ({ leading: icon, label: captionOf(item.label, item.snippet), hint: <EnterHint /> }),
+  }
+}
+
+export interface ReferenceTriggerOptions extends ReferenceMenuOptions {
+  /** Everything `[` can offer, asked each time the query changes. */
+  items: () => readonly CaptionedItem[]
+  /** The node a pick inserts. Default `captionedReference`. */
+  nodeName: string
+}
+
+/**
+ * `[` — reference something, inserted as a {@link CaptionedReference} chip.
+ *
+ * Its own extension rather than the chip's suggestion, so the chip's text (its
+ * `renderText`) does not change with the key that summons the list.
+ */
+export const ReferenceTrigger = Extension.create<ReferenceTriggerOptions>({
+  name: 'referenceTrigger',
+  addOptions() {
+    return { items: () => [], nodeName: 'captionedReference', ariaLabel: 'References', sectionLabel: 'References', icon: null }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    return [
+      Suggestion<CaptionedItem>({
+        editor: this.editor,
+        char: '[',
+        pluginKey: new PluginKey('referenceTrigger'),
+        // As a mention's: only where the chip may go.
+        allow: ({ state, range }) => {
+          const type = state.schema.nodes[options.nodeName]
+          return !!type && !!state.doc.resolve(range.from).parent.type.contentMatch.matchType(type)
+        },
+        items: ({ query }) => filterReferences(options.items(), query),
+        render: suggestionPopup(referenceMenu(options)),
+        command: ({ editor, range, props: item }) => {
+          editor
+            .chain()
+            .focus()
+            .insertContentAt(range, [
+              { type: options.nodeName, attrs: { id: item.id, label: item.label, snippet: item.snippet, uri: item.uri } },
+              { type: 'text', text: ' ' },
+            ])
+            .run()
+        },
+      }),
+    ]
+  },
+})
+
+// ─── / ───
+
+/** A row of the `/` list, and what choosing it does. */
+export interface SlashCommand {
+  key: string
+  row: SuggestionMenuRow
+  /** Matched beside the row's label: an id, a trigger, a description. */
+  keywords?: readonly string[]
+  /** Runs once the `/query` that summoned the list has been removed. */
+  run: (editor: Editor) => void
+}
+
+export interface SlashSection {
+  label: string
+  commands: readonly SlashCommand[]
+}
+
+export type FormatId = 'paragraph' | 'heading' | 'subheading' | 'quote' | 'bulletList' | 'orderedList' | 'code'
+
+export interface FormatDef {
+  id: FormatId
+  label: string
+  /** What you type to get it — the input rule the extension registers. Blank when there is none. */
+  trigger?: string
+}
+
+/**
+ * The formats `/` offers, in order. The hint is what you would type, not a key
+ * chord. Bold, italic and underline are absent: they act on text already
+ * written, so they are the selection toolbar's.
+ */
+export const FORMATS: readonly FormatDef[] = [
+  { id: 'paragraph', label: 'Text' },
+  { id: 'heading', label: 'Heading', trigger: '#' },
+  { id: 'subheading', label: 'Subheading', trigger: '##' },
+  { id: 'quote', label: 'Quote', trigger: '>' },
+  { id: 'code', label: 'Code', trigger: '`' },
+  { id: 'bulletList', label: 'Bulleted list', trigger: '-' },
+  { id: 'orderedList', label: 'Numbered list', trigger: '1.' },
+]
+
+/** Code as a mark inside the line, or as a block of its own. */
+export type CodeFormat = 'inline' | 'block'
+
+/**
+ * Apply one format to the current block. `set*` wherever Tiptap has one:
+ * choosing Heading should make a heading, not turn one off. `false` means
+ * nothing changed, not that anything failed.
+ */
+export function applyFormat(editor: Editor, id: FormatId, code: CodeFormat = 'inline'): boolean {
+  const chain = editor.chain().focus()
+  /*
+    The node's own command, called by name: StarterKit's extensions declare
+    them, and this package builds without StarterKit. Its own command, rather
+    than the core one it wraps, because a list's runs with the app's options
+    (`keepMarks`, `itemTypeName`). An editor without that node changes nothing.
+  */
+  const run = (command: string, ...args: unknown[]): boolean => {
+    const named = (chain as unknown as Record<string, ((...a: unknown[]) => { run: () => boolean }) | undefined>)[command]
+    return named ? named(...args).run() : false
+  }
+  switch (id) {
+    case 'paragraph':
+      return run('setParagraph')
+    case 'heading':
+      return run('setHeading', { level: 1 })
+    case 'subheading':
+      return run('setHeading', { level: 2 })
+    case 'quote':
+      return run('toggleBlockquote')
+    case 'bulletList':
+      return run('toggleBulletList')
+    case 'orderedList':
+      return run('toggleOrderedList')
+    case 'code':
+      return run(code === 'block' ? 'toggleCodeBlock' : 'toggleCode')
+    default:
+      return false
+  }
+}
+
+/** The Format section every app's `/` opens with. */
+export function formatSection(code: CodeFormat = 'inline'): SlashSection {
+  return {
+    label: 'Format',
+    commands: FORMATS.map((format) => ({
+      key: `format-${format.id}`,
+      row: { label: format.label, shortcut: format.trigger },
+      keywords: [format.id],
+      run: (editor) => {
+        applyFormat(editor, format.id, code)
+      },
+    })),
+  }
+}
+
+/** A row that types another trigger, so its own list opens — `@` from `/`. */
+export function typeTrigger(input: string): SlashCommand['run'] {
+  // Deferred a frame: the delete of the `/query` has to land first, or the
+  // trigger's plugin sees the character arrive inside a range still being removed.
+  return (editor) => {
+    requestAnimationFrame(() => editor.commands.insertContent(input))
+  }
+}
+
+function matches(command: SlashCommand, q: string): boolean {
+  return [command.row.label, ...(command.keywords ?? [])].some((text) => text.toLowerCase().includes(q))
+}
+
+/** The sections narrowed to a query — the text typed after the `/`. Empty sections stay. */
+export function filterSlashSections(sections: readonly SlashSection[], query: string): SlashSection[] {
+  const q = query.toLowerCase()
+  return sections.map((section) => ({ ...section, commands: q ? section.commands.filter((command) => matches(command, q)) : section.commands }))
+}
+
+export interface SlashCommandsOptions {
+  /** The sections, in order: {@link formatSection} first, then the app's own. */
+  sections: readonly SlashSection[]
+}
+
+type SlashRow = SlashCommand & { section: number }
+
+/**
+ * `/` — format the line or insert something, at the caret, mid-sentence too.
+ * A `/` inside a word (`and/or`, a path) opens nothing: the plugin wants a
+ * space or the line's start before it.
+ */
+export const SlashCommands = Extension.create<SlashCommandsOptions>({
+  name: 'slashCommands',
+  addOptions() {
+    return { sections: [formatSection()] }
+  },
+  addProseMirrorPlugins() {
+    const sections = this.options.sections
+    return [
+      Suggestion<SlashRow>({
+        editor: this.editor,
+        char: '/',
+        startOfLine: false,
+        pluginKey: new PluginKey('slashCommands'),
+        items: ({ query }) => filterSlashSections(sections, query).flatMap((section, at) => section.commands.map((command) => ({ ...command, section: at }))),
+        command: ({ editor, range, props }) => {
+          editor.chain().focus().deleteRange(range).run()
+          props.run(editor)
+        },
+        render: suggestionPopup<SlashRow>({
+          ariaLabel: 'Commands',
+          width: 'w-[300px]',
+          maxHeight: 'max-h-[400px]',
+          sections: (rows) => sections.map((section, at) => ({ label: section.label, items: rows.filter((row) => row.section === at) })),
+          itemKey: (row) => row.key,
+          row: (row) => row.row,
+        }),
+      }),
+    ]
+  },
+})

package/src/NavItem.mdx

@@ -28,6 +28,19 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithMenu} />
 
+- A row with rows under it takes them as `children`: more `NavItem`s. The
+  row stays a link; while it is pointed at or focused, its icon becomes the
+  arrow that folds them, in the icon's own place, and they slide shut. For a
+  whole tree from one list, use **NavTree**.
+
+<Canvas of={NavItemStories.WithRowsUnder} />
+
+- A word that helps only while the row is pointed at — where the item comes
+  from — is `hint`: pass a neutral **Chip**. It shows left of the count, and
+  the label ends with "…" before it instead of running under it.
+
+<Canvas of={NavItemStories.WithHintLongLabel} />
+
 ## When not
 
 - An icon rail's tile → **RailItem**.
@@ -55,6 +68,11 @@ import { NavItem } from '@estiva-app/ui'
 - The label truncates; the count never gives up its width.
 - `menu` is the items only: `menu={<MenuItem label="Move to Folder…" onClick={move} />}`.
   The ⋮'s name is `More options for {label}` unless `menuLabel` says otherwise.
+- `children` start open; `defaultOpen={false}` starts them folded, and
+  `open` with `onOpenChange` hands the state to the app. The arrow's name is
+  `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.
 
 - A row is 32px tall, 8px in on each side, 8px between the icon and the label,
   the label 14px regular, 6px corners.
@@ -68,6 +86,18 @@ It does these by itself. Write none of them around it.
 | Marks the current place for assistive technology when `active` | `aria-current` |  |
 | Keeps its 32px in a scrolling column | `shrink-0` |  |
 | Shows a ⋮ over the count while pointed at, focused or open, and keeps the row's hover look under it | a positioned `IconButton` + `Menu` over the row, `group-hover` reveals |  |
+| 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 |  |
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Tab | the link, then its arrow (with `children`), then its ⋮ (with `menu`) |
+| Enter, Space | on the arrow: folds or unfolds the rows under it |
+
+The rows are not an ARIA tree: there are no arrow keys between rows yet.
 
 ## Props
 

package/src/NavItem.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSquareRounded } from '@tabler/icons-react'
+import { Chip } from './Chip'
 import { MenuItem } from './Menu'
 import { NavItem } from './NavItem'
 
@@ -60,3 +61,36 @@ export const WithMenuActive: Story = {
 export const WithMenuNoCount: Story = {
   args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, menu: MENU },
 }
+
+/** A hint shows only while the row is pointed at or focused, left of the count: here a neutral Chip. */
+export const WithHint: Story = {
+  args: { icon: placeholder, count: 3, countLabel: '3 open', hint: <Chip type="neutral" label="Label" /> },
+}
+
+/** A long label gives way to the hint while it shows: it ends with "…" before the chip instead of running under it. */
+export const WithHintLongLabel: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, count: 12, countLabel: '12 open', hint: <Chip type="neutral" label="Label" /> },
+}
+
+/** Rows under a row: point at it and its icon becomes the arrow that folds them. The row itself stays a link. */
+export const WithRowsUnder: Story = {
+  args: { icon: placeholder },
+  render: (args) => (
+    <NavItem {...args}>
+      <NavItem href="#" label="Item two" icon={placeholder} />
+      <NavItem href="#" label="Item three" icon={placeholder}>
+        <NavItem href="#" label="Item four" icon={placeholder} />
+      </NavItem>
+    </NavItem>
+  ),
+}
+
+/** Starts folded: point at it, or Tab to its arrow, to open it. */
+export const WithRowsUnderClosed: Story = {
+  args: { icon: placeholder, defaultOpen: false },
+  render: (args) => (
+    <NavItem {...args}>
+      <NavItem href="#" label="Item two" icon={placeholder} />
+    </NavItem>
+  ),
+}

package/src/NavItem.test.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+/**
+ * What the page claims for the rows under a row and the hint: the arrow folds
+ * the rows and says so, the rows are hidden rather than gone, the row itself
+ * stays a link a click does not fold, and the hint is there to be revealed.
+ * The reveal on hover and the slide are Chrome's to show.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { NavItem } from './NavItem'
+
+afterEach(cleanup)
+
+const arrow = (name: RegExp) => screen.getByRole('button', { name })
+
+describe('NavItem with rows under it', () => {
+  const tree = (props: Partial<Parameters<typeof NavItem>[0]> = {}) => (
+    <NavItem href="#one" label="Item one" {...props}>
+      <NavItem href="#two" label="Item two" />
+    </NavItem>
+  )
+
+  it('starts open: the arrow says so and names what it folds, and the rows are there', () => {
+    render(tree())
+    const button = arrow(/Hide what is under Item one/)
+    expect(button.getAttribute('aria-expanded')).toBe('true')
+    expect(document.getElementById(button.getAttribute('aria-controls') ?? '')).not.toBeNull()
+    expect(screen.getByText('Item two').closest('[hidden]')).toBeNull()
+  })
+
+  it('the arrow folds the rows, hidden rather than gone, and unfolds them', async () => {
+    render(tree())
+    await userEvent.click(arrow(/Hide what is under Item one/))
+    expect(arrow(/Show what is under Item one/).getAttribute('aria-expanded')).toBe('false')
+    expect(screen.getByText('Item two').closest('[hidden]')).not.toBeNull()
+    await userEvent.click(arrow(/Show what is under Item one/))
+    expect(screen.getByText('Item two').closest('[hidden]')).toBeNull()
+  })
+
+  it('a click on the row is the link’s, and does not fold it', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(tree({ onClick }))
+    await userEvent.click(screen.getByRole('link', { name: 'Item one' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(arrow(/Hide what is under Item one/).getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('starts folded with defaultOpen false, and reports a change through onOpenChange', async () => {
+    const onOpenChange = vi.fn()
+    render(tree({ defaultOpen: false, onOpenChange }))
+    expect(screen.getByText('Item two').closest('[hidden]')).not.toBeNull()
+    await userEvent.click(arrow(/Show what is under Item one/))
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+  })
+
+  it('Enter on the arrow folds the rows', async () => {
+    render(tree())
+    arrow(/Hide what is under Item one/).focus()
+    await userEvent.keyboard('{Enter}')
+    expect(arrow(/Show what is under Item one/).getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('a row with a menu and rows under it: the open rows do not hold the ⋮ open', () => {
+    render(tree({ menu: <span>Action</span> }))
+    const menu = screen.getByRole('button', { name: 'More options for Item one' }).closest('[data-nav-menu]')
+    expect(menu).not.toBeNull()
+    expect(menu?.querySelector('[aria-expanded=true]')).toBeNull()
+  })
+})
+
+describe('NavItem with a hint', () => {
+  it('draws the hint inside the row, beside the label', () => {
+    render(<NavItem href="#" label="Item one" hint={<span>Label</span>} />)
+    expect(screen.getByRole('link', { name: /Item one/ }).textContent).toContain('Label')
+  })
+
+  it('without children, a menu or a hint, the row is the bare link', () => {
+    const { container } = render(<NavItem href="#" label="Item one" />)
+    expect(container.firstElementChild?.tagName).toBe('A')
+  })
+})