@domternal/extension-block-controls 0.10.0

package/dist/index.d.cts

@@ -0,0 +1,488 @@
+import { Extension, FloatingMenuOptions, Editor, FloatingMenuItemsOverride, FloatingMenuItem } from '@domternal/core';
+export { CreateFloatingMenuPluginOptions, FloatingMenuKeymap, FloatingMenuOptions, createFloatingMenuPlugin, floatingMenuPluginKey } from '@domternal/core';
+import { PluginKey, Plugin } from '@domternal/pm/state';
+import { Node, ResolvedPos, Attrs } from '@domternal/pm/model';
+import { EditorView } from '@domternal/pm/view';
+
+/**
+ * FloatingMenu extension: registers the floating-menu plugin under the shared
+ * `floatingMenuPluginKey`. The plugin machinery (visibility, positioning,
+ * dismiss, keyboard entry) lives in `@domternal/core` so framework wrappers
+ * can build their menus without depending on this package; everything is
+ * re-exported here for backward compatibility.
+ */
+
+declare const FloatingMenu: Extension<FloatingMenuOptions, unknown>;
+
+/**
+ * Gutter-bias resolution for nested drag-target selection.
+ *
+ * When the cursor sits near a configured edge of a candidate's rect, that
+ * candidate counts as "in the gutter" and its rank is reduced proportionally to
+ * its depth, so shallower ancestors win against deeper descendants in the gutter
+ * zone. "Deepest-match" mode skips this bias and returns the innermost allowed
+ * block under the cursor.
+ */
+/** Cardinal edge of a candidate's bounding rect. */
+type GutterEdge = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Named presets for the bias config:
+ *  - `'left'`  → ['left', 'top']  (left gutter, default)
+ *  - `'right'` → ['right', 'top'] (right gutter, RTL-friendly)
+ *  - `'both'`  → ['left', 'right', 'top']
+ *  - `'none'`  → no gutter bias (deepest match wins)
+ */
+type GutterBiasPreset = 'left' | 'right' | 'both' | 'none';
+interface GutterBiasConfig {
+    /** Edges that constitute the "gutter" zone. */
+    edges: GutterEdge[];
+    /** Pixel distance from the edge at which the bias activates. */
+    threshold: number;
+    /** Bias factor applied per depth level when in the gutter. */
+    strength: number;
+}
+
+/**
+ * Predicate-based block matching for nested drag-target resolution. A matcher
+ * answers "is this candidate eligible to become the drag target?" with an
+ * allow/reject verdict; the resolver filters before ranking. The contract is
+ * binary (eligible or not), with rank decided separately by depth + optional
+ * gutter bias.
+ */
+
+/** Eligibility verdict returned by a matcher's `test()`. */
+type MatchVerdict = 'allow' | 'reject';
+/**
+ * Information passed to a matcher: the node, its position metadata, parent
+ * context, and the live editor view (for DOM lookups).
+ */
+interface BlockCandidate {
+    /** The PM node being considered as a drag target. */
+    block: Node;
+    /** Document position immediately before `block`. */
+    documentPos: number;
+    /** Depth in the PM tree; 0 is the doc root and is never a candidate. */
+    treeDepth: number;
+    /** Parent node, or `null` when there is no parent. */
+    container: Node | null;
+    /** Index of `block` inside `container.content`. */
+    positionInContainer: number;
+    /** Convenience: `positionInContainer === 0`. */
+    isFirstChild: boolean;
+    /** Convenience: `positionInContainer === container.childCount - 1`. */
+    isLastChild: boolean;
+    /** The ProseMirror resolved position the resolver started from. */
+    resolvedPos: ResolvedPos;
+    /** Live editor view; matchers may call `editorView.nodeDOM(pos)`. */
+    editorView: EditorView;
+}
+/** A matcher: a stable name (for debugging / opt-out) and a pure predicate. */
+interface BlockMatcher {
+    name: string;
+    test(candidate: BlockCandidate): MatchVerdict;
+}
+
+/**
+ * BlockHandle Extension
+ *
+ * Notion-style gutter handle on the left of each top-level block, shown on
+ * hover. Two buttons:
+ *
+ * 1. `⋮⋮` drag handle (click → opens BlockContextMenu, drag → reorder)
+ * 2. `+` insert button (inserts an empty paragraph below; FloatingMenu
+ *    picks up the empty-line state and auto-shows its insert menu)
+ *
+ * This plugin owns visibility + drag + context-menu trigger; the menu UI
+ * lives in `BlockContextMenu.ts`, which listens for the
+ * `dm:block-context-menu-open` event dispatched here.
+ *
+ * Styles ship via `@domternal/theme` (`_block-handle.scss`). The plugin adds
+ * a `dm-editor--has-block-handle` class so the theme can widen `.ProseMirror`
+ * padding-left for gutter space inside the `overflow:hidden` wrapper.
+ */
+
+/** Default list of nodes treated as drag-targetable when `nested: true`. */
+declare const DEFAULT_NESTED_NODES: string[];
+declare const blockHandlePluginKey: PluginKey<BlockHandlePluginState>;
+interface BlockHandleOptions {
+    /**
+     * Ms to wait before hiding the handle after the mouse leaves the editor, so
+     * users can move onto the handle without it vanishing.
+     * @default 200
+     */
+    hideDelay?: number;
+    /**
+     * Disable drag-to-reorder while still showing the plus/drag buttons
+     * (drag becomes a no-op, click opens context menu only).
+     * @default false
+     */
+    disableDrag?: boolean;
+    /**
+     * Auto-scroll the nearest scrollable ancestor when dragging near the
+     * top/bottom edge. Disable if the host app manages its own drag scroll.
+     * @default true
+     */
+    autoScroll?: boolean;
+    /**
+     * Distance in CSS px from the top/bottom edge that triggers auto-scroll.
+     * @default 48
+     */
+    autoScrollThreshold?: number;
+    /**
+     * Peak scroll speed in CSS px per frame. Ramps linearly from 0 at the
+     * threshold to this value at the edge.
+     * @default 18
+     */
+    autoScrollMaxSpeed?: number;
+    /**
+     * Whether the handle should resolve to nested block containers (list
+     * items, task items, and optionally others) instead of always the
+     * top-level block.
+     *
+     * - `false` - only top-level blocks are hoverable / draggable (default).
+     * - `true` - list items and task items resolve individually (Notion behaviour).
+     * - object - fine-grained config; see `NestedConfig`.
+     *
+     * @default false
+     */
+    nested?: boolean | NestedConfig;
+    /**
+     * Px threshold from a list item's LEFT edge past which a drop becomes
+     * nested-child (dragged block becomes a child of that item) instead of
+     * sibling. Mirrors Notion's "drop indented = nested, drop on the marker =
+     * sibling" UX. Set to `0` to disable nested-drop (every drop is sibling).
+     *
+     * X-detection only fires when nested mode is on AND the target is a
+     * `listItem`/`taskItem`; other containers stay sibling-only.
+     *
+     * @default 28
+     */
+    nestThreshold?: number;
+    /**
+     * Custom drop indicator that mirrors exactly where a handle-drag lands.
+     * Replaces `prosemirror-dropcursor` for handle drags (PM's `posAtCoords` can
+     * disagree with our resolver in the gutter / inter-block gap). During a drag
+     * the editor gets a `dm-block-handle-dragging` class so the theme can hide
+     * the native dropcursor for this drag only; non-handle drags (text selection,
+     * file drops) keep it. Set `false` to use the native dropcursor.
+     * @default true
+     */
+    dropIndicator?: boolean;
+}
+/**
+ * Configuration for nested resolution. Backwards-compatible with the
+ * earlier `{ allowedNodes }` literal - every field is optional.
+ */
+interface NestedConfig {
+    /**
+     * Node type names treated as drag targets when nested mode is on.
+     * @default ['listItem', 'taskItem']
+     */
+    allowedNodes?: string[];
+    /**
+     * Restrict resolution to nodes that have at least one ancestor of one
+     * of these type names. Use to scope nested mode to specific structures
+     * (e.g. only inside `table`). Empty / omitted → no restriction.
+     */
+    allowedContainers?: string[];
+    /**
+     * "Promote to parent at the gutter": within `threshold` px of a configured
+     * edge, a candidate's score drops by `strength * depth`, so a shallower
+     * ancestor (e.g. the wrapping list) wins near the boundary.
+     *
+     * - `false` / `undefined` / `'none'` → deepest match wins.
+     * - `true` / `'left'` → defaults: edges `['left','top']`, threshold 12, strength 500.
+     * - `'right'` / `'both'` → preset variants.
+     * - object → custom config (any field optional, merged over defaults).
+     *
+     * @default false
+     */
+    promoteOnEdge?: boolean | GutterBiasPreset | Partial<GutterBiasConfig>;
+    /**
+     * Append custom block matchers. Default matchers still apply unless
+     * `defaultMatchers: false` is also set.
+     */
+    matchers?: BlockMatcher[];
+    /**
+     * Set `false` to disable the built-in matchers (firstChildOfListItem,
+     * listContainerSkip, tableInternals, inlineNodes). Almost always wanted;
+     * opt out only for testing or specialised host editors.
+     * @default true
+     */
+    defaultMatchers?: boolean;
+}
+interface BlockHandlePluginState {
+    /** Absolute position of the top-level block currently under the cursor, or null. */
+    hoveredPos: number | null;
+    /**
+     * Source position of the block being dragged (set on dragstart, cleared on
+     * dragend). `handleDrop` uses it to tell whether the drop came from our handle.
+     */
+    draggedFrom: number | null;
+}
+/**
+ * Internal, fully-resolved view of `NestedConfig`: plain arrays + optional edge
+ * config so the resolver doesn't interpret presets at hover time.
+ */
+interface NestedResolution {
+    /** Allowed drag targets. Empty array → top-level-only mode. */
+    allowedNodes: string[];
+    /** Optional ancestor whitelist; empty array → no restriction. */
+    allowedContainers: string[];
+    /** Gutter bias config; `null` → deepest match wins. */
+    gutterBias: GutterBiasConfig | null;
+    /** Effective matcher list (defaults + user, or just user when defaults off). */
+    matchers: BlockMatcher[];
+}
+interface CreateBlockHandlePluginOptions {
+    pluginKey: PluginKey<BlockHandlePluginState>;
+    editor: Editor;
+    hideDelay: number;
+    disableDrag: boolean;
+    autoScroll: boolean;
+    autoScrollThreshold: number;
+    autoScrollMaxSpeed: number;
+    nested: NestedResolution;
+    dropIndicator: boolean;
+    /**
+     * Pixel threshold for nested-drop X-detection (see `BlockHandleOptions.nestThreshold`).
+     * `0` disables nested-drop.
+     */
+    nestThreshold: number;
+}
+/**
+ * Creates a standalone BlockHandle PM plugin. Exported so framework wrappers can
+ * build on it without the Extension factory.
+ */
+declare function createBlockHandlePlugin(options: CreateBlockHandlePluginOptions): Plugin<BlockHandlePluginState>;
+declare const BlockHandle: Extension<BlockHandleOptions, unknown>;
+
+/**
+ * Built-in eligibility matchers. They constrain the drag resolver to
+ * user-visible block units (paragraphs, headings, list/task items, images) and
+ * exclude structural plumbing (table cells, inline text, list containers whose
+ * items are draggable individually). Hosts can disable them with
+ * `defaultMatchers: false` and supply their own via `matchers`.
+ */
+
+declare const DEFAULT_BLOCK_MATCHERS: readonly BlockMatcher[];
+
+/**
+ * `Mod-Shift-ArrowUp` / `Mod-Shift-ArrowDown` move the top-level block
+ * containing the selection. Accessibility companion to BlockHandle drag.
+ * Shares `moveBlock` so position math and self-move rejection match.
+ */
+
+declare const KeyboardReorder: Extension<unknown, unknown>;
+
+/** Wrapper-style "Turn into" commands, each from the matching node extension.
+ *  Lists use the per-item `turnInto*` commands (Notion turn-into: convert only
+ *  the targeted block and split the run); the whole-list `toggle*List` commands
+ *  stay reserved for the toolbar button and Mod-Shift shortcut. */
+type WrapperCommand = 'turnIntoBulletList' | 'turnIntoOrderedList' | 'turnIntoTaskList' | 'toggleBlockquote';
+
+/**
+ * Popup menu opened by clicking the BlockHandle drag handle without dragging.
+ * Offers Delete, Duplicate, and Turn into (change block type) for the target.
+ *
+ * Triggered by the `dm:block-context-menu-open` event from BlockHandle, with
+ * payload `{ blockPos, anchorElement }`. Mirrors FloatingMenu / SlashCommand
+ * styling: `role="menu"`, `role="menuitem"`, `data-show`, positionFloatingOnce.
+ */
+
+/**
+ * `props.decorations` applies the `dm-block-context-active` class via a PM
+ * Decoration (not inline classList) so the highlight survives view rerenders
+ * from other transactions, e.g. UniqueID stamping `id` via setNodeMarkup.
+ */
+interface BlockContextMenuPluginState {
+    activeBlockPos: number | null;
+}
+declare const blockContextMenuPluginKey: PluginKey<BlockContextMenuPluginState>;
+/** A block type offered by the "Turn into" submenu. */
+interface TurnIntoTarget {
+    /** Display label, e.g. "Heading 1". */
+    label: string;
+    /** Icon key resolved against `defaultIcons`. */
+    icon: string;
+    /** Schema node name, e.g. "heading", "paragraph", "blockquote". */
+    nodeType: string;
+    /** Optional node attributes (e.g. `{ level: 1 }` for Heading 1). */
+    attrs?: Attrs;
+    /**
+     * Command for wrapper (non-textblock) targets like lists and blockquote.
+     * When set, runTurnInto routes through `turnIntoWrapper` instead of
+     * `setBlockType`. Leave undefined for textblock targets (paragraph,
+     * heading, codeBlock).
+     */
+    command?: WrapperCommand;
+}
+interface BlockContextMenuOptions {
+    /**
+     * Show the "Turn into" section of the menu. Disable to limit operations
+     * to Delete + Duplicate.
+     * @default true
+     */
+    turnIntoEnabled?: boolean;
+    /**
+     * Block types offered by "Turn into". Override to curate the list or
+     * add project-specific block types.
+     * @default DEFAULT_TURN_INTO
+     */
+    turnIntoTargets?: TurnIntoTarget[];
+    /**
+     * Show "Copy link" when the target block has an id attribute AND the
+     * `UniqueID` extension is loaded. No effect without UniqueID.
+     * @default true
+     */
+    copyLinkEnabled?: boolean;
+    /**
+     * Builds the URL written to the clipboard on "Copy link". Default appends
+     * `#<id>` to the current pathname+search (works for static pages); apps
+     * with client-side routing should provide a callback matching their scheme.
+     */
+    onCopyLink?: (blockId: string, editor: Editor) => string;
+    /**
+     * Show the Colors section (text + background) when the `BlockColor`
+     * extension is loaded and the target block is in its `types` list.
+     * @default true
+     */
+    blockColorEnabled?: boolean;
+}
+interface CreateBlockContextMenuPluginOptions {
+    pluginKey: PluginKey<BlockContextMenuPluginState>;
+    editor: Editor;
+    turnIntoEnabled: boolean;
+    turnIntoTargets: TurnIntoTarget[];
+    copyLinkEnabled: boolean;
+    onCopyLink: (blockId: string, editor: Editor) => string;
+    blockColorEnabled: boolean;
+}
+/**
+ * Builds the popup DOM, listens for `dm:block-context-menu-open` on
+ * `.dm-editor`, and runs block operations via `helpers/blockOperations.ts`.
+ */
+declare function createBlockContextMenuPlugin(options: CreateBlockContextMenuPluginOptions): Plugin;
+declare const BlockContextMenu: Extension<BlockContextMenuOptions, unknown>;
+
+/**
+ * `/` trigger that opens a filtered popup of insertable blocks. Items are
+ * shared with FloatingMenu and BlockHandle via `addFloatingMenuItems()`.
+ * On select, the `/query` range is deleted and the item's command runs at
+ * the now-empty cursor (so "Heading 1" transforms the block, "Image" opens
+ * its popover, etc.).
+ */
+
+declare const slashCommandPluginKey: PluginKey<SlashCommandPluginState>;
+interface SlashCommandProps {
+    /** The editor instance (passed so custom renderers can read state). */
+    editor: Editor;
+    /** Current query string (text after the `/`). */
+    query: string;
+    /** Document range of the `/` + query (for replacement). */
+    range: {
+        from: number;
+        to: number;
+    };
+    /** Filtered and ranked items matching the query. */
+    items: FloatingMenuItem[];
+    /** Execute the selected item and close the popup. */
+    command: (item: FloatingMenuItem) => void;
+    /** Returns the client rect of the cursor for positioning the popup. */
+    clientRect: () => DOMRect | null;
+    /** The editor's ProseMirror DOM node (for portal parents etc.). */
+    element: HTMLElement;
+}
+interface SlashCommandRenderer {
+    onStart: (props: SlashCommandProps) => void;
+    onUpdate: (props: SlashCommandProps) => void;
+    onExit: () => void;
+    /** Return `true` to consume the key event and prevent default handling. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+interface SlashCommandOptions {
+    /**
+     * The trigger character. @default '/'
+     */
+    char?: string;
+    /**
+     * Items override. When omitted, items from `editor.floatingMenuItems`
+     * (collected via `addFloatingMenuItems()`) are used. An array replaces
+     * defaults; a function transforms them.
+     */
+    items?: FloatingMenuItemsOverride;
+    /**
+     * Factory returning render callbacks for the popup. Default uses
+     * `createSlashSuggestionRenderer()`.
+     */
+    render?: () => SlashCommandRenderer;
+    /**
+     * Node types where slash should NOT activate (e.g. `codeBlock`).
+     * @default ['codeBlock']
+     */
+    invalidNodes?: string[];
+}
+interface CreateSlashCommandPluginOptions {
+    pluginKey: PluginKey<SlashCommandPluginState>;
+    editor: Editor;
+    char: string;
+    items?: FloatingMenuItemsOverride;
+    render: () => SlashCommandRenderer;
+    invalidNodes: string[];
+}
+interface SlashCommandPluginState {
+    active: boolean;
+    query: string;
+    range: {
+        from: number;
+        to: number;
+    } | null;
+}
+/**
+ * Filters and ranks FloatingMenuItems against a query. Priority:
+ *   1. Exact label prefix (case-insensitive)
+ *   2. Label substring match
+ *   3. Keyword match (preserving original keyword index for stable ranking)
+ * Returns items in rank order, stable within the same rank.
+ */
+declare function filterSlashItems(items: FloatingMenuItem[], query: string): FloatingMenuItem[];
+declare function createSlashCommandPlugin(options: CreateSlashCommandPluginOptions): Plugin<SlashCommandPluginState>;
+declare const SlashCommand: Extension<SlashCommandOptions, unknown>;
+/** Programmatically dismisses the slash suggestion. */
+declare function dismissSlashCommand(view: EditorView): void;
+
+declare function createSlashSuggestionRenderer(): SlashCommandRenderer;
+
+/**
+ * Pasting block-level content at an INLINE position normally goes through PM's
+ * content fitter, which strips the block wrapper and pastes only inline text.
+ * SmartPaste catches the relevant cases and routes each to the right strategy:
+ *
+ *  1. List slice into a list ancestor: same-kind items merge as siblings; a
+ *     different-kind list keeps its kind and splits the host list around it.
+ *  2. Trailing hardBreak (Shift+Enter): trim the hardBreak, insert as sibling.
+ *  3. Truly empty parent paragraph (`parentSize === 0`): replace the parent.
+ *  4-6. Caret at start / end / middle: insert as sibling or split-and-insert.
+ *  7. Range selection: delete first, then run through 2-6.
+ *
+ * Skipped (PM default applies) when: cursor isn't in a textblock; the slice's
+ * top-level blocks are ALL plain paragraphs; or the slice is a SINGLE top-level
+ * block of the SAME TYPE as the destination (heading-into-heading, etc.) where
+ * PM's inline merge is what the user wants.
+ *
+ * Do NOT bail on `openStart > 0`: PM's clipboard parser routinely sets
+ * `openStart=1` even for closed-looking input like `<h1>x</h1>`. Top-level
+ * children of the slice are what matter.
+ */
+
+interface SmartPasteOptions {
+    /**
+     * Disable the plugin without removing the extension (falls back to PM's
+     * default paste handling).
+     * @default true
+     */
+    enabled?: boolean;
+}
+declare const SmartPaste: Extension<SmartPasteOptions, unknown>;
+
+export { type BlockCandidate, BlockContextMenu, type BlockContextMenuOptions, BlockHandle, type BlockHandleOptions, type BlockHandlePluginState, type BlockMatcher, type CreateBlockContextMenuPluginOptions, type CreateBlockHandlePluginOptions, type CreateSlashCommandPluginOptions, DEFAULT_BLOCK_MATCHERS, DEFAULT_NESTED_NODES, FloatingMenu, KeyboardReorder, type MatchVerdict, type NestedConfig, SlashCommand, type SlashCommandOptions, type SlashCommandPluginState, type SlashCommandProps, type SlashCommandRenderer, SmartPaste, type SmartPasteOptions, type TurnIntoTarget, type WrapperCommand, blockContextMenuPluginKey, blockHandlePluginKey, createBlockContextMenuPlugin, createBlockHandlePlugin, createSlashCommandPlugin, createSlashSuggestionRenderer, dismissSlashCommand, filterSlashItems, slashCommandPluginKey };