@vespercms/admin 0.0.0-stage → 0.1.0-next.1

package/src/body/document.ts

@@ -0,0 +1,388 @@
+import type { JSONContent } from '@tiptap/core';
+import type { MarkdownManager } from '@tiptap/markdown';
+import {
+  editTable,
+  parseBody,
+  type BodyBlock,
+  type BodyFormat,
+  type BodyItem,
+  type MarkdocParseOptions,
+  type ParsedBody,
+  type TableEdit,
+  type TableValue,
+} from '@vespercms/core';
+import type { Catalog } from './catalog.ts';
+import { hasPlaceholderCharacters, restoreChips, withPlaceholders } from './chips.ts';
+import { WRITABLE_NODES, type ContainerTypes } from './nodes.ts';
+import { cellFits, editorValue, savedValue } from './table.ts';
+
+/*
+ * The body as editor nodes, and back (DECISIONS.md: "The body editor splices
+ * changed blocks into the original text"). Each block becomes one node
+ * tagged with its path: Markdown the writing view can show faithfully, a
+ * tag or component the site declares (a container with editable children,
+ * or a card), or a protected source block. On save, a node whose content
+ * didn't change copies its original bytes, a container re-writes its
+ * opening only if its attributes changed, and only changed or new blocks
+ * are written by the Markdown serializer.
+ */
+
+export type BodyContext = {
+  format: BodyFormat;
+  markdown: MarkdownManager;
+  catalog: Catalog;
+  containers: ContainerTypes;
+  markdoc?: MarkdocParseOptions;
+};
+
+export type BodyDocument = {
+  /** The text the document was built from, and its blocks. */
+  parsed: ParsedBody;
+  doc: JSONContent;
+};
+
+/** Builds the editor document for a body. */
+export function buildDocument(body: string, context: BodyContext): BodyDocument {
+  const parsed = parseBody(
+    body,
+    context.format,
+    context.markdoc ? { markdoc: context.markdoc } : {},
+  );
+  const content = nodesOf(parsed.text, parsed.blocks, null, '', context, null);
+  return {
+    parsed,
+    doc: { type: 'doc', content: content.length > 0 ? content : [{ type: 'paragraph' }] },
+  };
+}
+
+const pathOf = (parent: string | null, index: number) =>
+  parent === null ? String(index) : `${parent}.${String(index)}`;
+
+function nodesOf(
+  text: string,
+  blocks: readonly BodyBlock[],
+  parent: string | null,
+  indent: string,
+  context: BodyContext,
+  allows: ((type: string) => boolean) | null,
+): JSONContent[] {
+  return blocks.map((block, index) => {
+    const path = pathOf(parent, index);
+    const node = nodeOf(text, block, path, indent, context);
+    return allows && !allows(node.type ?? '') ? sourceNode(text, block, path) : node;
+  });
+}
+
+function sourceNode(text: string, block: BodyBlock, path: string): JSONContent {
+  return {
+    type: 'sourceBlock',
+    attrs: { vesperBlock: path, text: text.slice(block.start, block.end), blockType: block.type },
+  };
+}
+
+function nodeOf(
+  text: string,
+  block: BodyBlock,
+  path: string,
+  indent: string,
+  context: BodyContext,
+): JSONContent {
+  const raw = text.slice(block.start, block.end);
+  if (block.kind === 'markdown' && !hasPlaceholderCharacters(raw)) {
+    const chips = (block.chips ?? []).map((c) => ({
+      start: c.start - block.start,
+      end: c.end - block.start,
+    }));
+    const source = dedent(withPlaceholders(raw, chips), indent);
+    const node = source === null ? null : writableNode(context.markdown, source);
+    if (node) return { ...node, attrs: { ...node.attrs, vesperBlock: path } };
+    return sourceNode(text, block, path);
+  }
+  if (block.kind === 'table' && block.table) {
+    const value = editorValue(text, block.table);
+    // Every cell must be one the writing view writes back, or the whole table is kept as written.
+    const fits = value.rows.every((row) =>
+      row.cells.every(
+        (cell) => !hasPlaceholderCharacters(restoreChips(cell)) && cellFits(context.markdown, cell),
+      ),
+    );
+    if (fits) return { type: 'vesperTable', attrs: { vesperBlock: path, value } };
+    return sourceNode(text, block, path);
+  }
+  const tag = block.tag;
+  const kind = block.kind === 'tag' && tag ? context.catalog.find(tag.syntax, tag.name) : undefined;
+  if (!tag || !kind) return sourceNode(text, block, path);
+
+  const containerType = context.containers.typeOf(kind);
+  if (containerType && tag.children && tag.closeStart !== undefined) {
+    const children = nodesOf(text, tag.children, path, tag.indent ?? '', context, (type) =>
+      context.containers.allows(kind, type),
+    );
+    return {
+      type: containerType,
+      attrs: {
+        vesperBlock: path,
+        syntax: tag.syntax,
+        name: tag.name,
+        open: text.slice(block.start, tag.openEnd),
+        close: text.slice(tag.closeStart, block.end),
+      },
+      content: children.length > 0 ? children : [{ type: 'paragraph' }],
+    };
+  }
+  return {
+    type: 'vesperCard',
+    attrs: { vesperBlock: path, syntax: tag.syntax, name: tag.name, source: raw },
+  };
+}
+
+/** Text with `indent` taken off every line after the first; null when a line isn't indented so. */
+export function dedent(text: string, indent: string): string | null {
+  if (indent === '') return text;
+  const lines = text.split('\n');
+  const out: string[] = [];
+  for (const [i, line] of lines.entries()) {
+    if (i === 0) out.push(line);
+    else if (line.trim() === '') out.push(line.trim());
+    else if (line.startsWith(indent)) out.push(line.slice(indent.length));
+    else return null;
+  }
+  return out.join('\n');
+}
+
+/**
+ * The one editor node a Markdown block becomes, or null when the writing
+ * view can't own it: it isn't exactly one supported node, or saving it would
+ * read back differently (a lossy parse would show the editor something
+ * other than what the site renders).
+ */
+function writableNode(markdown: MarkdownManager, text: string): JSONContent | null {
+  try {
+    const nodes = markdown.parse(text).content ?? [];
+    const [node] = nodes;
+    if (nodes.length !== 1 || !node?.type || !WRITABLE_NODES.has(node.type)) return null;
+    const again =
+      markdown.parse(markdown.serialize({ type: 'doc', content: [node] })).content ?? [];
+    return again.length === 1 && JSON.stringify(again[0]) === JSON.stringify(node) ? node : null;
+  } catch {
+    return null;
+  }
+}
+
+const isContainer = (node: JSONContent, containers: ContainerTypes) =>
+  node.type !== undefined && containers.kindOf(node.type) !== undefined;
+
+/** How every node with a path first looked: its JSON, or for a container its opening. */
+export function snapshot(doc: JSONContent, containers: ContainerTypes): Map<string, string> {
+  const initial = new Map<string, string>();
+  const visit = (nodes: readonly JSONContent[] | undefined) => {
+    for (const node of nodes ?? []) {
+      const path = node.attrs?.vesperBlock as unknown;
+      if (typeof path === 'string' && !initial.has(path)) {
+        initial.set(
+          path,
+          isContainer(node, containers)
+            ? JSON.stringify({ open: node.attrs?.open as unknown })
+            : JSON.stringify(node),
+        );
+      }
+      if (isContainer(node, containers)) visit(node.content);
+    }
+  };
+  visit(doc.content);
+  return initial;
+}
+
+/** The index of `path` within `parent`, when it's a direct child of it there. */
+function childIndex(path: unknown, parent: string | null): number | null {
+  if (typeof path !== 'string') return null;
+  const dot = path.lastIndexOf('.');
+  const parentPart = dot === -1 ? null : path.slice(0, dot);
+  if (parentPart !== parent) return null;
+  return Number(path.slice(dot + 1));
+}
+
+type ItemsContext = Pick<BodyContext, 'markdown' | 'containers'> & {
+  parsed?: ParsedBody;
+  /** How the body parses, for checking a changed table reads back. */
+  format?: BodyFormat;
+  markdoc?: MarkdocParseOptions;
+};
+
+/** The edited body as items: unchanged blocks keep their bytes, changed ones are written. */
+export function bodyItems(
+  doc: JSONContent,
+  initial: ReadonlyMap<string, string>,
+  context: ItemsContext,
+): BodyItem[] {
+  return itemsOf(doc.content, null, initial, context);
+}
+
+/** The original block at a path ("3", "3.1"), and the indentation of the container holding it. */
+function blockAt(parsed: ParsedBody, path: string): { block: BodyBlock; indent: string } | null {
+  let blocks: readonly BodyBlock[] = parsed.blocks;
+  let indent = '';
+  const parts = path.split('.');
+  for (const [i, part] of parts.entries()) {
+    const block = blocks[Number(part)];
+    if (!block) return null;
+    if (i === parts.length - 1) return { block, indent };
+    if (!block.tag?.children) return null;
+    blocks = block.tag.children;
+    indent = block.tag.indent ?? '';
+  }
+  return null;
+}
+
+/** Each chip's source, in order, and the node with every chip's source blanked. */
+function chipShape(node: JSONContent): { sources: string[]; shape: string } {
+  const sources: string[] = [];
+  const blank = (n: JSONContent): JSONContent => {
+    if (n.type === 'vesperInline') {
+      sources.push(String(n.attrs?.source ?? ''));
+      return { ...n, attrs: { ...n.attrs, source: '' } };
+    }
+    return n.content ? { ...n, content: n.content.map(blank) } : n;
+  };
+  return { sources, shape: JSON.stringify(blank(node)) };
+}
+
+/**
+ * When a Markdown block's only change is inside its chips (an inline tag's
+ * settings, a variable edited as text), the chips' new text is spliced into
+ * the block's original text, so nothing else in it is re-serialized: editing
+ * one tag changes only that tag's text. Null when anything else changed.
+ */
+function chipSplice(
+  node: JSONContent,
+  path: string,
+  initial: ReadonlyMap<string, string>,
+  parsed: ParsedBody | undefined,
+): string | null {
+  const before = initial.get(path);
+  const found = parsed ? blockAt(parsed, path) : null;
+  if (!before || !parsed || !found?.block.chips) return null;
+  const was = chipShape(JSON.parse(before) as JSONContent);
+  const now = chipShape(node);
+  const chips = found.block.chips;
+  if (was.shape !== now.shape || now.sources.length !== chips.length) return null;
+  let text = parsed.text.slice(found.block.start, found.block.end);
+  // Right to left, so earlier offsets stay valid.
+  for (let i = chips.length - 1; i >= 0; i--) {
+    const chip = chips[i];
+    if (!chip) return null;
+    const from = chip.start - found.block.start;
+    const to = chip.end - found.block.start;
+    text = text.slice(0, from) + (now.sources[i] ?? '') + text.slice(to);
+  }
+  // The assembler indents lines after the first like their container's content.
+  return dedent(text, found.indent);
+}
+
+function itemsOf(
+  nodes: readonly JSONContent[] | undefined,
+  parent: string | null,
+  initial: ReadonlyMap<string, string>,
+  context: ItemsContext,
+): BodyItem[] {
+  const items: BodyItem[] = [];
+  for (const node of nodes ?? []) {
+    const path = node.attrs?.vesperBlock as unknown;
+    const index = childIndex(path, parent);
+    if (isContainer(node, context.containers)) {
+      const open = String(node.attrs?.open ?? '');
+      if (index !== null && typeof path === 'string') {
+        const before = initial.get(path);
+        const children = itemsOf(node.content, path, initial, context);
+        items.push({
+          replaces: index,
+          ...(before !== JSON.stringify({ open }) ? { open } : {}),
+          children,
+        });
+      } else {
+        items.push({
+          open,
+          close: String(node.attrs?.close ?? ''),
+          children: itemsOf(node.content, null, initial, context),
+        });
+      }
+      continue;
+    }
+    if (index !== null && typeof path === 'string' && initial.get(path) === JSON.stringify(node)) {
+      items.push({ keep: index });
+      continue;
+    }
+    if (node.type === 'vesperTable') {
+      // The table view checked this change when it was made, so it can't be refused here.
+      const edit = tableEdit(
+        typeof path === 'string' ? path : null,
+        node.attrs?.value as TableValue,
+        context,
+      );
+      if (!edit.ok) throw new Error(edit.reason);
+      items.push(index === null ? { text: edit.text } : { text: edit.text, replaces: index });
+      continue;
+    }
+    const spliced =
+      index !== null && typeof path === 'string'
+        ? chipSplice(node, path, initial, context.parsed)
+        : null;
+    const text = spliced ?? nodeText(node, context.markdown);
+    // An empty paragraph (the line the cursor sits on) writes nothing.
+    if (text === '' && index === null) continue;
+    items.push(index === null ? { text } : { text, replaces: index });
+  }
+  return items;
+}
+
+/**
+ * A table's text as it will be saved: spliced into the table it was loaded
+ * from (`path`), or written new. Refused when it wouldn't read back as this
+ * table.
+ */
+export function tableEdit(
+  path: string | null,
+  value: TableValue,
+  context: ItemsContext,
+): TableEdit {
+  if (!context.format) throw new Error('Saving a table needs the body’s format.');
+  const options = {
+    format: context.format,
+    ...(context.markdoc ? { markdoc: context.markdoc } : {}),
+  };
+  const found = path !== null && context.parsed ? blockAt(context.parsed, path) : null;
+  const table = found?.block.table;
+  const source =
+    found && table && context.parsed
+      ? { text: context.parsed.text, table, indent: found.indent }
+      : null;
+  return editTable(source, savedValue(value), options);
+}
+
+/** A node's text as it will be saved. */
+export function nodeText(node: JSONContent, markdown: MarkdownManager): string {
+  if (node.type === 'sourceBlock') return String(node.attrs?.text ?? '');
+  if (node.type === 'vesperCard') return String(node.attrs?.source ?? '');
+  const { vesperBlock: _vesperBlock, ...attrs } = node.attrs ?? {};
+  return restoreChips(
+    markdown.serialize({ type: 'doc', content: [{ ...node, attrs }] }).replace(/\s+$/, ''),
+  );
+}
+
+/** A plain-language name for a protected block, from its parser type. */
+export function sourceLabel(blockType: string): string {
+  const labels: Record<string, string> = {
+    mdxjsEsm: 'Import',
+    mdxJsxFlowElement: 'Component',
+    mdxFlowExpression: 'Expression',
+    html: 'HTML',
+    html_block: 'HTML',
+    comment: 'Comment',
+    definition: 'Link reference',
+    footnoteDefinition: 'Footnote',
+    table: 'Table',
+    tag: 'Markdoc tag',
+    unparsed: 'Body that couldn’t be read',
+  };
+  return labels[blockType] ?? 'Formatted text';
+}

package/src/body/insert.tsx

@@ -0,0 +1,301 @@
+import { Extension, type Editor } from '@tiptap/core';
+import { Plugin, PluginKey, type EditorState } from '@tiptap/pm/state';
+import { useEditorState } from '@tiptap/react';
+import { Menu, cx, popoverClass } from '@vespercms/ui';
+import { useId } from 'react';
+import { insertable, type BlockKind, type BlockShape, type Catalog } from './catalog.ts';
+import { placementAt } from './commands.ts';
+import type { ContainerTypes } from './nodes.ts';
+
+/*
+ * Inserting tags (spec §6.5.1, "Inserting"): typing "/" at the start of a
+ * line or after a space opens a list of what fits at the cursor, filtered as
+ * you type; the toolbar's Insert button offers the same list as a menu.
+ *
+ * The "/" list follows the combobox pattern: focus stays in the text, which
+ * becomes a combobox while the list is open (aria-expanded, aria-controls,
+ * aria-activedescendant), and the arrow keys move through the options.
+ */
+
+export type InsertChoice = { kind: BlockKind; shape: BlockShape };
+
+type SlashState = { active: false } | { active: true; from: number; index: number };
+
+export const slashKey = new PluginKey<SlashState>('vesperSlash');
+
+/** What can be inserted at the cursor right now, by friendly name. */
+export function choicesAt(
+  state: EditorState,
+  catalog: Catalog,
+  containers: ContainerTypes,
+): InsertChoice[] {
+  return insertable(catalog)
+    .flatMap((kind) => {
+      const shape = placementAt(state, kind, containers);
+      return shape ? [{ kind, shape }] : [];
+    })
+    .sort((a, b) => a.kind.label.localeCompare(b.kind.label));
+}
+
+export function slashQuery(state: EditorState): string | null {
+  const slash = slashKey.getState(state);
+  if (!slash?.active) return null;
+  return state.doc.textBetween(slash.from + 1, state.selection.from, '\n');
+}
+
+export function filterChoices(choices: readonly InsertChoice[], query: string): InsertChoice[] {
+  const q = query.toLowerCase();
+  return choices.filter(
+    (c) => c.kind.label.toLowerCase().includes(q) || c.kind.name.toLowerCase().includes(q),
+  );
+}
+
+export type SlashOptions = {
+  listboxId: string;
+  optionId: (index: number) => string;
+  /** The options for the current query (computed by the caller, which knows the catalog). */
+  choices: (state: EditorState) => InsertChoice[];
+  choose: (choice: InsertChoice, range: { from: number; to: number }) => void;
+  disabled: () => boolean;
+};
+
+/**
+ * The "/" plugin: opens on "/" typed at a line's start or after a space in a
+ * paragraph, closes on Escape, a space, or the cursor leaving the query, and
+ * sets the editor's role and ARIA state while it's open.
+ */
+export function SlashCommands(options: SlashOptions) {
+  return Extension.create({
+    name: 'vesperSlash',
+    // Ahead of every other key handler, so Enter, Escape and the arrows
+    // belong to the list while it's open.
+    priority: 1000,
+    addProseMirrorPlugins() {
+      return [
+        new Plugin<SlashState>({
+          key: slashKey,
+          state: {
+            init: () => ({ active: false }),
+            apply(tr, previous, _old, next) {
+              const meta = tr.getMeta(slashKey) as SlashState | { index: number } | undefined;
+              let state: SlashState = previous;
+              // A list opened by this transaction already points into the new document.
+              const opened = meta !== undefined && 'active' in meta;
+              if (opened) state = meta;
+              else if (meta && state.active) state = { ...state, index: meta.index };
+              if (!state.active) return state;
+              const from = opened ? state.from : tr.mapping.map(state.from, -1);
+              const { selection } = next;
+              const text = next.doc.textBetween(from, Math.max(from, selection.from), '\n');
+              const still =
+                selection.empty &&
+                selection.from > from &&
+                next.doc.resolve(from).parent === selection.$from.parent &&
+                text.startsWith('/') &&
+                !/\s/.test(text);
+              return still ? { ...state, from } : { active: false };
+            },
+          },
+          props: {
+            handleTextInput(view, from, to, text) {
+              if (text !== '/' || options.disabled()) return false;
+              const $from = view.state.doc.resolve(from);
+              if ($from.parent.type.name !== 'paragraph') return false;
+              const before = $from.parent.textBetween(0, $from.parentOffset, '\n');
+              if (before !== '' && !/\s$/.test(before)) return false;
+              view.dispatch(
+                view.state.tr
+                  .insertText('/', from, to)
+                  .setMeta(slashKey, { active: true, from, index: 0 }),
+              );
+              return true;
+            },
+            handleKeyDown(view, event) {
+              const state = slashKey.getState(view.state);
+              if (!state?.active) return false;
+              const query = slashQuery(view.state) ?? '';
+              const list = filterChoices(options.choices(view.state), query);
+              if (event.key === 'Escape') {
+                view.dispatch(view.state.tr.setMeta(slashKey, { active: false }));
+                return true;
+              }
+              if (list.length === 0) return false;
+              if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                const step = event.key === 'ArrowDown' ? 1 : -1;
+                const index = (state.index + step + list.length) % list.length;
+                view.dispatch(view.state.tr.setMeta(slashKey, { index }));
+                return true;
+              }
+              if (event.key === 'Enter' || event.key === 'Tab') {
+                const choice = list[Math.min(state.index, list.length - 1)];
+                if (!choice) return false;
+                const range = { from: state.from, to: view.state.selection.from };
+                view.dispatch(view.state.tr.setMeta(slashKey, { active: false }));
+                options.choose(choice, range);
+                return true;
+              }
+              return false;
+            },
+          },
+        }),
+      ];
+    },
+  });
+}
+
+/**
+ * The text's role and ARIA state: a multi-line textbox, or a combobox while
+ * the "/" list is open. Given to the editor through `editorProps.attributes`,
+ * which is the only place that can replace Tiptap's own `role="textbox"`.
+ */
+export function slashAttributes(
+  state: EditorState,
+  options: Pick<SlashOptions, 'listboxId' | 'optionId'> & { count: (query: string) => number },
+): Record<string, string> {
+  const slash = slashKey.getState(state);
+  if (!slash?.active) return { role: 'textbox', 'aria-multiline': 'true' };
+  const count = options.count(slashQuery(state) ?? '');
+  return {
+    role: 'combobox',
+    'aria-expanded': 'true',
+    'aria-controls': options.listboxId,
+    'aria-autocomplete': 'list',
+    ...(count > 0
+      ? { 'aria-activedescendant': options.optionId(Math.min(slash.index, count - 1)) }
+      : {}),
+  };
+}
+
+/** The "/" list, shown under the cursor while the plugin is open. */
+export function SlashList({
+  editor,
+  listboxId,
+  optionId,
+  choices,
+  onChoose,
+}: {
+  editor: Editor;
+  listboxId: string;
+  optionId: (index: number) => string;
+  choices: (state: EditorState) => InsertChoice[];
+  onChoose: (choice: InsertChoice, range: { from: number; to: number }) => void;
+}) {
+  const state = useEditorState({
+    editor,
+    selector: ({ editor: e }) => {
+      const slash = slashKey.getState(e.state);
+      if (!slash?.active) return null;
+      return {
+        from: slash.from,
+        to: e.state.selection.from,
+        index: slash.index,
+        query: slashQuery(e.state) ?? '',
+        place: placeOf(e, slash.from),
+      };
+    },
+    equalityFn: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+  });
+  if (!state) return null;
+  const { place } = state;
+  const list = filterChoices(choices(editor.state), state.query);
+  const active = Math.min(state.index, Math.max(0, list.length - 1));
+  return (
+    <div
+      id={listboxId}
+      role="listbox"
+      aria-label="Insert a block"
+      style={place ? { top: place.top, left: place.left } : undefined}
+      className={cx('fixed z-40 max-h-64 min-w-56 overflow-y-auto', popoverClass)}
+    >
+      {list.length === 0 ? (
+        <div
+          role="option"
+          tabIndex={-1}
+          aria-selected="false"
+          aria-disabled="true"
+          className="px-3 py-2 text-small text-content-muted"
+        >
+          Nothing fits here
+        </div>
+      ) : (
+        list.map((choice, index) => (
+          <div
+            key={choice.kind.key}
+            id={optionId(index)}
+            role="option"
+            tabIndex={-1}
+            aria-selected={index === active}
+            className={cx(
+              'flex min-h-9 cursor-default items-center rounded-md px-3 text-body text-content',
+              index === active && 'bg-accent-subtle',
+            )}
+            onMouseDown={(event) => {
+              // Keep focus (and the "/" range) in the text.
+              event.preventDefault();
+              onChoose(choice, { from: state.from, to: state.to });
+            }}
+          >
+            {choice.kind.label}
+            {choice.shape === 'inline' && (
+              <span className="text-content-muted"> (in this line)</span>
+            )}
+          </div>
+        ))
+      )}
+    </div>
+  );
+}
+
+/** Where the list goes: just under the "/". Null when the view can't say (no layout). */
+function placeOf(editor: Editor, from: number): { top: number; left: number } | null {
+  try {
+    const coords = editor.view.coordsAtPos(from);
+    return { top: coords.bottom + 4, left: coords.left };
+  } catch {
+    return null;
+  }
+}
+
+/** The toolbar's Insert menu: the same list, for people who don't use "/". */
+export function InsertMenu({
+  editor,
+  choices,
+  onChoose,
+  disabled,
+}: {
+  editor: Editor;
+  choices: (state: EditorState) => InsertChoice[];
+  onChoose: (choice: InsertChoice) => void;
+  disabled: boolean;
+}) {
+  const list = useEditorState({
+    editor,
+    selector: ({ editor: e }) =>
+      choices(e.state)
+        .map((c) => `${c.kind.key}|${c.shape}`)
+        .join(','),
+  });
+  const available = choices(editor.state);
+  if (disabled || list === '' || available.length === 0) return null;
+  return (
+    <Menu
+      label="Insert a block"
+      triggerText="Insert"
+      triggerIcon="add"
+      items={available.map((c) => ({
+        id: `${c.kind.key}|${c.shape}`,
+        label: c.shape === 'inline' ? `${c.kind.label} (in this line)` : c.kind.label,
+      }))}
+      onAction={(id) => {
+        const choice = available.find((c) => `${c.kind.key}|${c.shape}` === id);
+        if (choice) onChoose(choice);
+      }}
+    />
+  );
+}
+
+/** Stable ids for the "/" listbox and its options. */
+export function useSlashIds(): { listboxId: string; optionId: (index: number) => string } {
+  const base = useId().replace(/:/g, '');
+  return { listboxId: `${base}-insert`, optionId: (index) => `${base}-insert-${String(index)}` };
+}