@prosekit/react 0.6.0 → 0.6.2

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

@@ -0,0 +1,93 @@
+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 ReactNodeViewUserOptions,
+} from '@prosemirror-adapter/react'
+import {
+  createElement,
+  useMemo,
+  type ComponentType,
+  type FC,
+} from 'react'
+
+import { useExtension } from '../hooks/use-extension'
+
+/**
+ * @public
+ */
+export interface ReactNodeViewProps extends NodeViewContext {}
+
+/**
+ * @public
+ */
+export type ReactNodeViewComponent = ComponentType<ReactNodeViewProps>
+
+/**
+ * Options for {@link defineReactNodeView}.
+ *
+ * @public
+ */
+export interface ReactNodeViewOptions extends CoreNodeViewUserOptions<ReactNodeViewComponent> {
+  /**
+   * The name of the node type.
+   */
+  name: string
+}
+
+function withNodeViewProps(component: ReactNodeViewComponent) {
+  return function NodeViewPropsWrapper() {
+    const props: ReactNodeViewProps = useNodeViewContext()
+    return createElement(component, props)
+  }
+}
+
+/**
+ * @internal
+ */
+export const ReactNodeViewConsumer: FC = () => {
+  const nodeViewFactory = useNodeViewFactory()
+  const extension = useMemo(
+    () => defineReactNodeViewFactory(nodeViewFactory),
+    [nodeViewFactory],
+  )
+  useExtension(extension)
+
+  return null
+}
+
+/**
+ * Defines a node view using a React component.
+ *
+ * @public
+ */
+export function defineReactNodeView(options: ReactNodeViewOptions): Extension {
+  const { name, component, ...userOptions } = options
+
+  const args: ReactNodeViewUserOptions = {
+    ...userOptions,
+    component: withNodeViewProps(component),
+  }
+
+  return defineNodeViewComponent<ReactNodeViewUserOptions>({
+    group: 'react',
+    name,
+    args,
+  })
+}
+
+function defineReactNodeViewFactory(
+  factory: (options: ReactNodeViewUserOptions) => NodeViewConstructor,
+) {
+  return defineNodeViewFactory<ReactNodeViewUserOptions>({
+    group: 'react',
+    factory,
+  })
+}

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

@@ -0,0 +1,24 @@
+import { defineDocChangeHandler } from '@prosekit/core'
+import type { ProseMirrorNode } from '@prosekit/pm/model'
+import { useMemo } from 'react'
+
+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 = useMemo(
+    () => defineDocChangeHandler((view) => handler(view.state.doc)),
+    [handler],
+  )
+  useExtension(extension, options)
+}

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

@@ -0,0 +1,85 @@
+import {
+  defineMountHandler,
+  defineUpdateHandler,
+  EditorNotFoundError,
+  union,
+  type Editor,
+  type Extension,
+} from '@prosekit/core'
+import {
+  useMemo,
+  useSyncExternalStore,
+} from 'react'
+
+import { useEditorContext } from '../contexts/editor-context'
+
+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?: 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 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.
+   *
+   * This function should be memoized.
+   */
+  derive: (editor: Editor<E>) => Derived,
+  options?: UseEditorDerivedOptions<E>,
+): Derived {
+  const editorContext = useEditorContext<E>()
+  const editor = options?.editor ?? editorContext
+  if (!editor) {
+    throw new EditorNotFoundError()
+  }
+
+  const [subscribe, getSnapshot] = useMemo(() => {
+    return createEditorStore(editor, derive)
+  }, [editor, derive])
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+function createEditorStore<Derived, E extends Extension = any>(editor: Editor<E>, derive: (editor: Editor<E>) => Derived) {
+  let dirty = true
+  let derived: Derived
+
+  const subscribe = (onChange: VoidFunction): VoidFunction => {
+    const handleChange = () => {
+      dirty = true
+      onChange()
+    }
+    const extension = union(
+      defineUpdateHandler(handleChange),
+      defineMountHandler(handleChange),
+    )
+    return editor.use(extension)
+  }
+
+  const getSnapshot = () => {
+    if (dirty) {
+      dirty = false
+      derived = derive(editor)
+    }
+    return derived
+  }
+
+  return [subscribe, getSnapshot] as const
+}

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

@@ -0,0 +1,24 @@
+import {
+  EditorNotFoundError,
+  type Editor,
+  type Extension,
+} from '@prosekit/core'
+import { useEffect } from 'react'
+
+/**
+ * @internal
+ */
+export function useEditorExtension(
+  editor: Editor | null | undefined,
+  extension: Extension | null,
+): void {
+  if (!editor) {
+    throw new EditorNotFoundError()
+  }
+
+  useEffect(() => {
+    if (extension) {
+      return editor.use(extension)
+    }
+  }, [editor, extension])
+}

package/src/hooks/use-editor.ts

@@ -0,0 +1,62 @@
+import {
+  defineMountHandler,
+  defineUpdateHandler,
+  ProseKitError,
+  union,
+  type Editor,
+  type Extension,
+} from '@prosekit/core'
+import {
+  useEffect,
+  useReducer,
+} from 'react'
+
+import { useEditorContext } from '../contexts/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.
+   *
+   * Note this this option doesn't work with [React
+   * compiler](https://react.dev/learn/react-compiler) because the returned
+   * editor will be the same instance after state updates. If you're using React
+   * compiler, you should use {@link useEditorDerivedValue} instead.
+   *
+   * @default false
+   */
+  update?: boolean
+}): 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 forceUpdate = useForceUpdate()
+
+  useEffect(() => {
+    if (update) {
+      const extension = union(
+        defineMountHandler(forceUpdate),
+        defineUpdateHandler(forceUpdate),
+      )
+      return editor.use(extension)
+    }
+  }, [editor, update, forceUpdate])
+
+  return editor
+}
+
+function useForceUpdate() {
+  const [, dispatch] = useReducer((x: number) => x + 1, 0)
+  return dispatch
+}

package/src/hooks/use-extension.ts

@@ -0,0 +1,41 @@
+import type {
+  Editor,
+  Extension,
+  Priority,
+} from '@prosekit/core'
+
+import { useEditorContext } from '../contexts/editor-context'
+
+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?: Editor
+
+  /**
+   * Optional priority to add the extension with.
+   */
+  priority?: Priority
+}
+
+/**
+ * Add an extension to the editor.
+ */
+export function useExtension(
+  /**
+   * The 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: Extension | null,
+  options?: UseExtensionOptions,
+): void {
+  const editorContext = useEditorContext()
+  useEditorExtension(
+    options?.editor || editorContext,
+    usePriorityExtension(extension, options?.priority),
+  )
+}

package/src/hooks/use-keymap.ts

@@ -0,0 +1,15 @@
+import {
+  defineKeymap,
+  type Keymap,
+} from '@prosekit/core'
+import { useMemo } from 'react'
+
+import {
+  useExtension,
+  type UseExtensionOptions,
+} from './use-extension'
+
+export function useKeymap(keymap: Keymap, options?: UseExtensionOptions): void {
+  const extension = useMemo(() => defineKeymap(keymap), [keymap])
+  useExtension(extension, options)
+}

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

@@ -0,0 +1,18 @@
+import {
+  withPriority,
+  type Extension,
+  type Priority,
+} from '@prosekit/core'
+import { useMemo } from 'react'
+
+/**
+ * @internal
+ */
+export function usePriorityExtension<T extends Extension = Extension>(
+  extension: T | null,
+  priority?: Priority | null,
+): T | null {
+  return useMemo(() => {
+    return extension && priority ? withPriority(extension, priority) : extension
+  }, [extension, priority])
+}

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

@@ -0,0 +1,24 @@
+import { defineUpdateHandler } from '@prosekit/core'
+import type { EditorState } from '@prosekit/pm/state'
+import { useMemo } from 'react'
+
+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 = useMemo(
+    () => defineUpdateHandler((view) => handler(view.state)),
+    [handler],
+  )
+  useExtension(extension, options)
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export {
+  ProseKit,
+  type ProseKitProps,
+} from './components/prosekit'
+export {
+  defineReactMarkView,
+  type ReactMarkViewComponent,
+  type ReactMarkViewOptions,
+  type ReactMarkViewProps,
+} from './extensions/react-mark-view'
+export {
+  defineReactNodeView,
+  type ReactNodeViewComponent,
+  type ReactNodeViewOptions,
+  type ReactNodeViewProps,
+} from './extensions/react-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'
+export { type PropsWithClassName } from './types'

package/src/types.ts

@@ -0,0 +1,6 @@
+/**
+ * @internal
+ */
+export type PropsWithClassName<P = unknown> = P & {
+  className?: string | undefined
+}