@estiva-app/ui 0.65.3 → 0.67.0

package/src/EditorTableControls.test.tsx

@@ -0,0 +1,288 @@
+// @vitest-environment jsdom
+/**
+ * A table's controls in an editor (RIC-21): what each row of the row and column
+ * menus and each ➕ bar does to the document, that new rows and cells get ids of
+ * their own, and that deleting a table's only row or column deletes the table.
+ * Where the controls sit is measured in real Chromium (the PR says how): jsdom
+ * lays nothing out.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { TableKit } from '@tiptap/extension-table'
+import { BlockId } from './BlockNodes'
+import { EditorTableControls, appendTableColumn, appendTableRow, deleteTableColumn, deleteTableRow } from './EditorTableControls'
+
+type Json = { type: string; attrs?: Record<string, unknown>; content?: Json[]; text?: string }
+
+const cell = (type: 'tableHeader' | 'tableCell', text: string): Json => ({ type, content: [{ type: 'paragraph', content: [{ type: 'text', text }] }] })
+const row = (type: 'tableHeader' | 'tableCell', ...texts: string[]): Json => ({ type: 'tableRow', content: texts.map((t) => cell(type, t)) })
+const table = (...rows: Json[]): object => ({ type: 'doc', content: [{ type: 'table', attrs: { blockId: 't1' }, content: rows }, { type: 'paragraph', content: [{ type: 'text', text: 'after' }] }] })
+const THREE = table(row('tableHeader', 'A', 'B', 'C'), row('tableCell', 'a1', 'b1', 'c1'), row('tableCell', 'a2', 'b2', 'c2'))
+
+const editors: Editor[] = []
+function editor(content: object = THREE, editable = true) {
+  const e = new Editor({ extensions: [StarterKit, TableKit.configure({ table: { resizable: false } }), BlockId], content, editable })
+  editors.push(e)
+  return e
+}
+
+/** The table as text, a row a line: `#` before a header cell. */
+function shape(e: Editor): string[] {
+  const t = (e.getJSON().content as Json[]).find((b) => b.type === 'table')
+  if (!t) return []
+  const text = (n: Json): string => n.text ?? (n.content ?? []).map(text).join('')
+  return (t.content ?? []).map((r) => (r.content ?? []).map((c) => (c.type === 'tableHeader' ? '#' : '') + text(c)).join('|'))
+}
+const cellOf = (text: string) => screen.getByText(text).closest('td, th') as HTMLTableCellElement
+const tableOf = (e: Editor) => e.view.dom.querySelector('table') as HTMLTableElement
+
+/** Every id under the table: rows and cells, each its own. */
+function ids(e: Editor): unknown[] {
+  const out: unknown[] = []
+  e.state.doc.descendants((n) => {
+    if (n.type.name.startsWith('table')) out.push(n.attrs.blockId)
+  })
+  return out
+}
+
+/** Press and release, as BlockHandle's test does: under jsdom `user.click` left a Base UI menu shut. */
+async function press(user: ReturnType<typeof userEvent.setup>, target: HTMLElement) {
+  await user.pointer({ keys: '[MouseLeft>]', target })
+  await user.pointer({ keys: '[/MouseLeft]', target })
+  await screen.findByRole('menu')
+}
+/**
+ * A click on a ➕ bar, with no pointer move before it. user-event moves the
+ * pointer first, and jsdom, with no layout, reports that move as leaving the
+ * frame (a `mouseleave` with no `relatedTarget`), which takes the bar away
+ * before its click. In Chromium the pointer reaches the bar from the cell (the
+ * PR says how).
+ */
+const tap = (target: HTMLElement) => act(async () => void fireEvent.click(target))
+/** The editor takes the focus back a frame later and measures the caret then. */
+const frame = () => act(() => new Promise<void>((done) => requestAnimationFrame(() => done())))
+/**
+ * `BlockId` gives the blocks their ids on the editor's `create`, a tick after it
+ * is made — which redraws every cell, so a cell found before it is no longer the
+ * editor's. Wait for it.
+ */
+const created = () => act(() => new Promise<void>((done) => setTimeout(done, 0)))
+
+beforeAll(() => {
+  const none = { top: 0, bottom: 0, left: 0, right: 0, width: 0, height: 0, x: 0, y: 0, toJSON: () => ({}) }
+  Range.prototype.getClientRects = () => [] as unknown as DOMRectList
+  Range.prototype.getBoundingClientRect = () => none as DOMRect
+})
+
+afterEach(() => {
+  cleanup()
+  for (const e of editors.splice(0)) e.destroy()
+})
+
+async function mount(e: Editor) {
+  const { EditorContent } = await import('@tiptap/react')
+  render(
+    <EditorTableControls editor={e}>
+      <EditorContent editor={e} />
+    </EditorTableControls>,
+  )
+  await created()
+  return userEvent.setup()
+}
+
+describe('the actions', () => {
+  it('a ➕ under the table adds an empty row after the last, of cells', () => {
+    const e = editor()
+    expect(appendTableRow(e, tableOf(e))).toBe(true)
+    expect(shape(e)).toEqual(['#A|#B|#C', 'a1|b1|c1', 'a2|b2|c2', '||'])
+  })
+
+  it('a ➕ right of the table adds an empty column after the last', () => {
+    const e = editor()
+    expect(appendTableColumn(e, tableOf(e))).toBe(true)
+    expect(shape(e)).toEqual(['#A|#B|#C|#', 'a1|b1|c1|', 'a2|b2|c2|'])
+  })
+
+  it('new rows and cells get ids of their own; the old ones keep theirs', async () => {
+    const e = editor()
+    await created()
+    const before = ids(e)
+    expect(before.every((id) => typeof id === 'string')).toBe(true)
+    appendTableRow(e, tableOf(e))
+    appendTableColumn(e, tableOf(e))
+    const after = ids(e)
+    expect(after.every((id) => typeof id === 'string' && id.length > 0)).toBe(true)
+    expect(new Set(after).size).toBe(after.length)
+    expect(before.every((id) => after.includes(id))).toBe(true)
+  })
+
+  it('deleting a row or a column leaves the rest as they were', async () => {
+    const e = editor()
+    await mount(e)
+    expect(deleteTableRow(e, cellOf('a1'))).toBe(true)
+    expect(deleteTableColumn(e, cellOf('B'))).toBe(true)
+    expect(shape(e)).toEqual(['#A|#C', 'a2|c2'])
+  })
+
+  it('Tab in the last cell adds a row; in another, moves to the next cell (TableKit’s own)', () => {
+    const e = editor()
+    const textAt = (text: string) => {
+      let at = -1
+      e.state.doc.descendants((n, pos) => {
+        if (n.isText && n.text === text) at = pos
+      })
+      return at
+    }
+    // The caret's row in the table, and its cell in the row.
+    const at = () => [e.state.selection.$from.index(1), e.state.selection.$from.index(2)]
+    // The key as the view gets it: `commands.keyboardShortcut` runs inside a command, whose own transaction then puts the selection back.
+    const press = (key: string, shiftKey = false) => e.view.someProp('handleKeyDown', (f) => f(e.view, new KeyboardEvent('keydown', { key, shiftKey })))
+    e.commands.setTextSelection(textAt('a1'))
+    press('Tab')
+    expect(at()).toEqual([1, 1])
+    press('Tab', true)
+    expect(at()).toEqual([1, 0])
+    e.commands.setTextSelection(textAt('c2'))
+    press('Tab')
+    expect(shape(e)).toEqual(['#A|#B|#C', 'a1|b1|c1', 'a2|b2|c2', '||'])
+    expect(at()).toEqual([3, 0])
+  })
+
+  it('deleting the only row, or the only column, deletes the table', async () => {
+    const one = editor(table(row('tableCell', 'x', 'y')))
+    await mount(one)
+    expect(deleteTableRow(one, cellOf('x'))).toBe(true)
+    expect(shape(one)).toEqual([])
+    cleanup()
+    const narrow = editor(table(row('tableCell', 'p'), row('tableCell', 'q')))
+    await mount(narrow)
+    expect(deleteTableColumn(narrow, cellOf('q'))).toBe(true)
+    expect(shape(narrow)).toEqual([])
+    expect(narrow.getText()).toContain('after')
+  })
+})
+
+describe('EditorTableControls', () => {
+  it('draws nothing until the pointer is on a cell', async () => {
+    const user = await mount(editor())
+    expect(screen.queryByRole('button', { name: 'Row menu' })).toBeNull()
+    await act(async () => user.hover(screen.getByText('after')))
+    expect(screen.queryByRole('button', { name: 'Row menu' })).toBeNull()
+    await act(async () => user.hover(screen.getByText('b1')))
+    expect(screen.getByRole('button', { name: 'Row menu' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Column menu' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: 'Add row' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Add column' })).toBeNull()
+  })
+
+  it('offers the ➕ under the table from the last row, and the one right of it from the last column', async () => {
+    const user = await mount(editor())
+    await act(async () => user.hover(screen.getByText('b2')))
+    expect(screen.getByRole('button', { name: 'Add row' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: 'Add column' })).toBeNull()
+    await act(async () => user.hover(screen.getByText('c1')))
+    expect(screen.queryByRole('button', { name: 'Add row' })).toBeNull()
+    expect(screen.getByRole('button', { name: 'Add column' })).toBeTruthy()
+    await act(async () => user.hover(screen.getByText('c2')))
+    expect(screen.getByRole('button', { name: 'Add row' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Add column' })).toBeTruthy()
+  })
+
+  it('the row menu inserts above and below the row pointed at, and deletes it', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('b1')))
+    await press(user, screen.getByRole('button', { name: 'Row menu' }))
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Insert above', 'Insert below', 'Delete', 'Delete table'])
+    await user.click(screen.getByRole('menuitem', { name: 'Insert below' }))
+    await frame()
+    expect(shape(e)).toEqual(['#A|#B|#C', 'a1|b1|c1', '||', 'a2|b2|c2'])
+
+    await act(async () => user.hover(screen.getByText('a2')))
+    await press(user, screen.getByRole('button', { name: 'Row menu' }))
+    await user.click(screen.getByRole('menuitem', { name: 'Delete' }))
+    await frame()
+    expect(shape(e)).toEqual(['#A|#B|#C', 'a1|b1|c1', '||'])
+  })
+
+  it('the column menu inserts left and right of the column pointed at, and deletes it', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('b2')))
+    await press(user, screen.getByRole('button', { name: 'Column menu' }))
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Insert left', 'Insert right', 'Delete', 'Delete table'])
+    await user.click(screen.getByRole('menuitem', { name: 'Insert left' }))
+    await frame()
+    expect(shape(e)).toEqual(['#A|#|#B|#C', 'a1||b1|c1', 'a2||b2|c2'])
+
+    await act(async () => user.hover(screen.getByText('c1')))
+    await press(user, screen.getByRole('button', { name: 'Column menu' }))
+    await user.click(screen.getByRole('menuitem', { name: 'Delete' }))
+    await frame()
+    expect(shape(e)).toEqual(['#A|#|#B', 'a1||b1', 'a2||b2'])
+  })
+
+  it('a header row offers nothing above it, and deleting it makes the next row the header', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('B')))
+    await press(user, screen.getByRole('button', { name: 'Row menu' }))
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Insert below', 'Delete', 'Delete table'])
+    await user.click(screen.getByRole('menuitem', { name: 'Delete' }))
+    await frame()
+    expect(shape(e)).toEqual(['#a1|#b1|#c1', 'a2|b2|c2'])
+  })
+
+  it('takes the controls away when the document changes without an update — someone else’s edit loaded', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('b1')))
+    expect(screen.getByRole('button', { name: 'Row menu' })).toBeTruthy()
+    await act(async () => void e.commands.setContent(THREE, { emitUpdate: false }))
+    expect(screen.queryByRole('button', { name: 'Row menu' })).toBeNull()
+  })
+
+  it('Delete table removes the table and keeps the text after it', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('a1')))
+    await press(user, screen.getByRole('button', { name: 'Row menu' }))
+    await user.click(screen.getByRole('menuitem', { name: 'Delete table' }))
+    await frame()
+    expect(shape(e)).toEqual([])
+    expect(e.getText()).toContain('after')
+  })
+
+  it('the ➕ bars add a row and a column at the end', async () => {
+    const e = editor()
+    const user = await mount(e)
+    await act(async () => user.hover(screen.getByText('a2')))
+    // The press keeps the focus in the field, so a field that saves on leaving does not save half-way: `false` is a prevented default.
+    expect(fireEvent.mouseDown(screen.getByRole('button', { name: 'Add row' }))).toBe(false)
+    await tap(screen.getByRole('button', { name: 'Add row' }))
+    await frame()
+    await act(async () => user.hover(screen.getByText('c1')))
+    await tap(screen.getByRole('button', { name: 'Add column' }))
+    await frame()
+    expect(shape(e)).toEqual(['#A|#B|#C|#', 'a1|b1|c1|', 'a2|b2|c2|', '|||'])
+  })
+
+  it('an editor that cannot be edited gets no controls', async () => {
+    const user = await mount(editor(THREE, false))
+    await act(async () => user.hover(screen.getByText('b1')))
+    expect(screen.queryByRole('button', { name: 'Row menu' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Add row' })).toBeNull()
+  })
+
+  it('draws nothing before its editor exists', () => {
+    render(
+      <EditorTableControls editor={null}>
+        <p>text</p>
+      </EditorTableControls>,
+    )
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+})

package/src/EditorTableControls.tsx

@@ -0,0 +1,255 @@
+import { useCallback, useEffect, useRef, useState, type MouseEvent, type ReactNode } from 'react'
+import type { Editor } from '@tiptap/core'
+import { TextSelection, type Command } from '@tiptap/pm/state'
+import { addColumnAfter, addColumnBefore, addRowAfter, addRowBefore, deleteColumn, deleteRow, deleteTable, toggleHeader } from '@tiptap/pm/tables'
+import { IconColumnInsertLeft, IconColumnInsertRight, IconGripHorizontal, IconGripVertical, IconPlus, IconRowInsertBottom, IconRowInsertTop, IconTrash } from '@tabler/icons-react'
+import { cn } from './cn'
+import { IconButton } from './IconButton'
+import { FLOATING_SURFACE_CLASSES } from './looks'
+import { Menu, MenuItem, MenuSeparator } from './Menu'
+
+export interface EditorTableControlsProps {
+  /** The editor, with TableKit (`@tiptap/extension-table`) in its extensions. Not editable, or not there yet: no controls. */
+  editor: Editor | null
+  /** The `EditorContent`. */
+  children: ReactNode
+  className?: string
+}
+
+/** The cell the pointer is on, and the table and row it is in. */
+interface Hovered {
+  table: HTMLTableElement
+  row: HTMLTableRowElement
+  cell: HTMLTableCellElement
+}
+
+/** Where the controls go, measured from the frame: they depend on the document, not on a size of ours. */
+interface Placed {
+  tableBox: { top: number; left: number; width: number; height: number }
+  rowBox: { top: number; height: number }
+  columnBox: { left: number; width: number }
+}
+
+/*
+  Every row runs the table command with the caret in a cell, as the command
+  expects — the hovered cell's, or for a ➕ bar the last row's or the last
+  column's — and leaves the editor focused there, as the block menu does: the
+  person is still in the field, so an editor that saves when they leave it
+  saves this too.
+*/
+
+/** Puts the caret in `cell` and runs `command` there. */
+function inCell(editor: Editor, cell: HTMLTableCellElement, command: Command): boolean {
+  const { view } = editor
+  if (!view.dom.contains(cell)) return false
+  const at = view.posAtDOM(cell, 0)
+  view.dispatch(view.state.tr.setSelection(TextSelection.near(view.state.doc.resolve(at))))
+  const done = command(view.state, view.dispatch, view)
+  editor.commands.focus()
+  return done
+}
+
+/** A row of header cells only: the table's header row. */
+function isHeaderRow(row: HTMLTableRowElement): boolean {
+  return row.cells.length > 0 && Array.from(row.cells).every((c) => c.tagName === 'TH')
+}
+
+/**
+ * The cell's row, or the whole table when it is its only one: a table holds at
+ * least one row (prosemirror-tables refuses to delete it). Deleting the header
+ * row makes the next row the header, so the table still opens with one.
+ */
+export function deleteTableRow(editor: Editor, cell: HTMLTableCellElement): boolean {
+  const row = cell.closest('tr')
+  const table = cell.closest('table')
+  if (!row || !table || table.rows.length <= 1) return inCell(editor, cell, deleteTable)
+  const header = isHeaderRow(row)
+  return inCell(editor, cell, header ? (state, dispatch, view) => deleteRow(state, dispatch) && (!view || toggleHeader('row')(view.state, view.dispatch)) : deleteRow)
+}
+
+/** The same for a column: the last one deletes the table. */
+export function deleteTableColumn(editor: Editor, cell: HTMLTableCellElement): boolean {
+  const row = cell.closest('tr')
+  return inCell(editor, cell, row && row.cells.length > 1 ? deleteColumn : deleteTable)
+}
+
+/** A row after the last one: the ➕ under the table. */
+export function appendTableRow(editor: Editor, table: HTMLTableElement): boolean {
+  const last = table.rows[table.rows.length - 1]?.cells[0]
+  return !!last && inCell(editor, last, addRowAfter)
+}
+
+/** A column after the last one: the ➕ right of the table. */
+export function appendTableColumn(editor: Editor, table: HTMLTableElement): boolean {
+  const first = table.rows[0]
+  const last = first?.cells[first.cells.length - 1]
+  return !!last && inCell(editor, last, addColumnAfter)
+}
+
+function place(frame: HTMLElement, { table, row, cell }: Hovered): Placed {
+  const at = frame.getBoundingClientRect()
+  const t = table.getBoundingClientRect()
+  const r = row.getBoundingClientRect()
+  const c = cell.getBoundingClientRect()
+  return {
+    tableBox: { top: t.top - at.top, left: t.left - at.left, width: t.width, height: t.height },
+    rowBox: { top: r.top - at.top, height: r.height },
+    columnBox: { left: c.left - at.left, width: c.width },
+  }
+}
+
+const ICON = { size: 16, stroke: 1.5, className: 'text-text-secondary' } as const
+
+/**
+ * A ➕ press keeps the focus where it is, as the selection toolbar's buttons do:
+ * the person never left the field, so an editor that saves when they leave it
+ * does not save half-way, and History gets one line for the edit, not one per
+ * press. (A handle's menu takes the focus, as every menu does.)
+ */
+const keepFocus = (e: MouseEvent) => e.preventDefault()
+
+/** What a handle and a ➕ bar sit in: the elevated surface's border and fill, opaque over the table's lines, with no shadow at this size. */
+const HANDLE_BOX = cn(FLOATING_SURFACE_CLASSES, 'shadow-none')
+
+/**
+ * A table's own controls in an editor, as in Notion: point at a cell and a
+ * handle sits on its row's left edge and on its column's top edge; press one
+ * for Insert above and below (left and right), Delete, and Delete table. On
+ * the last row a ➕ bar under the table adds a row, and on the last column one
+ * right of it adds a column. Tab in
+ * the last cell adds a row too — that is TableKit's own.
+ *
+ * Deleting a table's only row or only column deletes the table, which cannot
+ * be left with none.
+ *
+ * Built on the editor library's own table commands; the controls are ours.
+ * Wrap the `EditorContent` in it, inside an `EditorBlockHandle` if there is
+ * one: the block handle stays the table's, in the gutter.
+ */
+export function EditorTableControls({ editor, children, className }: EditorTableControlsProps) {
+  const frame = useRef<HTMLDivElement>(null)
+  // The cell pointed at and where its controls go, as one: the boxes mean nothing without their elements.
+  const [hovered, setHovered] = useState<(Hovered & Placed) | null>(null)
+  // A menu that is up keeps its row and column, wherever the pointer goes.
+  const [menu, setMenu] = useState<'row' | 'column' | null>(null)
+  const editable = !!editor && editor.isEditable
+
+  const follow = useCallback(
+    (target: EventTarget | null) => {
+      if (!editor || !frame.current || !(target instanceof Element)) return
+      // On a control of ours: keep what it was drawn for.
+      if (target.closest('[data-table-control]')) return
+      const cell = target.closest<HTMLTableCellElement>('td, th')
+      const row = cell?.closest('tr')
+      const table = row?.closest('table')
+      if (!cell || !row || !table || !editor.view.dom.contains(table)) {
+        setHovered(null)
+        return
+      }
+      // Measured on every move, the same cell too: a panel resized or a cell's text wrapping moves the edges under a still pointer.
+      const next = { table, row, cell, ...place(frame.current, { table, row, cell }) }
+      setHovered((was) => (was && was.cell === cell && JSON.stringify([was.tableBox, was.rowBox, was.columnBox]) === JSON.stringify([next.tableBox, next.rowBox, next.columnBox]) ? was : next))
+    },
+    [editor],
+  )
+
+  /*
+    Any change to the document moves everything under the controls, so they go
+    until the pointer moves again: a row added or deleted here, and someone
+    else's edit loaded into the field — which an app does without an `update`
+    (`emitUpdate: false`), and which redraws the cells the controls point at.
+  */
+  useEffect(() => {
+    if (!editor) return
+    const changed = ({ transaction }: { transaction: { docChanged: boolean } }) => {
+      if (transaction.docChanged && !menu) setHovered(null)
+    }
+    editor.on('transaction', changed)
+    return () => {
+      editor.off('transaction', changed)
+    }
+  }, [editor, menu])
+
+  const shown = editable ? hovered : null
+  const run = (act: () => boolean) => () => {
+    if (editor) act()
+    setMenu(null)
+    setHovered(null)
+  }
+
+  return (
+    <div
+      ref={frame}
+      className={cn('relative', className)}
+      onMouseMove={(e) => {
+        if (!menu) follow(e.target)
+      }}
+      onMouseLeave={() => {
+        if (!menu) setHovered(null)
+      }}
+    >
+      {children}
+      {shown && editor && (
+        <>
+          {/* The row's handle, centred on the table's left edge: the box is ours, so the table's line does not show through it. */}
+          <div data-table-control className={cn(HANDLE_BOX, 'absolute -translate-x-1/2 -translate-y-1/2')} style={{ left: shown.tableBox.left, top: shown.rowBox.top + shown.rowBox.height / 2 }}>
+            <Menu
+              open={menu === 'row'}
+              onOpenChange={(open) => setMenu(open ? 'row' : null)}
+              trigger={
+                <IconButton aria-label="Row menu" tooltip="Row" className="h-6 w-4 p-0">
+                  <IconGripVertical size={16} stroke={1.5} />
+                </IconButton>
+              }
+            >
+              {/* Nothing goes above a header row: it is the table's first row, and a header anywhere else is no header (RichText, the agent's text). */}
+              {!isHeaderRow(shown.row) && <MenuItem label="Insert above" leading={<IconRowInsertTop {...ICON} />} onClick={run(() => inCell(editor, shown.cell, addRowBefore))} />}
+              <MenuItem label="Insert below" leading={<IconRowInsertBottom {...ICON} />} onClick={run(() => inCell(editor, shown.cell, addRowAfter))} />
+              <MenuSeparator />
+              <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={run(() => deleteTableRow(editor, shown.cell))} />
+              <MenuItem label="Delete table" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={run(() => inCell(editor, shown.cell, deleteTable))} />
+            </Menu>
+          </div>
+          {/* The column's handle, centred on the table's top edge. */}
+          <div data-table-control className={cn(HANDLE_BOX, 'absolute -translate-x-1/2 -translate-y-1/2')} style={{ left: shown.columnBox.left + shown.columnBox.width / 2, top: shown.tableBox.top }}>
+            <Menu
+              open={menu === 'column'}
+              onOpenChange={(open) => setMenu(open ? 'column' : null)}
+              trigger={
+                <IconButton aria-label="Column menu" tooltip="Column" className="h-4 w-6 p-0">
+                  <IconGripHorizontal size={16} stroke={1.5} />
+                </IconButton>
+              }
+            >
+              <MenuItem label="Insert left" leading={<IconColumnInsertLeft {...ICON} />} onClick={run(() => inCell(editor, shown.cell, addColumnBefore))} />
+              <MenuItem label="Insert right" leading={<IconColumnInsertRight {...ICON} />} onClick={run(() => inCell(editor, shown.cell, addColumnAfter))} />
+              <MenuSeparator />
+              <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={run(() => deleteTableColumn(editor, shown.cell))} />
+              <MenuItem label="Delete table" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={run(() => inCell(editor, shown.cell, deleteTable))} />
+            </Menu>
+          </div>
+          {/*
+            The ➕ bars, flush with the table so the pointer reaches them from a
+            cell without leaving it — the row's from the last row, the column's
+            from the last column. Anywhere else the one under the table would
+            lie over the top of the next block for nothing.
+          */}
+          {shown.row === shown.table.rows[shown.table.rows.length - 1] && (
+            <div data-table-control className={cn(HANDLE_BOX, 'absolute flex h-4')} style={{ left: shown.tableBox.left, top: shown.tableBox.top + shown.tableBox.height, width: shown.tableBox.width }}>
+              <IconButton aria-label="Add row" tooltip="Add row" className="h-full w-full p-0" onMouseDown={keepFocus} onClick={run(() => appendTableRow(editor, shown.table))}>
+                <IconPlus size={12} stroke={1.5} />
+              </IconButton>
+            </div>
+          )}
+          {shown.cell === shown.row.cells[shown.row.cells.length - 1] && (
+            <div data-table-control className={cn(HANDLE_BOX, 'absolute flex w-4')} style={{ left: shown.tableBox.left + shown.tableBox.width, top: shown.tableBox.top, height: shown.tableBox.height }}>
+              <IconButton aria-label="Add column" tooltip="Add column" className="h-full w-full p-0" onMouseDown={keepFocus} onClick={run(() => appendTableColumn(editor, shown.table))}>
+                <IconPlus size={12} stroke={1.5} />
+              </IconButton>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}

package/src/NavItem.mdx

@@ -30,6 +30,14 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithMenu} />
 
+- One thing done often enough to stay in sight — take the row off a list —
+  is `action`: an icon, its tooltip and its handler, the shape of a
+  **SectionHeader**'s actions. It shows with the ⋮, in the count's place, and
+  before the ⋮ when the row has a menu too. One, never a row of them: a second
+  thing to do goes in the menu.
+
+<Canvas of={NavItemStories.WithAction} />
+
 - 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
@@ -77,6 +85,8 @@ 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.
+- `action` is `{ icon, tooltip, onClick }`: `action={{ icon: <IconX size={16} stroke={1.5} />, tooltip: 'Remove from list', onClick: remove }}`.
+  Its name is `{tooltip}: {label}`.
 - `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}`.

package/src/NavItem.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconSquareRounded } from '@tabler/icons-react'
+import { IconSquareRounded, IconX } from '@tabler/icons-react'
 import { Chip } from './Chip'
 import { MenuItem } from './Menu'
 import { NavItem } from './NavItem'
@@ -109,3 +109,25 @@ export const UnreadUrgent: Story = {
 export const UnreadWithMenu: Story = {
   args: { icon: placeholder, unread: true, menu: MENU },
 }
+
+const REMOVE = { icon: <IconX size={16} stroke={1.5} />, tooltip: 'Remove from list', onClick: () => {} }
+
+/** One button of its own, in sight rather than in a menu: point at the row and it takes the count's place, as the ⋮ does. */
+export const WithAction: Story = {
+  args: { icon: placeholder, action: REMOVE },
+}
+
+/** The button and the ⋮ together: the button sits before it, and a long label stops short of both. */
+export const WithActionAndMenu: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, action: REMOVE, menu: MENU },
+}
+
+/** A hint and a button: point at it and the chip shows, then the button — a row whose state is a word (here, archived) and which can be taken off the list. */
+export const WithActionAndHint: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, action: REMOVE, hint: <Chip type="neutral" label="Archived" /> },
+}
+
+/** Unread, with a button: point at it and the button lands on the dot. */
+export const UnreadWithAction: Story = {
+  args: { icon: placeholder, unread: true, action: REMOVE },
+}

package/src/NavItem.test.tsx

@@ -141,3 +141,39 @@ describe('NavItem unread', () => {
     expect(menu?.className).toContain('right-1')
   })
 })
+
+describe('NavItem with a button of its own', () => {
+  const remove = (onClick = () => {}) => ({ icon: <svg />, tooltip: 'Remove from list', onClick })
+
+  it('draws the button beside the link, named for its row, and a click runs it, not the link', async () => {
+    const onClick = vi.fn()
+    const onLink = vi.fn()
+    render(<NavItem href="#" label="Item one" action={remove(onClick)} onClick={onLink} />)
+    const button = screen.getByRole('button', { name: 'Remove from list: Item one' })
+    expect(button.closest('a')).toBeNull()
+    await userEvent.click(button)
+    expect(onClick).toHaveBeenCalledOnce()
+    expect(onLink).not.toHaveBeenCalled()
+  })
+
+  it('shows with the row, as the ⋮ does: in its place at right-1, always on a screen with no hover', () => {
+    render(<NavItem href="#" label="Item one" action={remove()} />)
+    const box = screen.getByRole('button', { name: 'Remove from list: Item one' }).closest('[data-nav-menu]')!
+    expect(box.className.split(' ')).toEqual(expect.arrayContaining(['right-1', 'opacity-0', 'group-hover/nav:opacity-100', '[@media(hover:none)]:opacity-100']))
+  })
+
+  it('with a menu too, sits before the ⋮, and the row keeps room for both while they show', () => {
+    const { container } = render(<NavItem href="#" label="Item one" action={remove()} menu={<span>Action</span>} />)
+    const buttons = [...container.querySelectorAll('[data-nav-menu] button')].map((b) => b.getAttribute('aria-label'))
+    expect(buttons).toEqual(['Remove from list: Item one', 'More options for Item one'])
+    const kept = [...container.querySelectorAll('a > [aria-hidden="true"]')].map((s) => s.className.split(' '))
+    expect(kept).toHaveLength(2)
+    expect(kept[0]).toContain('w-5')
+    expect(kept[1]).toContain('w-6')
+  })
+
+  it('lands on the dot, which steps aside for it', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread action={remove()} />)
+    expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('group-hover/nav:opacity-0')
+  })
+})