ink-prompt 0.1.8 → 0.2.0

package/README.md

@@ -1,8 +1,7 @@
 # ink-prompt
 
-A React Ink component library focused on terminal-friendly prompts. The first
-export is `MultilineInput`, an Ink component for collecting multi-line text in
-CLIs.
+A React Ink component library for creating interactive CLI prompts. Provides
+`MultilineInput` for collecting multi-line text in terminal applications.
 
 ## Installation
 
@@ -23,7 +22,6 @@ const App = () => {
       <Text>Describe your change (press Enter to submit):</Text>
       <MultilineInput
         onSubmit={(value) => console.log(value)}
-        width={80}
       />
     </Box>
   );
@@ -32,12 +30,119 @@ const App = () => {
 render(<App />);
 ```
 
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | | External control of the text value (controlled mode) |
+| `onChange` | `(value: string) => void` | | Called when text content changes |
+| `onSubmit` | `(value: string) => void` | | Called when Enter is pressed (without trailing `\`) |
+| `placeholder` | `string` | | Placeholder text shown when empty and cursor is hidden |
+| `showCursor` | `boolean` | `true` | Whether to display the cursor |
+| `width` | `number` | terminal width | Width for word wrapping (auto-resizes with terminal) |
+| `isActive` | `boolean` | `true` | Whether the input accepts keyboard events |
+| `onCursorChange` | `(offset: number) => void` | | Called when cursor position changes |
+| `cursorOverride` | `number` | | Force cursor to a specific offset |
+| `onBoundaryArrow` | `(dir) => void` | | Called when arrow key reaches a boundary |
+| `undoDebounceMs` | `number` | `200` | Milliseconds of inactivity to commit undo batch (`0` = disable) |
+| `pasteThreshold` | `number` | | Max paste length before text is replaced by a placeholder |
+| `formatPastePlaceholder` | `(id: number) => string` | | Custom placeholder display format |
+
+### Keyboard Controls
+
 `MultilineInput` supports typical editing controls:
 
-- Arrow keys for navigation
-- `Ctrl+J` or typing `\` before Enter to add a newline
-- `Ctrl+Z`/`Ctrl+Y` for undo/redo
-- Enter submits the current buffer
+- **Arrow keys** for navigation
+- `Ctrl+J` or typing `\` before **Enter** to add a newline
+- `Ctrl+Z` / `Ctrl+Y` for undo/redo
+- `Ctrl+A` / `Ctrl+E` for jump to line start/end
+- **Home** / **End** keys for line start/end
+- `Ctrl+V` to paste text or images (when `enableImagePaste` is enabled)
+- **Enter** submits the current buffer
+- **Delete** for forward delete
+
+### Paste Placeholders
+
+When pasting large amounts of text, you can use `pasteThreshold` to automatically
+replace the pasted content with a compact placeholder for cleaner display.
+
+```tsx
+<MultilineInput
+  onSubmit={(value) => console.log(value)}
+  pasteThreshold={200}            // Text >200 chars becomes a placeholder
+  formatPastePlaceholder={(id) => `[Pasted block #${id}]`}  // Optional formatter
+/>
+```
+
+**How it works:**
+- Pasted text exceeding `pasteThreshold` is replaced with a placeholder (default: `[Paste text #N]`, customizable via `formatPastePlaceholder`)
+- The full original text is preserved — `onChange` / `onSubmit` return the unmodified content
+- Placeholders are **atomic**: backspace/delete removes the entire placeholder in one action
+- Arrow keys skip over placeholders (cursor cannot land inside one)
+- Undo/redo correctly tracks placeholder state
+- Counter resets per component instance
+
+## Image Paste
+
+Image paste is opt-in through `enableImagePaste`. When enabled, `Ctrl+V`
+reads the system clipboard. Text is inserted as usual; supported images are
+inserted into the text buffer as placeholders such as `[Pasted Image #1]` and
+returned separately through `onSubmit` or `onImagesChange`.
+
+```tsx
+import React, {useState} from 'react';
+import {render, Box, Text} from 'ink';
+import {MultilineInput, type ImageRef, type PasteErrorReason} from 'ink-prompt';
+
+const App = () => {
+  const [images, setImages] = useState<ImageRef[]>([]);
+
+  return (
+    <Box flexDirection="column">
+      <Text>Prompt:</Text>
+      <MultilineInput
+        enableImagePaste
+        maxImageCount={5}
+        maxImageSizeBytes={5 * 1024 * 1024}
+        acceptedMimeTypes={['image/png', 'image/jpeg', 'image/webp', 'image/gif']}
+        images={images}
+        onImagesChange={setImages}
+        onPasteError={(reason: PasteErrorReason) => {
+          console.error(`Paste failed: ${reason}`);
+        }}
+        onSubmit={(value, submittedImages) => {
+          console.log(value);
+          console.log(submittedImages);
+        }}
+        width={80}
+      />
+    </Box>
+  );
+};
+
+render(<App />);
+```
+
+Supported image types are detected from image bytes: PNG, JPEG, WebP, and GIF.
+Clipboard access is platform-specific:
+
+- macOS: `osascript`
+- Linux X11: `xclip`
+- Linux Wayland: `wl-paste`
+- Windows: PowerShell and `System.Windows.Forms.Clipboard`
+
+Related props:
+
+- `enableImagePaste?: boolean` - enables image-aware `Ctrl+V` handling.
+- `images?: ImageRef[]` and `onImagesChange?: (images: ImageRef[]) => void` -
+  controlled image state for pasted images.
+- `onSubmit?: (value: string, images?: ImageRef[]) => void` - receives the text
+  buffer and current images.
+- `onPasteError?: (reason: PasteErrorReason) => void` - receives paste and
+  validation failures.
+- `maxImageSizeBytes?: number` - defaults to 10 MiB.
+- `maxImageCount?: number` - defaults to 10.
+- `acceptedMimeTypes?: string[]` - restricts accepted image MIME types.
 
 ## Development
 
@@ -53,6 +158,11 @@ npm run dev
 
 # Type check
 npm run type-check
+
+# Run tests
+npm test
+npm run test:watch
+npm run test:ui
 ```
 
 ## License

package/dist/components/MultilineInput/ImageSentinel.d.ts

@@ -0,0 +1,15 @@
+export declare function generateImageId(): string;
+export declare function createSentinel(id: string, displayNumber: number): string;
+export interface SentinelInfo {
+    id: string;
+    displayNumber: number;
+    start: number;
+    end: number;
+}
+export declare function parseSentinels(text: string): SentinelInfo[];
+export declare function findSentinelAt(text: string, offset: number): SentinelInfo | null;
+export declare function isInsideSentinel(text: string, offset: number): boolean;
+export declare function removeSentinel(text: string, offset: number): string;
+export declare function getPlaceholderText(displayNumber: number): string;
+export declare function getPlaceholderVisualWidth(displayNumber: number): number;
+export declare function getSentinelVisualWidthFromText(text: string, offset: number): number | null;

package/dist/components/MultilineInput/ImageSentinel.js

@@ -0,0 +1,62 @@
+import { SENTINEL_OPEN, SENTINEL_CLOSE } from './ImageTypes.js';
+export function generateImageId() {
+    return Math.random().toString(36).substring(2, 10) + Math.random().toString(36).substring(2, 6);
+}
+export function createSentinel(id, displayNumber) {
+    return `${SENTINEL_OPEN}${id}:${displayNumber}${SENTINEL_CLOSE}`;
+}
+export function parseSentinels(text) {
+    const result = [];
+    let i = 0;
+    while (i < text.length) {
+        const openIdx = text.indexOf(SENTINEL_OPEN, i);
+        if (openIdx === -1)
+            break;
+        const closeIdx = text.indexOf(SENTINEL_CLOSE, openIdx + 1);
+        if (closeIdx === -1)
+            break;
+        const raw = text.substring(openIdx + 1, closeIdx);
+        const colonIdx = raw.lastIndexOf(':');
+        const id = colonIdx >= 0 ? raw.substring(0, colonIdx) : raw;
+        const displayNumber = colonIdx >= 0 ? parseInt(raw.substring(colonIdx + 1), 10) || 1 : 1;
+        result.push({ id, displayNumber, start: openIdx, end: closeIdx + 1 });
+        i = closeIdx + 1;
+    }
+    return result;
+}
+export function findSentinelAt(text, offset) {
+    const sentinels = parseSentinels(text);
+    for (const s of sentinels) {
+        if (offset >= s.start && offset <= s.end) {
+            return s;
+        }
+    }
+    return null;
+}
+export function isInsideSentinel(text, offset) {
+    const sentinels = parseSentinels(text);
+    for (const s of sentinels) {
+        if (offset >= s.start && offset < s.end) {
+            return true;
+        }
+    }
+    return false;
+}
+export function removeSentinel(text, offset) {
+    const sentinel = findSentinelAt(text, offset);
+    if (!sentinel)
+        return text;
+    return text.slice(0, sentinel.start) + text.slice(sentinel.end);
+}
+export function getPlaceholderText(displayNumber) {
+    return `[Pasted Image #${displayNumber}]`;
+}
+export function getPlaceholderVisualWidth(displayNumber) {
+    return getPlaceholderText(displayNumber).length;
+}
+export function getSentinelVisualWidthFromText(text, offset) {
+    const s = findSentinelAt(text, offset);
+    if (!s)
+        return null;
+    return getPlaceholderVisualWidth(s.displayNumber);
+}

package/dist/components/MultilineInput/ImageTypes.d.ts

@@ -0,0 +1,10 @@
+export interface ImageRef {
+    id: string;
+    data: string;
+    mimeType: string;
+    byteSize: number;
+    displayNumber: number;
+}
+export type PasteErrorReason = 'clipboard-timeout' | 'clipboard-read-error' | 'clipboard-unsupported-type' | 'image-too-large' | 'too-many-images' | 'clipboard-empty';
+export declare const SENTINEL_OPEN = "\uE000";
+export declare const SENTINEL_CLOSE = "\uE001";

package/dist/components/MultilineInput/ImageTypes.js

@@ -0,0 +1,2 @@
+export const SENTINEL_OPEN = '\uE000';
+export const SENTINEL_CLOSE = '\uE001';

package/dist/components/MultilineInput/ImageValidator.d.ts

@@ -0,0 +1,7 @@
+import type { ImageRef } from './ImageTypes.js';
+export interface ValidateImageOptions {
+    maxImageSizeBytes?: number;
+    maxImageCount?: number;
+    acceptedMimeTypes?: string[];
+}
+export declare function validateImage(bytes: Buffer, existingImages: ImageRef[], options: ValidateImageOptions): ImageRef;

package/dist/components/MultilineInput/ImageValidator.js

@@ -0,0 +1,50 @@
+import { generateImageId } from './ImageSentinel.js';
+const MAGIC_BYTES = [
+    { mimeType: 'image/png', magic: [0x89, 0x50, 0x4e, 0x47] },
+    { mimeType: 'image/jpeg', magic: [0xff, 0xd8, 0xff] },
+    { mimeType: 'image/webp', magic: [0x52, 0x49, 0x46, 0x46] },
+    { mimeType: 'image/gif', magic: [0x47, 0x49, 0x46, 0x38] },
+];
+function detectMimeType(bytes) {
+    for (const { mimeType, magic } of MAGIC_BYTES) {
+        if (magic.every((b, i) => bytes[i] === b)) {
+            // WebP requires additional check for WEBP header at offset 8
+            if (mimeType === 'image/webp') {
+                if (bytes.length >= 12 &&
+                    bytes[8] === 0x57 && bytes[9] === 0x45 &&
+                    bytes[10] === 0x42 && bytes[11] === 0x50) {
+                    return mimeType;
+                }
+                continue;
+            }
+            return mimeType;
+        }
+    }
+    return null;
+}
+export function validateImage(bytes, existingImages, options) {
+    const maxSize = options.maxImageSizeBytes ?? 10 * 1024 * 1024;
+    const maxCount = options.maxImageCount ?? 10;
+    if (bytes.length > maxSize) {
+        throw new Error('image-too-large');
+    }
+    if (existingImages.length >= maxCount) {
+        throw new Error('too-many-images');
+    }
+    const mimeType = detectMimeType(bytes);
+    if (!mimeType) {
+        throw new Error('clipboard-unsupported-type');
+    }
+    if (options.acceptedMimeTypes && !options.acceptedMimeTypes.includes(mimeType)) {
+        throw new Error('clipboard-unsupported-type');
+    }
+    const maxDisplayNumber = existingImages.reduce((max, img) => Math.max(max, img.displayNumber), 0);
+    const displayNumber = maxDisplayNumber + 1;
+    return {
+        id: generateImageId(),
+        data: bytes.toString('base64'),
+        mimeType,
+        byteSize: bytes.length,
+        displayNumber,
+    };
+}

package/dist/components/MultilineInput/KeyHandler.d.ts

@@ -1,8 +1,9 @@
 import { type Key, type Buffer, type Cursor } from './types.js';
 import { type UseTextInputResult } from './useTextInput.js';
-export interface KeyHandlerActions extends Omit<UseTextInputResult, 'value' | 'cursor' | 'cursorOffset' | 'setCursorOffset'> {
+export interface KeyHandlerActions extends Omit<UseTextInputResult, 'value' | 'cursor' | 'cursorOffset' | 'setCursorOffset' | 'buffer' | 'placeholderState' | 'insertImage' | 'images' | 'getImages' | 'setImages'> {
     submit: () => void;
     onBoundaryArrow?: (direction: 'up' | 'down' | 'left' | 'right') => void;
+    paste?: () => void;
 }
 /**
  * Handles keyboard input and maps it to text input actions.

package/dist/components/MultilineInput/KeyHandler.js

@@ -192,8 +192,12 @@ export function handleKey(key, input, buffer, actions, cursor, rawInput, width)
         actions.moveCursor('lineEnd');
         return;
     }
-    // History
+    // Paste / History
     if (key.ctrl) {
+        if (input === 'v' && actions.paste) {
+            actions.paste();
+            return;
+        }
         if (input === 'z') {
             actions.undo();
             return;

package/dist/components/MultilineInput/Placeholder.d.ts

@@ -0,0 +1,30 @@
+import type { PlaceholderInfo, PlaceholderState } from './types.js';
+export declare const MARKER_REGEX: RegExp;
+export declare function createMarker(id: number): string;
+export declare function createPlaceholderState(): PlaceholderState;
+export declare function addPlaceholder(state: PlaceholderState, originalText: string, displayText: string): {
+    id: number;
+    marker: string;
+    state: PlaceholderState;
+};
+export declare function removePlaceholder(state: PlaceholderState, id: number): PlaceholderState;
+export declare function getDisplayLine(line: string, placeholders: Map<number, PlaceholderInfo>): string;
+export declare function getValue(lines: string[], placeholders: Map<number, PlaceholderInfo>): string;
+export interface MarkerRange {
+    id: number;
+    start: number;
+    end: number;
+}
+export declare function findPlaceholderAt(line: string, column: number): MarkerRange | null;
+export declare function findPlaceholderAfter(line: string, column: number): MarkerRange | null;
+export declare function findPlaceholderBefore(line: string, column: number): MarkerRange | null;
+export declare function bufferColToDisplayCol(line: string, column: number, placeholders: Map<number, PlaceholderInfo>): number;
+export declare function displayColToBufferCol(line: string, displayColumn: number, placeholders: Map<number, PlaceholderInfo>): number;
+export declare function getValueCursorOffset(lines: string[], cursor: {
+    line: number;
+    column: number;
+}, placeholders: Map<number, PlaceholderInfo>): number;
+export declare function getCursorFromValueOffset(lines: string[], offset: number, placeholders: Map<number, PlaceholderInfo>): {
+    line: number;
+    column: number;
+};

package/dist/components/MultilineInput/Placeholder.js

@@ -0,0 +1,200 @@
+export const MARKER_REGEX = /\x00P(\d+)\x00/g;
+export function createMarker(id) {
+    return `\x00P${id}\x00`;
+}
+export function createPlaceholderState() {
+    return { placeholders: new Map(), nextId: 0 };
+}
+export function addPlaceholder(state, originalText, displayText) {
+    const id = state.nextId;
+    const marker = createMarker(id);
+    const newPlaceholders = new Map(state.placeholders);
+    newPlaceholders.set(id, { id, originalText, displayText });
+    return { id, marker, state: { placeholders: newPlaceholders, nextId: id + 1 } };
+}
+export function removePlaceholder(state, id) {
+    const newPlaceholders = new Map(state.placeholders);
+    newPlaceholders.delete(id);
+    return { ...state, placeholders: newPlaceholders };
+}
+export function getDisplayLine(line, placeholders) {
+    return line.replace(MARKER_REGEX, (_, idStr) => {
+        const info = placeholders.get(Number(idStr));
+        return info ? info.displayText : '';
+    });
+}
+export function getValue(lines, placeholders) {
+    const text = lines.join('\n');
+    return text.replace(MARKER_REGEX, (_, idStr) => {
+        const info = placeholders.get(Number(idStr));
+        return info ? info.originalText : '';
+    });
+}
+export function findPlaceholderAt(line, column) {
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const start = match.index;
+        const end = start + match[0].length;
+        if (column > start && column < end) {
+            return { id: Number(match[1]), start, end };
+        }
+    }
+    return null;
+}
+export function findPlaceholderAfter(line, column) {
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        if (match.index === column) {
+            return { id: Number(match[1]), start: match.index, end: match.index + match[0].length };
+        }
+    }
+    return null;
+}
+export function findPlaceholderBefore(line, column) {
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const end = match.index + match[0].length;
+        if (end === column) {
+            return { id: Number(match[1]), start: match.index, end };
+        }
+    }
+    return null;
+}
+export function bufferColToDisplayCol(line, column, placeholders) {
+    if (!placeholders || placeholders.size === 0)
+        return column;
+    let displayCol = 0;
+    let lastEnd = 0;
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const markerStart = match.index;
+        const markerEnd = markerStart + match[0].length;
+        if (column <= markerStart) {
+            return displayCol + (column - lastEnd);
+        }
+        displayCol += markerStart - lastEnd;
+        const info = placeholders.get(Number(match[1]));
+        const displayLen = info ? info.displayText.length : 0;
+        if (column <= markerEnd) {
+            return displayCol + displayLen;
+        }
+        displayCol += displayLen;
+        lastEnd = markerEnd;
+    }
+    return displayCol + (column - lastEnd);
+}
+export function displayColToBufferCol(line, displayColumn, placeholders) {
+    if (!placeholders || placeholders.size === 0)
+        return displayColumn;
+    let bufPos = 0;
+    let dispPos = 0;
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const markerStart = match.index;
+        const markerEnd = markerStart + match[0].length;
+        const textLen = markerStart - bufPos;
+        if (displayColumn <= dispPos + textLen) {
+            return bufPos + (displayColumn - dispPos);
+        }
+        dispPos += textLen;
+        bufPos = markerStart;
+        const info = placeholders.get(Number(match[1]));
+        const displayLen = info ? info.displayText.length : 0;
+        if (displayColumn <= dispPos + displayLen) {
+            return markerEnd;
+        }
+        dispPos += displayLen;
+        bufPos = markerEnd;
+    }
+    return bufPos + (displayColumn - dispPos);
+}
+export function getValueCursorOffset(lines, cursor, placeholders) {
+    let offset = 0;
+    for (let i = 0; i < cursor.line; i++) {
+        offset += getExpandedLineLength(lines[i], placeholders) + 1;
+    }
+    const line = lines[cursor.line];
+    let bufPos = 0;
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const markerStart = match.index;
+        const markerEnd = markerStart + match[0].length;
+        if (cursor.column <= markerStart) {
+            offset += cursor.column - bufPos;
+            return offset;
+        }
+        offset += markerStart - bufPos;
+        const info = placeholders.get(Number(match[1]));
+        offset += info ? info.originalText.length : 0;
+        bufPos = markerEnd;
+        if (cursor.column <= markerEnd) {
+            return offset;
+        }
+    }
+    offset += cursor.column - bufPos;
+    return offset;
+}
+export function getCursorFromValueOffset(lines, offset, placeholders) {
+    let currentOffset = 0;
+    const lineCount = lines.length;
+    for (let i = 0; i < lineCount; i++) {
+        const lineLen = getExpandedLineLength(lines[i], placeholders);
+        if (i === lineCount - 1) {
+            if (offset <= currentOffset + lineLen) {
+                const colInExpanded = offset - currentOffset;
+                return { line: i, column: valueOffsetToBufferColumn(lines[i], colInExpanded, placeholders) };
+            }
+            return { line: i, column: lines[i].length };
+        }
+        if (offset <= currentOffset + lineLen) {
+            const colInExpanded = offset - currentOffset;
+            return { line: i, column: valueOffsetToBufferColumn(lines[i], colInExpanded, placeholders) };
+        }
+        currentOffset += lineLen + 1;
+    }
+    const lastIdx = lines.length - 1;
+    return { line: lastIdx, column: lines[lastIdx].length };
+}
+function getExpandedLineLength(line, placeholders) {
+    let len = 0;
+    let lastEnd = 0;
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        len += match.index - lastEnd;
+        const info = placeholders.get(Number(match[1]));
+        len += info ? info.originalText.length : 0;
+        lastEnd = match.index + match[0].length;
+    }
+    len += line.length - lastEnd;
+    return len;
+}
+function valueOffsetToBufferColumn(line, offsetInExpanded, placeholders) {
+    let bufPos = 0;
+    let expandedPos = 0;
+    MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MARKER_REGEX.exec(line)) !== null) {
+        const markerStart = match.index;
+        const textLen = markerStart - bufPos;
+        if (offsetInExpanded <= expandedPos + textLen) {
+            return bufPos + (offsetInExpanded - expandedPos);
+        }
+        expandedPos += textLen;
+        bufPos = markerStart;
+        const info = placeholders.get(Number(match[1]));
+        const originalLen = info ? info.originalText.length : 0;
+        if (offsetInExpanded <= expandedPos + originalLen) {
+            return markerStart + match[0].length;
+        }
+        expandedPos += originalLen;
+        bufPos = markerStart + match[0].length;
+    }
+    return bufPos + (offsetInExpanded - expandedPos);
+}

package/dist/components/MultilineInput/TextBuffer.d.ts

@@ -45,6 +45,8 @@ interface VisualRowInfo {
  * Break a line into visual rows using word-aware wrapping.
  * Words are kept intact when possible, breaking at spaces.
  * Long words that exceed width are hard-wrapped.
+ * Sentinel blocks are atomic: never split, and occupy visual width
+ * equal to their placeholder text length.
  */
 export declare function getVisualRows(line: string, width: number): VisualRowInfo[];
 /**