// Type definitions for @oix1987/yjd
// 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;
  /**
   * Custom token this trigger serializes to in getContent()/getMarkdown().
   * Defaults to `#[Name](id)`. Return e.g. `'#' + item.id` to store a bare id
   * with no regex post-processing.
   */
  serialize?: (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;
  /** Custom token for the primary trigger. Defaults to `@[Name](id)`. */
  serialize?: (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;
  /** Display cap for inserted images (px or any CSS length, e.g. '60vh'). */
  maxHeight?: number | string;
  /** Display cap for inserted images (px or any CSS length). */
  maxWidth?: number | string;
}

/** 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;
}

/** Video drop/insert config (inline <video> player, parallel to images). */
export interface VideoOptions {
  /**
   * Upload a video (dropped, pasted, picked in the toolbar popup, or attached
   * in the prompt tray) and resolve to its URL (string, or { url }). While
   * pending a placeholder is shown; on resolve an inline <video controls> is
   * inserted. Omit to inline a data: URL.
   */
  upload?: (file: File) => string | { url?: string } | Promise<string | { url?: string }>;
  /** Accepted video MIME types (default 'video/*'). */
  accept?: string;
  /** Maximum file size in bytes; larger files emit 'video:error'. */
  maxSize?: number;
  /**
   * Display cap for the inline player so a tall/portrait clip doesn't blow out
   * the frame (px or any CSS length, e.g. '60vh'). Defaults to 480px; the user
   * can still drag-resize larger. Sets `--rte-video-max-h`.
   */
  maxHeight?: number | string;
  /** Display width cap for the inline player (px or any CSS length). Sets `--rte-video-max-w`. */
  maxWidth?: number | string;
}

/** Cross-format media handling. */
export interface MediaOptions {
  /**
   * Opt-in: when content loads (constructor `content`, setContent/setMarkdown/
   * setJSON), re-upload any legacy `data:` `<img>`/`<video>` through the
   * matching upload hook (`video.upload`, falling back to `image.upload`) and
   * swap the src to the returned URL in place. Heals drafts saved during the
   * base64 era so they stop re-embedding megabytes on every save. Best-effort:
   * an element with no hook, or whose upload throws, is left untouched. Emits
   * `media:migrate` (start), `media:migrated` ({el, url}), and
   * `media:migrate-error` ({el, file, error}).
   */
  migrateDataUrls?: boolean;
}

/** 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. In the prompt
   * layout the send button uses this too. Prefer `onSubmit` for new code.
   */
  onEnter?: (html: string, editor: Editor) => void;
  /**
   * Preferred submit handler — fired by both Enter-to-send and the prompt
   * layout's send button. Receives the current HTML and the editor instance.
   * The prompt layout renders its Send button only when `onSubmit` (or
   * `onEnter`) is configured.
   */
  onSubmit?: (html: string, editor: Editor) => void;
  /** Shift+Enter inserts a newline (default true). */
  newlineOnShiftEnter?: boolean;
  /**
   * When Enter submits vs. inserts a newline (the send button always submits):
   * - 'auto' (default): submit on Enter, EXCEPT on a touch soft keyboard in the
   *   prompt layout, where Enter inserts a newline.
   * - 'always': Enter always submits (even on mobile).
   * - 'never': Enter is always a newline; only the send button submits.
   */
  enterToSend?: 'auto' | 'always' | 'never';
}

/** 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;
  /**
   * When accepting an AI edit of selected text, show an inline word-level diff
   * (green additions / struck-through removals) and let the user accept or
   * reject it word-by-word (click a word to toggle) before applying. On by
   * default; set `false` for the old replace-on-accept behaviour. Fires the
   * same `ai:accept` / `ai:discard` events.
   */
  diff?: boolean;
  /**
   * Tag AI-written content with `class="yjd-ai-mark" data-ai` so it can be shown
   * (editor.showAiMarks), read (getAiRanges) or stripped (stripAiMarks) later.
   * Off by default.
   */
  trackAuthorship?: boolean;
  /**
   * Auto-open the selection AI menu whenever text is selected. Off by default —
   * the selection shows the formatting bubble, whose "✦ AI" entry (and the
   * toolbar pill) opens this menu.
   */
  openOnSelect?: boolean;
}

/** 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, or full custom groups via toolbar1/toolbar2.
 *
 * The flat array is an **allow-list**: only the named controls render, and no
 * UI (pickers, popovers) is mounted for anything else.
 */
export type ToolbarOption =
  | 'full'
  | 'compact'
  /** Chat-style bottom bar: [ + add ] [ format tools ] [ send ]. Implied by layout:'prompt'. */
  | 'prompt'
  | { exclude?: string[]; /** false = never split into a "more" row; the toolbar wraps instead. */ overflow?: boolean }
  | string[];

/** An item in the prompt "+" add-menu: a built-in insert action or a custom entry. */
export type PromptAddItem =
  | 'image' | 'file' | 'video' | 'table' | 'separator'
  | { label: string; icon?: string; onSelect: (editor: Editor) => void };

/** Prompt/chat layout configuration (used with layout:'prompt'). */
export interface PromptOptions {
  /** A single item makes "+" do it directly (no popover) — the default is ['image'] (tap "+" to add an image). Two or more items open a popover menu. */
  add?: PromptAddItem[];
  /**
   * Format buttons next to "+" in the bottom bar. Default: ['bold', 'italic']
   * (basic, no popovers). `[]` removes them entirely. Preferred name; `tools`
   * is the historical alias (`format` wins when both are set).
   */
  format?: string[];
  /** Historical alias of `format`. */
  tools?: string[];
  /**
   * Skip the built-in image/file upload hook when an attachment is added; the
   * integrator uploads later (e.g. on submit) and writes src/url/meta/status
   * back onto the item from an 'attachment:add' handler.
   */
  deferUpload?: boolean;
  /**
   * Append tray attachments to the content passed to the submit handler:
   * - true: a default HTML tail (<img> / <a>) per attachment.
   * - function: a custom string per attachment (e.g. markdown `![](src)`).
   */
  serializeAttachments?: boolean | ((att: PromptAttachment) => string);
  /**
   * Show a live token/cost meter next to the send button (for AI prompt inputs).
   * `true` estimates ~chars/4. Customise the estimate, label, or cost.
   */
  tokens?: boolean | {
    /** Estimate tokens for the message text (default ~chars/4). */
    estimate?: (text: string) => number;
    /** Custom meter label from the token count. */
    label?: (tokens: number) => string;
    /** Show an estimated cost at this price per 1k tokens. */
    costPer1k?: number;
    /** Currency symbol for the cost (default '$'). */
    currency?: string;
  };
}

/** A prompt context chip (an @file / @selection / URL reference). */
export interface PromptContext {
  id: number;
  label: string;
  value?: any;
  meta: Record<string, any>;
}

/** One tray attachment, as returned by getAttachments() and the attachment events. */
export interface PromptAttachment {
  /** Stable id within this composer (correlate add/remove events). */
  id: number;
  kind: 'image' | 'video' | 'file';
  file: File;
  /** Uploaded URL when an upload hook ran, else the preview value (image data URL, or undefined). */
  src?: string;
  /** Upload state: 'done' when nothing to upload or resolved; 'pending' mid-upload; 'error' on failure. */
  status: 'pending' | 'done' | 'error';
  /** Integrator-supplied bag (empty by default); set it from an 'attachment:add' handler. */
  meta: Record<string, any>;
}

/** 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[];
}

/** A custom action button in the selection bubble (#74). */
export interface BubbleButton {
  id: string;
  /** Tooltip / aria-label. */
  title?: string;
  /** A registered icon name or a raw `<svg …>` string. */
  icon?: string;
  /** Text content when no icon is given (e.g. an emoji). */
  text?: string;
  /** Click handler; the selection is preserved (pointerdown is prevented). */
  onClick: (editor: RichEditor, selection: Selection) => void;
}

/** Selection bubble (block-toolbar module) options. */
export interface BlockToolbarOptions {
  /** Show on a non-collapsed selection (default true). */
  showOnSelection?: boolean;
  /** Show after Enter at the caret (default false). */
  showOnEnter?: boolean;
  /**
   * Input-like fields: show the bubble when the editor gains focus, anchored
   * at the caret; it follows a collapsed caret and hides on blur (default
   * false).
   */
  showOnFocus?: boolean;
  /** Built-in format names and/or custom action buttons. */
  buttons?: (string | BubbleButton)[];
  /**
   * The "⋮" overflow sheet: true = all entries (default), false = no sheet,
   * or an allow-list of 'highlight' | 'comment' | 'copy' | 'clear-format'.
   * The ⋮ toggle disappears when nothing remains.
   */
  sheet?: boolean | string[];
}

// Editor options interface
export interface EditorOptions {
  placeholder?: string;
  /**
   * Colour theme. 'inherit' (default) follows the nearest ancestor [data-theme]
   * (falling back to the light :root tokens); 'light' / 'dark' force a theme;
   * 'auto' follows the OS via prefers-color-scheme.
   */
  theme?: 'inherit' | 'light' | 'dark' | 'auto';
  /** Editor height in px, or 'auto' to grow with content (no max cap). */
  height?: number | 'auto';
  /** Explicit min/max height in px (override the height-derived defaults). */
  minHeight?: number;
  maxHeight?: number;
  /** Editor width. Default '100%' — fills the container (number = px). */
  width?: number | string;
  /** Width cap (default 1200). Applies on top of `width`. */
  maxWidth?: number | string;
  content?: string | null;
  /**
   * Focus the editor after mount (default: true). Set false for editors
   * rendered on page load — prevents scroll-jump and mobile keyboard pop.
   */
  autoFocus?: boolean;
  /** List feature config: restrict the list picker to these types. */
  list?: { types?: Array<'checklist' | 'bullet' | 'ordered' | 'roman' | 'alpha'> };
  onChange?: (content: string) => void;
  /** When true, paste always inserts plain text (default: false). */
  pasteAsPlainText?: boolean;
  /**
   * Plain-text mode for chat/prompt/comment hosts that store text (default
   * false). All formatting is off: no format UI (toolbar/prompt-bar buttons,
   * bubble), ⌘B/I/U/K are no-ops, markdown input rules and auto-linkify are
   * disabled, paste is forced plain. `getContent()`, `onChange` and the
   * `submit` handler deliver plain text (blocks newline-separated);
   * `setContent()` flattens any markup it is given. Mentions and the AI
   * module keep working — both round-trip plain text.
   */
  plainText?: boolean;
  /** Accessible label for the editable region (defaults to placeholder). */
  ariaLabel?: string;
  /** Maximum number of characters allowed. */
  maxLength?: number;
  /** Initial text direction. */
  direction?: 'ltr' | 'rtl';
  /** Enable markdown shortcuts (default: true). Set false to disable. */
  markdown?: boolean;
  /** Auto-convert a bare URL to a link on space/Enter (default: true). */
  linkify?: 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;
  /** Dropped-video handling (inline <video> player + optional upload hook). */
  video?: VideoOptions;
  /** @mention / #task autocomplete. Inert until a `source` is given. */
  mention?: MentionOptions;
  /**
   * Where toolbar popovers (link/image/video/tag/table/import/emoji/list/align
   * and the format dropdowns) are placed:
   *  - `'auto'` (default) — portal to `<body>` with `position: fixed` ONLY when a
   *    clipping or transforming ancestor sits between the editor and `<body>`
   *    (the case that clips/buries popovers in host apps); otherwise placed
   *    inside the editor as before.
   *  - `'fixed'` — always portal to `<body>` (immune to a host's
   *    overflow/transform/stacking; the tradeoff is it can overlay host chrome).
   *  - `'wrapper'` — legacy: always placed absolutely inside the editor.
   */
  popup?: 'auto' | 'fixed' | 'wrapper';
  /**
   * Localise the built-in UI strings (toolbar tooltips, popup titles/buttons,
   * add-menu labels, attachment chrome). Either a flat map of `key → string` or
   * a function `(key, englishFallback) => string`; anything missing (or a
   * nullish function return) keeps the English default. Keys are dot-namespaced,
   * e.g. `'toolbar.bold'`, `'popup.insertLink'`, `'apply'`, `'cancel'`,
   * `'uploading'`, `'addMenu.image'`, `'addMenu.head'`.
   */
  strings?: Record<string, string> | ((key: string, fallback: string) => string | null | undefined);
  /** Media handling that isn't tied to a single format (see MediaOptions). */
  media?: MediaOptions;
  /** 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;
  /**
   * Overall layout. 'default' (top toolbar) or 'prompt' — a chat-style pill with
   * the toolbar as a bottom action bar. layout:'prompt' also defaults to a prompt
   * bottom bar and height:'auto' unless you configure otherwise.
   */
  layout?: 'default' | 'prompt';
  /** Prompt/chat layout configuration (the "+" add-menu and its format tools). */
  prompt?: PromptOptions;
  /** Warn (emit 'content:overflow') when serialized HTML exceeds this many chars. */
  maxContentSize?: number;
  /**
   * One size for every UI glyph (toolbar, add-menu, attachment chips, popups).
   * Number → px, string passed verbatim. Sets the `--rte-icon-size` CSS token on
   * this editor (default 16px). Override globally at `:root` instead if you want
   * every editor to change.
   */
  iconSize?: number | string;
  /**
   * Override or add icons. Map of `{ name: '<svg …>' }` — match a built-in name
   * (e.g. 'bold', 'video', 'upload', 'close') to replace it, or use a new name
   * for a custom glyph. The icon registry is global (shared by every editor on
   * the page); see also the exported `registerIcons` and `RichEditor.registerIcons`.
   */
  icons?: Record<string, string>;
  /**
   * Right rail with Outline · Comments · Versions tabs (UI 2.0). `true` for
   * all three, or pick tabs: { tabs: ['outline','comments'] }. Off by default.
   */
  sidePanel?: boolean | { tabs?: Array<'outline' | 'comments' | 'versions'>; user?: { name: string } };
  features?: {
    emoji?: boolean;
    image?: boolean;
    table?: boolean;
    wordCount?: boolean;
    breadcrumb?: boolean;
  };
  toolbar1?: Array<{
    group: string;
    items: string[];
  }>;
  toolbar2?: Array<{
    group: string;
    items: string[];
  }>;
  /**
   * Explicit list of module names to load, overriding the default set
   * (e.g. ['toolbar', 'history']). Names resolve against the registry.
   */
  modules?: string[];
  /**
   * Selection bubble (block-toolbar module) configuration. The bubble floats
   * above the selection, may overhang short editors, and coexists with the
   * top toolbar.
   */
  'block-toolbar'?: BlockToolbarOptions;
  /**
   * Explicit list of format names to load, overriding the default set.
   * Names resolve against the registry.
   */
  formats?: string[];
}

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;
  /**
   * Register or override icons globally (shared by every editor on the page).
   * Map of `{ name: '<svg …>' }`; match a built-in name to replace it, or use a
   * new name for a custom glyph. Same as the exported `registerIcons`.
   */
  static registerIcons(icons: Record<string, string>): void;
  /** The contentEditable element (public — apps may attach listeners to it). */
  editor: HTMLElement;
  /** The AI module, present when `ai.complete` was configured. */
  ai?: AiController;
  /**
   * Subscribe to an editor event. Notable events:
   * - 'change' / 'text-change' (html), 'mention:select' (MentionItem)
   * - 'attachment:add' / 'attachment:remove' (PromptAttachment) — the payload is
   *   the live item; set src/url/meta/status on it for a deferred-upload model.
   */
  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;
  /**
   * Resolve a UI string through `options.strings`, falling back to the built-in
   * English `fallback`. The single lookup every localisable label goes through.
   */
  t(key: string, fallback: string): string;
  /**
   * Stream a Markdown response and render it as formatted HTML token-by-token,
   * partial-safe (an open **bold or code fence renders cleanly) — for showing an
   * LLM reply "typing" with real formatting. `commit()` finalizes; `cancel()`
   * undoes the whole stream. Requires the serialize methods (all-in-one build,
   * or `applySerializeMethods(Editor)`).
   */
  streamMarkdown(): StreamSink;
  getText(): string;
  /** Undo the last change (uses the history module, falls back to execCommand). */
  undo(): void;
  /** Redo the last undone change. */
  redo(): void;
  isEmpty(): boolean;
  clear(): void;
  insertText(text: string): void;
  insertHTML(html: string): void;
  /**
   * Prompt layout: attach a file as a chat-style thumbnail (not inserted into the
   * message text). kind defaults to 'image'. Opens the file picker.
   */
  promptAttach(kind?: 'image' | 'video' | 'file'): Promise<void>;
  /** Prompt layout: current attachments. Read them in your submit handler. */
  getAttachments(): PromptAttachment[];
  /** Empty the prompt attachment tray (text untouched). `clear()` does this too. */
  clearAttachments(): void;
  /** Add a context chip (@file / @selection / URL) to the prompt tray. */
  addContext(ctx: { label: string; value?: any; meta?: Record<string, any> }): Promise<number | undefined>;
  /** Prompt layout: current context chips. Read them in your submit handler. */
  getContext(): PromptContext[];
  /** Highlight AI-authored spans (needs ai.trackAuthorship). */
  showAiMarks(on?: boolean): this;
  /** AI-authored runs currently in the document: [{ text }]. */
  getAiRanges(): Array<{ text: string }>;
  /** Remove AI authorship marks (unwrap), leaving the text as normal content. */
  stripAiMarks(): this;
  /** 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;
  /** Insert an inline date chip at the caret (`data-date` carries the ISO date). */
  insertDateChip(date?: Date): void;
  /** Print the document via a hidden iframe styled with the read-view CSS. */
  printContent(): void;
  /** Download the document as a styled HTML file, or Markdown with `'md'`. */
  downloadContent(format?: 'html' | 'md'): void;
  /** Headings (H1–H3) in document order — needs the side-panel module. */
  getOutline(): Array<{ level: number; text: string; el: HTMLElement }>;
  /** Wrap the selection in a comment mark and store the thread. Returns the id. */
  addComment(body: string, author?: string): string | null;
  removeComment(id: string): void;
  /** Append a reply to a thread (design section 09). */
  addReply(id: string, body: string, author?: string): { author: string; body: string; time: number } | null;
  /** Resolve keeps the thread in the rail but clears the highlight. */
  resolveComment(id: string, by?: string): void;
  unresolveComment(id: string): void;
  /** Open the new-comment composer on the current selection (also ⌘⌥M). */
  openCommentComposer(): void;
  /** Open a thread's popover anchored at its mark (bottom sheet on touch). */
  openCommentThread(id: string): void;
  getComments(): Array<{ id: string; body: string; author: string; quote: string; time: number; replies: Array<{ author: string; body: string; time: number }>; resolved: boolean; resolvedBy?: string }>;
  setComments(list: Array<{ id: string; body: string; author: string; quote: string; time: number; replies?: Array<{ author: string; body: string; time: number }>; resolved?: boolean; resolvedBy?: string }>): void;
  /** Snapshot the current document into the Versions tab. */
  saveVersion(label?: string): { v: string; label: string; html: string; words: number; time: number };
  getVersions(): Array<{ v: string; label: string; html: string; words: number; time: number }>;
  setVersions(list: Array<{ v: string; label: string; html: string; words: number; time: number }>): void;
  insertImageFile(file: File): void;
  /** Insert a non-image File as a file chip (uses options.file.upload). */
  insertFileAttachment(file: File): void;
  /** Transient status toast (used by the unhandled-drop path). */
  showToast(message: string, opts?: { duration?: number }): HTMLElement;
  /** 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;
  /** Switch the colour theme at runtime. */
  setTheme(theme: 'inherit' | 'light' | 'dark' | 'auto'): this;
  /** Current theme option. */
  getTheme(): 'inherit' | 'light' | 'dark' | 'auto';
  setDirection(dir: 'ltr' | 'rtl'): void;
  getDirection(): 'ltr' | 'rtl';
  toggleDirection(): void;
  clearAutosave(): void;
  focus(): void;
  destroy(): void;
}

export class Module {}
export class Format {}
export class InlineFormat extends Format {}
export class BlockFormat extends Format {}
export const registry: any;

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;
  /** Inherited from Editor (returns a fully-featured RichEditor). */
  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;
export const Underline: any;
export const Strike: any;
export const Subscript: any;
export const Superscript: any;
export const Color: any;
export const Background: any;
export const Link: any;
export const Table: any;
export const Heading: any;
export const FontFamily: any;
export const LineHeight: any;
export const Capitalization: any;
export const TextAlign: any;
export const List: any;
export const Indent: any;
export const IndentIncrease: any;
export const IndentDecrease: any;
export const Emoji: any;
export const Image: any;
export const Video: any;
export const Tag: any;
export const TextSize: any;
export const Import: any;

// Modules
export const Toolbar: any;
export const History: any;
export const BlockToolbar: any;
export const TableToolbar: any;
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
export const ColorPicker: any;
export const IconUtils: any;
/**
 * Register or override icons globally (shared by every editor on the page).
 * Map of `{ name: '<svg …>' }`; match a built-in name (e.g. 'bold', 'video',
 * 'upload', 'close') to replace it, or use a new name for a custom glyph.
 */
export function registerIcons(icons: Record<string, string>): void;
export const LinkPopup: any;
export const TablePopup: any;
export const TextAlignPicker: any;
export const ListPicker: any;
export const EmojiPicker: any;
export const ImagePopup: any;
export const VideoPopup: any;
export const TagPopup: any;

export const createCustomButton: any;

export default RichEditor;