@aiquants/contact-map 0.8.0 → 0.10.0

package/README.md

@@ -173,26 +173,36 @@ Worker を作れないか Worker が落ちると、250 ms 後と 500 ms 後の 2
 
 ## 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:
+The search box reads its text as keywords. Each whitespace-separated word is a keyword of its own, and the words between two quotation marks (`"`, `＂`, `“`, `”`; any of them opens or closes a group, and a group left open runs to the end) are one keyword.
+The page searches every keyword with `@aiquants/fuzzy-search`: `useFuzzySearch`'s `querySetsOf` reads the term with `parseQuerySets`, and `FuzzySearchManager.searchSets` searches one query set per keyword. The AND / OR button next to the search box combines the keywords' answers: AND keeps the contacts every keyword finds (intersection), OR the contacts any keyword finds (union). The button starts at OR, and switching it searches the current term again without rebuilding the index.
+A quoted keyword is matched by fuzzy-search's multi-word matching, whose operator is the settings tab's "Operator for words inside quotes" select (`multiTermOperator`, AND at first): AND requires every word of the group to appear in some search field, OR does not. A keyword of one word matches the same under either operator.
+A "Maximum results" cap of the index or Levenshtein settings (no limit at first) applies to each keyword's answer before the keywords are combined, so with a cap an AND search can miss a contact that one keyword's capped answer left out.
 
-- Invisible characters (U+200B, U+FEFF) are removed, and surrounding whitespace (U+3000 and U+00A0 included) is trimmed.
+The search page normalizes the typed text 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. Every keyword is therefore only brought into a form those fields can hold:
+
+- Invisible characters (U+200B, U+FEFF) are removed before the keywords are read, and each keyword's 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@example.com`, `営業部 tanaka`, `tanaka1`, `ke-su`, `sony`).
+- The keywords are replaced by their katakana readings only when every keyword is romaji that reads completely. Each must hold only Latin letters and whitespace, and select-box's `romajiToKatakana` must leave no letter untransliterated (`tanaka` → `タナカ`, `yamada taro` → `ヤマダ タロ`, `"yamada taro" suzuki` → `"ヤマダ タロ" スズキ`, `tsuduki` → `ツヅキ`).
+- Mixed text, digits and symbols, and words that do not read completely keep their width / kana / case form, and so does every other keyword of the text (`user@example.com`, `営業部 tanaka`, `tanaka1`, `ke-su`, `sony`, `"yamada taro" sony`).
+- The keywords are written back with fuzzy-search's `formatQuerySets`: single spaces between them, a keyword holding whitespace in ASCII quotation marks (`＂ＡＢＣ 商事＂` → `"abc 商事"`), and neither a blank keyword nor a keyword that normalization made equal to an earlier one. `parseQuerySets` therefore reads exactly these keywords from the term. Text without quotation marks becomes its whitespace-separated words, each normalized as above and written once, separated by single spaces.
 
-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 result highlight and the exact-match ranking are one derivation from the text as typed. `createSearchQueryPattern(query)` finds the spellings that `getSearchQuerySpellings(query)` lists (select-box's `getNormalizedVariants` of each word of the text's keywords and of its normalized form's keywords, read with fuzzy-search's `parseQuerySets`, so a quotation mark is never part of a spelling), 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 every keyword 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` から公開) で正規化し、あいまい検索の検索語にする。連絡先のフィールド (氏名・会社・部署・役職・メール・電話番号) は保存されたままの値で照合する。そのため検索語は、それらのフィールドが持ちうる形に揃えるだけ:
+検索欄はテキストをキーワードとして読む。空白で区切った語はそれぞれ 1 つのキーワードで、2 つの引用符 (`"`・`＂`・`“`・`”`。どれでも組を開き閉じ、開いたままの組は終わりまで続く) の間の語はまとめて 1 つのキーワード。ページはどのキーワードも `@aiquants/fuzzy-search` で検索する: `useFuzzySearch` の `querySetsOf` が `parseQuerySets` で検索語を読み、`FuzzySearchManager.searchSets` がキーワードごとに 1 つの問い合わせのセットを検索する。検索欄の隣の AND / OR ボタンはキーワードの答えをまとめ、AND はどのキーワードも見つけた連絡先 (積集合)、OR はどれかのキーワードが見つけた連絡先 (和集合) を残す。ボタンは OR で始まり、切り替えると索引を建て直さずに今の検索語を検索し直す。
+引用符で囲んだキーワードは fuzzy-search の複数語の照合で照合し、その演算子は設定タブの「引用符の中の語の演算子」セレクト (`multiTermOperator`。最初は AND): AND は組のどの語もいずれかの検索フィールドに現れることを求め、OR は求めない。1 語のキーワードはどちらの演算子でも同じに照合する。
+
+検索ページは入力されたテキストを `normalizeSearchInput` (`@aiquants/contact-map` から公開) で正規化し、あいまい検索の検索語にする。連絡先のフィールド (氏名・会社・部署・役職・メール・電話番号) は保存されたままの値で照合する。そのため各キーワードは、それらのフィールドが持ちうる形に揃えるだけ:
 
-- 不可視文字 (U+200B・U+FEFF) を除き、端の空白 (U+3000・U+00A0 を含む) を除く。
+- キーワードを読む前に不可視文字 (U+200B・U+FEFF) を除き、各キーワードの端の空白 (U+3000・U+00A0 を含む) を除く。
 - select-box の `normalizeText` で全角/半角・かな (ひらがな → カタカナ)・大文字小文字を統一する (`ＡＢＣ商事` → `abc商事`、`さとう` → `サトウ`)。かなは書いたまま (`つづき` → `ツヅキ`)。
-- 検索語全体が完全に読めるローマ字のときだけ、カタカナの読みに置き換える。ラテン文字と空白だけで、select-box の `romajiToKatakana` が音訳しない文字を残さないことが条件 (`tanaka` → `タナカ`、`yamada taro` → `ヤマダ タロ`、`tsuduki` → `ツヅキ`)。
-- 混在テキスト・数字や記号・完全には読めない語は、全角/半角・かな・大文字小文字の形のまま (`user@example.com`、`営業部 tanaka`、`tanaka1`、`ke-su`、`sony`)。
+- どのキーワードも完全に読めるローマ字のときだけ、各キーワードをカタカナの読みに置き換える。どれもラテン文字と空白だけで、select-box の `romajiToKatakana` が音訳しない文字を残さないことが条件 (`tanaka` → `タナカ`、`yamada taro` → `ヤマダ タロ`、`"yamada taro" suzuki` → `"ヤマダ タロ" スズキ`、`tsuduki` → `ツヅキ`)。
+- 混在テキスト・数字や記号・完全には読めない語は全角/半角・かな・大文字小文字の形のままで、そのテキストのほかのキーワードも同じ (`user@example.com`、`営業部 tanaka`、`tanaka1`、`ke-su`、`sony`、`"yamada taro" sony`)。
+- キーワードは fuzzy-search の `formatQuerySets` で書き戻す: キーワードの間は 1 つの空白、空白を持つキーワードは ASCII の引用符で囲み (`＂ＡＢＣ 商事＂` → `"abc 商事"`)、空のキーワードと、正規化で先のキーワードと等しくなったキーワードは書かない。そのため `parseQuerySets` は検索語からちょうどこれらのキーワードを読む。引用符の無いテキストは、空白で区切った各語を上のとおり正規化して 1 度ずつ並べ、1 つの空白で区切ったものになる。
 
-検索結果のハイライトと完全一致による並べ替えは、入力されたままの検索語からの 1 つの導出。`createSearchQueryPattern(query)` は `getSearchQuerySpellings(query)` が並べる表記 (検索語の各語とその正規化形の各語に対する select-box の `getNormalizedVariants`) を、最長のものから大文字小文字を区別せずに探す。`HighlightedText` はその一致に印を付け、`createExactMatchRanker(query, fields)` はいずれかのフィールドに一致を持つ結果を先頭へ移す (各グループ内ではあいまい検索の順序を保つ)。そのため、フィールドにハイライトが付くのは、そのフィールドがレコードを完全一致として並べさせるときちょうど。かなの読みに印が付くのは検索語全体がローマ字として読めるときだけ。
+検索結果のハイライトと完全一致による並べ替えは、入力されたままのテキストからの 1 つの導出。`createSearchQueryPattern(query)` は `getSearchQuerySpellings(query)` が並べる表記 (テキストのキーワードとその正規化形のキーワードの各語に対する select-box の `getNormalizedVariants`。語は fuzzy-search の `parseQuerySets` で読むため、引用符は表記の一部にならない) を、最長のものから大文字小文字を区別せずに探す。`HighlightedText` はその一致に印を付け、`createExactMatchRanker(query, fields)` はいずれかのフィールドに一致を持つ結果を先頭へ移す (各グループ内ではあいまい検索の順序を保つ)。そのため、フィールドにハイライトが付くのは、そのフィールドがレコードを完全一致として並べさせるときちょうど。かなの読みに印が付くのはどのキーワードもローマ字として読めるときだけ。
 
 入力されたままの検索語を使うのは、正規化が検索語の持つ表記を落とすことがあるため。select-box はかなに続かない長音記号をハイフンと読むので、`ーヒー` (`コーヒー` の途中) は検索語 `-ヒー` になるが、ハイライトと並べ替えは `ーヒー` を探し続ける。検索のアウトレットコンテキストは両方を運ぶ: `searchQuery` (入力されたまま) と `searchTerm` (`normalizeSearchInput(searchQuery)`)。select-box のピア範囲は ^0.11.0 (公開時に `workspace:^` から展開)。
 
@@ -437,10 +447,10 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `basicCaseSensitive` | `"Case-sensitive"` | `"大文字小文字を区別"` |
 | `basicHighlight` | `"Highlight matches"` | `"ハイライト表示"` |
 | `basicOpenEmailsWithGmail` | `"Open email addresses in Gmail compose"` | `"メールアドレスを Gmail の作成画面で開く"` |
-| `basicMultiTermOperator` | `"Multi-term query operator"` | `"複数語クエリの演算子"` |
-| `basicOperatorOr` | `"OR (any term matches)"` | `"OR (いずれか一致)"` |
-| `basicOperatorAnd` | `"AND (all terms match)"` | `"AND (すべて一致)"` |
-| `basicMultiTermHint` | `"How space-separated terms are combined (default: OR)"` | `"複数語をスペースで入力したときの結合方法 (既定は OR)"` |
+| `basicMultiTermOperator` | `"Operator for words inside quotes"` | `"引用符の中の語の演算子"` |
+| `basicOperatorOr` | `"OR (any word matches)"` | `"OR (いずれか一致)"` |
+| `basicOperatorAnd` | `"AND (all words match)"` | `"AND (すべて一致)"` |
+| `basicMultiTermHint` | `'How words between quotation marks ("tanaka taro") are combined (default: AND). Words outside quotation marks are separate keywords combined by the AND / OR button'` | `'引用符で囲んだ語 ("田中 太郎") の結合方法 (既定は AND)。引用符の外の語はそれぞれ別のキーワードで、AND / OR ボタンで結合する'` |
 | `basicSortHeading` | `"Sorting"` | `"ソート設定"` |
 | `basicSortBy` | `"Sort by"` | `"ソート基準"` |
 | `basicSortByScore` | `"Score"` | `"スコア"` |

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-hAxBVVH6.mjs";
+import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-BghOEeyw.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-hAxBVVH6.js";
+import { C as ContactRecord, a as ContactMapStreamPhase, b as ContactMapSearchOutletContext, c as ContactMapOutletContext, d as ContactMapLogger, S as SerializedContactStreamRow } from "./wire-BghOEeyw.js";
 import { DirectoryTreeLabels, DirectoryTreeVirtualScrollOptions } from "@aiquants/directory-tree";
 import * as _aiquants_virtualscroll from "@aiquants/virtualscroll";
 import { VirtualScrollLocale } from "@aiquants/virtualscroll";