@jackuait/blok 0.10.0-beta.9 → 0.10.1

package/src/tools/table/table-corner-drag.ts

@@ -0,0 +1,247 @@
+import { show as showTooltip, hide as hideTooltip } from '../../components/utils/tooltip';
+
+const CORNER_DRAG_ATTR = 'data-blok-table-corner-drag';
+
+export interface TableCornerDragOptions {
+  wrapper: HTMLElement;
+  gridEl: HTMLElement;
+  onAddRow: () => void;
+  onAddColumn: () => void;
+  onRemoveLastRow: () => void;
+  onRemoveLastColumn: () => void;
+  onDragStart: () => void;
+  onDragEnd: () => void;
+  getTableSize: () => { rows: number; cols: number };
+  canRemoveLastRow: () => boolean;
+  canRemoveLastColumn: () => boolean;
+  onClickAdd?: () => void;
+}
+
+const DRAG_THRESHOLD = 5;
+
+interface DragState {
+  startX: number;
+  startY: number;
+  unitWidth: number;
+  unitHeight: number;
+  addedRows: number;
+  addedCols: number;
+  pointerId: number;
+  didDrag: boolean;
+}
+
+export class TableCornerDrag {
+  private wrapper: HTMLElement;
+  private gridEl: HTMLElement;
+  private hitZone: HTMLElement;
+  private getTableSize: () => { rows: number; cols: number };
+  private onAddRow: () => void;
+  private onAddColumn: () => void;
+  private onRemoveLastRow: () => void;
+  private onRemoveLastColumn: () => void;
+  private onDragStart: () => void;
+  private onDragEnd: () => void;
+  private canRemoveLastRow: () => boolean;
+  private canRemoveLastColumn: () => boolean;
+  private onClickAdd: (() => void) | null;
+  private dragState: DragState | null = null;
+  private readonly boundMouseEnter: () => void;
+  private readonly boundMouseLeave: () => void;
+  private readonly boundPointerDown: (e: PointerEvent) => void;
+  private readonly boundPointerMove: (e: PointerEvent) => void;
+  private readonly boundPointerUp: (e: PointerEvent) => void;
+
+  constructor(options: TableCornerDragOptions) {
+    this.wrapper = options.wrapper;
+    this.gridEl = options.gridEl;
+    this.getTableSize = options.getTableSize;
+    this.onAddRow = options.onAddRow;
+    this.onAddColumn = options.onAddColumn;
+    this.onRemoveLastRow = options.onRemoveLastRow;
+    this.onRemoveLastColumn = options.onRemoveLastColumn;
+    this.onDragStart = options.onDragStart;
+    this.onDragEnd = options.onDragEnd;
+    this.canRemoveLastRow = options.canRemoveLastRow;
+    this.canRemoveLastColumn = options.canRemoveLastColumn;
+    this.onClickAdd = options.onClickAdd ?? null;
+
+    this.hitZone = document.createElement('div');
+    this.hitZone.setAttribute(CORNER_DRAG_ATTR, '');
+    this.hitZone.setAttribute('contenteditable', 'false');
+    this.hitZone.style.position = 'absolute';
+    this.hitZone.style.width = '36px';
+    this.hitZone.style.height = '36px';
+    this.hitZone.style.cursor = 'nwse-resize';
+    this.hitZone.style.zIndex = '2';
+    this.hitZone.style.pointerEvents = 'auto';
+    this.hitZone.style.bottom = '-36px';
+    this.hitZone.style.right = '-16px';
+
+    this.boundMouseEnter = this.handleMouseEnter.bind(this);
+    this.boundMouseLeave = this.handleMouseLeave.bind(this);
+    this.boundPointerDown = this.handlePointerDown.bind(this);
+    this.boundPointerMove = this.handlePointerMove.bind(this);
+    this.boundPointerUp = this.handlePointerUp.bind(this);
+
+    this.hitZone.addEventListener('mouseenter', this.boundMouseEnter);
+    this.hitZone.addEventListener('mouseleave', this.boundMouseLeave);
+    this.hitZone.addEventListener('pointerdown', this.boundPointerDown);
+
+    this.wrapper.appendChild(this.hitZone);
+  }
+
+  private updateTooltip(): void {
+    const size = this.getTableSize();
+
+    showTooltip(this.hitZone, `${size.cols}\u00D7${size.rows}`, { placement: 'bottom' });
+  }
+
+  private handleMouseEnter(): void {
+    this.updateTooltip();
+  }
+
+  private handleMouseLeave(): void {
+    if (this.dragState !== null) {
+      return;
+    }
+    hideTooltip();
+  }
+
+  private measureUnitHeight(): number {
+    const rows = this.gridEl.querySelectorAll('[data-blok-table-row]');
+    const lastRow = rows[rows.length - 1] as HTMLElement | undefined;
+
+    return lastRow?.offsetHeight || 30;
+  }
+
+  private measureUnitWidth(): number {
+    const firstRow = this.gridEl.querySelector('[data-blok-table-row]');
+
+    if (!firstRow) {
+      return 100;
+    }
+
+    const cells = firstRow.querySelectorAll('[data-blok-table-cell]');
+    const lastCell = cells[cells.length - 1] as HTMLElement | undefined;
+
+    return lastCell?.offsetWidth || 100;
+  }
+
+  private handlePointerDown(e: PointerEvent): void {
+    this.dragState = {
+      startX: e.clientX,
+      startY: e.clientY,
+      unitWidth: this.measureUnitWidth(),
+      unitHeight: this.measureUnitHeight(),
+      addedRows: 0,
+      addedCols: 0,
+      pointerId: e.pointerId,
+      didDrag: false,
+    };
+
+    this.updateTooltip();
+
+    this.hitZone.setPointerCapture(e.pointerId);
+    this.hitZone.addEventListener('pointermove', this.boundPointerMove);
+    this.hitZone.addEventListener('pointerup', this.boundPointerUp);
+  }
+
+  private handlePointerMove(e: PointerEvent): void {
+    if (this.dragState === null) {
+      return;
+    }
+
+    const dx = e.clientX - this.dragState.startX;
+    const dy = e.clientY - this.dragState.startY;
+
+    if (!this.dragState.didDrag) {
+      const distance = Math.sqrt(dx * dx + dy * dy);
+
+      if (distance < DRAG_THRESHOLD) {
+        return;
+      }
+
+      this.dragState.didDrag = true;
+      document.body.style.cursor = 'nwse-resize';
+      document.body.style.userSelect = 'none';
+      this.onDragStart();
+    }
+
+    const { unitHeight, unitWidth } = this.dragState;
+
+    const targetRows = Math.trunc(dy / unitHeight);
+    const targetCols = Math.trunc(dx / unitWidth);
+
+    while (this.dragState.addedRows < targetRows) {
+      this.onAddRow();
+      this.dragState.addedRows++;
+    }
+
+    while (this.dragState.addedRows > targetRows && this.canRemoveLastRow()) {
+      this.onRemoveLastRow();
+      this.dragState.addedRows--;
+    }
+
+    while (this.dragState.addedCols < targetCols) {
+      this.onAddColumn();
+      this.dragState.addedCols++;
+    }
+
+    while (this.dragState.addedCols > targetCols && this.canRemoveLastColumn()) {
+      this.onRemoveLastColumn();
+      this.dragState.addedCols--;
+    }
+
+    this.updateTooltip();
+  }
+
+  private handlePointerUp(_e: PointerEvent): void {
+    if (this.dragState === null) {
+      return;
+    }
+
+    const { didDrag, pointerId } = this.dragState;
+
+    this.dragState = null;
+    hideTooltip();
+    this.hitZone.releasePointerCapture(pointerId);
+    this.hitZone.removeEventListener('pointermove', this.boundPointerMove);
+    this.hitZone.removeEventListener('pointerup', this.boundPointerUp);
+
+    if (!didDrag) {
+      if (this.onClickAdd) {
+        this.onClickAdd();
+      } else {
+        this.onAddRow();
+        this.onAddColumn();
+      }
+    } else {
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+      this.onDragEnd();
+    }
+  }
+
+  public setDisplay(visible: boolean): void {
+    this.hitZone.style.display = visible ? '' : 'none';
+  }
+
+  public setInteractive(interactive: boolean): void {
+    this.hitZone.style.pointerEvents = interactive ? 'auto' : 'none';
+  }
+
+  public destroy(): void {
+    this.hitZone.removeEventListener('mouseenter', this.boundMouseEnter);
+    this.hitZone.removeEventListener('mouseleave', this.boundMouseLeave);
+    this.hitZone.removeEventListener('pointerdown', this.boundPointerDown);
+    this.hitZone.removeEventListener('pointermove', this.boundPointerMove);
+    this.hitZone.removeEventListener('pointerup', this.boundPointerUp);
+    if (this.dragState?.didDrag) {
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    }
+    this.dragState = null;
+    hideTooltip();
+    this.hitZone.remove();
+  }
+}

package/src/tools/table/table-operations.ts

@@ -1,4 +1,5 @@
 import type { API } from '../../../types';
+import { DATA_ATTR } from '../../components/constants/data-attributes';
 
 import type { TableCellBlocks } from './table-cell-blocks';
 import { CELL_BLOCKS_ATTR } from './table-cell-blocks';
@@ -288,16 +289,28 @@ export const mountCellBlocksReadOnly = (
 
       if (!isCellWithBlocks(cellContent)) {
         // Read-only render path must not mutate block state.
-        // Use innerHTML so that legacy HTML markup (e.g. <b>bold</b>) is
-        // interpreted by the browser rather than shown as literal text.
-        container.innerHTML = cellContent;
+        // Wrap in a div with leading-[1.5] so the line-height matches paragraph
+        // blocks used in edit mode (where legacy strings are converted to real
+        // paragraph blocks with that line-height). Without this wrapper, the
+        // text inherits the cell's leading-none, producing shorter cells.
+        const wrapper = document.createElement('div');
+
+        wrapper.className = 'leading-[1.5]';
+        wrapper.innerHTML = cellContent;
+        container.replaceChildren(wrapper);
 
         return;
       }
 
-      // If this container previously rendered legacy text, clear it before mounting holders.
-      if (!hasExistingBlocks && (container.textContent ?? '').length > 0) {
-        container.textContent = '';
+      // Clear the container before (re-)mounting block holders.
+      // This covers two cases:
+      //   1. Legacy text was previously rendered and needs to be replaced with blocks.
+      //   2. Block holders are already mounted (e.g. from edit mode before a
+      //      setReadOnly toggle) — without clearing, the clone-guard below would
+      //      duplicate every holder because it detects them inside a
+      //      [data-blok-nested-blocks] container and appends a cloneNode(true).
+      if (hasExistingBlocks || (container.textContent ?? '').length > 0) {
+        container.replaceChildren();
       }
 
       for (const blockId of cellContent.blocks) {
@@ -313,12 +326,20 @@ export const mountCellBlocksReadOnly = (
           continue;
         }
 
+        // Skip blocks that don't belong to this table.
+        // Corrupted data may contain cross-table references; mounting them
+        // would steal (or clone) DOM nodes from the other table.
+        if (block.parentId !== _tableBlockId) {
+          continue;
+        }
+
         // Guard: if the block holder is already inside another table cell's
-        // blocks container, skip it. Without this check, appendChild would
-        // move (steal) the DOM node from the first table, leaving its cell
-        // empty. This can happen when corrupted data references the same
-        // block in multiple tables.
-        if (block.holder.closest(`[${CELL_BLOCKS_ATTR}]`)) {
+        // blocks container, clone its visual content instead of moving (stealing)
+        // the DOM node. This can happen when corrupted data references the same
+        // block in multiple tables. In read-only mode a deep clone is safe
+        // because the content is non-interactive.
+        if (block.holder.closest(`[${DATA_ATTR.nestedBlocks}]`)) {
+          container.appendChild(block.holder.cloneNode(true));
           continue;
         }
 
@@ -374,8 +395,8 @@ export const normalizeTableData = (
 export const setupKeyboardNavigation = (
   gridEl: HTMLElement,
   cellBlocks: TableCellBlocks | null,
-): void => {
-  gridEl.addEventListener('keydown', (event: KeyboardEvent) => {
+): (() => void) => {
+  const handler = (event: KeyboardEvent): void => {
     const target = event.target as HTMLElement;
     const cell = target.closest<HTMLElement>(`[${CELL_ATTR}]`);
 
@@ -388,7 +409,13 @@ export const setupKeyboardNavigation = (
     if (position) {
       cellBlocks?.handleKeyDown(event, position);
     }
-  });
+  };
+
+  gridEl.addEventListener('keydown', handler);
+
+  return () => {
+    gridEl.removeEventListener('keydown', handler);
+  };
 };
 
 export const SCROLL_OVERFLOW_CLASSES = ['overflow-x-auto', 'overflow-y-hidden'];

package/src/tools/toggle/dom-builder.ts

@@ -88,6 +88,7 @@ export const buildToggleItem = (context: ToggleDOMBuilderContext): ToggleBuildRe
   const childContainerElement = document.createElement('div');
   childContainerElement.className = TOGGLE_CHILDREN_STYLES;
   childContainerElement.setAttribute(TOGGLE_ATTR.toggleChildren, '');
+  childContainerElement.setAttribute(DATA_ATTR.nestedBlocks, '');
   // Block DOM mutations inside the children container from triggering the toggle tool's
   // didMutated → syncBlockDataToYjs path. Child block insertions/removals are tracked
   // via the block hierarchy (parentId / contentIds) and must not create spurious Yjs

package/src/tools/toggle/index.ts

@@ -229,6 +229,31 @@ export class ToggleItem implements BlockTool {
     this.setOpenState(false);
   }
 
+  public setReadOnly(state: boolean): void {
+    if (!this._element) {
+      return;
+    }
+
+    const wasReadOnly = this.readOnly;
+
+    this.readOnly = state;
+
+    // Toggle contentEditable on the content element
+    if (this._contentElement) {
+      this._contentElement.contentEditable = state ? 'false' : 'true';
+    }
+
+    // Manage block changed event subscription
+    if (state && !wasReadOnly) {
+      this.api.events.off('block changed', this.handleBlockChanged);
+    } else if (!state && wasReadOnly) {
+      this.api.events.on('block changed', this.handleBlockChanged);
+    }
+
+    // Update body placeholder visibility (hidden in read-only mode)
+    this.updateBodyPlaceholderVisibility();
+  }
+
   public removed(): void {
     this.api.events.off('block changed', this.handleBlockChanged);
   }

package/src/tools/toggle/toggle-lifecycle.ts

@@ -6,6 +6,7 @@
 
 import type { API } from '../../../types';
 
+import { mountChildBlocks } from '../nested-blocks';
 import { setupPlaceholder } from '../../components/utils/placeholder';
 
 import { TOGGLE_ATTR } from './constants';
@@ -94,11 +95,11 @@ export const updateChildrenVisibility = (
     arrowElement.focus();
   }
 
-  for (const child of children) {
-    if (childContainer && child.holder.parentElement !== childContainer) {
-      childContainer.appendChild(child.holder);
-    }
+  if (childContainer) {
+    mountChildBlocks(childContainer, children);
+  }
 
+  for (const child of children) {
     if (isOpen) {
       child.holder.classList.remove('hidden');
     } else {

package/src/types-internal/jsdom.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Declaration for jsdom (used in CLI for HTML conversion)
+ */
+declare module 'jsdom' {
+  export class JSDOM {
+    constructor(html: string);
+    window: typeof globalThis;
+  }
+}

package/types/tools/adapters/block-tool-adapter.d.ts

@@ -35,6 +35,12 @@ interface BlockToolAdapter extends BaseToolAdapter<ToolType.Block, BlockTool>{
    */
   isReadOnlySupported: boolean;
 
+  /**
+   * Returns true if the Tool's prototype has a setReadOnly method,
+   * enabling the in-place read-only toggle path (no save/clear/render cycle).
+   */
+  supportsInPlaceReadOnly: boolean;
+
   /**
    * Returns true if Tool supports linebreaks
    */

package/types/tools/block-tool.d.ts

@@ -87,6 +87,26 @@ export interface BlockTool extends BaseTool {
    * @returns Object with left offset in pixels, or undefined if no offset should be applied
    */
   getContentOffset?(hoveredElement: Element): { left: number } | undefined;
+
+  /**
+   * Returns the element that the toolbar should vertically center on.
+   * Used by tools whose editable area is deeply nested below non-editable UI
+   * (e.g., a header bar), where the default contenteditable-descendant search
+   * would position the toolbar too far down inside the block.
+   *
+   * Return undefined to use the default positioning logic.
+   */
+  getToolbarAnchorElement?(): HTMLElement | undefined;
+
+  /**
+   * Called when read-only mode is toggled without re-rendering the block.
+   * Implementations should update the DOM in place: toggle contentEditable,
+   * bind/unbind event listeners, show/hide interactive elements, etc.
+   *
+   * Optional — tools without this method trigger a full save/clear/render
+   * fallback when read-only mode is toggled.
+   */
+  setReadOnly?(state: boolean): void;
 }
 
 /**

package/types/utils/popover/popover-item.d.ts

@@ -151,6 +151,12 @@ export interface PopoverItemDefaultBaseParams {
    */
   icon?: string;
 
+  /**
+   * Icon to be displayed on the trailing (right) side of the item.
+   * Rendered without a box background, suitable for indicators like a checkmark.
+   */
+  trailingIcon?: string;
+
   /**
    * Additional displayed text
    */

package/bin/blok.mjs

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { readFileSync } from 'node:fs';
-import { run } from '../dist/cli.mjs';
-
-const version = process.env.npm_package_version
-  || JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version;
-const args = process.argv.slice(2);
-
-run(args, version);

package/dist/cli.mjs

@@ -1,37 +0,0 @@
-import * as e from "node:fs";
-//#region src/cli/commands/migrationContent.ts
-var t = "# Migrating from EditorJS to Blok\n\nThis guide covers the breaking changes when migrating from EditorJS to Blok.\n\n## Table of Contents\n\n- [Core Changes](#core-changes)\n- [Data Attributes](#data-attributes)\n- [CSS Classes](#css-classes)\n- [Bundled Tools](#bundled-tools)\n  - [Tool Configuration](#tool-configuration)\n  - [Lifecycle Hooks](#lifecycle-hooks)\n  - [Delimiter → Divider](#delimiter--divider)\n- [Configuration Defaults](#configuration-defaults)\n- [New API Methods](#new-api-methods)\n- [DOM Selectors](#dom-selectors)\n- [E2E Test Selectors](#e2e-test-selectors)\n\n---\n\n## Core Changes\n\n### Class Name\n\n```diff\n- import EditorJS from '@editorjs/editorjs';\n+ import Blok from '@jackuait/blok';\n\n- const editor = new EditorJS({ ... });\n+ const editor = new Blok({ ... });\n```\n\n### Default Holder\n\nThe default holder ID changed from `editorjs` to `blok`:\n\n```diff\n- <div id=\"editorjs\"></div>\n+ <div id=\"blok\"></div>\n```\n\nOr specify explicitly:\n\n```javascript\nconst editor = new Blok({\n  holder: 'my-editor', // works the same as before\n});\n```\n\n### TypeScript Types\n\n```diff\n- import type { EditorConfig, OutputData } from '@editorjs/editorjs';\n+ import type { BlokConfig, OutputData } from '@jackuait/blok';\n```\n\n---\n\n## Data Attributes\n\nBlok uses `data-blok-*` attributes instead of EditorJS's mixed naming conventions.\n\n| EditorJS | Blok |\n|----------|------|\n| `data-id` | `data-blok-id` |\n| `data-item-name` | `data-blok-item-name` |\n| `data-empty` | `data-blok-empty` |\n| `.ce-block--selected` (class) | `data-blok-selected=\"true\"` |\n| — | `data-blok-component` (tool name) |\n| — | `data-blok-interface` (element type) |\n| — | `data-blok-testid` (testing) |\n| — | `data-blok-opened` (toolbar state) |\n| — | `data-blok-placeholder` |\n| — | `data-blok-stretched` |\n| — | `data-blok-focused` |\n| — | `data-blok-popover-opened` |\n| — | `data-blok-tool` (tool name on rendered element) |\n| — | `data-blok-dragging` (block being dragged) |\n| — | `data-blok-hidden` (hidden state) |\n| — | `data-blok-rtl` (RTL mode) |\n| — | `data-blok-drag-handle` (drag handle element) |\n| — | `data-blok-overlay` (selection overlay) |\n| — | `data-blok-overlay-rectangle` (selection rectangle) |\n\n### Querying Blocks\n\n```diff\n- document.querySelector('[data-id=\"abc123\"]');\n+ document.querySelector('[data-blok-id=\"abc123\"]');\n\n- document.querySelector('[data-item-name=\"bold\"]');\n+ document.querySelector('[data-blok-item-name=\"bold\"]');\n```\n\n---\n\n## CSS Classes\n\nBlok replaces BEM class names with data attributes for selection.\n\n### Editor Wrapper\n\n| EditorJS | Blok |\n|----------|------|\n| `.codex-editor` | `[data-blok-editor]` |\n| `.codex-editor__redactor` | `[data-blok-redactor]` |\n| `.codex-editor--rtl` | `[data-blok-rtl=\"true\"]` |\n\n### Block Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block--selected` | `[data-blok-selected=\"true\"]` |\n| `.ce-block--stretched` | `[data-blok-stretched=\"true\"]` |\n| `.ce-block--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n\n### Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-toolbox--opened` | `[data-blok-toolbox][data-blok-opened=\"true\"]` |\n\n### Inline Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-inline-tool` | `[data-blok-testid=\"inline-tool\"]` |\n| `.ce-inline-tool--link` | `[data-blok-testid=\"inline-tool-link\"]` |\n| `.ce-inline-tool--bold` | `[data-blok-testid=\"inline-tool-bold\"]` |\n| `.ce-inline-tool--italic` | `[data-blok-testid=\"inline-tool-italic\"]` |\n\n### Popover\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover--opened` | `[data-blok-popover][data-blok-opened=\"true\"]` |\n| `.ce-popover__container` | `[data-blok-popover-container]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `.ce-popover-item--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-popover-item--confirmation` | `[data-blok-confirmation=\"true\"]` |\n| `.ce-popover-item__icon` | `[data-blok-testid=\"popover-item-icon\"]` |\n| `.ce-popover-item__icon--tool` | `[data-blok-testid=\"popover-item-icon-tool\"]` |\n\n### Tool-Specific Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-paragraph` | `[data-blok-tool=\"paragraph\"]` |\n| `.ce-header` | `[data-blok-tool=\"header\"]` |\n\n### Conversion Toolbar & Settings\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-conversion-toolbar` | `[data-blok-testid=\"conversion-toolbar\"]` |\n| `.ce-conversion-tool` | `[data-blok-testid=\"conversion-tool\"]` |\n| `.ce-settings` | `[data-blok-testid=\"block-settings\"]` |\n| `.ce-tune` | `[data-blok-testid=\"block-tune\"]` |\n\n### Other Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-stub` | `[data-blok-stub]` |\n| `.ce-drag-handle` | `[data-blok-drag-handle]` |\n| `.ce-ragged-right` | `[data-blok-ragged-right=\"true\"]` |\n\n### CDX List Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-list` | `[data-blok-list]` |\n| `.cdx-list__item` | `[data-blok-list-item]` |\n| `.cdx-list--ordered` | `[data-blok-list=\"ordered\"]` |\n| `.cdx-list--unordered` | `[data-blok-list=\"unordered\"]` |\n\n### CDX Utility Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-button` | `[data-blok-button]` |\n| `.cdx-input` | `[data-blok-input]` |\n| `.cdx-loader` | `[data-blok-loader]` |\n| `.cdx-search-field` | `[data-blok-search-field]` |\n\n---\n\n## Bundled Tools\n\nBlok includes Header and Paragraph tools. No external packages needed:\n\n```diff\n- import Header from '@editorjs/header';\n- import Paragraph from '@editorjs/paragraph';\n\n+ import Blok from '@jackuait/blok';\n\nconst editor = new Blok({\n  tools: {\n-   header: Header,\n-   paragraph: Paragraph,\n+   header: Blok.Header,\n+   paragraph: Blok.Paragraph, // optional, it's the default\n  },\n});\n```\n\n### Tool Configuration\n\nBoth bundled tools accept configuration options:\n\n#### HeaderConfig\n\n```typescript\nimport type { HeaderConfig } from '@jackuait/blok';\n\nconst editor = new Blok({\n  tools: {\n    header: {\n      class: Blok.Header,\n      config: {\n        placeholder: 'Enter a heading',\n        levels: [2, 3, 4],      // Restrict to H2-H4 only\n        defaultLevel: 2,        // Default to H2\n      } as HeaderConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty header |\n| `levels` | `number[]` | `[1,2,3,4,5,6]` | Available heading levels (1-6) |\n| `defaultLevel` | `number` | `2` | Default heading level |\n\n#### ParagraphConfig\n\n```typescript\nimport type { ParagraphConfig } from '@jackuait/blok';\n\nconst editor = new Blok({\n  tools: {\n    paragraph: {\n      class: Blok.Paragraph,\n      config: {\n        placeholder: 'Start typing...',\n        preserveBlank: true,\n      } as ParagraphConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty paragraph |\n| `preserveBlank` | `boolean` | `false` | Keep empty paragraphs when saving |\n\n### Delimiter → Divider\n\nEditor.js's `@editorjs/delimiter` is replaced by Blok's built-in `divider` tool:\n\n```diff\n- import Delimiter from '@editorjs/delimiter';\n\nconst editor = new Blok({\n  tools: {\n-   delimiter: Delimiter,\n+   divider: Blok.Divider,\n  },\n});\n```\n\n**Saved data migration:** The block type name changed from `\"delimiter\"` to `\"divider\"`. The data format is identical (empty `{}`):\n\n```diff\n  {\n-   \"type\": \"delimiter\",\n+   \"type\": \"divider\",\n    \"data\": {}\n  }\n```\n\n> **Note:** Blok automatically recognizes `\"delimiter\"` blocks and renders them as dividers, so existing articles work without data migration. However, renaming the type in your database is recommended for consistency.\n\n---\n\n## Configuration Defaults\n\n| Option | EditorJS | Blok |\n|--------|----------|------|\n| `holder` | `\"editorjs\"` | `\"blok\"` |\n| `defaultBlock` | `\"paragraph\"` | `\"paragraph\"` |\n\n---\n\n## New API Methods\n\nBlok exposes shorthand methods directly on the instance:\n\n```javascript\nconst editor = new Blok({ ... });\n\n// Shorthand methods\nawait editor.save();      // Same as editor.saver.save()\neditor.clear();           // Same as editor.blocks.clear()\nawait editor.render(data);// Same as editor.blocks.render(data)\neditor.focus();           // Same as editor.caret.focus()\n\n// Event methods\neditor.on('change', handler);   // Same as editor.events.on()\neditor.off('change', handler);  // Same as editor.events.off()\neditor.emit('custom', data);    // Same as editor.events.emit()\n```\n\n---\n\n## DOM Selectors\n\nBlok uses consistent `data-blok-interface` attributes for major UI components:\n\n```javascript\n// Find the editor wrapper\nconst editorWrapper = document.querySelector('[data-blok-interface=\"blok\"]');\n\n// Find inline toolbar\nconst inlineToolbar = document.querySelector('[data-blok-interface=\"inline-toolbar\"]');\n\n// Find tooltip\nconst tooltip = document.querySelector('[data-blok-interface=\"tooltip\"]');\n```\n\nThese selectors are stable and recommended for programmatic access to Blok's UI components.\n\n### Key Changes\n\n1. **Prefix custom classes** with `blok-` instead of `ce-` or `cdx-`\n2. **Use `data-blok-*`** attributes instead of `data-*`\n\n---\n\n## E2E Test Selectors\n\nUpdate your test selectors to use Blok's `data-blok-testid` attributes:\n\n| EditorJS | Blok |\n|----------|------|\n| `[data-cy=editorjs]` | `[data-blok-testid=\"blok-editor\"]` |\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `[data-item-name=\"...\"]` | `[data-blok-item-name=\"...\"]` |\n\n### Playwright Example\n\n```diff\n// EditorJS\n- await page.locator('[data-cy=editorjs] .ce-block').click();\n- await page.locator('.ce-toolbar__settings-btn').click();\n- await page.locator('[data-item-name=\"delete\"]').click();\n\n// Blok\n+ await page.locator('[data-blok-element]').click();\n+ await page.locator('[data-blok-settings-toggler]').click();\n+ await page.locator('[data-blok-item-name=\"delete\"]').click();\n```\n\n### Additional Test Selectors\n\n| Element | Selector |\n|---------|----------|\n| Block tunes popover | `[data-blok-testid=\"block-tunes-popover\"]` |\n| Popover search input | `[data-blok-testid=\"popover-search-input\"]` |\n| Popover item title | `[data-blok-testid=\"popover-item-title\"]` |\n| Popover overlay | `[data-blok-testid=\"popover-overlay\"]` |\n| Inline tool input | `[data-blok-testid=\"inline-tool-input\"]` |\n| Tooltip | `[data-blok-testid=\"tooltip\"]` |\n| Redactor | `[data-blok-testid=\"redactor\"]` |\n| Toolbox | `[data-blok-testid=\"toolbox\"]` |\n| Toolbox popover | `[data-blok-testid=\"toolbox-popover\"]` |\n| Selection overlay | `[data-blok-testid=\"overlay\"]` |\n| Selection rectangle | `[data-blok-testid=\"overlay-rectangle\"]` |\n\n---\n\n### State Selectors\n\n| State | Selector |\n|-------|----------|\n| Toolbar opened | `[data-blok-opened=\"true\"]` |\n| Block selected | `[data-blok-selected=\"true\"]` |\n| Popover opened | `[data-blok-popover-opened=\"true\"]` |\n| Item focused | `[data-blok-focused=\"true\"]` |\n| Item disabled | `[data-blok-disabled=\"true\"]` |\n| Nested popover | `[data-blok-nested=\"true\"]` |\n| Toolbox opened | `[data-blok-toolbox-opened=\"true\"]` |\n| Block dragging | `[data-blok-dragging=\"true\"]` |\n| Element hidden | `[data-blok-hidden=\"true\"]` |\n| RTL mode | `[data-blok-rtl=\"true\"]` |\n\n---\n\n## Quick Checklist\n\n- [ ] Replace `new EditorJS` with `new Blok`\n- [ ] Update imports from `@editorjs/*` to `@jackuait/blok`\n- [ ] Change holder from `editorjs` to `blok` (or specify explicitly)\n- [ ] Use bundled tools: `Blok.Header`, `Blok.Paragraph`\n- [ ] Replace `@editorjs/delimiter` with built-in `Blok.Divider`\n- [ ] Update `EditorConfig` type to `BlokConfig`\n- [ ] Replace `data-id` with `data-blok-id` in queries\n- [ ] Replace `data-item-name` with `data-blok-item-name`\n- [ ] Replace `.ce-*` selectors with `[data-blok-*]` attributes\n- [ ] Replace `.cdx-*` selectors with `[data-blok-*]` attributes\n- [ ] Update E2E test selectors\n", n = (e) => [
-	"# Blok Migration Guide (for LLM-assisted migration)",
-	"",
-	"> This document contains everything needed to migrate a project from EditorJS to Blok.",
-	"> Apply these changes systematically to the user's codebase.",
-	`> Current Blok version: ${e}`,
-	"",
-	"---",
-	""
-].join("\n") + t, r = (t, n) => {
-	n ? (e.writeFileSync(n, t, "utf-8"), process.stderr.write(`Written to ${n}\n`)) : process.stdout.write(t);
-}, i = "Usage: blok [options]\n\nOptions:\n  --migration          Output the EditorJS to Blok migration guide (LLM-friendly)\n  --output <file>      Write output to a file instead of stdout\n  --help               Show this help message\n\nExamples:\n  npx @jackuait/blok --migration\n  npx @jackuait/blok --migration | pbcopy\n  npx @jackuait/blok --migration --output migration-guide.md\n", a = (e) => {
-	if (e.includes("--help")) return { command: "help" };
-	if (e.includes("--migration")) {
-		let t = e.indexOf("--output");
-		return {
-			command: "migration",
-			output: t === -1 ? void 0 : e[t + 1]
-		};
-	}
-	return { command: null };
-}, o = (e, t) => {
-	let { command: o, output: s } = a(e);
-	switch (o) {
-		case "migration":
-			r(n(t), s);
-			break;
-		case "help":
-		case null:
-			process.stdout.write(i);
-			break;
-	}
-};
-//#endregion
-export { o as run };