@bloklabs/react 1.2.6 → 1.4.0

package/types/index.d.ts

@@ -1,6 +1,8 @@
-import type { BlokConfig, BlockToolData, OutputBlockData, OutputData } from '@bloklabs/core';
-import type { BlockAPI, BlockToolConstructable, ToolboxConfig } from '@bloklabs/core';
+import type { BlokConfig, BlockToolData, OutputBlockData, OutputData, LooseOutputData } from '@bloklabs/core';
+import type { BlocksToHtmlOptions } from '@bloklabs/core/view';
+import type { BlockAPI, BlockToolConstructable, ToolboxConfigEntry } from '@bloklabs/core';
 import type { InlineToolConstructable, SanitizerConfig } from '@bloklabs/core';
+import type { API, MarkSnapshot, MarkSpec } from '@bloklabs/core';
 import type { Blok, EditorWidth, BlockRenderedPayload, BlocksRenderedPayload } from '@bloklabs/core';
 import type { BlockTuneData } from '@bloklabs/core';
 import type { MarkdownImportConfig } from '@bloklabs/core/markdown';
@@ -11,11 +13,21 @@ import type React from 'react';
  * Accepts all BlokConfig properties except `holder`, plus a React-only `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)`
  * - `placeholder` — calls `editor.placeholder.set(value)`
+ * - `style.tokens` — calls `editor.tokens.set(value)` (deep-equal–deduped;
+ *   replace semantics, so pass the complete token set on each change)
+ * - `i18n` — calls `editor.i18n.update({ locale, messages, direction })`
+ *   (deep-equal–deduped; relabels the editor chrome in place, so caret, focus
+ *   and undo history survive a language switch). `defaultLocale` is not
+ *   forwarded — it only affects the initial locale resolution.
  * - `data` — re-renders via `editor.render(value)` when the content changes
  *   (deep-equal–deduped and serialized; seeds the initial content at creation)
  *
@@ -541,6 +553,43 @@ export interface UseBlocksApi {
  */
 export declare function useBlocks(editor: Blok | null): UseBlocksApi;
 
+// ---------------------------------------------------------------------------
+// Scoped readiness (useBlokReady)
+// ---------------------------------------------------------------------------
+
+/** 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; it is re-read on every readiness
+   * change, so a ref that attaches after the first render is picked up.
+   *
+   * Omit it to observe every editor on the page.
+   */
+  within?: React.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 keeps
+ * following 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 declare function useBlokReady(options?: UseBlokReadyOptions): boolean;
+
 // ---------------------------------------------------------------------------
 // Block authoring (createReactBlock + portal host)
 // ---------------------------------------------------------------------------
@@ -587,15 +636,46 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   BlockChildren: React.ComponentType;
 }
 
+/**
+ * Props handed to a React block's `viewComponent` (the read-only renderer):
+ * the entry props minus `commit` (no write path) and `readOnly` (always true).
+ */
+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. Accepts the markup string core consumes directly, or the same
+   * React element rendered in the block body — the factory serializes elements
+   * 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 | React.ReactElement;
+};
+
+/** Toolbox config for React blocks: single entry or several variants. */
+export type ReactToolboxConfig = ReactToolboxConfigEntry | ReactToolboxConfigEntry[];
+
 /** Spec for {@link createReactBlock}. */
 export interface CreateReactBlockSpec<
   Data extends BlockToolData = BlockToolData,
   Config = Record<string, unknown>
 > {
   type: string;
-  toolbox?: ToolboxConfig;
+  toolbox?: ReactToolboxConfig;
   propSchema: PropSchema;
   component: React.ComponentType<ReactBlockRenderProps<Data, Config>>;
+  /**
+   * Optional read-only renderer: rendered INSTEAD of `component` while the
+   * editor is read-only, so blocks need no display-vs-edit ternary. Toggling
+   * read-only swaps renderers (ephemeral state does not survive the swap);
+   * omit it to keep the single-component in-place toggle.
+   */
+  viewComponent?: React.ComponentType<ReactBlockViewProps<Data, Config>>;
   onRendered?: (block: BlockAPI) => void;
   onMoved?: (block: BlockAPI) => void;
   onRemoved?: (block: BlockAPI) => void;
@@ -644,21 +724,86 @@ 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;
+}
+
+/**
+ * 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 declare function useInlineTool<Config = Record<string, unknown>, State = void>(): 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: React.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;
@@ -680,13 +825,12 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
  *   type: 'descriptionColor',
  *   title: 'Text color',
  *   component: ({ active }) => <FontColorIcon active={active} />,
- *   surround: (range) => applyColor(range),
- *   checkState: (selection) => hasColor(selection),
+ *   mark: { tag: 'span', className: 'hl-description' },
  * });
  * ```
  */
-export declare function createReactInlineTool<Config = Record<string, unknown>>(
-  spec: CreateReactInlineToolSpec<Config>
+export declare function createReactInlineTool<Config = Record<string, unknown>, State = void>(
+  spec: CreateReactInlineToolSpec<Config, State>
 ): InlineToolConstructable;
 
 /**
@@ -745,3 +889,49 @@ export interface BlockPortalHostProps {
  * for advanced setups that manage the registry themselves.
  */
 export declare function BlockPortalHost(props: BlockPortalHostProps): React.ReactElement;
+
+/**
+ * Props for {@link BlokView}.
+ *
+ * @experimental Built on the `@experimental` view tree of
+ * `@bloklabs/core/view` — not frozen until a second framework adapter
+ * consumes it.
+ */
+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, so it renders identically
+ * under SSR.
+ *
+ * @experimental Not frozen until a second framework adapter consumes the
+ * underlying view tree.
+ */
+export declare function BlokView(props: BlokViewProps): React.ReactNode;
+
+/**
+ * Render a saved Blok document to React elements with NO wrapper element —
+ * a Fragment of the block elements, for placement inside labels, table
+ * cells, and other slots where an extra `<div>` is invalid or unwanted.
+ * Synchronous, effect-free (SSR-safe), memoized on the data reference and
+ * the individual option values.
+ *
+ * @experimental Not frozen until a second framework adapter consumes the
+ * underlying view tree.
+ */
+export declare function useBlokView(
+  data: OutputData | LooseOutputData | null | undefined,
+  options?: BlocksToHtmlOptions
+): React.ReactNode;