@estiva-app/ui 0.70.0 → 0.72.0-widgets2.0

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.70.0",
-    "exports": 163,
-    "typeExports": 153,
+    "packageVersion": "0.72.0-widgets2.0",
+    "exports": 166,
+    "typeExports": 155,
     "files": null
   },
   "storybook": {
@@ -2335,9 +2335,9 @@
         },
         {
           "name": "turnInto",
-          "takes": "readonly BlockTurnInto[]",
+          "takes": "a handler",
           "required": false,
-          "note": "Turn into's rows. Offered for a block of text — a paragraph, a heading, code."
+          "note": "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."
         },
         {
           "name": "actions",
@@ -7786,6 +7786,63 @@
         "truncate text-left text-input-value text-text-muted"
       ]
     },
+    {
+      "name": "turnIntoRows",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "The block menu's Turn into for one block, the same in every app (Miky, LEAF-11's kickoff, 15 October):",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "turnListInto",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "Turns the whole list at `pos`, every item, the nested ones too.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "turnQuoteInto",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/EditorBlockHandle.tsx",
+      "purpose": "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).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-editorblockhandle--docs",
+      "storyId": "primitives-editorblockhandle--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "typeTrigger",
       "repo": "estiva-ui",

package/src/BlockHandle.test.tsx

@@ -178,7 +178,7 @@ describe('BlockHandle', () => {
     // jsdom lays nothing out: every block's top is 0, so the pointer is on the last.
     await act(async () => user.hover(screen.getByText('two')))
     await press(user, screen.getByRole('button', { name: 'Block menu' }))
-    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Duplicate', 'Delete'])
+    expect(screen.getAllByRole('menuitem').map((r) => r.textContent)).toEqual(['Turn into', 'Duplicate', 'Delete'])
     await user.click(screen.getByRole('menuitem', { name: 'Delete' }))
     // The editor takes the focus back a frame later and measures the caret then: wait for it, so it is part of the test.
     await act(() => new Promise<void>((done) => requestAnimationFrame(() => done())))

package/src/BlockNodes.tsx

@@ -474,6 +474,8 @@ export const ReferenceNode = Node.create<ReferenceNodeOptions>({
  * Not editable, deliberately: an affordance that lets a person change
  * something they cannot see is worse than one that says the content is there
  * and belongs to another surface.
+ *
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/the-block-editor-kit-lives-in-protocol-and-ui.md
  */
 export const UnknownBlock = Node.create({
   name: 'unknownBlock',

package/src/ComposerTriggers.tsx

@@ -21,6 +21,8 @@ import { suggestionPopup, type SuggestionPopupOptions } from './suggestionPopup'
  * `messageReference`, `urgentTagsFor`), so a client without React writes the
  * same bytes. A chip here carries what that needs: a person's `pubkey`, a
  * reference's `uri`.
+ *
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/composer-triggers-are-one-shared-kit.md
  */
 
 // ─── @ and !@ ───
@@ -482,7 +484,7 @@ export const FORMATS: readonly FormatDef[] = [
  * `Callout` extensions. Note and Warning are the two callouts offered (Miky,
  * 2026-10-13); the other tones are read and kept, not offered.
  */
-const DOCUMENT_FORMATS: readonly FormatDef[] = [
+export const DOCUMENT_FORMATS: readonly FormatDef[] = [
   { id: 'checklist', label: 'Checklist', trigger: '[]' },
   { id: 'note', label: 'Note' },
   { id: 'warning', label: 'Warning' },

package/src/EditorBlockHandle.mdx

@@ -28,24 +28,29 @@ for Turn into, Duplicate and Delete, then the app's rows.
 ```tsx
 import { EditorContent, useEditor } from '@tiptap/react'
 import StarterKit from '@tiptap/starter-kit'
-import { BlockId, EditorBlockHandle, type BlockTurnInto } from '@estiva-app/ui/editor'
+import { BlockId, Callout, Checklist, EditorBlockHandle } from '@estiva-app/ui/editor'
 import { MenuItem, type HandleBlock } from '@estiva-app/ui'
 
-const turnInto: BlockTurnInto[] = [
-  { label: 'Text', run: (editor) => editor.chain().setParagraph().run(), active: (node) => node.type.name === 'paragraph' },
-  { label: 'Heading', run: (editor) => editor.chain().setHeading({ level: 1 }).run() },
-]
 const rows = (block: HandleBlock) => <MenuItem label="Copy link" onClick={() => navigator.clipboard.writeText(`#${block.id}`)} />
 
-const editor = useEditor({ extensions: [StarterKit, BlockId] })
+const editor = useEditor({ extensions: [StarterKit, BlockId, Checklist, Callout] })
 
-<EditorBlockHandle editor={editor} turnInto={turnInto} actions={rows}>
+<EditorBlockHandle editor={editor} actions={rows}>
   <EditorContent editor={editor} />
 </EditorBlockHandle>
 ```
 
-- `turnInto`'s `run` gets the editor with the caret already in the block, and
-  is offered only for a block of text: a paragraph, a heading, code.
+- **Turn into is the same in every app** (`turnIntoRows`): a block of text gets the `/` menu's formats, code as a block, and
+  Checklist, Note and Warning; a list gets Bulleted list, Numbered list,
+  Checklist and Text; a quote gets Quote, Note, Warning and Text. Checklist
+  and the callouts appear only where the editor has `Checklist` and `Callout`.
+- **A list or a quote turns whole**, and keeps its id and every item's, so a
+  comment anchored to it stays: Checklist keeps the ticks there are, Bulleted
+  and Numbered drop them, Text makes each item a paragraph under the item's
+  id. `turnListInto` and `turnQuoteInto` are those rows' actions.
+- `turnInto` takes other rows: a function of the block, or a list offered for
+  a block of text only, its `run` getting the editor with the caret already in
+  the block. `[]` offers none.
 - **Every row leaves the editor focused**, as a drop does: Turn into in the
   block, Duplicate in the copy, Delete where the block was. An editor that
   saves when the person leaves it saves these the same way.

package/src/EditorBlockHandle.stories.tsx

@@ -3,8 +3,8 @@ import { EditorContent, useEditor } from '@tiptap/react'
 import StarterKit from '@tiptap/starter-kit'
 import { IconLink, IconMessage } from '@tabler/icons-react'
 import type { HandleBlock } from './BlockHandle'
-import { BlockId } from './BlockNodes'
-import { EditorBlockHandle, blockDropCursor, type BlockTurnInto } from './EditorBlockHandle'
+import { BlockId, Callout, Checklist } from './BlockNodes'
+import { EditorBlockHandle, blockDropCursor } from './EditorBlockHandle'
 import { MenuItem } from './Menu'
 import { richTextClassName } from './RichText'
 
@@ -35,17 +35,11 @@ const DOCUMENT = {
         { type: 'listItem', attrs: { blockId: 'b6' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item two' }] }] },
       ],
     },
+    { type: 'blockquote', attrs: { blockId: 'b8' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A quote. Turn it into a Note or a Warning.' }] }] },
     { type: 'paragraph', attrs: { blockId: 'b7' }, content: [{ type: 'text', text: 'The last paragraph.' }] },
   ],
 }
 
-const TURN_INTO: BlockTurnInto[] = [
-  { label: 'Text', run: (editor) => editor.chain().setParagraph().run(), active: (node) => node.type.name === 'paragraph' },
-  { label: 'Heading', run: (editor) => editor.chain().setHeading({ level: 1 }).run(), active: (node) => node.type.name === 'heading' && node.attrs.level === 1 },
-  { label: 'Subheading', run: (editor) => editor.chain().setHeading({ level: 2 }).run(), active: (node) => node.type.name === 'heading' && node.attrs.level === 2 },
-  { label: 'Code', run: (editor) => editor.chain().setCodeBlock().run(), active: (node) => node.type.name === 'codeBlock' },
-]
-
 /** The rows an app adds: here they only say which block they were pressed on. */
 function rows(block: HandleBlock) {
   return (
@@ -58,13 +52,13 @@ function rows(block: HandleBlock) {
 
 function Editing({ editable }: { editable: boolean }) {
   const editor = useEditor({
-    extensions: [StarterKit.configure({ dropcursor: blockDropCursor }), BlockId],
+    extensions: [StarterKit.configure({ dropcursor: blockDropCursor }), BlockId, Checklist, Callout],
     content: DOCUMENT,
     editable,
     editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
   })
   return (
-    <EditorBlockHandle editor={editor} turnInto={TURN_INTO} actions={rows} className="ml-8 max-w-[560px]">
+    <EditorBlockHandle editor={editor} actions={rows} className="ml-8 max-w-[560px]">
       <EditorContent editor={editor} />
     </EditorBlockHandle>
   )

package/src/EditorBlockHandle.test.tsx

@@ -0,0 +1,200 @@
+// @vitest-environment jsdom
+/**
+ * The block menu's Turn into (LEAF-11): what each row makes of a list, a quote
+ * and a block of text, and that the block keeps its id — what a comment
+ * anchored to it is attached by.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { act, cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Editor, type Extensions } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, Callout, Checklist } from './BlockNodes'
+import { EditorBlockHandle, turnIntoRows, turnListInto, turnQuoteInto } from './EditorBlockHandle'
+
+type Json = { type: string; attrs?: Record<string, unknown>; content?: Json[]; text?: string }
+
+const item = (id: string, text: string, attrs: Record<string, unknown> = {}, nested?: Json): Json => ({
+  type: 'listItem',
+  attrs: { blockId: id, ...attrs },
+  content: [{ type: 'paragraph', content: [{ type: 'text', text }] }, ...(nested ? [nested] : [])],
+})
+const para = (id: string, text: string): Json => ({ type: 'paragraph', attrs: { blockId: id }, content: [{ type: 'text', text }] })
+const quote = (id: string, text: string, tone: string | null = null): Json => ({ type: 'blockquote', attrs: { blockId: id, tone }, content: [{ type: 'paragraph', content: [{ type: 'text', text }] }] })
+
+const editors: Editor[] = []
+function editor(content: Json[], extensions: Extensions = [StarterKit, BlockId, Checklist, Callout]) {
+  const e = new Editor({ extensions, content: { type: 'doc', content } })
+  editors.push(e)
+  return e
+}
+/** The document's blocks, less the empty paragraph StarterKit keeps after a last list or quote. */
+const blocks = (e: Editor) => (e.getJSON().content as Json[]).filter((b, i, all) => !(i === all.length - 1 && b.type === 'paragraph' && !b.content))
+const posOf = (e: Editor, id: string) => {
+  let at = -1
+  e.state.doc.forEach((node, pos) => {
+    if (node.attrs.blockId === id) at = pos
+  })
+  return at
+}
+/** Each item of the list as `id text checked`, the nested ones after their parent. */
+const items = (list: Json): string[] =>
+  (list.content ?? []).flatMap((i) => [
+    `${i.attrs?.blockId} ${i.content?.[0].content?.[0].text} ${i.attrs?.checked ?? '-'}`,
+    ...(i.content ?? []).slice(1).flatMap(items),
+  ])
+const texts = (e: Editor) => blocks(e).map((b) => `${b.type} ${b.attrs?.blockId} ${b.content?.[0]?.content?.[0]?.text ?? b.content?.[0]?.text}`)
+
+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()
+})
+
+describe('turnListInto', () => {
+  const LIST: Json = { type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'milk', { checked: true }), item('i2', 'eggs', {}, { type: 'bulletList', content: [item('i3', 'brown')] })] }
+
+  it('a list into a checklist makes every item one, nested ones too, keeping ticks and every id', () => {
+    const e = editor([LIST])
+    expect(turnListInto(e, 0, 'checklist')).toBe(true)
+    const [list] = blocks(e)
+    expect(list.type).toBe('bulletList')
+    expect(list.attrs?.blockId).toBe('l1')
+    expect(items(list)).toEqual(['i1 milk true', 'i2 eggs false', 'i3 brown false'])
+  })
+
+  it('a checklist into a numbered list keeps the list’s id and drops every tick', () => {
+    const e = editor([LIST])
+    turnListInto(e, 0, 'checklist')
+    turnListInto(e, 0, 'orderedList')
+    const [list] = blocks(e)
+    expect(list.type).toBe('orderedList')
+    expect(list.attrs?.blockId).toBe('l1')
+    expect(list.content?.[1].content?.[1].type).toBe('orderedList')
+    expect(items(list)).toEqual(['i1 milk -', 'i2 eggs -', 'i3 brown -'])
+  })
+
+  it('does not join a list into a numbered list beside it, as Tiptap’s toggle would', () => {
+    const e = editor([LIST, { type: 'orderedList', attrs: { blockId: 'l2' }, content: [item('i9', 'after')] }])
+    turnListInto(e, 0, 'orderedList')
+    expect(blocks(e).map((b) => `${b.type} ${b.attrs?.blockId}`)).toEqual(['orderedList l1', 'orderedList l2'])
+  })
+
+  it('a list into text makes each item a paragraph with the item’s id, in order', () => {
+    const e = editor([para('p0', 'before'), LIST])
+    turnListInto(e, posOf(e, 'l1'), 'text')
+    expect(texts(e)).toEqual(['paragraph p0 before', 'paragraph i1 milk', 'paragraph i2 eggs', 'paragraph i3 brown'])
+  })
+
+  it('a numbered list into a checklist stays numbered', () => {
+    const e = editor([{ type: 'orderedList', attrs: { blockId: 'l1' }, content: [item('i1', 'a')] }])
+    turnListInto(e, 0, 'checklist')
+    expect(blocks(e)[0].type).toBe('orderedList')
+    expect(items(blocks(e)[0])).toEqual(['i1 a false'])
+  })
+
+  it('the kind a list or a quote already is makes no edit', () => {
+    // A paragraph last, or StarterKit adds one on the first change and that is an edit.
+    const e = editor([{ type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'a')] }, quote('q1', 'b', 'note'), para('p9', 'end')])
+    let updates = 0
+    e.on('update', () => updates++)
+    turnListInto(e, 0, 'bulletList')
+    turnQuoteInto(e, posOf(e, 'q1'), 'note')
+    expect(updates).toBe(0)
+    expect(e.can().undo()).toBe(false)
+  })
+
+  it('does nothing where there is no list', () => {
+    const e = editor([para('p0', 'before')])
+    expect(turnListInto(e, 0, 'checklist')).toBe(false)
+    expect(texts(e)).toEqual(['paragraph p0 before'])
+  })
+})
+
+describe('turnQuoteInto', () => {
+  it('a quote into a Warning and back keeps its id and text', () => {
+    const e = editor([quote('q1', 'careful')])
+    turnQuoteInto(e, 0, 'warning')
+    expect(blocks(e)[0].attrs).toMatchObject({ blockId: 'q1', tone: 'warning' })
+    turnQuoteInto(e, 0, 'quote')
+    expect(blocks(e)[0].attrs).toMatchObject({ blockId: 'q1', tone: null })
+    expect(texts(e)).toEqual(['blockquote q1 careful'])
+  })
+
+  it('a callout into text is a paragraph with the quote’s id', () => {
+    const e = editor([quote('q1', 'careful', 'note')])
+    turnQuoteInto(e, 0, 'text')
+    expect(texts(e)).toEqual(['paragraph q1 careful'])
+  })
+})
+
+describe('turnIntoRows', () => {
+  const labels = (e: Editor, id: string) => turnIntoRows(e.state.doc.nodeAt(posOf(e, id))!, e).map((r) => r.label)
+  const selected = (e: Editor, id: string) => {
+    const node = e.state.doc.nodeAt(posOf(e, id))!
+    return turnIntoRows(node, e).filter((r) => r.active?.(node)).map((r) => r.label)
+  }
+
+  it('offers a list its kinds and Text, a quote its callouts and Text, a paragraph everything', () => {
+    const e = editor([para('p1', 'one'), { type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'a')] }, quote('q1', 'b', 'warning')])
+    expect(labels(e, 'l1')).toEqual(['Bulleted list', 'Numbered list', 'Checklist', 'Text'])
+    expect(labels(e, 'q1')).toEqual(['Quote', 'Note', 'Warning', 'Text'])
+    expect(labels(e, 'p1')).toEqual(['Text', 'Heading', 'Subheading', 'Quote', 'Code', 'Bulleted list', 'Numbered list', 'Checklist', 'Note', 'Warning'])
+    expect(selected(e, 'l1')).toEqual(['Bulleted list'])
+    expect(selected(e, 'q1')).toEqual(['Warning'])
+  })
+
+  it('selects Checklist, not Bulleted list, on a list of checklist items', () => {
+    const e = editor([{ type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'a', { checked: false })] }])
+    expect(selected(e, 'l1')).toEqual(['Checklist'])
+  })
+
+  it('selects no row on a list only partly of checklist items, since every row changes it', () => {
+    const e = editor([{ type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'a', { checked: true }), item('i2', 'b')] }])
+    expect(selected(e, 'l1')).toEqual([])
+  })
+
+  it('offers no checklist or callout where the editor cannot hold one', () => {
+    const e = editor([{ type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'a')] }, quote('q1', 'b')], [StarterKit, BlockId])
+    expect(labels(e, 'l1')).toEqual(['Bulleted list', 'Numbered list', 'Text'])
+    expect(labels(e, 'q1')).toEqual(['Quote', 'Text'])
+  })
+
+  it('offers a block that is not text, a list or a quote nothing — a rule', () => {
+    const e = editor([para('p1', 'one')])
+    expect(turnIntoRows(e.schema.nodes.horizontalRule.create(), e)).toEqual([])
+  })
+})
+
+describe('EditorBlockHandle Turn into', () => {
+  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')
+  }
+
+  it('turns a list into a checklist from the block menu, with no rows passed', async () => {
+    // jsdom lays nothing out: every block's top is 0, so the pointer is on the last — the list.
+    const e = editor([para('p1', 'one'), { type: 'bulletList', attrs: { blockId: 'l1' }, content: [item('i1', 'milk'), item('i2', 'eggs')] }])
+    const { EditorContent } = await import('@tiptap/react')
+    render(
+      <EditorBlockHandle editor={e}>
+        <EditorContent editor={e} />
+      </EditorBlockHandle>,
+    )
+    const user = userEvent.setup()
+    await act(async () => user.hover(screen.getByText('eggs')))
+    await press(user, screen.getByRole('button', { name: 'Block menu' }))
+    await user.click(screen.getByRole('menuitem', { name: 'Turn into' }))
+    await user.click(await screen.findByRole('menuitem', { name: 'Checklist' }))
+    await act(() => new Promise<void>((done) => requestAnimationFrame(() => done())))
+    const list = blocks(e)[1]
+    expect(list.attrs?.blockId).toBe('l1')
+    expect(items(list)).toEqual(['i1 milk false', 'i2 eggs false'])
+  })
+})

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'