@dxos/ui-editor 0.9.1-staging.ee54ba693a → 0.11.0

package/src/extensions/structure/blocks/DESIGN.md

@@ -0,0 +1,134 @@
+# Block selection, drag, and clipboard
+
+Design for gutter-driven block selection in the editor: select whole blocks
+(paragraphs, list items, headings, …), drag them to reorder, and cut/copy/paste
+them. The machinery is **document-agnostic** — markdown top-level blocks and
+outliner task lines are both just "documents" that supply the same operations.
+
+## Concept
+
+A **block selection** is an ordered set of whole blocks, distinct from
+CodeMirror's text selection. It drives which gutter drag handle is shown, what a
+drag moves, and what cut/copy/paste act on. When empty, the editor behaves
+exactly as before (text-selection cut/copy/paste, single-block drag from the
+cursor's block).
+
+## Operations contract
+
+Both documents provide the same options bag; nothing below is markdown-specific.
+
+```ts
+type Block = { from: number; to: number };
+
+type BlockOps = {
+  // Blocks in document order; ranges non-overlapping. Memoized per state.
+  getBlocks: (state: EditorState) => Block[];
+  // Move the blocks at `sourceIndices` to the slot before `dropIndex` (end when
+  // dropIndex === blocks.length), preserving their relative order, as one edit.
+  moveBlocks: (view, sourceIndices: number[], dropIndex: number) => void;
+  // Serialize blocks to text for the clipboard (markdown joins with a blank line;
+  // the outliner joins with newlines).
+  serialize: (state, blocks: Block[]) => string;
+  // Remove the blocks (with separators) and, when text is non-null, insert it at
+  // the first removed slot — one edit. null = cut (delete), non-null = paste.
+  replaceBlocks: (view, indices: number[], text: string | null) => void;
+};
+```
+
+Single-block drag is just `moveBlocks(view, [i], drop)`.
+
+## State
+
+```ts
+// Block anchors (each block's `from`), sorted. Positions — not indices — so they
+// survive edits: `update` maps each anchor through `tr.changes` (no filtering).
+const blockSelectionField: StateField<readonly number[]>;
+const setBlockSelection = StateEffect<readonly number[]>(); // replace
+const toggleBlockSelection = StateEffect<number>(); // add/remove one
+```
+
+- `getSelectedBlocks(state)` — resolves anchors to `{ block, index }` in order,
+  dropping anchors that no longer identify a block start.
+- The set is **cleared** on a non-shift `mousedown` in the content (a plain text
+  click); keyboard caret moves keep it so it can be extended.
+
+## Feature design
+
+### 1 · Handle only on the active block
+
+`gutter.markers` emits **one** handle (not one per block), at:
+
+- the top-most block in the selection set, if non-empty (feature 4); else
+- the block containing `state.selection.main.head`.
+
+Recompute on selection/set change: `lineMarkerChange: u => u.selectionSet ||
+hasEffect(u, setBlockSelection, toggleBlock)`.
+
+### 2 · Click handle → toggle the block
+
+The gutter `mousedown` is split arm → move → up:
+
+- **mousedown**: ignore non-primary button; record block + start point; do not
+  drag yet.
+- **move > 4px**: begin the real drag.
+- **mouseup without moving** = click:
+  - move the caret to the block start and **collapse** any text selection
+    (answer 3);
+  - plain: `setBlockSelection([block])`; if it was already the sole selection,
+    clear to `[]` (answer 1);
+  - `shift`: `toggleBlock(block)` — add/remove, keep the rest (feature 3).
+
+### 4 · Handle on first selected block
+
+Covered by (1)'s priority: with a non-empty set the grip sits on the top-most
+selected block, always giving the group a grab point.
+
+### 5 · Drag moves the whole selection
+
+On drag begin: if the grabbed block ∈ set and `|set| > 1`, drag the **set**; else
+drag just the grabbed block. `moveBlocks` extracts the selected blocks in document
+order, deletes them (with separators), and re-inserts them joined at the drop slot
+— they land contiguous there, order preserved, one undo step. The drop index
+skips the moving blocks (can't drop inside the group). The floating preview stacks
+the selected blocks; the placeholder height is their combined height.
+
+### 6 · Cut / copy / paste
+
+`EditorView.domEventHandlers({ copy, cut, paste })`, active only when the set is
+non-empty (else fall through to native text behavior). Mod-C/X/V route through
+these same DOM events, so no extra keymap.
+
+- **copy**: `serialize` the set → `clipboardData`; `preventDefault`; keep the set.
+- **cut**: copy + `removeBlocks`; clear the set.
+- **paste**: `insertBlocks` the clipboard text, **replacing** the selection
+  (answer 2); if the set is empty, native paste at the caret.
+
+## Cross-cutting
+
+- **Abort on `docChanged`**: the drag plugin's `update()` cancels an in-flight
+  drag when a concurrent/collaborative edit lands (stale indices would otherwise
+  resolve against a changed doc on drop).
+- **Primary button only** for drag/click.
+- **Highlight**: selected blocks get a `cm-blockSelected` border/background
+  (accent-tinted), drawn in a below-text layer by its own extension
+  (`createBlockSelectionHighlight`) so the visual travels with the drag grip
+  independently of the selection state/clipboard.
+
+## Module layout
+
+- `selection.ts` — the field + effects and `getSelectedBlocks`;
+  `createBlockSelectionHighlight(getBlocks)` (the highlight layer); and
+  `createBlockSelection(ops)` (clipboard `domEventHandlers` + clear-on-text-press).
+  Exports the module-level `blockSelectionField` (deduped by CM if included twice).
+- `drag.ts` — `createBlockDrag(ops)`: gutter + drag, reads `blockSelectionField`
+  for handle placement and multi-block drag; click/shift-click dispatch selection
+  effects.
+- `blocks.ts` — markdown `BlockOps` (findBlocks, moveBlocks, serialize,
+  replaceBlocks); public `blockSelectionHighlight()`, `blockSelection()`,
+  `blockDrag()`; `blocks()` composes highlight + selection + drag.
+- `outliner/dnd.ts` — outliner `BlockOps` over the item tree.
+
+## Non-goals (this pass)
+
+- Rectangular/column selection, cross-document drag, nested-block reparenting on
+  drop (outliner drop keeps the existing re-indent behavior).

package/src/extensions/structure/blocks/blocks.test.ts

@@ -0,0 +1,147 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown';
+import { ensureSyntaxTree } from '@codemirror/language';
+import { EditorState, type TransactionSpec } from '@codemirror/state';
+import { describe, test } from 'vitest';
+
+import { invariant } from '@dxos/invariant';
+
+import { findBlocks, moveBlocksSpec, replaceBlocksSpec } from './blocks';
+import { blockSelectionField } from './selection';
+
+const extensions = [markdown({ base: markdownLanguage }), blockSelectionField];
+
+// `findBlocks` walks the syntax tree, and CodeMirror's initial parse is budgeted in wall-clock time —
+// on a loaded CI runner it can expire having parsed almost nothing, collapsing the document to a single
+// block. Parse to the end before asserting so the tests measure `findBlocks`, not the parse scheduler.
+const parsed = (state: EditorState): EditorState => {
+  ensureSyntaxTree(state, state.doc.length, 10_000);
+  return state;
+};
+
+const create = (doc: string) => parsed(EditorState.create({ doc, extensions }));
+
+describe('findBlocks', () => {
+  test('splits into top-level blocks', ({ expect }) => {
+    const state = create('# Heading\n\npara\n\n- a\n- b');
+    const blocks = findBlocks(state);
+    expect(blocks.length).to.eq(3);
+    expect(state.doc.sliceString(blocks[0].from, blocks[0].to)).to.eq('# Heading');
+    expect(state.doc.sliceString(blocks[1].from, blocks[1].to)).to.eq('para');
+    // A list is a single block.
+    expect(state.doc.sliceString(blocks[2].from, blocks[2].to)).to.eq('- a\n- b');
+  });
+});
+
+describe('moveBlocksSpec', () => {
+  test('moves a block before another and puts the caret at its end', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, moveBlocksSpec(state, [0], 2));
+    expect(next.doc.toString()).to.eq('B\n\nA\n\nC');
+    // The caret is at the end of the moved block — not the block that took its old slot.
+    expect(charBeforeCaret(next)).to.eq('A');
+    const moved = findBlocks(next)[1];
+    expect(next.selection.main.head).to.eq(moved.to);
+  });
+
+  test('moves a block to the end', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, moveBlocksSpec(state, [0], 3));
+    expect(next.doc.toString()).to.eq('B\n\nC\n\nA');
+    expect(next.selection.main.head).to.eq(next.doc.length);
+  });
+
+  test('moves the last block without orphaning its separator', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, moveBlocksSpec(state, [2], 0));
+    expect(next.doc.toString()).to.eq('C\n\nA\n\nB');
+  });
+
+  test('moves multiple contiguous blocks as a group', ({ expect }) => {
+    const state = create('A\n\nB\n\nC\n\nD');
+    const next = apply(state, moveBlocksSpec(state, [0, 1], 4));
+    expect(next.doc.toString()).to.eq('C\n\nD\n\nA\n\nB');
+  });
+
+  test('moves multiple non-contiguous blocks, preserving order', ({ expect }) => {
+    const state = create('A\n\nB\n\nC\n\nD');
+    const next = apply(state, moveBlocksSpec(state, [0, 2], 4));
+    expect(next.doc.toString()).to.eq('B\n\nD\n\nA\n\nC');
+  });
+
+  test('keeps the moved blocks selected after the drop', ({ expect }) => {
+    const state = create('A\n\nB\n\nC\n\nD');
+    // A single block dropped before another.
+    expect(selectedText(apply(state, moveBlocksSpec(state, [1], 3)))).to.deep.eq(['B']);
+    // Multiple non-contiguous blocks moved to the end stay selected, in document order.
+    expect(selectedText(apply(state, moveBlocksSpec(state, [0, 2], 4)))).to.deep.eq(['A', 'C']);
+  });
+
+  test('is a no-op when dropping onto a source block', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    expect(moveBlocksSpec(state, [0], 0)).to.eq(null);
+    expect(moveBlocksSpec(state, [1], 1)).to.eq(null);
+  });
+
+  test('is a no-op for empty sources', ({ expect }) => {
+    const state = create('A\n\nB');
+    expect(moveBlocksSpec(state, [], 1)).to.eq(null);
+  });
+});
+
+describe('replaceBlocksSpec', () => {
+  test('cut deletes the block and its separator', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, replaceBlocksSpec(state, [1], null));
+    expect(next.doc.toString()).to.eq('A\n\nC');
+  });
+
+  test('cut removes the last block without orphaning its separator', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, replaceBlocksSpec(state, [2], null));
+    expect(next.doc.toString()).to.eq('A\n\nB');
+  });
+
+  test('cut removes multiple blocks', ({ expect }) => {
+    const state = create('A\n\nB\n\nC\n\nD');
+    const next = apply(state, replaceBlocksSpec(state, [1, 2], null));
+    expect(next.doc.toString()).to.eq('A\n\nD');
+  });
+
+  test('paste replaces the selected block with block(s)', ({ expect }) => {
+    const state = create('A\n\nB\n\nC');
+    const next = apply(state, replaceBlocksSpec(state, [1], 'X\n\nY'));
+    expect(next.doc.toString()).to.eq('A\n\nX\n\nY\n\nC');
+  });
+
+  test('is a no-op for empty indices', ({ expect }) => {
+    const state = create('A\n\nB');
+    expect(replaceBlocksSpec(state, [], 'X')).to.eq(null);
+  });
+});
+
+// The blocks selected in a state, as their source strings.
+const selectedText = (state: EditorState): string[] => {
+  const anchors = state.field(blockSelectionField);
+  const byFrom = new Map(findBlocks(state).map((block) => [block.from, block]));
+  return anchors.map((anchor) => {
+    const block = byFrom.get(anchor);
+    invariant(block, `no block at anchor ${anchor}`);
+    return state.doc.sliceString(block.from, block.to);
+  });
+};
+
+// Applies a (non-null) transaction spec and returns the resulting state.
+const apply = (state: EditorState, spec: TransactionSpec | null): EditorState => {
+  invariant(spec, 'expected a transaction spec');
+  return parsed(state.update(spec).state);
+};
+
+// The character at the caret's left, so tests can assert the caret lands at the end of a moved block.
+const charBeforeCaret = (state: EditorState) => {
+  const head = state.selection.main.head;
+  return state.doc.sliceString(head - 1, head);
+};

package/src/extensions/structure/blocks/blocks.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type EditorState, type Extension, type TransactionSpec } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import { createBlockDrag } from './drag';
+import { type BlockOps, createBlockSelection, createBlockSelectionHighlight, setBlockSelection } from './selection';
+import { type Block } from './types';
+
+export type BlockOptions = {
+  /**
+   * Pin the drag preview to the block's left edge so it only tracks vertically (default `true`).
+   * When `false`, the preview follows the pointer on both axes.
+   */
+  clampX?: boolean;
+};
+
+/**
+ * Whole-block editing over the top-level markdown blocks: click/shift-click the gutter grip to select,
+ * drag-to-reorder, cut/copy/paste, with a border/background behind the selection. Composes
+ * `blockSelectionHighlight` (the box behind selected blocks), `blockSelection` (selection state and
+ * clipboard), and `blockDrag` (the gutter grip that populates the selection and drag-to-move). The grip
+ * lives in `blockDrag` and drives the selection, so these are used together (or via this `blocks()`).
+ */
+export const blocks = ({ clampX }: BlockOptions = {}): Extension => [
+  blockSelectionHighlight(),
+  blockSelection(),
+  blockDrag({ clampX }),
+];
+
+/**
+ * Draws a border/background box behind each selected top-level markdown block. See
+ * `createBlockSelectionHighlight`.
+ */
+export const blockSelectionHighlight = (): Extension => createBlockSelectionHighlight(findBlocks);
+
+/**
+ * Whole-block selection state and block cut/copy/paste over the top-level markdown blocks. The gutter
+ * grip gesture that populates the selection is provided by `blockDrag` and the highlight by
+ * `blockSelectionHighlight`, so pair them (or use `blocks()`, which composes them). See
+ * `createBlockSelection`.
+ */
+export const blockSelection = (): Extension => createBlockSelection(markdownBlockOps);
+
+/**
+ * Adds a gutter drag grip to the active markdown block and moves the block (or the whole block
+ * selection) on drop. See `createBlockDrag`.
+ */
+export const blockDrag = ({ clampX }: Pick<BlockOptions, 'clampX'> = {}): Extension =>
+  createBlockDrag({ getBlocks: findBlocks, moveBlocks, clampX });
+
+/**
+ * Top-level markdown blocks (headings, paragraphs, lists, blockquotes, fenced code, …) from the
+ * syntax tree, so a list or code fence moves and boxes as a single unit. Memoized per state — the
+ * highlight layer, the gutter, and the drag plugin all query it on the same state.
+ */
+const blockCache = new WeakMap<EditorState, Block[]>();
+
+export const findBlocks = (state: EditorState): Block[] => {
+  const cached = blockCache.get(state);
+  if (cached) {
+    return cached;
+  }
+
+  const blocks: Block[] = [];
+  const cursor = syntaxTree(state).topNode.cursor();
+  if (cursor.firstChild()) {
+    do {
+      if (cursor.to > cursor.from) {
+        blocks.push({ from: cursor.from, to: cursor.to });
+      }
+    } while (cursor.nextSibling());
+  }
+
+  blockCache.set(state, blocks);
+  return blocks;
+};
+
+// Merges sorted ranges, combining any that overlap or touch.
+const mergeRanges = (ranges: { from: number; to: number }[]): { from: number; to: number }[] => {
+  const sorted = [...ranges].sort((a, b) => a.from - b.from);
+  const merged: { from: number; to: number }[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (last && range.from <= last.to) {
+      last.to = Math.max(last.to, range.to);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+};
+
+// Delete ranges for the given blocks: each block plus its blank-line separator (the one below it, down to
+// the next block; for the last block the one above it instead, so no trailing blank is orphaned), merged
+// so adjacent selections form one range.
+const deleteRanges = (state: EditorState, blocks: Block[], indices: number[]): { from: number; to: number }[] => {
+  const count = blocks.length;
+  return mergeRanges(
+    indices.map((index) => ({
+      from: index === count - 1 && index > 0 ? blocks[index - 1].to : blocks[index].from,
+      to: index + 1 < count ? blocks[index + 1].from : state.doc.length,
+    })),
+  );
+};
+
+/**
+ * Transaction that moves the blocks at `sourceIndices` to the slot before `dropIndex` (the end of the
+ * document when `dropIndex === blocks.length`), preserving their relative order and blank-line
+ * separation, as a single undo step. Places the caret at the end of the moved content and clears the
+ * block selection. Returns `null` for a no-op (empty/invalid sources, or a drop inside the moved region).
+ * Pure — exported for tests.
+ */
+export const moveBlocksSpec = (
+  state: EditorState,
+  sourceIndices: number[],
+  dropIndex: number,
+): TransactionSpec | null => {
+  const blocks = findBlocks(state);
+  const count = blocks.length;
+  const sources = [...new Set(sourceIndices)].filter((index) => index >= 0 && index < count).sort((a, b) => a - b);
+  // Dropping onto a selected block is a no-op.
+  if (sources.length === 0 || sources.includes(dropIndex)) {
+    return null;
+  }
+
+  const text = sources.map((index) => state.doc.sliceString(blocks[index].from, blocks[index].to)).join('\n\n');
+  const deletes = deleteRanges(state, blocks, sources);
+  const insertAt = dropIndex < count ? blocks[dropIndex].from : state.doc.length;
+  // Dropping inside the removed region is a no-op.
+  if (deletes.some((range) => insertAt > range.from && insertAt < range.to)) {
+    return null;
+  }
+
+  const insert = dropIndex < count ? `${text}\n\n` : `\n\n${text}`;
+  const changes = [...deletes.map((range) => ({ from: range.from, to: range.to })), { from: insertAt, insert }];
+  // The inserted text starts where `insertAt` maps to (dropping any deletes before it), then `text` sits
+  // at its start (or after the `\n\n` prefix when appending).
+  const changeSet = state.changes(changes);
+  const textStart = changeSet.mapPos(insertAt, -1) + (dropIndex < count ? 0 : 2);
+  // Keep the moved blocks selected: their new anchors are the start of each block within the inserted
+  // text, joined by `\n\n` (block length + 2). The caret lands at the end of the moved content.
+  const anchors: number[] = [];
+  let anchor = textStart;
+  for (const index of sources) {
+    anchors.push(anchor);
+    anchor += blocks[index].to - blocks[index].from + 2;
+  }
+  const caret = textStart + text.length;
+  return {
+    changes,
+    selection: { anchor: Math.min(caret, changeSet.newLength) },
+    effects: setBlockSelection.of(anchors),
+    userEvent: 'move.block',
+  };
+};
+
+const moveBlocks = (view: EditorView, sourceIndices: number[], dropIndex: number): void => {
+  const spec = moveBlocksSpec(view.state, sourceIndices, dropIndex);
+  if (spec) {
+    view.dispatch(spec);
+  }
+};
+
+/**
+ * Transaction that removes the blocks at `indices` and, when `text` is non-null, inserts it as block(s)
+ * at the first removed slot — a single edit. `null` is a pure delete (cut); non-null is a replace
+ * (paste). Returns `null` for a no-op. Pure — exported for tests.
+ */
+export const replaceBlocksSpec = (
+  state: EditorState,
+  indices: number[],
+  text: string | null,
+): TransactionSpec | null => {
+  const blocks = findBlocks(state);
+  const count = blocks.length;
+  const sources = [...new Set(indices)].filter((index) => index >= 0 && index < count).sort((a, b) => a - b);
+  if (sources.length === 0) {
+    return null;
+  }
+
+  const deletes = deleteRanges(state, blocks, sources);
+  const changes: { from: number; to: number; insert?: string }[] = deletes.map((range) => ({
+    from: range.from,
+    to: range.to,
+  }));
+  let anchor = deletes[0].from;
+  if (text != null && text.length > 0) {
+    // Replace the first removed range with the pasted text (keeping a trailing blank unless at doc end).
+    const insert = deletes[0].to >= state.doc.length ? text : `${text}\n\n`;
+    changes[0] = { from: deletes[0].from, to: deletes[0].to, insert };
+    anchor = deletes[0].from + text.length;
+  }
+
+  const changeSet = state.changes(changes);
+  return {
+    changes,
+    selection: { anchor: Math.min(anchor, changeSet.newLength) },
+    effects: setBlockSelection.of([]),
+    userEvent: text == null ? 'delete.block' : 'input.paste',
+  };
+};
+
+const replaceBlocks = (view: EditorView, indices: number[], text: string | null): void => {
+  const spec = replaceBlocksSpec(view.state, indices, text);
+  if (spec) {
+    view.dispatch(spec);
+  }
+};
+
+export const markdownBlockOps: BlockOps = {
+  getBlocks: findBlocks,
+  moveBlocks,
+  serialize: (state, blocks) => blocks.map((block) => state.doc.sliceString(block.from, block.to)).join('\n\n'),
+  replaceBlocks,
+};