@shelamkoff/rector 1.0.0

package/dist/core/UndoManager.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @typedef {{ time?: number, version: string, blocks: string[], blockId?: string, offset?: number }} Snapshot
+ */
+export class UndoManager {
+    /**
+     * @param {import('./types.js').IBlockReader} blocks
+     * @param {import('./types.js').IEventBus} events
+     * @param {() => import('./types.js').EditorDocument} captureFn
+     * @param {(data: import('./types.js').EditorDocument, caret?: { blockId: string, offset: number }) => void} renderFn
+     * @param {() => { blockId: string, offset: number } | null} getCaretFn
+     * @param {{ maxStack: number, debounceMs: number }} [tuning]
+     */
+    constructor(blocks: import("./types.js").IBlockReader, events: import("./types.js").IEventBus, captureFn: () => import("./types.js").EditorDocument, renderFn: (data: import("./types.js").EditorDocument, caret?: {
+        blockId: string;
+        offset: number;
+    }) => void, getCaretFn: () => {
+        blockId: string;
+        offset: number;
+    } | null, tuning?: {
+        maxStack: number;
+        debounceMs: number;
+    });
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Mask public command availability without pausing history recording.
+     * @param {boolean} enabled
+     * @param {{ notify?: boolean }} [options]
+     */
+    setCommandsEnabled(enabled: boolean, options?: {
+        notify?: boolean;
+    }): void;
+    /**
+     * Flush any pending debounce and commit the current document snapshot.
+     * Call BEFORE structural operations (insert, remove, move, convert)
+     * to ensure the pre-change state is in the undo stack.
+     */
+    commit(): void;
+    /**
+     * Restore the previous state.
+     */
+    undo(): boolean;
+    /**
+     * Restore the next state.
+     */
+    redo(): boolean;
+    /**
+     * Begin a batch — all changes until endBatch() are treated as one undo step.
+     * Captures the pre-change state when the outer batch begins.
+     */
+    beginBatch(): void;
+    /**
+     * End the batch and take a snapshot of the final state.
+     */
+    endBatch(): void;
+    /**
+     * Clear all history.
+     */
+    clear(): void;
+    /**
+     * Clean up.
+     */
+    destroy(): void;
+    #private;
+}
+export type Snapshot = {
+    time?: number;
+    version: string;
+    blocks: string[];
+    blockId?: string;
+    offset?: number;
+};

package/dist/core/UndoManager.js

@@ -0,0 +1,383 @@
+import { EditorEvent } from './editorEvents.js'
+
+/**
+ * @typedef {{ time?: number, version: string, blocks: string[], blockId?: string, offset?: number }} Snapshot
+ */
+
+export class UndoManager {
+  /** @type {number} */
+  #maxStack
+
+  /** @type {number} */
+  #debounceMs
+
+  /** @type {import('./types').IBlockReader} */
+  #blocks
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {() => import('./types').EditorDocument} */
+  #captureFn
+
+  /** @type {(data: import('./types').EditorDocument, caret?: { blockId: string, offset: number }) => void} */
+  #renderFn
+
+  /** @type {() => { blockId: string, offset: number } | null} */
+  #getCaretFn
+
+  /** @type {Snapshot[]} */
+  #undoStack = []
+
+  /** @type {Snapshot[]} */
+  #redoStack = []
+
+  /** @type {WeakMap<object, string>} */
+  #serializedBlocks = new WeakMap()
+
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  #debounceTimer = null
+
+  /** @type {boolean} */
+  #destroyed = false
+
+  /** Nesting depth for compound operations. Only the outer boundary commits. */
+  #batchDepth = 0
+
+  /** @type {boolean} */
+  #restoring = false
+
+  /** A live change exists but has not reached its coalesced snapshot yet. */
+  #pendingChange = false
+
+  /** @type {boolean | null} */
+  #lastCanUndo = null
+
+  /** @type {boolean | null} */
+  #lastCanRedo = null
+
+  /** History keeps recording, but commands are unavailable in read-only mode. */
+  #commandsEnabled = true
+
+  /** @type {() => void} */
+  #unsubscribe
+
+  /**
+   * @param {import('./types').IBlockReader} blocks
+   * @param {import('./types').IEventBus} events
+   * @param {() => import('./types').EditorDocument} captureFn
+   * @param {(data: import('./types').EditorDocument, caret?: { blockId: string, offset: number }) => void} renderFn
+   * @param {() => { blockId: string, offset: number } | null} getCaretFn
+   * @param {{ maxStack: number, debounceMs: number }} [tuning]
+   */
+  constructor(blocks, events, captureFn, renderFn, getCaretFn, tuning) {
+    this.#blocks = blocks
+    this.#events = events
+    this.#captureFn = captureFn
+    this.#renderFn = renderFn
+    this.#getCaretFn = getCaretFn
+    this.#maxStack = tuning?.maxStack ?? 100
+    this.#debounceMs = tuning?.debounceMs ?? 300
+
+    // Take initial snapshot synchronously
+    this.#takeSnapshot()
+
+    // Capture pre-change state before structural operations
+    const unsubWillChange = events.on(EditorEvent.WILL_CHANGE, () => {
+      if (this.#restoring) return
+      this.commit()
+    })
+
+    // Listen for changes
+    const unsubChanged = events.on(EditorEvent.CHANGED, () => {
+      if (this.#restoring) return
+      this.#pendingChange = true
+      this.#emitState()
+      this.#debouncedSnapshot()
+    })
+
+    // Batch events
+    const unsubBatchStart = events.on(EditorEvent.UNDO_BATCH_START, () => { if (!this.#restoring) this.beginBatch() })
+    const unsubBatchEnd = events.on(EditorEvent.UNDO_BATCH_END, () => { if (!this.#restoring) this.endBatch() })
+    const unsubCommit = events.on(EditorEvent.HISTORY_COMMIT, () => {
+      if (!this.#restoring) this.commit()
+    })
+
+    this.#unsubscribe = () => { unsubWillChange(); unsubChanged(); unsubBatchStart(); unsubBatchEnd(); unsubCommit() }
+  }
+
+  get canUndo() {
+    return this.#commandsEnabled && (this.#pendingChange || this.#undoStack.length > 1)
+  }
+
+  get canRedo() {
+    return this.#commandsEnabled && !this.#pendingChange && this.#redoStack.length > 0
+  }
+
+  /**
+   * Mask public command availability without pausing history recording.
+   * @param {boolean} enabled
+   * @param {{ notify?: boolean }} [options]
+   */
+  setCommandsEnabled(enabled, options = {}) {
+    if (this.#destroyed || enabled === this.#commandsEnabled) return
+    this.#commandsEnabled = enabled
+    if (options.notify === false) {
+      this.#lastCanUndo = this.canUndo
+      this.#lastCanRedo = this.canRedo
+      return
+    }
+    this.#emitState()
+  }
+
+  /**
+   * Flush any pending debounce and commit the current document snapshot.
+   * Call BEFORE structural operations (insert, remove, move, convert)
+   * to ensure the pre-change state is in the undo stack.
+   */
+  commit() {
+    if (this.#destroyed) return
+    if (this.#batchDepth > 0) return
+    if (this.#debounceTimer) {
+      clearTimeout(this.#debounceTimer)
+      this.#debounceTimer = null
+    }
+    this.#takeSnapshot()
+  }
+
+  /**
+   * Restore the previous state.
+   */
+  undo() {
+    if (this.#destroyed) return false
+    this.#reconcileCurrentState()
+
+    if (!this.canUndo) return false
+
+    const current = this.#undoStack.pop()
+    if (current) this.#redoStack.push(current)
+
+    const prev = this.#undoStack[this.#undoStack.length - 1]
+    if (prev) {
+      try {
+        this.#restore(prev)
+      } catch (error) {
+        if (current) {
+          this.#redoStack.pop()
+          this.#undoStack.push(current)
+        }
+        throw error
+      }
+      this.#emitState()
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Restore the next state.
+   */
+  redo() {
+    if (this.#destroyed) return false
+    this.#reconcileCurrentState()
+
+    if (!this.canRedo) return false
+
+    const next = this.#redoStack.pop()
+    if (next) {
+      this.#undoStack.push(next)
+      try {
+        this.#restore(next)
+      } catch (error) {
+        this.#undoStack.pop()
+        this.#redoStack.push(next)
+        throw error
+      }
+      this.#emitState()
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Begin a batch — all changes until endBatch() are treated as one undo step.
+   * Captures the pre-change state when the outer batch begins.
+   */
+  beginBatch() {
+    if (this.#batchDepth === 0) {
+      this.commit()
+    }
+    this.#batchDepth++
+  }
+
+  /**
+   * End the batch and take a snapshot of the final state.
+   */
+  endBatch() {
+    if (this.#batchDepth === 0) return
+    this.#batchDepth--
+    if (this.#batchDepth === 0) {
+      this.#takeSnapshot()
+    }
+  }
+
+  /**
+   * Clear all history.
+   */
+  clear() {
+    this.#undoStack = []
+    this.#redoStack = []
+    this.#serializedBlocks = new WeakMap()
+    this.#batchDepth = 0
+    this.#pendingChange = false
+    if (this.#debounceTimer) {
+      clearTimeout(this.#debounceTimer)
+      this.#debounceTimer = null
+    }
+    if (!this.#destroyed) this.#emitState()
+  }
+
+  /**
+   * Clean up.
+   */
+  destroy() {
+    this.#destroyed = true
+    this.clear()
+    this.#unsubscribe()
+  }
+
+  #debouncedSnapshot() {
+    if (this.#batchDepth > 0) return
+    if (this.#debounceTimer) clearTimeout(this.#debounceTimer)
+    this.#debounceTimer = setTimeout(() => {
+      this.#debounceTimer = null
+      try {
+        this.#takeSnapshot()
+      } catch (error) {
+        console.warn('[UndoManager] Failed to take debounced snapshot:', error)
+      }
+    }, this.#debounceMs)
+  }
+
+  /**
+   * Reconcile the live editor state at the history command boundary.
+   *
+   * History correctness must not depend on a debounce timer still being
+   * active. A synchronous/custom command may have changed the canonical
+   * document even when its final change notification was missed. Pushing is
+   * content-deduplicated, so the normal committed path remains a no-op here;
+   * an uncommitted current state becomes the newest entry and can be undone
+   * without accidentally reverting the preceding structural command.
+   */
+  #reconcileCurrentState() {
+    if (this.#debounceTimer) {
+      clearTimeout(this.#debounceTimer)
+      this.#debounceTimer = null
+    }
+    this.#takeSnapshot()
+  }
+
+  /**
+   * Deduplicate, serialize, and push a snapshot onto the undo stack.
+   * @param {import('./types').EditorDocument} data
+   * @returns {boolean} true if pushed, false if deduplicated
+   */
+  #pushSnapshot(data) {
+    const blocks = data.blocks.map(block => {
+      const cached = this.#serializedBlocks.get(block)
+      if (cached !== undefined) return cached
+
+      const serialized = JSON.stringify(block)
+      if (serialized === undefined) {
+        throw new TypeError('Editor block is not JSON serializable')
+      }
+      this.#serializedBlocks.set(block, serialized)
+      return serialized
+    })
+
+    // Arrays are new per entry, while strings for unchanged canonical
+    // blocks are shared between snapshots.
+    const lastSnapshot = this.#undoStack.length
+      ? this.#undoStack[this.#undoStack.length - 1]
+      : null
+    const unchanged = lastSnapshot?.blocks.length === blocks.length
+      && blocks.every((block, index) => block === lastSnapshot.blocks[index])
+
+    if (unchanged && lastSnapshot) {
+      const caret = this.#getCaretFn()
+      if (caret) {
+        lastSnapshot.blockId = caret.blockId
+        lastSnapshot.offset = caret.offset
+      }
+      return false
+    }
+
+    const caret = this.#getCaretFn()
+    /** @type {Snapshot} */
+    const snapshot = {
+      time: data.time,
+      version: data.version,
+      blocks,
+    }
+    if (caret) {
+      snapshot.blockId = caret.blockId
+      snapshot.offset = caret.offset
+    }
+
+    this.#undoStack.push(snapshot)
+    // Keep the current state plus the configured number of undoable states.
+    if (this.#undoStack.length > this.#maxStack + 1) {
+      this.#undoStack.shift()
+    }
+    this.#redoStack = []
+    return true
+  }
+
+  #emitState() {
+    const canUndo = this.canUndo
+    const canRedo = this.canRedo
+    if (canUndo === this.#lastCanUndo && canRedo === this.#lastCanRedo) return
+    this.#lastCanUndo = canUndo
+    this.#lastCanRedo = canRedo
+    this.#events.emit(EditorEvent.HISTORY_CHANGED, {
+      canUndo,
+      canRedo,
+    })
+  }
+
+  #takeSnapshot() {
+    if (this.#destroyed) return
+    // Capture and serialize first. A plugin save failure must not consume the
+    // pending change or publish history state that never committed.
+    const snapshot = this.#captureFn()
+    this.#pushSnapshot(snapshot)
+    this.#pendingChange = false
+    this.#emitState()
+  }
+
+  /**
+   * @param {Snapshot} snapshot
+   */
+  #restore(snapshot) {
+    let data
+    try {
+      data = {
+        time: snapshot.time,
+        version: snapshot.version,
+        blocks: snapshot.blocks.map(block => JSON.parse(block)),
+      }
+    } catch (err) {
+      throw new Error('[UndoManager] Failed to parse snapshot', { cause: err })
+    }
+    const caret = snapshot.blockId != null
+      ? { blockId: snapshot.blockId, offset: snapshot.offset ?? 0 }
+      : undefined
+    // Suppress event handlers during render so undo/redo does not create snapshots.
+    this.#restoring = true
+    try {
+      this.#renderFn(data, caret)
+    } finally {
+      this.#restoring = false
+    }
+  }
+}

package/dist/core/block-settings-menu/BlockActions.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @typedef {Object} BlockActionsDeps
+ * @property {import('../types.js').IBlockManager} blocks
+ * @property {import('../types.js').ISelectionManager} selection
+ * @property {import('../BlockOperations.js').BlockOperations} blockOps
+ * @property {Map<string, import('../types.js').BlockPlugin>} plugins
+ * @property {import('../types.js').ICrossBlockSelection} crossBlockSelection
+ * @property {import('../types.js').IEventBus} events
+ * @property {import('../CommandDispatcher.js').CommandDispatcher} commands
+ * @property {string} defaultBlockType
+ * @property {(current: import('../types.js').IBlock, index: number) => import('../types.js').IBlock | undefined} duplicateBlock
+ * @property {() => void} onClose       called after each terminal action
+ * @property {() => void} onAfterMove   called after move (rebuild + reposition)
+ * @property {() => Range | null} getSavedRange
+ *   Returns the range that was active when the menu opened — used by `convertTo`
+ *   to restore caret before slicing the block.
+ */
+/**
+ * The actual block-mutating operations exposed by the settings menu:
+ * move up/down, duplicate, delete, convert to type, plugin-specific
+ * settings actions (e.g. heading level change).
+ *
+ * Each method is "fire-and-forget" — it performs the mutation and (in
+ * most cases) closes the menu via `deps.onClose()`. Move operations
+ * keep the menu open via `deps.onAfterMove()`.
+ */
+export class BlockActions {
+    /** @param {BlockActionsDeps} deps */
+    constructor(deps: BlockActionsDeps);
+    moveUp(): void;
+    moveDown(): void;
+    duplicate(): void;
+    delete(): void;
+    /**
+     * Convert the current block (or the cross-block range) to a different type.
+     *
+     * Three branches:
+     *  1. Cross-block range → delegate to `convertCrossBlockRange`.
+     *  2. Single block, no selection or full-block selection → swap whole block.
+     *  3. Single block, partial selection → `splitAndConvert` (creates two blocks).
+     *
+     * @param {string} type
+     * @param {Record<string, unknown>} [data]
+     */
+    convertTo(type: string, data?: Record<string, unknown>): void;
+    /**
+     * Handle a plugin-specific settings item (e.g. "Heading 2" → changeLevel(2)).
+     * Falls back to `onSettingsAction` + `convert` for plugins without an
+     * in-place update path.
+     *
+     * @param {import('../types.js').IBlock} current
+     * @param {import('../types.js').BlockPlugin} plugin
+     * @param {HTMLElement} item
+     */
+    handleSettingsAction(current: import("../types.js").IBlock, plugin: import("../types.js").BlockPlugin, item: HTMLElement): void;
+    #private;
+}
+export type BlockActionsDeps = {
+    blocks: import("../types.js").IBlockManager;
+    selection: import("../types.js").ISelectionManager;
+    blockOps: import("../BlockOperations.js").BlockOperations;
+    plugins: Map<string, import("../types.js").BlockPlugin>;
+    crossBlockSelection: import("../types.js").ICrossBlockSelection;
+    events: import("../types.js").IEventBus;
+    commands: import("../CommandDispatcher.js").CommandDispatcher;
+    defaultBlockType: string;
+    duplicateBlock: (current: import("../types.js").IBlock, index: number) => import("../types.js").IBlock | undefined;
+    /**
+     * called after each terminal action
+     */
+    onClose: () => void;
+    /**
+     * called after move (rebuild + reposition)
+     */
+    onAfterMove: () => void;
+    /**
+     *   Returns the range that was active when the menu opened — used by `convertTo`
+     *   to restore caret before slicing the block.
+     */
+    getSavedRange: () => Range | null;
+};