@estiva-app/ui 0.69.2 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.69.2",
+  "version": "0.71.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.69.2",
-    "exports": 162,
-    "typeExports": 152,
+    "packageVersion": "0.71.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",
@@ -4819,6 +4819,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "PastedMarkdown",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedMarkdown.ts",
+      "purpose": "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.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedmarkdown--docs",
+      "storyId": "primitives-pastedmarkdown--in-an-editor",
+      "docPage": "src/PastedMarkdown.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "peopleMenu",
       "repo": "estiva-ui",
@@ -7767,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'])
+  })
+})