@estiva-app/ui 0.54.0 → 0.55.0

package/src/BlockHandle.tsx

@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useRef, useState, type DragEvent, type MouseEvent, type ReactNode } from 'react'
+import type { BaseUIEvent } from '@base-ui/react/types'
+import { IconGripVertical } from '@tabler/icons-react'
+import { cn } from './cn'
+import { IconButton } from './IconButton'
+import { Menu, MenuSeparator } from './Menu'
+
+/** The block the pointer is on: its §13.3 id, its element, and — in an editor — where it starts. */
+export interface HandleBlock {
+  /** `undefined` only for a block that has none yet, which nothing can address. */
+  id: string | undefined
+  element: HTMLElement
+  /** Position before the block in the editor's document; absent when reading. */
+  pos?: number
+}
+
+/** What `EditorBlockHandle` hands this part to make it edit. A reading surface leaves it off. */
+export interface BlockHandleEditing {
+  /** The block level with `y`, in the editor's own document. */
+  find: (y: number) => HandleBlock | null
+  /** The editing rows, before the caller's. */
+  rows: (block: HandleBlock) => ReactNode
+  /** Starts the browser's drag of the block; the handle is draggable only with this. */
+  startDrag: (block: HandleBlock, event: globalThis.DragEvent) => void
+  /** Drops the dragged block before `target`, or after it: a drop in the gutter, where the editor has none. */
+  drop: (target: HandleBlock, after: boolean) => void
+  endDrag: () => void
+  /** Calls back when the document changes, so a block found before is found again. Returns the unsubscribe. */
+  onChange: (changed: () => void) => () => void
+}
+
+export interface BlockHandleProps {
+  /** The caller's own rows — a link to the block, a comment on it. Reading, they are the whole menu; with none, no handle is drawn. */
+  actions?: (block: HandleBlock) => ReactNode
+  /** Given by `EditorBlockHandle` (from `@estiva-app/ui/editor`). Leave it off to read. */
+  editing?: BlockHandleEditing
+  /** What the blocks are drawn in. Reading: a surface whose top-level elements carry `data-block-id`, as `RichText` draws. */
+  children: ReactNode
+  className?: string
+}
+
+/** A block's id as a reading surface writes it: on the element, or on the first inside it (a table's wrapper). */
+function readId(element: HTMLElement): string | undefined {
+  const own = element.getAttribute('data-block-id') ?? element.querySelector('[data-block-id]')?.getAttribute('data-block-id')
+  return own || undefined
+}
+
+/** The last of `blocks` whose top is at or above `y` — the gap between two blocks belongs to the one before. */
+export function blockAtY(blocks: readonly HandleBlock[], y: number): HandleBlock | null {
+  let found: HandleBlock | null = null
+  for (const block of blocks) {
+    if (block.element.getBoundingClientRect().top > y) break
+    found = block
+  }
+  return found ?? blocks[0] ?? null
+}
+
+/** The top-level blocks of a reading surface: its root's children that carry an id. */
+function readingBlocks(root: Element | null): HandleBlock[] {
+  if (!root) return []
+  return Array.from(root.children)
+    .filter((el): el is HTMLElement => el instanceof HTMLElement)
+    .map((element) => ({ id: readId(element), element }))
+    .filter((b) => b.id !== undefined)
+}
+
+/** The handle's 24px, against the block's first line. */
+const HANDLE = 24
+
+/**
+ * How far down the block the handle starts, so it is centred on the first
+ * line: a heading's line is taller than a paragraph's. A table's or a list's
+ * first line is its first descendant's.
+ */
+function firstLineOffset(element: HTMLElement): number {
+  const text = element.querySelector<HTMLElement>('p, h1, h2, h3, pre, li') ?? element
+  const line = parseFloat(getComputedStyle(text).lineHeight)
+  if (!Number.isFinite(line)) return 0
+  const inset = text === element ? 0 : text.getBoundingClientRect().top - element.getBoundingClientRect().top
+  return inset + (line - HANDLE) / 2
+}
+
+/**
+ * The handle at the left of the block under the pointer, and the block's menu
+ * behind it. Reading, the menu is the caller's rows only, so someone who
+ * cannot edit can still point at one block — copy a link to it, comment on
+ * it. In an editor, `EditorBlockHandle` adds the drag, Turn into, Duplicate
+ * and Delete.
+ *
+ * It sits in the gutter left of the content, 28px out, so wrapping the content
+ * moves nothing. The gutter counts as the block's, as in Notion: the handle
+ * stays while the pointer crosses to it.
+ */
+export function BlockHandle({ actions, editing, children, className }: BlockHandleProps) {
+  const frame = useRef<HTMLDivElement>(null)
+  const content = useRef<HTMLDivElement>(null)
+  const [block, setBlock] = useState<HandleBlock | null>(null)
+  const [top, setTop] = useState(0)
+  const [open, setOpen] = useState(false)
+
+  const follow = useCallback(
+    (y: number) => {
+      if (!content.current || !frame.current) return
+      const found = editing ? editing.find(y) : blockAtY(readingBlocks(content.current.firstElementChild), y)
+      setBlock(found)
+      if (found) setTop(found.element.getBoundingClientRect().top - frame.current.getBoundingClientRect().top + firstLineOffset(found.element))
+    },
+    [editing],
+  )
+
+  // A block moved or deleted under the handle would leave its rows acting on a stale position.
+  useEffect(() => {
+    if (!editing) return
+    return editing.onChange(() => {
+      if (!open) setBlock(null)
+    })
+  }, [editing, open])
+
+  const rows = editing && block ? editing.rows(block) : null
+  const own = actions && block ? actions(block) : null
+
+  /*
+    A block dragged down the gutter lands by height, as in Notion: the top half
+    of a block puts it before, the bottom half after, and the line shows where.
+    Over the text, the editor draws its own line and makes its own drop.
+  */
+  const dragging = useRef(false)
+  const [line, setLine] = useState<number | null>(null)
+  const inGutter = (e: DragEvent<HTMLDivElement>) => dragging.current && !!editing && !!content.current && !content.current.contains(e.target as Node)
+  const landing = (y: number) => {
+    const target = editing?.find(y)
+    if (!target || !frame.current) return null
+    const box = target.element.getBoundingClientRect()
+    const after = y > box.top + box.height / 2
+    // Midway across the gap to the neighbour, where the editor draws its own line.
+    const neighbour = (after ? target.element.nextElementSibling : target.element.previousElementSibling)?.getBoundingClientRect()
+    const edge = after ? (neighbour ? (box.bottom + neighbour.top) / 2 : box.bottom) : neighbour ? (neighbour.bottom + box.top) / 2 : box.top
+    return { target, after, top: edge - frame.current.getBoundingClientRect().top }
+  }
+  const endDrag = () => {
+    dragging.current = false
+    setLine(null)
+    editing?.endDrag()
+  }
+
+  return (
+    <div
+      ref={frame}
+      className={cn('relative', className)}
+      onMouseMove={(e) => {
+        if (!open) follow(e.clientY)
+      }}
+      onMouseLeave={() => {
+        if (!open) setBlock(null)
+      }}
+      onDragOver={(e) => {
+        if (!inGutter(e)) return setLine(null)
+        e.preventDefault()
+        setLine(landing(e.clientY)?.top ?? null)
+      }}
+      onDrop={(e) => {
+        if (inGutter(e)) {
+          e.preventDefault()
+          const at = landing(e.clientY)
+          if (at) editing?.drop(at.target, at.after)
+        }
+        // The drop can redraw the document and take the handle with it, before its dragend.
+        endDrag()
+      }}
+      onDragLeave={(e) => {
+        if (!frame.current?.contains(e.relatedTarget as Node)) setLine(null)
+      }}
+    >
+      <div ref={content}>{children}</div>
+      {/* The gutter is the frame's own, so the pointer on its way from the text to the handle never leaves it. */}
+      <div aria-hidden className="absolute inset-y-0 -left-7 w-7" />
+      {line !== null && <div aria-hidden className="pointer-events-none absolute inset-x-0 h-px bg-accent-primary" style={{ top: line }} />}
+      {block && (rows || own) && (
+        // The top is the block's, measured: it depends on the document, not on a size of ours.
+        <div className={cn('absolute -left-7', rows && 'cursor-grab active:cursor-grabbing')} style={{ top }}>
+          <Menu
+            open={open}
+            onOpenChange={setOpen}
+            trigger={
+              <IconButton
+                aria-label="Block menu"
+                tooltip={rows ? 'Drag to move, click for the menu' : 'Menu'}
+                draggable={!!rows}
+                // Base UI opens a menu on the press, so a drag flashed it open.
+                // The handle's menu opens on the click instead, as Notion's does:
+                // a press that becomes a drag never clicks.
+                onMouseDown={(e: BaseUIEvent<MouseEvent<HTMLButtonElement>>) => e.preventBaseUIHandler()}
+                onClick={(e: BaseUIEvent<MouseEvent<HTMLButtonElement>>) => {
+                  e.preventBaseUIHandler()
+                  setOpen((was) => !was)
+                }}
+                onDragStart={(e: DragEvent<HTMLButtonElement>) => {
+                  if (!editing || !rows) return
+                  setOpen(false)
+                  dragging.current = true
+                  editing.startDrag(block, e.nativeEvent)
+                }}
+                onDragEnd={() => {
+                  endDrag()
+                  setBlock(null)
+                }}
+              >
+                <IconGripVertical size={16} stroke={1.5} />
+              </IconButton>
+            }
+          >
+            {rows}
+            {rows && own && <MenuSeparator />}
+            {own}
+          </Menu>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/EditorBlockHandle.mdx

@@ -0,0 +1,65 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as EditorBlockHandleStories from './EditorBlockHandle.stories'
+
+<Meta of={EditorBlockHandleStories} />
+
+# EditorBlockHandle
+
+`BlockHandle` in a Tiptap editor: drag the handle to move the block, press it
+for Turn into, Duplicate and Delete, then the app's rows.
+
+<Canvas of={EditorBlockHandleStories.Default} />
+
+## When
+
+- **An editor of a block document** (SPEC §13.3) that someone reorganises —
+  with `BlockNodes`' `BlockId` in its extensions, so every block has an id.
+- **Not editable**: the same handle reads — no drag, the app's rows only.
+
+## When not
+
+- The document being read, with no editor → **BlockHandle**, from the main
+  entry, which loads no Tiptap.
+- Formatting a few words inside a block → **SelectionToolbar**. This acts on
+  whole blocks.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, EditorBlockHandle, type BlockTurnInto } 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] })
+
+<EditorBlockHandle editor={editor} turnInto={turnInto} 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.
+- **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.
+- `duplicateBlock`, `deleteBlock` and `startBlockDrag` are the rows' own
+  actions, for a caller that offers them elsewhere (a shortcut, a test).
+
+<Canvas of={EditorBlockHandleStories.NotEditable} />
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Moves the block through ProseMirror's own drop, so it arrives with its id and its anchored comments still find it | a drop handler, or a delete and an insert | |
+| Duplicates a block under a fresh id, the original keeping its own (`BlockId` decides) | an id for the copy | |
+| Puts the caret in the block before a Turn into row runs | a selection before your `run` | |

package/src/EditorBlockHandle.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+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 { MenuItem } from './Menu'
+import { richTextClassName } from './RichText'
+
+/**
+ * `BlockHandle` in an editor. Drag the handle to move a block; press it for
+ * Turn into, Duplicate, Delete, then the app's rows.
+ */
+const meta = {
+  title: 'Primitives/EditorBlockHandle',
+  // The handle sits 28px left of the content, in the page's margin.
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'heading', attrs: { level: 1, blockId: 'b1' }, content: [{ type: 'text', text: 'A heading' }] },
+    { type: 'paragraph', attrs: { blockId: 'b2' }, content: [{ type: 'text', text: 'The first paragraph. Drag its handle below the list.' }] },
+    { type: 'paragraph', attrs: { blockId: 'b3' }, content: [{ type: 'text', text: 'The second paragraph.' }] },
+    {
+      type: 'bulletList',
+      attrs: { blockId: 'b4' },
+      content: [
+        { type: 'listItem', attrs: { blockId: 'b5' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item one' }] }] },
+        { type: 'listItem', attrs: { blockId: 'b6' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item two' }] }] },
+      ],
+    },
+    { 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 (
+    <>
+      <MenuItem label="Copy link" leading={<IconLink size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('copy link', block.id)} />
+      <MenuItem label="Comment" leading={<IconMessage size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => console.info('comment', block.id)} />
+    </>
+  )
+}
+
+function Editing({ editable }: { editable: boolean }) {
+  const editor = useEditor({
+    extensions: [StarterKit.configure({ dropcursor: blockDropCursor }), BlockId],
+    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]">
+      <EditorContent editor={editor} />
+    </EditorBlockHandle>
+  )
+}
+
+/** Drag to move; Turn into, Duplicate and Delete; then the app's rows. */
+export const Default: Story = {
+  render: () => <Editing editable />,
+}
+
+/** An editor that is not editable: no drag, and only the app's rows. */
+export const NotEditable: Story = {
+  render: () => <Editing editable={false} />,
+}

package/src/EditorBlockHandle.tsx

@@ -0,0 +1,181 @@
+import { useMemo, type ReactNode } from 'react'
+import type { Editor } from '@tiptap/core'
+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 { MenuItem, MenuSub } from './Menu'
+
+/** 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
+  /** Whether the block already is this — drawn as the selected row. */
+  active?: (node: ProseMirrorNode) => boolean
+}
+
+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[]
+  /** The caller's own rows, after the editing ones. */
+  actions?: (block: HandleBlock) => ReactNode
+  /** The `EditorContent`. */
+  children: ReactNode
+  className?: string
+}
+
+/** The editor's top-level blocks, where each starts and what it is. */
+function editorBlocks(view: EditorView): HandleBlock[] {
+  const out: HandleBlock[] = []
+  view.state.doc.forEach((node, pos) => {
+    const element = view.nodeDOM(pos)
+    if (element instanceof HTMLElement) out.push({ id: (node.attrs.blockId as string | null) || undefined, element, pos })
+  })
+  return out
+}
+
+/*
+  Duplicate and Delete leave the editor focused, as Turn into and a drop do: the
+  person is still in the field, so an editor that saves when they leave it saves
+  these too — and one that loads someone else's edit while unfocused does not
+  load it over them.
+*/
+
+/** A copy of the block straight after it, the caret in the copy. `BlockId` gives the copy a fresh id; the original keeps its own. */
+export function duplicateBlock(editor: Editor, pos: number): boolean {
+  const node = editor.state.doc.nodeAt(pos)
+  if (!node) return false
+  editor.view.dispatch(editor.state.tr.insert(pos + node.nodeSize, node).scrollIntoView())
+  editor.commands.focus(pos + node.nodeSize + 1)
+  return true
+}
+
+/** Removes the block, the caret where it was. The last block of a document becomes an empty paragraph, since a document holds at least one. */
+export function deleteBlock(editor: Editor, pos: number): boolean {
+  const { state } = editor
+  const node = state.doc.nodeAt(pos)
+  if (!node) return false
+  const tr = state.doc.childCount === 1 ? state.tr.replaceWith(pos, pos + node.nodeSize, state.schema.nodes.paragraph.create()) : state.tr.delete(pos, pos + node.nodeSize)
+  editor.view.dispatch(tr)
+  editor.commands.focus(Math.min(pos + 1, editor.state.doc.content.size))
+  return true
+}
+
+/**
+ * Moves the block at `from` to `to` (a position between top-level blocks), the
+ * caret in it: what a drop in the gutter does, where the editor has no drop of
+ * its own. The node moves whole, attributes and all, so it keeps its id, as
+ * ProseMirror's drop keeps it.
+ */
+export function moveBlock(editor: Editor, from: number, to: number): boolean {
+  const node = editor.state.doc.nodeAt(from)
+  if (!node || (to >= from && to <= from + node.nodeSize)) return false
+  const tr = editor.state.tr.delete(from, from + node.nodeSize)
+  const at = tr.mapping.map(to)
+  editor.view.dispatch(tr.insert(at, node).scrollIntoView())
+  editor.commands.focus(at + 1)
+  return true
+}
+
+/**
+ * Starts the browser's own drag of the block, as ProseMirror starts one of a
+ * selected node: the block selected, its slice on `view.dragging` with `move`,
+ * and its HTML on the transfer. ProseMirror's drop then deletes the selection
+ * and inserts the slice with its attributes — so the block arrives with the
+ * id it left with, and every comment anchored to it still finds it.
+ */
+export function startBlockDrag(editor: Editor, pos: number, event: Pick<globalThis.DragEvent, 'dataTransfer'>, image?: Element) {
+  editor.commands.setNodeSelection(pos)
+  const { view } = editor
+  const slice = view.state.selection.content()
+  const { dom, text } = view.serializeForClipboard(slice)
+  const transfer = event.dataTransfer
+  if (transfer) {
+    transfer.clearData()
+    transfer.setData('text/html', dom.innerHTML)
+    transfer.setData('text/plain', text)
+    transfer.effectAllowed = 'copyMove'
+    if (image) transfer.setDragImage(image, 0, 0)
+  }
+  view.dragging = { slice, move: true }
+}
+
+/**
+ * The drop line a dragged block shows, in the package's accent instead of the
+ * editor's default (the text's colour). Give it to the editor's StarterKit:
+ * `StarterKit.configure({ dropcursor: blockDropCursor })`.
+ */
+export const blockDropCursor = { color: false, class: 'bg-accent-primary' } as const
+
+const NOTHING_YET: BlockHandleEditing = { find: () => null, rows: () => null, startDrag: () => {}, drop: () => {}, endDrag: () => {}, onChange: () => () => {} }
+
+/**
+ * `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) {
+  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
+    // Where the block being dragged starts.
+    let dragged: number | undefined
+    return {
+      find: (y) => blockAtY(editorBlocks(editor.view), y),
+      rows: (block) => {
+        const pos = block.pos
+        // Not editable: the caller's rows only, and no drag.
+        if (!editor.isEditable) return null
+        const node = pos === undefined ? null : editor.state.doc.nodeAt(pos)
+        if (pos === undefined || !node) return null
+        return (
+          <>
+            {node.isTextblock && turnInto.length > 0 && (
+              <MenuSub label="Turn into">
+                {turnInto.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)
+                    }}
+                  />
+                ))}
+              </MenuSub>
+            )}
+            <MenuItem label="Duplicate" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => duplicateBlock(editor, pos)} />
+            <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => deleteBlock(editor, pos)} />
+          </>
+        )
+      },
+      startDrag: (block, event) => {
+        dragged = block.pos
+        if (block.pos !== undefined) startBlockDrag(editor, block.pos, event, block.element)
+      },
+      drop: (target, after) => {
+        const node = target.pos === undefined ? null : editor.state.doc.nodeAt(target.pos)
+        if (dragged === undefined || target.pos === undefined || !node) return
+        moveBlock(editor, dragged, after ? target.pos + node.nodeSize : target.pos)
+      },
+      // ProseMirror clears `dragging` on its own dragend, which a drag started outside its element never reaches.
+      endDrag: () => setTimeout(() => (editor.view.dragging = null), 50),
+      onChange: (changed) => {
+        editor.on('update', changed)
+        return () => {
+          editor.off('update', changed)
+        }
+      },
+    }
+  }, [editor, turnInto])
+
+  return (
+    <BlockHandle editing={editing} actions={actions} className={className}>
+      {children}
+    </BlockHandle>
+  )
+}

package/src/editor.ts

@@ -9,6 +9,7 @@
  */
 export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
+export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
 export {
   PersonMention,
   UrgentPersonMention,

package/src/index.ts

@@ -14,6 +14,7 @@ export { AttachmentCard, type AttachmentCardProps, type AttachmentCardState } fr
 export { Avatar, hueFor, initialsFor, type AvatarProps } from './Avatar'
 export { AvatarGroup, type AvatarGroupMember, type AvatarGroupProps } from './AvatarGroup'
 export { Banner, type BannerProps, type BannerTone } from './Banner'
+export { BlockHandle, blockAtY, type BlockHandleProps, type BlockHandleEditing, type HandleBlock } from './BlockHandle'
 export { Button, type ButtonProps, type ButtonSize, type ButtonVariant } from './Button'
 export { Card, type CardAttention, type CardFill, type CardHover, type CardProps } from './Card'
 export { Checkbox, type CheckboxProps } from './Checkbox'

package/src/registry/registry.test.ts

@@ -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 122 names over 67 files: 98 components, 23 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October)', () => {
+  it('counts 130 names over 69 files: 100 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, and moveBlock and blockDropCursor, the drop in the gutter, on 5 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The ten `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: 98, helper: 23, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(67)
+    expect(kinds).toEqual({ component: 100, helper: 29, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(69)
   })
 
   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(63)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(59)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(65)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(65)
   })
 
   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

@@ -70,6 +70,8 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | Bold, italic and the like over selected text in an editor | **SelectionToolbar**, from `@estiva-app/ui/editor` — it follows the selection by itself |
 | A composer's `@`, `!@`, `[` and `/` — mention a person, reference something, format or insert | **ComposerTriggers** — `PersonMention`, `UrgentPersonMention`, `CaptionedReference`, `ReferenceTrigger` and `SlashCommands` from `@estiva-app/ui/editor`; the app passes its people, its items and its own `/` rows |
 | An editor that saves a block document and must keep its block ids | **BlockNodes** — `BlockId`, `UnknownBlock`, `ReferenceNode` and `AttachmentNode` from `@estiva-app/ui/editor`, beside StarterKit and TableKit |
+| Move, turn, duplicate or delete one block of a document being edited | **EditorBlockHandle**, from `@estiva-app/ui/editor`, with your rows after its own |
+| Offer a link or a comment on one block of a document being read | **BlockHandle** — your rows only, and no Tiptap loaded |
 | Anything with a title, body and footer | **DialogShell** |
 | "Are you sure?" | **ConfirmDialog** |
 | A picture full screen, from a thumbnail | **Lightbox** — an **AttachmentCard** opens one by itself |