@prosekit/vue 0.5.0 → 0.6.0

package/src/extensions/vue-node-view.ts

@@ -0,0 +1,98 @@
+import {
+  defineNodeViewComponent,
+  defineNodeViewFactory,
+  type Extension,
+} from '@prosekit/core'
+import type { NodeViewConstructor } from '@prosekit/pm/view'
+import type { CoreNodeViewUserOptions } from '@prosemirror-adapter/core'
+import {
+  useNodeViewContext,
+  useNodeViewFactory,
+  type NodeViewContext,
+  type NodeViewFactory,
+  type VueNodeViewUserOptions,
+} from '@prosemirror-adapter/vue'
+import {
+  computed,
+  defineComponent,
+  h,
+  type DefineComponent,
+} from 'vue'
+
+import { useExtension } from '../hooks/use-extension'
+
+/**
+ * @public
+ */
+export interface VueNodeViewProps extends NodeViewContext {}
+
+/**
+ * @public
+ */
+export type VueNodeViewComponent = DefineComponent<VueNodeViewProps, any, any>
+
+/**
+ * Options for {@link defineVueNodeView}.
+ *
+ * @public
+ */
+export interface VueNodeViewOptions extends CoreNodeViewUserOptions<VueNodeViewComponent> {
+  /**
+   * The name of the node type.
+   */
+  name: string
+}
+
+function withNodeViewProps(component: VueNodeViewComponent) {
+  return defineComponent({
+    name: 'NodeViewPropsWrapper',
+    setup: () => {
+      const props: Readonly<VueNodeViewProps> = useNodeViewContext()
+      return () => h(component, props)
+    },
+  })
+}
+
+/**
+ * @internal
+ */
+export const VueNodeViewsConsumer: DefineComponent = /* @__PURE__ */ defineComponent({
+  name: 'VueNodeViewsConsumer',
+  setup: () => {
+    const nodeViewFactory: NodeViewFactory = useNodeViewFactory()
+    const extension = computed(() => {
+      return defineVueNodeViewFactory(nodeViewFactory)
+    })
+    useExtension(extension)
+    return (): null => null
+  },
+})
+
+/**
+ * Defines a node view using a Vue component.
+ *
+ * @public
+ */
+export function defineVueNodeView(options: VueNodeViewOptions): Extension {
+  const { name, component, ...userOptions } = options
+
+  const args: VueNodeViewUserOptions = {
+    ...userOptions,
+    component: withNodeViewProps(component),
+  }
+
+  return defineNodeViewComponent<VueNodeViewUserOptions>({
+    group: 'vue',
+    name,
+    args,
+  })
+}
+
+function defineVueNodeViewFactory(
+  factory: (options: VueNodeViewUserOptions) => NodeViewConstructor,
+) {
+  return defineNodeViewFactory<VueNodeViewUserOptions>({
+    group: 'vue',
+    factory,
+  })
+}

package/src/hooks/use-doc-change.ts

@@ -0,0 +1,20 @@
+import { defineDocChangeHandler } from '@prosekit/core'
+import type { ProseMirrorNode } from '@prosekit/pm/model'
+
+import {
+  useExtension,
+  type UseExtensionOptions,
+} from './use-extension'
+
+/**
+ * Calls the given handler whenever the editor document changes.
+ *
+ * @public
+ */
+export function useDocChange(
+  handler: (doc: ProseMirrorNode) => void,
+  options?: UseExtensionOptions,
+): void {
+  const extension = defineDocChangeHandler((view) => handler(view.state.doc))
+  useExtension(extension, options)
+}

package/src/hooks/use-editor-derived-value.ts

@@ -0,0 +1,51 @@
+import type {
+  Editor,
+  Extension,
+} from '@prosekit/core'
+import {
+  computed,
+  toValue,
+  type MaybeRefOrGetter,
+  type Ref,
+  type ShallowRef,
+} from 'vue'
+
+import { useEditor } from './use-editor'
+
+export interface UseEditorDerivedOptions<E extends Extension = any> {
+  /**
+   * The editor to add the extension to. If not provided, it will use the
+   * editor from the nearest `<ProseKit>` component.
+   */
+  editor?: MaybeRefOrGetter<Editor<E>>
+}
+
+/**
+ * Runs a function to derive a value from the editor instance after editor state
+ * changes.
+ *
+ * This is useful when you need to render something based on the editor state,
+ * for example, whether the selected text is wrapped in an italic mark.
+ *
+ * It returns a shallow ref of the derived value that updates whenever the editor
+ * state changes.
+ *
+ * @public
+ */
+export function useEditorDerivedValue<E extends Extension, Derived>(
+  /**
+   * A function that receives the editor instance and returns a derived value.
+   *
+   * It will be called whenever the editor's document state changes, or when it
+   * mounts.
+   */
+  derive: (editor: Editor<E>) => Derived,
+  options?: UseEditorDerivedOptions<E>,
+): ShallowRef<Derived> {
+  const initialEditor = options?.editor
+  const editorAccessor: Ref<Editor<E>> = initialEditor
+    ? computed(() => toValue(initialEditor))
+    : useEditor<E>({ update: true })
+
+  return computed(() => derive(toValue(editorAccessor)))
+}

package/src/hooks/use-editor-extension.ts

@@ -0,0 +1,34 @@
+import {
+  EditorNotFoundError,
+  type Editor,
+  type Extension,
+} from '@prosekit/core'
+import {
+  toValue,
+  watchPostEffect,
+  type MaybeRefOrGetter,
+} from 'vue'
+
+import { useEditorContext } from '../injection/editor-context'
+
+/**
+ * @internal
+ */
+export function useEditorExtension(
+  editorRef: MaybeRefOrGetter<Editor> | null | undefined,
+  extensionRef: MaybeRefOrGetter<Extension | null> | null,
+): void {
+  const editorContext = useEditorContext()
+
+  watchPostEffect((onCleanup) => {
+    const editor = toValue(editorRef) || toValue(editorContext)
+    const extension = toValue(extensionRef)
+
+    if (!editor) {
+      throw new EditorNotFoundError()
+    }
+    if (extension) {
+      onCleanup(editor.use(extension))
+    }
+  })
+}

package/src/hooks/use-editor.ts

@@ -0,0 +1,57 @@
+import {
+  defineMountHandler,
+  defineUpdateHandler,
+  ProseKitError,
+  union,
+  type Editor,
+  type Extension,
+} from '@prosekit/core'
+import {
+  onMounted,
+  onUnmounted,
+  shallowRef,
+  triggerRef,
+  type ShallowRef,
+} from 'vue'
+
+import { useEditorContext } from '../injection/editor-context'
+
+/**
+ * Retrieves the editor instance from the nearest ProseKit component.
+ *
+ * @public
+ */
+export function useEditor<E extends Extension = any>(options?: {
+  /**
+   * Whether to update the component when the editor is mounted or editor state
+   * is updated.
+   *
+   * @default false
+   */
+  update?: boolean
+}): ShallowRef<Editor<E>> {
+  const update = options?.update ?? false
+
+  const editor = useEditorContext<E>()
+  if (!editor) {
+    throw new ProseKitError(
+      'useEditor must be used within the ProseKit component',
+    )
+  }
+
+  const editorRef = shallowRef<Editor<E>>(editor)
+
+  if (update) {
+    onMounted(() => {
+      const forceUpdate = () => triggerRef(editorRef)
+      const extension = union(
+        defineMountHandler(forceUpdate),
+        defineUpdateHandler(forceUpdate),
+      )
+      const dispose = editor.use(extension)
+      onUnmounted(dispose)
+    })
+  }
+
+  return editorRef
+}

package/src/hooks/use-extension.spec.ts

@@ -0,0 +1,90 @@
+import {
+  createEditor,
+  defineNodeSpec,
+  definePlugin,
+  union,
+  type defineBaseCommands,
+  type Editor,
+} from '@prosekit/core'
+import {
+  Plugin,
+  PluginKey,
+} from '@prosekit/pm/state'
+import { mount } from '@vue/test-utils'
+import {
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import { defineComponent } from 'vue'
+
+import { useExtension } from './use-extension'
+
+function defineText() {
+  return defineNodeSpec({ name: 'text', topNode: true })
+}
+
+describe('useExtension', () => {
+  it('should register and dispose an extension', async () => {
+    const editor = createEditor({
+      extension: union(defineText()),
+    }) as Editor<ReturnType<typeof defineBaseCommands>>
+
+    editor.mount(document.createElement('div'))
+
+    const pluginKey = new PluginKey('test-plugin-key')
+    const extension = definePlugin(new Plugin({ key: pluginKey }))
+    const hasPlugin = (): boolean => {
+      const plugins = editor.state.plugins
+      return plugins.some((plugin) => plugin.spec.key === pluginKey)
+    }
+    const usePlugin = () => useExtension(extension, { editor })
+
+    const TestComponent = defineComponent({
+      setup: () => {
+        usePlugin()
+      },
+      render: () => null,
+    })
+
+    await vi.waitFor(() => expect(hasPlugin()).toBe(false))
+    const wrapper = mount(TestComponent)
+    await vi.waitFor(() => expect(hasPlugin()).toBe(true))
+    wrapper.unmount()
+    await vi.waitFor(() => expect(hasPlugin()).toBe(false))
+  })
+
+  it('should not print warning if the editor context is not available', () => {
+    const editor = createEditor({
+      extension: union(defineText()),
+    }) as Editor<ReturnType<typeof defineBaseCommands>>
+    editor.mount(document.createElement('div'))
+
+    const pluginKey = new PluginKey('test-plugin-key')
+    const extension = definePlugin(new Plugin({ key: pluginKey }))
+
+    const TestComponent = defineComponent({
+      setup: () => {
+        useExtension(extension, { editor })
+      },
+      render: () => null,
+    })
+
+    const messages: string[] = []
+    const warnHandler = vi.fn((message: string) => {
+      messages.push(message)
+    })
+
+    const wrapper = mount(TestComponent, {
+      global: {
+        config: {
+          warnHandler,
+        },
+      },
+    })
+    wrapper.unmount()
+
+    expect(messages).toEqual([])
+  })
+})

package/src/hooks/use-extension.ts

@@ -0,0 +1,41 @@
+import type {
+  Editor,
+  Extension,
+  Priority,
+} from '@prosekit/core'
+import type { MaybeRefOrGetter } from 'vue'
+
+import { useEditorExtension } from './use-editor-extension'
+import { usePriorityExtension } from './use-priority-extension'
+
+export interface UseExtensionOptions {
+  /**
+   * The editor to add the extension to. If not provided, it will use the
+   * editor from the nearest `<ProseKit>` component.
+   */
+  editor?: MaybeRefOrGetter<Editor>
+
+  /**
+   * Optional priority to add the extension with.
+   */
+  priority?: Priority
+}
+
+/**
+ * Add an extension to the editor.
+ *
+ * @public
+ */
+export function useExtension(
+  /**
+   * The ref to an extension to add to the editor. If it changes, the previous
+   * extension will be removed and the new one (if not null) will be added.
+   */
+  extension: MaybeRefOrGetter<Extension | null>,
+  options?: UseExtensionOptions,
+): void {
+  useEditorExtension(
+    options?.editor,
+    usePriorityExtension(extension, options?.priority),
+  )
+}

package/src/hooks/use-keymap.ts

@@ -0,0 +1,22 @@
+import {
+  defineKeymap,
+  type Keymap,
+} from '@prosekit/core'
+import {
+  computed,
+  toValue,
+  type MaybeRefOrGetter,
+} from 'vue'
+
+import {
+  useExtension,
+  type UseExtensionOptions,
+} from './use-extension'
+
+export function useKeymap(
+  keymap: MaybeRefOrGetter<Keymap>,
+  options?: UseExtensionOptions,
+): void {
+  const extension = computed(() => defineKeymap(toValue(keymap)))
+  useExtension(extension, options)
+}

package/src/hooks/use-priority-extension.ts

@@ -0,0 +1,24 @@
+import {
+  withPriority,
+  type Extension,
+  type Priority,
+} from '@prosekit/core'
+import {
+  computed,
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from 'vue'
+
+/**
+ * @internal
+ */
+export function usePriorityExtension<T extends Extension = Extension>(
+  extension: MaybeRefOrGetter<T | null>,
+  priority: Priority | null | undefined,
+): ComputedRef<T | null> {
+  return computed(() => {
+    const ext = toValue(extension)
+    return ext && priority ? withPriority(ext, priority) : ext
+  })
+}

package/src/hooks/use-state-update.ts

@@ -0,0 +1,20 @@
+import { defineUpdateHandler } from '@prosekit/core'
+import type { EditorState } from '@prosekit/pm/state'
+
+import {
+  useExtension,
+  type UseExtensionOptions,
+} from './use-extension'
+
+/**
+ * Calls the given handler whenever the editor state changes.
+ *
+ * @public
+ */
+export function useStateUpdate(
+  handler: (state: EditorState) => void,
+  options?: UseExtensionOptions,
+): void {
+  const extension = defineUpdateHandler((view) => handler(view.state))
+  useExtension(extension, options)
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export {
+  ProseKit,
+  type ProseKitProps,
+} from './components/prosekit'
+export {
+  defineVueMarkView,
+  type VueMarkViewComponent,
+  type VueMarkViewOptions,
+  type VueMarkViewProps,
+} from './extensions/vue-mark-view'
+export {
+  defineVueNodeView,
+  type VueNodeViewComponent,
+  type VueNodeViewOptions,
+  type VueNodeViewProps,
+} from './extensions/vue-node-view'
+export { useDocChange } from './hooks/use-doc-change'
+export { useEditor } from './hooks/use-editor'
+export {
+  useEditorDerivedValue,
+  type UseEditorDerivedOptions,
+} from './hooks/use-editor-derived-value'
+export {
+  useExtension,
+  type UseExtensionOptions,
+} from './hooks/use-extension'
+export { useKeymap } from './hooks/use-keymap'
+export { useStateUpdate } from './hooks/use-state-update'

package/src/injection/editor-context.ts

@@ -0,0 +1,25 @@
+import type {
+  Editor,
+  Extension,
+} from '@prosekit/core'
+import {
+  inject,
+  provide,
+  type InjectionKey,
+} from 'vue'
+
+const symbol = Symbol('prosekit-vue-editor-context') as InjectionKey<Editor>
+
+/**
+ * @internal
+ */
+export function provideEditor(editor: Editor): void {
+  provide(symbol, editor)
+}
+
+/**
+ * @internal
+ */
+export function useEditorContext<E extends Extension>(): Editor<E> | undefined {
+  return inject(symbol, undefined)
+}