@claude-code-kit/ui 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { Color } from '@claude-code-kit/ink-renderer';
+import { Color, Styles, DOMElement, ClickEvent, FocusEvent, KeyboardEvent, ColorType } from '@claude-code-kit/ink-renderer';
 export * from '@claude-code-kit/ink-renderer';
-import React from 'react';
+import * as React from 'react';
+import React__default, { PropsWithChildren, Ref, ReactNode } from 'react';
+import { Tokens } from 'marked';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type DividerProps = {
@@ -10,22 +12,22 @@ type DividerProps = {
     padding?: number;
     title?: string;
 };
-declare function Divider({ width, color, char, padding, title }: DividerProps): React.ReactNode;
+declare function Divider({ width, color, char, padding, title }: DividerProps): React__default.ReactNode;
 
-type Props$2 = {
+type Props$b = {
     ratio: number;
     width: number;
     fillColor?: Color;
     emptyColor?: Color;
 };
-declare function ProgressBar({ ratio: inputRatio, width, fillColor, emptyColor }: Props$2): React.ReactNode;
+declare function ProgressBar({ ratio: inputRatio, width, fillColor, emptyColor }: Props$b): React__default.ReactNode;
 
 type Status = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'loading';
-type Props$1 = {
+type Props$a = {
     status: Status;
     withSpace?: boolean;
 };
-declare function StatusIcon({ status, withSpace }: Props$1): React.ReactNode;
+declare function StatusIcon({ status, withSpace }: Props$a): React__default.ReactNode;
 
 type StatusLineSegment = {
     content: string;
@@ -40,7 +42,7 @@ type StatusLineProps = {
     borderStyle?: 'none' | 'single' | 'round';
     borderColor?: Color;
 };
-declare function StatusLine({ segments, text, paddingX, gap, borderStyle, borderColor, }: StatusLineProps): React.ReactNode;
+declare function StatusLine({ segments, text, paddingX, gap, borderStyle, borderColor, }: StatusLineProps): React__default.ReactNode;
 declare function useStatusLine(updater: () => StatusLineSegment[] | string, deps: unknown[], intervalMs?: number): StatusLineSegment[] | string;
 
 type CommandResult = {
@@ -64,7 +66,7 @@ type LocalCommand = CommandBase & {
 };
 type JSXCommand = CommandBase & {
     type: 'jsx';
-    render: (onDone: CommandOnDone, args: string) => React.ReactNode;
+    render: (onDone: CommandOnDone, args: string) => React__default.ReactNode;
 };
 type Command$1 = LocalCommand | JSXCommand;
 
@@ -161,8 +163,8 @@ declare function useKeybindings(handlers: Record<string, () => void | false | Pr
  * ~/.claude/keybindings.json, with hot-reload support when the file changes.
  */
 
-type Props = {
-    children: React.ReactNode;
+type Props$9 = {
+    children: React__default.ReactNode;
     /** Optional callback invoked when keybinding warnings are present */
     onWarnings?: (message: string, isError: boolean) => void;
 };
@@ -184,10 +186,18 @@ type Props = {
  * - User bindings override defaults (later entries win)
  * - Chord support with automatic timeout
  */
-declare function KeybindingSetup({ children, onWarnings }: Props): React.ReactNode;
+declare function KeybindingSetup({ children, onWarnings }: Props$9): React__default.ReactNode;
 
 declare const DEFAULT_BINDINGS: KeybindingBlock[];
 
+declare function useDoublePress(setPending: (pending: boolean) => void, onDoublePress: () => void, onFirstPress?: () => void): () => void;
+
+type TerminalSize = {
+    columns: number;
+    rows: number;
+};
+declare function useTerminalSize(): TerminalSize;
+
 type Command = {
     name: string;
     description: string;
@@ -204,7 +214,7 @@ type PromptInputProps = {
     onCommandSelect?: (name: string) => void;
     history?: string[];
 };
-declare function PromptInput({ value, onChange, onSubmit, placeholder, prefix, prefixColor, disabled, commands, onCommandSelect, history, }: PromptInputProps): React.ReactNode;
+declare function PromptInput({ value, onChange, onSubmit, placeholder, prefix, prefixColor, disabled, commands, onCommandSelect, history, }: PromptInputProps): React__default.ReactNode;
 
 type SpinnerProps = {
     label?: string;
@@ -213,7 +223,46 @@ type SpinnerProps = {
     color?: string;
     showElapsed?: boolean;
 };
-declare function Spinner({ label, verb, verbs, color, showElapsed, }: SpinnerProps): React.ReactNode;
+declare function Spinner({ label, verb, verbs, color, showElapsed, }: SpinnerProps): React__default.ReactNode;
+
+type Props$8 = {
+    children: string;
+    /** When true, render all text content as dim */
+    dimColor?: boolean;
+};
+declare function Markdown(props: Props$8): React__default.ReactNode;
+type StreamingProps = {
+    children: string;
+};
+declare function StreamingMarkdown({ children, }: StreamingProps): React__default.ReactNode;
+
+/**
+ * Stub for cli-highlight. Syntax highlighting is optional — returns null
+ * when cli-highlight is not available, causing code blocks to render as
+ * plain text.
+ */
+type CliHighlight = {
+    highlight: (code: string, options?: {
+        language?: string;
+    }) => string;
+    supportsLanguage: (lang: string) => boolean;
+};
+
+type Props$7 = {
+    token: Tokens.Table;
+    highlight: CliHighlight | null;
+    /** Override terminal width (useful for testing) */
+    forceWidth?: number;
+};
+/**
+ * Renders a markdown table using Ink's Box layout.
+ * Handles terminal width by:
+ * 1. Calculating minimum column widths based on longest word
+ * 2. Distributing available space proportionally
+ * 3. Wrapping text within cells (no truncation)
+ * 4. Properly aligning multi-line rows with borders
+ */
+declare function MarkdownTable({ token, highlight, forceWidth }: Props$7): React__default.ReactNode;
 
 type SelectOption<T = string> = {
     value: T;
@@ -246,9 +295,9 @@ type Message = {
 type MessageListProps = {
     messages: Message[];
     streamingContent?: string | null;
-    renderMessage?: (message: Message) => React.ReactNode;
+    renderMessage?: (message: Message) => React__default.ReactNode;
 };
-declare function MessageList({ messages, streamingContent, renderMessage, }: MessageListProps): React.ReactNode;
+declare function MessageList({ messages, streamingContent, renderMessage, }: MessageListProps): React__default.ReactNode;
 
 type StreamingTextProps = {
     text: string;
@@ -257,7 +306,7 @@ type StreamingTextProps = {
     onComplete?: () => void;
     color?: string;
 };
-declare function StreamingText({ text, speed, interval, onComplete, color, }: StreamingTextProps): React.ReactNode;
+declare function StreamingText({ text, speed, interval, onComplete, color, }: StreamingTextProps): React__default.ReactNode;
 
 type REPLCommand = {
     name: string;
@@ -276,9 +325,348 @@ type REPLProps = {
     prefix?: string;
     placeholder?: string;
     history?: string[];
-    renderMessage?: (message: Message) => React.ReactNode;
-    spinner?: React.ReactNode;
+    renderMessage?: (message: Message) => React__default.ReactNode;
+    spinner?: React__default.ReactNode;
+};
+declare function REPL({ onSubmit, onExit, messages, isLoading, streamingContent, commands, model, statusSegments, prefix, placeholder, history: externalHistory, renderMessage, spinner, }: REPLProps): React__default.ReactNode;
+
+type ThemeName = 'dark' | 'light';
+type ThemeSetting = ThemeName | 'auto';
+type Theme = {
+    text: string;
+    dimText: string;
+    border: string;
+    accent: string;
+    success: string;
+    warning: string;
+    error: string;
+    assistant: string;
+    inactive: string;
+    inverseText: string;
+    permission: string;
+};
+declare function getTheme(name: ThemeName): Theme;
+type Props$6 = {
+    children: React__default.ReactNode;
+    initialState?: ThemeSetting;
+    onThemeSave?: (setting: ThemeSetting) => void;
+};
+declare function ThemeProvider({ children, initialState, onThemeSave, }: Props$6): react_jsx_runtime.JSX.Element;
+declare function useTheme(): [ThemeName, (setting: ThemeSetting) => void];
+declare function useThemeSetting(): ThemeSetting;
+declare function usePreviewTheme(): {
+    setPreviewTheme: (setting: ThemeSetting) => void;
+    savePreview: () => void;
+    cancelPreview: () => void;
+};
+
+type ThemedColorProps = {
+    readonly borderColor?: keyof Theme | Color;
+    readonly borderTopColor?: keyof Theme | Color;
+    readonly borderBottomColor?: keyof Theme | Color;
+    readonly borderLeftColor?: keyof Theme | Color;
+    readonly borderRightColor?: keyof Theme | Color;
+    readonly backgroundColor?: keyof Theme | Color;
+};
+type BaseStylesWithoutColors = Omit<Styles, 'textWrap' | 'borderColor' | 'borderTopColor' | 'borderBottomColor' | 'borderLeftColor' | 'borderRightColor' | 'backgroundColor'>;
+type Props$5 = BaseStylesWithoutColors & ThemedColorProps & {
+    ref?: Ref<DOMElement>;
+    tabIndex?: number;
+    autoFocus?: boolean;
+    onClick?: (event: ClickEvent) => void;
+    onFocus?: (event: FocusEvent) => void;
+    onFocusCapture?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
+    onBlurCapture?: (event: FocusEvent) => void;
+    onKeyDown?: (event: KeyboardEvent) => void;
+    onKeyDownCapture?: (event: KeyboardEvent) => void;
+    onMouseEnter?: () => void;
+    onMouseLeave?: () => void;
+};
+declare function ThemedBox({ borderColor, borderTopColor, borderBottomColor, borderLeftColor, borderRightColor, backgroundColor, children, ref, ...rest }: PropsWithChildren<Props$5>): React__default.ReactNode;
+
+/** Colors uncolored ThemedText in the subtree. Precedence: explicit `color` >
+ *  this > dimColor. Crosses Box boundaries (Ink's style cascade doesn't). */
+declare const TextHoverColorContext: React__default.Context<keyof Theme | undefined>;
+type Props$4 = {
+    readonly color?: keyof Theme | Color;
+    readonly backgroundColor?: keyof Theme;
+    readonly dimColor?: boolean;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strikethrough?: boolean;
+    readonly inverse?: boolean;
+    readonly wrap?: Styles['textWrap'];
+    readonly children?: ReactNode;
+};
+declare function ThemedText({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props$4): React__default.ReactNode;
+
+type DialogProps = {
+    title: React__default.ReactNode;
+    subtitle?: React__default.ReactNode;
+    children: React__default.ReactNode;
+    onCancel: () => void;
+    color?: keyof Theme;
+    hideInputGuide?: boolean;
+    hideBorder?: boolean;
+};
+/**
+ * A dialog box with title, content, and keyboard hints.
+ * Press Esc to cancel/close.
+ */
+declare function Dialog({ title, subtitle, children, onCancel, color, hideInputGuide, hideBorder, }: DialogProps): React__default.ReactNode;
+
+type PickerAction<T> = {
+    action: string;
+    handler: (item: T) => void;
+};
+type Props$3<T> = {
+    title: string;
+    placeholder?: string;
+    initialQuery?: string;
+    items: readonly T[];
+    getKey: (item: T) => string;
+    renderItem: (item: T, isFocused: boolean) => React.ReactNode;
+    renderPreview?: (item: T) => React.ReactNode;
+    previewPosition?: 'bottom' | 'right';
+    visibleCount?: number;
+    direction?: 'down' | 'up';
+    onQueryChange: (query: string) => void;
+    onSelect: (item: T) => void;
+    onTab?: PickerAction<T>;
+    onShiftTab?: PickerAction<T>;
+    onFocus?: (item: T | undefined) => void;
+    onCancel: () => void;
+    emptyMessage?: string | ((query: string) => string);
+    matchLabel?: string;
+    selectAction?: string;
+    extraHints?: React.ReactNode;
+};
+declare function FuzzyPicker<T>({ title, placeholder, initialQuery, items, getKey, renderItem, renderPreview, previewPosition, visibleCount: requestedVisible, direction, onQueryChange, onSelect, onTab, onShiftTab, onFocus, onCancel, emptyMessage, matchLabel, selectAction, extraHints, }: Props$3<T>): React.ReactNode;
+
+type Props$2 = {
+    /** The key or chord to display (e.g., "ctrl+o", "Enter", "↑/↓") */
+    shortcut: string;
+    /** The action the key performs (e.g., "expand", "select", "navigate") */
+    action: string;
+    /** Whether to wrap the hint in parentheses. Default: false */
+    parens?: boolean;
+    /** Whether to render the shortcut in bold. Default: false */
+    bold?: boolean;
+};
+/**
+ * Renders a keyboard shortcut hint like "ctrl+o to expand" or "(tab to toggle)"
+ *
+ * Wrap in <Text dimColor> for the common dim styling.
+ *
+ * @example
+ * // Simple hint wrapped in dim Text
+ * <Text dimColor><KeyboardShortcutHint shortcut="esc" action="cancel" /></Text>
+ *
+ * // With parentheses: "(ctrl+o to expand)"
+ * <Text dimColor><KeyboardShortcutHint shortcut="ctrl+o" action="expand" parens /></Text>
+ *
+ * // With bold shortcut: "Enter to confirm" (Enter is bold)
+ * <Text dimColor><KeyboardShortcutHint shortcut="Enter" action="confirm" bold /></Text>
+ *
+ * // Multiple hints with middot separator - use Byline
+ * <Text dimColor>
+ *   <Byline>
+ *     <KeyboardShortcutHint shortcut="Enter" action="confirm" />
+ *     <KeyboardShortcutHint shortcut="Esc" action="cancel" />
+ *   </Byline>
+ * </Text>
+ */
+declare function KeyboardShortcutHint({ shortcut, action, parens, bold, }: Props$2): React__default.ReactNode;
+
+type ListItemProps = {
+    /**
+     * Whether this item is currently focused (keyboard selection).
+     * Shows the pointer indicator (❯) when true.
+     */
+    isFocused: boolean;
+    /**
+     * Whether this item is selected (chosen/checked).
+     * Shows the checkmark indicator (✓) when true.
+     * @default false
+     */
+    isSelected?: boolean;
+    /** The content to display for this item. */
+    children: ReactNode;
+    /** Optional description text displayed below the main content. */
+    description?: string;
+    /**
+     * Show a down arrow indicator instead of pointer (for scroll hints).
+     * Only applies when not focused.
+     */
+    showScrollDown?: boolean;
+    /**
+     * Show an up arrow indicator instead of pointer (for scroll hints).
+     * Only applies when not focused.
+     */
+    showScrollUp?: boolean;
+    /**
+     * Whether to apply automatic styling to the children based on focus/selection state.
+     * - When true (default): children are wrapped in Text with state-based colors
+     * - When false: children are rendered as-is, allowing custom styling
+     * @default true
+     */
+    styled?: boolean;
+    /**
+     * Whether this item is disabled. Disabled items show dimmed text and no indicators.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether this ListItem should declare the terminal cursor position.
+     * Set false when a child (e.g. BaseTextInput) declares its own cursor.
+     * @default true
+     */
+    declareCursor?: boolean;
+};
+/**
+ * A list item component for selection UIs (dropdowns, multi-selects, menus).
+ *
+ * Handles the common pattern of:
+ * - Pointer indicator (❯) for focused items
+ * - Checkmark indicator (✓) for selected items
+ * - Scroll indicators (↓↑) for truncated lists
+ * - Color states for focus/selection
+ *
+ * @example
+ * // Basic usage in a selection list
+ * {options.map((option, i) => (
+ *   <ListItem
+ *     key={option.id}
+ *     isFocused={focusIndex === i}
+ *     isSelected={selectedId === option.id}
+ *   >
+ *     {option.label}
+ *   </ListItem>
+ * ))}
+ *
+ * @example
+ * // With scroll indicators
+ * <ListItem isFocused={false} showScrollUp>First visible item</ListItem>
+ * ...
+ * <ListItem isFocused={false} showScrollDown>Last visible item</ListItem>
+ *
+ * @example
+ * // With description
+ * <ListItem isFocused isSelected={false} description="Secondary text here">
+ *   Primary text
+ * </ListItem>
+ *
+ * @example
+ * // Custom children styling (styled=false)
+ * <ListItem isFocused styled={false}>
+ *   <Text color="claude">Custom styled content</Text>
+ * </ListItem>
+ */
+declare function ListItem({ isFocused, isSelected, children, description, showScrollDown, showScrollUp, styled, disabled, declareCursor, }: ListItemProps): React__default.ReactNode;
+
+type LoadingStateProps = {
+    /** The loading message to display next to the spinner. */
+    message: string;
+    /**
+     * Display the message in bold.
+     * @default false
+     */
+    bold?: boolean;
+    /**
+     * Display the message in dimmed color.
+     * @default false
+     */
+    dimColor?: boolean;
+    /** Optional subtitle displayed below the main message. */
+    subtitle?: string;
+};
+/**
+ * A spinner with loading message for async operations.
+ *
+ * @example
+ * <LoadingState message="Loading..." />
+ *
+ * @example
+ * <LoadingState message="Loading sessions" bold subtitle="Fetching your sessions..." />
+ */
+declare function LoadingState({ message, bold, dimColor, subtitle, }: LoadingStateProps): React__default.ReactNode;
+
+type PaneProps = {
+    children: React__default.ReactNode;
+    color?: keyof Theme;
 };
-declare function REPL({ onSubmit, onExit, messages, isLoading, streamingContent, commands, model, statusSegments, prefix, placeholder, history: externalHistory, renderMessage, spinner, }: REPLProps): React.ReactNode;
+/**
+ * A pane -- a region of the terminal bounded by a colored top line with
+ * horizontal padding. Used by slash-command screens.
+ */
+declare function Pane({ children, color }: PaneProps): React__default.ReactNode;
+
+type Props$1 = {
+    children: React__default.ReactNode;
+    lock?: 'always' | 'offscreen';
+};
+declare function Ratchet({ children, lock, }: Props$1): React__default.ReactNode;
+
+type TabsProps = {
+    children: Array<React__default.ReactElement<TabProps>>;
+    title?: string;
+    color?: keyof Theme;
+    defaultTab?: string;
+    hidden?: boolean;
+    useFullWidth?: boolean;
+    selectedTab?: string;
+    onTabChange?: (tabId: string) => void;
+    banner?: React__default.ReactNode;
+    disableNavigation?: boolean;
+};
+declare function Tabs({ title, color, defaultTab, children, hidden, useFullWidth, selectedTab: controlledSelectedTab, onTabChange, banner, disableNavigation, }: TabsProps): React__default.ReactNode;
+type TabProps = {
+    title: string;
+    id?: string;
+    children: React__default.ReactNode;
+};
+declare function Tab({ title, id, children }: TabProps): React__default.ReactNode;
+declare function useTabsWidth(): number | undefined;
+
+type Props = {
+    /** The items to join with a middot separator */
+    children: React__default.ReactNode;
+};
+/**
+ * Joins children with a middot separator (" · ") for inline metadata display.
+ *
+ * Named after the publishing term "byline" - the line of metadata typically
+ * shown below a title (e.g., "John Doe · 5 min read · Mar 12").
+ *
+ * Automatically filters out null/undefined/false children and only renders
+ * separators between valid elements.
+ *
+ * @example
+ * // Basic usage: "Enter to confirm · Esc to cancel"
+ * <Text dimColor>
+ *   <Byline>
+ *     <KeyboardShortcutHint shortcut="Enter" action="confirm" />
+ *     <KeyboardShortcutHint shortcut="Esc" action="cancel" />
+ *   </Byline>
+ * </Text>
+ *
+ * @example
+ * // With conditional children: "Esc to cancel" (only one item shown)
+ * <Text dimColor>
+ *   <Byline>
+ *     {showEnter && <KeyboardShortcutHint shortcut="Enter" action="confirm" />}
+ *     <KeyboardShortcutHint shortcut="Esc" action="cancel" />
+ *   </Byline>
+ * </Text>
+ */
+declare function Byline({ children }: Props): React__default.ReactNode;
+
+/**
+ * Curried theme-aware color function. Resolves theme keys to raw color
+ * values before delegating to the ink renderer's colorize.
+ */
+declare function color(c: keyof Theme | Color | undefined, theme: ThemeName, type?: ColorType): (text: string) => string;
 
-export { type Command$1 as Command, type CommandBase, type CommandOnDone, CommandRegistry, type CommandResult, DEFAULT_BINDINGS, Divider, type JSXCommand, KeybindingSetup, type LocalCommand, type Message, MessageList, type MessageListProps, MultiSelect, type MultiSelectProps, ProgressBar, PromptInput, REPL, type REPLProps, Select, type SelectOption, type SelectProps, Spinner, StatusIcon, StatusLine, type StatusLineProps, type StatusLineSegment, StreamingText, type StreamingTextProps, clearCommand, createCommandRegistry, defineCommand, defineJSXCommand, defineLocalCommand, exitCommand, helpCommand, useKeybinding, useKeybindings, useStatusLine };
+export { Byline, type Command$1 as Command, type CommandBase, type CommandOnDone, CommandRegistry, type CommandResult, DEFAULT_BINDINGS, Dialog, Divider, FuzzyPicker, type JSXCommand, KeybindingSetup, KeyboardShortcutHint, ListItem, LoadingState, type LocalCommand, Markdown, MarkdownTable, type Message, MessageList, type MessageListProps, MultiSelect, type MultiSelectProps, Pane, ProgressBar, PromptInput, REPL, type REPLProps, Ratchet, Select, type SelectOption, type SelectProps, Spinner, StatusIcon, StatusLine, type StatusLineProps, type StatusLineSegment, StreamingMarkdown, StreamingText, type StreamingTextProps, Tab, Tabs, type TerminalSize, TextHoverColorContext, type Theme, type ThemeName, ThemeProvider, type ThemeSetting, ThemedBox, type Props$5 as ThemedBoxProps, ThemedText, type Props$4 as ThemedTextProps, clearCommand, color, createCommandRegistry, defineCommand, defineJSXCommand, defineLocalCommand, exitCommand, getTheme, helpCommand, useDoublePress, useKeybinding, useKeybindings, usePreviewTheme, useStatusLine, useTabsWidth, useTerminalSize, useTheme, useThemeSetting };