@llui/markdown-editor 0.3.0 → 0.5.0

package/dist/plugins/block-drag.js

@@ -0,0 +1,983 @@
+// Block drag-and-drop reordering — a hover gutter grip that reorders TOP-LEVEL
+// blocks, by pointer drag or by keyboard.
+//
+// ## Why not HTML5 drag-and-drop
+// `draggable=true` + `dragover`/`drop` cannot work here: the drag source lives in
+// a portaled overlay while the drop zone is a `contenteditable`, and Lexical owns
+// the native drag/drop pipeline for content insertion. Hijacking it fights the
+// editor. Raw `mousedown` → document `mousemove`/`mouseup` (the same mechanics the
+// reference ProseMirror implementation uses) keeps the editor's own drag handling
+// untouched and gives exact control over the drop-slot geometry.
+//
+// ## Why the reorder goes through Lexical, never the DOM
+// Moving DOM nodes under a `contenteditable` desynchronizes Lexical's node map
+// from the DOM and is reverted on the next reconcile. The commit is a single
+// `target.insertAfter(source)` / `insertBefore` inside one `editor.update`, so it
+// is ONE undo step, replays correctly through the collab CRDT (`@lexical/yjs`
+// observes node moves, not DOM mutations), and preserves the moved node's key —
+// selection anchored inside it (or inside any other block) survives.
+//
+// ## Shape
+// All geometry is PURE (see {@link blockAtPoint} / {@link findDropTarget} /
+// {@link indicatorRect}): the DOM layer only measures rects and feeds numbers in.
+// Everything rendered lives in this plugin's JSON state slice and is drawn with
+// the package's shared {@link overlayRoot} primitive — no competing overlay
+// system, no imperative DOM writes in the view.
+//
+// ## Stacking
+// Both surfaces sit BELOW the `OVERLAY_Z` scale in `overlay.ts` (60+): the gutter
+// grip and the drop indicator are chrome for the document body and must never
+// cover a typeahead, the context menu, or the floating toolbar.
+import { $getNodeByKey, $getRoot, $getSelection, $isElementNode, $isRangeSelection, COMMAND_PRIORITY_LOW, KEY_DOWN_COMMAND, } from 'lexical';
+import { mergeRegister } from '@lexical/utils';
+import { button, div, onMount, text } from '@llui/dom';
+import { definePluginUI } from './ui.js';
+import { onViewportChange, overlayRoot } from './overlay.js';
+/** Stacking levels for this plugin's two surfaces — deliberately below the
+ * shared `OVERLAY_Z` scale (60+) so document chrome never covers a menu. */
+export const BLOCK_DRAG_Z = { handle: 58, indicator: 59, menu: 62 };
+/** Pixels of pointer travel before a grip mousedown becomes a drag (below the
+ * threshold it is a click, which toggles keyboard grab mode instead). */
+const DRAG_THRESHOLD = 5;
+/** Vertical slack when deciding which block the pointer is "on" — block margins
+ * leave real gaps between rects, and the gutter must not flicker across them. */
+const HOVER_TOLERANCE = 6;
+/** How far LEFT of the editor's content box the hover zone extends, i.e. how
+ * much room the gutter grip is given. */
+const GUTTER_WIDTH = 40;
+// ── Pure geometry ───────────────────────────────────────────────────────────
+/**
+ * The block whose vertical band contains `clientY`, or `null` when the pointer
+ * is in no block's band.
+ *
+ * TWO passes, and the order matters. A block's OWN rect always wins outright;
+ * only a point in no block at all falls through to the widened search, where
+ * the NEAREST band within `tolerance` wins (ties biased upward, matching how a
+ * reader attributes a gap to the block above it).
+ *
+ * A single widened pass with first-match-wins — which this was — is wrong
+ * wherever two rects touch or nearly touch, and touching rects are the common
+ * case, not the exotic one: list items, table rows, consecutive lines, and any
+ * margin-collapsed heading. With `tolerance = 6` and adjacent rects [0,20] and
+ * [20,40], every y in [20,26] resolved to the FIRST block, so the block below
+ * lost the top 6px of its own body — the grip targeted, grabbed and dragged the
+ * wrong block. Generally, for an inter-block gap `g < tolerance`, block N stole
+ * the first `tolerance - g` px of block N+1.
+ */
+export function blockAtPoint(blocks, clientY, tolerance = HOVER_TOLERANCE) {
+    for (const block of blocks) {
+        if (clientY >= block.top && clientY <= block.bottom)
+            return block;
+    }
+    let best = null;
+    let bestDistance = Infinity;
+    for (const block of blocks) {
+        const distance = clientY < block.top
+            ? block.top - clientY
+            : clientY > block.bottom
+                ? clientY - block.bottom
+                : 0;
+        if (distance <= tolerance && distance < bestDistance) {
+            best = block;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * The slot `clientY` points at, expressed relative to a neighbouring block.
+ *
+ * The document has `n + 1` slots for `n` blocks; the slot index is the count of
+ * blocks whose vertical midpoint is above the pointer. Two of those slots are
+ * where `sourceKey` already sits — dropping there is a no-op, so both return
+ * `null` and the caller shows no indicator and commits nothing. That check is
+ * what stops a 1px twitch from producing a spurious undo entry.
+ */
+export function findDropTarget(blocks, clientY, sourceKey) {
+    const sourceIndex = blocks.findIndex((b) => b.key === sourceKey);
+    if (sourceIndex === -1)
+        return null;
+    let slot = 0;
+    for (const block of blocks) {
+        if (clientY > (block.top + block.bottom) / 2)
+            slot++;
+        else
+            break;
+    }
+    // The two boundaries of the source's own slot are both no-ops.
+    if (slot === sourceIndex || slot === sourceIndex + 1)
+        return null;
+    if (slot === 0)
+        return { key: blocks[0].key, place: 'before' };
+    return { key: blocks[slot - 1].key, place: 'after' };
+}
+/** Where to draw the indicator line for a resolved {@link DropTarget}: on the
+ * target's top edge for `before`, its bottom edge for `after`. */
+export function indicatorRect(blocks, target) {
+    const block = blocks.find((b) => b.key === target.key);
+    if (!block)
+        return null;
+    return {
+        x: block.left,
+        y: target.place === 'before' ? block.top : block.bottom,
+        width: block.width,
+    };
+}
+// ── Lexical reads / writes ──────────────────────────────────────────────────
+/** Measure every top-level block. Blocks with no rendered element (never the
+ * case in practice, but possible mid-reconcile) are skipped rather than
+ * measured as zeros, which would corrupt every midpoint comparison. */
+function readBlockRects(editor) {
+    const keys = editor.getEditorState().read(() => $getRoot()
+        .getChildren()
+        .map((n) => n.getKey()));
+    const rects = [];
+    for (const key of keys) {
+        const el = editor.getElementByKey(key);
+        if (!el)
+            continue;
+        const r = el.getBoundingClientRect();
+        rects.push({ key, top: r.top, bottom: r.bottom, left: r.left, width: r.width });
+    }
+    return rects;
+}
+/** A short, speakable name for a block: its leading text, else its node type. */
+function blockLabel(node) {
+    const content = node.getTextContent().trim().replace(/\s+/g, ' ');
+    if (content === '')
+        return node.getType();
+    return content.length > 32 ? `${content.slice(0, 32)}…` : content;
+}
+/** Move `sourceKey` to `place` `targetKey` among the root's children, inside the
+ * caller's `editor.update`. Returns `null` (no mutation, so no undo entry) when
+ * either key is stale, they are the same node, or the move is a no-op. */
+function $moveBlock(sourceKey, targetKey, place) {
+    if (sourceKey === targetKey)
+        return null;
+    const root = $getRoot();
+    const children = root.getChildren();
+    const source = children.find((n) => n.getKey() === sourceKey);
+    const target = children.find((n) => n.getKey() === targetKey);
+    if (!source || !target)
+        return null;
+    const sourceIndex = source.getIndexWithinParent();
+    const targetIndex = target.getIndexWithinParent();
+    // Already in that slot — mutating would push an empty undo step.
+    if (place === 'after' && targetIndex === sourceIndex - 1)
+        return null;
+    if (place === 'before' && targetIndex === sourceIndex + 1)
+        return null;
+    const label = blockLabel(source);
+    // `insertAfter`/`insertBefore` detach the node from its current parent first
+    // and re-anchor an element-anchored selection, so this is a true move.
+    if (place === 'after')
+        target.insertAfter(source);
+    else
+        target.insertBefore(source);
+    return {
+        key: sourceKey,
+        announcement: `${label} moved to position ${source.getIndexWithinParent() + 1} of ${root.getChildrenSize()}.`,
+    };
+}
+/** Move the block one slot up (`-1`) or down (`1`). Clamped at both ends, where
+ * it reports the boundary rather than silently doing nothing. */
+function $shiftBlock(key, direction) {
+    const root = $getRoot();
+    const children = root.getChildren();
+    const index = children.findIndex((n) => n.getKey() === key);
+    if (index === -1)
+        return null;
+    const next = index + direction;
+    if (next < 0)
+        return { key, announcement: 'Already at the first position.' };
+    if (next >= children.length)
+        return { key, announcement: 'Already at the last position.' };
+    const neighbour = children[next];
+    return $moveBlock(key, neighbour.getKey(), direction === 1 ? 'after' : 'before');
+}
+/** Deep-clone a node with FRESH keys via serialize→deserialize. `constructor.clone`
+ * is unusable here — it preserves the key, so the "copy" would collide with the
+ * original. `importJSON(exportJSON())` mints a new node; element children are not
+ * carried by `exportJSON`, so they are cloned and re-appended recursively. */
+function $cloneNode(node) {
+    const klass = node.constructor;
+    const clone = klass.importJSON(node.exportJSON());
+    if ($isElementNode(node) && $isElementNode(clone)) {
+        for (const child of node.getChildren())
+            clone.append($cloneNode(child));
+    }
+    return clone;
+}
+/** Insert a deep copy of the top-level block `key` immediately after it. */
+function $duplicateBlock(key) {
+    const node = $getNodeByKey(key);
+    if (node === null)
+        return null;
+    const clone = $cloneNode(node);
+    node.insertAfter(clone);
+    return { key: clone.getKey(), announcement: `${blockLabel(node)} duplicated.` };
+}
+/** Remove the top-level block `key`. Returns the announcement, or `null` when the
+ * key is stale. */
+function $deleteBlock(key) {
+    const node = $getNodeByKey(key);
+    if (node === null)
+        return null;
+    const label = blockLabel(node);
+    node.remove();
+    return { announcement: `${label} deleted.` };
+}
+/** Put a collapsed selection at the start of block `key` so a selection-based
+ * command (the turn-into items) acts on THAT block. Returns whether it selected. */
+function $selectBlockStart(key) {
+    const node = $getNodeByKey(key);
+    if (node === null)
+        return false;
+    node.selectStart();
+    return true;
+}
+const INITIAL = {
+    handleVisible: false,
+    handleX: 0,
+    handleY: 0,
+    hoverKey: '',
+    dragging: false,
+    indicatorVisible: false,
+    indicatorX: 0,
+    indicatorY: 0,
+    indicatorWidth: 0,
+    grabbedKey: '',
+    menuOpen: false,
+    menuKey: '',
+    menuX: 0,
+    menuY: 0,
+    announce: '',
+    announceNonce: 0,
+    keyboardReveal: false,
+};
+function hideIndicator(state) {
+    return state.indicatorVisible ? { ...state, indicatorVisible: false } : state;
+}
+/**
+ * INVARIANT: a grab cannot outlive the grip that owns it —
+ * `handleVisible === false` implies `grabbedKey === ''`.
+ *
+ * Enforced in ONE place, on every reducer result, rather than at each case that
+ * hides the handle. Violating it wedges the gutter permanently and
+ * unrecoverably: `hover` and `hoverOut` are both hard-gated on
+ * `grabbedKey === ''`, so once the handle is hidden with a grab still pending,
+ * every subsequent hover is swallowed and the grip never renders again — and the
+ * only senders of `releaseGrab` are the grip's own `onKeyDown`/`onBlur`, which
+ * cannot fire on a grip that is not in the DOM.
+ *
+ * It was originally three separate clears (`dragStart`, `dragEnd`, `drop`).
+ * That worked, but it was untestable: the three were mutually redundant, so
+ * deleting any ONE of them left every test green while re-arming the bug for the
+ * next path someone added. A single invariant is both DRY and pinnable.
+ */
+function normalize(state) {
+    if (state.handleVisible || state.grabbedKey === '')
+        return state;
+    return { ...state, grabbedKey: '' };
+}
+function reduceRaw(state, msg) {
+    switch (msg.type) {
+        case 'hover':
+            // While a block is grabbed, being dragged, or the menu is open the gutter is
+            // pinned — a stray pointer move must not silently re-target the pending op.
+            if (state.grabbedKey !== '' || state.dragging || state.menuOpen)
+                return state;
+            if (state.handleVisible &&
+                state.hoverKey === msg.key &&
+                state.handleX === msg.x &&
+                state.handleY === msg.y)
+                return state;
+            return {
+                ...state,
+                handleVisible: true,
+                hoverKey: msg.key,
+                handleX: msg.x,
+                handleY: msg.y,
+                keyboardReveal: false,
+            };
+        case 'revealAtSelection':
+            // The KEYBOARD entry point. The grip is rendered only while
+            // `handleVisible`, which `hover` alone could set — and `hover` is produced
+            // only by `mousemove`. So without this message the grip was never in the
+            // DOM and never in the tab order for a keyboard or screen-reader user, and
+            // the unconditional help text ("Press Enter or Space to grab this block…")
+            // described an affordance they could not reach. Reordering was mouse-only.
+            // Reveal AND grab in one step: the grip's Enter/Space now opens the actions
+            // menu, so the keyboard reorder path (Mod+Shift+D / the "Move block" command)
+            // enters grab mode directly rather than only revealing a grip the user would
+            // then have to Enter — which would open the menu instead of grabbing.
+            return [
+                {
+                    ...state,
+                    handleVisible: true,
+                    hoverKey: msg.key,
+                    handleX: msg.x,
+                    handleY: msg.y,
+                    keyboardReveal: true,
+                    grabbedKey: msg.key,
+                },
+                [{ type: 'describe', key: msg.key, grabbed: true }],
+            ];
+        case 'hoverOut':
+            if (state.grabbedKey !== '' || state.dragging || state.menuOpen)
+                return state;
+            return state.handleVisible ? { ...state, handleVisible: false } : state;
+        case 'dragStart':
+            // The grip is hidden for the duration: it sits under the cursor and would
+            // otherwise read as a second, stationary drop affordance.
+            //
+            // Any pending grab is dropped by `normalize` below, because the handle is
+            // going away.
+            return { ...state, dragging: true, handleVisible: false };
+        case 'dragOver':
+            return {
+                ...state,
+                indicatorVisible: true,
+                indicatorX: msg.x,
+                indicatorY: msg.y,
+                indicatorWidth: msg.width,
+            };
+        case 'dragOverNone':
+            return hideIndicator(state);
+        case 'dragEnd':
+            return { ...hideIndicator(state), dragging: false };
+        case 'drop':
+            return [
+                { ...state, dragging: false, indicatorVisible: false, handleVisible: false },
+                [{ type: 'move', sourceKey: msg.sourceKey, targetKey: msg.targetKey, place: msg.place }],
+            ];
+        case 'toggleGrab': {
+            if (state.grabbedKey !== '')
+                return [
+                    { ...state, grabbedKey: '' },
+                    [{ type: 'describe', key: state.grabbedKey, grabbed: false }],
+                ];
+            if (state.hoverKey === '')
+                return state;
+            return [
+                { ...state, grabbedKey: state.hoverKey },
+                [{ type: 'describe', key: state.hoverKey, grabbed: true }],
+            ];
+        }
+        case 'moveGrabbed':
+            if (state.grabbedKey === '')
+                return state;
+            return [state, [{ type: 'shift', key: state.grabbedKey, direction: msg.direction }]];
+        case 'releaseGrab':
+            // Announce the cancellation rather than BLANKING the live region. This is
+            // also the `onBlur` handler, so clearing it meant Escape (and any focus
+            // loss) silently ended a grab with nothing spoken.
+            return state.grabbedKey === ''
+                ? state
+                : {
+                    ...state,
+                    grabbedKey: '',
+                    announce: 'Reorder cancelled.',
+                    announceNonce: state.announceNonce + 1,
+                };
+        case 'openMenu':
+            // The grip stays visible as the menu's anchor; the hover gate below then
+            // pins the gutter (a stray pointer move must not re-target while the menu
+            // is open). A menu with no target block is meaningless.
+            if (msg.key === '')
+                return state;
+            return { ...state, menuOpen: true, menuKey: msg.key, menuX: msg.x, menuY: msg.y };
+        case 'closeMenu':
+            return state.menuOpen ? { ...state, menuOpen: false } : state;
+        case 'shiftBlock':
+            return [
+                { ...state, menuOpen: false },
+                [{ type: 'shift', key: msg.key, direction: msg.direction }],
+            ];
+        case 'duplicate':
+            return [{ ...state, menuOpen: false }, [{ type: 'duplicate', key: msg.key }]];
+        case 'deleteBlock':
+            return [{ ...state, menuOpen: false }, [{ type: 'delete', key: msg.key }]];
+        case 'announce':
+            // The nonce is what makes a REPEATED announcement audible. `aria-live`
+            // regions re-announce on text CHANGE, so two identical strings in a row —
+            // pressing ArrowUp twice at the top of the document, which yields
+            // 'Already at the first position.' both times — left the second one
+            // silent. The nonce is not rendered; it only forces the text binding to
+            // re-commit. (Bumped unconditionally, so even a deduped-by-value message
+            // still speaks.)
+            return { ...state, announce: msg.text, announceNonce: state.announceNonce + 1 };
+        case 'reposition':
+            return state.handleX === msg.x && state.handleY === msg.y
+                ? state
+                : { ...state, handleX: msg.x, handleY: msg.y };
+    }
+}
+function reduce(state, msg) {
+    const out = reduceRaw(state, msg);
+    return Array.isArray(out) ? [normalize(out[0]), out[1]] : normalize(out);
+}
+let seq = 0;
+/**
+ * Reorder top-level blocks by dragging a hover gutter grip, or from the keyboard
+ * (focus the grip, Enter/Space to grab, ↑/↓ to move, Enter/Space to drop, Escape
+ * to cancel). Every reorder is one Lexical node move, hence one undo step.
+ */
+export function blockDragPlugin(options = {}) {
+    const gutterOffset = options.gutterOffset ?? 28;
+    const sessions = new WeakMap();
+    /** Per-editor keyboard entry point, so the command item can reach it. */
+    const revealers = new WeakMap();
+    const uid = `md-block-drag-${++seq}`;
+    const helpId = `${uid}-help`;
+    const gripId = `${uid}-grip`;
+    const menuId = `${uid}-menu`;
+    // The block-type conversions offered in the actions menu's "Turn into" section,
+    // captured from the merged command items so any plugin's block type appears
+    // automatically. Turn-into items are the block/list-group items that report an
+    // active block type (`isActive`), which excludes inserts and this plugin's own
+    // "Move block" command. Read once at construction.
+    let turnIntoItems = [];
+    return {
+        name: 'blockDrag',
+        onItems: (all) => {
+            turnIntoItems = all.filter((i) => (i.group === 'block' || i.group === 'list') && i.isActive !== undefined);
+        },
+        // The command-surface half of the keyboard entry point (Mod+Shift+D is the
+        // direct binding). Without one of these two, the entire reorder protocol —
+        // and the help text that describes it — is unreachable without a pointer.
+        items: [
+            {
+                id: 'blockDrag',
+                label: 'Move block',
+                icon: 'blockDrag',
+                group: 'block',
+                keywords: ['move', 'reorder', 'drag', 'block'],
+                run: (editor) => {
+                    revealers.get(editor)?.();
+                },
+                surfaces: ['slash', 'context'],
+            },
+        ],
+        // Hover tracking only. The drag session itself is owned by the view (it is
+        // started by the grip's own mousedown), which keeps the two concerns apart:
+        // `register` answers "which block is the pointer near", the view answers
+        // "where would a drop land".
+        register: (editor, ctx) => {
+            const session = { dragging: false };
+            sessions.set(editor, session);
+            let lastKey = '';
+            let pending = 0;
+            const measure = (event) => {
+                // A read-only editor gets no reorder affordance at all.
+                if (!editor.isEditable() || session.dragging)
+                    return;
+                const root = editor.getRootElement();
+                if (!root)
+                    return;
+                const bounds = root.getBoundingClientRect();
+                // The live zone is the content box widened LEFT by the gutter, so the
+                // pointer can travel onto the grip without the handle vanishing.
+                const inside = event.clientX >= bounds.left - GUTTER_WIDTH &&
+                    event.clientX <= bounds.right &&
+                    event.clientY >= bounds.top - HOVER_TOLERANCE &&
+                    event.clientY <= bounds.bottom + HOVER_TOLERANCE;
+                if (!inside) {
+                    if (lastKey !== '') {
+                        lastKey = '';
+                        ctx.emit({ type: 'plugin', name: 'blockDrag', msg: { type: 'hoverOut' } });
+                    }
+                    return;
+                }
+                const blocks = readBlockRects(editor);
+                const block = blockAtPoint(blocks, event.clientY);
+                if (!block) {
+                    if (lastKey !== '') {
+                        lastKey = '';
+                        ctx.emit({ type: 'plugin', name: 'blockDrag', msg: { type: 'hoverOut' } });
+                    }
+                    return;
+                }
+                lastKey = block.key;
+                ctx.emit({
+                    type: 'plugin',
+                    name: 'blockDrag',
+                    msg: {
+                        type: 'hover',
+                        key: block.key,
+                        x: block.left - gutterOffset,
+                        y: block.top,
+                    },
+                });
+            };
+            // Coalesce to one measurement per frame: `mousemove` fires far faster than
+            // the handle can meaningfully move, and each tick costs a layout read.
+            // Keep the LATEST event, not the first of the frame. Discarding the rest
+            // positioned the grip from stale coordinates: during a fast sweep the
+            // pointer can cross two or three blocks inside one frame, and the handle
+            // would resolve to the block the pointer was over when the frame STARTED.
+            let latest = null;
+            const onMouseMove = (event) => {
+                latest = event;
+                if (pending)
+                    return;
+                pending = requestAnimationFrame(() => {
+                    pending = 0;
+                    if (latest)
+                        measure(latest);
+                });
+            };
+            const hide = () => {
+                if (session.dragging)
+                    return;
+                lastKey = '';
+                ctx.emit({ type: 'plugin', name: 'blockDrag', msg: { type: 'hoverOut' } });
+            };
+            /**
+             * Reveal the grip for the block containing the caret and focus it, so the
+             * whole reorder protocol is reachable without a pointer. Bound to
+             * Mod+Shift+D below and also exposed as a command item.
+             */
+            const revealAtSelection = () => {
+                if (!editor.isEditable())
+                    return false;
+                const key = editor.getEditorState().read(() => {
+                    const selection = $getSelection();
+                    if (!$isRangeSelection(selection))
+                        return null;
+                    return selection.anchor.getNode().getTopLevelElement()?.getKey() ?? null;
+                });
+                if (!key)
+                    return false;
+                const block = readBlockRects(editor).find((b) => b.key === key);
+                if (!block)
+                    return false;
+                lastKey = key;
+                ctx.emit({
+                    type: 'plugin',
+                    name: 'blockDrag',
+                    msg: {
+                        type: 'revealAtSelection',
+                        key,
+                        x: block.left - gutterOffset,
+                        y: block.top,
+                    },
+                });
+                return true;
+            };
+            revealers.set(editor, revealAtSelection);
+            // Right-click a block → the same actions menu, at the pointer. Scoped to the
+            // editor's own content (a contextmenu elsewhere keeps the native menu).
+            const onContextMenu = (event) => {
+                if (!editor.isEditable() || session.dragging)
+                    return;
+                const root = editor.getRootElement();
+                if (!root || !(event.target instanceof Node) || !root.contains(event.target))
+                    return;
+                const block = blockAtPoint(readBlockRects(editor), event.clientY);
+                if (!block)
+                    return;
+                event.preventDefault();
+                ctx.emit({
+                    type: 'plugin',
+                    name: 'blockDrag',
+                    msg: { type: 'openMenu', key: block.key, x: event.clientX, y: event.clientY },
+                });
+            };
+            document.addEventListener('mousemove', onMouseMove, { passive: true });
+            document.addEventListener('contextmenu', onContextMenu);
+            return mergeRegister(() => {
+                document.removeEventListener('mousemove', onMouseMove);
+                document.removeEventListener('contextmenu', onContextMenu);
+                if (pending)
+                    cancelAnimationFrame(pending);
+                sessions.delete(editor);
+                revealers.delete(editor);
+            }, editor.registerCommand(KEY_DOWN_COMMAND, (event) => {
+                if (event.key !== 'D' && event.key !== 'd')
+                    return false;
+                if (!event.shiftKey || !(event.metaKey || event.ctrlKey))
+                    return false;
+                if (!revealAtSelection())
+                    return false;
+                event.preventDefault();
+                return true;
+            }, COMMAND_PRIORITY_LOW), 
+            // Any scroll invalidates the measured gutter position; recomputing from a
+            // stale pointer is wrong, so simply retract the handle.
+            onViewportChange(hide));
+        },
+        ui: definePluginUI({
+            init: () => ({ ...INITIAL }),
+            update: reduce,
+            onEffect: (effect, ctx) => {
+                const editor = ctx.editor();
+                if (!editor)
+                    return;
+                if (effect.type === 'describe') {
+                    const label = editor.getEditorState().read(() => {
+                        const node = $getRoot()
+                            .getChildren()
+                            .find((n) => n.getKey() === effect.key);
+                        return node ? blockLabel(node) : '';
+                    });
+                    ctx.send({
+                        type: 'announce',
+                        text: effect.grabbed
+                            ? `${label} grabbed. Use the up and down arrow keys to move it, Enter to drop, Escape to cancel.`
+                            : `${label} dropped.`,
+                    });
+                    return;
+                }
+                // Held in a box rather than a bare `let`: the assignment happens inside
+                // the update callback, which TypeScript's control-flow analysis cannot
+                // see, so a plain local would narrow to `null` at every read below. `key`
+                // is the block to re-anchor the gutter to (`null` for delete — the block
+                // is gone, so there is nothing to follow).
+                const box = {
+                    outcome: null,
+                };
+                editor.update(() => {
+                    switch (effect.type) {
+                        case 'move':
+                            box.outcome = $moveBlock(effect.sourceKey, effect.targetKey, effect.place);
+                            break;
+                        case 'shift':
+                            box.outcome = $shiftBlock(effect.key, effect.direction);
+                            break;
+                        case 'duplicate':
+                            box.outcome = $duplicateBlock(effect.key);
+                            break;
+                        case 'delete': {
+                            const removed = $deleteBlock(effect.key);
+                            box.outcome = removed ? { key: null, announcement: removed.announcement } : null;
+                            break;
+                        }
+                    }
+                }, {
+                    // Re-measure AFTER reconciliation so the gutter follows the block it
+                    // is pinned to; measuring inside the update would read the old layout.
+                    onUpdate: () => {
+                        const moved = box.outcome;
+                        if (!moved || moved.key === null)
+                            return;
+                        const el = editor.getElementByKey(moved.key);
+                        if (!el)
+                            return;
+                        const r = el.getBoundingClientRect();
+                        ctx.send({ type: 'reposition', x: r.left - gutterOffset, y: r.top });
+                    },
+                });
+                const moved = box.outcome;
+                if (moved)
+                    ctx.send({ type: 'announce', text: moved.announcement });
+            },
+            view: ({ state, send, editor }) => {
+                // The pointer drag session. Installed on `document` for the duration of a
+                // single drag and torn down on mouseup, so nothing lingers between drags;
+                // `abort` covers the unmount-mid-drag case.
+                let abort = null;
+                const beginDrag = (event) => {
+                    const live = editor();
+                    if (!live || !live.isEditable())
+                        return;
+                    const sourceKey = state.peek().hoverKey;
+                    if (sourceKey === '')
+                        return;
+                    // Keep the editor's SELECTION exactly where it was — a reorder must
+                    // never move the caret.
+                    event.preventDefault();
+                    // …but `preventDefault` on mousedown also cancels the default FOCUS
+                    // action, and the sub-threshold path below deliberately falls through
+                    // to the keyboard protocol. Without an explicit focus the grip was
+                    // never `document.activeElement`, so `onKeyDown` (bound to the grip)
+                    // never saw the arrow keys — they went to the contenteditable and
+                    // moved the caret instead of the block, while `aria-pressed="true"`
+                    // and the grabbed highlight claimed otherwise. `:focus-visible` never
+                    // applied and `onBlur`/`releaseGrab` could never fire, so the user was
+                    // stuck in a visible mode with no working keys.
+                    if (event.currentTarget instanceof HTMLElement)
+                        event.currentTarget.focus();
+                    const session = sessions.get(live);
+                    const startX = event.clientX;
+                    const startY = event.clientY;
+                    let dragging = false;
+                    let target = null;
+                    const onMove = (ev) => {
+                        if (!dragging) {
+                            if (Math.abs(ev.clientX - startX) + Math.abs(ev.clientY - startY) < DRAG_THRESHOLD)
+                                return;
+                            dragging = true;
+                            if (session)
+                                session.dragging = true;
+                            send({ type: 'dragStart' });
+                        }
+                        const blocks = readBlockRects(live);
+                        target = findDropTarget(blocks, ev.clientY, sourceKey);
+                        const rect = target ? indicatorRect(blocks, target) : null;
+                        if (rect)
+                            send({ type: 'dragOver', ...rect });
+                        else
+                            send({ type: 'dragOverNone' });
+                    };
+                    const finish = () => {
+                        document.removeEventListener('mousemove', onMove);
+                        document.removeEventListener('mouseup', onUp);
+                        abort = null;
+                        if (session)
+                            session.dragging = false;
+                    };
+                    const onUp = () => {
+                        finish();
+                        if (!dragging) {
+                            // Below the threshold this was a click, not a drag: open the block
+                            // actions menu anchored at the grip. (Mouse users still get free
+                            // reordering from the drag itself, or Move up/down in the menu;
+                            // keyboard-grab is Mod+Shift+D.)
+                            const s = state.peek();
+                            send({ type: 'openMenu', key: sourceKey, x: s.handleX, y: s.handleY });
+                            return;
+                        }
+                        if (target) {
+                            send({ type: 'drop', sourceKey, targetKey: target.key, place: target.place });
+                        }
+                        else {
+                            send({ type: 'dragEnd' });
+                        }
+                    };
+                    abort = () => {
+                        finish();
+                        send({ type: 'dragEnd' });
+                    };
+                    document.addEventListener('mousemove', onMove);
+                    document.addEventListener('mouseup', onUp);
+                };
+                const onKeyDown = (event) => {
+                    switch (event.key) {
+                        case 'Enter':
+                        case ' ': {
+                            // Handled here rather than via `click` so Space cannot ALSO fire the
+                            // button's synthetic click and act twice. While grabbed, Enter/Space
+                            // DROPS the block; otherwise it opens the actions menu at the grip.
+                            event.preventDefault();
+                            const s = state.peek();
+                            if (s.grabbedKey !== '')
+                                send({ type: 'toggleGrab' });
+                            else
+                                send({ type: 'openMenu', key: s.hoverKey, x: s.handleX, y: s.handleY });
+                            return;
+                        }
+                        case 'ArrowUp':
+                            event.preventDefault();
+                            send({ type: 'moveGrabbed', direction: -1 });
+                            return;
+                        case 'ArrowDown':
+                            event.preventDefault();
+                            send({ type: 'moveGrabbed', direction: 1 });
+                            return;
+                        case 'Escape':
+                            event.preventDefault();
+                            send({ type: 'releaseGrab' });
+                            return;
+                    }
+                };
+                const grabbed = state.map((s) => s.grabbedKey !== '');
+                /** Convert the menu's target block by reusing a merged command item: put a
+                 * selection at the block, then run the item (which converts the selection).
+                 * A no-op `send` — these items never talk back to the host here. */
+                const runTurnInto = (item) => {
+                    const live = editor();
+                    if (!live)
+                        return;
+                    const key = state.peek().menuKey;
+                    if (key === '')
+                        return;
+                    live.update(() => {
+                        $selectBlockStart(key);
+                    });
+                    item.run(live, { send: () => { } });
+                    send({ type: 'closeMenu' });
+                };
+                const menuButton = (label, onClick) => button({
+                    type: 'button',
+                    role: 'menuitem',
+                    'data-scope': 'md-block-drag',
+                    'data-part': 'menu-item',
+                    tabindex: '-1',
+                    // `mousedown` preventDefault keeps focus/selection stable; the action
+                    // runs on click.
+                    onMouseDown: (e) => e.preventDefault(),
+                    onClick,
+                }, [text(label)]);
+                /** Roving focus + dismissal for the menu. Native click/Enter activates a
+                 * focused item; here we add ↑/↓ traversal and Escape-to-close. */
+                const onMenuKeyDown = (event) => {
+                    const menu = event.currentTarget;
+                    if (!(menu instanceof HTMLElement))
+                        return;
+                    if (event.key === 'Escape') {
+                        event.preventDefault();
+                        send({ type: 'closeMenu' });
+                        return;
+                    }
+                    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp')
+                        return;
+                    event.preventDefault();
+                    const items = [...menu.querySelectorAll('[data-part="menu-item"]')];
+                    if (items.length === 0)
+                        return;
+                    const active = menu.ownerDocument.activeElement;
+                    const current = items.findIndex((el) => el === active);
+                    const delta = event.key === 'ArrowDown' ? 1 : -1;
+                    const nextIndex = (current + delta + items.length) % items.length;
+                    items[nextIndex]?.focus();
+                };
+                return [
+                    // The live region and the instructions are rendered UNCONDITIONALLY.
+                    // A live region injected at announcement time is frequently missed by
+                    // screen readers, and `aria-describedby` must resolve even before the
+                    // grip exists. `sr-only` is inlined rather than left to the stylesheet
+                    // because a missing rule here would leak debug text into the page.
+                    div({
+                        'data-scope': 'md-block-drag',
+                        'data-part': 'a11y',
+                        style: 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0',
+                    }, [
+                        div({ 'data-scope': 'md-block-drag', 'data-part': 'help', id: helpId }, [
+                            text('Press Enter or Space to grab this block, then the up and down arrow keys to move it. Press Enter to drop, or Escape to cancel.'),
+                        ]),
+                        div({
+                            'data-scope': 'md-block-drag',
+                            'data-part': 'announcer',
+                            role: 'status',
+                            'aria-live': 'polite',
+                            'aria-atomic': 'true',
+                        }, [
+                            text(state.map((s) => 
+                            // The zero-width space alternates with the nonce, so a
+                            // repeated boundary bump ('Already at the first
+                            // position.') is a NEW string and gets spoken again. It
+                            // renders as nothing and is not selectable text.
+                            s.announce === '' ? '' : s.announce + (s.announceNonce % 2 ? '\u200B' : ''))),
+                        ]),
+                    ]),
+                    ...overlayRoot({
+                        open: state.at('handleVisible'),
+                        x: state.at('handleX'),
+                        y: state.at('handleY'),
+                        zIndex: BLOCK_DRAG_Z.handle,
+                        attrs: { 'data-scope': 'md-block-drag', 'data-part': 'handle' },
+                        children: () => [
+                            button({
+                                type: 'button',
+                                'data-scope': 'md-block-drag',
+                                'data-part': 'grip',
+                                id: gripId,
+                                'aria-label': 'Reorder block',
+                                'aria-roledescription': 'draggable block handle',
+                                'aria-describedby': helpId,
+                                'aria-pressed': grabbed.map((g) => (g ? 'true' : 'false')),
+                                'data-grabbed': grabbed.map((g) => (g ? '' : undefined)),
+                                title: 'Drag to reorder — or press Enter and use the arrow keys',
+                                onMouseDown: beginDrag,
+                                onKeyDown,
+                                // Losing focus abandons a keyboard grab rather than leaving an
+                                // invisible mode armed on an element the user can no longer see.
+                                onBlur: () => send({ type: 'releaseGrab' }),
+                            }, [
+                                text('⠿'),
+                                // Take focus ONLY when the keyboard revealed us. `overlayRoot`
+                                // rebuilds this subtree each time it opens, so this runs once
+                                // per reveal. Focusing on a mouse hover would yank the caret
+                                // out of the contenteditable on every pointer move.
+                                onMount((root) => {
+                                    if (!state.peek().keyboardReveal)
+                                        return;
+                                    // Looked up by id on the OWNER DOCUMENT, not under `root`:
+                                    // `onMount` hands back the component's root element, while
+                                    // `overlayRoot` portals the grip to a body-level sibling, so
+                                    // the grip is never a descendant of `root`. The id is derived
+                                    // from this plugin instance's `uid`, which keeps it correct
+                                    // when several editors are mounted at once.
+                                    const grip = root.ownerDocument.getElementById(gripId);
+                                    grip?.focus();
+                                }),
+                            ]),
+                        ],
+                    }),
+                    ...overlayRoot({
+                        open: state.at('menuOpen'),
+                        x: state.at('menuX'),
+                        y: state.at('menuY'),
+                        zIndex: BLOCK_DRAG_Z.menu,
+                        attrs: { 'data-scope': 'md-block-drag', 'data-part': 'menu-root' },
+                        children: () => [
+                            div({
+                                'data-scope': 'md-block-drag',
+                                'data-part': 'menu',
+                                id: menuId,
+                                role: 'menu',
+                                'aria-label': 'Block actions',
+                                onKeyDown: onMenuKeyDown,
+                            }, [
+                                ...(turnIntoItems.length > 0
+                                    ? [
+                                        div({ 'data-scope': 'md-block-drag', 'data-part': 'menu-label' }, [
+                                            text('Turn into'),
+                                        ]),
+                                        ...turnIntoItems.map((item) => menuButton(item.label, () => runTurnInto(item))),
+                                        div({ 'data-scope': 'md-block-drag', 'data-part': 'menu-sep' }, []),
+                                    ]
+                                    : []),
+                                menuButton('Duplicate', () => send({ type: 'duplicate', key: state.peek().menuKey })),
+                                menuButton('Move up', () => send({ type: 'shiftBlock', key: state.peek().menuKey, direction: -1 })),
+                                menuButton('Move down', () => send({ type: 'shiftBlock', key: state.peek().menuKey, direction: 1 })),
+                                menuButton('Delete', () => send({ type: 'deleteBlock', key: state.peek().menuKey })),
+                                // Focus the first item on open, and close on an outside pointer.
+                                // The mousedown listener is armed on the NEXT tick so it never
+                                // catches the very click that opened the menu.
+                                onMount((root) => {
+                                    const menu = root.ownerDocument.getElementById(menuId);
+                                    menu?.querySelector('[data-part="menu-item"]')?.focus();
+                                    const onDocDown = (e) => {
+                                        if (menu && e.target instanceof Node && menu.contains(e.target))
+                                            return;
+                                        send({ type: 'closeMenu' });
+                                    };
+                                    const armed = setTimeout(() => document.addEventListener('mousedown', onDocDown), 0);
+                                    return () => {
+                                        clearTimeout(armed);
+                                        document.removeEventListener('mousedown', onDocDown);
+                                    };
+                                }),
+                            ]),
+                        ],
+                    }),
+                    ...overlayRoot({
+                        open: state.at('indicatorVisible'),
+                        x: state.at('indicatorX'),
+                        y: state.at('indicatorY'),
+                        zIndex: BLOCK_DRAG_Z.indicator,
+                        attrs: { 'data-scope': 'md-block-drag', 'data-part': 'indicator-root' },
+                        children: () => [
+                            div({
+                                'data-scope': 'md-block-drag',
+                                'data-part': 'indicator',
+                                'aria-hidden': 'true',
+                                // Only the WIDTH is inline (it is measured, hence dynamic); the
+                                // line's appearance belongs to `styles/block-drag.css`.
+                                style: state.at('indicatorWidth').map((w) => `width:${w}px`),
+                            }),
+                        ],
+                    }),
+                    // Abandon any in-flight pointer session if the editor unmounts mid-drag,
+                    // so the document listeners never outlive the component. `onMount`'s
+                    // returned cleanup is the sanctioned teardown hook; the Mountable MUST
+                    // be placed in the view array or it registers nothing.
+                    onMount(() => () => abort?.()),
+                ];
+            },
+        }),
+    };
+}
+//# sourceMappingURL=block-drag.js.map