@bloklabs/react 1.2.6 → 1.4.0

package/src/provide-blok.tsx

@@ -66,5 +66,5 @@ export function mergeBlokDefaults(
     merged.tools = { ...defaults.tools, ...config.tools };
   }
 
-  return merged as UseBlokConfig;
+  return merged;
 }

package/src/types.ts

@@ -6,7 +6,11 @@ import type { BlokConfig, Blok, EditorWidth } from '@/types';
  * React-only reactive `width` prop.
  *
  * Reactive props (sync after mount without recreation):
- * - `readOnly` — calls `editor.readOnly.set(value)`
+ * - `readOnly` — calls `editor.readOnly.set(value)`; the object form also
+ *   syncs `hideControls` via `editor.readOnly.set(enabled, { hideControls })`
+ * - `hideToolbar` — calls `editor.toolbar.setHidden(value)`
+ * - `inlineToolbar` — calls `editor.tools.setInlineToolbar(value)` (arrays
+ *   are compared by content, so a re-created literal is a no-op)
  * - `autofocus` — calls `editor.focus()` when changed to true
  * - `theme` — calls `editor.theme.set(value)`
  * - `width` — calls `editor.width.set(value)`

package/src/useBlok.ts

@@ -11,7 +11,7 @@ import {
 } from './block-portal-registry';
 import { setRegistry, removeRegistry } from './registry-map';
 import { bindLiveToolConfigFunctions, buildLiveBlockConfig } from './live-tool-config';
-import { normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
+import { createEmittedEchoWindow, normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
 
@@ -70,7 +70,7 @@ const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): un
       typeof entry === 'function' ? { class: entry } : { ...(entry as Record<string, unknown>) };
 
     base.config = {
-      ...((base.config as Record<string, unknown> | undefined) ?? {}),
+      ...((base.config) ?? {}),
       [BLOK_PORTAL_REGISTRY_CONFIG_KEY]: registry,
       [BLOK_TOOL_NAME_CONFIG_KEY]: name,
     };
@@ -124,6 +124,13 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   // 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);
+  // Window of recently emitted `onSave` payloads. The baseline above only
+  // remembers the LAST one, but a host that persists on save and refetches can
+  // echo an EARLIER save after a newer one replaced the baseline (the user kept
+  // typing). Such a stale echo is still the editor's own output — re-rendering
+  // it would clobber the caret and the content typed since — so the data effect
+  // treats a match against ANY windowed payload as a no-op.
+  const echoWindowRef = useRef(createEmittedEchoWindow());
   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
@@ -144,6 +151,9 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   const liveRegistryRef = useRef<BlockPortalRegistry | null>(null);
   const wrappedToolsRef = useRef<unknown>(undefined);
   const pushedBlockConfigsRef = useRef<Map<string, Record<string, unknown>>>(new Map());
+  // Last-applied tool-level `toolbox` setting per tool name (dedupe baseline for
+  // the reactive toolbox effect below). Seeded from the construction-time tools.
+  const appliedToolboxRef = useRef<Map<string, unknown>>(new Map());
 
   // Main lifecycle effect
   useEffect(() => {
@@ -224,6 +234,12 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     liveRegistryRef.current = registry;
     wrappedToolsRef.current = wrappedTools;
     pushedBlockConfigsRef.current = new Map();
+    appliedToolboxRef.current = new Map(
+      Object.entries((currentConfig.tools ?? {}) as Record<string, unknown>).map(([name, entry]) => [
+        name,
+        entry !== null && typeof entry === 'object' ? (entry as { toolbox?: unknown }).toolbox : undefined,
+      ])
+    );
 
     const blokConfig = {
       ...currentConfig,
@@ -249,6 +265,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
         // 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];
+        echoWindowRef.current.record(args[0]);
         configRef.current.onSave?.(...args);
       };
     }
@@ -269,7 +286,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       };
     }
 
-    const blok = new BlokRuntime(blokConfig) as unknown as Blok;
+    const blok = new BlokRuntime(blokConfig);
     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.
@@ -358,14 +375,93 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     }
   });
 
-  // Reactive: readOnly (object form normalized so the effect dep is a stable boolean)
-  const readOnlyEnabled = normalizeReadOnlyConfig(config.readOnly).enabled;
+  // Live tool-level `toolbox` setting. Toolbox membership was construction-only,
+  // which forced permission-style gating (`toolbox: false` for users who may not
+  // insert a tool) into `deps` — recreating the whole editor on a permission
+  // flip. Instead, diff each tool's `toolbox` setting against the last applied
+  // value on every render and push genuine changes through the runtime
+  // `tools.update` API (which reaches the live adapter and rebuilds the Toolbox
+  // UI). Applies only once the editor is ready — module APIs attach at isReady —
+  // and the ready transition re-renders, so a change made earlier is not lost.
+  useEffect(() => {
+    const state = stateRef.current;
+
+    if (state.editor === null || state.isDestroyed || !state.isEditorReady) {
+      return;
+    }
+
+    const latestTools = configRef.current.tools as Record<string, unknown> | undefined;
+
+    if (latestTools === null || typeof latestTools !== 'object') {
+      return;
+    }
+
+    for (const [name, entry] of Object.entries(latestTools)) {
+      // Only tools the editor was constructed with can be updated at runtime.
+      if (!appliedToolboxRef.current.has(name)) {
+        continue;
+      }
+
+      const latest =
+        entry !== null && typeof entry === 'object' ? (entry as { toolbox?: unknown }).toolbox : undefined;
+      const applied = appliedToolboxRef.current.get(name);
+
+      if (deepEqual(latest, applied)) {
+        continue;
+      }
+
+      appliedToolboxRef.current.set(name, latest);
+      (state.editor as unknown as {
+        tools?: { update: (toolName: string, config: Record<string, unknown>) => void };
+      }).tools?.update(name, { toolbox: latest });
+    }
+  });
+
+  // Reactive: readOnly (object form normalized so the effect deps are stable booleans).
+  // The object form additionally syncs `hideControls` through the options
+  // parameter of `readOnly.set` — a plain boolean prop keeps the historical
+  // boolean-only call so it never overwrites a construction-time object form.
+  const readOnlyIsObjectForm = typeof config.readOnly === 'object' && config.readOnly !== null;
+  const { enabled: readOnlyEnabled, hideControls: readOnlyHideControls } = normalizeReadOnlyConfig(config.readOnly);
   useEffect(() => {
     if (editor === null) {
       return;
     }
-    void editor.readOnly.set(readOnlyEnabled);
-  }, [editor, readOnlyEnabled]);
+
+    if (readOnlyIsObjectForm) {
+      void editor.readOnly.set(readOnlyEnabled, { hideControls: readOnlyHideControls });
+    } else {
+      void editor.readOnly.set(readOnlyEnabled);
+    }
+  }, [editor, readOnlyEnabled, readOnlyHideControls, readOnlyIsObjectForm]);
+
+  // Reactive: hideToolbar — `toolbar.setHidden` writes `config.hideToolbar`
+  // (read live by the toolbar's open guards) AND toggles the wrapper's
+  // toolbar-hidden attribute (the CSS hook that collapses the gutter), so a
+  // prop flip takes effect in place. Guarded on `undefined` so a consumer who
+  // never sets the prop gets no call at all (mirrors theme/width).
+  const { hideToolbar } = config;
+  useEffect(() => {
+    if (editor === null || hideToolbar === undefined) {
+      return;
+    }
+    editor.toolbar.setHidden(hideToolbar);
+  }, [editor, hideToolbar]);
+
+  // Reactive: inlineToolbar — `tools.setInlineToolbar` re-assigns every block
+  // tool's inline set and invalidates sanitize caches, so the change lands on
+  // the next selection without a re-render. The dep is a content serialization
+  // (boolean | string[]) so a re-created array literal with the same entries
+  // does not re-fire the setter.
+  const { inlineToolbar } = config;
+  const inlineToolbarKey = inlineToolbar === undefined ? undefined : JSON.stringify(inlineToolbar);
+  useEffect(() => {
+    if (editor === null || inlineToolbar === undefined) {
+      return;
+    }
+    editor.tools.setInlineToolbar(inlineToolbar);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- inlineToolbar is deliberately depped by CONTENT (inlineToolbarKey) so a re-created array literal with the same entries does not thrash the setter
+  }, [editor, inlineToolbarKey]);
 
   // Reactive: autofocus
   const { autofocus } = config;
@@ -394,6 +490,72 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     editor.width.set(width);
   }, [editor, width]);
 
+  // Reactive: style.tokens
+  //
+  // Theme tokens were construction-only, so a host with a live light/dark
+  // toggle had to bump `deps` (destroying the editor, losing caret/history) or
+  // hand-write the global stylesheet Blok already injects. Push genuine changes
+  // through the runtime `tokens` API instead, deep-equal–deduped because
+  // `tokens` is almost always a fresh object literal each render.
+  const styleTokens = config.style?.tokens;
+  /*
+   * Seeded with the mount-time value: construction already injected those
+   * tokens, so the first effect run is a no-op and only genuine changes push.
+   */
+  const appliedTokensRef = useRef<Record<string, string> | undefined>(config.style?.tokens);
+
+  useEffect(() => {
+    if (editor === null || styleTokens === undefined) {
+      return;
+    }
+
+    if (deepEqual(styleTokens, appliedTokensRef.current)) {
+      return;
+    }
+
+    appliedTokensRef.current = styleTokens;
+    editor.tokens.set(styleTokens);
+  }, [editor, styleTokens]);
+
+  // Reactive: i18n
+  //
+  // `config.i18n` was read once during the editor's boot and never again, so a
+  // host driving a language switcher from React state had no correct option:
+  // accept a permanently stale UI, or bump `deps` and destroy the editor
+  // mid-typing. Push genuine changes through the runtime `i18n.update` API
+  // instead, deep-equal–deduped because `i18n` is almost always a fresh object
+  // literal each render (a `useMemo`d message map re-created on locale change
+  // is the whole point of the prop).
+  //
+  // `defaultLocale` is deliberately not forwarded: it only decides the
+  // fallback while resolving the INITIAL locale, so it is inert after mount.
+  const { i18n } = config;
+  /*
+   * Seeded with the mount-time value: construction already applied it, so the
+   * first effect run is a no-op and only genuine changes push.
+   */
+  const appliedI18nRef = useRef<UseBlokConfig['i18n']>(config.i18n);
+
+  useEffect(() => {
+    if (editor === null || i18n === undefined) {
+      return;
+    }
+
+    if (deepEqual(i18n, appliedI18nRef.current)) {
+      return;
+    }
+
+    appliedI18nRef.current = i18n;
+
+    const { locale, messages, direction } = i18n;
+
+    void editor.i18n.update({
+      ...(locale === undefined ? {} : { locale }),
+      ...(messages === undefined ? {} : { messages }),
+      ...(direction === undefined ? {} : { direction }),
+    });
+  }, [editor, i18n]);
+
   // Reactive: placeholder
   const { placeholder } = config;
   useEffect(() => {
@@ -441,6 +603,8 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       // 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;
+      // Payloads emitted by a PRIOR editor are likewise moot for this one.
+      echoWindowRef.current.clear();
 
       if (deepEqual(data, constructedDataRef.current)) {
         lastRenderedDataRef.current = data;
@@ -456,6 +620,17 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       return;
     }
 
+    // Skip stale echoes: content the editor itself emitted via `onSave` recently,
+    // arriving back reshaped (fresh envelope, stripped ids) and/or late — after a
+    // newer save already replaced the baseline above.
+    if (echoWindowRef.current.matches(data)) {
+      return;
+    }
+
+    // Genuinely external content takes over: earlier emitted payloads are moot,
+    // and keeping them could wrongly no-op a later deliberate revert to one.
+    echoWindowRef.current.clear();
+
     // 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

package/src/useBlokReady.ts

@@ -0,0 +1,60 @@
+import { useEffect, useState, type RefObject } from 'react';
+import { Blok as BlokRuntime } from '@bloklabs/core';
+
+/** Options accepted by {@link useBlokReady}. */
+export interface UseBlokReadyOptions {
+  /**
+   * Restrict the wait to editors mounted inside this element. Accepts the ref
+   * you already hold on the container (read on every notification, so a ref
+   * that attaches after the first render is picked up).
+   *
+   * Omit it to observe every editor on the page. Passing it while it still
+   * resolves to null reports NOT ready — an unresolved scope must never fall
+   * back to the page-global one.
+   */
+  within?: RefObject<Element | null> | Element | null;
+  /**
+   * `'ready'` (default) settles when each editor has finished booting.
+   * `'rendered'` also waits for its content to be in the DOM and re-arms on
+   * every post-boot re-render.
+   */
+  settleOn?: 'ready' | 'rendered';
+}
+
+/**
+ * Live readiness of the Blok editors in a DOM scope.
+ *
+ * Returns `false` until every editor inside `within` is settled, and follows
+ * the scope afterwards: editors mounted later re-close the gate, and with
+ * `settleOn: 'rendered'` so does each re-render. A scope holding no editors is
+ * ready, so callers need no "nothing to wait for" special case.
+ *
+ * The first render always reports `false` — the scope element is not attached
+ * yet, and over-waiting is safe while under-waiting is a bug.
+ * @param options - scope and readiness depth
+ */
+export function useBlokReady(options: UseBlokReadyOptions = {}): boolean {
+  const { within, settleOn } = options;
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const read = (): void => {
+      const scope = within instanceof Element ? within : (within?.current ?? null);
+
+      // A scope that was asked for but has not resolved yet is NOT the global
+      // scope — reporting ready here would gate on the wrong set of editors.
+      setReady(within !== undefined && scope === null
+        ? false
+        : BlokRuntime.readyState({
+          within: scope,
+          settleOn,
+        }).ready);
+    };
+
+    read();
+
+    return BlokRuntime.subscribeReady(read);
+  }, [within, settleOn]);
+
+  return ready;
+}

package/src/useBlokView.ts

@@ -0,0 +1,38 @@
+import { createElement, Fragment, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import { blocksToViewNodes } from '@bloklabs/core/view';
+import type { BlocksToHtmlOptions } from '@bloklabs/core/view';
+import type { LooseOutputData, OutputData } from '@bloklabs/core';
+
+import { viewNodesToReact } from './view-nodes-to-react';
+
+/**
+ * Render a saved Blok document to React elements with NO wrapper element —
+ * a Fragment of the block elements, for placement inside `<label>`s, table
+ * cells, and other slots where an extra `<div>` is invalid or unwanted.
+ *
+ * Synchronous and effect-free (SSR-safe); memoized on the data reference and
+ * the individual option values.
+ *
+ * @experimental Built on the `@experimental` ViewNode tree of
+ * `@bloklabs/core/view` — not frozen until a second framework adapter
+ * consumes it.
+ * @param data - saved document (strict or loose wire shape; nullish tolerated)
+ * @param options - schema / custom renderers / unknown-block policy
+ */
+export const useBlokView = (
+  data: OutputData | LooseOutputData | null | undefined,
+  options?: BlocksToHtmlOptions
+): ReactNode => {
+  const schema = options?.schema;
+  const renderers = options?.renderers;
+  const onUnknownBlock = options?.onUnknownBlock;
+
+  return useMemo(() => {
+    return createElement(
+      Fragment,
+      null,
+      ...viewNodesToReact(blocksToViewNodes(data, { schema, renderers, onUnknownBlock }))
+    );
+  }, [data, schema, renderers, onUnknownBlock]);
+};

package/src/view-nodes-to-react.ts

@@ -0,0 +1,138 @@
+/**
+ * ViewNode → React element mapping for the synchronous view bindings.
+ * Real elements via `createElement` recursion — never `dangerouslySetInnerHTML`.
+ */
+import { createElement } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
+import type { ViewNode } from '@bloklabs/core/view';
+
+/** HTML void elements — must never receive children. */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/**
+ * Presence-valued HTML attributes mapped to boolean React props. `checked`
+ * is handled separately (→ `defaultChecked`, so React does not treat the
+ * input as controlled).
+ */
+const BOOLEAN_ATTRIBUTES = new Set([
+  'disabled', 'open', 'controls', 'autoplay', 'loop', 'muted', 'required',
+  'multiple', 'playsinline', 'reversed', 'hidden', 'default', 'novalidate',
+  'allowfullscreen', 'itemscope',
+]);
+
+/** HTML attribute name → React prop name (beyond the identity mapping). */
+const ATTRIBUTE_NAME_MAP: Record<string, string> = {
+  class: 'className',
+  for: 'htmlFor',
+  colspan: 'colSpan',
+  rowspan: 'rowSpan',
+  tabindex: 'tabIndex',
+  readonly: 'readOnly',
+  srcset: 'srcSet',
+  srclang: 'srcLang',
+  datetime: 'dateTime',
+  autoplay: 'autoPlay',
+  playsinline: 'playsInline',
+  novalidate: 'noValidate',
+  allowfullscreen: 'allowFullScreen',
+  crossorigin: 'crossOrigin',
+  referrerpolicy: 'referrerPolicy',
+  contenteditable: 'contentEditable',
+  spellcheck: 'spellCheck',
+  maxlength: 'maxLength',
+  minlength: 'minLength',
+  usemap: 'useMap',
+  itemscope: 'itemScope',
+};
+
+/**
+ * Convert a sanitized `style` attribute string to a React style object
+ * (React only accepts object styles). Custom properties keep their raw name;
+ * everything else is camelCased.
+ * @param css - style attribute text
+ */
+const styleStringToObject = (css: string): CSSProperties => {
+  const style: Record<string, string> = {};
+
+  for (const declaration of css.split(';')) {
+    const separator = declaration.indexOf(':');
+
+    if (separator === -1) {
+      continue;
+    }
+
+    const property = declaration.slice(0, separator).trim();
+    const value = declaration.slice(separator + 1).trim();
+
+    if (property === '' || value === '') {
+      continue;
+    }
+
+    const key = property.startsWith('--')
+      ? property
+      : property.toLowerCase().replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+    style[key] = value;
+  }
+
+  return style;
+};
+
+/**
+ * Map one ViewNode attribute record to React props.
+ * @param attrs - sanitized attributes from the view tree
+ * @param key - sibling index used as the React key
+ */
+const attrsToProps = (attrs: Record<string, string>, key: number): Record<string, unknown> => {
+  const props: Record<string, unknown> = { key };
+
+  for (const [name, value] of Object.entries(attrs)) {
+    if (name === 'style') {
+      props.style = styleStringToObject(value);
+      continue;
+    }
+
+    if (name === 'checked') {
+      props.defaultChecked = true;
+      continue;
+    }
+
+    if (name === 'value') {
+      props.defaultValue = value;
+      continue;
+    }
+
+    if (BOOLEAN_ATTRIBUTES.has(name)) {
+      props[ATTRIBUTE_NAME_MAP[name] ?? name] = true;
+      continue;
+    }
+
+    props[ATTRIBUTE_NAME_MAP[name] ?? name] = value;
+  }
+
+  return props;
+};
+
+/**
+ * Map a list of ViewNodes to React nodes. Element keys come from the sibling
+ * index (the tree is static per render).
+ * @param nodes - view tree siblings
+ */
+export const viewNodesToReact = (nodes: ViewNode[]): ReactNode[] => {
+  return nodes.map((node, index): ReactNode => {
+    if ('text' in node) {
+      return node.text;
+    }
+
+    const props = attrsToProps(node.attrs, index);
+
+    if (VOID_ELEMENTS.has(node.tag) || node.children.length === 0) {
+      return createElement(node.tag, props);
+    }
+
+    return createElement(node.tag, props, ...viewNodesToReact(node.children));
+  });
+};