@bloklabs/react 1.3.0 → 1.4.1

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.3.0",
-  "description": "React bindings for the Blok editor",
+  "version": "1.4.1",
+  "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",
+  "homepage": "https://blokeditor.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/JackUait/blok.git",
     "directory": "packages/react"
   },
+  "bugs": {
+    "url": "https://github.com/JackUait/blok/issues"
+  },
+  "keywords": [
+    "blok",
+    "react",
+    "react-component",
+    "block-editor",
+    "rich-text-editor",
+    "wysiwyg",
+    "editor",
+    "notion",
+    "notion-like",
+    "headless",
+    "block-based",
+    "contenteditable",
+    "json",
+    "typescript"
+  ],
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",
@@ -30,10 +50,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "yarn run -T vite build --mode production"
+    "build": "yarn run -T vite build --mode production",
+    "test": "yarn run -T vitest run"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.3.0",
+    "@bloklabs/core": "^1.4.1",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokEditor.tsx

@@ -38,7 +38,9 @@ import type { UseBlokConfig } from './types';
  */
 export interface BlokEditorProps
   extends Omit<UseBlokConfig, 'onReady'>,
-    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
+    // `onChange`/`onError` are Blok config callbacks here — drop the DOM
+    // element's same-named event handlers so the config signatures win.
+    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange' | 'onError'> {
   /**
    * When any value changes, the editor is destroyed and recreated. Keep each
    * value referentially stable (primitives or useMemo-stable objects) — a dep

package/src/BlokView.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+import type { BlocksToHtmlOptions } from '@bloklabs/core/view';
+import type { LooseOutputData, OutputData } from '@bloklabs/core';
+
+import { useBlokView } from './useBlokView';
+
+/**
+ * Props for {@link BlokView}.
+ */
+export interface BlokViewProps {
+  /** Saved document to display (strict or loose wire shape; nullish tolerated). */
+  data: OutputData | LooseOutputData | null | undefined;
+  /** View schema from `defineBlokSchema` — display under the composition that produced the document. */
+  schema?: BlocksToHtmlOptions['schema'];
+  /** Custom per-tool renderers; win over built-ins. */
+  renderers?: BlocksToHtmlOptions['renderers'];
+  /** Unknown-tool policy (default 'skip'). */
+  onUnknownBlock?: BlocksToHtmlOptions['onUnknownBlock'];
+  /** Class for the single wrapper div. */
+  className?: string;
+}
+
+/**
+ * Display a saved Blok document synchronously — one `<div>` wrapper, no
+ * editor chrome, no ids, no async, no effects. Content is mapped from the
+ * sanitized view tree to real React elements (never
+ * `dangerouslySetInnerHTML`), so it renders identically under SSR.
+ *
+ * @experimental Built on the `@experimental` ViewNode tree of
+ * `@bloklabs/core/view` — not frozen until a second framework adapter
+ * consumes it.
+ */
+export const BlokView = ({ data, schema, renderers, onUnknownBlock, className }: BlokViewProps): ReactNode => {
+  const content = useBlokView(data, { schema, renderers, onUnknownBlock });
+
+  return <div className={className}>{content}</div>;
+};

package/src/config-keys.ts

@@ -31,6 +31,7 @@ export const USE_BLOK_CONFIG_KEYS = [
   'onReady',
   'onChange',
   'onSave',
+  'onError',
   'onEnter',
   'onBeforeRender',
   'onAfterRender',

package/src/createReactInlineTool.tsx

@@ -1,10 +1,12 @@
-import type { ComponentType } from 'react';
+import { createContext, useContext, useMemo, type ComponentType, type ReactElement } from 'react';
+import { markSanitizerConfig } from '@bloklabs/core/adapters';
 import {
   BLOK_PORTAL_REGISTRY_CONFIG_KEY,
   BLOK_TOOL_NAME_CONFIG_KEY,
   type BlockPortalRegistry,
 } from './block-portal-registry';
-import type { SanitizerConfig } from '@/types';
+import type { API, SanitizerConfig } from '@/types';
+import type { MarkSnapshot, MarkSpec } from '@/types';
 import type { InlineTool, InlineToolConstructorOptions, MenuConfig } from '@/types/tools';
 
 /** Adapter-internal config keys, stripped before the config reaches the component. */
@@ -37,8 +39,57 @@ export interface ReactInlineToolRenderProps<Config = Record<string, unknown>> {
   config: Readonly<Partial<Config>>;
 }
 
+/** The spec's mark operations, bound to the live selection via `api.marks`. */
+export interface InlineToolMarkOps<State = void> {
+  /** Whether the whole selection currently carries the mark. */
+  has(): boolean;
+  /** Toggle the mark on the selection; returns true when now applied. */
+  toggle(state?: State): boolean;
+  /** Apply (or update in place) the mark on the selection. */
+  apply(state?: State): HTMLElement[];
+  /** Remove the mark from the selection. */
+  remove(): HTMLElement[];
+  /** Read the mark's current declared values at the selection. */
+  read(): MarkSnapshot | null;
+}
+
+/**
+ * Everything a React inline tool's component (and any component nested in it —
+ * swatches, popovers) can reach via {@link useInlineTool} without prop-drilling.
+ */
+export interface InlineToolHandle<Config = Record<string, unknown>, State = void> {
+  /** Live active state, same value as the component's `active` prop. */
+  active: boolean;
+  /** The tool's config, same value as the component's `config` prop. */
+  config: Readonly<Partial<Config>>;
+  /** The editor API handed to the tool's constructor (undefined outside core). */
+  api: API | undefined;
+  /**
+   * Operations bound to the spec's `mark` — null when the spec declares no
+   * mark or the editor api provides no `marks` surface.
+   */
+  mark: InlineToolMarkOps<State> | null;
+}
+
+const InlineToolContext = createContext<InlineToolHandle | null>(null);
+
+/**
+ * Reach the enclosing React inline tool from any component inside its
+ * portaled UI: live `active` state, the tool `config`, the editor `api`, and
+ * the spec's mark operations bound to the live selection.
+ */
+export function useInlineTool<Config = Record<string, unknown>, State = void>(): InlineToolHandle<Config, State> {
+  const handle = useContext(InlineToolContext);
+
+  if (handle === null) {
+    throw new Error('useInlineTool() must be called from a component rendered by createReactInlineTool');
+  }
+
+  return handle as InlineToolHandle<Config, State>;
+}
+
 /** Spec for {@link createReactInlineTool}. */
-export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
+export interface CreateReactInlineToolSpec<Config = Record<string, unknown>, State = void> {
   /** Tool type name — the MenuConfig item name (fallback when the tools-map key is unavailable). */
   type: string;
   /** Optional toolbar item title (shown in overflow/search contexts). */
@@ -52,13 +103,32 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
   titleKey?: string;
   /** The component rendered as the tool's toolbar icon/UI. */
   component: ComponentType<ReactInlineToolRenderProps<Config>>;
-  /** Applies/removes the formatting on the LIVE selection's range (captured at activation time). */
-  surround?: (range: Range) => void;
-  /** Reports whether the formatting is active for the given selection. */
-  checkState?: (selection: Selection | null) => boolean;
+  /**
+   * Declarative description of the wrapper this tool produces. When present,
+   * `surround` (toggle), `checkState` (whole-range coverage) and `sanitize`
+   * are derived from it — range-aware splitting, adjacent-run semantics and
+   * the trailing-whitespace fix come from the editor's mark engine
+   * (`api.marks`) with no DOM plumbing in the tool.
+   */
+  mark?: MarkSpec<State>;
+  /**
+   * Applies/removes the formatting on the LIVE selection's range (captured at
+   * activation time). Receives the editor API as its second argument.
+   * Takes precedence over the `mark` derivation.
+   */
+  surround?: (range: Range, api: API | undefined) => void;
+  /**
+   * Reports whether the formatting is active for the given selection.
+   * Receives the editor API as its second argument.
+   * Takes precedence over the `mark` derivation.
+   */
+  checkState?: (selection: Selection | null, api: API | undefined) => boolean;
   /** Keyboard shortcut (e.g. `CMD+SHIFT+C`). */
   shortcut?: string;
-  /** Inline sanitizer config declaring the markup this tool produces. */
+  /**
+   * Inline sanitizer config declaring the markup this tool produces.
+   * Defaults to the config derived from `mark` when one is declared.
+   */
   sanitize?: SanitizerConfig;
   /** Whether the tool stays available in read-only mode. */
   isReadOnlySupported?: boolean;
@@ -76,11 +146,15 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
  * `destroy()` (called by the inline toolbar on close/teardown) unregisters the
  * portal so the component unmounts deterministically — no leaked React roots.
  *
+ * The editor `api` handed to the constructor is kept: it reaches `surround`/
+ * `checkState` as their second argument, powers the `mark` derivation, and is
+ * exposed to the portaled component tree via {@link useInlineTool}.
+ *
  * Without an injected registry (vanilla core, no `useBlok`), the tool still
  * renders a valid MenuConfig — the host element just stays empty.
  */
-export function createReactInlineTool<Config = Record<string, unknown>>(
-  spec: CreateReactInlineToolSpec<Config>
+export function createReactInlineTool<Config = Record<string, unknown>, State = void>(
+  spec: CreateReactInlineToolSpec<Config, State>
 ): (new (options: InlineToolConstructorOptions) => InlineTool) & {
   readonly __isBlokReactInlineTool: true;
   readonly isInline: true;
@@ -108,7 +182,11 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
     }
 
     public static get sanitize(): SanitizerConfig | undefined {
-      return spec.sanitize;
+      if (spec.sanitize !== undefined) {
+        return spec.sanitize;
+      }
+
+      return spec.mark !== undefined ? markSanitizerConfig(spec.mark) : undefined;
     }
 
     public static get isReadOnlySupported(): boolean {
@@ -116,12 +194,20 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
     }
 
     private readonly registry: BlockPortalRegistry | undefined;
+    /** The editor API — kept (not discarded) so the tool has the same reach as a vanilla one. */
+    private readonly api: API | undefined;
     /** Name this tool is registered under in the consumer's `tools` map. */
     private readonly toolName: string;
     /** Unique portal-registry key — inline tools have no block id. */
     private readonly portalKey: string;
     /** The consumer's tool config with adapter-internal keys stripped. */
     private readonly toolConfig: Readonly<Partial<Config>>;
+    /**
+     * Stable provider component wrapping `spec.component` with the
+     * {@link useInlineTool} context. Created once per instance so prop pushes
+     * (setProps) re-render without remounting the consumer's component.
+     */
+    private readonly portalComponent: ComponentType<ReactInlineToolRenderProps<Config>>;
     /** Last active state pushed to the mounted component (change-dedup baseline). */
     private active = false;
     /** True while this instance owns a registered portal entry. */
@@ -130,6 +216,7 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
     public constructor(options: InlineToolConstructorOptions) {
       const config: Record<string, unknown> = options?.config ?? {};
 
+      this.api = options?.api;
       this.registry = config[BLOK_PORTAL_REGISTRY_CONFIG_KEY] as BlockPortalRegistry | undefined;
 
       const toolName = config[BLOK_TOOL_NAME_CONFIG_KEY];
@@ -145,6 +232,7 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
         }
       }
       this.toolConfig = Object.freeze(publicConfig) as Readonly<Partial<Config>>;
+      this.portalComponent = this.createPortalComponent();
     }
 
     public render(): MenuConfig {
@@ -157,7 +245,7 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
       if (this.registry !== undefined) {
         this.registry.register(this.portalKey, {
           hostEl: host,
-          component: spec.component as unknown as ComponentType<Record<string, unknown>>,
+          component: this.portalComponent as unknown as ComponentType<Record<string, unknown>>,
           props: { active: this.active, config: this.toolConfig },
           toolName: this.toolName,
         });
@@ -169,19 +257,7 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
         title: spec.title,
         icon: host,
         onActivate: (): void => {
-          if (typeof spec.surround !== 'function') {
-            return;
-          }
-
-          // Capture the LIVE selection at activation time (matching
-          // wrapLegacyInlineTool) — never a range snapshotted at render.
-          const selection = window.getSelection();
-
-          if (!selection || selection.rangeCount === 0) {
-            return;
-          }
-
-          spec.surround(selection.getRangeAt(0));
+          this.activate();
         },
         isActive: (): boolean => this.refreshActiveState(),
       };
@@ -202,15 +278,37 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
       this.registry?.unregister(this.portalKey);
     }
 
+    /**
+     * Run the tool's formatting action: an explicit `surround` on the LIVE
+     * selection's range (captured at activation time, matching
+     * wrapLegacyInlineTool — never a range snapshotted at render), or the
+     * mark derivation (`api.marks.toggle`) when only a `mark` is declared.
+     */
+    private activate(): void {
+      if (typeof spec.surround === 'function') {
+        const selection = window.getSelection();
+
+        if (!selection || selection.rangeCount === 0) {
+          return;
+        }
+
+        spec.surround(selection.getRangeAt(0), this.api);
+
+        return;
+      }
+
+      if (spec.mark !== undefined && this.api?.marks !== undefined) {
+        this.api.marks.toggle(spec.mark);
+      }
+    }
+
     /**
      * Recompute the active state from the live selection and push it to the
      * mounted component ONLY when it actually changed (no redundant
      * external-store notifications).
      */
     private refreshActiveState(): boolean {
-      const active = typeof spec.checkState === 'function'
-        ? Boolean(spec.checkState(window.getSelection()))
-        : false;
+      const active = this.computeActiveState();
 
       if (active !== this.active) {
         this.active = active;
@@ -222,5 +320,64 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
 
       return active;
     }
+
+    /**
+     * Explicit `checkState` wins; otherwise the mark derivation answers
+     * "does the WHOLE selection carry the mark" via `api.marks.has`.
+     */
+    private computeActiveState(): boolean {
+      if (typeof spec.checkState === 'function') {
+        return Boolean(spec.checkState(window.getSelection(), this.api));
+      }
+
+      if (spec.mark !== undefined && this.api?.marks !== undefined) {
+        return this.api.marks.has(spec.mark);
+      }
+
+      return false;
+    }
+
+    /**
+     * Build the per-instance provider component: the consumer's component
+     * rendered inside the {@link useInlineTool} context, so nested
+     * swatches/popovers reach the tool without prop-drilling.
+     */
+    private createPortalComponent(): ComponentType<ReactInlineToolRenderProps<Config>> {
+      const api = this.api;
+      const mark = spec.mark;
+      const Component = spec.component;
+
+      const markOps: InlineToolMarkOps<State> | null = mark !== undefined && api?.marks !== undefined
+        ? {
+            has: (): boolean => api.marks.has(mark),
+            toggle: (state?: State): boolean => api.marks.toggle(mark, state),
+            apply: (state?: State): HTMLElement[] => api.marks.apply(mark, state),
+            remove: (): HTMLElement[] => api.marks.remove(mark),
+            read: (): MarkSnapshot | null => api.marks.read(mark),
+          }
+        : null;
+
+      const PortalComponent = (props: ReactInlineToolRenderProps<Config>): ReactElement => {
+        const handle = useMemo<InlineToolHandle>(
+          () => ({
+            active: props.active,
+            config: props.config,
+            api,
+            mark: markOps as InlineToolMarkOps | null,
+          }),
+          [props.active, props.config]
+        );
+
+        return (
+          <InlineToolContext.Provider value={handle}>
+            <Component active={props.active} config={props.config} />
+          </InlineToolContext.Provider>
+        );
+      };
+
+      PortalComponent.displayName = `BlokInlineTool(${this.toolName})`;
+
+      return PortalComponent;
+    }
   };
 }

package/src/index.ts

@@ -5,6 +5,11 @@ export { BlokProvider, useBlokDefaults } from './provide-blok';
 export type { UseBlokConfig, BlokContentProps } from './types';
 export type { BlokEditorProps } from './BlokEditor';
 export { useBlocks } from './useBlocks';
+export { useBlokReady } from './useBlokReady';
+export type { UseBlokReadyOptions } from './useBlokReady';
+export { BlokView } from './BlokView';
+export type { BlokViewProps } from './BlokView';
+export { useBlokView } from './useBlokView';
 export { createReactBlock } from './createReactBlock';
 export type {
   CreateReactBlockSpec,
@@ -15,10 +20,12 @@ export type {
   PropSchema,
   PropSchemaEntry,
 } from './createReactBlock';
-export { createReactInlineTool } from './createReactInlineTool';
+export { createReactInlineTool, useInlineTool } from './createReactInlineTool';
 export type {
   CreateReactInlineToolSpec,
   ReactInlineToolRenderProps,
+  InlineToolHandle,
+  InlineToolMarkOps,
 } from './createReactInlineTool';
 export {
   createBlockPortalRegistry,

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

@@ -417,14 +417,51 @@ 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;
+  // 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;
@@ -480,6 +517,45 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     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(() => {

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]);
+};