@aiquants/contact-map 0.2.0 → 0.3.0

package/README.md

@@ -70,7 +70,7 @@ Peer dependencies:
 
 | Entry Point | Target | Contents |
 | --- | --- | --- |
-| `@aiquants/contact-map` | Universal | Domain types, Zod schemas, wire protocols, geometry, parsers, and tree builders. |
+| `@aiquants/contact-map` | Universal | Domain types, Zod schemas, wire protocols, geometry, parsers, tree builders, and search query normalization. |
 | `@aiquants/contact-map/client` | Browser / SSR | React components (`ContactMapSearchPage`, `ContactMapSearchListView`, `ContactMapSearchTreeView`), hooks, and Worker clients. |
 | `@aiquants/contact-map/server` | Node / Server | DI port interfaces (`ContactMapServerPorts`), streaming handlers, and Drizzle MSSQL service queries. |
 | `@aiquants/contact-map/styles/contact-map.standalone.css` | CSS | Pre-compiled Tailwind v4 standalone utility styles. |
@@ -123,6 +123,26 @@ export default function ContactMapRoute() {
 }
 ```
 
+## Search Normalization / 検索語の正規化
+
+The search page normalizes the typed query with `normalizeSearchInput` (exported from `@aiquants/contact-map`) before using it in three places: the fuzzy search term, the exact-match ranking term and the highlight query. The contact fields (name, company, department, title, email, phone numbers) are matched as stored. The query is therefore only brought into a form those fields can hold:
+
+- Invisible characters (U+200B, U+FEFF) are removed, and surrounding whitespace (U+3000 and U+00A0 included) is trimmed.
+- Width, kana (hiragana → katakana) and case are unified with select-box's `normalizeText` (`ＡＢＣ商事` → `abc商事`, `さとう` → `サトウ`). Kana stays as written (`つづき` → `ツヅキ`).
+- The query is replaced by its katakana reading only when the whole query is romaji that reads completely. It must hold only Latin letters and whitespace, and select-box's `romajiToKatakana` must leave no letter untransliterated (`tanaka` → `タナカ`, `yamada taro` → `ヤマダ タロ`, `tsuduki` → `ツヅキ`).
+- Mixed text, digits and symbols, and words that do not read completely keep their width / kana / case form (`user@corp.co.jp`, `営業部 tanaka`, `tanaka1`, `ke-su`, `sony`).
+
+The highlight marks the spellings that `getSearchQuerySpellings(query)` lists: select-box's `getNormalizedVariants` of each word of the query and of its normalized form. A kana reading is therefore marked only when the whole query reads as romaji. The select-box peer range is ^0.11.0, expanded from `workspace:^` at publish.
+
+検索ページは入力された検索語を `normalizeSearchInput` (`@aiquants/contact-map` から公開) で正規化してから、3 か所で使う: あいまい検索の検索語、完全一致による並べ替えの検索語、ハイライトの検索語。連絡先のフィールド (氏名・会社・部署・役職・メール・電話番号) は保存されたままの値で照合する。そのため検索語は、それらのフィールドが持ちうる形に揃えるだけ:
+
+- 不可視文字 (U+200B・U+FEFF) を除き、端の空白 (U+3000・U+00A0 を含む) を除く。
+- select-box の `normalizeText` で全角/半角・かな (ひらがな → カタカナ)・大文字小文字を統一する (`ＡＢＣ商事` → `abc商事`、`さとう` → `サトウ`)。かなは書いたまま (`つづき` → `ツヅキ`)。
+- 検索語全体が完全に読めるローマ字のときだけ、カタカナの読みに置き換える。ラテン文字と空白だけで、select-box の `romajiToKatakana` が音訳しない文字を残さないことが条件 (`tanaka` → `タナカ`、`yamada taro` → `ヤマダ タロ`、`tsuduki` → `ツヅキ`)。
+- 混在テキスト・数字や記号・完全には読めない語は、全角/半角・かな・大文字小文字の形のまま (`user@corp.co.jp`、`営業部 tanaka`、`tanaka1`、`ke-su`、`sony`)。
+
+ハイライトは `getSearchQuerySpellings(query)` が並べる表記に印を付ける。表記は、検索語の各語とその正規化形の各語に対する select-box の `getNormalizedVariants`。そのため、かなの読みに印が付くのは検索語全体がローマ字として読めるときだけ。select-box のピア範囲は ^0.11.0 (公開時に `workspace:^` から展開)。
+
 ## Localization / UI 言語
 
 Every string the client components render on their own (tabs, buttons, headings, status badges, column headers, empty states, aria-labels, the settings and statistics panels, and the fallback names of tree nodes without a company or a person name) comes from one label catalog per UI chrome locale. The embedded `@aiquants/virtualscroll` list and `@aiquants/directory-tree` tree receive the same locale and their part of the labels, and the tree Web Worker receives the fallback names, so the whole feature speaks one language.