@fusion.dev/helix-headless 0.215.3 → 0.216.0

package/dist/code-editor/root/code-editor-root.d.ts

@@ -0,0 +1,367 @@
+import { AriaForwardController, HelixFormElement, ListedController } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../button/index.js';
+import '../../icon-button/index.js';
+import '../../toolbar/index.js';
+/** A problem in the text, from a linter or a language server, by where it is. */
+export interface EditorDiagnostic {
+    /** Where it starts and ends, as offsets into the value. */
+    from: number;
+    message: string;
+    to: number;
+    /** How bad it is. `danger` by default. */
+    tone?: 'danger' | 'info' | 'warning';
+}
+/** What an editor shows, which an engine draws. */
+export interface EditorEngineState {
+    diagnostics: readonly EditorDiagnostic[];
+    /** The editor's name, for the engine's text area. */
+    label: string;
+    /** The language to highlight, such as `ts`, `css`, `md` or `rust`. Empty is plain text. */
+    language: string;
+    lineNumbers: boolean;
+    placeholder: string;
+    readOnly: boolean;
+    value: string;
+    wrap: boolean;
+}
+/** What the editor tells the engine, which the engine calls as the reader works. */
+export interface EditorEngineListeners {
+    /** The caret or selection moved, as offsets into the value. */
+    caret?(from: number, to: number): void;
+    /** The reader changed the text. Returns whether the change stands, so the engine can refuse one the page refused. */
+    change(value: string): boolean;
+}
+/** What the find bar asks an engine to look for. */
+export interface EditorFindQuery {
+    caseSensitive: boolean;
+    regex: boolean;
+    /** What Replace puts in place of a match. */
+    replace: string;
+    search: string;
+    wholeWord: boolean;
+}
+/** Where a search stands: how many matches, and which is selected, counting from 0, or -1 for none. */
+export interface EditorFindResult {
+    count: number;
+    index: number;
+}
+/** An engine drawing one editor, which the editor drives. */
+export interface EditorEngineView {
+    /** Takes the engine out of the page. */
+    destroy(): void;
+    /**
+     * Finds `query` and selects a match: the first from the caret, or the next
+     * or previous from the selected one. Marks every match while the find bar
+     * is open.
+     */
+    find?(query: EditorFindQuery, direction: 'first' | 'next' | 'previous'): EditorFindResult;
+    /** Takes the marks a search drew away, as the find bar closes. */
+    findEnd?(): void;
+    /** Puts the caret in the engine's text area. */
+    focus?(): void;
+    /** Replaces the selected match, or every match, and returns where the search stands after. */
+    replace?(query: EditorFindQuery, all: boolean): EditorFindResult;
+    /** Selects a range, scrolls it into view and puts the caret there. */
+    select?(from: number, to: number): void;
+    /** Shows a new state: a value set from outside, a language, diagnostics. */
+    update(state: EditorEngineState): void;
+}
+/**
+ * Something that draws a code editor, such as CodeMirror through
+ * `@fusion.dev/helix-editor`. The editor hands it an element to draw in.
+ */
+export interface EditorEngine {
+    mount(parent: HTMLElement, state: EditorEngineState, listeners: EditorEngineListeners): EditorEngineView;
+}
+/** Each diagnostic's line, counted from 1, by its start, from one pass over the value. */
+export declare const diagnosticLines: (value: string, diagnostics: readonly EditorDiagnostic[]) => number[];
+/** The line and column an offset is at, each counted from 1. */
+export declare const positionOf: (value: string, at: number) => {
+    column: number;
+    line: number;
+};
+/** Where a query matches in a text, as `[from, to]` offsets, with no empty match. */
+export declare const findRanges: (text: string, query: EditorFindQuery) => Array<[number, number]>;
+declare const HelixHeadlessCodeEditor_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary An editor for a file of code, drawn by a code editor you connect.
+ *
+ * @description
+ * A pane for working on a file: a header with its name, its language and the
+ * page's own actions, the code, the problems in it, and a status line that
+ * says where the caret is. On its own the code is a `<textarea>` in the code
+ * face. Connect an engine and it draws the code instead: `connectEditor` from
+ * `@fusion.dev/helix-editor` connects CodeMirror, with highlighting in your
+ * theme's syntax colors, line numbers, folding, bracket matching and history.
+ * The value, the form, validation and the events stay the editor's, so a page
+ * reads and writes it the same either way.
+ *
+ * For a few lines in a form, such as a setting in JSON, use `Code Input`,
+ * which needs no engine.
+ *
+ * - `language` picks the highlighting, such as `ts`, `css`, `html`, `md`,
+ *   `json`, `python`, `rust` or `sh`, and the header names it.
+ * - `diagnostics` marks problems, from a linter or a language server: each is
+ *   underlined in the text, its line number is drawn in its tone, and it is
+ *   listed under the code, where pressing it moves the caret to it.
+ * - The find bar finds, with the case, whole words or a regular expression,
+ *   and replaces once its first button shows the replace field, in the
+ *   engine or in the plain field alike.
+ * - Every change goes through `requestValue`, so a listener refusing
+ *   `helix-before-change` refuses the keystroke, in the engine too.
+ *
+ * **Keyboard.** Command+F, or Control+F elsewhere, opens the find bar, Enter
+ * and Shift+Enter move between matches, and Escape closes it. In an engine,
+ * Tab indents and Escape then Tab leaves the editor, so the editor is never a
+ * trap for a reader without a pointer.
+ *
+ * @since 0.216.0
+ * @status experimental
+ * @category inputs
+ * @aliases Code editor, CodeMirror, File editor, IDE, Monaco
+ * @documentation https://fusion.dev/helix/components/code-editor
+ *
+ * @slot actions - The page's own controls in the header, such as Run or Format, before the built-in ones.
+ * @slot hint - Help under the editor, in place of `hint`.
+ * @slot label - The editor's name in the header, such as a file name, in place of `label`.
+ *
+ * @event {Event} change - The reader finished an edit and focus left the code, in the engine or the plain field.
+ * @event {HelixBeforeChangeEvent} helix-before-change - The text is about to change. Cancelable: cancel it to keep the current text.
+ * @event {Event} input - Fired after the text changes.
+ *
+ * @csspart body - The box the code is drawn in, between the header and the problems.
+ * @csspart control - The `<textarea>` the editor is without an engine, and that keeps its validity with one.
+ * @csspart controls - The toolbar in the header: the page's actions, then Find.
+ * @csspart controls-toolbar - The box inside the header's toolbar that lays its buttons out.
+ * @csspart diagnostic - One problem in the list, a button that moves the caret to it.
+ * @csspart diagnostic-danger - A problem whose tone is `danger`, beside `diagnostic`.
+ * @csspart diagnostic-icon - The mark of a problem's tone, before its words.
+ * @csspart diagnostic-info - A problem whose tone is `info`, beside `diagnostic`.
+ * @csspart diagnostic-warning - A problem whose tone is `warning`, beside `diagnostic`.
+ * @csspart diagnostics - The list of problems under the code, while there are any.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The frame around the header, the code, the problems and the status line.
+ * @csspart find - The button in the header that opens the find bar.
+ * @csspart find-bar - The find bar under the header, while it is open.
+ * @csspart find-button - The Find button's inner button.
+ * @csspart find-close - The button that closes the find bar.
+ * @csspart find-close-button - The close button's inner button.
+ * @csspart find-close-live - The close button's live region, which speaks while the button is pending.
+ * @csspart find-close-spinner - The ring the close button turns while it is pending.
+ * @csspart find-close-text - The box the close button's icon sits in.
+ * @csspart find-controls - The find bar's toolbar of options and moves.
+ * @csspart find-controls-toolbar - The box inside the find bar's toolbar that lays its buttons out.
+ * @csspart find-count - Which match is selected, of how many.
+ * @csspart find-field - The field the search is typed in.
+ * @csspart find-live - The Find button's live region, which speaks while the button is pending.
+ * @csspart find-match-case - The option that finds only the same case. Pressed while it applies.
+ * @csspart find-match-case-button - The match case button's inner button.
+ * @csspart find-match-case-live - The match case button's live region, which speaks while the button is pending.
+ * @csspart find-match-case-spinner - The ring the match case button turns while it is pending.
+ * @csspart find-match-case-text - The box the match case button's icon sits in.
+ * @csspart find-next - The button that selects the next match.
+ * @csspart find-next-button - The next match button's inner button.
+ * @csspart find-next-live - The next match button's live region, which speaks while the button is pending.
+ * @csspart find-next-spinner - The ring the next match button turns while it is pending.
+ * @csspart find-next-text - The box the next match button's icon sits in.
+ * @csspart find-previous - The button that selects the previous match.
+ * @csspart find-previous-button - The previous match button's inner button.
+ * @csspart find-previous-live - The previous match button's live region, which speaks while the button is pending.
+ * @csspart find-previous-spinner - The ring the previous match button turns while it is pending.
+ * @csspart find-previous-text - The box the previous match button's icon sits in.
+ * @csspart find-regex - The option that reads the search as a regular expression. Pressed while it applies.
+ * @csspart find-regex-button - The regular expression button's inner button.
+ * @csspart find-regex-live - The regular expression button's live region, which speaks while the button is pending.
+ * @csspart find-regex-spinner - The ring the regular expression button turns while it is pending.
+ * @csspart find-regex-text - The box the regular expression button's icon sits in.
+ * @csspart find-replace - The button that shows the replace field under the find field. Expanded while it shows.
+ * @csspart find-replace-button - The find and replace button's inner button.
+ * @csspart find-replace-live - The find and replace button's live region, which speaks while the button is pending.
+ * @csspart find-replace-spinner - The ring the find and replace button turns while it is pending.
+ * @csspart find-replace-text - The box the find and replace button's icon sits in.
+ * @csspart find-spinner - The ring the Find button turns while it is pending.
+ * @csspart find-text - The box the Find button's icon sits in.
+ * @csspart find-whole-word - The option that finds only whole words. Pressed while it applies.
+ * @csspart find-whole-word-button - The whole word button's inner button.
+ * @csspart find-whole-word-live - The whole word button's live region, which speaks while the button is pending.
+ * @csspart find-whole-word-spinner - The ring the whole word button turns while it is pending.
+ * @csspart find-whole-word-text - The box the whole word button's icon sits in.
+ * @csspart header - The strip above the code: the name, the language, and the controls.
+ * @csspart hint - Help under the editor, while nothing is wrong.
+ * @csspart label - The editor's name in the header.
+ * @csspart language - The language's name in the header.
+ * @csspart position - The caret's line and column, in the status line.
+ * @csspart problem-count - How many problems there are, in the status line.
+ * @csspart replace - The button that replaces the selected match.
+ * @csspart replace-all - The button that replaces every match.
+ * @csspart replace-all-button - The Replace all button's inner button.
+ * @csspart replace-all-live - The Replace all button's live region, which speaks while the button is pending.
+ * @csspart replace-all-spinner - The ring the Replace all button turns while it is pending.
+ * @csspart replace-all-text - The box the Replace all button's words sit in.
+ * @csspart replace-button - The Replace button's inner button.
+ * @csspart replace-field - The field the replacement is typed in.
+ * @csspart replace-live - The Replace button's live region, which speaks while the button is pending.
+ * @csspart replace-spinner - The ring the Replace button turns while it is pending.
+ * @csspart replace-text - The box the Replace button's words sit in.
+ * @csspart status - The strip under the code.
+ * @csspart view - Where an engine draws, while one is connected.
+ *
+ * @cssstate connected - An engine draws the editor.
+ * @cssstate find-open - The find bar is open.
+ * @cssstate invalid - The editor has an error to show, from `required` or your `feedback`.
+ * @cssstate replace-open - The replace field shows under the find field.
+ */
+export declare class HelixHeadlessCodeEditor extends HelixHeadlessCodeEditor_base {
+    protected static markRules: string[];
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-code-editor': { findLabel: 'Suchen' } })`.
+     */
+    static words: string;
+    /** On the page's list of controls, where a command palette and a shortcut overlay find it. */
+    protected readonly listed: ListedController;
+    protected readonly aria: AriaForwardController;
+    /** Typed, so every edit is announced. */
+    protected readonly announcesInput = true;
+    /** The name of the header's toolbar, read by screen readers. */
+    controlsLabel: string;
+    /** How one problem in the list reads. `{line}` is its line and `{message}` what it says. */
+    diagnosticLabel: string;
+    /** The problems in the text, each underlined and listed under the editor. */
+    diagnostics: readonly EditorDiagnostic[];
+    /** The list of problems' name. */
+    diagnosticsLabel: string;
+    /**
+     * What draws the editor, such as `codeMirrorEngine()` from
+     * `@fusion.dev/helix-editor`. Absent, the editor is a plain text field.
+     */
+    engine: EditorEngine | undefined;
+    /** The name of the find bar's Close button. */
+    findCloseLabel: string;
+    /** The name of the find bar's toolbar, read by screen readers. */
+    findControlsLabel: string;
+    /** What the find bar says when its regular expression cannot be read. */
+    findInvalidLabel: string;
+    /** The name of the Find button and the find bar's field. */
+    findLabel: string;
+    /** The name of the option that finds only the same case. */
+    findMatchCaseLabel: string;
+    /** The name of the button that selects the next match. */
+    findNextLabel: string;
+    /** The name of the button that selects the previous match. */
+    findPreviousLabel: string;
+    /** The name of the option that reads the search as a regular expression. */
+    findRegexLabel: string;
+    /** The name of the button that shows the replace field under the find field. */
+    findReplaceLabel: string;
+    /** The name of the option that finds only whole words. */
+    findWholeWordLabel: string;
+    /** The language to highlight, such as `ts`, `css`, `md` or `rust`. Empty is plain text. */
+    language: string;
+    /** Draws each line's number beside it, in an engine. */
+    lineNumbers: boolean;
+    /**
+     * What the find bar says of its matches. `{index}` is the selected match,
+     * counting from 1, and `{count}` how many there are.
+     */
+    matchesLabel: string;
+    /** Shown while the editor is empty. */
+    placeholder: string;
+    /** Where the caret is, in the status line. `{line}` and `{column}` count from 1. */
+    positionLabel: string;
+    /** How many problems there are, in the status line. `{count}` is the number. */
+    problemsLabel: string;
+    /** Lets the reader select and copy, and not change, the text. */
+    readOnly: boolean;
+    /** The name of the button that replaces every match. */
+    replaceAllLabel: string;
+    /** The name of the button that replaces the selected match. */
+    replaceLabel: string;
+    /** The name of the field the replacement is typed in. */
+    replaceWithLabel: string;
+    /** How many lines tall the plain field is before it scrolls, without an engine. */
+    rows: number;
+    /** Wraps long lines to the editor's width, in place of scrolling sideways. */
+    wrap: boolean;
+    /** Where the caret is, as an offset into the value. */
+    private caret;
+    /** Whether the find bar is open. */
+    private findOpen;
+    /** Where the search stands, or nothing before one. */
+    private found;
+    /** Whether the replace field shows under the find field. */
+    private replaceOpen;
+    private query;
+    private view;
+    /** Whether Escape came just before, which lets Tab leave the plain field. */
+    private escaped;
+    /** The value the engine last reported, which it need not be handed back. */
+    private engineValue;
+    /** Whether the engine took an edit since focus last left it, which `change` reports. */
+    private engineEdited;
+    /** The textarea, which the form's validity is read from either way. */
+    private get control();
+    private get engineState();
+    /** Whether the search can be read, which a regular expression may not be. */
+    private get readable();
+    /** Puts the caret in the editor, as a label pointing at it would. */
+    focus(options?: FocusOptions): void;
+    /** Selects a range of the code and puts the caret there, in the engine or the plain field. */
+    select(from: number, to?: number): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** An edit in the engine: through `requestValue`, and announced where it stands. */
+    private engineChanged;
+    /** Focus left the engine after an edit, which is when a field says `change`. */
+    private readonly handleViewFocusOut;
+    /** Opens the find bar, with the selection as the search where one is selected, and puts focus in its field. */
+    private openFind;
+    /** Closes the find bar, takes the marks away, and puts focus back in the code. */
+    private closeFind;
+    /** Finds the search and selects a match, in the engine or the plain field. */
+    private search;
+    /** Replaces the selected match, or every match, through `requestValue`. */
+    private replace;
+    /** Turns one of the find bar's options on or off, and searches again with it. */
+    private toggleOption;
+    /** The find key opens the find bar from anywhere in the editor, ahead of the browser's own. */
+    private readonly handleKeys;
+    private readonly handleFindInput;
+    private readonly handleReplaceInput;
+    private readonly handleFindKeys;
+    /** An edit in the textarea, which has taken the character already: put back where it is refused. */
+    private readonly handleInput;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /** The caret in the plain field moved, by a key or a press. */
+    private readonly handleCaret;
+    /**
+     * Tab in the textarea types two spaces, as it does in an engine, unless
+     * Escape came just before it, which lets the reader leave.
+     */
+    private readonly handleKeydown;
+    /** The words the find bar's count says, or its regular expression's fault. */
+    private get countText();
+    /** The header: the name, the language, and the toolbar of the page's actions and Find. */
+    protected renderHeader(): TemplateResult;
+    /**
+     * The find bar, kept in the tree while closed so its fields keep what was
+     * typed. The fields stand outside the toolbar, which leaves the arrows to a
+     * text field.
+     */
+    protected renderFind(): TemplateResult;
+    /** The problems, each a button that moves the caret to it, in its tone. */
+    protected renderDiagnostics(): TemplateResult | typeof nothing;
+    /** The status line: where the caret is, and how many problems there are. */
+    protected renderStatus(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-code-editor': HelixHeadlessCodeEditor;
+    }
+}
+export {};