@effect-tui/react 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.5.0",
+	"version": "0.6.1",
 	"description": "React bindings for @effect-tui/core",
 	"type": "module",
 	"files": [
@@ -83,7 +83,7 @@
 		"prepublishOnly": "bun run typecheck && bun run build"
 	},
 	"dependencies": {
-		"@effect-tui/core": "^0.5.0",
+		"@effect-tui/core": "^0.6.1",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",

package/src/components/ListView.tsx

@@ -0,0 +1,138 @@
+// ListView.tsx — Virtualized selection-aware scrolling list
+import type { ReactNode } from "react"
+import { useEffect, useRef } from "react"
+import { useScroll } from "../hooks/use-scroll.js"
+
+export interface ListViewProps<T> {
+	/** Items to render */
+	items: readonly T[]
+	/** Currently selected index */
+	selectedIndex: number
+	/** Render function for each item */
+	renderItem: (item: T, index: number, isSelected: boolean) => ReactNode
+	/** Extract unique key for each item */
+	keyExtractor: (item: T, index: number) => string | number
+	/** Height of each item in rows (default: 1) */
+	itemHeight?: number
+	/** Padding rows to keep around selected item (default: 0) */
+	scrollPadding?: number
+	/** Show scrollbar (default: true) */
+	showScrollbar?: boolean
+	/** Empty state content when items is empty */
+	emptyContent?: ReactNode
+	/** Number of extra items to render above/below viewport for smooth scrolling (default: 3) */
+	overscan?: number
+}
+
+/**
+ * A virtualized scrolling list view with selection and scroll-into-view behavior.
+ *
+ * Features:
+ * - **Virtualized**: Only renders visible items + overscan buffer for performance
+ * - Automatically scrolls to keep selected item visible when selection changes
+ * - Supports mouse wheel scrolling with macOS-style acceleration
+ * - Shows a scroll bar when content overflows
+ *
+ * Keyboard navigation should be handled by the parent component - update
+ * `selectedIndex` and ListView will scroll to keep it visible.
+ *
+ * @example
+ * ```tsx
+ * const [selectedIndex, setSelectedIndex] = useState(0)
+ *
+ * // Handle keyboard in parent
+ * useKeyboard((key) => {
+ *   if (key.name === "down" || key.text === "j") {
+ *     setSelectedIndex(i => Math.min(items.length - 1, i + 1))
+ *   }
+ *   if (key.name === "up" || key.text === "k") {
+ *     setSelectedIndex(i => Math.max(0, i - 1))
+ *   }
+ * })
+ *
+ * return (
+ *   <ListView
+ *     items={cards}
+ *     selectedIndex={selectedIndex}
+ *     renderItem={(card, i, isSelected) => (
+ *       <CardListItem card={card} isSelected={isSelected} />
+ *     )}
+ *     keyExtractor={(card) => card.id}
+ *   />
+ * )
+ * ```
+ */
+export function ListView<T>({
+	items,
+	selectedIndex,
+	renderItem,
+	keyExtractor,
+	itemHeight = 1,
+	scrollPadding = 0,
+	showScrollbar = true,
+	emptyContent,
+	overscan = 3,
+}: ListViewProps<T>) {
+	const { state, scrollProps, scrollToVisible } = useScroll({
+		enableKeyboard: false, // Parent handles keyboard for selection
+		enableMouseWheel: true, // Free scroll with wheel
+	})
+
+	// Track previous selection to detect changes
+	const prevSelectedRef = useRef(selectedIndex)
+
+	// Scroll to keep selection visible when it changes
+	useEffect(() => {
+		if (selectedIndex !== prevSelectedRef.current) {
+			prevSelectedRef.current = selectedIndex
+			scrollToVisible(selectedIndex, itemHeight, scrollPadding)
+		}
+	}, [selectedIndex, itemHeight, scrollPadding, scrollToVisible])
+
+	// Also scroll on initial render if selection is not 0
+	useEffect(() => {
+		if (selectedIndex > 0) {
+			scrollToVisible(selectedIndex, itemHeight, scrollPadding)
+		}
+		// Only run on mount
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [])
+
+	if (items.length === 0 && emptyContent) {
+		return <>{emptyContent}</>
+	}
+
+	// Calculate visible range for virtualization
+	const totalHeight = items.length * itemHeight
+	const startIndex = Math.max(0, Math.floor(state.offset / itemHeight) - overscan)
+	const endIndex = Math.min(items.length, Math.ceil((state.offset + state.viewportSize) / itemHeight) + overscan)
+
+	// Calculate spacer heights for virtual scrolling
+	const topSpacerHeight = startIndex * itemHeight
+	const bottomSpacerHeight = Math.max(0, totalHeight - endIndex * itemHeight)
+
+	// Get visible slice of items
+	const visibleItems = items.slice(startIndex, endIndex)
+
+	return (
+		<scroll {...scrollProps} showScrollbar={showScrollbar}>
+			<vstack>
+				{/* Virtual top spacer */}
+				{topSpacerHeight > 0 && <spacer height={topSpacerHeight} />}
+
+				{/* Render only visible items */}
+				{visibleItems.map((item, i) => {
+					const actualIndex = startIndex + i
+					return (
+						<vstack key={keyExtractor(item, actualIndex)}>
+							{renderItem(item, actualIndex, actualIndex === selectedIndex)}
+						</vstack>
+					)
+				})}
+
+				{/* Virtual bottom spacer */}
+				{bottomSpacerHeight > 0 && <spacer height={bottomSpacerHeight} />}
+			</vstack>
+		</scroll>
+	)
+}

package/src/components/index.ts

@@ -1,4 +1,5 @@
 export { Divider, type DividerProps } from "./Divider.js"
+export { ListView, type ListViewProps } from "./ListView.js"
 export { Markdown, type MarkdownProps, type MarkdownTheme } from "./Markdown.js"
 export { MultilineTextInput, type MultilineTextInputProps } from "./MultilineTextInput.js"
 export { Overlay, type OverlayItemProps, type OverlayProps } from "./Overlay.js"

package/src/index.ts

@@ -6,6 +6,8 @@ export { CodeBlock } from "./codeblock.js"
 // Input components
 export {
 	type ColumnProps,
+	ListView,
+	type ListViewProps,
 	Markdown,
 	type MarkdownProps,
 	type MarkdownTheme,