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

package/dist/ink/components/{Spinner.d.ts → spinner.d.ts}

@@ -24,19 +24,17 @@
  * 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 { SpinnerName } from "@visulima/spinner";
 import type { ReactElement } from "react";
 export type Props = {
     /**
      * Type of a spinner.
-     * See [cli-spinners](https://github.com/sindresorhus/cli-spinners) for available spinners.
+     * Accepts any preset from `@visulima/spinner` (cli-spinners + custom frame sets).
      * @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/{StaticRender.d.ts → static-render.d.ts}

@@ -10,19 +10,31 @@
  * is ready, the component stops calling the function so React does not
  * re-reconcile the subtree on subsequent renders.
  *
+ * Re-rendering the cached content is controlled via the `deps` prop (similar
+ * to React's hook deps). When `deps` changes, the cache is invalidated and
+ * `children()` is invoked again. If `deps` is omitted, the cache is
+ * invalidated whenever the `children` function reference changes.
+ *
  * 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 type { DependencyList, ReactNode } from "react";
 import React from "react";
 import type { Styles } from "../styles.d.ts";
+/**
+ * @property children Render function invoked once to produce the cached content.
+ * @property deps Dependencies that control when the static content is re-rendered. When any dependency changes (shallow, Object.is comparison), the cache is invalidated and children() is invoked again. If omitted, the cache is invalidated whenever the children function reference changes.
+ * @property style Optional style applied to the static-render container.
+ * @property width Optional fixed width for the cached region.
+ */
 export type Props = {
     readonly children: () => ReactNode;
+    readonly deps?: DependencyList;
     readonly style?: Styles;
     readonly width?: number;
 };
-declare const StaticRender: ({ children, style, width }: Props) => React.ReactNode;
+declare const StaticRender: ({ children, deps, style, width }: Props) => React.ReactNode;
 export default StaticRender;

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

@@ -0,0 +1,30 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Background color spanning the whole row.
+     */
+    readonly backgroundColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Content rendered in the center. Optional.
+     */
+    readonly center?: ReactNode;
+    /**
+     * Default foreground for text rendered inside the row.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Content rendered flush-left.
+     */
+    readonly left?: ReactNode;
+    /**
+     * Content rendered flush-right.
+     */
+    readonly right?: ReactNode;
+};
+/**
+ * Full-width status bar with left / center / right slots. Typically pinned to
+ * the bottom of the UI.
+ */
+export default function StatusLine({ backgroundColor, center, color, left, right }: Props): ReactElement;

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

@@ -0,0 +1,42 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type StepStatus = "active" | "completed" | "error" | "pending";
+export type StepperStep = {
+    readonly description?: string;
+    readonly key?: string;
+    readonly label: ReactNode;
+    readonly status?: StepStatus;
+};
+export type Props = {
+    /**
+     * Color used for active and completed steps.
+     * @default "blue"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Index of the current step (used when steps do not provide a status).
+     * @default 0
+     */
+    readonly activeIndex?: number;
+    /**
+     * Color used for errors.
+     * @default "red"
+     */
+    readonly errorColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Orientation of the stepper.
+     * @default "horizontal"
+     */
+    readonly orientation?: "horizontal" | "vertical";
+    /**
+     * List of steps.
+     */
+    readonly steps: ReadonlyArray<StepperStep>;
+};
+/**
+ * Step indicator for multi-stage flows.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the steps horizontally or vertically.
+ */
+export default function Stepper({ accentColor, activeIndex, errorColor, orientation, steps }: Props): ReactElement;

package/dist/ink/components/{Stopwatch.d.ts → stopwatch.d.ts}

@@ -1,10 +1,9 @@
-import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { ReactElement, Ref } 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;
@@ -19,16 +18,15 @@ export type Props = {
     /**
      * 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;
+    readonly ref?: Ref<StopwatchRef>;
 };
 /**
  * A count-up stopwatch component.
@@ -36,9 +34,9 @@ export type Props = {
  * Exposes `start`, `stop`, `toggle`, `reset`, and `lap` methods via ref.
  *
  * ```tsx
- * const ref = useRef<StopwatchRef>(null);
- * <Stopwatch ref={ref} autoStart />
+ * const ref = useRef&lt;StopwatchRef>(null);
+ * &lt;Stopwatch ref={ref} autoStart />
  * ```
  */
-declare const Stopwatch: ForwardRefExoticComponent<Props & RefAttributes<StopwatchRef>>;
+declare const Stopwatch: ({ autoStart, bold, color, format, interval, ref }: Props) => ReactElement;
 export default Stopwatch;

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

@@ -0,0 +1,38 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement } from "react";
+import type { LiteralUnion } from "type-fest";
+export type Props = {
+    /**
+     * Color applied to the streamed output.
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Optional cursor character rendered while streaming.
+     * @default "▊"
+     */
+    readonly cursor?: string;
+    /**
+     * Milliseconds between characters.
+     * @default 20
+     */
+    readonly interval?: number;
+    /**
+     * Called exactly once per `text` value, after the full text has been revealed.
+     */
+    readonly onComplete?: () => void;
+    /**
+     * Whether to display the cursor after streaming completes.
+     * @default false
+     */
+    readonly showCursorWhenDone?: boolean;
+    /**
+     * Full text to stream into the output.
+     */
+    readonly text: string;
+};
+/**
+ * Typewriter animation that reveals text one character at a time.
+ * Automatically resets and replays when `text` changes. `onComplete`
+ * fires exactly once per `text` value once it is fully revealed.
+ */
+export default function StreamingText({ color, cursor, interval, onComplete, showCursorWhenDone, text }: Props): ReactElement;

package/dist/ink/components/switch.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 = {
+    /**
+     * Accent color for the on state.
+     * @default "green"
+     */
+    readonly accentColor?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Auto-focus when mounted if nothing else is focused.
+     */
+    readonly autoFocus?: boolean;
+    /**
+     * Optional label rendered after the switch.
+     */
+    readonly children?: ReactNode;
+    /**
+     * Initial value when uncontrolled.
+     */
+    readonly defaultValue?: boolean;
+    /**
+     * Disable input and dim the switch.
+     */
+    readonly isDisabled?: boolean;
+    /**
+     * Labels displayed inside the switch track.
+     * @default ["off", "on"]
+     */
+    readonly labels?: readonly [string, string];
+    /**
+     * Fired when the switch is toggled.
+     */
+    readonly onChange?: (value: boolean) => void;
+    /**
+     * Controlled value. Pair with `onChange` to update the parent.
+     */
+    readonly value?: boolean;
+};
+/**
+ * Focusable on/off switch. Toggles with Space or Enter.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering two labeled segments plus an optional
+ * trailing label.
+ */
+export default function Switch({ accentColor, autoFocus, children, defaultValue, isDisabled, labels, onChange, value, }: Props): ReactElement;

package/dist/ink/components/{Tabs.d.ts → tabs.d.ts}

@@ -10,7 +10,7 @@
 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";
+import type { Props as TabProps } from "./tab.d.ts";
 /**
  * Keyboard navigation configuration for Tabs.
  */

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

@@ -0,0 +1,30 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type TagVariant = "outline" | "solid" | "subtle";
+export type Props = {
+    /**
+     * Tag content.
+     */
+    readonly children: ReactNode;
+    /**
+     * Base color.
+     * @default "blue"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Optional symbol rendered before the label (e.g. `●`, `✔`, `★`).
+     */
+    readonly icon?: ReactNode;
+    /**
+     * Visual style.
+     * @default "subtle"
+     */
+    readonly variant?: TagVariant;
+};
+/**
+ * Render a short pill-shaped label.
+ * @param props See {@link Props}.
+ * @returns A `ReactElement` rendering the tag in the requested variant.
+ */
+export default function Tag({ children, color, icon, variant }: Props): ReactElement;

package/dist/ink/components/{Timer.d.ts → timer.d.ts}

@@ -1,10 +1,9 @@
-import type { ForwardRefExoticComponent, RefAttributes } from "react";
+import type { ReactElement, Ref } 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;
@@ -23,13 +22,11 @@ export type Props = {
     /**
      * 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;
@@ -37,6 +34,7 @@ export type Props = {
      * Called once when the timer reaches zero.
      */
     readonly onTimeout?: () => void;
+    readonly ref?: Ref<TimerRef>;
 };
 /**
  * A countdown timer component.
@@ -44,9 +42,9 @@ export type Props = {
  * Exposes `start`, `stop`, `toggle`, and `reset` methods via ref.
  *
  * ```tsx
- * const ref = useRef<TimerRef>(null);
- * <Timer ref={ref} duration={60_000} autoStart />
+ * const ref = useRef&lt;TimerRef>(null);
+ * &lt;Timer ref={ref} duration={60_000} autoStart />
  * ```
  */
-declare const Timer: ForwardRefExoticComponent<Props & RefAttributes<TimerRef>>;
+declare const Timer: ({ autoStart, bold, color, duration, format, interval, onTimeout, ref }: Props) => ReactElement;
 export default Timer;

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

@@ -0,0 +1,41 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Variant } from "./variant-config.d.ts";
+export type ToastVariant = Variant;
+export type Props = {
+    /**
+     * Toast body.
+     */
+    readonly children: ReactNode;
+    /**
+     * Milliseconds to display before auto-dismissing. Use `0` to disable.
+     * @default 4000
+     */
+    readonly duration?: number;
+    /**
+     * Called after the toast dismisses itself.
+     */
+    readonly onDismiss?: () => void;
+    /**
+     * Optional title rendered before the body.
+     */
+    readonly title?: string;
+    /**
+     * Visual variant determining the icon and border color.
+     * @default "info"
+     */
+    readonly variant?: ToastVariant;
+    /**
+     * Manually control visibility. When provided, `duration` is ignored.
+     */
+    readonly visible?: boolean;
+    /**
+     * Optional width override.
+     */
+    readonly width?: number;
+};
+/**
+ * Ephemeral notification. Disappears automatically after `duration` ms.
+ * @param props See {@link Props}.
+ * @returns A bordered `ReactElement` while visible; `null` once dismissed.
+ */
+export default function Toast({ children, duration, onDismiss, title, variant, visible, width }: Props): ReactElement | null;

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

@@ -0,0 +1,36 @@
+import type { AnsiColors } from "@visulima/colorize";
+import type { ReactElement, ReactNode } from "react";
+import type { LiteralUnion } from "type-fest";
+export type TooltipPlacement = "bottom" | "left" | "right" | "top";
+export type Props = {
+    /**
+     * The element the tooltip is attached to.
+     */
+    readonly children: ReactNode;
+    /**
+     * Border color.
+     * @default "gray"
+     */
+    readonly color?: LiteralUnion<AnsiColors, string>;
+    /**
+     * Tooltip body content.
+     */
+    readonly content: ReactNode;
+    /**
+     * Controls whether the tooltip is rendered.
+     * @default true
+     */
+    readonly isVisible?: boolean;
+    /**
+     * Relative position. Terminal rendering does not support floating layers,
+     * so the tooltip is placed inline next to (or above / below) the anchor.
+     * @default "right"
+     */
+    readonly placement?: TooltipPlacement;
+};
+/**
+ * Renders supplementary text next to an anchor. Because terminals don't have
+ * a floating-layer concept, the tooltip lives inline in the layout. Hide it
+ * by toggling `isVisible`.
+ */
+export default function Tooltip({ children, color, content, isVisible, placement }: Props): ReactElement;

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

@@ -0,0 +1,53 @@
+import type { ReactElement, ReactNode } from "react";
+export type TransitionPreset = "fade" | "reveal" | "slide-down" | "slide-left" | "slide-right" | "slide-up";
+export type TransitionPhase = "entered" | "entering" | "exited" | "exiting";
+export type Props = {
+    /**
+     * Content to animate.
+     */
+    readonly children: ReactNode;
+    /**
+     * For slide presets, how many characters of offset to animate across.
+     * For the `reveal` preset, the maximum row count to scale through.
+     * @default 4
+     */
+    readonly distance?: number;
+    /**
+     * Duration of both enter and exit transitions, in milliseconds.
+     * @default 240
+     */
+    readonly duration?: number;
+    /**
+     * Called once the exit animation finishes (i.e. the component has fully
+     * transitioned out). AnimatePresence uses this to unmount the wrapper.
+     */
+    readonly onExit?: () => void;
+    /**
+     * Animation preset controlling how the content appears/disappears.
+     * @default "fade"
+     */
+    readonly preset?: TransitionPreset;
+    /**
+     * Controls the target phase. `true` drives towards `entered`, `false`
+     * drives towards `exited`. Flip the value to trigger animation.
+     * @default true
+     */
+    readonly show?: boolean;
+    /**
+     * Tick interval in milliseconds. Lower values yield smoother animation
+     * at the cost of CPU.
+     * @default 30
+     */
+    readonly tickInterval?: number;
+};
+type TransitionComponent = ((props: Props) => ReactElement | null) & {
+    isAnimatable: true;
+};
+/**
+ * Static marker used by `AnimatePresence` to recognize Transition children
+ * even when the consumer hasn't explicitly passed a `show` prop. Consumers
+ * can apply the same marker to their own wrappers (`MyWrapper.isAnimatable
+ * = true`) to opt them into animation orchestration.
+ */
+declare const TransitionWithMarker: TransitionComponent;
+export default TransitionWithMarker;

package/dist/ink/components/tree-view/theme.d.ts

@@ -1,5 +1,5 @@
-import type { Props as BoxProps } from "../Box.d.ts";
-import type { Props as TextProps } from "../Text.d.ts";
+import type { Props as BoxProps } from "../box.d.ts";
+import type { Props as TextProps } from "../text.d.ts";
 type StyleFunctionProps = {
     readonly depth?: number;
     readonly hasChildren?: boolean;

package/dist/ink/cursor-helpers.d.ts

@@ -2,9 +2,6 @@ export type CursorPosition = {
     x: number;
     y: number;
 };
-declare const showCursorEscape = "\u001B[?25h";
-declare const hideCursorEscape = "\u001B[?25l";
-export { hideCursorEscape, showCursorEscape };
 /**
  * Compare two cursor positions. Returns true if they differ.
  */

package/dist/ink/dom.d.ts

@@ -1,4 +1,5 @@
 import type { Node as YogaNode } from "yoga-layout";
+import type { Region } from "./region.d.ts";
 import type { OutputTransformer } from "./render-node-to-output.d.ts";
 import type ResizeObserver from "./resize-observer.d.ts";
 import type { ScrollState } from "./scroll.d.ts";
@@ -62,7 +63,7 @@ export type DOMElement = InkNode & {
      * skipped during rendering and the cached region is composited directly.
      * Set by setCachedRender(), cleared on unmount by cleanupNodeTree().
      */
-    cachedRender?: import("./region").Region;
+    cachedRender?: Region;
     childNodes: DOMNode[];
     internal_accessibility?: {
         role?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
@@ -100,6 +101,12 @@ export type DOMElement = InkNode & {
      * Maximum scrollTop ever reached, used with stableScrollback.
      */
     internal_maxScrollTop?: number;
+    /**
+     * Callback invoked after prepareYogaTree() caches the render output for
+     * an ink-static-render node. StaticRender uses this to set `isRendered`
+     * state, which prevents React from re-reconciling children once cached.
+     */
+    internal_onRendered?: () => void;
     /**
      * Whether this element is opaque (prevents rendering of covered content beneath it).
      */
@@ -145,12 +152,6 @@ export type DOMElement = InkNode & {
     };
     internal_transform?: OutputTransformer;
     isStaticDirty?: boolean;
-    /**
-     * Callback invoked after prepareYogaTree() caches the render output for
-     * an ink-static-render node. StaticRender uses this to set `isRendered`
-     * state, which prevents React from re-reconciling children once cached.
-     */
-    internal_onRendered?: () => void;
     /**
      * Whether the Yoga subtree has been detached (children removed from Yoga layout)
      * because a cachedRender was set. When cachedRender is invalidated,
@@ -195,7 +196,7 @@ export declare const emitLayoutListeners: (rootNode: DOMElement) => void;
  *
  * Ported from jacob314/ink (Google LLC, Apache-2.0).
  */
-export declare const setCachedRender: (node: DOMElement, cachedRender: import("./region").Region) => void;
+export declare const setCachedRender: (node: DOMElement, cachedRender: Region) => void;
 /**
  * Get the path from the root to this node (inclusive).
  * Returns an array starting with the root and ending with the node.

package/dist/ink/hooks/use-animation.d.ts

@@ -1,14 +1,12 @@
 type Options = {
     /**
      * Time between ticks in milliseconds.
-     *
      * @default 100
      */
     readonly interval?: number;
     /**
      * Whether the animation is running. When set to `false`, the animation stops.
      * When toggled back to `true`, all values reset to `0`.
-     *
      * @default true
      */
     readonly isActive?: boolean;

package/dist/ink/hooks/use-app.d.ts

@@ -1,4 +1,4 @@
-import type { Props } from "../components/AppContext.d.ts";
+import type { Props } from "../components/app-context.d.ts";
 /**
  * A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.
  */

package/dist/ink/hooks/use-focus-manager.d.ts

@@ -1,4 +1,4 @@
-import type { Props } from '../components/FocusContext.d.ts';
+import type { Props } from '../components/focus-context.d.ts';
 type Output = {
     /**
      * The ID of the currently focused component, or `undefined` if no component is focused.

package/dist/ink/hooks/use-form.d.ts

@@ -0,0 +1,70 @@
+export type ValidationResult = string | undefined;
+export type FieldValidator<V> = (value: V, values: Readonly<Record<string, unknown>>) => ValidationResult;
+export type FieldConfig<V = unknown> = {
+    /**
+     * Initial value.
+     */
+    readonly initialValue: V;
+    /**
+     * Optional validator. Return a string to indicate an error; return
+     * `undefined` for valid.
+     */
+    readonly validate?: FieldValidator<V>;
+};
+export type FormSchema = Readonly<Record<string, FieldConfig<never>>>;
+export type FormValues<S extends Readonly<Record<string, FieldConfig>>> = {
+    [K in keyof S]: S[K] extends FieldConfig<infer V> ? V : never;
+};
+export type UseFormOptions<S extends Readonly<Record<string, FieldConfig>>> = {
+    /**
+     * Field declarations.
+     */
+    readonly fields: S;
+    /**
+     * Called on submit if all fields validate.
+     */
+    readonly onSubmit?: (values: FormValues<S>) => void | Promise<void>;
+};
+export type UseFormResult<S extends Readonly<Record<string, FieldConfig>>> = {
+    /**
+     * Map of fieldName -> validation error (if any).
+     */
+    readonly errors: Readonly<Partial<Record<keyof S, string>>>;
+    /**
+     * True while the last `submit()` is in-flight.
+     */
+    readonly isSubmitting: boolean;
+    /**
+     * Reset all fields back to their initial values and clear errors / touched.
+     */
+    readonly reset: () => void;
+    /**
+     * Mark a field as touched. Useful on blur.
+     */
+    readonly setTouched: <K extends keyof S>(name: K, touched?: boolean) => void;
+    /**
+     * Update a single field.
+     */
+    readonly setValue: <K extends keyof S>(name: K, value: FormValues<S>[K]) => void;
+    /**
+     * Trigger validation and call the `onSubmit` option. Returns true if
+     * submission succeeded (all fields valid).
+     */
+    readonly submit: () => Promise<boolean>;
+    /**
+     * Map of fieldName -> boolean. Field is considered touched after the
+     * first `setTouched(name)` or `submit()` invocation.
+     */
+    readonly touched: Readonly<Partial<Record<keyof S, boolean>>>;
+    /**
+     * Current values.
+     */
+    readonly values: FormValues<S>;
+};
+/**
+ * Minimal headless form state machine. Tracks values, touched state, errors,
+ * and submission in-flight. Pair with `&lt;Form />` for default layout, or wire
+ * up your own inputs directly.
+ */
+declare const useForm: <S extends Readonly<Record<string, FieldConfig>>>(options: UseFormOptions<S>) => UseFormResult<S>;
+export default useForm;