ink-virtual-list 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 archcorsair
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 archcorsair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,213 +1,213 @@
-# ink-virtual-list
-
-A virtualized list component for [Ink](https://github.com/vadimdemedes/ink) terminal applications. Only renders visible items for optimal performance with large datasets.
-
-## Features
-
-- **Virtualized rendering** - Only renders items visible in the viewport
-- **Automatic scrolling** - Keeps selected item in view as you navigate
-- **Terminal-aware** - Responds to terminal resize events
-- **Flexible height** - Fixed height or auto-fill available terminal space
-- **Customizable indicators** - Override default overflow indicators ("▲ N more")
-- **TypeScript first** - Full type safety with generics
-- **Imperative API** - Programmatic scrolling via ref
-
-## Installation
-
-```bash
-# npm
-npm install ink-virtual-list
-
-# jsr
-npx jsr add @archcorsair/ink-virtual-list
-
-# bun
-bun add ink-virtual-list
-```
-
-## Usage
-
-### Basic Example
-
-```tsx
-import { VirtualList } from 'ink-virtual-list';
-import { Text } from 'ink';
-import { useState } from 'react';
-
-function App() {
-  const [selectedIndex, setSelectedIndex] = useState(0);
-  const items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`);
-
-  return (
-    <VirtualList
-      items={items}
-      selectedIndex={selectedIndex}
-      height={10}
-      renderItem={({ item, isSelected }) => (
-        <Text color={isSelected ? 'cyan' : 'white'}>
-          {isSelected ? '> ' : '  '}
-          {item}
-        </Text>
-      )}
-    />
-  );
-}
-```
-
-### Auto-fill Terminal Height
-
-```tsx
-<VirtualList
-  items={items}
-  height="auto"
-  reservedLines={5}  // Reserve space for header/footer
-  renderItem={({ item }) => <Text>{item}</Text>}
-/>
-```
-
-### Custom Overflow Indicators
-
-```tsx
-<VirtualList
-  items={items}
-  renderOverflowTop={(count) => <Text dimColor>↑ {count} hidden</Text>}
-  renderOverflowBottom={(count) => <Text dimColor>↓ {count} hidden</Text>}
-  renderItem={({ item }) => <Text>{item}</Text>}
-/>
-```
-
-### Imperative Scrolling
-
-```tsx
-import { useRef } from 'react';
-import type { VirtualListRef } from 'ink-virtual-list';
-
-function App() {
-  const listRef = useRef<VirtualListRef>(null);
-
-  const scrollToTop = () => {
-    listRef.current?.scrollToIndex(0, 'top');
-  };
-
-  return (
-    <VirtualList
-      ref={listRef}
-      items={items}
-      renderItem={({ item }) => <Text>{item}</Text>}
-    />
-  );
-}
-```
-
-## API
-
-### Props
-
-#### Required
-
-- **`items: T[]`** - Array of items to render
-- **`renderItem: (props: RenderItemProps<T>) => ReactNode`** - Render function for each visible item
-  - Receives: `{ item: T, index: number, isSelected: boolean }`
-
-#### Optional
-
-- **`selectedIndex?: number`** - Index of currently selected item (default: `0`)
-- **`keyExtractor?: (item: T, index: number) => string`** - Custom key extractor for list items
-- **`height?: number | "auto"`** - Fixed height in lines or `"auto"` to fill terminal (default: `10`)
-- **`reservedLines?: number`** - Lines to reserve when using `height="auto"` (default: `0`)
-- **`itemHeight?: number`** - Height of each item in lines (default: `1`)
-- **`showOverflowIndicators?: boolean`** - Show "N more" indicators (default: `true`)
-- **`renderOverflowTop?: (count: number) => ReactNode`** - Custom top overflow indicator
-- **`renderOverflowBottom?: (count: number) => ReactNode`** - Custom bottom overflow indicator
-- **`renderScrollBar?: (viewport: ViewportState) => ReactNode`** - Custom scrollbar renderer
-- **`onViewportChange?: (viewport: ViewportState) => void`** - Callback when viewport changes
-
-### Ref Methods
-
-```typescript
-interface VirtualListRef {
-  scrollToIndex: (index: number, alignment?: 'auto' | 'top' | 'center' | 'bottom') => void;
-  getViewport: () => ViewportState;
-  remeasure: () => void;
-}
-```
-
-- **`scrollToIndex(index, alignment?)`** - Scroll to bring an index into view
-  - `'auto'` (default) - Only scroll if needed
-  - `'top'` - Align item to top of viewport
-  - `'center'` - Center item in viewport
-  - `'bottom'` - Align item to bottom of viewport
-- **`getViewport()`** - Get current viewport state (`{ offset, visibleCount, totalCount }`)
-- **`remeasure()`** - Force recalculation of viewport dimensions
-
-### Types
-
-```typescript
-interface RenderItemProps<T> {
-  item: T;
-  index: number;
-  isSelected: boolean;
-}
-
-interface ViewportState {
-  offset: number;       // Items scrolled past
-  visibleCount: number; // Items currently visible
-  totalCount: number;   // Total items
-}
-```
-
-## Advanced Example
-
-```tsx
-import { VirtualList } from 'ink-virtual-list';
-import { Box, Text } from 'ink';
-import { useRef, useState } from 'react';
-import type { VirtualListRef } from 'ink-virtual-list';
-
-interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-}
-
-function TodoApp() {
-  const [todos] = useState<Todo[]>([
-    { id: '1', title: 'Learn Ink', completed: true },
-    { id: '2', title: 'Build CLI', completed: false },
-    // ... 1000s more
-  ]);
-  const [selectedIndex, setSelectedIndex] = useState(0);
-  const listRef = useRef<VirtualListRef>(null);
-
-  return (
-    <Box flexDirection="column">
-      <Text bold>My Todos ({todos.length})</Text>
-
-      <VirtualList
-        ref={listRef}
-        items={todos}
-        selectedIndex={selectedIndex}
-        height="auto"
-        reservedLines={3}
-        keyExtractor={(todo) => todo.id}
-        renderItem={({ item, isSelected }) => (
-          <Box>
-            <Text color={isSelected ? 'cyan' : 'white'}>
-              {isSelected ? '❯ ' : '  '}
-              {item.completed ? '✓' : '○'} {item.title}
-            </Text>
-          </Box>
-        )}
-      />
-
-      <Text dimColor>
-        {selectedIndex + 1} / {todos.length}
-      </Text>
-    </Box>
-  );
-}
-```
-
-## License
-
-MIT
+# ink-virtual-list
+
+A virtualized list component for [Ink](https://github.com/vadimdemedes/ink) terminal applications. Only renders visible items for optimal performance with large datasets.
+
+## Features
+
+- **Virtualized rendering** - Only renders items visible in the viewport
+- **Automatic scrolling** - Keeps selected item in view as you navigate
+- **Terminal-aware** - Responds to terminal resize events
+- **Flexible height** - Fixed height or auto-fill available terminal space
+- **Customizable indicators** - Override default overflow indicators ("▲ N more")
+- **TypeScript first** - Full type safety with generics
+- **Imperative API** - Programmatic scrolling via ref
+
+## Installation
+
+```bash
+# npm
+npm install ink-virtual-list
+
+# jsr
+npx jsr add @archcorsair/ink-virtual-list
+
+# bun
+bun add ink-virtual-list
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { VirtualList } from 'ink-virtual-list';
+import { Text } from 'ink';
+import { useState } from 'react';
+
+function App() {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`);
+
+  return (
+    <VirtualList
+      items={items}
+      selectedIndex={selectedIndex}
+      height={10}
+      renderItem={({ item, isSelected }) => (
+        <Text color={isSelected ? 'cyan' : 'white'}>
+          {isSelected ? '> ' : '  '}
+          {item}
+        </Text>
+      )}
+    />
+  );
+}
+```
+
+### Auto-fill Terminal Height
+
+```tsx
+<VirtualList
+  items={items}
+  height="auto"
+  reservedLines={5}  // Reserve space for header/footer
+  renderItem={({ item }) => <Text>{item}</Text>}
+/>
+```
+
+### Custom Overflow Indicators
+
+```tsx
+<VirtualList
+  items={items}
+  renderOverflowTop={(count) => <Text dimColor>↑ {count} hidden</Text>}
+  renderOverflowBottom={(count) => <Text dimColor>↓ {count} hidden</Text>}
+  renderItem={({ item }) => <Text>{item}</Text>}
+/>
+```
+
+### Imperative Scrolling
+
+```tsx
+import { useRef } from 'react';
+import type { VirtualListRef } from 'ink-virtual-list';
+
+function App() {
+  const listRef = useRef<VirtualListRef>(null);
+
+  const scrollToTop = () => {
+    listRef.current?.scrollToIndex(0, 'top');
+  };
+
+  return (
+    <VirtualList
+      ref={listRef}
+      items={items}
+      renderItem={({ item }) => <Text>{item}</Text>}
+    />
+  );
+}
+```
+
+## API
+
+### Props
+
+#### Required
+
+- **`items: T[]`** - Array of items to render
+- **`renderItem: (props: RenderItemProps<T>) => ReactNode`** - Render function for each visible item
+  - Receives: `{ item: T, index: number, isSelected: boolean }`
+
+#### Optional
+
+- **`selectedIndex?: number`** - Index of currently selected item (default: `0`)
+- **`keyExtractor?: (item: T, index: number) => string`** - Custom key extractor for list items
+- **`height?: number | "auto"`** - Fixed height in lines or `"auto"` to fill terminal (default: `10`)
+- **`reservedLines?: number`** - Lines to reserve when using `height="auto"` (default: `0`)
+- **`itemHeight?: number`** - Height of each item in lines (default: `1`)
+- **`showOverflowIndicators?: boolean`** - Show "N more" indicators (default: `true`)
+- **`renderOverflowTop?: (count: number) => ReactNode`** - Custom top overflow indicator
+- **`renderOverflowBottom?: (count: number) => ReactNode`** - Custom bottom overflow indicator
+- **`renderScrollBar?: (viewport: ViewportState) => ReactNode`** - Custom scrollbar renderer
+- **`onViewportChange?: (viewport: ViewportState) => void`** - Callback when viewport changes
+
+### Ref Methods
+
+```typescript
+interface VirtualListRef {
+  scrollToIndex: (index: number, alignment?: 'auto' | 'top' | 'center' | 'bottom') => void;
+  getViewport: () => ViewportState;
+  remeasure: () => void;
+}
+```
+
+- **`scrollToIndex(index, alignment?)`** - Scroll to bring an index into view
+  - `'auto'` (default) - Only scroll if needed
+  - `'top'` - Align item to top of viewport
+  - `'center'` - Center item in viewport
+  - `'bottom'` - Align item to bottom of viewport
+- **`getViewport()`** - Get current viewport state (`{ offset, visibleCount, totalCount }`)
+- **`remeasure()`** - Force recalculation of viewport dimensions
+
+### Types
+
+```typescript
+interface RenderItemProps<T> {
+  item: T;
+  index: number;
+  isSelected: boolean;
+}
+
+interface ViewportState {
+  offset: number;       // Items scrolled past
+  visibleCount: number; // Items currently visible
+  totalCount: number;   // Total items
+}
+```
+
+## Advanced Example
+
+```tsx
+import { VirtualList } from 'ink-virtual-list';
+import { Box, Text } from 'ink';
+import { useRef, useState } from 'react';
+import type { VirtualListRef } from 'ink-virtual-list';
+
+interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+function TodoApp() {
+  const [todos] = useState<Todo[]>([
+    { id: '1', title: 'Learn Ink', completed: true },
+    { id: '2', title: 'Build CLI', completed: false },
+    // ... 1000s more
+  ]);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const listRef = useRef<VirtualListRef>(null);
+
+  return (
+    <Box flexDirection="column">
+      <Text bold>My Todos ({todos.length})</Text>
+
+      <VirtualList
+        ref={listRef}
+        items={todos}
+        selectedIndex={selectedIndex}
+        height="auto"
+        reservedLines={3}
+        keyExtractor={(todo) => todo.id}
+        renderItem={({ item, isSelected }) => (
+          <Box>
+            <Text color={isSelected ? 'cyan' : 'white'}>
+              {isSelected ? '❯ ' : '  '}
+              {item.completed ? '✓' : '○'} {item.title}
+            </Text>
+          </Box>
+        )}
+      />
+
+      <Text dimColor>
+        {selectedIndex + 1} / {todos.length}
+      </Text>
+    </Box>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -41,6 +41,8 @@ interface VirtualListProps<T> {
 	itemHeight?: number;
 	/** Whether to show "N more" indicators when items overflow (default: true) */
 	showOverflowIndicators?: boolean;
+	/** Minimum overflow count before showing indicators (default: 1) */
+	overflowIndicatorThreshold?: number;
 	/** Custom renderer for the top overflow indicator */
 	renderOverflowTop?: (count: number) => ReactNode;
 	/** Custom renderer for the bottom overflow indicator */
@@ -75,8 +77,9 @@ interface TerminalSize {
 * Uses Ink's stdout to detect terminal dimensions.
 */
 declare function useTerminalSize(): TerminalSize;
+declare function validateItemHeight(itemHeight: number): void;
 declare function VirtualListInner<T>(props: VirtualListProps<T>, ref: React.ForwardedRef<VirtualListRef>): React.JSX.Element;
 declare const VirtualList: <T>(props: VirtualListProps<T> & {
 	ref?: React.ForwardedRef<VirtualListRef>;
 }) => ReturnType<typeof VirtualListInner>;
-export { useTerminalSize, VirtualListRef, VirtualListProps, VirtualList, ViewportState, TerminalSize, RenderItemProps };
+export { validateItemHeight, useTerminalSize, VirtualListRef, VirtualListProps, VirtualList, ViewportState, TerminalSize, RenderItemProps };

package/dist/index.js

@@ -10,6 +10,9 @@ function useTerminalSize() {
     columns: stdout.columns ?? DEFAULT_COLUMNS
   });
   useEffect(() => {
+    if (!stdout.isTTY) {
+      return;
+    }
     const handleResize = () => {
       setSize({
         rows: stdout.rows ?? DEFAULT_ROWS,
@@ -29,6 +32,23 @@ import { forwardRef, useEffect as useEffect2, useImperativeHandle, useMemo, useS
 import { jsxDEV } from "react/jsx-dev-runtime";
 var DEFAULT_HEIGHT = 10;
 var DEFAULT_ITEM_HEIGHT = 1;
+function getDefaultKey(item, index) {
+  if (item && typeof item === "object") {
+    const obj = item;
+    if ("id" in obj && (typeof obj.id === "string" || typeof obj.id === "number")) {
+      return String(obj.id);
+    }
+    if ("key" in obj && (typeof obj.key === "string" || typeof obj.key === "number")) {
+      return String(obj.key);
+    }
+  }
+  return String(index);
+}
+function validateItemHeight(itemHeight) {
+  if (!Number.isInteger(itemHeight) || itemHeight < 1) {
+    throw new Error(`[ink-virtual-list] itemHeight must be a positive integer, got: ${itemHeight}`);
+  }
+}
 function calculateViewportOffset(selectedIndex, currentOffset, visibleCount) {
   if (selectedIndex < currentOffset) {
     return selectedIndex;
@@ -48,11 +68,13 @@ function VirtualListInner(props, ref) {
     reservedLines = 0,
     itemHeight = DEFAULT_ITEM_HEIGHT,
     showOverflowIndicators = true,
+    overflowIndicatorThreshold = 1,
     renderOverflowTop,
     renderOverflowBottom,
     renderScrollBar,
     onViewportChange
   } = props;
+  validateItemHeight(itemHeight);
   const { rows: terminalRows } = useTerminalSize();
   const resolvedHeight = useMemo(() => {
     if (typeof height === "number") {
@@ -65,22 +87,21 @@ function VirtualListInner(props, ref) {
   const availableHeight = Math.max(0, resolvedHeight - indicatorLines);
   const visibleCount = Math.floor(availableHeight / resolvedItemHeight);
   const clampedSelectedIndex = Math.max(0, Math.min(selectedIndex, items.length - 1));
-  const calculatedOffset = useMemo(() => {
+  const [viewportOffset, setViewportOffset] = useState2(() => {
     if (items.length === 0)
       return 0;
     const maxOffset = Math.max(0, items.length - visibleCount);
-    let offset = 0;
     if (clampedSelectedIndex >= visibleCount) {
-      offset = clampedSelectedIndex - visibleCount + 1;
+      return Math.min(clampedSelectedIndex - visibleCount + 1, maxOffset);
     }
-    return Math.min(Math.max(0, offset), maxOffset);
-  }, [items.length, visibleCount, clampedSelectedIndex]);
-  const [viewportOffset, setViewportOffset] = useState2(calculatedOffset);
+    return 0;
+  });
   useEffect2(() => {
-    const newOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);
-    if (newOffset !== viewportOffset) {
-      const maxOffset = Math.max(0, items.length - visibleCount);
-      setViewportOffset(Math.min(newOffset, maxOffset));
+    const maxOffset = Math.max(0, items.length - visibleCount);
+    const targetOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);
+    const clampedOffset = Math.min(Math.max(0, targetOffset), maxOffset);
+    if (clampedOffset !== viewportOffset) {
+      setViewportOffset(clampedOffset);
     }
   }, [clampedSelectedIndex, viewportOffset, visibleCount, items.length]);
   const viewport = useMemo(() => ({
@@ -149,26 +170,32 @@ function VirtualListInner(props, ref) {
   return /* @__PURE__ */ jsxDEV(Box, {
     flexDirection: "column",
     children: [
-      showOverflowIndicators && overflowTop > 0 && topIndicator(overflowTop),
+      showOverflowIndicators && overflowTop >= overflowIndicatorThreshold && topIndicator(overflowTop),
       visibleItems.map((item, idx) => {
         const actualIndex = viewportOffset + idx;
-        const key = keyExtractor ? keyExtractor(item, actualIndex) : String(actualIndex);
+        const key = keyExtractor ? keyExtractor(item, actualIndex) : getDefaultKey(item, actualIndex);
         const itemProps = {
           item,
           index: actualIndex,
           isSelected: actualIndex === clampedSelectedIndex
         };
         return /* @__PURE__ */ jsxDEV(Box, {
+          height: resolvedItemHeight,
+          overflow: "hidden",
           children: renderItem(itemProps)
         }, key, false, undefined, this);
       }),
-      showOverflowIndicators && overflowBottom > 0 && bottomIndicator(overflowBottom),
+      showOverflowIndicators && overflowBottom >= overflowIndicatorThreshold && bottomIndicator(overflowBottom),
       renderScrollBar?.(viewport)
     ]
   }, undefined, true, undefined, this);
 }
 var VirtualList = forwardRef(VirtualListInner);
 export {
+  validateItemHeight,
   useTerminalSize,
   VirtualList
 };
+
+//# debugId=BD24055224F4B27D64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["src\\useTerminalSize.ts", "src\\VirtualList.tsx"],
+  "sourcesContent": [
+    "import { useStdout } from \"ink\";\nimport { useEffect, useState } from \"react\";\n\n/**\n * Represents the terminal dimensions.\n */\nexport interface TerminalSize {\n  /** Number of rows (lines) in the terminal */\n  rows: number;\n  /** Number of columns (characters) in the terminal */\n  columns: number;\n}\n\nconst DEFAULT_ROWS = 24;\nconst DEFAULT_COLUMNS = 80;\n\n/**\n * Hook that returns the current terminal size and updates on resize.\n * Uses Ink's stdout to detect terminal dimensions.\n */\nexport function useTerminalSize(): TerminalSize {\n  const { stdout } = useStdout();\n  const [size, setSize] = useState<TerminalSize>({\n    rows: stdout.rows ?? DEFAULT_ROWS,\n    columns: stdout.columns ?? DEFAULT_COLUMNS,\n  });\n\n  useEffect(() => {\n    // Skip resize listener in non-TTY environments (CI, pipes)\n    if (!stdout.isTTY) {\n      return;\n    }\n\n    const handleResize = () => {\n      setSize({\n        rows: stdout.rows ?? DEFAULT_ROWS,\n        columns: stdout.columns ?? DEFAULT_COLUMNS,\n      });\n    };\n\n    stdout.on(\"resize\", handleResize);\n    return () => {\n      stdout.off(\"resize\", handleResize);\n    };\n  }, [stdout]);\n\n  return size;\n}\n",
+    "import { Box, Text } from \"ink\";\nimport { forwardRef, useEffect, useImperativeHandle, useMemo, useState } from \"react\";\nimport type { RenderItemProps, ViewportState, VirtualListProps, VirtualListRef } from \"./types\";\nimport { useTerminalSize } from \"./useTerminalSize\";\n\nconst DEFAULT_HEIGHT = 10;\nconst DEFAULT_ITEM_HEIGHT = 1;\n\n/**\n * Attempts to extract a stable key from an item.\n * Checks for 'id' or 'key' properties on objects before falling back to index.\n */\nfunction getDefaultKey<T>(item: T, index: number): string {\n  if (item && typeof item === \"object\") {\n    const obj = item as Record<string, unknown>;\n    if (\"id\" in obj && (typeof obj.id === \"string\" || typeof obj.id === \"number\")) {\n      return String(obj.id);\n    }\n    if (\"key\" in obj && (typeof obj.key === \"string\" || typeof obj.key === \"number\")) {\n      return String(obj.key);\n    }\n  }\n  return String(index);\n}\n\nexport function validateItemHeight(itemHeight: number): void {\n  if (!Number.isInteger(itemHeight) || itemHeight < 1) {\n    throw new Error(`[ink-virtual-list] itemHeight must be a positive integer, got: ${itemHeight}`);\n  }\n}\n\nfunction calculateViewportOffset(selectedIndex: number, currentOffset: number, visibleCount: number): number {\n  // Selection above viewport - scroll up\n  if (selectedIndex < currentOffset) {\n    return selectedIndex;\n  }\n\n  // Selection below viewport - scroll down\n  if (selectedIndex >= currentOffset + visibleCount) {\n    return selectedIndex - visibleCount + 1;\n  }\n\n  // Selection visible - no change\n  return currentOffset;\n}\n\nfunction VirtualListInner<T>(props: VirtualListProps<T>, ref: React.ForwardedRef<VirtualListRef>): React.JSX.Element {\n  const {\n    items,\n    renderItem,\n    selectedIndex = 0,\n    keyExtractor,\n    height = DEFAULT_HEIGHT,\n    reservedLines = 0,\n    itemHeight = DEFAULT_ITEM_HEIGHT,\n    showOverflowIndicators = true,\n    overflowIndicatorThreshold = 1,\n    renderOverflowTop,\n    renderOverflowBottom,\n    renderScrollBar,\n    onViewportChange,\n  } = props;\n\n  // Validate itemHeight\n  validateItemHeight(itemHeight);\n\n  const { rows: terminalRows } = useTerminalSize();\n\n  // Calculate resolved height\n  const resolvedHeight = useMemo(() => {\n    if (typeof height === \"number\") {\n      return height;\n    }\n    // 'auto' - use terminal rows minus reserved\n    return Math.max(1, terminalRows - reservedLines);\n  }, [height, terminalRows, reservedLines]);\n\n  const resolvedItemHeight = itemHeight ?? DEFAULT_ITEM_HEIGHT;\n\n  // Reserve space for overflow indicators within the height budget\n  const indicatorLines = showOverflowIndicators ? 2 : 0;\n  const availableHeight = Math.max(0, resolvedHeight - indicatorLines);\n\n  // Calculate how many items fit in viewport\n  const visibleCount = Math.floor(availableHeight / resolvedItemHeight);\n\n  // Clamp selectedIndex to valid range\n  const clampedSelectedIndex = Math.max(0, Math.min(selectedIndex, items.length - 1));\n\n  // Lazy initial offset - positions selection at bottom of viewport if needed\n  const [viewportOffset, setViewportOffset] = useState(() => {\n    if (items.length === 0) return 0;\n    const maxOffset = Math.max(0, items.length - visibleCount);\n    if (clampedSelectedIndex >= visibleCount) {\n      return Math.min(clampedSelectedIndex - visibleCount + 1, maxOffset);\n    }\n    return 0;\n  });\n\n  // Sync viewport when selection changes\n  useEffect(() => {\n    const maxOffset = Math.max(0, items.length - visibleCount);\n    const targetOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);\n    const clampedOffset = Math.min(Math.max(0, targetOffset), maxOffset);\n    if (clampedOffset !== viewportOffset) {\n      setViewportOffset(clampedOffset);\n    }\n  }, [clampedSelectedIndex, viewportOffset, visibleCount, items.length]);\n\n  // Build viewport state\n  const viewport: ViewportState = useMemo(\n    () => ({\n      offset: viewportOffset,\n      visibleCount,\n      totalCount: items.length,\n    }),\n    [viewportOffset, visibleCount, items.length],\n  );\n\n  // Notify on viewport change\n  useEffect(() => {\n    onViewportChange?.(viewport);\n  }, [viewport, onViewportChange]);\n\n  // Imperative handle\n  useImperativeHandle(\n    ref,\n    () => ({\n      scrollToIndex: (index: number, alignment: \"auto\" | \"top\" | \"center\" | \"bottom\" = \"auto\") => {\n        const clampedIndex = Math.max(0, Math.min(index, items.length - 1));\n        let newOffset: number;\n\n        switch (alignment) {\n          case \"top\":\n            newOffset = clampedIndex;\n            break;\n          case \"center\":\n            newOffset = clampedIndex - Math.floor(visibleCount / 2);\n            break;\n          case \"bottom\":\n            newOffset = clampedIndex - visibleCount + 1;\n            break;\n          default: // 'auto'\n            newOffset = calculateViewportOffset(clampedIndex, viewportOffset, visibleCount);\n        }\n\n        const maxOffset = Math.max(0, items.length - visibleCount);\n        setViewportOffset(Math.min(Math.max(0, newOffset), maxOffset));\n      },\n      getViewport: () => viewport,\n      remeasure: () => {\n        // Force recalculation by updating state\n        setViewportOffset((prev) => {\n          const maxOffset = Math.max(0, items.length - visibleCount);\n          return Math.min(prev, maxOffset);\n        });\n      },\n    }),\n    [items.length, visibleCount, viewportOffset, viewport],\n  );\n\n  // Calculate overflow counts\n  const overflowTop = viewportOffset;\n  const overflowBottom = Math.max(0, items.length - viewportOffset - visibleCount);\n\n  // Get visible items\n  const visibleItems = items.slice(viewportOffset, viewportOffset + visibleCount);\n\n  // Default overflow renderers (paddingLeft aligns with list content)\n  const defaultOverflowTop = (count: number) => (\n    <Box paddingLeft={2}>\n      <Text dimColor>▲ {count} more</Text>\n    </Box>\n  );\n  const defaultOverflowBottom = (count: number) => (\n    <Box paddingLeft={2}>\n      <Text dimColor>▼ {count} more</Text>\n    </Box>\n  );\n\n  const topIndicator = renderOverflowTop ?? defaultOverflowTop;\n  const bottomIndicator = renderOverflowBottom ?? defaultOverflowBottom;\n\n  return (\n    <Box flexDirection=\"column\">\n      {showOverflowIndicators && overflowTop >= overflowIndicatorThreshold && topIndicator(overflowTop)}\n\n      {visibleItems.map((item, idx) => {\n        const actualIndex = viewportOffset + idx;\n        const key = keyExtractor ? keyExtractor(item, actualIndex) : getDefaultKey(item, actualIndex);\n\n        const itemProps: RenderItemProps<T> = {\n          item,\n          index: actualIndex,\n          isSelected: actualIndex === clampedSelectedIndex,\n        };\n\n        return (\n          <Box key={key} height={resolvedItemHeight} overflow=\"hidden\">\n            {renderItem(itemProps)}\n          </Box>\n        );\n      })}\n\n      {showOverflowIndicators && overflowBottom >= overflowIndicatorThreshold && bottomIndicator(overflowBottom)}\n\n      {renderScrollBar?.(viewport)}\n    </Box>\n  );\n}\n\nexport const VirtualList = forwardRef(VirtualListInner) as <T>(\n  props: VirtualListProps<T> & { ref?: React.ForwardedRef<VirtualListRef> },\n) => ReturnType<typeof VirtualListInner>;\n"
+  ],
+  "mappings": "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",
+  "debugId": "BD24055224F4B27D64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "ink-virtual-list",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A virtualized list component for Ink terminal applications",
   "type": "module",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,6 +17,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
+    "test": "bun test --only-failures",
     "build": "bunup",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
@@ -54,6 +54,7 @@
     "@types/bun": "latest",
     "@types/react": "^19.2.7",
     "bunup": "^0.16.17",
+    "ink-testing-library": "^4.0.0",
     "typescript": "^5.9.3"
   }
 }

package/src/VirtualList.tsx

@@ -1,192 +0,0 @@
-import { Box, Text } from "ink";
-import { forwardRef, useEffect, useImperativeHandle, useMemo, useState } from "react";
-import type { RenderItemProps, ViewportState, VirtualListProps, VirtualListRef } from "./types";
-import { useTerminalSize } from "./useTerminalSize";
-
-const DEFAULT_HEIGHT = 10;
-const DEFAULT_ITEM_HEIGHT = 1;
-
-function calculateViewportOffset(selectedIndex: number, currentOffset: number, visibleCount: number): number {
-  // Selection above viewport - scroll up
-  if (selectedIndex < currentOffset) {
-    return selectedIndex;
-  }
-
-  // Selection below viewport - scroll down
-  if (selectedIndex >= currentOffset + visibleCount) {
-    return selectedIndex - visibleCount + 1;
-  }
-
-  // Selection visible - no change
-  return currentOffset;
-}
-
-function VirtualListInner<T>(props: VirtualListProps<T>, ref: React.ForwardedRef<VirtualListRef>): React.JSX.Element {
-  const {
-    items,
-    renderItem,
-    selectedIndex = 0,
-    keyExtractor,
-    height = DEFAULT_HEIGHT,
-    reservedLines = 0,
-    itemHeight = DEFAULT_ITEM_HEIGHT,
-    showOverflowIndicators = true,
-    renderOverflowTop,
-    renderOverflowBottom,
-    renderScrollBar,
-    onViewportChange,
-  } = props;
-
-  const { rows: terminalRows } = useTerminalSize();
-
-  // Calculate resolved height
-  const resolvedHeight = useMemo(() => {
-    if (typeof height === "number") {
-      return height;
-    }
-    // 'auto' - use terminal rows minus reserved
-    return Math.max(1, terminalRows - reservedLines);
-  }, [height, terminalRows, reservedLines]);
-
-  const resolvedItemHeight = itemHeight ?? DEFAULT_ITEM_HEIGHT;
-
-  // Reserve space for overflow indicators within the height budget
-  const indicatorLines = showOverflowIndicators ? 2 : 0;
-  const availableHeight = Math.max(0, resolvedHeight - indicatorLines);
-
-  // Calculate how many items fit in viewport
-  const visibleCount = Math.floor(availableHeight / resolvedItemHeight);
-
-  // Clamp selectedIndex to valid range
-  const clampedSelectedIndex = Math.max(0, Math.min(selectedIndex, items.length - 1));
-
-  // Calculate viewport offset - use useMemo to derive from selectedIndex
-  // This ensures the viewport is always in sync with selection
-  const calculatedOffset = useMemo(() => {
-    if (items.length === 0) return 0;
-
-    const maxOffset = Math.max(0, items.length - visibleCount);
-
-    // Calculate what offset would show the selected item
-    let offset = 0;
-
-    // Selection below viewport - scroll down
-    if (clampedSelectedIndex >= visibleCount) {
-      offset = clampedSelectedIndex - visibleCount + 1;
-    }
-
-    return Math.min(Math.max(0, offset), maxOffset);
-  }, [items.length, visibleCount, clampedSelectedIndex]);
-
-  const [viewportOffset, setViewportOffset] = useState(calculatedOffset);
-
-  // Sync viewportOffset when selection changes
-  useEffect(() => {
-    const newOffset = calculateViewportOffset(clampedSelectedIndex, viewportOffset, visibleCount);
-    if (newOffset !== viewportOffset) {
-      const maxOffset = Math.max(0, items.length - visibleCount);
-      setViewportOffset(Math.min(newOffset, maxOffset));
-    }
-  }, [clampedSelectedIndex, viewportOffset, visibleCount, items.length]);
-
-  // Build viewport state
-  const viewport: ViewportState = useMemo(
-    () => ({
-      offset: viewportOffset,
-      visibleCount,
-      totalCount: items.length,
-    }),
-    [viewportOffset, visibleCount, items.length],
-  );
-
-  // Notify on viewport change
-  useEffect(() => {
-    onViewportChange?.(viewport);
-  }, [viewport, onViewportChange]);
-
-  // Imperative handle
-  useImperativeHandle(
-    ref,
-    () => ({
-      scrollToIndex: (index: number, alignment: "auto" | "top" | "center" | "bottom" = "auto") => {
-        const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
-        let newOffset: number;
-
-        switch (alignment) {
-          case "top":
-            newOffset = clampedIndex;
-            break;
-          case "center":
-            newOffset = clampedIndex - Math.floor(visibleCount / 2);
-            break;
-          case "bottom":
-            newOffset = clampedIndex - visibleCount + 1;
-            break;
-          default: // 'auto'
-            newOffset = calculateViewportOffset(clampedIndex, viewportOffset, visibleCount);
-        }
-
-        const maxOffset = Math.max(0, items.length - visibleCount);
-        setViewportOffset(Math.min(Math.max(0, newOffset), maxOffset));
-      },
-      getViewport: () => viewport,
-      remeasure: () => {
-        // Force recalculation by updating state
-        setViewportOffset((prev) => {
-          const maxOffset = Math.max(0, items.length - visibleCount);
-          return Math.min(prev, maxOffset);
-        });
-      },
-    }),
-    [items.length, visibleCount, viewportOffset, viewport],
-  );
-
-  // Calculate overflow counts
-  const overflowTop = viewportOffset;
-  const overflowBottom = Math.max(0, items.length - viewportOffset - visibleCount);
-
-  // Get visible items
-  const visibleItems = items.slice(viewportOffset, viewportOffset + visibleCount);
-
-  // Default overflow renderers (paddingLeft aligns with list content)
-  const defaultOverflowTop = (count: number) => (
-    <Box paddingLeft={2}>
-      <Text dimColor>▲ {count} more</Text>
-    </Box>
-  );
-  const defaultOverflowBottom = (count: number) => (
-    <Box paddingLeft={2}>
-      <Text dimColor>▼ {count} more</Text>
-    </Box>
-  );
-
-  const topIndicator = renderOverflowTop ?? defaultOverflowTop;
-  const bottomIndicator = renderOverflowBottom ?? defaultOverflowBottom;
-
-  return (
-    <Box flexDirection="column">
-      {showOverflowIndicators && overflowTop > 0 && topIndicator(overflowTop)}
-
-      {visibleItems.map((item, idx) => {
-        const actualIndex = viewportOffset + idx;
-        const key = keyExtractor ? keyExtractor(item, actualIndex) : String(actualIndex);
-
-        const itemProps: RenderItemProps<T> = {
-          item,
-          index: actualIndex,
-          isSelected: actualIndex === clampedSelectedIndex,
-        };
-
-        return <Box key={key}>{renderItem(itemProps)}</Box>;
-      })}
-
-      {showOverflowIndicators && overflowBottom > 0 && bottomIndicator(overflowBottom)}
-
-      {renderScrollBar?.(viewport)}
-    </Box>
-  );
-}
-
-export const VirtualList = forwardRef(VirtualListInner) as <T>(
-  props: VirtualListProps<T> & { ref?: React.ForwardedRef<VirtualListRef> },
-) => ReturnType<typeof VirtualListInner>;

package/src/index.ts

@@ -1,9 +0,0 @@
-export type {
-  RenderItemProps,
-  ViewportState,
-  VirtualListProps,
-  VirtualListRef,
-} from "./types";
-export type { TerminalSize } from "./useTerminalSize";
-export { useTerminalSize } from "./useTerminalSize";
-export { VirtualList } from "./VirtualList";

package/src/types.ts

@@ -1,72 +0,0 @@
-import type { ReactNode } from "react";
-
-/**
- * Props passed to the renderItem function for each visible item.
- */
-export interface RenderItemProps<T> {
-  /** The item data from the items array */
-  item: T;
-  /** The index of this item in the full items array */
-  index: number;
-  /** Whether this item is currently selected */
-  isSelected: boolean;
-}
-
-/**
- * Represents the current viewport state of the virtual list.
- */
-export interface ViewportState {
-  /** Number of items scrolled past (hidden above viewport) */
-  offset: number;
-  /** Number of items currently visible in the viewport */
-  visibleCount: number;
-  /** Total number of items in the list */
-  totalCount: number;
-}
-
-/**
- * Props for the VirtualList component.
- */
-export interface VirtualListProps<T> {
-  /** Array of items to render */
-  items: T[];
-  /** Render function for each visible item */
-  renderItem: (props: RenderItemProps<T>) => ReactNode;
-
-  /** Index of the currently selected item (default: 0) */
-  selectedIndex?: number;
-  /** Function to extract a unique key for each item */
-  keyExtractor?: (item: T, index: number) => string;
-
-  /** Fixed height in lines, or "auto" to fill available terminal space (default: 10) */
-  height?: number | "auto";
-  /** Lines to reserve when using height="auto" (e.g., for headers/footers) */
-  reservedLines?: number;
-  /** Height of each item in lines (default: 1) */
-  itemHeight?: number;
-
-  /** Whether to show "N more" indicators when items overflow (default: true) */
-  showOverflowIndicators?: boolean;
-  /** Custom renderer for the top overflow indicator */
-  renderOverflowTop?: (count: number) => ReactNode;
-  /** Custom renderer for the bottom overflow indicator */
-  renderOverflowBottom?: (count: number) => ReactNode;
-
-  /** Custom renderer for a scrollbar (receives viewport state) */
-  renderScrollBar?: (viewport: ViewportState) => ReactNode;
-
-  /** Callback fired when the viewport changes */
-  onViewportChange?: (viewport: ViewportState) => void;
-}
-
-/**
- * Imperative handle methods exposed via ref.
- */
-export interface VirtualListRef {
-  /** Scroll to bring a specific index into view */
-  scrollToIndex: (index: number, alignment?: "auto" | "top" | "center" | "bottom") => void;
-  /** Get the current viewport state */
-  getViewport: () => ViewportState;
-  /** Force recalculation of viewport dimensions */
-  remeasure: () => void;
-}

package/src/useTerminalSize.ts

@@ -1,43 +0,0 @@
-import { useStdout } from "ink";
-import { useEffect, useState } from "react";
-
-/**
- * Represents the terminal dimensions.
- */
-export interface TerminalSize {
-  /** Number of rows (lines) in the terminal */
-  rows: number;
-  /** Number of columns (characters) in the terminal */
-  columns: number;
-}
-
-const DEFAULT_ROWS = 24;
-const DEFAULT_COLUMNS = 80;
-
-/**
- * Hook that returns the current terminal size and updates on resize.
- * Uses Ink's stdout to detect terminal dimensions.
- */
-export function useTerminalSize(): TerminalSize {
-  const { stdout } = useStdout();
-  const [size, setSize] = useState<TerminalSize>({
-    rows: stdout.rows ?? DEFAULT_ROWS,
-    columns: stdout.columns ?? DEFAULT_COLUMNS,
-  });
-
-  useEffect(() => {
-    const handleResize = () => {
-      setSize({
-        rows: stdout.rows ?? DEFAULT_ROWS,
-        columns: stdout.columns ?? DEFAULT_COLUMNS,
-      });
-    };
-
-    stdout.on("resize", handleResize);
-    return () => {
-      stdout.off("resize", handleResize);
-    };
-  }, [stdout]);
-
-  return size;
-}