@bloklabs/react 1.16.1 → 2.0.0

package/src/useBlokHandle.ts

@@ -1,141 +0,0 @@
-import { useRef, useMemo, type RefCallback } from 'react';
-import { EMPTY_OUTPUT_DATA } from '@bloklabs/core/adapters';
-import { getContentBaseline } from './content-baseline-map';
-import type { Blok, OutputData, LooseOutputData } from '@/types';
-
-/**
- * A typed, null-safe imperative handle for a Blok editor embedded via
- * `<BlokEditor>`. Solves the "raw ref is `Blok | null` until ready" papercut:
- * instead of every consumer re-declaring a `forwardRef`/`useImperativeHandle`
- * with `?.` guards, `useBlokHandle()` returns this stable object whose methods
- * safely no-op until the editor is ready.
- *
- * Attach it via `ref`: `<BlokEditor ref={handle.ref} … />`. The methods read the
- * live instance through an internal ref, so they can be called from event
- * handlers without re-subscribing, and they stay valid across re-renders.
- *
- * `current` / `isReady` are IMPERATIVE reads (they reflect the instance at call
- * time and do NOT trigger a re-render when readiness flips). For render-reactive
- * readiness use `useBlokReady`; drop to `current` when you need the full editor
- * API beyond the handful of shortcuts below.
- */
-export interface BlokEditorHandle {
-  /**
-   * Ref callback to attach to `<BlokEditor ref={handle.ref} />`. Stable across
-   * renders. Stores the live instance (or null before ready / after unmount).
-   */
-  readonly ref: RefCallback<Blok | null>;
-  /** The live editor instance, or null before ready / after unmount. */
-  readonly current: Blok | null;
-  /** True once the editor is ready (the ref has been populated). */
-  readonly isReady: boolean;
-  /**
-   * Focus the editor. Returns whether focus landed; `false` (no-op) before ready.
-   * @param atEnd - place the caret at the end of the focused block
-   */
-  focus(atEnd?: boolean): boolean;
-  /**
-   * Clear all content. Resolves immediately (no-op) before ready.
-   *
-   * Safe to mix with a controlled `data` prop: the adapter's content baseline is
-   * updated once the clear lands, so setting `data` back to the document the
-   * editor itself emitted re-renders it instead of being dismissed as an echo.
-   */
-  clear(): Promise<void>;
-  /** Serialize the current content, or resolve to `null` before ready. */
-  save(): Promise<OutputData | null>;
-  /** Ask before an in-app navigation (see `Blok.confirmLeave`). Resolves `true` before ready. */
-  confirmLeave(): Promise<boolean>;
-  /**
-   * Render new content in place. Resolves immediately (no-op) before ready.
-   *
-   * Safe to mix with a controlled `data` prop: the rendered document becomes the
-   * adapter's content baseline, so a later `data` change back to the previous
-   * document still re-renders.
-   * @param data - the document to render
-   */
-  render(data: OutputData | LooseOutputData): Promise<void>;
-  /**
-   * Set or toggle read-only mode. Resolves to the resulting state; `false`
-   * (no-op) before ready.
-   * @param state - explicit state; omit to toggle
-   */
-  setReadOnly(state?: boolean): Promise<boolean>;
-}
-
-/**
- * Returns a stable, null-safe {@link BlokEditorHandle} for a `<BlokEditor>`.
- *
- * @example
- * ```tsx
- * const blok = useBlokHandle();
- * return (
- *   <>
- *     <BlokEditor ref={blok.ref} tools={tools} data={data} />
- *     <button onClick={() => blok.focus()}>Focus</button>
- *     <button onClick={() => blok.save().then(onSubmit)}>Send</button>
- *   </>
- * );
- * ```
- */
-export function useBlokHandle(): BlokEditorHandle {
-  const instanceRef = useRef<Blok | null>(null);
-
-  // Built once and kept stable: every method reads the live instance through
-  // `instanceRef`, so the handle identity (and its ref callback) never changes
-  // across renders even as the underlying editor is created or destroyed.
-  return useMemo<BlokEditorHandle>(() => ({
-    ref: (node): void => {
-      instanceRef.current = node;
-    },
-    get current(): Blok | null {
-      return instanceRef.current;
-    },
-    get isReady(): boolean {
-      return instanceRef.current !== null;
-    },
-    focus: (atEnd?: boolean): boolean => instanceRef.current?.focus(atEnd) ?? false,
-    // clear/render change the content OUT OF BAND of the controlled `data`
-    // effect, so they report the result to the adapter's content baseline (see
-    // content-baseline-map). Reported only once the call RESOLVES: a failed one
-    // leaves the editor on its previous content, and a baseline pointing at
-    // content the editor never showed would dedupe away the correcting update.
-    clear: (): Promise<void> => {
-      const instance = instanceRef.current;
-
-      if (instance === null) {
-        return Promise.resolve();
-      }
-
-      return instance.clear().then(() => {
-        getContentBaseline(instance)?.markRendered(EMPTY_OUTPUT_DATA);
-      });
-    },
-    save: (): Promise<OutputData | null> =>
-      instanceRef.current !== null ? instanceRef.current.save() : Promise.resolve(null),
-    confirmLeave: (): Promise<boolean> =>
-      instanceRef.current !== null ? instanceRef.current.confirmLeave() : Promise.resolve(true),
-    render: (data: OutputData | LooseOutputData): Promise<void> => {
-      const instance = instanceRef.current;
-
-      if (instance === null) {
-        return Promise.resolve();
-      }
-
-      return instance.render(data).then(() => {
-        getContentBaseline(instance)?.markRendered(data);
-      });
-    },
-    setReadOnly: (state?: boolean): Promise<boolean> => {
-      const instance = instanceRef.current;
-
-      if (instance === null) {
-        return Promise.resolve(false);
-      }
-
-      // Resolve the toggle here (omitted `state` flips current) so we can use the
-      // non-deprecated `set()`, which requires an explicit target state.
-      return instance.readOnly.set(state ?? !instance.readOnly.isEnabled);
-    },
-  }), []);
-}

package/src/useBlokReady.ts

@@ -1,60 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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.
- *
- * The props-based signature is semver-stable. The raw `ViewNode` tree the
- * bindings map from remains `@experimental` — but consumers of this hook never
- * touch it directly.
- * @param data - saved document (strict or loose wire shape; nullish tolerated)
- * @param options - schema / renderers / inlineRenderers / unknown-block policy / toolAttributes / blockIds / transformUrl / pageHref / pageInfo
- */
-export const useBlokView = (
-  data: OutputData | LooseOutputData | null | undefined,
-  options?: BlocksToHtmlOptions
-): ReactNode => {
-  const schema = options?.schema;
-  const renderers = options?.renderers;
-  const onUnknownBlock = options?.onUnknownBlock;
-  const toolAttributes = options?.toolAttributes;
-  const blockIds = options?.blockIds;
-  const transformUrl = options?.transformUrl;
-  const inlineRenderers = options?.inlineRenderers;
-  const pageHref = options?.pageHref;
-  const pageInfo = options?.pageInfo;
-  const classes = options?.classes;
-  const direction = options?.direction;
-
-  return useMemo(() => {
-    return createElement(
-      Fragment,
-      null,
-      ...viewNodesToReact(
-        blocksToViewNodes(data, {
-          schema,
-          renderers,
-          onUnknownBlock,
-          toolAttributes,
-          blockIds,
-          transformUrl,
-          inlineRenderers,
-          pageHref,
-          pageInfo,
-          /**
-           * Opt-in, NOT defaulted on. Parity rendering wraps every block in the
-           * core's holder → content scaffolding, which would contradict this
-           * hook's contract of emitting no wrapper element — the reason it
-           * exists is placement inside `<label>`s, table cells and other slots
-           * where extra elements are invalid or unwanted.
-           *
-           * `<BlokView>` passes `classes: true` for its own output, since it
-           * already owns a wrapper and its job IS to look like the editor.
-           */
-          classes,
-          direction,
-        })
-      )
-    );
-  }, [data, schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl, inlineRenderers, pageHref, pageInfo, classes, direction]);
-};

package/src/view-nodes-to-react.ts

@@ -1,153 +0,0 @@
-/**
- * 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',
-};
-
-/**
- * React names SVG attributes in camelCase (`stroke-width` → `strokeWidth`) and
- * warns on the raw form. Only inside `<svg>`: elsewhere a hyphenated name (a
- * custom element's attribute) must reach the DOM as written.
- * @param name - SVG attribute name
- */
-const svgPropName = (name: string): string => (
-  name.startsWith('aria-') || name.startsWith('data-')
-    ? name
-    : name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
-);
-
-/**
- * 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
- * @param inSvg - whether the element sits in an `<svg>` subtree
- */
-const attrsToProps = (attrs: Record<string, string>, key: number, inSvg: boolean): 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] ?? (inSvg ? svgPropName(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
- * @param inSvg - whether the siblings sit in an `<svg>` subtree
- */
-export const viewNodesToReact = (nodes: ViewNode[], inSvg = false): ReactNode[] => {
-  return nodes.map((node, index): ReactNode => {
-    if ('text' in node) {
-      return node.text;
-    }
-
-    const svg = inSvg || node.tag === 'svg';
-    const props = attrsToProps(node.attrs, index, svg);
-
-    if (VOID_ELEMENTS.has(node.tag) || node.children.length === 0) {
-      return createElement(node.tag, props);
-    }
-
-    return createElement(node.tag, props, ...viewNodesToReact(node.children, svg));
-  });
-};