@shelamkoff/rector 1.0.0

package/dist/core/BlockOperations.js

@@ -0,0 +1,238 @@
+import { EditorEvent } from './editorEvents.js'
+
+/** @typedef {import('./types').IBlockOperations} IBlockOperationsContract */
+/** @implements {IBlockOperationsContract} */
+export class BlockOperations {
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {import('./types').ISelectionManager} */
+  #selection
+
+  /** @type {string} */
+  #defaultBlockType
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /**
+   * @param {import('./types').IBlockManager} blocks
+   * @param {import('./types').ISelectionManager} selection
+   * @param {string} defaultBlockType
+   * @param {import('./types').IEventBus} events
+   */
+  constructor(blocks, selection, defaultBlockType, events) {
+    this.#blocks = blocks
+    this.#selection = selection
+    this.#defaultBlockType = defaultBlockType
+    this.#events = events
+  }
+
+  /**
+   * Insert a new block, set it as current, place the caret, and focus.
+   * @param {string} type
+   * @param {Record<string, unknown>} [data]
+   * @param {number} [index]
+   * @param {'start' | 'end'} [caretPosition='start']
+   * @returns {import('./types').IBlock}
+   */
+  insertAndFocus(type, data, index, caretPosition = 'start') {
+    const newBlock = this.#blocks.insert(type, data, index)
+    const newIndex = this.#blocks.getBlockIndex(newBlock.id)
+    this.#blocks.setCurrentIndex(newIndex)
+    this.#selection.setCaretToBlock(newBlock.id, caretPosition)
+    newBlock.focus()
+    return newBlock
+  }
+
+  /**
+   * If the current block is empty and of the default type, convert it in place.
+   * Otherwise, insert a new block after it. Focuses the result.
+   * @param {string} type
+   * @param {Record<string, unknown>} [data]
+   * @param {'start' | 'end'} [caretPosition='start']
+   * @returns {import('./types').IBlock}
+   */
+  replaceEmptyOrInsert(type, data, caretPosition = 'start') {
+    const currentIndex = this.#blocks.getCurrentIndex()
+    const currentBlock = this.#blocks.getBlockByIndex(currentIndex)
+
+    if (currentBlock?.isEmpty()
+        && currentBlock.type === this.#defaultBlockType
+        && currentBlock.type !== type) {
+      const converted = this.#blocks.convert(currentIndex, type, data)
+      if (converted) {
+        this.#blocks.setCurrentIndex(currentIndex)
+        this.#selection.setCaretToBlock(converted.id, caretPosition)
+        converted.focus()
+        return converted
+      }
+    }
+
+    return this.insertAndFocus(type, data, currentIndex + 1, caretPosition)
+  }
+
+  /**
+   * Split the current block at the caret position (Enter key).
+   * Extracts content after caret into a new block of the same type.
+   */
+  splitBlock() {
+    const blocks = this.#blocks
+    const current = blocks.getCurrentBlock()
+    if (!current) return
+
+    this.#events.emit(EditorEvent.UNDO_BATCH_START)
+    try {
+      const fragmentHtml = this.#selection.extractFragmentAfterCaret()
+      current.markDirty()
+      this.#events.emit(EditorEvent.BLOCK_CHANGED, { blockId: current.id })
+
+      const currentIndex = blocks.getCurrentIndex()
+      const data = fragmentHtml ? { text: fragmentHtml } : {}
+      this.insertAndFocus(this.#defaultBlockType, data, currentIndex + 1)
+    } finally {
+      this.#events.emit(EditorEvent.UNDO_BATCH_END)
+    }
+  }
+
+  /**
+   * Convert the current empty non-default block to the configured default
+   * block and preserve focus. This is the common "exit block" operation used
+   * by list-like plugins and by Backspace handling.
+   * @returns {boolean} Whether a block was converted.
+   */
+  exitEmptyBlock() {
+    const current = this.#blocks.getCurrentBlock()
+    if (!current || !current.isEmpty() || current.type === this.#defaultBlockType) return false
+
+    const index = this.#blocks.getCurrentIndex()
+    const converted = this.#blocks.convert(index, this.#defaultBlockType)
+    if (!converted) return false
+
+    this.#blocks.setCurrentIndex(index)
+    converted.focus()
+    this.#selection.setCaretToBlock(converted.id, 'start')
+    return true
+  }
+
+  /**
+   * Merge the current block with the previous one (Backspace at start).
+   * If current block is empty — removes it and focuses previous.
+   * If both are the same type and support merge — merges content.
+   * @returns {boolean} Whether the merge was handled
+   */
+  mergeWithPrevious() {
+    if (!this.#selection.isAtStart()) return false
+
+    const blocks = this.#blocks
+    const currentIndex = blocks.getCurrentIndex()
+    if (currentIndex <= 0) return false
+
+    const current = blocks.getCurrentBlock()
+    const prev = blocks.getBlockByIndex(currentIndex - 1)
+    if (!current || !prev) return false
+
+    if (current.isEmpty()) {
+      blocks.remove(currentIndex)
+      blocks.setCurrentIndex(currentIndex - 1)
+      this.#selection.setCaretToBlock(prev.id, 'end')
+      prev.focus()
+      return true
+    }
+
+    if (prev.type === current.type && prev.canMerge) {
+      this.#events.emit(EditorEvent.UNDO_BATCH_START)
+      try {
+        const currentData = current.save().data
+        const mergeOffset = prev.contentElement.textContent?.length ?? 0
+        prev.merge(currentData)
+        blocks.remove(currentIndex)
+        blocks.setCurrentIndex(currentIndex - 1)
+        prev.focus()
+        const actualLength = prev.contentElement.textContent?.length ?? 0
+        this.#selection.setCaretToOffset(prev.id, Math.min(mergeOffset, actualLength))
+      } finally {
+        this.#events.emit(EditorEvent.UNDO_BATCH_END)
+      }
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Merge the next block into the current one (Delete at end).
+   * If next block is empty - removes it.
+   * If both are the same type and support merge - merges content.
+   * @returns {boolean} Whether the merge was handled
+   */
+  mergeWithNext() {
+    if (!this.#selection.isAtEnd()) return false
+
+    const blocks = this.#blocks
+    const currentIndex = blocks.getCurrentIndex()
+    const current = blocks.getCurrentBlock()
+    const next = blocks.getBlockByIndex(currentIndex + 1)
+    if (!current || !next) return false
+
+    if (next.isEmpty()) {
+      blocks.remove(currentIndex + 1)
+      return true
+    }
+
+    if (current.type === next.type && current.canMerge) {
+      this.#events.emit(EditorEvent.UNDO_BATCH_START)
+      try {
+        const nextData = next.save().data
+        const mergeOffset = current.contentElement.textContent?.length ?? 0
+        current.merge(nextData)
+        blocks.remove(currentIndex + 1)
+        const actualLength = current.contentElement.textContent?.length ?? 0
+        this.#selection.setCaretToOffset(current.id, Math.min(mergeOffset, actualLength))
+      } finally {
+        this.#events.emit(EditorEvent.UNDO_BATCH_END)
+      }
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Move the caret to the end of the previous block (ArrowUp at start).
+   * @returns {boolean} Whether navigation happened
+   */
+  navigateToPrevious() {
+    if (!this.#selection.isAtStart()) return false
+
+    const blocks = this.#blocks
+    const currentIndex = blocks.getCurrentIndex()
+    if (currentIndex <= 0) return false
+
+    const prev = blocks.getBlockByIndex(currentIndex - 1)
+    if (!prev) return false
+
+    blocks.setCurrentIndex(currentIndex - 1)
+    this.#selection.setCaretToBlock(prev.id, 'end')
+    prev.focus()
+    return true
+  }
+
+  /**
+   * Move the caret to the start of the next block (ArrowDown at end).
+   * @returns {boolean} Whether navigation happened
+   */
+  navigateToNext() {
+    if (!this.#selection.isAtEnd()) return false
+
+    const blocks = this.#blocks
+    const currentIndex = blocks.getCurrentIndex()
+    const next = blocks.getBlockByIndex(currentIndex + 1)
+    if (!next) return false
+
+    blocks.setCurrentIndex(currentIndex + 1)
+    this.#selection.setCaretToBlock(next.id, 'start')
+    next.focus()
+    return true
+  }
+}

package/dist/core/ChangeNotifier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Debounced change notification.
+ * Calls the onChange callback after a quiet period following editor changes.
+ */
+export class ChangeNotifier {
+    /**
+     * @param {() => import('./types.js').EditorDocument | Promise<import('./types.js').EditorDocument>} saveFn
+     * @param {((data: import('./types.js').EditorDocument) => void)} [onChange]
+     * @param {number} [delay]
+     */
+    constructor(saveFn: () => import("./types.js").EditorDocument | Promise<import("./types.js").EditorDocument>, onChange?: ((data: import("./types.js").EditorDocument) => void), delay?: number);
+    schedule(): void;
+    destroy(): void;
+    #private;
+}

package/dist/core/ChangeNotifier.js

@@ -0,0 +1,55 @@
+/**
+ * Debounced change notification.
+ * Calls the onChange callback after a quiet period following editor changes.
+ */
+export class ChangeNotifier {
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  #timer = null
+
+  /** @type {() => import('./types').EditorDocument | Promise<import('./types').EditorDocument>} */
+  #saveFn
+
+  /** @type {((data: import('./types').EditorDocument) => void) | undefined} */
+  #onChange
+
+  /** @type {number} */
+  #delay
+
+  /** @type {boolean} */
+  #destroyed = false
+
+  /**
+   * @param {() => import('./types').EditorDocument | Promise<import('./types').EditorDocument>} saveFn
+   * @param {((data: import('./types').EditorDocument) => void)} [onChange]
+   * @param {number} [delay]
+   */
+  constructor(saveFn, onChange, delay = 250) {
+    this.#saveFn = saveFn
+    this.#onChange = onChange
+    this.#delay = delay
+  }
+
+  schedule() {
+    if (this.#destroyed || !this.#onChange) return
+    if (this.#timer) clearTimeout(this.#timer)
+    this.#timer = setTimeout(async () => {
+      this.#timer = null
+      if (this.#onChange) {
+        try {
+          const data = await this.#saveFn()
+          if (!this.#destroyed) this.#onChange?.(data)
+        } catch (err) {
+          console.warn('[ChangeNotifier] Failed to save:', err)
+        }
+      }
+    }, this.#delay)
+  }
+
+  destroy() {
+    this.#destroyed = true
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = null
+    }
+  }
+}

package/dist/core/CommandDispatcher.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Single execution boundary for editor commands.
+ *
+ * Commands may provide a cheap inverse rollback. Otherwise, the dispatcher
+ * restores the canonical pre-command checkpoint configured by the composition
+ * root. Nested commands join the outer command and produce one history entry.
+ */
+export class CommandDispatcher {
+    /**
+     * @param {import('./types.js').IBlockManager} blocks Block manager whose
+     * affected instances are marked dirty after a successful command.
+     * @param {import('./types.js').IEventBus} events Event bus used to delimit
+     * document changes and history transactions.
+     * @param {import('./Diagnostics.js').Diagnostics} [diagnostics] Optional
+     * diagnostics sink for failed and slow commands.
+     */
+    constructor(blocks: import("./types.js").IBlockManager, events: import("./types.js").IEventBus, diagnostics?: import("./Diagnostics.js").Diagnostics);
+    /** Configure the canonical fallback used when a command throws. */
+    configureRollback(capture: any, restore: any): void;
+    get active(): boolean;
+    runForRange(range: any, operation: any): any;
+    runForBlock(block: any, operation: any): any;
+    runForBlocks(blocks: any, operation: any): any;
+    /** Commit a mutation performed by an integration callback outside execute(). */
+    commitExternal(block: any): void;
+    /** Commit a callback that already changed a known set of blocks. */
+    commitExternalMany(blocks: any): void;
+    /**
+     * Execute a command object.
+     * @template T
+     * @param {{
+     *   name: string,
+     *   affected?: Iterable<import('./types.js').IBlock>,
+     *   apply: () => T,
+     *   rollback?: () => void,
+     *   markDirty?: boolean,
+     *   notifyChange?: boolean,
+     *   notify?: (result: T) => void,
+     * }} command
+     * @returns {T}
+     */
+    execute<T>(command: {
+        name: string;
+        affected?: Iterable<import("./types.js").IBlock>;
+        apply: () => T;
+        rollback?: () => void;
+        markDirty?: boolean;
+        notifyChange?: boolean;
+        notify?: (result: T) => void;
+    }): T;
+    #private;
+}

package/dist/core/CommandDispatcher.js

@@ -0,0 +1,208 @@
+import { EditorEvent } from './editorEvents.js'
+
+/**
+ * Single execution boundary for editor commands.
+ *
+ * Commands may provide a cheap inverse rollback. Otherwise, the dispatcher
+ * restores the canonical pre-command checkpoint configured by the composition
+ * root. Nested commands join the outer command and produce one history entry.
+ */
+export class CommandDispatcher {
+  /** @type {import('./types').IBlockManager} */ #blocks
+  /** @type {import('./types').IEventBus} */ #events
+  /** @type {number} */ #depth = 0
+  /** @type {Set<import('./types').IBlock>} */ #affected = new Set()
+  /** @type {(() => import('./types').EditorDocument) | null} */ #capture = null
+  /** @type {((document: import('./types').EditorDocument) => void) | null} */ #restore = null
+  /** @type {boolean} */ #restoring = false
+  /** @type {unknown} */ #nestedFailure = null
+  /** @type {import('./Diagnostics').Diagnostics | null} */ #diagnostics
+
+  /**
+   * @param {import('./types').IBlockManager} blocks Block manager whose
+   * affected instances are marked dirty after a successful command.
+   * @param {import('./types').IEventBus} events Event bus used to delimit
+   * document changes and history transactions.
+   * @param {import('./Diagnostics').Diagnostics} [diagnostics] Optional
+   * diagnostics sink for failed and slow commands.
+   */
+  constructor(blocks, events, diagnostics) {
+    this.#blocks = blocks
+    this.#events = events
+    this.#diagnostics = diagnostics ?? null
+  }
+
+  /**
+   * Propagate a nested command failure to the outer transaction even when an
+   * intermediate caller caught it.
+   * @param {boolean} outermost Whether the current command owns the transaction.
+   * @throws {unknown} The first failure raised by a nested command.
+   */
+  #throwNestedFailure(outermost) {
+    if (outermost && this.#nestedFailure) throw this.#nestedFailure
+  }
+
+  /** Configure the canonical fallback used when a command throws. */
+  configureRollback(capture, restore) {
+    this.#capture = capture
+    this.#restore = restore
+  }
+
+  get active() { return this.#depth > 0 }
+
+  runForRange(range, operation) {
+    return this.execute({
+      name: 'inline-range',
+      affected: this.#blocksForRange(range),
+      apply: operation,
+    })
+  }
+
+  runForBlock(block, operation) {
+    return this.execute({ name: `block:${block.type}`, affected: [block], apply: operation })
+  }
+
+  runForBlocks(blocks, operation) {
+    return this.execute({ name: 'blocks', affected: blocks, apply: operation })
+  }
+
+  /** Commit a mutation performed by an integration callback outside execute(). */
+  commitExternal(block) {
+    this.commitExternalMany([block])
+  }
+
+  /** Commit a callback that already changed a known set of blocks. */
+  commitExternalMany(blocks) {
+    for (const block of blocks) this.#affected.add(block)
+    if (this.#depth > 0) return
+    const affected = [...this.#affected]
+    this.#affected.clear()
+    this.#markAndCommit(affected)
+  }
+
+  /**
+   * Execute a command object.
+   * @template T
+   * @param {{
+   *   name: string,
+   *   affected?: Iterable<import('./types').IBlock>,
+   *   apply: () => T,
+   *   rollback?: () => void,
+   *   markDirty?: boolean,
+   *   notifyChange?: boolean,
+   *   notify?: (result: T) => void,
+   * }} command
+   * @returns {T}
+   */
+  execute(command) {
+    if (this.#restoring) return command.apply()
+
+    const outermost = this.#depth === 0
+    const startedAt = outermost && this.#diagnostics?.enabled ? this.#diagnostics.now() : 0
+    if (outermost) this.#nestedFailure = null
+    for (const block of command.affected ?? []) this.#affected.add(block)
+    const checkpoint = outermost && this.#capture ? this.#capture() : null
+    if (outermost && command.notifyChange !== false) this.#events.emit(EditorEvent.WILL_CHANGE)
+
+    let failed = false
+    this.#depth++
+    try {
+      const result = command.apply()
+      command.notify?.(result)
+      // A nested command cannot be made successful by catching its error in
+      // the caller: the outer transaction is poisoned and rolls back whole.
+      this.#throwNestedFailure(outermost)
+      return result
+    } catch (cause) {
+      failed = true
+      this.#nestedFailure ??= cause
+      if (outermost) {
+        this.#diagnostics?.emit('command.failed', {
+          operation: command.name,
+          errorName: this.#diagnostics.errorName(cause),
+        })
+      }
+      if (outermost) this.#rollback(command, checkpoint, cause)
+      throw cause
+    } finally {
+      this.#depth--
+      if (outermost) {
+        const affected = [...this.#affected]
+        this.#affected.clear()
+        // A failed command was restored and must not create a history entry.
+        if (!failed && command.notifyChange !== false) {
+          this.#markAndCommit(command.markDirty === false ? [] : affected)
+        }
+        if (startedAt && this.#diagnostics) {
+          const durationMs = this.#diagnostics.now() - startedAt
+          if (durationMs >= this.#diagnostics.threshold('commandMs')) {
+            this.#diagnostics.emit('command.slow', { operation: command.name, durationMs })
+          }
+        }
+        this.#nestedFailure = null
+      }
+    }
+  }
+
+  #rollback(command, checkpoint, cause) {
+    let inverseError = null
+    if (command.rollback) {
+      try {
+        command.rollback()
+        return
+      } catch (error) {
+        inverseError = error
+      }
+    }
+
+    if (!checkpoint || !this.#restore) {
+      if (inverseError) throw new AggregateError([cause, inverseError], `Command "${command.name}" and its rollback failed`)
+      return
+    }
+
+    this.#restoring = true
+    try {
+      this.#restore(checkpoint)
+    } catch (restoreError) {
+      throw new AggregateError(
+        inverseError ? [cause, inverseError, restoreError] : [cause, restoreError],
+        `Command "${command.name}" failed and its checkpoint could not be restored`,
+      )
+    } finally {
+      this.#restoring = false
+    }
+  }
+
+  #markAndCommit(affected) {
+    const seen = new Set()
+    for (const block of affected) {
+      if (seen.has(block) || this.#blocks.getBlockById(block.id) !== block) continue
+      seen.add(block)
+      block.markDirty()
+      this.#events.emit(EditorEvent.BLOCK_CHANGED, { blockId: block.id })
+    }
+    this.#events.emit(EditorEvent.CHANGED)
+    this.#events.emit(EditorEvent.HISTORY_COMMIT)
+  }
+
+  #blocksForRange(range) {
+    const result = []
+    for (const block of this.#blocks) {
+      const content = block.contentElement
+      let intersects = content.contains(range.startContainer)
+        || content.contains(range.endContainer)
+      try {
+        intersects ||= range.intersectsNode(content)
+      } catch { /* detached node */ }
+      if (intersects) result.push(block)
+    }
+
+    if (result.length === 0) {
+      const start = this.#blocks.getBlockByChildNode(range.startContainer)
+      const end = this.#blocks.getBlockByChildNode(range.endContainer)
+      if (start) result.push(start)
+      if (end && end !== start) result.push(end)
+    }
+    return result
+  }
+}

package/dist/core/CrossBlockSelection.d.ts

@@ -0,0 +1,30 @@
+export class CrossBlockSelection {
+    /**
+     * Show a visual-only CSS Highlight for a range (no state change).
+     * @param {Range} range
+     */
+    static showHighlight(range: Range): void;
+    /**
+     * Remove the visual-only CSS Highlight (no state change).
+     */
+    static hideHighlight(): void;
+    /** @returns {Range | null} */
+    get range(): Range | null;
+    /** @param {Range} range */
+    set(range: Range): void;
+    clear(): void;
+    /** @returns {Range | null} */
+    clone(): Range | null;
+    /**
+     * Store the range and activate visual highlight.
+     * @param {Range} range
+     * @param {HTMLElement} rootEl - `.oe-editor` element
+     */
+    activate(range: Range, rootEl: HTMLElement): void;
+    /**
+     * Clear the stored range and remove visual highlight.
+     * @param {HTMLElement} [rootEl] - `.oe-editor` element
+     */
+    deactivate(rootEl?: HTMLElement): void;
+    #private;
+}

package/dist/core/CrossBlockSelection.js

@@ -0,0 +1,74 @@
+/**
+ * Stores the cross-block Range that native Selection cannot represent.
+ * Browsers clip Selection to the focused contentEditable, so this service
+ * preserves the full range across editing hosts for copy/cut/format/convert.
+ *
+ * Also manages the visual side-effects: CSS Highlight API painting and
+ * the `.oe-editor--cross-selecting` class that suppresses `::selection`.
+ */
+/** Highlight key used across the editor for cross-block visual highlight. */
+const HIGHLIGHT_KEY = 'oe-cross-select'
+
+export class CrossBlockSelection {
+  /** @type {Range | null} */
+  #range = null
+
+  /** @returns {Range | null} */
+  get range() {
+    return this.#range
+  }
+
+  /** @param {Range} range */
+  set(range) {
+    this.#range = range
+  }
+
+  clear() {
+    this.#range = null
+  }
+
+  /** @returns {Range | null} */
+  clone() {
+    return this.#range?.cloneRange() ?? null
+  }
+
+  /**
+   * Show a visual-only CSS Highlight for a range (no state change).
+   * @param {Range} range
+   */
+  static showHighlight(range) {
+    if (typeof Highlight !== 'undefined' && CSS.highlights) {
+      CSS.highlights.set(HIGHLIGHT_KEY, new Highlight(range))
+    }
+  }
+
+  /**
+   * Remove the visual-only CSS Highlight (no state change).
+   */
+  static hideHighlight() {
+    if (typeof CSS !== 'undefined' && CSS.highlights) {
+      CSS.highlights.delete(HIGHLIGHT_KEY)
+    }
+  }
+
+  /**
+   * Store the range and activate visual highlight.
+   * @param {Range} range
+   * @param {HTMLElement} rootEl - `.oe-editor` element
+   */
+  activate(range, rootEl) {
+    this.#range = range
+    rootEl.classList.add('oe-editor--cross-selecting')
+    CrossBlockSelection.showHighlight(range)
+  }
+
+  /**
+   * Clear the stored range and remove visual highlight.
+   * @param {HTMLElement} [rootEl] - `.oe-editor` element
+   */
+  deactivate(rootEl) {
+    this.#range = null
+    if (rootEl) rootEl.classList.remove('oe-editor--cross-selecting')
+    CrossBlockSelection.hideHighlight()
+  }
+}

package/dist/core/Diagnostics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Content-free, opt-in production diagnostics.
+ * Consumer callbacks are isolated and can never break editor execution.
+ */
+export class Diagnostics {
+    /**
+     * @param {import('./types.js').EditorConfig['onDiagnostic']} report
+     * @param {import('./types.js').EditorConfig['diagnosticThresholds']} thresholds
+     */
+    constructor(report: import("./types.js").EditorConfig["onDiagnostic"], thresholds?: import("./types.js").EditorConfig["diagnosticThresholds"]);
+    get enabled(): boolean;
+    /** @param {keyof import('./types.js').DiagnosticThresholds} name */
+    threshold(name: keyof import("./types.js").DiagnosticThresholds): number;
+    now(): number;
+    /**
+     * @param {import('./types.js').EditorDiagnosticCode} code
+     * @param {Omit<import('./types.js').EditorDiagnostic, 'code' | 'timestamp'>} [details]
+     */
+    emit(code: import("./types.js").EditorDiagnosticCode, details?: Omit<import("./types.js").EditorDiagnostic, "code" | "timestamp">): void;
+    /** @param {unknown} error */
+    errorName(error: unknown): string;
+    #private;
+}