@shelamkoff/rector 1.0.0

package/dist/core/config.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Merge user-supplied tuning overrides onto defaults.
+ * Shallow per-group (one level deep) — each group is an object with primitive leaves.
+ *
+ * @param {import('./types.js').EditorConfig['tuning']} [overrides]
+ * @returns {EditorTuning}
+ */
+export function resolveTuning(overrides?: import("./types.js").EditorConfig["tuning"]): EditorTuning;
+/**
+ * Default behavioral tuning for the editor.
+ *
+ * Pass overrides through the `tuning` property of `createEditor()`.
+ * These are UX/behavior defaults, not performance tuning — the name `tuning`
+ * reflects that.
+ *
+ * @typedef {Object} EditorTuning
+ * @property {{ threshold: number }} drag
+ *   Drag-and-drop — minimum pixel movement before a mousedown becomes a drag.
+ * @property {{ maxStack: number, debounceMs: number }} undo
+ *   Undo stack — max history depth and coalescing debounce.
+ * @property {{ debounceMs: number }} change
+ *   `onChange` coalescing window for ChangeNotifier.
+ * @property {{ filterThreshold: number }} toolbar
+ *   TypeSelector search — minimum plugin count before filter input appears.
+ * @property {{ blockInsertMs: number, blockMoveMs: number, blockRemoveMs: number }} animations
+ *   Block insert/move/remove animation durations.
+ * @property {number} mobileBreakpoint
+ *   Width below which the UI switches to mobile layout (matches CSS media queries).
+ */
+/** @type {EditorTuning} */
+export const DEFAULT_TUNING: EditorTuning;
+/**
+ * Default behavioral tuning for the editor.
+ *
+ * Pass overrides through the `tuning` property of `createEditor()`.
+ * These are UX/behavior defaults, not performance tuning — the name `tuning`
+ * reflects that.
+ */
+export type EditorTuning = {
+    /**
+     *   Drag-and-drop — minimum pixel movement before a mousedown becomes a drag.
+     */
+    drag: {
+        threshold: number;
+    };
+    /**
+     *   Undo stack — max history depth and coalescing debounce.
+     */
+    undo: {
+        maxStack: number;
+        debounceMs: number;
+    };
+    /**
+     *   `onChange` coalescing window for ChangeNotifier.
+     */
+    change: {
+        debounceMs: number;
+    };
+    /**
+     *   TypeSelector search — minimum plugin count before filter input appears.
+     */
+    toolbar: {
+        filterThreshold: number;
+    };
+    /**
+     *   Block insert/move/remove animation durations.
+     */
+    animations: {
+        blockInsertMs: number;
+        blockMoveMs: number;
+        blockRemoveMs: number;
+    };
+    /**
+     *   Width below which the UI switches to mobile layout (matches CSS media queries).
+     */
+    mobileBreakpoint: number;
+};

package/dist/core/config.js

@@ -0,0 +1,100 @@
+/**
+ * Default behavioral tuning for the editor.
+ *
+ * Pass overrides through the `tuning` property of `createEditor()`.
+ * These are UX/behavior defaults, not performance tuning — the name `tuning`
+ * reflects that.
+ *
+ * @typedef {Object} EditorTuning
+ * @property {{ threshold: number }} drag
+ *   Drag-and-drop — minimum pixel movement before a mousedown becomes a drag.
+ * @property {{ maxStack: number, debounceMs: number }} undo
+ *   Undo stack — max history depth and coalescing debounce.
+ * @property {{ debounceMs: number }} change
+ *   `onChange` coalescing window for ChangeNotifier.
+ * @property {{ filterThreshold: number }} toolbar
+ *   TypeSelector search — minimum plugin count before filter input appears.
+ * @property {{ blockInsertMs: number, blockMoveMs: number, blockRemoveMs: number }} animations
+ *   Block insert/move/remove animation durations.
+ * @property {number} mobileBreakpoint
+ *   Width below which the UI switches to mobile layout (matches CSS media queries).
+ */
+
+/** @type {EditorTuning} */
+export const DEFAULT_TUNING = {
+  drag: { threshold: 5 },
+  undo: { maxStack: 100, debounceMs: 300 },
+  change: { debounceMs: 250 },
+  toolbar: { filterThreshold: 7 },
+  animations: { blockInsertMs: 350, blockMoveMs: 200, blockRemoveMs: 350 },
+  mobileBreakpoint: 768,
+}
+
+/**
+ * Validate a numeric tuning value.
+ * @param {number} value Candidate value.
+ * @param {string} path Property path used in validation error messages.
+ * @param {{ integer?: boolean, min?: number }} [rules] Numeric constraints.
+ * @returns {void}
+ */
+function validateNumber(value, path, rules = {}) {
+  const min = rules.min ?? 0
+  if (
+    typeof value !== 'number'
+    || !Number.isFinite(value)
+    || value < min
+    || (rules.integer && !Number.isInteger(value))
+  ) {
+    const kind = rules.integer ? 'an integer' : 'a finite number'
+    throw new RangeError(`${path} must be ${kind} greater than or equal to ${min}`)
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @returns {Record<string, unknown>}
+ */
+function validateGroup(value, path) {
+  if (Object.prototype.toString.call(value) !== '[object Object]') {
+    throw new TypeError(`${path} must be an object`)
+  }
+  return /** @type {Record<string, unknown>} */ (value)
+}
+
+/**
+ * Merge user-supplied tuning overrides onto defaults.
+ * Shallow per-group (one level deep) — each group is an object with primitive leaves.
+ *
+ * @param {import('./types').EditorConfig['tuning']} [overrides]
+ * @returns {EditorTuning}
+ */
+export function resolveTuning(overrides) {
+  const supplied = /** @type {Partial<EditorTuning>} */ (
+    overrides === undefined ? {} : validateGroup(overrides, 'tuning')
+  )
+  const drag = supplied.drag === undefined ? {} : validateGroup(supplied.drag, 'tuning.drag')
+  const undo = supplied.undo === undefined ? {} : validateGroup(supplied.undo, 'tuning.undo')
+  const change = supplied.change === undefined ? {} : validateGroup(supplied.change, 'tuning.change')
+  const toolbar = supplied.toolbar === undefined ? {} : validateGroup(supplied.toolbar, 'tuning.toolbar')
+  const animations = supplied.animations === undefined ? {} : validateGroup(supplied.animations, 'tuning.animations')
+  const resolved = {
+    drag: { ...DEFAULT_TUNING.drag, ...drag },
+    undo: { ...DEFAULT_TUNING.undo, ...undo },
+    change: { ...DEFAULT_TUNING.change, ...change },
+    toolbar: { ...DEFAULT_TUNING.toolbar, ...toolbar },
+    animations: { ...DEFAULT_TUNING.animations, ...animations },
+    mobileBreakpoint: supplied.mobileBreakpoint ?? DEFAULT_TUNING.mobileBreakpoint,
+  }
+
+  validateNumber(resolved.drag.threshold, 'tuning.drag.threshold')
+  validateNumber(resolved.undo.maxStack, 'tuning.undo.maxStack', { integer: true, min: 1 })
+  validateNumber(resolved.undo.debounceMs, 'tuning.undo.debounceMs')
+  validateNumber(resolved.change.debounceMs, 'tuning.change.debounceMs')
+  validateNumber(resolved.toolbar.filterThreshold, 'tuning.toolbar.filterThreshold', { integer: true })
+  validateNumber(resolved.animations.blockInsertMs, 'tuning.animations.blockInsertMs')
+  validateNumber(resolved.animations.blockMoveMs, 'tuning.animations.blockMoveMs')
+  validateNumber(resolved.animations.blockRemoveMs, 'tuning.animations.blockRemoveMs')
+  validateNumber(resolved.mobileBreakpoint, 'tuning.mobileBreakpoint')
+  return resolved
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,23 @@
+/** Default block type used when no explicit default is configured. */
+export const DEFAULT_BLOCK_TYPE: "paragraph";
+export const DEFAULT_THEME: "dark";
+/** CSS class applied to every block wrapper element. */
+export const BLOCK_CLASS: "oe-block";
+/** CSS selector for block wrapper elements (`.oe-block`). */
+export const BLOCK_SELECTOR: ".oe-block";
+/**
+ * Opt-in attribute for controls that remain usable in read-only mode because
+ * they only change transient presentation and never mutate document data or
+ * invoke application side effects.
+ */
+export const READ_ONLY_INTERACTIVE_ATTRIBUTE: "data-oe-read-only-interactive";
+/**
+ * Internal marker used by the alignment tool and Block serializer. The value
+ * mirrors the canonical `tunes.textAlign` setting; an empty value explicitly
+ * removes that setting.
+ */
+export const TEXT_ALIGN_TUNE_ATTRIBUTE: "data-oe-text-align-tune";
+/** Editor document format version — shared by EditorFacade.save() and UndoManager. */
+export const EDITOR_VERSION: "1.0.0";
+/** Duration of the offcanvas slide/backdrop-fade animation (ms). */
+export const OFFCANVAS_ANIMATION_MS: 250;

package/dist/core/constants.js

@@ -0,0 +1,30 @@
+/** Default block type used when no explicit default is configured. */
+export const DEFAULT_BLOCK_TYPE = 'paragraph'
+
+export const DEFAULT_THEME = 'dark'
+
+/** CSS class applied to every block wrapper element. */
+export const BLOCK_CLASS = 'oe-block'
+
+/** CSS selector for block wrapper elements (`.oe-block`). */
+export const BLOCK_SELECTOR = '.oe-block'
+
+/**
+ * Opt-in attribute for controls that remain usable in read-only mode because
+ * they only change transient presentation and never mutate document data or
+ * invoke application side effects.
+ */
+export const READ_ONLY_INTERACTIVE_ATTRIBUTE = 'data-oe-read-only-interactive'
+
+/**
+ * Internal marker used by the alignment tool and Block serializer. The value
+ * mirrors the canonical `tunes.textAlign` setting; an empty value explicitly
+ * removes that setting.
+ */
+export const TEXT_ALIGN_TUNE_ATTRIBUTE = 'data-oe-text-align-tune'
+
+/** Editor document format version — shared by EditorFacade.save() and UndoManager. */
+export const EDITOR_VERSION = '1.0.0'
+
+/** Duration of the offcanvas slide/backdrop-fade animation (ms). */
+export const OFFCANVAS_ANIMATION_MS = 250

package/dist/core/crossBlockConvert.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-block conversion shared by the inline type selector and the block
+ * settings menu. Endpoint analysis is completed before any command runs, so
+ * an unsupported structured selection is a safe no-op.
+ */
+/**
+ * Check whether a block accepts neutral rich text during conversion.
+ * `isTextBlock` does not imply that the plugin root is contenteditable; list
+ * and checklist plugins are structured text targets as well.
+ * @param {Map<string, import('./types.js').BlockPlugin>} plugins
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isTextType(plugins: Map<string, import("./types.js").BlockPlugin>, type: string): boolean;
+/**
+ * Convert a cross-block selection. A text target receives one converted block
+ * per selected source block. A non-text target replaces the selected interval
+ * with one block. Unselected endpoint data always stays in its source type.
+ *
+ * @param {object} ctx
+ * @param {import('./types.js').IBlockManager} ctx.blocks
+ * @param {import('./types.js').ISelectionManager} ctx.selection
+ * @param {Map<string, import('./types.js').BlockPlugin>} ctx.plugins
+ * @param {import('./types.js').ICrossBlockSelection} [ctx.crossBlockSelection]
+ * @param {import('./types.js').IEventBus} [ctx.events]
+ * @param {Range} crossRange
+ * @param {string} targetType
+ * @param {Record<string, unknown>} [targetData]
+ * @param {(() => void) | null} [onDone]
+ * @returns {boolean} whether the document was changed
+ */
+export function convertCrossBlockRange(ctx: {
+    blocks: import("./types.js").IBlockManager;
+    selection: import("./types.js").ISelectionManager;
+    plugins: Map<string, import("./types.js").BlockPlugin>;
+    crossBlockSelection?: import("./types.js").ICrossBlockSelection;
+    events?: import("./types.js").IEventBus;
+}, crossRange: Range, targetType: string, targetData?: Record<string, unknown>, onDone?: (() => void) | null): boolean;

package/dist/core/crossBlockConvert.js

@@ -0,0 +1,253 @@
+import { closestBlock } from './dom.js'
+import { EditorEvent } from './editorEvents.js'
+import { rangeStartsAtBeginning, rangeEndsAtEnd } from './splitConvert.js'
+
+/**
+ * Cross-block conversion shared by the inline type selector and the block
+ * settings menu. Endpoint analysis is completed before any command runs, so
+ * an unsupported structured selection is a safe no-op.
+ */
+
+/**
+ * Check whether a block accepts neutral rich text during conversion.
+ * `isTextBlock` does not imply that the plugin root is contenteditable; list
+ * and checklist plugins are structured text targets as well.
+ * @param {Map<string, import('./types').BlockPlugin>} plugins
+ * @param {string} type
+ * @returns {boolean}
+ */
+export function isTextType(plugins, type) {
+  const plugin = plugins.get(type)
+  if (!plugin) return false
+  const ctor = /** @type {import('./types').BlockPluginConstructor} */ (plugin.constructor)
+  return ctor?.isTextBlock === true
+}
+
+/** @param {Range} range @returns {string} */
+function rangeHtml(range) {
+  const container = document.createElement('div')
+  container.appendChild(range.cloneContents())
+  return container.innerHTML
+}
+
+/** @param {string} html @returns {boolean} */
+function hasTransferableContent(html) {
+  const container = document.createElement('div')
+  container.innerHTML = html
+  if ((container.textContent || '').replace(/\u00a0/g, ' ').trim()) return true
+  return !!container.querySelector('img, video, audio, iframe, [data-inline-plugin]')
+}
+
+/**
+ * Describe one partially selected endpoint without mutating plugin DOM.
+ * Structured plugins own their data boundaries through `splitSelection()`;
+ * the generic path is intentionally limited to a single editable root whose
+ * serialized representation is `{ text }`.
+ *
+ * @param {import('./types').IBlock} block
+ * @param {Range} range
+ * @param {'first' | 'last'} side
+ * @returns {{ remainingData: Record<string, unknown> | null, selectedData: Record<string, unknown> } | null}
+ */
+function analyzePartialEndpoint(block, range, side) {
+  const content = block.contentElement
+  const pluginSplit = block.plugin.splitSelection?.(content, range)
+  if (pluginSplit) {
+    if (!pluginSplit.selectedData || typeof pluginSplit.selectedData !== 'object' || Array.isArray(pluginSplit.selectedData)) {
+      return null
+    }
+    if (pluginSplit.remainingData !== null && (
+      typeof pluginSplit.remainingData !== 'object' || Array.isArray(pluginSplit.remainingData)
+    )) return null
+    return pluginSplit
+  }
+
+  if (content.getAttribute('contenteditable') !== 'true') return null
+
+  try {
+    const selectedRange = document.createRange()
+    selectedRange.selectNodeContents(content)
+    const remainingRange = document.createRange()
+    remainingRange.selectNodeContents(content)
+
+    if (side === 'first') {
+      selectedRange.setStart(range.startContainer, range.startOffset)
+      remainingRange.setEnd(range.startContainer, range.startOffset)
+    } else {
+      selectedRange.setEnd(range.endContainer, range.endOffset)
+      remainingRange.setStart(range.endContainer, range.endOffset)
+    }
+
+    const selectedHtml = rangeHtml(selectedRange)
+    if (!hasTransferableContent(selectedHtml)) return null
+    const remainingHtml = rangeHtml(remainingRange)
+    return {
+      selectedData: { text: selectedHtml },
+      remainingData: hasTransferableContent(remainingHtml) ? { text: remainingHtml } : null,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Convert a cross-block selection. A text target receives one converted block
+ * per selected source block. A non-text target replaces the selected interval
+ * with one block. Unselected endpoint data always stays in its source type.
+ *
+ * @param {object} ctx
+ * @param {import('./types').IBlockManager} ctx.blocks
+ * @param {import('./types').ISelectionManager} ctx.selection
+ * @param {Map<string, import('./types').BlockPlugin>} ctx.plugins
+ * @param {import('./types').ICrossBlockSelection} [ctx.crossBlockSelection]
+ * @param {import('./types').IEventBus} [ctx.events]
+ * @param {Range} crossRange
+ * @param {string} targetType
+ * @param {Record<string, unknown>} [targetData]
+ * @param {(() => void) | null} [onDone]
+ * @returns {boolean} whether the document was changed
+ */
+export function convertCrossBlockRange(ctx, crossRange, targetType, targetData, onDone) {
+  const { blocks, selection, plugins, crossBlockSelection, events } = ctx
+
+  const startBlockEl = closestBlock(/** @type {import('./types').DOMNode} */ (crossRange.startContainer))
+  const endBlockEl = closestBlock(/** @type {import('./types').DOMNode} */ (crossRange.endContainer))
+  if (!startBlockEl || !endBlockEl) return false
+
+  const startId = startBlockEl.dataset.blockId
+  const endId = endBlockEl.dataset.blockId
+  if (!startId || !endId) return false
+  const firstIdx = blocks.getBlockIndex(startId)
+  const lastIdx = blocks.getBlockIndex(endId)
+  if (firstIdx < 0 || lastIdx <= firstIdx) return false
+
+  const firstBlock = blocks.getBlockByIndex(firstIdx)
+  const lastBlock = blocks.getBlockByIndex(lastIdx)
+  if (!firstBlock || !lastBlock || !plugins.has(targetType)) return false
+
+  const firstFull = rangeStartsAtBeginning(firstBlock.contentElement, crossRange)
+  const lastFull = rangeEndsAtEnd(lastBlock.contentElement, crossRange)
+  const firstSplit = firstFull ? null : analyzePartialEndpoint(firstBlock, crossRange, 'first')
+  const lastSplit = lastFull ? null : analyzePartialEndpoint(lastBlock, crossRange, 'last')
+
+  // Do not start a batch or mutate any block until both endpoint contracts are
+  // known to be representable. This prevents partial corruption when only one
+  // structured plugin supports data-level splitting.
+  if ((!firstFull && !firstSplit) || (!lastFull && !lastSplit)) return false
+
+  const targetIsText = isTextType(plugins, targetType)
+  /** @type {import('./types').IBlock[]} */
+  const convertedBlocks = []
+  /** @type {import('./types').IBlock | null} */
+  let focusBlock = null
+  const recordConverted = (block) => {
+    if (block && !convertedBlocks.includes(block)) convertedBlocks.push(block)
+    return block
+  }
+
+  events?.emit(EditorEvent.UNDO_BATCH_START)
+  try {
+    if (targetIsText) {
+      // Process from the end so inserted endpoint remainders do not invalidate
+      // the model indices of earlier selected blocks.
+      if (lastSplit) {
+        const converted = blocks.convert(lastIdx, targetType, {
+          ...lastSplit.selectedData,
+          ...(targetData || {}),
+        })
+        if (converted) focusBlock = recordConverted(converted)
+        if (lastSplit.remainingData) blocks.insert(lastBlock.type, lastSplit.remainingData, lastIdx + 1)
+      } else {
+        const converted = blocks.convert(lastIdx, targetType, targetData)
+        if (converted) focusBlock = recordConverted(converted)
+      }
+
+      for (let index = lastIdx - 1; index > firstIdx; index--) {
+        const block = blocks.getBlockByIndex(index)
+        if (!block) continue
+        if (block.type === targetType) {
+          focusBlock = recordConverted(block)
+          continue
+        }
+        const converted = blocks.convert(index, targetType, targetData)
+        if (converted) focusBlock = recordConverted(converted)
+      }
+
+      if (firstSplit) {
+        if (firstSplit.remainingData) {
+          // Re-render the source from its plugin-owned remaining data. This is
+          // safer than rewriting structured DOM and keeps lifecycle ownership.
+          blocks.convert(firstIdx, firstBlock.type, firstSplit.remainingData)
+          focusBlock = recordConverted(blocks.insert(targetType, {
+            ...firstSplit.selectedData,
+            ...(targetData || {}),
+          }, firstIdx + 1))
+        } else {
+          const converted = blocks.convert(firstIdx, targetType, {
+            ...firstSplit.selectedData,
+            ...(targetData || {}),
+          })
+          if (converted) focusBlock = recordConverted(converted)
+        }
+      } else {
+        const converted = blocks.convert(firstIdx, targetType, targetData)
+        if (converted) focusBlock = recordConverted(converted)
+      }
+    } else {
+      // Keep only unselected endpoint data, remove every fully selected block,
+      // then place one non-text target between the surviving endpoint blocks.
+      if (lastSplit?.remainingData) {
+        blocks.convert(lastIdx, lastBlock.type, lastSplit.remainingData)
+      } else {
+        blocks.remove(lastIdx)
+      }
+
+      for (let index = lastIdx - 1; index > firstIdx; index--) blocks.remove(index)
+
+      let insertAt = firstIdx
+      if (firstSplit?.remainingData) {
+        blocks.convert(firstIdx, firstBlock.type, firstSplit.remainingData)
+        insertAt++
+      } else {
+        blocks.remove(firstIdx)
+      }
+
+      focusBlock = blocks.insert(targetType, /** @type {Record<string, unknown>} */ (targetData || {}), insertAt)
+    }
+
+    const liveConverted = convertedBlocks
+      .filter(block => blocks.getBlockById(block.id) === block)
+      .sort((a, b) => blocks.getBlockIndex(a.id) - blocks.getBlockIndex(b.id))
+    const newFirstBlock = liveConverted[0]
+    const newLastBlock = liveConverted[liveConverted.length - 1]
+
+    if (targetIsText && newFirstBlock && newLastBlock && newFirstBlock !== newLastBlock) {
+      try {
+        const newRange = document.createRange()
+        newRange.selectNodeContents(newFirstBlock.contentElement)
+        newRange.setEnd(newLastBlock.contentElement, newLastBlock.contentElement.childNodes.length)
+        const editor = /** @type {HTMLElement | null} */ (newFirstBlock.contentElement.closest('.oe-editor'))
+        if (crossBlockSelection && editor) crossBlockSelection.activate(newRange, editor)
+      } catch { /* focus fallback below */ }
+
+      const newLastIndex = blocks.getBlockIndex(newLastBlock.id)
+      if (newLastIndex >= 0) blocks.setCurrentIndex(newLastIndex)
+      newLastBlock.focus()
+      selection.setCaretToBlock(newLastBlock.id, 'end')
+    } else {
+      const editor = /** @type {HTMLElement | null} */ (startBlockEl.closest('.oe-editor'))
+      crossBlockSelection?.deactivate(editor ?? undefined)
+      if (focusBlock) {
+        const focusIndex = blocks.getBlockIndex(focusBlock.id)
+        if (focusIndex >= 0) blocks.setCurrentIndex(focusIndex)
+        selection.setCaretToBlock(focusBlock.id, 'start')
+        focusBlock.focus()
+      }
+    }
+
+    onDone?.()
+    return true
+  } finally {
+    events?.emit(EditorEvent.UNDO_BATCH_END)
+  }
+}

package/dist/core/dom.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Create an element with optional class name and attributes.
+ * @param {string} tag
+ * @param {string} [className]
+ * @param {Record<string, string>} [attrs]
+ * @returns {HTMLElement}
+ */
+export function el(tag: string, className?: string, attrs?: Record<string, string>): HTMLElement;
+/**
+ * Find the closest `.oe-block` ancestor of a DOM node.
+ * Consolidates the repeated `node.closest('.oe-block')` pattern.
+ * @param {import('./types.js').DOMNode} node
+ * @returns {HTMLElement | null}
+ */
+export function closestBlock(node: import("./types.js").DOMNode): HTMLElement | null;
+/**
+ * Position a popup element below (or above if no space) an anchor rect.
+ *
+ * Two modes:
+ *  - `relative: false` (default) — sets absolute pixel values computed
+ *    against `rootRect` (the editor root's bounding rect).
+ *  - `relative: true` — sets CSS `calc(100% + …)` values, useful when
+ *    the popup is a direct child of its anchor.
+ *
+ * @param {HTMLElement} popupEl
+ * @param {DOMRect} anchorRect
+ * @param {DOMRect | null} rootRect  — required when `relative` is false
+ * @param {{ defaultHeight?: number, gap?: number, buffer?: number, relative?: boolean }} [options]
+ */
+export function positionPopup(popupEl: HTMLElement, anchorRect: DOMRect, rootRect: DOMRect | null, { defaultHeight, gap, buffer, relative }?: {
+    defaultHeight?: number;
+    gap?: number;
+    buffer?: number;
+    relative?: boolean;
+}): void;

package/dist/core/dom.js

@@ -0,0 +1,65 @@
+import { BLOCK_SELECTOR } from './constants.js'
+
+/**
+ * Create an element with optional class name and attributes.
+ * @param {string} tag
+ * @param {string} [className]
+ * @param {Record<string, string>} [attrs]
+ * @returns {HTMLElement}
+ */
+export function el(tag, className, attrs) {
+  const element = document.createElement(tag)
+  if (className) element.className = className
+  if (attrs) {
+    for (const [key, value] of Object.entries(attrs)) {
+      element.setAttribute(key, value)
+    }
+  }
+  return element
+}
+
+/**
+ * Find the closest `.oe-block` ancestor of a DOM node.
+ * Consolidates the repeated `node.closest('.oe-block')` pattern.
+ * @param {import('./types').DOMNode} node
+ * @returns {HTMLElement | null}
+ */
+export function closestBlock(node) {
+  const el = node.nodeType === Node.ELEMENT_NODE
+    ? /** @type {Element} */ (node)
+    : node.parentElement
+  return /** @type {HTMLElement | null} */ (el?.closest(BLOCK_SELECTOR) ?? null)
+}
+
+/**
+ * Position a popup element below (or above if no space) an anchor rect.
+ *
+ * Two modes:
+ *  - `relative: false` (default) — sets absolute pixel values computed
+ *    against `rootRect` (the editor root's bounding rect).
+ *  - `relative: true` — sets CSS `calc(100% + …)` values, useful when
+ *    the popup is a direct child of its anchor.
+ *
+ * @param {HTMLElement} popupEl
+ * @param {DOMRect} anchorRect
+ * @param {DOMRect | null} rootRect  — required when `relative` is false
+ * @param {{ defaultHeight?: number, gap?: number, buffer?: number, relative?: boolean }} [options]
+ */
+export function positionPopup(popupEl, anchorRect, rootRect, { defaultHeight = 300, gap = 4, buffer = 8, relative = false } = {}) {
+  const height = popupEl.offsetHeight || defaultHeight
+  const spaceBelow = window.innerHeight - anchorRect.bottom - buffer
+  const spaceAbove = anchorRect.top - buffer
+
+  if (spaceBelow >= height || spaceBelow >= spaceAbove) {
+    popupEl.style.bottom = 'auto'
+    popupEl.style.top = relative
+      ? `calc(100% + ${gap}px)`
+      : `${anchorRect.bottom - /** @type {DOMRect} */ (rootRect).top + gap}px`
+  } else {
+    popupEl.style.top = 'auto'
+    popupEl.style.bottom = relative
+      ? `calc(100% + ${gap}px)`
+      : `${/** @type {DOMRect} */ (rootRect).bottom - anchorRect.top + gap}px`
+  }
+}
+