@citisen/litearea 0.1.0

package/dist/types/core/vocabulary.d.ts

@@ -0,0 +1,82 @@
+import type { ResolvedVocabulary, Scope, Severity, VocabularyContext, VocabularyEntry, WordsSource } from './types.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 declare function defineVocabulary<State = unknown>(spec: VocabularySpec<State>): ResolvedVocabulary<State>;
+/**
+ * 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 declare function vocabularyWords<State>(vocabulary: ResolvedVocabulary<State>, context: VocabularyContext<State>): readonly string[];
+/**
+ * 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 declare function asResolvedVocabulary<State>(source: WordsSource<State>): 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 declare function resolveWordsSource<State>(source: WordsSource<State>, context: VocabularyContext<State>): readonly string[];
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/types/core/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../../src/core/vocabulary.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,kBAAkB,EAClB,KAAK,EACL,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,WAAW,EACZ,MAAM,YAAY,CAAA;AAGnB,6EAA6E;AAC7E,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO;IAC7C,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,CAAA;IACrF,yEAAyE;IACzE,KAAK,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,CAAA;IACzC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,KAAK,CAAA;IACpB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC,CAAA;IAChF,+DAA+D;IAC/D,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAA;IACzD,kEAAkE;IAClE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAC7C,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAC9C,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,GAC1B,kBAAkB,CAAC,KAAK,CAAC,CAuD3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EACnC,UAAU,EAAE,kBAAkB,CAAC,KAAK,CAAC,EACrC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAChC,SAAS,MAAM,EAAE,CAEnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EACxC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,GACzB,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAIvC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,EAC1B,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAChC,SAAS,MAAM,EAAE,CASnB"}

package/dist/types/dom/create.d.ts

@@ -0,0 +1,17 @@
+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 declare function createEditor<State = unknown>(target: Element, options: LiteAreaOptions<State>): LiteArea<State>;
+//# sourceMappingURL=create.d.ts.map

package/dist/types/dom/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/dom/create.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAG,OAAO,EAC1C,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,GAC9B,QAAQ,CAAC,KAAK,CAAC,CAKjB"}

package/dist/types/dom/editing.d.ts

@@ -0,0 +1,89 @@
+/** 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 declare function readSelection(field: HTMLTextAreaElement): TextSelection;
+/**
+ * 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 declare function writeSelection(field: HTMLTextAreaElement, start: number, end?: number): void;
+/** The line height in force on a field, falling back to the computed font size. */
+export declare function fieldLineHeight(field: HTMLTextAreaElement): number;
+/**
+ * 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 declare function replaceThroughPipeline(field: HTMLTextAreaElement, from: number, to: number, text: string): EditOutcome;
+/**
+ * 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 declare function dispatchInput(field: HTMLTextAreaElement, text: string): void;
+/**
+ * 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 declare function undoField(field: HTMLTextAreaElement): boolean;
+/**
+ * Redo, through the browser's own history.
+ * @param field - the textarea.
+ * @returns whether the call was possible at all.
+ */
+export declare function redoField(field: HTMLTextAreaElement): boolean;
+/**
+ * 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 declare function writeDocument(field: HTMLTextAreaElement, next: string, preserveHistory?: boolean): EditOutcome;
+//# sourceMappingURL=editing.d.ts.map

package/dist/types/dom/editing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editing.d.ts","sourceRoot":"","sources":["../../../src/dom/editing.ts"],"names":[],"mappings":"AA6BA,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE7D,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa,CAIvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAc,GAClB,IAAI,CAKN;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAOlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,WAAW,CA0Bb;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAU5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAQ7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,MAAM,EACZ,eAAe,UAAQ,GACtB,WAAW,CAMb"}

package/dist/types/dom/editor.d.ts

@@ -0,0 +1,366 @@
+import type { Completion, Decoration, Diagnostic, Grammar, HoverInfo, Range, Severity } from '../core/types.js';
+import type { Inspection } from '../core/inspect.js';
+import { type ResolvedGrammar } from '../core/scan.js';
+import { type EditOutcome, type TextSelection } from './editing.js';
+/** How the box follows its content. */
+export interface LiteAreaSizing {
+    /**
+     * Whether the height follows the content, so that no scrollbar is shown while
+     * the content fits. Default `true`.
+     */
+    autoGrow?: boolean;
+    /**
+     * The fewest lines to show, written to the textarea's own `rows` attribute.
+     *
+     * The native attribute is set rather than only a pixel minimum, so the box has
+     * the right height on the very first frame — before any measurement, and in a
+     * document where the script never runs at all. Default 1.
+     */
+    minRows?: number;
+    /** The most lines to show before a scrollbar appears. */
+    maxRows?: number;
+    /** A minimum height in pixels, in addition to `minRows`. */
+    minHeight?: number;
+    /** A maximum height in pixels, in addition to `maxRows`. */
+    maxHeight?: number;
+}
+/** How the completion list behaves. */
+export interface LiteAreaCompletion {
+    /** Whether suggestions appear while typing. Default `true`. */
+    auto?: boolean;
+    /**
+     * Characters that open the list in addition to word characters.
+     *
+     * Default `' '`, and that default is doing real work: both reference languages
+     * put a value after a name, so a space is exactly where the next word becomes
+     * guessable.
+     */
+    triggerCharacters?: string;
+    /** The most rows to offer. Default 100. */
+    limit?: number;
+    /** Whether the documentation panel is shown. Default `true`. */
+    showDocumentation?: boolean;
+}
+/** How the hover tooltip behaves. */
+export interface LiteAreaHover {
+    /** Whether tooltips appear at all. Default `true`. */
+    enabled?: boolean;
+    /** How long the pointer must rest, in milliseconds. Default 140. */
+    delay?: number;
+}
+/** Everything a host may configure. */
+export interface LiteAreaOptions<State = unknown> {
+    /** The language. Nothing else in this library knows anything about syntax. */
+    grammar: Grammar<State> | ResolvedGrammar<State>;
+    /** The initial text. */
+    value?: string;
+    /** Shown while the box is empty. */
+    placeholder?: string;
+    /** Whether the user may edit. */
+    readOnly?: boolean;
+    /** Whether the browser may spell-check. Default `false`, because a DSL is not prose. */
+    spellCheck?: boolean;
+    /** The accessible name. */
+    ariaLabel?: string;
+    /** An extra class on the wrapper. */
+    className?: string;
+    /**
+     * CSS custom properties for THIS instance, for per-instance theming.
+     *
+     * A key may be written `font`, `--litearea-font`, or any other `--…` name; the first two
+     * forms mean the same thing, and a key that already starts with `--` is used verbatim so a
+     * host's own properties work too. The value is used as written, so `'13px'`,
+     * `'var(--my-ui-font)'`, and `'1.6'` are all fine.
+     *
+     *     createEditor(target, {
+     *       grammar,
+     *       variables: { font: '"Fira Code", monospace', 'font-size': '14px', accent: '#c2410c' },
+     *     })
+     *
+     * CSS stays the theme language on purpose — the editor's whole appearance is already
+     * described by custom properties, and a second vocabulary for the same facts would mean two
+     * places to keep in step. This exists only so that ONE instance can be themed without a host
+     * writing a stylesheet rule for it, and so that two editors on a page can differ.
+     */
+    variables?: Record<string, string>;
+    /** How the box follows its content. */
+    sizing?: LiteAreaSizing;
+    /** How the list behaves, or `false` to switch completions off entirely. */
+    completion?: LiteAreaCompletion | false;
+    /** How tooltips behave, or `false` to switch them off entirely. */
+    hover?: LiteAreaHover | false;
+    /** Whether semantic decorations are painted. Default `true`. */
+    decorations?: boolean;
+    /** Whether to inject the stylesheet. Default `true`. */
+    injectStyles?: boolean;
+    /** A CSP nonce for the injected stylesheet. */
+    styleNonce?: string;
+    /** Called after a user edit, with the new text. Not called for programmatic writes. */
+    onChange?: (value: string) => void;
+    /** Called when the caret or selection moves. */
+    onSelectionChange?: (selection: TextSelection) => void;
+    /** Called when the problem list changes. */
+    onDiagnostics?: (diagnostics: readonly Diagnostic[]) => void;
+    /** Called when the list opens, filters, or closes. */
+    onCompletion?: (completion: Completion | undefined) => void;
+    /** Called when a tooltip appears or goes away. */
+    onHover?: (info: HoverInfo | undefined) => void;
+}
+/**
+ * A code editor over a textarea.
+ *
+ * The tree it builds:
+ *
+ *     div.litearea            ← the positioning container, and this.element
+ *       div.litearea-box      ← the border, the radius, and the focus ring
+ *         div.litearea-layer  ← the painted text, behind and inert
+ *         textarea            ← the real field: transparent text, visible caret
+ *       div.litearea-popup    ← the completion list
+ *       div.litearea-tooltip  ← the hover tooltip
+ *
+ * The layer is inside the box while the floating elements are outside it, because
+ * the box clips nothing and a list that had to fit inside a rounded border would be
+ * cut off at the bottom.
+ */
+export declare class LiteArea<State = unknown> {
+    /** The positioning container. Put this in the page. */
+    readonly element: HTMLDivElement;
+    /** The real field. Exposed for a host that needs the element itself. */
+    readonly input: HTMLTextAreaElement;
+    private readonly document;
+    private readonly view;
+    /**
+     * The grammar as the host declared it, kept so {@link refresh} can re-resolve it.
+     *
+     * Mutable on purpose, and it is what lets a host pass a live object — a proxy
+     * reading the newest props, say — without the editor having to be rebuilt when the
+     * language changes. A rebuild would throw away the undo history, which is the one
+     * thing this library must not do, so re-resolving is the only acceptable answer.
+     */
+    private declaredGrammar;
+    /** The grammar the engine is currently running, with its defaults filled in. */
+    private grammar;
+    private readonly box;
+    private readonly overlay;
+    private readonly popup;
+    private readonly tooltip;
+    private readonly mirror;
+    private readonly sizing;
+    private readonly completion;
+    private readonly hover;
+    private readonly paintDecorations;
+    private readonly handlers;
+    private readonly injectedStyle;
+    private readonly instanceId;
+    private readonly fontsReady;
+    /** The current inspection, and the text it was computed from. */
+    private current;
+    private currentText;
+    /** Bumped whenever the inspection changes, so the painter can skip work. */
+    private revision;
+    /** The list on screen, with the range frozen when it opened. */
+    private completionState;
+    /** True during an IME composition, when no completion may run. */
+    private composing;
+    /** True while the editor itself is writing, so its own edit does not re-open the list. */
+    private applying;
+    /** The height and overflow last written, so unchanged values are not rewritten. */
+    private appliedHeight;
+    private appliedOverflow;
+    private appliedScrollbar;
+    /** The offset the tooltip last described, so a resting pointer does not re-query. */
+    private hoverOffset;
+    /** The custom properties this instance set, so one that disappears can be removed. */
+    private appliedVariables;
+    private hoverTimer;
+    /** Watches for a width change, which invalidates wrapping and the box height. */
+    private resizeObserver;
+    private observedWidth;
+    /**
+     * A signature of the last announced problem list, so the host is told once.
+     *
+     * Starts as `undefined` rather than as the empty string, because "no problems" is a
+     * real signature and a host waiting to be told that the list is clear would otherwise
+     * never hear it — it would keep whatever it was showing before the editor existed.
+     */
+    private announced;
+    private destroyed;
+    /**
+     * @param options - the grammar, the initial text, and the behaviour to use.
+     */
+    constructor(options: LiteAreaOptions<State>);
+    /** The current text. */
+    get value(): string;
+    /** The caret or selection. */
+    get selection(): TextSelection;
+    /** The last inspection, or undefined before the first one. */
+    get inspection(): Inspection<State> | undefined;
+    /** The problems the grammar found. */
+    get diagnostics(): readonly Diagnostic[];
+    /** The list on screen, when one is. */
+    get currentCompletion(): Completion | undefined;
+    /** Whether the editor has focus. */
+    get focused(): boolean;
+    /**
+     * Replace the text.
+     *
+     * `preserveHistory` writes through the editing pipeline, so the replacement is
+     * one undoable edit and Ctrl+Z brings the old text back — what a Reset button
+     * wants. Without it the value property is assigned, which is faster and clears
+     * the history, which is what loading a different document wants.
+     *
+     * This is the only path that writes the text, and it is never used for an edit
+     * the user could have made.
+     * @param next - the new text.
+     * @param preserveHistory - whether Ctrl+Z should be able to undo it.
+     * @returns how the write landed.
+     */
+    setValue(next: string, preserveHistory?: boolean): EditOutcome;
+    /**
+     * Put the caret somewhere.
+     * @param start - the anchor offset.
+     * @param end - the moving offset; defaults to `start`.
+     */
+    setSelection(start: number, end?: number): void;
+    /** Move the caret into the field. */
+    focus(): void;
+    /** Undo, through the browser's history. */
+    undo(): boolean;
+    /** Redo, through the browser's history. */
+    redo(): boolean;
+    /**
+     * Set CSS custom properties on the wrapper, replacing whatever this method set last time.
+     *
+     * A property that has disappeared from the record is removed rather than left behind, so a
+     * host can un-theme by passing a smaller object. Properties set by other means — a stylesheet,
+     * or the wrapper's inline style directly — are not touched, and a removed one falls back to
+     * whatever CSS says.
+     *
+     * Safe to call at any time after construction. The constructor uses the private write-only
+     * half, because re-measuring needs the field, the mirror, and the overlay, none of which exist
+     * until it has finished.
+     * @param next - the properties, keyed as {@link LiteAreaOptions.variables} describes.
+     */
+    setVariables(next: Readonly<Record<string, string>>): void;
+    /** Write the properties, and forget the ones that are gone. No re-measure. */
+    private applyVariables;
+    /**
+     * Re-read the document with the same text.
+     *
+     * For a host whose grammar depends on something outside it — an installed font
+     * list that has just been re-read, a palette that changed — and for the moment a
+     * web font finishes loading.
+     *
+     * The grammar is re-resolved here, which is what makes a live grammar object
+     * work: a host that rebuilds its rules on every render can call `refresh()` and
+     * the editor picks the new ones up without being rebuilt, so the undo history
+     * survives a language change.
+     */
+    refresh(): void;
+    /** Open the completion list on demand, as Ctrl+Space does. */
+    showCompletions(): void;
+    /** Close the completion list. */
+    hideCompletions(): void;
+    /** Remove the editor and every listener it owns. */
+    destroy(): void;
+    /**
+     * Bring everything up to date with the field.
+     *
+     * The inspection is cached on the text, so moving the caret or scrolling costs
+     * nothing beyond the paint — and the paint itself is skipped when neither the
+     * text nor the analysis changed.
+     */
+    private sync;
+    /** Paint the layer, and mark the box when a problem is an error. */
+    private paint;
+    /** Tell the host, once, when the problem list actually changed. */
+    private announceDiagnostics;
+    /**
+     * Size the box to its content.
+     *
+     * The mirror has no scrollbar, so its measurement is the height the content wants
+     * with the full width available — which is exactly the number that decides whether
+     * a scrollbar is needed at all. If it fits under the maximum, the height becomes
+     * the content height and the overflow stays hidden, which is the promise of "grow
+     * and shrink so no scrollbar is ever shown". If it does not fit, the height is
+     * clamped and the overflow becomes `auto`.
+     *
+     * Clamping introduces a second problem that is easy to miss: a scrollbar narrows
+     * the text, so the field rewraps, so the PAINT no longer wraps the same way and
+     * every coloured span slides off its character. The measured scrollbar width is
+     * therefore published as a custom property, and the stylesheet adds it to the
+     * layer's own right padding so the two keep wrapping identically.
+     *
+     * An UNMOUNTED field is skipped rather than measured. Before the element is in the
+     * document it has no layout, so its `clientWidth` is zero, the mirror wraps at every
+     * character, and the measurement comes back several times too tall — a wrong height
+     * that then has to be corrected on the next keystroke, which is what a box that
+     * jumps on first focus actually is. The `ResizeObserver` installed at construction
+     * does the first real measurement as soon as there is a width to measure against.
+     * @param text - the current text.
+     */
+    private resize;
+    /** The caret's offset, clamped into the text. */
+    private caret;
+    /** Resolve and show a list for the caret. */
+    private openCompletion;
+    /** Close the list and tell the host. */
+    private closeCompletion;
+    /** Keep the field's `aria-activedescendant` pointing at the active row. */
+    private syncActiveDescendant;
+    /** Put the list under the caret. */
+    private placePopup;
+    /**
+     * Take the active row.
+     * @param index - the row to take.
+     * @param commitCharacter - a character typed to trigger the pick, written after
+     *   the completion so the keystroke is not swallowed.
+     */
+    private acceptCompletion;
+    /** Decide what an edit does to the list. */
+    private updateCompletionAfterInput;
+    /** Whether a keystroke is a reason to offer suggestions. */
+    private shouldAutoOpen;
+    /** Close a list the caret has left. */
+    private updateCompletionForCaret;
+    /** Start, or restart, the timer that shows a tooltip. */
+    private queueHover;
+    /** Resolve and show a tooltip. */
+    private showHover;
+    /** Hide the tooltip and forget what it described. */
+    private hideTooltip;
+    /** Attach every listener. */
+    private bind;
+    /** Detach every listener. */
+    private unbind;
+    private readonly onInput;
+    private readonly onKeyDown;
+    /**
+     * Whether a keystroke is a commit character for the active row.
+     *
+     * Typing `=` at the end of `shape` takes the `shape=` row and keeps the
+     * character, rather than either swallowing the keystroke or leaving the row to be
+     * clicked. A row opts in; nothing has a commit character by default.
+     * @param event - the key event.
+     * @returns whether the keystroke was consumed.
+     */
+    private commitCharacter;
+    /** Make a row active and keep the ARIA pointer in step. */
+    private setActive;
+    private readonly onScroll;
+    private readonly onCaretMoved;
+    private readonly onKeyUp;
+    private readonly onSelectionChange;
+    private readonly onBlur;
+    private readonly onMouseMove;
+    private readonly onMouseLeave;
+    private readonly onCompositionStart;
+    private readonly onCompositionEnd;
+}
+/** A severity, re-exported so a host can narrow a diagnostic without importing core. */
+export type EditorSeverity = Severity;
+/** A range, re-exported for the same reason. */
+export type EditorRange = Range;
+/** A decoration, re-exported for the same reason. */
+export type EditorDecoration = Decoration;
+//# sourceMappingURL=editor.d.ts.map

package/dist/types/dom/editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../../src/dom/editor.ts"],"names":[],"mappings":"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"}

package/dist/types/dom/index.d.ts

@@ -0,0 +1,9 @@
+export { LiteArea, type EditorDecoration, type EditorRange, type EditorSeverity, type LiteAreaCompletion, type LiteAreaHover, type LiteAreaOptions, type LiteAreaSizing, } from './editor.js';
+export { createEditor } from './create.js';
+export { dispatchInput, fieldLineHeight, readSelection, redoField, replaceThroughPipeline, undoField, writeDocument, writeSelection, type EditOutcome, type TextSelection, } from './editing.js';
+export { TextMirror, type CaretBox } from './mirror.js';
+export { Overlay, type OverlayClassNames } from './overlay.js';
+export { Popup, type AnchorBox, type PopupHandlers } from './popup.js';
+export { Tooltip, type TooltipAnchor } from './tooltip.js';
+export { canEditThroughPipeline, hasCaretHitTest, hasDocument, offsetFromPoint, withDefaults, } from './support.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/dom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dom/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,QAAQ,EACR,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,EACL,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEvD,OAAO,EAAE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAE9D,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAE1D,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,cAAc,CAAA"}