@bloklabs/vue 1.1.1

package/src/BlockPortalHost.ts

@@ -0,0 +1,46 @@
+// src/vue/BlockPortalHost.ts
+import { defineComponent, h, Teleport, Fragment, onErrorCaptured, type PropType } from 'vue';
+
+import type { BlockPortalRegistry } from './block-portal-registry';
+
+/**
+ * Wraps a single block's render so a throw inside it can't tear down the whole
+ * editor's render tree. `onErrorCaptured` returning false stops propagation.
+ * Authored as a render function (no `.vue` SFC) per the adapter invariant.
+ */
+const BlockErrorBoundary = defineComponent({
+  name: 'BlockErrorBoundary',
+  setup(_props, { slots }) {
+    onErrorCaptured(() => false);
+
+    return () => slots.default?.();
+  },
+});
+
+/**
+ * The single shared render tree that teleports each registered Vue block into
+ * its Blok-owned host element. Mounted once per editor (by `BlokContent`), it
+ * iterates the reactive registry and emits one `<Teleport>` per entry — so all
+ * blocks share one reconciler and the surrounding app's provide/inject context
+ * (Teleport preserves the component render context, not the DOM target's).
+ */
+export const BlockPortalHost = defineComponent({
+  name: 'BlockPortalHost',
+  props: {
+    registry: { type: Object as PropType<BlockPortalRegistry>, required: true },
+  },
+  setup(props) {
+    return () =>
+      h(
+        Fragment,
+        // Iterating the reactive Map tracks it, so register/unregister re-renders.
+        Array.from(props.registry.entries.entries()).map(([id, entry]) =>
+          h(Teleport, { key: id, to: entry.hostEl }, [
+            h(BlockErrorBoundary, null, {
+              default: () => h(entry.component, entry.props),
+            }),
+          ])
+        )
+      );
+  },
+});

package/src/BlokContent.ts

@@ -0,0 +1,80 @@
+import { defineComponent, h, onMounted, onBeforeUnmount, ref, toRaw, watch, type PropType } from 'vue';
+import { getHolder } from './holder-map';
+import { getRegistry } from './registry-map';
+import { BlockPortalHost } from './BlockPortalHost';
+import type { Blok } from '@/types';
+
+/**
+ * Provides the DOM mount point for a Blok editor. Renders a `<div>` and adopts
+ * the editor's detached holder element into it (the Vue analog of React's
+ * `BlokContent`). When `editor` is null it renders an empty div for layout
+ * stability. The holder subtree is owned entirely by core — Vue's renderer never
+ * manages its children, so the container is always rendered with no vnode
+ * children and the holder is appended/removed imperatively.
+ *
+ * `toRaw` unwraps the editor before the holder-map lookup: Vue stores the object
+ * prop behind a reactive proxy, and the holder WeakMap is keyed by the raw Blok
+ * instance (Risk R0 — Vue proxies must never be used as identity keys).
+ */
+export const BlokContent = defineComponent({
+  name: 'BlokContent',
+  props: {
+    editor: {
+      type: Object as PropType<Blok | null>,
+      default: null,
+    },
+  },
+  setup(props) {
+    const container = ref<HTMLDivElement | null>(null);
+
+    const adopt = (editor: Blok | null): void => {
+      if (container.value === null || editor === null) {
+        return;
+      }
+
+      const holder = getHolder(toRaw(editor));
+
+      if (holder === undefined) {
+        return;
+      }
+
+      container.value.appendChild(holder);
+    };
+
+    const detach = (editor: Blok | null): void => {
+      if (editor === null) {
+        return;
+      }
+
+      getHolder(toRaw(editor))?.remove();
+    };
+
+    onMounted(() => {
+      adopt(props.editor);
+    });
+
+    watch(
+      () => props.editor,
+      (next, previous) => {
+        detach(previous ?? null);
+        adopt(next);
+      }
+    );
+
+    onBeforeUnmount(() => {
+      detach(props.editor);
+    });
+
+    return () => {
+      const editorVal = props.editor;
+      // The shared portal host for `createVueBlock` tools (when this editor has
+      // one). It emits ONLY <Teleport> anchors — no real DOM in the container —
+      // so the imperatively-appended holder is undisturbed and the container
+      // stays a single root for attribute fallthrough. Registry-less editors
+      // (vanilla-only) render the bare div exactly as before.
+      const registry = editorVal === null ? undefined : getRegistry(toRaw(editorVal));
+
+      return h('div', { ref: container }, registry === undefined ? [] : [h(BlockPortalHost, { registry })]);
+    };
+  },
+});

package/src/BlokEditor.ts

@@ -0,0 +1,197 @@
+import { computed, defineComponent, getCurrentInstance, h, watch, type PropType } from 'vue';
+import { useBlok } from './useBlok';
+import { BlokContent } from './BlokContent';
+import { BLOK_EDITOR_CONFIG_KEYS } from './config-keys';
+import type {
+  API,
+  BlockMutationEvent,
+  BlokConfig,
+  EditorWidth,
+  OutputData,
+  ResolvedTheme,
+  ThemeMode,
+} from '@/types';
+import type { UseBlokConfig } from './types';
+
+/**
+ * The blessed all-in-one component for embedding Blok in Vue. Wires `useBlok`
+ * and `BlokContent`, maps Vue emits onto the core config callbacks (gated on
+ * listener presence, since their mere presence makes core do extra work), and
+ * threads the return-valued transform hooks through.
+ *
+ * Every declared prop is removed from `$attrs`, so any extra attribute
+ * (`id`/`class`/`aria-*`/`data-*`) falls through to the editor container.
+ */
+export const BlokEditor = defineComponent({
+  name: 'BlokEditor',
+  // Bind fallthrough attrs explicitly onto the container (below) instead of
+  // relying on implicit double-fallthrough through BlokContent.
+  inheritAttrs: false,
+  // Reactive config + seed props. `default: undefined` on the boolean props keeps
+  // an unset prop `undefined` (Vue otherwise coerces absent Boolean props to
+  // false), so `provideBlok` defaults can apply and core can coerce.
+  props: {
+    autofocus: { type: Boolean as PropType<boolean | undefined>, default: undefined },
+    defaultBlock: { type: String, default: undefined },
+    dataModel: { type: String as PropType<BlokConfig['dataModel']>, default: undefined },
+    placeholder: { type: [String, Boolean] as PropType<string | false>, default: undefined },
+    sanitizer: { type: Object as PropType<BlokConfig['sanitizer']>, default: undefined },
+    hideToolbar: { type: Boolean as PropType<boolean | undefined>, default: undefined },
+    maxHistoryLength: { type: Number, default: undefined },
+    historyDebounceTime: { type: Number, default: undefined },
+    newGroupDelay: { type: Number, default: undefined },
+    globalUndoRedo: { type: Boolean as PropType<boolean | undefined>, default: undefined },
+    tools: { type: Object as PropType<BlokConfig['tools']>, default: undefined },
+    data: { type: Object as PropType<OutputData>, default: undefined },
+    minHeight: { type: Number, default: undefined },
+    logLevel: { type: String as PropType<BlokConfig['logLevel']>, default: undefined },
+    readOnly: { type: Boolean as PropType<boolean | undefined>, default: undefined },
+    i18n: { type: Object as PropType<BlokConfig['i18n']>, default: undefined },
+    link: { type: Object as PropType<BlokConfig['link']>, default: undefined },
+    linkPaste: { type: Object as PropType<BlokConfig['linkPaste']>, default: undefined },
+    inlineToolbar: { type: [Array, Boolean] as PropType<string[] | boolean>, default: undefined },
+    tunes: { type: Array as PropType<string[]>, default: undefined },
+    style: { type: Object as PropType<BlokConfig['style']>, default: undefined },
+    theme: { type: String as PropType<ThemeMode>, default: undefined },
+    scrollToBlock: { type: Object as PropType<BlokConfig['scrollToBlock']>, default: undefined },
+    user: { type: Object as PropType<BlokConfig['user']>, default: undefined },
+    resolveUser: { type: Function as PropType<BlokConfig['resolveUser']>, default: undefined },
+    notifierPosition: { type: String as PropType<BlokConfig['notifierPosition']>, default: undefined },
+    notifier: { type: Function as PropType<BlokConfig['notifier']>, default: undefined },
+    width: { type: String as PropType<EditorWidth>, default: undefined },
+    onBeforeRender: { type: Function as PropType<BlokConfig['onBeforeRender']>, default: undefined },
+    onBeforePaste: { type: Function as PropType<BlokConfig['onBeforePaste']>, default: undefined },
+    /** Changing this prop's identity destroys and recreates the editor. */
+    recreateKey: { type: null as unknown as PropType<unknown> },
+  },
+  emits: {
+    ready: (_instance: unknown): boolean => true,
+    change: (_payload: { api: API; event: BlockMutationEvent | BlockMutationEvent[] }): boolean => true,
+    save: (_data: OutputData): boolean => true,
+    'update:data': (_data: OutputData): boolean => true,
+    'after-render': (_api: API): boolean => true,
+    'theme-change': (_theme: ResolvedTheme): boolean => true,
+    'blocks-rendered': (_payload: unknown): boolean => true,
+    'block-rendered': (_payload: unknown): boolean => true,
+  },
+  setup(props, { emit, expose, attrs }) {
+    const instance = getCurrentInstance();
+
+    /** Listener presence (the Vue analog of Angular's `output.observed`). */
+    const hasListener = (handlerKey: string): boolean => {
+      const vnodeProps = instance?.vnode.props;
+
+      return vnodeProps != null && handlerKey in vnodeProps;
+    };
+
+    /**
+     * Snapshot the props + gated emit-callbacks into a `UseBlokConfig`. App-wide
+     * `provideBlok` defaults are merged in by `useBlok` (the lifecycle engine),
+     * so this component stays thin and the escape-hatch path honors defaults too
+     * — mirroring React, where only `useBlok` merges.
+     */
+    const buildConfig = (): UseBlokConfig => {
+      const config: Record<string, unknown> = {};
+
+      for (const key of BLOK_EDITOR_CONFIG_KEYS) {
+        const value = props[key];
+
+        if (value !== undefined) {
+          config[key] = value;
+        }
+      }
+
+      if (hasListener('onChange')) {
+        config.onChange = (api: API, event: BlockMutationEvent | BlockMutationEvent[]): void => {
+          emit('change', { api, event });
+        };
+      }
+
+      // onSave makes core serialize on every change batch — wire it only when a
+      // v-model:data binding or an explicit @save listener consumes it.
+      if (hasListener('onSave') || hasListener('onUpdate:data')) {
+        config.onSave = (data: OutputData): void => {
+          emit('update:data', data);
+          emit('save', data);
+        };
+      }
+
+      if (hasListener('onAfterRender')) {
+        config.onAfterRender = (api: API): void => {
+          emit('after-render', api);
+        };
+      }
+
+      if (hasListener('onThemeChange')) {
+        config.onThemeChange = (resolved: ResolvedTheme): void => {
+          emit('theme-change', resolved);
+        };
+      }
+
+      return config as UseBlokConfig;
+    };
+
+    const editor = useBlok(
+      () => buildConfig(),
+      () => props.recreateKey
+    );
+
+    // 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) => {
+      if (ed === null) {
+        return;
+      }
+
+      const subscriptions: Array<[string, (payload?: unknown) => void]> = [];
+
+      if (hasListener('onBlocksRendered')) {
+        const handler = (payload?: unknown): void => emit('blocks-rendered', payload);
+
+        ed.on('blocks:rendered', handler);
+        subscriptions.push(['blocks:rendered', handler]);
+      }
+
+      if (hasListener('onBlockRendered')) {
+        const handler = (payload?: unknown): void => emit('block-rendered', payload);
+
+        ed.on('block:rendered', handler);
+        subscriptions.push(['block:rendered', handler]);
+      }
+
+      onCleanup(() => {
+        for (const [name, handler] of subscriptions) {
+          ed.off(name, handler);
+        }
+      });
+    });
+
+    // Emit `ready` once per editor, after the instance is published to the ref
+    // (and to `expose` below), so a consumer reading the instance inside the
+    // handler — or via a template ref — sees the live editor. The last-emitted
+    // instance is held in an object to avoid `let` reassignment.
+    const readyState: { last: typeof editor.value } = { last: null };
+
+    watch(editor, (ed) => {
+      if (ed !== null && ed !== readyState.last) {
+        readyState.last = ed;
+        emit('ready', ed);
+      }
+    });
+
+    // Curated imperative facade (delegates to the live instance; no-ops until
+    // ready). `instance` is live (null before ready, the Blok after).
+    expose({
+      instance: computed(() => editor.value),
+      save: (): ReturnType<NonNullable<typeof editor.value>['save']> | undefined => editor.value?.save(),
+      focus: (atEnd?: boolean): void => {
+        editor.value?.focus(atEnd);
+      },
+      render: (data: OutputData): ReturnType<NonNullable<typeof editor.value>['render']> | undefined =>
+        editor.value?.render(data),
+    });
+
+    return () => h(BlokContent, { editor: editor.value, ...attrs });
+  },
+});

package/src/block-portal-registry.ts

@@ -0,0 +1,79 @@
+// src/vue/block-portal-registry.ts
+import { markRaw, reactive, type Component } from 'vue';
+
+/**
+ * Tool-config key carrying the editor's portal registry into a `createVueBlock`
+ * tool. The tool is constructed by CORE (outside any Vue `setup`), so it cannot
+ * `inject()` — `useBlok` injects the editor-scoped registry through each
+ * vue-block tool's `config`, and the tool reads it here.
+ */
+export const BLOK_PORTAL_REGISTRY_CONFIG_KEY = '__blokPortalRegistry';
+
+/**
+ * One mounted Vue block in the portal registry. `hostEl` is the Blok-owned
+ * `toolRenderedElement` (tagged `data-blok-mutation-free`) the component is
+ * teleported into; `props` is a REACTIVE object so `setProps` updates the
+ * rendered block in place (no remount).
+ */
+export interface BlockPortalEntry {
+  hostEl: HTMLElement;
+  component: Component;
+  props: Record<string, unknown>;
+}
+
+/**
+ * Per-editor registry of Vue blocks. A single shared {@link BlockPortalHost}
+ * renders one `<Teleport>` per entry, so every block lives in ONE render tree
+ * (shared provide/inject + app plugins, one effect scope) — the TipTap
+ * `VueNodeViewRenderer` pattern, not a Vue app per block.
+ */
+export interface BlockPortalRegistry {
+  /** Reactive set of entries the host iterates (keyed by block id). */
+  readonly entries: ReadonlyMap<string, BlockPortalEntry>;
+  /**
+   * Register (or replace) the entry for `id`. Idempotent: a second register
+   * 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;
+  /** Merge `props` into the live entry's reactive props (in-place update). */
+  setProps(id: string, props: Record<string, unknown>): void;
+}
+
+/**
+ * Create a fresh portal registry. One per editor instance (associated via the
+ * registry map, mirroring the holder WeakMap), so multiple editors on a page
+ * never cross-render each other's blocks.
+ */
+export const createBlockPortalRegistry = (): BlockPortalRegistry => {
+  // Vue's reactive Map tracks iteration (entries/size), so the host re-renders
+  // on register/unregister.
+  const entries = reactive(new Map<string, BlockPortalEntry>());
+
+  return {
+    entries: entries as ReadonlyMap<string, BlockPortalEntry>,
+    register(id: string, entry: BlockPortalEntry): void {
+      // markRaw so the reactive Map (which must still track add/delete) does NOT
+      // deep-proxy the entry — a proxied component DEFINITION or DOM host would
+      // break rendering ("received a Component made reactive"). Per-entry prop
+      // reactivity, when needed, lives on the `props` object itself.
+      // set() replaces an existing entry — idempotent, never duplicates.
+      entries.set(id, markRaw(entry));
+    },
+    unregister(id: string): void {
+      entries.delete(id);
+    },
+    setProps(id: string, props: Record<string, unknown>): void {
+      const entry = entries.get(id);
+
+      if (entry === undefined) {
+        return;
+      }
+
+      // Mutate the reactive props object in place so the mounted component
+      // re-renders without being remounted (preserving its internal state).
+      Object.assign(entry.props, props);
+    },
+  };
+};

package/src/blocks-snapshot.ts

@@ -0,0 +1,17 @@
+// src/vue/blocks-snapshot.ts
+//
+// The block-tree data types, pure flat-index resolvers, AND the `UseBlocksApi`
+// connection contract are framework-agnostic and live in the shared core module
+// (`components/utils/blocks-tree`). The Vue `useBlocks` is a thin reactivity
+// wrapper over the shared `createBlocksApiForEditor`, so it exposes the IDENTICAL
+// surface as the React adapter — this file re-exports those shapes (no Vue-local
+// redefinition, so the two adapters cannot drift).
+export type {
+  BlockNode,
+  CaretTarget,
+  InsertPosition,
+  InsertSpec,
+  TreeInsertSpec,
+  MoveTarget,
+  UseBlocksApi,
+} from '@bloklabs/core/adapters';

package/src/config-keys.ts

@@ -0,0 +1,66 @@
+/**
+ * Prop keys that `<BlokEditor>` copies straight into the Blok config (the plain
+ * seed/reactive options plus the two return-valued transform hooks). The
+ * emit-mapped callbacks — `onReady`/`onChange`/`onSave`/`onAfterRender` — are NOT
+ * here: they are derived from Vue emits, gated on listener presence.
+ *
+ * Any prop on `<BlokEditor>` whose key is NOT a declared prop falls through to
+ * the container div via `$attrs` (Vue removes declared props from `$attrs`
+ * automatically — the analog of React's manual config/div partition).
+ *
+ * The compile-time guard in this file (step 14) keeps this list in sync with the
+ * adapter's public config surface.
+ */
+import type { UseBlokConfig } from './types';
+
+export const BLOK_EDITOR_CONFIG_KEYS = [
+  'autofocus',
+  'defaultBlock',
+  'dataModel',
+  'placeholder',
+  'sanitizer',
+  'hideToolbar',
+  'maxHistoryLength',
+  'historyDebounceTime',
+  'newGroupDelay',
+  'globalUndoRedo',
+  'tools',
+  'data',
+  'minHeight',
+  'logLevel',
+  'readOnly',
+  'i18n',
+  'link',
+  'linkPaste',
+  'inlineToolbar',
+  'tunes',
+  'style',
+  'theme',
+  'scrollToBlock',
+  'user',
+  'resolveUser',
+  'notifierPosition',
+  'notifier',
+  'width',
+  'onBeforeRender',
+  'onBeforePaste',
+] as const satisfies readonly (keyof UseBlokConfig)[];
+
+export type BlokEditorConfigKey = (typeof BLOK_EDITOR_CONFIG_KEYS)[number];
+
+/**
+ * Config callbacks that `<BlokEditor>` surfaces as Vue emits (gated on listener
+ * presence) instead of declared props.
+ */
+export type EmitMappedConfigKey = 'onReady' | 'onChange' | 'onSave' | 'onAfterRender' | 'onThemeChange';
+
+/**
+ * Compile-time exhaustiveness guard: every `UseBlokConfig` key must be either a
+ * declared `<BlokEditor>` prop (`BLOK_EDITOR_CONFIG_KEYS`) or emit-mapped. If a
+ * new `BlokConfig` key is added and not handled here, `_uncovered` reds under
+ * `tsc`, forcing the adapter (and `types/vue.d.ts`) to keep pace.
+ */
+type _UncoveredConfigKey = Exclude<keyof UseBlokConfig, BlokEditorConfigKey | EmitMappedConfigKey>;
+const _uncovered: _UncoveredConfigKey extends never ? true : never = true;
+
+void _uncovered;