@bloklabs/react 1.2.1 → 1.2.2

package/src/useBlok.ts

@@ -3,6 +3,13 @@ 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,
+  type BlockPortalRegistry,
+} from './block-portal-registry';
+import { setRegistry, removeRegistry } from './registry-map';
+import { bindLiveToolConfigFunctions } from './live-tool-config';
 import { normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
@@ -18,6 +25,45 @@ 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 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>)) {
+    const toolClass = typeof entry === 'function' ? entry : (entry as { class?: unknown })?.class;
+    const isReactBlock =
+      typeof toolClass === 'function' &&
+      (toolClass as { __isBlokReactBlock?: boolean }).__isBlokReactBlock === true;
+
+    if (!isReactBlock) {
+      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,
+    };
+    result[name] = base;
+  }
+
+  return result;
+};
+
 /**
  * React hook that manages a Blok editor instance lifecycle.
  *
@@ -115,6 +161,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 +183,25 @@ 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 liveTools =
+      currentConfig.tools === undefined
+        ? undefined
+        : injectPortalRegistry(
+            bindLiveToolConfigFunctions(currentConfig.tools, () => configRef.current.tools),
+            registry
+          );
+
     const blokConfig = {
       ...currentConfig,
+      ...(liveTools === undefined ? {} : { tools: liveTools as UseBlokConfig['tools'] }),
       holder,
       onReady: (...args: Parameters<NonNullable<UseBlokConfig['onReady']>>): void => {
         configRef.current.onReady?.(...args);
@@ -182,6 +246,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 +258,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       .catch(() => {
         if (state.editor === blok && !state.isDestroyed) {
           removeHolder(blok);
+          removeRegistry(blok);
           try {
             blok.destroy();
           } catch {
@@ -348,6 +414,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';
@@ -536,3 +537,114 @@ 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> {
+  /** 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. */
+  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;
+  /** Engine-owned child slot — render `<BlockChildren />` for a container block. */
+  BlockChildren: React.ComponentType;
+}
+
+/** Spec for {@link createReactBlock}. */
+export interface CreateReactBlockSpec<Data extends BlockToolData = BlockToolData> {
+  type: string;
+  toolbox?: ToolboxConfig;
+  propSchema: PropSchema;
+  component: React.ComponentType<ReactBlockRenderProps<Data>>;
+  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>(
+  spec: CreateReactBlockSpec<Data>
+): 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';
+
+/** One mounted React block in the portal registry. */
+export interface BlockPortalEntry {
+  hostEl: HTMLElement;
+  component: React.ComponentType<Record<string, unknown>>;
+  props: Record<string, unknown>;
+}
+
+/**
+ * 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;
+  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;