@jackuait/blok 0.23.2 → 0.23.4

package/src/components/modules/modificationsObserver.ts

@@ -42,6 +42,12 @@ export class ModificationsObserver extends Module {
    */
   private readonly batchTime = modificationsObserverBatchTimeout;
 
+  /**
+   * Set once the module is destroyed so an in-flight serialization (onSave)
+   * doesn't call back into a torn-down editor after its promise resolves.
+   */
+  private destroyed = false;
+
   /**
    * Prepare the module
    * @param options - options used by the modification observer module
@@ -103,7 +109,7 @@ export class ModificationsObserver extends Module {
    * @param event - some of our custom change events
    */
   private particularBlockChanged(event: BlockMutationEvent): void {
-    if (this.disabled || !isFunction(this.config.onChange)) {
+    if (this.disabled || (!isFunction(this.config.onChange) && !isFunction(this.config.onSave))) {
       return;
     }
 
@@ -127,14 +133,45 @@ export class ModificationsObserver extends Module {
         ? queuedEvents[0]
         : queuedEvents;
 
-      if (this.config.onChange) {
+      if (isFunction(this.config.onChange)) {
         this.config.onChange(this.Blok.API.methods, eventsToEmit);
       }
 
+      if (isFunction(this.config.onSave)) {
+        this.emitOnSave();
+      }
+
       this.batchingOnChangeQueue.clear();
     }, this.batchTime);
   }
 
+  /**
+   * Serializes the editor and delivers the full OutputData to the consumer's
+   * `onSave` callback. Invoked once per batched change window, so a burst of
+   * edits results in a single serialization. Skips delivery if the module was
+   * destroyed while the (async) serialization was in flight.
+   */
+  private emitOnSave(): void {
+    void this.Blok.Saver.save()
+      .then((data) => {
+        if (this.destroyed || data === undefined) {
+          return;
+        }
+
+        const { onSave } = this.config;
+
+        if (isFunction(onSave)) {
+          onSave(data, this.Blok.API.methods);
+        }
+      })
+      .catch(() => {
+        /**
+         * Serialization failed — the Saver already surfaces the error via its
+         * own channel, so swallow here to avoid an unhandled rejection.
+         */
+      });
+  }
+
   /**
    * Cleans up the module: disconnects the MutationObserver and cancels any
    * pending batching timeout.  Called by the editor's destroy() chain so that
@@ -144,6 +181,7 @@ export class ModificationsObserver extends Module {
    */
   public destroy(): void {
     this.disabled = true;
+    this.destroyed = true;
     this.mutationObserver.disconnect();
 
     if (this.batchingTimeout !== null) {

package/src/components/modules/paste/index.ts

@@ -113,7 +113,16 @@ export class Paste extends Module {
    */
   public async processDataTransfer(dataTransfer: DataTransfer, pasteTarget?: Element): Promise<void> {
     const plainData = dataTransfer.getData('text/plain');
-    const rawHtmlData = dataTransfer.getData('text/html');
+
+    // Give consumers a chance to transform or drop the raw clipboard HTML
+    // before any Blok preprocessing/sanitization runs. Returning a string
+    // replaces the HTML for the rest of the pipeline; returning null aborts the
+    // HTML paste path entirely (an empty string makes HtmlHandler bail, so the
+    // paste falls through to the plain-text handler).
+    const clipboardHtml = dataTransfer.getData('text/html');
+    const rawHtmlData = clipboardHtml && this.config.onBeforePaste
+      ? this.config.onBeforePaste(clipboardHtml) ?? ''
+      : clipboardHtml;
 
     // Native Blok clipboard data always wins. When absent, fall back to the
     // lossless proprietary flavours of other editors (web→web paste): they

package/src/components/modules/renderer.ts

@@ -13,6 +13,7 @@ import {
   type DataFormatAnalysis,
 } from '../utils/data-model-transform';
 import { migrateMarkColors } from '../utils/color-migration';
+import { BlocksRendered } from '../events';
 
 /**
  * Map of legacy EditorJS tool names to their Blok equivalents.
@@ -86,146 +87,160 @@ export class Renderer extends Module {
    */
   public render(blocksData: OutputBlockData[]): Promise<void> {
     return new Promise((resolve) => {
-      const { Tools, BlockManager } = this.Blok;
-
-      if (blocksData.length === 0) {
-        BlockManager.insert();
-      } else {
-        // Analyze and potentially transform the input data
-        const dataModelConfig = this.config.dataModel || 'auto';
-        const analysis = analyzeDataFormat(blocksData);
-        this.detectedInputFormat = analysis.format;
-
-        // Transform to hierarchical if config requires it
-        const expandedBlocks = shouldExpandToHierarchical(dataModelConfig, analysis.format)
-          ? expandToHierarchical(blocksData)
-          : blocksData;
-
-        // Recover migrated cells whose text a pre-fix save detached to root:
-        // re-attach `cell-<row>-<col>`-id orphans back into their empty cell.
-        // Runs before normalize so reclaimed refs get parented in the same pass.
-        const reclaimedBlocks = reclaimDetachedTableCells(expandedBlocks);
-
-        // Tables persist child references via `data.content[r][c].blocks = [<id>]`
-        // rather than an explicit `parent` field on each child. Pre-normalize
-        // those parent references so downstream code that gates on parentId
-        // (read-only cell mounter, saver filter, hierarchy queries) correctly
-        // recognizes the children as belonging to their table.
-        const processedBlocks = normalizeTableChildParents(reclaimedBlocks);
-
-        // Note: Yjs data layer is loaded via BlockManager.insertMany() with the correct block IDs
-
-        /**
-         * Track seen IDs to detect and resolve duplicates
-         */
-        const seenIds = new Set<string>();
-
-        /**
-         * Create Blocks instances
-         */
-        const blocks = processedBlocks.map((blockData: OutputBlockData) => {
-          const { tunes, parent, content, lastEditedAt, lastEditedBy } = blockData;
-          const hasDuplicateId = blockData.id !== undefined && seenIds.has(blockData.id);
-
-          if (hasDuplicateId) {
-            logLabeled(`Duplicate block id «${blockData.id}» replaced with a generated id to ensure uniqueness`, 'warn');
-          }
-
-          const id = hasDuplicateId ? generateBlockId() : blockData.id;
-
-          if (id !== undefined) {
-            seenIds.add(id);
-          }
-          const originalTool = blockData.type;
+      const renderedCount = this.insertRenderedBlocks(blocksData);
 
-          /**
-           * Validate that block data has the expected shape.
-           * Since OutputBlockData<Data> defaults to `any` for Data, we need to narrow the type.
-           */
-          const isValidBlockData = (data: unknown): data is Record<string, unknown> => {
-            return typeof data === 'object' && data !== null;
-          };
+      /**
+       * Wait till browser will render inserted Blocks and resolve a promise
+       */
+      window.requestIdleCallback(() => {
+        this.eventsDispatcher.emit(BlocksRendered, { count: renderedCount });
+        resolve();
+      }, { timeout: 2000 });
+    });
+  }
 
-          const blockToolData = isValidBlockData(blockData.data) ? blockData.data : {};
-
-          const availabilityResult = (() => {
-            if (Tools.available.has(originalTool)) {
-              return {
-                tool: originalTool,
-                data: blockToolData,
-              };
-            }
-
-            const aliasTarget = TOOL_ALIASES[originalTool];
-
-            if (aliasTarget !== undefined && Tools.available.has(aliasTarget)) {
-              return {
-                tool: aliasTarget,
-                data: blockToolData,
-              };
-            }
-
-            logLabeled(`Tool «${originalTool}» is not found. Check 'tools' property at the Blok config.`, 'warn');
-
-            return {
-              tool: Tools.stubTool,
-              data: this.composeStubDataForTool(originalTool, blockToolData, id),
-            };
-          })();
-
-          const buildBlock = (tool: string, data: BlockToolData): Block => {
-            try {
-              return BlockManager.composeBlock({
-                id,
-                tool,
-                data,
-                tunes,
-                parentId: parent,
-                contentIds: content,
-                lastEditedAt,
-                lastEditedBy,
-              });
-            } catch (error) {
-              log(`Block «${tool}» skipped because of plugins error`, 'error', {
-                data,
-                error,
-              });
-
-              /**
-               * If tool throws an error during render, we should render stub instead of it
-               */
-              const stubData = this.composeStubDataForTool(tool, data, id);
-
-              return BlockManager.composeBlock({
-                id,
-                tool: Tools.stubTool,
-                data: stubData,
-                tunes,
-                parentId: parent,
-                contentIds: content,
-                lastEditedAt,
-                lastEditedBy,
-              });
-            }
-          };
+  /**
+   * Inserts the given blocks (or a single default block when the input is
+   * empty) and returns the number of top-level blocks rendered in this batch.
+   * @param blocksData - blocks to render
+   */
+  private insertRenderedBlocks(blocksData: OutputBlockData[]): number {
+    const { Tools, BlockManager } = this.Blok;
+
+    if (blocksData.length === 0) {
+      BlockManager.insert();
 
-          return buildBlock(availabilityResult.tool, availabilityResult.data);
-        });
+      return 1;
+    }
 
-        /**
-         * Insert batch of Blocks
-         */
-        BlockManager.insertMany(blocks);
-        migrateMarkColors(this.Blok.UI.nodes.redactor);
+    // Analyze and potentially transform the input data
+    const dataModelConfig = this.config.dataModel || 'auto';
+    const analysis = analyzeDataFormat(blocksData);
+    this.detectedInputFormat = analysis.format;
+
+    // Transform to hierarchical if config requires it
+    const expandedBlocks = shouldExpandToHierarchical(dataModelConfig, analysis.format)
+      ? expandToHierarchical(blocksData)
+      : blocksData;
+
+    // Recover migrated cells whose text a pre-fix save detached to root:
+    // re-attach `cell-<row>-<col>`-id orphans back into their empty cell.
+    // Runs before normalize so reclaimed refs get parented in the same pass.
+    const reclaimedBlocks = reclaimDetachedTableCells(expandedBlocks);
+
+    // Tables persist child references via `data.content[r][c].blocks = [<id>]`
+    // rather than an explicit `parent` field on each child. Pre-normalize
+    // those parent references so downstream code that gates on parentId
+    // (read-only cell mounter, saver filter, hierarchy queries) correctly
+    // recognizes the children as belonging to their table.
+    const processedBlocks = normalizeTableChildParents(reclaimedBlocks);
+
+    // Note: Yjs data layer is loaded via BlockManager.insertMany() with the correct block IDs
+
+    /**
+     * Track seen IDs to detect and resolve duplicates
+     */
+    const seenIds = new Set<string>();
+
+    /**
+     * Create Blocks instances
+     */
+    const blocks = processedBlocks.map((blockData: OutputBlockData) => {
+      const { tunes, parent, content, lastEditedAt, lastEditedBy } = blockData;
+      const hasDuplicateId = blockData.id !== undefined && seenIds.has(blockData.id);
+
+      if (hasDuplicateId) {
+        logLabeled(`Duplicate block id «${blockData.id}» replaced with a generated id to ensure uniqueness`, 'warn');
       }
 
+      const id = hasDuplicateId ? generateBlockId() : blockData.id;
+
+      if (id !== undefined) {
+        seenIds.add(id);
+      }
+      const originalTool = blockData.type;
+
       /**
-       * Wait till browser will render inserted Blocks and resolve a promise
+       * Validate that block data has the expected shape.
+       * Since OutputBlockData<Data> defaults to `any` for Data, we need to narrow the type.
        */
-      window.requestIdleCallback(() => {
-        resolve();
-      }, { timeout: 2000 });
+      const isValidBlockData = (data: unknown): data is Record<string, unknown> => {
+        return typeof data === 'object' && data !== null;
+      };
+
+      const blockToolData = isValidBlockData(blockData.data) ? blockData.data : {};
+
+      const availabilityResult = (() => {
+        if (Tools.available.has(originalTool)) {
+          return {
+            tool: originalTool,
+            data: blockToolData,
+          };
+        }
+
+        const aliasTarget = TOOL_ALIASES[originalTool];
+
+        if (aliasTarget !== undefined && Tools.available.has(aliasTarget)) {
+          return {
+            tool: aliasTarget,
+            data: blockToolData,
+          };
+        }
+
+        logLabeled(`Tool «${originalTool}» is not found. Check 'tools' property at the Blok config.`, 'warn');
+
+        return {
+          tool: Tools.stubTool,
+          data: this.composeStubDataForTool(originalTool, blockToolData, id),
+        };
+      })();
+
+      const buildBlock = (tool: string, data: BlockToolData): Block => {
+        try {
+          return BlockManager.composeBlock({
+            id,
+            tool,
+            data,
+            tunes,
+            parentId: parent,
+            contentIds: content,
+            lastEditedAt,
+            lastEditedBy,
+          });
+        } catch (error) {
+          log(`Block «${tool}» skipped because of plugins error`, 'error', {
+            data,
+            error,
+          });
+
+          /**
+           * If tool throws an error during render, we should render stub instead of it
+           */
+          const stubData = this.composeStubDataForTool(tool, data, id);
+
+          return BlockManager.composeBlock({
+            id,
+            tool: Tools.stubTool,
+            data: stubData,
+            tunes,
+            parentId: parent,
+            contentIds: content,
+            lastEditedAt,
+            lastEditedBy,
+          });
+        }
+      };
+
+      return buildBlock(availabilityResult.tool, availabilityResult.data);
     });
+
+    /**
+     * Insert batch of Blocks
+     */
+    BlockManager.insertMany(blocks);
+    migrateMarkColors(this.Blok.UI.nodes.redactor);
+
+    return blocks.length;
   }
 
   /**

package/src/components/modules/toolbar/plus-button.ts

@@ -1,5 +1,6 @@
 import type { BlokModules } from '../../../types-internal/blok-modules';
 import type { Block } from '../../block';
+import { DATA_ATTR, TEST_ID } from '../../constants';
 import { Dom as $ } from '../../dom';
 import { IconPlus } from '../../icons';
 import { SelectionUtils } from '../../selection/index';
@@ -126,7 +127,7 @@ export class PlusButtonHandler {
       innerHTML: IconPlus,
     });
 
-    plusButton.setAttribute('data-blok-testid', 'plus-button');
+    plusButton.setAttribute(DATA_ATTR.testid, TEST_ID.plusButton);
 
     // eslint-disable-next-line no-param-reassign -- nodes is mutated by design
     nodes.plusButton = plusButton;

package/src/components/modules/toolbar/settings-toggler.ts

@@ -1,6 +1,6 @@
 import type { BlokModules } from '../../../types-internal/blok-modules';
 import type { Block } from '../../block';
-import { DATA_ATTR } from '../../constants';
+import { DATA_ATTR, TEST_ID } from '../../constants';
 import { Dom as $ } from '../../dom';
 import { IconMenu } from '../../icons';
 import { getUserOS } from '../../utils';
@@ -136,7 +136,7 @@ export class SettingsTogglerHandler {
 
     settingsToggler.setAttribute(DATA_ATTR.settingsToggler, '');
     settingsToggler.setAttribute(DATA_ATTR.dragHandle, '');
-    settingsToggler.setAttribute('data-blok-testid', 'settings-toggler');
+    settingsToggler.setAttribute(DATA_ATTR.testid, TEST_ID.settingsToggler);
 
     // Accessibility: make the drag handle accessible to screen readers
     // Using tabindex="-1" keeps it accessible but removes from tab order

package/src/components/modules/tools.ts

@@ -212,6 +212,24 @@ export class Tools extends Module {
     this.prepareBlockTools();
   }
 
+  /**
+   * Shallow-merges new user configuration into an already-prepared tool.
+   *
+   * Lets consumers swap config (e.g. an uploader) at runtime without recreating
+   * the editor. The stored config is mutated in place, so the live tool adapter
+   * and any block created afterwards pick up the new values. Blocks already
+   * mounted keep their current config until they are re-rendered.
+   * @param name - tool name
+   * @param config - partial tool config to merge in
+   */
+  public updateToolConfig(name: string, config: Partial<ToolConfig>): void {
+    if (!this.available.has(name) && !this.unavailable.has(name)) {
+      throw new Error(`Tool "${name}" is not registered.`);
+    }
+
+    this.getFactory().updateConfig(name, config);
+  }
+
   /**
    * Return general Sanitizer config for all inline tools
    */

package/src/components/tools/factory.ts

@@ -1,6 +1,6 @@
 import type { API as ApiMethods, I18n } from '../../../types';
 import type { BlokConfig } from '../../../types/configs';
-import type { ToolConstructable, ToolSettings } from '../../../types/tools';
+import type { ToolConfig, ToolConstructable, ToolSettings } from '../../../types/tools';
 import type { API as ApiModule } from '../modules/api';
 
 import { InternalInlineToolSettings, InternalTuneSettings } from './base';
@@ -45,6 +45,33 @@ export class ToolsFactory {
     this.blokConfig = blokConfig;
   }
 
+  /**
+   * Shallow-merges new user configuration into a registered tool's stored config.
+   *
+   * The merge targets the tool's nested `config` object (the part passed to the
+   * tool constructor) and mutates it IN PLACE. Adapters read their config lazily
+   * and share this exact object reference, so the live adapter — and any freshly
+   * built adapter — both observe the new values immediately.
+   * @param name - tool name
+   * @param config - partial tool config to merge in
+   */
+  public updateConfig(name: string, config: Partial<ToolConfig>): void {
+    const settings = this.config[name];
+
+    if (settings === undefined) {
+      throw new Error(`Tool "${name}" is not registered.`);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- Internal: mutating legacy nested config in place to keep live + future adapters in sync
+    if (settings.config === undefined) {
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- Internal: initialize nested config object before merging
+      settings.config = {};
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- Internal: in-place merge so the shared nested config reference reflects the update
+    Object.assign(settings.config, config);
+  }
+
   /**
    * Returns Tool object based on it's type
    * @param name - tool name

package/src/react/BlokEditor.tsx

@@ -20,10 +20,21 @@ import type { UseBlokConfig } from './types';
  * keep their editor-config meaning (they collide with div attributes of the same
  * name), so the container is styled via `className` rather than an inline `style`.
  *
- * `data` is uncontrolled (seed-only): it sets the INITIAL content. After mount the
- * editor owns the document — passing a new `data` reference does NOT reload it.
- * Read content via `onChange` or the ref (`ref.current.save()`); replace it
- * imperatively via `ref.current.render(newData)`.
+ * `data` is reactive (controlled-ish): it seeds the INITIAL content and, after
+ * mount, changing it to new *content* re-renders the editor via `render()` — no
+ * recreation. Updates are deep-equal–deduped (a new reference with identical
+ * content is a no-op, so it won't clobber the caret) and serialized (rapid
+ * changes can't overlap). For ad-hoc reloads you can still call
+ * `ref.current.render(newData)`.
+ *
+ * Pair `data` with `onSave` for a true controlled component: `onSave` is the
+ * output half, firing (debounced) with the full serialized `OutputData` on every
+ * content change — no manual `ref.current.save()` polling. Echoing that payload
+ * straight back via `onSave={setData}` is safe and caret-stable: the adapter
+ * records the editor's own emitted output as the content baseline, so the
+ * `onSave → setState → data` round-trip deep-equals that baseline and is deduped
+ * to a no-op (no re-render, no caret reset, no recursion). Genuine external `data`
+ * changes still re-render in place.
  */
 export interface BlokEditorProps
   extends Omit<UseBlokConfig, 'onReady'>,

package/src/react/config-keys.ts

@@ -25,9 +25,12 @@ export const USE_BLOK_CONFIG_KEYS = [
   'logLevel',
   'readOnly',
   'i18n',
+  'link',
   'linkPaste',
+  'onBeforePaste',
   'onReady',
   'onChange',
+  'onSave',
   'inlineToolbar',
   'tunes',
   'style',

package/src/react/deep-equal.ts

@@ -0,0 +1,48 @@
+/**
+ * Structural deep equality for JSON-like values (Blok `OutputData`).
+ *
+ * Used to dedupe reactive `data` updates so identical content does not trigger
+ * a redundant re-render that would clobber the caret/selection. Handles the
+ * value shapes that appear in editor data: plain objects, arrays, and
+ * primitives (including `null`/`undefined`).
+ * @param a - first value to compare
+ * @param b - second value to compare
+ * @returns true when both values are structurally equal
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+    return false;
+  }
+
+  const aIsArray = Array.isArray(a);
+  const bIsArray = Array.isArray(b);
+
+  if (aIsArray !== bIsArray) {
+    return false;
+  }
+
+  if (aIsArray && bIsArray) {
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+
+  return aKeys.every(
+    (key) => Object.prototype.hasOwnProperty.call(bObj, key) && deepEqual(aObj[key], bObj[key])
+  );
+}

package/src/react/types.ts

@@ -11,6 +11,12 @@ import type { BlokConfig, Blok, EditorWidth } from '@/types';
  * - `theme` — calls `editor.theme.set(value)`
  * - `width` — calls `editor.width.set(value)`
  * - `placeholder` — calls `editor.placeholder.set(value)`
+ * - `data` — re-renders via `editor.render(value)` when content changes
+ *   (deep-equal–deduped and serialized; seeds the initial content at creation)
+ *
+ * The `onSave` config (inherited from `BlokConfig`) is the controlled output
+ * half: it fires with the full serialized `OutputData` on every content change,
+ * so `data` + `onSave` form a controlled component without manual `save()` calls.
  */
 export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {
   /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */