@bloklabs/react 1.1.1

package/src/index.ts

@@ -0,0 +1,16 @@
+export { useBlok } from './useBlok';
+export { BlokContent } from './BlokContent';
+export { BlokEditor } from './BlokEditor';
+export { BlokProvider, useBlokDefaults } from './provide-blok';
+export type { UseBlokConfig, BlokContentProps } from './types';
+export type { BlokEditorProps } from './BlokEditor';
+export { useBlocks } from './useBlocks';
+export type {
+  BlockNode,
+  CaretTarget,
+  InsertSpec,
+  TreeInsertSpec,
+  InsertPosition,
+  MoveTarget,
+  UseBlocksApi,
+} from './blocks-snapshot';

package/src/provide-blok.tsx

@@ -0,0 +1,70 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import type { UseBlokConfig } from './types';
+
+/**
+ * Context holding app-wide Blok defaults (shared tools registry, default theme,
+ * i18n). Merged UNDER per-instance config by `useBlok` / `<BlokEditor>`. Mirrors
+ * Vue's and Angular's `provideBlok`.
+ */
+export const BlokDefaultsContext = createContext<Partial<UseBlokConfig>>({});
+
+/**
+ * Registers app-wide Blok defaults for every `useBlok` / `<BlokEditor>` rendered
+ * beneath it. Per-instance config overrides these, and the `tools` registry is
+ * merged (shared registry composes with per-instance additions) rather than
+ * replaced. Mirrors Vue's and Angular's `provideBlok`.
+ *
+ * @example
+ * ```tsx
+ * <BlokProvider defaults={{ theme: 'dark', tools: sharedTools }}>
+ *   <App />
+ * </BlokProvider>
+ * ```
+ */
+export function BlokProvider({
+  defaults,
+  children,
+}: {
+  defaults: Partial<UseBlokConfig>;
+  children?: ReactNode;
+}): React.ReactElement {
+  return <BlokDefaultsContext.Provider value={defaults}>{children}</BlokDefaultsContext.Provider>;
+}
+
+/** Reads the app-wide Blok defaults from the nearest `BlokProvider` (or `{}`). */
+export function useBlokDefaults(): Partial<UseBlokConfig> {
+  return useContext(BlokDefaultsContext);
+}
+
+/**
+ * Merge app-wide `defaults` UNDER a per-instance `config`: a defined config value
+ * overrides the default, and the `tools` registry is merged across both layers.
+ * Returns the original `config` reference when there are no defaults, so the
+ * no-provider path stays identity-stable (no spurious editor recreation).
+ */
+export function mergeBlokDefaults(
+  defaults: Partial<UseBlokConfig>,
+  config: UseBlokConfig
+): UseBlokConfig {
+  if (Object.keys(defaults).length === 0) {
+    return config;
+  }
+
+  const merged: Record<string, unknown> = { ...defaults };
+
+  for (const key of Object.keys(config)) {
+    const value = (config as Record<string, unknown>)[key];
+
+    if (value !== undefined) {
+      merged[key] = value;
+    }
+  }
+
+  // tools registries MERGE across layers (a shared registry composes with
+  // per-instance additions) rather than the instance replacing the default.
+  if (defaults.tools !== undefined || config.tools !== undefined) {
+    merged.tools = { ...defaults.tools, ...config.tools };
+  }
+
+  return merged as UseBlokConfig;
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+import type { BlokConfig, Blok, EditorWidth } from '@/types';
+
+/**
+ * Configuration for useBlok hook.
+ * Same as BlokConfig but without `holder` (managed by BlokContent), plus a
+ * React-only reactive `width` prop.
+ *
+ * Reactive props (sync after mount without recreation):
+ * - `readOnly` — calls `editor.readOnly.set(value)`
+ * - `autofocus` — calls `editor.focus()` when changed to true
+ * - `theme` — calls `editor.theme.set(value)`
+ * - `width` — calls `editor.width.set(value)`
+ * - `placeholder` — calls `editor.placeholder.set(value)`
+ * - `data` — re-renders via `editor.render(value)` when content changes
+ *   (deep-equal–deduped and serialized; seeds the initial content at creation)
+ *
+ * The `onSave` config (inherited from `BlokConfig`) is the controlled output
+ * half: it fires with the full serialized `OutputData` on every content change,
+ * so `data` + `onSave` form a controlled component without manual `save()` calls.
+ */
+export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {
+  /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */
+  width?: EditorWidth;
+}
+
+/**
+ * Props for the BlokContent component.
+ * Extends standard div HTML attributes so className, style, id, etc. pass through.
+ */
+export interface BlokContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The Blok editor instance returned by useBlok. Pass null if editor is not ready yet. */
+  editor: Blok | null;
+}

package/src/useBlocks.ts

@@ -0,0 +1,91 @@
+// packages/react/src/useBlocks.ts
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+
+import type { Blok } from '@/types';
+import { createBlocksApiForEditor, EMPTY_API } from '@bloklabs/core/adapters';
+
+import type { UseBlocksApi } from './blocks-snapshot';
+
+const BLOCK_CHANGED_EVENT = 'block changed';
+
+/**
+ * React hook exposing an id/parentId-relative, reactive view of the block tree.
+ * Re-renders whenever the editor emits 'block changed' — including programmatic
+ * `nest`/`unnest` reparents, which Blok surfaces as a structural mutation.
+ *
+ * The block-tree logic itself is framework-agnostic and lives in the shared
+ * {@link createBlocksApiForEditor} core (one implementation behind both the
+ * React and Vue `useBlocks`, so the two adapters cannot drift). This hook only
+ * supplies React's reactivity wrapper: `useSyncExternalStore` re-renders the
+ * component on 'block changed', and the shared API's reads run live during that
+ * render — so React needs no per-read dependency tracking (the default no-op
+ * `onRead`).
+ *
+ * Reactivity contract: reads refresh ONLY in response to the editor's
+ * 'block changed' event. A mutation that advances the editor state WITHOUT
+ * emitting it (a tool that mutates its own data without a sync, say) would leave
+ * these reads frozen on the previous snapshot until the next emission. The
+ * built-in mutators here all route through paths that emit, so this only bites
+ * out-of-band tool writes.
+ *
+ * Pre-ready contract: while `editor` is null (before `useBlok` resolves) the
+ * returned API is the stable {@link EMPTY_API} — every MUTATOR is a no-op,
+ * `insert`/`getById` return `null`, and `getChildren` returns `[]`. The one
+ * exception is `transact`, which still invokes its callback even pre-ready.
+ * Mutator calls made before the editor is ready are silently dropped, so guard
+ * on a non-null editor (or render-gate on it) when an insert must not be lost.
+ *
+ * Referential stability: the returned API object is stable across renders (it
+ * only changes when `editor` does), but each `getById`/`getChildren` call
+ * allocates fresh `BlockNode` objects/arrays from a live snapshot. Read them in
+ * render and re-read after a change — do NOT put a `getById`/`getChildren`
+ * result (or the api handle) in a `useMemo`/`useEffect` dependency array
+ * expecting it to change identity per mutation; depend on the node `id`s instead.
+ * @param editor - the Blok instance from useBlok, or null before it is ready
+ */
+export function useBlocks(editor: Blok | null): UseBlocksApi {
+  // Monotonic version bumped on every 'block changed'; drives useSyncExternalStore.
+  const versionRef = useRef(0);
+
+  // Reset the monotonic version when the editor INSTANCE changes so a fresh
+  // editor doesn't inherit a stale version from a previous one. Done in render
+  // (idempotent: editorRef is updated in the same pass, so a re-render with the
+  // same editor won't reset again) — safe for useSyncExternalStore, which just
+  // re-reads getSnapshot and re-renders if the value differs.
+  const editorRef = useRef(editor);
+
+  if (editorRef.current !== editor) {
+    editorRef.current = editor;
+    versionRef.current = 0;
+  }
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void): (() => void) => {
+      if (editor === null) {
+        return () => undefined;
+      }
+
+      const handler = (): void => {
+        versionRef.current += 1;
+        onStoreChange();
+      };
+
+      editor.on(BLOCK_CHANGED_EVENT, handler);
+
+      return () => editor.off(BLOCK_CHANGED_EVENT, handler);
+    },
+    [editor]
+  );
+
+  const getSnapshot = useCallback((): number => versionRef.current, []);
+
+  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  // React re-renders the whole component on 'block changed' (above), and the
+  // shared API's reads run live during that render, so no per-read dependency
+  // tracking is needed — the default no-op `onRead` is correct here.
+  return useMemo<UseBlocksApi>(
+    () => (editor === null ? EMPTY_API : createBlocksApiForEditor(editor)),
+    [editor]
+  );
+}

package/src/useBlok.ts

@@ -0,0 +1,365 @@
+import { useState, useEffect, useRef, useMemo, useContext, type DependencyList } from 'react';
+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 { normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
+import type { Blok } from '@/types';
+import type { UseBlokConfig } from './types';
+
+interface EditorInstanceState {
+  editor: Blok | null;
+  holder: HTMLDivElement | null;
+  destroyTimeout: ReturnType<typeof setTimeout> | null;
+  isDestroyed: boolean;
+  /** True once `editor.isReady` has resolved and its API surface is attached. */
+  isEditorReady: boolean;
+  /** Opaque token identifying which deps cycle created this editor */
+  depsToken: Record<string, unknown> | null;
+}
+
+/**
+ * React hook that manages a Blok editor instance lifecycle.
+ *
+ * Creates a detached holder div, instantiates Blok, and returns the instance
+ * once `isReady` resolves. Handles StrictMode double-mount by deferring
+ * destroy via `setTimeout(0)` and cancelling on remount.
+ *
+ * @param config - Blok configuration without `holder` (managed internally)
+ * @param deps - Optional dependency array; when values change, the editor is recreated
+ * @returns The Blok instance once ready, or null during initialization / SSR
+ */
+export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok | null {
+  // App-wide defaults from the nearest <BlokProvider> are merged UNDER the
+  // per-instance config (instance wins; tools registries merge). When no
+  // provider is present this returns `configInput` unchanged.
+  const defaults = useContext(BlokDefaultsContext);
+  const config = mergeBlokDefaults(defaults, configInput);
+
+  const [editor, setEditor] = useState<Blok | null>(null);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const stateRef = useRef<EditorInstanceState>({
+    editor: null,
+    holder: null,
+    destroyTimeout: null,
+    isDestroyed: false,
+    isEditorReady: false,
+    depsToken: null,
+  });
+
+  // A new token is created only when deps change (useMemo compares deps).
+  // StrictMode re-runs see the SAME token. Deps changes produce a NEW token.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const depsToken = useMemo(() => ({}), deps ?? []);
+
+  // Tracks the data the editor currently reflects — set when content is seeded
+  // or rendered (the reactive `data` effect below) AND when the editor emits its
+  // own serialized content via `onSave`. The latter is what makes a controlled
+  // `onSave -> setData -> data` round-trip a no-op: the echoed payload deep-equals
+  // this baseline, so the data effect skips the redundant render() (which would
+  // 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);
+  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
+  // editor identity) so a prop that diverged from the construction value —
+  // undefined-at-mount then loaded, or changed before the editor finished
+  // initializing — still renders instead of being mistaken for the seed.
+  const constructedDataRef = useRef(config.data);
+  const renderChainRef = useRef<Promise<void>>(Promise.resolve());
+  // The content of the render currently queued/in-flight (distinct from
+  // `lastRenderedDataRef`, which tracks the last SUCCESSFULLY rendered content).
+  // Used to dedupe a re-queue of the same in-flight content without advancing the
+  // success baseline — so a failed render can't strand the baseline on content
+  // the editor never actually showed.
+  const pendingDataRef = useRef<UseBlokConfig['data']>(undefined);
+
+  // Main lifecycle effect
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    const state = stateRef.current;
+
+    // Cancel pending deferred destroy (StrictMode remount)
+    if (state.destroyTimeout !== null) {
+      clearTimeout(state.destroyTimeout);
+      state.destroyTimeout = null;
+    }
+
+    // Reuse editor on StrictMode remount (same deps cycle). The construction
+    // effect below only calls setEditor(blok) once `blok.isReady` resolves and
+    // exportAPI() has attached the full instance API (readOnly, focus, etc.).
+    // StrictMode's synchronous cleanup+remount cycle happens well before that
+    // promise can settle, so publishing `state.editor` here unconditionally
+    // exposed a half-constructed instance to every reactive effect (e.g. the
+    // readOnly sync effect calling `.readOnly.set(...)` on an instance whose
+    // API surface wasn't attached yet, throwing). Only reuse it into state
+    // once it's actually known-ready — otherwise leave `editor` as-is and let
+    // the still-pending `isReady.then()` from the original construction (never
+    // torn down, since only its destroy was deferred) publish it for real.
+    if (state.editor !== null && !state.isDestroyed && state.depsToken === depsToken) {
+      if (state.isEditorReady) {
+        setEditor(state.editor);
+      }
+
+      return (): void => {
+        deferDestroy(state, setEditor);
+      };
+    }
+
+    // Destroy leftover editor from a previous deps cycle
+    if (state.editor !== null && !state.isDestroyed) {
+      removeHolder(state.editor);
+      try {
+        state.editor.destroy();
+      } catch {
+        // destroy may throw — still clean up state
+      }
+      state.editor = null;
+      state.holder = null;
+      state.isDestroyed = true;
+      state.isEditorReady = false;
+      setEditor(null);
+    }
+
+    // Create detached holder
+    const holder = document.createElement('div');
+    state.holder = holder;
+    state.isDestroyed = false;
+    state.isEditorReady = false;
+    state.depsToken = depsToken;
+
+    // Wrap callbacks via ref so they never go stale
+    const currentConfig = configRef.current;
+    const blokConfig = {
+      ...currentConfig,
+      holder,
+      onReady: (...args: Parameters<NonNullable<UseBlokConfig['onReady']>>): void => {
+        configRef.current.onReady?.(...args);
+      },
+      onChange: (...args: Parameters<NonNullable<UseBlokConfig['onChange']>>): void => {
+        configRef.current.onChange?.(...args);
+      },
+    };
+
+    // Only attach onSave when the consumer opted in: its mere presence makes the
+    // core serialize on every change batch, so an absent prop must stay absent.
+    // The wrapper reads through the ref so the latest callback is always used.
+    if (currentConfig.onSave) {
+      blokConfig.onSave = (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
+        // Record the editor's own serialized output as the rendered baseline so a
+        // 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];
+        configRef.current.onSave?.(...args);
+      };
+    }
+
+    // onBeforeRender / onAfterRender are opt-in (absent prop must stay absent so
+    // the core skips them). When present, route through the ref so the latest
+    // callback is always used without recreating the editor.
+    if (currentConfig.onBeforeRender) {
+      blokConfig.onBeforeRender = (
+        ...args: Parameters<NonNullable<UseBlokConfig['onBeforeRender']>>
+      ): ReturnType<NonNullable<UseBlokConfig['onBeforeRender']>> =>
+        configRef.current.onBeforeRender?.(...args) ?? args[0];
+    }
+
+    if (currentConfig.onAfterRender) {
+      blokConfig.onAfterRender = (...args: Parameters<NonNullable<UseBlokConfig['onAfterRender']>>): void => {
+        configRef.current.onAfterRender?.(...args);
+      };
+    }
+
+    const blok = new BlokRuntime(blokConfig) as unknown as Blok;
+    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.
+    constructedDataRef.current = currentConfig.data;
+    setHolder(blok, holder);
+
+    void blok.isReady
+      .then(() => {
+        if (state.editor === blok && !state.isDestroyed) {
+          state.isEditorReady = true;
+          setEditor(blok);
+        }
+      })
+      .catch(() => {
+        if (state.editor === blok && !state.isDestroyed) {
+          removeHolder(blok);
+          try {
+            blok.destroy();
+          } catch {
+            // destroy may also throw — still clean up state
+          }
+          state.editor = null;
+          state.holder = null;
+          state.isDestroyed = true;
+          state.isEditorReady = false;
+          setEditor(null);
+        }
+      });
+
+    return (): void => {
+      deferDestroy(state, setEditor);
+    };
+  }, [depsToken]);
+
+  // Reactive: readOnly (object form normalized so the effect dep is a stable boolean)
+  const readOnlyEnabled = normalizeReadOnlyConfig(config.readOnly).enabled;
+  useEffect(() => {
+    if (editor === null) {
+      return;
+    }
+    void editor.readOnly.set(readOnlyEnabled);
+  }, [editor, readOnlyEnabled]);
+
+  // Reactive: autofocus
+  const { autofocus } = config;
+  useEffect(() => {
+    if (editor === null || !autofocus) {
+      return;
+    }
+    editor.focus();
+  }, [editor, autofocus]);
+
+  // Reactive: theme
+  const { theme } = config;
+  useEffect(() => {
+    if (editor === null || theme === undefined) {
+      return;
+    }
+    editor.theme.set(theme);
+  }, [editor, theme]);
+
+  // Reactive: width
+  const { width } = config;
+  useEffect(() => {
+    if (editor === null || width === undefined) {
+      return;
+    }
+    editor.width.set(width);
+  }, [editor, width]);
+
+  // Reactive: placeholder
+  const { placeholder } = config;
+  useEffect(() => {
+    if (editor === null || placeholder === undefined) {
+      return;
+    }
+    editor.placeholder.set(placeholder);
+  }, [editor, placeholder]);
+
+  // Reactive: data (controlled content)
+  //
+  // `data` seeds the editor at construction. Afterwards, changing the prop to
+  // new *content* re-renders the editor via the public render() API — no
+  // recreation. Updates are deep-equal–deduped against the editor's current
+  // content baseline (`lastRenderedDataRef`, declared above and also updated by
+  // the `onSave` wrapper) so a new reference with the same content — including
+  // the editor's own serialized output echoed back — is a no-op and won't
+  // clobber the caret. Renders are serialized so rapid changes can't overlap.
+  const { data } = config;
+  useEffect(() => {
+    if (editor === null || data === undefined) {
+      return;
+    }
+
+    // The lifecycle effect runs BEFORE this one, so a commit that changes `deps`
+    // AND `data` together has already swapped `state.editor` to the freshly
+    // constructed instance (and may have destroyed the old one) by the time this
+    // effect fires with the PREVIOUS render's `editor` closure. Rendering through
+    // that stale handle would target a destroyed editor — and the new instance is
+    // already seeded with the new `data` at construction. Skip unless this closure
+    // still owns the live editor, mirroring the isReady guard above.
+    const state = stateRef.current;
+
+    if (state.editor !== editor || state.isDestroyed) {
+      return;
+    }
+
+    // First time observing this editor: it was seeded at construction with
+    // `constructedDataRef`. When the current prop still matches that seed, just
+    // record the baseline and skip the redundant render. When it has diverged
+    // (undefined-at-mount then loaded, or changed before the editor finished
+    // initializing), fall through and render so the editor reflects the prop.
+    if (seededEditorRef.current !== editor) {
+      seededEditorRef.current = editor;
+      // 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;
+
+      if (deepEqual(data, constructedDataRef.current)) {
+        lastRenderedDataRef.current = data;
+
+        return;
+      }
+    }
+
+    // Skip when the editor already reflects this content (last SUCCESSFUL render)
+    // OR a render of the same content is already queued/in-flight — re-rendering
+    // identical content would needlessly reset the caret.
+    if (deepEqual(data, lastRenderedDataRef.current) || deepEqual(data, pendingDataRef.current)) {
+      return;
+    }
+
+    // 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
+    // run of consecutive failures (e.g. successive malformed `data`) would strand
+    // the baseline on a never-rendered payload and wrongly dedupe a later retry.
+    pendingDataRef.current = data;
+    renderChainRef.current = renderChainRef.current
+      .catch(() => undefined)
+      .then(() => editor.render(data))
+      .then(
+        () => {
+          lastRenderedDataRef.current = data;
+        },
+        () => {
+          // render failed: keep the last successful baseline so a later identical
+          // or corrected `data` re-renders instead of being deduped. Owning the
+          // rejection here also keeps it off the unhandled-rejection path.
+        }
+      )
+      .then(() => {
+        // Clear the in-flight marker once settled, unless a newer render has since
+        // claimed it (then that newer render owns the clear).
+        if (pendingDataRef.current === data) {
+          pendingDataRef.current = undefined;
+        }
+      });
+  }, [editor, data]);
+
+  return editor;
+}
+
+function deferDestroy(
+  state: EditorInstanceState,
+  setEditorState: React.Dispatch<React.SetStateAction<Blok | null>>
+): void {
+  /* eslint-disable no-param-reassign -- intentional mutation of shared state ref */
+  state.destroyTimeout = setTimeout(() => {
+    if (state.editor !== null) {
+      removeHolder(state.editor);
+      try {
+        state.editor.destroy();
+      } catch {
+        // destroy may throw — still clean up state
+      }
+      state.editor = null;
+      state.holder = null;
+      state.isDestroyed = true;
+      state.isEditorReady = false;
+      state.destroyTimeout = null;
+      setEditorState(null);
+    }
+  }, 0);
+  /* eslint-enable no-param-reassign */
+}