@milkdown/crepe 7.19.2 → 7.21.0

package/src/feature/ai/instruction-tooltip/suggestions.ts

@@ -0,0 +1,249 @@
+import {
+  aiIcon,
+  editIcon,
+  grammarCheckIcon,
+  longerIcon,
+  shorterIcon,
+  translateIcon,
+} from '../../../icons'
+
+/// A single AI suggestion. `prompt` is sent to the provider; `streamingLabel`
+/// is the active-form text shown in the streaming indicator while AI runs.
+export interface AISuggestionItem {
+  icon: string
+  label: string
+  streamingLabel?: string
+  prompt: string
+}
+
+/// A submenu definition. `title` is shown next to the back arrow when the
+/// submenu is open; `searchPlaceholder` replaces the input placeholder.
+export interface AISubmenuDef {
+  icon: string
+  label: string
+  title: string
+  searchPlaceholder: string
+}
+
+/// Mutates a submenu's items in place. Obtained from
+/// `AISuggestionsBuilder.addSubmenu` (via the build callback) or
+/// `AISuggestionsBuilder.getSubmenu(id)`.
+export interface AISubmenuBuilder {
+  addItem: (id: string, item: AISuggestionItem) => AISubmenuBuilder
+  removeItem: (id: string) => AISubmenuBuilder
+  getItem: (id: string) => AISuggestionItem | undefined
+  clear: () => AISubmenuBuilder
+}
+
+interface SubmenuNode {
+  def: AISubmenuDef
+  items: Map<string, AISuggestionItem>
+}
+
+function createSubmenuBuilder(node: SubmenuNode): AISubmenuBuilder {
+  const builder: AISubmenuBuilder = {
+    addItem: (id, item) => {
+      node.items.set(id, item)
+      return builder
+    },
+    removeItem: (id) => {
+      node.items.delete(id)
+      return builder
+    },
+    getItem: (id) => node.items.get(id),
+    clear: () => {
+      node.items.clear()
+      return builder
+    },
+  }
+  return builder
+}
+
+type RootNode =
+  | { kind: 'item'; id: string; item: AISuggestionItem }
+  | { kind: 'submenu'; id: string; node: SubmenuNode }
+
+export type ResolvedItemEntry = {
+  kind: 'item'
+  id: string
+  item: AISuggestionItem
+}
+
+export type ResolvedSubmenuEntry = {
+  kind: 'submenu'
+  id: string
+  def: AISubmenuDef
+}
+
+/// Resolved tree consumed by the tooltip view. `submenus` is keyed by
+/// submenu id so the view can switch between main and submenu lists.
+export interface ResolvedSuggestions {
+  main: Array<ResolvedItemEntry | ResolvedSubmenuEntry>
+  submenus: Record<
+    string,
+    { def: AISubmenuDef; items: Array<{ id: string; item: AISuggestionItem }> }
+  >
+}
+
+export class AISuggestionsBuilder {
+  #nodes: RootNode[] = []
+
+  addItem = (id: string, item: AISuggestionItem) => {
+    this.#removeById(id)
+    this.#nodes.push({ kind: 'item', id, item })
+    return this
+  }
+
+  /// Add a submenu. Populate items via the optional `build` callback,
+  /// or call `getSubmenu(id)` afterward. Returns `this` so calls can be
+  /// chained at the parent level alongside `addItem`.
+  addSubmenu = (
+    id: string,
+    def: AISubmenuDef,
+    build?: (sub: AISubmenuBuilder) => void
+  ) => {
+    this.#removeById(id)
+    const node: SubmenuNode = { def, items: new Map() }
+    if (build) build(createSubmenuBuilder(node))
+    this.#nodes.push({ kind: 'submenu', id, node })
+    return this
+  }
+
+  removeItem = (id: string) => {
+    this.#removeById(id)
+    return this
+  }
+
+  getItem = (id: string) => {
+    const node = this.#nodes.find((n) => n.kind === 'item' && n.id === id)
+    return node?.kind === 'item' ? node.item : undefined
+  }
+
+  /// Return a builder that mutates the submenu's items in place.
+  /// Multiple calls return distinct builder objects backed by the same
+  /// underlying node, so changes are always visible.
+  getSubmenu = (id: string) => {
+    const node = this.#nodes.find((n) => n.kind === 'submenu' && n.id === id)
+    return node?.kind === 'submenu'
+      ? createSubmenuBuilder(node.node)
+      : undefined
+  }
+
+  clear = () => {
+    this.#nodes = []
+    return this
+  }
+
+  build = (): ResolvedSuggestions => {
+    const main: ResolvedSuggestions['main'] = []
+    const submenus: ResolvedSuggestions['submenus'] = {}
+    for (const node of this.#nodes) {
+      if (node.kind === 'item') {
+        main.push({ kind: 'item', id: node.id, item: node.item })
+      } else {
+        main.push({ kind: 'submenu', id: node.id, def: node.node.def })
+        submenus[node.id] = {
+          def: node.node.def,
+          items: Array.from(node.node.items.entries()).map(([id, item]) => ({
+            id,
+            item,
+          })),
+        }
+      }
+    }
+    return { main, submenus }
+  }
+
+  #removeById = (id: string) => {
+    this.#nodes = this.#nodes.filter((n) => n.id !== id)
+  }
+}
+
+/// Populate a builder with the built-in defaults. Called before the
+/// user's `buildAISuggestions` callback so the user can add to,
+/// inspect, or remove any default.
+export function applyDefaultSuggestions(builder: AISuggestionsBuilder): void {
+  builder
+    .addItem('improve', {
+      icon: aiIcon,
+      label: 'Improve writing',
+      streamingLabel: 'Improving writing',
+      prompt: 'Improve the writing while preserving the original meaning.',
+    })
+    .addItem('grammar', {
+      icon: grammarCheckIcon,
+      label: 'Fix grammar & spelling',
+      streamingLabel: 'Fixing grammar & spelling',
+      prompt:
+        'Fix any grammar and spelling errors without changing the meaning.',
+    })
+    .addItem('shorter', {
+      icon: shorterIcon,
+      label: 'Make shorter',
+      streamingLabel: 'Making shorter',
+      prompt: 'Make this shorter while preserving the key information.',
+    })
+    .addItem('longer', {
+      icon: longerIcon,
+      label: 'Make longer',
+      streamingLabel: 'Expanding',
+      prompt: 'Expand this with more detail and examples.',
+    })
+
+  builder.addSubmenu(
+    'tone',
+    {
+      icon: editIcon,
+      label: 'Change tone…',
+      title: 'Change tone',
+      searchPlaceholder: 'Search tones…',
+    },
+    (sub) => {
+      const tones: Array<[string, string]> = [
+        ['professional', 'Professional'],
+        ['casual', 'Casual'],
+        ['confident', 'Confident'],
+        ['friendly', 'Friendly'],
+        ['direct', 'Direct'],
+        ['formal', 'Formal'],
+      ]
+      for (const [id, label] of tones) {
+        sub.addItem(id, {
+          icon: editIcon,
+          label,
+          streamingLabel: 'Adjusting tone',
+          prompt: `Rewrite this in a ${label.toLowerCase()} tone.`,
+        })
+      }
+    }
+  )
+
+  builder.addSubmenu(
+    'translate',
+    {
+      icon: translateIcon,
+      label: 'Translate…',
+      title: 'Translate',
+      searchPlaceholder: 'Search languages…',
+    },
+    (sub) => {
+      const languages: Array<[string, string, string]> = [
+        ['english', 'English', 'English'],
+        ['chinese', 'Chinese', 'Chinese (Simplified)'],
+        ['japanese', 'Japanese', 'Japanese'],
+        ['korean', 'Korean', 'Korean'],
+        ['spanish', 'Spanish', 'Spanish'],
+        ['french', 'French', 'French'],
+        ['german', 'German', 'German'],
+      ]
+      for (const [id, label, promptName] of languages) {
+        sub.addItem(id, {
+          icon: translateIcon,
+          label,
+          streamingLabel: `Translating to ${label}`,
+          prompt: `Translate this to ${promptName}.`,
+        })
+      }
+    }
+  )
+}

package/src/feature/ai/instruction-tooltip/view.ts

@@ -0,0 +1,159 @@
+import type { Ctx } from '@milkdown/kit/ctx'
+import type { EditorState, PluginView } from '@milkdown/kit/prose/state'
+import type { EditorView } from '@milkdown/kit/prose/view'
+
+import { commandsCtx, editorViewCtx } from '@milkdown/kit/core'
+import { TooltipProvider } from '@milkdown/kit/plugin/tooltip'
+import { posToDOMRect } from '@milkdown/kit/prose'
+import { TextSelection } from '@milkdown/kit/prose/state'
+import { createApp, ref, type App } from 'vue'
+
+import type { ResolvedSuggestions } from './suggestions'
+
+import { runAICmd } from '../commands'
+import {
+  AIInstructionInput,
+  type AIInstructionTooltipChrome,
+} from './component'
+
+export interface AIInstructionTooltipViewConfig {
+  placeholder: string
+  chrome: AIInstructionTooltipChrome
+  suggestions: ResolvedSuggestions
+}
+
+export class AIInstructionTooltipView implements PluginView {
+  #content: HTMLElement
+  #provider: TooltipProvider
+  #app: App
+  #placeholder
+  #resetSignal
+  #from = -1
+  #to = -1
+  /// Source of truth for "should the palette currently be showing".
+  /// `TooltipProvider.shouldShow` reads this so that forwarding `update()`
+  /// to the provider on every editor transition (needed to keep the
+  /// floating position in sync with layout changes) doesn't dismiss the
+  /// palette behind our back.
+  #wantsShow = false
+
+  constructor(
+    readonly ctx: Ctx,
+    view: EditorView,
+    config: AIInstructionTooltipViewConfig
+  ) {
+    // Wrapped in a ref so the Vue component re-renders if it ever
+    // changes; today there's no setter, but keeping it reactive lets a
+    // future API (e.g. context-sensitive placeholders) plug in cleanly.
+    this.#placeholder = ref(config.placeholder)
+    // Bumped on each `show()` so the component clears input/submenu/cursor
+    // state — the Vue app stays mounted across hide/show cycles, so its
+    // local state would otherwise persist into the next session.
+    this.#resetSignal = ref(0)
+
+    const content = document.createElement('div')
+    content.className = 'milkdown-ai-instruction'
+
+    const app = createApp(AIInstructionInput, {
+      placeholder: this.#placeholder,
+      resetSignal: this.#resetSignal,
+      suggestions: config.suggestions,
+      chrome: config.chrome,
+      onConfirm: this.#onConfirm,
+      onCancel: this.#onCancel,
+    })
+    app.mount(content)
+    this.#app = app
+    this.#content = content
+
+    this.#provider = new TooltipProvider({
+      content,
+      debounce: 0,
+      offset: 10,
+      shouldShow: () => this.#wantsShow,
+      floatingUIOptions: {
+        placement: 'bottom',
+      },
+    })
+    this.#provider.onHide = () => {
+      this.#wantsShow = false
+      requestAnimationFrame(() => {
+        try {
+          // Only restore focus to the editor when the palette itself
+          // was holding focus at hide time (Escape, Enter-to-confirm,
+          // selection-driven dismissal). If the user dismissed the
+          // palette by clicking somewhere else, focus is already on
+          // that target and stealing it back would frustrate keyboard
+          // and assistive-technology users trying to leave the editor.
+          const root = this.#content.getRootNode() as Document | ShadowRoot
+          const active = root.activeElement
+          if (!active || !this.#content.contains(active)) return
+          const v = this.ctx.get(editorViewCtx)
+          v.dom.focus({ preventScroll: true })
+        } catch {
+          // Editor may be destroyed
+        }
+      })
+    }
+    this.#provider.update(view)
+  }
+
+  #onConfirm = (instruction: string, label?: string) => {
+    if (!instruction.trim()) return
+    // Dispatch first and only dismiss the palette on success. If
+    // `runAICmd` rejects (no provider, an active streaming session, an
+    // active diff review, …) the user's typed instruction stays visible
+    // so they can retry once the editor is in a state that accepts it.
+    const commands = this.ctx.get(commandsCtx)
+    const accepted = commands.call(runAICmd.key, { instruction, label })
+    if (!accepted) return
+    this.#wantsShow = false
+    this.#provider.hide()
+  }
+
+  #onCancel = () => {
+    this.#wantsShow = false
+    this.#provider.hide()
+  }
+
+  show = (from: number, to: number) => {
+    this.#from = from
+    this.#to = to
+    this.#resetSignal.value++
+    this.#wantsShow = true
+    const view = this.ctx.get(editorViewCtx)
+    this.#provider.show(
+      { getBoundingClientRect: () => posToDOMRect(view, from, to) },
+      view
+    )
+    requestAnimationFrame(() => {
+      this.#content.querySelector('input')?.focus()
+    })
+  }
+
+  update = (view: EditorView, prevState?: EditorState) => {
+    const { selection } = view.state
+    // Hide whenever the anchor selection moves OR becomes a non-text
+    // selection (e.g. user clicks an image or table node). Otherwise the
+    // tooltip would stay orphaned on screen with no valid range.
+    const isTextSelection = selection instanceof TextSelection
+    const movedRange =
+      selection.from !== this.#from || selection.to !== this.#to
+    if (!isTextSelection || movedRange) {
+      this.#wantsShow = false
+      this.#provider.hide()
+      return
+    }
+
+    // Forward to the provider so floating UI re-runs its position
+    // calculation against the current view (anchor coordinates can shift
+    // with layout/document changes even when from/to stay the same).
+    this.#provider.update(view, prevState)
+  }
+
+  destroy = () => {
+    this.#app.unmount()
+    this.#provider.destroy()
+    this.#content.remove()
+  }
+}

package/src/feature/ai/streaming-indicator.ts

@@ -0,0 +1,183 @@
+import type { Ctx } from '@milkdown/kit/ctx'
+import type { Node } from '@milkdown/kit/prose/model'
+
+import { commandsCtx } from '@milkdown/kit/core'
+import {
+  abortStreamingCmd,
+  streamingPluginKey,
+} from '@milkdown/kit/plugin/streaming'
+import { Plugin, PluginKey } from '@milkdown/kit/prose/state'
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view'
+import { $prose } from '@milkdown/kit/utils'
+
+import type { AIStreamingIndicatorConfig } from './types'
+
+import { abortAICmd, aiSessionCtx } from './commands'
+
+const CLASS_PREFIX = 'milkdown-ai-streaming'
+const SPINNER_PERIOD_MS = 800
+
+export const DEFAULT_STREAMING_FALLBACK_LABEL = 'Generating'
+export const DEFAULT_STREAMING_CANCEL_HINT = 'Esc to cancel'
+
+const indicatorKey = new PluginKey<DecorationSet>(
+  'CREPE_AI_STREAMING_INDICATOR'
+)
+
+/// One spinner per streaming session. The rotation is driven by
+/// requestAnimationFrame instead of CSS keyframes so that DOM moves
+/// (which happen every chunk as the indicator's position advances) do
+/// not reset the animation back to 0deg.
+class IndicatorWidget {
+  readonly dom: HTMLElement
+  readonly #spinner: HTMLElement
+  readonly #label: HTMLElement
+  readonly #fallbackLabel: string
+  readonly #start = performance.now()
+  #lastLabelText = ''
+  #rafId = 0
+
+  constructor(ctx: Ctx, fallbackLabel: string, cancelHint: string) {
+    this.#fallbackLabel = fallbackLabel
+
+    const dom = document.createElement('span')
+    dom.className = `${CLASS_PREFIX}-indicator`
+    dom.contentEditable = 'false'
+    // Treat the pill as a status live region so assistive technologies
+    // get notified when AI starts streaming and when the active-form
+    // label changes between sessions ("Improving writing…",
+    // "Translating to French…", etc.).
+    dom.setAttribute('role', 'status')
+    dom.setAttribute('aria-live', 'polite')
+
+    const spinner = document.createElement('span')
+    spinner.className = `${CLASS_PREFIX}-spinner`
+    // The decorative rotation has no semantic value for screen readers.
+    spinner.setAttribute('aria-hidden', 'true')
+    dom.appendChild(spinner)
+
+    const label = document.createElement('span')
+    label.className = `${CLASS_PREFIX}-label`
+    dom.appendChild(label)
+
+    const escHint = document.createElement('span')
+    escHint.className = `${CLASS_PREFIX}-esc`
+    escHint.textContent = cancelHint
+    dom.appendChild(escHint)
+
+    this.dom = dom
+    this.#spinner = spinner
+    this.#label = label
+    this.setLabel(ctx)
+    this.#tick()
+  }
+
+  setLabel(ctx: Ctx) {
+    const session = ctx.get(aiSessionCtx.key)
+    const text = `${session.label || this.#fallbackLabel}…`
+    if (text === this.#lastLabelText) return
+    this.#lastLabelText = text
+    this.#label.textContent = text
+  }
+
+  destroy() {
+    if (this.#rafId) cancelAnimationFrame(this.#rafId)
+    this.#rafId = 0
+  }
+
+  #tick = () => {
+    const elapsed = performance.now() - this.#start
+    const angle = (elapsed / SPINNER_PERIOD_MS) * 360
+    this.#spinner.style.transform = `rotate(${angle}deg)`
+    this.#rafId = requestAnimationFrame(this.#tick)
+  }
+}
+
+interface StreamingIndicatorPluginOptions {
+  config?: AIStreamingIndicatorConfig
+}
+
+export function streamingIndicatorPlugin(
+  options: StreamingIndicatorPluginOptions = {}
+) {
+  const { config } = options
+  const fallbackLabel =
+    config?.fallbackLabel ?? DEFAULT_STREAMING_FALLBACK_LABEL
+  const cancelHint = config?.cancelHint ?? DEFAULT_STREAMING_CANCEL_HINT
+
+  return $prose((ctx) => {
+    let widget: IndicatorWidget | null = null
+
+    function ensureWidget(): IndicatorWidget {
+      if (!widget) widget = new IndicatorWidget(ctx, fallbackLabel, cancelHint)
+      else widget.setLabel(ctx)
+      return widget
+    }
+
+    function dropWidget(): void {
+      if (widget) {
+        widget.destroy()
+        widget = null
+      }
+    }
+
+    function buildSet(doc: Node, insertEndPos: number): DecorationSet {
+      const pos = Math.min(insertEndPos, doc.content.size)
+      const decoration = Decoration.widget(pos, ensureWidget().dom, {
+        side: 1,
+        key: 'ai-streaming-indicator',
+      })
+      return DecorationSet.create(doc, [decoration])
+    }
+
+    return new Plugin<DecorationSet>({
+      key: indicatorKey,
+      state: {
+        init: () => DecorationSet.empty,
+        apply(tr, decorations, _oldState, newState) {
+          const streaming = streamingPluginKey.getState(newState)
+          if (!streaming?.active || streaming.insertEndPos == null) {
+            dropWidget()
+            return DecorationSet.empty
+          }
+          if (tr.getMeta(streamingPluginKey) || tr.docChanged) {
+            return buildSet(newState.doc, streaming.insertEndPos)
+          }
+          return decorations.map(tr.mapping, tr.doc)
+        },
+      },
+      view() {
+        return {
+          destroy() {
+            dropWidget()
+          },
+        }
+      },
+      props: {
+        decorations(state) {
+          return indicatorKey.getState(state) ?? DecorationSet.empty
+        },
+        handleKeyDown(view, event) {
+          if (event.key !== 'Escape') return false
+          const commands = ctx.get(commandsCtx)
+          // AI-driven session: route through abortAICmd so the AI
+          // session state (abortController, label) cleans up too.
+          if (ctx.get(aiSessionCtx.key).abortController) {
+            event.preventDefault()
+            commands.call(abortAICmd.key, { keep: true })
+            return true
+          }
+          // Manual streaming session (no AI session in flight) — abort
+          // the streaming plugin directly so the "Esc to cancel" hint
+          // shown in the pill isn't misleading.
+          if (streamingPluginKey.getState(view.state)?.active) {
+            event.preventDefault()
+            commands.call(abortStreamingCmd.key, { keep: true })
+            return true
+          }
+          return false
+        },
+      },
+    })
+  })
+}