@tiptap/vue-2 3.29.2 → 3.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiptap/vue-2",
-  "version": "3.29.2",
+  "version": "3.30.1",
   "description": "Vue components for tiptap",
   "keywords": [
     "tiptap",
@@ -52,17 +52,17 @@
   },
   "devDependencies": {
     "vue": "^2.7.16",
-    "@tiptap/core": "^3.29.2",
-    "@tiptap/pm": "^3.29.2"
+    "@tiptap/core": "^3.30.1",
+    "@tiptap/pm": "^3.30.1"
   },
   "peerDependencies": {
     "vue": "^2.6.0",
-    "@tiptap/core": "3.29.2",
-    "@tiptap/pm": "3.29.2"
+    "@tiptap/core": "3.30.1",
+    "@tiptap/pm": "3.30.1"
   },
   "optionalDependencies": {
-    "@tiptap/extension-bubble-menu": "^3.29.2",
-    "@tiptap/extension-floating-menu": "^3.29.2"
+    "@tiptap/extension-bubble-menu": "^3.30.1",
+    "@tiptap/extension-floating-menu": "^3.30.1"
   },
   "scripts": {
     "build": "tsup"

package/src/VueWidgetRenderer.ts

@@ -0,0 +1,135 @@
+import { createWidgetDecoration } from '@tiptap/core'
+import type {
+  Editor as CoreEditor,
+  WidgetDecoration,
+  WidgetDecorationOptions,
+  WidgetRenderer,
+} from '@tiptap/core'
+import type { Component, VueConstructor } from 'vue'
+
+import type { Editor } from './Editor.js'
+import { createWidgetConstructor } from './utils/createWidgetConstructor.js'
+import { VueRenderer } from './VueRenderer.js'
+
+/**
+ * Props every widget-decoration component receives in addition to the props you
+ * pass through `VueWidgetRenderer`. Declare the ones you use on your component.
+ */
+export interface VueWidgetDecorationProps {
+  editor: CoreEditor
+  getPos: () => number | undefined
+}
+
+export interface VueWidgetRendererOptions<
+  P extends Record<string, any> = object,
+> extends WidgetDecorationOptions {
+  /**
+   * The editor instance.
+   */
+  editor: Editor
+  /**
+   * The document position the widget is rendered at.
+   */
+  pos: number
+  /**
+   * A stable, position-independent identifier for the widget.
+   * Reusing the same key keeps the component mounted across re-renders.
+   * Good: `comment-${id}`. Bad: paragraph index or document position.
+   */
+  key: string
+  /**
+   * Props passed to the component (merged with {@link VueWidgetDecorationProps}).
+   * The component must render a single root element.
+   */
+  props?: P
+}
+
+const WIDGET_CACHE = Symbol('tiptapVue2WidgetCache')
+
+// @ts-ignore
+const isDev = process.env.NODE_ENV !== 'production'
+
+/** The `VueRenderer` plus the warning wrapper the widget cache drives. */
+interface WidgetRendererEntry extends WidgetRenderer {
+  renderer: VueRenderer
+}
+
+// Vue 2 fixes the prop list at construction. Keys absent on first mount are
+// never declared, so updateProps silently drops them on later updates.
+function warnUndeclaredProps(renderer: VueRenderer, props: Record<string, any>, key: string): void {
+  if (!isDev) {
+    return
+  }
+
+  const declared = renderer.ref.$props ?? {}
+
+  for (const name of Object.keys(props)) {
+    if (!(name in declared)) {
+      console.warn(
+        `[tiptap warn]: VueWidgetRenderer prop "${name}" was not passed on first mount for widget "${key}".`,
+        'Vue 2 cannot declare new props after mount, so this value is ignored.',
+      )
+    }
+  }
+}
+
+// Wrap the renderer so every prop push warns, whether it comes from the first
+// render or from the deferred flush.
+function withPropWarnings(renderer: VueRenderer, key: string): WidgetRendererEntry {
+  return {
+    renderer,
+    updateProps: props => {
+      warnUndeclaredProps(renderer, props, key)
+      renderer.updateProps(props)
+    },
+    destroy: () => renderer.destroy(),
+  }
+}
+
+/**
+ * Renders a Vue 2 component into a ProseMirror widget decoration.
+ * Reuses Tiptap's `VueRenderer` so the component is mounted under the editor's
+ * content component (inject/provide works as usual). Use a stable `key` for
+ * stateful widgets. The component must render a single root element.
+ * @example
+ * addDecorations() {
+ *   return {
+ *     create: ({ editor, state }) =>
+ *       findMatches(state.doc).map(match =>
+ *         VueWidgetRenderer(MyWidget, {
+ *           editor, pos: match.pos, key: `match-${match.id}`,
+ *           props: { label: match.label },
+ *         }),
+ *       ),
+ *   }
+ * }
+ */
+export function VueWidgetRenderer<P extends Record<string, any> = object>(
+  component: Component,
+  options: VueWidgetRendererOptions<P>,
+): WidgetDecoration {
+  const { editor, key, props = {} as P } = options
+
+  return createWidgetDecoration<WidgetRendererEntry>({
+    // Forwards editor, pos, key and the ProseMirror widget options unchanged.
+    ...options,
+    props,
+    cacheKey: WIDGET_CACHE,
+    // `view` is not passed on purpose: Vue 2 deeply observes props and
+    // observing a ProseMirror view corrupts its internals.
+    context: getPos => ({ editor, getPos }),
+    create: renderProps => {
+      const base = (editor.contentComponent?.$options as any)?._base as VueConstructor | undefined
+      const Constructor = createWidgetConstructor(base, component, renderProps)
+
+      return withPropWarnings(
+        new VueRenderer(Constructor, {
+          parent: editor.contentComponent,
+          propsData: renderProps,
+        }),
+        key,
+      )
+    },
+    materialize: entry => entry.renderer.element as HTMLElement,
+  })
+}

package/src/index.ts

@@ -4,4 +4,5 @@ export * from './NodeViewContent.js'
 export * from './NodeViewWrapper.js'
 export * from './VueNodeViewRenderer.js'
 export * from './VueRenderer.js'
+export * from './VueWidgetRenderer.js'
 export * from '@tiptap/core'

package/src/menus/FloatingMenu.ts

@@ -16,6 +16,7 @@ export interface FloatingMenuInterface extends Vue {
   appendTo: FloatingMenuPluginProps['appendTo']
   shouldShow: FloatingMenuPluginProps['shouldShow']
   getPluginKey: () => FloatingMenuPluginProps['pluginKey']
+  isDestroyed: boolean
 }
 
 export const FloatingMenu: Component = {
@@ -58,39 +59,38 @@ export const FloatingMenu: Component = {
     },
   },
 
-  watch: {
-    editor: {
-      immediate: true,
-      handler(this: FloatingMenuInterface, editor: FloatingMenuPluginProps['editor']) {
-        if (!editor) {
-          return
-        }
-
-        if (!this.$el) {
-          return
-        }
-
-        ;(this.$el as HTMLElement).style.visibility = 'hidden'
-        ;(this.$el as HTMLElement).style.position = 'absolute'
-
-        this.$el.remove()
-
-        this.$nextTick(() => {
-          editor.registerPlugin(
-            FloatingMenuPlugin({
-              pluginKey: this.getPluginKey(),
-              editor,
-              element: this.$el as HTMLElement,
-              updateDelay: this.updateDelay,
-              resizeDelay: this.resizeDelay,
-              options: this.options,
-              appendTo: this.appendTo,
-              shouldShow: this.shouldShow,
-            }),
-          )
-        })
-      },
-    },
+  mounted(this: FloatingMenuInterface) {
+    const editor = this.editor
+    const el = this.$el as HTMLElement
+
+    if (!editor || !el) {
+      return
+    }
+
+    el.style.visibility = 'hidden'
+    el.style.position = 'absolute'
+
+    // Remove element from DOM; plugin will re-parent it when shown
+    el.remove()
+
+    this.$nextTick(() => {
+      if (this.isDestroyed) {
+        return
+      }
+
+      editor.registerPlugin(
+        FloatingMenuPlugin({
+          pluginKey: this.getPluginKey(),
+          editor,
+          element: el,
+          updateDelay: this.updateDelay,
+          resizeDelay: this.resizeDelay,
+          options: this.options,
+          appendTo: this.appendTo,
+          shouldShow: this.shouldShow,
+        }),
+      )
+    })
   },
 
   render(this: FloatingMenuInterface, createElement: CreateElement) {
@@ -109,7 +109,15 @@ export const FloatingMenu: Component = {
   },
 
   beforeDestroy(this: FloatingMenuInterface) {
-    this.editor.unregisterPlugin(this.getPluginKey())
+    this.isDestroyed = true
+
+    const editor = this.editor
+
+    if (!editor) {
+      return
+    }
+
+    editor.unregisterPlugin(this.getPluginKey())
   },
 
   methods: {

package/src/utils/createWidgetConstructor.ts

@@ -0,0 +1,38 @@
+import type { Component, VueConstructor } from 'vue'
+
+import { Vue } from '../Vue.js'
+
+/**
+ * Builds the Vue 2 constructor for a widget component.
+ *
+ * Extends the editor's own Vue constructor so the widget shares its context,
+ * then auto-declares every passed prop the component does not declare itself.
+ * Vue 2 fixes the prop list at construction, so undeclared keys would be
+ * dropped. Existing declarations keep their type, default and validator.
+ *
+ * @param base The editor's Vue constructor, or undefined to fall back to `Vue`.
+ * @param component The widget component.
+ * @param props The props the widget is mounted with.
+ * @returns A constructor that accepts every key in `props`.
+ * @example
+ * createWidgetConstructor(undefined, MyWidget, { editor, getPos, label: 'a' })
+ */
+export function createWidgetConstructor(
+  base: VueConstructor | undefined,
+  component: Component,
+  props: Record<string, any>,
+): VueConstructor {
+  const VueBase = base ?? Vue
+  const Extended = VueBase.extend(component as any)
+  const declaredProps = {
+    ...(Extended as unknown as { options: { props?: Record<string, any> } }).options.props,
+  }
+
+  for (const name of Object.keys(props)) {
+    if (!Object.prototype.hasOwnProperty.call(declaredProps, name)) {
+      declaredProps[name] = null
+    }
+  }
+
+  return Extended.extend({ props: declaredProps })
+}