@jrichman/ink 6.4.11 → 6.4.12

package/build/output.d.ts

@@ -1,5 +1,7 @@
 import { type StyledChar } from '@alcalzone/ansi-tokenize';
 import { type OutputTransformer } from './render-node-to-output.js';
+import { type CursorPosition } from './log-update.js';
+import { type StickyHeader, type DOMElement } from './dom.js';
 /**
 "Virtual" output class
 
@@ -7,9 +9,12 @@ Handles the positioning and saving of the output of each node in the tree. Also
 
 Used to generate the final output of all nodes before writing it to actual output stream (e.g. stdout)
 */
+export declare function clampCursorColumn(line: StyledChar[], col: number): number;
 type Options = {
     width: number;
     height: number;
+    node?: DOMElement;
+    id?: string | number;
 };
 type Clip = {
     x1: number | undefined;
@@ -17,34 +22,214 @@ type Clip = {
     y1: number | undefined;
     y2: number | undefined;
 };
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare function intersectRect(a: Rect, b: Rect): Rect | undefined;
+export declare function isRectIntersectingClip(rect: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}, clip: {
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+}): boolean;
+/**
+ * Represents a rendered rectangular area in the terminal.
+ * You can think of it a bit like a `<div>` element rendered in a web browser.
+ * Regions can be nested to support complex layouts, including scrollable areas,
+ * clipped views, and floating elements (like sticky headers).
+ * Each region contains its own localized buffer of rendered lines and maintains
+ * its own coordinates, dimensions, scroll state, borders, background colors, and children.
+ */
+export type Region = {
+    id: number | string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    lines: StyledChar[][];
+    styledOutput: StyledChar[][];
+    isScrollable: boolean;
+    isVerticallyScrollable?: boolean;
+    isHorizontallyScrollable?: boolean;
+    scrollTop?: number;
+    scrollLeft?: number;
+    scrollHeight?: number;
+    scrollWidth?: number;
+    scrollbarVisible?: boolean;
+    overflowToBackbuffer?: boolean;
+    marginRight?: number;
+    marginBottom?: number;
+    scrollbarThumbColor?: string;
+    backgroundColor?: string;
+    opaque?: boolean;
+    borderTop?: number;
+    borderBottom?: number;
+    stickyHeaders: StickyHeader[];
+    cachedStickyHeaders?: StickyHeader[];
+    children: Region[];
+    cursorPosition?: CursorPosition;
+    stableScrollback?: boolean;
+    nodeId?: number;
+    node?: DOMElement;
+    selectableText?: string;
+    selectableSpans: Array<{
+        y: number;
+        startX: number;
+        endX: number;
+        text: string;
+    }>;
+};
+export type RegionNode = {
+    id: string | number;
+    children: RegionNode[];
+};
+export type RegionUpdate = {
+    id: string | number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    scrollTop?: number;
+    scrollLeft?: number;
+    scrollHeight?: number;
+    scrollWidth?: number;
+    isScrollable?: boolean;
+    isVerticallyScrollable?: boolean;
+    isHorizontallyScrollable?: boolean;
+    scrollbarVisible?: boolean;
+    overflowToBackbuffer?: boolean;
+    marginRight?: number;
+    marginBottom?: number;
+    scrollbarThumbColor?: string;
+    backgroundColor?: string;
+    opaque?: boolean;
+    borderTop?: number;
+    borderBottom?: number;
+    stickyHeaders?: StickyHeader[];
+    lines?: {
+        updates: Array<{
+            start: number;
+            end: number;
+            data: Uint8Array;
+            source?: Uint8Array;
+        }>;
+        totalLength: number;
+    };
+};
+export declare const regionLayoutProperties: readonly ["x", "y", "width", "height", "scrollTop", "scrollLeft", "scrollHeight", "scrollWidth", "isScrollable", "isVerticallyScrollable", "isHorizontallyScrollable", "scrollbarVisible", "overflowToBackbuffer", "marginRight", "marginBottom", "scrollbarThumbColor", "backgroundColor", "opaque", "borderTop", "borderBottom"];
+export type RegionLayoutProps = {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    scrollTop?: number;
+    scrollLeft?: number;
+    scrollHeight?: number;
+    scrollWidth?: number;
+    isScrollable?: boolean;
+    isVerticallyScrollable?: boolean;
+    isHorizontallyScrollable?: boolean;
+    scrollbarVisible?: boolean;
+    overflowToBackbuffer?: boolean;
+    marginRight?: number;
+    marginBottom?: number;
+    scrollbarThumbColor?: string;
+    backgroundColor?: string;
+    opaque?: boolean;
+    borderTop?: number;
+    borderBottom?: number;
+};
+export declare function copyRegionProperty<K extends (typeof regionLayoutProperties)[number]>(target: RegionLayoutProps, source: RegionLayoutProps, key: K): void;
 export default class Output {
     width: number;
     height: number;
-    private readonly operations;
-    private cursorFocusInfo;
+    root: Region;
+    private readonly activeRegionStack;
     private readonly clips;
     constructor(options: Options);
     getCurrentClip(): Clip | undefined;
+    getActiveRegion(): Region;
+    getRegionAbsoluteOffset(): {
+        x: number;
+        y: number;
+    };
+    startChildRegion(options: {
+        id: number | string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        isScrollable: boolean;
+        isVerticallyScrollable?: boolean;
+        isHorizontallyScrollable?: boolean;
+        scrollState?: {
+            scrollTop: number;
+            scrollLeft: number;
+            scrollHeight: number;
+            scrollWidth: number;
+        };
+        scrollbarVisible?: boolean;
+        overflowToBackbuffer?: boolean;
+        marginRight?: number;
+        marginBottom?: number;
+        scrollbarThumbColor?: string;
+        backgroundColor?: string;
+        opaque?: boolean;
+        nodeId?: number;
+        stableScrollback?: boolean;
+        borderTop?: number;
+        borderBottom?: number;
+    }): void;
+    endChildRegion(): void;
+    addStickyHeader(header: StickyHeader): void;
     write(x: number, y: number, items: string | StyledChar[], options: {
         transformers: OutputTransformer[];
         lineIndex?: number;
         preserveBackgroundColor?: boolean;
         isTerminalCursorFocused?: boolean;
         terminalCursorPosition?: number;
+        isSelectable?: boolean;
     }): void;
     clip(clip: Clip): void;
     unclip(): void;
-    get(): {
-        output: string;
-        height: number;
-        styledOutput: StyledChar[][];
+    get(): Region;
+    addRegionTree(region: Region, x: number, y: number): void;
+    private cloneRegion;
+    private trimRegionLines;
+    private clampCursorPosition;
+    private initLines;
+    private applyWrite;
+    private clearRange;
+    private clipChars;
+}
+/**
+ * Flattens a hierarchy of nested regions into a single 2D array of styled characters
+ * that represents the final visual output to be written to the terminal.
+ * This effectively renders the nested region tree (much like compositing layers
+ * in a web browser) into a single screen buffer.
+ */
+export declare function flattenRegion(root: Region, options?: {
+    context?: {
         cursorPosition?: {
             row: number;
             col: number;
         };
     };
-    private clearRange;
-    private applyWriteOperation;
-    private clipChars;
-}
+    skipScrollbars?: boolean;
+    skipStickyHeaders?: boolean;
+}): StyledChar[][];
+export declare const extractSelectableText: (spans: Array<{
+    y: number;
+    startX: number;
+    endX: number;
+    text: string;
+}>) => string;
 export {};