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

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

@@ -0,0 +1,60 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Accent color for today / the focused cell.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the grid on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Initial focused day when uncontrolled. Defaults to `value` or today.
+     */
+    readonly defaultValue?: Date;
+    /**
+     * First day of the week: 0 = Sunday, 1 = Monday.
+     * @default 1
+     */
+    readonly firstDayOfWeek?: 0 | 1;
+    /**
+     * When true, disable input and render the grid dim.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Upper bound; days after `maxDate` cannot be selected.
+     */
+    readonly maxDate?: Date;
+    /**
+     * Lower bound; days before `minDate` cannot be selected.
+     */
+    readonly minDate?: Date;
+    /**
+     * Called whenever the user navigates or selects a day.
+     */
+    readonly onChange?: (date: Date) => void;
+    /**
+     * Called when the user presses Enter.
+     */
+    readonly onSubmit?: (date: Date) => void;
+    /**
+     * Color used to mark the currently selected day.
+     * @default "green"
+     */
+    readonly selectedColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Controlled selected date.
+     */
+    readonly value?: Date;
+};
+/**
+ * Month-grid date picker. Arrow keys move focus by one day, page up/down move
+ * by month. Enter submits; Space or Enter selects.
+ * @param props See {@link Props}.
+ * @returns A bordered `ReactElement` containing the month header, weekday
+ * labels, and the day grid.
+ */
+export default function Calendar({ accentColor, autoFocus, defaultValue, firstDayOfWeek, isDisabled, maxDate, minDate, onChange, onSubmit, selectedColor, value, }: Props): ReactElement;

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

@@ -0,0 +1,38 @@
+import type { ReactElement } from "react";
+import type { CanvasContext } from "../canvas/buffer.d.ts";
+export type { CanvasColor, CanvasContext, CellStyle } from "../canvas/buffer.d.ts";
+export type Props = {
+    /**
+     * Imperative draw callback. Mutates the underlying typed-array buffer via
+     * the provided `CanvasContext`. Runs in a `useMemo` keyed by `version` —
+     * pass a stable reference (or hash) so the canvas only re-renders when
+     * the input data truly changes.
+     */
+    readonly draw: (context: CanvasContext) => void;
+    /**
+     * Number of rows (character cells vertically).
+     */
+    readonly height: number;
+    /**
+     * Invalidation key — required so the memoization contract is explicit.
+     * Re-runs `draw` and re-serializes only the rows the draw callback
+     * dirtied. Pass the data you render (or a hash of it). Use a stable
+     * value (e.g. a counter) when you intentionally want to redraw on
+     * every render.
+     */
+    readonly version: unknown;
+    /**
+     * Number of columns (character cells horizontally).
+     */
+    readonly width: number;
+};
+/**
+ * A fixed-size cell grid backed by typed arrays. Use the imperative `draw`
+ * callback to paint. The canvas emits one `Text` child per row (not per cell)
+ * and caches the ANSI output of each row: only rows marked dirty by the last
+ * draw pass are re-serialized, and only when `version` changes.
+ *
+ * This is the foundation for chart/grid components that need more layout
+ * control than `Text` alone.
+ */
+export default function Canvas({ draw, height, version, width }: Props): ReactElement;

package/dist/ink/components/card.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 = {
+    /**
+     * Border color.
+     */
+    readonly borderColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Border style name, passed through to `Box`.
+     * @default "round"
+     */
+    readonly borderStyle?: "arrow" | "bold" | "classic" | "double" | "doubleSingle" | "round" | "single" | "singleDouble";
+    /**
+     * Card body.
+     */
+    readonly children: ReactNode;
+    /**
+     * Optional footer rendered below body with a dim divider.
+     */
+    readonly footer?: ReactNode;
+    /**
+     * Optional content rendered after the title on the same row.
+     */
+    readonly headerRight?: ReactNode;
+    /**
+     * Optional subtitle rendered below the title.
+     */
+    readonly subtitle?: string;
+    /**
+     * Optional title rendered in the header area.
+     */
+    readonly title?: string;
+    /**
+     * Color applied to the title.
+     */
+    readonly titleColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Fix the card width. When omitted the card grows to fill its parent.
+     */
+    readonly width?: number | string;
+};
+/**
+ * Bordered container with optional title, subtitle, and footer.
+ */
+export default function Card({ borderColor, borderStyle, children, footer, headerRight, subtitle, title, titleColor, width }: Props): ReactElement;

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

@@ -0,0 +1,54 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { LiteralUnion } from "type-fest";
+/**
+ * A single 2D data point.
+ */
+export type Point = {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * Minimal shape every "series-like" chart entry conforms to. Used so chart
+ * components share utilities without coupling to a specific Props type.
+ */
+export type SeriesLike = {
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    readonly data: ReadonlyArray<number> | ReadonlyArray<Point>;
+    readonly label?: string;
+};
+/**
+ * Default palette cycled through when a series does not declare its own color.
+ */
+export declare const DEFAULT_CHART_PALETTE: ReadonlyArray<LiteralUnion<AnsiColors, string>>;
+/**
+ * Normalize the per-series `data` prop into a uniform `Point[]`. Numeric
+ * arrays are treated as y-values with their index as x.
+ * @param data Either a numeric array or an array of `{x, y}` points.
+ * @returns A uniform `Point[]` — empty when no samples were provided.
+ */
+export declare const toPoints: (data: SeriesLike["data"]) => ReadonlyArray<Point>;
+/**
+ * Pick the effective color for a series: per-series override, else palette
+ * cycling by index, with a safe `"cyan"` fallback.
+ * @param series The series whose color we want.
+ * @param index The series index for palette cycling.
+ * @param palette Fallback palette.
+ * @returns The resolved color string.
+ */
+export declare const pickSeriesColor: (series: SeriesLike, index: number, palette: ReadonlyArray<LiteralUnion<AnsiColors, string>>) => LiteralUnion<AnsiColors, string>;
+export type Extents = {
+    readonly xMax: number;
+    readonly xMin: number;
+    readonly yMax: number;
+    readonly yMin: number;
+};
+/**
+ * Single-pass min/max scan for an arbitrary collection of series. Returns
+ * `Infinity` / `-Infinity` sentinels when no points are provided; callers
+ * should replace these with their chosen defaults before rendering.
+ * @param seriesList Iterable of series whose projected `points` need extents.
+ * @returns The `{xMin, xMax, yMin, yMax}` tuple across all input points.
+ */
+export declare const computeExtents: (seriesList: Iterable<{
+    readonly points: ReadonlyArray<Point>;
+}>) => Extents;

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

@@ -0,0 +1,39 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Accent color when focused.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus when mounted if nothing else is focused.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Label rendered next to the checkbox.
+     */
+    readonly children?: ReactNode;
+    /**
+     * Initial checked state when uncontrolled.
+     * @default false
+     */
+    readonly defaultChecked?: boolean;
+    /**
+     * Controlled checked state. When provided, `onChange` should update the parent.
+     */
+    readonly isChecked?: boolean;
+    /**
+     * Disable input and dim the label.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Fired when the checkbox toggles.
+     */
+    readonly onChange?: (checked: boolean) => void;
+};
+/**
+ * Focusable checkbox. Toggles with Space or Enter.
+ */
+export default function Checkbox({ accentColor, autoFocus, children, defaultChecked, isChecked, isDisabled, onChange, }: Props): ReactElement;

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

@@ -0,0 +1,43 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Accent color when the header is focused.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the collapsible on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Child content rendered when open.
+     */
+    readonly children: ReactNode;
+    /**
+     * Whether the section starts expanded.
+     * @default false
+     */
+    readonly defaultOpen?: boolean;
+    /**
+     * Disable interaction.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Controlled open state.
+     */
+    readonly isOpen?: boolean;
+    /**
+     * Called when the user toggles the section.
+     */
+    readonly onToggle?: (isOpen: boolean) => void;
+    /**
+     * Header label.
+     */
+    readonly title: ReactNode;
+};
+/**
+ * Focusable section that can be expanded or collapsed.
+ */
+export default function Collapsible({ accentColor, autoFocus, children, defaultOpen, isDisabled, isOpen, onToggle, title, }: Props): ReactElement;

package/dist/ink/components/command-block.d.ts

@@ -0,0 +1,38 @@
+import type { ReactElement, ReactNode } from "react";
+export type CommandStatus = "error" | "idle" | "running" | "success";
+export type Props = {
+    /**
+     * Shell command rendered in the header.
+     */
+    readonly command: string;
+    /**
+     * Optional working directory shown after the command name.
+     */
+    readonly cwd?: string;
+    /**
+     * Duration in ms; shown when finished.
+     */
+    readonly durationMs?: number;
+    /**
+     * Exit code of the completed command.
+     */
+    readonly exitCode?: number;
+    /**
+     * Max output rows rendered before truncation. Use `Infinity` to disable.
+     */
+    readonly maxOutputRows?: number;
+    /**
+     * Command output. Either a string (rendered as-is) or arbitrary children.
+     */
+    readonly output?: ReactNode;
+    /**
+     * Lifecycle state. Controls the header icon and color.
+     * @default "idle"
+     */
+    readonly status?: CommandStatus;
+};
+/**
+ * Renders a shell command with its output and a status header. Designed for
+ * coding-agent UIs that stream terminal operations.
+ */
+export default function CommandBlock({ command, cwd, durationMs, exitCode, maxOutputRows, output, status }: Props): ReactElement;

package/dist/ink/components/command-palette.d.ts

@@ -0,0 +1,72 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type CommandEntry = {
+    /**
+     * Optional description rendered under the label.
+     */
+    readonly description?: string;
+    /**
+     * Optional hotkey rendered on the right.
+     */
+    readonly hotkey?: string;
+    /**
+     * Optional icon rendered before the label.
+     */
+    readonly icon?: ReactNode;
+    /**
+     * Stable identifier returned by `onSelect`.
+     */
+    readonly id: string;
+    /**
+     * Optional keywords to boost matching (not displayed).
+     */
+    readonly keywords?: ReadonlyArray<string>;
+    /**
+     * Label shown in the list (and used as the primary match target).
+     */
+    readonly label: string;
+};
+export type Props = {
+    /**
+     * Accent color for the border and focused row.
+     * @default "cyan"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the palette on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Available commands to search.
+     */
+    readonly commands: ReadonlyArray<CommandEntry>;
+    /**
+     * Empty-state text when nothing matches.
+     * @default "No results"
+     */
+    readonly emptyText?: string;
+    /**
+     * Max rows rendered in the list.
+     * @default 8
+     */
+    readonly limit?: number;
+    /**
+     * Called when the user presses Escape.
+     */
+    readonly onCancel?: () => void;
+    /**
+     * Called when the user picks a command with Enter.
+     */
+    readonly onSelect: (id: string, query: string) => void;
+    /**
+     * Placeholder inside the search field.
+     * @default "Type a command or search..."
+     */
+    readonly placeholder?: string;
+};
+/**
+ * Ctrl-P style fuzzy command finder. Features a search input, ranked results,
+ * keyboard navigation, and Esc to cancel.
+ */
+export default function CommandPalette({ accentColor, autoFocus, commands, emptyText, limit, onCancel, onSelect, placeholder, }: Props): ReactElement;

package/dist/ink/components/confirm-dialog.d.ts

@@ -0,0 +1,63 @@
+import type { ReactElement, ReactNode } from "react";
+export type ConfirmTone = "danger" | "info" | "warning";
+export type Props = {
+    /**
+     * Auto-focus the dialog on mount. Set `false` if a parent already owns
+     * focus and routes input here.
+     * @default true
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Label for the cancel button.
+     * @default "Cancel"
+     */
+    readonly cancelLabel?: string;
+    /**
+     * Body content (rendered between title and buttons).
+     */
+    readonly children?: ReactNode;
+    /**
+     * Label for the confirm button.
+     * @default "Confirm"
+     */
+    readonly confirmLabel?: string;
+    /**
+     * Default button when opening the dialog.
+     * @default "confirm"
+     */
+    readonly defaultFocus?: "cancel" | "confirm";
+    /**
+     * Disable input.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Fired when the user declines.
+     */
+    readonly onCancel: () => void;
+    /**
+     * Fired when the user confirms.
+     */
+    readonly onConfirm: () => void;
+    /**
+     * Heading rendered at the top of the dialog.
+     */
+    readonly title?: string;
+    /**
+     * Controls the border color.
+     * @default "info"
+     */
+    readonly tone?: ConfirmTone;
+    /**
+     * Dialog width.
+     */
+    readonly width?: number;
+};
+/**
+ * Full-width modal-style confirm/cancel prompt. Unlike `ConfirmInput`, this
+ * renders a visible two-button UI: ← / → to toggle focus, Enter to activate,
+ * y/n as shortcuts, Esc to cancel.
+ * @param props See {@link Props}.
+ * @returns A bordered `ReactElement` with optional title, body, and two
+ * buttons (cancel / confirm).
+ */
+export default function ConfirmDialog({ autoFocus, cancelLabel, children, confirmLabel, defaultFocus, isDisabled, onCancel, onConfirm, title, tone, width, }: Props): ReactElement;

package/dist/ink/components/content-switcher.d.ts

@@ -0,0 +1,49 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type ContentSwitcherOption = {
+    readonly content: ReactNode;
+    readonly icon?: ReactNode;
+    readonly id: string;
+    readonly label: string;
+};
+export type Props = {
+    /**
+     * Accent color for the selected segment.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the switcher on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Initial selected id (uncontrolled).
+     */
+    readonly defaultValue?: string;
+    /**
+     * Disable input.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Called when the selection changes.
+     */
+    readonly onChange?: (id: string) => void;
+    /**
+     * Segments to toggle between.
+     */
+    readonly options: ReadonlyArray<ContentSwitcherOption>;
+    /**
+     * Controlled selected id.
+     */
+    readonly value?: string;
+};
+/**
+ * Segmented control that flips between mutually exclusive content. More
+ * compact than `Tabs`: the selected segment is highlighted as a pill, and
+ * only the active segment's content is rendered.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` with a segmented header row and the active
+ * panel's content beneath it.
+ */
+export default function ContentSwitcher({ accentColor, autoFocus, defaultValue, isDisabled, onChange, options, value, }: Props): ReactElement;

package/dist/ink/components/date-picker.d.ts

@@ -0,0 +1,53 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Accent color used by the inner calendar when open.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus the picker on mount.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Initial selected date when uncontrolled.
+     */
+    readonly defaultValue?: Date;
+    /**
+     * Override the way the selected date is rendered in the input row.
+     */
+    readonly formatValue?: (date: Date) => string;
+    /**
+     * Disable the picker.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Upper bound for selectable dates.
+     */
+    readonly maxDate?: Date;
+    /**
+     * Lower bound for selectable dates.
+     */
+    readonly minDate?: Date;
+    /**
+     * Fired when the user commits a date with Enter.
+     */
+    readonly onChange?: (date: Date) => void;
+    /**
+     * Placeholder rendered when no date is selected.
+     * @default "Pick a date"
+     */
+    readonly placeholder?: string;
+    /**
+     * Controlled selected date.
+     */
+    readonly value?: Date;
+};
+/**
+ * Compact date input. Shows the currently-selected date; Enter / Space opens
+ * the inline `Calendar` for navigation. Enter inside the calendar commits the
+ * date and closes the picker.
+ */
+export default function DatePicker({ accentColor, autoFocus, defaultValue, formatValue, isDisabled, maxDate, minDate, onChange, placeholder, value, }: Props): ReactElement;

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

@@ -0,0 +1,37 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type DefinitionItem = {
+    readonly description: ReactNode;
+    readonly key?: string;
+    readonly term: ReactNode;
+};
+export type Props = {
+    /**
+     * Spacing between term and description columns.
+     * @default 2
+     */
+    readonly columnGap?: number;
+    /**
+     * Entries to render.
+     */
+    readonly items: ReadonlyArray<DefinitionItem>;
+    /**
+     * Inline items display on the same row; stacked items display with the term above the description.
+     * @default "inline"
+     */
+    readonly layout?: "inline" | "stacked";
+    /**
+     * Color applied to the term.
+     * @default "cyan"
+     */
+    readonly termColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Minimum width used to align inline terms.
+     */
+    readonly termWidth?: number;
+};
+/**
+ * Key/value style definition list. Equivalent to the HTML `&lt;dl>` element.
+ */
+export default function DefinitionList({ columnGap, items, layout, termColor, termWidth }: Props): ReactElement;

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

@@ -0,0 +1,40 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Custom character to use instead of the default line character.
+     */
+    readonly character?: string;
+    /**
+     * Color of the divider line.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Render the divider with dim color.
+     */
+    readonly dimColor?: boolean;
+    /**
+     * Optional label rendered in the middle of a horizontal divider.
+     */
+    readonly label?: string;
+    /**
+     * Padding around the label.
+     * @default 1
+     */
+    readonly labelPadding?: number;
+    /**
+     * Total length of the divider. When omitted, horizontal dividers stretch to
+     * fill the available space and vertical dividers default to one row.
+     */
+    readonly length?: number;
+    /**
+     * Orientation of the divider.
+     * @default "horizontal"
+     */
+    readonly orientation?: "horizontal" | "vertical";
+};
+/**
+ * Horizontal or vertical divider line, optionally with a centered label.
+ */
+export default function Divider({ character, color, dimColor, label, labelPadding, length, orientation }: Props): ReactElement;