@bloklabs/react 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "React block editor — official React bindings for Blok, the headless Notion-like rich text editor. Hooks and components that render blocks and save to JSON.",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -54,7 +54,7 @@
     "test": "yarn run -T vitest run"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.7.0",
+    "@bloklabs/core": "^1.8.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokContent.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, forwardRef } from 'react';
 import { getHolder } from './holder-map';
 import { getRegistry } from './registry-map';
 import { BlockPortalHost } from './BlockPortalHost';
+import { BlokInstanceContext } from './blok-instance-context';
 import type { Blok } from '@/types';
 import type { BlokContentProps } from './types';
 
@@ -91,11 +92,20 @@ export const BlokContent = forwardRef<HTMLDivElement, BlokContentProps>(
     // 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.
+    //
+    // The instance provider rides along for the same reason: this is the one
+    // place that holds BOTH the live editor and the portal host, so publishing
+    // it here is what lets a block component call `useBlocks(useBlokInstance())`
+    // without the host prop-drilling the instance into every block.
     const registry = editor === null ? undefined : getRegistry(editor);
 
     return (
       <div ref={setRefs} {...divProps}>
-        {registry === undefined ? null : <BlockPortalHost registry={registry} />}
+        {registry === undefined ? null : (
+          <BlokInstanceContext.Provider value={editor}>
+            <BlockPortalHost registry={registry} />
+          </BlokInstanceContext.Provider>
+        )}
       </div>
     );
   }

package/src/block-portal-registry.ts

@@ -47,8 +47,17 @@ export interface BlockPortalRegistry {
    * 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;
+  /**
+   * Remove the entry for `id`. Safe (no-op) when absent.
+   *
+   * Pass the caller's own `hostEl` to make the removal OWNERSHIP-CHECKED: the
+   * entry is deleted only when it is still the one that host registered. Core
+   * composes a replacement block (which registers under the SAME id) BEFORE it
+   * destroys the block it replaces, so a superseded tool's `removed()`/
+   * `destroy()` teardown arrives after the live entry is already in place —
+   * without the check it deletes that live entry and the holder stays empty.
+   */
+  unregister(id: string, hostEl?: HTMLElement): void;
   /** Merge `props` into the entry's props (in-place update, no remount). */
   setProps(id: string, props: Record<string, unknown>): void;
   /**
@@ -92,8 +101,15 @@ export const createBlockPortalRegistry = (): BlockPortalRegistry => {
       );
       commit(next);
     },
-    unregister(id: string): void {
-      if (!state.snapshot.has(id)) {
+    unregister(id: string, hostEl?: HTMLElement): void {
+      const current = state.snapshot.get(id);
+
+      if (current === undefined) {
+        return;
+      }
+
+      // A superseded owner may not evict the entry that replaced it.
+      if (hostEl !== undefined && current.hostEl !== hostEl) {
         return;
       }
 

package/src/blok-instance-context.ts

@@ -0,0 +1,35 @@
+import { createContext, useContext } from 'react';
+import type { Blok } from '@/types';
+
+/**
+ * Carries the LIVE editor instance down to everything `BlokContent` renders —
+ * which, because `createPortal` preserves the COMPONENT tree's context (not the
+ * DOM target's), includes every `createReactBlock` block mounted through the
+ * editor's shared `BlockPortalHost`.
+ *
+ * Null until the instance exists (SSR, first render, between recreations),
+ * matching `useBlok`'s own pre-ready contract.
+ */
+export const BlokInstanceContext = createContext<Blok | null>(null);
+
+/**
+ * The live Blok instance a component is rendered inside, or null before it
+ * exists. Inside a `createReactBlock` component this is the block's OWN editor —
+ * so a block can drive the tree it lives in without the host prop-drilling the
+ * instance into it:
+ *
+ * ```tsx
+ * const blocks = useBlocks(useBlokInstance());
+ * const children = blocks.getChildren(block.id);
+ * ```
+ *
+ * That pairing is also what makes a container block REACTIVE to its own child
+ * tree: `useBlocks` re-renders on the editor's `block changed` event, which core
+ * emits for every structural mutation — including children the adapter itself
+ * never sees (a pasted paragraph, a Tab-indent from the keyboard).
+ *
+ * Outside a `BlokContent`/`BlokEditor` subtree it returns null.
+ */
+export function useBlokInstance(): Blok | null {
+  return useContext(BlokInstanceContext);
+}

package/src/config-keys.ts

@@ -49,6 +49,7 @@ export const USE_BLOK_CONFIG_KEYS = [
   'width',
   'migrations',
   'uploader',
+  'captureClicksBelowEditor',
 ] as const satisfies readonly (keyof UseBlokConfig)[];
 
 /**

package/src/content-baseline-map.ts

@@ -0,0 +1,38 @@
+import type { LooseOutputData, OutputData } from '@/types';
+
+/**
+ * The controlled-content bookkeeping `useBlok` keeps for one editor: the
+ * baseline it believes the editor currently reflects, plus the window of
+ * payloads the editor emitted through `onSave`.
+ *
+ * The declarative `data` effect dedupes against both, which is only sound while
+ * that effect is the ONLY thing changing the content. An imperative
+ * `useBlokHandle().clear()` / `.render()` moves the editor out from under the
+ * bookkeeping: without this channel, restoring a document the editor itself
+ * emitted is dismissed as an echo and never rendered — the editor stays empty
+ * while React state says otherwise. Registered per instance (mirrors the holder
+ * / portal-registry WeakMaps) so the handle can reach it from the editor alone.
+ */
+export interface ContentBaseline {
+  /**
+   * Records `content` as what the editor now reflects and drops every remembered
+   * emitted payload — content the editor emitted BEFORE an out-of-band change is
+   * no longer content it holds, so it must not no-op a later controlled restore.
+   * @param content - the document the editor now reflects
+   */
+  markRendered(content: OutputData | LooseOutputData | null): void;
+}
+
+const baselines = new WeakMap<WeakKey, ContentBaseline>();
+
+export function setContentBaseline(editor: WeakKey, baseline: ContentBaseline): void {
+  baselines.set(editor, baseline);
+}
+
+export function getContentBaseline(editor: WeakKey): ContentBaseline | undefined {
+  return baselines.get(editor);
+}
+
+export function removeContentBaseline(editor: WeakKey): void {
+  baselines.delete(editor);
+}