@synclineapi/mdx-editor 0.1.2 → 1.0.1

package/dist/core/config/EditorConfig.d.ts

@@ -0,0 +1,5 @@
+import { EditorConfig } from '../types';
+export declare function resolveConfig(config: Partial<EditorConfig> & {
+    container: EditorConfig['container'];
+}): EditorConfig;
+export declare function validateConfig(config: EditorConfig): void;

package/dist/core/config/defaults.d.ts

@@ -0,0 +1,33 @@
+import { EditorConfig, EditorMode } from '../types';
+export declare const DEFAULT_MODE: EditorMode;
+export declare const DEFAULT_PLACEHOLDER = "Start writing markdown...";
+export declare const DEFAULT_PREVIEW_DELAY = 150;
+export declare const DEFAULT_FEATURES: {
+    readonly lineNumbers: false;
+    readonly wordCount: true;
+    readonly lineCount: true;
+    readonly modeSwitcher: true;
+    readonly statusBar: true;
+    readonly autoPreview: true;
+    readonly previewDelay: 150;
+    readonly spellcheck: false;
+    readonly autocomplete: false;
+    readonly dragAndDrop: true;
+    readonly pasteImages: false;
+    readonly keyboardShortcuts: true;
+    readonly autoSave: false;
+    readonly autoSaveKey: "smdx-autosave";
+    readonly autofocus: false;
+    readonly vimMode: false;
+    readonly history: {
+        readonly maxSize: 100;
+        readonly debounce: 300;
+    };
+};
+export declare const DEFAULT_LAYOUT: {
+    readonly splitterPosition: 50;
+    readonly minEditorWidth: 200;
+    readonly minPreviewWidth: 200;
+    readonly resizableSplitter: true;
+};
+export declare function resolveDefaults(config: Partial<EditorConfig>): EditorConfig;

package/dist/core/config/index.d.ts

@@ -0,0 +1,2 @@
+export { resolveConfig, validateConfig } from './EditorConfig';
+export { resolveDefaults, DEFAULT_MODE, DEFAULT_PLACEHOLDER, DEFAULT_FEATURES, DEFAULT_LAYOUT } from './defaults';

package/dist/core/dom/editor-pane.d.ts

@@ -0,0 +1,7 @@
+export interface EditorPaneElements {
+    pane: HTMLDivElement;
+    scrollWrapper: HTMLDivElement;
+    gutter: HTMLDivElement;
+    textarea: HTMLTextAreaElement;
+}
+export declare function createEditorPane(id: string): EditorPaneElements;

package/dist/core/dom/editor-root.d.ts

@@ -0,0 +1,8 @@
+export interface EditorRootElements {
+    root: HTMLDivElement;
+    skipLink: HTMLAnchorElement;
+    toolbarSlot: HTMLDivElement;
+    main: HTMLDivElement;
+    statusBarSlot: HTMLDivElement;
+}
+export declare function createEditorRoot(id: string): EditorRootElements;

package/dist/core/dom/index.d.ts

@@ -0,0 +1,11 @@
+export { createEditorRoot } from './editor-root';
+export type { EditorRootElements } from './editor-root';
+export { createEditorPane } from './editor-pane';
+export type { EditorPaneElements } from './editor-pane';
+export { createPreviewPane } from './preview-pane';
+export type { PreviewPaneElements } from './preview-pane';
+export { createToolbarDOM } from './toolbar-dom';
+export type { ToolbarDOMElements } from './toolbar-dom';
+export { createStatusBar } from './status-bar';
+export type { StatusBarConfig, StatusBarElements } from './status-bar';
+export { createSkipLink } from './skip-link';

package/dist/core/dom/preview-pane.d.ts

@@ -0,0 +1,5 @@
+export interface PreviewPaneElements {
+    pane: HTMLDivElement;
+    content: HTMLDivElement;
+}
+export declare function createPreviewPane(id: string): PreviewPaneElements;

package/dist/core/dom/skip-link.d.ts

@@ -0,0 +1 @@
+export declare function createSkipLink(targetId: string): HTMLAnchorElement;

package/dist/core/dom/status-bar.d.ts

@@ -0,0 +1,13 @@
+export interface StatusBarConfig {
+    showWordCount?: boolean;
+    showLineCount?: boolean;
+    showModeSwitcher?: boolean;
+}
+export interface StatusBarElements {
+    bar: HTMLDivElement;
+    wordCount: HTMLSpanElement;
+    lineCount: HTMLSpanElement;
+    charCount: HTMLSpanElement;
+    modeSwitcher: HTMLDivElement;
+}
+export declare function createStatusBar(config?: StatusBarConfig): StatusBarElements;

package/dist/core/dom/toolbar-dom.d.ts

@@ -0,0 +1,5 @@
+export interface ToolbarDOMElements {
+    container: HTMLDivElement;
+    toolbar: HTMLDivElement;
+}
+export declare function createToolbarDOM(): ToolbarDOMElements;

package/dist/core/editor.d.ts

@@ -1,33 +1,155 @@
-import { EditorConfig, EditorAPI, EditorPlugin, EditorMode, SelectionState } from './types';
+import { EditorConfig, EditorAPI, EditorPlugin, EditorMode, SelectionState, PluginTokenProvider } from './types';
+import { CompletionItem } from '@synclineapi/editor';
 export declare class SynclineMDXEditor implements EditorAPI {
     private root;
     private toolbarEl;
+    private toolbarLeft;
+    private modeArea;
+    /** Container div where SynclineEditor mounts its DOM. */
+    private editorHost;
+    /** Hidden textarea kept for getTextarea() API compatibility. */
+    private textarea;
     private editorPane;
     private previewPane;
-    private textarea;
     private previewContent;
     private statusBar;
+    private tocContainer;
+    private tocCollapsed;
+    private splitterController;
+    /** The SynclineEditor instance (from editor/ folder). */
+    private codeEditor;
+    /** Watches .smdx-dark class changes to swap the code-editor theme in real time. */
+    private themeObserver;
     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;
+    /**
+     * Returns true only when an explicit `smdx-dark` class is present on the
+     * editor root, a parent element, or the document/body.
+     * Deliberately ignores OS-level prefers-color-scheme so that the theme
+     * follows the toolbar toggle button, not the system setting.
+     */
+    private isDarkMode;
+    /**
+     * Apply the correct light/dark code-editor theme AND token colours.
+     * Called automatically whenever the `.smdx-dark` class changes on any
+     * ancestor element. Can also be called programmatically when the host app
+     * switches themes via means other than a CSS class toggle (e.g. data-theme
+     * attribute, CSS variable override, or a custom theme API).
+     */
+    syncCodeEditorTheme(): void;
+    /** Observe class / data-theme mutations on the root / document so we can
+     * swap code-editor themes live.
+     *
+     * Walks every ancestor from `this.root` up to `<html>` inclusive so that
+     * toggling `.smdx-dark` OR `data-theme` on ANY containing element is caught
+     * and forwarded to `syncCodeEditorTheme()`. This covers:
+     *   - CSS class toggles  (.smdx-dark on root, body, or html)
+     *   - data-theme attribute patterns  (Next.js, Nuxt, Tailwind dark-mode)
+     *   - app-shell / modal wrapper patterns
+     */
+    private setupThemeObserver;
+    /** Completions registered directly by the consumer via `registerAutoComplete()`. */
+    private _userCompletions;
+    /** Token providers registered directly by the consumer via `registerSyntaxHighlighter()`. */
+    private _userTokenProviders;
+    private mountCodeEditor;
+    /**
+     * Rebuilds the full completions list pushed into the SynclineEditor.
+     *
+     * Merge order:
+     *   1. Built-in MDX completions  — tags, attributes
+     *   2. Built-in MDX snippets     — toolbar-matched snippet bodies
+     *   3. Plugin completions        — each registered plugin's items
+     *   4. User completions          — items added via `registerAutoComplete()`
+     *
+     * Called automatically after every `registerPlugin` / `unregisterPlugin`
+     * and every `registerAutoComplete()` call.
+     */
+    private _refreshCompletions;
+    /**
+     * Register one or more custom autocomplete items on top of the built-in
+     * MDX completions. Items appear in the popup immediately and persist for
+     * the lifetime of the editor instance.
+     *
+     * Use `kind: 'snip'` with a `body` template for snippet expansion — Tab
+     * or clicking the item inserts the full body with the cursor placed at
+     * the first `$1` tab stop.
+     *
+     * @example
+     * ```ts
+     * editor.registerAutoComplete([
+     *   {
+     *     label: 'mycard',
+     *     kind: 'snip',
+     *     detail: '<MyCard> component',
+     *     description: 'Inserts a custom card block.',
+     *     body: '<MyCard title="$1">\n  $2\n</MyCard>',
+     *   },
+     *   { label: 'MyCard', kind: 'cls', detail: 'component' },
+     * ]);
+     * ```
+     */
+    registerAutoComplete(items: CompletionItem | CompletionItem[]): void;
+    /**
+     * Rebuilds the composed `provideTokens` function pushed into the
+     * SynclineEditor, merging:
+     *   1. Built-in MDX base tokeniser (headings, bold, italic, links, etc.)
+     *   2. Plugin token providers  — each registered plugin's `provideTokens`
+     *   3. User token providers    — added via `registerSyntaxHighlighter()`
+     *
+     * Called automatically after every `registerPlugin` / `unregisterPlugin`
+     * and every `registerSyntaxHighlighter()` call.
+     */
+    private _refreshTokenProvider;
+    /**
+     * Register one or more custom syntax token providers on top of the
+     * built-in MDX tokeniser and any plugin-contributed providers.
+     *
+     * Each provider is called on every visible line in the code editor and
+     * may return `TokenSegment` objects covering the character ranges that
+     * should receive custom syntax colouring. The result is LRU-cached by
+     * the underlying `SynclineEditor`.
+     *
+     * Providers added here are equivalent to declaring `provideTokens` on a
+     * custom `EditorPlugin` — use whichever is more convenient.
+     *
+     * @example
+     * ```ts
+     * editor.registerSyntaxHighlighter((line, _lang) => {
+     *   const segs: TokenSegment[] = [];
+     *   // Highlight <MyBlock component names
+     *   for (const m of line.matchAll(/<\/?( MyBlock)(?=[\s>/])/g)) {
+     *     const s = m.index! + 1 + (m[0][1] === '/' ? 1 : 0);
+     *     segs.push({ cls: 'cls', start: s, end: s + 'MyBlock'.length });
+     *   }
+     *   return segs;
+     * });
+     * ```
+     */
+    registerSyntaxHighlighter(fn: PluginTokenProvider | PluginTokenProvider[]): void;
     private buildDOM;
+    /** Convert a flat character offset to { row, col } in the document. */
+    private offsetToPos;
+    /** Convert { row, col } to a flat character offset. */
+    private posToOffset;
     private registerPlugins;
     private getDefaultToolbar;
-    private onInput;
-    private onKeyDown;
     private matchShortcut;
-    private onSelectionChange;
     private scheduleRender;
+    private getCursorPosition;
     private updateStatusBar;
+    private updateModeButtons;
+    private buildTocPanel;
+    refreshToc(): void;
+    toggleToc(): void;
     getValue(): string;
     setValue(value: string): void;
     insertText(text: string): void;
@@ -57,5 +179,15 @@ export declare class SynclineMDXEditor implements EditorAPI {
     insertAt(position: number, text: string): void;
     getWordCount(): number;
     getLineCount(): number;
+    setLineNumbers(enabled: boolean): void;
+    jumpToLine(lineNumber: number): void;
     private applyTheme;
+    /**
+     * Directly set a `ThemeDefinition` on the embedded code editor.
+     * Use this when you need to apply a theme that cannot be expressed via
+     * CSS class toggles — e.g. a fully custom colour palette loaded at runtime.
+     * Passing `null` reverts the code editor to the default MDX light/dark theme
+     * derived from the current `.smdx-dark` class state.
+     */
+    setCodeEditorTheme(theme: import('@synclineapi/editor').ThemeDefinition | null): void;
 }

package/dist/core/mdx-themes.d.ts

@@ -0,0 +1,3 @@
+import { ThemeDefinition } from '@synclineapi/editor';
+export declare const THEME_MDX_DARK: ThemeDefinition;
+export declare const THEME_MDX_LIGHT: ThemeDefinition;

package/dist/core/platform.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Platform detection utilities for cross-platform shortcut label formatting.
+ *
+ * Shortcut labels are stored in Mac notation (⌘, ⇧, ⌥).
+ * On Windows/Linux these Unicode symbols are converted to readable text
+ * (Ctrl+, Shift+, Alt+) so users see the correct key names for their OS.
+ */
+/**
+ * Returns true when running on macOS.
+ * Tries the modern `navigator.userAgentData.platform` first, then falls back
+ * to the legacy `navigator.platform` and `navigator.userAgent`.
+ */
+export declare function isMac(): boolean;
+/**
+ * Converts a shortcut label to the correct format for the current platform.
+ *
+ * On macOS, text modifiers are converted to Unicode symbols (e.g. "Ctrl+B" → "⌘B").
+ * On Windows/Linux, Unicode symbols are replaced with their keyboard text
+ * equivalents (e.g. "⌘B" → "Ctrl+B", "⌘⇧X" → "Ctrl+Shift+X").
+ *
+ * Substitutions applied on macOS (case-insensitive):
+ *   Ctrl+   →  ⌘
+ *   Shift+  →  ⇧
+ *   Alt+    →  ⌥
+ *
+ * Substitutions applied on Windows/Linux:
+ *   ⌘  →  Ctrl+
+ *   ⇧  →  Shift+
+ *   ⌥  →  Alt+
+ */
+export declare function formatShortcutLabel(label: string): string;

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

@@ -1,24 +1 @@
-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;
-}
+export { PluginManager } from './plugins/PluginManager';

package/dist/core/plugins/PluginContext.d.ts

@@ -0,0 +1,26 @@
+import { EditorAPI, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EventHandler, PluginTokenProvider } from '../types';
+export interface PluginContextOptions {
+    editor: EditorAPI;
+    registerToolbarItem: (item: ToolbarItemConfig) => void;
+    registerShortcut: (shortcut: ShortcutConfig) => void;
+    registerRenderer: (renderer: RendererConfig) => void;
+    registerParser: (parser: ParserConfig) => void;
+    injectStyles: (css: string) => void;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: EventHandler) => void;
+    off: (event: string, handler: EventHandler) => void;
+    registerTokenProvider: (fn: PluginTokenProvider) => void;
+}
+export declare class PluginContext {
+    readonly editor: EditorAPI;
+    readonly registerToolbarItem: (item: ToolbarItemConfig) => void;
+    readonly registerShortcut: (shortcut: ShortcutConfig) => void;
+    readonly registerRenderer: (renderer: RendererConfig) => void;
+    readonly registerParser: (parser: ParserConfig) => void;
+    readonly injectStyles: (css: string) => void;
+    readonly emit: (event: string, data?: unknown) => void;
+    readonly on: (event: string, handler: EventHandler) => void;
+    readonly off: (event: string, handler: EventHandler) => void;
+    readonly registerTokenProvider: (fn: PluginTokenProvider) => void;
+    constructor(options: PluginContextOptions);
+}

package/dist/core/plugins/PluginManager.d.ts

@@ -0,0 +1,41 @@
+import { EditorPlugin, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EditorAPI, CompletionItem, PluginTokenProvider } 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;
+    /** All completion items contributed by plugins, keyed by plugin name. */
+    private completionsByPlugin;
+    /** All token providers contributed by plugins, keyed by plugin name. */
+    private tokenProvidersByPlugin;
+    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[];
+    /**
+     * Returns the flat list of all completion items contributed by every
+     * currently-registered plugin (both static `completions` declarations and
+     * items added dynamically via `ctx.registerCompletion()`).
+     */
+    getCompletions(): CompletionItem[];
+    /**
+     * Returns the flat list of all token provider functions contributed by every
+     * currently-registered plugin (both static `provideTokens` declarations and
+     * providers added dynamically via `ctx.registerTokenProvider()`).
+     */
+    getTokenProviders(): PluginTokenProvider[];
+    hasPlugin(name: string): boolean;
+    getPlugin(name: string): EditorPlugin | undefined;
+    private createContext;
+    private injectStyles;
+    destroy(): void;
+}

package/dist/core/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { PluginManager } from './PluginManager';
+export { PluginContext } from './PluginContext';
+export type { PluginContextOptions } from './PluginContext';

package/dist/core/renderer/CodeRenderer.d.ts

@@ -0,0 +1,4 @@
+export declare class CodeRenderer {
+    private escapeHtml;
+    renderBlock(lang: string, filename: string | undefined, code: string): string;
+}

package/dist/core/renderer/ListRenderer.d.ts

@@ -0,0 +1,5 @@
+export declare class ListRenderer {
+    private isListItem;
+    private buildNestedList;
+    render(text: string): string;
+}

package/dist/core/renderer/MarkdownRenderer.d.ts

@@ -0,0 +1,7 @@
+export declare class MarkdownRenderer {
+    private codeRenderer;
+    private tableRenderer;
+    private listRenderer;
+    private escapeHtml;
+    render(source: string): string;
+}

package/dist/core/renderer/MdxValidator.d.ts

@@ -0,0 +1,3 @@
+export declare class MdxValidator {
+    validate(source: string): string[];
+}

package/dist/core/renderer/Renderer.d.ts

@@ -0,0 +1,10 @@
+import { RendererConfig, ParserConfig } from '../types';
+export declare class Renderer {
+    private renderers;
+    private parsers;
+    private markdownRenderer;
+    private mdxValidator;
+    setRenderers(renderers: RendererConfig[]): void;
+    setParsers(parsers: ParserConfig[]): void;
+    render(source: string): Promise<string>;
+}

package/dist/core/renderer/TableRenderer.d.ts

@@ -0,0 +1,4 @@
+export declare class TableRenderer {
+    private parseTableRow;
+    render(html: string): string;
+}

package/dist/core/renderer/index.d.ts

@@ -0,0 +1,7 @@
+export { Renderer } from './Renderer';
+export { MarkdownRenderer } from './MarkdownRenderer';
+export { CodeRenderer } from './CodeRenderer';
+export { TableRenderer } from './TableRenderer';
+export { ListRenderer } from './ListRenderer';
+export { MdxValidator } from './MdxValidator';
+export { sanitizeHtml } from './sanitize';

package/dist/core/renderer/sanitize.d.ts

@@ -0,0 +1 @@
+export { sanitizeHtml } from '../sanitize';

package/dist/core/renderer.d.ts

@@ -1,31 +1,6 @@
-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 isListItem;
-    private buildNestedList;
-    private renderNestedLists;
-    private escapeHtml;
-    /**
-     * Validate MDX component tags — detect unclosed or mismatched tags.
-     * Only checks PascalCase tags (MDX components), not standard HTML.
-     */
-    private validateMdxTags;
-}
+export { Renderer } from './renderer/Renderer';
+export { MarkdownRenderer } from './renderer/MarkdownRenderer';
+export { CodeRenderer } from './renderer/CodeRenderer';
+export { TableRenderer } from './renderer/TableRenderer';
+export { ListRenderer } from './renderer/ListRenderer';
+export { MdxValidator } from './renderer/MdxValidator';

package/dist/core/toolbar.d.ts

@@ -17,6 +17,7 @@ export declare class Toolbar {
     private renderGroup;
     private renderDropdownGroup;
     private renderDropdownItem;
+    private positionMenu;
     private renderSubmenu;
     private createButton;
     private createMenuButton;