@oix1987/yjd 2.1.2 → 2.2.0

package/index.d.ts

@@ -76,6 +76,84 @@ export interface SubmitOptions {
   newlineOnShiftEnter?: boolean;
 }
 
+/** Context passed to the AI `complete` hook for one request. */
+export interface AiContext {
+  /** Action id ('improve', 'fix', 'ask', 'autocomplete', or a custom id). */
+  action: string;
+  /** Instruction for the action (the action's prompt, or the user's question). */
+  prompt: string;
+  /** The selected text (or, for autocomplete, the preceding context). */
+  text: string;
+  /** The selected HTML, when available. */
+  html: string;
+  /** Aborts when the request is superseded or cancelled. */
+  signal: AbortSignal;
+}
+
+/** A selection-toolbar action. */
+export interface AiAction {
+  id: string;
+  label: string;
+  /** Instruction handed to the `complete` hook as `prompt`. */
+  prompt: string;
+}
+
+/** Inline ghost-text autocomplete tuning. */
+export interface AiAutocompleteOptions {
+  /** Idle delay before requesting a suggestion (ms, default 400). */
+  debounce?: number;
+  /** Minimum context length before suggesting (default 3). */
+  minChars?: number;
+  /** Max characters of preceding text sent as context (default 600). */
+  maxContext?: number;
+}
+
+/**
+ * AI configuration. Inert until a `complete` hook is given (BYO-model, like
+ * `mention.source`). Enables a selection toolbar (improve/fix/shorten/…/Ask AI)
+ * with accept-or-discard, and optional ghost-text autocomplete.
+ */
+export interface AiOptions {
+  /**
+   * Call your LLM and resolve to the generated text. Stream by invoking
+   * `onToken` with each chunk; if you only stream, return undefined and the
+   * chunks are joined.
+   */
+  complete: (ctx: AiContext, onToken: (chunk: string) => void) => string | void | Promise<string | void>;
+  /** Replace/extend the selection-toolbar actions. */
+  actions?: AiAction[];
+  /** Inline ghost-text autocomplete (Tab to accept). */
+  autocomplete?: boolean | AiAutocompleteOptions;
+}
+
+/** Streaming sink returned by editor.streamInto(). */
+export interface StreamSink {
+  /** Append a chunk at the caret (first append replaces the selection). */
+  append(chunk: string): void;
+  /** Finish the stream. */
+  commit(): void;
+  /** Undo the whole streamed insertion. */
+  cancel(): void;
+}
+
+/** A snapshot of the current selection (the context an AI/tool acts on). */
+export interface SelectionSnapshot {
+  text: string;
+  html: string;
+  isEmpty: boolean;
+  range: Range;
+}
+
+/** The AI module instance, exposed as `editor.ai` when configured. */
+export interface AiController {
+  /** Run a built-in/custom action or a free-form prompt on the selection. */
+  run(action: AiAction | string, opts?: { text?: string; html?: string }): Promise<string>;
+  /** Open the assistant bar (selection actions, or Ask-AI at the caret). */
+  openFromToolbar(): void;
+  /** Manually trigger a ghost-text completion at the caret. */
+  autocomplete(): void;
+}
+
 /**
  * Toolbar configuration: a built-in preset, an exclusion of default items,
  * a flat item list (single group), or full custom groups via toolbar1/toolbar2.
@@ -126,6 +204,8 @@ export interface EditorOptions {
   mention?: MentionOptions;
   /** Enter-to-submit behaviour for comment-style editors. */
   submit?: SubmitOptions;
+  /** AI assistant (selection toolbar + ghost-text). Inert until `complete` is set. */
+  ai?: AiOptions;
   /** Built-in preset / exclusion / flat list, instead of toolbar1/toolbar2. */
   toolbar?: ToolbarOption;
   /** Warn (emit 'content:overflow') when serialized HTML exceeds this many chars. */
@@ -159,6 +239,8 @@ export class Editor {
   ): TextareaEditor;
   /** The contentEditable element (public — apps may attach listeners to it). */
   editor: HTMLElement;
+  /** The AI module, present when `ai.complete` was configured. */
+  ai?: AiController;
   on(event: string, handler: (data: any) => void): void;
   /** Remove a previously-added listener (symmetric with on()). */
   off(event: string, handler: (data: any) => void): void;
@@ -179,6 +261,12 @@ export class Editor {
   clear(): void;
   insertText(text: string): void;
   insertHTML(html: string): void;
+  /** Snapshot of the current selection (null when outside the editor). */
+  getSelection(): SelectionSnapshot | null;
+  /** Replace the current selection with content (sanitized, undo-aware). */
+  replaceSelection(content: string, opts?: { asText?: boolean }): void;
+  /** Open a streaming sink at the caret for token-by-token AI output. */
+  streamInto(): StreamSink;
   clearFormatting(): void;
   insertHorizontalRule(): void;
   insertImageFile(file: File): void;
@@ -281,6 +369,7 @@ export const CodeView: any;
 export const FindReplace: any;
 export const SlashMenu: any;
 export const Mention: any;
+export const Ai: any;
 export const ResizeHandles: any;
 
 // UI components

package/index.js

@@ -41,6 +41,7 @@ import CodeView from './lib/modules/code-view.js';
 import FindReplace from './lib/modules/find-replace.js';
 import SlashMenu from './lib/modules/slash-menu.js';
 import Mention from './lib/modules/mention.js';
+import Ai from './lib/modules/ai.js';
 
 import ResizeHandles from './lib/modules/resize-handles.js';
 
@@ -97,6 +98,7 @@ registry.register('modules/code-view', CodeView, true);
 registry.register('modules/find-replace', FindReplace, true);
 registry.register('modules/slash-menu', SlashMenu, true);
 registry.register('modules/mention', Mention, true);
+registry.register('modules/ai', Ai, true);
 
 registry.register('modules/resize-handles', ResizeHandles, true);
 
@@ -206,6 +208,7 @@ export {
   FindReplace,
   SlashMenu,
   Mention,
+  Ai,
 
   ResizeHandles
 };

package/lib/core/editor.js

@@ -264,6 +264,12 @@ export default class Editor {
       modulesToLoad.push('mention');
     }
 
+    // The AI module is inert without an `ai.complete` hook, so it is never in
+    // the default set — load it only when the app configures one.
+    if (this.options.ai && !modulesToLoad.includes('ai')) {
+      modulesToLoad.push('ai');
+    }
+
     
     modulesToLoad.forEach(moduleName => {
       const ModuleClass = this.registry.get(`modules/${moduleName}`);
@@ -941,6 +947,86 @@ export default class Editor {
     this.onContentChange();
   }
 
+  /**
+   * Snapshot of the current selection — the context an AI action (or any tool)
+   * needs to operate on what the user picked. Returns null when the selection
+   * is outside this editor.
+   * @returns {{text:string, html:string, isEmpty:boolean, range:Range}|null}
+   */
+  getSelection() {
+    const sel = window.getSelection();
+    if (!sel || !sel.rangeCount) return null;
+    const range = sel.getRangeAt(0);
+    if (!this.editor.contains(range.commonAncestorContainer)) return null;
+    const holder = document.createElement('div');
+    holder.appendChild(range.cloneContents());
+    return {
+      text: range.toString(),
+      html: holder.innerHTML,
+      isEmpty: range.collapsed,
+      // A detached clone, so the snapshot doesn't mutate as the caret moves.
+      range: range.cloneRange(),
+    };
+  }
+
+  /**
+   * Replace the current selection with new content (sanitized, undo-aware). The
+   * write path for AI rewrites and any "replace what I selected" tool. With a
+   * collapsed selection it inserts at the caret.
+   * @param {string} content
+   * @param {{asText?: boolean}} [opts] - insert as plain text instead of HTML
+   */
+  replaceSelection(content, opts = {}) {
+    if (typeof content !== 'string') return;
+    const history = this.getModule('history');
+    if (history && typeof history.saveBeforeFormat === 'function') history.saveBeforeFormat();
+    this.focus();
+    if (opts.asText) {
+      execFormat('insertText', content);
+    } else {
+      execFormat('insertHTML', sanitizeHtml(content));
+    }
+    this.onContentChange();
+  }
+
+  /**
+   * Open a streaming sink at the current caret/selection so an AI response can
+   * be written token-by-token. The first append replaces the selection; later
+   * appends extend it. Designed for the "watch it type" UX.
+   *
+   *   const s = editor.streamInto();
+   *   for await (const chunk of res) s.append(chunk);
+   *   s.commit();            // or s.cancel() to undo the whole stream
+   *
+   * @returns {{append(t:string):void, commit():void, cancel():void}}
+   */
+  streamInto() {
+    const history = this.getModule('history');
+    if (history && typeof history.saveBeforeFormat === 'function') history.saveBeforeFormat();
+    this.focus();
+    // Snapshot the pre-stream HTML so cancel() can restore it in one step —
+    // a stream produces several history entries, so a single undo() wouldn't
+    // roll back the whole thing.
+    const snapshot = this.editor.innerHTML;
+    let inserted = '';
+    const append = (chunk) => {
+      if (typeof chunk !== 'string' || chunk === '') return;
+      execFormat('insertText', chunk);
+      inserted += chunk;
+      this.onContentChange();
+    };
+    return {
+      append,
+      commit: () => { this.onContentChange(); },
+      cancel: () => {
+        if (inserted) {
+          this.editor.innerHTML = snapshot;
+          this.onContentChange();
+        }
+      },
+    };
+  }
+
   /**
    * Handle a paste event: sanitize pasted HTML, or paste as plain text.
    * @param {ClipboardEvent} e
@@ -1471,6 +1557,9 @@ export default class Editor {
     if (m && m.isOpen) return true;
     const s = this.modules.get('slash-menu');
     if (s && s.isOpen) return true;
+    // Note: the AI selection bar is intentionally NOT treated as an open menu —
+    // it doesn't capture Enter, so suppressing submit would only insert a stray
+    // newline. Enter-to-submit stays available while the bar floats.
     // Any visible portaled popup (emoji, link, image, table…).
     const sel = '.yjd-mention-menu, .yjd-slash-menu, .emoji-picker-popup.visible, .link-popup, .image-popup, .video-popup, .tag-popup';
     return [...document.querySelectorAll(sel)].some((el) => {
@@ -1661,7 +1750,7 @@ export default class Editor {
     this.emit('toolbar-click', data);
     
     // Commands that should always work regardless of selection location
-    const alwaysAllowedCommands = ['more', 'undo', 'redo', 'code-view', 'theme', 'text-direction', 'find'];
+    const alwaysAllowedCommands = ['more', 'undo', 'redo', 'code-view', 'theme', 'text-direction', 'find', 'ai'];
 
     if (alwaysAllowedCommands.includes(command)) {
       // These commands can execute regardless of selection location
@@ -1685,6 +1774,11 @@ export default class Editor {
         case 'find':
           // Find/replace module listens to 'toolbar-click' and opens its panel
           return;
+        case 'ai': {
+          const aiMod = this.getModule('ai');
+          if (aiMod && typeof aiMod.openFromToolbar === 'function') aiMod.openFromToolbar();
+          return;
+        }
       }
     }