@shelamkoff/rector 1.0.0

package/dist/core/block-settings-menu/BlockActions.js

@@ -0,0 +1,233 @@
+import { EditorEvent } from '../editorEvents.js'
+import { convertCrossBlockRange, isTextType } from '../crossBlockConvert.js'
+import { splitAndConvert, isFullBlockSelected } from '../splitConvert.js'
+
+/**
+ * @typedef {Object} BlockActionsDeps
+ * @property {import('../types').IBlockManager} blocks
+ * @property {import('../types').ISelectionManager} selection
+ * @property {import('../BlockOperations').BlockOperations} blockOps
+ * @property {Map<string, import('../types').BlockPlugin>} plugins
+ * @property {import('../types').ICrossBlockSelection} crossBlockSelection
+ * @property {import('../types').IEventBus} events
+ * @property {import('../CommandDispatcher').CommandDispatcher} commands
+ * @property {string} defaultBlockType
+ * @property {(current: import('../types').IBlock, index: number) => import('../types').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 {
+  /** @type {BlockActionsDeps} */
+  #deps
+
+  /** @type {import('../CommandDispatcher').CommandDispatcher} */
+  #mutations
+
+  /** @param {BlockActionsDeps} deps */
+  constructor(deps) {
+    this.#deps = deps
+    this.#mutations = deps.commands
+  }
+
+  moveUp() {
+    const index = this.#deps.blocks.getCurrentIndex()
+    if (index <= 0) return
+    this.#deps.blocks.move(index, index - 1)
+    this.#deps.onAfterMove()
+  }
+
+  moveDown() {
+    const index = this.#deps.blocks.getCurrentIndex()
+    if (index >= this.#deps.blocks.getBlockCount() - 1) return
+    this.#deps.blocks.move(index, index + 2)
+    this.#deps.onAfterMove()
+  }
+
+  duplicate() {
+    const blocks = this.#deps.blocks
+    const index = blocks.getCurrentIndex()
+    const current = blocks.getBlockByIndex(index)
+    if (!current) return
+
+    this.#deps.duplicateBlock(current, index)
+    this.#deps.onClose()
+  }
+
+  delete() {
+    this.#deps.events.emit(EditorEvent.UNDO_BATCH_START)
+    try {
+      const blocks = this.#deps.blocks
+      const index = blocks.getCurrentIndex()
+      blocks.remove(index)
+
+      if (blocks.getBlockCount() === 0) {
+        blocks.insert(this.#deps.defaultBlockType)
+      }
+
+      const focusIdx = Math.min(index, blocks.getBlockCount() - 1)
+      blocks.setCurrentIndex(focusIdx)
+      const block = blocks.getBlockByIndex(focusIdx)
+      if (block) {
+        block.focus()
+        this.#deps.selection.setCaretToBlock(block.id, 'start')
+      }
+    } finally {
+      this.#deps.events.emit(EditorEvent.UNDO_BATCH_END)
+    }
+    this.#deps.onClose()
+  }
+
+  /**
+   * 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, data) {
+    const crossRange = this.#deps.crossBlockSelection.range
+
+    if (crossRange) {
+      convertCrossBlockRange(
+        {
+          blocks: this.#deps.blocks,
+          selection: this.#deps.selection,
+          plugins: this.#deps.plugins,
+          crossBlockSelection: this.#deps.crossBlockSelection,
+          events: this.#deps.events,
+        },
+        crossRange, type, data,
+        null,
+      )
+      this.#deps.onClose()
+      return
+    }
+
+    // Restore the saved selection so the conversion happens against
+    // the user's actual caret/range, not the menu focus.
+    const savedRange = this.#deps.getSavedRange()
+    if (savedRange) {
+      const sel = window.getSelection()
+      if (sel) {
+        try { sel.removeAllRanges(); sel.addRange(savedRange) } catch { /* detached DOM */ }
+      }
+    }
+
+    const blocks = this.#deps.blocks
+    const index = blocks.getCurrentIndex()
+    const current = blocks.getBlockByIndex(index)
+    if (!current) { this.#deps.onClose(); return }
+
+    if (type === current.type && !data) { this.#deps.onClose(); return }
+
+    const sel = window.getSelection()
+    if (!sel || sel.rangeCount === 0) {
+      // No selection — full block convert.
+      const converted = blocks.convert(index, type, data)
+      if (converted) {
+        blocks.setCurrentIndex(index)
+        this.#deps.selection.setCaretToBlock(converted.id, 'end')
+        converted.focus()
+      }
+      this.#deps.onClose()
+      return
+    }
+
+    const range = sel.getRangeAt(0)
+    const contentEl = current.contentElement
+    const isFullBlock = sel.isCollapsed || isFullBlockSelected(contentEl, range)
+
+    this.#deps.events.emit(EditorEvent.UNDO_BATCH_START)
+    try {
+      if (isFullBlock) {
+        const converted = blocks.convert(index, type, data)
+        if (converted) {
+          blocks.setCurrentIndex(index)
+          this.#deps.selection.setCaretToBlock(converted.id, 'start')
+          converted.focus()
+        }
+      } else {
+        splitAndConvert(
+          blocks,
+          this.#deps.selection,
+          index,
+          current.type,
+          contentEl,
+          range,
+          type,
+          data,
+          isTextType(this.#deps.plugins, type),
+        )
+      }
+    } finally {
+      this.#deps.events.emit(EditorEvent.UNDO_BATCH_END)
+    }
+    this.#deps.onClose()
+  }
+
+  /**
+   * 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').IBlock} current
+   * @param {import('../types').BlockPlugin} plugin
+   * @param {HTMLElement} item
+   */
+  handleSettingsAction(current, plugin, item) {
+    const action = item.dataset.level || item.dataset.action || ''
+
+    // Special case: Heading has changeLevel() for in-place updates.
+    if (plugin.changeLevel && action) {
+      const level = parseInt(action, 10)
+      if (level) {
+        this.#mutations.runForBlock(current, () => {
+          const newEl = plugin.changeLevel(current.contentElement, level)
+          if (newEl !== current.contentElement) {
+            current.replaceContentElement(newEl)
+          }
+        })
+        this.#deps.onClose()
+        // Restore focus to the (possibly new) content element — closing
+        // the settings menu shifts focus away, and changeLevel's internal
+        // selection restore runs before the close.
+        current.contentElement.focus()
+        return
+      }
+    }
+
+    // Fallback: re-render via convert.
+    if (plugin.onSettingsAction) {
+      this.#mutations.runForBlock(current, () => {
+        const newData = plugin.onSettingsAction(current.contentElement, action)
+        if (newData) {
+          const index = this.#deps.blocks.getCurrentIndex()
+          const converted = this.#deps.blocks.convert(index, current.type, newData)
+          if (converted) {
+            this.#deps.blocks.setCurrentIndex(index)
+            this.#deps.selection.setCaretToBlock(converted.id, 'end')
+            converted.focus()
+          }
+        }
+      })
+    }
+    this.#deps.onClose()
+  }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * The drill-down menu shown next to a block: move/duplicate/convert/delete
+ * plus any plugin-specific settings (heading levels, table operations, etc.).
+ *
+ * Coordinates three collaborators:
+ *  - `MenuBuilder`     — DOM construction (main view + convert view + items)
+ *  - `BlockActions`    — block-mutating operations
+ *  - `MenuPositioner`  — desktop/mobile placement
+ *
+ * The menu itself owns lifecycle (open/close/destroy), the saved selection
+ * range, and the keyboard navigation handler. The native selection range
+ * gets snapshotted on open and restored on close so the user's caret
+ * survives the menu's focus shift.
+ */
+export class BlockSettingsMenu {
+    /**
+     * @param {HTMLElement} rootEl
+     * @param {import('../types.js').IBlockManager} blocks
+     * @param {import('../types.js').ISelectionManager} selection
+     * @param {Map<string, import('../types.js').BlockPlugin>} plugins
+     * @param {import('../I18n.js').I18n} i18n
+     * @param {import('../types.js').IEventBus} events
+     * @param {import('../types.js').ICrossBlockSelection} crossBlockSelection
+     * @param {import('../BlockOperations.js').BlockOperations} blockOps
+     * @param {string} defaultBlockType
+     * @param {(current: import('../types.js').IBlock, index: number) => import('../types.js').IBlock | undefined} duplicateBlock
+     * @param {import('../CommandDispatcher.js').CommandDispatcher} commands
+     * @param {{ mobileBreakpoint?: number }} [tuning]
+     */
+    constructor(rootEl: HTMLElement, blocks: import("../types.js").IBlockManager, selection: import("../types.js").ISelectionManager, plugins: Map<string, import("../types.js").BlockPlugin>, i18n: import("../I18n.js").I18n, events: import("../types.js").IEventBus, crossBlockSelection: import("../types.js").ICrossBlockSelection, blockOps: import("../BlockOperations.js").BlockOperations, defaultBlockType: string, duplicateBlock: (current: import("../types.js").IBlock, index: number) => import("../types.js").IBlock | undefined, commands: import("../CommandDispatcher.js").CommandDispatcher, tuning?: {
+        mobileBreakpoint?: number;
+    });
+    /** @returns {boolean} */
+    get isOpen(): boolean;
+    /** @returns {HTMLElement} */
+    get menuEl(): HTMLElement;
+    /** @param {() => void} cb */
+    set onClose(cb: () => void);
+    toggle(): void;
+    /** @param {{ restoreSelection?: boolean }} [options] */
+    close(options?: {
+        restoreSelection?: boolean;
+    }): void;
+    destroy(): void;
+    #private;
+}

package/dist/core/block-settings-menu/BlockSettingsMenu.js

@@ -0,0 +1,205 @@
+import { el } from '../dom.js'
+import { CrossBlockSelection } from '../CrossBlockSelection.js'
+import { handleMenuKeydown } from '../menuKeyboardNav.js'
+import { restoreSelection } from '../splitConvert.js'
+import { BlockActions } from './BlockActions.js'
+import { MenuBuilder } from './MenuBuilder.js'
+import { MenuPositioner } from './MenuPositioner.js'
+
+/**
+ * The drill-down menu shown next to a block: move/duplicate/convert/delete
+ * plus any plugin-specific settings (heading levels, table operations, etc.).
+ *
+ * Coordinates three collaborators:
+ *  - `MenuBuilder`     — DOM construction (main view + convert view + items)
+ *  - `BlockActions`    — block-mutating operations
+ *  - `MenuPositioner`  — desktop/mobile placement
+ *
+ * The menu itself owns lifecycle (open/close/destroy), the saved selection
+ * range, and the keyboard navigation handler. The native selection range
+ * gets snapshotted on open and restored on close so the user's caret
+ * survives the menu's focus shift.
+ */
+export class BlockSettingsMenu {
+  /** @type {HTMLElement} */
+  #rootEl
+
+  /** @type {import('../types').ICrossBlockSelection} */
+  #crossBlockSelection
+
+  /** @type {HTMLElement} */
+  #menuEl
+
+  /** @type {boolean} */
+  #open = false
+
+  /** @type {(() => void) | null} */
+  #onCloseCallback = null
+
+  /** @type {Range | null} */
+  #savedRange = null
+
+  /** @type {MenuBuilder} */
+  #builder
+
+  /** @type {BlockActions} */
+  #actions
+
+  /** @type {MenuPositioner} */
+  #positioner
+
+  /**
+   * @param {HTMLElement} rootEl
+   * @param {import('../types').IBlockManager} blocks
+   * @param {import('../types').ISelectionManager} selection
+   * @param {Map<string, import('../types').BlockPlugin>} plugins
+   * @param {import('../I18n').I18n} i18n
+   * @param {import('../types').IEventBus} events
+   * @param {import('../types').ICrossBlockSelection} crossBlockSelection
+   * @param {import('../BlockOperations').BlockOperations} blockOps
+   * @param {string} defaultBlockType
+   * @param {(current: import('../types').IBlock, index: number) => import('../types').IBlock | undefined} duplicateBlock
+   * @param {import('../CommandDispatcher').CommandDispatcher} commands
+   * @param {{ mobileBreakpoint?: number }} [tuning]
+   */
+  constructor(rootEl, blocks, selection, plugins, i18n, events, crossBlockSelection, blockOps, defaultBlockType, duplicateBlock, commands, tuning) {
+    this.#rootEl = rootEl
+    this.#crossBlockSelection = crossBlockSelection
+
+    this.#menuEl = el('ul', 'oe-settings-menu', { role: 'menu', tabindex: '-1' })
+    this.#menuEl.style.display = 'none'
+    this.#menuEl.addEventListener('keydown', this.#onMenuKeydown)
+    // Prevent mousedown from propagating to the editor root — otherwise the
+    // editor's onMouseDown handler clears the cross-block selection.
+    this.#menuEl.addEventListener('mousedown', (e) => e.stopPropagation())
+    rootEl.appendChild(this.#menuEl)
+
+    document.addEventListener('click', this.#onDocumentClick, true)
+
+    this.#actions = new BlockActions({
+      blocks, selection, blockOps, plugins, crossBlockSelection, events, commands,
+      defaultBlockType, duplicateBlock,
+      // Every terminal action positions focus/caret itself. Restoring the
+      // range captured before the menu opened would either move focus back to
+      // the source block (duplicate) or target detached DOM (delete/convert).
+      onClose: () => this.close({ restoreSelection: false }),
+      onAfterMove: () => this.#refreshAfterMove(),
+      getSavedRange: () => this.#savedRange,
+    })
+
+    this.#builder = new MenuBuilder(this.#menuEl, {
+      blocks, plugins, i18n,
+      actions: this.#actions,
+      rebuildMain: (direction) => this.#builder.buildMainView(direction),
+    })
+
+    this.#positioner = new MenuPositioner(this.#menuEl, rootEl, tuning?.mobileBreakpoint ?? 768)
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /** @returns {boolean} */
+  get isOpen() {
+    return this.#open
+  }
+
+  /** @returns {HTMLElement} */
+  get menuEl() {
+    return this.#menuEl
+  }
+
+  /** @param {() => void} cb */
+  set onClose(cb) {
+    this.#onCloseCallback = cb
+  }
+
+  toggle() {
+    if (this.#open) this.close()
+    else this.#show()
+  }
+
+  /** @param {{ restoreSelection?: boolean }} [options] */
+  close(options = {}) {
+    if (!this.#open) return
+    const restore = options.restoreSelection ?? true
+    this.#open = false
+    this.#menuEl.style.display = 'none'
+    CrossBlockSelection.hideHighlight()
+    if (restore) this.#restoreSelection()
+    this.#savedRange = null
+    this.#onCloseCallback?.()
+  }
+
+  destroy() {
+    document.removeEventListener('click', this.#onDocumentClick, true)
+    this.#menuEl.removeEventListener('keydown', this.#onMenuKeydown)
+    this.#menuEl.remove()
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  #show() {
+    this.#open = true
+
+    // Snapshot the live selection so we can restore it after the menu closes.
+    const sel = window.getSelection()
+    if (sel && sel.rangeCount > 0) {
+      this.#savedRange = sel.getRangeAt(0).cloneRange()
+    }
+    if (this.#crossBlockSelection.range) {
+      this.#savedRange = this.#crossBlockSelection.clone()
+    }
+
+    // Use the CSS Highlight API so the selection stays visible while focus
+    // is in the menu (otherwise contenteditable loses its visual highlight).
+    if (this.#savedRange && !this.#savedRange.collapsed) {
+      CrossBlockSelection.showHighlight(this.#savedRange)
+    }
+
+    this.#builder.buildMainView()
+    this.#menuEl.style.display = ''
+    this.#positioner.position()
+
+    // Focus the menu container for keyboard nav, but not individual items
+    // (avoids a focus-visible highlight when opened by mouse click).
+    requestAnimationFrame(() => {
+      if (this.#open) this.#menuEl.focus()
+    })
+  }
+
+  /** Rebuild items + reposition after a move (keep menu open). */
+  #refreshAfterMove() {
+    this.#builder.buildMainView('none')
+    this.#positioner.position()
+  }
+
+  #restoreSelection() {
+    restoreSelection(this.#savedRange, this.#crossBlockSelection)
+  }
+
+  /** @param {KeyboardEvent} e */
+  #onMenuKeydown = (e) => {
+    handleMenuKeydown(e, this.#menuEl, {
+      onEscape: () => this.close(),
+    })
+  }
+
+  #onDocumentClick = (/** @type {MouseEvent} */ e) => {
+    if (!this.#open) return
+    const target = e.target
+    if (!(target instanceof globalThis.Node)) return
+    const targetNode = /** @type {import('../types').DOMNode} */ (target)
+    if (this.#menuEl.contains(targetNode)) return
+
+    // Ignore clicks on the toolbar (drag handle has its own toggle path).
+    const toolbar = this.#rootEl.querySelector('.oe-toolbar')
+    if (toolbar?.contains(targetNode)) return
+
+    // On mobile the backdrop handles closing via Toolbar.
+    const backdrop = this.#rootEl.closest('.oe-editor')?.parentElement?.querySelector('.oe-offcanvas-backdrop')
+      ?? document.querySelector('.oe-offcanvas-backdrop')
+    if (backdrop?.contains(targetNode)) return
+
+    this.close()
+  }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * @typedef {Object} MenuBuilderDeps
+ * @property {import('../types.js').IBlockManager} blocks
+ * @property {Map<string, import('../types.js').BlockPlugin>} plugins
+ * @property {import('../I18n.js').I18n} i18n
+ * @property {import('./BlockActions.js').BlockActions} actions
+ * @property {(direction?: 'forward' | 'back' | 'none') => void} rebuildMain
+ *   Used by the convert-view back button to redraw the main view.
+ */
+/**
+ * Builds the contents of the block settings menu.
+ *
+ * Two views:
+ *  - Main view: move up/down, plugin settings (e.g. heading levels),
+ *    duplicate, convert-to (drill-down), delete.
+ *  - Convert view: list of all block types, with the current one marked active.
+ *
+ * Drill-down direction is conveyed via two CSS classes
+ * (`oe-settings-menu--forward`/`--back`) so the menu can animate.
+ */
+export class MenuBuilder {
+    /**
+     * @param {HTMLElement} menuEl
+     * @param {MenuBuilderDeps} deps
+     */
+    constructor(menuEl: HTMLElement, deps: MenuBuilderDeps);
+    /**
+     * @param {'forward' | 'back' | 'none'} [direction]
+     */
+    buildMainView(direction?: "forward" | "back" | "none"): void;
+    buildConvertView(): void;
+    #private;
+}
+export type MenuBuilderDeps = {
+    blocks: import("../types.js").IBlockManager;
+    plugins: Map<string, import("../types.js").BlockPlugin>;
+    i18n: import("../I18n.js").I18n;
+    actions: import("./BlockActions.js").BlockActions;
+    /**
+     *   Used by the convert-view back button to redraw the main view.
+     */
+    rebuildMain: (direction?: "forward" | "back" | "none") => void;
+};