@jackuait/blok 0.23.2 → 0.23.4

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';
 
@@ -42,6 +43,17 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const depsToken = useMemo(() => ({}), deps ?? []);
 
+  // Tracks the data the editor currently reflects — set when content is seeded
+  // or rendered (the reactive `data` effect below) AND when the editor emits its
+  // own serialized content via `onSave`. The latter is what makes a controlled
+  // `onSave -> setData -> data` round-trip a no-op: the echoed payload deep-equals
+  // this baseline, so the data effect skips the redundant render() (which would
+  // otherwise reset the caret). Declared here so the `onSave` wrapper below can
+  // update it before the consumer's setState re-runs the data effect.
+  const lastRenderedDataRef = useRef(config.data);
+  const seededEditorRef = useRef<Blok | null>(null);
+  const renderChainRef = useRef<Promise<void>>(Promise.resolve());
+
   // Main lifecycle effect
   useEffect(() => {
     if (typeof window === 'undefined') {
@@ -98,6 +110,19 @@ export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | nu
       },
     };
 
+    // Only attach onSave when the consumer opted in: its mere presence makes the
+    // core serialize on every change batch, so an absent prop must stay absent.
+    // The wrapper reads through the ref so the latest callback is always used.
+    if (currentConfig.onSave) {
+      blokConfig.onSave = (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
+        // Record the editor's own serialized output as the rendered baseline so a
+        // controlled consumer echoing it straight back into `data` is a no-op —
+        // no redundant render(), no caret reset, no round-trip recursion.
+        lastRenderedDataRef.current = args[0];
+        configRef.current.onSave?.(...args);
+      };
+    }
+
     const blok = new BlokRuntime(blokConfig) as unknown as Blok;
     state.editor = blok;
     setHolder(blok, holder);
@@ -173,6 +198,41 @@ 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 against the editor's current
+  // content baseline (`lastRenderedDataRef`, declared above and also updated by
+  // the `onSave` wrapper) so a new reference with the same content — including
+  // the editor's own serialized output echoed back — is a no-op and won't
+  // clobber the caret. Renders are serialized so rapid changes can't overlap.
+  const { data } = config;
+  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;
 }

package/types/configs/blok-config.d.ts

@@ -59,6 +59,17 @@ export interface BlokConfig {
    */
   sanitizer?: SanitizerConfig;
 
+  /**
+   * Transform or clean the raw clipboard HTML before Blok processes it.
+   * Runs on the unmodified `text/html` payload, before any Blok preprocessing
+   * or sanitization, so you no longer need a capture-phase paste interceptor.
+   *
+   * @param html - the raw `text/html` clipboard string
+   * @returns the transformed HTML to feed into the rest of the paste pipeline,
+   *          or `null` to skip the HTML paste path (paste falls through to plain text).
+   */
+  onBeforePaste?: (html: string) => string | null;
+
   /**
    * If true, toolbar won't be shown
    */
@@ -124,6 +135,32 @@ export interface BlokConfig {
    */
   i18n?: I18nConfig;
 
+  /**
+   * Configures how the Link inline tool builds anchor elements, so consumers can
+   * control the created `<a>` instead of post-processing the rendered DOM.
+   */
+  link?: {
+    /**
+     * `target` attribute applied to created anchors.
+     * @default '_blank'
+     */
+    target?: string;
+
+    /**
+     * `rel` attribute applied to created anchors.
+     * @default 'nofollow'
+     */
+    rel?: string;
+
+    /**
+     * Transforms the href just before it is assigned to the anchor.
+     * Runs after URL validation/normalization, on the final value.
+     * @param href - the validated, protocol-normalized href
+     * @returns the href to set on the anchor
+     */
+    transformHref?: (href: string) => string;
+  };
+
   /**
    * Notion-style link-paste behavior. Pasting a URL always opens a small menu
    * (Plain link / Bookmark / Embed) instead of auto-inserting a block.
@@ -150,6 +187,23 @@ export interface BlokConfig {
    */
   onChange?(api: API, event: BlockMutationEvent | BlockMutationEvent[]): void;
 
+  /**
+   * Fires with the full serialized {@link OutputData} whenever the content
+   * changes. This is the "output half" of a controlled editor: pair it with the
+   * `data` config (or the React `data` prop) to mirror the editor state into your
+   * own store with a single callback instead of calling `saver.save()` by hand.
+   *
+   * Serialization is debounced through the same change-batching window as
+   * `onChange`, so a burst of edits produces a single `onSave` call. Only
+   * user-driven content changes trigger it — programmatic `render()` does not
+   * (the change observer is disabled during render), so a controlled
+   * `data → render → onSave → setData` round-trip won't recurse.
+   *
+   * @param data - the full serialized output of the editor
+   * @param api - blok.js api
+   */
+  onSave?(data: OutputData, api: API): void;
+
   /**
    * Defines default toolbar for all tools.
    */

package/types/events/editor-events.ts

@@ -0,0 +1,41 @@
+/**
+ * Public payloads and name map for editor lifecycle events observable via
+ * `blok.events.on(...)`.
+ *
+ * These complement the mutation events delivered through the `onChange`
+ * config callback ({@link ./block}). Use together with the exported event-name
+ * constants `BlockRendered` (`'block:rendered'`) and `BlocksRendered`
+ * (`'blocks:rendered'`).
+ */
+
+/**
+ * Payload for the `block:rendered` event.
+ */
+export interface BlockRenderedPayload {
+  /**
+   * Id of the block that has just been rendered into the DOM.
+   * Use `blok.blocks.getById(blockId)` to access it.
+   */
+  blockId: string;
+}
+
+/**
+ * Payload for the `blocks:rendered` event.
+ */
+export interface BlocksRenderedPayload {
+  /**
+   * Number of top-level blocks rendered in the completed batch.
+   */
+  count: number;
+}
+
+/**
+ * Map of editor lifecycle event name -> payload.
+ *
+ * Subscribers get fully typed payloads for these well-known events while the
+ * `Events` API still accepts arbitrary string event names for custom events.
+ */
+export interface BlokEditorEventMap {
+  'block:rendered': BlockRenderedPayload;
+  'blocks:rendered': BlocksRenderedPayload;
+}

package/types/index.d.ts

@@ -42,6 +42,7 @@ import { BlockAddedMutationType, BlockAddedEvent } from './events/block/BlockAdd
 import { BlockChangedMutationType, BlockChangedEvent } from './events/block/BlockChanged';
 import { BlockMovedMutationType, BlockMovedEvent } from './events/block/BlockMoved';
 import { BlockRemovedMutationType, BlockRemovedEvent } from './events/block/BlockRemoved';
+import { BlokEditorEventMap, BlockRenderedPayload, BlocksRenderedPayload } from './events/editor-events';
 
 /**
  * Interfaces used for development
@@ -144,6 +145,9 @@ export {
   BlockMovedEvent,
   BlockChangedMutationType,
   BlockChangedEvent,
+  BlokEditorEventMap,
+  BlockRenderedPayload,
+  BlocksRenderedPayload,
 }
 
 /**
@@ -170,7 +174,7 @@ export interface API {
   ui: Ui;
   theme: Theme;
   /** Read-only view of selected editor configuration. */
-  config: Readonly<Pick<BlokConfig, 'linkPaste'>>;
+  config: Readonly<Pick<BlokConfig, 'linkPaste' | 'link'>>;
   rectangleSelection: {
     cancelActiveSelection: () => void;
     isRectActivated: () => boolean;

package/types/react.d.ts

@@ -12,6 +12,8 @@ import type React from 'react';
  * - `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 the content changes
+ *   (deep-equal–deduped and serialized; seeds the initial content at creation)
  *
  * All other config is consumed once at editor creation.
  */