@gajae-code/tui 0.1.1

package/dist/types/tui.d.ts

@@ -0,0 +1,161 @@
+import type { Terminal } from "./terminal";
+import { visibleWidth } from "./utils";
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+/**
+ * Component interface - all components must implement this
+ */
+export interface Component {
+    /**
+     * Render the component to lines for the given viewport width
+     * @param width - Current viewport width
+     * @returns Array of strings, each representing a line
+     */
+    render(width: number): string[];
+    /**
+     * Optional handler for keyboard input when component has focus
+     */
+    handleInput?(data: string): void;
+    /**
+     * If true, component receives key release events (Kitty protocol).
+     * Default is false - release events are filtered out.
+     */
+    wantsKeyRelease?: boolean;
+    /**
+     * Invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate(): void;
+}
+/**
+ * Interface for components that can receive focus and display a hardware cursor.
+ * When focused, the component should emit CURSOR_MARKER at the cursor position
+ * in its render output. TUI will find this marker and position the hardware
+ * cursor there for proper IME candidate window positioning.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+}
+/** Type guard to check if a component implements Focusable */
+export declare function isFocusable(component: Component | null): component is Component & Focusable;
+/**
+ * Cursor position marker - APC (Application Program Command) sequence.
+ * This is a zero-width escape sequence that terminals ignore.
+ * Components emit this at the cursor position when focused.
+ * TUI finds and strips this marker, then positions the hardware cursor there.
+ */
+export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+export { visibleWidth };
+/**
+ * Anchor position for overlays
+ */
+export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Margin configuration for overlays
+ */
+export interface OverlayMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Value that can be absolute (number) or percentage (string like "50%") */
+export type SizeValue = number | `${number}%`;
+/**
+ * Options for overlay positioning and sizing.
+ * Values can be absolute numbers or percentage strings (e.g., "50%").
+ */
+export interface OverlayOptions {
+    /** Width in columns, or percentage of terminal width (e.g., "50%") */
+    width?: SizeValue;
+    /** Minimum width in columns */
+    minWidth?: number;
+    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
+    maxHeight?: SizeValue;
+    /** Anchor point for positioning (default: 'center') */
+    anchor?: OverlayAnchor;
+    /** Horizontal offset from anchor position (positive = right) */
+    offsetX?: number;
+    /** Vertical offset from anchor position (positive = down) */
+    offsetY?: number;
+    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
+    row?: SizeValue;
+    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
+    col?: SizeValue;
+    /** Margin from terminal edges. Number applies to all sides. */
+    margin?: OverlayMargin | number;
+    /**
+     * Control overlay visibility based on terminal dimensions.
+     * If provided, overlay is only rendered when this returns true.
+     * Called each render cycle with current terminal dimensions.
+     */
+    visible?: (termWidth: number, termHeight: number) => boolean;
+}
+/**
+ * Handle returned by showOverlay for controlling the overlay
+ */
+export interface OverlayHandle {
+    /** Permanently remove the overlay (cannot be shown again) */
+    hide(): void;
+    /** Temporarily hide or show the overlay */
+    setHidden(hidden: boolean): void;
+    /** Check if overlay is temporarily hidden */
+    isHidden(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    children: Component[];
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    #private;
+    terminal: Terminal;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    overlayStack: {
+        component: Component;
+        options?: OverlayOptions;
+        preFocus: Component | null;
+        hidden: boolean;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    get fullRedraws(): number;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    /**
+     * Set whether to trigger full re-render when content shrinks.
+     * When true (default), empty rows are cleared when content shrinks.
+     * When false, empty rows remain (reduces redraws on slower terminals).
+     */
+    setClearOnShrink(enabled: boolean): void;
+    setFocus(component: Component | null): void;
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay(): void;
+    /** Check if there are any visible overlays */
+    hasOverlay(): boolean;
+    invalidate(): void;
+    start(): void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    stop(): void;
+    requestRender(force?: boolean): void;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,74 @@
+import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@gajae-code/natives";
+export { Ellipsis } from "@gajae-code/natives";
+export { getDefaultTabWidth, getIndentation } from "@gajae-code/utils";
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string;
+export declare function wrapTextWithAnsi(text: string, width: number): string[];
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;
+/**
+ * Tab width in columns for `file`, using `process.cwd()` as the project root for relative paths.
+ */
+export declare function getIndentationNoescape(file?: string): number;
+export declare function replaceTabs(text: string, file?: string): string;
+/**
+ * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
+ */
+export declare function padding(n: number): string;
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getSegmenter(): Intl.Segmenter;
+export declare function visibleWidthRaw(str: string): number;
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export declare function visibleWidth(str: string): number;
+/**
+ * Normalize text for terminal output without changing logical editor content.
+ * Some terminals render precomposed Thai/Lao AM vowels inconsistently during
+ * differential repaint. Their compatibility decompositions have the same cell
+ * width but avoid stale-cell artifacts in terminal renderers.
+ */
+export declare function normalizeTerminalOutput(str: string): string;
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Check if a character is punctuation.
+ */
+export declare function isPunctuationChar(char: string): boolean;
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export declare function getWordNavKind(grapheme: string): WordNavKind;
+export declare function isWordNavJoiner(grapheme: string): boolean;
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordLeft(text: string, cursor: number): number;
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordRight(text: string, cursor: number): number;
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;

package/package.json

@@ -0,0 +1,73 @@
+{
+	"type": "module",
+	"name": "@gajae-code/tui",
+	"version": "0.1.1",
+	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
+	"homepage": "https://gajae-code.dev",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gajae-ai/gajae-code.git",
+		"directory": "packages/tui"
+	},
+	"bugs": {
+		"url": "https://github.com/gajae-ai/gajae-code/issues"
+	},
+	"keywords": [
+		"tui",
+		"terminal",
+		"ui",
+		"text-editor",
+		"differential-rendering",
+		"typescript",
+		"cli"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test test/*.test.ts",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@gajae-code/natives": "0.1.1",
+		"@gajae-code/utils": "0.1.1",
+		"lru-cache": "11.3.6",
+		"marked": "^18.0.3"
+	},
+	"devDependencies": {
+		"chalk": "^5.6.2",
+		"@xterm/headless": "^6.0.0"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./components/*": {
+			"types": "./dist/types/components/*.d.ts",
+			"import": "./src/components/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}