6615
Yc
yoctoselect / files
yoctoselect / AGENTS.md
3.2 KB
1# yoctoselect 2 3A minimal TypeScript library providing a single `select()` function for interactive list selection in the terminal. Prefix-match filtering, keyboard navigation, inline rendering (append-only), 16 ANSI colors via yoctocolors. 4 5## API 6 7```ts 8import { select } from "yoctoselect"; 9 10type SelectItem = string | { 11 label: string; // displayed text (can include ANSI colors) 12 value: string; // returned on selection 13 filterText?: string; // prefix-matched against search query (defaults to label, must be plain text if label has ANSI) 14}; 15 16const picked = await select({ 17 items: SelectItem[], 18 placeholder?: string, // shown in search input when empty, default "type to filter..." 19 maxVisible?: number, // default 20 20}); 21// Returns: string (the value) or null (ESC/no selection) 22``` 23 24## Visual Behavior 25 26``` 27 search: son 28 › claude-sonnet-4 ← highlighted (cyan), moved with ↑/↓ 29 claude-sonnet-4-6 30 2 more 31``` 32 33- **Search line**: `search: ` prompt + typed text + cursor 34- **Items**: prefix-matched against typed text, listed below search. Highlighted item has `›` prefix and cyan coloring. Others are indented with spaces. 35- **Overflow**: when filtered results exceed `maxVisible`, show dim `N more` at the bottom 36- **No matches**: dim `no matches` line 37- **Cancel**: ESC clears all rendered lines (search + items) and returns `null` 38- **Select**: Enter on highlighted item clears all rendered lines and returns the value 39- **Navigation**: ↑/↓ move highlight, wraps around. Home/End jump to first/last. 40- **Typing**: filters the list, resets highlight to first match 41 42## Rendering Strategy 43 44On each keystroke: move cursor up to the search line, clear from there down, re-render search + filtered items. On exit (select or cancel), clear all lines and leave no artifacts. This is a localized redraw of just the widget area — not a full-screen alternate buffer. 45 46## Tech Stack 47 48- Bun.js runtime + bundler 49- TypeScript 50- yoctocolors for terminal colors 51- Zero other dependencies 52- biome, prettier, lefthook, knip, jscpd 53 54## Package Structure 55 56``` 57src/ 58 index.ts — public API (re-exports select) 59 select.ts — select() implementation: event handling, render, filter 60 input.ts — stdin buffer parsing: tokenizes raw bytes into InputEvents 61 filter.ts — prefix match logic 62 viewport.ts — scroll offset and highlight movement (pure functions) 63 ansi.ts — ANSI escape helpers (cursor movement, clear lines) 64tests/ 65 filter.test.ts — test prefix matching 66package.json 67tsconfig.json 68biome.json 69README.md 70AGENTS.md 71``` 72 73## Testing 74 75- `filter.ts`: prefix matching with string items, `{label, value}` items, and `{label, value, filterText}` items. Case insensitivity. Empty query returns all. filterText takes precedence over label for matching. 76- Do NOT test rendering or stdin — that's integration with the terminal 77- Tests live next to code they test (`foo.test.ts` beside `foo.ts`) 78 79## Conventions 80 81- Conventional Commits for commit messages 82- DRY, KISS, YAGNI — no unnecessary complexity 83- No mocks or stubs in tests 84- Use 16 ANSI colors only (inherited from terminal theme) 85- Performance first 86- Use `bun` for everything: runtime, test runner, package manager, and `bunx` instead of `npx`