@oix1987/yjd 2.1.1 → 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. */
@@ -149,8 +229,18 @@ export interface EditorOptions {
 
 export class Editor {
   constructor(selector: string | Element, options?: EditorOptions);
+  /**
+   * Progressive-enhance a <textarea> into an editor with two-way sync + a
+   * controller (getValue/setValue/destroy). Available from `/core` too.
+   */
+  static fromTextarea(
+    textarea: HTMLTextAreaElement | string,
+    options?: EditorOptions & { format?: 'html' | 'markdown' }
+  ): 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;
@@ -171,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;
@@ -200,12 +296,7 @@ export class RichEditor extends Editor {
   static register(path: string, definition: any, suppressWarning?: boolean): void;
   static get(path: string): any;
   static create(selector: string | Element, options?: EditorOptions): RichEditor;
-  /**
-   * Progressive-enhance a <textarea> into an editor with TWO-WAY sync (editor
-   * edits update textarea.value + fire native events; writing textarea.value
-   * updates the editor). The returned editor also exposes a controller:
-   * getValue()/setValue()/destroy() (destroy restores the textarea).
-   */
+  /** Inherited from Editor (returns a fully-featured RichEditor). */
   static fromTextarea(
     textarea: HTMLTextAreaElement | string,
     options?: EditorOptions & { format?: 'html' | 'markdown' }
@@ -278,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);
 
@@ -147,100 +149,9 @@ class RichEditor extends Editor {
     return new RichEditor(selector, options);
   }
 
-  /**
-   * Progressive-enhance a <textarea>: hide it, mount an editor in its place,
-   * and keep the textarea's value in sync so existing form submits keep working.
-   *
-   *   const ed = RichEditor.fromTextarea(document.querySelector('#body'), {
-   *     // any editor option; `format` chooses how the textarea is read/written:
-   *     format: 'html' | 'markdown',  // default 'html'
-   *   });
-   *
-   * The textarea's current value seeds the editor (parsed as HTML or Markdown
-   * per `format`). Binding is TWO-WAY: editor edits update textarea.value (and
-   * fire native input/change events), and writing `textarea.value = …` from app
-   * code (e.g. resetting a form) updates the editor. The returned editor also
-   * carries a small controller:
-   *
-   *   const ed = RichEditor.fromTextarea('#body', { format: 'markdown' });
-   *   ed.setValue(md);   // load new content into the editor
-   *   ed.getValue();     // current content (html or markdown per `format`)
-   *   ed.destroy();      // remove the editor, restore the textarea + last value
-   *
-   * @param {HTMLTextAreaElement|string} textarea  Element or selector.
-   * @param {object} [options]  Editor options + optional `format`.
-   * @returns {RichEditor}
-   */
-  static fromTextarea(textarea, options = {}) {
-    const ta = typeof textarea === 'string' ? document.querySelector(textarea) : textarea;
-    if (!ta) throw new Error('RichEditor.fromTextarea: textarea not found');
-
-    const format = options.format === 'markdown' ? 'markdown' : 'html';
-    const read = (ed) => (format === 'markdown' ? ed.getMarkdown() : ed.getContent());
-    const write = (ed, v) => (format === 'markdown' ? ed.setMarkdown(v || '') : ed.setHTML(v || ''));
-
-    // Mount point right after the textarea; hide the original.
-    const mount = document.createElement('div');
-    ta.after(mount);
-    ta.style.display = 'none';
-    ta.setAttribute('aria-hidden', 'true');
-
-    // Take over textarea.value so app writes flow into the editor and reads
-    // reflect it. Keep the native descriptor to restore on destroy + to set the
-    // real value (for form submission) without re-triggering our setter.
-    const nativeDesc = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value');
-    let raw = ta.value || '';
-    let syncing = false; // guards editor→textarea writes from re-entering setValue
-
-    const initial = raw;
-    const editor = new RichEditor(mount, {
-      width: '100%',
-      ...options,
-      content: options.content != null ? options.content
-        : (format === 'markdown' ? markdownToHtml(initial) : initial),
-    });
-
-    Object.defineProperty(ta, 'value', {
-      configurable: true,
-      get() { return raw; },
-      set(v) {
-        raw = v == null ? '' : String(v);
-        nativeDesc.set.call(ta, raw);   // keep the real textarea value for submits
-        if (!syncing) write(editor, raw); // app write → update editor
-      },
-    });
-
-    // editor edit → push to textarea + fire native events for app bindings.
-    const onChange = () => {
-      const next = read(editor);
-      if (raw === next) return;
-      raw = next;
-      syncing = true;
-      nativeDesc.set.call(ta, next);
-      ta.dispatchEvent(new Event('input', { bubbles: true }));
-      ta.dispatchEvent(new Event('change', { bubbles: true }));
-      syncing = false;
-    };
-    editor.on('change', onChange);
-    onChange(); // normalise textarea to the editor's serialization up front.
-
-    // Controller surface on the editor instance.
-    editor.textarea = ta;
-    editor.getValue = () => read(editor);
-    editor.setValue = (v) => { write(editor, v); };
-    const baseDestroy = editor.destroy.bind(editor);
-    editor.destroy = () => {
-      const last = read(editor);
-      editor.off('change', onChange);
-      baseDestroy();
-      mount.remove();
-      delete ta.value; // restore the prototype's value accessor
-      nativeDesc.set.call(ta, last);
-      ta.style.display = '';
-      ta.removeAttribute('aria-hidden');
-    };
-    return editor;
-  }
+  // fromTextarea() is inherited from the base Editor (defined in core so it is
+  // also available from the tree-shakeable /core entry). RichEditor.fromTextarea
+  // therefore returns a fully-featured RichEditor (via `new this(...)`).
 }
 
 // Export classes for extension. `yjd` is the brand-aligned name; `RichEditor`
@@ -297,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
@@ -1090,6 +1176,84 @@ export default class Editor {
     return `${n >= 10 || i === 0 ? Math.round(n) : n.toFixed(1)} ${u[i]}`;
   }
 
+  /**
+   * Progressive-enhance a <textarea> into an editor with TWO-WAY sync, returning
+   * the editor with a controller (getValue/setValue/destroy). Defined on the
+   * base Editor so it is available from the tree-shakeable `/core` entry too
+   * (no need to pull the all-in-one build just for fromTextarea).
+   *
+   *   const ed = Editor.fromTextarea('#body', { format: 'markdown' });
+   *
+   * @param {HTMLTextAreaElement|string} textarea
+   * @param {object} [options]  Editor options + optional `format: 'html'|'markdown'`.
+   * @returns {Editor}
+   */
+  static fromTextarea(textarea, options = {}) {
+    const ta = typeof textarea === 'string' ? document.querySelector(textarea) : textarea;
+    if (!ta) throw new Error('Editor.fromTextarea: textarea not found');
+
+    const format = options.format === 'markdown' ? 'markdown' : 'html';
+    const read = (ed) => (format === 'markdown' ? ed.getMarkdown() : ed.getContent());
+    const writeVal = (ed, v) => (format === 'markdown' ? ed.setMarkdown(v || '') : ed.setHTML(v || ''));
+
+    const mount = document.createElement('div');
+    ta.after(mount);
+    ta.style.display = 'none';
+    ta.setAttribute('aria-hidden', 'true');
+
+    const nativeDesc = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value');
+    let raw = ta.value || '';
+    let syncing = false;
+
+    const initial = raw;
+    // `this` is the class fromTextarea was called on (Editor or a subclass).
+    const editor = new this(mount, {
+      width: '100%',
+      ...options,
+      content: options.content != null ? options.content
+        : (format === 'markdown' ? markdownToHtml(initial) : initial),
+    });
+
+    Object.defineProperty(ta, 'value', {
+      configurable: true,
+      get() { return raw; },
+      set(v) {
+        raw = v == null ? '' : String(v);
+        nativeDesc.set.call(ta, raw);
+        if (!syncing) writeVal(editor, raw);
+      },
+    });
+
+    const onChange = () => {
+      const next = read(editor);
+      if (raw === next) return;
+      raw = next;
+      syncing = true;
+      nativeDesc.set.call(ta, next);
+      ta.dispatchEvent(new Event('input', { bubbles: true }));
+      ta.dispatchEvent(new Event('change', { bubbles: true }));
+      syncing = false;
+    };
+    editor.on('change', onChange);
+    onChange();
+
+    editor.textarea = ta;
+    editor.getValue = () => read(editor);
+    editor.setValue = (v) => { writeVal(editor, v); };
+    const baseDestroy = editor.destroy.bind(editor);
+    editor.destroy = () => {
+      const last = read(editor);
+      editor.off('change', onChange);
+      baseDestroy();
+      mount.remove();
+      delete ta.value;
+      nativeDesc.set.call(ta, last);
+      ta.style.display = '';
+      ta.removeAttribute('aria-hidden');
+    };
+    return editor;
+  }
+
   /**
    * Open the native picker for a non-image attachment, then insert it as a
    * file chip via the options.file.upload hook.
@@ -1393,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) => {
@@ -1583,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
@@ -1607,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;
+        }
       }
     }