@visulima/tui 0.0.1 → 1.0.0-alpha.2

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

@@ -0,0 +1,26 @@
+/**
+ * Status message component for Ink.
+ *
+ * Inspired by ink-ui StatusMessage by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-ui
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { ReactElement, ReactNode } from "react";
+import type { Variant } from "./variant-config.d.ts";
+export type StatusMessageVariant = Variant;
+export type Props = {
+    /**
+     * Message content.
+     */
+    readonly children: ReactNode;
+    /**
+     * Determines the icon and color of the status message.
+     */
+    readonly variant: StatusMessageVariant;
+};
+/**
+ * Renders a status notification with a colored icon and message text.
+ */
+export default function StatusMessage({ children, variant }: Props): ReactElement;

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

@@ -0,0 +1,16 @@
+import type { Context } from "react";
+export type Props = {
+    /**
+     * Stderr stream passed to `render()` in `options.stderr` or `process.stderr` by default.
+     */
+    readonly stderr: NodeJS.WriteStream;
+    /**
+     * Write any string to stderr while preserving Ink's output. It's useful when you want to display external information outside of Ink's rendering and ensure there's no conflict between the two. It's similar to `<Static>`, except it can't accept components; it only works with strings.
+     */
+    readonly write: (data: string) => void;
+};
+/**
+ * `StderrContext` is a React context that exposes the stderr stream.
+ */
+declare const StderrContext: Context<Props>;
+export default StderrContext;

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

@@ -0,0 +1,29 @@
+import { EventEmitter } from "node:events";
+import type { Context } from "react";
+export type PublicProps = {
+    /**
+     * A boolean flag determining if the current `stdin` supports `setRawMode`. A component using `setRawMode` might want to use `isRawModeSupported` to nicely fall back in environments where raw mode is not supported.
+     */
+    readonly isRawModeSupported: boolean;
+    /**
+     * Ink exposes this function via own `<StdinContext>` to be able to handle Ctrl+C, that's why you should use Ink's `setRawMode` instead of `process.stdin.setRawMode`. If the `stdin` stream passed to Ink does not support setRawMode, this function does nothing.
+     */
+    readonly setRawMode: (value: boolean) => void;
+    /**
+     * The stdin stream passed to `render()` in `options.stdin`, or `process.stdin` by default. Useful if your app needs to handle user input.
+     */
+    readonly stdin: NodeJS.ReadStream;
+};
+export type Props = PublicProps & {
+    readonly internal_eventEmitter: EventEmitter;
+    readonly internal_exitOnCtrlC: boolean;
+    /**
+     * Enable or disable bracketed paste mode on the terminal. When enabled, pasted text is wrapped in escape sequences that allow it to be distinguished from typed input.
+     */
+    readonly setBracketedPasteMode: (value: boolean) => void;
+};
+/**
+ * `StdinContext` is a React context that exposes the input stream.
+ */
+declare const StdinContext: Context<Props>;
+export default StdinContext;

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

@@ -0,0 +1,16 @@
+import type { Context } from "react";
+export type Props = {
+    /**
+     * Stdout stream passed to `render()` in `options.stdout` or `process.stdout` by default.
+     */
+    readonly stdout: NodeJS.WriteStream;
+    /**
+     * Write any string to stdout while preserving Ink's output. It's useful when you want to display external information outside of Ink's rendering and ensure there's no conflict between the two. It's similar to `<Static>`, except it can't accept components; it only works with strings.
+     */
+    readonly write: (data: string) => void;
+};
+/**
+ * `StdoutContext` is a React context that exposes the stdout stream where Ink renders your app.
+ */
+declare const StdoutContext: Context<Props>;
+export default StdoutContext;

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

@@ -0,0 +1,44 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { UseStopwatchResult } from "../hooks/use-stopwatch.d.ts";
+export type StopwatchRef = Omit<UseStopwatchResult, "elapsed" | "isRunning" | "laps">;
+export type Props = {
+    /**
+     * Whether to start counting immediately.
+     *
+     * @default false
+     */
+    readonly autoStart?: boolean;
+    /**
+     * Make the rendered text bold.
+     */
+    readonly bold?: boolean;
+    /**
+     * Text color for the rendered time.
+     */
+    readonly color?: string;
+    /**
+     * Custom formatter for the elapsed time.
+     * Receives elapsed milliseconds, returns a display string.
+     *
+     * @default formatDuration (MM:SS or HH:MM:SS)
+     */
+    readonly format?: (elapsed: number) => string;
+    /**
+     * Tick interval in milliseconds.
+     *
+     * @default 1000
+     */
+    readonly interval?: number;
+};
+/**
+ * A count-up stopwatch component.
+ *
+ * Exposes `start`, `stop`, `toggle`, `reset`, and `lap` methods via ref.
+ *
+ * ```tsx
+ * const ref = useRef<StopwatchRef>(null);
+ * <Stopwatch ref={ref} autoStart />
+ * ```
+ */
+declare const Stopwatch: ForwardRefExoticComponent<Props & RefAttributes<StopwatchRef>>;
+export default Stopwatch;

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

@@ -0,0 +1,25 @@
+/**
+ * Tab component for Ink.
+ *
+ * Inspired by ink-tab by Julien Deniau.
+ * @see https://github.com/jdeniau/ink-tab
+ *
+ * MIT License
+ * Copyright (c) Julien Deniau (github.com/jdeniau)
+ */
+import type { ReactElement, ReactNode } from "react";
+export type Props = {
+    /**
+     * Tab content to render when the tab is active.
+     */
+    readonly children: ReactNode;
+    /**
+     * Unique name identifying this tab.
+     */
+    readonly name: string;
+};
+/**
+ * A single tab within a Tabs container.
+ * The `name` prop identifies the tab; `children` is rendered when active.
+ */
+export default function Tab({ children }: Props): ReactElement;

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

@@ -0,0 +1,80 @@
+import type { BorderStyle, HorizontalAlignment } from "@visulima/tabular";
+import type { ReactElement } from "react";
+/**
+ * Scalar value that can be displayed in a table cell.
+ */
+type Scalar = bigint | boolean | number | string | null | undefined;
+/**
+ * Dictionary with scalar values, representing a single row of data.
+ */
+type ScalarDict = Record<string, Scalar>;
+/**
+ * Configuration for a single table column.
+ */
+type ColumnConfig<T extends ScalarDict> = {
+    /**
+     * Horizontal alignment of cell content.
+     */
+    readonly align?: HorizontalAlignment;
+    /**
+     * Custom header label. Defaults to the key name.
+     */
+    readonly header?: string;
+    /**
+     * Key from the data object to display in this column.
+     */
+    readonly key: keyof T & string;
+    /**
+     * Fixed width for this column in characters.
+     */
+    readonly width?: number;
+};
+type Props<T extends ScalarDict> = {
+    /**
+     * Border style preset name or a custom `BorderStyle` object from `@visulima/tabular`.
+     * @default "default"
+     */
+    readonly borderStyle?: "ascii" | "block" | "default" | "dots" | "double" | "markdown" | "minimal" | "none" | "rounded" | "thick" | BorderStyle;
+    /**
+     * Columns to display and their order.
+     * Accepts simple key strings or `ColumnConfig` objects for advanced control.
+     * If omitted, all keys from the first data item are used.
+     */
+    readonly columns?: ((keyof T & string) | ColumnConfig<T>)[];
+    /**
+     * Array of objects to display as rows.
+     */
+    readonly data: T[];
+    /**
+     * Format a cell value before rendering. Return a string to display in the cell.
+     */
+    readonly formatCell?: (value: Scalar, column: keyof T & string, rowIndex: number) => string;
+    /**
+     * Format a header label before rendering. Return a string to display as the column header.
+     */
+    readonly formatHeader?: (column: keyof T & string) => string;
+    /**
+     * Maximum width of the table in characters. Columns will be truncated or wrapped to fit.
+     */
+    readonly maxWidth?: number;
+    /**
+     * Cell padding (left and right) in characters.
+     * @default 1
+     */
+    readonly padding?: number;
+    /**
+     * Whether to show the header row.
+     * @default true
+     */
+    readonly showHeader?: boolean;
+    /** Placeholder shown in place of `null` or `undefined` cell values. Defaults to an empty string. */
+    readonly skeleton?: string;
+    /**
+     * Enable word wrap instead of truncation when cells exceed their width.
+     * @default false
+     */
+    readonly wordWrap?: boolean;
+};
+declare const _default: <T extends ScalarDict>(props: Props<T>) => ReactElement;
+export default _default;
+export type { ColumnConfig, Props, Scalar, ScalarDict };

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

@@ -0,0 +1,104 @@
+/**
+ * Tabs component for Ink.
+ *
+ * Inspired by ink-tab by Julien Deniau.
+ * @see https://github.com/jdeniau/ink-tab
+ *
+ * MIT License
+ * Copyright (c) Julien Deniau (github.com/jdeniau)
+ */
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+import type { Props as TabProps } from "./Tab.d.ts";
+/**
+ * Keyboard navigation configuration for Tabs.
+ */
+export type KeyMap = {
+    /**
+     * Key names that move to the next tab.
+     * Defaults to `["rightArrow"]` for row layouts and `["downArrow"]` for column layouts.
+     */
+    readonly next?: ReadonlyArray<string>;
+    /**
+     * Key names that move to the previous tab.
+     * Defaults to `["leftArrow"]` for row layouts and `["upArrow"]` for column layouts.
+     */
+    readonly previous?: ReadonlyArray<string>;
+    /**
+     * Whether Meta/Cmd + 1–9 jumps to a specific tab.
+     * @default true
+     */
+    readonly useNumbers?: boolean;
+    /**
+     * Whether the Tab key cycles through tabs (only when `isFocused` is not managed by Ink).
+     * @default true
+     */
+    readonly useTab?: boolean;
+};
+/**
+ * Color customization for active tab styling.
+ */
+export type TabColors = {
+    readonly activeTab?: {
+        readonly backgroundColor?: LiteralUnion<AnsiColors, string>;
+        readonly color?: LiteralUnion<AnsiColors, string>;
+    };
+};
+export type Props = {
+    /**
+     * Tab elements to render.
+     */
+    readonly children: ReactNode;
+    /**
+     * Active tab colors. When `isFocused` is `false`, the active tab uses gray.
+     */
+    readonly colors?: TabColors;
+    /**
+     * Name of the tab to select initially (uncontrolled mode).
+     * Ignored when `value` is provided.
+     */
+    readonly defaultValue?: string;
+    /**
+     * Layout direction for the tab bar.
+     * @default "row"
+     */
+    readonly flexDirection?: "column" | "column-reverse" | "row" | "row-reverse";
+    /**
+     * Whether the tabs are focused and respond to keyboard input.
+     * - `true`: focused, uses active colors.
+     * - `false`: unfocused, uses gray active color, ignores input.
+     * - `undefined`/`null`: always active (focus not managed by Ink).
+     * @default undefined
+     */
+    readonly isFocused?: boolean | null;
+    /**
+     * Custom keyboard mappings.
+     */
+    readonly keyMap?: KeyMap;
+    /**
+     * Called when the active tab changes.
+     */
+    readonly onChange: (name: string, activeTab: ReactElement<TabProps>) => void;
+    /**
+     * Whether to display 1-based index numbers before each tab name.
+     * @default true
+     */
+    readonly showIndex?: boolean;
+    /**
+     * Controlled active tab name. When provided, the component is controlled —
+     * the parent owns the active tab state and must update it via `onChange`.
+     * When omitted, the component manages its own state (uncontrolled mode).
+     */
+    readonly value?: string;
+    /**
+     * Width of the container Box. Also determines the separator width in column layouts.
+     */
+    readonly width?: number | string;
+};
+/**
+ * Tabbed navigation component. Renders a row or column of tabs with keyboard
+ * navigation (arrow keys, Tab, number keys) and calls `onChange` when the
+ * active tab changes.
+ */
+export default function Tabs({ children, colors: colorsProp, defaultValue, flexDirection, isFocused, keyMap: keyMapProp, onChange, showIndex, value, width, }: Props): ReactElement;

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

@@ -0,0 +1,63 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+import type { Styles } from "../styles.d.ts";
+export type Props = {
+    /**
+     * Hide the element from screen readers.
+     */
+    readonly "aria-hidden"?: boolean;
+    /**
+     * A label for the element for screen readers.
+     */
+    readonly "aria-label"?: string;
+    /**
+     * Same as `color`, but for the background.
+     */
+    readonly backgroundColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Make the text bold.
+     */
+    readonly bold?: boolean;
+    readonly children?: ReactNode;
+    /**
+     * Change text color. Ink uses @visulima/colorize under the hood, so all its functionality is supported.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Dim the color (make it less bright).
+     */
+    readonly dimColor?: boolean;
+    /**
+     * Inverse background and foreground colors.
+     */
+    readonly inverse?: boolean;
+    /**
+     * Make the text italic.
+     */
+    readonly italic?: boolean;
+    /**
+     * Make the text crossed out with a line.
+     */
+    readonly strikethrough?: boolean;
+    /**
+     * Make the text underlined.
+     */
+    readonly underline?: boolean;
+    /**
+     * Controls how text wraps when it exceeds the container width.
+     *
+     * - `wrap` (default) — Wrap at word boundaries; break inside words only when a single word exceeds the width.
+     * - `wrap-anywhere` — Break at any character boundary, even when a whitespace break exists earlier.
+     * - `wrap-preserve-words` — Wrap at word boundaries; never break inside words (long words may overflow).
+     * - `wrap-strict` — Enforce exact width; always break at the column limit.
+     * - `truncate` / `truncate-end` — Truncate at the end with an ellipsis.
+     * - `truncate-start` — Truncate at the start with an ellipsis.
+     * - `truncate-middle` — Truncate in the middle with an ellipsis.
+     */
+    readonly wrap?: Styles["textWrap"];
+};
+/**
+ * This component can display text and change its style to make it bold, underlined, italic, or strikethrough.
+ */
+export default function Text({ "aria-hidden": ariaHidden, "aria-label": ariaLabel, backgroundColor, bold, children, color, dimColor, inverse, italic, strikethrough, underline, wrap, }: Props): ReactElement | null;

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

@@ -0,0 +1,48 @@
+/**
+ * Text input component for Ink.
+ *
+ * Inspired by ink-ui TextInput by Vadim Demedes and ink-text-input by Sindre Sorhus.
+ * @see https://github.com/vadimdemedes/ink-ui
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { ReactElement } from "react";
+export type Props = {
+    /** @default "" */
+    readonly defaultValue?: string;
+    /**
+     * When true, all input is ignored and text is dimmed.
+     * @default false
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * When true, renders asterisks instead of the actual characters.
+     * @default false
+     */
+    readonly mask?: boolean;
+    /**
+     * Fires on every keystroke with the updated text.
+     */
+    readonly onChange?: (value: string) => void;
+    /**
+     * Fires when the user presses Enter.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Greyed-out text shown when the input is empty.
+     */
+    readonly placeholder?: string;
+    /**
+     * Autocomplete candidates. The first case-sensitive prefix match is shown
+     * dimmed after the current input. Press right-arrow or Enter to accept.
+     */
+    readonly suggestions?: ReadonlyArray<string>;
+};
+/**
+ * A single-line text input with cursor navigation, optional placeholder,
+ * autocomplete suggestions, and password masking.
+ *
+ * Supports arrow keys, Home/End, Ctrl+A/E, Ctrl+U/K/W, Backspace, Delete.
+ */
+export default function TextInput({ defaultValue, isDisabled, mask, onChange, onSubmit, placeholder, suggestions }: Props): ReactElement;

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

@@ -0,0 +1,62 @@
+/**
+ * Multi-line text input component for Ink.
+ *
+ * Provides a full-featured textarea with cursor navigation, selection,
+ * clipboard support, undo/redo, and viewport scrolling.
+ */
+import type { ReactElement } from "react";
+export type Props = {
+    /** @default "" */
+    readonly defaultValue?: string;
+    /**
+     * When true, all input is ignored and text is dimmed.
+     * @default false
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * When true, the component responds to keyboard input.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Maximum visible rows before viewport scrolling kicks in.
+     * When set, the textarea will grow from `rows` to `maxRows` before scrolling.
+     */
+    readonly maxRows?: number;
+    /**
+     * Fires on every edit with the updated text.
+     */
+    readonly onChange?: (value: string) => void;
+    /**
+     * Fires when the user presses Meta+Enter or Ctrl+Enter.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Greyed-out text shown when the textarea is empty.
+     */
+    readonly placeholder?: string;
+    /**
+     * Number of visible rows (viewport height).
+     * @default 5
+     */
+    readonly rows?: number;
+    /**
+     * Show line numbers in the left gutter.
+     * @default false
+     */
+    readonly showLineNumbers?: boolean;
+    /**
+     * Number of spaces inserted for a Tab key press.
+     * @default 2
+     */
+    readonly tabSize?: number;
+};
+/**
+ * A multi-line text input with cursor navigation, selection, clipboard, undo/redo,
+ * paste support, and viewport scrolling.
+ *
+ * ```tsx
+ * <Textarea defaultValue="Hello\nWorld" rows={10} onChange={setValue} onSubmit={handleSubmit} />
+ * ```
+ */
+export default function Textarea({ defaultValue, isDisabled, isFocused, maxRows, onChange, onSubmit, placeholder, rows, showLineNumbers, tabSize, }: Props): ReactElement;

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

@@ -0,0 +1,52 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { UseTimerResult } from "../hooks/use-timer.d.ts";
+export type TimerRef = Omit<UseTimerResult, "isFinished" | "isRunning" | "remaining">;
+export type Props = {
+    /**
+     * Whether to start the timer immediately.
+     *
+     * @default false
+     */
+    readonly autoStart?: boolean;
+    /**
+     * Make the rendered text bold.
+     */
+    readonly bold?: boolean;
+    /**
+     * Text color for the rendered time.
+     */
+    readonly color?: string;
+    /**
+     * Total countdown duration in milliseconds.
+     */
+    readonly duration: number;
+    /**
+     * Custom formatter for the remaining time.
+     * Receives remaining milliseconds, returns a display string.
+     *
+     * @default formatDuration (MM:SS or HH:MM:SS)
+     */
+    readonly format?: (remaining: number) => string;
+    /**
+     * Tick interval in milliseconds.
+     *
+     * @default 1000
+     */
+    readonly interval?: number;
+    /**
+     * Called once when the timer reaches zero.
+     */
+    readonly onTimeout?: () => void;
+};
+/**
+ * A countdown timer component.
+ *
+ * Exposes `start`, `stop`, `toggle`, and `reset` methods via ref.
+ *
+ * ```tsx
+ * const ref = useRef<TimerRef>(null);
+ * <Timer ref={ref} duration={60_000} autoStart />
+ * ```
+ */
+declare const Timer: ForwardRefExoticComponent<Props & RefAttributes<TimerRef>>;
+export default Timer;

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

@@ -0,0 +1,16 @@
+import type { ReactElement, ReactNode } from "react";
+export type Props = {
+    /**
+     * Screen-reader-specific text to output. If this is set, all children will be ignored.
+     */
+    readonly accessibilityLabel?: string;
+    readonly children?: ReactNode;
+    /**
+     * Function that transforms children output. It accepts children and must return transformed children as well. Note that when children use `<Text>` styling props (e.g. `color`, `bold`), the string will contain ANSI escape codes.
+     */
+    readonly transform: (children: string, index: number) => string;
+};
+/**
+ * Transform a string representation of React components before they're written to output. For example, you might want to apply a gradient to text, add a clickable link, or create some text effects. These use cases can't accept React nodes as input; they expect a string. That's what the <Transform> component does: it gives you an output string of its child components and lets you transform it in any way.
+ */
+export default function Transform({ accessibilityLabel, children, transform }: Props): ReactElement | null;

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

@@ -0,0 +1,35 @@
+/**
+ * Unordered list component for Ink.
+ *
+ * Inspired by ink-ui UnorderedList by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-ui
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { ReactElement, ReactNode } from "react";
+export type UnorderedListEntry = {
+    /**
+     * Content of the list entry. Can be a string or nested list.
+     */
+    readonly children?: ReadonlyArray<UnorderedListEntry>;
+    /**
+     * Display text for this item.
+     */
+    readonly label: ReactNode;
+};
+export type Props = {
+    /**
+     * Entries to render as a bullet list.
+     */
+    readonly items: ReadonlyArray<UnorderedListEntry>;
+    /**
+     * Custom bullet symbol(s). A string uses the same symbol at all depths.
+     * An array cycles through symbols by nesting depth.
+     */
+    readonly marker?: ReadonlyArray<string> | string;
+};
+/**
+ * Renders a bullet list with nesting support.
+ */
+export default function UnorderedList({ items, marker }: Props): ReactElement;