@sigx/lynx-richtext 0.4.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+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,95 @@
+# @sigx/lynx-richtext
+
+A **native rich-text input element** for Lynx: `<sigx-richtext>` wraps
+`UITextView` (iOS) and `EditText` (Android) with attributed-text editing —
+bold is bold *inside* the editable field. It powers `@sigx/lynx-markdown`'s
+`MarkdownEditor`, but is markdown-agnostic and usable on its own.
+
+## The document model
+
+A flat, span-based `RichDoc` crosses the bridge — it maps 1:1 onto
+`NSAttributedString` / `Spannable` (UTF-16 offsets everywhere, zero index
+translation):
+
+```ts
+interface RichDoc {
+  text: string;                 // flat text, '\n' separates paragraphs
+  spans: InlineSpan[];          // {start, end, type: 'bold'|'italic'|'strike'|'code'|'link'|'mention', attrs?}
+  blocks: BlockAttr[];          // paragraph ranges: {start, end, type: 'paragraph'|'heading'|…, level?}
+  v: number;                    // monotonic version (echo/stale-write protection)
+}
+```
+
+Native never parses markdown; after every edit it **reads the model back out of
+its own text storage** (explicit marker attributes/spans, so a heading's bold
+font never reads back as a `bold` span) and emits the full doc.
+
+## Use
+
+```tsx
+import { RichTextInput, RichTextMethods, type RichTextHandle } from '@sigx/lynx-richtext';
+
+let el: RichTextHandle = null;
+
+<RichTextInput
+  placeholder="Write something…"
+  minHeight={40}
+  maxHeight={160}
+  onElement={(handle) => { el = handle; }}
+  onChange={(doc, isComposing) => { /* doc is a decoded RichDoc */ }}
+  onSelection={(sel) => { /* sel.activeFormats drives toolbar state */ }}
+  onHeightChange={(h) => { /* auto-grow: set the element's style height */ }}
+/>;
+
+// Commands are fire-and-forget (BG → MT via the INVOKE_UI_METHOD op);
+// state reconciles through the next bindchange/bindselection.
+RichTextMethods.toggleFormat(el, 'bold');
+RichTextMethods.setBlockType(el, 'heading', 2);
+RichTextMethods.insertText(el, '🎉');
+```
+
+## IME / echo contract
+
+1. Every user edit bumps the doc version; `bindchange` carries it.
+2. `setDocument` with structurally-identical content is a silent no-op.
+3. `setDocument` based on a stale version is dropped; current state re-emits.
+4. `setDocument` during an active IME composition is dropped (composition
+   would be corrupted); `bindchange` flags `isComposing` so callers never echo
+   mid-composition.
+
+Prefer the **lightly-controlled** pattern: don't echo keystrokes back — treat
+the element as the source of truth for live text and push `setDocument` only
+for genuine programmatic mutations (load, clear-on-send, block changes).
+
+## Beyond markdown
+
+The element has **no serialization format of its own** — `RichDoc` is plain
+`text + spans + blocks`, and what those *mean* is the consumer's choice.
+`@sigx/lynx-markdown`'s `MarkdownEditor` is one consumer (its `mdToDoc` /
+`docToMd` converters give the doc markdown semantics), but the same element
+backs, for example:
+
+- a styled chat/comment input that stores the **doc JSON directly** (no
+  text format at all — render it back with the same spans);
+- an editor that serializes to **HTML**, Slack-style mrkdwn, or a custom
+  wire format — write the two converters, the rest is identical;
+- a plain input that only uses auto-grow + IME-safe programmatic writes,
+  ignoring formatting entirely.
+
+The constraint is the **vocabulary**, not the format: v1 ships a fixed set of
+span types (`bold` / `italic` / `strike` / `code` / `link` / `mention`) and
+block types (`paragraph` / `heading` / … / `raw`). Custom mark types arrive
+with the editor plugin API (P3).
+
+## v1 scope
+
+Inline: bold / italic / strike / code / link (render + toggle + typing-edge
+inheritance). Blocks: paragraph + headings (1–3 styled; 4–6 fall back to a
+smaller scale). Auto-height reporting (`bindheightchange`) with
+`min-height`/`max-height` clamping and internal scroll past the ceiling.
+Reserved in the model for follow-ups: lists/quote/codeBlock rendering, atomic
+mention chips, task checkboxes.
+
+Native code is autolinked by `sigx prebuild` (`signalx-module.json` →
+`ios.uiComponents` / `android.behaviors`); run a native rebuild after adding
+the package.

package/android/com/sigx/richtext/DocumentMapper.kt

@@ -0,0 +1,148 @@
+package com.sigx.richtext
+
+import android.graphics.Color
+import android.text.Spannable
+import android.text.SpannableStringBuilder
+import android.text.Spanned
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** Theme knobs shared by the spans (colors resolved on the UI side). */
+data class RichTextTheme(
+    var fontSizePx: Float = 0f, // 0 → leave EditText default
+    var textColor: Int = Color.BLACK,
+    var accentColor: Int = Color.parseColor("#3478F6"),
+    var codeBackground: Int = Color.parseColor("#1F7F7F7F"), // ~12% gray
+)
+
+/**
+ * RichDoc (JSON) ↔ Spannable mapping. Readback enumerates only the sigx marker
+ * spans (see [SigxSpans.kt]) so the model is unambiguous; native storage is
+ * authoritative after every edit.
+ */
+object DocumentMapper {
+
+    /** Inline span flag: typing at the trailing edge extends the format. */
+    const val INLINE_FLAGS: Int = Spanned.SPAN_EXCLUSIVE_INCLUSIVE
+
+    data class Parsed(val text: SpannableStringBuilder, val version: Int)
+
+    /** Parse a JSON RichDoc. Returns null when unparseable. */
+    fun parse(json: String, theme: RichTextTheme): Parsed? {
+        val obj = try { JSONObject(json) } catch (_: Exception) { return null }
+        val text = obj.optString("text", "")
+        val builder = SpannableStringBuilder(text)
+        val max = builder.length
+
+        val spans: JSONArray = obj.optJSONArray("spans") ?: JSONArray()
+        for (i in 0 until spans.length()) {
+            val span = spans.optJSONObject(i) ?: continue
+            val start = span.optInt("start", -1).coerceIn(0, max)
+            val end = span.optInt("end", -1).coerceIn(0, max)
+            if (end <= start) continue
+            val attrs = span.optJSONObject("attrs")
+            val mark: Any? = when (span.optString("type")) {
+                "bold" -> SigxBoldSpan()
+                "italic" -> SigxItalicSpan()
+                "strike" -> SigxStrikeSpan()
+                "code" -> SigxCodeSpan(theme.codeBackground)
+                "link" -> SigxLinkSpan(attrs?.optString("href") ?: "", theme.accentColor)
+                "mention" -> SigxMentionSpan(attrs.toStringMap(), theme.accentColor)
+                else -> null
+            }
+            if (mark != null) builder.setSpan(mark, start, end, INLINE_FLAGS)
+        }
+
+        val blocks: JSONArray = obj.optJSONArray("blocks") ?: JSONArray()
+        for (i in 0 until blocks.length()) {
+            val block = blocks.optJSONObject(i) ?: continue
+            val type = block.optString("type")
+            if (type.isEmpty() || type == "paragraph") continue
+            val start = block.optInt("start", -1).coerceIn(0, max)
+            val end = block.optInt("end", -1).coerceIn(0, max)
+            if (end < start) continue
+            val snapped = snapToParagraph(builder, start, end)
+            builder.setSpan(
+                SigxBlockSpan(type, block.optInt("level", 0), block.optBoolean("checked", false)),
+                snapped.first,
+                snapped.second,
+                Spanned.SPAN_PARAGRAPH,
+            )
+        }
+
+        return Parsed(builder, obj.optInt("v", 0))
+    }
+
+    /** Read the model back out of live storage → JSON RichDoc. */
+    fun encode(text: Spannable, version: Int): String {
+        val doc = JSONObject()
+        doc.put("text", text.toString())
+
+        val spans = JSONArray()
+        fun add(start: Int, end: Int, type: String, attrs: JSONObject? = null) {
+            if (end <= start) return
+            val entry = JSONObject()
+            entry.put("start", start)
+            entry.put("end", end)
+            entry.put("type", type)
+            if (attrs != null) entry.put("attrs", attrs)
+            spans.put(entry)
+        }
+
+        for (span in text.getSpans(0, text.length, SigxBoldSpan::class.java)) {
+            add(text.getSpanStart(span), text.getSpanEnd(span), "bold")
+        }
+        for (span in text.getSpans(0, text.length, SigxItalicSpan::class.java)) {
+            add(text.getSpanStart(span), text.getSpanEnd(span), "italic")
+        }
+        for (span in text.getSpans(0, text.length, SigxStrikeSpan::class.java)) {
+            add(text.getSpanStart(span), text.getSpanEnd(span), "strike")
+        }
+        for (span in text.getSpans(0, text.length, SigxCodeSpan::class.java)) {
+            add(text.getSpanStart(span), text.getSpanEnd(span), "code")
+        }
+        for (span in text.getSpans(0, text.length, SigxLinkSpan::class.java)) {
+            add(
+                text.getSpanStart(span), text.getSpanEnd(span), "link",
+                JSONObject().put("href", span.href),
+            )
+        }
+        for (span in text.getSpans(0, text.length, SigxMentionSpan::class.java)) {
+            val attrs = JSONObject()
+            for ((k, v) in span.attrs) attrs.put(k, v)
+            add(text.getSpanStart(span), text.getSpanEnd(span), "mention", attrs)
+        }
+        doc.put("spans", spans)
+
+        val blocks = JSONArray()
+        for (span in text.getSpans(0, text.length, SigxBlockSpan::class.java)) {
+            val entry = JSONObject()
+            entry.put("start", text.getSpanStart(span))
+            entry.put("end", text.getSpanEnd(span))
+            entry.put("type", span.type)
+            if (span.level > 0) entry.put("level", span.level)
+            if (span.type == "task") entry.put("checked", span.checked)
+            blocks.put(entry)
+        }
+        doc.put("blocks", blocks)
+        doc.put("v", version)
+        return doc.toString()
+    }
+
+    /** Snap [start, end) to enclosing line boundaries (SPAN_PARAGRAPH requirement). */
+    fun snapToParagraph(text: CharSequence, start: Int, end: Int): Pair<Int, Int> {
+        var s = start.coerceIn(0, text.length)
+        var e = end.coerceIn(s, text.length)
+        while (s > 0 && text[s - 1] != '\n') s--
+        while (e < text.length && text[e] != '\n') e++
+        if (e < text.length) e++ // include the trailing newline, paragraph-span style
+        return s to e
+    }
+
+    private fun JSONObject?.toStringMap(): Map<String, String> {
+        if (this == null) return emptyMap()
+        val out = mutableMapOf<String, String>()
+        for (key in keys()) out[key] = optString(key)
+        return out
+    }
+}

package/android/com/sigx/richtext/RichEditText.kt

@@ -0,0 +1,41 @@
+package com.sigx.richtext
+
+import android.content.Context
+import android.view.Gravity
+import android.widget.EditText
+
+/**
+ * `EditText` subclass backing `<sigx-richtext>`.
+ *
+ * Adds a selection-change callback (EditText has no listener for it) and a
+ * content-height helper for auto-grow reporting. Chip-aware deletion hooks
+ * land in P3.
+ */
+class RichEditText(context: Context) : EditText(context) {
+
+    var onSelectionChangedCallback: ((start: Int, end: Int) -> Unit)? = null
+
+    init {
+        background = null
+        gravity = Gravity.TOP or Gravity.START
+        setPadding(0, dp(8), 0, dp(8))
+        // Text color stays at the platform default (textColorPrimary, which
+        // tracks the system light/dark theme) unless the `text-color` prop
+        // overrides it.
+        isVerticalScrollBarEnabled = true
+    }
+
+    override fun onSelectionChanged(selStart: Int, selEnd: Int) {
+        super.onSelectionChanged(selStart, selEnd)
+        onSelectionChangedCallback?.invoke(selStart, selEnd)
+    }
+
+    /** Intrinsic content height (px) for the current width. */
+    fun contentHeight(): Int {
+        val l = layout ?: return paddingTop + paddingBottom + lineHeight
+        return l.height + paddingTop + paddingBottom
+    }
+
+    private fun dp(value: Int): Int =
+        (value * resources.displayMetrics.density).toInt()
+}

package/android/com/sigx/richtext/SigxRichTextBehavior.kt

@@ -0,0 +1,18 @@
+package com.sigx.richtext
+
+import com.lynx.tasm.behavior.Behavior
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.behavior.ui.LynxUI
+
+/**
+ * Registers the `<sigx-richtext>` JSX tag with Lynx's UI registry.
+ *
+ * Discovered by the autolinker via `signalx-module.json`'s `android.behaviors`;
+ * the generated `GeneratedBehaviors.attachAll(builder)` adds this behavior to
+ * every `LynxViewBuilder` in the app.
+ */
+class SigxRichTextBehavior : Behavior("sigx-richtext") {
+    override fun createUI(context: LynxContext): LynxUI<*> {
+        return SigxRichTextUI(context)
+    }
+}