@bloklabs/vue 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/vue",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Vue block editor — official Vue 3 bindings for Blok, the headless Notion-like rich text editor. Composables and components that render blocks and save to JSON.",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -54,7 +54,7 @@
     "build": "yarn run -T vite build --mode production"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.7.0",
+    "@bloklabs/core": "^1.8.0",
     "vue": "^3.5.0"
   }
 }

package/src/BlokContent.ts

@@ -1,7 +1,19 @@
-import { defineComponent, h, onMounted, onBeforeUnmount, ref, toRaw, watch, type PropType } from 'vue';
+import {
+  computed,
+  defineComponent,
+  h,
+  onMounted,
+  onBeforeUnmount,
+  provide,
+  ref,
+  toRaw,
+  watch,
+  type PropType,
+} from 'vue';
 import { getHolder } from './holder-map';
 import { getRegistry } from './registry-map';
 import { BlockPortalHost } from './BlockPortalHost';
+import { BLOK_EDITOR_INSTANCE } from './blok-instance';
 import type { Blok } from '@/types';
 
 /**
@@ -27,6 +39,17 @@ export const BlokContent = defineComponent({
   setup(props) {
     const container = ref<HTMLDivElement | null>(null);
 
+    // Publish the live instance to everything rendered beneath — including every
+    // `createVueBlock` block, because <Teleport> preserves the COMPONENT render
+    // context. That is what lets a block call `useBlocks(useBlokInstance())`
+    // without the host prop-drilling the instance into it. `toRaw` for the same
+    // reason the holder lookup uses it (Risk R0): the prop may arrive behind a
+    // reactive proxy, and consumers compare the instance BY IDENTITY.
+    provide(
+      BLOK_EDITOR_INSTANCE,
+      computed(() => (props.editor === null ? null : toRaw(props.editor)))
+    );
+
     const adopt = (editor: Blok | null): void => {
       if (container.value === null || editor === null) {
         return;

package/src/BlokEditor.ts

@@ -1,6 +1,7 @@
-import { computed, defineComponent, getCurrentInstance, h, watch, type PropType } from 'vue';
+import { computed, defineComponent, getCurrentInstance, h, onUpdated, ref, watch, type PropType } from 'vue';
 import { useBlok } from './useBlok';
 import { BlokContent } from './BlokContent';
+import { getContentBaseline } from './content-baseline-map';
 import { BLOK_EDITOR_CONFIG_KEYS } from './config-keys';
 import type {
   API,
@@ -75,6 +76,8 @@ export const BlokEditor = defineComponent({
     migrations: { type: Object as PropType<BlokConfig['migrations']>, default: undefined },
     /** Editor-level uploader, routed by asset kind (images, video, audio, files). */
     uploader: { type: Object as PropType<BlokConfig['uploader']>, default: undefined },
+    /** Opt-in: clicks on the host page below the editor append a block. */
+    captureClicksBelowEditor: { type: Boolean as PropType<boolean | undefined>, default: undefined },
     /** Changing this prop's identity destroys and recreates the editor. */
     recreateKey: { type: null as unknown as PropType<unknown> },
   },
@@ -91,13 +94,56 @@ export const BlokEditor = defineComponent({
   setup(props, { emit, expose, attrs }) {
     const instance = getCurrentInstance();
 
-    /** Listener presence (the Vue analog of Angular's `output.observed`). */
-    const hasListener = (handlerKey: string): boolean => {
+    /**
+     * The `onXxx` keys currently on the component's vnode, as a sorted, stable
+     * string. Emit-mapped listeners (`@change`, `@save`, `v-model:data`,
+     * `@after-render`, …) are not declared props, so `vnode.props` is the only
+     * place they exist.
+     */
+    const readListenerKeys = (): string => {
       const vnodeProps = instance?.vnode.props;
 
-      return vnodeProps != null && handlerKey in vnodeProps;
+      if (vnodeProps == null) {
+        return '';
+      }
+
+      return Object.keys(vnodeProps)
+        .filter((key) => key.startsWith('on'))
+        .sort()
+        .join('|');
     };
 
+    /**
+     * Reactive mirror of `readListenerKeys()`. `vnode.props` is a plain object
+     * Vue swaps out on each patch — reading it tracks nothing, so a host that
+     * added or removed a listener WITHOUT also changing a reactive prop never
+     * re-ran the config snapshot and the flip was silently lost (core reads
+     * callback PRESENCE as intent: `onSave` arms the change pipeline).
+     *
+     * This ref is the missing reactive source. It is READ by `hasListener` (so
+     * every watcher that snapshots the config depends on it) and WRITTEN only
+     * from `onUpdated` — never from the snapshot itself, which would make the
+     * read its own write and self-trigger an endless update loop. Storing the
+     * key set rather than a counter makes "bump only on a genuine presence
+     * change" structural: re-assigning an equal string is inert.
+     *
+     * One case stays out of reach, and it is Vue's, not the ref's:
+     * `hasPropsChanged` skips keys that name a declared emit, so REPLACING one
+     * emit listener with a different one while the vnode's prop count and every
+     * other prop stay identical (`@change` out, `@save` in, nothing else moving)
+     * skips the child update entirely — no hook fires anywhere. Anything that
+     * also changes the prop count, including plain add/remove, updates.
+     */
+    const listenerKeys = ref(readListenerKeys());
+
+    onUpdated(() => {
+      listenerKeys.value = readListenerKeys();
+    });
+
+    /** Listener presence (the Vue analog of Angular's `output.observed`). */
+    const hasListener = (handlerKey: string): boolean =>
+      listenerKeys.value.split('|').includes(handlerKey);
+
     /**
      * Snapshot the props + gated emit-callbacks into a `UseBlokConfig`. App-wide
      * `provideBlok` defaults are merged in by `useBlok` (the lifecycle engine),
@@ -152,8 +198,11 @@ export const BlokEditor = defineComponent({
 
     // Subscribe to the editor's rendered-lifecycle events once it exists (gated
     // on the emits being listened). `onCleanup` unsubscribes when the instance is
-    // replaced or the component unmounts.
-    watch(editor, (ed, _previous, onCleanup) => {
+    // replaced or the component unmounts. `listenerKeys` is a source too, so a
+    // listener added after mount subscribes instead of waiting for a recreate —
+    // presence is re-read from scratch each run, and the cleanup keeps the
+    // subscriptions balanced.
+    watch([editor, listenerKeys], ([ed], _previous, onCleanup) => {
       if (ed === null) {
         return;
       }
@@ -202,8 +251,29 @@ export const BlokEditor = defineComponent({
       focus: (atEnd?: boolean): void => {
         editor.value?.focus(atEnd);
       },
-      render: (data: OutputData): ReturnType<NonNullable<typeof editor.value>['render']> | undefined =>
-        editor.value?.render(data),
+      /**
+       * Replace the editor content.
+       *
+       * 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, and a baseline naming content it never showed
+       * would dedupe away the correcting update.
+       * @param data - the document to render
+       */
+      render: (data: OutputData): Promise<void> | undefined => {
+        const ed = editor.value;
+
+        if (ed === null) {
+          return undefined;
+        }
+
+        return ed.render(data).then(() => {
+          getContentBaseline(ed)?.markRendered(data);
+        });
+      },
     });
 
     return () => h(BlokContent, { editor: editor.value, ...attrs });

package/src/block-portal-registry.ts

@@ -35,8 +35,17 @@ export interface BlockPortalRegistry {
    * for the same id replaces the entry rather than mounting a duplicate.
    */
   register(id: string, entry: BlockPortalEntry): void;
-  /** Remove the entry for `id`. Safe (no-op) when absent. */
-  unregister(id: string): void;
+  /**
+   * Remove the entry for `id`. Safe (no-op) when absent.
+   *
+   * Pass the caller's own `hostEl` to make the removal OWNERSHIP-CHECKED: the
+   * entry is deleted only when it is still the one that host registered. Core
+   * composes a replacement block (which registers under the SAME id) BEFORE it
+   * destroys the block it replaces, so a superseded tool's `removed()`/
+   * `destroy()` teardown arrives after the live entry is already in place —
+   * without the check it deletes that live entry and the holder stays empty.
+   */
+  unregister(id: string, hostEl?: HTMLElement): void;
   /** Merge `props` into the live entry's reactive props (in-place update). */
   setProps(id: string, props: Record<string, unknown>): void;
 }
@@ -61,7 +70,12 @@ export const createBlockPortalRegistry = (): BlockPortalRegistry => {
       // set() replaces an existing entry — idempotent, never duplicates.
       entries.set(id, markRaw(entry));
     },
-    unregister(id: string): void {
+    unregister(id: string, hostEl?: HTMLElement): void {
+      // A superseded owner may not evict the entry that replaced it.
+      if (hostEl !== undefined && entries.get(id)?.hostEl !== hostEl) {
+        return;
+      }
+
       entries.delete(id);
     },
     setProps(id: string, props: Record<string, unknown>): void {

package/src/blok-instance.ts

@@ -0,0 +1,40 @@
+import { inject, shallowRef, type InjectionKey, type ShallowRef } from 'vue';
+import type { Blok } from '@/types';
+
+/**
+ * Injection key carrying the LIVE editor instance down to everything
+ * `BlokContent` renders — which, because `<Teleport>` preserves the COMPONENT
+ * render context (not the DOM target's), includes every `createVueBlock` block
+ * mounted through the editor's shared `BlockPortalHost`.
+ *
+ * The provided ref is null until the instance exists, matching `useBlok`'s own
+ * pre-ready contract.
+ */
+export const BLOK_EDITOR_INSTANCE: InjectionKey<Readonly<ShallowRef<Blok | null>>> =
+  Symbol('BLOK_EDITOR_INSTANCE');
+
+/** Stable "no editor here" ref for components rendered outside a BlokContent. */
+const NO_EDITOR: Readonly<ShallowRef<Blok | null>> = shallowRef(null);
+
+/**
+ * The live Blok instance a component is rendered inside, as a ref, or a ref of
+ * null before it exists. Inside a `createVueBlock` block this is the block's OWN
+ * editor — so a block can drive the tree it lives in without the host
+ * prop-drilling the instance into it:
+ *
+ * ```ts
+ * const blocks = useBlocks(useBlokInstance());
+ * const children = computed(() => blocks.getChildren(ctx.block.id));
+ * ```
+ *
+ * That pairing is also what makes a container block REACTIVE to its own child
+ * tree: `useBlocks` refreshes on the editor's `block changed` event, which core
+ * emits for every structural mutation — including children the adapter itself
+ * never sees (a pasted paragraph, a Tab-indent from the keyboard).
+ *
+ * Call it inside `setup`. Outside a `BlokContent`/`BlokEditor` subtree it
+ * returns a ref of null.
+ */
+export function useBlokInstance(): Readonly<ShallowRef<Blok | null>> {
+  return inject(BLOK_EDITOR_INSTANCE, NO_EDITOR);
+}

package/src/config-keys.ts

@@ -49,6 +49,7 @@ export const BLOK_EDITOR_CONFIG_KEYS = [
   'onError',
   'migrations',
   'uploader',
+  'captureClicksBelowEditor',
 ] as const satisfies readonly (keyof UseBlokConfig)[];
 
 export type BlokEditorConfigKey = (typeof BLOK_EDITOR_CONFIG_KEYS)[number];

package/src/content-baseline-map.ts

@@ -0,0 +1,38 @@
+import type { LooseOutputData, OutputData } from '@/types';
+
+/**
+ * The controlled-content bookkeeping `useBlok` keeps for one editor: the
+ * baseline it believes the editor currently reflects.
+ *
+ * The reactive `data` watcher dedupes against that baseline, which is only sound
+ * while the watcher is the ONLY thing changing the content. `<BlokEditor>`'s
+ * exposed `render()` moves the editor out from under it: without this channel
+ * the baseline still names the document shown BEFORE the imperative call, so
+ * setting `data` back to that document is dismissed as an unchanged value and
+ * the editor keeps showing whatever `render()` installed.
+ *
+ * Registered per instance (mirrors the holder / portal-registry WeakMaps) so the
+ * exposed facade can reach it from the editor alone — `useBlok` returns only the
+ * instance ref, never its internal state.
+ */
+export interface ContentBaseline {
+  /**
+   * Record `content` as the document the editor now reflects.
+   * @param content - the document the editor now reflects
+   */
+  markRendered(content: OutputData | LooseOutputData | null): void;
+}
+
+const baselines = new WeakMap<WeakKey, ContentBaseline>();
+
+export function setContentBaseline(editor: WeakKey, baseline: ContentBaseline): void {
+  baselines.set(editor, baseline);
+}
+
+export function getContentBaseline(editor: WeakKey): ContentBaseline | undefined {
+  return baselines.get(editor);
+}
+
+export function removeContentBaseline(editor: WeakKey): void {
+  baselines.delete(editor);
+}