@bloklabs/react 1.2.6 → 1.4.0

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.2.6",
-  "description": "React bindings for the Blok editor",
+  "version": "1.4.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",
+  "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.2.6",
+    "@bloklabs/core": "^1.4.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokEditor.tsx

@@ -108,7 +108,7 @@ export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
       }
     }
 
-    const editor = useBlok(config as UseBlokConfig, deps);
+    const editor = useBlok(config, deps);
 
     useImperativeHandle<Blok | null, Blok | null>(ref, () => editor, [editor]);
 

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/createReactBlock.tsx

@@ -1,5 +1,6 @@
-import { useEffect, useRef, type ComponentType, type ReactElement } from 'react';
+import { isValidElement, useEffect, useRef, type ComponentType, type ReactElement } from 'react';
 import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
 import { DATA_ATTR, deepEqual, fillDefaults, mountChildBlocks, type PropSchema } from '@bloklabs/core/adapters';
 import {
   BLOK_PORTAL_REGISTRY_CONFIG_KEY,
@@ -7,7 +8,7 @@ import {
   type BlockPortalRegistry,
 } from './block-portal-registry';
 import type { BlockAPI } from '@/types/api';
-import type { BlockToolConstructorOptions, BlockToolData, ToolboxConfig } from '@/types/tools';
+import type { BlockToolConstructorOptions, BlockToolData, ToolboxConfig, ToolboxConfigEntry } from '@/types/tools';
 
 export type { PropSchema, PropSchemaEntry } from '@bloklabs/core/adapters';
 
@@ -21,7 +22,12 @@ const INTERNAL_CONFIG_KEYS: readonly string[] = [
 export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   /** 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. */
+  /**
+   * The ONLY data write path: merge a partial patch and sync once. Idempotency
+   * is part of the public contract — a patch that changes nothing is a FULL
+   * no-op (no re-render, no change event), so effects may echo current values
+   * through `commit` on any render, including mount, without a guard.
+   */
   commit: (patch: Partial<Data>) => void;
   /** This block's per-block API (id, connection methods, dispatchChange…). */
   block: BlockAPI;
@@ -46,16 +52,49 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   BlockChildren: ComponentType;
 }
 
+/**
+ * Props handed to a React block's `viewComponent` (the read-only renderer):
+ * the entry props minus `commit` — a display renderer has no write path.
+ */
+export type ReactBlockViewProps<Data, Config = Record<string, unknown>> = Omit<
+  ReactBlockRenderProps<Data, Config>,
+  'commit' | 'readOnly'
+>;
+
+/** A toolbox entry whose `icon` may be a React element instead of an SVG string. */
+export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
+  /**
+   * Toolbox icon. Core's toolbox chrome consumes markup strings, but React
+   * authors may pass the same element they render in the block body — the
+   * factory serializes it to markup once (lazily, cached) so icons are never
+   * duplicated as parallel raw SVG strings. Without a DOM (SSR) the element is
+   * returned as-is and serialization retries on the next browser-side access.
+   */
+  icon?: string | ReactElement;
+};
+
+/** Toolbox config for React blocks: single entry or several variants. */
+export type ReactToolboxConfig = ReactToolboxConfigEntry | ReactToolboxConfigEntry[];
+
 /** Spec for {@link createReactBlock}. */
 export interface CreateReactBlockSpec<Data = BlockToolData, Config = Record<string, unknown>> {
   /** Tool type name (registered key). */
   type: string;
-  /** Optional toolbox entry. */
-  toolbox?: ToolboxConfig;
+  /** Optional toolbox entry; `icon` accepts a React element (see {@link ReactToolboxConfigEntry}). */
+  toolbox?: ReactToolboxConfig;
   /** Declarative defaults that also define the exact `save()` key set. */
   propSchema: PropSchema;
   /** The component rendered for each block instance. */
   component: ComponentType<ReactBlockRenderProps<Data, Config>>;
+  /**
+   * Optional read-only renderer: when the editor is read-only, this component
+   * is rendered INSTEAD of `component`, so blocks don't hand-plumb a
+   * display-vs-edit ternary. It receives the entry props minus `commit` (no
+   * write path) and minus `readOnly` (always true by definition). Toggling read-only
+   * swaps renderers — ephemeral state does not survive the swap; omit
+   * `viewComponent` to keep the single-component in-place toggle instead.
+   */
+  viewComponent?: ComponentType<ReactBlockViewProps<Data, Config>>;
   /** Optional lifecycle callbacks mapped from Blok's block hooks. */
   onRendered?: (block: BlockAPI) => void;
   onMoved?: (block: BlockAPI) => void;
@@ -96,12 +135,116 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
   readonly toolbox: ToolboxConfig | undefined;
   readonly isReadOnlySupported: boolean;
 } {
+  /**
+   * Serialize a React element (an icon) to markup with a throwaway synchronous
+   * root. Returns null when serialization cannot complete: without a DOM
+   * (SSR — core never reads `toolbox` server-side, but a consumer may), or
+   * when the flush was deferred because React was already rendering (flushSync
+   * inside a render is a no-op with a warning, leaving the mount empty). A
+   * null result is NOT cached, so the next access retries.
+   */
+  const renderElementToMarkup = (element: ReactElement): string | null => {
+    if (typeof document === 'undefined') {
+      return null;
+    }
+
+    const mount = document.createElement('div');
+    const root = createRoot(mount);
+
+    flushSync(() => {
+      root.render(element);
+    });
+
+    const markup = mount.innerHTML;
+
+    root.unmount();
+
+    return markup === '' ? null : markup;
+  };
+
+  const convertToolbox = (): { value: ToolboxConfig | undefined; complete: boolean } => {
+    const status = { complete: true };
+
+    const toEntry = (entry: ReactToolboxConfigEntry): ToolboxConfigEntry => {
+      if (!isValidElement(entry.icon)) {
+        return entry as ToolboxConfigEntry;
+      }
+
+      const markup = renderElementToMarkup(entry.icon);
+
+      if (markup === null) {
+        // Leave the element in place (a consumer reading `toolbox` outside the
+        // browser can still use it) and skip caching so a later browser-side
+        // access serializes it properly.
+        status.complete = false;
+
+        return entry as ToolboxConfigEntry;
+      }
+
+      return { ...entry, icon: markup };
+    };
+
+    if (spec.toolbox === undefined) {
+      return { value: undefined, complete: status.complete };
+    }
+
+    const value = Array.isArray(spec.toolbox) ? spec.toolbox.map(toEntry) : toEntry(spec.toolbox);
+
+    return { value, complete: status.complete };
+  };
+
+  /** Lazily-computed core-compatible toolbox (React element icons serialized once). */
+  const toolboxCache: { resolved: boolean; value: ToolboxConfig | undefined } = {
+    resolved: false,
+    value: undefined,
+  };
+
+  const resolveToolbox = (): ToolboxConfig | undefined => {
+    if (toolboxCache.resolved) {
+      return toolboxCache.value;
+    }
+
+    const { value, complete } = convertToolbox();
+
+    // Only a fully-serialized toolbox is cached; an incomplete pass (no DOM,
+    // deferred flush) is returned as-is and recomputed on the next access.
+    if (complete) {
+      toolboxCache.value = value;
+      toolboxCache.resolved = true;
+    }
+
+    return value;
+  };
+
+  /**
+   * The component actually registered with the portal: when the spec provides a
+   * `viewComponent`, this chooser swaps to it while read-only (dropping the
+   * write-path props); otherwise the edit component is registered directly and
+   * keeps its in-place read-only toggle semantics.
+   */
+  const ReadOnlySwitch = (props: ReactBlockRenderProps<Data, Config>): ReactElement => {
+    const ViewComponent = spec.viewComponent;
+
+    if (props.readOnly && ViewComponent !== undefined) {
+      const { commit: _commit, readOnly: _readOnly, ...viewProps } = props;
+
+      return <ViewComponent {...(viewProps)} />;
+    }
+
+    const EditComponent = spec.component;
+
+    return <EditComponent {...props} />;
+  };
+
+  const entryComponent: ComponentType<ReactBlockRenderProps<Data, Config>> =
+    spec.viewComponent === undefined ? spec.component : ReadOnlySwitch;
+
   return class ReactBlockTool {
     /** Marker so `useBlok` can detect react-block tools and inject the registry. */
     public static readonly __isBlokReactBlock = true as const;
 
     public static get toolbox(): ToolboxConfig | undefined {
-      return spec.toolbox;
+      return resolveToolbox();
     }
 
     /**
@@ -190,7 +333,7 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 
       this.registry?.register(this.blockApi.id, {
         hostEl: host,
-        component: spec.component as unknown as ComponentType<Record<string, unknown>>,
+        component: entryComponent as unknown as ComponentType<Record<string, unknown>>,
         props: this.buildProps(),
         toolName: this.toolName,
       });
@@ -205,7 +348,7 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 
     public save(): BlockToolData {
       // The complete, frozen mirror — never the DOM, never partial.
-      return this.mirror as BlockToolData;
+      return this.mirror;
     }
 
     public async setData(newData: BlockToolData): Promise<boolean> {

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,21 +39,96 @@ 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). */
   title?: string;
+  /**
+   * Translation key for the toolbar label, resolved by core i18n as
+   * `toolNames.{titleKey}` (or used verbatim when it contains a dot). Without
+   * it a custom tool's label is only localizable through the legacy
+   * capitalized-tool-name fallback.
+   */
+  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;
@@ -69,15 +146,20 @@ 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;
   readonly title: string | undefined;
+  readonly titleKey: string | undefined;
   readonly shortcut: string | undefined;
   readonly sanitize: SanitizerConfig | undefined;
   readonly isReadOnlySupported: boolean;
@@ -91,12 +173,20 @@ export function createReactInlineTool<Config = Record<string, unknown>>(
       return spec.title;
     }
 
+    public static get titleKey(): string | undefined {
+      return spec.titleKey;
+    }
+
     public static get shortcut(): string | undefined {
       return spec.shortcut;
     }
 
     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 {
@@ -104,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. */
@@ -118,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];
@@ -133,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 {
@@ -145,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,
         });
@@ -157,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(),
       };
@@ -190,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;
@@ -210,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,17 +5,27 @@ 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,
   ReactBlockRenderProps,
+  ReactBlockViewProps,
+  ReactToolboxConfig,
+  ReactToolboxConfigEntry,
   PropSchema,
   PropSchemaEntry,
 } from './createReactBlock';
-export { createReactInlineTool } from './createReactInlineTool';
+export { createReactInlineTool, useInlineTool } from './createReactInlineTool';
 export type {
   CreateReactInlineToolSpec,
   ReactInlineToolRenderProps,
+  InlineToolHandle,
+  InlineToolMarkOps,
 } from './createReactInlineTool';
 export {
   createBlockPortalRegistry,