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

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

@@ -0,0 +1,74 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type FormFieldProps = {
+    /**
+     * The input element (TextInput, Checkbox, Select, …).
+     */
+    readonly children: ReactNode;
+    /**
+     * Optional helper text rendered beneath the input.
+     */
+    readonly description?: string;
+    /**
+     * Validation error — dimmed red below the input.
+     */
+    readonly error?: string;
+    /**
+     * When true, the field's label and description are dim.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Label rendered above the input.
+     */
+    readonly label: string;
+    /**
+     * Mark the field as required (adds a trailing `*`).
+     */
+    readonly required?: boolean;
+};
+/**
+ * Standard form field wrapper: label + input + helper/error.
+ */
+export declare const FormField: ({ children, description, error, isDisabled, label, required }: FormFieldProps) => ReactElement;
+export type Props = {
+    /**
+     * Accent color for the form chrome.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Render a border around the form.
+     * @default true
+     */
+    readonly bordered?: boolean;
+    /**
+     * Fields composed via `&lt;FormField />`.
+     */
+    readonly children: ReactNode;
+    /**
+     * Optional description rendered under the title.
+     */
+    readonly description?: string;
+    /**
+     * Optional footer rendered below the fields (buttons, hints, summary).
+     */
+    readonly footer?: ReactNode;
+    /**
+     * Optional heading rendered at the top.
+     */
+    readonly title?: string;
+    /**
+     * Fixed width.
+     */
+    readonly width?: number;
+};
+type FormComponent = ((props: Props) => ReactElement) & {
+    Field: typeof FormField;
+};
+/**
+ * Stateless form layout. Pair with the `useForm` hook for state management
+ * and `FormField` for consistent label/error styling.
+ */
+declare const Form: FormComponent;
+export default Form;

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

@@ -0,0 +1,75 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type GaugeThreshold = {
+    /**
+     * Color used for the arc segment and, when the current value falls into
+     * this segment, for the value readout.
+     */
+    readonly color: LiteralUnion<AnsiColors, string>;
+    /**
+     * Optional label used by the legend under the gauge.
+     */
+    readonly label?: string;
+    /**
+     * Upper bound of this threshold segment (inclusive). Segments are sorted
+     * ascending and painted in order.
+     */
+    readonly max: number;
+};
+export type GaugeSize = "large" | "medium" | "small";
+export type Props = {
+    /**
+     * Color of the arc background (the portion beyond `value`).
+     * @default "gray"
+     */
+    readonly backgroundColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Format for the numeric readout. Defaults to rounding to an integer.
+     */
+    readonly formatValue?: (value: number) => string;
+    /**
+     * Optional label rendered above the readout.
+     */
+    readonly label?: string;
+    /**
+     * Upper bound of the range.
+     * @default 100
+     */
+    readonly max?: number;
+    /**
+     * Lower bound of the range.
+     * @default 0
+     */
+    readonly min?: number;
+    /**
+     * Show a legend listing thresholds below the gauge.
+     * @default false
+     */
+    readonly showLegend?: boolean;
+    /**
+     * Show a numeric readout in the middle of the gauge.
+     * @default true
+     */
+    readonly showValue?: boolean;
+    /**
+     * Overall dimension preset.
+     * @default "medium"
+     */
+    readonly size?: GaugeSize;
+    /**
+     * Color threshold ramp. When provided, segments of the arc are painted in
+     * the corresponding colors and the value readout picks up the color for
+     * the segment `value` lands in.
+     */
+    readonly thresholds?: ReadonlyArray<GaugeThreshold>;
+    /**
+     * Current value. Clamped into the `[min, max]` range.
+     */
+    readonly value: number;
+};
+/**
+ * Semi-circular gauge rendered at 2x4 sub-cell resolution. Supports colored
+ * threshold segments and an optional needle.
+ */
+export default function Gauge({ backgroundColor, formatValue, label, max, min, showLegend, showValue, size, thresholds, value, }: Props): ReactElement;

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

@@ -0,0 +1,27 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type Props = {
+    /**
+     * Heading content.
+     */
+    readonly children: ReactNode;
+    /**
+     * Explicit color. By default the color is derived from the level.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Heading level controls decoration and color.
+     * @default 1
+     */
+    readonly level?: HeadingLevel;
+    /**
+     * When true, renders an underline on a second line.
+     */
+    readonly underline?: boolean;
+};
+/**
+ * Semantic heading with level-based styling.
+ */
+export default function Heading({ children, color, level, underline }: Props): ReactElement;

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

@@ -0,0 +1,51 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type HeatmapProps = {
+    /**
+     * Width of each cell in character columns.
+     * @default 2
+     */
+    readonly cellWidth?: number;
+    /**
+     * Character used to paint each heatmap cell. Defaults to `█` so the
+     * background color fills the cell.
+     * @default "█"
+     */
+    readonly character?: string;
+    /**
+     * Column labels rendered below the grid.
+     */
+    readonly columnLabels?: ReadonlyArray<string>;
+    /**
+     * 2D matrix, rows × cols.
+     */
+    readonly data: ReadonlyArray<ReadonlyArray<number>>;
+    /**
+     * Fixed maximum (for consistent scales across multiple heatmaps).
+     */
+    readonly max?: number;
+    /**
+     * Fixed minimum.
+     */
+    readonly min?: number;
+    /**
+     * Color palette, lowest-to-highest intensity. Values are mapped into the
+     * palette by their position in the [min, max] range.
+     * @default ["#0b1e4f", "#1f3b96", "#3258c8", "#4e84ec", "#78b0ff"]
+     */
+    readonly palette?: ReadonlyArray<string>;
+    /**
+     * Row labels rendered to the left of the grid.
+     */
+    readonly rowLabels?: ReadonlyArray<string>;
+    /**
+     * Foreground color override (rarely needed since the character is a full block).
+     */
+    readonly textColor?: LiteralUnion<AnsiColors, string>;
+};
+/**
+ * 2D heatmap. Each cell's background color is derived from its value's
+ * position in the [min, max] range mapped into `palette`.
+ */
+export default function Heatmap({ cellWidth, character, columnLabels, data, max: maxOverride, min: minOverride, palette, rowLabels, textColor, }: HeatmapProps): ReactElement;

package/dist/ink/components/{Help.d.ts → help.d.ts}

@@ -4,22 +4,19 @@ export type Props = {
     /**
      * Key bindings to display. Typically the `bindings` array returned by `useKeyBindings`.
      */
-    readonly bindings: readonly KeyBinding[];
+    readonly bindings: ReadonlyArray<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;
@@ -27,13 +24,11 @@ export type Props = {
      * 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;
@@ -42,8 +37,8 @@ export type Props = {
  * Renders a keybinding help bar from an array of `KeyBinding` definitions.
  *
  * ```tsx
- * <Help bindings={bindings} />
- * <Help bindings={bindings} mode="full" />
+ * &lt;Help bindings={bindings} />
+ * &lt;Help bindings={bindings} mode="full" />
  * ```
  */
-export default function Help({ bindings, descriptionColor, keyColor, maxColumns, mode, separator, }: Props): ReactElement;
+export default function Help({ bindings, descriptionColor, keyColor, maxColumns, mode, separator }: Props): ReactElement;

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

@@ -0,0 +1,52 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Number of equal-width buckets. Ignored if `thresholds` is set.
+     * @default 10
+     */
+    readonly bins?: number;
+    /**
+     * Bar color.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Raw values to bin.
+     */
+    readonly data: ReadonlyArray<number>;
+    /**
+     * Plot height in character rows.
+     * @default 10
+     */
+    readonly height?: number;
+    /**
+     * Optional fixed maximum.
+     */
+    readonly max?: number;
+    /**
+     * Optional fixed minimum.
+     */
+    readonly min?: number;
+    /**
+     * Render a numeric count above each bucket.
+     * @default false
+     */
+    readonly showValues?: boolean;
+    /**
+     * Explicit bin edges. When provided, `bins`, `min`, and `max` are ignored.
+     * Must be strictly increasing.
+     */
+    readonly thresholds?: ReadonlyArray<number>;
+    /**
+     * Plot width in character columns.
+     */
+    readonly width?: number;
+};
+/**
+ * Histogram built on top of BarChart. Bins the raw values (via explicit
+ * thresholds or equal-width bins) and hands the counts off to BarChart.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering a BarChart of bucket counts.
+ */
+export default function Histogram({ bins, color, data, height, max: maxOverride, min: minOverride, showValues, thresholds, width, }: Props): ReactElement;

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

@@ -0,0 +1,27 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Key cap content.
+     */
+    readonly children: ReactNode;
+    /**
+     * Background color of the key cap.
+     * @default "gray"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Visual style.
+     * - `solid` (default): background filled
+     * - `outline`: border only
+     * - `bare`: no decoration, just dimmed text
+     */
+    readonly variant?: "bare" | "outline" | "solid";
+};
+/**
+ * Render a keyboard key (e.g. `&lt;Kbd>Enter&lt;/Kbd>`).
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` styled as a key cap (solid / outline / bare).
+ */
+export default function Kbd({ children, color, variant }: Props): ReactElement;

package/dist/ink/components/line-chart.d.ts

@@ -0,0 +1,94 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+import type { CanvasContext } from "../canvas/buffer.d.ts";
+import type { Point } from "./chart-utils.d.ts";
+export type LineSeries = {
+    /**
+     * Per-series color override. Falls back to the chart-level palette.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Numeric samples to plot. Pass either a list of y-values (x is the
+     * index) or {x, y} tuples.
+     */
+    readonly data: ReadonlyArray<number> | ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+    }>;
+    /**
+     * Optional label shown in the legend.
+     */
+    readonly label?: string;
+};
+export type LineChartProps = {
+    /**
+     * Color for axis ticks / labels.
+     * @default "gray"
+     */
+    readonly axisColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Chart body height in character rows.
+     * @default 10
+     */
+    readonly height?: number;
+    /**
+     * Upper bound for the y-axis. When omitted the chart auto-scales.
+     */
+    readonly maxY?: number;
+    /**
+     * Lower bound for the y-axis. When omitted the chart auto-scales.
+     */
+    readonly minY?: number;
+    /**
+     * Fallback palette cycled through when a series does not set `color`.
+     * @default ["cyan", "magenta", "yellow", "green", "blue", "red"]
+     */
+    readonly palette?: ReadonlyArray<LiteralUnion<AnsiColors, string>>;
+    /**
+     * One or more line series.
+     */
+    readonly series: ReadonlyArray<LineSeries>;
+    /**
+     * Render the legend row under the plot.
+     * @default true
+     */
+    readonly showLegend?: boolean;
+    /**
+     * Chart body width in character columns.
+     * @default 40
+     */
+    readonly width?: number;
+};
+type RenderConfig = {
+    readonly axisColor: LiteralUnion<AnsiColors, string>;
+    readonly palette: ReadonlyArray<LiteralUnion<AnsiColors, string>>;
+    readonly seriesList: ReadonlyArray<{
+        color: LiteralUnion<AnsiColors, string>;
+        points: ReadonlyArray<Point>;
+        series: LineSeries;
+    }>;
+    readonly xMax: number;
+    readonly xMin: number;
+    readonly yMax: number;
+    readonly yMin: number;
+};
+/**
+ * Project an (x, y) data point into pixel-grid coordinates for the given
+ * canvas size. Used by every chart that paints on top of a braille grid.
+ */
+export declare const projectPoint: (point: Point, config: Pick<RenderConfig, "xMax" | "xMin" | "yMax" | "yMin">, pixelWidth: number, pixelHeight: number) => {
+    px: number;
+    py: number;
+};
+/**
+ * Shared drawing path used by LineChart and ScatterPlot. AreaChart wraps
+ * this with a fill pass.
+ */
+export declare const drawSeriesOnCanvas: (context: CanvasContext, mode: "line" | "scatter", config: RenderConfig) => void;
+/**
+ * Smooth multi-series line chart rendered at 2x4 sub-cell resolution using
+ * Unicode braille patterns. Auto-scales both axes by default.
+ */
+export default function LineChart({ axisColor, height, maxY, minY, palette, series, showLegend, width, }: LineChartProps): ReactElement;
+export type { RenderConfig as LineChartRenderConfig };

package/dist/ink/components/loading-indicator.d.ts

@@ -0,0 +1,24 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { SpinnerName } from "@visulima/spinner";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Optional message rendered after the spinner.
+     */
+    readonly children?: ReactNode;
+    /**
+     * Color used for the spinner and label.
+     * @default "cyan"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Spinner preset.
+     * @default "dots"
+     */
+    readonly type?: SpinnerName;
+};
+/**
+ * Compact spinner + label for loading states.
+ */
+export default function LoadingIndicator({ children, color, type }: Props): ReactElement;

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

@@ -0,0 +1,41 @@
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * Initial raw value (digits/characters only, without mask symbols).
+     */
+    readonly defaultValue?: string;
+    /**
+     * Disable input and dim the display.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Mask definition. Each `#` is replaced with a user character; any other
+     * character is rendered literally. Example: `(###) ###-####`.
+     */
+    readonly mask: string;
+    /**
+     * Called whenever the underlying raw value changes.
+     */
+    readonly onChange?: (value: string) => void;
+    /**
+     * Called when the user presses Enter with the current raw value.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Placeholder character used in the mask for empty positions.
+     * @default "_"
+     */
+    readonly placeholderChar?: string;
+    /**
+     * Character used to mark editable positions.
+     * @default "#"
+     */
+    readonly token?: string;
+};
+/**
+ * Input with a fixed-width mask. The mask token (`#` by default) marks
+ * positions where the user can type; every other character is preserved.
+ * Supports ←/→ to move within the mask, Home/End to jump, and
+ * Backspace/Delete to clear characters.
+ */
+export default function MaskedInput({ defaultValue, isDisabled, mask, onChange, onSubmit, placeholderChar, token, }: Props): ReactElement;

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;