feat : add fuzzy matching for searching

2026-09-12 16:07:16 +07:00
parent 0ec214d3e0
commit 92b57e0ed3
15 changed files with 318 additions and 79 deletions
@@ -0,0 +1,33 @@
+---
+name: fuzzy-search
+description: Add or maintain buzz-sheet name searches using the project’s shared collection-level fuzzy fallback. Use for guide, team, character, weapon, artifact, and glossary searches or catalog pickers; exclude numeric and fixed-option dropdowns.
+---
+
+# Buzz-sheet fuzzy search
+
+Use this project’s shared search implementation for finding entities by name or alias. Preserve explicit user choices if they call for different tolerance or ranking.
+
+## Default behavior
+
+- Preserve existing case-insensitive substring matching and its searchable fields. Return direct results in their original order.
+- Attempt fuzzy matching only when the entire eligible collection has no direct results. Do not decide fallback independently for each item.
+- Restrict fuzzy candidates to names, aliases, and individual whitespace-separated words. Keep overview prose and internal keys available for existing direct searches, but exclude them from fuzzy candidates.
+- Normalize with NFC, trim, lowercase, and compare Unicode code points. Keep queries shorter than four code points strict.
+- Use bounded optimal-string-alignment Damerau–Levenshtein distance, including adjacent transpositions. Allow one edit for 4–7 code points and two for longer queries, capped at 25% of query length. Rank by edit distance with stable source-order ties.
+- Empty queries return the eligible collection. Show the localized close-match notice only when fuzzy fallback returns results.
+
+## Reuse the project implementation
+
+Use `searchItems` from `lib/search.ts`, returning `{ items, fuzzy }`. Supply separate selectors for existing direct-search text and fuzzy candidate names. Use `SearchNotice` from `components/search-notice.tsx` for fallback feedback.
+
+Use `searchTeams` from `lib/guides/team-search.ts` for collection-level team searches. Apply active groups, permissions, and category restrictions before matching. Explicit DPS sorting takes precedence over fuzzy ranking. Direct team queries must match within one candidate name, not span multiple members.
+
+Use `FuzzyCombobox` from `components/ui/combobox.tsx` for catalog pickers, passing `items` and `searchNames`. It retains Base UI selection handling and disables native filtering with `filter={null}` after filtering the collection. Do not add another filter that would discard typo results. Preserve object identities and single/multiple selection behavior.
+
+Keep searches local against the already loaded collections. Reuse these utilities instead of adding another search engine or dependency.
+
+## Verify observable behavior
+
+Test collection-wide direct-match precedence, empty and short queries, edits and transpositions, aliases, multiword names, Thai/Unicode text, thresholds, unrelated inputs, stable ranking, and exclusion of prose/keys from fuzzy candidates. `muala` should directly match `Mualani`; `mulani` should find it through fallback.
+
+For pickers, verify keyboard selection, clearing, reopening, popup inputs, and multiple selection against the actual component. For teams, verify category restrictions and explicit sorting after matching. Run `bun run test`, `bun run lint`, and `bun run typecheck`; report pre-existing failures separately.
@@ -0,0 +1,3 @@
+interface:
+  display_name: "Fuzzy Search"
+  short_description: "Add typo-tolerant searches with direct-match fallback"