ink-cartridge 3.6.1

package/dist/components/select/SelectInput.js

@@ -0,0 +1,147 @@
+import React, { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import { Box, Text } from 'ink';
+import { useKeyboard, useFocusState } from '../../keyboard/hook.js';
+function defaultIndicator({ isSelected }) {
+    return React.createElement(Box, { marginRight: 1 }, isSelected
+        ? React.createElement(Text, { color: 'blue' }, '\u276F')
+        : React.createElement(Text, null, ' '));
+}
+function defaultItem(props) {
+    return React.createElement(Text, { color: props.isSelected ? 'blue' : undefined }, props.label);
+}
+function clamp(n, min, max) {
+    return Math.max(min, Math.min(n, max));
+}
+/**
+ * A single-select list component integrated with the ink-cartridge keyboard and
+ * focus system.
+ *
+ * Each instance registers a focus target identified by {@link SelectInputProps.focusId}
+ * on the current screen's keyboard layer. Users navigate between multiple
+ * SelectInputs on the same screen with Tab / Shift+Tab. Within the active
+ * component, arrow keys (or vim-style j/k) move the highlight, and Enter
+ * confirms the selection. Number keys 1-9 directly select an item.
+ *
+ * When the component is not the active focus target, its items are visually
+ * dimmed and no key events are delivered to it.
+ *
+ * @typeParam T - The type of the value associated with each item.
+ * @typeParam I - The extended item type, must extend Item<T>. Defaults to Item<T>.
+ */
+export function SelectInput({ items = [], onSelect, itemComponent, indicatorComponent, focusId, limit: limitProp = 10, storage, storageKey, }) {
+    const isFocused = useFocusState(focusId);
+    const { boundKeyboard, focusUnregister } = useKeyboard();
+    const IndicatorComp = indicatorComponent ?? defaultIndicator;
+    const ItemComp = (itemComponent ??
+        defaultItem);
+    const persistKey = storageKey ?? `select:${focusId}`;
+    const hasLimit = items.length > limitProp;
+    const limit = hasLimit ? limitProp : items.length;
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const [scrollOffset, setScrollOffset] = useState(0);
+    useEffect(() => {
+        if (!storage || items.length === 0)
+            return;
+        let cancelled = false;
+        storage.read.num(persistKey, 0).then((absIdx) => {
+            if (cancelled)
+                return;
+            const clamped = clamp(absIdx, 0, Math.max(0, items.length - 1));
+            if (hasLimit) {
+                const newScroll = Math.max(0, Math.min(clamped, items.length - limit));
+                setScrollOffset(newScroll);
+                setSelectedIndex(clamped - newScroll);
+            }
+            else {
+                setSelectedIndex(clamped);
+            }
+        });
+        return () => { cancelled = true; };
+    }, [storage, persistKey, items.length, hasLimit, limit]);
+    useEffect(() => {
+        if (!storage || items.length === 0)
+            return;
+        const absIdx = scrollOffset + selectedIndex;
+        storage.write.num(persistKey, absIdx);
+    }, [storage, persistKey, selectedIndex, scrollOffset, items.length]);
+    const selectedIndexRef = useRef(selectedIndex);
+    selectedIndexRef.current = selectedIndex;
+    const onSelectRef = useRef(onSelect);
+    onSelectRef.current = onSelect;
+    const visibleItems = useMemo(() => {
+        if (!hasLimit)
+            return items;
+        return items.slice(scrollOffset, scrollOffset + limit);
+    }, [items, hasLimit, limit, scrollOffset]);
+    const visibleItemsRef = useRef(visibleItems);
+    visibleItemsRef.current = visibleItems;
+    useEffect(() => {
+        if (items.length === 0) {
+            setSelectedIndex(0);
+            setScrollOffset(0);
+            return;
+        }
+        if (scrollOffset + limit > items.length) {
+            setScrollOffset(Math.max(0, items.length - limit));
+        }
+        if (selectedIndex >= limit || selectedIndex >= visibleItems.length) {
+            setSelectedIndex(clamp(items.length > 0 ? items.length - 1 : 0, 0, limit - 1));
+        }
+    }, [items.length, scrollOffset, limit, selectedIndex, visibleItems.length]);
+    const moveHighlight = useCallback((delta) => {
+        setSelectedIndex((prev) => {
+            if (!hasLimit) {
+                return clamp(prev + delta, 0, Math.max(0, items.length - 1));
+            }
+            const absIdx = scrollOffset + prev;
+            const newAbs = clamp(absIdx + delta, 0, Math.max(0, items.length - 1));
+            if (newAbs < scrollOffset) {
+                setScrollOffset(newAbs);
+                return 0;
+            }
+            if (newAbs >= scrollOffset + limit) {
+                setScrollOffset(newAbs - limit + 1);
+                return limit - 1;
+            }
+            return newAbs - scrollOffset;
+        });
+    }, [hasLimit, items.length, limit, scrollOffset]);
+    // Unregister old focus target when focusId changes
+    useEffect(() => {
+        return () => focusUnregister(focusId);
+    }, [focusId]);
+    useEffect(() => {
+        const fid = focusId;
+        const unUp = boundKeyboard(['up', 'k'], () => moveHighlight(-1), { focusId: fid });
+        const unDown = boundKeyboard(['down', 'j'], () => moveHighlight(1), { focusId: fid });
+        const unReturn = boundKeyboard(['return'], () => {
+            const item = visibleItemsRef.current[selectedIndexRef.current];
+            if (item)
+                onSelectRef.current(item);
+        }, { focusId: fid });
+        const numUnbinds = [];
+        for (let i = 1; i <= Math.min(9, visibleItems.length); i++) {
+            const idx = i - 1;
+            numUnbinds.push(boundKeyboard([String(i)], () => {
+                const item = visibleItemsRef.current[idx];
+                if (item)
+                    onSelectRef.current(item);
+            }, { focusId: fid }));
+        }
+        return () => {
+            unUp();
+            unDown();
+            unReturn();
+            numUnbinds.forEach((fn) => fn());
+        };
+    }, [
+        focusId,
+        boundKeyboard,
+        moveHighlight,
+        visibleItems.length,
+    ]);
+    return React.createElement(Box, { flexDirection: 'column' }, ...visibleItems.map((item, index) => {
+        const isItemSelected = index === selectedIndex && isFocused;
+        return React.createElement(Box, { key: item.Key ?? String(item.value) }, React.createElement(IndicatorComp, { isSelected: isItemSelected }), React.createElement(ItemComp, { ...item, isSelected: isItemSelected }));
+    }));
+}

package/dist/components/select/types.d.ts

@@ -0,0 +1,63 @@
+import React from "react";
+import type { StorageAPI } from "../../storage/index.js";
+/**
+ * The SelectInput component is required to pass in a type interface that must be included to act as a constraint
+ */
+export interface Item<T> {
+    /**
+     * Something that is used to show the user
+     */
+    label: string;
+    /**
+     * What is the actual value of the selected item
+     */
+    value: T;
+    /**
+     * Key convenient for dynamic addition and deletion
+     */
+    Key?: string;
+}
+export interface SelectInputProps<T, I extends Item<T> = Item<T>> {
+    /**
+     * Array to be passed in for UI display, etc.
+     */
+    items: I[];
+    /**
+     * What happens when the user presses Enter
+     * Accepts a parameter that represents the currently selected item
+     */
+    onSelect: (item: I) => void;
+    /**
+     * UI components for custom rendering
+     */
+    itemComponent?: React.ComponentType<I & {
+        isSelected: boolean;
+    }>;
+    /**
+     * Custom Indicator UI Component
+     */
+    indicatorComponent?: React.ComponentType<{
+        isSelected: boolean;
+    }>;
+    /**
+     * Focus, string type, controls whether this component is active
+     * Effectively prevents two SelectInputs from competing with each other
+     * Is not a Boolean type Because of the integration of the keyboard system.
+     */
+    focusId: string;
+    /**
+    * When the number of items exceeds what?
+    * The list will be scrolled
+    */
+    limit?: number;
+    /**
+     * Optional persistence instance. When provided, the cursor position
+     * (selectedIndex) is automatically saved and restored across sessions.
+     */
+    storage?: StorageAPI;
+    /**
+     * Storage key used for persistence. Defaults to `"select:<focusId>"` when
+     * not provided.
+     */
+    storageKey?: string;
+}

package/dist/components/select/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+import React from 'react';
+declare const FRAMES: Record<string, string[]>;
+export type SpinnerType = keyof typeof FRAMES;
+interface SpinnerProps {
+    type?: SpinnerType;
+    label?: string;
+    color?: string;
+    speed?: number;
+    active?: boolean;
+}
+export declare function Spinner({ type, label, color, speed, active, }: SpinnerProps): React.JSX.Element;
+export {};

package/dist/components/spinner/Spinner.js

@@ -0,0 +1,24 @@
+import React, { useState, useEffect } from 'react';
+import { Text } from 'ink';
+const FRAMES = {
+    dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+    line: ['─', '━', '─', '━', '─', '━', '─', '━'],
+    simple: ['|', '/', '-', '\\'],
+    triangle: ['◢', '◣', '◤', '◥'],
+    arc: ['◜', '◝', '◞', '◟'],
+};
+export function Spinner({ type = 'dots', label, color, speed = 80, active = true, }) {
+    const [index, setIndex] = useState(0);
+    const frames = FRAMES[type] ?? FRAMES.dots;
+    useEffect(() => {
+        if (!active || frames.length <= 1)
+            return;
+        const timer = setInterval(() => {
+            setIndex((prev) => (prev + 1) % frames.length);
+        }, speed);
+        return () => clearInterval(timer);
+    }, [active, speed, frames.length]);
+    const displayIndex = active ? index : 0;
+    const content = label ? `${frames[displayIndex]} ${label}` : frames[displayIndex];
+    return React.createElement(Text, { color: color }, content);
+}

package/dist/components/tabs/Tabs.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { TabsProps } from './types.js';
+export declare function Tabs({ focusId, tabs, activeTab: controlledActive, onChange, defaultActiveTab, storage, storageKey, }: TabsProps): React.JSX.Element;

package/dist/components/tabs/Tabs.js

@@ -0,0 +1,57 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import { Box, Text } from 'ink';
+import { useKeyboard, useFocusState } from '../../keyboard/index.js';
+export function Tabs({ focusId, tabs, activeTab: controlledActive, onChange, defaultActiveTab, storage, storageKey, }) {
+    const isFocused = useFocusState(focusId);
+    const { boundKeyboard, focusUnregister } = useKeyboard();
+    const isControlled = controlledActive !== undefined;
+    const [internalActive, setInternalActive] = useState(defaultActiveTab ?? tabs[0]?.id);
+    const persistKey = storageKey ?? `tabs:${focusId}`;
+    useEffect(() => {
+        if (!storage)
+            return;
+        let cancelled = false;
+        storage.read.str(persistKey, defaultActiveTab ?? tabs[0]?.id ?? '').then((v) => {
+            if (!cancelled)
+                setInternalActive(v);
+        });
+        return () => { cancelled = true; };
+    }, [storage, persistKey, defaultActiveTab, tabs]);
+    const activeId = isControlled ? controlledActive : internalActive;
+    const activeIndex = tabs.findIndex((t) => t.id === activeId);
+    const prev = useCallback(() => {
+        const nextIdx = activeIndex <= 0 ? tabs.length - 1 : activeIndex - 1;
+        const id = tabs[nextIdx].id;
+        if (isControlled) {
+            onChange?.(id);
+        }
+        else {
+            setInternalActive(id);
+            storage?.write.str(persistKey, id);
+        }
+    }, [activeIndex, tabs, isControlled, onChange, storage, persistKey]);
+    const next = useCallback(() => {
+        const nextIdx = (activeIndex + 1) % tabs.length;
+        const id = tabs[nextIdx].id;
+        if (isControlled) {
+            onChange?.(id);
+        }
+        else {
+            setInternalActive(id);
+            storage?.write.str(persistKey, id);
+        }
+    }, [activeIndex, tabs, isControlled, onChange, storage, persistKey]);
+    useEffect(() => {
+        const unLeft = boundKeyboard(['left'], () => prev(), { focusId });
+        const unRight = boundKeyboard(['right'], () => next(), { focusId });
+        return () => {
+            unLeft();
+            unRight();
+            focusUnregister(focusId);
+        };
+    }, [focusId, boundKeyboard, focusUnregister, prev, next]);
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Box, null, tabs.map((tab, i) => (React.createElement(Box, { key: tab.id, marginRight: 1, paddingX: 1 },
+            React.createElement(Text, { color: i === activeIndex ? 'cyan' : 'grey', bold: i === activeIndex, underline: i === activeIndex && isFocused }, tab.label))))),
+        React.createElement(Box, { marginTop: 1 }, tabs[activeIndex]?.content)));
+}

package/dist/components/tabs/types.d.ts

@@ -0,0 +1,32 @@
+import React from "react";
+import type { StorageAPI } from "../../storage/index.js";
+export interface Tab {
+    /** Unique identifier for this tab. */
+    id: string;
+    /** Display label shown in the tab bar. */
+    label: string;
+    /** Content rendered when this tab is active. */
+    content: React.ReactNode;
+}
+export interface TabsProps {
+    /** Focus target for the tab bar. */
+    focusId: string;
+    /** Array of tab definitions. */
+    tabs: Tab[];
+    /** Controlled: currently active tab id. */
+    activeTab?: string;
+    /** Controlled: called when active tab changes. */
+    onChange?: (id: string) => void;
+    /** Uncontrolled: initial active tab id (defaults to first tab). */
+    defaultActiveTab?: string;
+    /**
+     * Optional persistence instance. When provided, the active tab is
+     * automatically saved and restored across sessions.
+     */
+    storage?: StorageAPI;
+    /**
+     * Storage key used for persistence. Defaults to `"tabs:<focusId>"` when
+     * not provided.
+     */
+    storageKey?: string;
+}

package/dist/components/tabs/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/text/TextInput.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import type { TextInputProps, UncontrolledTextInputProps } from './types.js';
+/**
+ * Controlled text input component integrated with the keyboard focus system.
+ *
+ * Supports:
+ * - Arrow keys to move cursor
+ * - Backspace/Delete to remove characters
+ * - Regular character input (via wildcard '*')
+ * - Optional mask (password mode)
+ * - Paste highlighting (highlight the whole pasted block)
+ * - Placeholder
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = useState('');
+ * <TextInput
+ *   focusId="name-field"
+ *   value={name}
+ *   onChange={setName}
+ *   placeholder="Enter your name"
+ *   showCursor
+ * />
+ * ```
+ */
+export declare function TextInput({ placeholder, mask, showCursor, highlightPastedText, value: originalValue, onChange, onSubmit, focusId, }: TextInputProps): React.FunctionComponentElement<import("ink").TextProps>;
+/**
+ * Uncontrolled text input component that manages its own internal state.
+ *
+ * @example
+ * ```tsx
+ * <UncontrolledTextInput
+ *   focusId="search"
+ *   initialValue="default"
+ *   onSubmit={(val) => console.log(val)}
+ * />
+ * ```
+ */
+export declare function UncontrolledTextInput({ initialValue, storage, storageKey, ...props }: UncontrolledTextInputProps): React.FunctionComponentElement<TextInputProps>;

package/dist/components/text/TextInput.js

@@ -0,0 +1,233 @@
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import { Text } from 'ink';
+import chalk from 'chalk';
+import { useKeyboard, useFocusState } from '../../keyboard/index.js';
+/**
+ * 将给定字符重复多次
+ */
+function repeatChar(char, count) {
+    return Array(count + 1).join(char);
+}
+/**
+ * 计算光标在可见字符串中的偏移量，并生成带高亮（反色）的渲染结果
+ */
+function renderWithCursor(value, placeholder, mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText) {
+    // 显示用的值：如果设置了掩码则每个字符替换为掩码字符
+    const displayValue = mask ? repeatChar(mask, value.length) : value;
+    // 未聚焦或不需要显示光标 → 直接返回纯文本（空时显示占位符）
+    if (!showCursor || !isFocused) {
+        if (displayValue.length === 0 && placeholder) {
+            return chalk.grey(placeholder);
+        }
+        return displayValue;
+    }
+    // 聚焦且显示光标时的处理
+    // 空值 + 有占位符 → 占位符第一个字符反色，其余灰色
+    if (displayValue.length === 0 && placeholder) {
+        if (placeholder.length === 0)
+            return chalk.inverse(' ');
+        return chalk.inverse(placeholder[0]) + chalk.grey(placeholder.slice(1));
+    }
+    // 实际高亮宽度（粘贴高亮时可能大于1）
+    const actualHighlightWidth = highlightPastedText ? cursorWidth : 0;
+    let result = '';
+    for (let i = 0; i < displayValue.length; i++) {
+        const isInHighlight = highlightPastedText
+            ? i >= cursorOffset - actualHighlightWidth && i < cursorOffset
+            : i >= cursorOffset - actualHighlightWidth && i <= cursorOffset;
+        result += isInHighlight ? chalk.inverse(displayValue[i]) : displayValue[i];
+    }
+    // 光标在末尾时追加一个反色空格
+    if (cursorOffset === displayValue.length) {
+        result += chalk.inverse(' ');
+    }
+    return result;
+}
+/**
+ * Controlled text input component integrated with the keyboard focus system.
+ *
+ * Supports:
+ * - Arrow keys to move cursor
+ * - Backspace/Delete to remove characters
+ * - Regular character input (via wildcard '*')
+ * - Optional mask (password mode)
+ * - Paste highlighting (highlight the whole pasted block)
+ * - Placeholder
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = useState('');
+ * <TextInput
+ *   focusId="name-field"
+ *   value={name}
+ *   onChange={setName}
+ *   placeholder="Enter your name"
+ *   showCursor
+ * />
+ * ```
+ */
+export function TextInput({ placeholder = '', mask, showCursor = true, highlightPastedText = false, value: originalValue, onChange, onSubmit, focusId, }) {
+    const isFocused = useFocusState(focusId);
+    const { boundKeyboard, focusUnregister, enableWildcardPriority } = useKeyboard();
+    // 光标位置（字符索引）
+    const [cursorOffset, setCursorOffset] = useState(originalValue.length);
+    // 粘贴高亮宽度（一次插入的字符数）
+    const [cursorWidth, setCursorWidth] = useState(0);
+    // 通配符优先模式的 disable 函数
+    const disablePriorityRef = useRef(null);
+    // 当外部 value 缩短时，修正光标位置避免越界
+    useEffect(() => {
+        setCursorOffset((prev) => Math.min(prev, originalValue.length));
+    }, [originalValue]);
+    /**
+     * 移动光标（左右箭头调用）
+     */
+    const moveCursor = useCallback((delta) => {
+        if (!showCursor)
+            return;
+        setCursorOffset((prev) => {
+            const next = prev + delta;
+            if (next < 0)
+                return 0;
+            if (next > originalValue.length)
+                return originalValue.length;
+            return next;
+        });
+        // 光标移动后清除粘贴高亮
+        setCursorWidth(0);
+    }, [showCursor, originalValue.length]);
+    /**
+     * 插入文本或删除字符
+     * @param insertion 要插入的字符串，undefined 表示执行删除操作
+     * @param isForwardDelete true 表示 Delete（删光标右侧），false/undefined 表示 Backspace（删光标左侧）
+     */
+    const modifyText = useCallback((insertion, isForwardDelete = false) => {
+        let newValue = originalValue;
+        let newOffset = cursorOffset;
+        if (insertion === undefined) {
+            // 删除操作
+            if (isForwardDelete && cursorOffset < originalValue.length) {
+                // Delete：删除光标右侧一个字符
+                newValue =
+                    originalValue.slice(0, cursorOffset) +
+                        originalValue.slice(cursorOffset + 1);
+                // 光标位置不变
+            }
+            else if (!isForwardDelete && cursorOffset > 0) {
+                // Backspace：删除光标左侧一个字符
+                newValue =
+                    originalValue.slice(0, cursorOffset - 1) +
+                        originalValue.slice(cursorOffset);
+                newOffset = cursorOffset - 1;
+            }
+            else {
+                return;
+            }
+        }
+        else {
+            // 插入
+            newValue =
+                originalValue.slice(0, cursorOffset) +
+                    insertion +
+                    originalValue.slice(cursorOffset);
+            newOffset = cursorOffset + insertion.length;
+        }
+        // 边界保护
+        newOffset = Math.max(0, Math.min(newOffset, newValue.length));
+        setCursorOffset(newOffset);
+        // 如果一次插入了多个字符且开启高亮，记录高亮宽度
+        if (insertion && insertion.length > 1 && highlightPastedText) {
+            setCursorWidth(insertion.length);
+        }
+        else {
+            setCursorWidth(0);
+        }
+        if (newValue !== originalValue) {
+            onChange(newValue);
+        }
+    }, [originalValue, cursorOffset, onChange, highlightPastedText]);
+    // 焦点目标生命周期 — focusId 变化时注销旧的，新的由绑定 effect 创建
+    useEffect(() => {
+        return () => focusUnregister(focusId);
+    }, [focusId]);
+    // 注册键盘绑定（仅在获得焦点时生效）
+    useEffect(() => {
+        const fid = focusId;
+        const unbindList = [];
+        // 开启通配符最高优先级，确保所有普通字符输入优先被 TextInput 捕获
+        disablePriorityRef.current?.();
+        const disablePriority = enableWildcardPriority();
+        disablePriorityRef.current = disablePriority;
+        // 左右移动光标
+        unbindList.push(boundKeyboard(['left'], () => moveCursor(-1), { focusId: fid }));
+        unbindList.push(boundKeyboard(['right'], () => moveCursor(1), { focusId: fid }));
+        // 退格 / 删除
+        unbindList.push(boundKeyboard(['backspace'], () => modifyText(), { focusId: fid }));
+        unbindList.push(boundKeyboard(['delete'], () => modifyText(undefined, true), { focusId: fid }));
+        // 回车提交 — 提交时解除通配符最高优先级
+        if (onSubmit) {
+            unbindList.push(boundKeyboard(['return'], () => {
+                // 用户提交后解除通配符优先级，恢复正常按键分发
+                disablePriority();
+                disablePriorityRef.current = null;
+                onSubmit(originalValue);
+            }, { focusId: fid }));
+        }
+        // 通配符 '*'：捕获所有普通字符输入
+        unbindList.push(boundKeyboard(['*'], (input) => modifyText(input), { focusId: fid }));
+        // 清理：解绑所有键盘回调并恢复通配符优先级
+        return () => {
+            unbindList.forEach((fn) => fn());
+            if (disablePriorityRef.current) {
+                disablePriorityRef.current();
+                disablePriorityRef.current = null;
+            }
+        };
+    }, [
+        focusId,
+        boundKeyboard,
+        moveCursor,
+        modifyText,
+        onSubmit,
+        originalValue,
+        enableWildcardPriority,
+    ]);
+    // 渲染最终显示的文本
+    const rendered = renderWithCursor(originalValue, placeholder, mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText);
+    return React.createElement(Text, null, rendered);
+}
+/**
+ * Uncontrolled text input component that manages its own internal state.
+ *
+ * @example
+ * ```tsx
+ * <UncontrolledTextInput
+ *   focusId="search"
+ *   initialValue="default"
+ *   onSubmit={(val) => console.log(val)}
+ * />
+ * ```
+ */
+export function UncontrolledTextInput({ initialValue = '', storage, storageKey, ...props }) {
+    const [value, setValue] = useState(initialValue);
+    const persistKey = storageKey ?? `text:${props.focusId}`;
+    useEffect(() => {
+        if (!storage)
+            return;
+        let cancelled = false;
+        storage.read.str(persistKey, initialValue).then((v) => {
+            if (!cancelled)
+                setValue(v);
+        });
+        return () => { cancelled = true; };
+    }, [storage, persistKey, initialValue]);
+    const handleChange = (newVal) => {
+        setValue(newVal);
+        storage?.write.str(persistKey, newVal);
+    };
+    return React.createElement(TextInput, {
+        ...props,
+        value,
+        onChange: handleChange,
+    });
+}

package/dist/components/text/types.d.ts

@@ -0,0 +1,62 @@
+import type { StorageAPI } from "../../storage/index.js";
+/**
+ * Props for the controlled TextInput component.
+ * @template T - The type of the value (typically string).
+ */
+export type TextInputProps = {
+    /**
+     * Placeholder text shown when value is empty.
+     */
+    readonly placeholder?: string;
+    /**
+     * Replace all characters with this mask string (e.g. '*' for passwords).
+     */
+    readonly mask?: string;
+    /**
+     * Whether to show a visual cursor and allow arrow key navigation.
+     * @default true
+     */
+    readonly showCursor?: boolean;
+    /**
+     * Highlight the last pasted text block (multiple characters inserted at once).
+     * @default false
+     */
+    readonly highlightPastedText?: boolean;
+    /**
+     * Current value of the input (controlled).
+     */
+    readonly value: string;
+    /**
+     * Called when the value changes.
+     */
+    readonly onChange: (value: string) => void;
+    /**
+     * Called when the Enter key is pressed.
+     */
+    readonly onSubmit?: (value: string) => void;
+    /**
+     * Focus identifier used by the keyboard system.
+     * Must be unique on the current screen.
+     */
+    readonly focusId: string;
+};
+/**
+ * Props for the uncontrolled TextInput component.
+ */
+export type UncontrolledTextInputProps = {
+    /**
+     * Initial value when the component mounts.
+     * @default ''
+     */
+    readonly initialValue?: string;
+    /**
+     * Optional persistence instance. When provided, the text value is
+     * automatically saved and restored across sessions.
+     */
+    readonly storage?: StorageAPI;
+    /**
+     * Storage key used for persistence. Defaults to `"text:<focusId>"` when
+     * not provided.
+     */
+    readonly storageKey?: string;
+} & Omit<TextInputProps, 'value' | 'onChange'>;