@aiquants/contact-map 0.2.0 → 0.4.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,31 @@ export default function ContactMapRoute() {
 }
 ```
 
+## Search Normalization / 検索語の正規化
+
+The search page normalizes the typed query with `normalizeSearchInput` (exported from `@aiquants/contact-map`) into the fuzzy search term. 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 result highlight and the exact-match ranking are one derivation from the query as typed. `createSearchQueryPattern(query)` finds the spellings that `getSearchQuerySpellings(query)` lists (select-box's `getNormalizedVariants` of each word of the query and of its normalized form), longest first and case-insensitively.
+`HighlightedText` marks its matches, and `createExactMatchRanker(query, fields)` moves the results with a match in one of the fields to the top, keeping the fuzzy order within each group. A field is therefore highlighted exactly when it ranks its record as an exact match. A kana reading is marked only when the whole query reads as romaji.
+
+The typed query is used because normalization can drop a spelling it holds. select-box reads a prolonged sound mark that follows no kana as a hyphen, so `ーヒー` (the middle of `コーヒー`) becomes the search term `-ヒー`, while the highlight and the ranking still find `ーヒー`. The search outlet context carries both: `searchQuery` (as typed) and `searchTerm` (`normalizeSearchInput(searchQuery)`). The select-box peer range is ^0.11.0, expanded from `workspace:^` at publish.
+
+検索ページは入力された検索語を `normalizeSearchInput` (`@aiquants/contact-map` から公開) で正規化し、あいまい検索の検索語にする。連絡先のフィールド (氏名・会社・部署・役職・メール・電話番号) は保存されたままの値で照合する。そのため検索語は、それらのフィールドが持ちうる形に揃えるだけ:
+
+- 不可視文字 (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`)。
+
+検索結果のハイライトと完全一致による並べ替えは、入力されたままの検索語からの 1 つの導出。`createSearchQueryPattern(query)` は `getSearchQuerySpellings(query)` が並べる表記 (検索語の各語とその正規化形の各語に対する select-box の `getNormalizedVariants`) を、最長のものから大文字小文字を区別せずに探す。`HighlightedText` はその一致に印を付け、`createExactMatchRanker(query, fields)` はいずれかのフィールドに一致を持つ結果を先頭へ移す (各グループ内ではあいまい検索の順序を保つ)。そのため、フィールドにハイライトが付くのは、そのフィールドがレコードを完全一致として並べさせるときちょうど。かなの読みに印が付くのは検索語全体がローマ字として読めるときだけ。
+
+入力されたままの検索語を使うのは、正規化が検索語の持つ表記を落とすことがあるため。select-box はかなに続かない長音記号をハイフンと読むので、`ーヒー` (`コーヒー` の途中) は検索語 `-ヒー` になるが、ハイライトと並べ替えは `ーヒー` を探し続ける。検索のアウトレットコンテキストは両方を運ぶ: `searchQuery` (入力されたまま) と `searchTerm` (`normalizeSearchInput(searchQuery)`)。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.

package/dist/client.d.mts

@@ -1,7 +1,7 @@
 import * as react from "react";
 import { CSSProperties, ReactNode, RefObject, PointerEvent, MouseEvent } from "react";
 import { UseFuzzySearchOptions } from "@aiquants/fuzzy-search/react";
-import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-BxEK32O0.mjs";
+import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-CFgYO13H.mjs";
 import { DirectoryTreeLabels, DirectoryTreeVirtualScrollOptions } from "@aiquants/directory-tree";
 import * as _aiquants_virtualscroll from "@aiquants/virtualscroll";
 import { VirtualScrollLocale } from "@aiquants/virtualscroll";

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import * as react from "react";
 import { CSSProperties, ReactNode, RefObject, PointerEvent, MouseEvent } from "react";
 import { UseFuzzySearchOptions } from "@aiquants/fuzzy-search/react";
-import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-BxEK32O0.js";
+import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-CFgYO13H.js";
 import { DirectoryTreeLabels, DirectoryTreeVirtualScrollOptions } from "@aiquants/directory-tree";
 import * as _aiquants_virtualscroll from "@aiquants/virtualscroll";
 import { VirtualScrollLocale } from "@aiquants/virtualscroll";