@bloklabs/react 1.2.5 → 1.3.0

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';
 
@@ -42,6 +42,16 @@ const isReactBlockEntry = (entry: unknown): boolean => {
   );
 };
 
+/** React inline tools (createReactInlineTool) need the same registry bridge. */
+const isReactInlineToolEntry = (entry: unknown): boolean => {
+  const toolClass = typeof entry === 'function' ? entry : (entry as { class?: unknown })?.class;
+
+  return (
+    typeof toolClass === 'function' &&
+    (toolClass as { __isBlokReactInlineTool?: boolean }).__isBlokReactInlineTool === true
+  );
+};
+
 const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): unknown => {
   if (tools === null || typeof tools !== 'object') {
     return tools;
@@ -50,7 +60,7 @@ const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): un
   const result: Record<string, unknown> = {};
 
   for (const [name, entry] of Object.entries(tools as Record<string, unknown>)) {
-    if (!isReactBlockEntry(entry)) {
+    if (!isReactBlockEntry(entry) && !isReactInlineToolEntry(entry)) {
       result[name] = entry;
 
       continue;
@@ -60,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,
     };
@@ -114,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
@@ -134,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(() => {
@@ -214,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,
@@ -239,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);
       };
     }
@@ -259,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.
@@ -348,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(() => {
@@ -384,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(() => {
@@ -431,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;
@@ -446,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,6 @@
 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';
 import type { MarkdownImportConfig } from '@bloklabs/core/markdown';
@@ -586,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;
@@ -624,6 +656,77 @@ export declare function createReactBlock<
   Config = Record<string, unknown>
 >(spec: CreateReactBlockSpec<Data, Config>): BlockToolConstructable;
 
+// ---------------------------------------------------------------------------
+// Inline-tool authoring (createReactInlineTool)
+// ---------------------------------------------------------------------------
+
+/** Props handed to a React inline tool's `component` (its toolbar icon/UI). */
+export interface ReactInlineToolRenderProps<Config = Record<string, unknown>> {
+  /**
+   * Whether the tool's formatting is active for the current selection —
+   * derived from the spec's `checkState` every time the toolbar queries it.
+   * Pushed IN PLACE (no remount), so the icon restyles live.
+   */
+  active: boolean;
+  /**
+   * The tool's `config` from the consumer's `tools` map (adapter-internal
+   * keys stripped) — the channel for host props (palette, locale…).
+   */
+  config: Readonly<Partial<Config>>;
+}
+
+/** Spec for {@link createReactInlineTool}. */
+export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
+  /** Tool type name — the MenuConfig item name (fallback when the tools-map key is unavailable). */
+  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). */
+  surround?: (range: Range) => void;
+  /** Reports whether the formatting is active for the given selection. */
+  checkState?: (selection: Selection | null) => boolean;
+  /** Keyboard shortcut (e.g. `CMD+SHIFT+C`). */
+  shortcut?: string;
+  /** Inline sanitizer config declaring the markup this tool produces. */
+  sanitize?: SanitizerConfig;
+  /** Whether the tool stays available in read-only mode. */
+  isReadOnlySupported?: boolean;
+}
+
+/**
+ * Author a first-party React inline tool: returns an inline-tool
+ * constructable registered exactly like a vanilla tool
+ * (`tools: { color: createReactInlineTool(...) }`). The tool's toolbar icon is
+ * a React component portaled through the editor's shared portal host INSIDE
+ * the React tree that renders `BlokContent`/`BlokEditor` — app-level context
+ * (themes, styled-components providers) reaches the icon with no
+ * consumer-managed `createRoot`, and the inline toolbar's teardown unmounts it
+ * deterministically (no leaked React roots).
+ *
+ * @example
+ * ```tsx
+ * const DescriptionColor = createReactInlineTool({
+ *   type: 'descriptionColor',
+ *   title: 'Text color',
+ *   component: ({ active }) => <FontColorIcon active={active} />,
+ *   surround: (range) => applyColor(range),
+ *   checkState: (selection) => hasColor(selection),
+ * });
+ * ```
+ */
+export declare function createReactInlineTool<Config = Record<string, unknown>>(
+  spec: CreateReactInlineToolSpec<Config>
+): InlineToolConstructable;
+
 /**
  * Tool-config key carrying the editor's portal registry into a
  * `createReactBlock` tool. Injected automatically by `useBlok`; exposed for