@estiva-app/ui 0.44.1 → 0.45.0

package/src/SuggestionMenu.stories.tsx

@@ -0,0 +1,202 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { Extension } from '@tiptap/core'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Suggestion from '@tiptap/suggestion'
+import { EnterHint } from './Menu'
+import { richTextClassName } from './RichText'
+import { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
+import { suggestionPopup } from './suggestionPopup'
+
+/**
+ * The list a text editor opens as you type — `/` for commands, `@` for people.
+ * Focus stays in the text: the editor hands its ↑, ↓ and Enter to the list.
+ */
+const meta = {
+  title: 'Primitives/SuggestionMenu',
+  component: SuggestionMenu,
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+interface Command {
+  id: string
+  label: string
+  keys?: string
+}
+
+const FORMAT: Command[] = [
+  { id: 'text', label: 'Text' },
+  { id: 'heading', label: 'Heading', keys: '#' },
+  { id: 'subheading', label: 'Subheading', keys: '##' },
+  { id: 'quote', label: 'Quote', keys: '>' },
+  { id: 'code', label: 'Code', keys: '`' },
+  { id: 'bullets', label: 'Bulleted list', keys: '-' },
+  { id: 'numbers', label: 'Numbered list', keys: '1.' },
+]
+const INSERT: Command[] = [
+  { id: 'item-one', label: 'Item one' },
+  { id: 'item-two', label: 'Item two' },
+]
+const commandRow = (c: Command): SuggestionMenuRow => ({ label: c.label, shortcut: c.keys })
+
+/**
+ * A line of text with the caret's place marked, and the list hung from it —
+ * the way the editor hangs it. The list is drawn from a rect, so the story
+ * measures a stand-in for the caret once it is on screen.
+ */
+function AtACaret<T>({ children, ...props }: { children?: ReactNode } & Omit<Parameters<typeof SuggestionMenu<T>>[0], 'rect'>) {
+  const caret = useRef<HTMLSpanElement>(null)
+  const [rect, setRect] = useState<DOMRect | null>(null)
+  useLayoutEffect(() => setRect(caret.current?.getBoundingClientRect() ?? null), [])
+  return (
+    <div className="flex h-[520px] items-end pb-6 text-body-2 text-text-primary">
+      <p>
+        Some text, then a slash
+        <span ref={caret}>/</span>
+        {children}
+      </p>
+      <SuggestionMenu<T> {...props} rect={rect} />
+    </div>
+  )
+}
+
+/** Two sections: headings, keys you could type instead, a hairline between. */
+export const Default: Story = {
+  render: () => (
+    <AtACaret<Command>
+      ariaLabel="Commands"
+      width="w-[300px]"
+      maxHeight="max-h-[400px]"
+      sections={[
+        { label: 'Format', items: FORMAT },
+        { label: 'Insert', items: INSERT },
+      ]}
+      itemKey={(c) => c.id}
+      row={commandRow}
+      onSelect={() => {}}
+    />
+  ),
+}
+
+/** Tall rows: a face, a second line, and Enter's hint on the highlighted one. */
+export const TallRows: Story = {
+  render: () => (
+    <AtACaret<string>
+      ariaLabel="Items"
+      width="w-[360px]"
+      maxHeight="max-h-[360px]"
+      sections={[{ label: 'Items', items: ['Item one', 'Item two', 'Item three'], className: 'px-3 py-1' }]}
+      itemKey={(s) => s}
+      row={(s) => ({
+        label: s,
+        description: 'A second line',
+        leading: <IconSquareRounded size={32} stroke={1.5} className="text-text-muted" />,
+        hint: <EnterHint />,
+        size: 'tall',
+      })}
+      onSelect={() => {}}
+    />
+  ),
+}
+
+/** More rows than fit: the box stops at `maxHeight` and scrolls in the package's scroll area. */
+export const Scrolling: Story = {
+  render: () => (
+    <AtACaret<string>
+      ariaLabel="Items"
+      width="w-[300px]"
+      maxHeight="max-h-[240px]"
+      sections={[{ label: 'Items', items: Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`) }]}
+      itemKey={(s) => s}
+      row={(s) => ({ label: s })}
+      onSelect={() => {}}
+    />
+  ),
+}
+
+/** The keys, driven from outside as an editor drives them: ↓ twice moves the highlight to the third row. */
+export const DrivenByKeys: Story = {
+  render: () => {
+    function Driven() {
+      const handle = useRef<SuggestionMenuHandle>(null)
+      const [picked, setPicked] = useState('nothing yet')
+      const sections = useMemo<SuggestionMenuSection<Command>[]>(() => [{ label: 'Format', items: FORMAT }], [])
+      useLayoutEffect(() => {
+        const press = (key: string) => handle.current?.onKeyDown(new KeyboardEvent('keydown', { key }))
+        requestAnimationFrame(() => {
+          press('ArrowDown')
+          press('ArrowDown')
+        })
+      }, [])
+      return (
+        <AtACaret<Command> handle={handle} ariaLabel="Commands" width="w-[300px]" maxHeight="max-h-[400px]" sections={sections} itemKey={(c) => c.id} row={commandRow} onSelect={(c) => setPicked(c.label)}>
+          <span className="ml-4 text-text-secondary">Chosen: {picked}</span>
+        </AtACaret>
+      )
+    }
+    return <Driven />
+  },
+}
+
+/*
+ * In a real editor: `suggestionPopup` connects a Tiptap suggestion plugin to
+ * this list. Type `/` anywhere after a space; ↑ ↓ Enter choose, Escape closes,
+ * and typing narrows the list.
+ */
+const Commands = Extension.create({
+  name: 'storyCommands',
+  addProseMirrorPlugins() {
+    return [
+      Suggestion<Command>({
+        editor: this.editor,
+        char: '/',
+        items: ({ query }) => [...FORMAT, ...INSERT].filter((c) => c.label.toLowerCase().includes(query.toLowerCase())),
+        command: ({ editor, range, props }) => {
+          const chain = editor.chain().focus().deleteRange(range)
+          if (props.id === 'heading') chain.setHeading({ level: 1 }).run()
+          else if (props.id === 'subheading') chain.setHeading({ level: 2 }).run()
+          else if (props.id === 'quote') chain.setBlockquote().run()
+          else if (props.id === 'code') chain.setCodeBlock().run()
+          else if (props.id === 'bullets') chain.toggleBulletList().run()
+          else if (props.id === 'numbers') chain.toggleOrderedList().run()
+          else chain.setParagraph().run()
+        },
+        render: suggestionPopup<Command>({
+          ariaLabel: 'Commands',
+          width: 'w-[300px]',
+          maxHeight: 'max-h-[400px]',
+          sections: (items) => [
+            { label: 'Format', items: items.filter((c) => FORMAT.includes(c)) },
+            { label: 'Insert', items: items.filter((c) => INSERT.includes(c)) },
+          ],
+          itemKey: (c) => c.id,
+          row: commandRow,
+        }),
+      }),
+    ]
+  },
+})
+
+/** A real editor with `/` wired through `suggestionPopup` (`@estiva-app/ui/editor`). Click in and type `/`. */
+export const InAnEditor: Story = {
+  render: () => {
+    function Live() {
+      const editor = useEditor({
+        extensions: [StarterKit, Commands],
+        content: '<p>Click here, then type / after a space.</p>',
+        editorProps: { attributes: { class: richTextClassName('default', 'outline-none min-h-24'), 'aria-label': 'Text' } },
+      })
+      return (
+        <div className="flex h-[520px] items-end pb-6">
+          <EditorContent editor={editor} className="w-full rounded-md border border-border-default bg-bg-surface p-3" />
+        </div>
+      )
+    }
+    return <Live />
+  },
+}

package/src/SuggestionMenu.test.tsx

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+/**
+ * The list an editor drives (UIG-31). jsdom cannot type into an editor, so this
+ * drives the part the way the editor does — through `handle` — with a plain
+ * element standing in for the editor's own. The real editor is proved in a
+ * browser through the `InAnEditor` story.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { createRef } from 'react'
+import { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuSection } from './SuggestionMenu'
+
+afterEach(cleanup)
+// jsdom lays nothing out, so it has no `scrollIntoView`; the highlighted row calls it.
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn()
+})
+
+const RECT = { top: 400, bottom: 420, left: 100, right: 110, width: 10, height: 20, x: 100, y: 400, toJSON: () => ({}) } as DOMRect
+const SECTIONS: SuggestionMenuSection<string>[] = [
+  { label: 'First', items: ['One', 'Two'] },
+  { label: 'Second', items: ['Three'] },
+]
+
+function draw({ sections = SECTIONS, editor, rect = RECT, onSelect = vi.fn() }: { sections?: SuggestionMenuSection<string>[]; editor?: HTMLElement; rect?: DOMRect | null; onSelect?: (s: string) => void } = {}) {
+  const handle = createRef<SuggestionMenuHandle>()
+  const result = render(
+    <SuggestionMenu handle={handle} rect={rect} editorElement={editor} ariaLabel="Commands" width="w-[300px]" maxHeight="max-h-[400px]" sections={sections} itemKey={(s) => s} row={(s) => ({ label: s })} onSelect={onSelect} />,
+  )
+  const press = (key: string) => {
+    let used = false
+    act(() => {
+      used = handle.current!.onKeyDown(new KeyboardEvent('keydown', { key }))
+    })
+    return used
+  }
+  return { ...result, handle, press, onSelect }
+}
+
+const active = () => screen.getAllByRole('option').findIndex((o) => o.getAttribute('aria-selected') === 'true')
+
+describe('SuggestionMenu', () => {
+  it('is a named listbox of options, in sections', async () => {
+    draw()
+    await screen.findByRole('listbox', { name: 'Commands' })
+    expect(screen.getAllByRole('option').map((o) => o.textContent)).toEqual(['One', 'Two', 'Three'])
+    expect(screen.getByRole('group', { name: 'First' })).toBeTruthy()
+    expect(screen.getByRole('group', { name: 'Second' })).toBeTruthy()
+  })
+
+  it('draws nothing when there is nothing to show', () => {
+    draw({ sections: [{ label: 'First', items: [] }] })
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('walks with ↓ and ↑ across sections, wrapping at both ends', async () => {
+    const { press } = draw()
+    await screen.findByRole('listbox')
+    expect(active()).toBe(0)
+    expect(press('ArrowDown')).toBe(true)
+    expect(active()).toBe(1)
+    press('ArrowDown')
+    expect(active()).toBe(2)
+    press('ArrowDown')
+    expect(active()).toBe(0)
+    press('ArrowUp')
+    expect(active()).toBe(2)
+  })
+
+  it('chooses the highlighted row on Enter, and leaves every other key to the editor', async () => {
+    const { press, onSelect } = draw()
+    await screen.findByRole('listbox')
+    press('ArrowDown')
+    expect(press('Enter')).toBe(true)
+    expect(onSelect).toHaveBeenCalledWith('Two')
+    expect(press('a')).toBe(false)
+    expect(press('Escape')).toBe(false)
+  })
+
+  it('chooses on a press, without taking the focus', async () => {
+    const { onSelect } = draw()
+    await screen.findByRole('listbox')
+    const row = screen.getByRole('option', { name: 'Three' })
+    const down = new MouseEvent('mousedown', { bubbles: true, cancelable: true })
+    row.dispatchEvent(down)
+    expect(onSelect).toHaveBeenCalledWith('Three')
+    expect(down.defaultPrevented).toBe(true)
+  })
+
+  it('moves the highlight with the pointer', async () => {
+    draw()
+    await screen.findByRole('listbox')
+    fireEvent.mouseEnter(screen.getByRole('option', { name: 'Three' }))
+    expect(active()).toBe(2)
+  })
+
+  it('goes back to the first row when the list changes', async () => {
+    const { press, rerender, handle } = draw()
+    await screen.findByRole('listbox')
+    press('ArrowDown')
+    expect(active()).toBe(1)
+    rerender(<SuggestionMenu handle={handle} rect={RECT} ariaLabel="Commands" width="w-[300px]" maxHeight="max-h-[400px]" sections={[{ items: ['Two', 'Three'] }]} itemKey={(s) => s} row={(s) => ({ label: s })} onSelect={() => {}} />)
+    expect(active()).toBe(0)
+  })
+
+  it('tells the editor it completes into the list, and which row is active', async () => {
+    const editor = document.createElement('div')
+    const { press } = draw({ editor })
+    const listbox = await screen.findByRole('listbox')
+    expect(editor.getAttribute('aria-autocomplete')).toBe('list')
+    expect(editor.getAttribute('aria-haspopup')).toBe('listbox')
+    expect(editor.getAttribute('aria-controls')).toBe(listbox.id)
+    const options = screen.getAllByRole('option')
+    expect(editor.getAttribute('aria-activedescendant')).toBe(options[0].id)
+    press('ArrowDown')
+    expect(editor.getAttribute('aria-activedescendant')).toBe(options[1].id)
+  })
+
+  it('leaves nothing on the editor once it is gone', async () => {
+    const editor = document.createElement('div')
+    const { unmount } = draw({ editor })
+    await screen.findByRole('listbox')
+    unmount()
+    for (const name of ['aria-autocomplete', 'aria-haspopup', 'aria-controls', 'aria-activedescendant']) {
+      expect(editor.hasAttribute(name), name).toBe(false)
+    }
+  })
+})

package/src/SuggestionMenu.tsx

@@ -0,0 +1,189 @@
+import { useCallback, useEffect, useId, useImperativeHandle, useMemo, useState, type ReactNode, type Ref } from 'react'
+import { MenuItem, MenuSection, MenuSeparator, type MenuItemProps } from './Menu'
+import { Popover } from './Popover'
+
+/**
+ * The list a text editor opens as you type — `/` for commands, `@` for people,
+ * `[` for a reference. UIG-31: Peek's four type-ahead menus, made one part.
+ *
+ * **Why it is not a `Combobox` or a `Menu`.** Base UI's lists need a text field
+ * of their own, and the text being completed is an editor, not an `<input>`.
+ * So focus never leaves the text: the editor hands its arrow keys and Enter to
+ * this list through `handle`, and the list tells the editor which row is
+ * active (`aria-activedescendant`), the pattern Base UI's `Combobox` builds.
+ * If Base UI ever adds a list that can be driven from outside its own field,
+ * this part moves onto it.
+ *
+ * **What it owns**, all of it written once here instead of in every menu:
+ *
+ * - the box: the package `Popover`, anchored to the caret, above it and below
+ *   when there is no room, clamped to the window, scrolling in the package's
+ *   `ScrollArea` past `maxHeight`;
+ * - the highlighted row: ↑ and ↓ (wrapping at the ends), Enter to choose, the
+ *   pointer moving the highlight, a press choosing without taking focus from
+ *   the text, the highlight back on the first row whenever the list changes,
+ *   and the highlighted row scrolled into view;
+ * - what a screen reader is told: the list is a `listbox`, each row an
+ *   `option`, and the editor says it completes into this list and which row
+ *   is active — all removed again when the list closes.
+ *
+ * What stays with the app: which rows exist, what choosing one does, and what
+ * each row shows (its label, face, keys, hint) — `row` returns the package
+ * `MenuItem`'s own props. With nothing to show there is no box at all.
+ */
+export interface SuggestionMenuRow {
+  label: string
+  description?: string
+  leading?: ReactNode
+  /** What you would type — drawn as keys at the right, e.g. `#` for a heading. */
+  shortcut?: string
+  /** Drawn at the right while the row is highlighted, e.g. `<EnterHint />`. */
+  hint?: ReactNode
+  /** `tall` for a row with a face and a second line — `MenuItem`'s own sizes. */
+  size?: MenuItemProps['size']
+}
+
+export interface SuggestionMenuSection<T> {
+  /** The section's heading. Without one, the rows stand alone. */
+  label?: string
+  items: readonly T[]
+  /** On the heading row, as `MenuSection`'s. */
+  className?: string
+}
+
+/** What the editor calls while the list is open. */
+export interface SuggestionMenuHandle {
+  /** ↑, ↓ and Enter. `true` when the list used the key, so the editor must not. */
+  onKeyDown: (event: KeyboardEvent) => boolean
+}
+
+export interface SuggestionMenuProps<T> {
+  /** The caret's rect, from the editor. `null` closes the box. */
+  rect: DOMRect | null
+  /** The editor's own element — told which row is active. Absent in a story. */
+  editorElement?: HTMLElement | null
+  /** Names the list — "Commands", "People". */
+  ariaLabel: string
+  /** The box's width, e.g. `w-[300px]`. */
+  width: string
+  /** The cap before the rows scroll, e.g. `max-h-[400px]`. */
+  maxHeight: string
+  sections: readonly SuggestionMenuSection<T>[]
+  /** A stable key for a row. */
+  itemKey: (item: T) => string
+  /** What a row shows. */
+  row: (item: T) => SuggestionMenuRow
+  onSelect: (item: T) => void
+  handle?: Ref<SuggestionMenuHandle>
+}
+
+export function SuggestionMenu<T>({ rect, editorElement, ariaLabel, width, maxHeight, sections, itemKey, row, onSelect, handle }: SuggestionMenuProps<T>) {
+  const shown = useMemo(() => sections.filter((section) => section.items.length > 0), [sections])
+  const items = useMemo(() => shown.flatMap((section) => section.items), [shown])
+  const keys = items.map(itemKey).join('\n')
+  const [highlight, setHighlight] = useState(0)
+  const base = useId()
+  const listboxId = `${base}-list`
+
+  // A new list is a new list: the old index may not exist in it.
+  useEffect(() => setHighlight(0), [keys])
+
+  useImperativeHandle(handle, () => ({
+    // The editor hands its arrow keys to this list: Base UI's lists need a text field of their own, and an editor is not one.
+    onKeyDown: (event) => {
+      if (!items.length) return false
+      if (event.key === 'ArrowDown') {
+        setHighlight((h) => (h + 1) % items.length)
+        return true
+      }
+      if (event.key === 'ArrowUp') {
+        setHighlight((h) => (h - 1 + items.length) % items.length)
+        return true
+      }
+      if (event.key === 'Enter') {
+        const item = items[highlight]
+        if (item !== undefined) onSelect(item)
+        return true
+      }
+      return false
+    },
+  }), [items, highlight, onSelect])
+
+  /*
+   * The editor completes into this list while it is open: it says so, names
+   * the list, and points at the active row. Removed on close — an editor left
+   * saying it controls a list that is gone is worse than saying nothing.
+   */
+  const open = rect !== null && items.length > 0
+  useEffect(() => {
+    if (!editorElement || !open) return
+    editorElement.setAttribute('aria-autocomplete', 'list')
+    editorElement.setAttribute('aria-haspopup', 'listbox')
+    editorElement.setAttribute('aria-controls', listboxId)
+    return () => {
+      for (const name of ['aria-autocomplete', 'aria-haspopup', 'aria-controls', 'aria-activedescendant']) editorElement.removeAttribute(name)
+    }
+  }, [editorElement, open, listboxId])
+  useEffect(() => {
+    if (!editorElement || !open) return
+    editorElement.setAttribute('aria-activedescendant', `${base}-${highlight}`)
+  }, [editorElement, open, base, highlight])
+
+  const scrollRef = useCallback((el: HTMLElement | null) => {
+    el?.scrollIntoView({ block: 'nearest' })
+  }, [])
+
+  if (items.length === 0) return null
+
+  const drawRow = (item: T) => {
+    const index = items.indexOf(item)
+    const selected = index === highlight
+    const { label, description, leading, shortcut, hint, size } = row(item)
+    return (
+      // A row of a list the editor drives from its caret: focus stays in the text, so the row is no Tab stop.
+      <MenuItem
+        key={itemKey(item)}
+        role="option"
+        id={`${base}-${index}`}
+        aria-selected={selected}
+        tabIndex={-1}
+        ref={selected ? scrollRef : undefined}
+        size={size}
+        label={label}
+        description={description}
+        leading={leading}
+        shortcut={shortcut}
+        hint={hint}
+        selected={selected}
+        onMouseEnter={() => setHighlight(index)}
+        onMouseDown={(event) => {
+          // Choosing must not take focus from the text.
+          event.preventDefault()
+          onSelect(item)
+        }}
+      />
+    )
+  }
+
+  return (
+    <Popover anchor={rect} open={rect !== null} side="top" align="left" className={width} maxHeight={maxHeight} ariaLabel={ariaLabel}>
+      {/* The list the editor drives from its caret: a listbox, because Base UI's lists need a text field of their own. */}
+      <div id={listboxId} role="listbox" aria-label={ariaLabel} className="flex flex-col">
+        {shown.map((section, i) => (
+          <div key={section.label ?? i} className="contents">
+            {i > 0 && <MenuSeparator />}
+            {section.label ? (
+              <div role="group" aria-label={section.label}>
+                <MenuSection label={section.label} className={section.className}>
+                  {section.items.map(drawRow)}
+                </MenuSection>
+              </div>
+            ) : (
+              section.items.map(drawRow)
+            )}
+          </div>
+        ))}
+      </div>
+    </Popover>
+  )
+}

package/src/editor.ts

@@ -0,0 +1,11 @@
+/**
+ * `@estiva-app/ui/editor` — the parts that work inside a Tiptap editor (UIG-31,
+ * Katerina's ruling 29 September: one editor corner in the package, option A).
+ *
+ * Its own entry because it imports Tiptap, which only an app with an editor
+ * installs: the main entry stays free of it, and the Tiptap peers are optional,
+ * as the eslint ones are. The rest of the package it draws with — `Popover`,
+ * `Toolbar`, `MenuItem`, `SuggestionMenu` — is the main entry's own, not a copy.
+ */
+export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
+export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'

package/src/eslint/no-rebuilt-behaviour.test.ts

@@ -25,7 +25,7 @@ const tester = new RuleTester({
 
 const component = (body: string) => `export function Probe() {\n  return (\n${body}\n  )\n}\n`
 const effect = (body: string) => `useEffect(() => {\n${body}\n}, [])\n`
-const LIST = ' To pick several, `ChipInput`; to search and act, `CommandPalette`; to tick several in a list, `Checkbox` with `row`.'
+const LIST = ' To pick several, `ChipInput`; to search and act, `CommandPalette`; to tick several in a list, `Checkbox` with `row`; for the list a text editor opens as you type, `SuggestionMenu`.'
 
 tester.run('no-rebuilt-behaviour', noRebuiltBehaviour, {
   valid: [

package/src/eslint/no-rebuilt-behaviour.ts

@@ -88,7 +88,7 @@ export const BASE_UI_PARTS: Record<string, OwnerPart | null> = {
 
 const LIST_PART: OwnerPart = {
   use: 'Select',
-  more: ' To pick several, `ChipInput`; to search and act, `CommandPalette`; to tick several in a list, `Checkbox` with `row`.',
+  more: ' To pick several, `ChipInput`; to search and act, `CommandPalette`; to tick several in a list, `Checkbox` with `row`; for the list a text editor opens as you type, `SuggestionMenu`.',
 }
 
 const MESSAGE_PART: OwnerPart = { use: 'FieldLine', more: ' For a notice, `Banner`; for a message that comes and goes, `Toast`.' }
@@ -232,7 +232,7 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
     id: 'walking',
     behaviour: 'Moves through its items with the arrow keys',
     baseUi: ['Menu', 'Select', 'Combobox', 'Autocomplete', 'Tabs', 'Toolbar'],
-    owners: ['Menu', 'Select', 'ChipInput', 'CommandPalette', 'Tabs', 'Toolbar'],
+    owners: ['Menu', 'Select', 'ChipInput', 'CommandPalette', 'SuggestionMenu', 'Tabs', 'Toolbar'],
     reads: `a key compared by hand with ${WALKING_KEYS.join(', ')}`,
   },
   {

package/src/how.test.ts

@@ -177,7 +177,7 @@ function compilerOptions(): ts.CompilerOptions {
   const parsed = ts.convertCompilerOptionsFromJson(raw.compilerOptions, REPO)
   // A placeholder is `any`: `people.map((p) => …)` would fail noImplicitAny on `p`,
   // the placeholder's fault, not the page's. A callback prop's parameter keeps the part's type.
-  return { ...parsed.options, noEmit: true, noImplicitAny: false, baseUrl: REPO, paths: { '@estiva-app/ui': ['./src/index.ts'] }, types: [] }
+  return { ...parsed.options, noEmit: true, noImplicitAny: false, baseUrl: REPO, paths: { '@estiva-app/ui': ['./src/index.ts'], '@estiva-app/ui/editor': ['./src/editor.ts'] }, types: [] }
 }
 
 function makeHost(options: ts.CompilerOptions, virtual: Map<string, string>): ts.CompilerHost {

package/src/index.ts

@@ -71,6 +71,7 @@ export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
 export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSeparator, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
 export { NavItem, type NavItemProps } from './NavItem'
 export { Popover, type PopoverProps } from './Popover'
+export { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuProps, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
 export { ScrollArea, type ScrollAreaProps } from './ScrollArea'
 export { ReactionPicker, type ReactionOption, type ReactionPickerProps } from './ReactionPicker'
 export { Toolbar, ToolbarButton, ToolbarInput, ToolbarLink, ToolbarSeparator, type ToolbarProps, type ToolbarButtonProps, type ToolbarInputProps, type ToolbarLinkProps } from './Toolbar'
@@ -93,3 +94,4 @@ export { SectionLabel } from './SectionLabel'
 export { Tabs, type TabDef, type TabsProps } from './Tabs'
 export { Toast, ToastProvider, useToast, type ToastOptions, type ToastProps, type ToastType } from './Toast'
 export { cn } from './cn'
+export { isApplePlatform, shortcutLabel } from './shortcuts'

package/src/keptSelection.test.ts

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { Editor } from '@tiptap/core'
+import { DecorationSet } from '@tiptap/pm/view'
+import StarterKit from '@tiptap/starter-kit'
+import { KeptSelection, keepSelection, releaseSelection, keptSelection, keptSelectionKey } from './SelectionToolbar'
+
+/**
+ * The kept selection (UIG-31; first written for the link field, PEE-19). Runs
+ * against a real editor with the extension registered.
+ */
+
+let editor: Editor
+
+beforeEach(() => {
+  editor = new Editor({ extensions: [StarterKit, KeptSelection], content: '<p>read the widgets topic first</p>' })
+  editor.commands.setTextSelection({ from: 10, to: 23 })
+})
+
+afterEach(() => {
+  editor.destroy()
+})
+
+/** The ranges the plugin is drawing right now. */
+function drawn(): Array<[number, number]> {
+  const plugin = keptSelectionKey.get(editor.state)
+  if (!plugin || typeof plugin.props.decorations !== 'function') return []
+  const set = plugin.props.decorations.call(plugin, editor.state)
+  if (!(set instanceof DecorationSet)) return []
+  return set.find().map((d) => [d.from, d.to])
+}
+
+describe('keeping the selection', () => {
+  it('draws nothing until asked', () => {
+    expect(keptSelection(editor)).toBeNull()
+    expect(drawn()).toEqual([])
+  })
+
+  it('draws the selection as it is when kept, and stops when released', () => {
+    keepSelection(editor)
+    expect(keptSelection(editor)).toEqual({ from: 10, to: 23 })
+    expect(drawn()).toEqual([[10, 23]])
+    releaseSelection(editor)
+    expect(keptSelection(editor)).toBeNull()
+    expect(drawn()).toEqual([])
+  })
+
+  it('follows the words through an edit before them', () => {
+    keepSelection(editor)
+    editor.commands.insertContentAt(1, 'X')
+    expect(keptSelection(editor)).toEqual({ from: 11, to: 24 })
+    expect(editor.state.doc.textBetween(11, 24)).toBe('widgets topic')
+  })
+
+  it('releasing with nothing kept dispatches nothing', () => {
+    const before = editor.state
+    releaseSelection(editor)
+    expect(editor.state).toBe(before)
+  })
+
+  it('an empty selection is kept but not drawn', () => {
+    editor.commands.setTextSelection(15)
+    keepSelection(editor)
+    expect(keptSelection(editor)).toEqual({ from: 15, to: 15 })
+    expect(drawn()).toEqual([])
+  })
+})