@opentui/core 0.1.23 → 0.1.25

package/lib/KeyHandler.d.ts

@@ -1,11 +1,18 @@
 import { EventEmitter } from "events";
 import { type ParsedKey } from "./parse.keypress";
+export type { ParsedKey };
 type KeyHandlerEventMap = {
     keypress: [ParsedKey];
+    keyrepeat: [ParsedKey];
+    keyrelease: [ParsedKey];
+    paste: [string];
 };
 export declare class KeyHandler extends EventEmitter<KeyHandlerEventMap> {
-    constructor();
+    private stdin;
+    private useKittyKeyboard;
+    private listener;
+    private pasteMode;
+    private pasteBuffer;
+    constructor(stdin?: NodeJS.ReadStream, useKittyKeyboard?: boolean);
     destroy(): void;
 }
-export declare function getKeyHandler(): KeyHandler;
-export {};

package/lib/env.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment variable registry
+ *
+ * Usage:
+ * ```ts
+ * import { registerEnvVar, env } from "./lib/env.ts";
+ *
+ * // Register environment variables
+ * registerEnvVar({
+ *   name: "DEBUG",
+ *   description: "Enable debug logging",
+ *   type: "boolean",
+ *   default: false
+ * });
+ *
+ * registerEnvVar({
+ *   name: "PORT",
+ *   description: "Server port number",
+ *   type: "number",
+ *   default: 3000
+ * });
+ *
+ * // Access environment variables
+ * if (env.DEBUG) {
+ *   console.log("Debug mode enabled");
+ * }
+ *
+ * const port = env.PORT; // number
+ * ```
+ */
+export interface EnvVarConfig {
+    name: string;
+    description: string;
+    default?: string | boolean | number;
+    type?: "string" | "boolean" | "number";
+}
+export declare const envRegistry: Record<string, EnvVarConfig>;
+export declare function registerEnvVar(config: EnvVarConfig): void;
+export declare function generateEnvMarkdown(): string;
+export declare function generateEnvColored(): string;
+export declare const env: Record<string, string | number | boolean>;

package/lib/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./border";
-export * from "./TrackedNode";
 export * from "./KeyHandler";
 export * from "./ascii.font";
 export * from "./hast-styled-text";
@@ -9,3 +8,4 @@ export * from "./styled-text";
 export * from "./yoga.options";
 export * from "./parse.mouse";
 export * from "./selection";
+export * from "./env";

package/lib/parse.keypress-kitty.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedKey } from "./parse.keypress";
+export declare function parseKittyKeyboard(sequence: string): ParsedKey | null;

package/lib/parse.keypress.d.ts

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 export declare const nonAlphanumericKeys: string[];
+export type KeyEventType = "press" | "repeat" | "release";
 export type ParsedKey = {
     name: string;
     ctrl: boolean;
@@ -9,6 +10,15 @@ export type ParsedKey = {
     sequence: string;
     number: boolean;
     raw: string;
+    eventType: KeyEventType;
     code?: string;
+    super?: boolean;
+    hyper?: boolean;
+    capsLock?: boolean;
+    numLock?: boolean;
+    baseCode?: number;
 };
-export declare const parseKeypress: (s?: Buffer | string) => ParsedKey;
+export type ParseKeypressOptions = {
+    useKittyKeyboard?: boolean;
+};
+export declare const parseKeypress: (s?: Buffer | string, options?: ParseKeypressOptions) => ParsedKey;

package/lib/renderable.validations.d.ts

@@ -0,0 +1,12 @@
+import type { RenderableOptions, Renderable } from "../Renderable";
+import type { PositionTypeString, OverflowString } from "./yoga.options";
+export declare function validateOptions(id: string, options: RenderableOptions<Renderable>): void;
+export declare function isValidPercentage(value: any): value is `${number}%`;
+export declare function isMarginType(value: any): value is number | "auto" | `${number}%`;
+export declare function isPaddingType(value: any): value is number | `${number}%`;
+export declare function isPositionType(value: any): value is number | "auto" | `${number}%`;
+export declare function isPositionTypeType(value: any): value is PositionTypeString;
+export declare function isOverflowType(value: any): value is OverflowString;
+export declare function isDimensionType(value: any): value is number | "auto" | `${number}%`;
+export declare function isFlexBasisType(value: any): value is number | "auto" | undefined;
+export declare function isSizeType(value: any): value is number | `${number}%` | undefined;

package/package.json

@@ -4,7 +4,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "OpenTUI is a TypeScript library for building terminal user interfaces (TUIs)",
   "license": "MIT",
   "repository": {
@@ -22,27 +22,29 @@
       "import": "./3d.js",
       "require": "./3d.js",
       "types": "./3d.d.ts"
+    },
+    "./testing": {
+      "import": "./testing.js",
+      "require": "./testing.js",
+      "types": "./testing.d.ts"
     }
   },
-  "dependencies": {
-    "jimp": "1.6.0",
-    "yoga-layout": "3.2.1"
-  },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/three": "0.177.0",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "typescript": "^5"
   },
   "optionalDependencies": {
     "@dimforge/rapier2d-simd-compat": "^0.17.3",
     "bun-webgpu": "0.1.3",
     "planck": "^1.4.2",
     "three": "0.177.0",
-    "@opentui/core-darwin-x64": "0.1.23",
-    "@opentui/core-darwin-arm64": "0.1.23",
-    "@opentui/core-linux-x64": "0.1.23",
-    "@opentui/core-linux-arm64": "0.1.23",
-    "@opentui/core-win32-x64": "0.1.23",
-    "@opentui/core-win32-arm64": "0.1.23"
+    "@opentui/core-darwin-x64": "0.1.25",
+    "@opentui/core-darwin-arm64": "0.1.25",
+    "@opentui/core-linux-x64": "0.1.25",
+    "@opentui/core-linux-arm64": "0.1.25",
+    "@opentui/core-win32-x64": "0.1.25",
+    "@opentui/core-win32-arm64": "0.1.25"
   }
 }

package/renderables/ASCIIFont.d.ts

@@ -4,7 +4,7 @@ import { type fonts, type ASCIIFontName } from "../lib/ascii.font";
 import { RGBA } from "../lib/RGBA";
 import { FrameBufferRenderable } from "./FrameBuffer";
 import type { RenderContext } from "../types";
-export interface ASCIIFontOptions extends RenderableOptions<ASCIIFontRenderable> {
+export interface ASCIIFontOptions extends Omit<RenderableOptions<ASCIIFontRenderable>, "width" | "height"> {
     text?: string;
     font?: ASCIIFontName;
     fg?: RGBA | RGBA[];

package/renderables/Input.d.ts

@@ -54,8 +54,8 @@ export declare class InputRenderable extends Renderable {
     set placeholder(placeholder: string);
     get cursorPosition(): number;
     set cursorPosition(position: number);
-    private insertText;
-    private deleteCharacter;
+    insertText(text: string): void;
+    deleteCharacter(direction: "backward" | "forward"): void;
     handleKeyPress(key: ParsedKey | string): boolean;
     set maxLength(maxLength: number);
     set backgroundColor(value: ColorInput);

package/renderables/ScrollBox.d.ts

@@ -20,6 +20,8 @@ export interface ScrollBoxOptions extends BoxOptions<ScrollBoxRenderable> {
     horizontalScrollbarOptions?: Omit<ScrollBarOptions, "orientation">;
     stickyScroll?: boolean;
     stickyStart?: "bottom" | "top" | "left" | "right";
+    scrollX?: boolean;
+    scrollY?: boolean;
 }
 export declare class ScrollBoxRenderable extends BoxRenderable {
     static idCounter: number;
@@ -61,7 +63,7 @@ export declare class ScrollBoxRenderable extends BoxRenderable {
     get scrollHeight(): number;
     private updateStickyState;
     private applyStickyStart;
-    constructor(ctx: RenderContext, { wrapperOptions, viewportOptions, contentOptions, rootOptions, scrollbarOptions, verticalScrollbarOptions, horizontalScrollbarOptions, stickyScroll, stickyStart, ...options }: ScrollBoxOptions);
+    constructor(ctx: RenderContext, { wrapperOptions, viewportOptions, contentOptions, rootOptions, scrollbarOptions, verticalScrollbarOptions, horizontalScrollbarOptions, stickyScroll, stickyStart, scrollX, scrollY, ...options }: ScrollBoxOptions);
     protected onUpdate(deltaTime: number): void;
     scrollBy(delta: number | {
         x: number;

package/renderables/Slider.d.ts

@@ -1,31 +1,44 @@
 import { type ColorInput, OptimizedBuffer, Renderable, type RenderableOptions, type RenderContext, RGBA } from "../index";
 export interface SliderOptions extends RenderableOptions<SliderRenderable> {
     orientation: "vertical" | "horizontal";
-    thumbSize?: number;
-    thumbPosition?: number;
+    value?: number;
+    min?: number;
+    max?: number;
+    viewPortSize?: number;
     backgroundColor?: ColorInput;
     foregroundColor?: ColorInput;
-    onChange?: (position: number) => void;
+    onChange?: (value: number) => void;
 }
 export declare class SliderRenderable extends Renderable {
     readonly orientation: "vertical" | "horizontal";
-    private _thumbSize;
-    private _thumbPosition;
+    private _value;
+    private _min;
+    private _max;
+    private _viewPortSize;
     private _backgroundColor;
     private _foregroundColor;
     private _onChange?;
     constructor(ctx: RenderContext, options: SliderOptions);
-    get thumbSize(): number;
-    set thumbSize(value: number);
-    get thumbPosition(): number;
-    set thumbPosition(value: number);
+    get value(): number;
+    set value(newValue: number);
+    get min(): number;
+    set min(newMin: number);
+    get max(): number;
+    set max(newMax: number);
+    set viewPortSize(size: number);
+    get viewPortSize(): number;
     get backgroundColor(): RGBA;
     set backgroundColor(value: ColorInput);
     get foregroundColor(): RGBA;
     set foregroundColor(value: ColorInput);
+    private calculateDragOffsetVirtual;
     private setupMouseHandling;
-    private updatePositionFromMouse;
-    private getThumbPosition;
+    private updateValueFromMouseDirect;
+    private updateValueFromMouseWithOffset;
     private getThumbRect;
     protected renderSelf(buffer: OptimizedBuffer): void;
+    private renderHorizontal;
+    private renderVertical;
+    private getVirtualThumbSize;
+    private getVirtualThumbStart;
 }

package/renderables/Text.d.ts

@@ -5,7 +5,7 @@ import { type TextChunk } from "../text-buffer";
 import { RGBA } from "../lib/RGBA";
 import { type RenderContext } from "../types";
 import type { OptimizedBuffer } from "../buffer";
-import { TextNodeRenderable } from "./TextNode";
+import { RootTextNodeRenderable, TextNodeRenderable } from "./TextNode";
 export interface TextOptions extends RenderableOptions<TextRenderable> {
     content?: StyledText | string;
     fg?: string | RGBA;
@@ -14,19 +14,24 @@ export interface TextOptions extends RenderableOptions<TextRenderable> {
     selectionFg?: string | RGBA;
     selectable?: boolean;
     attributes?: number;
+    wrap?: boolean;
+    wrapMode?: "char" | "word";
 }
 export declare class TextRenderable extends Renderable {
     selectable: boolean;
     private _text;
+    private _hasManualStyledText;
     private _defaultFg;
     private _defaultBg;
     private _defaultAttributes;
     private _selectionBg;
     private _selectionFg;
+    private _wrap;
+    private _wrapMode;
     private lastLocalSelection;
     private textBuffer;
     private _lineInfo;
-    private rootTextNode;
+    protected rootTextNode: RootTextNodeRenderable;
     protected _defaultOptions: {
         content: string;
         fg: RGBA;
@@ -35,6 +40,8 @@ export declare class TextRenderable extends Renderable {
         selectionFg: undefined;
         selectable: true;
         attributes: number;
+        wrap: true;
+        wrapMode: "char" | "word";
     };
     constructor(ctx: RenderContext, options: TextOptions);
     private updateTextBuffer;
@@ -43,6 +50,7 @@ export declare class TextRenderable extends Renderable {
     get plainText(): string;
     get textLength(): number;
     get chunks(): TextChunk[];
+    get textNode(): RootTextNodeRenderable;
     set content(value: StyledText | string);
     get fg(): RGBA;
     set fg(value: RGBA | string | undefined);
@@ -54,9 +62,15 @@ export declare class TextRenderable extends Renderable {
     set bg(value: RGBA | string | undefined);
     get attributes(): number;
     set attributes(value: number);
+    get wrap(): boolean;
+    set wrap(value: boolean);
+    get wrapMode(): "char" | "word";
+    set wrapMode(value: "char" | "word");
     protected onResize(width: number, height: number): void;
     private updateLocalSelection;
     private updateTextInfo;
+    private updateLineInfo;
+    private updateWrapWidth;
     private setupMeasureFunc;
     insertChunk(chunk: TextChunk, index?: number): void;
     removeChunk(chunk: TextChunk): void;
@@ -65,6 +79,7 @@ export declare class TextRenderable extends Renderable {
     add(obj: TextNodeRenderable | StyledText | string, index?: number): number;
     remove(id: string): void;
     insertBefore(obj: BaseRenderable | any, anchor?: TextNodeRenderable): number;
+    getTextChildren(): BaseRenderable[];
     clear(): void;
     shouldStartSelection(x: number, y: number): boolean;
     onSelectionChanged(selection: Selection | null): boolean;
@@ -74,7 +89,7 @@ export declare class TextRenderable extends Renderable {
         start: number;
         end: number;
     } | null;
-    protected onUpdate(deltaTime: number): void;
+    onLifecyclePass: () => void;
     render(buffer: OptimizedBuffer, deltaTime: number): void;
     protected renderSelf(buffer: OptimizedBuffer): void;
     destroy(): void;

package/renderables/TextNode.d.ts

@@ -1,3 +1,4 @@
+import type { TextRenderable } from ".";
 import { BaseRenderable, type BaseRenderableOptions } from "../Renderable";
 import { RGBA } from "../lib/RGBA";
 import { StyledText } from "../lib/styled-text";
@@ -12,9 +13,9 @@ declare const BrandedTextNodeRenderable: unique symbol;
 export declare function isTextNodeRenderable(obj: any): obj is TextNodeRenderable;
 export declare class TextNodeRenderable extends BaseRenderable {
     [BrandedTextNodeRenderable]: boolean;
-    fg?: RGBA;
-    bg?: RGBA;
-    attributes: number;
+    private _fg?;
+    private _bg?;
+    private _attributes;
     private _children;
     parent: TextNodeRenderable | null;
     constructor(options: TextNodeOptions);
@@ -22,6 +23,7 @@ export declare class TextNodeRenderable extends BaseRenderable {
     set children(children: (string | TextNodeRenderable)[]);
     requestRender(): void;
     add(obj: TextNodeRenderable | StyledText | string, index?: number): number;
+    replace(obj: TextNodeRenderable | string, index: number): void;
     insertBefore(child: string | TextNodeRenderable | StyledText, anchorNode: TextNodeRenderable | string | unknown): this;
     remove(child: string | TextNodeRenderable): this;
     clear(): void;
@@ -49,10 +51,17 @@ export declare class TextNodeRenderable extends BaseRenderable {
     getChildren(): BaseRenderable[];
     getChildrenCount(): number;
     getRenderable(id: string): BaseRenderable | undefined;
+    get fg(): RGBA | undefined;
+    set fg(fg: RGBA | string | undefined);
+    set bg(bg: RGBA | string | undefined);
+    get bg(): RGBA | undefined;
+    set attributes(attributes: number);
+    get attributes(): number;
 }
 export declare class RootTextNodeRenderable extends TextNodeRenderable {
     private readonly ctx;
-    constructor(ctx: RenderContext, options: TextNodeOptions);
+    textParent: TextRenderable;
+    constructor(ctx: RenderContext, options: TextNodeOptions, textParent: TextRenderable);
     requestRender(): void;
 }
 export {};

package/renderer.d.ts

@@ -8,6 +8,7 @@ import { TerminalConsole, type ConsoleOptions } from "./console";
 import { type MouseEventType, type RawMouseEvent, type ScrollInfo } from "./lib/parse.mouse";
 import { Selection } from "./lib/selection";
 import { EventEmitter } from "events";
+import { KeyHandler } from "./lib/KeyHandler";
 export interface CliRendererConfig {
     stdin?: NodeJS.ReadStream;
     stdout?: NodeJS.WriteStream;
@@ -25,6 +26,7 @@ export interface CliRendererConfig {
     useAlternateScreen?: boolean;
     useConsole?: boolean;
     experimental_splitHeight?: number;
+    useKittyKeyboard?: boolean;
 }
 export type PixelResolution = {
     width: number;
@@ -78,6 +80,7 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     currentRenderBuffer: OptimizedBuffer;
     private _isRunning;
     private targetFps;
+    private automaticMemorySnapshot;
     private memorySnapshotInterval;
     private memorySnapshotTimer;
     private lastMemorySnapshot;
@@ -111,6 +114,7 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     };
     private _console;
     private _resolution;
+    private _keyHandler;
     private animationRequest;
     private resizeTimeoutId;
     private resizeDebounceDelay;
@@ -135,7 +139,15 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     private _capabilities;
     private _latestPointer;
     private _currentFocusedRenderable;
+    private lifecyclePasses;
+    private handleError;
+    private dumpOutputCache;
+    private exitHandler;
+    private warningHandler;
     constructor(lib: RenderLib, rendererPtr: Pointer, stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream, width: number, height: number, config?: CliRendererConfig);
+    registerLifecyclePass(renderable: Renderable): void;
+    unregisterLifecyclePass(renderable: Renderable): void;
+    getLifecyclePasses(): Set<Renderable>;
     get currentFocusedRenderable(): Renderable | null;
     focusRenderable(renderable: Renderable): void;
     addToHitGrid(x: number, y: number, width: number, height: number, id: number): void;
@@ -147,6 +159,7 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     get isRunning(): boolean;
     get resolution(): PixelResolution | null;
     get console(): TerminalConsole;
+    get keyInput(): KeyHandler;
     get terminalWidth(): number;
     get terminalHeight(): number;
     get useThread(): boolean;
@@ -158,7 +171,7 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     get capabilities(): any | null;
     set experimental_splitHeight(splitHeight: number);
     private interceptStdoutWrite;
-    private disableStdoutInterception;
+    disableStdoutInterception(): void;
     private flushStdoutCache;
     private enableMouse;
     private disableMouse;
@@ -166,9 +179,12 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
     disableKittyKeyboard(): void;
     set useThread(useThread: boolean);
     setupTerminal(): Promise<void>;
+    private stdinListener;
+    private setupInput;
     private handleMouseData;
     private takeMemorySnapshot;
     private startMemorySnapshotTimer;
+    private stopMemorySnapshotTimer;
     setMemorySnapshotInterval(interval: number): void;
     private handleResize;
     private queryPixelResolution;
@@ -179,7 +195,6 @@ export declare class CliRenderer extends EventEmitter implements RenderContext {
         enabled?: boolean;
         corner?: DebugOverlayCorner;
     }): void;
-    clearTerminal(): void;
     setTerminalTitle(title: string): void;
     dumpHitGrid(): void;
     dumpBuffers(timestamp?: number): void;

package/testing/mock-keys.d.ts

@@ -64,4 +64,5 @@ export declare function createMockKeys(renderer: CliRenderer): {
     pressBackspace: () => void;
     pressArrow: (direction: "up" | "down" | "left" | "right") => void;
     pressCtrlC: () => void;
+    pasteBracketedText: (text: string) => Promise<void>;
 };

package/testing/mock-mouse.d.ts

@@ -0,0 +1,38 @@
+import type { CliRenderer } from "../renderer";
+export declare const MouseButtons: {
+    readonly LEFT: 0;
+    readonly MIDDLE: 1;
+    readonly RIGHT: 2;
+    readonly WHEEL_UP: 64;
+    readonly WHEEL_DOWN: 65;
+    readonly WHEEL_LEFT: 66;
+    readonly WHEEL_RIGHT: 67;
+};
+export type MouseButton = (typeof MouseButtons)[keyof typeof MouseButtons];
+export interface MousePosition {
+    x: number;
+    y: number;
+}
+export interface MouseModifiers {
+    shift?: boolean;
+    alt?: boolean;
+    ctrl?: boolean;
+}
+export type MouseEventType = "down" | "up" | "move" | "drag" | "scroll";
+export interface MouseEventOptions {
+    button?: MouseButton;
+    modifiers?: MouseModifiers;
+    delayMs?: number;
+}
+export declare function createMockMouse(renderer: CliRenderer): {
+    moveTo: (x: number, y: number, options?: MouseEventOptions) => Promise<void>;
+    click: (x: number, y: number, button?: MouseButton, options?: MouseEventOptions) => Promise<void>;
+    doubleClick: (x: number, y: number, button?: MouseButton, options?: MouseEventOptions) => Promise<void>;
+    pressDown: (x: number, y: number, button?: MouseButton, options?: MouseEventOptions) => Promise<void>;
+    release: (x: number, y: number, button?: MouseButton, options?: MouseEventOptions) => Promise<void>;
+    drag: (startX: number, startY: number, endX: number, endY: number, button?: MouseButton, options?: MouseEventOptions) => Promise<void>;
+    scroll: (x: number, y: number, direction: "up" | "down" | "left" | "right", options?: MouseEventOptions) => Promise<void>;
+    getCurrentPosition: () => MousePosition;
+    getPressedButtons: () => MouseButton[];
+    emitMouseEvent: (type: MouseEventType, x: number, y: number, button?: MouseButton, options?: Omit<MouseEventOptions, "button">) => Promise<void>;
+};

package/testing/test-renderer.d.ts

@@ -1,6 +1,19 @@
 import { CliRenderer, type CliRendererConfig } from "../renderer";
 import { createMockKeys } from "./mock-keys";
-export declare function createTestRenderer(options: CliRendererConfig): Promise<{
-    renderer: CliRenderer;
-    mockInput: ReturnType<typeof createMockKeys>;
+import { createMockMouse } from "./mock-mouse";
+export interface TestRendererOptions extends CliRendererConfig {
+    width?: number;
+    height?: number;
+}
+export interface TestRenderer extends CliRenderer {
+}
+export type MockInput = ReturnType<typeof createMockKeys>;
+export type MockMouse = ReturnType<typeof createMockMouse>;
+export declare function createTestRenderer(options: TestRendererOptions): Promise<{
+    renderer: TestRenderer;
+    mockInput: MockInput;
+    mockMouse: MockMouse;
+    renderOnce: () => Promise<void>;
+    captureCharFrame: () => string;
+    resize: (width: number, height: number) => void;
 }>;

package/testing.d.ts

@@ -0,0 +1,3 @@
+export * from "./testing/test-renderer";
+export * from "./testing/mock-keys";
+export * from "./testing/mock-mouse";