@bloklabs/react 1.2.5 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "React bindings for the Blok editor",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -33,7 +33,7 @@
     "build": "yarn run -T vite build --mode production"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.2.5",
+    "@bloklabs/core": "^1.3.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/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

@@ -0,0 +1,226 @@
+import type { ComponentType } from 'react';
+import {
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+  type BlockPortalRegistry,
+} from './block-portal-registry';
+import type { SanitizerConfig } from '@/types';
+import type { InlineTool, InlineToolConstructorOptions, MenuConfig } from '@/types/tools';
+
+/** Adapter-internal config keys, stripped before the config reaches the component. */
+const INTERNAL_CONFIG_KEYS: readonly string[] = [
+  BLOK_PORTAL_REGISTRY_CONFIG_KEY,
+  BLOK_TOOL_NAME_CONFIG_KEY,
+];
+
+/**
+ * Unique portal-registry key per tool instance (inline tools have no block id
+ * to key on, and multiple instances of the same tool can coexist — e.g. the
+ * visible toolbar's instance plus a shortcut render-probe).
+ * @param toolName - name the tool is registered under
+ */
+const generatePortalKey = (toolName: string): string =>
+  `__blok-inline-tool__:${toolName}:${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+/** Props handed to a React inline tool's `component` (its toolbar icon/UI). */
+export interface ReactInlineToolRenderProps<Config = Record<string, unknown>> {
+  /**
+   * Whether the tool's formatting is active for the current selection —
+   * derived from the spec's `checkState` every time the toolbar queries it.
+   * Pushed IN PLACE (no remount), so the icon restyles live.
+   */
+  active: boolean;
+  /**
+   * The tool's `config` from the consumer's `tools` map (adapter-internal
+   * keys stripped) — the channel for host props (palette, locale…).
+   */
+  config: Readonly<Partial<Config>>;
+}
+
+/** Spec for {@link createReactInlineTool}. */
+export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
+  /** 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;
+  /** Keyboard shortcut (e.g. `CMD+SHIFT+C`). */
+  shortcut?: string;
+  /** Inline sanitizer config declaring the markup this tool produces. */
+  sanitize?: SanitizerConfig;
+  /** Whether the tool stays available in read-only mode. */
+  isReadOnlySupported?: boolean;
+}
+
+/**
+ * Author a first-party React inline tool. Returns an inline-tool constructable
+ * registered exactly like a vanilla tool (`tools: { color: createReactInlineTool(...) }`).
+ *
+ * Mirrors the `createReactBlock` portal pattern: `render()` returns a
+ * `MenuConfig` whose `icon` is a Blok-owned host element
+ * (`data-blok-mutation-free`) the component is portaled into via the editor's
+ * shared `BlockPortalHost` tree — app-level context (themes, styled-components
+ * providers) reaches the icon with no consumer-managed `createRoot`, and
+ * `destroy()` (called by the inline toolbar on close/teardown) unregisters the
+ * portal so the component unmounts deterministically — no leaked React roots.
+ *
+ * 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>
+): (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;
+} {
+  return class ReactInlineTool implements InlineTool {
+    /** Marker so `useBlok` can detect react inline tools and inject the registry. */
+    public static readonly __isBlokReactInlineTool = true as const;
+    public static readonly isInline = true as const;
+
+    public static get title(): string | undefined {
+      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;
+    }
+
+    public static get isReadOnlySupported(): boolean {
+      return spec.isReadOnlySupported ?? false;
+    }
+
+    private readonly registry: BlockPortalRegistry | 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>>;
+    /** Last active state pushed to the mounted component (change-dedup baseline). */
+    private active = false;
+    /** True while this instance owns a registered portal entry. */
+    private registered = false;
+
+    public constructor(options: InlineToolConstructorOptions) {
+      const config: Record<string, unknown> = options?.config ?? {};
+
+      this.registry = config[BLOK_PORTAL_REGISTRY_CONFIG_KEY] as BlockPortalRegistry | undefined;
+
+      const toolName = config[BLOK_TOOL_NAME_CONFIG_KEY];
+
+      this.toolName = typeof toolName === 'string' ? toolName : spec.type;
+      this.portalKey = generatePortalKey(this.toolName);
+
+      const publicConfig: Record<string, unknown> = {};
+
+      for (const [key, value] of Object.entries(config)) {
+        if (!INTERNAL_CONFIG_KEYS.includes(key)) {
+          publicConfig[key] = value;
+        }
+      }
+      this.toolConfig = Object.freeze(publicConfig) as Readonly<Partial<Config>>;
+    }
+
+    public render(): MenuConfig {
+      // The Blok-owned host: React reconciles the icon portaled INTO it, and
+      // this attribute makes core's MutationObserver ignore those mutations.
+      const host = document.createElement('div');
+
+      host.setAttribute('data-blok-mutation-free', 'true');
+
+      if (this.registry !== undefined) {
+        this.registry.register(this.portalKey, {
+          hostEl: host,
+          component: spec.component as unknown as ComponentType<Record<string, unknown>>,
+          props: { active: this.active, config: this.toolConfig },
+          toolName: this.toolName,
+        });
+        this.registered = true;
+      }
+
+      return {
+        name: this.toolName,
+        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));
+        },
+        isActive: (): boolean => this.refreshActiveState(),
+      };
+    }
+
+    /**
+     * Idempotent teardown, called by the inline toolbar when this instance is
+     * dropped (toolbar close, editor destroy, or a throwaway render probe).
+     * Unregisters the portal entry so React unmounts the icon component —
+     * the unmount signal consumer-managed `createRoot` hacks never had.
+     */
+    public destroy(): void {
+      if (!this.registered) {
+        return;
+      }
+
+      this.registered = false;
+      this.registry?.unregister(this.portalKey);
+    }
+
+    /**
+     * 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;
+
+      if (active !== this.active) {
+        this.active = active;
+
+        if (this.registered) {
+          this.registry?.setProps(this.portalKey, { active });
+        }
+      }
+
+      return active;
+    }
+  };
+}

package/src/index.ts

@@ -9,9 +9,17 @@ export { createReactBlock } from './createReactBlock';
 export type {
   CreateReactBlockSpec,
   ReactBlockRenderProps,
+  ReactBlockViewProps,
+  ReactToolboxConfig,
+  ReactToolboxConfigEntry,
   PropSchema,
   PropSchemaEntry,
 } from './createReactBlock';
+export { createReactInlineTool } from './createReactInlineTool';
+export type {
+  CreateReactInlineToolSpec,
+  ReactInlineToolRenderProps,
+} from './createReactInlineTool';
 export {
   createBlockPortalRegistry,
   BLOK_PORTAL_REGISTRY_CONFIG_KEY,

package/src/provide-blok.tsx

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