xonecas.io
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`