@solidrt/core 0.0.49 → 0.0.51

package/src/runtime-modules.d.ts

@@ -88,8 +88,9 @@ declare module "srt:dev" {
   /**
    * Register a named debug command, listable and callable from the dev server
    * (the list_debug / call_debug MCP tools). `args` arrives JSON-parsed; the
-   * return value must be JSON-serializable and synchronous (promises are not
-   * awaited). Re-registering a name replaces it; registrations reset on hot
+   * return value must be JSON-serializable and synchronous (an async command's
+   * Promise is not awaited - the call errors). Re-registering a name replaces
+   * it; registrations reset on hot
    * reload, so register at module init. Callable in every build, but only dev
    * clients ever invoke commands.
    */

package/src/scroll.ts

@@ -2,7 +2,7 @@
 // scrollable region -- the offset and its clamping against the measured content
 // and viewport sizes -- and nothing with a UI opinion. Wheel/drag input,
 // momentum, scrollbars and styling are policy and belong to the component (the
-// "skin") that composes this, the same way createCaretScroll backs TextInput.
+// "skin") that composes this, the same way createTextEditorLayout backs TextInput.
 
 import { createSignal, flush } from "@solidjs/signals"
 import { getBoundingBox } from "./core"

package/src/text-input.ts

@@ -1,11 +1,12 @@
 // Headless text-input mechanism. These primitives own the objective parts of
-// an editable single-line field -- the value buffer (text + caret/selection)
-// and the scroll-to-caret geometry -- and nothing with a UI opinion. Caret
-// blink, keybindings, placeholder and styling are policy and belong to the
-// component (the "skin") that composes these.
+// an editable field -- the value buffer (text + caret/selection) and the line
+// and caret geometry with the scroll that keeps the caret in view -- and
+// nothing with a UI opinion. Caret blink, keybindings, placeholder and styling
+// are policy and belong to the component (the "skin") that composes these.
 
-import { createSignal, flush } from "@solidjs/signals"
-import { getBoundingBox, measureText } from "./core"
+import { createMemo, createSignal, flush, untrack } from "@solidjs/signals"
+import { getBoundingBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
+import type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
 import { onLayout } from "./window"
 
 /**
@@ -31,6 +32,20 @@ export type TextBufferOptions = {
   onInput?: (value: string) => void
   /** Max length; inserts past it are clamped. */
   maxLength?: () => number | undefined
+  /**
+   * The offset one caret step left/right of `offset` in `text`: what a
+   * single Left/Right, Backspace or Delete moves over. Defaults to one code
+   * unit, which splits surrogate pairs and combining marks; an editor with
+   * grapheme geometry (createTextEditorLayout.step) supplies the real one.
+   */
+  step?: (text: string, offset: number, direction: "left" | "right") => number
+  /**
+   * Called before every edit with the range it replaces and the text going
+   * in (already clamped to maxLength), for owners that keep parallel state
+   * over the text (a rich text document's attributed runs). setValue/clear
+   * report a whole-text replace.
+   */
+  onReplace?: (start: number, end: number, text: string) => void
 }
 
 export type TextBuffer = {
@@ -71,8 +86,10 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
   let initial = options.defaultValue ?? ""
   let [internalValue, setInternalValue] = createSignal(initial)
   // The caret starts at the end of the current text: for a controlled buffer
-  // that is the owner's value, which defaultValue does not reflect.
-  let initialCaret = (options.value?.() ?? initial).length
+  // that is the owner's value, which defaultValue does not reflect. A
+  // one-shot read by design, so untracked (the buffer is created in a
+  // component body, where a bare reactive read is flagged).
+  let initialCaret = untrack(() => options.value?.() ?? initial).length
   let [selectionState, setSelectionState] = createSignal<Selection>({
     anchor: initialCaret,
     focus: initialCaret,
@@ -94,18 +111,26 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
 
   let setCaret = (offset: number) => setSelectionState({ anchor: offset, focus: offset })
 
-  // Apply a text edit and place the caret, clamping to maxLength. The flush
+  let step = (text: string, offset: number, direction: "left" | "right"): number => {
+    if (options.step) return Math.max(0, Math.min(options.step(text, offset, direction), text.length))
+    return direction === "left" ? Math.max(0, offset - 1) : Math.min(text.length, offset + 1)
+  }
+
+  // Every edit is a replace of [start, end) by `text`, caret after it. The
+  // inserted text is clamped to what maxLength leaves room for. The flush
   // commits the writes (including a controlled owner's from onInput) before
   // returning: edits must observe each other within one task, because event
   // bursts can dispatch several handlers with no microtask between them
   // (Android IME input arrives as backspace+commit bursts; see
   // okf/backlog/event-burst-stale-signal-reads.md).
-  let apply = (next: string, caret: number) => {
+  let replace = (start: number, end: number, text: string) => {
+    let v = value()
     let max = options.maxLength?.()
-    if (max != null && next.length > max) next = next.slice(0, max)
-    caret = Math.min(caret, next.length)
+    if (max != null) text = text.slice(0, Math.max(0, max - (v.length - (end - start))))
+    options.onReplace?.(start, end, text)
+    let next = v.slice(0, start) + text + v.slice(end)
     if (options.value?.() == null) setInternalValue(next)
-    setCaret(caret)
+    setCaret(start + text.length)
     options.onInput?.(next)
     flush()
   }
@@ -116,23 +141,21 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
     caret: () => selection().focus,
 
     insertText: (text) => {
-      let v = value()
       let [start, end] = range()
-      apply(v.slice(0, start) + text + v.slice(end), start + text.length)
+      replace(start, end, text)
     },
 
     deleteBackward: () => {
-      let v = value()
       let [start, end] = range()
-      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
-      else if (start > 0) apply(v.slice(0, start - 1) + v.slice(start), start - 1)
+      if (start !== end) replace(start, end, "")
+      else if (start > 0) replace(step(value(), start, "left"), start, "")
     },
 
     deleteForward: () => {
       let v = value()
       let [start, end] = range()
-      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
-      else if (end < v.length) apply(v.slice(0, end) + v.slice(end + 1), end)
+      if (start !== end) replace(start, end, "")
+      else if (end < v.length) replace(end, step(v, end, "right"), "")
     },
 
     move: (direction, opts) => {
@@ -146,8 +169,8 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
         return
       }
       let next = focus
-      if (direction === "left") next = Math.max(0, focus - 1)
-      else if (direction === "right") next = Math.min(len, focus + 1)
+      if (direction === "left") next = step(value(), focus, "left")
+      else if (direction === "right") next = step(value(), focus, "right")
       else if (direction === "start") next = 0
       else if (direction === "end") next = len
       setSelectionState({ anchor: extend ? anchor : next, focus: next })
@@ -160,62 +183,276 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
       flush()
     },
 
-    setValue: (next) => apply(next, next.length),
-    clear: () => apply("", 0),
+    setValue: (next) => replace(0, value().length, next),
+    clear: () => replace(0, value().length, ""),
   }
 }
 
-export type CaretScrollInput = {
+export type TextEditorLayoutInput = {
   text: string
-  fontSize: number
-  /** Caret offset into `text`. Defaults to the text end. */
-  caret?: number
+  font: MeasureTextOptions
+  /** Styled ranges over `text` (prepareText `runs`): the geometry then follows per-run fonts. */
+  runs?: TextRunRange[]
+  /** Caret offset into `text`. */
+  caret: number
   /** Px reserved so the caret stays visible at the viewport edge. Default 0. */
   caretWidth?: number
+  /** Break lines at the viewport width; else one line per hard break. */
+  wrap: boolean
+}
+
+/** One drawn line of an editor: `text.slice(start, end)` at `y`, `height` tall. */
+export type EditorLine = {
+  start: number
+  end: number
+  y: number
+  height: number
+  /** Ink width. */
+  width: number
+}
+
+/** The caret's box in content coordinates (before scroll). */
+export type CaretRect = { x: number; y: number; height: number }
+
+export type TextEditorLayout = {
+  lines(): EditorLine[]
+  caret(): CaretRect
+  /** Index into lines() of the line the caret sits on. */
+  caretLine(): number
+  /** The caret position (grapheme boundary) on line `line` nearest to content x. */
+  offsetAtX(line: number, x: number): number
+  /** Index of the line at content y (clamped to the first/last line). */
+  lineAtY(y: number): number
+  /** The caret position one grapheme left/right of `offset`; a break sequence is one step. For createTextBuffer's `step`. */
+  step(offset: number, direction: "left" | "right"): number
+  scrollX(): number
+  scrollY(): number
 }
 
 /**
- * Returns the horizontal scroll offset that keeps the caret within the viewport
- * node. The offset is retained between frames and only adjusted when the caret
- * would fall outside the visible range (scrolled left when the caret runs past
- * the right edge, right when it moves before the left edge), so stationary text
- * does not jump. The viewport width and offset are computed in onLayout and the
- * synchronous flush drains the update before paint, so the scroll tracks a caret
- * or width change in the same frame. Pure geometry: no caret rendering and no
+ * The line and caret geometry of an editable text, plus the scroll offsets
+ * that keep the caret within the viewport node. Lines come from prepareText
+ * (with caret stops) + layoutNextLine at the viewport width (or unbounded
+ * when not wrapping) and are drawn by the caller, one d-text per line. A unit
+ * wider than the wrap width is split into its graphemes first, so long
+ * unbroken text wraps instead of overflowing. An empty text, or one ending in
+ * a hard break, still gets a (blank) last line to sit the caret on. Caret
+ * positions are the units' grapheme stops: the caret x, the nearest position
+ * to an x, and a caret step all come from the same shaping that is drawn.
+ *
+ * The scroll offsets are retained between frames and only adjusted when the
+ * caret would fall outside the visible range, so stationary text does not
+ * jump. The viewport size is read in onLayout and the synchronous flush
+ * drains the update before paint, so lines and scroll track a caret, text or
+ * size change in the same frame. Pure geometry: no caret rendering and no
  * placeholder/visual policy.
  */
-export function createCaretScroll(
+export function createTextEditorLayout(
   viewport: () => { id: number } | undefined,
-  input: () => CaretScrollInput,
-): () => number {
+  input: () => TextEditorLayoutInput,
+): TextEditorLayout {
+  let [viewportSize, setViewportSize] = createSignal({ width: 0, height: 0 }, { equals: (a, b) => a.width === b.width && a.height === b.height })
   let [scrollX, setScrollX] = createSignal(0)
+  let [scrollY, setScrollY] = createSignal(0)
+
+  let prepared = createMemo(() => {
+    let { text, font, runs } = input()
+    return prepareText(text, { ...font, runs, carets: true })
+  })
+
+  // Lines carry their unit range so the caret math walks only their units.
+  type PlacedLine = EditorLine & { from: number; to: number }
+  let placed = createMemo((): { units: TextUnit[]; lines: PlacedLine[] } => {
+    let { text, font, wrap, caretWidth = 0 } = input()
+    // Wrapped lines leave room for the caret at the end of a full line, so a
+    // wrapping editor never scrolls horizontally.
+    let width = wrap ? Math.max(0, viewportSize().width - caretWidth) : Infinity
+    let units = wrap ? splitWide(prepared(), width) : prepared()
+    let out: PlacedLine[] = []
+    let y = 0
+    let cursor = 0
+    let line = layoutNextLine(units, cursor, width)
+    let hardBreak = false
+    while (line) {
+      out.push({ start: line.start, end: line.end, y, height: line.height, width: line.width, from: line.from, to: line.to })
+      y += line.height
+      hardBreak = line.hardBreak
+      line = layoutNextLine(units, line.cursor, width)
+    }
+    if (out.length === 0 || hardBreak) {
+      let height = measureText(" ", font).height
+      let n = units.units.length
+      out.push({ start: text.length, end: text.length, y, height, width: 0, from: n, to: n })
+    }
+    return { units: units.units, lines: out }
+  })
+  let lines = createMemo((): EditorLine[] => placed().lines)
+
+  // The caret stops of a line, left to right, with the pen advanced per unit;
+  // duplicates at unit seams (a unit's end is the next one's start) skipped.
+  let lineStops = (index: number): { offset: number; x: number }[] => {
+    let { units, lines } = placed()
+    let line = lines[index]
+    if (!line) return []
+    let stops: { offset: number; x: number }[] = []
+    let pen = 0
+    for (let u = line.from; u < line.to; u++) {
+      let unit = units[u]!
+      for (let stop of unit.carets ?? []) {
+        let x = pen + stop.x
+        if (stops.length && stops[stops.length - 1]!.offset === stop.offset) continue
+        stops.push({ offset: stop.offset, x })
+      }
+      pen += unit.advance
+    }
+    if (stops.length === 0) stops.push({ offset: line.start, x: 0 })
+    return stops
+  }
+
+  // The line an offset sits on: the first whose range extends past it, so an
+  // offset on a soft-wrap boundary is the start of the next line (one offset
+  // is one position; a caret does not hang after the wrap space, which would
+  // take an affinity flag). The very end of the text is on the last line.
+  let lineOf = (offset: number): number => {
+    let ls = lines()
+    for (let i = 0; i < ls.length; i++) {
+      if (offset < ls[i]!.end) return i
+    }
+    return ls.length - 1
+  }
+  let caretLine = createMemo(() => lineOf(input().caret))
+
+  // The caret sits at the last stop at or before its offset (an offset inside
+  // a grapheme, e.g. from a controlled value, snaps back).
+  let caret = createMemo((): CaretRect => {
+    let offset = input().caret
+    let index = caretLine()
+    let line = lines()[index]!
+    let x = 0
+    for (let stop of lineStops(index)) {
+      if (stop.offset > offset) break
+      x = stop.x
+    }
+    return { x, y: line.y, height: line.height }
+  })
+
+  // Only positions that show on this line are candidates: a boundary offset
+  // that displays on the next line is that line's start, not this one's end.
+  let offsetAtX = (index: number, x: number): number => {
+    let best = lines()[index]?.start ?? 0
+    let bestDistance = Infinity
+    for (let stop of lineStops(index)) {
+      if (lineOf(stop.offset) !== index) continue
+      let d = Math.abs(stop.x - x)
+      if (d < bestDistance) {
+        best = stop.offset
+        bestDistance = d
+      }
+    }
+    return best
+  }
+
+  let lineAtY = (y: number): number => {
+    let ls = lines()
+    let index = 0
+    while (index + 1 < ls.length && ls[index + 1]!.y <= y) index++
+    return index
+  }
+
+  let step = (offset: number, direction: "left" | "right"): number => {
+    let { units } = placed()
+    let text = input().text
+    if (direction === "right") {
+      for (let unit of units) {
+        if (unit.end <= offset) continue
+        for (let stop of unit.carets ?? []) if (stop.offset > offset) return stop.offset
+        // Past the unit's shaped text: over its break characters in one step.
+        return unit.end
+      }
+      return text.length
+    }
+    for (let u = units.length - 1; u >= 0; u--) {
+      let unit = units[u]!
+      if (unit.start >= offset) continue
+      let stops = unit.carets ?? []
+      for (let i = stops.length - 1; i >= 0; i--) if (stops[i]!.offset < offset) return stops[i]!.offset
+      return unit.start
+    }
+    return 0
+  }
 
   onLayout(() => {
     let node = viewport()
     if (!node) return
-    let vw = getBoundingBox(node)?.width ?? 0
-    let { text, fontSize, caret, caretWidth = 0 } = input()
-    let len = text.length
-    let c = caret == null ? len : Math.max(0, Math.min(caret, len))
-
-    let totalWidth = measureText(text, { fontSize }).width
-    let caretX = c >= len ? totalWidth : measureText(text.slice(0, c), { fontSize }).width
-    let maxScroll = Math.max(0, totalWidth + caretWidth - vw)
-
-    let cur = scrollX()
-    let next = cur
-    if (vw <= 0) {
-      next = 0
-    } else if (caretX < cur) {
-      next = caretX
-    } else if (caretX + caretWidth > cur + vw) {
-      next = caretX + caretWidth - vw
-    }
-    next = Math.max(0, Math.min(next, maxScroll))
+    let box = getBoundingBox(node)
+    setViewportSize({ width: box?.width ?? 0, height: box?.height ?? 0 })
+    flush()
+    let { width: vw, height: vh } = viewportSize()
+    let { caretWidth = 0, wrap } = input()
+    let ls = lines()
+    let contentWidth = ls.reduce((w, l) => Math.max(w, l.width), 0)
+    let last = ls[ls.length - 1]!
+    let contentHeight = last.y + last.height
+    let c = caret()
 
-    if (next !== cur) setScrollX(next)
+    setScrollX(wrap ? 0 : follow(scrollX(), c.x, caretWidth, vw, contentWidth + caretWidth))
+    setScrollY(follow(scrollY(), c.y, c.height, vh, contentHeight))
     flush()
   })
 
-  return scrollX
-}
+  return { lines, caret, caretLine, offsetAtX, lineAtY, step, scrollX, scrollY }
+}
+
+// Wrap units wider than `width` (through their glued pieces) split into one
+// unit per grapheme (from their caret stops), so the greedy breaker wraps
+// them like `<text>`'s overflowWrap "anywhere". Everything else is passed
+// through as is.
+function splitWide(prepared: PreparedText, width: number): PreparedText {
+  let all = prepared.units
+  if (!all.some((u, i) => !u.glue && unitInk(all, i) > width)) return prepared
+  let wide = false
+  let units: TextUnit[] = []
+  for (let u = 0; u < all.length; u++) {
+    let unit = all[u]!
+    if (!unit.glue) wide = unitInk(all, u) > width
+    let stops = unit.carets
+    if (!wide || !stops || stops.length <= 2) {
+      units.push(unit)
+      continue
+    }
+    for (let i = 1; i < stops.length; i++) {
+      let a = stops[i - 1]!
+      let b = stops[i]!
+      let last = i === stops.length - 1
+      let advance = last ? unit.advance - a.x : b.x - a.x
+      units.push({
+        text: prepared.text.slice(a.offset, b.offset),
+        start: a.offset,
+        end: last ? unit.end : b.offset,
+        advance,
+        width: Math.max(0, Math.min(b.x, unit.width) - a.x),
+        ascent: unit.ascent,
+        descent: unit.descent,
+        hardBreak: last && unit.hardBreak,
+        glue: i === 1 && unit.glue,
+        run: unit.run,
+        carets: [
+          { offset: a.offset, x: 0 },
+          { offset: b.offset, x: b.x - a.x },
+        ],
+      })
+    }
+  }
+  return { text: prepared.text, units }
+}
+
+// The scroll offset along one axis that keeps [pos, pos + size] within a
+// viewport of `extent`, moved only when it is out of view and clamped to the
+// content.
+function follow(current: number, pos: number, size: number, extent: number, content: number): number {
+  if (extent <= 0) return 0
+  let next = current
+  if (pos < current) next = pos
+  else if (pos + size > current + extent) next = pos + size - extent
+  return Math.max(0, Math.min(next, Math.max(0, content - extent)))
+}