@effect-tui/core 0.1.0-alpha.1

package/src/ui/shinytext.ts

@@ -0,0 +1,159 @@
+/* shinytext.ts — reusable shining text component */
+
+import type { Palette, Surface } from "../render/surface.js"
+import { Colors } from "../render/surface.js"
+import type { Rect } from "./core/geometry.js"
+import { Step, type Stepper } from "../anim.js"
+import { View } from "./core/view.js"
+
+export type ShineTextOptions = {
+  /**
+   * Center position of the shine in character coordinates (can be fractional).
+   * 0 = before first char, length-1 = last char. Values outside are fine for overscan.
+   */
+  center?: number
+  /**
+   * Alternative to center: normalized progress 0..1 across the text.
+   * If provided, takes precedence and maps to center internally.
+   */
+  progress?: number
+  /** Gaussian falloff spread; larger = wider shine. Default 2.25 */
+  spread?: number
+  /** Base gray level (0..23). Default 12 */
+  baseGray?: number
+  /** Max additional gray levels added at peak (0..23). Default 8 */
+  boost?: number
+  /** Bold threshold on intensity (0..1). Default 0.75 */
+  boldThreshold?: number
+}
+
+export class ShinyText extends View {
+  constructor(
+    readonly text: string,
+    readonly opts?: ShineTextOptions,
+  ) {
+    super()
+  }
+
+  private getChars(): string[] {
+    return [...this.text]
+  }
+
+  protected measureContent(maxW: number, _maxH: number) {
+    const w = Math.min(maxW, this.getChars().length)
+    return { w, h: 1 }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    const chars = this.getChars()
+    const n = Math.min(rect.w, chars.length)
+    if (rect.h <= 0 || n <= 0) return
+
+    const spread = this.opts?.spread ?? 2.25
+    const base = Math.max(0, Math.min(23, (this.opts?.baseGray ?? 12) | 0))
+    const boost = Math.max(0, Math.min(23, (this.opts?.boost ?? 8) | 0))
+    const boldTh = this.opts?.boldThreshold ?? 0.75
+
+    const progress = this.opts?.progress
+    const center = progress != null ? progress * (chars.length - 1) : (this.opts?.center ?? 0)
+
+    const styleFor = (i: number) => {
+      const d = (i - center) / Math.max(1e-3, spread)
+      const intensity = Math.exp(-d * d)
+      const level = Math.max(0, Math.min(23, base + Math.round(intensity * boost)))
+      const bold = intensity > boldTh
+      return pal.id({ fg: Colors.gray(level), bold })
+    }
+
+    // Emit minimal runs per style id
+    const y = rect.y
+    let x = rect.x
+    let runStyle = -1
+    let runStart = x
+    let runText = ""
+    const flush = () => {
+      if (runText.length > 0) {
+        const maxW = Math.max(0, rect.x + rect.w - runStart)
+        if (maxW > 0) s.drawText(runStart, y, runText, runStyle, maxW)
+        runText = ""
+      }
+    }
+    for (let i = 0; i < n; i++) {
+      const ch = chars[i]
+      const id = styleFor(i)
+      if (id !== runStyle) {
+        flush()
+        runStyle = id
+        runStart = x
+      }
+      runText += ch
+      x++
+    }
+    flush()
+  }
+}
+
+// Optional builder contribution for the View object
+export type ViewShinyTextExt = {
+  shineText(text: string, opts?: ShineTextOptions): View
+}
+export const viewShinyText: ViewShinyTextExt = {
+  shineText(text: string, opts?: ShineTextOptions): View {
+    return new ShinyText(text, opts)
+  },
+}
+
+// ----------------------------------------------------------------------------
+// Stateful convenience API (init/tick/setSpeed + node factory)
+// ----------------------------------------------------------------------------
+
+export type ShinyTextModel = {
+  text: string
+  step: Stepper
+  speedMs: number
+  overscan: number
+  shine?: Omit<ShineTextOptions, "center" | "progress">
+}
+
+export type InitShinyOptions = {
+  speedMs?: number
+  overscan?: number
+  shine?: Omit<ShineTextOptions, "center" | "progress">
+}
+
+export function initShinyText(text: string, opts?: InitShinyOptions): ShinyTextModel {
+  const speedMs = Math.max(1, (opts?.speedMs ?? 40) | 0)
+  const overscan = Math.max(0, (opts?.overscan ?? 6) | 0)
+  const width = [...text].length
+  const step = Step.init(width + overscan * 2, speedMs, 0)
+  return { text, step, speedMs, overscan, shine: opts?.shine }
+}
+
+export function tickShinyText(state: ShinyTextModel, nowMs: number): ShinyTextModel {
+  const step = Step.tick(state.step, nowMs)
+  return { ...state, step }
+}
+
+export function setShinySpeed(state: ShinyTextModel, speedMs: number): ShinyTextModel {
+  const ms = Math.max(1, speedMs | 0)
+  const step = { ...state.step, intervalMs: ms }
+  return { ...state, speedMs: ms, step }
+}
+
+/** Create a ShinyText node from state. Use with chainers like .frame/.padding. */
+export function shinyText(state: ShinyTextModel): View {
+  const center = state.step.index - state.overscan
+  return new ShinyText(state.text, { ...state.shine, center })
+}
+
+// Merged namespace to expose a cohesive API: ShinyText.make(), ShinyText.tick(), ShinyText.setSpeed(), ShinyText.view()
+export namespace ShinyText {
+  export type Model = ShinyTextModel
+  export type Options = ShineTextOptions
+  export type MakeOptions = InitShinyOptions
+
+  export const make = initShinyText
+  export const tick = tickShinyText
+  export const setSpeed = setShinySpeed
+  export const view = shinyText
+}

package/src/ui/text/layout.ts

@@ -0,0 +1,119 @@
+/* text/layout.ts — Shared text layout utilities for wrapping and caret mapping
+ *
+ * Single source of truth for:
+ * - Computing wrapped visual lines (first-line width vs subsequent)
+ * - Mapping between grapheme cursor index and visual caret coordinates
+ * - Mapping from visual cell X back to cursor index (for vertical nav)
+ *
+ * These helpers mirror renderer behavior by delegating to render/measure.ts
+ * (displayWidth, graphemes, sliceByWidth), ensuring edit-time and render-time
+ * wrapping boundaries are identical.
+ */
+
+import { displayWidth, graphemes, sliceByWidth } from "../../render/measure.js"
+
+export type WrappedLine = { text: string; graphemes: string[]; start: number; width: number }
+export type Wrapped = { lines: Array<WrappedLine> }
+
+export type WrapOptions = {
+  widthFirst: number
+  widthOther: number
+  wordWrap: boolean
+  breakWords: boolean
+}
+
+/** Compute wrapped lines with widths and grapheme start offsets (soft + hard breaks). */
+export function wrapText(value: string, opts: WrapOptions): Wrapped {
+  const lines: Array<{ graphemes: string[]; start: number; width: number }> = []
+  const widthFor = (isFirstVisual: boolean) => Math.max(0, isFirstVisual ? opts.widthFirst : opts.widthOther)
+
+  let gOffset = 0 // grapheme index from start of whole value
+  let isFirstVisual = true
+
+  // Split logical lines by explicit newlines
+  const logicals = value.split("\n")
+  for (let li = 0; li < logicals.length; li++) {
+    const logical = logicals[li]
+    let rest = logical
+    // Even for empty logical lines, emit one visual line (empty)
+    if (rest.length === 0) {
+      lines.push({ graphemes: [], start: gOffset, width: 0 })
+      if (li < logicals.length - 1) gOffset += 1 // the "\n" grapheme
+      isFirstVisual = false
+      continue
+    }
+    while (rest.length > 0) {
+      const maxW = widthFor(isFirstVisual)
+      const { text } = sliceByWidth(rest, maxW)
+      const used = text.length > 0 ? text : rest.slice(0, 1) // ensure progress even when maxW == 0
+      const usedGs = graphemes(used)
+      const w = displayWidth(used)
+      lines.push({ graphemes: usedGs, start: gOffset, width: w })
+      gOffset += usedGs.length
+      rest = rest.slice(used.length)
+      isFirstVisual = false
+      if (used.length === 0) break
+    }
+    if (li < logicals.length - 1) gOffset += 1 // account for newline between logical segments
+  }
+  return { lines: lines.map((l) => ({ ...l, text: l.graphemes.join("") })) }
+}
+
+/** Locate the visual line and column within that line for a grapheme cursor. */
+export function findVisualPos(wrap: Wrapped, cursor: number): { lineIdx: number; colInLine: number } {
+  for (let i = 0; i < wrap.lines.length; i++) {
+    const ln = wrap.lines[i]
+    const start = ln.start
+    // Use next line's start as upper bound (accounts for newline gaps)
+    const nextStart = i + 1 < wrap.lines.length ? wrap.lines[i + 1].start : Infinity
+
+    // Cursor in range [start, nextStart) belongs to this line
+    if (cursor >= start && cursor < nextStart) {
+      // For empty lines, cursor must be exactly at start
+      if (ln.graphemes.length === 0) {
+        return { lineIdx: i, colInLine: 0 }
+      }
+      const col = Math.min(cursor - start, ln.graphemes.length)
+      return { lineIdx: i, colInLine: col }
+    }
+  }
+  // Fallback: end of last line
+  const last = wrap.lines[wrap.lines.length - 1]
+  return { lineIdx: wrap.lines.length - 1, colInLine: last.graphemes.length }
+}
+
+/** Sum display widths of graphemes up to a column to get visual cell X. */
+export function cellXWithinLine(wrap: Wrapped, lineIdx: number, colInLine: number): number {
+  const ln = wrap.lines[lineIdx]
+  const gs = ln.graphemes
+  let x = 0
+  for (let i = 0; i < Math.min(colInLine, gs.length); i++) x += displayWidth(gs[i])
+  return x
+}
+
+/** Map a visual cell X back to a cursor index on a given line (nearest-left by centers). */
+export function cursorFromCellX(wrap: Wrapped, lineIdx: number, x: number): number {
+  const ln = wrap.lines[lineIdx]
+  const gs = ln.graphemes
+  let acc = 0
+  for (let i = 0; i < gs.length; i++) {
+    const w = displayWidth(gs[i])
+    const center = acc + w / 2
+    if (x < center) return ln.start + i
+    acc += w
+  }
+  return ln.start + gs.length
+}
+
+/** Map cursor index to absolute caret coordinates using provided anchors. */
+export function caretXYFromCursor(
+  wrap: Wrapped,
+  cursor: number,
+  anchors: { xFirst: number; xOther: number },
+): { x: number; y: number } {
+  const { lineIdx, colInLine } = findVisualPos(wrap, cursor)
+  const baseX = lineIdx === 0 ? anchors.xFirst : anchors.xOther
+  const x = baseX + cellXWithinLine(wrap, lineIdx, colInLine)
+  const y = lineIdx
+  return { x, y }
+}