@react-x11/components 0.1.0 → 0.2.1

package/dist/terminal/vt/node.d.ts

@@ -0,0 +1,246 @@
+import { Node } from 'react-x11/node';
+import type { Context2D, MeasureConstraints, MeasuredSize } from 'react-x11/node';
+import type { KeyboardEvent, MouseEvent, WheelEvent } from 'react-x11';
+import type { Style } from 'react-x11/style';
+import type { TerminalColors } from '../backends.js';
+import type { RendererStats } from './renderer.js';
+import type { XtermTerminal } from './xterm.js';
+/** The element name — the registration key, `kind`, and the JSX tag. */
+export declare const ELEMENT = "vtterm";
+/** The props `<vtterm>` takes. Everything user-facing is on `<Terminal>`. */
+export interface VtTermProps {
+    /** The live emulator. Null while the component is still resolving it. */
+    term?: XtermTerminal | null;
+    /** Bytes the user produced, on their way to the pty. */
+    onInput?: (data: string) => void;
+    /** The element's box changed size: this many cells now fit. */
+    onGridResize?: (cols: number, rows: number) => void;
+    onSelectionChange?: (text: string) => void;
+    colors?: TerminalColors;
+    cursorStyle?: 'block' | 'underline' | 'bar';
+    cursorBlink?: boolean;
+    /** OSC 52 writes to CLIPBOARD. Reads are never answered — see `_onOsc52`. */
+    allowClipboardWrite?: boolean;
+    /** The visual bell, mid-flash: the palette runs inverted for a moment.
+     *  Held by the component so the flash is one state change, not a timer in
+     *  the node. */
+    inverted?: boolean;
+    style?: Style | Style[];
+}
+export declare class VtTermNode extends Node {
+    private _term;
+    private _disposables;
+    private _fonts;
+    private _fontKey;
+    private _palette;
+    private _paletteKey;
+    private _renderer;
+    private _mirror;
+    private _snapshot;
+    private _workCell;
+    private _cols;
+    private _rows;
+    private _reportedCols;
+    private _reportedRows;
+    private _focused;
+    private _cursorOn;
+    private _blink;
+    /** Selection anchor and head, in buffer-absolute coordinates. */
+    private _anchor;
+    private _head;
+    private _selection;
+    private _dragMode;
+    /** Escape armed one pass-through Tab — the way out of the keyboard trap. */
+    private _tabEscapes;
+    /** Not in `modes`: tracked from DECSET/DECRST (see `_watchModes`). */
+    private _mouseEncoding;
+    private _alternateScroll;
+    constructor(props: Record<string, unknown>, app: unknown);
+    private _props;
+    applyProps(next: Record<string, unknown>, prev: Record<string, unknown>): void;
+    destroySubtree(): void;
+    /**
+     * Subscribe to everything that means "the screen may look different".
+     *
+     * Only render-relevant events: the component keeps `onData`, `onTitleChange`
+     * and `onBell`, which are about the process rather than about pixels.
+     */
+    private _attach;
+    private _detach;
+    /**
+     * The two things `modes` does not carry.
+     *
+     * Mouse *encoding* (SGR 1006, urxvt 1015, UTF-8 1005) and alternate-scroll
+     * (1007) are set by DECSET/DECRST and read back nowhere, so a passive CSI
+     * observer records them and **returns false** — xterm still processes the
+     * sequence itself, and this handler is a listener rather than an
+     * implementation. Filed upstream as a request to expose `mouseEncoding`
+     * alongside `mouseTrackingMode`.
+     */
+    private _watchModes;
+    /**
+     * The font, off the **style** rather than off a prop of its own.
+     *
+     * `fontFamily` and `fontSize` are style properties, and core throws in
+     * development on an element that takes one as a flat prop — for good
+     * reason: a terminal inheriting the font from the tree above it is what
+     * makes `<box style={{ fontSize: 15 }}>` mean what it says. `<Terminal>`'s
+     * `fontFamily`/`fontSize` props are folded into this element's style.
+     */
+    private _fontStyle;
+    private _fontSet;
+    /**
+     * 80×24, or as much of it as is on offer.
+     *
+     * A terminal in a dialog with nothing else to size it should be a terminal
+     * rather than a sliver; flex owns everything past that.
+     */
+    measureContent({ width, height }: MeasureConstraints): MeasuredSize;
+    /** Cells that fit the content box right now. */
+    gridSize(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Tell the component the grid changed, off the paint stack.
+     *
+     * `onGridResize` ends in `term.resize` and `pty.resize`, and both of those
+     * can synchronously produce output — running them inside paint would have
+     * the emulator writing to a buffer the renderer is halfway through reading.
+     */
+    resizeToFit(): void;
+    get cols(): number;
+    get rows(): number;
+    private _repaint;
+    paint(ctx: Context2D): void;
+    private _ensureRenderer;
+    private _cursorState;
+    /**
+     * One dirty span, as three passes over the same cells: backgrounds merged
+     * into runs of one colour, one glyph run per non-blank cell, then the
+     * decorations. The renderer batches each pass into a single request per
+     * colour, so a span of 80 cells is a handful of requests however many
+     * colours it carries.
+     */
+    private _drawSpan;
+    private _decorateSpan;
+    /** The shapes a colour swap cannot express: bar, underline, and the hollow
+     *  box an unfocused terminal draws. */
+    private _drawCursor;
+    defaultFocus(): void;
+    defaultBlur(): void;
+    private _reportFocus;
+    private _syncBlink;
+    /**
+     * The terminal's own key behaviour, run after the application's `onKeyDown`
+     * handlers and not at all if one of them called `preventDefault()` — so an
+     * app-level chord still beats the terminal, the same bargain the XEmbed
+     * path documents.
+     *
+     * **Tab and the way out.** Core cycles focus on Tab before default actions,
+     * and a terminal that consumes Tab owes the keyboard user an exit. The
+     * convention `docs/extending.md` asks for is "Escape arms one pass-through
+     * Tab", with one terminal-specific twist: Escape is *also* still sent to the
+     * program (arming is a side effect, not a swallow), and arming is off while
+     * the alternate screen is up — a full-screen vim owns Esc-then-Tab as real
+     * input, and a focus-trapped full-screen application is the expected shape.
+     * The pointer always leaves.
+     */
+    defaultKeyDown(ev: KeyboardEvent): void;
+    /**
+     * The clipboard chords, and why a terminal's are not everyone else's.
+     *
+     * **Ctrl+C and Ctrl+V are not available.** Ctrl+C is SIGINT — the single
+     * most-pressed key in a terminal — and Ctrl+V is readline's literal-next.
+     * Both have to reach the program, so every terminal since xterm spells the
+     * clipboard with Shift: **Ctrl+Shift+C / Ctrl+Shift+V**, which is what
+     * gnome-terminal, konsole, kitty and alacritty all use.
+     *
+     * Three more are accepted because they cost the program nothing:
+     *
+     * - **Super+C / Super+V** (Command on a Mac keyboard under XQuartz).
+     *   `keys.ts` never forwards a Super chord — those belong to the desktop —
+     *   so nothing is taken from the program by answering them here, and it is
+     *   the chord a Mac user's fingers already know.
+     * - **Shift+Insert** pastes PRIMARY and **Ctrl+Insert** copies to
+     *   CLIPBOARD: the X convention that predates all of the above and still
+     *   works everywhere.
+     * - **Ctrl+Shift+A** selects the screen. (Not Ctrl+A: that is
+     *   beginning-of-line, and readline wants it.)
+     *
+     * The letter comes from core's `ctrlChordLetter`, which is public for
+     * exactly this and gets the subtlety right — ntk derives `codepoint` from
+     * the *shifted* keysym, so Ctrl+Shift+V arrives as `V` and Ctrl+V as `v`,
+     * while the keysym does not shift.
+     */
+    private _clipboardChord;
+    /**
+     * A dead key or a Compose sequence finishing.
+     *
+     * Composition stays **on** for this element — unlike `<foreign>`, which
+     * turns it off because the embedded client has an input method of its own.
+     * Here there is no other side: the keys a composition takes never reach
+     * `defaultKeyDown`, so without this the text a Compose sequence produced
+     * would be typed into nothing. Only the commit is sent; the preedit is not
+     * drawn, which is the honest state of IME support in this component (see
+     * the PRD's non-goals).
+     */
+    defaultComposition(ev: {
+        type: string;
+        data: string;
+    }): void;
+    /** Input scrolls back to the prompt and drops the selection, like every
+     *  other terminal. */
+    private _typed;
+    private _send;
+    private _cellAt;
+    private _absLine;
+    /**
+     * Whether this gesture belongs to the program rather than to the user.
+     *
+     * Shift is the universal override: an application that grabbed the mouse
+     * still has to let the user select text, and Shift is how every terminal
+     * spells that.
+     */
+    private _reporting;
+    defaultMouseDown(ev: MouseEvent): void;
+    defaultMouseDrag(ev: MouseEvent): void;
+    defaultMouseUp(ev: MouseEvent): void;
+    /**
+     * The wheel. No default-action seam exists for it, so the component wires
+     * `onWheel` to this — the same shape `<CodeEditor>` uses.
+     */
+    handleWheel(ev: WheelEvent): boolean;
+    private _updateSelection;
+    private _wordRange;
+    /** The selected text, reflow-true: a wrapped line joins with no newline. */
+    selectionText(): string | null;
+    clearSelection(): this;
+    selectAll(): this;
+    private _clipboard;
+    copySelection(selection?: string): void;
+    paste(selection?: string): void;
+    /**
+     * OSC 52 — the program asking for the clipboard.
+     *
+     * **Writes** are honoured (that is how `tmux`, `vim` and `nvim` copy out of
+     * an ssh session, and it is the whole point of the sequence), capped, and
+     * CLIPBOARD only. **Reads are answered with nothing, always**: replying
+     * would hand whatever the user last copied — a password, a token — to a
+     * program that merely printed eight bytes, so the answer is the same one
+     * kitty and iTerm ship by default.
+     */
+    private _onOsc52;
+    scrollLines(amount: number): void;
+    scrollToBottom(): void;
+    /** The visible screen as text — "copy all", and what the tests read. */
+    serialize(): string | null;
+    /** The renderer in use, and what the last frame cost — the draw-op budget
+     *  assertions read this. */
+    get rendererStats(): {
+        kind: string;
+        stats: RendererStats;
+        totals: RendererStats;
+    };
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/terminal/vt/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/terminal/vt/node.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAClB,YAAY,EACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAS7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAuBrD,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAA8B,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,wEAAwE;AACxE,eAAO,MAAM,OAAO,WAAW,CAAC;AAchC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,KAAK,CAAC;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;oBAEgB;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,CAAC;CACzB;AAUD,qBAAa,UAAW,SAAQ,IAAI;IAClC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,MAAM,CAAiB;IAC/B,iEAAiE;IACjE,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,SAAS,CAAyC;IAC1D,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAAS;IAC5B,sEAAsE;IACtE,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,gBAAgB,CAAQ;IAEhC,YAAY,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,EAevD;IAED,OAAO,CAAC,MAAM;IAML,UAAU,CACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI,CA4BN;IAEQ,cAAc,IAAI,IAAI,CAO9B;IAID;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IA2Bf,OAAO,CAAC,OAAO;IAaf;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;IA6BnB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,QAAQ;IAYhB;;;;;OAKG;IACM,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,kBAAkB,GAAG,YAAY,CAQ3E;IAED,gDAAgD;IAChD,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAQzC;IAED;;;;;;OAMG;IACH,WAAW,IAAI,IAAI,CAOlB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,OAAO,CAAC,QAAQ;IASP,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAwEnC;IAED,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,YAAY;IAcpB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAyCjB,OAAO,CAAC,aAAa;IAuCrB;2CACuC;IACvC,OAAO,CAAC,WAAW;IAiCV,YAAY,IAAI,IAAI,CAM5B;IAEQ,WAAW,IAAI,IAAI,CAM3B;IAED,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,UAAU;IAiBlB;;;;;;;;;;;;;;OAcG;IACM,cAAc,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAqB/C;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,eAAe;IAuBvB;;;;;;;;;;OAUG;IACM,kBAAkB,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAIpE;IAED;0BACsB;IACtB,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,QAAQ;IAIhB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAKT,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAsD9C;IAEQ,gBAAgB,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAiC9C;IAEQ,cAAc,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAoC5C;IAED;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CA+CnC;IAID,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,UAAU;IAWlB,4EAA4E;IAC5E,aAAa,IAAI,MAAM,GAAG,IAAI,CAiB7B;IAIQ,cAAc,IAAI,IAAI,CAQ9B;IAEQ,SAAS,IAAI,IAAI,CAWzB;IAID,OAAO,CAAC,UAAU;IAOlB,aAAa,CAAC,SAAS,SAAc,GAAG,IAAI,CAM3C;IAED,KAAK,CAAC,SAAS,SAAc,GAAG,IAAI,CAWnC;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;IAgBhB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGhC;IAED,cAAc,IAAI,IAAI,CAGrB;IAED,wEAAwE;IACxE,SAAS,IAAI,MAAM,GAAG,IAAI,CAazB;IAED;gCAC4B;IAC5B,IAAI,aAAa,IAAI;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,aAAa,CAAC;QACrB,MAAM,EAAE,aAAa,CAAC;KACvB,CAeA;CACF"}