@bloklabs/react 1.2.1 → 1.2.3

package/src/live-tool-config.ts

@@ -0,0 +1,154 @@
+/**
+ * Live tool-config functions: the reason a consumer should never have to freeze
+ * callback identities (`useState(() => ...)`) or recreate the editor to get
+ * fresh closures into tool configs.
+ *
+ * Core snapshots each tool's config when a block instance is constructed
+ * (`ToolClass.settings` builds a merged copy), so a function passed in `tools`
+ * at editor construction would otherwise be pinned forever — consumers worked
+ * around it by freezing identities and smuggling live values through external
+ * stores. Instead, `useBlok` hands core STABLE wrapper functions that delegate
+ * to whatever closure the LATEST render passed at the same config path. New
+ * render → new closure → the wrapper calls it; the editor is never recreated.
+ */
+
+type AnyFunction = (...args: unknown[]) => unknown;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const proto: unknown = Object.getPrototypeOf(value);
+
+  return proto === Object.prototype || proto === null;
+};
+
+/** Walk `root` down `path`, returning undefined the moment the shape diverges. */
+const resolveAtPath = (root: unknown, path: readonly (string | number)[]): unknown =>
+  path.reduce<unknown>((node, key) => {
+    if (Array.isArray(node)) {
+      return typeof key === 'number' ? node[key] : undefined;
+    }
+
+    if (isPlainObject(node)) {
+      return node[key];
+    }
+
+    return undefined;
+  }, root);
+
+/**
+ * Build the component-facing `config` for a react block from the LATEST render's
+ * raw config, preferring the stable live wrapper from `wrappedConfig` wherever
+ * both sides hold a function at the same path. The result carries the newest
+ * non-function VALUES while keeping function identities stable across renders
+ * (wrappers already delegate to the latest closure), so a deep-equal dedupe of
+ * successive results only fires when a value genuinely changed.
+ */
+export const buildLiveBlockConfig = (
+  wrappedConfig: unknown,
+  latestConfig: unknown
+): Record<string, unknown> => {
+  const merge = (latest: unknown, wrapped: unknown): unknown => {
+    if (typeof latest === 'function') {
+      return typeof wrapped === 'function' ? wrapped : latest;
+    }
+
+    if (Array.isArray(latest)) {
+      const wrappedArray = Array.isArray(wrapped) ? wrapped : [];
+
+      return latest.map((item, index) => merge(item, wrappedArray[index]));
+    }
+
+    if (isPlainObject(latest)) {
+      const wrappedObject = isPlainObject(wrapped) ? wrapped : {};
+      const result: Record<string, unknown> = {};
+
+      for (const [key, value] of Object.entries(latest)) {
+        result[key] = merge(value, wrappedObject[key]);
+      }
+
+      return result;
+    }
+
+    return latest;
+  };
+
+  const merged = merge(latestConfig, wrappedConfig);
+
+  return isPlainObject(merged) ? merged : {};
+};
+
+/**
+ * Return a copy of `tools` where every function inside a tool's `config` is
+ * replaced by a stable wrapper that calls the function found at the same path
+ * in `getLatestTools()` (falling back to the construction-time original when
+ * the latest config no longer carries one). Tool classes and non-function
+ * values pass through untouched; the consumer's objects are never mutated.
+ */
+export const bindLiveToolConfigFunctions = (tools: unknown, getLatestTools: () => unknown): unknown => {
+  if (!isPlainObject(tools)) {
+    return tools;
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [name, entry] of Object.entries(tools)) {
+    if (!isPlainObject(entry) || !isPlainObject(entry.config)) {
+      result[name] = entry;
+
+      continue;
+    }
+
+    const seen = new WeakSet();
+
+    const wrapNode = (node: unknown, path: readonly (string | number)[]): unknown => {
+      if (typeof node === 'function') {
+        const original = node as AnyFunction;
+
+        return function liveConfigFunction(this: unknown, ...args: unknown[]): unknown {
+          const latestTools = getLatestTools();
+          const latestEntry = isPlainObject(latestTools) ? latestTools[name] : undefined;
+          const latestConfig = isPlainObject(latestEntry) ? latestEntry.config : undefined;
+          const latest = resolveAtPath(latestConfig, path);
+          const target = typeof latest === 'function' ? (latest as AnyFunction) : original;
+
+          // Preserve the call-site `this` (config functions may be invoked as
+          // methods of their config object).
+          return Reflect.apply(target, this, args);
+        };
+      }
+
+      if (Array.isArray(node)) {
+        if (seen.has(node)) {
+          return node;
+        }
+        seen.add(node);
+
+        return node.map((item, index) => wrapNode(item, [...path, index]));
+      }
+
+      if (isPlainObject(node)) {
+        if (seen.has(node)) {
+          return node;
+        }
+        seen.add(node);
+
+        const wrapped: Record<string, unknown> = {};
+
+        for (const [key, value] of Object.entries(node)) {
+          wrapped[key] = wrapNode(value, [...path, key]);
+        }
+
+        return wrapped;
+      }
+
+      return node;
+    };
+
+    result[name] = { ...entry, config: wrapNode(entry.config, []) };
+  }
+
+  return result;
+};

package/src/registry-map.ts

@@ -0,0 +1,21 @@
+import type { BlockPortalRegistry } from './block-portal-registry';
+
+/**
+ * Associates each live Blok instance with its portal registry, keyed by the
+ * editor (mirrors the holder WeakMap). `useBlok` sets it at creation;
+ * `BlokContent` reads it to mount the shared `BlockPortalHost`. WeakMap → no
+ * leak on destroy.
+ */
+const registries = new WeakMap<WeakKey, BlockPortalRegistry>();
+
+export function setRegistry(editor: WeakKey, registry: BlockPortalRegistry): void {
+  registries.set(editor, registry);
+}
+
+export function getRegistry(editor: WeakKey): BlockPortalRegistry | undefined {
+  return registries.get(editor);
+}
+
+export function removeRegistry(editor: WeakKey): void {
+  registries.delete(editor);
+}

package/src/useBlok.ts

@@ -3,6 +3,14 @@ import { Blok as BlokRuntime } from '@bloklabs/core';
 import { setHolder, removeHolder } from './holder-map';
 import { deepEqual } from './deep-equal';
 import { BlokDefaultsContext, mergeBlokDefaults } from './provide-blok';
+import {
+  createBlockPortalRegistry,
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+  type BlockPortalRegistry,
+} from './block-portal-registry';
+import { setRegistry, removeRegistry } from './registry-map';
+import { bindLiveToolConfigFunctions, buildLiveBlockConfig } from './live-tool-config';
 import { normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
@@ -18,6 +26,50 @@ interface EditorInstanceState {
   depsToken: Record<string, unknown> | null;
 }
 
+/**
+ * Inject the editor's portal registry into every `createReactBlock` tool's
+ * config (vanilla tools are left untouched), returning a NEW tools object so
+ * the consumer's config is never mutated. A react-block tool is constructed by
+ * CORE, outside any React render, so it cannot read context — this config
+ * bridge is how the tool reaches its editor-scoped registry.
+ */
+const isReactBlockEntry = (entry: unknown): boolean => {
+  const toolClass = typeof entry === 'function' ? entry : (entry as { class?: unknown })?.class;
+
+  return (
+    typeof toolClass === 'function' &&
+    (toolClass as { __isBlokReactBlock?: boolean }).__isBlokReactBlock === true
+  );
+};
+
+const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): unknown => {
+  if (tools === null || typeof tools !== 'object') {
+    return tools;
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [name, entry] of Object.entries(tools as Record<string, unknown>)) {
+    if (!isReactBlockEntry(entry)) {
+      result[name] = entry;
+
+      continue;
+    }
+
+    const base: Record<string, unknown> =
+      typeof entry === 'function' ? { class: entry } : { ...(entry as Record<string, unknown>) };
+
+    base.config = {
+      ...((base.config as Record<string, unknown> | undefined) ?? {}),
+      [BLOK_PORTAL_REGISTRY_CONFIG_KEY]: registry,
+      [BLOK_TOOL_NAME_CONFIG_KEY]: name,
+    };
+    result[name] = base;
+  }
+
+  return result;
+};
+
 /**
  * React hook that manages a Blok editor instance lifecycle.
  *
@@ -76,6 +128,12 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   // success baseline — so a failed render can't strand the baseline on content
   // the editor never actually showed.
   const pendingDataRef = useRef<UseBlokConfig['data']>(undefined);
+  // Live block-config channel (see the sync effect below): the current editor's
+  // portal registry, its construction-time wrapped tools (stable function
+  // wrappers), and the last config pushed per tool name (dedupe baseline).
+  const liveRegistryRef = useRef<BlockPortalRegistry | null>(null);
+  const wrappedToolsRef = useRef<unknown>(undefined);
+  const pushedBlockConfigsRef = useRef<Map<string, Record<string, unknown>>>(new Map());
 
   // Main lifecycle effect
   useEffect(() => {
@@ -115,6 +173,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     // Destroy leftover editor from a previous deps cycle
     if (state.editor !== null && !state.isDestroyed) {
       removeHolder(state.editor);
+      removeRegistry(state.editor);
       try {
         state.editor.destroy();
       } catch {
@@ -136,8 +195,29 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
 
     // Wrap callbacks via ref so they never go stale
     const currentConfig = configRef.current;
+
+    // Per-editor portal registry for `createReactBlock` tools: injected into
+    // each react-block tool's config (so the core-constructed tool can reach
+    // it) and associated with the editor below (so BlokContent can mount the
+    // shared portal host). Tool-config FUNCTIONS are first re-bound to stable
+    // wrappers that always call the latest render's closure — so consumers
+    // never need to freeze identities or recreate the editor to update them.
+    const registry = createBlockPortalRegistry();
+    const wrappedTools =
+      currentConfig.tools === undefined
+        ? undefined
+        : bindLiveToolConfigFunctions(currentConfig.tools, () => configRef.current.tools);
+    const liveTools = wrappedTools === undefined ? undefined : injectPortalRegistry(wrappedTools, registry);
+
+    // Reset the live block-config channel for this editor: the sync effect below
+    // reads these to push changed non-function config VALUES to mounted blocks.
+    liveRegistryRef.current = registry;
+    wrappedToolsRef.current = wrappedTools;
+    pushedBlockConfigsRef.current = new Map();
+
     const blokConfig = {
       ...currentConfig,
+      ...(liveTools === undefined ? {} : { tools: liveTools as UseBlokConfig['tools'] }),
       holder,
       onReady: (...args: Parameters<NonNullable<UseBlokConfig['onReady']>>): void => {
         configRef.current.onReady?.(...args);
@@ -182,6 +262,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     // tell a genuine post-construction change from the construction value itself.
     constructedDataRef.current = currentConfig.data;
     setHolder(blok, holder);
+    setRegistry(blok, registry);
 
     void blok.isReady
       .then(() => {
@@ -193,6 +274,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       .catch(() => {
         if (state.editor === blok && !state.isDestroyed) {
           removeHolder(blok);
+          removeRegistry(blok);
           try {
             blok.destroy();
           } catch {
@@ -211,6 +293,58 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     };
   }, [depsToken]);
 
+  // Live tool-config VALUES for react blocks. Function slots are already live
+  // via the stable wrappers, but non-function values (permissions, URLs,
+  // locale…) were snapshotted at construction — which forced consumers to put
+  // them in `deps` and recreate the whole editor to change them. Instead, this
+  // effect runs on every render, rebuilds each react-block tool's
+  // component-facing config from the LATEST render's values (keeping wrapper
+  // identities for functions), and pushes it through the portal registry when
+  // it genuinely changed — mounted blocks re-render in place, future blocks
+  // start from the latest config.
+  useEffect(() => {
+    const registry = liveRegistryRef.current;
+    const state = stateRef.current;
+
+    if (registry === null || state.editor === null || state.isDestroyed) {
+      return;
+    }
+
+    const latestTools = configRef.current.tools as Record<string, unknown> | undefined;
+
+    if (latestTools === null || typeof latestTools !== 'object') {
+      return;
+    }
+
+    const wrappedTools = wrappedToolsRef.current as Record<string, unknown> | undefined;
+
+    for (const [name, entry] of Object.entries(latestTools)) {
+      if (!isReactBlockEntry(entry)) {
+        continue;
+      }
+
+      const latestConfig =
+        typeof entry === 'function' ? {} : ((entry as { config?: unknown }).config ?? {});
+      const wrappedEntry = wrappedTools?.[name];
+      const wrappedConfig =
+        wrappedEntry !== null && typeof wrappedEntry === 'object'
+          ? (wrappedEntry as { config?: unknown }).config
+          : undefined;
+
+      const candidate = buildLiveBlockConfig(wrappedConfig, latestConfig);
+      const pushed = pushedBlockConfigsRef.current.get(name);
+
+      if (pushed !== undefined && deepEqual(candidate, pushed)) {
+        continue;
+      }
+
+      const frozen = Object.freeze(candidate);
+
+      pushedBlockConfigsRef.current.set(name, frozen);
+      registry.setToolConfig(name, frozen);
+    }
+  });
+
   // Reactive: readOnly (object form normalized so the effect dep is a stable boolean)
   const readOnlyEnabled = normalizeReadOnlyConfig(config.readOnly).enabled;
   useEffect(() => {
@@ -348,6 +482,7 @@ function deferDestroy(
   state.destroyTimeout = setTimeout(() => {
     if (state.editor !== null) {
       removeHolder(state.editor);
+      removeRegistry(state.editor);
       try {
         state.editor.destroy();
       } catch {

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { BlokConfig, BlockToolData, OutputBlockData, OutputData } from '@bloklabs/core';
+import type { BlockAPI, BlockToolConstructable, ToolboxConfig } 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';
@@ -38,7 +39,7 @@ export interface BlokContentProps extends React.HTMLAttributes<HTMLDivElement> {
  * React hook that creates and manages a Blok editor instance.
  *
  * @param config - Editor configuration (all BlokConfig props except `holder`)
- * @param deps - Optional dependency array. When any dep changes, the editor is destroyed and recreated. Keep each value referentially stable (primitives or useMemo-stable objects) so the editor isn't recreated every render.
+ * @param deps - Optional dependency array. When any dep changes, the editor is destroyed and recreated. Keep each value referentially stable (primitives or useMemo-stable objects) so the editor isn't recreated every render. Reserve it for true identity changes (e.g. the document id): tool-config functions are re-bound to the latest render's closure automatically, and non-function config values of `createReactBlock` tools are pushed to mounted blocks in place — neither belongs in deps.
  * @returns The Blok editor instance, or null during SSR / before initialization.
  *
  * @example
@@ -80,6 +81,8 @@ export interface BlokEditorProps
    * 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.
+   * Reserve it for true identity changes (e.g. the document id): tool-config
+   * functions and `createReactBlock` config values stay live without it.
    */
   deps?: React.DependencyList;
   /** Test id forwarded to the editor container element (via data-testid). */
@@ -536,3 +539,144 @@ export interface UseBlocksApi {
  * @param editor - the Blok instance from useBlok, or null before it is ready
  */
 export declare function useBlocks(editor: Blok | null): UseBlocksApi;
+
+// ---------------------------------------------------------------------------
+// Block authoring (createReactBlock + portal host)
+// ---------------------------------------------------------------------------
+
+/** One field of a {@link CreateReactBlockSpec.propSchema}. */
+export interface PropSchemaEntry {
+  default: unknown;
+  values?: readonly unknown[];
+}
+
+/**
+ * Declarative data shape. Its keys are EXACTLY the keys `save()` returns to Yjs
+ * (a cleared field is written as its default, never dropped).
+ */
+export type PropSchema = Record<string, PropSchemaEntry>;
+
+/** Props handed to a React block's `component` (the only data write path is `commit`). */
+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. Idempotent —
+   * a patch that changes nothing is a full no-op (no re-render, no change
+   * event), so effects may safely echo current values without a guard.
+   */
+  commit: (patch: Partial<Data>) => void;
+  /** This block's per-block API. */
+  block: BlockAPI;
+  /**
+   * Read-only flag. Toggled IN PLACE by core's read-only switch (no remount,
+   * ephemeral state survives). Honor it — a block that ignores it stays
+   * interactive when the editor is read-only.
+   */
+  readOnly: boolean;
+  /**
+   * The tool's `config` from the consumer's `tools` map (adapter-internal keys
+   * stripped) — the first-class channel for host props (permissions, CDN/upload
+   * URLs, locale…). LIVE under `useBlok`/`BlokEditor`: functions always call
+   * the latest render's closure, and changed non-function values are pushed to
+   * mounted blocks in place — config values never belong in `deps`.
+   */
+  config: Readonly<Partial<Config>>;
+  /** Engine-owned child slot — render `<BlockChildren />` for a container block. */
+  BlockChildren: React.ComponentType;
+}
+
+/** Spec for {@link createReactBlock}. */
+export interface CreateReactBlockSpec<
+  Data extends BlockToolData = BlockToolData,
+  Config = Record<string, unknown>
+> {
+  type: string;
+  toolbox?: ToolboxConfig;
+  propSchema: PropSchema;
+  component: React.ComponentType<ReactBlockRenderProps<Data, Config>>;
+  onRendered?: (block: BlockAPI) => void;
+  onMoved?: (block: BlockAPI) => void;
+  onRemoved?: (block: BlockAPI) => void;
+}
+
+/**
+ * Author a first-party React block: returns a `BlockToolConstructable`
+ * registered exactly like a vanilla tool (`tools: { type: createReactBlock(...) }`).
+ * Every block renders through the editor's shared portal host INSIDE the React
+ * tree that renders `BlokContent`/`BlokEditor`, so app-level context (themes,
+ * design-system providers, stores) reaches block components with no bridge, and
+ * fresh render closures reach them with no editor recreation.
+ *
+ * @example
+ * ```tsx
+ * const Callout = createReactBlock<{ text: string }>({
+ *   type: 'callout',
+ *   propSchema: { text: { default: '' } },
+ *   component: ({ data, commit }) => (
+ *     <aside onClick={() => commit({ text: 'hi' })}>{data.text}</aside>
+ *   ),
+ * });
+ * ```
+ */
+export declare function createReactBlock<
+  Data extends BlockToolData = BlockToolData,
+  Config = Record<string, unknown>
+>(spec: CreateReactBlockSpec<Data, Config>): BlockToolConstructable;
+
+/**
+ * Tool-config key carrying the editor's portal registry into a
+ * `createReactBlock` tool. Injected automatically by `useBlok`; exposed for
+ * advanced setups that construct tools outside `useBlok`.
+ */
+export declare const BLOK_PORTAL_REGISTRY_CONFIG_KEY: '__blokPortalRegistry';
+
+/**
+ * Tool-config key carrying the name a react-block tool is registered under in
+ * the consumer's `tools` map. Injected automatically by `useBlok`; routes live
+ * tool-config updates to the tool's mounted blocks.
+ */
+export declare const BLOK_TOOL_NAME_CONFIG_KEY: '__blokToolName';
+
+/** One mounted React block in the portal registry. */
+export interface BlockPortalEntry {
+  hostEl: HTMLElement;
+  component: React.ComponentType<Record<string, unknown>>;
+  props: Record<string, unknown>;
+  /** Name the tool is registered under — routes per-tool live config updates. */
+  toolName?: string;
+}
+
+/**
+ * Per-editor registry of React blocks, shaped as an external store
+ * (`subscribe`/`getSnapshot`) consumed by `BlockPortalHost` via
+ * `useSyncExternalStore`. Snapshots are immutable and referentially stable
+ * between mutations.
+ */
+export interface BlockPortalRegistry {
+  register(id: string, entry: BlockPortalEntry): void;
+  unregister(id: string): void;
+  setProps(id: string, props: Record<string, unknown>): void;
+  /**
+   * Replace the `config` prop of every entry registered under `toolName`, and
+   * remember it so entries registered later start from the latest config.
+   */
+  setToolConfig(toolName: string, config: Record<string, unknown>): void;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): ReadonlyMap<string, BlockPortalEntry>;
+}
+
+/** Create a fresh portal registry (one per editor instance). */
+export declare function createBlockPortalRegistry(): BlockPortalRegistry;
+
+/** Props for {@link BlockPortalHost}. */
+export interface BlockPortalHostProps {
+  registry: BlockPortalRegistry;
+}
+
+/**
+ * The single shared render tree that portals each registered React block into
+ * its Blok-owned host element. Mounted automatically by `BlokContent`; exposed
+ * for advanced setups that manage the registry themselves.
+ */
+export declare function BlockPortalHost(props: BlockPortalHostProps): React.ReactElement;