@visulima/tui 0.0.1 → 1.0.0-alpha.1

package/dist/ink/components/Badge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Badge component for Ink.
+ *
+ * Inspired by ink-ui Badge by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-ui
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Label content. Strings are automatically uppercased.
+     */
+    readonly children: ReactNode;
+    /**
+     * Background color for the badge.
+     * @default "magenta"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+};
+/**
+ * Renders an uppercase colored label badge, useful for status indicators.
+ */
+export default function Badge({ children, color }: Props): ReactElement;

package/dist/ink/components/BigText.d.ts

@@ -0,0 +1,71 @@
+import type { ReactElement } from "react";
+/**
+ * Available CFonts font faces.
+ */
+type Font = "3d" | "block" | "chrome" | "grid" | "huge" | "pallet" | "shade" | "simple" | "simple3d" | "simpleBlock" | "slick" | "tiny";
+/**
+ * Horizontal text alignment.
+ */
+type Align = "center" | "left" | "right";
+/**
+ * Terminal background color names supported by CFonts.
+ */
+type BackgroundColor = "black" | "blue" | "cyan" | "green" | "magenta" | "red" | "transparent" | "white" | "yellow";
+type Props = {
+    /**
+     * Horizontal alignment of the text.
+     * @default "left"
+     */
+    readonly align?: Align;
+    /**
+     * Background color.
+     * @default "transparent"
+     */
+    readonly backgroundColor?: BackgroundColor;
+    /**
+     * Colors to use for the font. Accepts color names, hex values, or `"system"` for terminal default.
+     * @default ["system"]
+     */
+    readonly colors?: string[];
+    /**
+     * Font face to use.
+     * @default "block"
+     * @see https://github.com/dominikwilkowski/cfonts#supported-fonts
+     */
+    readonly font?: Font;
+    /**
+     * Letter spacing.
+     * @default 1
+     */
+    readonly letterSpacing?: number;
+    /**
+     * Line height.
+     * @default 1
+     */
+    readonly lineHeight?: number;
+    /**
+     * Maximum character length per line. `0` means no limit.
+     * @default 0
+     */
+    readonly maxLength?: number;
+    /**
+     * Whether to add an empty line on top and at the bottom of the output.
+     * @default true
+     */
+    readonly space?: boolean;
+    /**
+     * The text to render in a large font.
+     */
+    readonly text: string;
+};
+/**
+ * Render large terminal text using CFonts.
+ * @example
+ * ```tsx
+ * import { BigText } from "@visulima/tui/ink";
+ *
+ * <BigText text="Hello" font="block" />
+ * ```
+ */
+export default function BigText({ align, backgroundColor, colors, font, letterSpacing, lineHeight, maxLength, space, text }: Props): ReactElement;
+export type { Align, BackgroundColor, Font, Props };

package/dist/ink/components/Box.d.ts

@@ -0,0 +1,58 @@
+import type { ForwardRefExoticComponent, PropsWithChildren, ReactNode, RefAttributes } from "react";
+import type { Except } from "type-fest";
+import type { DOMElement } from "../dom.d.ts";
+import type { Styles } from "../styles.d.ts";
+export type Props = Except<Styles, "textWrap"> & {
+    /**
+     * Hide the element from screen readers.
+     */
+    readonly "aria-hidden"?: boolean;
+    /**
+     * A label for the element for screen readers.
+     */
+    readonly "aria-label"?: string;
+    /**
+     * The role of the element.
+     */
+    readonly "aria-role"?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
+    /**
+     * The state of the element.
+     */
+    readonly "aria-state"?: {
+        readonly busy?: boolean;
+        readonly checked?: boolean;
+        readonly disabled?: boolean;
+        readonly expanded?: boolean;
+        readonly multiline?: boolean;
+        readonly multiselectable?: boolean;
+        readonly readonly?: boolean;
+        readonly required?: boolean;
+        readonly selected?: boolean;
+    };
+    /**
+     * Whether this element is opaque (prevents rendering of covered content beneath it).
+     * Useful for performance optimization with layered content.
+     */
+    readonly opaque?: boolean;
+    /**
+     * Whether to render a scrollbar for this scrollable element.
+     * Only applies when `overflow` is `'scroll'`. Defaults to `true`.
+     */
+    readonly scrollbar?: boolean;
+    /**
+     * Makes this element sticky within its scroll container.
+     * - `true` or `'top'`: pinned to the top during scroll
+     * - `'bottom'`: pinned to the bottom during scroll
+     */
+    readonly sticky?: boolean | "top" | "bottom";
+    /**
+     * Alternate content to render when this element is in its sticky (pinned) state.
+     * Only applies when `sticky` is set. When omitted, the normal children are used.
+     */
+    readonly stickyChildren?: ReactNode;
+};
+/**
+ * `&lt;Box>` is an essential Ink component to build your layout. It's like `&lt;div style="display: flex">` in the browser.
+ */
+declare const Box: ForwardRefExoticComponent<PropsWithChildren<Props> & RefAttributes<DOMElement>>;
+export default Box;

package/dist/ink/components/Code.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Syntax-highlighted code display component for Ink.
+ *
+ * Uses Shiki for tokenization and maps themed tokens to colored
+ * Ink Text elements for terminal rendering.
+ */
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * The source code string to highlight.
+     */
+    readonly code: string;
+    /**
+     * Set of line numbers to visually emphasize.
+     */
+    readonly highlightLines?: ReadonlySet<number>;
+    /**
+     * Programming language for syntax highlighting.
+     * Falls back to plain text if the language is unknown.
+     */
+    readonly language?: string;
+    /**
+     * Whether to show line numbers in the gutter.
+     * @default false
+     */
+    readonly showLineNumbers?: boolean;
+    /**
+     * Starting line number (useful for code excerpts).
+     * @default 1
+     */
+    readonly startLine?: number;
+    /**
+     * Shiki theme name.
+     * @default "github-dark-default"
+     */
+    readonly theme?: string;
+};
+/**
+ * Render source code with syntax highlighting.
+ *
+ * ```tsx
+ * &lt;Code code="const x = 42;" language="typescript" />
+ * &lt;Code code={source} language="python" showLineNumbers />
+ * ```
+ */
+export default function Code({ code, highlightLines, language, showLineNumbers, startLine, theme }: Props): ReactElement;

package/dist/ink/components/ConfirmInput.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Confirm input component for Ink.
+ *
+ * Inspired by ink-ui ConfirmInput by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-ui
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * The default action when pressing Enter without typing Y or N.
+     * @default "confirm"
+     */
+    readonly defaultChoice?: "cancel" | "confirm";
+    /**
+     * Whether the input is disabled.
+     * @default false
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Called when the user cancels (presses N).
+     */
+    readonly onCancel: () => void;
+    /**
+     * Called when the user confirms (presses Y).
+     */
+    readonly onConfirm: () => void;
+    /**
+     * Whether pressing Enter submits the default choice.
+     * @default true
+     */
+    readonly submitOnEnter?: boolean;
+};
+/**
+ * Renders a Y/N confirmation prompt. Shows "Y/n" when default is confirm,
+ * or "y/N" when default is cancel.
+ */
+export default function ConfirmInput({ defaultChoice, isDisabled, onCancel, onConfirm, submitOnEnter }: Props): ReactElement;

package/dist/ink/components/ConsoleOverlay.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Console overlay component for Ink.
+ *
+ * Captures console.log/warn/error/debug output and displays it
+ * in a dockable panel within the TUI, similar to browser devtools.
+ */
+import type { ReactElement } from "react";
+import type { ConsoleLevel } from "../hooks/use-console-capture.d.ts";
+export type ConsoleOverlayDock = "bottom" | "top";
+export type Props = {
+    /**
+     * Dock position within the parent container.
+     * @default "bottom"
+     */
+    readonly dock?: ConsoleOverlayDock;
+    /**
+     * Which console levels to capture.
+     * @default ["log", "info", "warn", "error", "debug"]
+     */
+    readonly filter?: ReadonlyArray<ConsoleLevel>;
+    /**
+     * Visible height in rows.
+     * @default 8
+     */
+    readonly height?: number;
+    /**
+     * Maximum entries to keep in the buffer.
+     * @default 200
+     */
+    readonly maxEntries?: number;
+    /**
+     * Show the log level label.
+     * @default true
+     */
+    readonly showLevel?: boolean;
+    /**
+     * Show timestamps on each entry.
+     * @default true
+     */
+    readonly showTimestamp?: boolean;
+};
+/**
+ * A dockable console overlay that captures and displays console output.
+ *
+ * ```tsx
+ * &lt;Box flexDirection="column" height="100%">
+ *     &lt;Box flexGrow={1}>{mainContent}&lt;/Box>
+ *     &lt;ConsoleOverlay dock="bottom" height={6} />
+ * &lt;/Box>
+ * ```
+ */
+export default function ConsoleOverlay({ dock, filter, height, maxEntries, showLevel, showTimestamp }: Props): ReactElement;

package/dist/ink/components/Cursor.d.ts

@@ -0,0 +1,43 @@
+import type { RefObject } from "react";
+import React from "react";
+import type { DOMElement } from "../dom.d.ts";
+export type Props = {
+    /**
+     * Optional reference to anchor cursor coordinates to a different element.
+     * If omitted, `<Cursor>` uses the parent container as anchor.
+     * If `anchorRef` is set but currently unresolved, Ink hides the cursor for that frame.
+     * If multiple `<Cursor>` components are rendered in one frame, the last rendered one controls the terminal cursor position.
+     */
+    readonly anchorRef?: RefObject<DOMElement | null>;
+    /**
+     * Horizontal offset from anchor content origin.
+     */
+    readonly x?: number;
+    /**
+     * Vertical offset from anchor content origin.
+     */
+    readonly y?: number;
+};
+/**
+ * Declaratively position the terminal cursor.
+ * `&lt;Cursor>` must not be rendered inside `&lt;Text>`.
+ *
+ * **Inline mode** (no props): place `&lt;Cursor />` after a `&lt;Text>` node and the
+ * cursor appears where that text ended — even when text wraps across lines.
+ *
+ * **Anchor mode**: pass `anchorRef` and/or `x`/`y` to position relative to
+ * another element's content origin.
+ * @example Inline mode — cursor follows text naturally
+ * ```jsx
+ * <Box>
+ *     <Text>{prompt + value}</Text>
+ *     <Cursor />
+ * </Box>
+ * ```
+ * @example Anchor mode — offset from a referenced element
+ * ```jsx
+ * <Box ref={ref} />
+ * <Cursor anchorRef={ref} x={5} />
+ * ```
+ */
+export default function Cursor({ anchorRef, x, y }: Props): React.JSX.Element;

package/dist/ink/components/CursorContext.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from "react";
+import type { CursorPosition } from "../log-update.d.ts";
+export type Props = {
+    /**
+     * Set the cursor position relative to the Ink output.
+     *
+     * Pass `undefined` to hide the cursor.
+     */
+    readonly setCursorPosition: (position: CursorPosition | undefined) => void;
+};
+declare const CursorContext: Context<Props>;
+export default CursorContext;

package/dist/ink/components/Dialog.d.ts

@@ -0,0 +1,93 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ScrollViewRef } from "./index.d.ts";
+export type Props = {
+    /**
+     * Background color for the dialog. Defaults to the detected terminal
+     * background color, falling back to `"black"`.
+     */
+    readonly backgroundColor?: string;
+    /**
+     * Border color.
+     * @default "cyan"
+     */
+    readonly borderColor?: string;
+    /**
+     * Border style.
+     * @default "round"
+     */
+    readonly borderStyle?: "arrow" | "bold" | "classic" | "double" | "doubleSingle" | "round" | "single" | "singleDouble";
+    /**
+     * Dialog content.
+     */
+    readonly children: ReactNode;
+    /**
+     * Override terminal columns. Useful in renderToString or testing contexts
+     * where useWindowSize is unavailable.
+     */
+    readonly columns?: number;
+    /**
+     * Footer content rendered below the scrollable area.
+     * Useful for hints like "Press ? to close".
+     */
+    readonly footer?: ReactNode;
+    /**
+     * Maximum height as a fraction of terminal rows (0-1) or absolute rows.
+     * Values <= 1 are treated as fractions; values > 1 as absolute row counts.
+     * @default 0.8
+     */
+    readonly maxHeight?: number;
+    /**
+     * Padding inside the dialog border.
+     * @default 2
+     */
+    readonly paddingX?: number;
+    /**
+     * Vertical padding inside the dialog border.
+     * @default 1
+     */
+    readonly paddingY?: number;
+    /**
+     * Override terminal rows. Useful in renderToString or testing contexts
+     * where useWindowSize is unavailable.
+     */
+    readonly rows?: number;
+    /**
+     * Scrollbar visual style.
+     * @default "block"
+     */
+    readonly scrollbarStyle?: "arrow" | "block" | "bold" | "classic" | "dots" | "double" | "doubleSingle" | "line" | "round" | "single" | "singleDouble" | "thick";
+    /**
+     * Ref to the internal ScrollView for programmatic scrolling.
+     */
+    readonly scrollRef?: React.Ref<ScrollViewRef>;
+    /**
+     * Title rendered at the top of the dialog. If a string is provided,
+     * it is rendered as bold cyan text.
+     */
+    readonly title?: ReactNode;
+    /**
+     * Whether the dialog is visible. When `false`, nothing is rendered.
+     * @default true
+     */
+    readonly visible?: boolean;
+    /**
+     * Dialog width in columns.
+     * @default 60
+     */
+    readonly width?: number;
+};
+/**
+ * A centered overlay dialog with automatic scrolling and scrollbar when
+ * content exceeds the available terminal height.
+ *
+ * Uses the terminal's detected background color by default so the
+ * dialog blends with the user's theme.
+ *
+ * ```tsx
+ * &lt;Dialog title="Help" footer={&lt;Text dimColor>Press Esc to close&lt;/Text>}>
+ *   &lt;Text>Dialog content here&lt;/Text>
+ * &lt;/Dialog>
+ * ```
+ */
+declare const Dialog: ({ backgroundColor: backgroundColorProp, borderColor, borderStyle, children, columns: columnsProp, footer, maxHeight: maxHeightProp, paddingX, paddingY, rows: rowsProp, scrollbarStyle: scrollbarStyleProp, scrollRef: externalScrollRef, title, visible, width, }: Props) => ReactElement | null;
+export default Dialog;

package/dist/ink/components/DiffView.d.ts

@@ -0,0 +1,71 @@
+import type { ReactElement } from "react";
+export type DiffViewMode = "split" | "unified";
+export type InlineDiffMode = "chars" | "words";
+export type Props = {
+    /**
+     * Number of unchanged context lines around changes.
+     * @default 3
+     */
+    readonly context?: number;
+    /**
+     * Pre-computed unified diff string. If provided, `oldText`/`newText` are ignored.
+     */
+    readonly diff?: string;
+    /**
+     * Enable character-level inline diff highlighting within changed lines.
+     * @default true
+     */
+    readonly inlineDiff?: boolean;
+    /**
+     * Granularity of inline diff highlighting.
+     * - `"chars"` — character-level (best for code)
+     * - `"words"` — word-level (best for prose)
+     * @default "chars"
+     */
+    readonly inlineDiffMode?: InlineDiffMode;
+    /**
+     * Programming language for syntax highlighting within diff lines.
+     * When provided, diff content is highlighted with Shiki.
+     */
+    readonly language?: string;
+    /**
+     * Display mode: unified (interleaved) or split (side-by-side).
+     * @default "unified"
+     */
+    readonly mode?: DiffViewMode;
+    /**
+     * Label for the new version.
+     */
+    readonly newLabel?: string;
+    /**
+     * Modified text ("new" / right side).
+     */
+    readonly newText?: string;
+    /**
+     * Label for the old version.
+     */
+    readonly oldLabel?: string;
+    /**
+     * Original text ("old" / left side).
+     */
+    readonly oldText?: string;
+    /**
+     * Whether to display line numbers.
+     * @default true
+     */
+    readonly showLineNumbers?: boolean;
+    /**
+     * Shiki theme for syntax highlighting.
+     * @default "github-dark-default"
+     */
+    readonly theme?: string;
+};
+/**
+ * Display file differences with colored additions/deletions.
+ *
+ * ```tsx
+ * <DiffView oldText="hello" newText="hello world" />
+ * <DiffView diff={unifiedDiffString} mode="split" />
+ * ```
+ */
+export default function DiffView({ context, diff: diffProp, inlineDiff, inlineDiffMode, language, mode, newLabel, newText, oldLabel, oldText, showLineNumbers, theme, }: Props): ReactElement;

package/dist/ink/components/ErrorBoundary.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import { PureComponent } from "react";
+type Props = {
+    readonly children: ReactNode;
+    readonly onError: (error: Error) => void;
+};
+type State = {
+    readonly error?: Error;
+};
+export default class ErrorBoundary extends PureComponent<Props, State> {
+    static displayName: string;
+    static getDerivedStateFromError(error: Error): State;
+    state: State;
+    componentDidCatch(error: Error): void;
+    render(): ReactNode;
+}
+export {};

package/dist/ink/components/ErrorOverview.d.ts

@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+type Props = {
+    readonly error: Error;
+};
+export default function ErrorOverview({ error }: Props): ReactElement;
+export {};

package/dist/ink/components/FocusContext.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "react";
+export type Props = {
+    readonly activate: (id: string) => void;
+    readonly activeId?: string;
+    readonly add: (id: string, options: {
+        autoFocus: boolean;
+    }) => void;
+    readonly deactivate: (id: string) => void;
+    readonly disableFocus: () => void;
+    readonly enableFocus: () => void;
+    readonly focus: (id: string) => void;
+    readonly focusNext: () => void;
+    readonly focusPrevious: () => void;
+    readonly remove: (id: string) => void;
+};
+declare const FocusContext: Context<Props>;
+export default FocusContext;

package/dist/ink/components/Gradient.d.ts

@@ -0,0 +1,38 @@
+import { multilineGradient } from "@visulima/colorize/gradient";
+import type { ReactElement, ReactNode } from "react";
+/**
+ * A color stop for the gradient — hex string, CSS color name, RGB tuple, RGB object, or positioned stop.
+ */
+type GradientStop = Parameters<typeof multilineGradient>[0][number];
+/**
+ * Built-in gradient presets.
+ */
+type GradientName = "atlas" | "cristal" | "fruit" | "instagram" | "mind" | "morning" | "pastel" | "passion" | "rainbow" | "retro" | "summer" | "teen" | "vice";
+/**
+ * Custom gradient colors — an array of color stops accepted by `@visulima/colorize`'s gradient API.
+ */
+type GradientColors = GradientStop[];
+export type Props = {
+    /**
+     * The content to colorize.
+     *
+     * Multiple `&lt;Text>` children are treated as separate nodes, which preserves layout when `&lt;Gradient>` is placed inside a `&lt;Box flexDirection="column">`.
+     *
+     * If you want a continuous gradient across multiple lines, pass a single string or a single `&lt;Text>` with `\n`.
+     */
+    readonly children: ReactNode;
+    /**
+     * [Colors to use to make the gradient.](https://visulima.com/packages/colorize)
+     *
+     * Mutually exclusive with `name`.
+     */
+    readonly colors?: GradientColors;
+    /**
+     * The name of a built-in gradient preset.
+     *
+     * Mutually exclusive with `colors`.
+     */
+    readonly name?: GradientName;
+};
+export default function Gradient({ children, colors, name }: Props): ReactElement | null;
+export type { GradientColors, GradientName };

package/dist/ink/components/Help.d.ts

@@ -0,0 +1,49 @@
+import type { ReactElement } from "react";
+import type { KeyBinding } from "../hooks/use-key-bindings.d.ts";
+export type Props = {
+    /**
+     * Key bindings to display. Typically the `bindings` array returned by `useKeyBindings`.
+     */
+    readonly bindings: readonly KeyBinding[];
+    /**
+     * Color for description text.
+     *
+     * @default undefined (uses dimColor)
+     */
+    readonly descriptionColor?: string;
+    /**
+     * Color for key labels.
+     *
+     * @default "cyan"
+     */
+    readonly keyColor?: string;
+    /**
+     * Maximum number of columns in full mode.
+     *
+     * @default 3
+     */
+    readonly maxColumns?: number;
+    /**
+     * Display mode.
+     * - `"short"`: Single-line horizontal bar, truncated to terminal width.
+     * - `"full"`: Multi-column layout grouped by `group` field.
+     *
+     * @default "short"
+     */
+    readonly mode?: "full" | "short";
+    /**
+     * Separator between key-description pairs in short mode.
+     *
+     * @default " \u00b7 "
+     */
+    readonly separator?: string;
+};
+/**
+ * Renders a keybinding help bar from an array of `KeyBinding` definitions.
+ *
+ * ```tsx
+ * <Help bindings={bindings} />
+ * <Help bindings={bindings} mode="full" />
+ * ```
+ */
+export default function Help({ bindings, descriptionColor, keyColor, maxColumns, mode, separator, }: Props): ReactElement;