@aicontextgateway/search-react 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@aicontextgateway/search-react",
+    "version": "0.0.1",
+    "description": "Embeddable AiContextGateway smart search bar: deterministic (no-AI) fuzzy/facet search as a React component and a self-contained <aicontextgateway-search> web component, with an optional AI answer layer.",
+    "license": "MIT",
+    "type": "module",
+    "files": [
+        "dist",
+        "loader",
+        "src/searchCore.js"
+    ],
+    "main": "./dist/search-react.umd.cjs",
+    "module": "./dist/search-react.js",
+    "exports": {
+        ".": {
+            "import": "./dist/search-react.js",
+            "require": "./dist/search-react.umd.cjs"
+        },
+        "./styles.css": "./dist/search-react.css",
+        "./core": "./src/searchCore.js",
+        "./element": "./dist/aicontextgateway-search.iife.js",
+        "./loader": "./loader/loader.js"
+    },
+    "scripts": {
+        "build": "vite build -c vite.config.react.js && vite build -c vite.config.element.js",
+        "test": "node src/searchCore.test.mjs"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    }
+}

package/src/searchCore.js

@@ -0,0 +1,269 @@
+/**
+ * Deterministic search core for @aicontextgateway/search.
+ *
+ * Zero dependencies, no DOM, no AI, no network — pure functions over
+ * caller-provided data. Runs client-side. Importable on its own (Node too),
+ * which is why the node smoke test can exercise it without a bundler.
+ *
+ * Capabilities: tokenization, prefix + fuzzy (bounded Levenshtein) matching,
+ * synonym expansion, field weighting, deterministic ranking, facet counts +
+ * filtering, and highlight segmentation.
+ */
+
+/** Split arbitrary text into lowercase alphanumeric tokens. */
+export function tokenize(text) {
+    if (text == null) return [];
+
+    return String(text)
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter(Boolean);
+}
+
+/**
+ * Bounded Damerau-Levenshtein (optimal string alignment): like Levenshtein but
+ * an adjacent transposition (the most common search typo, e.g. "shose"->"shoes")
+ * costs 1, not 2. Returns max+1 as soon as the distance provably exceeds max.
+ */
+export function editDistance(a, b, max) {
+    if (a === b) return 0;
+    const al = a.length;
+    const bl = b.length;
+    if (Math.abs(al - bl) > max) return max + 1;
+
+    let prevPrev = null;
+    let prev = new Array(bl + 1);
+    for (let j = 0; j <= bl; j++) prev[j] = j;
+
+    for (let i = 1; i <= al; i++) {
+        const cur = new Array(bl + 1);
+        cur[0] = i;
+        let rowMin = cur[0];
+
+        for (let j = 1; j <= bl; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let val = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                val = Math.min(val, prevPrev[j - 2] + 1);
+            }
+            cur[j] = val;
+            if (val < rowMin) rowMin = val;
+        }
+
+        if (rowMin > max) return max + 1;
+        prevPrev = prev;
+        prev = cur;
+    }
+
+    return prev[bl];
+}
+
+/** Max edits allowed for a token: 0 for short tokens, 1–2 as they get longer (unless disabled). */
+function maxEditsFor(token, fuzzy) {
+    if (fuzzy === false) return 0;
+    if (typeof fuzzy === 'number') return Math.max(0, fuzzy);
+    if (token.length >= 8) return 2;
+    if (token.length >= 4) return 1;
+
+    return 0;
+}
+
+/**
+ * Build a token -> Set(group) map from a synonyms object like
+ * { shoes: ['sneaker', 'trainer'] }. Grouping is bidirectional.
+ */
+export function buildSynonyms(synonyms) {
+    const map = new Map();
+    if (!synonyms) return map;
+
+    for (const [key, alts] of Object.entries(synonyms)) {
+        const group = new Set([key.toLowerCase(), ...(alts || []).map((a) => String(a).toLowerCase())]);
+        for (const term of group) {
+            const existing = map.get(term) || new Set();
+            for (const g of group) existing.add(g);
+            map.set(term, existing);
+        }
+    }
+
+    return map;
+}
+
+/** Expand one query token to its synonym group (itself included). */
+function expand(token, synonymMap) {
+    const group = synonymMap.get(token);
+
+    return group ? Array.from(group) : [token];
+}
+
+/** Collect the searchable string tokens of an item across the chosen fields. */
+function itemTokens(item, fields) {
+    const keys = fields && fields.length ? fields : Object.keys(item || {});
+    const tokens = [];
+
+    for (const key of keys) {
+        const value = item ? item[key] : undefined;
+        if (value == null) continue;
+
+        if (Array.isArray(value)) {
+            for (const v of value) tokens.push(...tokenize(v).map((t) => ({ field: key, token: t })));
+        } else if (typeof value === 'object') {
+            continue;
+        } else {
+            tokens.push(...tokenize(value).map((t) => ({ field: key, token: t })));
+        }
+    }
+
+    return tokens;
+}
+
+/** Best score for one query variant-set against one item's field tokens. 3 exact, 2 prefix, 1 fuzzy. */
+function scoreToken(variants, fieldTokens, fieldWeights, fuzzy) {
+    let best = 0;
+
+    for (const variant of variants) {
+        const edits = maxEditsFor(variant, fuzzy);
+
+        for (const { field, token } of fieldTokens) {
+            const weight = fieldWeights[field] ?? 1;
+            let raw = 0;
+
+            if (token === variant) raw = 3;
+            else if (variant.length >= 2 && token.startsWith(variant)) raw = 2;
+            else if (edits > 0 && editDistance(variant, token, edits) <= edits) raw = 1;
+
+            const scored = raw * weight;
+            if (scored > best) best = scored;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Search `items` for `query`. Deterministic and stable (ties keep input order).
+ *
+ * options:
+ *   fields        string[]  fields to search (default: all scalar/array fields)
+ *   fieldWeights  object    per-field weight, e.g. { title: 3, tags: 2 }
+ *   synonyms      object    { canonical: [alts] }
+ *   fuzzy         bool|num  typo tolerance (default true; number = max edits)
+ *   facetKeys     string[]  fields to compute facet counts over
+ *   activeFacets  object    { field: value } filters applied to results
+ *   limit         number    cap results (default 20)
+ *
+ * returns { results: [{ item, score, matched: string[] }], facets: { key: [{ value, count }] }, total }
+ */
+export function search(items, query, options = {}) {
+    const list = Array.isArray(items) ? items : [];
+    const {
+        fields,
+        fieldWeights = {},
+        synonyms,
+        fuzzy = true,
+        facetKeys = [],
+        activeFacets = {},
+        limit = 20,
+    } = options;
+
+    const synonymMap = buildSynonyms(synonyms);
+    const queryTokens = tokenize(query);
+
+    let matched;
+
+    if (queryTokens.length === 0) {
+        // Empty query: everything matches with score 0, input order preserved.
+        matched = list.map((item, index) => ({ item, index, score: 0, matched: [] }));
+    } else {
+        const variantSets = queryTokens.map((t) => expand(t, synonymMap));
+        matched = [];
+
+        list.forEach((item, index) => {
+            const fieldTokens = itemTokens(item, fields);
+            let score = 0;
+            const hitTokens = [];
+
+            queryTokens.forEach((token, i) => {
+                const s = scoreToken(variantSets[i], fieldTokens, fieldWeights, fuzzy);
+                if (s > 0) {
+                    score += s;
+                    hitTokens.push(token);
+                }
+            });
+
+            if (hitTokens.length === 0) return;
+
+            // Reward covering more of the query; big bonus when every token hits.
+            score += hitTokens.length;
+            if (hitTokens.length === queryTokens.length) score += 5;
+
+            matched.push({ item, index, score, matched: hitTokens });
+        });
+    }
+
+    // Facet counts are computed over the query-matched set (before active-facet filtering).
+    const facets = {};
+    for (const key of facetKeys) {
+        const counts = new Map();
+        for (const { item } of matched) {
+            const raw = item ? item[key] : undefined;
+            const values = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+            for (const v of values) counts.set(v, (counts.get(v) || 0) + 1);
+        }
+        facets[key] = Array.from(counts, ([value, count]) => ({ value, count })).sort(
+            (a, b) => b.count - a.count || String(a.value).localeCompare(String(b.value)),
+        );
+    }
+
+    // Apply active facet filters to the returned results.
+    let filtered = matched;
+    for (const [key, wanted] of Object.entries(activeFacets)) {
+        if (wanted == null || wanted === '') continue;
+        filtered = filtered.filter(({ item }) => {
+            const raw = item ? item[key] : undefined;
+            if (Array.isArray(raw)) return raw.includes(wanted);
+
+            return raw === wanted;
+        });
+    }
+
+    filtered.sort((a, b) => b.score - a.score || a.index - b.index);
+    const total = filtered.length;
+    const results = filtered.slice(0, limit).map(({ item, score, matched: m }) => ({ item, score, matched: m }));
+
+    return { results, facets, total };
+}
+
+/**
+ * Segment `text` into [{ text, match }] runs so a UI can highlight matches.
+ * A word is a match when it exactly/prefix/fuzzy-matches a query variant.
+ */
+export function highlightSegments(text, query, options = {}) {
+    const raw = text == null ? '' : String(text);
+    const synonymMap = buildSynonyms(options.synonyms);
+    const variants = new Set();
+    for (const t of tokenize(query)) for (const v of expand(t, synonymMap)) variants.add(v);
+    if (variants.size === 0 || raw === '') return [{ text: raw, match: false }];
+
+    const variantList = Array.from(variants);
+    const isMatch = (word) => {
+        const w = word.toLowerCase();
+
+        return variantList.some((v) => {
+            const edits = maxEditsFor(v, options.fuzzy ?? true);
+
+            return w === v || (v.length >= 2 && w.startsWith(v)) || (edits > 0 && editDistance(v, w, edits) <= edits);
+        });
+    };
+
+    const segments = [];
+    const parts = raw.split(/(\s+)/);
+    for (const part of parts) {
+        if (part === '') continue;
+        const match = /\s/.test(part) ? false : isMatch(part.replace(/[^a-z0-9]/gi, ''));
+        const last = segments[segments.length - 1];
+        if (last && last.match === match) last.text += part;
+        else segments.push({ text: part, match });
+    }
+
+    return segments;
+}