@oix1987/yjd 2.0.0 → 2.1.1

package/index.d.ts

@@ -2,6 +2,100 @@
 // These declarations are the package entry types (referenced via "types" in package.json),
 // so they are declared at top level rather than wrapped in `declare module`.
 
+/** A person/task suggestion returned by a mention source. */
+export interface MentionItem {
+  id: string | number;
+  name?: string;
+  label?: string;
+  avatar_url?: string;
+  [key: string]: any;
+}
+
+/** Config for a single mention trigger character. */
+export interface MentionTrigger {
+  /** Trigger character, e.g. '#'. */
+  char: string;
+  /** Async (or sync) lookup of suggestions for the typed query. */
+  source: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  /** Custom HTML for a suggestion row. Defaults to avatar + name. */
+  renderItem?: (item: MentionItem) => string;
+}
+
+/** @mention configuration. The token inserted carries `data-id`. */
+export interface MentionOptions {
+  /** Primary trigger character (default '@'). */
+  trigger?: string;
+  source?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  renderItem?: (item: MentionItem) => string;
+  /** Additional triggers, e.g. '#' for task references. */
+  triggers?: MentionTrigger[];
+}
+
+/** Image upload hook configuration. */
+export interface ImageOptions {
+  /**
+   * Upload the chosen file and resolve to its URL. While pending, a placeholder
+   * is shown; on resolve the src is swapped, on reject the image is removed.
+   * Omit to fall back to inline base64 (data URLs).
+   */
+  upload?: (file: File) => string | Promise<string>;
+  /** `accept` attribute for the file picker (default 'image/*'). */
+  accept?: string;
+  /** Maximum file size in bytes; larger files emit 'image:error'. */
+  maxSize?: number;
+}
+
+/** Result of a file.upload hook — a URL, or richer metadata. */
+export interface FileUploadResult {
+  url: string;
+  name?: string;
+  size?: string;
+}
+
+/** Attachment (non-image file) upload hook. Inserts a "file chip". */
+export interface FileOptions {
+  /**
+   * Upload the chosen file; resolve to a URL string or { url, name, size }.
+   * While pending a placeholder chip is shown. Omit to inline a data: URL.
+   */
+  upload?: (file: File) => string | FileUploadResult | Promise<string | FileUploadResult>;
+  /** `accept` attribute for the file picker (e.g. '.pdf,.zip,.docx'). */
+  accept?: string;
+  /** Maximum file size in bytes; larger files emit 'file:error'. */
+  maxSize?: number;
+}
+
+/** Enter-to-submit behaviour (e.g. a comment box). */
+export interface SubmitOptions {
+  /**
+   * Called when Enter is pressed and no autocomplete popup (mention/slash/emoji)
+   * is open. Receives the current HTML and the editor instance.
+   */
+  onEnter: (html: string, editor: Editor) => void;
+  /** Shift+Enter inserts a newline (default true). */
+  newlineOnShiftEnter?: boolean;
+}
+
+/**
+ * Toolbar configuration: a built-in preset, an exclusion of default items,
+ * a flat item list (single group), or full custom groups via toolbar1/toolbar2.
+ */
+export type ToolbarOption = 'full' | 'compact' | { exclude: string[] } | string[];
+
+/** A JSON document node produced by getJSON()/domToJson. */
+export interface JsonNode {
+  tag?: string;
+  text?: string;
+  attrs?: Record<string, string>;
+  content?: JsonNode[];
+}
+
+/** Root JSON document. */
+export interface JsonDoc {
+  type: 'doc';
+  content: JsonNode[];
+}
+
 // Editor options interface
 export interface EditorOptions {
   placeholder?: string;
@@ -24,6 +118,18 @@ export interface EditorOptions {
   markdown?: boolean;
   /** Autosave drafts to localStorage. true, or { key, debounce(ms) }. */
   autosave?: boolean | { key?: string; debounce?: number };
+  /** Image upload hook (replaces inline base64 when `upload` is provided). */
+  image?: ImageOptions | boolean;
+  /** Attachment (non-image file) upload hook → inserts a file chip. */
+  file?: FileOptions;
+  /** @mention / #task autocomplete. Inert until a `source` is given. */
+  mention?: MentionOptions;
+  /** Enter-to-submit behaviour for comment-style editors. */
+  submit?: SubmitOptions;
+  /** Built-in preset / exclusion / flat list, instead of toolbar1/toolbar2. */
+  toolbar?: ToolbarOption;
+  /** Warn (emit 'content:overflow') when serialized HTML exceeds this many chars. */
+  maxContentSize?: number;
   features?: {
     emoji?: boolean;
     image?: boolean;
@@ -43,11 +149,23 @@ export interface EditorOptions {
 
 export class Editor {
   constructor(selector: string | Element, options?: EditorOptions);
+  /** The contentEditable element (public — apps may attach listeners to it). */
+  editor: HTMLElement;
   on(event: string, handler: (data: any) => void): void;
+  /** Remove a previously-added listener (symmetric with on()). */
   off(event: string, handler: (data: any) => void): void;
   emit(event: string, data: any): void;
   getContent(): string;
   setContent(content: string): void;
+  /** Alias of getContent() / setContent(). */
+  getHTML(): string;
+  setHTML(html: string): void;
+  /** Export/import the document as a JSON tree. */
+  getJSON(): JsonDoc;
+  setJSON(json: JsonDoc | JsonNode[]): void;
+  /** Export/import the document as Markdown (mention ids preserved). */
+  getMarkdown(): string;
+  setMarkdown(markdown: string): void;
   getText(): string;
   isEmpty(): boolean;
   clear(): void;
@@ -56,6 +174,12 @@ export class Editor {
   clearFormatting(): void;
   insertHorizontalRule(): void;
   insertImageFile(file: File): void;
+  /** Insert a non-image File as a file chip (uses options.file.upload). */
+  insertFileAttachment(file: File): void;
+  /** Open the native picker for a file attachment. */
+  openFileAttachmentPicker(): void;
+  /** True when a mention/slash/emoji popup that captures Enter is open. */
+  isMenuOpen(): boolean;
   setReadOnly(readOnly: boolean): void;
   isReadOnly(): boolean;
   setDirection(dir: 'ltr' | 'rtl'): void;
@@ -76,10 +200,48 @@ 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).
+   */
+  static fromTextarea(
+    textarea: HTMLTextAreaElement | string,
+    options?: EditorOptions & { format?: 'html' | 'markdown' }
+  ): TextareaEditor;
+  /** The original textarea, when created via fromTextarea(). */
+  textarea?: HTMLTextAreaElement;
 }
 
+/** Editor returned by fromTextarea(), with a value controller. */
+export interface TextareaEditor extends RichEditor {
+  textarea: HTMLTextAreaElement;
+  /** Current content (HTML or Markdown per the `format` option). */
+  getValue(): string;
+  /** Replace the editor content (HTML or Markdown per `format`). */
+  setValue(value: string): void;
+  /** Remove the editor and restore the textarea with its last value. */
+  destroy(): void;
+}
+
+/** Brand-aligned alias of {@link RichEditor}. */
+export { RichEditor as yjd };
+
 export function createEditor(selector: string | Element, options?: EditorOptions): RichEditor;
 
+/**
+ * Render stored HTML into a read-only view that matches the editor's styling.
+ * Sanitizes the HTML and tags the host element with `.yjd-content`.
+ */
+export function renderStatic(html: string, target?: Element): Element;
+
+// Serialization helpers (also available on the editor as get/set methods)
+export function htmlToMarkdown(html: string): string;
+export function markdownToHtml(markdown: string): string;
+export function domToJson(html: string): JsonDoc;
+export function jsonToHtml(json: JsonDoc | JsonNode[]): string;
+
 // Formats
 export const Bold: any;
 export const Italic: any;
@@ -115,6 +277,7 @@ export const TableToolbar: any;
 export const CodeView: any;
 export const FindReplace: any;
 export const SlashMenu: any;
+export const Mention: any;
 export const ResizeHandles: any;
 
 // UI components

package/index.js

@@ -3,6 +3,8 @@ import registry from './lib/core/registry.js';
 import Module from './lib/core/module.js';
 import { Format, InlineFormat, BlockFormat } from './lib/core/format.js';
 import StylesLoader from './lib/styles-loader.js';
+import { renderStatic } from './lib/static.js';
+import { htmlToMarkdown, markdownToHtml, domToJson, jsonToHtml } from './lib/serialize.js';
 
 // Import formats
 import Bold from './lib/formats/bold.js';
@@ -38,6 +40,7 @@ import TableToolbar from './lib/modules/table-toolbar.js';
 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 ResizeHandles from './lib/modules/resize-handles.js';
 
@@ -93,6 +96,7 @@ registry.register('modules/table-toolbar', TableToolbar, true);
 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/resize-handles', ResizeHandles, true);
 
@@ -142,11 +146,109 @@ class RichEditor extends Editor {
   static create(selector, options = {}) {
     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;
+  }
 }
 
-// Export classes for extension
+// Export classes for extension. `yjd` is the brand-aligned name; `RichEditor`
+// is kept as an alias for backward compatibility.
 export {
   RichEditor as default,
+  RichEditor,
+  RichEditor as yjd,
   Editor,
   Module,
   Format,
@@ -194,6 +296,7 @@ export {
   CodeView,
   FindReplace,
   SlashMenu,
+  Mention,
 
   ResizeHandles
 };
@@ -214,6 +317,15 @@ export {
   createCustomButton
 };
 
+// Static rendering + serialization helpers
+export {
+  renderStatic,
+  htmlToMarkdown,
+  markdownToHtml,
+  domToJson,
+  jsonToHtml
+};
+