@jackuait/blok 0.23.1 → 0.23.3

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,15 +20,22 @@ 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). Read content via `onChange` or the ref
+ * (`ref.current.save()`). For ad-hoc reloads you can still call
+ * `ref.current.render(newData)`.
  */
 export interface BlokEditorProps
   extends Omit<UseBlokConfig, 'onReady'>,
     Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
-  /** When any value changes, the editor is destroyed and recreated. */
+  /**
+   * When any value changes, the editor is destroyed and recreated. Keep each
+   * value referentially stable (primitives or useMemo-stable objects) — a dep
+   * whose identity changes every render recreates the editor each time.
+   */
   deps?: DependencyList;
   /** Test id forwarded to the editor container element (via data-testid). */
   'data-testid'?: string;
@@ -46,6 +53,11 @@ const CONFIG_KEY_SET = new Set<string>(USE_BLOK_CONFIG_KEYS);
  * The recommended way to embed Blok in React. Internally wires `useBlok` and
  * `BlokContent`, and forwards a ref to the live `Blok` instance.
  *
+ * Don't wrap this component in `styled()` or any HOC that reserves the `theme`
+ * prop — styled-components claims `theme` for its own `ThemeProvider`, so it
+ * never reaches the editor and theme sync silently breaks. Render it directly
+ * and style the container via `className`.
+ *
  * @example
  * ```tsx
  * const ref = useRef<Blok | null>(null);

package/src/react/config-keys.ts

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

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,8 @@ 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)
  */
 export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {
   /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */

package/src/react/useBlok.ts

@@ -1,6 +1,7 @@
 import { useState, useEffect, useRef, useMemo, type DependencyList } from 'react';
 import { Blok as BlokRuntime } from '../blok';
 import { setHolder, removeHolder } from './holder-map';
+import { deepEqual } from './deep-equal';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
 
@@ -173,6 +174,42 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
     editor.placeholder.set(placeholder);
   }, [editor, placeholder]);
 
+  // Reactive: data (controlled content)
+  //
+  // `data` seeds the editor at construction. Afterwards, changing the prop to
+  // new *content* re-renders the editor via the public render() API — no
+  // recreation. Updates are deep-equal–deduped (so a new reference with the
+  // same content is a no-op and won't clobber the caret) and serialized (so
+  // rapid changes can't trigger overlapping render passes).
+  const { data } = config;
+  const lastRenderedDataRef = useRef(config.data);
+  const seededEditorRef = useRef<Blok | null>(null);
+  const renderChainRef = useRef<Promise<void>>(Promise.resolve());
+  useEffect(() => {
+    if (editor === null || data === undefined) {
+      return;
+    }
+
+    // A freshly created editor was already seeded with `data` at construction;
+    // record it without re-rendering.
+    if (seededEditorRef.current !== editor) {
+      seededEditorRef.current = editor;
+      lastRenderedDataRef.current = data;
+
+      return;
+    }
+
+    // Unchanged content — skip the redundant render.
+    if (deepEqual(data, lastRenderedDataRef.current)) {
+      return;
+    }
+
+    lastRenderedDataRef.current = data;
+    renderChainRef.current = renderChainRef.current
+      .catch(() => undefined)
+      .then(() => editor.render(data));
+  }, [editor, data]);
+
   return editor;
 }
 

package/types/api/events.d.ts

@@ -1,17 +1,39 @@
+import { BlokEditorEventMap } from '../events/editor-events';
+
 /**
- * Describes Blok`s events API
+ * Describes Blok`s events API.
+ *
+ * Well-known editor lifecycle events (see {@link BlokEditorEventMap}, e.g.
+ * `'blocks:rendered'` and `'block:rendered'`) get fully typed payloads.
+ * Arbitrary string event names are still accepted for custom events.
  */
 export interface Events {
   /**
-   * Emits event
+   * Emits a typed editor lifecycle event.
+   *
+   * @param eventName - one of the well-known editor event names
+   * @param data - payload matching the event
+   */
+  emit<Name extends keyof BlokEditorEventMap>(eventName: Name, data: BlokEditorEventMap[Name]): void;
+
+  /**
+   * Emits an event.
    *
    * @param {string} eventName
    * @param {any} data
    */
-  emit(eventName: string, data: any): void;
+  emit(eventName: string, data?: any): void;
 
   /**
-   * Unsubscribe from event
+   * Unsubscribe from a typed editor lifecycle event.
+   *
+   * @param eventName - one of the well-known editor event names
+   * @param callback - the handler to remove
+   */
+  off<Name extends keyof BlokEditorEventMap>(eventName: Name, callback: (data: BlokEditorEventMap[Name]) => void): void;
+
+  /**
+   * Unsubscribe from event.
    *
    * @param {string} eventName
    * @param {(data: any) => void} callback
@@ -19,7 +41,15 @@ export interface Events {
   off(eventName: string, callback: (data?: any) => void): void;
 
   /**
-   * Subscribe to event
+   * Subscribe to a typed editor lifecycle event.
+   *
+   * @param eventName - one of the well-known editor event names
+   * @param callback - receives a typed payload
+   */
+  on<Name extends keyof BlokEditorEventMap>(eventName: Name, callback: (data: BlokEditorEventMap[Name]) => void): void;
+
+  /**
+   * Subscribe to event.
    *
    * @param {string} eventName
    * @param {(data: any) => void} callback

package/types/api/tools.d.ts

@@ -1,5 +1,5 @@
 import { BlockToolAdapter } from '../tools/adapters/block-tool-adapter';
-import { ToolConstructable, ToolSettings } from '../tools';
+import { ToolConfig, ToolConstructable, ToolSettings } from '../tools';
 import { ThemeMode } from './theme';
 
 /**
@@ -26,4 +26,19 @@ export interface Tools {
    * Useful for creating nested Blok editors with the same tools.
    */
   getToolsConfig(): ToolsConfig;
+
+  /**
+   * Shallow-merges new configuration into an already-installed tool, without
+   * recreating the editor. Useful for swapping config at runtime — e.g. pointing
+   * an image tool at a new uploader function.
+   *
+   * The merge targets the tool's `config` object (the part passed to the tool
+   * constructor). Blocks created after the call (and the next operation on the
+   * live tool) pick up the new config; blocks already mounted keep their current
+   * config until they are re-rendered.
+   * @param name - registered tool name
+   * @param config - partial tool config to merge in
+   * @throws if `name` is not a registered tool
+   */
+  update(name: string, config: Partial<ToolConfig>): void;
 }