@bloklabs/react 1.4.2 → 1.4.4

package/src/useBlokView.ts

@@ -14,11 +14,11 @@ import { viewNodesToReact } from './view-nodes-to-react';
  * Synchronous and effect-free (SSR-safe); memoized on the data reference and
  * the individual option values.
  *
- * @experimental Built on the `@experimental` ViewNode tree of
- * `@bloklabs/core/view` — not frozen until a second framework adapter
- * consumes it.
+ * 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 / custom renderers / unknown-block policy
+ * @param options - schema / renderers / unknown-block policy / toolAttributes / blockIds / transformUrl
  */
 export const useBlokView = (
   data: OutputData | LooseOutputData | null | undefined,
@@ -27,12 +27,17 @@ export const useBlokView = (
   const schema = options?.schema;
   const renderers = options?.renderers;
   const onUnknownBlock = options?.onUnknownBlock;
+  const toolAttributes = options?.toolAttributes;
+  const blockIds = options?.blockIds;
+  const transformUrl = options?.transformUrl;
 
   return useMemo(() => {
     return createElement(
       Fragment,
       null,
-      ...viewNodesToReact(blocksToViewNodes(data, { schema, renderers, onUnknownBlock }))
+      ...viewNodesToReact(
+        blocksToViewNodes(data, { schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl })
+      )
     );
-  }, [data, schema, renderers, onUnknownBlock]);
+  }, [data, schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl]);
 };

package/types/index.d.ts

@@ -8,6 +8,11 @@ import type { BlockTuneData } from '@bloklabs/core';
 import type { MarkdownImportConfig } from '@bloklabs/core/markdown';
 import type React from 'react';
 
+// Host-i18n bridge (#41): the direction/normalization helpers re-exported by
+// the runtime index. Bare `@bloklabs/core/locales` resolves to the core's own
+// self-contained declaration, so this stays free of any `../src` reference.
+export { getDirection, normalizeLocale } from '@bloklabs/core/locales';
+
 /**
  * Configuration for the useBlok hook.
  * Accepts all BlokConfig properties except `holder`, plus a React-only `width` prop.
@@ -102,6 +107,13 @@ export interface BlokEditorProps
   'data-testid'?: string;
   /** Called once the editor is ready, with the live Blok instance (ref is also committed). */
   onReady?: (editor: Blok) => void;
+  /**
+   * Library-neutral shorthand for the active locale — a plain BCP-47 string the
+   * host owns and updates. Normalized and routed to `editor.i18n.update` in
+   * place. Shorthand for `i18n={{ locale }}` (wins if both are set); pair with
+   * the re-exported `getDirection` / `normalizeLocale` to compute `dir`.
+   */
+  locale?: string;
   /**
    * Called after a batch render completes (core `blocks:rendered` event). The
    * declarative analog of `ref.current.on('blocks:rendered', …)` — mirrors the
@@ -131,6 +143,47 @@ export declare const BlokEditor: React.ForwardRefExoticComponent<
   BlokEditorProps & React.RefAttributes<Blok | null>
 >;
 
+/**
+ * A typed, null-safe imperative handle for a `<BlokEditor>`. Its methods safely
+ * no-op until the editor is ready, so consumers don't re-declare a
+ * `forwardRef`/`useImperativeHandle` with `?.` guards. Attach via
+ * `<BlokEditor ref={handle.ref} />`.
+ *
+ * `current` / `isReady` are imperative reads (they do NOT trigger a re-render
+ * when readiness flips — use `useBlokReady` for that); `current` is the escape
+ * hatch to the full editor API beyond the shortcuts below.
+ */
+export interface BlokEditorHandle {
+  /** Ref callback to attach to `<BlokEditor ref={handle.ref} />`. Stable across renders. */
+  readonly ref: React.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. */
+  focus(atEnd?: boolean): boolean;
+  /** Clear all content. Resolves immediately (no-op) before ready. */
+  clear(): Promise<void>;
+  /** Serialize the current content, or resolve to `null` before ready. */
+  save(): Promise<OutputData | null>;
+  /** Render new content in place. Resolves immediately (no-op) before ready. */
+  render(data: OutputData | LooseOutputData): Promise<void>;
+  /** Set or toggle read-only mode. Resolves to the resulting state; `false` (no-op) before ready. */
+  setReadOnly(state?: boolean): Promise<boolean>;
+}
+
+/**
+ * Returns a stable, null-safe {@link BlokEditorHandle} for a `<BlokEditor>`.
+ *
+ * @example
+ * ```tsx
+ * const blok = useBlokHandle();
+ * <BlokEditor ref={blok.ref} tools={tools} data={data} />;
+ * <button onClick={() => blok.focus()}>Focus</button>;
+ * ```
+ */
+export declare function useBlokHandle(): BlokEditorHandle;
+
 /**
  * Registers app-wide Blok defaults for every `useBlok` / `<BlokEditor>` rendered
  * beneath it. Per-instance config overrides these, and the `tools` registry is
@@ -645,8 +698,8 @@ export type ReactBlockViewProps<Data, Config = Record<string, unknown>> = Omit<
   'commit' | 'readOnly'
 >;
 
-/** A toolbox entry whose `icon` may be a React element instead of an SVG string. */
-export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
+/** A toolbox entry whose `icon`/`title` may be a React element instead of a string. */
+export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon' | 'title'> & {
   /**
    * Toolbox icon. Accepts the markup string core consumes directly, or the same
    * React element rendered in the block body — the factory serializes elements
@@ -655,6 +708,16 @@ export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
    * serialization retries on the next browser-side access.
    */
   icon?: string | React.ReactElement;
+  /**
+   * Toolbox label. A plain string is translated by core through the
+   * `toolNames.*` namespace. A ReactElement instead renders live in the host's
+   * React tree (via the editor's shared BlockPortalHost), so the label tracks
+   * the host's OWN i18n — no mirroring strings into Blok's dictionary. Pair a
+   * ReactElement title with `titleKey` so multilingual search still resolves an
+   * English term. Requires `useBlok`/`BlokEditor` (which wires the portal
+   * registry); with vanilla core a ReactElement title is dropped.
+   */
+  title?: string | React.ReactElement;
 };
 
 /** Toolbox config for React blocks: single entry or several variants. */
@@ -771,9 +834,9 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>, Sta
   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.
+   * `toolNames.{titleKey}` (or used verbatim when it contains a dot). Defaults
+   * to `type`, so a custom tool localizes through the conventional
+   * `toolNames.{type}` key (as built-in tools do) with no extra wiring.
    */
   titleKey?: string;
   /** The component rendered as the tool's toolbar icon/UI. */
@@ -831,7 +894,20 @@ export interface CreateReactInlineToolSpec<Config = Record<string, unknown>, Sta
  */
 export declare function createReactInlineTool<Config = Record<string, unknown>, State = void>(
   spec: CreateReactInlineToolSpec<Config, State>
-): InlineToolConstructable;
+): InlineToolConstructable & {
+  readonly __isBlokReactInlineTool: true;
+  readonly isInline: true;
+  /** The tool's type name (also the default `titleKey`). */
+  readonly type: string;
+  readonly title: string | undefined;
+  /** Translation key core resolves as `toolNames.{titleKey}`; defaults to `type`. */
+  readonly titleKey: string;
+  readonly shortcut: string | undefined;
+  /** The declared mark spec, exposed so tools can be unit-tested without mocking the factory. */
+  readonly mark: MarkSpec<State> | undefined;
+  readonly sanitize: SanitizerConfig | undefined;
+  readonly isReadOnlySupported: boolean;
+};
 
 /**
  * Tool-config key carrying the editor's portal registry into a
@@ -891,13 +967,11 @@ export interface BlockPortalHostProps {
 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.
+ * Props for {@link BlokView}. Beyond the render options below, any standard
+ * `<div>` attribute (`id`, `style`, `data-*`, `aria-*`, event handlers, …) is
+ * forwarded onto the single wrapper element.
  */
-export interface BlokViewProps {
+export interface BlokViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
   /** 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. */
@@ -906,18 +980,23 @@ export interface BlokViewProps {
   renderers?: BlocksToHtmlOptions['renderers'];
   /** Unknown-tool policy (default 'skip'). */
   onUnknownBlock?: BlocksToHtmlOptions['onUnknownBlock'];
-  /** Class for the single wrapper div. */
-  className?: string;
+  /** Stamp `data-blok-tool="<type>"` on each block root as a styling hook (pairs with the opt-in view stylesheet). */
+  toolAttributes?: BlocksToHtmlOptions['toolAttributes'];
+  /** Stamp `data-blok-id="<id>"` on each block root (list items on their `<li>`) for "copy link to block" deep links. */
+  blockIds?: BlocksToHtmlOptions['blockIds'];
+  /** Pure URL rewrite hook for block URLs + inline anchors, run before the unsafe-scheme strip. */
+  transformUrl?: BlocksToHtmlOptions['transformUrl'];
 }
 
 /**
  * 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.
+ * editor chrome, 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.
+ * The intended read-only path — reach for it instead of `BlokEditor readOnly`,
+ * which ships the full editing runtime to every viewer. The props API is
+ * semver-stable; only the raw `ViewNode` tree the bindings map from remains
+ * `@experimental`, and using `BlokView` never exposes you to it.
  */
 export declare function BlokView(props: BlokViewProps): React.ReactNode;
 
@@ -928,8 +1007,8 @@ export declare function BlokView(props: BlokViewProps): React.ReactNode;
  * 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.
+ * The props-based signature is semver-stable; only the raw `ViewNode` tree the
+ * bindings map from remains `@experimental`.
  */
 export declare function useBlokView(
   data: OutputData | LooseOutputData | null | undefined,