@shelamkoff/rector 1.0.0

package/dist/core/PublicEditorApi.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Intentional public block surface. Structural commands delegate to the
+ * manager, while returned objects never expose manager-invariant mutators.
+ */
+export class EditorBlocksApi {
+    /**
+     * @param {import('./types.js').IBlockManager} blocks
+     * @param {import('./types.js').IEventBus} events
+     */
+    constructor(blocks: import("./types.js").IBlockManager, events: import("./types.js").IEventBus);
+    getBlockByIndex(index: any): PublicBlockView;
+    getBlockById(id: any): PublicBlockView;
+    getCurrentBlock(): PublicBlockView;
+    getCurrentIndex(): number;
+    getBlockCount(): number;
+    getBlockIndex(id: any): number;
+    getSelectedBlocks(): PublicBlockView[];
+    hasSelectedBlocks(): boolean;
+    /** Focus/navigation state is safe to expose as an explicit command. */
+    setCurrentIndex(index: any): void;
+    /** @param {string[]} blockIds */
+    selectBlocks(blockIds: string[]): void;
+    clearSelection(): void;
+    insert(type: any, data: any, index: any, id: any, inline: any): PublicBlockView;
+    remove(index: any): void;
+    move(fromIndex: any, toIndex: any): void;
+    convert(index: any, type: any, data: any): PublicBlockView;
+    [Symbol.iterator](): Generator<PublicBlockView, void, unknown>;
+    #private;
+}
+/** Public subscription-only facade over the internal mutable event bus. */
+export class EditorEventSubscriptions {
+    /** @param {import('./types.js').IEventBus} events */
+    constructor(events: import("./types.js").IEventBus);
+    on(event: any, handler: any): () => void;
+    off(event: any, handler: any): void;
+    once(event: any, handler: any): () => void;
+    #private;
+}
+/** Minimal consumer handle; the composition facade remains core-internal. */
+export class EditorHandle {
+    /** @param {import('./EditorFacade.js').EditorFacade} facade */
+    constructor(facade: import("./EditorFacade.js").EditorFacade);
+    get isReady(): boolean;
+    get blocks(): EditorBlocksApi;
+    get events(): EditorEventSubscriptions;
+    get rootElement(): HTMLElement;
+    get readOnly(): boolean;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    save(): import("./types.js").EditorDocument;
+    render(data: any): void;
+    clear(): void;
+    focus(): void;
+    undo(): boolean;
+    redo(): boolean;
+    setReadOnly(readOnly: any): void;
+    insertInlinePlugin(type: any, data: any): boolean;
+    destroy(): void;
+    #private;
+}
+/**
+ * Safe view over an internal Block. It deliberately omits manager-integrity
+ * methods such as destroy(), markDirty(), merge() and replaceContentElement().
+ */
+declare class PublicBlockView {
+    /** @param {import('./types.js').IBlock} block */
+    constructor(block: import("./types.js").IBlock);
+    get id(): string;
+    get type(): string;
+    get element(): HTMLElement;
+    get contentElement(): HTMLElement;
+    get focused(): boolean;
+    get selected(): boolean;
+    get hasInlineTools(): boolean;
+    get canMerge(): boolean;
+    get version(): number;
+    focus(): void;
+    isEmpty(): boolean;
+    #private;
+}
+export {};

package/dist/core/PublicEditorApi.js

@@ -0,0 +1,158 @@
+import { EditorEvent } from './editorEvents.js'
+
+/**
+ * Safe view over an internal Block. It deliberately omits manager-integrity
+ * methods such as destroy(), markDirty(), merge() and replaceContentElement().
+ */
+class PublicBlockView {
+  /** @type {import('./types').IBlock} */
+  #block
+
+  /** @param {import('./types').IBlock} block */
+  constructor(block) {
+    this.#block = block
+  }
+
+  get id() { return this.#block.id }
+  get type() { return this.#block.type }
+  get element() { return this.#block.element }
+  get contentElement() { return this.#block.contentElement }
+  get focused() { return this.#block.focused }
+  get selected() { return this.#block.selected }
+  get hasInlineTools() { return this.#block.hasInlineTools }
+  get canMerge() { return this.#block.canMerge }
+  get version() { return this.#block.version }
+  focus() { this.#block.focus() }
+  isEmpty() { return this.#block.isEmpty() }
+}
+
+/**
+ * Intentional public block surface. Structural commands delegate to the
+ * manager, while returned objects never expose manager-invariant mutators.
+ */
+export class EditorBlocksApi {
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {WeakMap<import('./types').IBlock, PublicBlockView>} */
+  #views = new WeakMap()
+
+  /**
+   * @param {import('./types').IBlockManager} blocks
+   * @param {import('./types').IEventBus} events
+   */
+  constructor(blocks, events) {
+    this.#blocks = blocks
+    this.#events = events
+  }
+
+  /** @returns {string[]} */
+  #selectedBlockIds() {
+    return this.#blocks.getSelectedBlocks().map(block => block.id)
+  }
+
+  /** @param {string[]} previousBlockIds */
+  #emitSelectionChanged(previousBlockIds) {
+    const blockIds = this.#selectedBlockIds()
+    const unchanged = blockIds.length === previousBlockIds.length
+      && blockIds.every((id, index) => id === previousBlockIds[index])
+    if (!unchanged) this.#events.emit(EditorEvent.BLOCK_SELECTED, { blockIds })
+  }
+
+  /** @param {import('./types').IBlock | undefined} block */
+  #view(block) {
+    if (!block) return undefined
+    let view = this.#views.get(block)
+    if (!view) {
+      view = new PublicBlockView(block)
+      this.#views.set(block, view)
+    }
+    return view
+  }
+
+  getBlockByIndex(index) { return this.#view(this.#blocks.getBlockByIndex(index)) }
+  getBlockById(id) { return this.#view(this.#blocks.getBlockById(id)) }
+  getCurrentBlock() { return this.#view(this.#blocks.getCurrentBlock()) }
+  getCurrentIndex() { return this.#blocks.getCurrentIndex() }
+  getBlockCount() { return this.#blocks.getBlockCount() }
+  getBlockIndex(id) { return this.#blocks.getBlockIndex(id) }
+  getSelectedBlocks() { return this.#blocks.getSelectedBlocks().map(block => this.#view(block)) }
+  hasSelectedBlocks() { return this.#blocks.hasSelectedBlocks() }
+
+  /** Focus/navigation state is safe to expose as an explicit command. */
+  setCurrentIndex(index) { this.#blocks.setCurrentIndex(index) }
+
+  /** @param {string[]} blockIds */
+  selectBlocks(blockIds) {
+    const previousBlockIds = this.#selectedBlockIds()
+    const selected = new Set(blockIds)
+    for (const block of this.#blocks) block.selected = selected.has(block.id)
+    this.#emitSelectionChanged(previousBlockIds)
+  }
+
+  clearSelection() {
+    const previousBlockIds = this.#selectedBlockIds()
+    this.#blocks.clearSelection()
+    this.#emitSelectionChanged(previousBlockIds)
+  }
+
+  insert(type, data, index, id, inline) {
+    return this.#view(this.#blocks.insert(type, data, index, id, inline))
+  }
+
+  remove(index) { this.#blocks.remove(index) }
+  move(fromIndex, toIndex) { this.#blocks.move(fromIndex, toIndex) }
+  convert(index, type, data) { return this.#view(this.#blocks.convert(index, type, data)) }
+
+  *[Symbol.iterator]() {
+    for (const block of this.#blocks) yield this.#view(block)
+  }
+}
+
+/** Public subscription-only facade over the internal mutable event bus. */
+export class EditorEventSubscriptions {
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @param {import('./types').IEventBus} events */
+  constructor(events) {
+    this.#events = events
+  }
+
+  on(event, handler) { return this.#events.on(event, handler) }
+  off(event, handler) { this.#events.off(event, handler) }
+  once(event, handler) { return this.#events.once(event, handler) }
+}
+
+/** Minimal consumer handle; the composition facade remains core-internal. */
+export class EditorHandle {
+  /** @type {import('./EditorFacade').EditorFacade} */
+  #facade
+
+  /** @param {import('./EditorFacade').EditorFacade} facade */
+  constructor(facade) { this.#facade = facade }
+
+  #assertActive() {
+    if (!this.#facade.isReady) throw new Error('Editor instance is destroyed')
+  }
+
+  get isReady() { return this.#facade.isReady }
+  get blocks() { this.#assertActive(); return this.#facade.blocks }
+  get events() { this.#assertActive(); return this.#facade.events }
+  get rootElement() { this.#assertActive(); return this.#facade.rootElement }
+  get readOnly() { this.#assertActive(); return this.#facade.readOnly }
+  get canUndo() { this.#assertActive(); return this.#facade.canUndo }
+  get canRedo() { this.#assertActive(); return this.#facade.canRedo }
+  save() { this.#assertActive(); return this.#facade.save() }
+  render(data) { this.#assertActive(); this.#facade.render(data) }
+  clear() { this.#assertActive(); this.#facade.clear() }
+  focus() { this.#assertActive(); this.#facade.focus() }
+  undo() { this.#assertActive(); return this.#facade.undo() }
+  redo() { this.#assertActive(); return this.#facade.redo() }
+  setReadOnly(readOnly) { this.#assertActive(); this.#facade.setReadOnly(readOnly) }
+  insertInlinePlugin(type, data) { this.#assertActive(); return this.#facade.insertInlinePlugin(type, data) }
+  destroy() { if (this.#facade.isReady) this.#facade.destroy() }
+}

package/dist/core/SelectionManager.d.ts

@@ -0,0 +1,50 @@
+/** @typedef {import('./types.js').ISelectionManager} ISelectionManagerContract */
+/** @implements {ISelectionManagerContract} */
+export class SelectionManager implements ISelectionManagerContract {
+    /**
+     * @param {HTMLElement} editorEl
+     * @param {import('./types.js').IBlockReader} blocks
+     */
+    constructor(editorEl: HTMLElement, blocks: import("./types.js").IBlockReader);
+    /**
+     * Get the current caret position info.
+     * @returns {import('./types.js').CaretPosition | null}
+     */
+    getCaret(): import("./types.js").CaretPosition | null;
+    /**
+     * Set the caret to the start or end of a block's content.
+     * @param {string} blockId
+     * @param {'start' | 'end'} position
+     */
+    setCaretToBlock(blockId: string, position: "start" | "end"): void;
+    /**
+     * Set the caret to a specific text offset within a block's content.
+     * Walks text nodes to find the correct position.
+     * @param {string} blockId
+     * @param {number} textOffset — character offset from start of block text
+     */
+    setCaretToOffset(blockId: string, textOffset: number): void;
+    /**
+     * Get the current text selection info (if any text is selected).
+     * @returns {import('./types.js').InlineSelection | null}
+     */
+    getSelection(): import("./types.js").InlineSelection | null;
+    /**
+     * Check if the caret is at the very start of the current block's content.
+     * @returns {boolean}
+     */
+    isAtStart(): boolean;
+    /**
+     * Check if the caret is at the very end of the current block's content.
+     * @returns {boolean}
+     */
+    isAtEnd(): boolean;
+    /**
+     * Extract the HTML content after the caret in the current block.
+     * Used for splitting blocks (Enter key) — intentionally mutates DOM.
+     * @returns {string | null}
+     */
+    extractFragmentAfterCaret(): string | null;
+    #private;
+}
+export type ISelectionManagerContract = import("./types.js").ISelectionManager;

package/dist/core/SelectionManager.js

@@ -0,0 +1,205 @@
+import { getTextOffset, firstTextNode, lastTextNode, editableTextWalker } from './textOffset.js'
+
+/** @typedef {import('./types').ISelectionManager} ISelectionManagerContract */
+/** @implements {ISelectionManagerContract} */
+export class SelectionManager {
+  /** @type {import('./types').IBlockReader} */
+  #blocks
+
+  /** @type {HTMLElement} */
+  #editorEl
+
+  /**
+   * @param {HTMLElement} editorEl
+   * @param {import('./types').IBlockReader} blocks
+   */
+  constructor(editorEl, blocks) {
+    this.#editorEl = editorEl
+    this.#blocks = blocks
+  }
+
+  /**
+   * Get the current native range if it's inside the editor.
+   * @returns {Range | null}
+   */
+  #getRange() {
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0) return null
+    const range = sel.getRangeAt(0)
+    if (!this.#editorEl.contains(range.startContainer)) return null
+    return range
+  }
+
+  /**
+   * Get the current caret position info.
+   * @returns {import('./types').CaretPosition | null}
+   */
+  getCaret() {
+    const range = this.#getRange()
+    if (!range) return null
+
+    const block = this.#blocks.getBlockByChildNode(range.startContainer)
+    if (!block) return null
+
+    return {
+      blockId: block.id,
+      offset: getTextOffset(block.contentElement, range.startContainer, range.startOffset),
+    }
+  }
+
+  /**
+   * Set the caret to the start or end of a block's content.
+   * @param {string} blockId
+   * @param {'start' | 'end'} position
+   */
+  setCaretToBlock(blockId, position) {
+    const block = this.#blocks.getBlockById(blockId)
+    if (!block) return
+
+    const element = block.contentElement
+    const sel = window.getSelection()
+    if (!sel) return
+
+    if (!element.hasChildNodes()) {
+      element.focus()
+      return
+    }
+
+    const range = document.createRange()
+
+    if (position === 'start') {
+      const node = firstTextNode(element) || element
+      range.setStart(node, 0)
+      range.collapse(true)
+    } else {
+      const node = lastTextNode(element) || element
+      const offset = node.nodeType === Node.TEXT_NODE
+        ? (node.textContent?.length ?? 0)
+        : node.childNodes.length
+      range.setStart(node, offset)
+      range.collapse(true)
+    }
+
+    sel.removeAllRanges()
+    sel.addRange(range)
+  }
+
+  /**
+   * Set the caret to a specific text offset within a block's content.
+   * Walks text nodes to find the correct position.
+   * @param {string} blockId
+   * @param {number} textOffset — character offset from start of block text
+   */
+  setCaretToOffset(blockId, textOffset) {
+    const block = this.#blocks.getBlockById(blockId)
+    if (!block) return
+
+    const element = block.contentElement
+    const sel = window.getSelection()
+    if (!sel) return
+
+    if (!element.hasChildNodes()) {
+      element.focus()
+      return
+    }
+
+    const walker = editableTextWalker(element)
+    let remaining = textOffset
+
+    while (walker.nextNode()) {
+      const node = walker.currentNode
+      const len = node.textContent?.length ?? 0
+
+      if (remaining <= len) {
+        const range = document.createRange()
+        range.setStart(node, remaining)
+        range.collapse(true)
+        sel.removeAllRanges()
+        sel.addRange(range)
+        return
+      }
+      remaining -= len
+    }
+
+    // Offset exceeds total text — clamp to end (can happen after merge/undo)
+    this.setCaretToBlock(blockId, 'end')
+  }
+
+  /**
+   * Get the current text selection info (if any text is selected).
+   * @returns {import('./types').InlineSelection | null}
+   */
+  getSelection() {
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0 || sel.isCollapsed) return null
+
+    const range = sel.getRangeAt(0)
+    if (!this.#editorEl.contains(range.startContainer)) return null
+
+    const block = this.#blocks.getBlockByChildNode(range.startContainer)
+    if (!block) return null
+
+    return {
+      blockId: block.id,
+      range: range.cloneRange(),
+      text: sel.toString(),
+    }
+  }
+
+  /**
+   * Check if the caret is at the very start of the current block's content.
+   * @returns {boolean}
+   */
+  isAtStart() {
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return false
+
+    const range = sel.getRangeAt(0)
+    const block = this.#blocks.getBlockByChildNode(range.startContainer)
+    if (!block) return false
+
+    return getTextOffset(block.contentElement, range.startContainer, range.startOffset) === 0
+  }
+
+  /**
+   * Check if the caret is at the very end of the current block's content.
+   * @returns {boolean}
+   */
+  isAtEnd() {
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return false
+
+    const range = sel.getRangeAt(0)
+    const block = this.#blocks.getBlockByChildNode(range.startContainer)
+    if (!block) return false
+
+    const totalLength = block.contentElement.textContent?.length ?? 0
+    const currentOffset = getTextOffset(block.contentElement, range.startContainer, range.startOffset)
+
+    return currentOffset >= totalLength
+  }
+
+  /**
+   * Extract the HTML content after the caret in the current block.
+   * Used for splitting blocks (Enter key) — intentionally mutates DOM.
+   * @returns {string | null}
+   */
+  extractFragmentAfterCaret() {
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0) return null
+
+    const range = sel.getRangeAt(0)
+    const block = this.#blocks.getBlockByChildNode(range.startContainer)
+    if (!block) return null
+
+    const endRange = document.createRange()
+    endRange.selectNodeContents(block.contentElement)
+    endRange.setStart(range.startContainer, range.startOffset)
+
+    const fragment = endRange.extractContents()
+    const temp = document.createElement('div')
+    temp.appendChild(fragment)
+
+    return temp.innerHTML
+  }
+}

package/dist/core/ShortcutRegistry.d.ts

@@ -0,0 +1,29 @@
+export class ShortcutRegistry {
+    /**
+     * Register a keyboard shortcut.
+     * Combo format: 'Mod+B', 'Mod+Shift+Z', 'Tab', 'Shift+Tab', 'Escape'
+     * 'Mod' maps to Cmd (Mac) / Ctrl (other).
+     *
+     * @param {string} combo — normalized combo string
+     * @param {(e: KeyboardEvent) => void} handler
+     * @param {{ scope?: 'content' | 'editor' }} [options]
+     * @returns {() => void} Unregister function
+     */
+    register(combo: string, handler: (e: KeyboardEvent) => void, options?: {
+        scope?: "content" | "editor";
+    }): () => void;
+    /**
+     * Try to handle a keyboard event. If a matching shortcut is found,
+     * calls its handler and returns true.
+     *
+     * @param {KeyboardEvent} e
+     * @param {'content' | 'editor'} [scope]
+     * @returns {boolean} Whether the event was handled
+     */
+    handle(e: KeyboardEvent, scope?: "content" | "editor"): boolean;
+    /**
+     * Remove all registered shortcuts.
+     */
+    clear(): void;
+    #private;
+}

package/dist/core/ShortcutRegistry.js

@@ -0,0 +1,106 @@
+export class ShortcutRegistry {
+  /** @type {Map<string, { handler: (e: KeyboardEvent) => void, scope: 'content' | 'editor' }>} */
+  #shortcuts = new Map()
+
+  /**
+   * Register a keyboard shortcut.
+   * Combo format: 'Mod+B', 'Mod+Shift+Z', 'Tab', 'Shift+Tab', 'Escape'
+   * 'Mod' maps to Cmd (Mac) / Ctrl (other).
+   *
+   * @param {string} combo — normalized combo string
+   * @param {(e: KeyboardEvent) => void} handler
+   * @param {{ scope?: 'content' | 'editor' }} [options]
+   * @returns {() => void} Unregister function
+   */
+  register(combo, handler, options = {}) {
+    const key = this.#normalizeCombo(combo)
+    this.#shortcuts.set(key, {
+      handler,
+      scope: options.scope ?? 'content',
+    })
+    return () => this.#shortcuts.delete(key)
+  }
+
+  /**
+   * Try to handle a keyboard event. If a matching shortcut is found,
+   * calls its handler and returns true.
+   *
+   * @param {KeyboardEvent} e
+   * @param {'content' | 'editor'} [scope]
+   * @returns {boolean} Whether the event was handled
+   */
+  handle(e, scope = 'content') {
+    const key = this.#eventToKey(e)
+    const entry = this.#shortcuts.get(key)
+
+    if (entry && (scope === 'content' || entry.scope === 'editor')) {
+      e.preventDefault()
+      entry.handler(e)
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Remove all registered shortcuts.
+   */
+  clear() {
+    this.#shortcuts.clear()
+  }
+
+  /**
+   * Normalize a combo string to a canonical form.
+   * Sorts modifier parts, lowercases the main key.
+   * 'Mod+Shift+Z' → 'mod+shift+z'
+   * @param {string} combo
+   * @returns {string}
+   */
+  #normalizeCombo(combo) {
+    const parts = combo.toLowerCase().split('+').map(p => p.trim())
+    // Separate modifiers from main key
+    const modifiers = []
+    let mainKey = ''
+
+    for (const part of parts) {
+      if (part === 'mod' || part === 'ctrl' || part === 'cmd' || part === 'meta') {
+        modifiers.push('mod')
+      } else if (part === 'shift' || part === 'alt') {
+        modifiers.push(part)
+      } else {
+        mainKey = part
+      }
+    }
+
+    // Sort modifiers for consistent key
+    modifiers.sort()
+    return [...modifiers, mainKey].join('+')
+  }
+
+  /**
+   * Convert a KeyboardEvent to the same canonical key format.
+   * Uses e.code for letter keys to be keyboard-layout-independent
+   * (e.g. Ctrl+Z works on Russian layout where e.key would be 'я').
+   * @param {KeyboardEvent} e
+   * @returns {string}
+   */
+  #eventToKey(e) {
+    const modifiers = []
+    if (e.metaKey || e.ctrlKey) modifiers.push('mod')
+    if (e.shiftKey) modifiers.push('shift')
+    if (e.altKey) modifiers.push('alt')
+    modifiers.sort()
+
+    // For letter keys, use e.code (layout-independent): 'KeyA' → 'a'
+    // For digit keys, use e.code: 'Digit1' → '1' (Shift+1 = '!' on US layout)
+    let key
+    if (e.code && e.code.startsWith('Key')) {
+      key = e.code.slice(3).toLowerCase()
+    } else if (e.code && e.code.startsWith('Digit')) {
+      key = e.code.slice(5)
+    } else {
+      key = e.key.toLowerCase()
+    }
+
+    return [...modifiers, key].join('+')
+  }
+}

package/dist/core/SlashCommands.d.ts

@@ -0,0 +1,34 @@
+export class SlashCommands {
+    /**
+     * @typedef {Object} SlashCommandsConfig
+     * @property {Map<string, import('./types.js').BlockPlugin>} plugins
+     * @property {import('./types.js').IBlockManager} blocks
+     * @property {import('./types.js').ISelectionManager} selection
+     * @property {import('./types.js').IEventBus} events
+     * @property {import('./CommandDispatcher.js').CommandDispatcher} commands
+     * @property {import('./I18n.js').I18n} i18n
+     * @property {import('./InlinePluginRegistry.js').InlinePluginRegistry} [inlinePluginRegistry]
+     * @property {import('./types.js').InlinePluginContext} [inlinePluginCtx]
+     */
+    /**
+     * @param {HTMLElement} rootEl
+     * @param {SlashCommandsConfig} config
+     */
+    constructor(rootEl: HTMLElement, config: {
+        plugins: Map<string, import("./types.js").BlockPlugin>;
+        blocks: import("./types.js").IBlockManager;
+        selection: import("./types.js").ISelectionManager;
+        events: import("./types.js").IEventBus;
+        commands: import("./CommandDispatcher.js").CommandDispatcher;
+        i18n: import("./I18n.js").I18n;
+        inlinePluginRegistry?: import("./InlinePluginRegistry.js").InlinePluginRegistry;
+        inlinePluginCtx?: import("./types.js").InlinePluginContext;
+    });
+    /** @returns {boolean} */
+    get isOpen(): boolean;
+    /** Close the slash menu. */
+    close(): void;
+    /** Clean up. */
+    destroy(): void;
+    #private;
+}