@visulima/tui 1.0.0-alpha.1 → 1.0.0-alpha.3

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

@@ -0,0 +1,70 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type MenuItem = {
+    /**
+     * Optional hotkey rendered on the right side of the row (e.g. `"Ctrl+S"`).
+     */
+    readonly hotkey?: string;
+    /**
+     * Optional icon rendered before the label.
+     */
+    readonly icon?: ReactNode;
+    /**
+     * Identifier returned by `onSelect`.
+     */
+    readonly id: string;
+    /**
+     * When true, renders the item dimmed and skips it during navigation.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Human-readable label.
+     */
+    readonly label: ReactNode;
+};
+export type MenuSection = {
+    readonly id: string;
+    readonly items: ReadonlyArray<MenuItem>;
+    readonly title?: string;
+};
+export type Props = {
+    /**
+     * Accent color for the focused item.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the menu on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Render a border around the menu.
+     * @default true
+     */
+    readonly bordered?: boolean;
+    /**
+     * Flat list of items. Ignored if `sections` is provided.
+     */
+    readonly items?: ReadonlyArray<MenuItem>;
+    /**
+     * Called with the item id when the user presses Enter.
+     */
+    readonly onSelect: (id: string) => void;
+    /**
+     * Grouped items. Takes precedence over `items`.
+     */
+    readonly sections?: ReadonlyArray<MenuSection>;
+    /**
+     * Optional title rendered at the top of the menu.
+     */
+    readonly title?: string;
+};
+/**
+ * Dropdown / context menu with optional sections and disabled items.
+ * Keyboard: ↑/↓ (or j/k) to navigate, Enter to select, Esc to cancel.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the menu, optionally wrapped in a
+ * rounded border when `bordered` is true.
+ */
+export default function Menu({ accentColor, autoFocus, bordered, items, onSelect, sections, title }: Props): ReactElement;

package/dist/ink/components/message-bubble.d.ts

@@ -0,0 +1,35 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type MessageRole = "assistant" | "system" | "tool" | "user";
+export type Props = {
+    /**
+     * Bubble body.
+     */
+    readonly children: ReactNode;
+    /**
+     * Color override.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * When true, draws the bubble without a border.
+     */
+    readonly flat?: boolean;
+    /**
+     * Text rendered above the bubble (name, model, etc.).
+     */
+    readonly label?: string;
+    /**
+     * Optional metadata rendered next to the label (e.g. timestamp).
+     */
+    readonly meta?: string;
+    /**
+     * Determines the alignment, color, and icon of the bubble.
+     * @default "assistant"
+     */
+    readonly role?: MessageRole;
+};
+/**
+ * Chat-style message bubble for AI agent UIs.
+ */
+export default function MessageBubble({ children, color, flat, label, meta, role }: Props): ReactElement;

package/dist/ink/components/model-badge.d.ts

@@ -0,0 +1,32 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Background color of the badge.
+     * @default "magenta"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Optional icon/symbol (e.g. `✨`, `◈`) shown before the label.
+     */
+    readonly icon?: ReactNode;
+    /**
+     * Short model identifier, e.g. `claude-opus-4.6`.
+     */
+    readonly model: string;
+    /**
+     * Optional provider name rendered as a separate chip before the model.
+     */
+    readonly provider?: string;
+    /**
+     * Visual style.
+     * @default "solid"
+     */
+    readonly variant?: "outline" | "solid" | "subtle";
+};
+/**
+ * Pill-shaped chip identifying the active model / provider. Pair with
+ * `MessageBubble` to label assistant output.
+ */
+export default function ModelBadge({ color, icon, model, provider, variant }: Props): ReactElement;

package/dist/ink/components/operation-tree.d.ts

@@ -0,0 +1,46 @@
+import type { ReactElement, ReactNode } from "react";
+export type OperationStatus = "completed" | "error" | "pending" | "running" | "skipped";
+export type OperationNode = {
+    /**
+     * Nested child operations rendered beneath this node.
+     */
+    readonly children?: ReadonlyArray<OperationNode>;
+    /**
+     * Optional supplementary info rendered on the next line (dimmed).
+     */
+    readonly details?: ReactNode;
+    /**
+     * Wall-clock duration in ms, displayed right-aligned.
+     */
+    readonly durationMs?: number;
+    /**
+     * Unique identifier within the tree.
+     */
+    readonly id: string;
+    /**
+     * Human-readable label.
+     */
+    readonly label: ReactNode;
+    /**
+     * Lifecycle state controlling icon + color.
+     */
+    readonly status: OperationStatus;
+};
+export type Props = {
+    /**
+     * Tree of operations. Each node can have its own children.
+     */
+    readonly nodes: ReadonlyArray<OperationNode>;
+    /**
+     * When true, runs the running-spinner animation.
+     * @default true
+     */
+    readonly showSpinner?: boolean;
+};
+/**
+ * Renders a tree of operations with per-node status. Perfect for agent
+ * progress panels (reading → editing → running tests → done).
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the nested tree of operation rows.
+ */
+export default function OperationTree({ nodes, showSpinner }: Props): ReactElement;

package/dist/ink/components/option-list.d.ts

@@ -0,0 +1,41 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type OptionListEntry = {
+    readonly description?: string;
+    readonly icon?: ReactNode;
+    readonly id: string;
+    readonly label: ReactNode;
+    readonly trailing?: ReactNode;
+};
+export type Props = {
+    /**
+     * Highlight color for the row marked as current.
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Render the list with a border.
+     */
+    readonly bordered?: boolean;
+    /**
+     * Id of the row to highlight. No visual change if omitted.
+     */
+    readonly currentId?: string;
+    /**
+     * Icon width in characters for column alignment.
+     * @default 2
+     */
+    readonly iconColumnWidth?: number;
+    /**
+     * Entries to render.
+     */
+    readonly options: ReadonlyArray<OptionListEntry>;
+};
+/**
+ * Read-only presentational option list. Like `SelectInput` but without focus,
+ * input handling, or scrolling — just a styled list of rows. Useful inside
+ * modals, sidebars, or summary panels.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the list; bordered when requested.
+ */
+export default function OptionList({ accentColor, bordered, currentId, iconColumnWidth, options }: Props): ReactElement;

package/dist/ink/components/{Paginator.d.ts → paginator.d.ts}

@@ -14,29 +14,26 @@ export type Props<T> = {
     /**
      * Render-prop that receives the current page items and page metadata.
      */
-    readonly children: (pageItems: readonly T[], meta: PageMeta) => ReactNode;
+    readonly children: (pageItems: ReadonlyArray<T>, meta: PageMeta) => ReactNode;
     /**
      * Uncontrolled initial page (0-indexed).
-     *
      * @default 0
      */
     readonly defaultPage?: number;
     /**
      * Color for the active page indicator.
-     *
      * @default "cyan"
      */
     readonly indicatorColor?: string;
     /**
      * Whether keyboard navigation is active.
-     *
      * @default true
      */
     readonly isFocused?: boolean;
     /**
      * The full list of items to paginate.
      */
-    readonly items: readonly T[];
+    readonly items: ReadonlyArray<T>;
     /**
      * Called when the page changes.
      */
@@ -54,22 +51,9 @@ export type Props<T> = {
      * - `"dots"`: `● ○ ○ ○`
      * - `"numeric"`: `‹ 1 / 4 ›`
      * - `"fraction"`: `1/4`
-     *
      * @default "dots"
      */
     readonly style?: "dots" | "fraction" | "numeric";
 };
-/**
- * Paginator component with render-prop children and a page indicator.
- *
- * ```tsx
- * <Paginator items={allItems} pageSize={5}>
- *   {(pageItems, meta) => (
- *     <Box flexDirection="column">
- *       {pageItems.map((item, i) => <Text key={i}>{item}</Text>)}
- *     </Box>
- *   )}
- * </Paginator>
- * ```
- */
-export default function Paginator<T>({ children, defaultPage, indicatorColor, isFocused, items, onChange, page: controlledPage, pageSize, style, }: Props<T>): ReactElement;
+declare const Paginator: <T>({ children, defaultPage, indicatorColor, isFocused, items, onChange, page: controlledPage, pageSize, style, }: Props<T>) => ReactElement;
+export default Paginator;

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

@@ -0,0 +1,31 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Paragraph body.
+     */
+    readonly children: ReactNode;
+    /**
+     * Foreground color.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Render the paragraph with dim color.
+     */
+    readonly dimColor?: boolean;
+    /**
+     * Blank lines to add after the paragraph.
+     * @default 1
+     */
+    readonly marginBottom?: number;
+    /**
+     * Blank lines to add before the paragraph.
+     * @default 0
+     */
+    readonly marginTop?: number;
+};
+/**
+ * Wraps body text with a trailing blank line. Useful for README-style layouts.
+ */
+export default function Paragraph({ children, color, dimColor, marginBottom, marginTop }: Props): ReactElement;

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

@@ -0,0 +1,47 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Whether to pulse the skeleton blocks (shimmer).
+     * @default true
+     */
+    readonly animated?: boolean;
+    /**
+     * Fill character used for each block.
+     * @default "█"
+     */
+    readonly character?: string;
+    /**
+     * Block color.
+     * @default "gray"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Milliseconds between pulses.
+     * @default 500
+     */
+    readonly interval?: number;
+    /**
+     * Number of skeleton rows to render.
+     * @default 3
+     */
+    readonly rows?: number;
+    /**
+     * Total width reference. When omitted, the block flexes to fill its
+     * parent.
+     */
+    readonly width?: number;
+    /**
+     * Relative widths of each row (0–1). The list is sampled cyclically.
+     * @default [1, 0.85, 0.6]
+     */
+    readonly widths?: ReadonlyArray<number>;
+};
+/**
+ * Skeleton loading indicator. Renders a stack of solid blocks whose widths
+ * vary to mimic text placeholders. Pair with `async` data fetching.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the skeleton rows.
+ */
+export default function Placeholder({ animated, character, color, interval, rows, width, widths, }: Props): ReactElement;

package/dist/ink/components/{ProgressBar.d.ts → progress-bar.d.ts}

@@ -8,7 +8,7 @@
  * Copyright (c) Frankie Bagnardi
  */
 import type { ReactElement } from "react";
-import type { Props as TextProps } from "./Text.d.ts";
+import type { Props as TextProps } from "./text.d.ts";
 export type Props = {
     /** Fill glyph repeated across the completed portion of the progress bar. Defaults to "█". */
     readonly character?: string;

package/dist/ink/components/radio-group.d.ts

@@ -0,0 +1,62 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type RadioOption = {
+    readonly description?: string;
+    readonly key?: string;
+    readonly label: string;
+    readonly value: string;
+};
+export type Props = {
+    /**
+     * Accent color for the focused and selected indicator.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus when mounted.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * When true, moving focus with arrow keys immediately updates the selected
+     * value (and fires `onChange`). When false, focus moves independently and
+     * selection commits only on Space or Enter.
+     * @default true
+     */
+    readonly commitOnNavigate?: boolean;
+    /**
+     * Initial selected value when uncontrolled.
+     */
+    readonly defaultValue?: string;
+    /**
+     * Disable input and dim labels.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Called when selection changes.
+     */
+    readonly onChange?: (value: string) => void;
+    /**
+     * Called when the user submits by pressing Enter.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Available options.
+     */
+    readonly options: ReadonlyArray<RadioOption>;
+    /**
+     * Orientation of options.
+     * @default "vertical"
+     */
+    readonly orientation?: "horizontal" | "vertical";
+    /**
+     * Controlled selected value.
+     */
+    readonly value?: string;
+};
+/**
+ * Single-choice radio group with keyboard navigation. By default, navigation
+ * commits selection; set `commitOnNavigate={false}` to require an explicit
+ * Space/Enter commit.
+ */
+export default function RadioGroup({ accentColor, autoFocus, commitOnNavigate, defaultValue, isDisabled, onChange, onSubmit, options, orientation, value, }: Props): ReactElement;

package/dist/ink/components/scatter-plot.d.ts

@@ -0,0 +1,23 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+import type { LineSeries } from "./line-chart.d.ts";
+export type Props = {
+    readonly axisColor?: LiteralUnion<AnsiColors, string>;
+    readonly height?: number;
+    readonly maxX?: number;
+    readonly maxY?: number;
+    readonly minX?: number;
+    readonly minY?: number;
+    readonly palette?: ReadonlyArray<LiteralUnion<AnsiColors, string>>;
+    readonly series: ReadonlyArray<LineSeries>;
+    readonly showLegend?: boolean;
+    readonly width?: number;
+};
+/**
+ * Scatter plot rendered on a braille pixel grid. Each sample lights one
+ * sub-cell pixel; overlapping points merge into denser braille glyphs.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` containing the plot and an optional legend.
+ */
+export default function ScatterPlot({ axisColor, height, maxX, maxY, minX, minY, palette, series, showLegend, width, }: Props): ReactElement;

package/dist/ink/components/scroll/{ControlledScrollView.d.ts → controlled-scroll-view.d.ts}

@@ -1,6 +1,6 @@
 import type React from "react";
 import type { ReactNode, Ref } from "react";
-import type { Props as BoxProps } from "../Box.d.ts";
+import type { Props as BoxProps } from "../box.d.ts";
 export interface ControlledScrollViewProps extends BoxProps {
     children?: ReactNode;
     debug?: boolean;

package/dist/ink/components/scroll/index.d.ts

@@ -1,10 +1,10 @@
-export type { ControlledScrollViewProps, ControlledScrollViewRef } from "./ControlledScrollView.d.ts";
-export { ControlledScrollView } from "./ControlledScrollView.d.ts";
-export type { ScrollBarPlacement, ScrollBarProps, ScrollBarStyle } from "./ScrollBar.d.ts";
-export { ScrollBar } from "./ScrollBar.d.ts";
-export type { ScrollBarBoxProps } from "./ScrollBarBox.d.ts";
-export { ScrollBarBox } from "./ScrollBarBox.d.ts";
-export type { ScrollAlignment, ScrollListProps, ScrollListRef } from "./ScrollList.d.ts";
-export { ScrollList } from "./ScrollList.d.ts";
-export type { ScrollViewProps, ScrollViewRef } from "./ScrollView.d.ts";
-export { ScrollView } from "./ScrollView.d.ts";
+export type { ControlledScrollViewProps, ControlledScrollViewRef } from "./controlled-scroll-view.d.ts";
+export { ControlledScrollView } from "./controlled-scroll-view.d.ts";
+export type { ScrollBarPlacement, ScrollBarProps, ScrollBarStyle } from "./scroll-bar.d.ts";
+export { ScrollBar } from "./scroll-bar.d.ts";
+export type { ScrollBarBoxProps } from "./scroll-bar-box.d.ts";
+export { ScrollBarBox } from "./scroll-bar-box.d.ts";
+export type { ScrollAlignment, ScrollListProps, ScrollListRef } from "./scroll-list.d.ts";
+export { ScrollList } from "./scroll-list.d.ts";
+export type { ScrollViewProps, ScrollViewRef } from "./scroll-view.d.ts";
+export { ScrollView } from "./scroll-view.d.ts";

package/dist/ink/components/scroll/{ScrollBarBox.d.ts → scroll-bar-box.d.ts}

@@ -1,5 +1,5 @@
 import type React from "react";
-import type { Props as BoxProps } from "../Box.d.ts";
+import type { Props as BoxProps } from "../box.d.ts";
 interface ScrollBarBoxProps extends BoxProps {
     children?: React.ReactNode;
     contentHeight: number;

package/dist/ink/components/scroll/{ScrollBar.d.ts → scroll-bar.d.ts}

@@ -1,5 +1,5 @@
 import React from "react";
-import type { Props as BoxProps } from "../Box.d.ts";
+import type { Props as BoxProps } from "../box.d.ts";
 type ScrollBarPlacement = "inset" | "left" | "right";
 type ScrollBarStyle = BoxProps["borderStyle"] | "block" | "line" | "thick" | "dots";
 interface ScrollBarProps {

package/dist/ink/components/scroll/{ScrollList.d.ts → scroll-list.d.ts}

@@ -1,6 +1,6 @@
 import type React from "react";
 import type { Ref } from "react";
-import type { ScrollViewProps, ScrollViewRef } from "./ScrollView.d.ts";
+import type { ScrollViewProps, ScrollViewRef } from "./scroll-view.d.ts";
 export type ScrollAlignment = "auto" | "bottom" | "center" | "top";
 export interface ScrollListProps extends ScrollViewProps {
     readonly scrollAlignment?: ScrollAlignment;

package/dist/ink/components/scroll/{ScrollView.d.ts → scroll-view.d.ts}

@@ -1,6 +1,6 @@
 import type React from "react";
 import type { ReactNode, Ref } from "react";
-import type { Props as BoxProps } from "../Box.d.ts";
+import type { Props as BoxProps } from "../box.d.ts";
 export interface ScrollViewProps extends BoxProps {
     children?: ReactNode;
     debug?: boolean;

package/dist/ink/components/search-input.d.ts

@@ -0,0 +1,46 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Color of the accent elements (border, icon).
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Initial value.
+     */
+    readonly defaultValue?: string;
+    /**
+     * Optional icon rendered before the input.
+     * @default "⌕"
+     */
+    readonly icon?: ReactNode;
+    /**
+     * Disable the input.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Fired whenever the value changes.
+     */
+    readonly onChange?: (value: string) => void;
+    /**
+     * Fired when the user presses Enter.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Placeholder text shown when the input is empty.
+     * @default "Search..."
+     */
+    readonly placeholder?: string;
+    /**
+     * Autocomplete suggestions.
+     */
+    readonly suggestions?: ReadonlyArray<string>;
+};
+/**
+ * Search-styled text input with an icon and bordered container.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` wrapping `TextInput` with an icon column.
+ */
+export default function SearchInput({ accentColor, defaultValue, icon, isDisabled, onChange, onSubmit, placeholder, suggestions, }: Props): ReactElement;

package/dist/ink/components/{SelectInput.d.ts → select-input.d.ts}

@@ -1,8 +1,8 @@
 import type { AnsiColors } from "@visulima/colorize";
 import type { FC, ReactElement } from "react";
 import type { LiteralUnion } from "type-fest";
-import type { Props as IndicatorProps } from "./SelectInputIndicator.d.ts";
-import type { Props as ItemProps } from "./SelectInputItem.d.ts";
+import type { Props as IndicatorProps } from "./select-input-indicator.d.ts";
+import type { Props as ItemProps } from "./select-input-item.d.ts";
 export type Item<V> = {
     /**
      * Called automatically when this item is selected (via Enter or number key).

package/dist/ink/components/shimmer-text.d.ts

@@ -0,0 +1,39 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Width of the highlighted band in characters.
+     * @default 3
+     */
+    readonly bandWidth?: number;
+    /**
+     * Base color of the non-highlighted text.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Highlight color of the sweeping band.
+     * @default "white"
+     */
+    readonly highlightColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Milliseconds between frames of the shimmer.
+     * @default 60
+     */
+    readonly interval?: number;
+    /**
+     * Text to render with a shimmer sweep.
+     */
+    readonly text: string;
+};
+/**
+ * Text with an animated highlight band that sweeps across the characters.
+ * Perfect for "generating…" states.
+ * @param props.bandWidth Number of characters in the bright band.
+ * @param props.color Color applied to characters outside the band.
+ * @param props.highlightColor Color applied to characters inside the band.
+ * @param props.interval Milliseconds between frames.
+ * @param props.text Content to shimmer.
+ * @returns A single `Text` element composed of per-character `Text` children.
+ */
+export default function ShimmerText({ bandWidth, color, highlightColor, interval, text }: Props): ReactElement;

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

@@ -0,0 +1,30 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Color applied to the chart glyphs.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Data points to plot. Values may be any real numbers.
+     */
+    readonly data: ReadonlyArray<number>;
+    /**
+     * Optional fixed maximum for the vertical scale.
+     * When omitted the maximum data value is used.
+     */
+    readonly max?: number;
+    /**
+     * Optional fixed minimum for the vertical scale.
+     * When omitted the minimum data value is used.
+     */
+    readonly min?: number;
+};
+/**
+ * Inline bar chart using Unicode block glyphs.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` containing the glyph string, or `null` when
+ * `data` is empty.
+ */
+export default function Sparkline({ color, data, max, min }: Props): ReactElement | null;