@citisen/litearea 0.1.0

package/src/core/segments.ts

@@ -0,0 +1,185 @@
+// ─── segments: one pass over the document, for the painter ──────────────────
+//
+// The painted layer has to cover every character exactly once, in order, and it
+// has to do it while three independent things want to say something about those
+// characters: the scope that colours them, the decoration that marks them, and the
+// diagnostic that underlines them.
+//
+// The naive way is three layers, and it does not work. Each would have to position
+// its spans itself, so each would need its own idea of where a range starts, and a
+// span positioned by measuring is a span that drifts as soon as the font, the
+// wrapping, or the padding is even slightly different from what was measured.
+//
+// So they are merged into ONE stream of adjacent segments, and the renderer emits
+// them back to back with no positioning at all: the characters lay out where the
+// characters lay out, and the colours follow. Alignment stops being something the
+// code maintains and becomes something the layout cannot get wrong.
+//
+// This is pure — text and ranges in, segments out — which is why the trickiest
+// part of the painter is testable without a browser.
+
+import type { Decoration, Diagnostic, Severity, Token } from './types.js'
+
+/** One run of characters that all share the same presentation. */
+export interface PaintSegment {
+  from: number
+  to: number
+  /** The characters themselves, so the painter never re-slices. */
+  text: string
+  /** The scope that colours them. */
+  scope: string
+  /** The decoration kinds that mark them, in declaration order. */
+  decorations: string[]
+  /** The loudest diagnostic covering them, when one does. */
+  severity: Severity | undefined
+  /** A hover title donated by a decoration, when it has one. */
+  title: string | undefined
+}
+
+/** What a segment builder needs: the three range lists and nothing else. */
+export interface SegmentInput {
+  tokens: readonly Token[]
+  decorations: readonly Decoration[]
+  diagnostics: readonly Diagnostic[]
+}
+
+/**
+ * The order severities outrank each other.
+ *
+ * One segment shows one squiggle, because two underlines on the same characters
+ * only make a messier line rather than a more informative one. The loudest wins,
+ * which is also the one a reader needs to see first.
+ */
+const SEVERITY_RANK: Record<Severity, number> = { error: 4, warning: 3, info: 2, hint: 1 }
+
+/**
+ * Merge a scope, a decoration, and a diagnostic into adjacent segments.
+ *
+ * @param text - the document the ranges refer to.
+ * @param input - the three range lists.
+ * @param fallbackScope - the scope for characters no token covers.
+ * @returns the segments, in order, covering the whole document.
+ */
+export function buildSegments(
+  text: string,
+  input: SegmentInput,
+  fallbackScope = 'text',
+): PaintSegment[] {
+  const length = text.length
+  if (length === 0) return []
+
+  // ── the cut points ────────────────────────────────────────────────────────
+  // Every range boundary is a potential change of presentation, so they are the
+  // only places a segment can begin or end.
+  const cuts = new Set<number>([0, length])
+  for (const token of input.tokens) {
+    cuts.add(Math.max(0, Math.min(token.from, length)))
+    cuts.add(Math.max(0, Math.min(token.to, length)))
+  }
+  for (const decoration of input.decorations) {
+    cuts.add(Math.max(0, Math.min(decoration.from, length)))
+    cuts.add(Math.max(0, Math.min(decoration.to, length)))
+  }
+  for (const diagnostic of input.diagnostics) {
+    cuts.add(Math.max(0, Math.min(diagnostic.from, length)))
+    cuts.add(Math.max(0, Math.min(diagnostic.to, length)))
+  }
+  const bounds = [...cuts].sort((left, right) => left - right)
+
+  const segments: PaintSegment[] = []
+  for (let index = 0; index < bounds.length - 1; index += 1) {
+    const from = bounds[index] ?? 0
+    const to = bounds[index + 1] ?? 0
+    if (to <= from) continue
+
+    const scope = coverScope(input.tokens, from, fallbackScope)
+    const decorations = coverDecorations(input.decorations, from, to)
+    const severity = coverSeverity(input.diagnostics, from, to)
+    const title = input.decorations.find(
+      (decoration) => decoration.title !== undefined && from >= decoration.from && to <= decoration.to,
+    )?.title
+
+    const last = segments[segments.length - 1]
+    if (
+      last !== undefined &&
+      last.scope === scope &&
+      last.severity === severity &&
+      last.title === title &&
+      sameList(last.decorations, decorations)
+    ) {
+      // Extending the previous segment keeps the DOM small without changing what
+      // is drawn, which is the only reason the merge exists.
+      last.to = to
+      last.text = text.slice(last.from, to)
+      continue
+    }
+    segments.push({ from, to, text: text.slice(from, to), scope, decorations, severity, title })
+  }
+  return segments
+}
+
+/** The scope of the token covering a position, or the fallback. */
+function coverScope(tokens: readonly Token[], offset: number, fallback: string): string {
+  for (const token of tokens) {
+    if (token.from > offset) break
+    if (offset >= token.from && offset < token.to) return token.scope
+  }
+  return fallback
+}
+
+/** The decoration kinds covering a range, in the order they were declared. */
+function coverDecorations(decorations: readonly Decoration[], from: number, to: number): string[] {
+  const kinds: string[] = []
+  for (const decoration of decorations) {
+    if (decoration.from <= from && to <= decoration.to) kinds.push(decoration.kind)
+  }
+  return kinds
+}
+
+/** The loudest diagnostic severity covering a range. */
+function coverSeverity(
+  diagnostics: readonly Diagnostic[],
+  from: number,
+  to: number,
+): Severity | undefined {
+  let loudest: Severity | undefined
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.from > from || diagnostic.to < to) continue
+    if (loudest === undefined || SEVERITY_RANK[diagnostic.severity] > SEVERITY_RANK[loudest]) {
+      loudest = diagnostic.severity
+    }
+  }
+  return loudest
+}
+
+/** Whether two short lists say the same thing, in the same order. */
+function sameList(left: readonly string[], right: readonly string[]): boolean {
+  if (left.length !== right.length) return false
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false
+  }
+  return true
+}
+
+/**
+ * The class attribute for a segment.
+ *
+ * Order matters for a stylesheet author's sanity rather than for the cascade: the
+ * scope comes first so a rule can target `scope + mark` if it ever needs to.
+ * @param segment - the segment.
+ * @param scopeClass - how a scope becomes a class.
+ * @param decorationClass - how a decoration kind becomes a class.
+ * @param severityClass - how a severity becomes a class.
+ * @returns the class list.
+ */
+export function segmentClasses(
+  segment: PaintSegment,
+  scopeClass: (scope: string) => string,
+  decorationClass: (kind: string) => string,
+  severityClass: (severity: string) => string,
+): string[] {
+  const classes = [scopeClass(segment.scope)]
+  for (const kind of segment.decorations) classes.push(decorationClass(kind))
+  if (segment.severity !== undefined) classes.push(severityClass(segment.severity))
+  return classes
+}

package/src/core/text.ts

@@ -0,0 +1,238 @@
+// ─── text: offsets, lines, and words ────────────────────────────────────────
+//
+// The engine counts in character offsets and nothing else. Not rows, not
+// columns, not pixels: every position that crosses a module boundary in litearea
+// is an offset into the document string, so there is exactly one coordinate
+// system to get wrong instead of three that must be kept in step.
+//
+// Pixels enter only in `src/dom/`, only to place the popup, and never travel
+// back inward. That boundary is the fix for a whole family of bugs in the
+// editors this library replaces, where a caret was tracked as a character index
+// in one place and read back as a screen position in another.
+
+import type { LineInfo, Range, Token, WordInfo } from './types.js'
+
+/** Keeps a number inside a range, which every caller here needs and none should repeat. */
+export function clamp(value: number, low: number, high: number): number {
+  return value < low ? low : value > high ? high : value
+}
+
+/** Whether a value is a usable offset: a finite, non-negative integer. */
+export function isOffset(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0
+}
+
+/**
+ * The offset each line starts at, in order. The first entry is always `0`.
+ *
+ * `\r\n`, `\n`, and a lone `\r` all end a line, because this text is typed by
+ * hand into a textarea and a paste from a Windows editor must not read as one
+ * long line. The terminator itself belongs to no line: a line's text excludes it
+ * so that column arithmetic never has to reason about a stray carriage return.
+ * @param source - the document.
+ * @returns one offset per line, ascending.
+ */
+export function lineStarts(source: string): number[] {
+  const starts = [0]
+  for (let index = 0; index < source.length; index += 1) {
+    const code = source.charCodeAt(index)
+    if (code === 10) {
+      starts.push(index + 1)
+    } else if (code === 13) {
+      if (source.charCodeAt(index + 1) === 10) index += 1
+      starts.push(index + 1)
+    }
+  }
+  return starts
+}
+
+/**
+ * The index of the line an offset falls on.
+ * @param starts - the result of {@link lineStarts}.
+ * @param offset - a character offset.
+ * @returns a zero-based line index.
+ */
+export function lineIndexAt(starts: readonly number[], offset: number): number {
+  let low = 0
+  let high = starts.length - 1
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2)
+    if ((starts[middle] ?? 0) <= offset) low = middle
+    else high = middle - 1
+  }
+  return low
+}
+
+/**
+ * The line an offset falls on, with the offset expressed inside it.
+ *
+ * `before` and `after` are the line's own text split at the caret, which is what
+ * completion and the indentation rules actually want; handing them out here
+ * means neither has to re-derive the split and get it subtly different.
+ * @param source - the document.
+ * @param offset - a character offset; clamped into the document.
+ * @param starts - the result of {@link lineStarts}, when the caller already has it.
+ * @returns the line, its bounds, and the caret's place in it.
+ */
+export function lineAt(source: string, offset: number, starts?: readonly number[]): LineInfo {
+  const position = clamp(offset, 0, source.length)
+  const boundaries = starts ?? lineStarts(source)
+  const index = lineIndexAt(boundaries, position)
+  const from = boundaries[index] ?? 0
+  const rawTo = boundaries[index + 1] ?? source.length
+  // The next line's start sits after the terminator, so the last character of
+  // the raw slice is the terminator itself — one character, or two for `\r\n`.
+  let to = rawTo
+  while (to > from) {
+    const code = source.charCodeAt(to - 1)
+    if (code === 10 || code === 13) to -= 1
+    else break
+  }
+  const text = source.slice(from, to)
+  const column = clamp(position - from, 0, text.length)
+  return {
+    from,
+    to,
+    text,
+    number: index,
+    column,
+    before: text.slice(0, column),
+    after: text.slice(column),
+  }
+}
+
+/**
+ * Whether a character is part of a word.
+ *
+ * The predicate is supplied by the grammar because it decides three things at
+ * once — what a completion replaces, what a diagnostic underlines, and where a
+ * double click puts the selection — and a language whose names contain a hyphen
+ * must say so or every completion will replace one segment of a name instead of
+ * the name.
+ * @param char - one character, or the empty string at the end of the document.
+ * @param wordChars - a single-character test.
+ * @returns whether the character continues a word.
+ */
+export function isWordChar(char: string, wordChars: RegExp): boolean {
+  return char !== '' && wordChars.test(char)
+}
+
+/**
+ * The word at an offset.
+ *
+ * The word is found by expanding in BOTH directions from the offset rather than
+ * by requiring the offset to be strictly inside a word. Completion needs the
+ * second reading: a caret sitting at `Geist|` is at the end of the word, and the
+ * word it is completing is still `Geist` — a lookup that insisted the offset be
+ * interior would find nothing at exactly the moment the user wants a list.
+ * @param source - the document.
+ * @param offset - a character offset; clamped into the document.
+ * @param wordChars - a single-character test.
+ * @returns the word, its range, and the text either side of the caret.
+ */
+export function wordInfoAt(source: string, offset: number, wordChars: RegExp): WordInfo {
+  const position = clamp(offset, 0, source.length)
+  let from = position
+  let to = position
+  while (from > 0 && isWordChar(source.charAt(from - 1), wordChars)) from -= 1
+  while (to < source.length && isWordChar(source.charAt(to), wordChars)) to += 1
+  const text = source.slice(from, to)
+  const column = position - from
+  return {
+    from,
+    to,
+    text,
+    prefix: text.slice(0, column),
+    suffix: text.slice(column),
+  }
+}
+
+/** Whether a range is empty. */
+export function isEmptyRange(range: Range): boolean {
+  return range.to <= range.from
+}
+
+/** Whether an offset lies inside a range, with `to` exclusive. */
+export function containsOffset(range: Range, offset: number): boolean {
+  return offset >= range.from && offset < range.to
+}
+
+// ─── reading the token stream ───────────────────────────────────────────────
+
+/**
+ * The token covering an offset.
+ *
+ * Zero-length tokens are skipped, so a caret at a boundary resolves to the token
+ * it is *inside* rather than to an empty marker sitting on the seam.
+ * @param tokens - the scanned tokens, ascending.
+ * @param offset - a character offset.
+ * @returns the covering token, or undefined in whitespace.
+ */
+export function tokenAt(tokens: readonly Token[], offset: number): Token | undefined {
+  for (const token of tokens) {
+    if (token.from <= offset && offset < token.to) return token
+    if (token.from > offset) break
+  }
+  return undefined
+}
+
+/**
+ * The scope painted at an offset, when there is one.
+ * @param tokens - the scanned tokens, ascending.
+ * @param offset - a character offset.
+ * @returns the scope, or undefined in whitespace.
+ */
+export function scopeAt(tokens: readonly Token[], offset: number): string | undefined {
+  return tokenAt(tokens, offset)?.scope
+}
+
+/**
+ * The nearest token that ends at or before an offset, skipping whitespace.
+ *
+ * Whitespace is skipped because every caller is asking a question about
+ * structure — "which slot is this word in?" — and a space is never an answer.
+ * @param tokens - the scanned tokens, ascending.
+ * @param offset - a character offset.
+ * @returns the token, or undefined at the start of the document.
+ */
+export function tokenBefore(tokens: readonly Token[], offset: number): Token | undefined {
+  let found
+  for (const token of tokens) {
+    if (token.to > offset) break
+    if (token.text.trim() !== '') found = token
+  }
+  return found
+}
+
+/**
+ * The nearest token that starts at or after an offset, skipping whitespace.
+ * @param tokens - the scanned tokens, ascending.
+ * @param offset - a character offset.
+ * @returns the token, or undefined at the end of the document.
+ */
+export function tokenAfter(tokens: readonly Token[], offset: number): Token | undefined {
+  for (const token of tokens) {
+    if (token.to <= offset) continue
+    if (token.text.trim() !== '') return token
+  }
+  return undefined
+}
+
+/**
+ * The non-whitespace tokens on one line, in order.
+ *
+ * Completion and diagnostics both ask "what is on this line so far", and both
+ * must ignore the indentation and the gaps between words. Returning the tokens
+ * rather than the words means a grammar can ask what they *were* (their scopes)
+ * and not only what they said.
+ * @param tokens - the scanned tokens, ascending.
+ * @param line - a line number, or a line record.
+ * @returns the tokens on that line.
+ */
+export function tokensOnLine(
+  tokens: readonly Token[],
+  line: number | LineInfo,
+): Token[] {
+  const number = typeof line === 'number' ? line : line.number
+  return tokens.filter((token) => token.line === number && token.text.trim() !== '')
+}