@milkdown/crepe 7.19.2 → 7.21.0

package/src/feature/ai/types.ts

@@ -0,0 +1,178 @@
+import type { Ctx } from '@milkdown/kit/ctx'
+import type { MilkdownError } from '@milkdown/kit/exception'
+import type { StreamingConfig } from '@milkdown/kit/plugin/streaming'
+
+import type { AISuggestionsBuilder } from './instruction-tooltip/suggestions'
+
+export type {
+  AISubmenuBuilder,
+  AISubmenuDef,
+  AISuggestionItem,
+  AISuggestionsBuilder,
+} from './instruction-tooltip/suggestions'
+
+export interface AIPromptContext {
+  document: string
+  selection: string
+  instruction: string
+}
+
+/// An async generator that yields markdown tokens from an LLM or
+/// similar source. Called by `runAICmd` with the assembled prompt
+/// context and an abort signal.
+export type AIProvider = (
+  context: AIPromptContext,
+  signal: AbortSignal
+) => AsyncIterable<string>
+
+/// Diff-related config options passed through to the diff plugin and component.
+export interface AIDiffConfig {
+  acceptLabel?: string
+  rejectLabel?: string
+  customBlockTypes?: string[]
+  ignoreAttrs?: Record<string, string[]>
+}
+
+/// Customize the inline streaming indicator pill shown while AI runs.
+export interface AIStreamingIndicatorConfig {
+  /// Fallback active-form label when the current session has none set
+  /// (i.e., `runAICmd` was called without a `label`).
+  /// @default DEFAULT_STREAMING_FALLBACK_LABEL
+  fallbackLabel?: string
+
+  /// Hint text shown after the label, suggesting how to cancel.
+  /// @default DEFAULT_STREAMING_CANCEL_HINT
+  cancelHint?: string
+}
+
+/// Customize the floating diff actions panel (Retry / Reject all / Accept all).
+///
+/// Note: the enter-key icon used in the Accept-all shortcut chip is
+/// shared with the instruction tooltip and overridden via the top-level
+/// `AIFeatureConfig.enterKeyIcon`.
+export interface AIDiffActionsConfig {
+  /// @default DEFAULT_DIFF_ACTIONS_RETRY_LABEL
+  retryLabel?: string
+
+  /// @default DEFAULT_DIFF_ACTIONS_REJECT_ALL_LABEL
+  rejectAllLabel?: string
+
+  /// @default DEFAULT_DIFF_ACTIONS_ACCEPT_ALL_LABEL
+  acceptAllLabel?: string
+
+  /// Icon for the Retry button. Default: refresh icon.
+  retryIcon?: string
+
+  /// Icon for the Reject all button. Default: 'X' icon.
+  rejectIcon?: string
+
+  /// Icon for the Accept all button. Default: checkmark icon.
+  acceptIcon?: string
+
+  /// Modifier key glyph shown alongside the enter-key icon. Set to
+  /// 'Ctrl' on non-Mac platforms if you need to disambiguate.
+  /// @default DEFAULT_DIFF_ACTIONS_MOD_SYMBOL
+  modSymbol?: string
+}
+
+/// Configuration for `CrepeFeature.AI`.
+export interface AIFeatureConfig {
+  /// Async generator that yields markdown tokens. Required for
+  /// `runAICmd`; without it the command returns false. The diff and
+  /// streaming plugins load either way, so the feature can be enabled
+  /// without a provider for diff-only or manual-streaming use cases.
+  provider?: AIProvider
+
+  /// Optional. Assemble the context passed to `provider`.
+  /// Defaults to serializing the document (+ selection if any) as markdown.
+  buildContext?: (ctx: Ctx, instruction: string) => AIPromptContext
+
+  /// Whether to enter diff review after streaming completes. Default true.
+  diffReviewOnEnd?: boolean
+
+  /// Pass-through config for the diff plugin.
+  diff?: AIDiffConfig
+
+  /// Pass-through config for the streaming plugin.
+  /// `diffReviewOnEnd` is excluded here because it's controlled by
+  /// `AIFeatureConfig.diffReviewOnEnd` at the AI layer — setting it on
+  /// both would be confusing.
+  streaming?: Partial<Omit<StreamingConfig, 'diffReviewOnEnd'>>
+
+  /// Called when an error occurs during AI processing.
+  /// Receives a `MilkdownError` with code `aiProviderError` or
+  /// `aiBuildContextError`.
+  onError?: (error: MilkdownError) => void
+
+  /// Custom icon for both the toolbar AI entry point and the prefix slot
+  /// inside the instruction input. The toolbar feature can override this
+  /// for just the toolbar button via `ToolbarFeatureConfig.aiIcon`.
+  aiIcon?: string
+
+  /// Placeholder text for the AI instruction input on the main view.
+  /// @default DEFAULT_INSTRUCTION_PLACEHOLDER
+  instructionPlaceholder?: string
+
+  /// Label for the suggestions section header.
+  /// @default DEFAULT_SUGGESTIONS_HEADER_LABEL
+  suggestionsHeaderLabel?: string
+
+  /// Label for the free-text prompt section header.
+  /// @default DEFAULT_SEND_AS_PROMPT_HEADER_LABEL
+  sendAsPromptHeaderLabel?: string
+
+  /// Prefix text for the free-text prompt entry, before the quoted input.
+  /// @default DEFAULT_SEND_AS_PROMPT_LABEL
+  sendAsPromptLabel?: string
+
+  /// Accessible name for the round submit button in the input pill.
+  /// Surfaced as `aria-label` so screen readers don't announce the
+  /// icon-only button as "unlabeled".
+  /// @default DEFAULT_SUBMIT_BUTTON_LABEL
+  submitButtonLabel?: string
+
+  /// Accessible name announced for the suggestion list (`role="listbox"`)
+  /// inside the palette. Localize alongside the other strings.
+  /// @default DEFAULT_LISTBOX_LABEL
+  listboxLabel?: string
+
+  /// Icon for the round submit button in the input pill.
+  /// Default: an upward arrow.
+  sendIcon?: string
+
+  /// Icon shown next to the "Ask AI: …" entry. Default: paper-plane.
+  sendPromptIcon?: string
+
+  /// Icon used in the keyboard shortcut chip on the prompt entry.
+  /// Default: enter-key arrow.
+  enterKeyIcon?: string
+
+  /// Icon for the back arrow at the top of a submenu. Default: chevron-left.
+  chevronLeftIcon?: string
+
+  /// Icon shown on the right of submenu entries. Default: chevron-right.
+  chevronRightIcon?: string
+
+  /// Customize the suggestion list. The builder is pre-populated with the
+  /// built-in suggestions; the callback can add, remove, or replace any
+  /// item or submenu. To start from scratch, call `builder.clear()` first.
+  buildAISuggestions?: (builder: AISuggestionsBuilder) => void
+
+  /// Customize the inline streaming indicator pill shown while AI runs.
+  streamingIndicator?: AIStreamingIndicatorConfig
+
+  /// Customize the floating diff actions panel (Retry / Reject all /
+  /// Accept all) that appears once streaming hands off to diff review.
+  diffActions?: AIDiffActionsConfig
+}
+
+/// Options passed to `runAICmd`.
+export interface RunAIOptions {
+  /// The user instruction to send to the AI provider.
+  instruction: string
+
+  /// Optional active-form label shown in the streaming indicator
+  /// (e.g., "Improving writing", "Translating"). When omitted, falls
+  /// back to `streamingIndicator.fallbackLabel` (default `'Generating'`).
+  label?: string
+}

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

@@ -1,8 +1,9 @@
 import { Icon } from '@milkdown/kit/component'
 import { defineComponent, ref, h, Fragment } from 'vue'
 
-h
-Fragment
+import { keepAlive } from '../../../utils/keep-alive'
+
+keepAlive(h, Fragment)
 
 interface BlockHandleProps {
   onAdd: () => void

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

@@ -14,9 +14,10 @@ import {
 
 import type { BlockEditFeatureConfig } from '..'
 
+import { keepAlive } from '../../../utils/keep-alive'
 import { getGroups } from './config'
 
-h
+keepAlive(h)
 
 type MenuProps = {
   ctx: Ctx
@@ -91,7 +92,7 @@ export const Menu = defineComponent<MenuProps>({
       const item = groupInfo.value.groups
         .flatMap((group) => group.items)
         .at(index)
-      if (item && ctx) item.onRun(ctx)
+      if (item?.onRun && ctx) item.onRun(ctx)
 
       hide()
     }

package/src/feature/block-edit/menu/config.ts

@@ -350,7 +350,7 @@ export function getGroups(
           commands.call(clearTextInCurrentBlockCommand.key)
           commands.call(addBlockTypeCommand.key, {
             nodeType: codeBlock,
-            attrs: { language: 'LaTex' },
+            attrs: { language: 'LaTeX' },
           })
         },
       })

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

@@ -31,6 +31,8 @@ interface ImageBlockConfig {
   blockUploadPlaceholderText: string
   blockOnUpload: (file: File) => Promise<string>
   onImageLoadError: (event: Event) => void | Promise<void>
+  maxWidth: number
+  maxHeight: number
 }
 
 export type ImageBlockFeatureConfig = Partial<ImageBlockConfig>
@@ -63,6 +65,8 @@ export const imageBlock: DefineFeature<ImageBlockFeatureConfig> = (
         onUpload: config?.blockOnUpload ?? config?.onUpload ?? value.onUpload,
         proxyDomURL: config?.proxyDomURL,
         onImageLoadError: config?.onImageLoadError ?? value.onImageLoadError,
+        maxWidth: config?.maxWidth,
+        maxHeight: config?.maxHeight,
       }))
     })
     .use(imageBlockComponent)

package/src/feature/index.ts

@@ -1,3 +1,4 @@
+import type { AIFeatureConfig } from './ai'
 import type { BlockEditFeatureConfig } from './block-edit'
 import type { CodeMirrorFeatureConfig } from './code-mirror'
 import type { CursorFeatureConfig } from './cursor'
@@ -8,10 +9,11 @@ import type { ListItemFeatureConfig } from './list-item'
 import type { PlaceholderFeatureConfig } from './placeholder'
 import type { TableFeatureConfig } from './table'
 import type { ToolbarFeatureConfig } from './toolbar'
+import type { TopBarFeatureConfig } from './top-bar'
 
 /// The crepe editor feature flags.
-/// Every feature is enabled by default.
-/// Every feature is a string literal type.
+/// Most features are enabled by default; `TopBar` and `AI` are opt-in.
+/// See `defaultFeatures` for the per-flag default.
 export enum CrepeFeature {
   /// Syntax highlighting and editing for code blocks with language support, theme customization, and preview capabilities.
   CodeMirror = 'code-mirror',
@@ -42,6 +44,12 @@ export enum CrepeFeature {
 
   /// Mathematical formula support with both inline and block math rendering using KaTeX.
   Latex = 'latex',
+
+  /// Fixed top toolbar with heading selector, formatting buttons, insert actions, and block commands.
+  TopBar = 'top-bar',
+
+  /// AI-assisted editing: streaming input, diff review, and provider integration.
+  AI = 'ai',
 }
 
 export interface CrepeFeatureConfig {
@@ -55,6 +63,8 @@ export interface CrepeFeatureConfig {
   [CrepeFeature.CodeMirror]?: CodeMirrorFeatureConfig
   [CrepeFeature.Table]?: TableFeatureConfig
   [CrepeFeature.Latex]?: LatexFeatureConfig
+  [CrepeFeature.TopBar]?: TopBarFeatureConfig
+  [CrepeFeature.AI]?: AIFeatureConfig
 }
 
 export const defaultFeatures: Record<CrepeFeature, boolean> = {
@@ -68,4 +78,6 @@ export const defaultFeatures: Record<CrepeFeature, boolean> = {
   [CrepeFeature.CodeMirror]: true,
   [CrepeFeature.Table]: true,
   [CrepeFeature.Latex]: true,
+  [CrepeFeature.TopBar]: false,
+  [CrepeFeature.AI]: false,
 }

package/src/feature/latex/inline-tooltip/component.tsx

@@ -5,14 +5,16 @@ import { defineComponent, type ShallowRef, type VNodeRef, h } from 'vue'
 
 import type { LatexConfig } from '..'
 
+import { keepAlive } from '../../../utils/keep-alive'
+
+keepAlive(h)
+
 type LatexTooltipProps = {
   config: Partial<LatexConfig>
   innerView: ShallowRef<EditorView | null>
   updateValue: ShallowRef<() => void>
 }
 
-h
-
 export const LatexTooltip = defineComponent<LatexTooltipProps>({
   props: {
     config: {

package/src/feature/latex/inline-tooltip/inline-tooltip.spec.ts

@@ -0,0 +1,81 @@
+import '@testing-library/jest-dom/vitest'
+import type { Node } from '@milkdown/kit/prose/model'
+
+import { editorViewCtx } from '@milkdown/kit/core'
+import { NodeSelection } from '@milkdown/kit/prose/state'
+import { afterEach, describe, expect, test } from 'vitest'
+
+import { Crepe } from '../../../core'
+import { mathInlineId } from '../inline-latex'
+
+function waitForAsync() {
+  return new Promise<void>((resolve) => setTimeout(resolve, 0))
+}
+
+function findMathInlinePos(doc: Node) {
+  let pos: number | undefined
+  doc.descendants((node, currentPos) => {
+    if (node.type.name === mathInlineId) {
+      pos = currentPos
+      return false
+    }
+    return true
+  })
+  return pos
+}
+
+describe('latex inline tooltip', () => {
+  afterEach(() => {
+    document.body.replaceChildren()
+  })
+
+  test('should show in edit mode', async () => {
+    const crepe = new Crepe({
+      defaultValue: '$x$',
+    })
+
+    await crepe.create()
+
+    const view = crepe.editor.ctx.get(editorViewCtx)
+    const pos = findMathInlinePos(view.state.doc)
+    expect(pos).toBeTypeOf('number')
+
+    view.dispatch(
+      view.state.tr.setSelection(NodeSelection.create(view.state.doc, pos!))
+    )
+    await waitForAsync()
+
+    expect(view.state.selection).toBeInstanceOf(NodeSelection)
+    expect((view.state.selection as NodeSelection).node.type.name).toBe(
+      mathInlineId
+    )
+    expect(
+      document.body.querySelector('.milkdown-latex-inline-edit')
+    ).toHaveAttribute('data-show', 'true')
+  })
+
+  test('should not show in readonly editor', async () => {
+    const crepe = new Crepe({
+      defaultValue: '$x$',
+    }).setReadonly(true)
+
+    await crepe.create()
+
+    const view = crepe.editor.ctx.get(editorViewCtx)
+    const pos = findMathInlinePos(view.state.doc)
+    expect(pos).toBeTypeOf('number')
+
+    view.dispatch(
+      view.state.tr.setSelection(NodeSelection.create(view.state.doc, pos!))
+    )
+    await waitForAsync()
+
+    expect(view.state.selection).toBeInstanceOf(NodeSelection)
+    expect((view.state.selection as NodeSelection).node.type.name).toBe(
+      mathInlineId
+    )
+    expect(
+      document.body.querySelector('.milkdown-latex-inline-edit')
+    ).toHaveAttribute('data-show', 'false')
+  })
+})

package/src/feature/latex/inline-tooltip/view.ts

@@ -58,6 +58,8 @@ export class LatexInlineTooltip implements PluginView {
 
   #shouldShow = (view: EditorView) => {
     const shouldShow = () => {
+      if (!view.editable) return false
+
       const { selection, schema } = view.state
       if (selection.empty) return false
       if (!(selection instanceof NodeSelection)) return false

package/src/feature/loader.ts

@@ -1,5 +1,6 @@
 import type { Editor } from '@milkdown/kit/core'
 
+import { ai } from './ai'
 import { blockEdit } from './block-edit'
 import { codeMirror } from './code-mirror'
 import { cursor } from './cursor'
@@ -11,6 +12,7 @@ import { listItem } from './list-item'
 import { placeholder } from './placeholder'
 import { table } from './table'
 import { toolbar } from './toolbar'
+import { topBar } from './top-bar'
 
 export function loadFeature(
   feature: CrepeFeature,
@@ -48,5 +50,11 @@ export function loadFeature(
     case CrepeFeature.Latex: {
       return latex(editor, config)
     }
+    case CrepeFeature.TopBar: {
+      return topBar(editor, config)
+    }
+    case CrepeFeature.AI: {
+      return ai(editor, config)
+    }
   }
 }

package/src/feature/toolbar/component.tsx

@@ -15,10 +15,10 @@ import {
 
 import type { ToolbarFeatureConfig } from '.'
 
+import { keepAlive } from '../../utils/keep-alive'
 import { getGroups, type ToolbarItem } from './config'
 
-h
-Fragment
+keepAlive(h, Fragment)
 
 type ToolbarProps = {
   ctx: Ctx
@@ -54,14 +54,16 @@ export const Toolbar = defineComponent<ToolbarProps>({
   setup(props) {
     const { ctx, config } = props
 
-    const onClick = (fn: (ctx: Ctx) => void) => (e: MouseEvent) => {
+    const onClick = (fn?: (ctx: Ctx) => void) => (e: MouseEvent) => {
       e.preventDefault()
-      ctx && fn(ctx)
+      if (ctx) {
+        fn?.(ctx)
+      }
     }
 
     function checkActive(checker: ToolbarItem['active']) {
       // make sure the function subscribed to vue reactive
-      props.selection.value
+      keepAlive(props.selection.value)
       // Check if the edtior is ready
       const status = ctx.get(editorCtx).status
       if (status !== EditorStatus.Created) return false

package/src/feature/toolbar/config.ts

@@ -1,7 +1,7 @@
 import type { Ctx } from '@milkdown/kit/ctx'
 
 import { toggleLinkCommand } from '@milkdown/kit/component/link-tooltip'
-import { commandsCtx } from '@milkdown/kit/core'
+import { commandsCtx, editorViewCtx } from '@milkdown/kit/core'
 import {
   emphasisSchema,
   inlineCodeSchema,
@@ -23,6 +23,7 @@ import type { ToolbarFeatureConfig } from '.'
 import { CrepeFeature } from '..'
 import { useCrepeFeatures } from '../../core/slice'
 import {
+  aiIcon,
   boldIcon,
   codeIcon,
   functionsIcon,
@@ -31,6 +32,8 @@ import {
   strikethroughIcon,
 } from '../../icons'
 import { GroupBuilder } from '../../utils/group-builder'
+import { aiProviderConfig } from '../ai/commands'
+import { aiInstructionTooltipAPI } from '../ai/instruction-tooltip'
 import { toggleLatexCommand } from '../latex/command'
 import { mathInlineSchema } from '../latex/inline-latex'
 
@@ -130,6 +133,29 @@ export function getGroups(config?: ToolbarFeatureConfig, ctx?: Ctx) {
     },
   })
 
+  // Skip the AI button entirely when the feature is disabled or when no
+  // provider is configured — without a provider the palette would open
+  // but `runAICmd` would silently reject every action. Toolbar-level
+  // `aiIcon` wins over `AIFeatureConfig.aiIcon` so consumers can override
+  // just the toolbar entry without touching the tooltip prefix.
+  // The aiProviderConfig slice is only injected when the AI feature is
+  // active, so guard the lookup behind the flag check.
+  if (ctx && flags?.includes(CrepeFeature.AI)) {
+    const aiCfg = ctx.get(aiProviderConfig.key)
+    if (aiCfg.provider) {
+      functionGroup.addItem('ai', {
+        icon: config?.aiIcon ?? aiCfg.aiIcon ?? aiIcon,
+        active: () => false,
+        onRun: (ctx) => {
+          const api = ctx.get(aiInstructionTooltipAPI.key)
+          const view = ctx.get(editorViewCtx)
+          const { from, to } = view.state.selection
+          api.show(from, to)
+        },
+      })
+    }
+  }
+
   config?.buildToolbar?.(groupBuilder)
 
   return groupBuilder.build()

package/src/feature/toolbar/index.ts

@@ -25,6 +25,7 @@ interface ToolbarConfig {
   linkIcon: string
   strikethroughIcon: string
   latexIcon: string
+  aiIcon: string
   buildToolbar: (builder: GroupBuilder<ToolbarItem>) => void
 }