@bloklabs/react 1.15.1 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "React block editor — official React bindings for Blok, the headless Notion-like rich text editor. Hooks and components that render blocks and save to JSON.",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -54,7 +54,7 @@
     "test": "yarn run -T vitest run"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.15.1",
+    "@bloklabs/core": "^1.16.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokView.tsx

@@ -26,6 +26,10 @@ export interface BlokViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'chi
   transformUrl?: BlocksToHtmlOptions['transformUrl'];
   /** Custom renderers for inline elements, keyed by lowercase tag name (equations, mentions). */
   inlineRenderers?: BlocksToHtmlOptions['inlineRenderers'];
+  /** Build the link for a `page` block from its `pageId`. A page card is a link only with this and an allowing {@link pageInfo}. */
+  pageHref?: BlocksToHtmlOptions['pageHref'];
+  /** Host metadata (title, icon, access) for a `page` block. Without it a page card shows a neutral "Page" label and no link. */
+  pageInfo?: BlocksToHtmlOptions['pageInfo'];
   /**
    * Render with the editor's presentational classes and per-block scaffolding
    * so the output matches a read-only editor render (default `true`). Needs
@@ -33,6 +37,8 @@ export interface BlokViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'chi
    * semantic markup.
    */
   classes?: BlocksToHtmlOptions['classes'];
+  /** Document direction: set as `dir` on the wrapper, and each block follows its own text. */
+  direction?: BlocksToHtmlOptions['direction'];
 }
 
 /**
@@ -59,7 +65,10 @@ export const BlokView = ({
   blockIds,
   transformUrl,
   inlineRenderers,
+  pageHref,
+  pageInfo,
   classes,
+  direction,
   ...divProps
 }: BlokViewProps): ReactNode => {
   /**
@@ -77,7 +86,10 @@ export const BlokView = ({
     blockIds,
     transformUrl,
     inlineRenderers,
+    pageHref,
+    pageInfo,
     classes: classes ?? true,
+    direction,
   });
 
   /**
@@ -90,5 +102,5 @@ export const BlokView = ({
    *
    * Written BEFORE the `divProps` spread so a caller can still override it.
    */
-  return <div data-blok-interface="view" {...divProps}>{content}</div>;
+  return <div data-blok-interface="view" dir={direction} {...divProps}>{content}</div>;
 };

package/src/config-keys.ts

@@ -23,6 +23,7 @@ export const USE_BLOK_CONFIG_KEYS = [
   'tools',
   'data',
   'minHeight',
+  'loader',
   'logLevel',
   'readOnly',
   'i18n',
@@ -33,12 +34,14 @@ export const USE_BLOK_CONFIG_KEYS = [
   'onChange',
   'onSave',
   'onError',
+  'onImageFailure',
   'onEnter',
   'onSubmit',
   'onBeforeRender',
   'onAfterRender',
   'inlineToolbar',
   'inlineEmoji',
+  'find',
   'tunes',
   'style',
   'theme',
@@ -51,10 +54,13 @@ export const USE_BLOK_CONFIG_KEYS = [
   'width',
   'migrations',
   'uploader',
+  'media',
   'server',
   'ticket',
   'persistence',
   'collaboration',
+  'documentId',
+  'tabSync',
   'captureClicksBelowEditor',
 ] as const satisfies readonly (keyof UseBlokConfig)[];
 
@@ -64,5 +70,3 @@ export const USE_BLOK_CONFIG_KEYS = [
  */
 type _MissingConfigKey = Exclude<keyof UseBlokConfig, (typeof USE_BLOK_CONFIG_KEYS)[number]>;
 const _exhaustive: _MissingConfigKey extends never ? true : never = true;
-
-void _exhaustive;

package/src/createReactBlock.tsx

@@ -10,6 +10,7 @@ import {
   fillDefaults,
   mountChildBlocks,
   type PropSchema,
+  withSlotlessDescendants,
 } from '@bloklabs/core/adapters';
 import {
   BLOK_PORTAL_REGISTRY_CONFIG_KEY,
@@ -330,6 +331,15 @@ export interface CreateReactBlockSpec<Data = BlockToolData, Config = Record<stri
    * @param block - this block's per-block API
    */
   getToolbarAnchorElement?: (host: HTMLElement, block: BlockAPI) => HTMLElement | null | undefined;
+  /**
+   * Enter (or Cmd/Ctrl+Enter) on this block while it is the keyboard
+   * navigation target — core's `onNavigationEnter` hook. Return true when the
+   * block handled it (e.g. opened a link); omit it, or return false, to let
+   * core put the caret in the block.
+   * @param event - the Enter keydown
+   * @param block - this block's per-block API
+   */
+  onNavigationEnter?: (event: KeyboardEvent, block: BlockAPI) => boolean;
   /** Optional lifecycle callbacks mapped from Blok's block hooks. */
   onRendered?: (block: BlockAPI) => void;
   /**
@@ -412,6 +422,7 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
   setData(newData: BlockToolData): Promise<boolean>;
   setReadOnly(state: boolean): void;
   getToolbarAnchorElement(): HTMLElement | undefined;
+  onNavigationEnter(event: KeyboardEvent): boolean;
   rendered(): void;
   moved(): void;
   removed(): void;
@@ -758,7 +769,9 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 
           const children = blockApi.getChildren();
 
-          mountChildBlocks(slotRef.current, children);
+          // A slotless child's own children live in this slot too. Decoration and
+          // the mounted event stay per DIRECT child.
+          mountChildBlocks(slotRef.current, withSlotlessDescendants(children, id => api.blocks.getChildren(id)));
           applyChildDecoration(ledgerRef.current, children, { childAttributes,
             childContentAttributes });
           emitChildrenMounted(api, blockApi.id, children);
@@ -910,6 +923,14 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
       return spec.getToolbarAnchorElement(host, this.blockApi) ?? undefined;
     }
 
+    /**
+     * Core's navigation-mode Enter hook. Only a real `true` from the spec
+     * counts as handled.
+     */
+    public onNavigationEnter(event: KeyboardEvent): boolean {
+      return spec.onNavigationEnter?.(event, this.blockApi) === true;
+    }
+
     public moved(): void {
       // No remount: Blok relocates the host element; the portal follows it.
       spec.onMoved?.(this.blockApi);

package/src/useBlok.ts

@@ -186,8 +186,11 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   // surfaced anywhere.
   const constructedCollaborationRef = useRef(config.collaboration);
   const renderChainRef = useRef<Promise<void>>(Promise.resolve());
-  // One collaboration warning per hook instance (see the data effect).
-  const collaborationWarnedRef = useRef(false);
+  // Editor the single collaboration warning has already been emitted for (see
+  // the data effect). Keyed by the editor, not a boolean, so the editor a `deps`
+  // change creates warns on its own first ignored `data` change instead of
+  // inheriting the previous editor's "already warned" flag and going silent.
+  const collaborationWarnedForRef = useRef<Blok | null>(null);
   // The content of the render currently queued/in-flight (distinct from
   // `lastRenderedDataRef`, which tracks the last SUCCESSFULLY rendered content).
   // Used to dedupe a re-queue of the same in-flight content without advancing the
@@ -716,22 +719,26 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   const appliedI18nRef = useRef<UseBlokConfig['i18n']>(config.i18n);
 
   useEffect(() => {
-    if (editor === null || i18n === undefined) {
+    const previous = appliedI18nRef.current;
+
+    if (editor === null || (i18n === undefined && previous?.direction === undefined)) {
       return;
     }
 
-    if (deepEqual(i18n, appliedI18nRef.current)) {
+    if (deepEqual(i18n, previous)) {
       return;
     }
 
     appliedI18nRef.current = i18n;
 
-    const { locale, messages, direction } = i18n;
+    const { locale, messages, direction } = i18n ?? {};
+    // A dropped direction must be cleared, or the editor keeps the old one.
+    const nextDirection = direction ?? (previous?.direction === undefined ? undefined : null);
 
     void editor.i18n.update({
       ...(locale === undefined ? {} : { locale }),
       ...(messages === undefined ? {} : { messages }),
-      ...(direction === undefined ? {} : { direction }),
+      ...(nextDirection === undefined ? {} : { direction: nextDirection }),
     });
   }, [editor, i18n]);
 
@@ -829,8 +836,8 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     const mountedCollaboration = constructedCollaborationRef.current;
 
     if (mountedCollaboration !== undefined) {
-      if (!collaborationWarnedRef.current) {
-        collaborationWarnedRef.current = true;
+      if (collaborationWarnedForRef.current !== editor) {
+        collaborationWarnedForRef.current = editor;
         console.warn(collaborationDataIgnoredMessage(mountedCollaboration.doc));
       }
 

package/src/useBlokHandle.ts

@@ -44,6 +44,8 @@ export interface BlokEditorHandle {
   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.
    *
@@ -111,6 +113,8 @@ export function useBlokHandle(): BlokEditorHandle {
     },
     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;
 

package/src/useBlokView.ts

@@ -18,7 +18,7 @@ import { viewNodesToReact } from './view-nodes-to-react';
  * 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
+ * @param options - schema / renderers / inlineRenderers / unknown-block policy / toolAttributes / blockIds / transformUrl / pageHref / pageInfo
  */
 export const useBlokView = (
   data: OutputData | LooseOutputData | null | undefined,
@@ -31,7 +31,10 @@ export const useBlokView = (
   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(
@@ -46,6 +49,8 @@ export const useBlokView = (
           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
@@ -57,8 +62,9 @@ export const useBlokView = (
            * already owns a wrapper and its job IS to look like the editor.
            */
           classes,
+          direction,
         })
       )
     );
-  }, [data, schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl, inlineRenderers, classes]);
+  }, [data, schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl, inlineRenderers, pageHref, pageInfo, classes, direction]);
 };

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

@@ -48,6 +48,18 @@ const ATTRIBUTE_NAME_MAP: Record<string, string> = {
   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;
@@ -85,8 +97,9 @@ const styleStringToObject = (css: string): CSSProperties => {
  * 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): Record<string, unknown> => {
+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)) {
@@ -110,7 +123,7 @@ const attrsToProps = (attrs: Record<string, string>, key: number): Record<string
       continue;
     }
 
-    props[ATTRIBUTE_NAME_MAP[name] ?? name] = value;
+    props[ATTRIBUTE_NAME_MAP[name] ?? (inSvg ? svgPropName(name) : name)] = value;
   }
 
   return props;
@@ -120,19 +133,21 @@ const attrsToProps = (attrs: Record<string, string>, key: number): Record<string
  * 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[]): ReactNode[] => {
+export const viewNodesToReact = (nodes: ViewNode[], inSvg = false): ReactNode[] => {
   return nodes.map((node, index): ReactNode => {
     if ('text' in node) {
       return node.text;
     }
 
-    const props = attrsToProps(node.attrs, index);
+    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));
+    return createElement(node.tag, props, ...viewNodesToReact(node.children, svg));
   });
 };

package/types/index.d.ts

@@ -192,6 +192,8 @@ export interface BlokEditorHandle {
   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
@@ -521,8 +523,12 @@ export interface UseBlocksApi {
    * the React-surface counterpart of core's `transactWithoutCapture`. Use for
    * silent auto-repair/normalization that a user's undo should never step
    * through. Mutations inside still emit reactively. Pre-ready it just runs `fn`.
+   *
+   * With `options`, the operations are data worked out from the `from` keys of
+   * block `derivedFrom` (a finished upload, for example): they join the undo
+   * entry that wrote those values, as in core.
    */
-  transactWithoutCapture(fn: () => void): void;
+  transactWithoutCapture(fn: () => void, options?: { derivedFrom?: string; from?: readonly string[] }): void;
   /** The current block count. Reactive (re-reads on 'block changed'). Pre-ready: 0. */
   getBlocksCount(): number;
   /** The flat index of the block holding the caret, or -1 when none. Pre-ready: -1. */
@@ -908,6 +914,15 @@ export interface CreateReactBlockSpec<
    * `null`/`undefined` (or omit) to keep core's default.
    */
   getToolbarAnchorElement?: (host: HTMLElement, block: BlockAPI) => HTMLElement | null | undefined;
+  /**
+   * Enter (or Cmd/Ctrl+Enter) on this block while it is the keyboard
+   * navigation target — core's `onNavigationEnter` hook. Return true when the
+   * block handled it (e.g. opened a link); omit it, or return false, to let
+   * core put the caret in the block.
+   * @param event - the Enter keydown
+   * @param block - this block's per-block API
+   */
+  onNavigationEnter?: (event: KeyboardEvent, block: BlockAPI) => boolean;
   onRendered?: (block: BlockAPI) => void;
   /**
    * Fired ONCE per block instance, after the portal's FIRST commit — the first
@@ -1219,6 +1234,10 @@ export interface BlokViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   transformUrl?: BlocksToHtmlOptions['transformUrl'];
   /** Custom renderers for inline elements, keyed by lowercase tag name (equations, mentions). */
   inlineRenderers?: BlocksToHtmlOptions['inlineRenderers'];
+  /** Build the link for a `page` block from its `pageId`. A page card is a link only with this and an allowing {@link pageInfo}. */
+  pageHref?: BlocksToHtmlOptions['pageHref'];
+  /** Host metadata (title, icon, access) for a `page` block. Without it a page card shows a neutral "Page" label and no link. */
+  pageInfo?: BlocksToHtmlOptions['pageInfo'];
   /**
    * Render with the editor's presentational classes and per-block scaffolding
    * so the output matches a read-only editor render (default `true`). Needs
@@ -1226,6 +1245,8 @@ export interface BlokViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    * semantic markup.
    */
   classes?: BlocksToHtmlOptions['classes'];
+  /** Document direction: set as `dir` on the wrapper, and each block follows its own text. */
+  direction?: BlocksToHtmlOptions['direction'];
 }
 
 /**