{ "$schema": "https://pi-tui.ratstack.sh/schema/pattern.schema.json", "aka": [ "Ranked picker" ], "animated": false, "apis": [ { "name": "Input", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "SelectList", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "KeybindingsManager.matches", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#handle-keyboard-input-and-focus" } ], "applicability": [ "Use this when substring and ordered-character matches need different priorities." ], "category": "lists", "categoryLabel": "Lists and pickers", "consequences": [ "Field weights distinguish stronger matches from weaker ones.", "Ranking and stable selection require more logic than a plain filter." ], "family": "behavioral", "familyLabel": "Behavioral", "id": "match-ladder", "implementation": [ "Subagents and skill-palette use different search algorithms.", "Keep the highlighted item stable where it remains in the results." ], "intent": "Rank matching options across weighted label and description fields.", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/match-ladder.json", "kind": "component", "knownUses": [ { "example": "fuzzy-list-filtering", "moreRefs": 0, "refs": [ { "file": "src/tui/render-helpers.ts", "lines": "1-29", "sha": "6826b054", "url": "https://github.com/nicobailon/pi-subagents/blob/6826b0545216077195ae8ffe468a6434715814b7/src/tui/render-helpers.ts#L1-L29" }, { "file": "src/slash/selector.ts", "lines": "85-117", "sha": "6826b054", "url": "https://github.com/nicobailon/pi-subagents/blob/6826b0545216077195ae8ffe468a6434715814b7/src/slash/selector.ts#L85-L117" } ], "repo": "pi-subagents", "repoUrl": "https://github.com/nicobailon/pi-subagents", "title": "Rank selector choices by best matching field" } ], "linkedFrom": [ { "how": "ranks rather than only narrowing", "id": "shrinking-sieve", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve.md", "name": "Shrinking Sieve", "url": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve/" } ], "links": { "agentGuide": "https://pi-tui.ratstack.sh/llms.txt", "index": "https://pi-tui.ratstack.sh/patterns.md", "skill": "https://pi-tui.ratstack.sh/skills/build-pi-tui-component.md" }, "mdUrl": "https://pi-tui.ratstack.sh/patterns/match-ladder.md", "motivation": "Subagents ranks matches across name, description and model rather than matching only one label.", "name": "Match Ladder", "participants": [ { "name": "Input", "role": "Owns single-line editing and cursor state.", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "SelectList", "role": "Owns a bounded selection list and selection callbacks.", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "KeybindingsManager.matches", "role": "Resolves input against configurable action bindings.", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#handle-keyboard-input-and-focus" }, { "name": "Match scorer", "role": "Weights fields and orders positive matches.", "url": null } ], "pi": "1.0.3", "related": [ { "how": "narrows candidates without field ranking", "id": "shrinking-sieve", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve.md", "name": "Shrinking Sieve", "url": "https://pi-tui.ratstack.sh/patterns/shrinking-sieve/" } ], "sampleCode": { "code": "// Match Ladder: rank weighted fields, then retain the selected identity.\nimport { getSelectListTheme } from \"@earendil-works/pi-coding-agent\";\nimport { Input, SelectList, Text, type SelectItem, type Component, type Focusable } from \"@earendil-works/pi-tui\";\nimport type { PatternStory } from \"../../../src/pattern.ts\";\n\nconst options = [\n { value: \"review\", label: \"Review\", description: \"Inspect a patch\", model: \"balanced\" },\n { value: \"audit\", label: \"Audit\", description: \"Review dependencies\", model: \"careful\" },\n { value: \"research\", label: \"Retrieve evidence\", description: \"Search notes\", model: \"rapid\" },\n];\nfunction matchScore(field: string, query: string): number {\n field = field.toLowerCase();\n if (field.includes(query)) return 10;\n let cursor = 0;\n for (const letter of field) if (letter === query[cursor]) cursor++;\n return cursor === query.length ? 1 : 0;\n}\nfunction ranked(query: string): SelectItem[] {\n return options.map(item => ({ item, score: Math.max(\n 3 * matchScore(item.label, query), 2 * matchScore(item.description, query),\n matchScore(item.model, query),\n ) })).filter(match => match.score > 0)\n .sort((a, b) => b.score - a.score).map(({ item, score }) => ({\n ...item, label: score + \" · \" + item.label,\n }));\n}\n\nexport const story: PatternStory = {\n id: \"match-ladder\", title: \"Match Ladder\", kind: \"component\",\n apis: [\"Input\", \"SelectList\", \"KeybindingsManager.matches\"], rows: 12,\n states: [\n { id: \"query\", label: \"Ranked matches\" },\n { id: \"navigation\", label: \"Keep selection\", steps: [\n { type: \"keys\", data: \"\\x1b[B\" }, { type: \"action\", name: \"refresh\" },\n ] },\n { id: \"empty\", label: \"No matches\", steps: [{ type: \"keys\", data: \"zzz\" }] },\n ],\n setup({ tui, theme, keybindings, action }) {\n const input = new Input({ prompt: \"Search: \" });\n input.setValue(\"rev\");\n input.handleInput(\"\\x05\"); // Move to the end of the initial query.\n let choices = new SelectList(ranked(input.getValue()), 5, getSelectListTheme());\n function refresh() {\n const identity = choices.getSelectedItem()?.value;\n const matches = ranked(input.getValue().toLowerCase());\n choices = new SelectList(matches, 5, getSelectListTheme());\n choices.setSelectedIndex(Math.max(0, matches.findIndex(item => item.value === identity)));\n tui.requestRender();\n }\n action(\"refresh\", refresh);\n const view: Component & Focusable = {\n focused: false,\n invalidate() { input.invalidate(); choices.invalidate(); },\n handleInput(data) {\n if (keybindings.matches(data, \"tui.select.up\") || keybindings.matches(data, \"tui.select.down\")) {\n choices.handleInput(data);\n } else { input.handleInput(data); refresh(); }\n tui.requestRender();\n },\n render(width) {\n input.focused = this.focused;\n return [\n ...new Text(theme.fg(\"accent\", \"Task picker · strongest field wins\"), 0, 0).render(width),\n ...input.render(width), \"\", ...choices.render(width), \"\",\n ...new Text(theme.fg(\"muted\", \"Label ×3 · description ×2 · model ×1\"), 0, 0).render(width),\n ...new Text(theme.fg(\"dim\", \"Substring outranks ordered characters\"), 0, 0).render(width),\n ];\n },\n };\n return view;\n },\n};\n", "lang": "ts", "path": "stories/patterns/behavioral/match-ladder.ts" }, "states": [ { "dont": false, "expectFail": [], "frames": [ { "alt": "Match Ladder, Ranked matches state, 40 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-40-dark.14fd5c0ddd84.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Match Ladder, Ranked matches state, 40 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-40-light.d11ece494259.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Match Ladder, Ranked matches state, 60 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-60-dark.d14bbd44d577.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Match Ladder, Ranked matches state, 60 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-60-light.4a027953086e.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Match Ladder, Ranked matches state, 80 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-80-dark.e2ece7aa00c4.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Match Ladder, Ranked matches state, 80 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-80-light.084c325f3c11.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Match Ladder, Ranked matches state, 120 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-120-dark.c53984c40c8f.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Match Ladder, Ranked matches state, 120 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/query-120-light.2be30367c5a4.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Show substring matches before weaker subsequence matches across synthetic fields.", "id": "query", "label": "Ranked matches", "problems": [] }, { "dont": false, "expectFail": [], "frames": [ { "alt": "Match Ladder, Keep selection state, 40 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-40-dark.b91f0b1ee16a.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Match Ladder, Keep selection state, 40 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-40-light.fb0fe09fa881.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Match Ladder, Keep selection state, 60 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-60-dark.52a408894c47.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Match Ladder, Keep selection state, 60 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-60-light.7f7863a5ad9a.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Match Ladder, Keep selection state, 80 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-80-dark.a173ced4253d.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Match Ladder, Keep selection state, 80 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-80-light.83e0a0c1c459.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Match Ladder, Keep selection state, 120 columns, dark theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-120-dark.0de6b4ba9fdc.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Match Ladder, Keep selection state, 120 columns, light theme, 9 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 396, "rows": 9, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/navigation-120-light.cb9a0fdaae52.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Move down without resetting selection to the first row.", "id": "navigation", "label": "Keep selection", "problems": [] }, { "dont": false, "expectFail": [], "frames": [ { "alt": "Match Ladder, No matches state, 40 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-40-dark.20e0cbcd3d1b.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Match Ladder, No matches state, 40 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-40-light.6918c7fecd48.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Match Ladder, No matches state, 60 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-60-dark.1b09960eb377.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Match Ladder, No matches state, 60 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-60-light.6828cc917199.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Match Ladder, No matches state, 80 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-80-dark.c866550da49f.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Match Ladder, No matches state, 80 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-80-light.0a41260fe076.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Match Ladder, No matches state, 120 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-120-dark.72fa9a73b77c.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Match Ladder, No matches state, 120 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/match-ladder/empty-120-light.7d6a4309b57f.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Show an explicit empty-result row.", "id": "empty", "label": "No matches", "problems": [] } ], "structure": "query + fields -> scores\nscores -> order -> selection", "thumbnails": { "dark": { "animation": null, "src": "https://pi-tui.ratstack.sh/thumbs/match-ladder/dark.240332dd115d.webp" }, "light": { "animation": null, "src": "https://pi-tui.ratstack.sh/thumbs/match-ladder/light.43d44d94565b.webp" } }, "url": "https://pi-tui.ratstack.sh/patterns/match-ladder/", "widths": [ 40, 60, 80, 120 ] }