ink-cartridge 3.8.2 → 3.8.3

package/README.md

@@ -109,6 +109,7 @@ npx ink-cartridge init my-tui
 - [TextInput](docs/components/TextInput/TextInput-API.md)
 - [UncontrolledTextInput](docs/components/TextInput/UncontrolledTextInput-API.md)
 - [NumberInput](docs/components/NumberInput/NumberInput-API.md)
+- [SearchBar](docs/components/SearchBar/SearchBar-API.md)
 - [SearchInput](docs/components/SearchInput/SearchInput-API.md)
 - [ConfirmDialog](docs/components/ConfirmDialog/ConfirmDialog-API.md)
 - [Spinner](docs/components/Spinner/Spinner-API.md)
@@ -164,9 +165,9 @@ npx ink-cartridge init my-tui
 - [closeDevTool](docs/dev-tool/closeDevTool-API.md)
 </details>
 
-## Other
+## Examples
 
-The method `penetration` (formerly `blockedKey`) marks keys as transparent (pass-through). Renamed in v3.8.1 to eliminate the historical naming confusion.
+Runnable demos for every component. See [examples/README.md](examples/README.md) for the full list and run commands.
 
 ## License
 

package/dist/components/search-bar/SearchBar.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { SearchBarItem, SearchBarProps } from "./search-bar-types.js";
+export default function SearchBar<T, I extends SearchBarItem<T> = SearchBarItem<T>>({ focusId, width, items, onSubmit, selectBar: SelectBar, }: SearchBarProps<T, I>): React.JSX.Element;

package/dist/components/search-bar/SearchBar.js

@@ -0,0 +1,62 @@
+import { Box, Text, useWindowSize } from "ink";
+import React, { useState, useMemo, useEffect, useCallback } from "react";
+import { TextInput } from "../text/TextInput.js";
+import { useKeyboard } from "../../keyboard/hook.js";
+/**
+ * Filter and sort items by query against their labels.
+ * Priority: exact match → prefix match → earlier substring position.
+ */
+function filterAndSort(items, query) {
+    if (!query.trim())
+        return items;
+    const lower = query.toLowerCase();
+    return items
+        .filter((item) => item.label.toLowerCase().includes(lower))
+        .sort((a, b) => {
+        const aLower = a.label.toLowerCase();
+        const bLower = b.label.toLowerCase();
+        if (aLower === lower && bLower !== lower)
+            return -1;
+        if (aLower !== lower && bLower === lower)
+            return 1;
+        const aStarts = aLower.startsWith(lower);
+        const bStarts = bLower.startsWith(lower);
+        if (aStarts && !bStarts)
+            return -1;
+        if (!aStarts && bStarts)
+            return 1;
+        return aLower.indexOf(lower) - bLower.indexOf(lower);
+    });
+}
+export default function SearchBar({ focusId, width, items = [], onSubmit, selectBar: SelectBar, }) {
+    const [value, setValue] = useState("");
+    const { columns } = useWindowSize();
+    const { focusSet, boundKeyboard } = useKeyboard();
+    const inputWidth = width ?? Math.max(1, columns - 4);
+    const resultsFocusId = `${focusId}-results`;
+    // Filter and sort results whenever the query or items change.
+    const results = useMemo(() => filterAndSort(items, value), [items, value]);
+    /**
+     * When selectBar confirms a selection, fire onSubmit and return
+     * focus to the TextInput.
+     */
+    const handleSelect = useCallback((item) => {
+        onSubmit?.(item);
+        focusSet(focusId);
+    }, [onSubmit, focusSet, focusId]);
+    // Enter in TextInput switches focus to the selectBar.
+    // Registered at screen level so it fires after TextInput's focus-level
+    // bindings (TextInput does not bind 'return' when onSubmit is not passed).
+    useEffect(() => {
+        const unReturn = boundKeyboard(['return'], () => {
+            focusSet(resultsFocusId);
+        });
+        return unReturn;
+    }, [boundKeyboard, focusSet, resultsFocusId]);
+    return (React.createElement(Box, { flexDirection: "column", width: "100%", height: "100%", borderColor: "white", borderStyle: "bold" },
+        React.createElement(Box, { flexDirection: "row" },
+            React.createElement(Text, { bold: true }, "> "),
+            React.createElement(TextInput, { focusId: focusId, value: value, onChange: setValue, width: inputWidth })),
+        React.createElement(Text, { bold: true }, "-".repeat(inputWidth)),
+        React.createElement(SelectBar, { items: results, onSelect: handleSelect, focusId: resultsFocusId, query: value })));
+}

package/dist/components/search-bar/search-bar-types.d.ts

@@ -0,0 +1,39 @@
+import type React from "react";
+export interface SearchBarItem<T> {
+    /** Display text shown in the results list */
+    label: string;
+    /** Value returned to onSubmit when this item is selected */
+    value: T;
+    /** Optional stable key for React reconciliation */
+    Key?: string;
+}
+export interface SearchBarProps<T, I extends SearchBarItem<T> = SearchBarItem<T>> {
+    /** Focus identifier for the TextInput in the keyboard system */
+    focusId: string;
+    /**
+     * Input area width in characters. When omitted, auto-detected from
+     * terminal dimensions (columns - 4 for border + prompt).
+     */
+    width?: number;
+    /** Items to search through. Filtered and sorted by label as the user types. */
+    items?: I[];
+    /**
+     * Called when the user confirms a selection via the selectBar.
+     * Receives the selected item.
+     */
+    onSubmit?: (item: I) => void;
+    /**
+     * Component that renders the filtered results and handles selection.
+     * Receives filtered items, an onSelect callback, a focusId for keyboard
+     * integration, and the current query string.
+     *
+     * Must be a component that registers its own keyboard bindings under the
+     * given focusId (e.g. SelectInput).
+     */
+    selectBar: React.ComponentType<{
+        items: I[];
+        onSelect: (item: I) => void;
+        focusId: string;
+        query: string;
+    }>;
+}

package/dist/components/search-bar/search-bar-types.js

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

package/dist/components/search-input/SearchInput.js

@@ -3,11 +3,14 @@ import { Box, Text } from 'ink';
 import { TextInput } from '../text/TextInput.js';
 import { useKeyboard } from '../../keyboard/index.js';
 export function SearchInput({ focusId, value, onChange, placeholder, onSubmit, }) {
-    const { boundKeyboard } = useKeyboard();
+    const { boundKeyboard, focusUnregister } = useKeyboard();
     useEffect(() => {
         const unEsc = boundKeyboard(['escape'], () => onChange(''), { focusId });
-        return () => { unEsc(); };
-    }, [focusId, onChange, boundKeyboard]);
+        return () => {
+            unEsc();
+            focusUnregister(focusId);
+        };
+    }, [focusId, onChange, boundKeyboard, focusUnregister]);
     return (React.createElement(Box, null,
         React.createElement(Text, { color: "blue" }, "Search "),
         React.createElement(TextInput, { focusId: focusId, value: value, onChange: onChange, placeholder: placeholder, onSubmit: onSubmit }),

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

@@ -1,39 +1,7 @@
 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>;
+export declare function TextInput({ placeholder, mask, showCursor, highlightPastedText, value: originalValue, onChange, onSubmit, focusId, wrap, width, }: TextInputProps): React.JSX.Element;
 /**
  * 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>;
+export declare function UncontrolledTextInput({ initialValue, storage, storageKey, ...props }: UncontrolledTextInputProps): React.JSX.Element;

package/dist/components/text/TextInput.js

@@ -1,34 +1,53 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
-import { Text } from 'ink';
+import { Text, Box, useWindowSize } from 'ink';
 import chalk from 'chalk';
 import { useKeyboard, useFocusState } from '../../keyboard/index.js';
-/**
- * 将给定字符重复多次
- */
 function repeatChar(char, count) {
     return Array(count + 1).join(char);
 }
 /**
- * 计算光标在可见字符串中的偏移量，并生成带高亮（反色）的渲染结果
+ * Split text into wrapped lines at maxWidth boundaries.
  */
+function wrapLines(text, maxWidth) {
+    if (maxWidth <= 0 || text.length === 0)
+        return [''];
+    const lines = [];
+    for (let i = 0; i < text.length; i += maxWidth) {
+        lines.push(text.slice(i, i + maxWidth));
+    }
+    return lines;
+}
+/**
+ * Convert a flat cursor offset to {line, col} in wrap mode.
+ */
+function offsetToLineCol(offset, maxWidth) {
+    if (maxWidth <= 0)
+        return { line: 0, col: 0 };
+    return {
+        line: Math.floor(offset / maxWidth),
+        col: offset % maxWidth,
+    };
+}
+/**
+ * Convert {line, col} back to a flat cursor offset, clamped to [0, textLength].
+ */
+function lineColToOffset(line, col, maxWidth, textLength) {
+    const offset = line * maxWidth + col;
+    return Math.max(0, Math.min(offset, textLength));
+}
 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++) {
@@ -37,84 +56,87 @@ function renderWithCursor(value, placeholder, mask, showCursor, isFocused, curso
             : 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, }) {
+export function TextInput({ placeholder = '', mask, showCursor = true, highlightPastedText = false, value: originalValue, onChange, onSubmit, focusId, wrap = false, width, }) {
     const isFocused = useFocusState(focusId);
     const { boundKeyboard, focusUnregister, enableWildcardPriority } = useKeyboard();
-    // 光标位置（字符索引）
+    const { columns: terminalColumns } = useWindowSize();
+    // Available width: prop override or terminal width.
+    const availableWidth = Math.max(1, (width ?? terminalColumns) || 80);
+    // Virtual-scroll offset (only used when wrap=false).
+    const [scrollOffset, setScrollOffset] = useState(0);
+    // Cursor position (flat character index).
     const [cursorOffset, setCursorOffset] = useState(originalValue.length);
-    // 粘贴高亮宽度（一次插入的字符数）
+    // Paste highlight width.
     const [cursorWidth, setCursorWidth] = useState(0);
-    // 通配符优先模式的 disable 函数
+    // Wildcard priority disable function.
     const disablePriorityRef = useRef(null);
-    // 当外部 value 缩短时，修正光标位置避免越界
+    // Clamp cursor when external value shortens.
     useEffect(() => {
         setCursorOffset((prev) => Math.min(prev, originalValue.length));
     }, [originalValue]);
+    // When wrap mode changes or text is cleared externally, reset scroll.
+    const isTextEmpty = originalValue.length === 0;
+    useEffect(() => {
+        setScrollOffset(0);
+    }, [wrap, isTextEmpty]);
     /**
-     * 移动光标（左右箭头调用）
+     * Ensure the cursor is visible within the virtual-scroll window.
+     * No-op when wrap is enabled.
      */
+    const ensureVisible = useCallback((newOffset) => {
+        if (wrap)
+            return;
+        // Reserve 1 char per side for scroll indicators.
+        const visibleW = Math.max(1, availableWidth - 2);
+        const maxScroll = Math.max(0, originalValue.length - visibleW);
+        setScrollOffset((prev) => {
+            let next = prev;
+            if (newOffset < next)
+                next = newOffset;
+            if (newOffset >= next + visibleW)
+                next = newOffset - visibleW + 1;
+            return Math.max(0, Math.min(next, maxScroll));
+        });
+    }, [wrap, availableWidth, originalValue.length]);
     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;
+            const clamped = Math.max(0, Math.min(next, originalValue.length));
+            ensureVisible(clamped);
+            return clamped;
         });
-        // 光标移动后清除粘贴高亮
         setCursorWidth(0);
-    }, [showCursor, originalValue.length]);
+    }, [showCursor, originalValue.length, ensureVisible]);
     /**
-     * 插入文本或删除字符
-     * @param insertion 要插入的字符串，undefined 表示执行删除操作
-     * @param isForwardDelete true 表示 Delete（删光标右侧），false/undefined 表示 Backspace（删光标左侧）
+     * Vertical cursor movement for wrap mode.
      */
+    const moveCursorVertical = useCallback((delta) => {
+        if (!showCursor || !wrap)
+            return;
+        const { line, col } = offsetToLineCol(cursorOffset, availableWidth);
+        const targetLine = Math.max(0, line + delta);
+        const newOffset = lineColToOffset(targetLine, col, availableWidth, originalValue.length);
+        setCursorOffset(newOffset);
+        setCursorWidth(0);
+    }, [showCursor, wrap, cursorOffset, availableWidth, originalValue.length]);
     const modifyText = useCallback((insertion, isForwardDelete = false) => {
         let newValue = originalValue;
         let newOffset = cursorOffset;
         if (insertion === undefined) {
-            // 删除操作
+            // Delete.
             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);
@@ -125,17 +147,16 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
             }
         }
         else {
-            // 插入
+            // Insert.
             newValue =
                 originalValue.slice(0, cursorOffset) +
                     insertion +
                     originalValue.slice(cursorOffset);
             newOffset = cursorOffset + insertion.length;
         }
-        // 边界保护
         newOffset = Math.max(0, Math.min(newOffset, newValue.length));
         setCursorOffset(newOffset);
-        // 如果一次插入了多个字符且开启高亮，记录高亮宽度
+        ensureVisible(newOffset);
         if (insertion && insertion.length > 1 && highlightPastedText) {
             setCursorWidth(insertion.length);
         }
@@ -145,37 +166,39 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
         if (newValue !== originalValue) {
             onChange(newValue);
         }
-    }, [originalValue, cursorOffset, onChange, highlightPastedText]);
-    // 焦点目标生命周期 — focusId 变化时注销旧的，新的由绑定 effect 创建
+    }, [originalValue, cursorOffset, onChange, highlightPastedText, ensureVisible]);
+    // Focus lifecycle.
     useEffect(() => {
         return () => focusUnregister(focusId);
     }, [focusId, focusUnregister]);
-    // 注册键盘绑定（仅在获得焦点时生效）
+    // Keyboard bindings.
     useEffect(() => {
         const fid = focusId;
         const unbindList = [];
-        // 开启通配符最高优先级，确保所有普通字符输入优先被 TextInput 捕获
         disablePriorityRef.current?.();
         const disablePriority = enableWildcardPriority();
         disablePriorityRef.current = disablePriority;
-        // 左右移动光标
+        // Left/right.
         unbindList.push(boundKeyboard(['left'], () => moveCursor(-1), { focusId: fid }));
         unbindList.push(boundKeyboard(['right'], () => moveCursor(1), { focusId: fid }));
-        // 退格 / 删除
+        // Up/down (wrap mode only).
+        if (wrap) {
+            unbindList.push(boundKeyboard(['up'], () => moveCursorVertical(-1), { focusId: fid }));
+            unbindList.push(boundKeyboard(['down'], () => moveCursorVertical(1), { focusId: fid }));
+        }
+        // Backspace / Delete.
         unbindList.push(boundKeyboard(['backspace'], () => modifyText(), { focusId: fid }));
         unbindList.push(boundKeyboard(['delete'], () => modifyText(undefined, true), { focusId: fid }));
-        // 回车提交 — 提交时解除通配符最高优先级
+        // Enter — submit.
         if (onSubmit) {
             unbindList.push(boundKeyboard(['return'], () => {
-                // 用户提交后解除通配符优先级，恢复正常按键分发
                 disablePriority();
                 disablePriorityRef.current = null;
                 onSubmit(originalValue);
             }, { focusId: fid }));
         }
-        // 通配符 '*'：捕获所有普通字符输入
+        // Wildcard: capture all character input.
         unbindList.push(boundKeyboard(['*'], (input) => modifyText(input), { focusId: fid }));
-        // 清理：解绑所有键盘回调并恢复通配符优先级
         return () => {
             unbindList.forEach((fn) => fn());
             if (disablePriorityRef.current) {
@@ -187,26 +210,55 @@ export function TextInput({ placeholder = '', mask, showCursor = true, highlight
         focusId,
         boundKeyboard,
         moveCursor,
+        moveCursorVertical,
         modifyText,
         onSubmit,
         originalValue,
         enableWildcardPriority,
+        wrap,
     ]);
-    // 渲染最终显示的文本
-    const rendered = renderWithCursor(originalValue, placeholder, mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText);
-    return React.createElement(Text, null, rendered);
+    // ── Render: wrap mode ──────────────────────────────────────────
+    if (wrap) {
+        const baseLines = wrapLines(originalValue, availableWidth);
+        const displayLines = baseLines.length === 0 ? [''] : [...baseLines];
+        const { line: cursorLine, col: cursorCol } = offsetToLineCol(cursorOffset, availableWidth);
+        // When empty and placeholder is set, show placeholder on first line.
+        if (originalValue.length === 0 && placeholder) {
+            return (React.createElement(Box, { flexDirection: "column" },
+                React.createElement(Text, null, renderWithCursor('', placeholder, mask, showCursor, isFocused, 0, 0, false))));
+        }
+        // Ensure the cursor always has a line to render on,
+        // even when it sits at the exact end of the last wrapped line.
+        while (displayLines.length <= cursorLine) {
+            displayLines.push('');
+        }
+        return (React.createElement(Box, { flexDirection: "column" }, displayLines.map((line, i) => {
+            if (i === cursorLine) {
+                return (React.createElement(Text, { key: i }, renderWithCursor(line, '', mask, showCursor, isFocused, cursorCol, cursorWidth, highlightPastedText)));
+            }
+            return React.createElement(Text, { key: i }, line);
+        })));
+    }
+    // ── Render: virtual-scroll mode ────────────────────────────────
+    if (originalValue.length === 0 && placeholder) {
+        return (React.createElement(Text, null, renderWithCursor('', placeholder, mask, showCursor, isFocused, 0, 0, false)));
+    }
+    if (originalValue.length <= availableWidth) {
+        return (React.createElement(Text, null, renderWithCursor(originalValue, '', mask, showCursor, isFocused, cursorOffset, cursorWidth, highlightPastedText)));
+    }
+    // Text is wider than available width — virtual scroll.
+    const visibleW = Math.max(1, availableWidth - 2);
+    const maxScroll = Math.max(0, originalValue.length - visibleW);
+    const windowStart = Math.max(0, Math.min(scrollOffset, maxScroll));
+    const windowText = originalValue.slice(windowStart, windowStart + visibleW);
+    const localCursor = cursorOffset - windowStart;
+    const textRendered = renderWithCursor(windowText, '', mask, showCursor, isFocused, localCursor, cursorWidth, highlightPastedText);
+    const leftIndicator = windowStart > 0 ? chalk.grey('←') : '';
+    const rightIndicator = windowStart + visibleW < originalValue.length ? chalk.grey('→') : '';
+    return React.createElement(Text, null, leftIndicator + textRendered + rightIndicator);
 }
 /**
  * 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);
@@ -225,9 +277,5 @@ export function UncontrolledTextInput({ initialValue = '', storage, storageKey,
         setValue(newVal);
         storage?.write.str(persistKey, newVal);
     };
-    return React.createElement(TextInput, {
-        ...props,
-        value,
-        onChange: handleChange,
-    });
+    return (React.createElement(TextInput, { ...props, value: value, onChange: handleChange }));
 }

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

@@ -39,6 +39,17 @@ export type TextInputProps = {
      * Must be unique on the current screen.
      */
     readonly focusId: string;
+    /**
+     * When true, text wraps to the next line instead of virtual-scrolling.
+     * Up/down arrow keys navigate between wrapped lines.
+     * @default false
+     */
+    readonly wrap?: boolean;
+    /**
+     * Available width in characters. When omitted, auto-detected from
+     * terminal dimensions via useWindowSize.
+     */
+    readonly width?: number;
 };
 /**
  * Props for the uncontrolled TextInput component.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { KeyboardProvider, useKeyboard } from "./keyboard/index.js";
 export { normalizeKeyNames, isNormalCharacter } from "./keyboard/index.js";
 export type { KeyHandler, BoundKeyboardOptions, BoundKeyEntry, ScreenKeyboardLayer, KeyboardProviderProps, GlobalKeyEntry, GlobalSequenceEntry, } from "./keyboard/index.js";
 export type { PenetrationOptions, AllowModalOptions, StopOptions, LayerKind, FocusTarget, SequenceOptions, ShortcutOperationEntry, SequenceOperationEntry, ModalMissEvent, ModalMissCallback, ModalMissOptions, ResolvedGlobalKeyEntry, } from "./keyboard/index.js";
-export { useFocusState } from "./keyboard/index.js";
+export { useFocusState, useModalMissListener } from "./keyboard/index.js";
 export { SelectInput } from "./components/select/SelectInput.js";
 export type { Item } from "./components/select/types.js";
 export type { SelectInputProps } from "./components/select/types.js";
@@ -24,6 +24,8 @@ export { Badge } from "./components/badge/Badge.js";
 export { KeyHint } from "./components/key-hint/KeyHint.js";
 export { NumberInput } from "./components/number-input/NumberInput.js";
 export { SearchInput } from "./components/search-input/SearchInput.js";
+export { default as SearchBar } from "./components/search-bar/SearchBar.js";
+export type { SearchBarItem, SearchBarProps } from "./components/search-bar/search-bar-types.js";
 export { Tabs } from "./components/tabs/Tabs.js";
 export type { Tab, TabsProps } from "./components/tabs/types.js";
 export { Fold } from "./components/fold/Fold.js";

package/dist/index.js

@@ -3,7 +3,7 @@ export { registerComponent, ScenarioManagementProvider, CurrentScreen, skip, bac
 // ── Keyboard System ────────────────────────────────────────
 export { KeyboardProvider, useKeyboard } from "./keyboard/index.js";
 export { normalizeKeyNames, isNormalCharacter } from "./keyboard/index.js";
-export { useFocusState } from "./keyboard/index.js";
+export { useFocusState, useModalMissListener } from "./keyboard/index.js";
 // Components — SelectInput
 export { SelectInput } from "./components/select/SelectInput.js";
 // Components — SelectRow
@@ -28,6 +28,8 @@ export { KeyHint } from "./components/key-hint/KeyHint.js";
 export { NumberInput } from "./components/number-input/NumberInput.js";
 // Components — SearchInput
 export { SearchInput } from "./components/search-input/SearchInput.js";
+// Components — SearchBar
+export { default as SearchBar } from "./components/search-bar/SearchBar.js";
 // Components — Tabs
 export { Tabs } from "./components/tabs/Tabs.js";
 // Components — Fold

package/dist/keyboard/modal-processor/index.js

@@ -1,18 +1,24 @@
 import { handleLayer } from '../layer-handler.js';
+function passAllowedKeys(allowedKeys, blockedKeys, eventNames) {
+    return allowedKeys.some((k) => !blockedKeys.includes(k.key) && eventNames.includes(k.key));
+}
 /**
  * Check whether a key event matches any entry in the allow-list of
  * the active focus target or the layer itself.
  */
 function isAllowed(layer, eventNames) {
-    if (layer.allowedKeys.some((r) => eventNames.includes(r.key))) {
-        return true;
-    }
+    const blockedKeys = layer.allowedKeys
+        .filter((r) => r.when?.() === false)
+        .map((r) => r.key);
     if (layer.currentFocusId) {
         const ft = layer.focusTargets.get(layer.currentFocusId);
-        if (ft?.allowedKeys.some((r) => eventNames.includes(r.key))) {
+        if (ft && passAllowedKeys(ft.allowedKeys, blockedKeys, eventNames)) {
             return true;
         }
     }
+    if (passAllowedKeys(layer.allowedKeys, blockedKeys, eventNames)) {
+        return true;
+    }
     return false;
 }
 /**

package/dist/keyboard/provider.js

@@ -434,7 +434,7 @@ export function KeyboardProvider({ children }) {
         const container = options?.focusId
             ? getOrCreateFocusTarget(layer, options.focusId)
             : layer;
-        return pushKeyEntries(container, 'allowedKeys', keys, (key) => ({ key }));
+        return pushKeyEntries(container, 'allowedKeys', keys, (key) => ({ key, when: options?.when }));
     }, [getCurrentOwner, getLayer, getOrCreateFocusTarget]);
     /**
      * Bind keys on the current layer (screen or overlay).

package/dist/keyboard/types.d.ts

@@ -385,6 +385,8 @@ export interface PenetrationOptions {
 export interface AllowModalOptions {
     /** If provided, allows only within the named focus target. */
     focusId?: string;
+    /** Optional condition callback. When provided, the key is only allowed through when this returns `true`. When `false`, the allow rule is ignored and the key is blocked. */
+    when?: () => boolean;
 }
 /**
  * A single global key definition.

package/dist/screen/context.d.ts

@@ -51,6 +51,8 @@ export interface ScreenSystemContextValue {
     closeModal: CloseModalFn;
     /** Close all open modals at once. */
     closeAllModals: CloseAllModalsFn;
+    /** Whether to turn on full screen effect */
+    fullScreen?: boolean;
 }
 /**
  * React context for the screen navigation system.

package/dist/screen/current-screen.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Box } from 'ink';
+import { Box, useWindowSize } from 'ink';
 import { useScreenSystem } from './hook.js';
 import { OverlayContext } from './OverlayContext.js';
 import { ModalContext } from './ModalContext.js';
@@ -18,7 +18,8 @@ import { ModalContext } from './ModalContext.js';
  * Architecturally symmetric between overlays and modals.
  */
 export function CurrentScreen() {
-    const { currentScreen, currentOverlays, displayedOverlays, currentModals, renderedModalEntries } = useScreenSystem();
+    const { currentScreen, currentOverlays, displayedOverlays, currentModals, renderedModalEntries, fullScreen } = useScreenSystem();
+    const { rows } = useWindowSize();
     // Build overlay elements with OverlayContext wrappers
     const wrappedOverlays = currentOverlays.map((overlayNode, i) => {
         const entry = displayedOverlays[i];
@@ -34,7 +35,7 @@ export function CurrentScreen() {
             return modalNode;
         return React.createElement(ModalContext.Provider, { value: { id: entry.id, originComponent: entry.originComponent }, key: `mdl-ctx-${entry.id}` }, modalNode);
     });
-    return (React.createElement(Box, { flexDirection: 'column', width: '100%', height: '100%' },
+    return (React.createElement(Box, { flexDirection: 'column', width: '100%', height: fullScreen ? rows : '100%' },
         currentScreen,
         wrappedOverlays.map((w) => w),
         wrappedModals.map((w) => w)));

package/dist/screen/provider.d.ts

@@ -111,6 +111,7 @@ export interface ScenarioManagementProviderProps {
     defaultScreen: React.ComponentType<any>;
     /** 默认参数（可选，未传则使用注册时的模板参数） */
     defaultParams?: Record<string, unknown>;
+    fullScreen?: boolean;
 }
 /**
  * Screen-management context provider.
@@ -118,4 +119,4 @@ export interface ScenarioManagementProviderProps {
  * Wraps the application and enables tree-based screen navigation, overlays,
  * and module-level navigation functions.
  */
-export declare function ScenarioManagementProvider({ children, defaultScreen, defaultParams, }: ScenarioManagementProviderProps): React.JSX.Element;
+export declare function ScenarioManagementProvider({ children, defaultScreen, defaultParams, fullScreen }: ScenarioManagementProviderProps): React.JSX.Element;

package/dist/screen/provider.js

@@ -483,7 +483,7 @@ function screenReducer(state, action) {
  * Wraps the application and enables tree-based screen navigation, overlays,
  * and module-level navigation functions.
  */
-export function ScenarioManagementProvider({ children, defaultScreen, defaultParams, }) {
+export function ScenarioManagementProvider({ children, defaultScreen, defaultParams, fullScreen }) {
     if (!hasComponent(defaultScreen)) {
         throw new Error(`[Ink-Cartridge] defaultScreen "${defaultScreen.displayName || defaultScreen.name || 'anonymous'}" is not registered. Please call registerComponent() first.`);
     }
@@ -614,6 +614,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
         openModal: openModalInContext,
         closeModal: closeModalInContext,
         closeAllModals: closeAllModalsInContext,
+        fullScreen
     }), [
         currentScreen,
         currentOverlays,
@@ -636,6 +637,7 @@ export function ScenarioManagementProvider({ children, defaultScreen, defaultPar
         closeModalInContext,
         closeAllModalsInContext,
         state.activeModalId,
+        fullScreen
     ]);
     return (React.createElement(ScreenSystemContext.Provider, { value: value }, children));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ink-cartridge",
-    "version": "3.8.2",
+    "version": "3.8.3",
     "description": "Ready-to-use Ink components and screen management system for building terminal UIs.",
     "type": "module",
     "main": "./dist/index.js",
@@ -62,7 +62,7 @@
         "eslint": "^9.39.4",
         "eslint-plugin-react": "^7.37.5",
         "eslint-plugin-react-hooks": "^7.1.1",
-        "ink": "^7.0.1",
+        "ink": "^7.1.0",
         "ink-testing-library": "^4.0.0",
         "jsdom": "^26.0.0",
         "react": "^19.2.4",