@jvs-milkdown/core 1.0.0

package/src/__internal__/index.ts

@@ -0,0 +1,2 @@
+export * from './utils'
+export * from './remark-handlers'

package/src/__internal__/remark-handlers.ts

@@ -0,0 +1,48 @@
+import type { Options } from 'remark-stringify'
+
+export const remarkHandlers: Required<Options>['handlers'] = {
+  text: (node, _, state, info) => {
+    // This config is to remove the `&#20;` entity when have trailing spaces
+    const value = node.value
+    // Check if the text contains only trailing spaces that might be encoded
+    if (/^[^*_\\]*\s+$/.test(value)) {
+      // For text that ends with spaces but has no markdown special characters that need escaping,
+      // return the value directly to preserve trailing spaces
+      return value
+    }
+    // For other text, use safe to handle markdown escaping but prevent space encoding
+    return state.safe(value, { ...info, encode: [] })
+  },
+  strong: (node, _, state, info) => {
+    const marker = node.marker || state.options.strong || '*'
+    const exit = state.enter('strong')
+    const tracker = state.createTracker(info)
+    let value = tracker.move(marker + marker)
+    value += tracker.move(
+      state.containerPhrasing(node, {
+        before: value,
+        after: marker,
+        ...tracker.current(),
+      })
+    )
+    value += tracker.move(marker + marker)
+    exit()
+    return value
+  },
+  emphasis: (node, _, state, info) => {
+    const marker = node.marker || state.options.emphasis || '*'
+    const exit = state.enter('emphasis')
+    const tracker = state.createTracker(info)
+    let value = tracker.move(marker)
+    value += tracker.move(
+      state.containerPhrasing(node, {
+        before: value,
+        after: marker,
+        ...tracker.current(),
+      })
+    )
+    value += tracker.move(marker)
+    exit()
+    return value
+  },
+}

package/src/__internal__/utils.ts

@@ -0,0 +1,14 @@
+import type { Meta, MilkdownPlugin } from '@jvs-milkdown/ctx'
+
+export function withMeta<T extends MilkdownPlugin>(
+  plugin: T,
+  meta: Partial<Meta> & Pick<Meta, 'displayName'>
+): T {
+  plugin.meta = {
+    package: '@jvs-milkdown/core',
+    group: 'System',
+    ...meta,
+  }
+
+  return plugin
+}

package/src/editor/editor.ts

@@ -0,0 +1,300 @@
+import type { CtxRunner, MilkdownPlugin, Telemetry } from '@jvs-milkdown/ctx'
+
+import { Clock, Container, Ctx } from '@jvs-milkdown/ctx'
+
+import type { Config } from '../internal-plugin'
+
+import {
+  commands,
+  config,
+  editorState,
+  editorView,
+  init,
+  keymap,
+  parser,
+  pasteRule,
+  schema,
+  serializer,
+} from '../internal-plugin'
+
+/// The status of the editor.
+export enum EditorStatus {
+  /// The editor is not initialized.
+  Idle = 'Idle',
+  /// The editor is creating.
+  OnCreate = 'OnCreate',
+  /// The editor has been created and ready to use.
+  Created = 'Created',
+  /// The editor is destroying.
+  OnDestroy = 'OnDestroy',
+  /// The editor has been destroyed.
+  Destroyed = 'Destroyed',
+}
+
+/// Type for the callback called when editor status changed.
+export type OnStatusChange = (status: EditorStatus) => void
+
+type EditorPluginStore = Map<
+  MilkdownPlugin,
+  {
+    ctx: Ctx | undefined
+    handler: CtxRunner | undefined
+    cleanup: ReturnType<CtxRunner>
+  }
+>
+
+/// The milkdown editor class.
+export class Editor {
+  /// Create a new editor instance.
+  static make() {
+    return new Editor()
+  }
+
+  /// @internal
+  #enableInspector = false
+  /// @internal
+  #status = EditorStatus.Idle
+  /// @internal
+  #configureList: Config[] = []
+  /// @internal
+  #onStatusChange: OnStatusChange = () => undefined
+
+  /// @internal
+  readonly #container = new Container()
+  /// @internal
+  readonly #clock = new Clock()
+
+  /// @internal
+  readonly #usrPluginStore: EditorPluginStore = new Map()
+
+  /// @internal
+  readonly #sysPluginStore: EditorPluginStore = new Map()
+
+  /// @internal
+  readonly #ctx = new Ctx(this.#container, this.#clock)
+
+  /// @internal
+  readonly #loadInternal = () => {
+    const configPlugin = config(async (ctx) => {
+      await Promise.all(
+        this.#configureList.map((fn) => Promise.resolve(fn(ctx)))
+      )
+    })
+    const internalPlugins = [
+      schema,
+      parser,
+      serializer,
+      commands,
+      keymap,
+      pasteRule,
+      editorState,
+      editorView,
+      init(this),
+      configPlugin,
+    ]
+    this.#prepare(internalPlugins, this.#sysPluginStore)
+  }
+
+  /// @internal
+  readonly #prepare = (plugins: MilkdownPlugin[], store: EditorPluginStore) => {
+    plugins.forEach((plugin) => {
+      const ctx = this.#ctx.produce(
+        this.#enableInspector ? plugin.meta : undefined
+      )
+      const handler = plugin(ctx)
+      store.set(plugin, { ctx, handler, cleanup: undefined })
+    })
+  }
+
+  /// @internal
+  readonly #cleanup = (plugins: MilkdownPlugin[], remove = false) => {
+    return Promise.all(
+      [plugins].flat().map(async (plugin) => {
+        const loader = this.#usrPluginStore.get(plugin)
+        const cleanup = loader?.cleanup
+        if (remove) this.#usrPluginStore.delete(plugin)
+        else
+          this.#usrPluginStore.set(plugin, {
+            ctx: undefined,
+            handler: undefined,
+            cleanup: undefined,
+          })
+
+        if (typeof cleanup === 'function') return cleanup()
+
+        return cleanup
+      })
+    )
+  }
+
+  /// @internal
+  readonly #cleanupInternal = async () => {
+    await Promise.all(
+      [...this.#sysPluginStore.entries()].map(async ([_, { cleanup }]) => {
+        if (typeof cleanup === 'function') return cleanup()
+
+        return cleanup
+      })
+    )
+    this.#sysPluginStore.clear()
+  }
+
+  /// @internal
+  readonly #setStatus = (status: EditorStatus) => {
+    this.#status = status
+    this.#onStatusChange(status)
+  }
+
+  /// @internal
+  readonly #loadPluginInStore = (store: EditorPluginStore) => {
+    return [...store.entries()].map(async ([key, loader]) => {
+      const { ctx, handler } = loader
+      if (!handler) return
+
+      const cleanup = await handler()
+
+      store.set(key, { ctx, handler, cleanup })
+    })
+  }
+
+  /// Get the ctx of the editor.
+  get ctx() {
+    return this.#ctx
+  }
+
+  /// Get the status of the editor.
+  get status() {
+    return this.#status
+  }
+
+  /// Enable the inspector for the editor.
+  /// You can also pass `false` to disable the inspector.
+  readonly enableInspector = (enable = true) => {
+    this.#enableInspector = enable
+
+    return this
+  }
+
+  /// Subscribe to the status change event for the editor.
+  /// The new subscription will replace the old one.
+  readonly onStatusChange = (onChange: OnStatusChange) => {
+    this.#onStatusChange = onChange
+    return this
+  }
+
+  /// Add a config for the editor.
+  readonly config = (configure: Config) => {
+    this.#configureList.push(configure)
+    return this
+  }
+
+  /// Remove a config for the editor.
+  readonly removeConfig = (configure: Config) => {
+    this.#configureList = this.#configureList.filter((x) => x !== configure)
+    return this
+  }
+
+  /// Use a plugin or a list of plugins for the editor.
+  readonly use = (plugins: MilkdownPlugin | MilkdownPlugin[]) => {
+    const _plugins = [plugins].flat()
+    _plugins.flat().forEach((plugin) => {
+      this.#usrPluginStore.set(plugin, {
+        ctx: undefined,
+        handler: undefined,
+        cleanup: undefined,
+      })
+    })
+
+    if (this.#status === EditorStatus.Created)
+      this.#prepare(_plugins, this.#usrPluginStore)
+
+    return this
+  }
+
+  /// Remove a plugin or a list of plugins from the editor.
+  readonly remove = async (
+    plugins: MilkdownPlugin | MilkdownPlugin[]
+  ): Promise<Editor> => {
+    if (this.#status === EditorStatus.OnCreate) {
+      console.warn(
+        '[Milkdown]: You are trying to remove plugins when the editor is creating, this is not recommended, please check your code.'
+      )
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve(this.remove(plugins))
+        }, 50)
+      })
+    }
+
+    await this.#cleanup([plugins].flat(), true)
+    return this
+  }
+
+  /// Create the editor with current config and plugins.
+  /// If the editor is already created, it will be recreated.
+  readonly create = async (): Promise<Editor> => {
+    if (this.#status === EditorStatus.OnCreate) return this
+
+    if (this.#status === EditorStatus.Created) await this.destroy()
+
+    this.#setStatus(EditorStatus.OnCreate)
+
+    this.#loadInternal()
+    this.#prepare([...this.#usrPluginStore.keys()], this.#usrPluginStore)
+
+    await Promise.all(
+      [
+        this.#loadPluginInStore(this.#sysPluginStore),
+        this.#loadPluginInStore(this.#usrPluginStore),
+      ].flat()
+    )
+
+    this.#setStatus(EditorStatus.Created)
+    return this
+  }
+
+  /// Destroy the editor.
+  /// If you want to clear all plugins, set `clearPlugins` to `true`.
+  readonly destroy = async (clearPlugins = false): Promise<Editor> => {
+    if (
+      this.#status === EditorStatus.Destroyed ||
+      this.#status === EditorStatus.OnDestroy
+    )
+      return this
+
+    if (this.#status === EditorStatus.OnCreate) {
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve(this.destroy(clearPlugins))
+        }, 50)
+      })
+    }
+
+    if (clearPlugins) this.#configureList = []
+
+    this.#setStatus(EditorStatus.OnDestroy)
+    await this.#cleanup([...this.#usrPluginStore.keys()], clearPlugins)
+    await this.#cleanupInternal()
+
+    this.#setStatus(EditorStatus.Destroyed)
+    return this
+  }
+
+  /// Call an action with the ctx of the editor.
+  /// This method should be used after the editor is created.
+  readonly action = <T>(action: (ctx: Ctx) => T) => action(this.#ctx)
+
+  /// Get inspections of plugins in editor.
+  /// Make sure you have enabled inspector by `editor.enableInspector()` before calling this method.
+  readonly inspect = (): Telemetry[] => {
+    if (!this.#enableInspector) {
+      console.warn(
+        '[Milkdown]: You are trying to collect inspection when inspector is disabled, please enable inspector by `editor.enableInspector()` first.'
+      )
+      return []
+    }
+    return [...this.#sysPluginStore.values(), ...this.#usrPluginStore.values()]
+      .map(({ ctx }) => ctx?.inspector?.read())
+      .filter((x): x is Telemetry => Boolean(x))
+  }
+}

package/src/editor/index.ts

@@ -0,0 +1 @@
+export * from './editor'

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './editor'
+export * from './internal-plugin'

package/src/internal-plugin/atoms.ts

@@ -0,0 +1,69 @@
+import type { SliceType, TimerType } from '@jvs-milkdown/ctx'
+import type { InputRule } from '@jvs-milkdown/prose/inputrules'
+import type { EditorState, Plugin } from '@jvs-milkdown/prose/state'
+import type {
+  EditorView,
+  MarkViewConstructor,
+  NodeViewConstructor,
+} from '@jvs-milkdown/prose/view'
+import type { RemarkParser, RemarkPlugin } from '@jvs-milkdown/transformer'
+import type { Options } from 'remark-stringify'
+
+import { createSlice } from '@jvs-milkdown/ctx'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import { unified } from 'unified'
+
+import type { Editor } from '../editor'
+
+import { remarkHandlers } from '../__internal__'
+
+/// A slice which contains the editor view instance.
+export const editorViewCtx = createSlice({} as EditorView, 'editorView')
+
+/// A slice which contains the editor state.
+export const editorStateCtx = createSlice({} as EditorState, 'editorState')
+
+/// A slice which stores timers that need to be waited for before starting to run the plugin.
+/// By default, it's `[ConfigReady]`.
+export const initTimerCtx = createSlice([] as TimerType[], 'initTimer')
+
+/// A slice which stores the editor instance.
+export const editorCtx = createSlice({} as Editor, 'editor')
+
+/// A slice which stores the input rules.
+export const inputRulesCtx = createSlice([] as InputRule[], 'inputRules')
+
+/// A slice which stores the prosemirror plugins.
+export const prosePluginsCtx = createSlice([] as Plugin[], 'prosePlugins')
+
+/// A slice which stores the remark plugins.
+export const remarkPluginsCtx = createSlice(
+  [] as RemarkPlugin[],
+  'remarkPlugins'
+)
+
+type NodeView = [nodeId: string, view: NodeViewConstructor]
+
+/// A slice which stores the prosemirror node views.
+export const nodeViewCtx = createSlice([] as NodeView[], 'nodeView')
+
+type MarkView = [nodeId: string, view: MarkViewConstructor]
+
+/// A slice which stores the prosemirror mark views.
+export const markViewCtx = createSlice([] as MarkView[], 'markView')
+
+/// A slice which stores the remark instance.
+export const remarkCtx: SliceType<RemarkParser, 'remark'> = createSlice(
+  unified().use(remarkParse).use(remarkStringify),
+  'remark'
+)
+
+/// A slice which stores the remark stringify options.
+export const remarkStringifyOptionsCtx = createSlice(
+  {
+    handlers: remarkHandlers,
+    encode: [],
+  } as Options,
+  'remarkStringifyOptions'
+)

package/src/internal-plugin/commands.ts

@@ -0,0 +1,176 @@
+import type { Ctx, MilkdownPlugin, SliceType } from '@jvs-milkdown/ctx'
+import type { Command } from '@jvs-milkdown/prose/state'
+
+import { Container, createSlice, createTimer } from '@jvs-milkdown/ctx'
+import { callCommandBeforeEditorView } from '@jvs-milkdown/exception'
+import { chainCommands } from '@jvs-milkdown/prose/commands'
+
+import { withMeta } from '../__internal__'
+import { editorViewCtx } from './atoms'
+import { SchemaReady } from './schema'
+
+/// @internal
+export type Cmd<T = undefined> = (payload?: T) => Command
+
+/// @internal
+export type CmdKey<T = undefined> = SliceType<Cmd<T>>
+
+type InferParams<T> = T extends CmdKey<infer U> ? U : never
+
+/// A chainable command helper.
+export interface CommandChain {
+  /// Run the command chain.
+  run: () => boolean
+  /// Add an inline command to the chain.
+  inline: (command: Command) => CommandChain
+  /// Add a registered command to the chain.
+  pipe: {
+    <T extends CmdKey<any>>(
+      slice: string,
+      payload?: InferParams<T>
+    ): CommandChain
+    <T>(slice: CmdKey<T>, payload?: T): CommandChain
+    (slice: string | CmdKey<any>, payload?: any): CommandChain
+  }
+}
+
+/// The command manager.
+/// This manager will manage all commands in editor.
+/// Generally, you don't need to use this manager directly.
+/// You can use the `$command` and `$commandAsync` in `@jvs-milkdown/utils` to create and call a command.
+export class CommandManager {
+  /// @internal
+  #container = new Container()
+
+  /// @internal
+  #ctx: Ctx | null = null
+
+  /// @internal
+  setCtx = (ctx: Ctx) => {
+    this.#ctx = ctx
+  }
+
+  get ctx() {
+    return this.#ctx
+  }
+
+  /// Register a command into the manager.
+  create<T>(meta: CmdKey<T>, value: Cmd<T>) {
+    const slice = meta.create(this.#container.sliceMap)
+    slice.set(value)
+    return slice
+  }
+
+  /// Get a command from the manager.
+  get<T extends CmdKey<any>>(slice: string): Cmd<InferParams<T>>
+  get<T>(slice: CmdKey<T>): Cmd<T>
+  get(slice: string | CmdKey<any>): Cmd<any>
+  get(slice: string | CmdKey<any>): Cmd<any> {
+    return this.#container.get(slice).get()
+  }
+
+  /// Remove a command from the manager.
+  remove<T extends CmdKey<any>>(slice: string): void
+  remove<T>(slice: CmdKey<T>): void
+  remove(slice: string | CmdKey<any>): void
+  remove(slice: string | CmdKey<any>): void {
+    return this.#container.remove(slice)
+  }
+
+  /// Call a registered command.
+  call<T extends CmdKey<any>>(slice: string, payload?: InferParams<T>): boolean
+  call<T>(slice: CmdKey<T>, payload?: T): boolean
+  call(slice: string | CmdKey<any>, payload?: any): boolean
+  call(slice: string | CmdKey<any>, payload?: any): boolean {
+    if (this.#ctx == null) throw callCommandBeforeEditorView()
+
+    const cmd = this.get(slice)
+    const command = cmd(payload)
+    const view = this.#ctx.get(editorViewCtx)
+    return command(view.state, view.dispatch, view)
+  }
+
+  /// Call an inline command.
+  inline(command: Command) {
+    if (this.#ctx == null) throw callCommandBeforeEditorView()
+    const view = this.#ctx.get(editorViewCtx)
+    return command(view.state, view.dispatch, view)
+  }
+
+  /// Create a command chain.
+  /// All commands added by `pipe` will be run in order until one of them returns `true`.
+  chain = (): CommandChain => {
+    if (this.#ctx == null) throw callCommandBeforeEditorView()
+    const ctx = this.#ctx
+    const commands: Command[] = []
+    const get = this.get.bind(this)
+
+    const chains: CommandChain = {
+      run: () => {
+        const chained = chainCommands(...commands)
+        const view = ctx.get(editorViewCtx)
+        return chained(view.state, view.dispatch, view)
+      },
+      inline: (command: Command) => {
+        commands.push(command)
+        return chains
+      },
+      pipe: pipe.bind(this),
+    }
+
+    function pipe<T extends CmdKey<any>>(
+      slice: string,
+      payload?: InferParams<T>
+    ): typeof chains
+    function pipe<T>(slice: CmdKey<T>, payload?: T): typeof chains
+    function pipe(slice: string | CmdKey<any>, payload?: any): typeof chains
+    function pipe(slice: string | CmdKey<any>, payload?: any) {
+      const cmd = get(slice)
+      commands.push(cmd(payload))
+      return chains
+    }
+
+    return chains
+  }
+}
+
+/// Create a command key, which is a slice type that contains a command.
+export function createCmdKey<T = undefined>(key = 'cmdKey'): CmdKey<T> {
+  return createSlice((() => () => false) as Cmd<T>, key)
+}
+
+/// A slice which contains the command manager.
+export const commandsCtx = createSlice(new CommandManager(), 'commands')
+
+/// A slice which stores timers that need to be waited for before starting to run the plugin.
+/// By default, it's `[SchemaReady]`.
+export const commandsTimerCtx = createSlice([SchemaReady], 'commandsTimer')
+
+/// The timer which will be resolved when the commands plugin is ready.
+export const CommandsReady = createTimer('CommandsReady')
+
+/// The commands plugin.
+/// This plugin will create a command manager.
+///
+/// This plugin will wait for the schema plugin.
+export const commands: MilkdownPlugin = (ctx) => {
+  const cmd = new CommandManager()
+  cmd.setCtx(ctx)
+  ctx
+    .inject(commandsCtx, cmd)
+    .inject(commandsTimerCtx, [SchemaReady])
+    .record(CommandsReady)
+  return async () => {
+    await ctx.waitTimers(commandsTimerCtx)
+
+    ctx.done(CommandsReady)
+
+    return () => {
+      ctx.remove(commandsCtx).remove(commandsTimerCtx).clearTimer(CommandsReady)
+    }
+  }
+}
+
+withMeta(commands, {
+  displayName: 'Commands',
+})

package/src/internal-plugin/config.ts

@@ -0,0 +1,34 @@
+import type { Ctx, MilkdownPlugin } from '@jvs-milkdown/ctx'
+
+import { createTimer } from '@jvs-milkdown/ctx'
+
+import { withMeta } from '../__internal__'
+
+/// @internal
+export type Config = (ctx: Ctx) => void | Promise<void>
+
+/// The timer which will be resolved when the config plugin is ready.
+export const ConfigReady = createTimer('ConfigReady')
+
+/// The config plugin.
+/// This plugin will load all user configs.
+export function config(configure: Config): MilkdownPlugin {
+  const plugin: MilkdownPlugin = (ctx) => {
+    ctx.record(ConfigReady)
+
+    return async () => {
+      await configure(ctx)
+      ctx.done(ConfigReady)
+
+      return () => {
+        ctx.clearTimer(ConfigReady)
+      }
+    }
+  }
+
+  withMeta(plugin, {
+    displayName: 'Config',
+  })
+
+  return plugin
+}