@synclineapi/mdx-editor 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RadhaHariharan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# @synclineapi/mdx-editor
+
+[![CI](https://github.com/RadhaHariharan/syncline-mdx-editor/actions/workflows/ci.yml/badge.svg)](https://github.com/RadhaHariharan/syncline-mdx-editor/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@synclineapi/mdx-editor.svg)](https://www.npmjs.com/package/@synclineapi/mdx-editor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)
+[![WCAG AA](https://img.shields.io/badge/Accessibility-WCAG%20AA-green.svg)](https://www.w3.org/TR/WCAG21/)
+
+A **framework-agnostic**, plugin-based MDX/Markdown editor with toolbar customization, live preview, and 33+ built-in features. Works with React, Vue, Angular, Next.js, Svelte, or plain JavaScript.
+
+## Quick Start
+
+```bash
+npm install @synclineapi/mdx-editor
+```
+
+### Vanilla JavaScript
+
+```html
+<div id="editor"></div>
+
+<script type="module">
+  import { createEditor } from '@synclineapi/mdx-editor';
+  import '@synclineapi/mdx-editor/style.css';
+
+  const editor = createEditor({
+    container: '#editor',
+    value: '# Hello World',
+    onChange: (markdown) => console.log('Content changed:', markdown),
+  });
+</script>
+```
+
+### Custom Plugin Selection
+
+```js
+import { SynclineMDXEditor, boldPlugin, italicPlugin, headingPlugin } from '@synclineapi/mdx-editor';
+import '@synclineapi/mdx-editor/style.css';
+
+const editor = new SynclineMDXEditor({
+  container: '#editor',
+  plugins: [headingPlugin(), boldPlugin(), italicPlugin()],
+  toolbar: [['heading', '|', 'bold', 'italic']],
+});
+```
+
+## Features (33+ Built-in Plugins)
+
+| Category | Plugins |
+|----------|---------|
+| **Formatting** | Heading (1–6), Bold, Italic, Strikethrough, Quote |
+| **Links & Media** | Link, Image, Image Background, Image Frame |
+| **Code** | Inline Code, Code Block (with syntax highlighting placeholder) |
+| **Lists** | Unordered List, Ordered List, Task List |
+| **Layout** | Table, Multi-Column (2–5), Tabs, Container |
+| **Components** | Accordion, Accordion Group, Card, Card Group, Steps |
+| **Callouts** | Admonition (Tip/Warning/Caution/Danger/Check/Info/Note), Tip (Good/Bad/Info) |
+| **Rich Content** | Highlight (8 colors), Emoji, Formula (inline/block via KaTeX), Tooltip, Copy Text |
+| **Embeds** | YouTube, Video file, GitHub Gist, Twitter/X, CodePen, CodeSandbox |
+| **Diagrams** | Mermaid (Flowchart, Sequence, Class, State, ER, Journey, Gantt) |
+| **Insert** | API Endpoint, Markdown Import, Code Snippet |
+
+## Architecture
+
+```
+@synclineapi/mdx-editor
+├── Core Engine (SynclineMDXEditor)
+│   ├── EventEmitter          – Pub/sub event system
+│   ├── PluginManager          – Plugin lifecycle
+│   ├── Toolbar                – Configurable toolbar renderer
+│   ├── Renderer               – Markdown/MDX → HTML engine
+│   └── History                – Undo/redo stack
+└── Plugins (33+)
+    └── Each exports: toolbarItems, shortcuts, renderers, parsers, styles
+```
+
+## Plugin API
+
+Create custom plugins:
+
+```ts
+import type { EditorPlugin } from '@synclineapi/mdx-editor';
+
+const myPlugin: EditorPlugin = {
+  name: 'my-custom-block',
+  toolbarItems: [{
+    id: 'myBlock',
+    label: 'My Block',
+    icon: '<svg>...</svg>',
+    tooltip: 'Insert my block',
+    action: ({ editor }) => {
+      editor.insertBlock('<MyBlock>\n  Content\n</MyBlock>');
+    },
+  }],
+  renderers: [{
+    name: 'myBlock',
+    pattern: /<MyBlock>([\s\S]*?)<\/MyBlock>/g,
+    render: (match) => {
+      const m = match.match(/<MyBlock>([\s\S]*?)<\/MyBlock>/);
+      return `<div class="my-block">${m?.[1] || ''}</div>`;
+    },
+  }],
+  shortcuts: [
+    { key: 'Ctrl+Shift+m', action: ({ editor }) => editor.insertBlock('<MyBlock>\n  Content\n</MyBlock>') },
+  ],
+  styles: `.my-block { border: 2px solid blue; padding: 16px; border-radius: 8px; }`,
+};
+```
+
+## Toolbar Customization
+
+### Flat toolbar
+
+```js
+createEditor({
+  container: '#editor',
+  toolbar: [['bold', 'italic', '|', 'heading', '|', 'link', 'image']],
+});
+```
+
+### Nested dropdowns
+
+```js
+createEditor({
+  container: '#editor',
+  toolbar: [[
+    'bold', 'italic', '|',
+    {
+      type: 'group',
+      label: 'Insert',
+      display: 'dropdown',
+      items: ['table', 'accordion', 'card', 'steps'],
+    },
+  ]],
+});
+```
+
+## Theming
+
+Override CSS custom properties:
+
+```css
+.smdx-editor {
+  --smdx-primary: #e11d48;
+  --smdx-bg: #0f172a;
+  --smdx-text: #e2e8f0;
+  --smdx-border: #334155;
+  --smdx-font-family: 'Inter', sans-serif;
+  --smdx-font-mono: 'JetBrains Mono', monospace;
+  --smdx-radius: 12px;
+}
+```
+
+Or pass theme via config:
+
+```js
+createEditor({
+  container: '#editor',
+  theme: {
+    '--smdx-primary': '#e11d48',
+    '--smdx-bg': '#0f172a',
+  },
+});
+```
+
+Add `.smdx-dark` class for dark mode:
+
+```js
+editor.getRoot().classList.add('smdx-dark');
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `container` | `HTMLElement \| string` | — | **Required.** The DOM element (or CSS selector) to mount the editor into. |
+| `value` | `string` | `''` | Initial markdown content. |
+| `onChange` | `(value: string) => void` | — | Callback invoked every time the content changes (user input, `setValue()`, undo/redo). |
+| `plugins` | `EditorPlugin[]` | all built-in plugins | Plugins to register. |
+| `toolbar` | `ToolbarConfig` | default toolbar | Toolbar layout. |
+| `theme` | `Record<string, string>` | — | CSS custom property overrides. |
+| `mode` | `'split' \| 'editor' \| 'preview'` | `'split'` | Initial editor mode. |
+| `placeholder` | `string` | — | Textarea placeholder text. |
+| `readOnly` | `boolean` | `false` | Make the editor read-only. |
+| `scrollSync` | `boolean` | `true` | Sync scroll position between editor and preview. |
+| `renderers` | `Record<string, RendererFn>` | — | Custom renderer overrides. |
+| `locale` | `Partial<EditorLocale>` | — | i18n overrides. |
+
+## API Reference
+
+```ts
+interface EditorAPI {
+  getValue(): string;
+  setValue(value: string): void;
+  insertText(text: string): void;
+  wrapSelection(prefix: string, suffix: string): void;
+  replaceSelection(text: string): void;
+  getSelection(): SelectionState;
+  insertBlock(template: string): void;
+  focus(): void;
+  renderPreview(): void;
+  getMode(): EditorMode;
+  setMode(mode: 'split' | 'editor' | 'preview'): void;
+  registerPlugin(plugin: EditorPlugin): void;
+  unregisterPlugin(name: string): void;
+  on(event: string, handler: Function): void;
+  off(event: string, handler: Function): void;
+  undo(): void;
+  redo(): void;
+  getWordCount(): number;
+  getLineCount(): number;
+  destroy(): void;
+}
+```
+
+## Events
+
+### `onChange` config callback (recommended)
+
+Pass `onChange` directly in the config for the simplest way to listen for content changes:
+
+```js
+const editor = createEditor({
+  container: '#editor',
+  onChange: (markdown) => {
+    console.log('Content changed:', markdown);
+  },
+});
+```
+
+### Event emitter
+
+For all events (including selection changes, mode changes, etc.) use the event emitter API:
+
+```js
+editor.on('change', (markdown) => console.log('Content changed:', markdown));
+editor.on('selection-change', (sel) => console.log('Selection:', sel));
+editor.on('mode-change', (mode) => console.log('Mode:', mode));
+editor.on('render', (html) => console.log('Preview rendered'));
+editor.on('toolbar-action', (id) => console.log('Toolbar clicked:', id));
+```
+
+## Development
+
+> **Note:** The GitHub repository for this package is **private** — the source code is not publicly visible. The package is freely installable from npm, but external contributions, forks, and pull requests are not accepted.
+>
+> To report a bug or request a feature, open an issue at the [GitHub Issues page](https://github.com/RadhaHariharan/syncline-mdx-editor/issues).
+>
+> ```bash
+> npm install @synclineapi/mdx-editor
+> ```
+
+Internal development commands (for maintainers only):
+
+```bash
+cd syncline-mdx-editor
+npm install
+npm run dev     # Start Vite dev server
+npm run build   # Build library for production
+```
+
+## Bundle Size
+
+Check the estimated npm publish size before publishing:
+
+```bash
+npm run build
+npm run size
+```
+
+The core bundle (with `mermaid`, `katex`, `highlight.js` externalised) targets **< 150 kB** for both ESM and UMD outputs.
+
+## Security
+
+All rendered Markdown/MDX HTML is sanitized via a built-in XSS sanitizer before DOM injection. Dangerous tags (`script`, `iframe`, `object`), event handler attributes (`onclick`, `onerror`, etc.), and `javascript:` protocol URLs are all stripped. See [SECURITY.md](./SECURITY.md) for the vulnerability disclosure policy.
+
+## Accessibility
+
+`@synclineapi/mdx-editor` targets **WCAG 2.1 AA** compliance:
+- All toolbar buttons have `aria-label` and `title` attributes
+- The editor textarea has `aria-label="Markdown editor"` and `aria-multiline="true"`
+- The preview pane has `role="region"`, `aria-label="Preview"`, and `aria-live="polite"`
+- Mode toggle buttons expose `aria-pressed` state
+- Toolbar dropdowns have `role="menu"` / `role="menuitem"`
+- A skip link is provided for keyboard users
+- All text meets WCAG AA color contrast ratios
+
+## Testing
+
+```bash
+npm run test             # Run all tests
+npm run test:watch       # Watch mode
+npm run test:coverage    # Coverage report (target: 80%+)
+npm run test:ui          # Visual test UI
+```
+
+## Peer Dependencies
+
+`mermaid`, `katex`, and `highlight.js` are optional peer dependencies. Install them only if you use those features:
+
+```bash
+npm install mermaid       # For Mermaid diagrams
+npm install katex         # For math formulas
+npm install highlight.js  # Included by default for syntax highlighting
+```
+
+## License
+
+MIT
+

package/dist/core/editor.d.ts

@@ -0,0 +1,61 @@
+import { EditorConfig, EditorAPI, EditorPlugin, EditorMode, SelectionState } from './types';
+export declare class SynclineMDXEditor implements EditorAPI {
+    private root;
+    private toolbarEl;
+    private editorPane;
+    private previewPane;
+    private textarea;
+    private previewContent;
+    private statusBar;
+    private events;
+    private pluginManager;
+    private toolbar;
+    private renderer;
+    private history;
+    private mode;
+    private config;
+    private renderTimer;
+    private historyTimer;
+    private _destroyed;
+    constructor(config: EditorConfig);
+    private init;
+    private buildDOM;
+    private registerPlugins;
+    private getDefaultToolbar;
+    private onInput;
+    private onKeyDown;
+    private matchShortcut;
+    private onSelectionChange;
+    private scheduleRender;
+    private updateStatusBar;
+    getValue(): string;
+    setValue(value: string): void;
+    insertText(text: string): void;
+    wrapSelection(prefix: string, suffix: string): void;
+    replaceSelection(text: string): void;
+    getSelection(): SelectionState;
+    setSelection(start: number, end: number): void;
+    insertBlock(template: string): void;
+    getTextarea(): HTMLTextAreaElement;
+    getPreview(): HTMLElement;
+    getRoot(): HTMLElement;
+    focus(): void;
+    renderPreview(): Promise<void>;
+    getMode(): EditorMode;
+    setMode(mode: EditorMode): void;
+    registerPlugin(plugin: EditorPlugin): void;
+    unregisterPlugin(name: string): void;
+    on(event: string, handler: (data?: unknown) => void): void;
+    off(event: string, handler: (data?: unknown) => void): void;
+    emit(event: string, data?: unknown): void;
+    destroy(): void;
+    undo(): void;
+    redo(): void;
+    getCurrentLine(): string;
+    getCurrentLineNumber(): number;
+    replaceCurrentLine(text: string): void;
+    insertAt(position: number, text: string): void;
+    getWordCount(): number;
+    getLineCount(): number;
+    private applyTheme;
+}

package/dist/core/events.d.ts

@@ -0,0 +1,8 @@
+import { EventHandler } from './types';
+export declare class EventEmitter {
+    private listeners;
+    on(event: string, handler: EventHandler): void;
+    off(event: string, handler: EventHandler): void;
+    emit(event: string, data?: unknown): void;
+    removeAllListeners(event?: string): void;
+}

package/dist/core/history.d.ts

@@ -0,0 +1,12 @@
+/** Simple undo/redo history stack */
+export declare class History {
+    private stack;
+    private pointer;
+    private maxSize;
+    constructor(maxSize?: number);
+    push(value: string): void;
+    undo(): string | undefined;
+    redo(): string | undefined;
+    current(): string | undefined;
+    clear(): void;
+}

package/dist/core/icons.d.ts

@@ -0,0 +1,2 @@
+/** Central SVG icon registry for toolbar buttons */
+export declare const icons: Record<string, string>;

package/dist/core/plugin-manager.d.ts

@@ -0,0 +1,24 @@
+import { EditorPlugin, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EditorAPI } from './types';
+import { EventEmitter } from './events';
+export declare class PluginManager {
+    private editorApi;
+    private plugins;
+    private toolbarItems;
+    private shortcuts;
+    private renderers;
+    private parsers;
+    private styleElements;
+    private events;
+    constructor(editorApi: EditorAPI, events: EventEmitter);
+    register(plugin: EditorPlugin): Promise<void>;
+    unregister(name: string): void;
+    getToolbarItem(id: string): ToolbarItemConfig | undefined;
+    getAllToolbarItems(): Map<string, ToolbarItemConfig>;
+    getShortcuts(): ShortcutConfig[];
+    getRenderers(): RendererConfig[];
+    getParsers(): ParserConfig[];
+    hasPlugin(name: string): boolean;
+    private createContext;
+    private injectStyles;
+    destroy(): void;
+}

package/dist/core/renderer.d.ts

@@ -0,0 +1,28 @@
+import { RendererConfig, ParserConfig } from './types';
+/**
+ * The Renderer transforms markdown+MDX source into preview HTML.
+ * It runs custom parsers first, then applies marked for standard markdown,
+ * then runs custom renderers for extended blocks.
+ */
+export declare class Renderer {
+    private renderers;
+    private parsers;
+    setRenderers(renderers: RendererConfig[]): void;
+    setParsers(parsers: ParserConfig[]): void;
+    render(source: string): Promise<string>;
+    private applyParsers;
+    private applyRenderers;
+    /**
+     * Lightweight built-in markdown renderer.
+     * Handles standard markdown without external deps.
+     */
+    private renderMarkdown;
+    private renderTables;
+    private parseTableRow;
+    private escapeHtml;
+    /**
+     * Validate MDX component tags — detect unclosed or mismatched tags.
+     * Only checks PascalCase tags (MDX components), not standard HTML.
+     */
+    private validateMdxTags;
+}

package/dist/core/sanitize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lightweight HTML sanitizer to prevent XSS.
+ * Strips dangerous tags (script, object, embed, style, base, form, input, link, meta)
+ * and dangerous attributes (on*, href=javascript:, src=javascript:, action, formaction).
+ * Iframes are allowed only when their src points to a known safe embed origin.
+ * Buttons are allowed (needed for code-block copy functionality); on* attributes are
+ * still stripped from them so no inline scripts can execute.
+ * Uses the browser's DOMParser for correctness, with a fallback regex pass for SSR/test environments.
+ */
+export declare function sanitizeHtml(html: string): string;

package/dist/core/toolbar.d.ts

@@ -0,0 +1,29 @@
+import { ToolbarConfig, EditorAPI } from './types';
+import { PluginManager } from './plugin-manager';
+import { EventEmitter } from './events';
+export declare class Toolbar {
+    private config;
+    private pluginManager;
+    private editorApi;
+    private events;
+    private el;
+    private activeDropdown;
+    private documentClickHandler;
+    constructor(config: ToolbarConfig, pluginManager: PluginManager, editorApi: EditorAPI, events: EventEmitter);
+    render(container: HTMLElement): HTMLElement;
+    private renderRow;
+    private renderDivider;
+    private renderItem;
+    private renderGroup;
+    private renderDropdownGroup;
+    private renderDropdownItem;
+    private renderSubmenu;
+    private createButton;
+    private createMenuButton;
+    private executeAction;
+    private getActionContext;
+    private toggleDropdown;
+    private closeDropdowns;
+    updateActiveStates(): void;
+    destroy(): void;
+}