@synclineapi/mdx-editor 1.0.0 → 1.0.1

package/README.md

@@ -5,7 +5,7 @@
 [![WCAG AA](https://img.shields.io/badge/Accessibility-WCAG%20AA-green.svg)](https://www.w3.org/TR/WCAG21/)
 [![Website](https://img.shields.io/badge/Website-markdown.synclineapi.com-blue)](https://markdown.synclineapi.com/)
 
-A **framework-agnostic**, plugin-based MDX/Markdown editor with a high-performance virtual-rendering code pane, live HTML preview, a configurable toolbar, and 33+ built-in content plugins. Works with React, Vue, Angular, Next.js, Svelte, or plain JavaScript.
+A **framework-agnostic**, plugin-based MDX/Markdown editor with a high-performance virtual-rendering code pane, live HTML preview, a configurable toolbar, and 38 built-in content plugins. Works with React, Vue, Angular, Next.js, Svelte, or plain JavaScript.
 
 **[Live Demo →](https://markdown.synclineapi.com/)**
 
@@ -76,7 +76,7 @@ const editor = new SynclineMDXEditor({
 
 ## Features
 
-### 33+ Built-in Plugins
+### 38 Built-in Plugins
 
 | Category | Plugins |
 |----------|---------|
@@ -88,6 +88,7 @@ const editor = new SynclineMDXEditor({
 | **Components** | Accordion, Accordion Group, Card, Card Group, Steps |
 | **Callouts** | Admonition (Tip / Warning / Caution / Danger / Info / Note), Tip (Good / Bad / Info) |
 | **Rich Content** | Highlight (8 colours), Emoji, Formula (KaTeX inline & block), Tooltip, Copy Text |
+| **Inline labels** | Badge (success / warning / error / info), Status Tag (live / beta / soon / archived) |
 | **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 |
@@ -96,8 +97,8 @@ const editor = new SynclineMDXEditor({
 
 - **Virtual rendering** — only visible rows are in the DOM; handles documents of 10 000+ lines at 60 fps
 - **Word wrap** — proper pixel-width wrap with full active-line highlight across all visual rows
-- **MDX autocomplete** — context-aware component-tag and attribute suggestions; Tab-trigger snippet expansion
-- **Single-colour prose mode** — all syntax tokens collapse to the text colour for distraction-free writing
+- **MDX autocomplete** — context-aware component-tag and attribute suggestions; Tab-trigger snippet expansion; plugins contribute items declaratively via `completions: [...]` or dynamically via `ctx.registerCompletion()`
+- **Semantic syntax highlighting** — every built-in plugin declares a `provideTokens` function mapping its MDX syntax to semantic token classes (`kw`, `cls`, `fn`, `str`, `op`, `typ`, `num`, `cmt`); consumers can extend this with `registerSyntaxHighlighter()`
 - **Live HTML preview** — side-by-side split / editor-only / preview-only modes with a draggable splitter
 - **Table of Contents** — auto-generated from headings, collapsible panel
 - **Theme system** — light / dark toggle; auto-syncs with `data-theme`, `.smdx-dark`, or `data-color-scheme`
@@ -165,6 +166,71 @@ document.documentElement.dataset.theme = 'dark';
 
 ---
 
+## Syntax Highlighting
+
+### `registerSyntaxHighlighter()`
+
+Add custom token providers that colour your own MDX component syntax on top of the built-in highlighting. Every built-in plugin already declares a `provideTokens` function; this API lets you extend it from outside.
+
+```ts
+import type { PluginTokenProvider } from '@synclineapi/mdx-editor';
+import { componentTagTokens } from '@synclineapi/mdx-editor';
+
+// Quickest option — use the built-in JSX helper
+// Highlights <MyCard …> tag names as `cls`, attribute names as `fn`, values as `str`.
+// Handles boolean attributes like `defaultOpen` and `disabled` automatically.
+editor.registerSyntaxHighlighter(componentTagTokens(['MyCard', 'MyCardGroup']));
+
+// Custom provider for non-JSX syntax  
+const myProvider: PluginTokenProvider = (line) => {
+  const segs = [];
+  // Highlight :::type admonition-style fences
+  const m = line.match(/^(:::)(\w+)/);
+  if (m) {
+    segs.push({ cls: 'kw',  start: 0,            end: 3 });
+    segs.push({ cls: 'cls', start: 3,             end: 3 + m[2].length });
+  }
+  return segs;
+};
+editor.registerSyntaxHighlighter(myProvider);
+
+// Pass an array to register several at once
+editor.registerSyntaxHighlighter([providerA, providerB]);
+```
+
+### Token classes
+
+| `cls` | Colour role | Typical MDX use |
+|-------|-------------|-----------------|
+| `kw`  | purple      | Heading `#`, code fences ` ``` `, `:::`, `---`, blockquotes `>` |
+| `str` | green       | Link URLs, attribute values, inline `` `code` ``, `$math$` |
+| `cmt` | muted gray  | ~~Strikethrough~~ text |
+| `fn`  | blue        | Link labels, *italic*, attribute names |
+| `num` | orange      | **Bold** text, `$$formula$$` markers |
+| `cls` | yellow      | `<Card>`, `<Tabs>`, `<Accordion>` — JSX component tag names |
+| `op`  | cyan        | List markers `- 1.`, table pipes `\|` |
+| `typ` | blue        | Code-fence language identifiers (`mermaid`, `ts`, `python`) |
+| `dec` | red         | Decorators (reserved for custom use) |
+
+### `componentTagTokens()` helper
+
+The built-in JSX highlighter factory. Handles:
+
+- **Tag names**: `<Card`, `</Card>`, `<Card />` → `cls`
+- **Value attributes**: `title="…"`, `src="…"` → name as `fn`, value as `str`
+- **Boolean attributes**: `defaultOpen`, `disabled`, `open` (no `=`) → `fn`
+- **Multi-line tags**: attributes that continue on the next line(s) are highlighted correctly — the provider tracks open-tag state across lines.
+- Attribute scanning is scoped to the region between the tag name and `>` so tag body text is never falsely coloured.
+
+```ts
+import { componentTagTokens } from '@synclineapi/mdx-editor';
+
+provideTokens: componentTagTokens(['Accordion', 'AccordionGroup']),
+// <Accordion title="…" defaultOpen>  →  Accordion=cls  title=fn  "…"=str  defaultOpen=fn
+```
+
+---
+
 ## Autocomplete
 
 ### `registerAutoComplete()`
@@ -251,6 +317,8 @@ const myPlugin: EditorPlugin = {
       detail: '<MyBlock> component',
       body: '<MyBlock>\n  $1Content\n</MyBlock>',
     },
+    // Component name entry (shows in autocomplete as a class suggestion)
+    { label: 'MyBlock', kind: 'cls', detail: 'custom block component' },
   ],
 
   // Preview renderer
@@ -263,6 +331,21 @@ const myPlugin: EditorPlugin = {
     },
   }],
 
+  // Syntax highlighting — called per-line, highlight component tag
+  // names, attribute names, and attribute values automatically.
+  // Use the built-in helper for JSX components:
+  provideTokens: componentTagTokens(['MyBlock']),
+  // Or write a custom provider for any syntax pattern:
+  // provideTokens: (line) => {
+  //   const segs = [];
+  //   const m = line.match(/^(:::)(\w+)/);
+  //   if (m) {
+  //     segs.push({ cls: 'kw', start: 0, end: 3 });
+  //     segs.push({ cls: 'cls', start: 3, end: 3 + m[2].length });
+  //   }
+  //   return segs;
+  // },
+
   shortcuts: [
     {
       key: 'Ctrl+Shift+m',
@@ -398,6 +481,9 @@ interface SynclineMDXEditor {
   // Autocomplete
   registerAutoComplete(items: CompletionItem | CompletionItem[]): void;
 
+  // Syntax highlighting
+  registerSyntaxHighlighter(fn: PluginTokenProvider | PluginTokenProvider[]): void;
+
   // Theme sync
   syncCodeEditorTheme(): void;
 

package/dist/core/editor.d.ts

@@ -1,4 +1,4 @@
-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;
@@ -58,6 +58,8 @@ export declare class SynclineMDXEditor implements EditorAPI {
     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.
@@ -96,6 +98,43 @@ export declare class SynclineMDXEditor implements EditorAPI {
      * ```
      */
     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;

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

@@ -1,4 +1,4 @@
-import { EditorAPI, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EventHandler } from '../types';
+import { EditorAPI, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EventHandler, PluginTokenProvider } from '../types';
 export interface PluginContextOptions {
     editor: EditorAPI;
     registerToolbarItem: (item: ToolbarItemConfig) => void;
@@ -9,6 +9,7 @@ export interface PluginContextOptions {
     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;
@@ -20,5 +21,6 @@ export declare class PluginContext {
     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

@@ -1,4 +1,4 @@
-import { EditorPlugin, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EditorAPI, CompletionItem } from '../types';
+import { EditorPlugin, ToolbarItemConfig, ShortcutConfig, RendererConfig, ParserConfig, EditorAPI, CompletionItem, PluginTokenProvider } from '../types';
 import { EventEmitter } from '../events';
 export declare class PluginManager {
     private editorApi;
@@ -11,6 +11,8 @@ export declare class PluginManager {
     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;
@@ -25,6 +27,12 @@ export declare class PluginManager {
      * 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;

package/dist/core/types.d.ts

@@ -1,5 +1,7 @@
-import { CompletionItem, CompletionKind } from '@synclineapi/editor';
-export type { CompletionItem, CompletionKind };
+import { CompletionItem, CompletionKind, TokenSegment } from '@synclineapi/editor';
+export type { CompletionItem, CompletionKind, TokenSegment };
+/** Function signature for a plugin-level syntax token provider. */
+export type PluginTokenProvider = (line: string, language: string) => TokenSegment[];
 export interface EditorConfig {
     container: HTMLElement | string;
     /** Initial markdown content */
@@ -70,6 +72,36 @@ export interface EditorPlugin {
      * ```
      */
     completions?: CompletionItem[];
+    /**
+     * Custom syntax token provider for this plugin's MDX constructs.
+     *
+     * Called on every visible line in the code editor **in addition to** the
+     * built-in MDX tokeniser. Return `TokenSegment` objects for the character
+     * ranges you want coloured. Ranges not covered fall back to the base MDX
+     * tokeniser.
+     *
+     * All plugin providers are composed into a single `provideTokens` function
+     * that is passed to the underlying `SynclineEditor`. The result is LRU-
+     * cached by the editor, so the function is only called once per unique
+     * `(text, language)` pair.
+     *
+     * Use `ctx.registerTokenProvider()` inside `init()` when the segments
+     * need to be computed dynamically (e.g. based on runtime config).
+     *
+     * @example
+     * ```ts
+     * provideTokens: (line, _lang) => {
+     *   const segs: TokenSegment[] = [];
+     *   // Highlight <MyBlock component name
+     *   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;
+     * }
+     * ```
+     */
+    provideTokens?: PluginTokenProvider;
 }
 export interface PluginContext {
     /** The editor instance */
@@ -100,6 +132,27 @@ export interface PluginContext {
      * ```
      */
     registerCompletion(item: CompletionItem): void;
+    /**
+     * Register a dynamic token provider for this plugin's MDX syntax.
+     * Equivalent to declaring `provideTokens` on the plugin definition but
+     * useful when the provider needs to be built dynamically inside `init()`.
+     *
+     * Multiple providers registered from the same plugin are all called and
+     * their results merged into the final token list.
+     *
+     * @example
+     * ```ts
+     * ctx.registerTokenProvider((line, _lang) => {
+     *   const segs: TokenSegment[] = [];
+     *   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;
+     * });
+     * ```
+     */
+    registerTokenProvider(fn: PluginTokenProvider): void;
     /** Emit a plugin event */
     emit(event: string, data?: unknown): void;
     /** Listen to events */
@@ -236,6 +289,31 @@ export interface EditorAPI {
      * ```
      */
     registerAutoComplete(items: CompletionItem | CompletionItem[]): void;
+    /**
+     * 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`.
+     *
+     * Equivalent to declaring `provideTokens` on a custom `EditorPlugin` —
+     * use whichever is more convenient.
+     *
+     * @example
+     * ```ts
+     * editor.registerSyntaxHighlighter((line, _lang) => {
+     *   const segs: TokenSegment[] = [];
+     *   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;
 }
 export interface SelectionState {
     start: number;

package/dist/index.d.ts

@@ -7,7 +7,8 @@ export { Toolbar } from './core/toolbar';
 export { Renderer } from './core/renderer';
 export { History } from './core/history';
 export { icons } from './core/icons';
-export type { EditorConfig, EditorPlugin, EditorAPI, EditorMode, PluginContext, ToolbarConfig, ToolbarRow, ToolbarGroup, ToolbarDivider, ToolbarItemConfig, ToolbarAction, ToolbarActionContext, SelectionState, RendererFn, RendererConfig, ParserConfig, ShortcutConfig, EventHandler, EditorLocale, CompletionItem, CompletionKind, } from './core/types';
+export type { EditorConfig, EditorPlugin, EditorAPI, EditorMode, PluginContext, ToolbarConfig, ToolbarRow, ToolbarGroup, ToolbarDivider, ToolbarItemConfig, ToolbarAction, ToolbarActionContext, SelectionState, RendererFn, RendererConfig, ParserConfig, ShortcutConfig, EventHandler, EditorLocale, CompletionItem, CompletionKind, TokenSegment, PluginTokenProvider, } from './core/types';
+export { componentTagTokens, mdxBaseTokens, composeTokenProviders } from './plugins/token-utils';
 export { headingPlugin, boldPlugin, italicPlugin, strikethroughPlugin, quotePlugin, linkPlugin, imagePlugin, codePlugin, unorderedListPlugin, orderedListPlugin, taskListPlugin, tablePlugin, highlightPlugin, admonitionPlugin, tabPlugin, imageBackgroundPlugin, imageFramePlugin, accordionPlugin, accordionGroupPlugin, multiColumnPlugin, cardPlugin, cardGroupPlugin, stepPlugin, tipPlugin, containerPlugin, copyTextPlugin, tooltipPlugin, embedVideoPlugin, embedOthersPlugin, mermaidPlugin, emojiPlugin, formulaPlugin, insertPlugin, tocPlugin, breakLinePlugin, horizontalRulePlugin, allPlugins, defaultToolbar, } from './plugins';
 export { Renderer as RendererPipeline } from './core/renderer/Renderer';
 export { MarkdownRenderer } from './core/renderer/MarkdownRenderer';

package/dist/plugins/token-utils.d.ts

@@ -0,0 +1,49 @@
+import { TokenSegment, PluginTokenProvider } from '../core/types';
+/**
+ * Creates a `provideTokens` function that highlights JSX component tag names
+ * for the given list of components with the `cls` (class/component) token class.
+ *
+ * Handles:
+ *   - Opening tags:      `<Card`, `<CardGroup`
+ *   - Closing tags:      `</Card>`, `</CardGroup>`
+ *   - Self-closing tags: `<Card />`, `<Card/>`
+ *   - Value attributes:  `title="…"`, `src="…"` → name as `fn`, value as `str`
+ *   - Boolean attributes:`defaultOpen`, `open`, `disabled` (no `=`) → `fn`
+ *
+ * Attribute scanning is scoped to the character region between the tag name
+ * and the closing `>` so tag body content is never falsely coloured.
+ *
+ * @example
+ * ```ts
+ * // In a plugin definition:
+ * provideTokens: componentTagTokens(['Accordion', 'AccordionGroup']),
+ * ```
+ */
+export declare function componentTagTokens(tagNames: string[]): PluginTokenProvider;
+/**
+ * Returns token segments for standard inline Markdown constructs on a line:
+ * - ATX headings:        `# … ######` → `kw`
+ * - Blockquote prefix:   `>` → `kw`
+ * - Horizontal rule:     `---` / `***` / `___` alone on a line → `kw`
+ * - Bold:                `**text**` → `num`
+ * - Italic:              `*text*` / `_text_` → `fn`
+ * - Strikethrough:       `~~text~~` → `cmt`
+ * - Inline code:         `` `code` `` → `str`
+ * - Code fence marker:   ` ``` ` / `~~~` + optional language → `kw` + `typ`
+ * - Links:               `[text](url)` → `fn` for `[text]`, `str` for `(url)`
+ * - Images:              `![alt](url)` → `fn` for `![alt]`, `str` for `(url)`
+ * - List markers:        `- `, `* `, `+ ` / `1. ` → `op`
+ * - Task list checkbox:  `[ ]` / `[x]` → `kw`
+ * - Table pipes:         `|` separators → `op`
+ * - Import / Export:     MDX `import`/`export` keyword lines → `kw` for the keyword
+ */
+export declare function mdxBaseTokens(line: string, _language: string): TokenSegment[];
+/**
+ * Compose an array of `PluginTokenProvider` functions into a single
+ * `provideTokens` function suitable for passing directly to `SynclineEditor`.
+ *
+ * Plugin providers run first (in registration order), then user providers.
+ * Segments from earlier providers take precedence for overlapping character
+ * ranges (the `SynclineEditor` renders the first covering segment).
+ */
+export declare function composeTokenProviders(pluginProviders: PluginTokenProvider[], userProviders: PluginTokenProvider[]): PluginTokenProvider;