@estiva-app/ui 0.69.2 → 0.71.0

package/src/EditorBlockHandle.tsx

@@ -4,13 +4,19 @@ import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import type { EditorView } from '@tiptap/pm/view'
 import { IconCopy, IconTrash } from '@tabler/icons-react'
 import { BlockHandle, blockAtY, type BlockHandleEditing, type HandleBlock } from './BlockHandle'
+import { Selection } from '@tiptap/pm/state'
 import { MenuItem, MenuSub } from './Menu'
+import { DOCUMENT_FORMATS, FORMATS, applyFormat, type FormatId } from './ComposerTriggers'
 
 /** A row of the block menu's Turn into: what the block becomes. */
 export interface BlockTurnInto {
   label: string
-  /** Turns the block the caret is in. The handle puts the caret there first. */
-  run: (editor: Editor) => void
+  /**
+   * Turns the block. The handle puts the caret in a block of text first, so a
+   * row for one can act at the caret; `pos` is where the block starts, for a
+   * list or a quote, whose row acts on the whole block.
+   */
+  run: (editor: Editor, pos: number) => void
   /** Whether the block already is this — drawn as the selected row. */
   active?: (node: ProseMirrorNode) => boolean
 }
@@ -18,8 +24,12 @@ export interface BlockTurnInto {
 export interface EditorBlockHandleProps {
   /** The editor. Not editable, or not there yet, and the handle reads: the caller's rows only. */
   editor: Editor | null
-  /** Turn into's rows. Offered for a block of text — a paragraph, a heading, code. */
-  turnInto?: readonly BlockTurnInto[]
+  /**
+   * Turn into's rows for a block. By default `turnIntoRows`, the same in every
+   * app: a block of text, a list and a quote each get theirs. A list of rows
+   * instead is offered for a block of text only; `[]` offers none.
+   */
+  turnInto?: readonly BlockTurnInto[] | ((node: ProseMirrorNode, editor: Editor) => readonly BlockTurnInto[])
   /** The caller's own rows, after the editing ones. */
   actions?: (block: HandleBlock) => ReactNode
   /** The `EditorContent`. */
@@ -116,7 +126,7 @@ const NOTHING_YET: BlockHandleEditing = { find: () => null, rows: () => null, st
  * `BlockHandle` in an editor: drag the handle to move the block, and the menu
  * gains Turn into, Duplicate and Delete before the caller's rows.
  */
-export function EditorBlockHandle({ editor, turnInto = [], actions, children, className }: EditorBlockHandleProps) {
+export function EditorBlockHandle({ editor, turnInto = turnIntoRows, actions, children, className }: EditorBlockHandleProps) {
   const editing = useMemo<BlockHandleEditing>(() => {
     // Before the editor exists there is no block to find — not the editor's whole element read as one.
     if (!editor) return NOTHING_YET
@@ -130,19 +140,20 @@ export function EditorBlockHandle({ editor, turnInto = [], actions, children, cl
         if (!editor.isEditable) return null
         const node = pos === undefined ? null : editor.state.doc.nodeAt(pos)
         if (pos === undefined || !node) return null
+        const turnRows = typeof turnInto === 'function' ? turnInto(node, editor) : node.isTextblock ? turnInto : []
         return (
           <>
-            {node.isTextblock && turnInto.length > 0 && (
+            {turnRows.length > 0 && (
               <MenuSub label="Turn into">
-                {turnInto.map((row) => (
+                {turnRows.map((row) => (
                   <MenuItem
                     key={row.label}
                     label={row.label}
                     selected={row.active?.(node) ?? false}
                     onClick={() => {
-                      // Inside the block's text, so the row's command turns this block and no other.
-                      editor.chain().focus().setTextSelection(pos + 1).run()
-                      row.run(editor)
+                      // Inside a block of text, so a row's command at the caret turns this block and no other.
+                      if (node.isTextblock) editor.chain().focus().setTextSelection(pos + 1).run()
+                      row.run(editor, pos)
                     }}
                   />
                 ))}
@@ -179,3 +190,163 @@ export function EditorBlockHandle({ editor, turnInto = [], actions, children, cl
     </BlockHandle>
   )
 }
+
+const LISTS = ['bulletList', 'orderedList']
+const isList = (node: ProseMirrorNode) => LISTS.includes(node.type.name)
+
+/** Every item of a list, the ones nested under an item too — the editor nests what §13.3 keeps flat (MAN-13). */
+function listItems(list: ProseMirrorNode, at: number): { node: ProseMirrorNode; pos: number }[] {
+  const out: { node: ProseMirrorNode; pos: number }[] = []
+  list.descendants((node, pos) => {
+    if (node.type.name === 'listItem') out.push({ node, pos: at + 1 + pos })
+  })
+  return out
+}
+
+const isChecklistItem = ({ node }: { node: ProseMirrorNode }) => typeof node.attrs.checked === 'boolean'
+/** Whether every item of the list is a checklist item. */
+const isChecklist = (list: ProseMirrorNode) => listItems(list, 0).every(isChecklistItem)
+/** A list of that type with no checklist item in it — a list partly ticked is neither, so no row reads as "nothing changes". */
+const isPlainList = (list: ProseMirrorNode, type: string) => list.type.name === type && !listItems(list, 0).some(isChecklistItem)
+
+const hasExtension = (editor: Editor, name: string) => editor.extensionManager.extensions.some((e) => e.name === name)
+
+/** The caret back in the block, the editor still focused — as Duplicate and Delete leave it, so a save on leaving saves this too. */
+function caretInto(editor: Editor, pos: number) {
+  const { state } = editor
+  editor.view.dispatch(state.tr.setSelection(Selection.near(state.doc.resolve(Math.min(pos + 1, state.doc.content.size)))))
+  editor.commands.focus()
+}
+
+export type ListKind = 'bulletList' | 'orderedList' | 'checklist' | 'text'
+
+/**
+ * Turns the whole list at `pos`, every item, the nested ones too.
+ *
+ * - **Bulleted, Numbered:** the list's own type changes and its attributes
+ *   stay, so it keeps its id; every item's tick goes. Not Tiptap's
+ *   `toggleList`, which makes the list anew — a fresh id, detaching every
+ *   comment anchored to it — and then joins it into a list of that type next
+ *   to it.
+ * - **Checklist:** every item a checklist item, the list's type as it was; an
+ *   item already one keeps its tick.
+ *
+ * The kind it already is changes nothing — no edit, no undo step.
+ * - **Text:** each item becomes a paragraph that takes the item's id, as
+ *   lifting an item out does (MAN-12). The list's own id goes with the list.
+ *
+ * `false` when there is no list at `pos`.
+ */
+export function turnListInto(editor: Editor, pos: number, kind: ListKind): boolean {
+  const { state } = editor
+  const list = state.doc.nodeAt(pos)
+  if (!list || !isList(list)) return false
+  const tr = state.tr
+  if (kind === 'text') {
+    const blocks: ProseMirrorNode[] = []
+    for (const { node: item } of listItems(list, pos)) {
+      item.forEach((child, _offset, index) => {
+        // Its nested list's items are in `listItems` already.
+        if (isList(child)) return
+        // The item's first block takes its id; any other gets one of its own from `BlockId`.
+        blocks.push(child.type.create({ ...child.attrs, blockId: index === 0 ? item.attrs.blockId : null }, child.content, child.marks))
+      })
+    }
+    tr.replaceWith(pos, pos + list.nodeSize, blocks)
+  } else {
+    // A checklist stays the list type it is: §13.3 ticks items of either.
+    const type = kind === 'checklist' ? list.type : state.schema.nodes[kind]
+    // The list and the lists nested in it, one type throughout: §13.3's indented items are their list's type.
+    if (list.type !== type) tr.setNodeMarkup(pos, type, list.attrs)
+    list.descendants((node, at) => {
+      if (isList(node) && node.type !== type) tr.setNodeMarkup(pos + 1 + at, type, node.attrs)
+    })
+    for (const { node, pos: at } of listItems(list, pos)) {
+      const checked = kind === 'checklist' ? (typeof node.attrs.checked === 'boolean' ? node.attrs.checked : false) : null
+      if (node.attrs.checked !== checked) tr.setNodeAttribute(at, 'checked', checked)
+    }
+  }
+  // The row it already is changes nothing: no edit to save, no step to undo.
+  if (tr.docChanged) editor.view.dispatch(tr.scrollIntoView())
+  caretInto(editor, pos)
+  return true
+}
+
+export type QuoteKind = 'quote' | 'note' | 'warning' | 'text'
+
+/**
+ * Turns the quote at `pos`: a plain quote, a Note or Warning callout (the
+ * tone changes, the id stays), or its text, whose first paragraph takes the
+ * quote's id, as lifting it out does (MAN-12). `false` when there is no quote
+ * at `pos`.
+ */
+export function turnQuoteInto(editor: Editor, pos: number, kind: QuoteKind): boolean {
+  const { state } = editor
+  const quote = state.doc.nodeAt(pos)
+  if (!quote || quote.type.name !== 'blockquote') return false
+  const tr = state.tr
+  if (kind === 'text') {
+    const blocks: ProseMirrorNode[] = []
+    quote.forEach((child) => blocks.push(blocks.length === 0 ? child.type.create({ ...child.attrs, blockId: quote.attrs.blockId }, child.content, child.marks) : child))
+    tr.replaceWith(pos, pos + quote.nodeSize, blocks)
+  } else {
+    const tone = kind === 'quote' ? null : kind
+    if ((quote.attrs.tone ?? null) !== tone) tr.setNodeAttribute(pos, 'tone', tone)
+  }
+  if (tr.docChanged) editor.view.dispatch(tr.scrollIntoView())
+  caretInto(editor, pos)
+  return true
+}
+
+function isFormat(node: ProseMirrorNode, id: FormatId): boolean {
+  if (id === 'paragraph') return node.type.name === 'paragraph'
+  if (id === 'heading') return node.type.name === 'heading' && node.attrs.level === 1
+  if (id === 'subheading') return node.type.name === 'heading' && node.attrs.level === 2
+  if (id === 'code') return node.type.name === 'codeBlock'
+  return false
+}
+
+/**
+ * The block menu's Turn into for one block, the same in every app (Miky,
+ * LEAF-11's kickoff, 15 October):
+ *
+ * - **A block of text** — a paragraph, a heading, code: the `/` menu's Format
+ *   rows, code as a block, and Checklist, Note and Warning where the editor
+ *   has `Checklist` and `Callout`.
+ * - **A list:** Bulleted list, Numbered list, Checklist (with `Checklist`), Text.
+ * - **A quote:** Quote, Note, Warning (with `Callout`), Text.
+ *
+ * Anything else — a table, an attachment — none. Each keeps the block's text
+ * and its id, and so the comments anchored to it.
+ */
+export function turnIntoRows(node: ProseMirrorNode, editor: Editor): readonly BlockTurnInto[] {
+  const checklist = hasExtension(editor, 'checklist')
+  const callout = hasExtension(editor, 'callout')
+  if (node.isTextblock) {
+    const document = DOCUMENT_FORMATS.filter((f) => (f.id === 'checklist' ? checklist : callout))
+    return [...FORMATS, ...document].map((format) => ({
+      label: format.label,
+      run: (e) => void applyFormat(e, format.id, 'block'),
+      active: (n) => isFormat(n, format.id),
+    }))
+  }
+  if (isList(node)) {
+    const rows: BlockTurnInto[] = [
+      { label: 'Bulleted list', run: (e, pos) => void turnListInto(e, pos, 'bulletList'), active: (n) => isPlainList(n, 'bulletList') },
+      { label: 'Numbered list', run: (e, pos) => void turnListInto(e, pos, 'orderedList'), active: (n) => isPlainList(n, 'orderedList') },
+    ]
+    if (checklist) rows.push({ label: 'Checklist', run: (e, pos) => void turnListInto(e, pos, 'checklist'), active: isChecklist })
+    rows.push({ label: 'Text', run: (e, pos) => void turnListInto(e, pos, 'text') })
+    return rows
+  }
+  if (node.type.name === 'blockquote') {
+    const rows: BlockTurnInto[] = [{ label: 'Quote', run: (e, pos) => void turnQuoteInto(e, pos, 'quote'), active: (n) => !n.attrs.tone }]
+    if (callout) {
+      rows.push({ label: 'Note', run: (e, pos) => void turnQuoteInto(e, pos, 'note'), active: (n) => n.attrs.tone === 'note' })
+      rows.push({ label: 'Warning', run: (e, pos) => void turnQuoteInto(e, pos, 'warning'), active: (n) => n.attrs.tone === 'warning' })
+    }
+    rows.push({ label: 'Text', run: (e, pos) => void turnQuoteInto(e, pos, 'text') })
+    return rows
+  }
+  return []
+}

package/src/LinkChips.ts

@@ -17,6 +17,8 @@
  * half-typed address never turns into a chip under the person's fingers. A
  * pasted URL is whole, so it is asked about and made a chip at once, the caret
  * still at its end — where `ReferenceMenu` opens its menu.
+ *
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-link-is-stored-as-the-url-a-person-wrote.md
  */
 import { Extension, type Editor } from '@tiptap/core'
 import { closeHistory } from '@tiptap/pm/history'

package/src/PastedMarkdown.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as PastedMarkdownStories from './PastedMarkdown.stories'
+
+<Meta of={PastedMarkdownStories} />
+
+# PastedMarkdown
+
+Markdown pasted into an editor as plain text lands as what it spells: a
+heading, a list, a checklist, a quote or callout, a table. A README's source or
+an answer copied from a chat arrives formatted, not full of `#` and `|`.
+
+<Canvas of={PastedMarkdownStories.InAnEditor} />
+
+## When
+
+- **An editor that saves a block document**: a page, a description. Give it
+  the protocol's reader, so a paste reads text the way everything else that
+  writes a block document does.
+
+## When not
+
+No alternative: a message box or a comment box leaves it out and pastes text
+as typed, because a message's text has no table.
+
+- A pasted picture → `PastedImages`.
+- A pasted URL that names something in the app → `LinkChips`.
+
+## How
+
+```tsx
+import StarterKit from '@tiptap/starter-kit'
+import { TableKit } from '@tiptap/extension-table'
+import { PastedMarkdown } from '@estiva-app/ui/editor'
+
+useEditor({
+  extensions: [
+    StarterKit,
+    TableKit,
+    PastedMarkdown.configure({
+      // Both from @estiva-app/protocol, which this package does not depend on.
+      read: (text) => toEditorDocument(descriptionTextToBlockDocument(text)),
+    }),
+  ],
+})
+```
+
+- **Only plain text is read.** A paste that carries HTML, a copy from a web
+  page, keeps the browser's own structure.
+- **Text that spells only paragraphs pastes exactly as before**, into the line
+  the caret is on.
+- **Ctrl/Cmd+Shift+V keeps the text as typed**, and so does a paste into code.
+- A table pasted inside a table cell stays text, and so does any block the
+  editor cannot hold (a table, in an editor without `TableKit`).
+- How text is read is the app's reader. When it lands, and when it stays
+  text, is this part's.
+
+## What it owns
+
+Nothing. It draws nothing; it hands pasted text to the app's reader and puts back what that reads.

package/src/PastedMarkdown.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { JSONContent } from '@tiptap/core'
+import { TableKit } from '@tiptap/extension-table'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { Button } from './Button'
+import { Card } from './Card'
+import { PastedMarkdown } from './PastedMarkdown'
+import { richTextClassName } from './RichText'
+
+/**
+ * "Copy as plain text" puts the lines below the box on the clipboard as plain
+ * text; paste them in and they land as a table. Paste them with
+ * Ctrl/Cmd+Shift+V: they stay text.
+ */
+const meta = {
+  title: 'Primitives/PastedMarkdown',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const SAMPLE = '| Item | Value |\n| --- | --- |\n| One | 1 |\n| Two | 2 |'
+
+/*
+  A stand-in for the app's reader, which is the protocol's and reads every
+  block text spells. This one reads a table and nothing else, enough to show
+  the paste.
+*/
+function readTable(text: string): JSONContent | undefined {
+  const lines = text.trim().split('\n')
+  if (lines.length < 2 || !/^\|( *:?-+:? *\|)+$/.test(lines[1].trim())) return undefined
+  const cells = (line: string) => line.trim().replace(/^\||\|$/g, '').split('|').map((cell) => cell.trim())
+  const cell = (type: string, text: string): JSONContent => ({ type, content: [{ type: 'paragraph', content: text ? [{ type: 'text', text }] : [] }] })
+  const rows = [lines[0], ...lines.slice(2)].map((line, r) => ({ type: 'tableRow', content: cells(line).map((text) => cell(r === 0 ? 'tableHeader' : 'tableCell', text)) }))
+  return { type: 'doc', content: [{ type: 'table', content: rows }] }
+}
+
+function Box() {
+  const editor = useEditor({
+    extensions: [StarterKit, TableKit, PastedMarkdown.configure({ read: readTable })],
+    content: '<p>Paste here.</p>',
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <div className="flex w-[520px] flex-col gap-3">
+      <Card fill="surface" className="p-3">
+        <EditorContent editor={editor} />
+      </Card>
+      <pre className="text-caption text-text-secondary">{SAMPLE}</pre>
+      <div className="flex items-center gap-2">
+        <Button variant="outlined" size="small" onClick={() => void navigator.clipboard.writeText(SAMPLE)}>
+          Copy as plain text
+        </Button>
+        <span className="text-caption text-text-secondary">then paste in the box. Selecting the lines above copies them with HTML, which pastes as before.</span>
+      </div>
+    </div>
+  )
+}
+
+export const InAnEditor: Story = { render: () => <Box /> }

package/src/PastedMarkdown.test.ts

@@ -0,0 +1,134 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Editor, type JSONContent } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { TableKit } from '@tiptap/extension-table'
+import { PastedMarkdown } from './PastedMarkdown'
+
+const TABLE_TEXT = '| Name | Since |\n| --- | --- |\n| Ada | 2026 |'
+const paragraph = (text: string): JSONContent => ({ type: 'paragraph', content: [{ type: 'text', text }] })
+const cell = (type: string, text: string): JSONContent => ({ type, content: [paragraph(text)] })
+const TABLE: JSONContent = {
+  type: 'table',
+  content: [
+    { type: 'tableRow', content: [cell('tableHeader', 'Name'), cell('tableHeader', 'Since')] },
+    { type: 'tableRow', content: [cell('tableCell', 'Ada'), cell('tableCell', '2026')] },
+  ],
+}
+
+/*
+  The reader an app passes — the protocol's, in Leaf and Ship. Its own reading
+  of text is the protocol package's to test; here it answers the texts these
+  tests paste, as that reader does.
+*/
+const READ: Record<string, JSONContent[]> = {
+  [TABLE_TEXT]: [TABLE],
+  [`Before\n\n${TABLE_TEXT}\n\nAfter`]: [paragraph('Before'), TABLE, paragraph('After')],
+  '# Plan\n\n- one': [{ type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Plan' }] }, { type: 'bulletList', content: [{ type: 'listItem', content: [paragraph('one')] }] }],
+  world: [paragraph('world')],
+  'A **bold** word': [{ type: 'paragraph', content: [{ type: 'text', text: 'A ' }, { type: 'text', text: 'bold', marks: [{ type: 'bold' }] }, { type: 'text', text: ' word' }] }],
+}
+const read = vi.fn((text: string) => {
+  if (text === 'reader breaks') throw new RangeError('Maximum call stack size exceeded')
+  return READ[text] ? { type: 'doc', content: READ[text] } : undefined
+})
+
+let editor: Editor | undefined
+afterEach(() => {
+  editor?.destroy()
+  read.mockClear()
+})
+
+function make(content: JSONContent, tables = true) {
+  editor = new Editor({
+    element: document.createElement('div'),
+    extensions: [StarterKit, ...(tables ? [TableKit] : []), PastedMarkdown.configure({ read })],
+    content,
+  })
+  return editor
+}
+
+/** A paste as the browser sends it, through ProseMirror's own handler. */
+function paste(ed: Editor, text: string, html = '', { shift = false } = {}) {
+  if (shift) ed.view.dom.dispatchEvent(new KeyboardEvent('keydown', { key: 'Shift', keyCode: 16, shiftKey: true, bubbles: true }))
+  const event = new Event('paste', { bubbles: true, cancelable: true })
+  Object.defineProperty(event, 'clipboardData', {
+    value: { types: html ? ['text/plain', 'text/html'] : ['text/plain'], files: [], getData: (type: string) => (type === 'text/plain' ? text : type === 'text/html' ? html : '') },
+  })
+  ed.view.dom.dispatchEvent(event)
+}
+
+const shapeOf = (ed: Editor) => (ed.getJSON().content ?? []).map((block) => block.type)
+const textOf = (ed: Editor) => ed.state.doc.textBetween(0, ed.state.doc.content.size, '\n')
+
+describe('PastedMarkdown', () => {
+  it('pastes a markdown table copied as plain text as a table, not pipes', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, TABLE_TEXT)
+    expect(shapeOf(ed)).toContain('table')
+    expect(textOf(ed)).not.toContain('|')
+  })
+
+  it('pastes the prose around a table as paragraphs, and the table between them', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, `Before\n\n${TABLE_TEXT}\n\nAfter`)
+    expect(shapeOf(ed)).toEqual(['paragraph', 'table', 'paragraph'])
+    expect(textOf(ed)).toMatch(/^Before\n[\s\S]*Ada[\s\S]*\nAfter$/)
+  })
+
+  it('pastes a heading and a list as a heading and a list', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, '# Plan\n\n- one')
+    // StarterKit keeps an empty paragraph after a last block that is not one.
+    expect(shapeOf(ed)).toEqual(['heading', 'bulletList', 'paragraph'])
+  })
+
+  it('pastes text that spells only paragraphs exactly as before, into the line it lands in', () => {
+    const ed = make({ type: 'doc', content: [paragraph('Hello ')] })
+    ed.commands.focus('end')
+    paste(ed, 'world')
+    expect(ed.getJSON().content).toEqual([paragraph('Hello world')])
+  })
+
+  it('pastes a paragraph whose text spells bold with the word bold, not with the asterisks', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, 'A **bold** word')
+    expect(textOf(ed)).toBe('A bold word')
+    expect(ed.getJSON().content?.[0].content?.[1]).toEqual({ type: 'text', text: 'bold', marks: [{ type: 'bold' }] })
+  })
+
+  it('pastes the text as typed when the reader throws, so the paste is never lost', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, 'reader breaks')
+    expect(textOf(ed)).toBe('reader breaks')
+  })
+
+  it('leaves a paste that carries HTML to the HTML, without reading the text', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, TABLE_TEXT, '<p>| Name | Since |</p>')
+    expect(read).not.toHaveBeenCalled()
+    expect(shapeOf(ed)).not.toContain('table')
+  })
+
+  it('keeps the pipes as text on the plain-text paste, Ctrl/Cmd+Shift+V', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] })
+    paste(ed, TABLE_TEXT, '', { shift: true })
+    expect(shapeOf(ed)).not.toContain('table')
+    expect(textOf(ed)).toContain('| Name | Since |')
+  })
+
+  it('keeps a table pasted inside a table cell as text, never a table in a table', () => {
+    const ed = make({ type: 'doc', content: [TABLE] })
+    ed.commands.setTextSelection(4)
+    paste(ed, TABLE_TEXT)
+    expect(JSON.stringify(ed.getJSON().content?.[0].content)).not.toContain('"type":"table"')
+    expect(textOf(ed)).toContain('| Name | Since |')
+  })
+
+  it('keeps the text in an editor that holds no tables', () => {
+    const ed = make({ type: 'doc', content: [{ type: 'paragraph' }] }, false)
+    paste(ed, TABLE_TEXT)
+    expect(shapeOf(ed)).toEqual(['paragraph', 'paragraph', 'paragraph'])
+    expect(textOf(ed)).toContain('| Ada | 2026 |')
+  })
+})

package/src/PastedMarkdown.ts

@@ -0,0 +1,68 @@
+import { Extension, type JSONContent } from '@tiptap/core'
+import { Slice, type ResolvedPos } from '@tiptap/pm/model'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+export interface PastedMarkdownOptions {
+  /**
+   * Plain text read as the blocks it spells, as editor JSON (`{ type: 'doc',
+   * content }`), or `undefined` to paste it as text. The app passes its
+   * protocol's reader — for a block document, `@estiva-app/protocol`'s
+   * `descriptionTextToBlockDocument` through `toEditorDocument` — so a paste
+   * reads text exactly as the agent's write of the same text does.
+   */
+  read: (text: string) => JSONContent | undefined
+}
+
+/** Inside a table cell: a pasted table there stays text, never a table in a table. */
+function inTableCell($context: ResolvedPos): boolean {
+  for (let depth = $context.depth; depth > 0; depth--) {
+    const role = $context.node(depth).type.spec.tableRole
+    if (role === 'cell' || role === 'header_cell') return true
+  }
+  return false
+}
+
+const hasTable = (blocks: JSONContent[]): boolean => blocks.some((block) => block.type === 'table' || hasTable(block.content ?? []))
+
+/**
+ * Markdown pasted as plain text lands as what it spells: a heading, a list, a
+ * checklist, a quote or callout, a table (LEAF-10; Miky, 2026-10-15). Only a
+ * paste with no HTML on the clipboard is read — a copy from a web page already
+ * pastes its own structure — and a paste that spells nothing but paragraphs
+ * pastes exactly as before. Ctrl/Cmd+Shift+V, the plain-text paste, keeps the
+ * text as typed, and so does a paste into code.
+ *
+ * For an editor that saves a block document. A message box leaves it out: a
+ * message's text has no table (SPEC §13.2), so a pasted table stays text there.
+ */
+export const PastedMarkdown = Extension.create<PastedMarkdownOptions>({
+  name: 'pastedMarkdown',
+  addOptions() {
+    return { read: () => undefined }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    return [
+      new Plugin({
+        key: new PluginKey('pastedMarkdown'),
+        props: {
+          // Reached only for a text paste outside code; `plain` is the Shift paste.
+          clipboardTextParser: (text, $context, plain, view) => {
+            if (plain) return undefined as unknown as Slice
+            try {
+              const blocks = options.read(text.replace(/\r\n?/g, '\n'))?.content ?? []
+              // Paragraphs only: the editor's own paste keeps each line a paragraph, and its paste rules make `**bold**` bold.
+              if (blocks.every((block) => block.type === 'paragraph')) return undefined as unknown as Slice
+              if (inTableCell($context) && hasTable(blocks)) return undefined as unknown as Slice
+              return Slice.maxOpen(view.state.schema.nodeFromJSON({ type: 'doc', content: blocks }).content)
+            } catch {
+              // A reader that throws, or a block this editor's schema does not
+              // hold (a table without TableKit): paste the text.
+              return undefined as unknown as Slice
+            }
+          },
+        },
+      }),
+    ]
+  },
+})

package/src/editor.ts

@@ -9,9 +9,24 @@
  */
 export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
 export { PastedImages, pastedImages, pastedImageName, type PastedImagesOptions, type ClipboardSource } from './PastedImages'
+export { PastedMarkdown, type PastedMarkdownOptions } from './PastedMarkdown'
 export { CodeBlockColours } from './CodeBlockColours'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
-export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
+export {
+  EditorBlockHandle,
+  blockDropCursor,
+  deleteBlock,
+  moveBlock,
+  duplicateBlock,
+  startBlockDrag,
+  turnIntoRows,
+  turnListInto,
+  turnQuoteInto,
+  type EditorBlockHandleProps,
+  type BlockTurnInto,
+  type ListKind,
+  type QuoteKind,
+} from './EditorBlockHandle'
 export { EditorTableControls, appendTableRow, appendTableColumn, deleteTableRow, deleteTableColumn, type EditorTableControlsProps } from './EditorTableControls'
 export {
   PersonMention,

package/src/pages.test.ts

@@ -41,6 +41,7 @@ const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
 const HOLDS_ONLY: Record<string, string> = {
   AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.',
   PastedImages: 'Nothing. It draws nothing; it hands a pasted picture to the app, named.',
+  PastedMarkdown: 'Nothing. It draws nothing; it hands pasted text to the app\'s reader and puts back what that reads.',
   CodeBlockColours: 'Nothing. It names each word of a code block; the RichText class list colours them.',
   LinkChips: 'Nothing. It draws nothing; it turns the URLs the app recognises into chips.',
   // Its box is the Popover's, which owns what a box does; it holds which chip the menu is on.

package/src/registry/registry.test.ts

@@ -26,7 +26,7 @@ import { SCHEMA_VERSION, validateRegistry, type Registry, type RegistryEntry } f
 const root = process.cwd()
 const registry = buildRegistry({ root })
 /** Editor extensions: named like components by the catalogue, and not React components. */
-const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'CodeBlockColours', 'Checklist', 'Callout', 'ReferenceCards', 'LinkChips', 'ReferenceMenu']
+const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'PastedMarkdown', 'CodeBlockColours', 'Checklist', 'Callout', 'ReferenceCards', 'LinkChips', 'ReferenceMenu']
 const entry = (name: string): RegistryEntry => {
   const found = registry.entries.find((candidate) => candidate.name === name)
   if (!found) throw new Error(`no entry for ${name}`)
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 162 names over 80 files: 114 components, 46 helpers and 2 hooks (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October)', () => {
+  it('counts 166 names over 81 files: 115 components, 49 helpers and 2 hooks (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 114, helper: 46, hook: 2 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(80)
+    expect(kinds).toEqual({ component: 115, helper: 49, hook: 2 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(81)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(76)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(86)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(77)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(89)
   })
 
   it('takes a name with a page of its own from the page, and a name without one from the code', () => {

package/stories/Choosing.mdx

@@ -98,6 +98,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A link — in text, on a title, beside a note, or a whole box | **Link** — `text`, `quiet`, `underlined`, `plain`; `external` for a new tab |
 | A document or an image attached to something, posted or waiting to be sent | **AttachmentCard** — the file decides the shape; `pending` in a composer |
 | A picture pasted into an editor, attached rather than pasted | **PastedImages** — from `@estiva-app/ui/editor`; the app hands it its upload |
+| Markdown pasted as plain text, landing as the headings, lists and tables it spells | **PastedMarkdown** — from `@estiva-app/ui/editor`, in an editor that saves a block document; the app hands it the protocol's reader |
 | A card a chip in a document asks for, drawn after its line | **ReferenceCards** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app draws its card into each slot |
 | A URL in a document that reads as the chip of what it points at | **LinkChips** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app says what each URL names |
 | Open a chip in a document, or choose its card, while writing | **ReferenceMenu** — from `@estiva-app/ui/editor`, beside `ReferenceCards`; a click on the chip, or putting one in, opens it |