@shelamkoff/rector 1.0.0

package/dist/core/MouseSelectionManager.js

@@ -0,0 +1,307 @@
+/**
+ * Handles mouse-driven selection across blocks:
+ * - Cross-block text selection via mouse drag
+ * - Click-area handling (clicking below all blocks)
+ * - CSS Highlight API for cross-contenteditable selection
+ */
+import { BLOCK_SELECTOR } from './constants.js'
+import { EditorEvent } from './editorEvents.js'
+
+export class MouseSelectionManager {
+  /** @type {HTMLElement} */
+  #rootEl
+
+  /** @type {HTMLElement} */
+  #blocksEl
+
+  /** @type {HTMLElement} */
+  #clickArea
+
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {import('./types').ISelectionManager} */
+  #selection
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {import('./types').ICrossBlockSelection} */
+  #crossBlockSelection
+
+  /** @type {string} */
+  #defaultBlockType
+
+  /** @type {import('./types').IBlock | null} */
+  #mouseStartBlock = null
+
+  /** @type {import('./types').DOMNode | null} exact DOM node of mousedown caret */
+  #mouseStartNode = null
+
+  /** @type {number} offset within mouseStartNode */
+  #mouseStartOffset = 0
+
+  /** @type {boolean} */
+  #isBlockSelecting = false
+
+  /**
+   * @typedef {Object} MouseSelectionConfig
+   * @property {HTMLElement} blocksEl
+   * @property {HTMLElement} clickArea
+   * @property {import('./types').IBlockManager} blocks
+   * @property {import('./types').ISelectionManager} selection
+   * @property {import('./types').IEventBus} events
+   * @property {import('./types').ICrossBlockSelection} crossBlockSelection
+   * @property {string} defaultBlockType
+   */
+
+  /**
+   * @param {HTMLElement} rootEl
+   * @param {MouseSelectionConfig} config
+   */
+  constructor(rootEl, config) {
+    const { blocksEl, clickArea, blocks, selection, events, crossBlockSelection, defaultBlockType } = config
+    this.#rootEl = rootEl
+    this.#blocksEl = blocksEl
+    this.#clickArea = clickArea
+    this.#blocks = blocks
+    this.#selection = selection
+    this.#events = events
+    this.#crossBlockSelection = crossBlockSelection
+    this.#defaultBlockType = defaultBlockType
+
+    rootEl.addEventListener('mousedown', this.#onMouseDown)
+    rootEl.addEventListener('click', this.#onClickArea)
+    document.addEventListener('mousemove', this.#onMouseMove)
+    document.addEventListener('mouseup', this.#onMouseUp)
+    // Outside-click handler: clears cross-block selection + native text
+    // selection when the user clicks anywhere outside the editor, mirroring
+    // how plain text fields lose selection on outside focus.
+    document.addEventListener('mousedown', this.#onDocumentMouseDown, true)
+  }
+
+  /**
+   * Clean up all event listeners.
+   */
+  destroy() {
+    this.#rootEl.removeEventListener('mousedown', this.#onMouseDown)
+    this.#rootEl.removeEventListener('click', this.#onClickArea)
+    document.removeEventListener('mousemove', this.#onMouseMove)
+    document.removeEventListener('mouseup', this.#onMouseUp)
+    document.removeEventListener('mousedown', this.#onDocumentMouseDown, true)
+  }
+
+  /**
+   * Clear any active block selection state.
+   */
+  #clearBlockSelection() {
+    this.#blocks.clearSelection()
+    this.#isBlockSelecting = false
+    this.#crossBlockSelection.deactivate(this.#rootEl)
+  }
+
+  /**
+   * Document-level mousedown. Clears block/cross-block selection and any
+   * native text selection that lives inside the editor when the user
+   * clicks ANYWHERE outside the editor root — matching the standard
+   * text-field UX where clicking elsewhere drops the selection.
+   *
+   * Events originating INSIDE the editor are left alone: the `rootEl`
+   * mousedown listener (`#onMouseDown`) already handles them.
+   *
+   * @param {MouseEvent} e
+   */
+  #onDocumentMouseDown = (e) => {
+    const target = e.target
+    if (!(target instanceof Node) || this.#rootEl.contains(target)) return
+
+    // Drop block + cross-block selection.
+    this.#clearBlockSelection()
+
+    // If the native text selection is still anchored inside the editor,
+    // collapse it so the user sees the selection disappear visually.
+    const nativeSel = window.getSelection()
+    if (nativeSel && nativeSel.rangeCount > 0) {
+      const anchor = nativeSel.anchorNode
+      if (anchor && this.#rootEl.contains(anchor)) {
+        nativeSel.removeAllRanges()
+      }
+    }
+  }
+
+  /**
+   * Get caret position under a point.
+   * @param {number} x
+   * @param {number} y
+   * @returns {{ node: import('./types').DOMNode, offset: number } | null}
+   */
+  #caretFromPoint(x, y) {
+    if (typeof document.caretPositionFromPoint === 'function') {
+      const p = document.caretPositionFromPoint(x, y)
+      return p ? { node: p.offsetNode, offset: p.offset } : null
+    }
+    // Compatibility fallback for engines that expose only the legacy API.
+    // Reflective access keeps the deprecated member out of the core contract.
+    const legacyCaretRangeFromPoint = /** @type {((x: number, y: number) => Range | null) | undefined} */ (
+      Reflect.get(document, 'caretRangeFromPoint')
+    )
+    if (typeof legacyCaretRangeFromPoint === 'function') {
+      const r = legacyCaretRangeFromPoint.call(document, x, y)
+      return r ? { node: r.startContainer, offset: r.startOffset } : null
+    }
+    return null
+  }
+
+  /** Check if target is the click area below all blocks */
+  #isClickAreaTarget(/** @type {HTMLElement} */ target) {
+    return target === this.#clickArea
+  }
+
+  /** Check if target is any empty space (gaps, root, blocks container, click area) */
+  #isEmptySpace(/** @type {HTMLElement} */ target) {
+    return target === this.#rootEl || target === this.#blocksEl || target === this.#clickArea
+  }
+
+  #onMouseDown = (/** @type {MouseEvent} */ e) => {
+    const target = e.target
+    if (!(target instanceof HTMLElement)) return
+
+    // Only clear cross-block selection when clicking inside content area,
+    // not on toolbar buttons or other UI elements
+    if (target.closest(BLOCK_SELECTOR) || target.closest('.oe-blocks') || this.#isClickAreaTarget(target)) {
+      this.#clearBlockSelection()
+    }
+
+    this.#mouseStartNode = null
+    this.#mouseStartOffset = 0
+
+    if (this.#isEmptySpace(target)) {
+      if (this.#isClickAreaTarget(target)) {
+        const lastBlock = this.#blocks.getBlockByIndex(this.#blocks.getBlockCount() - 1)
+        this.#mouseStartBlock = lastBlock || null
+      } else {
+        this.#mouseStartBlock = null
+      }
+      return
+    }
+
+    this.#mouseStartBlock = this.#blocks.getBlockByChildNode(target) ?? null
+
+    const caret = this.#caretFromPoint(e.clientX, e.clientY)
+    if (caret) {
+      this.#mouseStartNode = caret.node
+      this.#mouseStartOffset = caret.offset
+    }
+  }
+
+  #onClickArea = (/** @type {MouseEvent} */ e) => {
+    if (this.#isBlockSelecting) return
+
+    const target = e.target
+    if (!(target instanceof HTMLElement)) return
+    if (!this.#isClickAreaTarget(target)) return
+
+    const blocks = this.#blocks
+    const lastBlock = blocks.getBlockByIndex(blocks.getBlockCount() - 1)
+
+    if (lastBlock && lastBlock.isEmpty() && lastBlock.type === this.#defaultBlockType) {
+      const idx = blocks.getBlockIndex(lastBlock.id)
+      blocks.setCurrentIndex(idx)
+      lastBlock.focus()
+      this.#selection.setCaretToBlock(lastBlock.id, 'start')
+      return
+    }
+
+    const focusBlock = blocks.insert(this.#defaultBlockType, undefined, blocks.getBlockCount())
+    const idx = blocks.getBlockIndex(focusBlock.id)
+    blocks.setCurrentIndex(idx)
+    focusBlock.focus()
+    this.#selection.setCaretToBlock(focusBlock.id, 'start')
+  }
+
+  #onMouseMove = (/** @type {MouseEvent} */ e) => {
+    if (!this.#mouseStartBlock || (e.buttons & 1) === 0) return
+
+    const blocks = this.#blocks
+    const currentBlock = blocks.getBlockByY(e.clientY)
+    if (!currentBlock) return
+
+    if (currentBlock.id === this.#mouseStartBlock.id) {
+      if (this.#isBlockSelecting) {
+        const rect = this.#mouseStartBlock.element.getBoundingClientRect()
+        if (e.clientY >= rect.top && e.clientY <= rect.bottom) {
+          this.#clearBlockSelection()
+        }
+      }
+      return
+    }
+
+    e.preventDefault()
+    if (!this.#mouseStartNode) return
+
+    this.#isBlockSelecting = true
+
+    const endContent = currentBlock.contentElement
+    const contentRect = endContent.getBoundingClientRect()
+    const clampedY = Math.max(contentRect.top + 1, Math.min(contentRect.bottom - 1, e.clientY))
+    let endCaret = this.#caretFromPoint(e.clientX, clampedY)
+    if (!endCaret) return
+
+    const range = document.createRange()
+    const startIdx = blocks.getBlockIndex(this.#mouseStartBlock.id)
+    const endIdx = blocks.getBlockIndex(currentBlock.id)
+
+    try {
+      if (startIdx <= endIdx) {
+        range.setStart(this.#mouseStartNode, this.#mouseStartOffset)
+        range.setEnd(endCaret.node, endCaret.offset)
+      } else {
+        range.setStart(endCaret.node, endCaret.offset)
+        range.setEnd(this.#mouseStartNode, this.#mouseStartOffset)
+      }
+    } catch {
+      return
+    }
+
+    this.#crossBlockSelection.activate(range, this.#rootEl)
+
+    const sel = window.getSelection()
+    if (sel) {
+      try {
+        sel.removeAllRanges()
+        sel.setBaseAndExtent(
+          this.#mouseStartNode, this.#mouseStartOffset,
+          endCaret.node, endCaret.offset,
+        )
+      } catch {
+        // Native selection across editing hosts not supported
+      }
+    }
+
+    const from = Math.min(startIdx, endIdx)
+    let to = Math.max(startIdx, endIdx)
+
+    const lastBlockIdx = blocks.getBlockCount() - 1
+    if (to === lastBlockIdx) {
+      const lb = blocks.getBlockByIndex(lastBlockIdx)
+      if (lb?.isEmpty()) to = Math.max(from, to - 1)
+    }
+
+    const ids = []
+    blocks.clearSelection()
+    for (let i = from; i <= to; i++) {
+      const b = blocks.getBlockByIndex(i)
+      if (b) {
+        b.selected = true
+        ids.push(b.id)
+      }
+    }
+    this.#events.emit(EditorEvent.BLOCK_SELECTED, { blockIds: ids })
+  }
+
+  #onMouseUp = () => {
+    this.#mouseStartBlock = null
+    this.#mouseStartNode = null
+    this.#mouseStartOffset = 0
+  }
+}

package/dist/core/PluginOwnership.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Prevent mutable plugin instances from being shared by live editors and
+ * release optional editor-scoped resources when ownership ends.
+ * @param {unknown[]} instances
+ * @returns {{ destroy(): void }}
+ */
+export function claimPluginInstances(instances: unknown[]): {
+    destroy(): void;
+};

package/dist/core/PluginOwnership.js

@@ -0,0 +1,40 @@
+/** Plugin instances carry mutable locale/config and belong to one live editor. */
+const owned = new WeakSet()
+
+/**
+ * Prevent mutable plugin instances from being shared by live editors and
+ * release optional editor-scoped resources when ownership ends.
+ * @param {unknown[]} instances
+ * @returns {{ destroy(): void }}
+ */
+export function claimPluginInstances(instances) {
+  const claimed = []
+  const pending = new Set()
+  for (const instance of instances) {
+    if ((typeof instance !== 'object' || instance === null) && typeof instance !== 'function') continue
+    if (owned.has(instance) || pending.has(instance)) {
+      throw new Error('A plugin instance cannot be shared by multiple live editors')
+    }
+    pending.add(instance)
+    claimed.push(instance)
+  }
+  for (const instance of claimed) owned.add(instance)
+
+  let released = false
+  return {
+    destroy() {
+      if (released) return
+      released = true
+      for (const instance of claimed) {
+        try {
+          const disposable = /** @type {{ dispose?: () => void }} */ (instance)
+          disposable.dispose?.()
+        } catch (error) {
+          console.warn('[PluginOwnership] Failed to dispose plugin:', error)
+        } finally {
+          owned.delete(instance)
+        }
+      }
+    },
+  }
+}

package/dist/core/PopupManager.d.ts

@@ -0,0 +1,50 @@
+/** @typedef {import('./types.js').InlinePluginContext} InlinePluginContextContract */
+/**
+ * Manages floating popups for inline plugins (color picker, etc.).
+ * Positions popup near an anchor element, handles outside-click dismissal.
+ *
+ * @implements {InlinePluginContextContract}
+ */
+export class PopupManager implements InlinePluginContextContract {
+    /**
+     * @param {import('./types.js').IEventBus} events
+     * @param {string} changedEvent
+     * @param {import('./types.js').IBlockManager} blocks
+     * @param {import('./CommandDispatcher.js').CommandDispatcher} commands
+     * @param {() => boolean} [isReadOnly]
+     */
+    constructor(events: import("./types.js").IEventBus, changedEvent: string, blocks: import("./types.js").IBlockManager, commands: import("./CommandDispatcher.js").CommandDispatcher, isReadOnly?: () => boolean);
+    get readOnly(): boolean;
+    /**
+     * Set the editor root element (popup inherits CSS variables from it).
+     * @param {HTMLElement} rootEl
+     */
+    setRoot(rootEl: HTMLElement): void;
+    /**
+     * Show a popup near an anchor element.
+     * @param {HTMLElement} anchor
+     * @param {HTMLElement} content
+     * @param {(() => void) | undefined} cleanup
+     */
+    showPopup(anchor: HTMLElement, content: HTMLElement, cleanup: (() => void) | undefined): void;
+    hidePopup(): void;
+    /**
+     * Notify through the concrete editing host whenever one can be resolved.
+     * This lets the editor invalidate the exact block cache rather than only
+     * scheduling a document-level change callback.
+     * @param {import('./types.js').DOMNode} [target]
+     */
+    notifyChanged(target?: import("./types.js").DOMNode): void;
+    /**
+     * Execute one inline-widget command against its exact owning block.
+     * Detached/stale widget callbacks are ignored.
+     * @template T
+     * @param {import('./types.js').DOMNode} target
+     * @param {() => T} operation
+     * @returns {T | undefined}
+     */
+    mutate<T>(target: import("./types.js").DOMNode, operation: () => T): T | undefined;
+    destroy(): void;
+    #private;
+}
+export type InlinePluginContextContract = import("./types.js").InlinePluginContext;

package/dist/core/PopupManager.js

@@ -0,0 +1,183 @@
+/** @typedef {import('./types').InlinePluginContext} InlinePluginContextContract */
+/**
+ * Manages floating popups for inline plugins (color picker, etc.).
+ * Positions popup near an anchor element, handles outside-click dismissal.
+ *
+ * @implements {InlinePluginContextContract}
+ */
+export class PopupManager {
+  /** @type {HTMLElement | null} */
+  #activePopup = null
+
+  /** @type {((e: MouseEvent) => void) | null} */
+  #outsideClickHandler = null
+
+  /** @type {(() => void) | null} */
+  #activeCleanup = null
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {string} */
+  #changedEvent
+
+  /** @type {HTMLElement | null} */
+  #rootEl = null
+
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {import('./CommandDispatcher').CommandDispatcher} */
+  #mutations
+
+  /** @type {() => boolean} */
+  #isReadOnly
+
+  /**
+   * @param {import('./types').IEventBus} events
+   * @param {string} changedEvent
+   * @param {import('./types').IBlockManager} blocks
+   * @param {import('./CommandDispatcher').CommandDispatcher} commands
+   * @param {() => boolean} [isReadOnly]
+   */
+  constructor(events, changedEvent, blocks, commands, isReadOnly = () => false) {
+    this.#events = events
+    this.#changedEvent = /** @type {*} */ (changedEvent)
+    this.#blocks = blocks
+    this.#mutations = commands
+    this.#isReadOnly = isReadOnly
+  }
+
+  get readOnly() {
+    return this.#isReadOnly()
+  }
+
+  /**
+   * Set the editor root element (popup inherits CSS variables from it).
+   * @param {HTMLElement} rootEl
+   */
+  setRoot(rootEl) {
+    this.#rootEl = rootEl
+  }
+
+  /**
+   * Show a popup near an anchor element.
+   * @param {HTMLElement} anchor
+   * @param {HTMLElement} content
+   * @param {(() => void) | undefined} cleanup
+   */
+  showPopup(anchor, content, cleanup) {
+    if (this.readOnly) {
+      this.#runCleanup(cleanup)
+      return
+    }
+    this.hidePopup()
+
+    const popup = document.createElement('div')
+    popup.className = 'oe-ip-popup'
+    popup.appendChild(content)
+
+    // Append inside editor root to inherit CSS variables (theme)
+    const container = this.#rootEl || document.body
+    container.appendChild(popup)
+
+    // Measure after append so offsetHeight is available.
+    // Popup uses position:fixed, so viewport coordinates are correct.
+    const rect = anchor.getBoundingClientRect()
+    const popupHeight = popup.offsetHeight || 260
+    const spaceBelow = window.innerHeight - rect.bottom - 8
+
+    popup.style.left = `${rect.left}px`
+    if (spaceBelow >= popupHeight) {
+      popup.style.top = `${rect.bottom + 4}px`
+    } else {
+      popup.style.top = `${rect.top - popupHeight - 4}px`
+    }
+
+    this.#activePopup = popup
+    this.#activeCleanup = cleanup || null
+
+    // Arm after the opening event finishes, without depending on a rendered
+    // animation frame (background tabs may suspend rAF indefinitely).
+    queueMicrotask(() => {
+      if (this.#activePopup !== popup) return
+      this.#outsideClickHandler = (/** @type {MouseEvent} */ e) => {
+        const target = e.target
+        if (!(target instanceof Node)) return
+        if (popup.contains(target)) return
+        if (anchor.contains(target)) return
+        this.hidePopup()
+      }
+      document.addEventListener('mousedown', this.#outsideClickHandler, true)
+    })
+  }
+
+  hidePopup() {
+    if (this.#outsideClickHandler) {
+      document.removeEventListener('mousedown', this.#outsideClickHandler, true)
+      this.#outsideClickHandler = null
+    }
+    if (this.#activePopup) {
+      this.#activePopup.remove()
+      this.#activePopup = null
+    }
+
+    const cleanup = this.#activeCleanup
+    this.#activeCleanup = null
+    this.#runCleanup(cleanup)
+  }
+
+  /**
+   * A plugin disposer must not interrupt a mode switch or editor teardown.
+   * @param {(() => void) | null | undefined} cleanup
+   */
+  #runCleanup(cleanup) {
+    if (!cleanup) return
+    try {
+      cleanup()
+    } catch (error) {
+      console.error('Inline popup cleanup failed', error)
+    }
+  }
+
+  /**
+   * Notify through the concrete editing host whenever one can be resolved.
+   * This lets the editor invalidate the exact block cache rather than only
+   * scheduling a document-level change callback.
+   * @param {import('./types').DOMNode} [target]
+   */
+  notifyChanged(target) {
+    if (this.readOnly) return
+    const candidate = target
+      ?? window.getSelection()?.anchorNode
+      ?? document.activeElement
+    const element = candidate?.nodeType === Node.ELEMENT_NODE
+      ? /** @type {Element} */ (candidate)
+      : candidate?.parentElement
+    const editable = element?.closest?.('[contenteditable="true"]')
+    if (editable && (!this.#rootEl || this.#rootEl.contains(editable))) {
+      editable.dispatchEvent(new InputEvent('input', { bubbles: true }))
+      return
+    }
+    this.#events.emit(/** @type {string} */ (this.#changedEvent))
+  }
+
+  /**
+   * Execute one inline-widget command against its exact owning block.
+   * Detached/stale widget callbacks are ignored.
+   * @template T
+   * @param {import('./types').DOMNode} target
+   * @param {() => T} operation
+   * @returns {T | undefined}
+   */
+  mutate(target, operation) {
+    if (this.readOnly) return undefined
+    const block = this.#blocks.getBlockByChildNode(target)
+    if (!block) return undefined
+    return this.#mutations.runForBlock(block, operation)
+  }
+
+  destroy() {
+    this.hidePopup()
+  }
+}

package/dist/core/PreservedBlockPlugin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Create an inert plugin for a document block whose implementation is not
+ * registered in this editor instance. The block remains removable and
+ * reorderable, but its plugin-owned payload is preserved byte-for-byte at the
+ * JSON value level instead of being handed to an unrelated default plugin.
+ *
+ * @param {string} type
+ * @param {(type: string) => string} label
+ * @returns {import('./types.js').BlockPlugin}
+ */
+export function createPreservedBlockPlugin(type: string, label: (type: string) => string): import("./types.js").BlockPlugin;

package/dist/core/PreservedBlockPlugin.js

@@ -0,0 +1,42 @@
+import { cloneEditorData } from '../shared/cloneEditorData.js'
+
+/**
+ * Create an inert plugin for a document block whose implementation is not
+ * registered in this editor instance. The block remains removable and
+ * reorderable, but its plugin-owned payload is preserved byte-for-byte at the
+ * JSON value level instead of being handed to an unrelated default plugin.
+ *
+ * @param {string} type
+ * @param {(type: string) => string} label
+ * @returns {import('./types').BlockPlugin}
+ */
+export function createPreservedBlockPlugin(type, label) {
+  /** @type {WeakMap<HTMLElement, Record<string, unknown>>} */
+  const dataByElement = new WeakMap()
+
+  return {
+    type,
+    title: type,
+    icon: '',
+    inlineTools: false,
+    render(data) {
+      const element = document.createElement('div')
+      element.className = 'oe-unsupported-block'
+      element.setAttribute('role', 'note')
+      const message = label(type)
+      element.setAttribute('aria-label', message)
+      element.textContent = message
+      dataByElement.set(element, cloneEditorData(data))
+      return element
+    },
+    save(element) {
+      return cloneEditorData(dataByElement.get(element) ?? {})
+    },
+    validate() {
+      return true
+    },
+    destroy(element) {
+      dataByElement.delete(element)
+    },
+  }
+}