@silvery/examples 0.4.2

package/examples/apps/search-filter.tsx

@@ -0,0 +1,240 @@
+/**
+ * Search Filter Example
+ *
+ * Demonstrates React concurrent features for responsive typing:
+ * - useTransition for low-priority state updates
+ * - useDeferredValue for deferred filtering
+ * - Typing remains responsive even with heavy filtering
+ */
+
+import React, { useState, useDeferredValue, useTransition } from "react"
+import { render, Box, Text, Kbd, Muted, Strong, Lead, useInput, useApp, createTerm, type Key } from "../../src/index.js"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Search Filter",
+  description: "useTransition + useDeferredValue for responsive concurrent search",
+  features: ["useDeferredValue", "useTransition", "useInput"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Item {
+  id: number
+  name: string
+  category: string
+  tags: string[]
+}
+
+// ============================================================================
+// Data
+// ============================================================================
+
+const items: Item[] = [
+  {
+    id: 1,
+    name: "React Hooks Guide",
+    category: "docs",
+    tags: ["react", "hooks", "tutorial"],
+  },
+  {
+    id: 2,
+    name: "TypeScript Patterns",
+    category: "docs",
+    tags: ["typescript", "patterns"],
+  },
+  {
+    id: 3,
+    name: "Build Configuration",
+    category: "config",
+    tags: ["webpack", "vite", "build"],
+  },
+  {
+    id: 4,
+    name: "Testing Best Practices",
+    category: "docs",
+    tags: ["testing", "jest", "vitest"],
+  },
+  {
+    id: 5,
+    name: "API Documentation",
+    category: "docs",
+    tags: ["api", "rest", "graphql"],
+  },
+  {
+    id: 6,
+    name: "Database Schema",
+    category: "config",
+    tags: ["database", "sql", "migration"],
+  },
+  {
+    id: 7,
+    name: "Authentication Flow",
+    category: "docs",
+    tags: ["auth", "security", "jwt"],
+  },
+  {
+    id: 8,
+    name: "CI/CD Pipeline",
+    category: "config",
+    tags: ["ci", "deployment", "github"],
+  },
+  {
+    id: 9,
+    name: "Performance Tuning",
+    category: "docs",
+    tags: ["performance", "optimization"],
+  },
+  {
+    id: 10,
+    name: "Error Handling",
+    category: "docs",
+    tags: ["errors", "debugging", "logging"],
+  },
+  {
+    id: 11,
+    name: "State Management",
+    category: "docs",
+    tags: ["state", "redux", "zustand"],
+  },
+  {
+    id: 12,
+    name: "CSS Architecture",
+    category: "docs",
+    tags: ["css", "tailwind", "styled"],
+  },
+  {
+    id: 13,
+    name: "Security Guidelines",
+    category: "docs",
+    tags: ["security", "owasp", "audit"],
+  },
+  {
+    id: 14,
+    name: "Deployment Scripts",
+    category: "config",
+    tags: ["deploy", "docker", "k8s"],
+  },
+  {
+    id: 15,
+    name: "Monitoring Setup",
+    category: "config",
+    tags: ["monitoring", "metrics", "logs"],
+  },
+]
+
+// ============================================================================
+// Components
+// ============================================================================
+
+function SearchInput({ value, onChange }: { value: string; onChange: (v: string) => void }) {
+  return (
+    <Box>
+      <Strong color="$primary">Search: </Strong>
+      <Text>{value}</Text>
+      <Text dim>|</Text>
+    </Box>
+  )
+}
+
+function FilteredList({ query, isPending }: { query: string; isPending: boolean }) {
+  // Simulate expensive filtering (in real app this might be fuzzy search)
+  const filtered = items.filter((item) => {
+    const searchLower = query.toLowerCase()
+    return (
+      item.name.toLowerCase().includes(searchLower) ||
+      item.category.toLowerCase().includes(searchLower) ||
+      item.tags.some((tag) => tag.toLowerCase().includes(searchLower))
+    )
+  })
+
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      <Box marginBottom={1}>
+        <Muted>
+          {filtered.length} results
+          {isPending && " (filtering...)"}
+        </Muted>
+      </Box>
+      {filtered.map((item) => (
+        <Box key={item.id} marginBottom={1}>
+          <Text bold>{item.name}</Text>
+          <Text dim> [{item.category}]</Text>
+          <Text color="gray"> {item.tags.join(", ")}</Text>
+        </Box>
+      ))}
+      {filtered.length === 0 && <Lead>No matches found</Lead>}
+    </Box>
+  )
+}
+
+export function SearchApp() {
+  const { exit } = useApp()
+  const [query, setQuery] = useState("")
+
+  // useDeferredValue: The filtered list uses a deferred version of the query
+  // This keeps typing responsive while the list catches up
+  const deferredQuery = useDeferredValue(query)
+
+  // useTransition: Mark filtering as low-priority (optional, shows pending state)
+  const [isPending, startTransition] = useTransition()
+
+  useInput((input: string, key: Key) => {
+    if (key.escape) {
+      exit()
+      return
+    }
+
+    if (key.backspace || key.delete) {
+      // Backspace: remove last character
+      startTransition(() => {
+        setQuery((prev) => prev.slice(0, -1))
+      })
+      return
+    }
+
+    // Add printable characters
+    if (input && !key.ctrl && !key.meta) {
+      startTransition(() => {
+        setQuery((prev) => prev + input)
+      })
+    }
+  })
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <SearchInput value={query} onChange={setQuery} />
+
+      {/* List uses deferredQuery so typing stays responsive */}
+      <Box flexGrow={1}>
+        <FilteredList query={deferredQuery} isPending={isPending} />
+      </Box>
+
+      <Muted>
+        {" "}
+        <Kbd>type</Kbd> to search <Kbd>Esc/q</Kbd> quit
+      </Muted>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="type to search  Esc quit">
+      <SearchApp />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/apps/task-list.tsx

@@ -0,0 +1,271 @@
+/**
+ * Task List Example
+ *
+ * A scrollable task list demonstrating:
+ * - 50+ items for scrolling demonstration
+ * - overflow="hidden" with manual scroll state
+ * - Toggle task completion with space
+ * - Variable height items (some with subtasks)
+ */
+
+import React, { useState, useMemo } from "react"
+import { render, Box, Text, Kbd, Muted, useInput, useApp, createTerm, type Key } from "../../src/index.js"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Task List",
+  description: "Scrollable list with priority badges, toggles, and expandable subtasks",
+  features: ["VirtualList", "variable itemHeight", "Box overflow"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Task {
+  id: number
+  title: string
+  completed: boolean
+  priority: "high" | "medium" | "low"
+  subtasks?: string[]
+}
+
+// ============================================================================
+// Data Generation
+// ============================================================================
+
+function generateTasks(count: number): Task[] {
+  const priorities: Array<"high" | "medium" | "low"> = ["high", "medium", "low"]
+  const taskTemplates = [
+    "Review pull request",
+    "Update documentation",
+    "Fix bug in authentication",
+    "Implement new feature",
+    "Write unit tests",
+    "Refactor legacy code",
+    "Update dependencies",
+    "Create API endpoint",
+    "Design database schema",
+    "Optimize performance",
+    "Add error handling",
+    "Setup CI/CD pipeline",
+    "Write integration tests",
+    "Code review feedback",
+    "Deploy to staging",
+  ]
+
+  const subtaskTemplates = [
+    ["Research solutions", "Implement changes", "Test thoroughly"],
+    ["Check requirements", "Update code"],
+    ["Review with team", "Make adjustments", "Get approval", "Merge"],
+  ]
+
+  return Array.from({ length: count }, (_, i) => ({
+    id: i + 1,
+    title: `${taskTemplates[i % taskTemplates.length]} #${Math.floor(i / taskTemplates.length) + 1}`,
+    completed: Math.random() > 0.7,
+    priority: priorities[i % 3] as "high" | "medium" | "low",
+    // Every 5th task has subtasks
+    subtasks: i % 5 === 0 ? subtaskTemplates[i % subtaskTemplates.length] : undefined,
+  }))
+}
+
+// ============================================================================
+// Components
+// ============================================================================
+
+function PriorityBadge({ priority }: { priority: "high" | "medium" | "low" }) {
+  const colors = {
+    high: "$error",
+    medium: "$warning",
+    low: "$success",
+  }
+  const symbols = {
+    high: "!!!",
+    medium: "!!",
+    low: "!",
+  }
+
+  return (
+    <Text color={colors[priority]} bold>
+      [{symbols[priority]}]
+    </Text>
+  )
+}
+
+function TaskItem({ task, isSelected, isExpanded }: { task: Task; isSelected: boolean; isExpanded: boolean }) {
+  const checkbox = task.completed ? "[x]" : "[ ]"
+  const hasSubtasks = task.subtasks && task.subtasks.length > 0
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        {isSelected ? (
+          <Text backgroundColor="$primary" color="black">
+            {" "}
+            {checkbox} {task.title}{" "}
+          </Text>
+        ) : (
+          <Text strikethrough={task.completed} dim={task.completed}>
+            {checkbox} {task.title}
+          </Text>
+        )}{" "}
+        <PriorityBadge priority={task.priority} />
+        {hasSubtasks && <Text dim> ({task.subtasks!.length} subtasks)</Text>}
+      </Box>
+      {hasSubtasks && isExpanded && (
+        <Box flexDirection="column" marginLeft={4}>
+          {task.subtasks!.map((subtask, idx) => (
+            <Text key={idx} dim>
+              - {subtask}
+            </Text>
+          ))}
+        </Box>
+      )}
+    </Box>
+  )
+}
+
+function StatusBar({
+  tasks,
+  cursor,
+  scrollOffset,
+  visibleCount,
+}: {
+  tasks: Task[]
+  cursor: number
+  scrollOffset: number
+  visibleCount: number
+}) {
+  const completed = tasks.filter((t) => t.completed).length
+  const total = tasks.length
+  const percent = Math.round((completed / total) * 100)
+
+  return (
+    <Box justifyContent="space-between">
+      <Muted>
+        {" "}
+        <Kbd>j/k</Kbd> navigate <Kbd>space</Kbd> toggle <Kbd>enter</Kbd> expand <Kbd>Esc/q</Kbd> quit
+      </Muted>
+      <Muted>
+        {" "}
+        <Text bold>{completed}</Text>/{total} ({percent}%) | {cursor + 1}/{total}{" "}
+      </Muted>
+    </Box>
+  )
+}
+
+export function TaskList() {
+  const { exit } = useApp()
+  const [tasks, setTasks] = useState(() => generateTasks(60))
+  const [cursor, setCursor] = useState(0)
+  const [expandedTasks, setExpandedTasks] = useState<Set<number>>(new Set())
+
+  // Fixed visible count (in a real app, this would use useContentRect)
+  const visibleCount = 15
+
+  // Calculate scroll offset to keep cursor visible
+  const scrollOffset = useMemo(() => {
+    const halfVisible = Math.floor(visibleCount / 2)
+    const maxOffset = Math.max(0, tasks.length - visibleCount)
+
+    // Keep cursor centered when possible
+    let offset = cursor - halfVisible
+    offset = Math.max(0, Math.min(offset, maxOffset))
+    return offset
+  }, [cursor, visibleCount, tasks.length])
+
+  // Get visible tasks
+  const visibleTasks = useMemo(() => {
+    return tasks.slice(scrollOffset, scrollOffset + visibleCount)
+  }, [tasks, scrollOffset, visibleCount])
+
+  useInput((input: string, key: Key) => {
+    if (input === "q" || key.escape) {
+      exit()
+    }
+    if (key.upArrow || input === "k") {
+      setCursor((prev) => Math.max(0, prev - 1))
+    }
+    if (key.downArrow || input === "j") {
+      setCursor((prev) => Math.min(tasks.length - 1, prev + 1))
+    }
+    if (key.pageUp) {
+      setCursor((prev) => Math.max(0, prev - visibleCount))
+    }
+    if (key.pageDown) {
+      setCursor((prev) => Math.min(tasks.length - 1, prev + visibleCount))
+    }
+    if (key.home) {
+      setCursor(0)
+    }
+    if (key.end) {
+      setCursor(tasks.length - 1)
+    }
+    if (input === " ") {
+      // Toggle completion
+      setTasks((prev) => prev.map((task, idx) => (idx === cursor ? { ...task, completed: !task.completed } : task)))
+    }
+    if (key.return || input === "e") {
+      // Toggle expand/collapse subtasks
+      const taskId = tasks[cursor]?.id
+      if (taskId !== undefined && tasks[cursor]?.subtasks) {
+        setExpandedTasks((prev) => {
+          const next = new Set(prev)
+          if (next.has(taskId)) {
+            next.delete(taskId)
+          } else {
+            next.add(taskId)
+          }
+          return next
+        })
+      }
+    }
+  })
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Box
+        flexGrow={1}
+        flexDirection="column"
+        borderStyle="round"
+        borderColor="$border"
+        overflow="hidden"
+        height={visibleCount + 2}
+      >
+        {visibleTasks.map((task, visibleIndex) => {
+          const actualIndex = scrollOffset + visibleIndex
+          return (
+            <TaskItem
+              key={task.id}
+              task={task}
+              isSelected={actualIndex === cursor}
+              isExpanded={expandedTasks.has(task.id)}
+            />
+          )
+        })}
+      </Box>
+
+      <StatusBar tasks={tasks} cursor={cursor} scrollOffset={scrollOffset} visibleCount={visibleCount} />
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="j/k navigate  space toggle  enter expand  Esc/q quit">
+      <TaskList />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}