@bloklabs/react 1.3.0 → 1.4.0

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

package/types/index.d.ts

@@ -1,6 +1,8 @@
-import type { BlokConfig, BlockToolData, OutputBlockData, OutputData } 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)
 // ---------------------------------------------------------------------------
@@ -675,8 +724,47 @@ 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). */
@@ -690,13 +778,32 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>> {
   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;
@@ -718,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;
 
 /**
@@ -783,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;