@cascivo/editor 0.1.1 → 0.2.1

package/README.md

@@ -58,6 +58,21 @@ import { Highlight } from '@cascivo/editor'
 Ships small, tree-shakeable grammars: `plaintext`, `json`, `javascript`, `typescript`, `css`,
 `html`, `markdown`, `bash`. Register your own with `registerGrammar(grammar)`.
 
+### Large documents
+
+The editor edits long Markdown documents — generated docs, concatenated books, big notes —
+well past the old ~5,000-line ceiling. On every render it tokenizes only the **visible window**
+(O(viewport)) rather than the whole document, and an edit re-tokenizes only the **changed
+suffix** until the grammar state reconverges. This is the same overlay + owned-tokenizer model,
+with **zero new dependencies** and **byte-identical highlighting output** — just a persistent
+per-line state index (`LineStateIndex`) feeding a viewport-scoped `tokenizeRange`. Scrolling and
+typing stay smooth well past 50,000 lines.
+
+One trade-off: with `wrap` (soft-wrap) on, row heights are variable so DOM windowing is disabled
+and every row renders (O(n) render). Edits stay cheap, but for sustained editing of very large
+documents (≳10,000 lines) disable `wrap`. See [`PERFORMANCE.md`](./PERFORMANCE.md) for the
+measured before/after numbers and the deferred worker-offload boundary.
+
 ### Extending the editor
 
 Three bounded seams — no plugin lifecycle, no transaction filters (use a full editor

package/dist/editor.css

@@ -0,0 +1,2 @@
+@layer cascivo.component{._root_1m6ns_2{background:var(--cascivo-editor-bg);max-block-size:100%;color:var(--cascivo-editor-fg);border:1px solid var(--cascivo-editor-border);border-radius:var(--cascivo-radius-field);font-family:var(--cascivo-font-mono);font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-normal);tab-size:var(--cascivo-editor-tab-size,2);display:flex;overflow:auto}._gutter_1m6ns_17{padding-block:var(--cascivo-space-3);background:var(--cascivo-editor-gutter-bg);color:var(--cascivo-editor-gutter-fg);text-align:end;-webkit-user-select:none;user-select:none;flex:none;padding-inline-start:var(--cascivo-space-3);padding-inline-end:var(--cascivo-space-2)}._gutterLine_1m6ns_28{min-block-size:1lh;display:block}._gutterActive_1m6ns_35{inset-inline:0;top:var(--cascivo-space-3);block-size:1lh;transform:translateY(calc(var(--cascivo-editor-caret-line,0) * 1lh));background:var(--cascivo-editor-gutter-active,var(--cascivo-editor-current-line));pointer-events:none;position:absolute}._pre_1m6ns_45{min-inline-size:0;padding-block:var(--cascivo-space-3);padding-inline:var(--cascivo-space-3);white-space:pre;font:inherit;tab-size:inherit;flex:auto;margin-block:0;margin-inline:0}._code_1m6ns_57{font:inherit}._line_1m6ns_62{min-block-size:1lh;display:block}._root_1m6ns_2[data-wrap=true] ._pre_1m6ns_45{white-space:pre-wrap;word-break:break-word}._root_1m6ns_2[data-line-numbers=false] ._gutter_1m6ns_17{display:none}._plain_1m6ns_77{color:var(--cascivo-editor-fg)}._keyword_1m6ns_80{color:var(--cascivo-editor-syntax-keyword)}._string_1m6ns_83{color:var(--cascivo-editor-syntax-string)}._number_1m6ns_86{color:var(--cascivo-editor-syntax-number)}._comment_1m6ns_89{color:var(--cascivo-editor-syntax-comment);font-style:italic}._function_1m6ns_93{color:var(--cascivo-editor-syntax-function)}._type_1m6ns_96{color:var(--cascivo-editor-syntax-type)}._operator_1m6ns_99{color:var(--cascivo-editor-syntax-operator)}._punctuation_1m6ns_102{color:var(--cascivo-editor-syntax-punctuation)}._variable_1m6ns_105{color:var(--cascivo-editor-syntax-variable)}._tag_1m6ns_108{color:var(--cascivo-editor-syntax-tag)}._attr_1m6ns_111{color:var(--cascivo-editor-syntax-attr)}._regexp_1m6ns_114{color:var(--cascivo-editor-syntax-regexp)}._boolean_1m6ns_117{color:var(--cascivo-editor-syntax-boolean)}._property_1m6ns_120{color:var(--cascivo-editor-syntax-property)}._match_1m6ns_125{background:var(--cascivo-editor-match,#7dd3fc47);border-radius:2px}._matchCurrent_1m6ns_129{background:var(--cascivo-editor-match-current,#facc1580);border-radius:2px}._bracketMatch_1m6ns_133{outline:1px solid var(--cascivo-editor-bracket,currentColor);border-radius:2px}._root_18xci_2{background:var(--cascivo-editor-bg);color:var(--cascivo-editor-fg);border:1px solid var(--cascivo-editor-border);border-radius:var(--cascivo-radius-field);font-family:var(--cascivo-font-mono);font-size:var(--cascivo-text-sm);line-height:var(--cascivo-leading-normal);tab-size:var(--cascivo-editor-tab-size,2);transition:box-shadow var(--cascivo-duration-150) var(--cascivo-ease-out);display:flex;position:relative;overflow:hidden}._root_18xci_2:has(._textarea_18xci_18:focus-visible){box-shadow:var(--cascivo-focus-ring);border-color:var(--cascivo-color-accent)}._gutter_18xci_23{padding-block:var(--cascivo-space-3);background:var(--cascivo-editor-gutter-bg);color:var(--cascivo-editor-gutter-fg);text-align:end;-webkit-user-select:none;user-select:none;flex:none;padding-inline-start:var(--cascivo-space-3);padding-inline-end:var(--cascivo-space-2);position:relative;overflow:hidden}._codeArea_18xci_36{flex:auto;min-inline-size:0;position:relative}._pre_18xci_43{padding-block:var(--cascivo-space-3);padding-inline:var(--cascivo-space-3);white-space:pre;pointer-events:none;font:inherit;tab-size:inherit;margin-block:0;margin-inline:0;position:absolute;inset:0;overflow:hidden}._currentLine_18xci_58{inset-inline:0;top:var(--cascivo-space-3);block-size:1lh;transform:translateY(calc(var(--cascivo-editor-caret-line,0) * 1lh));background:var(--cascivo-editor-current-line);pointer-events:none;position:absolute}._textarea_18xci_18{block-size:100%;inline-size:100%;padding-block:var(--cascivo-space-3);padding-inline:var(--cascivo-space-3);resize:none;color:#0000;caret-color:var(--cascivo-editor-fg);white-space:pre;font:inherit;tab-size:inherit;background:0 0;border:0;outline:none;margin-block:0;margin-inline:0;position:absolute;inset:0;overflow:auto}._textarea_18xci_18::placeholder{color:var(--cascivo-editor-gutter-fg)}._textarea_18xci_18::selection{background:var(--cascivo-editor-selection)}._textarea_18xci_18:disabled{cursor:not-allowed;opacity:var(--cascivo-disabled-opacity)}._root_18xci_2[data-wrap=true] ._pre_18xci_43,._root_18xci_2[data-wrap=true] ._textarea_18xci_18{white-space:pre-wrap;word-break:break-word}._root_18xci_2[data-line-numbers=false] ._gutter_18xci_23{display:none}@media (pointer:coarse){._root_18xci_2{min-block-size:var(--cascivo-target-min-coarse,2.75rem)}}@media (prefers-reduced-motion:reduce){._root_18xci_2{transition:none}}._panel_hawkv_2{z-index:2;gap:var(--cascivo-space-1);padding:var(--cascivo-space-2);background:var(--cascivo-editor-bg);border:1px solid var(--cascivo-editor-border);border-radius:var(--cascivo-radius-field);box-shadow:var(--cascivo-shadow-md,0 4px 12px #0003);font-family:var(--cascivo-font-sans);font-size:var(--cascivo-text-sm);color:var(--cascivo-editor-fg);flex-direction:column;display:flex;position:absolute;inset-block-start:var(--cascivo-space-2);inset-inline-end:var(--cascivo-space-2)}._row_hawkv_20{align-items:center;gap:var(--cascivo-space-1);display:flex}._input_hawkv_26{min-inline-size:8rem;padding-block:var(--cascivo-space-1);padding-inline:var(--cascivo-space-2);background:var(--cascivo-editor-gutter-bg,transparent);color:inherit;border:1px solid var(--cascivo-editor-border);border-radius:var(--cascivo-radius-field);font:inherit;flex:auto}._input_hawkv_26:focus-visible{border-color:var(--cascivo-color-accent);box-shadow:var(--cascivo-focus-ring);outline:none}._count_hawkv_44{padding-inline:var(--cascivo-space-1);color:var(--cascivo-editor-gutter-fg);font-variant-numeric:tabular-nums;white-space:nowrap;flex:none}._button_hawkv_52,._toggle_hawkv_53{min-inline-size:1.75rem;padding-block:var(--cascivo-space-1);padding-inline:var(--cascivo-space-2);color:inherit;border-radius:var(--cascivo-radius-field);font:inherit;cursor:pointer;background:0 0;border:1px solid #0000;justify-content:center;align-items:center;line-height:1;display:inline-flex}._button_hawkv_52:hover,._toggle_hawkv_53:hover{background:var(--cascivo-editor-current-line)}._button_hawkv_52:focus-visible,._toggle_hawkv_53:focus-visible{box-shadow:var(--cascivo-focus-ring);outline:none}._active_hawkv_80{border-color:var(--cascivo-color-accent);color:var(--cascivo-color-accent)}@media (pointer:coarse){._button_hawkv_52,._toggle_hawkv_53,._input_hawkv_26{min-block-size:var(--cascivo-target-min-coarse,2.75rem)}}}@media (forced-colors:active){._root_18xci_2{border:1px solid fieldtext}._pre_18xci_43{display:none}._textarea_18xci_18{color:canvastext;caret-color:canvastext}}
+/*$vite$:1*/

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+import { HTMLAttributes, KeyboardEvent, Ref, TextareaHTMLAttributes } from "react";
+
+/**
+ * Token classes the syntax palette colors. Every kind maps to a
+ * `--cascivo-editor-syntax-<kind>` custom property (see @cascivo/tokens). `plain`
+ * is uncolored text (whitespace, identifiers a grammar chose not to classify).
+ */
+type TokenKind = 'keyword' | 'string' | 'number' | 'comment' | 'function' | 'type' | 'operator' | 'punctuation' | 'variable' | 'tag' | 'attr' | 'regexp' | 'boolean' | 'property' | 'plain';
+/** A single highlighted span. The concatenation of a line's token values is the line. */
+interface Token {
+  kind: TokenKind;
+  value: string;
+}
+/**
+ * Opaque per-grammar continuation carried from one line to the next so multi-line
+ * constructs (block comments, template literals, fenced code) continue correctly.
+ * Each grammar owns the meaning of its own state strings; `'default'` is the start.
+ */
+type GrammarState = string;
+/** Result of tokenizing one line: its spans plus the state to feed the next line. */
+interface LineTokens {
+  tokens: Token[];
+  state: GrammarState;
+}
+/**
+ * A language grammar. Pure and deterministic: `tokenizeLine` must depend only on
+ * `(line, state)` and must be lossless (the token values concatenate back to `line`).
+ */
+interface Grammar {
+  name: string;
+  initialState: GrammarState;
+  tokenizeLine(line: string, state: GrammarState): LineTokens;
+}
+/**
+ * A persistent, mutable index of per-line grammar **end-states** — the state
+ * carried *after* each line, which is exactly the start-state of the next line.
+ * It lets a windowed tokenizer obtain the start-state of any visible line as a
+ * read (or a lazy compute) instead of re-walking the whole document from line 0
+ * on every render.
+ *
+ * `endStates[i]` is the state after line `i`; the start-state of line `i` is
+ * therefore `endStates[i-1]` (line 0 starts at `grammar.initialState`). The array
+ * is always a contiguous prefix `[0, length-1]` — methods never leave gaps.
+ *
+ * Framework-free: pure data + methods, no React, no signals. The component holds
+ * one in a `useRef` as mutable infrastructure (like the undo/redo history handle).
+ */
+interface LineStateIndex {
+  /** The grammar this index threads state for. */
+  readonly grammar: Grammar;
+  /** Count of known end-states (always a contiguous prefix from line 0). */
+  readonly length: number;
+  /** Lazily compute + memoize end-states up to (and including) line `upto`. */
+  ensure(lines: readonly string[], upto: number): void;
+  /** The threaded start-state for line `i` (ensures the prefix as a side effect). */
+  startStateOf(lines: readonly string[], i: number): GrammarState;
+  /** Record the end-state of line `i` (append at the prefix end, or overwrite). */
+  setEndState(i: number, state: GrammarState): void;
+  /** Drop the end-state of `line` and everything after it (called on an edit). */
+  invalidateFrom(line: number): void;
+}
+/** Create an empty {@link LineStateIndex} for `grammar`. */
+declare function createLineStateIndex(grammar: Grammar): LineStateIndex;
+/** Result of tokenizing one line: spans plus the continuation state. */
+interface TokenizeResult {
+  tokens: Token[];
+  endState: GrammarState;
+}
+/**
+ * Tokenize a single line, restartable from `startState`, memoized. Pure from the
+ * caller's perspective: identical `(grammar, line, startState)` yield identical
+ * results (a cache hit returns the previously-computed value).
+ */
+declare function tokenize(grammar: Grammar, line: string, startState: GrammarState): TokenizeResult;
+/**
+ * Tokenize a whole document, threading each line's `endState` into the next so
+ * block comments / template literals / fenced code continue across lines.
+ * Returns one token array per line. The per-line memo makes a single-line edit
+ * re-tokenize only the changed line(s) until the start-state reconverges.
+ */
+declare function tokenizeDocument(grammar: Grammar, text: string): Token[][];
+/**
+ * Tokenize only the line range `[from, to)`, using a {@link LineStateIndex} for
+ * the window's seed state instead of re-walking the document from line 0. The
+ * index supplies the start-state of `from` (computing the prefix lazily, once),
+ * and each line's fresh end-state is written back into the index so later windows
+ * reuse it — making per-render work O(viewport), not O(document).
+ *
+ * Returns a plain `Token[][]` of length `to - from`: element `j` is line
+ * `from + j`. The consumer knows the window starts at `from`, so alignment with
+ * the rendered rows stays trivial. Output is byte-for-byte identical to
+ * `tokenizeDocument(grammar, lines.join('\n')).slice(from, to)`.
+ */
+declare function tokenizeRange(grammar: Grammar, lines: readonly string[], from: number, to: number, index: LineStateIndex): Token[][];
+/** Register (or replace) a grammar under its `name`. */
+declare function registerGrammar(grammar: Grammar): void;
+/** Resolve a grammar by name, falling back to `plaintext` for unknown languages. */
+declare function getGrammar(name?: string): Grammar;
+/** List the names of all currently-registered grammars. */
+declare function listGrammars(): string[];
+/**
+ * One tokenizer rule. `match` is anchored at the current scan position (compiled
+ * sticky internally). On a non-empty match the matched text becomes a token of
+ * `kind`, the position advances, and the state transitions via `push`/`pop`.
+ */
+interface Rule {
+  match: RegExp;
+  kind: TokenKind;
+  /** Switch to this state after matching (for entering multi-line constructs). */
+  push?: string;
+  /** Return to the `default` state after matching (for leaving them). */
+  pop?: boolean;
+}
+interface RuleSpec {
+  name: string;
+  /** Per-state ordered rule lists. Must include a `default` state. */
+  states: Record<string, Rule[]>;
+}
+/**
+ * Build a {@link Grammar} from ordered, state-keyed regex rules — a tiny
+ * Monarch/Prism-style engine. At each position, the first rule in the current
+ * state whose sticky regex matches wins; unmatched characters accumulate into
+ * `plain` tokens, so the tokenizer is always lossless. State carries across
+ * lines for block comments, template literals, and fenced code.
+ */
+declare function createRuleGrammar(spec: RuleSpec): Grammar;
+/** The trivial fallback grammar: one uncolored `plain` token per line. */
+declare const plaintext: Grammar;
+/**
+ * JSON: property keys vs string values, numbers, booleans/null, punctuation.
+ * A string immediately followed by a colon is a property key; other strings are
+ * values.
+ */
+declare const json: Grammar;
+/** JavaScript: keywords, strings (incl. multi-line template literals), numbers,
+ * line + block comments (state carry), function calls, identifiers, operators. */
+declare const javascript: Grammar;
+declare const typescript: Grammar;
+/**
+ * CSS: at-rules, selectors, property names, values, numbers/units, strings, and
+ * `/* *\/` block comments (state carried across lines).
+ */
+declare const css: Grammar;
+/**
+ * HTML: tags, attribute names/values, `<!-- -->` comments (state carried across
+ * lines), and text. Inside a tag, attributes and strings are colored until `>`.
+ */
+declare const html: Grammar;
+/**
+ * Markdown for a notes/wiki surface: ATX headings, horizontal rules, task &
+ * ordered/unordered lists, blockquotes, inline + fenced code (state carried across
+ * lines), strong/emphasis/strikethrough, and links/images. Line-based, so setext
+ * headings and CommonMark tables/footnotes are intentionally out of scope; the
+ * fence body is colored uniformly (embedded-language highlight is a future step).
+ */
+declare const markdown: Grammar;
+/** Bash: comments, strings, keywords, variables (`$VAR` / `${...}`), operators. */
+declare const bash: Grammar;
+/**
+ * A visual decoration: a `[start, end)` column range on a given line tagged with a
+ * CSS class. The overlay layer splits token spans at decoration boundaries and adds
+ * the class to the covered slice. Used internally for search matches and bracket
+ * pairs, and exposed publicly via the editor's `decorations` prop.
+ */
+interface Decoration {
+  line: number;
+  start: number;
+  end: number;
+  className: string;
+}
+/** What a {@link Command} receives: the live textarea, the originating event, and the commit fn. */
+interface CommandContext {
+  textarea: HTMLTextAreaElement;
+  event: KeyboardEvent<HTMLTextAreaElement>;
+  /** Commit a new document value through the editor's controllable signal + history. */
+  setText: (value: string) => void;
+}
+/** A keymap command. Returns `true` when it handled the event (the caller then prevents default). */
+type Command = (ctx: CommandContext) => boolean;
+/** A public keymap: chord string → command. Merged over the built-ins (user wins). */
+type KeyMap = Record<string, Command>;
+/**
+ * Per-instance theme overrides — a partial map of `--cascivo-editor-*` custom
+ * properties spread onto the editor root. Swapping it re-themes live (Zen mode),
+ * while global `data-theme` remains the default.
+ */
+type EditorTheme = Partial<Record<`--cascivo-editor-${string}`, string>>;
+/**
+ * Imperative handle (via `ref`) for callers that drive their own transactions —
+ * a remote pull, a programmatic insert, a reset. Edits route through the same
+ * history as keyboard edits, so they stay undoable.
+ */
+interface CodeEditorHandle {
+  /** Replace `[from, to)` with `text` (an undoable edit), leaving the caret after it. */
+  applyEdit(range: {
+    from: number;
+    to: number;
+  }, text: string): void;
+  /** Current selection offsets. */
+  getSelection(): {
+    start: number;
+    end: number;
+  };
+  /** Focus the editing surface. */
+  focus(): void;
+  /** Undo / redo the owned history. */
+  undo(): void;
+  redo(): void;
+  /** Open the find panel. */
+  openFind(): void;
+}
+interface CodeEditorProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange' | 'wrap'> {
+  /** Controlled value. */
+  value?: string;
+  /** Initial value for uncontrolled use. */
+  defaultValue?: string;
+  /** Called with the new text on every edit. */
+  onValueChange?: (value: string) => void;
+  /** Grammar name (defaults to `plaintext`; unknown names fall back to it). */
+  language?: string;
+  /** Show the line-number gutter (default true). */
+  lineNumbers?: boolean;
+  /** Spaces per tab stop (default 2). */
+  tabSize?: number;
+  /** Insert spaces (default) vs a literal tab on Tab. */
+  insertSpaces?: boolean;
+  /** Soft-wrap long lines instead of scrolling horizontally (default false). */
+  wrap?: boolean;
+  /**
+   * Render only the visible lines for large documents. Defaults to auto
+   * (on above ~1000 lines); disabled when `wrap` makes row heights variable.
+   */
+  virtualize?: boolean;
+  /** Accessible label for the editor (defaults to the i18n "Code editor"). */
+  label?: string;
+  /** Called with the current value on `Mod-S` (the browser save dialog is suppressed). */
+  onSave?: (value: string) => void;
+  /** Extra key bindings, merged over the built-ins (user wins on the same chord). */
+  keymap?: KeyMap;
+  /** Extra decorations — offset ranges → CSS class — merged with internal ones. */
+  decorations?: readonly Decoration[] | ((value: string) => readonly Decoration[]);
+  /** Per-instance `--cascivo-editor-*` overrides; swapping it re-themes live. */
+  theme?: EditorTheme;
+  /** Highlight the bracket matching the one adjacent to the caret (default false). */
+  bracketMatching?: boolean;
+}
+/**
+ * A lightweight code editor: a native `<textarea>` overlaid on a syntax-highlighted
+ * `Highlight` layer. The browser owns editing/caret/IME/undo/a11y; JS handles only
+ * tokenizing, scroll-sync, and Tab/Shift-Tab indent. Signal-driven, no banned hooks.
+ *
+ * Performance: tokenization is per-line memoized, the highlight layer is
+ * rAF-debounced (typing never blocks), and large documents window to the visible
+ * range while the textarea always holds the full text.
+ */
+declare const CodeEditor: import("react").ForwardRefExoticComponent<CodeEditorProps & import("react").RefAttributes<CodeEditorHandle>>;
+interface HighlightProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Code to render. */
+  value: string;
+  /** Grammar name (defaults to `plaintext`; unknown names fall back to it). */
+  language?: string;
+  /** Show the line-number gutter. */
+  lineNumbers?: boolean;
+  /** Soft-wrap long lines instead of scrolling horizontally. */
+  wrap?: boolean;
+  /** Spaces per tab stop (default 2). */
+  tabSize?: number;
+  /** Accessible label for the read-only code block. */
+  label?: string;
+  /** Ref to the scrollable `<pre>` (used by `CodeEditor` for scroll-sync). */
+  preRef?: Ref<HTMLPreElement>;
+  /** Ref to the gutter column (used by `CodeEditor` for scroll-sync). */
+  gutterRef?: Ref<HTMLDivElement>;
+}
+/**
+ * Read-only, syntax-highlighted `<pre><code>` rendered from the owned tokenizer.
+ * The same render layer `CodeEditor` overlays its `<textarea>` on. Signal-safe,
+ * themeable, and accessible — no banned hooks.
+ */
+declare function Highlight({
+  value,
+  language,
+  lineNumbers,
+  wrap,
+  tabSize,
+  label,
+  className,
+  preRef,
+  gutterRef,
+  style,
+  ...rest
+}: HighlightProps): import("react").JSX.Element;
+export { CodeEditor, type CodeEditorHandle, type CodeEditorProps, type Command, type CommandContext, type Decoration, type EditorTheme, type Grammar, type GrammarState, Highlight, type HighlightProps, type KeyMap, type LineStateIndex, type LineTokens, type Rule, type RuleSpec, type Token, type TokenKind, type TokenizeResult, bash, createLineStateIndex, createRuleGrammar, css, getGrammar, html, javascript, json, listGrammars, markdown, plaintext, registerGrammar, tokenize, tokenizeDocument, tokenizeRange, typescript };