@bloklabs/react 1.2.1 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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.1",
+    "@bloklabs/core": "^1.2.3",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlockPortalHost.tsx

@@ -0,0 +1,58 @@
+import { Component, useSyncExternalStore, type ReactElement, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import type { BlockPortalRegistry } from './block-portal-registry';
+
+interface BoundaryState {
+  failed: boolean;
+}
+
+/**
+ * Wraps a single block's render so a throw inside it can't tear down the whole
+ * editor's render tree (only the broken block goes blank).
+ */
+class BlockErrorBoundary extends Component<{ children: ReactNode }, BoundaryState> {
+  public state: BoundaryState = { failed: false };
+
+  public static getDerivedStateFromError(): BoundaryState {
+    return { failed: true };
+  }
+
+  public componentDidCatch(): void {
+    // Swallowed: one broken block must not unmount its siblings.
+  }
+
+  public render(): ReactNode {
+    return this.state.failed ? null : this.props.children;
+  }
+}
+
+export interface BlockPortalHostProps {
+  registry: BlockPortalRegistry;
+}
+
+/**
+ * The single shared render tree that portals each registered React block into
+ * its Blok-owned host element. Mounted once per editor (by `BlokContent`), it
+ * subscribes to the registry and emits one `createPortal` per entry — so all
+ * blocks share one reconciler and the surrounding app's React context
+ * (`createPortal` preserves the component tree's context, not the DOM target's).
+ */
+export function BlockPortalHost({ registry }: BlockPortalHostProps): ReactElement {
+  const entries = useSyncExternalStore(registry.subscribe, registry.getSnapshot, registry.getSnapshot);
+
+  return (
+    <>
+      {Array.from(entries.entries()).map(([id, entry]) => {
+        const BlockComponent = entry.component;
+
+        return createPortal(
+          <BlockErrorBoundary>
+            <BlockComponent {...entry.props} />
+          </BlockErrorBoundary>,
+          entry.hostEl,
+          id
+        );
+      })}
+    </>
+  );
+}

package/src/BlokContent.tsx

@@ -1,5 +1,7 @@
 import { useEffect, useRef, forwardRef } from 'react';
 import { getHolder } from './holder-map';
+import { getRegistry } from './registry-map';
+import { BlockPortalHost } from './BlockPortalHost';
 import type { BlokContentProps } from './types';
 
 /**
@@ -41,6 +43,16 @@ export const BlokContent = forwardRef<HTMLDivElement, BlokContentProps>(
       };
     }, [editor]);
 
-    return <div ref={setRefs} {...divProps} />;
+    // The portal host renders the editor's `createReactBlock` tools INSIDE this
+    // component tree (via createPortal into each Blok-owned host element), so
+    // app-level React context flows into block tools with no bridge. It emits
+    // no DOM at this position, leaving the imperatively-adopted holder alone.
+    const registry = editor === null ? undefined : getRegistry(editor);
+
+    return (
+      <div ref={setRefs} {...divProps}>
+        {registry === undefined ? null : <BlockPortalHost registry={registry} />}
+      </div>
+    );
   }
 );

package/src/BlokEditor.tsx

@@ -43,6 +43,14 @@ 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.
+   *
+   * Tool configs do NOT belong here — reserve deps for true identity changes
+   * (e.g. the document id). FUNCTIONS inside tool configs are re-bound to the
+   * latest render's closure automatically (an inline `uploadByFile` with a
+   * fresh identity each render reaches the editor live), and non-function
+   * config VALUES of `createReactBlock` tools (permissions, URLs, locale…) are
+   * pushed to mounted blocks in place when they change. Neither requires
+   * recreation or `useState` identity-freezing.
    */
   deps?: DependencyList;
   /** Test id forwarded to the editor container element (via data-testid). */

package/src/block-portal-registry.ts

@@ -0,0 +1,145 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Tool-config key carrying the editor's portal registry into a
+ * `createReactBlock` tool. The tool is constructed by CORE (outside any React
+ * render), so it cannot read context — `useBlok` injects the editor-scoped
+ * registry through each react-block tool's `config`, and the tool reads it here.
+ */
+export const BLOK_PORTAL_REGISTRY_CONFIG_KEY = '__blokPortalRegistry';
+
+/**
+ * Tool-config key carrying the name the tool was registered under in the
+ * consumer's `tools` map (injected next to the registry). The factory needs it
+ * to associate portal entries with their tool so live config updates can be
+ * routed; it is stripped (with the registry key) before the sanitized config
+ * reaches the component.
+ */
+export const BLOK_TOOL_NAME_CONFIG_KEY = '__blokToolName';
+
+/**
+ * One mounted React block in the portal registry. `hostEl` is the Blok-owned
+ * `toolRenderedElement` (tagged `data-blok-mutation-free`) the component is
+ * portaled into; `props` is replaced immutably by `setProps` so the mounted
+ * component re-renders in place (no remount).
+ */
+export interface BlockPortalEntry {
+  hostEl: HTMLElement;
+  component: 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. A single shared `BlockPortalHost`
+ * renders one `createPortal` per entry, so every block lives in ONE React tree
+ * (shared context, one reconciler) — the TipTap ReactNodeViewRenderer pattern,
+ * not a `createRoot` per block.
+ *
+ * Shaped as an external store (`subscribe`/`getSnapshot`) so the host can read
+ * it through `useSyncExternalStore`. The snapshot is immutable: every mutation
+ * replaces it, and `getSnapshot` is referentially stable between mutations.
+ */
+export interface BlockPortalRegistry {
+  /**
+   * Register (or replace) the entry for `id`. Idempotent: a second register
+   * for the same id replaces the entry rather than mounting a duplicate.
+   */
+  register(id: string, entry: BlockPortalEntry): void;
+  /** Remove the entry for `id`. Safe (no-op) when absent. */
+  unregister(id: string): void;
+  /** Merge `props` into the entry's props (in-place update, no remount). */
+  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 this latest config
+   * instead of their construction-time snapshot.
+   */
+  setToolConfig(toolName: string, config: Record<string, unknown>): void;
+  /** Subscribe to snapshot changes; returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** Current immutable snapshot (stable identity until the next mutation). */
+  getSnapshot(): ReadonlyMap<string, BlockPortalEntry>;
+}
+
+/**
+ * Create a fresh portal registry. One per editor instance (associated via the
+ * registry map, mirroring the holder WeakMap), so multiple editors on a page
+ * never cross-render each other's blocks.
+ */
+export const createBlockPortalRegistry = (): BlockPortalRegistry => {
+  const state = {
+    snapshot: new Map<string, BlockPortalEntry>() as ReadonlyMap<string, BlockPortalEntry>,
+  };
+  const listeners = new Set<() => void>();
+  /** Latest per-tool config, applied to mounted entries and future registers. */
+  const toolConfigs = new Map<string, Record<string, unknown>>();
+
+  const commit = (next: Map<string, BlockPortalEntry>): void => {
+    state.snapshot = next;
+    listeners.forEach(listener => listener());
+  };
+
+  return {
+    register(id: string, entry: BlockPortalEntry): void {
+      const next = new Map(state.snapshot);
+      const liveConfig = entry.toolName === undefined ? undefined : toolConfigs.get(entry.toolName);
+
+      next.set(
+        id,
+        liveConfig === undefined ? entry : { ...entry, props: { ...entry.props, config: liveConfig } }
+      );
+      commit(next);
+    },
+    unregister(id: string): void {
+      if (!state.snapshot.has(id)) {
+        return;
+      }
+
+      const next = new Map(state.snapshot);
+
+      next.delete(id);
+      commit(next);
+    },
+    setProps(id: string, props: Record<string, unknown>): void {
+      const current = state.snapshot.get(id);
+
+      if (current === undefined) {
+        return;
+      }
+
+      const next = new Map(state.snapshot);
+
+      next.set(id, { ...current, props: { ...current.props, ...props } });
+      commit(next);
+    },
+    setToolConfig(toolName: string, config: Record<string, unknown>): void {
+      toolConfigs.set(toolName, config);
+
+      const matching = [...state.snapshot].filter(([, entry]) => entry.toolName === toolName);
+
+      if (matching.length === 0) {
+        return;
+      }
+
+      const next = new Map(state.snapshot);
+
+      for (const [id, entry] of matching) {
+        next.set(id, { ...entry, props: { ...entry.props, config } });
+      }
+
+      commit(next);
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+
+      return (): void => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot(): ReadonlyMap<string, BlockPortalEntry> {
+      return state.snapshot;
+    },
+  };
+};

package/src/createReactBlock.tsx

@@ -0,0 +1,346 @@
+import { useEffect, useRef, type ComponentType, type ReactElement } from 'react';
+import { flushSync } from 'react-dom';
+import { DATA_ATTR, deepEqual, fillDefaults, mountChildBlocks, type PropSchema } from '@bloklabs/core/adapters';
+import {
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+  type BlockPortalRegistry,
+} from './block-portal-registry';
+import type { BlockAPI } from '@/types/api';
+import type { BlockToolConstructorOptions, BlockToolData, ToolboxConfig } from '@/types/tools';
+
+export type { PropSchema, PropSchemaEntry } from '@bloklabs/core/adapters';
+
+/** Adapter-internal config keys, stripped before the config reaches the component. */
+const INTERNAL_CONFIG_KEYS: readonly string[] = [
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+];
+
+/** 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. */
+  commit: (patch: Partial<Data>) => void;
+  /** This block's per-block API (id, connection methods, dispatchChange…). */
+  block: BlockAPI;
+  /**
+   * Read-only flag. Render disabled/inert UI when true (e.g. drop
+   * `contentEditable`, hide controls). Toggled IN PLACE by core's read-only
+   * switch — the component re-renders without remounting, so ephemeral state
+   * survives. Honor it: a block that ignores `readOnly` stays interactive when
+   * the editor is read-only (same contract as a vanilla tool's `setReadOnly`).
+   */
+  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…). No context provider needed. Under `useBlok`/`BlokEditor`
+   * this prop is LIVE: functions always call the latest render's closure, and
+   * changed non-function values are pushed to mounted blocks in place — so
+   * config values never belong in `deps`.
+   */
+  config: Readonly<Partial<Config>>;
+  /** Engine-owned child slot — render `<BlockChildren />` for a container block. */
+  BlockChildren: ComponentType;
+}
+
+/** 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;
+  /** 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 lifecycle callbacks mapped from Blok's block hooks. */
+  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(...) }`).
+ *
+ * The factory owns the host element (`data-blok-mutation-free`), a frozen
+ * defaults-filled data mirror, and the entry props the component reads. It
+ * portals the component into the host via the editor's shared portal registry
+ * (the TipTap `ReactNodeViewRenderer` pattern) — every block renders inside the
+ * SAME React tree that renders `BlokContent`, so app-level context (themes,
+ * design-system providers, stores) flows into blocks with no bridge. Blok's
+ * block lifecycle maps to React:
+ * - `render()` creates the host and registers the portal entry (returned sync).
+ * - `setData()` dedups, pushes the new snapshot, and flushes React's commit
+ *   before resolving `true` — defeating core's default remount.
+ * - `save()` returns the complete frozen mirror (never the DOM, never partial).
+ * - `commit()` merges a patch and fires `dispatchChange` exactly once.
+ * - `removed()`/`destroy()` unregister the portal (deterministic unmount).
+ */
+export function createReactBlock<Data = BlockToolData, Config = Record<string, unknown>>(
+  spec: CreateReactBlockSpec<Data, Config>
+): (new (options: BlockToolConstructorOptions) => {
+  render(): HTMLElement;
+  save(): BlockToolData;
+  setData(newData: BlockToolData): Promise<boolean>;
+  setReadOnly(state: boolean): void;
+  rendered(): void;
+  moved(): void;
+  removed(): void;
+  destroy(): void;
+}) & {
+  readonly __isBlokReactBlock: true;
+  readonly toolbox: ToolboxConfig | undefined;
+  readonly isReadOnlySupported: boolean;
+} {
+  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;
+    }
+
+    /**
+     * React blocks support read-only mode: `setReadOnly` pushes a new prop the
+     * component reads, so the block re-renders read-only IN PLACE. Without this
+     * flag core's ReadOnly module throws a critical error when read-only is
+     * enabled and a React block is present.
+     */
+    public static get isReadOnlySupported(): boolean {
+      return true;
+    }
+
+    private readonly blockApi: BlockAPI;
+    private readonly registry: BlockPortalRegistry | undefined;
+    /** Name this tool is registered under in the consumer's `tools` map. */
+    private readonly toolName: string | undefined;
+    /** The consumer's tool config with adapter-internal keys stripped. */
+    private readonly toolConfig: Readonly<Partial<Config>>;
+    private readonly pointerDrag: () => boolean;
+    private readonly childrenComponent: ComponentType;
+    private mirror: Readonly<Data>;
+    /** Dedup baseline: skip a redundant render of identical data. */
+    private lastRendered: Readonly<Data>;
+    /** Read-only flag mirrored into the entry props by setReadOnly. */
+    private readOnly: boolean;
+    private hostEl: HTMLElement | null = null;
+    /** True while a deferred dispatch is waiting for a pointer drag to end. */
+    private pendingDispatch = false;
+
+    public constructor(options: BlockToolConstructorOptions) {
+      this.blockApi = options.block;
+
+      const config = (options.config ?? {}) as Record<string, unknown>;
+
+      this.registry = config[BLOK_PORTAL_REGISTRY_CONFIG_KEY] as BlockPortalRegistry | undefined;
+      const toolName = config[BLOK_TOOL_NAME_CONFIG_KEY];
+
+      this.toolName = typeof toolName === 'string' ? toolName : undefined;
+
+      const publicConfig: Record<string, unknown> = {};
+
+      for (const [key, value] of Object.entries(config)) {
+        if (!INTERNAL_CONFIG_KEYS.includes(key)) {
+          publicConfig[key] = value;
+        }
+      }
+      this.toolConfig = Object.freeze(publicConfig) as Readonly<Partial<Config>>;
+
+      // Read the LIVE pointer-drag flag so a mid-drag commit can be deferred
+      // (core silently drops a dispatchChange while a drag is active).
+      const api = options.api as unknown as { blocks?: { isPointerDragActive?: boolean } } | undefined;
+
+      this.pointerDrag = (): boolean => api?.blocks?.isPointerDragActive === true;
+
+      this.mirror = fillDefaults<Data>(spec.propSchema, (options.data ?? {}) as Record<string, unknown>);
+      this.lastRendered = this.mirror;
+      this.readOnly = options.readOnly;
+
+      const blockApi = this.blockApi;
+
+      // Per-instance child slot: a childless ref'd div Blok owns; mountChildBlocks
+      // appends the real child holders imperatively (React never reconciles them).
+      this.childrenComponent = function BlockChildren(): ReactElement {
+        const slotRef = useRef<HTMLDivElement | null>(null);
+
+        // No dep array: re-adopt children after EVERY render (mirrors the Vue
+        // adapter's onMounted + onUpdated pair).
+        useEffect(() => {
+          if (slotRef.current !== null) {
+            mountChildBlocks(slotRef.current, blockApi.getChildren());
+          }
+        });
+
+        return <div ref={slotRef} {...{ [DATA_ATTR.nestedBlocks]: '' }} />;
+      };
+    }
+
+    public render(): HTMLElement {
+      const host = document.createElement('div');
+
+      // The Blok-owned host: React reconciles the chrome portaled INTO it, but
+      // this attribute makes core's MutationObserver ignore those mutations, so
+      // React's reconciliation never registers as a user edit.
+      host.setAttribute('data-blok-mutation-free', 'true');
+      this.hostEl = host;
+
+      this.registry?.register(this.blockApi.id, {
+        hostEl: host,
+        component: spec.component as unknown as ComponentType<Record<string, unknown>>,
+        props: this.buildProps(),
+        toolName: this.toolName,
+      });
+
+      // Returned synchronously; React flushes the portal on its next commit.
+      return host;
+    }
+
+    public rendered(): void {
+      spec.onRendered?.(this.blockApi);
+    }
+
+    public save(): BlockToolData {
+      // The complete, frozen mirror — never the DOM, never partial.
+      return this.mirror as BlockToolData;
+    }
+
+    public async setData(newData: BlockToolData): Promise<boolean> {
+      const next = fillDefaults<Data>(spec.propSchema, newData ?? {});
+
+      // Dedup: identical data → skip the render entirely, but still return true
+      // so core keeps the block in place (no remount).
+      if (deepEqual(next, this.lastRendered)) {
+        return true;
+      }
+
+      this.mirror = next;
+      this.lastRendered = next;
+
+      // Flush React's commit before resolving. Core drives setData inside its
+      // RAF-extended Yjs-suppression window, so the re-render must land before
+      // suppression lifts — without ever remounting.
+      this.pushProps({ data: next });
+
+      return true;
+    }
+
+    /**
+     * In-place read-only toggle. Pushes a new `readOnly` prop the component
+     * reads, so the block re-renders read-only WITHOUT a remount (ephemeral
+     * component state survives). A regular prototype method (not an arrow
+     * field) so core's `supportsInPlaceReadOnly` — which probes the
+     * constructable's PROTOTYPE for `setReadOnly` — selects the in-place path.
+     */
+    public setReadOnly(state: boolean): void {
+      this.readOnly = state;
+      this.pushProps({ readOnly: state });
+    }
+
+    public moved(): void {
+      // No remount: Blok relocates the host element; the portal follows it.
+      spec.onMoved?.(this.blockApi);
+    }
+
+    public removed(): void {
+      this.registry?.unregister(this.blockApi.id);
+      spec.onRemoved?.(this.blockApi);
+    }
+
+    public destroy(): void {
+      // Idempotent with removed(); unregister is safe when already absent.
+      this.registry?.unregister(this.blockApi.id);
+    }
+
+    /** The full entry props handed to the component on (re-)register. */
+    private buildProps(): Record<string, unknown> {
+      const props: ReactBlockRenderProps<Data, Config> = {
+        data: this.mirror,
+        commit: this.commit,
+        block: this.blockApi,
+        readOnly: this.readOnly,
+        config: this.toolConfig,
+        BlockChildren: this.childrenComponent,
+      };
+
+      return props as unknown as Record<string, unknown>;
+    }
+
+    /** Push a prop patch to the mounted component and flush React's commit. */
+    private pushProps(props: Record<string, unknown>): void {
+      const registry = this.registry;
+
+      if (registry === undefined) {
+        return;
+      }
+
+      // setData/setReadOnly arrive from core outside React's render phase, so a
+      // synchronous flush is safe and makes the DOM update deterministic.
+      flushSync(() => {
+        registry.setProps(this.blockApi.id, props);
+      });
+    }
+
+    /**
+     * The only data write path. Merges the patch into the frozen mirror, pushes
+     * the new snapshot, records the dedup baseline, and fires dispatchChange
+     * EXACTLY once — deferring it while a pointer drag is active (core would
+     * otherwise silently drop it).
+     */
+    private readonly commit = (patch: Partial<Data>): void => {
+      const next = fillDefaults<Data>(spec.propSchema, {
+        ...(this.mirror as Record<string, unknown>),
+        ...(patch as Record<string, unknown>),
+      });
+
+      // Idempotent: a patch that changes nothing is a full no-op — no props
+      // push, no dispatchChange. This is what makes an effect that echoes the
+      // current value back through commit safe without a consumer-side guard
+      // (an unguarded echo would otherwise loop commit → render → effect).
+      if (deepEqual(next, this.mirror)) {
+        return;
+      }
+
+      this.mirror = next;
+      this.lastRendered = next;
+      // No flushSync here: commit is called from React event handlers (inside a
+      // render batch), where a sync flush is illegal — the normal async commit
+      // is fine because the change originates from the component itself.
+      this.registry?.setProps(this.blockApi.id, { data: next });
+
+      this.flushDispatch();
+    };
+
+    /** Dispatch the change, or retry on the next frame if a drag is in progress. */
+    private flushDispatch(): void {
+      if (!this.pointerDrag()) {
+        this.pendingDispatch = false;
+        this.blockApi.dispatchChange();
+
+        return;
+      }
+
+      if (this.pendingDispatch) {
+        return;
+      }
+
+      this.pendingDispatch = true;
+
+      const retry = (): void => {
+        if (this.pointerDrag()) {
+          requestAnimationFrame(retry);
+
+          return;
+        }
+
+        this.pendingDispatch = false;
+        this.blockApi.dispatchChange();
+      };
+
+      requestAnimationFrame(retry);
+    }
+  };
+}

package/src/index.ts

@@ -5,6 +5,21 @@ export { BlokProvider, useBlokDefaults } from './provide-blok';
 export type { UseBlokConfig, BlokContentProps } from './types';
 export type { BlokEditorProps } from './BlokEditor';
 export { useBlocks } from './useBlocks';
+export { createReactBlock } from './createReactBlock';
+export type {
+  CreateReactBlockSpec,
+  ReactBlockRenderProps,
+  PropSchema,
+  PropSchemaEntry,
+} from './createReactBlock';
+export {
+  createBlockPortalRegistry,
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+} from './block-portal-registry';
+export type { BlockPortalRegistry, BlockPortalEntry } from './block-portal-registry';
+export { BlockPortalHost } from './BlockPortalHost';
+export type { BlockPortalHostProps } from './BlockPortalHost';
 export type {
   BlockNode,
   CaretTarget,