@sigx/lynx-markdown 0.4.7 → 0.4.9

package/README.md

@@ -9,10 +9,6 @@ AI output: as the source string grows token-by-token, finalized blocks keep a
 stable identity and are never re-parsed or remounted, so completed content
 doesn't flicker or reflow while new tokens stream in.
 
-The package also ships [`XMarkdown`](#xmarkdown--native-element-wrapper), the
-thin wrapper around Lynx's native `<x-markdown>` element, for cases where you
-want the platform's built-in renderer.
-
 ## Install
 
 ```
@@ -120,22 +116,56 @@ import { markdownComponents } from '@sigx/lynx-daisyui';
 <MarkdownView value={src} components={markdownComponents} />;
 ```
 
-## `XMarkdown` — native element wrapper
-
-`XMarkdown` wraps Lynx's native `<x-markdown>` XElement. It's fast where
-available but platform-gated and opaque (the engine owns parsing and styling):
 
-| Platform | First version   | Notes                                               |
-| -------- | --------------- | --------------------------------------------------- |
-| Harmony  | Lynx 3.7.0      | Stable.                                             |
-| Android  | Lynx 3.8.0-rc.0 | Ships as `org.lynxsdk.lynx:lynx_xelement_markdown`. |
-| iOS      | (post-3.8.0)    | Currently only on the upstream `main` branch.       |
+## `MarkdownEditor` — true-WYSIWYG editing
 
-On platforms where `<x-markdown>` is not registered, it renders nothing. Prefer
-`MarkdownView` for cross-platform, streaming, and customizable rendering.
+`MarkdownEditor` provides WYSIWYG markdown editing on the native
+[`@sigx/lynx-richtext`](../lynx-richtext) element (optional peer dependency —
+bold is bold *inside* the input, not `**` markers). The external contract stays
+markdown: `value` in, `onChange(markdown)` out.
 
 ```tsx
-import { XMarkdown } from '@sigx/lynx-markdown';
+import { MarkdownEditor, type MarkdownEditorController } from '@sigx/lynx-markdown';
+
+let ctrl: MarkdownEditorController | null = null;
+
+<MarkdownEditor
+  value={draft}
+  placeholder="Message…"
+  minLines={1}
+  maxLines={4}              // chat-style: grow 1→4 lines, then scroll
+  mode="auto"               // 'auto' | 'fixed' | 'fullscreen'
+  confirmType="send"
+  onChange={(md) => { draft = md; }}
+  onSelectionChange={(sel) => toolbarState(sel.activeFormats)}
+  controllerRef={(c) => { ctrl = c; }}
+/>;
+
+// Imperative commands (what a toolbar drives):
+ctrl?.toggleBold();
+ctrl?.setHeading(2);
+ctrl?.clear();              // chat send
+```
+
+### Toolbar
 
-<XMarkdown value={'# Hello'} effect="typewriter" onLink={(e) => open(e.detail.url)} />;
+The built-in toolbar mirrors the renderer's override pattern — items are data,
+rendering is replaceable:
+
+```tsx
+<MarkdownEditor toolbar />                       // neutral default, below the input
+<MarkdownEditor toolbar="top" />                 // above instead
+<MarkdownEditor toolbar toolbarItems={items} />  // custom ToolbarItem[]
+<MarkdownEditor toolbar renderToolbarItem={fn} />// re-skin (what daisyUI does)
 ```
+
+`<EditorToolbar>` is also exported standalone (pass `controller` + `selection`
+yourself — e.g. inside a keyboard-sticky send bar). `ToolbarItem` is
+`{ id, label, icon?, group?, isActive?(sel), run(ctx) }`; plugins contribute
+items through the same shape (P3). The toolbar root carries `ignore-focus` so
+taps never blur the editor. The daisyUI skin lives in `@sigx/lynx-daisyui`.
+
+v1 models paragraphs, headings, and bold/italic/strike/code/link in-field;
+everything else (lists, tables, code fences) round-trips **losslessly** as raw
+markdown source via `raw` blocks until later phases model them. Conversion
+helpers `mdToDoc`/`docToMd` are exported for advanced use.

package/dist/ast.d.ts

@@ -8,7 +8,7 @@
  * reconciliation) and `raw` (the exact source slice, used for memo equality and
  * introspection).
  */
-export type InlineNode = InlineText | InlineStrong | InlineEm | InlineDel | InlineCodeSpan | InlineLink | InlineImage | InlineAutolink | InlineBreak;
+export type InlineNode = InlineText | InlineStrong | InlineEm | InlineDel | InlineCodeSpan | InlineLink | InlineImage | InlineAutolink | InlineBreak | InlineExtension;
 /** A run of literal text. */
 export interface InlineText {
     type: 'text';
@@ -58,6 +58,23 @@ export interface InlineAutolink {
 export interface InlineBreak {
     type: 'br';
 }
+/**
+ * A plugin-defined inline construct (e.g. a mention `@[label](id)`), produced
+ * by a `ParserInlineExtension`'s `match`. Opaque to the emphasis stack — same
+ * precedence tier as code spans and links. Rendered through
+ * `components.extension[name]`, falling back to `raw` as literal text.
+ */
+export interface InlineExtension {
+    type: 'extension';
+    /** Extension name; the render dispatch key. */
+    name: string;
+    /** Opaque structured payload (e.g. `{ id, label }` for a mention). */
+    attrs: Record<string, string>;
+    /** Optional nested inline content; absent for leaf extensions. */
+    children?: InlineNode[];
+    /** Exact source slice — the literal-text fallback and round-trip source. */
+    raw: string;
+}
 export interface BlockBase {
     /** Stable reconciliation key, assigned by the incremental engine. */
     key: string;

package/dist/editor/MarkdownEditor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `<MarkdownEditor>` — true-WYSIWYG markdown editing on the native
+ * `<sigx-richtext>` element.
+ *
+ * The external contract is **markdown**: `value` in, `onChange(markdown)` out.
+ * Internally the editor converts markdown ↔ the element's `RichDoc` span model
+ * (`convert/mdToDoc`, `convert/docToMd`) and drives formatting through
+ * fire-and-forget commands; the element is the single source of truth for live
+ * text and selection (lightly-controlled — keystrokes are never echoed back).
+ *
+ * ### Echo / IME rules (JS side)
+ * - An incoming `value` identical to the last markdown we emitted is our own
+ *   echo → ignored (string compare; exact).
+ * - Otherwise it's compared structurally against the element's last document —
+ *   only genuinely different content is pushed via `setDocument`.
+ * - While the IME is composing, external values are buffered and applied on
+ *   the composition-end change; `onChange` is also suppressed mid-composition.
+ *
+ * Sizing: `minLines`/`maxLines` × line height drive the element's auto-grow
+ * window (`mode="auto"`, chat-style 1 → N lines then internal scroll);
+ * `mode="fixed"` pins the height at `maxLines`; `mode="fullscreen"` fills the
+ * parent.
+ */
+import { type Define } from '@sigx/lynx';
+import { type SelectionState } from '@sigx/lynx-richtext';
+import { type ToolbarRenderItem } from './toolbar/Toolbar.js';
+import { type ToolbarItem } from './toolbar/items.js';
+import type { MarkdownEditorPlugin } from './plugin.js';
+export type MarkdownEditorMode = 'auto' | 'fixed' | 'fullscreen';
+/** Imperative command surface — what toolbars and plugins drive. */
+export interface MarkdownEditorController {
+    toggleBold(): void;
+    toggleItalic(): void;
+    toggleStrike(): void;
+    toggleCode(): void;
+    /** 1–6 sets a heading; 0 reverts to paragraph. */
+    setHeading(level: 0 | 1 | 2 | 3 | 4 | 5 | 6): void;
+    insertText(text: string): void;
+    /**
+     * Replace `[start, end)` (UTF-16 offsets in the document text) with
+     * `text`, leaving the caret after it. What trigger plugins use to swap
+     * the typed query for the selected suggestion.
+     */
+    replaceRange(start: number, end: number, text: string): void;
+    /** Clear the document (chat send). */
+    clear(): void;
+    focus(): void;
+    blur(): void;
+    /** The current markdown (as of the last element change). */
+    getMarkdown(): string;
+    /** The current selection state (as of the last selection event). */
+    getSelection(): SelectionState | null;
+}
+export type MarkdownEditorProps = Define.Prop<'value', string, false> & Define.Prop<'placeholder', string, false> & Define.Prop<'minLines', number, false> & Define.Prop<'maxLines', number, false> & Define.Prop<'mode', MarkdownEditorMode, false> & Define.Prop<'fontSize', number, false> & Define.Prop<'textColor', string, false> & Define.Prop<'accentColor', string, false> & Define.Prop<'placeholderColor', string, false> & Define.Prop<'confirmType', 'send' | 'search' | 'next' | 'go' | 'done', false> & Define.Prop<'autoFocus', boolean, false> & Define.Prop<'disabled', boolean, false> & Define.Prop<'class', string, false>
+/**
+ * Built-in formatting toolbar. `true` ≡ `'bottom'` — below the input is
+ * the common chat placement (selection handles and the iOS edit menu pop
+ * up *above* the selection, so a toolbar on top would sit under them).
+ */
+ & Define.Prop<'toolbar', boolean | 'top' | 'bottom', false>
+/** Override the built-in toolbar's items (defaults to `defaultToolbarItems`). */
+ & Define.Prop<'toolbarItems', ToolbarItem[], false>
+/** Re-skin the built-in toolbar's item rendering (what daisyUI does). */
+ & Define.Prop<'renderToolbarItem', ToolbarRenderItem, false>
+/**
+ * Editor plugins ({@link MarkdownEditorPlugin}) — inline syntax, trigger
+ * suggestions, extra toolbar items. Pass a stable array (e.g. a module
+ * constant); the set is captured at mount.
+ */
+ & Define.Prop<'plugins', MarkdownEditorPlugin[], false> & Define.Prop<'onChange', (markdown: string) => void, false> & Define.Prop<'onSelectionChange', (sel: SelectionState) => void, false> & Define.Prop<'onFocus', () => void, false> & Define.Prop<'onBlur', () => void, false>
+/** Receives the imperative controller once on mount. */
+ & Define.Prop<'controllerRef', (ctrl: MarkdownEditorController) => void, false>;
+export declare const MarkdownEditor: import("@sigx/runtime-core").ComponentFactory<MarkdownEditorProps, void, {}>;

package/dist/editor/MarkdownEditor.js

@@ -0,0 +1,243 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<MarkdownEditor>` — true-WYSIWYG markdown editing on the native
+ * `<sigx-richtext>` element.
+ *
+ * The external contract is **markdown**: `value` in, `onChange(markdown)` out.
+ * Internally the editor converts markdown ↔ the element's `RichDoc` span model
+ * (`convert/mdToDoc`, `convert/docToMd`) and drives formatting through
+ * fire-and-forget commands; the element is the single source of truth for live
+ * text and selection (lightly-controlled — keystrokes are never echoed back).
+ *
+ * ### Echo / IME rules (JS side)
+ * - An incoming `value` identical to the last markdown we emitted is our own
+ *   echo → ignored (string compare; exact).
+ * - Otherwise it's compared structurally against the element's last document —
+ *   only genuinely different content is pushed via `setDocument`.
+ * - While the IME is composing, external values are buffered and applied on
+ *   the composition-end change; `onChange` is also suppressed mid-composition.
+ *
+ * Sizing: `minLines`/`maxLines` × line height drive the element's auto-grow
+ * window (`mode="auto"`, chat-style 1 → N lines then internal scroll);
+ * `mode="fixed"` pins the height at `maxLines`; `mode="fullscreen"` fills the
+ * parent.
+ */
+import { component, signal, useElementLayout, watch } from '@sigx/lynx';
+import { RichTextInput, RichTextMethods, docEquals, normalizeDoc, emptyDoc, } from '@sigx/lynx-richtext';
+import { mdToDoc } from './convert/mdToDoc.js';
+import { docToMd } from './convert/docToMd.js';
+import { EditorToolbar } from './toolbar/Toolbar.js';
+import { defaultToolbarItems } from './toolbar/items.js';
+import { createTriggerSessionManager } from './trigger/session.js';
+import { SuggestionPopup } from './trigger/SuggestionPopup.js';
+const DEFAULT_FONT_SIZE = 16;
+/** Vertical padding the element applies internally (8 top + 8 bottom). */
+const ELEMENT_PADDING = 16;
+export const MarkdownEditor = component(({ props }) => {
+    let el = null;
+    // --- plugins (captured at mount; pass a stable array) ---
+    const plugins = props.plugins ?? [];
+    const inlinePlugins = plugins.filter((p) => p.inline);
+    // Duplicate identifiers would silently last-win (conversion maps) or make
+    // trigger routing ambiguous (plugin name lookups) — flag the config error.
+    const warnDuplicates = (key, values) => {
+        const seen = new Set();
+        for (const value of values) {
+            if (seen.has(value)) {
+                // Conversion maps resolve last-wins, trigger routing first-wins
+                // — don't promise either; duplicates are a config error.
+                console.warn(`[MarkdownEditor] duplicate plugin ${key} "${value}" — resolution is ambiguous, rename to disambiguate.`);
+            }
+            seen.add(value);
+        }
+    };
+    warnDuplicates('name', plugins.map((p) => p.name));
+    warnDuplicates('syntax.name', inlinePlugins.map((p) => p.inline.syntax.name));
+    warnDuplicates('docMapping.spanType', inlinePlugins.map((p) => p.inline.docMapping.spanType));
+    // Trigger routing is first-match-wins — a duplicate char/pattern means the
+    // later plugin's trigger is silently unreachable.
+    warnDuplicates('trigger', plugins
+        .filter((p) => p.trigger)
+        .map((p) => (p.trigger.char !== undefined ? `char:${p.trigger.char}` : `pattern:${p.trigger.pattern}`)));
+    const convertIn = inlinePlugins.length
+        ? {
+            extensions: inlinePlugins.map((p) => p.inline.syntax),
+            spanMappers: Object.fromEntries(inlinePlugins.map((p) => [p.inline.syntax.name, p.inline.docMapping.toSpan])),
+        }
+        : undefined;
+    const convertOut = inlinePlugins.length
+        ? {
+            serializers: new Map(inlinePlugins.map((p) => [
+                p.inline.docMapping.spanType,
+                (span, text) => p.inline.serialize(span, text),
+            ])),
+        }
+        : undefined;
+    const pluginToolbarItems = plugins.flatMap((p) => p.toolbar ?? []);
+    // --- sync state (see module docs) ---
+    const initialMd = typeof props.value === 'string' ? props.value : '';
+    let lastEmittedMd = initialMd;
+    let lastDocFromElement = normalizeDoc(mdToDoc(initialMd, 0, convertIn));
+    let lastSeenVersion = 0;
+    let composing = false;
+    let pendingExternal = null;
+    // Reactive box (not a plain var): the built-in toolbar derives active
+    // states from it, so selection events must re-render.
+    const selBox = signal({ current: null });
+    // Auto-grow: the native element reports its (clamped) content height and
+    // the editor feeds it back as the element's layout height — Lynx layout
+    // sizes views from styles, never from native intrinsic content.
+    const reportedHeight = signal(0);
+    // --- trigger sessions (suggestion popup) ---
+    const triggers = plugins
+        .filter((p) => p.trigger)
+        .map((p) => ({ plugin: p.name, spec: p.trigger }));
+    // Boxed like selBox: signal values must be objects.
+    const sessionBox = signal({ current: null });
+    const triggerManager = triggers.length
+        ? createTriggerSessionManager({
+            triggers,
+            onUpdate: (s) => {
+                sessionBox.current = s;
+            },
+        })
+        : null;
+    // Page-absolute frame of the input's relative wrapper — the popup needs
+    // it to relate the element-local caret rect to the keyboard.
+    const { layout: inputFrame, onLayoutChange: onInputLayout } = useElementLayout();
+    const applyExternal = (md) => {
+        if (md === lastEmittedMd)
+            return; // our own echo
+        if (composing) {
+            pendingExternal = md;
+            return;
+        }
+        const doc = mdToDoc(md, lastSeenVersion, convertIn);
+        if (docEquals(normalizeDoc(doc), lastDocFromElement)) {
+            lastEmittedMd = md; // same content, different markdown spelling
+            return;
+        }
+        RichTextMethods.setDocument(el, doc);
+    };
+    watch(() => props.value, (next) => {
+        if (typeof next === 'string')
+            applyExternal(next);
+    });
+    const handleChange = (doc, isComposing) => {
+        composing = isComposing;
+        lastSeenVersion = doc.v;
+        lastDocFromElement = normalizeDoc(doc);
+        triggerManager?.syncText(doc.text);
+        if (isComposing)
+            return;
+        const md = docToMd(doc, convertOut);
+        if (md !== lastEmittedMd) {
+            lastEmittedMd = md;
+            props.onChange?.(md);
+        }
+        if (pendingExternal !== null) {
+            const pending = pendingExternal;
+            pendingExternal = null;
+            applyExternal(pending);
+        }
+    };
+    const controller = {
+        toggleBold: () => RichTextMethods.toggleFormat(el, 'bold'),
+        toggleItalic: () => RichTextMethods.toggleFormat(el, 'italic'),
+        toggleStrike: () => RichTextMethods.toggleFormat(el, 'strike'),
+        toggleCode: () => RichTextMethods.toggleFormat(el, 'code'),
+        setHeading: (level) => {
+            if (level === 0)
+                RichTextMethods.setBlockType(el, 'paragraph');
+            else
+                RichTextMethods.setBlockType(el, 'heading', level);
+        },
+        insertText: (text) => RichTextMethods.insertText(el, text),
+        replaceRange: (start, end, text) => {
+            // insertText replaces the selection — two existing fire-and-forget
+            // commands compose into a range replace (no new native method).
+            RichTextMethods.setSelectionRange(el, start, end);
+            RichTextMethods.insertText(el, text);
+        },
+        clear: () => RichTextMethods.setDocument(el, emptyDoc(lastSeenVersion)),
+        focus: () => RichTextMethods.focus(el),
+        blur: () => RichTextMethods.blur(el),
+        getMarkdown: () => lastEmittedMd ?? '',
+        getSelection: () => selBox.current,
+    };
+    props.controllerRef?.(controller);
+    const handleTriggerSelect = (item) => {
+        const session = triggerManager?.session;
+        if (!session)
+            return;
+        const spec = plugins.find((p) => p.name === session.plugin)?.trigger;
+        if (!spec)
+            return;
+        const range = { start: session.anchor, end: session.caret };
+        const api = {
+            replaceQuery: (text) => controller.replaceRange(range.start, range.end, text),
+            range,
+            controller,
+        };
+        triggerManager.close();
+        spec.onSelect(item, api);
+    };
+    return () => {
+        const fontSize = props.fontSize ?? DEFAULT_FONT_SIZE;
+        const lineHeight = Math.round(fontSize * 1.5);
+        const mode = props.mode ?? 'auto';
+        const minLines = Math.max(1, props.minLines ?? 1);
+        const maxLines = Math.max(minLines, props.maxLines ?? 4);
+        let minHeight = minLines * lineHeight + ELEMENT_PADDING;
+        let maxHeight = maxLines * lineHeight + ELEMENT_PADDING;
+        if (mode === 'fixed')
+            minHeight = maxHeight;
+        if (mode === 'fullscreen')
+            maxHeight = 0; // unbounded; element fills parent
+        const toolbarPlacement = props.toolbar === true ? 'bottom' : props.toolbar;
+        // Plugin items append after the base set (explicit `toolbarItems` wins
+        // as the base, otherwise the defaults).
+        const toolbarItems = pluginToolbarItems.length
+            ? [...(props.toolbarItems ?? defaultToolbarItems), ...pluginToolbarItems]
+            : props.toolbarItems;
+        const toolbarNode = toolbarPlacement
+            ? (_jsx(EditorToolbar, { controller: controller, selection: selBox.current, items: toolbarItems, renderItem: props.renderToolbarItem }))
+            : null;
+        const session = sessionBox.current;
+        const activeTrigger = session
+            ? plugins.find((p) => p.name === session.plugin)?.trigger
+            : undefined;
+        // Gate on the wrapper frame being measured — before the first
+        // bindlayoutchange the placement math would clamp against a 0-height
+        // container and misposition the popup.
+        const popupNode = session && activeTrigger && session.items.length > 0 && inputFrame.value
+            ? (_jsx(SuggestionPopup, { items: session.items, caretRect: selBox.current?.caretRect ?? null, containerFrame: inputFrame.value, renderItem: activeTrigger.renderItem, onSelect: handleTriggerSelect }))
+            : null;
+        const inputNode = (_jsx(RichTextInput, { value: mdToDoc(initialMd, 0, convertIn), placeholder: props.placeholder, editable: props.disabled !== true, minHeight: minHeight, maxHeight: maxHeight, fontSize: fontSize, textColor: props.textColor, accentColor: props.accentColor, placeholderColor: props.placeholderColor, confirmType: props.confirmType, autoFocus: props.autoFocus, style: mode === 'fullscreen'
+                ? { flexGrow: 1 }
+                : { height: Math.max(minHeight, Math.min(reportedHeight.value || minHeight, maxHeight)) }, onElement: (handle) => {
+                el = handle;
+            }, onHeightChange: (height) => {
+                reportedHeight.value = height;
+            }, onChange: handleChange, onSelection: (sel) => {
+                selBox.current = sel;
+                triggerManager?.syncCaret(sel.start === sel.end ? sel.start : -1);
+                props.onSelectionChange?.(sel);
+            }, onFocus: () => props.onFocus?.(), onBlur: () => {
+                triggerManager?.close();
+                props.onBlur?.();
+            } }));
+        return (_jsxs("view", { class: props.class, style: {
+                display: 'flex',
+                flexDirection: 'column',
+                ...(mode === 'fullscreen' ? { flexGrow: 1, flexShrink: 1 } : {}),
+            }, children: [toolbarPlacement === 'top' ? toolbarNode : null, triggers.length
+                    ? (_jsxs("view", { bindlayoutchange: onInputLayout, style: {
+                            position: 'relative',
+                            ...(mode === 'fullscreen'
+                                ? { display: 'flex', flexDirection: 'column', flexGrow: 1 }
+                                : {}),
+                        }, children: [inputNode, popupNode] }))
+                    : inputNode, toolbarPlacement === 'bottom' ? toolbarNode : null] }));
+    };
+});

package/dist/editor/convert/docToMd.d.ts

@@ -0,0 +1,24 @@
+/**
+ * {@link RichDoc} → markdown — the serializer (inverse of `mdToDoc`).
+ *
+ * Segments the flat text by `blocks[]` (raw chunks verbatim, heading lines
+ * prefixed, remaining lines as paragraphs), then serializes inline spans per
+ * segment via elementary runs + a close/reopen delimiter stack (valid nesting
+ * from arbitrarily overlapping spans).
+ *
+ * Round-trip contract: `mdToDoc(docToMd(doc))` is structurally equal to a
+ * *normalized* `doc` — emphasis markers, hard breaks (→ paragraph breaks), and
+ * blank lines normalize; `raw` blocks round-trip byte-for-byte.
+ */
+import type { InlineSpan, RichDoc } from '@sigx/lynx-richtext';
+/** Serialize one plugin-owned span back to markdown (a plugin's `inline.serialize`). */
+export type SpanSerializer = (span: InlineSpan, text: string) => string;
+export interface DocToMdOptions {
+    /**
+     * Plugin serializers keyed by the span type they own
+     * (`docMapping.spanType`). A plugin-owned span is emitted **atomically**:
+     * the serializer's output replaces the covered text entirely.
+     */
+    serializers?: ReadonlyMap<string, SpanSerializer>;
+}
+export declare function docToMd(doc: RichDoc, options?: DocToMdOptions): string;