@visulima/tui 0.0.1 → 1.0.0-alpha.2

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

@@ -0,0 +1,34 @@
+import type { ReactElement, ReactNode } from "react";
+type Props = {
+    readonly children: ReactNode;
+    /**
+     * Determines whether the URL should be printed for unsupported terminals.
+     *
+     * - `true` (default): appends the URL after the text, e.g. `"My website https://example.com"`
+     * - `false`: renders just the text with no URL
+     * - `function`: custom fallback formatting, e.g. `(text, url) => \`[\${text}](\${url})\``
+     * @default true
+     */
+    readonly fallback?: ((text: string, url: string) => string) | boolean;
+    /**
+     * The URL to link to.
+     */
+    readonly url: string;
+};
+/**
+ * An Ink component that creates clickable links in the terminal using OSC 8 hyperlink sequences.
+ *
+ * [Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
+ *
+ * For unsupported terminals, the link will be printed after the text: `My website https://example.com`.
+ *
+ * ```tsx
+ * import { Link, Text } from "@visulima/tui/ink";
+ *
+ * <Link url="https://example.com">
+ *     <Text color="cyan">My Website</Text>
+ * </Link>
+ * ```
+ */
+export default function Link({ children, fallback, url }: Props): ReactElement;
+export type { Props };

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

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * The Markdown source string.
+     */
+    readonly children: string;
+    /**
+     * Shiki theme for code block syntax highlighting.
+     * @default "github-dark-default"
+     */
+    readonly codeTheme?: string;
+    /**
+     * Maximum width for text wrapping. Defaults to terminal width.
+     */
+    readonly maxWidth?: number;
+    /**
+     * Enable streaming mode for progressive rendering.
+     * When true, the component re-renders on every prop change and handles
+     * incomplete Markdown gracefully (e.g., unclosed code fences, partial lists).
+     * Useful for rendering AI-generated text arriving token-by-token.
+     * @default false
+     */
+    readonly streaming?: boolean;
+};
+/**
+ * Render Markdown content as Ink terminal UI elements.
+ *
+ * ```tsx
+ * <Markdown>{"# Hello\n\nThis is **bold** and *italic*."}</Markdown>
+ * <Markdown codeTheme="github-dark-default">{"```js\nconst x = 1;\n```"}</Markdown>
+ * <Markdown streaming>{"# Streaming\n\nText arriving..."}</Markdown>
+ * ```
+ */
+export default function Markdown({ children, codeTheme, maxWidth: maxWidthProp, streaming }: Props): ReactElement;

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

@@ -0,0 +1,63 @@
+/**
+ * Multi-select input component for Ink.
+ *
+ * Inspired by ink-ui MultiSelect 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 } from "react";
+import type { LiteralUnion } from "type-fest";
+export type MultiSelectOption = {
+    readonly key?: string;
+    readonly label: string;
+    readonly value: string;
+};
+export type Props = {
+    /**
+     * Color for the focused item indicator and selected checkmarks.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Color for unselected, unfocused option labels.
+     */
+    readonly defaultColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Initially selected values.
+     */
+    readonly defaultValue?: ReadonlyArray<string>;
+    /**
+     * When true, all input is ignored and labels are dimmed.
+     * @default false
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Whether the parent has focus. When false, indicators are dimmed.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Number of visible options before scrolling.
+     * When omitted, auto-limits to terminal height.
+     */
+    readonly limit?: number;
+    /**
+     * Fires when the set of selected values changes (space to toggle).
+     */
+    readonly onChange?: (values: ReadonlyArray<string>) => void;
+    /**
+     * Fires when the user presses Enter to submit.
+     */
+    readonly onSubmit?: (values: ReadonlyArray<string>) => void;
+    /**
+     * Available choices to pick from.
+     */
+    readonly options: ReadonlyArray<MultiSelectOption>;
+};
+/**
+ * Renders a multi-choice selection list with checkboxes and keyboard navigation.
+ */
+export default function MultiSelect({ accentColor, defaultColor, defaultValue, isDisabled, isFocused, limit: customLimit, onChange, onSubmit, options, }: Props): ReactElement;

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

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * Number of newlines to insert.
+     * @default 1
+     */
+    readonly count?: number;
+};
+/**
+ * Adds one or more newline (`\n`) characters. Must be used within `<Text>` components.
+ */
+export default function Newline({ count }: Props): ReactElement;

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

@@ -0,0 +1,30 @@
+/**
+ * Ordered list component for Ink.
+ *
+ * Inspired by ink-ui OrderedList 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 OrderedListEntry = {
+    /**
+     * Nested sub-items, rendered as a sub-list with hierarchical numbering.
+     */
+    readonly children?: ReadonlyArray<OrderedListEntry>;
+    /**
+     * Display text for this item.
+     */
+    readonly label: ReactNode;
+};
+export type Props = {
+    /**
+     * Entries to render as a numbered list.
+     */
+    readonly items: ReadonlyArray<OrderedListEntry>;
+};
+/**
+ * Renders a numbered list with hierarchical nesting support.
+ */
+export default function OrderedList({ items }: Props): ReactElement;

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

@@ -0,0 +1,75 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Metadata about the current page state, passed to the render-prop children.
+ */
+export type PageMeta = {
+    readonly currentPage: number;
+    readonly endIndex: number;
+    readonly isFirstPage: boolean;
+    readonly isLastPage: boolean;
+    readonly startIndex: number;
+    readonly totalPages: number;
+};
+export type Props<T> = {
+    /**
+     * Render-prop that receives the current page items and page metadata.
+     */
+    readonly children: (pageItems: readonly 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[];
+    /**
+     * Called when the page changes.
+     */
+    readonly onChange?: (page: number) => void;
+    /**
+     * Controlled current page (0-indexed). When provided, the component is controlled.
+     */
+    readonly page?: number;
+    /**
+     * Number of items per page.
+     */
+    readonly pageSize: number;
+    /**
+     * Indicator style.
+     * - `"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;

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

@@ -0,0 +1,51 @@
+/**
+ * Progress bar component for Ink.
+ *
+ * Based on ink-progress-bar by Frankie Bagnardi (brigand).
+ * @see https://github.com/brigand/ink-progress-bar
+ *
+ * MIT License
+ * Copyright (c) Frankie Bagnardi
+ */
+import type { ReactElement } from "react";
+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;
+    /**
+     * Override the terminal width used for calculation.
+     * When 0, uses the actual terminal width.
+     * @default 0
+     */
+    readonly columns?: number;
+    /**
+     * Number of columns reserved on the left side (e.g. for labels).
+     * @default 0
+     */
+    readonly left?: number;
+    /**
+     * Completion percentage between 0 and 1.
+     * @default 1
+     */
+    readonly percent?: number;
+    /**
+     * Number of columns reserved on the right side (e.g. for percentage text).
+     * @default 0
+     */
+    readonly right?: number;
+    /**
+     * Whether to pad the remaining space with whitespace.
+     * Useful when rendering the bar over a background color.
+     * @default false
+     */
+    readonly rightPad?: boolean;
+} & Omit<TextProps, "children">;
+/**
+ * A terminal progress bar that fills proportionally to a percentage value.
+ *
+ * ```tsx
+ * &lt;ProgressBar percent={0.5} />
+ * &lt;ProgressBar percent={0.75} color="green" left={10} right={5} />
+ * ```
+ */
+export default function ProgressBar({ character, columns: columnsProp, left, percent, right, rightPad, ...textProps }: Props): ReactElement;

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

@@ -0,0 +1,96 @@
+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";
+export type Item<V> = {
+    /**
+     * Called automatically when this item is selected (via Enter or number key).
+     * Fires after `onSelect`. Useful for defining per-item behavior inline.
+     */
+    readonly action?: () => void;
+    readonly key?: string;
+    readonly label: string;
+    readonly value: V;
+};
+export type SeparatorItem = {
+    /**
+     * Marks this entry as a non-focusable separator line.
+     */
+    readonly isSeparator: true;
+    readonly key?: string;
+    /**
+     * Custom separator text. Defaults to `"───"`.
+     */
+    readonly label?: string;
+};
+export type SelectInputEntry<V> = Item<V> | SeparatorItem;
+export type Props<V> = {
+    /**
+     * Color used for the selected item and indicator.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Color used for unselected items.
+     */
+    readonly defaultColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Controlled selected index. When provided, the component becomes controlled
+     * and `initialIndex` is ignored. Update this value in the `onHighlight` callback
+     * to track selection externally. If the index points to a separator, the nearest
+     * selectable item is highlighted instead.
+     */
+    readonly index?: number;
+    /**
+     * Custom component to override the default indicator component.
+     */
+    readonly indicatorComponent?: FC<IndicatorProps>;
+    /**
+     * Index of initially-selected item in `items` array.
+     * Ignored when `index` is provided.
+     * When omitted (`undefined`), no item is highlighted until the user presses a key.
+     * If the index points to a separator, the nearest selectable item is used.
+     */
+    readonly initialIndex?: number;
+    /**
+     * Whether the input is focused. Useful for when there are multiple
+     * inputs on the screen and you need to control which one captures input.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Custom component to override the default item component.
+     */
+    readonly itemComponent?: FC<ItemProps>;
+    /** @default [] */
+    readonly items?: ReadonlyArray<SelectInputEntry<V>>;
+    /**
+     * Number of visible items. Useful if the list is long and you want
+     * to limit the display with a scrolling window.
+     */
+    readonly limit?: number;
+    /**
+     * Called when the user highlights a new item via arrow keys or `j`/`k`.
+     * The second argument is the index of the highlighted item in the visible list.
+     */
+    readonly onHighlight?: (item: Item<V>, index: number) => void;
+    /**
+     * Called when the user selects an item via Enter or a number key (1-9).
+     */
+    readonly onSelect?: (item: Item<V>) => void;
+    /**
+     * Whether to reset the selection when items change.
+     * Set to `false` to preserve the current selection across item updates.
+     * @default true
+     */
+    readonly resetOnItemsChange?: boolean;
+};
+/**
+ * A select input component for terminal UIs.
+ *
+ * Renders a list of items with an indicator showing the currently highlighted item.
+ * Users can navigate with arrow keys or `j`/`k`, select with Enter, or jump to an
+ * item by pressing a number key (1-9).
+ */
+export default function SelectInput<V>({ accentColor, defaultColor, index, indicatorComponent, initialIndex, isFocused, itemComponent, items, limit: customLimit, onHighlight, onSelect, resetOnItemsChange, }: Props<V>): ReactElement;

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

@@ -0,0 +1,36 @@
+/**
+ * Default indicator component for SelectInput.
+ *
+ * Based on ink-select-input by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-select-input
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Color of the indicator when selected.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Whether the parent SelectInput has focus.
+     * When `false`, the indicator is dimmed even if the item is selected.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Whether this indicator's item is currently selected.
+     * @default false
+     */
+    readonly isSelected?: boolean;
+};
+/**
+ * Renders a pointer indicator next to the selected item, or a blank space otherwise.
+ * When unfocused, the indicator is rendered with `dimColor` to visually distinguish
+ * the active select input from inactive ones.
+ */
+export default function SelectInputIndicator({ accentColor, isFocused, isSelected }: Props): ReactElement;

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

@@ -0,0 +1,43 @@
+/**
+ * Default item component for SelectInput.
+ *
+ * Based on ink-select-input by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-select-input
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ */
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Color of the label when selected.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Color of the label when not selected.
+     */
+    readonly defaultColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Whether the parent SelectInput has focus.
+     * When `false`, the selected item is dimmed.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Whether this item is currently selected.
+     * @default false
+     */
+    readonly isSelected?: boolean;
+    /**
+     * Text label to display for this item.
+     */
+    readonly label: string;
+};
+/**
+ * Renders an item label, using `accentColor` when selected and `defaultColor` otherwise.
+ * When unfocused, selected items are rendered with `dimColor`.
+ */
+export default function SelectInputItem({ accentColor, defaultColor, isFocused, isSelected, label }: Props): ReactElement;

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

@@ -0,0 +1,92 @@
+/**
+ * Slider component for Ink.
+ *
+ * A keyboard-driven range input for terminal UIs, supporting
+ * horizontal and vertical orientations.
+ */
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Accent color for the filled portion of the track and thumb.
+     * @default "green"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Color for the empty portion of the track.
+     * @default "gray"
+     */
+    readonly defaultColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Initial value when uncontrolled.
+     * @default 0
+     */
+    readonly defaultValue?: number;
+    /**
+     * Character used for the empty portion of the track.
+     * @default "░"
+     */
+    readonly emptyCharacter?: string;
+    /**
+     * Character used for the filled portion of the track.
+     * @default "█"
+     */
+    readonly filledCharacter?: string;
+    /**
+     * When true, all input is ignored and the slider is dimmed.
+     * @default false
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * When true, the component responds to keyboard input.
+     * @default true
+     */
+    readonly isFocused?: boolean;
+    /**
+     * Maximum value.
+     * @default 100
+     */
+    readonly max?: number;
+    /**
+     * Minimum value.
+     * @default 0
+     */
+    readonly min?: number;
+    /**
+     * Fires whenever the value changes.
+     */
+    readonly onChange?: (value: number) => void;
+    /**
+     * Layout direction of the slider.
+     * @default "horizontal"
+     */
+    readonly orientation?: "horizontal" | "vertical";
+    /**
+     * Increment size for arrow key presses.
+     * @default 1
+     */
+    readonly step?: number;
+    /**
+     * Character used to indicate the current position.
+     * @default "●"
+     */
+    readonly thumbCharacter?: string;
+    /**
+     * Controlled value. When provided, `defaultValue` is ignored.
+     */
+    readonly value?: number;
+    /**
+     * Width of the slider track in columns (horizontal) or rows (vertical).
+     * @default 20
+     */
+    readonly width?: number;
+};
+/**
+ * A keyboard-driven slider / range input.
+ *
+ * ```tsx
+ * &lt;Slider defaultValue={50} min={0} max={100} onChange={setValue} />
+ * ```
+ */
+export default function Slider({ accentColor, defaultColor, defaultValue, emptyCharacter, filledCharacter, isDisabled, isFocused, max, min, onChange, orientation, step, thumbCharacter, value: controlledValue, width, }: Props): ReactElement;

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

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+/**
+ * A flexible space that expands along the major axis of its containing layout.
+ *
+ * It's useful as a shortcut for filling all the available space between elements.
+ */
+export default function Spacer(): ReactElement;

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

@@ -0,0 +1,42 @@
+/**
+ * Spinner component for Ink.
+ *
+ * Based on ink-spinner by Vadim Demedes.
+ * @see https://github.com/vadimdemedes/ink-spinner
+ *
+ * MIT License
+ * Copyright (c) Vadym Demedes (github.com/vadimdemedes)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in the
+ * Software without restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so, subject to the
+ * following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+import type { SpinnerName } from "cli-spinners";
+import type { ReactElement } from "react";
+export type Props = {
+    /**
+     * Type of a spinner.
+     * See [cli-spinners](https://github.com/sindresorhus/cli-spinners) for available spinners.
+     * @default "dots"
+     */
+    readonly type?: SpinnerName;
+};
+/**
+ * Spinner component that renders an animated loading indicator.
+ *
+ * Uses spinners from [cli-spinners](https://github.com/sindresorhus/cli-spinners).
+ */
+export default function Spinner({ type }: Props): ReactElement;

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

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Styles } from "../styles.d.ts";
+export type Props<T> = {
+    /**
+     * Function that is called to render every item in the `items` array. The first argument is the item itself, and the second argument is the index of that item in the `items` array. Note that a `key` must be assigned to the root component.
+     */
+    readonly children: (item: T, index: number) => ReactNode;
+    /**
+     * Array of items of any type to render using the function you pass as a component child.
+     */
+    readonly items: T[];
+    /**
+     * Styles to apply to a container of child elements. See &lt;Box> for supported properties.
+     */
+    readonly style?: Styles;
+};
+/**
+ * `&lt;Static>` component permanently renders its output above everything else. It's useful for displaying activity like completed tasks or logs—things that don't change after they're rendered (hence the name "Static").
+ *
+ * It's preferred to use `&lt;Static>` for use cases like these when you can't know or control the number of items that need to be rendered.
+ *
+ * For example, [Tap](https://github.com/tapjs/node-tap) uses `&lt;Static>` to display a list of completed tests. [Gatsby](https://github.com/gatsbyjs/gatsby) uses it to display a list of generated pages while still displaying a live progress bar.
+ */
+export default function Static<T>(props: Props<T>): ReactElement;

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

@@ -0,0 +1,28 @@
+/**
+ * StaticRender component — pre-renders children once and caches the result.
+ *
+ * When mounted, StaticRender renders its children into a Region via
+ * prepareYogaTree() in the Ink layout phase, then caches the result on the
+ * DOM node. On subsequent renders, the cached Region is composited directly
+ * via addRegionTree(), skipping the entire subtree traversal.
+ *
+ * Children are passed as a render function `() => ReactNode`. Once the cache
+ * is ready, the component stops calling the function so React does not
+ * re-reconcile the subtree on subsequent renders.
+ *
+ * Use this for content that renders once and doesn't change (e.g., completed
+ * task output, logged messages, static headers).
+ *
+ * Ported from jacob314/ink (Google LLC, Apache-2.0).
+ * @license Apache-2.0
+ */
+import type { ReactNode } from "react";
+import React from "react";
+import type { Styles } from "../styles.d.ts";
+export type Props = {
+    readonly children: () => ReactNode;
+    readonly style?: Styles;
+    readonly width?: number;
+};
+declare const StaticRender: ({ children, style, width }: Props) => React.ReactNode;
+export default StaticRender;