markdown-text-editor 1.6.0 → 1.8.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "markdown-text-editor",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "type": "module",
-  "description": "Lightweight Markdown editor with hybrid WYSIWYG mode, real-time preview, and zero-config setup. Works with any backend via native textarea.",
+  "description": "A markdown editor that enhances your textarea instead of replacing it, so form submission, validation and required fields keep working. WYSIWYG hybrid mode, live preview, find and replace, RTL, TypeScript types. Works with any backend.",
   "funding": "https://ko-fi.com/nezanuha",
   "main": "./dist/markdown-text-editor.umd.js",
   "module": "./dist/markdown-text-editor.es.js",
@@ -11,6 +11,7 @@
   "jsdelivr": "./dist/markdown-text-editor.min.js",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./dist/markdown-text-editor.es.js",
       "require": "./dist/markdown-text-editor.umd.js",
       "default": "./dist/markdown-text-editor.umd.js"
@@ -18,6 +19,7 @@
   },
   "files": [
     "dist/",
+    "types/",
     "README.md",
     "LICENSE"
   ],
@@ -30,7 +32,9 @@
     "build": "vite build",
     "preview": "vite preview",
     "prepublishOnly": "npm run build",
-    "postversion": "git push origin main --tags"
+    "postversion": "git push origin main --tags",
+    "test": "node test/smoke.mjs",
+    "typecheck": "tsc --noEmit --strict --lib es2020,dom --moduleResolution bundler --module esnext test/types.test.ts"
   },
   "publishConfig": {
     "provenance": true,
@@ -56,7 +60,12 @@
     "csp compatible",
     "form markdown editor",
     "live preview",
-    "mde"
+    "mde",
+    "typescript",
+    "markdown-it",
+    "template editor",
+    "merge tags",
+    "placeholders"
   ],
   "author": "Nezanuha",
   "license": "MIT",
@@ -65,18 +74,21 @@
     "url": "https://github.com/nezanuha/markdown-text-editor/issues"
   },
   "dependencies": {
-    "dompurify": "^3.4.14",
-    "marked": "~18.0.11"
+    "dompurify": "^3.4.16",
+    "marked": "~18.0.14"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.3",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4.3.3",
     "diff": "^9.0.0",
-    "frutjam": "^2.2.5",
-    "postcss": "^8.5.26",
+    "frutjam": "^2.2.6",
+    "happy-dom": "^20.14.5",
+    "postcss": "^8.5.28",
     "tailwindcss": "^4.3.3",
-    "vite": "^8.2.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.1",
     "vite-plugin-css-injected-by-js": "^5.0.2"
-  }
+  },
+  "types": "./types/index.d.ts"
 }

package/types/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Type definitions for markdown-text-editor.
+ *
+ * Options are read once, when the editor is constructed. Changing them afterwards
+ * has no effect; call destroy() and construct a new editor instead.
+ */
+
+/** Tools that take no configuration, referenced by name in `toolbar`. */
+export type ToolName =
+    | 'heading'
+    | 'bold'
+    | 'italic'
+    | 'strikethrough'
+    | 'blockquote'
+    | 'ul'
+    | 'ol'
+    | 'checklist'
+    | 'indent'
+    | 'outdent'
+    | 'code'
+    | 'codeblock'
+    | 'hr'
+    | 'table'
+    | 'link'
+    | 'image'
+    | 'undo'
+    | 'redo'
+    | 'preview';
+
+/** A single entry in the variables dropdown. */
+export interface Variable {
+    /** Text shown in the dropdown. Rendered as plain text, never as markup. */
+    label: string;
+    /** Inserted at the cursor when the entry is clicked. */
+    value: string;
+    /**
+     * Shown in place of `value` in the preview. The textarea keeps the real
+     * placeholder. Entries without a sample appear as written.
+     */
+    sample?: string;
+}
+
+/** A headed section of variables. Groups and flat entries can be mixed. */
+export interface VariableGroup {
+    /** Heading shown above the group. Not clickable. */
+    label: string;
+    items: Variable[];
+}
+
+/** Toolbar entries that carry their own configuration. */
+export interface VariablesTool {
+    variables: Array<Variable | VariableGroup>;
+}
+
+export interface ImageTool {
+    image: {
+        fileInput?: {
+            /** Allowed extensions, e.g. `['webp', 'avif', 'png']`. */
+            accept?: string[];
+            /** Endpoint the `File` is POSTed to. */
+            uploadUrl?: string;
+        };
+        /** `false` disables alt text validation. */
+        altInput?: boolean | { required?: boolean };
+    };
+}
+
+export type ToolbarEntry = ToolName | VariablesTool | ImageTool;
+
+/** Status bar fields. `false` hides the bar entirely. */
+export interface FooterOptions {
+    /** Default `true`. */
+    line?: boolean;
+    /** Default `true`. */
+    col?: boolean;
+    /** Default `true`. */
+    chars?: boolean;
+    /** Default `false`. */
+    words?: boolean;
+}
+
+export interface MarkdownEditorOptions {
+    /**
+     * `'hybrid'` renders formatting live as you type, `'plain'` shows raw
+     * markdown. Default `'plain'`.
+     */
+    mode?: 'plain' | 'hybrid';
+
+    /** Text shown when the editor is empty. */
+    placeholder?: string;
+
+    /**
+     * Which tools appear and in what order. Omit for the default toolbar.
+     * Note that `preview` must be present for the preview pane to exist.
+     */
+    toolbar?: ToolbarEntry[];
+
+    /** Status bar configuration, or `false` to hide it. */
+    footer?: false | FooterOptions;
+
+    /**
+     * Overrides the theme. Without it the editor inherits `data-theme` from the
+     * nearest ancestor, or from the textarea itself.
+     */
+    theme?: 'light' | 'dark' | 'snowberry' | 'darkberry' | (string & {});
+
+    /** Minimum height in pixels. Default `200`. */
+    minHeight?: number;
+
+    /** Maximum height in pixels before the editor scrolls. Default `500`. */
+    maxHeight?: number;
+
+    /** Called on every content change with the current markdown. */
+    onChange?: (value: string) => void;
+
+    /**
+     * Translations for the editor's own interface, keyed by the English text:
+     * tooltips, menu items, modal fields and buttons. Anything not listed stays
+     * in English. CSS class names are unaffected.
+     *
+     * @example labels: { Bold: 'Negrita', 'Insert variable': 'Insertar variable' }
+     */
+    labels?: Record<string, string>;
+
+    /**
+     * Replaces the markdown parser used for the preview. Must be synchronous and
+     * return an HTML string. Affects the preview pane only; hybrid mode's live
+     * formatting uses a separate internal renderer.
+     *
+     * Clickable task list checkboxes are found by looking for
+     * `input[type="checkbox"]` in the output, so a renderer without task list
+     * support will break them.
+     *
+     * @example renderer: markdown => markdownIt.render(markdown)
+     */
+    renderer?: (markdown: string) => string;
+
+    /**
+     * Replaces the HTML sanitizer. Must be synchronous and return an HTML string.
+     * Defaults to DOMPurify, which still runs when only `renderer` is given.
+     *
+     * Replacing this replaces your XSS protection. A pass-through such as
+     * `html => html` disables sanitizing entirely.
+     *
+     * @example sanitizer: html => DOMPurify.sanitize(html, { ADD_TAGS: ['iframe'] })
+     */
+    sanitizer?: (html: string) => string;
+}
+
+export default class MarkdownEditor {
+    /**
+     * @param selector A CSS selector for a `<textarea>`, or the element itself.
+     */
+    constructor(selector: string | HTMLTextAreaElement, options?: MarkdownEditorOptions);
+
+    /** The original textarea. Its `.value` is always the current markdown. */
+    readonly usertextarea: HTMLTextAreaElement;
+
+    /** The wrapper the editor builds around the textarea. */
+    readonly editorContainer: HTMLDivElement;
+
+    /** Options exactly as passed in. */
+    readonly options: MarkdownEditorOptions;
+
+    /** Variables parsed out of the toolbar configuration. */
+    readonly variables: Array<Variable | VariableGroup>;
+
+    /**
+     * Inserts text at the cursor, replacing any selection, then restores focus,
+     * scrolls the insertion into view, re-renders and fires `onChange`.
+     *
+     * @param selectionOffset Where the caret lands, measured from the insertion point.
+     * @param trailingLength Characters at the end to leave outside the selection.
+     */
+    insertText(text: string, selectionOffset?: number, trailingLength?: number): void;
+
+    /** Re-renders the preview and the hybrid display layer from the textarea. */
+    render(): void;
+
+    /**
+     * Removes the editor UI, restores the original textarea and detaches every
+     * listener. Call this on unmount in single page applications.
+     */
+    destroy(): void;
+}