@sigx/lynx-richtext 0.4.7

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import './jsx-augment.js';
+export { RichTextInput } from './RichTextInput.js';
+export type { RichTextInputProps } from './RichTextInput.js';
+export { RichTextMethods } from './methods.js';
+export type { RichTextHandle } from './methods.js';
+export { encodeDoc, decodeDoc, docEquals, normalizeDoc, emptyDoc } from './model/codec.js';
+export type { RichDoc, InlineSpan, InlineSpanType, BlockAttr, BlockAttrType, SelectionState, RichTextChangeEvent, RichTextSelectionEvent, RichTextHeightChangeEvent, RichTextFocusEvent, } from './model/types.js';
+export type { SigxRichTextAttributes } from './jsx-augment.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+import './jsx-augment.js';
+export { RichTextInput } from './RichTextInput.js';
+export { RichTextMethods } from './methods.js';
+export { encodeDoc, decodeDoc, docEquals, normalizeDoc, emptyDoc } from './model/codec.js';

package/dist/jsx-augment.d.ts

@@ -0,0 +1,48 @@
+/**
+ * JSX intrinsic type augmentation for the native `<sigx-richtext>` element.
+ *
+ * Registered natively via the autolinker (`signalx-module.json` →
+ * `ios.uiComponents` / `android.behaviors`). Importing this module (pulled in
+ * by the package entry point) declares the tag and its typed attribute/event
+ * surface.
+ */
+import type { LynxCommonAttributes, LynxEventHandler } from '@sigx/lynx-runtime';
+import type { RichTextChangeEvent, RichTextFocusEvent, RichTextHeightChangeEvent, RichTextSelectionEvent } from './model/types.js';
+export interface SigxRichTextAttributes extends LynxCommonAttributes {
+    /**
+     * Initial document as a JSON-encoded `RichDoc` (`encodeDoc`). Initial-only
+     * once the user has edited — programmatic replacements must go through the
+     * `setDocument` UI method (see `RichTextMethods`).
+     */
+    value?: string;
+    placeholder?: string;
+    editable?: boolean;
+    /** Auto-grow floor, px. */
+    'min-height'?: number;
+    /** Auto-grow ceiling, px — content beyond this scrolls internally. */
+    'max-height'?: number;
+    /** Base font size, px (headings scale from this). */
+    'font-size'?: number;
+    /** Base text color (hex). */
+    'text-color'?: string;
+    /** Caret tint + link color (hex). */
+    'accent-color'?: string;
+    /** Placeholder text color (hex). */
+    'placeholder-color'?: string;
+    /** Native confirm/return key type. */
+    'confirm-type'?: 'send' | 'search' | 'next' | 'go' | 'done';
+    /** Focus + raise the keyboard on mount. */
+    'auto-focus'?: boolean;
+    bindchange?: LynxEventHandler<RichTextChangeEvent>;
+    bindselection?: LynxEventHandler<RichTextSelectionEvent>;
+    bindheightchange?: LynxEventHandler<RichTextHeightChangeEvent>;
+    bindfocus?: LynxEventHandler<RichTextFocusEvent>;
+    bindblur?: LynxEventHandler<RichTextFocusEvent>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'sigx-richtext': SigxRichTextAttributes;
+        }
+    }
+}

package/dist/jsx-augment.js

@@ -0,0 +1,9 @@
+/**
+ * JSX intrinsic type augmentation for the native `<sigx-richtext>` element.
+ *
+ * Registered natively via the autolinker (`signalx-module.json` →
+ * `ios.uiComponents` / `android.behaviors`). Importing this module (pulled in
+ * by the package entry point) declares the tag and its typed attribute/event
+ * surface.
+ */
+export {};

package/dist/methods.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Background-thread command surface for `<sigx-richtext>`.
+ *
+ * Commands ride the `INVOKE_UI_METHOD` op (BG→MT, fire-and-forget — landed in
+ * lynx-runtime#145): no `main-thread:ref` worklet plumbing is needed. Return
+ * values are deliberately not part of this surface — state reconciles through
+ * the element's `bindchange`/`bindselection` events, which is the editor's
+ * single source of truth.
+ *
+ * The element handle is the ShadowElement delivered by a callback `ref`:
+ *
+ * ```tsx
+ * let el: RichTextHandle = null;
+ * <sigx-richtext ref={(e) => { el = e; }} … />
+ * RichTextMethods.toggleFormat(el, 'bold');
+ * ```
+ */
+import type { BlockAttrType, InlineSpanType, RichDoc } from './model/types.js';
+/** Minimal structural handle — the BG ShadowElement from a callback `ref`. */
+export type RichTextHandle = {
+    id: number;
+} | null | undefined;
+export declare const RichTextMethods: {
+    /**
+     * Replace the document. Carries the version the write was based on —
+     * native drops stale writes (`doc.v < localVersion`) and re-emits current
+     * state, and rejects writes during an active IME composition.
+     */
+    readonly setDocument: (el: RichTextHandle, doc: RichDoc) => void;
+    /** Toggle an inline format over the current selection (collapsed → flips typing attributes). */
+    readonly toggleFormat: (el: RichTextHandle, type: InlineSpanType) => void;
+    /** Set the block type of the paragraph(s) covering the current selection. */
+    readonly setBlockType: (el: RichTextHandle, type: BlockAttrType, level?: number) => void;
+    /** Insert text at the caret (inherits typing attributes). */
+    readonly insertText: (el: RichTextHandle, text: string) => void;
+    /** Move/extend the caret. */
+    readonly setSelectionRange: (el: RichTextHandle, start: number, end: number) => void;
+    readonly focus: (el: RichTextHandle) => void;
+    readonly blur: (el: RichTextHandle) => void;
+};

package/dist/methods.js

@@ -0,0 +1,57 @@
+/**
+ * Background-thread command surface for `<sigx-richtext>`.
+ *
+ * Commands ride the `INVOKE_UI_METHOD` op (BG→MT, fire-and-forget — landed in
+ * lynx-runtime#145): no `main-thread:ref` worklet plumbing is needed. Return
+ * values are deliberately not part of this surface — state reconciles through
+ * the element's `bindchange`/`bindselection` events, which is the editor's
+ * single source of truth.
+ *
+ * The element handle is the ShadowElement delivered by a callback `ref`:
+ *
+ * ```tsx
+ * let el: RichTextHandle = null;
+ * <sigx-richtext ref={(e) => { el = e; }} … />
+ * RichTextMethods.toggleFormat(el, 'bold');
+ * ```
+ */
+import { OP, pushOp, scheduleFlush } from '@sigx/lynx';
+import { encodeDoc } from './model/codec.js';
+function invoke(el, method, params) {
+    if (!el)
+        return;
+    pushOp(OP.INVOKE_UI_METHOD, el.id, method, params);
+    scheduleFlush();
+}
+export const RichTextMethods = {
+    /**
+     * Replace the document. Carries the version the write was based on —
+     * native drops stale writes (`doc.v < localVersion`) and re-emits current
+     * state, and rejects writes during an active IME composition.
+     */
+    setDocument(el, doc) {
+        invoke(el, 'setDocument', { doc: encodeDoc(doc) });
+    },
+    /** Toggle an inline format over the current selection (collapsed → flips typing attributes). */
+    toggleFormat(el, type) {
+        invoke(el, 'toggleFormat', { type });
+    },
+    /** Set the block type of the paragraph(s) covering the current selection. */
+    setBlockType(el, type, level) {
+        invoke(el, 'setBlockType', { type, ...(level !== undefined ? { level } : {}) });
+    },
+    /** Insert text at the caret (inherits typing attributes). */
+    insertText(el, text) {
+        invoke(el, 'insertText', { text });
+    },
+    /** Move/extend the caret. */
+    setSelectionRange(el, start, end) {
+        invoke(el, 'setSelectionRange', { start, end });
+    },
+    focus(el) {
+        invoke(el, 'focus', {});
+    },
+    blur(el) {
+        invoke(el, 'blur', {});
+    },
+};

package/dist/model/codec.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The single JSON codec for {@link RichDoc} — used by the `value` prop,
+ * `setDocument`/`getDocument`, and `bindchange` payloads, so there is exactly
+ * one wire schema and one validation point.
+ *
+ * `decodeDoc` is defensive: malformed input degrades to an empty document
+ * rather than throwing (events from native should never crash the BG thread).
+ */
+import type { RichDoc } from './types.js';
+export declare function emptyDoc(v?: number): RichDoc;
+export declare function encodeDoc(doc: RichDoc): string;
+export declare function decodeDoc(raw: string | null | undefined): RichDoc;
+/**
+ * Structural equality, ignoring `v` — the echo-suppression comparison.
+ * (Two docs with identical content but different versions are "equal": the
+ * version exists to order writes, not to distinguish content.)
+ */
+export declare function docEquals(a: RichDoc, b: RichDoc): boolean;
+/**
+ * Normalize a doc so structurally-identical content compares equal regardless
+ * of producer ordering: spans sorted by (start, end, type), blocks by start.
+ */
+export declare function normalizeDoc(doc: RichDoc): RichDoc;

package/dist/model/codec.js

@@ -0,0 +1,123 @@
+/**
+ * The single JSON codec for {@link RichDoc} — used by the `value` prop,
+ * `setDocument`/`getDocument`, and `bindchange` payloads, so there is exactly
+ * one wire schema and one validation point.
+ *
+ * `decodeDoc` is defensive: malformed input degrades to an empty document
+ * rather than throwing (events from native should never crash the BG thread).
+ */
+export function emptyDoc(v = 0) {
+    return { text: '', spans: [], blocks: [], v };
+}
+export function encodeDoc(doc) {
+    return JSON.stringify(doc);
+}
+export function decodeDoc(raw) {
+    if (!raw)
+        return emptyDoc();
+    try {
+        const parsed = JSON.parse(raw);
+        const text = typeof parsed.text === 'string' ? parsed.text : '';
+        return {
+            text,
+            spans: sanitizeSpans(parsed.spans, text.length),
+            blocks: sanitizeBlocks(parsed.blocks, text.length),
+            v: typeof parsed.v === 'number' && Number.isFinite(parsed.v) ? parsed.v : 0,
+        };
+    }
+    catch {
+        return emptyDoc();
+    }
+}
+function sanitizeSpans(spans, max) {
+    if (!Array.isArray(spans))
+        return [];
+    const out = [];
+    for (const s of spans) {
+        if (!s || typeof s.start !== 'number' || typeof s.end !== 'number' || !s.type)
+            continue;
+        const start = clamp(s.start, 0, max);
+        const end = clamp(s.end, 0, max);
+        if (end <= start)
+            continue;
+        out.push({ start, end, type: s.type, ...(s.attrs ? { attrs: s.attrs } : {}) });
+    }
+    return out;
+}
+function sanitizeBlocks(blocks, max) {
+    if (!Array.isArray(blocks))
+        return [];
+    const out = [];
+    for (const b of blocks) {
+        if (!b || typeof b.start !== 'number' || typeof b.end !== 'number' || !b.type)
+            continue;
+        const start = clamp(b.start, 0, max);
+        const end = clamp(b.end, 0, max);
+        if (end < start)
+            continue;
+        out.push({
+            start,
+            end,
+            type: b.type,
+            ...(b.level !== undefined ? { level: b.level } : {}),
+            ...(b.checked !== undefined ? { checked: b.checked } : {}),
+        });
+    }
+    return out;
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, Math.floor(n)));
+}
+/**
+ * Structural equality, ignoring `v` — the echo-suppression comparison.
+ * (Two docs with identical content but different versions are "equal": the
+ * version exists to order writes, not to distinguish content.)
+ */
+export function docEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a.text !== b.text)
+        return false;
+    if (a.spans.length !== b.spans.length || a.blocks.length !== b.blocks.length)
+        return false;
+    for (let i = 0; i < a.spans.length; i++) {
+        const x = a.spans[i];
+        const y = b.spans[i];
+        if (x.start !== y.start || x.end !== y.end || x.type !== y.type)
+            return false;
+        if (!attrsEqual(x.attrs, y.attrs))
+            return false;
+    }
+    for (let i = 0; i < a.blocks.length; i++) {
+        const x = a.blocks[i];
+        const y = b.blocks[i];
+        if (x.start !== y.start || x.end !== y.end || x.type !== y.type ||
+            x.level !== y.level || x.checked !== y.checked)
+            return false;
+    }
+    return true;
+}
+function attrsEqual(a, b) {
+    if (a === b)
+        return true;
+    const ka = a ? Object.keys(a) : [];
+    const kb = b ? Object.keys(b) : [];
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka)
+        if (a[k] !== b?.[k])
+            return false;
+    return true;
+}
+/**
+ * Normalize a doc so structurally-identical content compares equal regardless
+ * of producer ordering: spans sorted by (start, end, type), blocks by start.
+ */
+export function normalizeDoc(doc) {
+    return {
+        text: doc.text,
+        spans: [...doc.spans].sort((a, b) => a.start - b.start || a.end - b.end || a.type.localeCompare(b.type)),
+        blocks: [...doc.blocks].sort((a, b) => a.start - b.start),
+        v: doc.v,
+    };
+}

package/dist/model/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The rich document model — the single data shape that crosses the JS↔native
+ * bridge for `<sigx-richtext>`.
+ *
+ * Design invariants (load-bearing — native code on both platforms relies on
+ * them):
+ *
+ * - **Flat text + ranges, not a tree.** `NSAttributedString` (iOS) and
+ *   `Spannable` (Android) are natively a flat string with attribute ranges, so
+ *   this model maps 1:1 onto the platform primitives with no tree walking.
+ * - **UTF-16 code-unit offsets everywhere.** JS strings, `NSRange`, and
+ *   Android `CharSequence` all index by UTF-16 code units, so no index
+ *   translation happens at any boundary. (Surrogate pairs — emoji — count
+ *   as 2; producers must never split one.)
+ * - **`blocks` ranges align to line boundaries** (`\n`-separated). Producers
+ *   normalize; native re-snaps defensively.
+ * - **Native never parses markdown.** Markdown ↔ RichDoc conversion lives in
+ *   `@sigx/lynx-markdown`; this package is markdown-agnostic.
+ * - **`v` is a monotonic version.** Every native-side user edit bumps it;
+ *   `setDocument` carries the version the write was based on so native can
+ *   drop stale writes (see the IME/echo rules in the package README).
+ */
+/** Inline character-range formats. `link` carries `attrs.href`; `mention` is an atomic chip with `attrs.id`/`attrs.label`. */
+export type InlineSpanType = 'bold' | 'italic' | 'strike' | 'code' | 'link' | 'mention';
+export interface InlineSpan {
+    /** Inclusive start, UTF-16 code units. */
+    start: number;
+    /** Exclusive end, UTF-16 code units. */
+    end: number;
+    type: InlineSpanType;
+    /** Type-specific payload (`href` for links, `id`/`label` for mentions). */
+    attrs?: Record<string, string>;
+}
+/**
+ * Paragraph-level block types. MVP renders `paragraph` + `heading`; the rest
+ * are reserved (P2/P3). `raw` is a consumer escape hatch (e.g. lynx-markdown
+ * keeps unmodeled markdown source verbatim in a raw block) — native renders it
+ * as a plain paragraph and round-trips the attr untouched.
+ */
+export type BlockAttrType = 'paragraph' | 'heading' | 'bullet' | 'ordered' | 'task' | 'blockquote' | 'codeBlock' | 'raw';
+export interface BlockAttr {
+    /** Inclusive start of the paragraph's char range (line boundary). */
+    start: number;
+    /** Exclusive end (line boundary / end of text). */
+    end: number;
+    type: BlockAttrType;
+    /** Heading level 1–6 (heading only). */
+    level?: number;
+    /** Task checkbox state (task only). */
+    checked?: boolean;
+}
+export interface RichDoc {
+    text: string;
+    spans: InlineSpan[];
+    blocks: BlockAttr[];
+    /** Monotonic document version (see module docs). */
+    v: number;
+}
+/** `bindchange` — fired after every user edit (and after applied programmatic mutations). */
+export interface RichTextChangeEvent {
+    type: 'change';
+    detail: {
+        /** JSON-encoded {@link RichDoc} (decode with `decodeDoc`). */
+        doc: string;
+        /** True while an IME composition session is active — do NOT echo writes back. */
+        isComposing: boolean;
+    };
+}
+/** `bindselection` — caret/selection moved. Drives toolbar active state + popup anchoring. */
+export interface RichTextSelectionEvent {
+    type: 'selection';
+    detail: {
+        start: number;
+        end: number;
+        /** Comma-separated inline formats covering the selection (or the typing attributes when collapsed), e.g. `"bold,italic"`. */
+        activeFormats: string;
+        /** Block type of the caret's paragraph. */
+        activeBlock: string;
+        /** Heading level when `activeBlock === 'heading'`. */
+        headingLevel?: number;
+        /** Caret rectangle in the element's own coordinate space (popup anchoring). */
+        caretX: number;
+        caretY: number;
+        caretHeight: number;
+    };
+}
+/** `bindheightchange` — intrinsic content height changed (auto-grow). */
+export interface RichTextHeightChangeEvent {
+    type: 'heightchange';
+    detail: {
+        /** Content height in px (may exceed the clamped frame height). */
+        height: number;
+        /** Line count. */
+        lines: number;
+    };
+}
+export interface RichTextFocusEvent {
+    type: 'focus' | 'blur';
+    detail: Record<string, never>;
+}
+/** Parsed form of `bindselection`'s detail (after `activeFormats` is split). */
+export interface SelectionState {
+    start: number;
+    end: number;
+    activeFormats: InlineSpanType[];
+    activeBlock: BlockAttrType;
+    headingLevel?: number;
+    caretRect: {
+        x: number;
+        y: number;
+        height: number;
+    };
+}

package/dist/model/types.js

@@ -0,0 +1,23 @@
+/**
+ * The rich document model — the single data shape that crosses the JS↔native
+ * bridge for `<sigx-richtext>`.
+ *
+ * Design invariants (load-bearing — native code on both platforms relies on
+ * them):
+ *
+ * - **Flat text + ranges, not a tree.** `NSAttributedString` (iOS) and
+ *   `Spannable` (Android) are natively a flat string with attribute ranges, so
+ *   this model maps 1:1 onto the platform primitives with no tree walking.
+ * - **UTF-16 code-unit offsets everywhere.** JS strings, `NSRange`, and
+ *   Android `CharSequence` all index by UTF-16 code units, so no index
+ *   translation happens at any boundary. (Surrogate pairs — emoji — count
+ *   as 2; producers must never split one.)
+ * - **`blocks` ranges align to line boundaries** (`\n`-separated). Producers
+ *   normalize; native re-snaps defensively.
+ * - **Native never parses markdown.** Markdown ↔ RichDoc conversion lives in
+ *   `@sigx/lynx-markdown`; this package is markdown-agnostic.
+ * - **`v` is a monotonic version.** Every native-side user edit bumps it;
+ *   `setDocument` carries the version the write was based on so native can
+ *   drop stale writes (see the IME/echo rules in the package README).
+ */
+export {};