@milkdown/crepe 7.11.0 → 7.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@milkdown/crepe",
   "type": "module",
-  "version": "7.11.0",
+  "version": "7.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,6 +21,61 @@
       "require": "./lib/cjs/index.js",
       "types": "./lib/types/index.d.ts"
     },
+    "./builder": {
+      "import": "./lib/esm/builder.js",
+      "require": "./lib/cjs/builder.js",
+      "types": "./lib/types/builder.d.ts"
+    },
+    "./feature/block-edit": {
+      "import": "./lib/esm/feature/block-edit/index.js",
+      "require": "./lib/cjs/feature/block-edit/index.js",
+      "types": "./lib/types/feature/block-edit/index.d.ts"
+    },
+    "./feature/code-mirror": {
+      "import": "./lib/esm/feature/code-mirror/index.js",
+      "require": "./lib/cjs/feature/code-mirror/index.js",
+      "types": "./lib/types/feature/code-mirror/index.d.ts"
+    },
+    "./feature/cursor": {
+      "import": "./lib/esm/feature/cursor/index.js",
+      "require": "./lib/cjs/feature/cursor/index.js",
+      "types": "./lib/types/feature/cursor/index.d.ts"
+    },
+    "./feature/image-block": {
+      "import": "./lib/esm/feature/image-block/index.js",
+      "require": "./lib/cjs/feature/image-block/index.js",
+      "types": "./lib/types/feature/image-block/index.d.ts"
+    },
+    "./feature/latex": {
+      "import": "./lib/esm/feature/latex/index.js",
+      "require": "./lib/cjs/feature/latex/index.js",
+      "types": "./lib/types/feature/latex/index.d.ts"
+    },
+    "./feature/link-tooltip": {
+      "import": "./lib/esm/feature/link-tooltip/index.js",
+      "require": "./lib/cjs/feature/link-tooltip/index.js",
+      "types": "./lib/types/feature/link-tooltip/index.d.ts"
+    },
+    "./feature/list-item": {
+      "import": "./lib/esm/feature/list-item/index.js",
+      "require": "./lib/cjs/feature/list-item/index.js",
+      "types": "./lib/types/feature/list-item/index.d.ts"
+    },
+    "./feature/placeholder": {
+      "import": "./lib/esm/feature/placeholder/index.js",
+      "require": "./lib/cjs/feature/placeholder/index.js",
+      "types": "./lib/types/feature/placeholder/index.d.ts"
+    },
+    "./feature/table": {
+      "import": "./lib/esm/feature/table/index.js",
+      "require": "./lib/cjs/feature/table/index.js",
+      "types": "./lib/types/feature/table/index.d.ts"
+    },
+    "./feature/toolbar": {
+      "import": "./lib/esm/feature/toolbar/index.js",
+      "require": "./lib/cjs/feature/toolbar/index.js",
+      "types": "./lib/types/feature/toolbar/index.d.ts"
+    },
     "./theme/common/*": "./lib/theme/common/*",
     "./theme/classic.css": "./lib/theme/classic/style.css",
     "./theme/classic-dark.css": "./lib/theme/classic-dark/style.css",
@@ -41,21 +96,23 @@
     "@codemirror/state": "^6.4.1",
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "^6.16.0",
+    "@types/lodash-es": "^4.17.12",
     "clsx": "^2.0.0",
     "codemirror": "^6.0.1",
     "katex": "^0.16.0",
+    "lodash-es": "^4.17.21",
     "nanoid": "^5.0.9",
     "prosemirror-virtual-cursor": "^0.4.2",
     "remark-math": "^6.0.0",
     "tslib": "^2.8.1",
     "unist-util-visit": "^5.0.0",
     "vue": "^3.5.13",
-    "@milkdown/kit": "7.11.0"
+    "@milkdown/kit": "7.12.0"
   },
   "scripts": {
     "build": "pnpm run build:es && pnpm run build:theme && echo",
     "build:es": "rollup -c",
-    "build:theme": "postcss 'src/theme' --base 'src/theme' --dir 'lib/theme'"
+    "build:theme": "postcss src/theme --base src/theme --dir lib/theme"
   },
   "types": "./lib/types/index.d.ts"
 }

package/src/builder.ts

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

package/src/core/builder.ts

@@ -0,0 +1,143 @@
+import {
+  type DefaultValue,
+  defaultValueCtx,
+  Editor,
+  EditorStatus,
+  editorViewCtx,
+  editorViewOptionsCtx,
+  rootCtx,
+} from '@milkdown/kit/core'
+import { clipboard } from '@milkdown/kit/plugin/clipboard'
+import { history } from '@milkdown/kit/plugin/history'
+import { indent, indentConfig } from '@milkdown/kit/plugin/indent'
+import {
+  listener,
+  listenerCtx,
+  type ListenerManager,
+} from '@milkdown/kit/plugin/listener'
+import { trailing } from '@milkdown/kit/plugin/trailing'
+import { commonmark } from '@milkdown/kit/preset/commonmark'
+import { gfm } from '@milkdown/kit/preset/gfm'
+import { getMarkdown } from '@milkdown/kit/utils'
+
+import type { CrepeFeature, CrepeFeatureConfig } from '../feature'
+import type { DefineFeature } from '../feature/shared'
+
+import { CrepeCtx, FeaturesCtx } from './slice'
+
+/// The crepe builder configuration.
+export interface CrepeBuilderConfig {
+  /// The root element for the editor.
+  /// Supports both DOM nodes and CSS selectors,
+  /// If not provided, the editor will be appended to the body.
+  root?: Node | string | null
+
+  /// The default value for the editor.
+  defaultValue?: DefaultValue
+}
+
+/// The crepe builder class.
+/// This class allows users to manually add features to the editor.
+export class CrepeBuilder {
+  /// @internal
+  readonly #editor: Editor
+
+  /// @internal
+  readonly #rootElement: Node
+
+  /// @internal
+  #editable = true
+
+  /// The constructor of the crepe builder.
+  /// You can pass configs to the builder to configure the editor.
+  constructor({ root, defaultValue = '' }: CrepeBuilderConfig) {
+    this.#rootElement =
+      (typeof root === 'string' ? document.querySelector(root) : root) ??
+      document.body
+    this.#editor = Editor.make()
+      .config((ctx) => {
+        ctx.inject(CrepeCtx, this)
+        ctx.inject(FeaturesCtx, [])
+      })
+      .config((ctx) => {
+        ctx.set(rootCtx, this.#rootElement)
+        ctx.set(defaultValueCtx, defaultValue)
+        ctx.set(editorViewOptionsCtx, {
+          editable: () => this.#editable,
+        })
+        ctx.update(indentConfig.key, (value) => ({
+          ...value,
+          size: 4,
+        }))
+      })
+      .use(commonmark)
+      .use(listener)
+      .use(history)
+      .use(indent)
+      .use(trailing)
+      .use(clipboard)
+      .use(gfm)
+  }
+
+  /// Add a feature to the editor.
+  addFeature: {
+    <T extends CrepeFeature>(
+      feature: DefineFeature<CrepeFeatureConfig[T]>,
+      config?: CrepeFeatureConfig[T]
+    ): CrepeBuilder
+    <C>(feature: DefineFeature<C>, config?: C): CrepeBuilder
+  } = (feature: DefineFeature, config?: never) => {
+    feature(this.#editor, config)
+    return this
+  }
+
+  /// Create the editor.
+  create = () => {
+    return this.#editor.create()
+  }
+
+  /// Destroy the editor.
+  destroy = () => {
+    return this.#editor.destroy()
+  }
+
+  /// Get the milkdown editor instance.
+  get editor(): Editor {
+    return this.#editor
+  }
+
+  /// Set the readonly mode of the editor.
+  setReadonly = (value: boolean) => {
+    this.#editable = !value
+    this.#editor.action((ctx) => {
+      if (this.#editor.status === EditorStatus.Created) {
+        const view = ctx.get(editorViewCtx)
+        view.setProps({
+          editable: () => !value,
+        })
+      }
+    })
+    return this
+  }
+
+  /// Get the markdown content of the editor.
+  getMarkdown = () => {
+    return this.#editor.action(getMarkdown())
+  }
+
+  /// Register event listeners.
+  on = (fn: (api: ListenerManager) => void) => {
+    if (this.#editor.status !== EditorStatus.Created) {
+      this.#editor.config((ctx) => {
+        const listener = ctx.get(listenerCtx)
+        fn(listener)
+      })
+      return this
+    }
+    this.#editor.action((ctx) => {
+      const listener = ctx.get(listenerCtx)
+      fn(listener)
+    })
+    return this
+  }
+}

package/src/core/crepe.ts

@@ -1,48 +1,38 @@
-import type { DefaultValue } from '@milkdown/kit/core'
-import type { ListenerManager } from '@milkdown/kit/plugin/listener'
-
-import {
-  Editor,
-  EditorStatus,
-  defaultValueCtx,
-  editorViewCtx,
-  editorViewOptionsCtx,
-  rootCtx,
-} from '@milkdown/kit/core'
-import { clipboard } from '@milkdown/kit/plugin/clipboard'
-import { history } from '@milkdown/kit/plugin/history'
-import { indent, indentConfig } from '@milkdown/kit/plugin/indent'
-import { listener, listenerCtx } from '@milkdown/kit/plugin/listener'
-import { trailing } from '@milkdown/kit/plugin/trailing'
-import { commonmark } from '@milkdown/kit/preset/commonmark'
-import { gfm } from '@milkdown/kit/preset/gfm'
-import { getMarkdown } from '@milkdown/kit/utils'
+import { defaultsDeep } from 'lodash-es'
 
 import type { CrepeFeatureConfig } from '../feature'
 
-import { CrepeFeature, defaultFeatures, loadFeature } from '../feature'
-import { configureFeatures, crepeCtx } from './slice'
+import { defaultConfig } from '../default-config'
+import { CrepeFeature, defaultFeatures } from '../feature'
+import { loadFeature } from '../feature/loader'
+import { CrepeBuilder, type CrepeBuilderConfig } from './builder'
 
-export interface CrepeConfig {
+/// The crepe editor configuration.
+export interface CrepeConfig extends CrepeBuilderConfig {
+  /// Enable/disable specific features.
   features?: Partial<Record<CrepeFeature, boolean>>
+
+  /// Configure individual features.
   featureConfigs?: CrepeFeatureConfig
-  root?: Node | string | null
-  defaultValue?: DefaultValue
 }
 
-export class Crepe {
+/// The crepe editor class.
+export class Crepe extends CrepeBuilder {
+  /// This is an alias for the `CrepeFeature` enum.
   static Feature = CrepeFeature
-  readonly #editor: Editor
-  readonly #initPromise: Promise<unknown>
-  readonly #rootElement: Node
-  #editable = true
 
+  /// The constructor of the crepe editor.
+  /// You can pass configs to the editor to configure the editor.
+  /// Calling the constructor will not create the editor, you need to call `create` to create the editor.
   constructor({
-    root,
     features = {},
     featureConfigs = {},
-    defaultValue = '',
+    ...crepeBuilderConfig
   }: CrepeConfig) {
+    super(crepeBuilderConfig)
+
+    const finalConfigs = defaultsDeep(featureConfigs, defaultConfig)
+
     const enabledFeatures = Object.entries({
       ...defaultFeatures,
       ...features,
@@ -50,88 +40,11 @@ export class Crepe {
       .filter(([, enabled]) => enabled)
       .map(([feature]) => feature as CrepeFeature)
 
-    this.#rootElement =
-      (typeof root === 'string' ? document.querySelector(root) : root) ??
-      document.body
-    this.#editor = Editor.make()
-      .config((ctx) => {
-        ctx.inject(crepeCtx, this)
-      })
-      .config(configureFeatures(enabledFeatures))
-      .config((ctx) => {
-        ctx.set(rootCtx, this.#rootElement)
-        ctx.set(defaultValueCtx, defaultValue)
-        ctx.set(editorViewOptionsCtx, {
-          editable: () => this.#editable,
-        })
-        ctx.update(indentConfig.key, (value) => ({
-          ...value,
-          size: 4,
-        }))
-      })
-      .use(commonmark)
-      .use(listener)
-      .use(history)
-      .use(indent)
-      .use(trailing)
-      .use(clipboard)
-      .use(gfm)
-
-    const promiseList: Promise<unknown>[] = []
-
     enabledFeatures.forEach((feature) => {
-      const config = (featureConfigs as Partial<Record<CrepeFeature, never>>)[
+      const config = (finalConfigs as Partial<Record<CrepeFeature, never>>)[
         feature
       ]
-      promiseList.push(loadFeature(feature, this.#editor, config))
-    })
-
-    this.#initPromise = Promise.all(promiseList)
-  }
-
-  create = async () => {
-    await this.#initPromise
-    return this.#editor.create()
-  }
-
-  destroy = async () => {
-    await this.#initPromise
-    return this.#editor.destroy()
-  }
-
-  get editor(): Editor {
-    return this.#editor
-  }
-
-  setReadonly = (value: boolean) => {
-    this.#editable = !value
-    this.#editor.action((ctx) => {
-      if (this.#editor.status === EditorStatus.Created) {
-        const view = ctx.get(editorViewCtx)
-        view.setProps({
-          editable: () => !value,
-        })
-      }
-    })
-    return this
-  }
-
-  getMarkdown = () => {
-    return this.#editor.action(getMarkdown())
-  }
-
-  on = (fn: (api: ListenerManager) => void) => {
-    if (this.#editor.status !== EditorStatus.Created) {
-      this.#editor.config((ctx) => {
-        const listener = ctx.get(listenerCtx)
-        fn(listener)
-      })
-      return this
-    }
-    this.#editor.action((ctx) => {
-      const listener = ctx.get(listenerCtx)
-      fn(listener)
+      loadFeature(feature, this.editor, config)
     })
-    return this
   }
 }

package/src/core/index.ts

@@ -1,2 +1,3 @@
 export { Crepe, type CrepeConfig } from './crepe'
-export { crepeCtx } from './slice'
+export { CrepeBuilder, type CrepeBuilderConfig } from './builder'
+export { useCrepe, useCrepeFeatures } from './slice'

package/src/core/slice.ts

@@ -1,16 +1,56 @@
-import type { Ctx } from '@milkdown/kit/ctx'
-
-import { createSlice } from '@milkdown/kit/ctx'
+import { createSlice, type Ctx } from '@milkdown/kit/ctx'
 
 import type { CrepeFeature } from '../feature'
-import type { Crepe } from './crepe'
+import type { CrepeBuilder } from './builder'
 
+/// @internal
+/// The feature flags context.
+/// ⚠️ Most of the time, you should use `useCrepeFeatures` to get the features.
 export const FeaturesCtx = createSlice([] as CrepeFeature[], 'FeaturesCtx')
 
-export const crepeCtx = createSlice({} as Crepe, 'CrepeCtx')
+/// @internal
+/// The crepe editor context.
+/// ⚠️ Most of the time, you should use `useCrepe` to get the crepe editor instance.
+export const CrepeCtx = createSlice({} as CrepeBuilder, 'CrepeCtx')
+
+/// The crepe editor context.
+/// You can use this context to access the crepe editor instance within Milkdown plugins.
+/// ```ts
+/// import { crepeCtx } from '@milkdown/crepe'
+/// const plugin = (ctx: Ctx) => {
+///   return () => {
+///     const crepe = useCrepe(ctx)
+///     crepe.setReadonly(true)
+///   }
+/// }
+/// ```
+export function useCrepe(ctx: Ctx) {
+  // We should use string slice here to avoid the slice to be bundled in multiple entries
+  return ctx.get<CrepeBuilder, 'CrepeCtx'>('CrepeCtx')
+}
+
+/// Check the enabled FeatureFlags
+/// ```ts
+/// import { useCrepeFeatures } from '@milkdown/crepe'
+/// const plugin = (ctx: Ctx) => {
+///   const features = useCrepeFeatures(ctx)
+///   if (features.get().includes(CrepeFeature.CodeMirror)) {
+///     // Do something with CodeMirror
+///   }
+/// }
+export function useCrepeFeatures(ctx: Ctx) {
+  // We should use string slice here to avoid the slice to be bundled in multiple entries
+  return ctx.use<CrepeFeature[], 'FeaturesCtx'>('FeaturesCtx')
+}
 
-export function configureFeatures(features: CrepeFeature[]) {
+/// @internal
+export function crepeFeatureConfig(feature: CrepeFeature) {
   return (ctx: Ctx) => {
-    ctx.inject(FeaturesCtx, features)
+    useCrepeFeatures(ctx).update((features) => {
+      if (features.includes(feature)) {
+        return features
+      }
+      return [...features, feature]
+    })
   }
 }

package/src/default-config/index.ts

@@ -0,0 +1,25 @@
+import { languages } from '@codemirror/language-data'
+import { oneDark } from '@codemirror/theme-one-dark'
+
+import { CrepeFeature, type CrepeFeatureConfig } from '../feature'
+import {
+  chevronDownIcon,
+  clearIcon,
+  editIcon,
+  searchIcon,
+  visibilityOffIcon,
+} from '../icons'
+
+export const defaultConfig: CrepeFeatureConfig = {
+  [CrepeFeature.CodeMirror]: {
+    theme: oneDark,
+    languages,
+    expandIcon: chevronDownIcon,
+    searchIcon: searchIcon,
+    clearSearchIcon: clearIcon,
+    searchPlaceholder: 'Search language',
+    noResultText: 'No result',
+    previewToggleIcon: (previewOnlyMode) =>
+      previewOnlyMode ? editIcon : visibilityOffIcon,
+  },
+}

package/src/feature/block-edit/handle/component.tsx

@@ -1,15 +1,13 @@
 import { Icon } from '@milkdown/kit/component'
 import { defineComponent, ref, h, Fragment } from 'vue'
 
-import type { Icon as IconType } from '../../shared'
-
 h
 Fragment
 
 export interface BlockHandleProps {
   onAdd: () => void
-  addIcon: IconType
-  handleIcon: IconType
+  addIcon: string
+  handleIcon: string
 }
 
 export const BlockHandle = defineComponent<BlockHandleProps>({
@@ -19,11 +17,11 @@ export const BlockHandle = defineComponent<BlockHandleProps>({
       required: true,
     },
     addIcon: {
-      type: Function,
+      type: String,
       required: true,
     },
     handleIcon: {
-      type: Function,
+      type: String,
       required: true,
     },
   },
@@ -48,10 +46,10 @@ export const BlockHandle = defineComponent<BlockHandleProps>({
               props.onAdd()
             }}
           >
-            <Icon icon={props.addIcon()} />
+            <Icon icon={props.addIcon} />
           </div>
           <div class="operation-item">
-            <Icon icon={props.handleIcon()} />
+            <Icon icon={props.handleIcon} />
           </div>
         </>
       )

package/src/feature/block-edit/handle/index.ts

@@ -26,8 +26,8 @@ export class BlockHandleView implements PluginView {
     content.classList.add('milkdown-block-handle')
     const app = createApp(BlockHandle, {
       onAdd: this.onAdd,
-      addIcon: config?.handleAddIcon ?? (() => plusIcon),
-      handleIcon: config?.handleDragIcon ?? (() => menuIcon),
+      addIcon: config?.handleAddIcon ?? plusIcon,
+      handleIcon: config?.handleDragIcon ?? menuIcon,
     })
     app.mount(content)
     this.#app = app

package/src/feature/block-edit/index.ts

@@ -1,62 +1,65 @@
 import { block } from '@milkdown/kit/plugin/block'
 
-import type { DefineFeature, Icon } from '../shared'
+import type { DefineFeature } from '../shared'
 import type { GroupBuilder } from './menu/group-builder'
 
+import { crepeFeatureConfig } from '../../core/slice'
+import { CrepeFeature } from '../index'
 import { configureBlockHandle } from './handle'
 import { configureMenu, menu, menuAPI } from './menu'
 
 interface BlockEditConfig {
-  handleAddIcon: Icon
-  handleDragIcon: Icon
+  handleAddIcon: string
+  handleDragIcon: string
   buildMenu: (builder: GroupBuilder) => void
 
   slashMenuTextGroupLabel: string
-  slashMenuTextIcon: Icon
+  slashMenuTextIcon: string
   slashMenuTextLabel: string
-  slashMenuH1Icon: Icon
+  slashMenuH1Icon: string
   slashMenuH1Label: string
-  slashMenuH2Icon: Icon
+  slashMenuH2Icon: string
   slashMenuH2Label: string
-  slashMenuH3Icon: Icon
+  slashMenuH3Icon: string
   slashMenuH3Label: string
-  slashMenuH4Icon: Icon
+  slashMenuH4Icon: string
   slashMenuH4Label: string
-  slashMenuH5Icon: Icon
+  slashMenuH5Icon: string
   slashMenuH5Label: string
-  slashMenuH6Icon: Icon
+  slashMenuH6Icon: string
   slashMenuH6Label: string
-  slashMenuQuoteIcon: Icon
+  slashMenuQuoteIcon: string
   slashMenuQuoteLabel: string
-  slashMenuDividerIcon: Icon
+  slashMenuDividerIcon: string
   slashMenuDividerLabel: string
 
   slashMenuListGroupLabel: string
-  slashMenuBulletListIcon: Icon
+  slashMenuBulletListIcon: string
   slashMenuBulletListLabel: string
-  slashMenuOrderedListIcon: Icon
+  slashMenuOrderedListIcon: string
   slashMenuOrderedListLabel: string
-  slashMenuTaskListIcon: Icon
+  slashMenuTaskListIcon: string
   slashMenuTaskListLabel: string
 
   slashMenuAdvancedGroupLabel: string
-  slashMenuImageIcon: Icon
+  slashMenuImageIcon: string
   slashMenuImageLabel: string
-  slashMenuCodeBlockIcon: Icon
+  slashMenuCodeBlockIcon: string
   slashMenuCodeBlockLabel: string
-  slashMenuTableIcon: Icon
+  slashMenuTableIcon: string
   slashMenuTableLabel: string
-  slashMenuMathIcon: Icon
+  slashMenuMathIcon: string
   slashMenuMathLabel: string
 }
 
 export type BlockEditFeatureConfig = Partial<BlockEditConfig>
 
-export const defineFeature: DefineFeature<BlockEditFeatureConfig> = (
+export const blockEdit: DefineFeature<BlockEditFeatureConfig> = (
   editor,
   config
 ) => {
   editor
+    .config(crepeFeatureConfig(CrepeFeature.BlockEdit))
     .config((ctx) => configureBlockHandle(ctx, config))
     .config((ctx) => configureMenu(ctx, config))
     .use(menuAPI)