@citisen/litearea 0.1.0

package/src/core/vocabulary.ts

@@ -0,0 +1,196 @@
+// ─── vocabulary: the four facts that must agree ─────────────────────────────
+//
+// A closed set of words appears four times in a language-aware editor: as the
+// syntax that accepts it, as the colour it is painted in, as the message a typo
+// earns, and as the documentation a hover shows. Written out four times they
+// drift — a word added to the parser and forgotten by the highlighter is the
+// ordinary way a grammar rots — and the drift is invisible until someone types
+// the new word and watches the editor get it wrong.
+//
+// So they are declared once. `defineVocabulary` returns an object the engine
+// already knows how to consume: hand it to a `words` rule and it paints, accepts,
+// rejects, and documents without being mentioned again.
+//
+//     const SHAPES = defineVocabulary({
+//       id: 'shape',
+//       words: ['circle', 'rounded', 'square', 'none'],
+//       unknownMessage: '"{word}" is not a shape — expected one of {allowed}.',
+//       docs: { circle: 'A full disc, the background for a busy state.' },
+//     })
+//
+//     { kind: 'words', words: SHAPES }
+
+import type {
+  ResolvedVocabulary,
+  Scope,
+  Severity,
+  VocabularyContext,
+  VocabularyEntry,
+  WordsSource,
+} from './types.js'
+import { fillTemplate, listPhrase } from './format.js'
+
+/** What a vocabulary is told about the document it is being resolved for. */
+export interface VocabularySpec<State = unknown> {
+  /** A stable id, used in the diagnostic code and for debugging. */
+  id: string
+  /**
+   * The members.
+   *
+   * A function is how a set that lives outside the document reaches the grammar
+   * without the grammar holding mutable state: the installed fonts, the states
+   * the host actually has. It is called once per scan.
+   */
+  words: readonly string[] | ((context: VocabularyContext<State>) => readonly string[])
+  /** The scope a member is painted with. Defaults to `vocabulary:<id>`. */
+  scope?: Scope | ((word: string) => Scope)
+  /** The scope a rejected word is painted with. Defaults to `'invalid'`. */
+  unknownScope?: Scope
+  /**
+   * The message a rejected word earns.
+   *
+   * Present, a word-shaped token outside the set is reported; absent, it is
+   * reported by nobody and the grammar is the poorer for it. `{word}` and
+   * `{allowed}` are substituted, the latter as a readable list.
+   */
+  unknownMessage?: string | ((word: string, allowed: readonly string[]) => string)
+  /** How loudly a rejected word complains. Default `'error'`. */
+  unknownSeverity?: Severity
+  /** A stable code for the rejection. Defaults to `vocabulary:<id>`. */
+  unknownCode?: string
+  /**
+   * What each member explains about itself, for hover. A bare string is taken as
+   * the body.
+   */
+  docs?: Readonly<Record<string, string | VocabularyEntry>>
+  /** A dimmed line shown beside a member in the completion list. */
+  detail?: (word: string) => string | undefined
+  /** Whether membership is case-sensitive. Default `false`. */
+  caseSensitive?: boolean
+  /**
+   * How a member is written into the document when it is accepted.
+   *
+   * Separate from the word itself because a member is not always insertable as
+   * typed: a font family containing a space has to be quoted, even though the
+   * vocabulary calls it `IBM Plex Mono`.
+   */
+  format?: (word: string) => string
+}
+
+/**
+ * Build a vocabulary: the set, its colour, its rejection, and its documentation.
+ * @param spec - the declaration.
+ * @returns a resolved vocabulary, ready for a `words` rule.
+ */
+export function defineVocabulary<State = unknown>(
+  spec: VocabularySpec<State>,
+): ResolvedVocabulary<State> {
+  const caseSensitive = spec.caseSensitive === true
+  const unknownScope = spec.unknownScope ?? 'invalid'
+  const defaultScope = `vocabulary:${spec.id}`
+  const unknownCode = spec.unknownCode ?? `vocabulary:${spec.id}`
+  const unknownSeverity = spec.unknownSeverity ?? 'error'
+  /** Fold a word for lookup, honouring the vocabulary's case rule. */
+  const fold = (word: string): string => (caseSensitive ? word : word.toLowerCase())
+  /** Find the member a word names, preserving the declared spelling. */
+  const memberOf = (word: string, allowed: readonly string[]): string | undefined => {
+    const needle = fold(word)
+    return allowed.find((candidate) => fold(candidate) === needle)
+  }
+  /** The declaration for one member, whichever of the two shapes it took. */
+  const docOf = (word: string): VocabularyEntry | undefined => {
+    if (spec.docs === undefined) return undefined
+    for (const [key, value] of Object.entries(spec.docs)) {
+      if (fold(key) !== fold(word)) continue
+      return typeof value === 'string' ? { body: value } : value
+    }
+    return undefined
+  }
+
+  return {
+    id: spec.id,
+    caseSensitive,
+    resolve: (context) => {
+      const words = typeof spec.words === 'function' ? spec.words(context) : spec.words
+      return Array.isArray(words) ? words : []
+    },
+    has: (word, context) => {
+      const words = typeof spec.words === 'function' ? spec.words(context) : spec.words
+      return memberOf(word, Array.isArray(words) ? words : []) !== undefined
+    },
+    scopeFor: (word) => {
+      if (typeof spec.scope === 'function') return spec.scope(memberOf(word, [word]) ?? word)
+      return spec.scope ?? defaultScope
+    },
+    unknownScope,
+    reject: (word, context) => {
+      if (spec.unknownMessage === undefined) return undefined
+      const allowed = typeof spec.words === 'function' ? spec.words(context) : spec.words
+      const members = Array.isArray(allowed) ? allowed : []
+      const message =
+        typeof spec.unknownMessage === 'function'
+          ? spec.unknownMessage(word, members)
+          : fillTemplate(spec.unknownMessage, {
+              word,
+              allowed: listPhrase(members, { conjunction: 'or' }),
+            })
+      return { message, severity: unknownSeverity, code: unknownCode }
+    },
+    entryFor: (word) => docOf(word),
+    format: (word) => (spec.format === undefined ? word : spec.format(word)),
+  }
+}
+
+/**
+ * The members of a vocabulary, resolved for a document.
+ *
+ * A helper for the common case of a caller that has a vocabulary and wants its
+ * words, without reaching through to `resolve` and re-supplying the context.
+ * @param vocabulary - a resolved vocabulary.
+ * @param context - the document it is being resolved for.
+ * @returns the members, in declaration order.
+ */
+export function vocabularyWords<State>(
+  vocabulary: ResolvedVocabulary<State>,
+  context: VocabularyContext<State>,
+): readonly string[] {
+  return vocabulary.resolve(context)
+}
+
+/**
+ * Recognize a vocabulary among the shapes a `WordsSource` may take.
+ *
+ * The test is structural rather than `instanceof`, so a grammar may hand over its
+ * own object as long as it carries the four facts — which is what lets a host
+ * wrap a vocabulary in logging, caching, or a translation layer without the
+ * engine needing to know.
+ * @param source - a words source.
+ * @returns the vocabulary, or undefined when the source is a bare list or function.
+ */
+export function asResolvedVocabulary<State>(
+  source: WordsSource<State>,
+): ResolvedVocabulary<State> | undefined {
+  if (typeof source !== 'object' || source === null || Array.isArray(source)) return undefined
+  const candidate = source as { resolve?: unknown }
+  return typeof candidate.resolve === 'function' ? (source as ResolvedVocabulary<State>) : undefined
+}
+
+/**
+ * The members any words source stands for, whichever shape it took.
+ * @param source - a bare list, a vocabulary, or a function.
+ * @param context - the document it is being resolved for.
+ * @returns the members, or an empty list when the source resolved to nothing.
+ */
+export function resolveWordsSource<State>(
+  source: WordsSource<State>,
+  context: VocabularyContext<State>,
+): readonly string[] {
+  const vocabulary = asResolvedVocabulary(source)
+  const raw =
+    vocabulary !== undefined
+      ? vocabulary.resolve(context)
+      : typeof source === 'function'
+        ? source(context)
+        : source
+  return Array.isArray(raw) ? raw.filter((word) => word !== '') : []
+}

package/src/dom/create.ts

@@ -0,0 +1,31 @@
+// ─── create: the one-line entry point ───────────────────────────────────────
+//
+// The class exists for a host that wants to hold the instance and drive it. This
+// exists for the far more common case of wanting an editor in an element and not
+// much else.
+
+import { LiteArea, type LiteAreaOptions } from './editor.js'
+
+/**
+ * Build an editor and put it in an element.
+ *
+ * The `refresh` after mounting is not a formality. A textarea that is not in the
+ * document has no layout, so it has no width, so nothing can be measured against it
+ * — and a measurement taken then is not merely imprecise, it wraps the text at every
+ * character and comes back several times too tall. The editor's own
+ * `ResizeObserver` would correct it on the next frame, which means one frame of a box
+ * at the wrong height. Measuring again here, synchronously, means the first frame is
+ * already right.
+ * @param target - where to mount it. Its contents are appended to, not replaced.
+ * @param options - the grammar, the initial text, and the behaviour to use.
+ * @returns the editor, so the caller can drive it.
+ */
+export function createEditor<State = unknown>(
+  target: Element,
+  options: LiteAreaOptions<State>,
+): LiteArea<State> {
+  const editor = new LiteArea(options)
+  target.appendChild(editor.element)
+  editor.refresh()
+  return editor
+}

package/src/dom/editing.ts

@@ -0,0 +1,213 @@
+// ─── editing: changing a textarea without breaking its history ──────────────
+//
+// This is the module the whole library exists to get right.
+//
+// A textarea owns its own undo stack, and that stack is maintained by the
+// browser's editing pipeline — not by the value property. Assigning to
+// `field.value` replaces the text and DESTROYS the history, which is why a
+// controlled component that round-trips every keystroke through React state (or a
+// state setter of any kind) has no working Ctrl+Z. It also resets the caret to the
+// end, which is the other half of the same mistake.
+//
+// So the editor never writes `value` for an edit the user could have made. It
+// moves the selection and asks the browser to insert text, which the browser
+// records as one undoable edit:
+//
+//     field.setSelectionRange(from, to)
+//     document.execCommand('insertText', false, text)   // ← undoable
+//
+// `execCommand` is deprecated, and there is no replacement. A synthetic
+// `beforeinput` or `InputEvent` is untrusted, so the browser will not run it
+// through the editing pipeline; `setRangeText` is the standard API and bypasses
+// the history entirely. Every editor that supports undo on a textarea uses this
+// call. Where it is missing the edit still happens through `setRangeText`, and the
+// caller is told plainly that the history did not get it, so a host can decide
+// whether that matters.
+
+import { clamp } from '../core/text.js'
+import { canEditThroughPipeline } from './support.js'
+
+/** A caret or selection, as offsets into the value. */
+export interface TextSelection {
+  /** The anchor end. Equal to `end` for a caret. */
+  start: number
+  /** The moving end. */
+  end: number
+}
+
+/**
+ * How an edit reached the document.
+ *
+ * `pipeline` means the browser recorded it and Ctrl+Z will undo it. `direct` means
+ * the text changed and the history did not, which only happens where
+ * `document.execCommand` is unavailable — a test environment, or a browser that
+ * has finally removed it.
+ */
+export type EditOutcome = 'pipeline' | 'direct' | 'unchanged'
+
+/** Read the caret or selection out of a field. */
+export function readSelection(field: HTMLTextAreaElement): TextSelection {
+  const start = field.selectionStart ?? 0
+  const end = field.selectionEnd ?? start
+  return { start, end }
+}
+
+/**
+ * Put a caret or selection into a field.
+ *
+ * Setting a selection moves the caret and nothing else: it does not touch the
+ * value, so it cannot disturb the undo stack. This is what the editor uses instead
+ * of re-rendering text to reposition the caret — the re-render was the bug.
+ *
+ * A range given the wrong way round is ordered rather than collapsed. `start` and
+ * `end` are named for a caret and a selection, and a caller that computes them from a
+ * backwards drag has still asked for that text to be selected; quietly selecting
+ * nothing at the far end would be a silent wrong answer.
+ * @param field - the textarea.
+ * @param start - the anchor offset.
+ * @param end - the moving offset; defaults to `start`.
+ */
+export function writeSelection(
+  field: HTMLTextAreaElement,
+  start: number,
+  end: number = start,
+): void {
+  const length = field.value.length
+  const from = clamp(Math.min(start, end), 0, length)
+  const to = clamp(Math.max(start, end), from, length)
+  field.setSelectionRange(from, to)
+}
+
+/** The line height in force on a field, falling back to the computed font size. */
+export function fieldLineHeight(field: HTMLTextAreaElement): number {
+  const styles = field.ownerDocument.defaultView?.getComputedStyle(field)
+  if (styles === null || styles === undefined) return 0
+  const lineHeight = Number.parseFloat(styles.lineHeight)
+  if (Number.isFinite(lineHeight)) return lineHeight
+  const fontSize = Number.parseFloat(styles.fontSize)
+  return Number.isFinite(fontSize) ? fontSize * 1.2 : 0
+}
+
+/**
+ * Replace a range through the browser's editing pipeline, so it can be undone.
+ *
+ * The field is focused first because the pipeline only runs on the focused
+ * element, and a completion accepted by mouse click would otherwise arrive after
+ * the click had already blurred the field.
+ * @param field - the textarea.
+ * @param from - the first offset to replace.
+ * @param to - the offset after the last.
+ * @param text - what to put there. The empty string deletes.
+ * @returns how the edit landed.
+ */
+export function replaceThroughPipeline(
+  field: HTMLTextAreaElement,
+  from: number,
+  to: number,
+  text: string,
+): EditOutcome {
+  const start = clamp(Math.min(from, to), 0, field.value.length)
+  const end = clamp(Math.max(from, to), start, field.value.length)
+  if (start === end && text === '') return 'unchanged'
+
+  if (field.ownerDocument.activeElement !== field) field.focus({ preventScroll: true })
+  writeSelection(field, start, end)
+
+  const before = field.value
+  if (canEditThroughPipeline()) {
+    try {
+      field.ownerDocument.execCommand('insertText', false, text)
+    } catch {
+      // Firefox throws rather than returning false for some input types. Falling
+      // through to the direct path is the right answer either way.
+    }
+    // The return value is not trustworthy across browsers, and it does not need to
+    // be: the VALUE decides. A change we did not make ourselves is one the
+    // browser's history already knows about, which is the whole point.
+    if (field.value !== before) return 'pipeline'
+  }
+
+  field.setRangeText(text, start, end, 'end')
+  if (field.value === before) return 'unchanged'
+  dispatchInput(field, text)
+  return 'direct'
+}
+
+/**
+ * Fire the event the browser would have fired, for the direct path only.
+ *
+ * The pipeline path needs no help: the browser dispatches `input` itself, which is
+ * exactly why the editor can treat both paths the same way downstream.
+ * @param field - the textarea.
+ * @param text - what was written.
+ */
+export function dispatchInput(field: HTMLTextAreaElement, text: string): void {
+  const view = field.ownerDocument.defaultView
+  const InputEventCtor = view === null ? undefined : (view as Window & { InputEvent?: typeof InputEvent }).InputEvent
+  if (typeof InputEventCtor === 'function') {
+    field.dispatchEvent(
+      new InputEventCtor('input', { bubbles: true, inputType: 'insertText', data: text }),
+    )
+    return
+  }
+  field.dispatchEvent(new Event('input', { bubbles: true }))
+}
+
+/**
+ * Undo, through the browser's own history.
+ *
+ * Exposed so a host can offer a button without reimplementing a stack, and so the
+ * browser harness can drive the same path a keyboard shortcut drives.
+ * @param field - the textarea.
+ * @returns whether the call was possible at all. It cannot report whether anything
+ *   was actually undone, because no browser exposes that.
+ */
+export function undoField(field: HTMLTextAreaElement): boolean {
+  if (!canEditThroughPipeline()) return false
+  if (field.ownerDocument.activeElement !== field) field.focus({ preventScroll: true })
+  try {
+    return field.ownerDocument.execCommand('undo')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Redo, through the browser's own history.
+ * @param field - the textarea.
+ * @returns whether the call was possible at all.
+ */
+export function redoField(field: HTMLTextAreaElement): boolean {
+  if (!canEditThroughPipeline()) return false
+  if (field.ownerDocument.activeElement !== field) field.focus({ preventScroll: true })
+  try {
+    return field.ownerDocument.execCommand('redo')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Write a whole document into a field.
+ *
+ * Two paths, and the difference matters. `preserveHistory` selects everything and
+ * inserts through the pipeline, so the replacement is one undoable edit and Ctrl+Z
+ * brings the previous text back — the right behaviour for a Reset button. Without
+ * it the value property is assigned, which is faster and clears the history, which
+ * is the right behaviour when a host is loading a different document entirely.
+ * @param field - the textarea.
+ * @param next - the new text.
+ * @param preserveHistory - whether the change should be undoable.
+ * @returns how the write landed.
+ */
+export function writeDocument(
+  field: HTMLTextAreaElement,
+  next: string,
+  preserveHistory = false,
+): EditOutcome {
+  if (field.value === next) return 'unchanged'
+  if (preserveHistory) return replaceThroughPipeline(field, 0, field.value.length, next)
+  field.value = next
+  writeSelection(field, next.length, next.length)
+  return 'direct'
+}