@termuijs/ui 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Widget } from '@termuijs/widgets';
 export { Box, Gauge, List, LogView, ProgressBar, Sparkline, Spinner, StatusIndicator, Table, Text, TextInput, Widget } from '@termuijs/widgets';
-import { Style, Screen } from '@termuijs/core';
+import { Style, Screen, KeyEvent } from '@termuijs/core';
 
 interface DividerOptions {
     char?: string;
@@ -282,4 +282,279 @@ declare class CommandPalette extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
-export { type Command, CommandPalette, type CommandPaletteOptions, ConfirmDialog, type ConfirmDialogOptions, Divider, type DividerOptions, Form, type FormField, type FormOptions, Modal, type ModalOptions, MultiSelect, type MultiSelectOption, type MultiSelectOptions, Select, type SelectOption, type SelectOptions, Spacer, type Tab, Tabs, type TabsOptions, Toast, type ToastMessage, type ToastOptions, type ToastType, Tree, type TreeNode, type TreeOptions };
+declare class NonInteractiveError extends Error {
+    constructor();
+}
+interface TextPromptOptions {
+    message: string;
+    placeholder?: string;
+    validate?: (value: string) => string | null;
+    default?: string;
+}
+interface ConfirmPromptOptions {
+    message: string;
+    default?: boolean;
+}
+interface SelectPromptOptions<T = string> {
+    message: string;
+    options: Array<{
+        label: string;
+        value: T;
+    }>;
+    default?: T;
+}
+declare function promptText(options: TextPromptOptions): Promise<string>;
+declare function promptConfirm(options: ConfirmPromptOptions): Promise<boolean>;
+declare function promptSelect<T = string>(options: SelectPromptOptions<T>): Promise<T>;
+/**
+ * Imperative prompts for CLI scripts — no widget stack required.
+ *
+ * ```ts
+ * const name = await prompt.text({ message: 'Project name:', default: 'my-app' });
+ * const ok = await prompt.confirm({ message: 'Continue?', default: true });
+ * const pkg = await prompt.select({ message: 'Package manager:', options: [
+ *     { label: 'pnpm', value: 'pnpm' },
+ *     { label: 'npm', value: 'npm' },
+ * ]});
+ * ```
+ *
+ * Throws `NonInteractiveError` when stdin is not a TTY.
+ */
+declare const prompt: {
+    readonly text: typeof promptText;
+    readonly confirm: typeof promptConfirm;
+    readonly select: typeof promptSelect;
+};
+
+interface Notification {
+    id: string;
+    message: string;
+    type: 'info' | 'success' | 'warning' | 'error';
+    durationMs?: number;
+    createdAt: number;
+}
+declare class NotificationStore {
+    private static _instance;
+    private _notifications;
+    private _subs;
+    static getInstance(): NotificationStore;
+    push(message: string, type?: Notification['type'], durationMs?: number): string;
+    dismiss(id: string): void;
+    dismissAll(): void;
+    subscribe(fn: (notifications: Notification[]) => void): () => void;
+    get notifications(): Notification[];
+    private _emit;
+}
+/** Global singleton accessor */
+declare const notifications: NotificationStore;
+declare function useNotifications(): {
+    notifications: Notification[];
+    push: (message: string, type?: Notification['type'], durationMs?: number) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+};
+interface NotificationCenterOptions {
+    position?: 'top-right' | 'bottom-right' | 'top-left' | 'bottom-left';
+    maxVisible?: number;
+    width?: number;
+}
+declare class NotificationCenter extends Widget {
+    private _position;
+    private _maxVisible;
+    private _notifWidth;
+    private _unsub?;
+    private _current;
+    constructor(options?: NotificationCenterOptions);
+    unmount(): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface PasswordInputOptions {
+    placeholder?: string;
+    maxLength?: number;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+}
+declare class PasswordInput extends Widget {
+    private _value;
+    private _cursorPos;
+    private _placeholder;
+    private _maxLength;
+    private _showText;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    private get _maskChar();
+    constructor(style?: Partial<Style>, options?: PasswordInputOptions);
+    /** The actual (unmasked) value. */
+    get value(): string;
+    set value(v: string);
+    /** Whether the text is currently visible (unmaksed). */
+    get showText(): boolean;
+    /** Toggle visibility of the actual text (Alt+V). */
+    toggleVisibility(): void;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     *  Alt+V  — toggle visibility
+     *  Other  — standard text editing
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface NumberInputOptions {
+    placeholder?: string;
+    step?: number;
+    min?: number;
+    max?: number;
+    allowDecimal?: boolean;
+    onChange?: (value: number | null) => void;
+    onSubmit?: (value: number | null) => void;
+}
+declare class NumberInput extends Widget {
+    private _raw;
+    private _cursorPos;
+    private _placeholder;
+    private _step;
+    private _min;
+    private _max;
+    private _allowDecimal;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    constructor(style?: Partial<Style>, options?: NumberInputOptions);
+    /** The numeric value, or null if the field is empty / invalid. */
+    get numericValue(): number | null;
+    /** Raw text string (what the user typed). */
+    get rawValue(): string;
+    set rawValue(v: string);
+    private _clamp;
+    private _notify;
+    /** Accept only digits, '-' at position 0 (if min < 0), and (optionally) one '.'. */
+    private _isAllowed;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    /** Increment value by step (↑ arrow). */
+    increment(): void;
+    /** Decrement value by step (↓ arrow). */
+    decrement(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface PathInputOptions {
+    placeholder?: string;
+    maxLength?: number;
+    cwd?: string;
+    maxCompletions?: number;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+}
+/**
+ * PathInput — filesystem path input with Tab-completion.
+ *
+ * @note height must be at least (maxCompletions + 2) to show completions.
+ * Default height of 3 shows up to 1 completion. If height is insufficient,
+ * the input line is still rendered but completions are hidden.
+ */
+declare class PathInput extends Widget {
+    private _value;
+    private _cursorPos;
+    private _placeholder;
+    private _maxLength;
+    private _cwd;
+    private _maxCompletions;
+    private _completions;
+    private _completionIndex;
+    private _preCompletionValue;
+    private _showCompletions;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    constructor(style?: Partial<Style>, options?: PathInputOptions);
+    get value(): string;
+    set value(v: string);
+    get completions(): string[];
+    get isShowingCompletions(): boolean;
+    private _dismissCompletions;
+    /** Compute completions for the current value. Does NOT throw. */
+    private _computeCompletions;
+    /** Trigger tab-completion. */
+    triggerCompletion(): void;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     *  Tab   — trigger/cycle completions
+     *  Esc   — dismiss completions
+     *  Enter — submit current value
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface ShortcutBinding {
+    key: string;
+    description: string;
+    category?: string;
+}
+interface KeyboardShortcutsOptions {
+    /** Color for the key label boxes */
+    keyColor?: Style['fg'];
+    /** Color for category headings */
+    categoryColor?: Style['fg'];
+    /** Number of columns (default 2) */
+    columns?: number;
+    /** Show category headings (default true) */
+    showCategories?: boolean;
+}
+declare class KeyboardShortcuts extends Widget {
+    private _bindings;
+    private _keyColor;
+    private _categoryColor;
+    private _columns;
+    private _showCategories;
+    constructor(bindings: ShortcutBinding[], options?: KeyboardShortcutsOptions);
+    /** Replace all bindings and trigger a re-render. */
+    setBindings(bindings: ShortcutBinding[]): void;
+    /** Group bindings by category, preserving insertion order. */
+    private _groupBindings;
+    /**
+     * Render a key label in a bordered box style:
+     *   ┌─────┐
+     *   │ key │
+     *   └─────┘
+     *
+     * We fit it on one line: [ key ] — box drawing characters or ASCII fallback.
+     */
+    private _renderKeyLabel;
+    protected _renderSelf(screen: Screen): void;
+}
+
+export { type Command, CommandPalette, type CommandPaletteOptions, ConfirmDialog, type ConfirmDialogOptions, type ConfirmPromptOptions, Divider, type DividerOptions, Form, type FormField, type FormOptions, KeyboardShortcuts, type KeyboardShortcutsOptions, Modal, type ModalOptions, MultiSelect, type MultiSelectOption, type MultiSelectOptions, NonInteractiveError, type Notification, NotificationCenter, type NotificationCenterOptions, NotificationStore, NumberInput, type NumberInputOptions, PasswordInput, type PasswordInputOptions, PathInput, type PathInputOptions, Select, type SelectOption, type SelectOptions, type SelectPromptOptions, type ShortcutBinding, Spacer, type Tab, Tabs, type TabsOptions, type TextPromptOptions, Toast, type ToastMessage, type ToastOptions, type ToastType, Tree, type TreeNode, type TreeOptions, notifications, prompt, useNotifications };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Widget } from '@termuijs/widgets';
 export { Box, Gauge, List, LogView, ProgressBar, Sparkline, Spinner, StatusIndicator, Table, Text, TextInput, Widget } from '@termuijs/widgets';
-import { Style, Screen } from '@termuijs/core';
+import { Style, Screen, KeyEvent } from '@termuijs/core';
 
 interface DividerOptions {
     char?: string;
@@ -282,4 +282,279 @@ declare class CommandPalette extends Widget {
     protected _renderSelf(screen: Screen): void;
 }
 
-export { type Command, CommandPalette, type CommandPaletteOptions, ConfirmDialog, type ConfirmDialogOptions, Divider, type DividerOptions, Form, type FormField, type FormOptions, Modal, type ModalOptions, MultiSelect, type MultiSelectOption, type MultiSelectOptions, Select, type SelectOption, type SelectOptions, Spacer, type Tab, Tabs, type TabsOptions, Toast, type ToastMessage, type ToastOptions, type ToastType, Tree, type TreeNode, type TreeOptions };
+declare class NonInteractiveError extends Error {
+    constructor();
+}
+interface TextPromptOptions {
+    message: string;
+    placeholder?: string;
+    validate?: (value: string) => string | null;
+    default?: string;
+}
+interface ConfirmPromptOptions {
+    message: string;
+    default?: boolean;
+}
+interface SelectPromptOptions<T = string> {
+    message: string;
+    options: Array<{
+        label: string;
+        value: T;
+    }>;
+    default?: T;
+}
+declare function promptText(options: TextPromptOptions): Promise<string>;
+declare function promptConfirm(options: ConfirmPromptOptions): Promise<boolean>;
+declare function promptSelect<T = string>(options: SelectPromptOptions<T>): Promise<T>;
+/**
+ * Imperative prompts for CLI scripts — no widget stack required.
+ *
+ * ```ts
+ * const name = await prompt.text({ message: 'Project name:', default: 'my-app' });
+ * const ok = await prompt.confirm({ message: 'Continue?', default: true });
+ * const pkg = await prompt.select({ message: 'Package manager:', options: [
+ *     { label: 'pnpm', value: 'pnpm' },
+ *     { label: 'npm', value: 'npm' },
+ * ]});
+ * ```
+ *
+ * Throws `NonInteractiveError` when stdin is not a TTY.
+ */
+declare const prompt: {
+    readonly text: typeof promptText;
+    readonly confirm: typeof promptConfirm;
+    readonly select: typeof promptSelect;
+};
+
+interface Notification {
+    id: string;
+    message: string;
+    type: 'info' | 'success' | 'warning' | 'error';
+    durationMs?: number;
+    createdAt: number;
+}
+declare class NotificationStore {
+    private static _instance;
+    private _notifications;
+    private _subs;
+    static getInstance(): NotificationStore;
+    push(message: string, type?: Notification['type'], durationMs?: number): string;
+    dismiss(id: string): void;
+    dismissAll(): void;
+    subscribe(fn: (notifications: Notification[]) => void): () => void;
+    get notifications(): Notification[];
+    private _emit;
+}
+/** Global singleton accessor */
+declare const notifications: NotificationStore;
+declare function useNotifications(): {
+    notifications: Notification[];
+    push: (message: string, type?: Notification['type'], durationMs?: number) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+};
+interface NotificationCenterOptions {
+    position?: 'top-right' | 'bottom-right' | 'top-left' | 'bottom-left';
+    maxVisible?: number;
+    width?: number;
+}
+declare class NotificationCenter extends Widget {
+    private _position;
+    private _maxVisible;
+    private _notifWidth;
+    private _unsub?;
+    private _current;
+    constructor(options?: NotificationCenterOptions);
+    unmount(): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface PasswordInputOptions {
+    placeholder?: string;
+    maxLength?: number;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+}
+declare class PasswordInput extends Widget {
+    private _value;
+    private _cursorPos;
+    private _placeholder;
+    private _maxLength;
+    private _showText;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    private get _maskChar();
+    constructor(style?: Partial<Style>, options?: PasswordInputOptions);
+    /** The actual (unmasked) value. */
+    get value(): string;
+    set value(v: string);
+    /** Whether the text is currently visible (unmaksed). */
+    get showText(): boolean;
+    /** Toggle visibility of the actual text (Alt+V). */
+    toggleVisibility(): void;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     *  Alt+V  — toggle visibility
+     *  Other  — standard text editing
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface NumberInputOptions {
+    placeholder?: string;
+    step?: number;
+    min?: number;
+    max?: number;
+    allowDecimal?: boolean;
+    onChange?: (value: number | null) => void;
+    onSubmit?: (value: number | null) => void;
+}
+declare class NumberInput extends Widget {
+    private _raw;
+    private _cursorPos;
+    private _placeholder;
+    private _step;
+    private _min;
+    private _max;
+    private _allowDecimal;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    constructor(style?: Partial<Style>, options?: NumberInputOptions);
+    /** The numeric value, or null if the field is empty / invalid. */
+    get numericValue(): number | null;
+    /** Raw text string (what the user typed). */
+    get rawValue(): string;
+    set rawValue(v: string);
+    private _clamp;
+    private _notify;
+    /** Accept only digits, '-' at position 0 (if min < 0), and (optionally) one '.'. */
+    private _isAllowed;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    /** Increment value by step (↑ arrow). */
+    increment(): void;
+    /** Decrement value by step (↓ arrow). */
+    decrement(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface PathInputOptions {
+    placeholder?: string;
+    maxLength?: number;
+    cwd?: string;
+    maxCompletions?: number;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+}
+/**
+ * PathInput — filesystem path input with Tab-completion.
+ *
+ * @note height must be at least (maxCompletions + 2) to show completions.
+ * Default height of 3 shows up to 1 completion. If height is insufficient,
+ * the input line is still rendered but completions are hidden.
+ */
+declare class PathInput extends Widget {
+    private _value;
+    private _cursorPos;
+    private _placeholder;
+    private _maxLength;
+    private _cwd;
+    private _maxCompletions;
+    private _completions;
+    private _completionIndex;
+    private _preCompletionValue;
+    private _showCompletions;
+    private _onChange?;
+    private _onSubmit?;
+    focusable: boolean;
+    constructor(style?: Partial<Style>, options?: PathInputOptions);
+    get value(): string;
+    set value(v: string);
+    get completions(): string[];
+    get isShowingCompletions(): boolean;
+    private _dismissCompletions;
+    /** Compute completions for the current value. Does NOT throw. */
+    private _computeCompletions;
+    /** Trigger tab-completion. */
+    triggerCompletion(): void;
+    insertChar(char: string): void;
+    deleteBack(): void;
+    deleteForward(): void;
+    moveCursorLeft(): void;
+    moveCursorRight(): void;
+    moveCursorHome(): void;
+    moveCursorEnd(): void;
+    submit(): void;
+    clear(): void;
+    /**
+     * Handle key events. Call this from your input loop.
+     *  Tab   — trigger/cycle completions
+     *  Esc   — dismiss completions
+     *  Enter — submit current value
+     */
+    handleKey(event: KeyEvent): void;
+    protected _renderSelf(screen: Screen): void;
+}
+
+interface ShortcutBinding {
+    key: string;
+    description: string;
+    category?: string;
+}
+interface KeyboardShortcutsOptions {
+    /** Color for the key label boxes */
+    keyColor?: Style['fg'];
+    /** Color for category headings */
+    categoryColor?: Style['fg'];
+    /** Number of columns (default 2) */
+    columns?: number;
+    /** Show category headings (default true) */
+    showCategories?: boolean;
+}
+declare class KeyboardShortcuts extends Widget {
+    private _bindings;
+    private _keyColor;
+    private _categoryColor;
+    private _columns;
+    private _showCategories;
+    constructor(bindings: ShortcutBinding[], options?: KeyboardShortcutsOptions);
+    /** Replace all bindings and trigger a re-render. */
+    setBindings(bindings: ShortcutBinding[]): void;
+    /** Group bindings by category, preserving insertion order. */
+    private _groupBindings;
+    /**
+     * Render a key label in a bordered box style:
+     *   ┌─────┐
+     *   │ key │
+     *   └─────┘
+     *
+     * We fit it on one line: [ key ] — box drawing characters or ASCII fallback.
+     */
+    private _renderKeyLabel;
+    protected _renderSelf(screen: Screen): void;
+}
+
+export { type Command, CommandPalette, type CommandPaletteOptions, ConfirmDialog, type ConfirmDialogOptions, type ConfirmPromptOptions, Divider, type DividerOptions, Form, type FormField, type FormOptions, KeyboardShortcuts, type KeyboardShortcutsOptions, Modal, type ModalOptions, MultiSelect, type MultiSelectOption, type MultiSelectOptions, NonInteractiveError, type Notification, NotificationCenter, type NotificationCenterOptions, NotificationStore, NumberInput, type NumberInputOptions, PasswordInput, type PasswordInputOptions, PathInput, type PathInputOptions, Select, type SelectOption, type SelectOptions, type SelectPromptOptions, type ShortcutBinding, Spacer, type Tab, Tabs, type TabsOptions, type TextPromptOptions, Toast, type ToastMessage, type ToastOptions, type ToastType, Tree, type TreeNode, type TreeOptions, notifications, prompt, useNotifications };