@bloklabs/react 1.2.6 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "React bindings for the Blok editor",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -33,7 +33,7 @@
     "build": "yarn run -T vite build --mode production"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.2.6",
+    "@bloklabs/core": "^1.3.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokEditor.tsx

@@ -108,7 +108,7 @@ export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
       }
     }
 
-    const editor = useBlok(config as UseBlokConfig, deps);
+    const editor = useBlok(config, deps);
 
     useImperativeHandle<Blok | null, Blok | null>(ref, () => editor, [editor]);
 

package/src/createReactBlock.tsx

@@ -1,5 +1,6 @@
-import { useEffect, useRef, type ComponentType, type ReactElement } from 'react';
+import { isValidElement, useEffect, useRef, type ComponentType, type ReactElement } from 'react';
 import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
 import { DATA_ATTR, deepEqual, fillDefaults, mountChildBlocks, type PropSchema } from '@bloklabs/core/adapters';
 import {
   BLOK_PORTAL_REGISTRY_CONFIG_KEY,
@@ -7,7 +8,7 @@ import {
   type BlockPortalRegistry,
 } from './block-portal-registry';
 import type { BlockAPI } from '@/types/api';
-import type { BlockToolConstructorOptions, BlockToolData, ToolboxConfig } from '@/types/tools';
+import type { BlockToolConstructorOptions, BlockToolData, ToolboxConfig, ToolboxConfigEntry } from '@/types/tools';
 
 export type { PropSchema, PropSchemaEntry } from '@bloklabs/core/adapters';
 
@@ -21,7 +22,12 @@ const INTERNAL_CONFIG_KEYS: readonly string[] = [
 export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   /** Frozen snapshot of the block data. Re-rendered with a new value on change; never mutate. */
   data: Readonly<Data>;
-  /** The ONLY data write path: merge a partial patch and sync once. */
+  /**
+   * The ONLY data write path: merge a partial patch and sync once. Idempotency
+   * is part of the public contract — a patch that changes nothing is a FULL
+   * no-op (no re-render, no change event), so effects may echo current values
+   * through `commit` on any render, including mount, without a guard.
+   */
   commit: (patch: Partial<Data>) => void;
   /** This block's per-block API (id, connection methods, dispatchChange…). */
   block: BlockAPI;
@@ -46,16 +52,49 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   BlockChildren: ComponentType;
 }
 
+/**
+ * Props handed to a React block's `viewComponent` (the read-only renderer):
+ * the entry props minus `commit` — a display renderer has no write path.
+ */
+export type ReactBlockViewProps<Data, Config = Record<string, unknown>> = Omit<
+  ReactBlockRenderProps<Data, Config>,
+  'commit' | 'readOnly'
+>;
+
+/** A toolbox entry whose `icon` may be a React element instead of an SVG string. */
+export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
+  /**
+   * Toolbox icon. Core's toolbox chrome consumes markup strings, but React
+   * authors may pass the same element they render in the block body — the
+   * factory serializes it to markup once (lazily, cached) so icons are never
+   * duplicated as parallel raw SVG strings. Without a DOM (SSR) the element is
+   * returned as-is and serialization retries on the next browser-side access.
+   */
+  icon?: string | ReactElement;
+};
+
+/** Toolbox config for React blocks: single entry or several variants. */
+export type ReactToolboxConfig = ReactToolboxConfigEntry | ReactToolboxConfigEntry[];
+
 /** Spec for {@link createReactBlock}. */
 export interface CreateReactBlockSpec<Data = BlockToolData, Config = Record<string, unknown>> {
   /** Tool type name (registered key). */
   type: string;
-  /** Optional toolbox entry. */
-  toolbox?: ToolboxConfig;
+  /** Optional toolbox entry; `icon` accepts a React element (see {@link ReactToolboxConfigEntry}). */
+  toolbox?: ReactToolboxConfig;
   /** Declarative defaults that also define the exact `save()` key set. */
   propSchema: PropSchema;
   /** The component rendered for each block instance. */
   component: ComponentType<ReactBlockRenderProps<Data, Config>>;
+  /**
+   * Optional read-only renderer: when the editor is read-only, this component
+   * is rendered INSTEAD of `component`, so blocks don't hand-plumb a
+   * display-vs-edit ternary. It receives the entry props minus `commit` (no
+   * write path) and minus `readOnly` (always true by definition). Toggling read-only
+   * swaps renderers — ephemeral state does not survive the swap; omit
+   * `viewComponent` to keep the single-component in-place toggle instead.
+   */
+  viewComponent?: ComponentType<ReactBlockViewProps<Data, Config>>;
   /** Optional lifecycle callbacks mapped from Blok's block hooks. */
   onRendered?: (block: BlockAPI) => void;
   onMoved?: (block: BlockAPI) => void;
@@ -96,12 +135,116 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
   readonly toolbox: ToolboxConfig | undefined;
   readonly isReadOnlySupported: boolean;
 } {
+  /**
+   * Serialize a React element (an icon) to markup with a throwaway synchronous
+   * root. Returns null when serialization cannot complete: without a DOM
+   * (SSR — core never reads `toolbox` server-side, but a consumer may), or
+   * when the flush was deferred because React was already rendering (flushSync
+   * inside a render is a no-op with a warning, leaving the mount empty). A
+   * null result is NOT cached, so the next access retries.
+   */
+  const renderElementToMarkup = (element: ReactElement): string | null => {
+    if (typeof document === 'undefined') {
+      return null;
+    }
+
+    const mount = document.createElement('div');
+    const root = createRoot(mount);
+
+    flushSync(() => {
+      root.render(element);
+    });
+
+    const markup = mount.innerHTML;
+
+    root.unmount();
+
+    return markup === '' ? null : markup;
+  };
+
+  const convertToolbox = (): { value: ToolboxConfig | undefined; complete: boolean } => {
+    const status = { complete: true };
+
+    const toEntry = (entry: ReactToolboxConfigEntry): ToolboxConfigEntry => {
+      if (!isValidElement(entry.icon)) {
+        return entry as ToolboxConfigEntry;
+      }
+
+      const markup = renderElementToMarkup(entry.icon);
+
+      if (markup === null) {
+        // Leave the element in place (a consumer reading `toolbox` outside the
+        // browser can still use it) and skip caching so a later browser-side
+        // access serializes it properly.
+        status.complete = false;
+
+        return entry as ToolboxConfigEntry;
+      }
+
+      return { ...entry, icon: markup };
+    };
+
+    if (spec.toolbox === undefined) {
+      return { value: undefined, complete: status.complete };
+    }
+
+    const value = Array.isArray(spec.toolbox) ? spec.toolbox.map(toEntry) : toEntry(spec.toolbox);
+
+    return { value, complete: status.complete };
+  };
+
+  /** Lazily-computed core-compatible toolbox (React element icons serialized once). */
+  const toolboxCache: { resolved: boolean; value: ToolboxConfig | undefined } = {
+    resolved: false,
+    value: undefined,
+  };
+
+  const resolveToolbox = (): ToolboxConfig | undefined => {
+    if (toolboxCache.resolved) {
+      return toolboxCache.value;
+    }
+
+    const { value, complete } = convertToolbox();
+
+    // Only a fully-serialized toolbox is cached; an incomplete pass (no DOM,
+    // deferred flush) is returned as-is and recomputed on the next access.
+    if (complete) {
+      toolboxCache.value = value;
+      toolboxCache.resolved = true;
+    }
+
+    return value;
+  };
+
+  /**
+   * The component actually registered with the portal: when the spec provides a
+   * `viewComponent`, this chooser swaps to it while read-only (dropping the
+   * write-path props); otherwise the edit component is registered directly and
+   * keeps its in-place read-only toggle semantics.
+   */
+  const ReadOnlySwitch = (props: ReactBlockRenderProps<Data, Config>): ReactElement => {
+    const ViewComponent = spec.viewComponent;
+
+    if (props.readOnly && ViewComponent !== undefined) {
+      const { commit: _commit, readOnly: _readOnly, ...viewProps } = props;
+
+      return <ViewComponent {...(viewProps)} />;
+    }
+
+    const EditComponent = spec.component;
+
+    return <EditComponent {...props} />;
+  };
+
+  const entryComponent: ComponentType<ReactBlockRenderProps<Data, Config>> =
+    spec.viewComponent === undefined ? spec.component : ReadOnlySwitch;
+
   return class ReactBlockTool {
     /** Marker so `useBlok` can detect react-block tools and inject the registry. */
     public static readonly __isBlokReactBlock = true as const;
 
     public static get toolbox(): ToolboxConfig | undefined {
-      return spec.toolbox;
+      return resolveToolbox();
     }
 
     /**
@@ -190,7 +333,7 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 
       this.registry?.register(this.blockApi.id, {
         hostEl: host,
-        component: spec.component as unknown as ComponentType<Record<string, unknown>>,
+        component: entryComponent as unknown as ComponentType<Record<string, unknown>>,
         props: this.buildProps(),
         toolName: this.toolName,
       });
@@ -205,7 +348,7 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 
     public save(): BlockToolData {
       // The complete, frozen mirror — never the DOM, never partial.
-      return this.mirror as BlockToolData;
+      return this.mirror;
     }
 
     public async setData(newData: BlockToolData): Promise<boolean> {

package/src/createReactInlineTool.tsx

@@ -43,6 +43,13 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
   type: string;
   /** Optional toolbar item title (shown in overflow/search contexts). */
   title?: string;
+  /**
+   * Translation key for the toolbar label, resolved by core i18n as
+   * `toolNames.{titleKey}` (or used verbatim when it contains a dot). Without
+   * it a custom tool's label is only localizable through the legacy
+   * capitalized-tool-name fallback.
+   */
+  titleKey?: string;
   /** The component rendered as the tool's toolbar icon/UI. */
   component: ComponentType<ReactInlineToolRenderProps<Config>>;
   /** Applies/removes the formatting on the LIVE selection's range (captured at activation time). */
@@ -78,6 +85,7 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
   readonly __isBlokReactInlineTool: true;
   readonly isInline: true;
   readonly title: string | undefined;
+  readonly titleKey: string | undefined;
   readonly shortcut: string | undefined;
   readonly sanitize: SanitizerConfig | undefined;
   readonly isReadOnlySupported: boolean;
@@ -91,6 +99,10 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
       return spec.title;
     }
 
+    public static get titleKey(): string | undefined {
+      return spec.titleKey;
+    }
+
     public static get shortcut(): string | undefined {
       return spec.shortcut;
     }

package/src/index.ts

@@ -9,6 +9,9 @@ export { createReactBlock } from './createReactBlock';
 export type {
   CreateReactBlockSpec,
   ReactBlockRenderProps,
+  ReactBlockViewProps,
+  ReactToolboxConfig,
+  ReactToolboxConfigEntry,
   PropSchema,
   PropSchemaEntry,
 } from './createReactBlock';

package/src/provide-blok.tsx

@@ -66,5 +66,5 @@ export function mergeBlokDefaults(
     merged.tools = { ...defaults.tools, ...config.tools };
   }
 
-  return merged as UseBlokConfig;
+  return merged;
 }

package/src/useBlok.ts

@@ -11,7 +11,7 @@ import {
 } from './block-portal-registry';
 import { setRegistry, removeRegistry } from './registry-map';
 import { bindLiveToolConfigFunctions, buildLiveBlockConfig } from './live-tool-config';
-import { normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
+import { createEmittedEchoWindow, normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
 
@@ -70,7 +70,7 @@ const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): un
       typeof entry === 'function' ? { class: entry } : { ...(entry as Record<string, unknown>) };
 
     base.config = {
-      ...((base.config as Record<string, unknown> | undefined) ?? {}),
+      ...((base.config) ?? {}),
       [BLOK_PORTAL_REGISTRY_CONFIG_KEY]: registry,
       [BLOK_TOOL_NAME_CONFIG_KEY]: name,
     };
@@ -124,6 +124,13 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   // 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);
+  // Window of recently emitted `onSave` payloads. The baseline above only
+  // remembers the LAST one, but a host that persists on save and refetches can
+  // echo an EARLIER save after a newer one replaced the baseline (the user kept
+  // typing). Such a stale echo is still the editor's own output — re-rendering
+  // it would clobber the caret and the content typed since — so the data effect
+  // treats a match against ANY windowed payload as a no-op.
+  const echoWindowRef = useRef(createEmittedEchoWindow());
   const seededEditorRef = useRef<Blok | null>(null);
   // The `data` the live editor was actually constructed with. The seed gate in
   // the reactive-`data` effect compares the current prop against THIS (not mere
@@ -144,6 +151,9 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   const liveRegistryRef = useRef<BlockPortalRegistry | null>(null);
   const wrappedToolsRef = useRef<unknown>(undefined);
   const pushedBlockConfigsRef = useRef<Map<string, Record<string, unknown>>>(new Map());
+  // Last-applied tool-level `toolbox` setting per tool name (dedupe baseline for
+  // the reactive toolbox effect below). Seeded from the construction-time tools.
+  const appliedToolboxRef = useRef<Map<string, unknown>>(new Map());
 
   // Main lifecycle effect
   useEffect(() => {
@@ -224,6 +234,12 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     liveRegistryRef.current = registry;
     wrappedToolsRef.current = wrappedTools;
     pushedBlockConfigsRef.current = new Map();
+    appliedToolboxRef.current = new Map(
+      Object.entries((currentConfig.tools ?? {}) as Record<string, unknown>).map(([name, entry]) => [
+        name,
+        entry !== null && typeof entry === 'object' ? (entry as { toolbox?: unknown }).toolbox : undefined,
+      ])
+    );
 
     const blokConfig = {
       ...currentConfig,
@@ -249,6 +265,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
         // 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];
+        echoWindowRef.current.record(args[0]);
         configRef.current.onSave?.(...args);
       };
     }
@@ -269,7 +286,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       };
     }
 
-    const blok = new BlokRuntime(blokConfig) as unknown as Blok;
+    const blok = new BlokRuntime(blokConfig);
     state.editor = blok;
     // Remember what this editor was seeded with so the reactive-`data` effect can
     // tell a genuine post-construction change from the construction value itself.
@@ -358,6 +375,48 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     }
   });
 
+  // Live tool-level `toolbox` setting. Toolbox membership was construction-only,
+  // which forced permission-style gating (`toolbox: false` for users who may not
+  // insert a tool) into `deps` — recreating the whole editor on a permission
+  // flip. Instead, diff each tool's `toolbox` setting against the last applied
+  // value on every render and push genuine changes through the runtime
+  // `tools.update` API (which reaches the live adapter and rebuilds the Toolbox
+  // UI). Applies only once the editor is ready — module APIs attach at isReady —
+  // and the ready transition re-renders, so a change made earlier is not lost.
+  useEffect(() => {
+    const state = stateRef.current;
+
+    if (state.editor === null || state.isDestroyed || !state.isEditorReady) {
+      return;
+    }
+
+    const latestTools = configRef.current.tools as Record<string, unknown> | undefined;
+
+    if (latestTools === null || typeof latestTools !== 'object') {
+      return;
+    }
+
+    for (const [name, entry] of Object.entries(latestTools)) {
+      // Only tools the editor was constructed with can be updated at runtime.
+      if (!appliedToolboxRef.current.has(name)) {
+        continue;
+      }
+
+      const latest =
+        entry !== null && typeof entry === 'object' ? (entry as { toolbox?: unknown }).toolbox : undefined;
+      const applied = appliedToolboxRef.current.get(name);
+
+      if (deepEqual(latest, applied)) {
+        continue;
+      }
+
+      appliedToolboxRef.current.set(name, latest);
+      (state.editor as unknown as {
+        tools?: { update: (toolName: string, config: Record<string, unknown>) => void };
+      }).tools?.update(name, { toolbox: latest });
+    }
+  });
+
   // Reactive: readOnly (object form normalized so the effect dep is a stable boolean)
   const readOnlyEnabled = normalizeReadOnlyConfig(config.readOnly).enabled;
   useEffect(() => {
@@ -394,6 +453,33 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     editor.width.set(width);
   }, [editor, width]);
 
+  // Reactive: style.tokens
+  //
+  // Theme tokens were construction-only, so a host with a live light/dark
+  // toggle had to bump `deps` (destroying the editor, losing caret/history) or
+  // hand-write the global stylesheet Blok already injects. Push genuine changes
+  // through the runtime `tokens` API instead, deep-equal–deduped because
+  // `tokens` is almost always a fresh object literal each render.
+  const styleTokens = config.style?.tokens;
+  /*
+   * Seeded with the mount-time value: construction already injected those
+   * tokens, so the first effect run is a no-op and only genuine changes push.
+   */
+  const appliedTokensRef = useRef<Record<string, string> | undefined>(config.style?.tokens);
+
+  useEffect(() => {
+    if (editor === null || styleTokens === undefined) {
+      return;
+    }
+
+    if (deepEqual(styleTokens, appliedTokensRef.current)) {
+      return;
+    }
+
+    appliedTokensRef.current = styleTokens;
+    editor.tokens.set(styleTokens);
+  }, [editor, styleTokens]);
+
   // Reactive: placeholder
   const { placeholder } = config;
   useEffect(() => {
@@ -441,6 +527,8 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       // A render still pending on a PRIOR editor is moot for this fresh instance;
       // clear it so its content can't dedupe a needed render on the new editor.
       pendingDataRef.current = undefined;
+      // Payloads emitted by a PRIOR editor are likewise moot for this one.
+      echoWindowRef.current.clear();
 
       if (deepEqual(data, constructedDataRef.current)) {
         lastRenderedDataRef.current = data;
@@ -456,6 +544,17 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       return;
     }
 
+    // Skip stale echoes: content the editor itself emitted via `onSave` recently,
+    // arriving back reshaped (fresh envelope, stripped ids) and/or late — after a
+    // newer save already replaced the baseline above.
+    if (echoWindowRef.current.matches(data)) {
+      return;
+    }
+
+    // Genuinely external content takes over: earlier emitted payloads are moot,
+    // and keeping them could wrongly no-op a later deliberate revert to one.
+    echoWindowRef.current.clear();
+
     // Mark the content in-flight, but DON'T advance the success baseline until the
     // render actually resolves. A failed render leaves the editor on its last
     // successful content, so the baseline must keep pointing there — otherwise a

package/types/index.d.ts

@@ -1,5 +1,5 @@
 import type { BlokConfig, BlockToolData, OutputBlockData, OutputData } from '@bloklabs/core';
-import type { BlockAPI, BlockToolConstructable, ToolboxConfig } from '@bloklabs/core';
+import type { BlockAPI, BlockToolConstructable, ToolboxConfigEntry } from '@bloklabs/core';
 import type { InlineToolConstructable, SanitizerConfig } from '@bloklabs/core';
 import type { Blok, EditorWidth, BlockRenderedPayload, BlocksRenderedPayload } from '@bloklabs/core';
 import type { BlockTuneData } from '@bloklabs/core';
@@ -587,15 +587,46 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   BlockChildren: React.ComponentType;
 }
 
+/**
+ * Props handed to a React block's `viewComponent` (the read-only renderer):
+ * the entry props minus `commit` (no write path) and `readOnly` (always true).
+ */
+export type ReactBlockViewProps<Data, Config = Record<string, unknown>> = Omit<
+  ReactBlockRenderProps<Data, Config>,
+  'commit' | 'readOnly'
+>;
+
+/** A toolbox entry whose `icon` may be a React element instead of an SVG string. */
+export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
+  /**
+   * Toolbox icon. Accepts the markup string core consumes directly, or the same
+   * React element rendered in the block body — the factory serializes elements
+   * to markup once (lazily, cached), so icons are never duplicated as parallel
+   * raw SVG strings. Without a DOM (SSR) the element is returned as-is and
+   * serialization retries on the next browser-side access.
+   */
+  icon?: string | React.ReactElement;
+};
+
+/** Toolbox config for React blocks: single entry or several variants. */
+export type ReactToolboxConfig = ReactToolboxConfigEntry | ReactToolboxConfigEntry[];
+
 /** Spec for {@link createReactBlock}. */
 export interface CreateReactBlockSpec<
   Data extends BlockToolData = BlockToolData,
   Config = Record<string, unknown>
 > {
   type: string;
-  toolbox?: ToolboxConfig;
+  toolbox?: ReactToolboxConfig;
   propSchema: PropSchema;
   component: React.ComponentType<ReactBlockRenderProps<Data, Config>>;
+  /**
+   * Optional read-only renderer: rendered INSTEAD of `component` while the
+   * editor is read-only, so blocks need no display-vs-edit ternary. Toggling
+   * read-only swaps renderers (ephemeral state does not survive the swap);
+   * omit it to keep the single-component in-place toggle.
+   */
+  viewComponent?: React.ComponentType<ReactBlockViewProps<Data, Config>>;
   onRendered?: (block: BlockAPI) => void;
   onMoved?: (block: BlockAPI) => void;
   onRemoved?: (block: BlockAPI) => void;
@@ -650,6 +681,13 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
   type: string;
   /** Optional toolbar item title (shown in overflow/search contexts). */
   title?: string;
+  /**
+   * Translation key for the toolbar label, resolved by core i18n as
+   * `toolNames.{titleKey}` (or used verbatim when it contains a dot). Without
+   * it a custom tool's label is only localizable through the legacy
+   * capitalized-tool-name fallback.
+   */
+  titleKey?: string;
   /** The component rendered as the tool's toolbar icon/UI. */
   component: React.ComponentType<ReactInlineToolRenderProps<Config>>;
   /** Applies/removes the formatting on the LIVE selection's range (captured at activation time). */