@bloklabs/vue 1.7.0 → 1.8.0

package/src/useBlok.ts

@@ -10,8 +10,9 @@ import {
   type Ref,
 } from 'vue';
 import { Blok as BlokRuntime } from '@bloklabs/core';
+import { setContentBaseline, removeContentBaseline } from './content-baseline-map';
 import { setHolder, removeHolder } from './holder-map';
-import { deepEqual , normalizeReadOnlyConfig, toRenderableData } from '@bloklabs/core/adapters';
+import { deepEqual, equalsOutputData, normalizeReadOnlyConfig, toRenderableData } from '@bloklabs/core/adapters';
 import { BLOK_DEFAULT_CONFIG, mergeBlokDefaults } from './provide-blok';
 import {
   createBlockPortalRegistry,
@@ -19,9 +20,29 @@ import {
   type BlockPortalRegistry,
 } from './block-portal-registry';
 import { setRegistry, removeRegistry } from './registry-map';
-import type { Blok, BlokConfig, LooseOutputData, OutputData } from '@/types';
+import type { Blok, BlokConfig, LiveHandlers, LooseOutputData, OutputData } from '@/types';
 import type { UseBlokConfig } from './types';
 
+/** Presence map for the live callback config (see the handler watcher below). */
+type HandlerPresence = Record<keyof LiveHandlers, boolean>;
+
+/**
+ * Which live callbacks the config currently carries. PRESENCE is load-bearing
+ * in core — an `onSubmit` turns Enter into serialize-and-submit, an `onSave`
+ * arms the change-observation pipeline — so it is tracked separately from the
+ * callbacks themselves (whose identity the adapter keeps stable).
+ * @param config - the merged per-render config
+ * @returns one boolean per live handler key
+ */
+const readHandlerPresence = (config: UseBlokConfig): HandlerPresence => ({
+  onChange: config.onChange !== undefined,
+  onSave: config.onSave !== undefined,
+  onEnter: config.onEnter !== undefined,
+  onSubmit: config.onSubmit !== undefined,
+  onBeforeRender: config.onBeforeRender !== undefined,
+  onAfterRender: config.onAfterRender !== undefined,
+});
+
 /**
  * Inject the editor's portal registry into every `createVueBlock` tool's config
  * (vanilla tools are left untouched), returning a NEW tools object so the
@@ -97,19 +118,60 @@ export function useBlok(
   // - `lastRenderedData` is the content the editor currently reflects, updated
   //   when `data` is seeded/rendered AND when the editor emits its own serialized
   //   output via the `onSave` wrapper — so a controlled `update:data -> data`
-  //   echo deep-equals this baseline and is deduped to a no-op (no caret reset).
+  //   echo content-equals this baseline and is deduped to a no-op (no caret
+  //   reset). `undefined` means "nothing recorded yet" — never an empty document.
   const state: {
     current: Blok | null;
     holder: HTMLDivElement | null;
     lastRenderedData: OutputData | LooseOutputData | null | undefined;
     seededEditor: Blok | null;
     renderChain: Promise<void>;
+    appliedHandlerPresence: HandlerPresence;
   } = {
     current: null,
     holder: null,
     lastRenderedData: mergedConfig().data,
     seededEditor: null,
     renderChain: Promise.resolve(),
+    appliedHandlerPresence: {
+      onChange: false,
+      onSave: false,
+      onEnter: false,
+      onSubmit: false,
+      onBeforeRender: false,
+      onAfterRender: false,
+    },
+  };
+
+  /**
+   * Stable wrappers for the live callback config. Each forwards to the LATEST
+   * config through `mergedConfig()`, so callback identity never goes stale and
+   * only PRESENCE has to be synced after mount (the watcher below).
+   */
+  const handlerWrappers: Required<LiveHandlers> = {
+    onChange: (...args: Parameters<NonNullable<UseBlokConfig['onChange']>>): void => {
+      mergedConfig().onChange?.(...args);
+    },
+    onSave: (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
+      // Record the editor's own serialized output as the dedup baseline BEFORE
+      // notifying the consumer, so a controlled `update:data -> data` echo
+      // content-equals it and never re-renders.
+      state.lastRenderedData = args[0];
+      mergedConfig().onSave?.(...args);
+    },
+    // Forward the return value: it is the "handled" signal the core acts on.
+    onEnter: (...args: Parameters<NonNullable<UseBlokConfig['onEnter']>>): boolean | void =>
+      mergedConfig().onEnter?.(...args),
+    onSubmit: (...args: Parameters<NonNullable<UseBlokConfig['onSubmit']>>): void => {
+      mergedConfig().onSubmit?.(...args);
+    },
+    onBeforeRender: (
+      ...args: Parameters<NonNullable<UseBlokConfig['onBeforeRender']>>
+    ): ReturnType<NonNullable<UseBlokConfig['onBeforeRender']>> =>
+      mergedConfig().onBeforeRender?.(...args) ?? args[0],
+    onAfterRender: (...args: Parameters<NonNullable<UseBlokConfig['onAfterRender']>>): void => {
+      mergedConfig().onAfterRender?.(...args);
+    },
   };
 
   /**
@@ -137,6 +199,7 @@ export function useBlok(
     if (state.current !== null) {
       removeHolder(state.current);
       removeRegistry(state.current);
+      removeContentBaseline(state.current);
       try {
         state.current.destroy();
       } catch {
@@ -165,22 +228,37 @@ export function useBlok(
       snapshot.tools = injectPortalRegistry(snapshot.tools, registry);
     }
 
-    // Wrap onSave (when the consumer opted in): record the editor's own
-    // serialized output as the dedup baseline BEFORE notifying the consumer, so a
-    // controlled `update:data -> data` echo deep-equals it and never re-renders.
-    // Reads the latest callback through the config getter so it never goes stale.
-    if (typeof snapshot.onSave === 'function') {
-      snapshot.onSave = (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
-        state.lastRenderedData = args[0];
-        mergedConfig().onSave?.(...args);
-      };
-    }
+    // Install the stable wrappers for the callbacks the consumer actually
+    // passed, and clear the rest: an absent handler must stay absent, because
+    // core reads PRESENCE as intent. What was installed is recorded so the
+    // watcher below can push later flips instead of recreating the editor.
+    const presence = readHandlerPresence(mergedConfig());
+
+    snapshot.onChange = presence.onChange ? handlerWrappers.onChange : undefined;
+    snapshot.onSave = presence.onSave ? handlerWrappers.onSave : undefined;
+    snapshot.onEnter = presence.onEnter ? handlerWrappers.onEnter : undefined;
+    snapshot.onSubmit = presence.onSubmit ? handlerWrappers.onSubmit : undefined;
+    snapshot.onBeforeRender = presence.onBeforeRender ? handlerWrappers.onBeforeRender : undefined;
+    snapshot.onAfterRender = presence.onAfterRender ? handlerWrappers.onAfterRender : undefined;
+
+    state.appliedHandlerPresence = presence;
 
     const blok = new BlokRuntime({ ...snapshot, holder });
 
     state.current = blok;
     setHolder(blok, holder);
     setRegistry(blok, registry);
+    // The out-of-band content channel: `<BlokEditor>`'s exposed `render()`
+    // changes the document without going through the reactive `data` watcher,
+    // so it reports the result here. Without it the watcher's baseline names a
+    // document the editor no longer shows, and a controlled `data` set back to
+    // that document is deduped away — leaving the editor on the imperative
+    // content while the host's state says otherwise.
+    setContentBaseline(blok, {
+      markRendered: (content): void => {
+        state.lastRenderedData = content;
+      },
+    });
 
     void blok.isReady
       .then(() => {
@@ -351,6 +429,63 @@ export function useBlok(
     { immediate: true }
   );
 
+  // Live callback config. Callback presence was frozen at construction and IS
+  // the semantics in core (`onSubmit` makes Enter serialize-and-submit instead
+  // of splitting the block; `onSave` arms the change pipeline), so a `@save`
+  // listener or an "Enter sends" toggle added after mount used to need an
+  // editor recreate — losing caret and undo history. Diff presence against what
+  // is installed and push genuine flips through the runtime `handlers.set` API,
+  // writing `undefined` for a callback that disappeared so the change is
+  // reversible. Identity is never diffed: the wrappers forward to the latest
+  // config already.
+  watch(
+    [editor, () => JSON.stringify(readHandlerPresence(mergedConfig()))],
+    ([ed]) => {
+      if (!ed) {
+        return;
+      }
+
+      const latest = readHandlerPresence(mergedConfig());
+      const applied = state.appliedHandlerPresence;
+      const diff: LiveHandlers = {};
+      const changed: { value: boolean } = { value: false };
+
+      const sync = <K extends keyof LiveHandlers>(key: K, write: (value: LiveHandlers[K]) => void): void => {
+        if (latest[key] === applied[key]) {
+          return;
+        }
+
+        applied[key] = latest[key];
+        changed.value = true;
+        write(latest[key] ? handlerWrappers[key] : undefined);
+      };
+
+      sync('onChange', (value) => {
+        diff.onChange = value;
+      });
+      sync('onSave', (value) => {
+        diff.onSave = value;
+      });
+      sync('onEnter', (value) => {
+        diff.onEnter = value;
+      });
+      sync('onSubmit', (value) => {
+        diff.onSubmit = value;
+      });
+      sync('onBeforeRender', (value) => {
+        diff.onBeforeRender = value;
+      });
+      sync('onAfterRender', (value) => {
+        diff.onAfterRender = value;
+      });
+
+      if (changed.value) {
+        ed.handlers.set(diff);
+      }
+    },
+    { immediate: true }
+  );
+
   // Reactive content. `data` seeds the editor at construction; afterwards a new
   // *content* value re-renders via the public render() API — deep-equal-deduped
   // against the baseline (so an unchanged reference, including the editor's own
@@ -371,7 +506,15 @@ export function useBlok(
         return;
       }
 
-      if (deepEqual(data, state.lastRenderedData)) {
+      // Structural comparison (`equalsOutputData`, not a raw deep-equal): a host
+      // that persists the editor's own document and hands back a stripped copy —
+      // fresh `time`, dropped ids, no `lastEditedAt` stamp — is still echoing
+      // content the editor already shows, and re-rendering it would reset the
+      // caret for zero visual change. `undefined` means "nothing recorded yet",
+      // which is NOT an empty document, so it must never match.
+      const baseline = state.lastRenderedData;
+
+      if (baseline !== undefined && equalsOutputData(data, baseline)) {
         return;
       }
 

package/types/index.d.ts

@@ -4,6 +4,7 @@ import type {
   Blok,
   BlockAPI,
   BlockMutationEvent,
+  BlockOrigin,
   BlockToolConstructable,
   BlockToolData,
   BlokConfig,
@@ -40,6 +41,13 @@ import type { MarkdownImportConfig } from '@bloklabs/core/markdown';
  *   forwarded — it only affects the initial locale resolution.
  * - `data` — re-renders via `editor.render(value)` when content changes
  *   (deep-equal–deduped and serialized; seeds the initial content at creation)
+ * - `onChange`, `onSave`, `onEnter`, `onSubmit`, `onBeforeRender`,
+ *   `onAfterRender` — calls `editor.handlers.set({ ... })` when a callback
+ *   APPEARS or DISAPPEARS. Callback presence is load-bearing in core (an
+ *   `onSubmit` turns Enter into serialize-and-submit; an `onSave` arms the
+ *   change pipeline), so dropping the prop UNSETS the handler rather than
+ *   leaving a stale one behind. Callback IDENTITY is always live — the adapter
+ *   forwards to the latest render, so you never need to memoize them.
  *
  * All other config is consumed once at editor creation.
  */
@@ -117,7 +125,16 @@ export interface BlokEditorExposed {
   save(): Promise<OutputData> | undefined;
   /** Move the caret into the editor. */
   focus(atEnd?: boolean): void;
-  /** Replace the editor content (undefined until ready). */
+  /**
+   * Replace the editor content (undefined until ready).
+   *
+   * Safe to mix with a controlled `data` prop: the rendered document becomes
+   * the adapter's content baseline once the call lands, so a later `data`
+   * change back to the previous document still re-renders instead of being
+   * deduped against a baseline the editor no longer reflects. Recorded only on
+   * the resolved path — a failed render leaves the editor on its previous
+   * content.
+   */
   render(data: OutputData): Promise<void> | undefined;
 }
 
@@ -157,6 +174,21 @@ export declare function provideBlok(defaults: Partial<UseBlokConfig>): void;
  */
 export declare function useBlokDefaults(): Partial<UseBlokConfig>;
 
+/**
+ * Injection key carrying the LIVE editor instance down to everything
+ * `BlokContent` renders — including every `createVueBlock` block, because
+ * `<Teleport>` preserves the component render context.
+ */
+export declare const BLOK_EDITOR_INSTANCE: InjectionKey<Readonly<ShallowRef<Blok | null>>>;
+
+/**
+ * The live Blok instance a component is rendered inside, as a ref (null before
+ * it exists). Inside a `createVueBlock` block this is the block's OWN editor, so
+ * `useBlocks(useBlokInstance())` works with no host plumbing — and makes a
+ * container block reactive to its own child tree. Call it inside `setup`.
+ */
+export declare function useBlokInstance(): Readonly<ShallowRef<Blok | null>>;
+
 /**
  * A plain, serializable view of one block in the tree. Snapshot-volatile: every
  * read allocates a fresh node and `contentIds` is derived per read — depend on
@@ -502,6 +534,23 @@ export interface PropSchemaEntry {
  */
 export type PropSchema = Record<string, PropSchemaEntry>;
 
+/**
+ * One child's decoration: attribute name -> value. `null`/`undefined` removes
+ * the attribute; a boolean or number is stringified (so `false` writes
+ * `data-active="false"`, which CSS can select, rather than dropping the hook).
+ */
+export type ChildAttributes = Record<string, string | number | boolean | null | undefined>;
+
+/** The `BlockChildren` per-child decorator (see {@link VueBlockRenderProps.BlockChildren}). */
+export type ChildAttributesFn = (child: BlockAPI, index: number) => ChildAttributes;
+
+/**
+ * Every STATIC member of core's block-tool contract a Vue block may declare for
+ * itself. `toolbox` and `isReadOnlySupported` are excluded — the factory owns
+ * them.
+ */
+export type BlockToolStatics = Omit<BlockToolConstructable, 'toolbox' | 'isReadOnlySupported'>;
+
 /** Context handed to a Vue block's `setup` (the only data write path is `commit`). */
 export interface VueBlockRenderProps<Data> {
   /** Reactive, frozen snapshot of the block data. Read `data.value`; never mutate. */
@@ -510,6 +559,12 @@ export interface VueBlockRenderProps<Data> {
   commit: (patch: Partial<Data>) => void;
   /** This block's per-block API. */
   block: BlockAPI;
+  /**
+   * The EDITOR-level API this block belongs to (`api.blocks`, `api.caret`…) —
+   * the same object a vanilla tool receives. For a reactive view of the tree
+   * pair `useBlocks` with `useBlokInstance()` instead; the api is not reactive.
+   */
+  api: API;
   /**
    * Reactive read-only flag. Read `readOnly.value` in render to disable editing.
    * Toggled IN PLACE by core's read-only switch (no remount, ephemeral state
@@ -517,7 +572,13 @@ export interface VueBlockRenderProps<Data> {
    * editor is read-only.
    */
   readOnly: Readonly<ShallowRef<boolean>>;
-  /** Engine-owned child slot — render `h(BlockChildren)` for a container block. */
+  /**
+   * Engine-owned child slot — render `h(BlockChildren)` for a container block.
+   * Accepts one optional prop, `childAttributes: ChildAttributesFn`, applied to
+   * each child's HOLDER after mounting (named hooks instead of positional
+   * `:nth-child()` CSS). Holders stay DIRECT children of the slot; attributes
+   * the callback stops producing are removed on the next pass.
+   */
   BlockChildren: Component;
 }
 
@@ -527,11 +588,87 @@ export interface CreateVueBlockSpec<Data extends BlockToolData = BlockToolData>
   toolbox?: ToolboxConfig;
   propSchema: PropSchema;
   setup: (props: VueBlockRenderProps<Data>) => () => unknown;
+  /**
+   * Static members of core's tool contract, forwarded verbatim onto the
+   * generated tool class (`ownsChildren`, `keepsChildrenOnEnter`,
+   * `conversionConfig`, `pasteConfig`, `sanitize`, `shortcut`, `upgradeData`…).
+   *
+   * `keepsChildrenOnEnter` is the per-tool Enter policy: declare it and Enter on
+   * this container's empty LAST child creates the new line INSIDE it instead of
+   * escaping to the container's parent (Blok's default, which is Notion's
+   * callout behaviour). It is policy the DOM cannot express — a callout renders
+   * the same nested-blocks slot as a column yet wants the escape — so a layout
+   * container (a card, a `steps` block) had to hijack the editor-global
+   * `config.onEnter` before it existed.
+   */
+  statics?: BlockToolStatics;
+  /**
+   * The element the +/drag toolbar should vertically center on — core's
+   * `getToolbarAnchorElement` hook, resolved against the block's host on every
+   * call. Return `null`/`undefined` to keep core's default positioning.
+   */
+  getToolbarAnchorElement?: (host: HTMLElement, block: BlockAPI) => HTMLElement | null | undefined;
   onRendered?: (block: BlockAPI) => void;
+  /**
+   * Fired ONCE per block instance, after the teleport's FIRST commit — the
+   * first moment this block's rendered DOM exists (and, for a container, the
+   * moment `BlockChildren` has adopted the child holders). `onRendered` cannot
+   * mean that: core calls `rendered()` in the same tick as `render()`, before
+   * Vue has drawn anything.
+   *
+   * It is also the create-vs-restore signal: `context.origin` says whether the
+   * author just made this block (`user`/`api`/`convert`) or the document is
+   * being re-materialised (`load`/`replay`/`paste`), so a container can seed its
+   * default children here exactly once.
+   *
+   * To observe OTHER blocks settling — e.g. before placing the caret in a child
+   * you just inserted — listen for the `block:childrenMounted` editor event
+   * instead: `api.events.on('block:childrenMounted', ({ blockId, childIds }) => …)`.
+   */
+  onMounted?: (block: BlockAPI, context: VueBlockMountedContext) => void;
+  /**
+   * The SEEDING hook: `onMounted`, narrowed to a genuine creation. Fired ONCE
+   * per block instance, after the teleport's first commit, and only when the
+   * author just made this block (`origin` of `user`, `api` or `convert`) —
+   * never for a `load`/`replay`/`paste` restore, and never for the off-tree
+   * `probe` instance core builds to read a tool's default data.
+   *
+   * Prefer it over hand-testing `context.origin` in `onMounted`: the intuitive
+   * `origin === 'user'` check is wrong — it drops `api.blocks.insert(...)` and
+   * turn-into, so the container comes up empty for every path except a
+   * keystroke.
+   * @example
+   * ```ts
+   * onCreated: (block, { api }) => {
+   *   if (block.getChildren().length === 0) {
+   *     api.blocks.insertInsideParent(block.id);
+   *   }
+   * }
+   * ```
+   */
+  onCreated?: (block: BlockAPI, context: VueBlockMountedContext) => void;
   onMoved?: (block: BlockAPI) => void;
   onRemoved?: (block: BlockAPI) => void;
 }
 
+/**
+ * Second argument of {@link CreateVueBlockSpec.onMounted} and
+ * {@link CreateVueBlockSpec.onCreated}.
+ */
+export interface VueBlockMountedContext {
+  /**
+   * Why this block instance was constructed. CREATION origins (`user`, `api`,
+   * `convert`) mean the author just made it, so seeding default children is
+   * correct; RESTORE origins (`load`, `replay`, `paste`) mean the document
+   * already says what the children are. `probe` is an off-tree instance built
+   * only to read a tool's default data and must not touch the block tree.
+   * Defaults to `'api'`.
+   */
+  origin: BlockOrigin;
+  /** The editor-level API (`api.blocks`, `api.caret`, `api.events`…). */
+  api: API;
+}
+
 /**
  * Author a first-party Vue block: returns a `BlockToolConstructable` registered
  * exactly like a vanilla tool (`tools: { type: { class: createVueBlock(...) } }`).