jekyll-client-search 0.1.0

data/assets/adapters/elasticlunr.js

@@ -0,0 +1,59 @@
+(function () {
+    "use strict";
+
+    /**
+     * ElasticLunr adapter — translates the uniform ClientSearch query model
+     * into ElasticLunr's native API.
+     *
+     * The base runtime owns the two-stage strategy (AND first, fuzzy OR
+     * fallback). This adapter only translates each stage's uniform options
+     * into ElasticLunr's search options and normalises results to
+     * { ref, score }. ElasticLunr already returns { ref, score } so the
+     * result translation is a pass-through.
+     */
+    var FIELD_OPTIONS = {
+        title: { boost: 10 },
+        categoriesText: { boost: 5 },
+        tagsText: { boost: 4 },
+        excerpt: { boost: 2 },
+        content: { boost: 1 }
+    };
+
+    window.ClientSearchAdapters = window.ClientSearchAdapters || {};
+    window.ClientSearchAdapters.elasticlunr = {
+        name: "elasticlunr",
+
+        available: function () {
+            return typeof window.elasticlunr !== "undefined";
+        },
+
+        buildIndex: function (documents) {
+            var index = window.elasticlunr(function () {
+                this.setRef("id");
+                Object.keys(FIELD_OPTIONS).forEach(function (field) {
+                    this.addField(field, FIELD_OPTIONS[field]);
+                }, this);
+            });
+            documents.forEach(function (document) {
+                index.addDoc(document);
+            });
+            return index;
+        },
+
+        search: function (index, query, options) {
+            var nativeOptions = {
+                fields: FIELD_OPTIONS,
+                bool: options.combineWith,
+                expand: options.prefix
+            };
+            if (options.fuzzy) {
+                nativeOptions.fuzzy = true;
+            }
+            return index.search(query, nativeOptions);
+        }
+    };
+
+    if (window.ClientSearch) {
+        window.ClientSearch.run(window.ClientSearchAdapters.elasticlunr);
+    }
+}());

data/assets/adapters/minisearch.js

@@ -0,0 +1,57 @@
+(function () {
+    "use strict";
+
+    /**
+     * MiniSearch adapter — translates the uniform ClientSearch query model
+     * into MiniSearch's native API.
+     *
+     * The base runtime owns the two-stage strategy (AND first, fuzzy OR
+     * fallback). This adapter only translates each stage's uniform options
+     * into MiniSearch's options and normalises results to { ref, score }.
+     */
+    var FIELDS = ["title", "excerpt", "content", "categoriesText", "tagsText"];
+    var BOOST = {
+        title: 10,
+        categoriesText: 5,
+        tagsText: 4,
+        excerpt: 2,
+        content: 1
+    };
+
+    window.ClientSearchAdapters = window.ClientSearchAdapters || {};
+    window.ClientSearchAdapters.minisearch = {
+        name: "minisearch",
+
+        available: function () {
+            return typeof window.MiniSearch !== "undefined";
+        },
+
+        buildIndex: function (documents) {
+            var miniSearch = new window.MiniSearch({
+                fields: FIELDS,
+                storeFields: ["title", "url", "excerpt", "categories", "tags"],
+                idField: "id"
+            });
+            miniSearch.addAll(documents);
+            return miniSearch;
+        },
+
+        search: function (index, query, options) {
+            var nativeOptions = {
+                combineWith: options.combineWith,
+                prefix: options.prefix,
+                boost: BOOST
+            };
+            if (options.fuzzy) {
+                nativeOptions.fuzzy = 0.2;
+            }
+            return index.search(query, nativeOptions).map(function (match) {
+                return { ref: match.id, score: match.score };
+            });
+        }
+    };
+
+    if (window.ClientSearch) {
+        window.ClientSearch.run(window.ClientSearchAdapters.minisearch);
+    }
+}());

data/assets/adapters/semantic.js

@@ -0,0 +1,154 @@
+(function () {
+    "use strict";
+
+    /**
+     * Semantic adapter — vector similarity search against pre-computed
+     * embeddings in the JSON index.
+     *
+     * This adapter expects each document to have an `embedding` field
+     * (a float vector) generated at Jekyll build time by the
+     * OllamaEmbeddingAdapter. At search time it calls
+     * ClientSearchQueryEmbedder, provided by a packaged query embedder or the
+     * consuming site, then ranks documents by cosine similarity.
+     *
+     * The base runtime's two-stage AND/OR strategy does not apply to
+     * vector search. This adapter implements its own ranking: it computes
+     * cosine similarity between the query embedding and every document
+     * embedding, returns those above a threshold, sorted by similarity.
+     *
+     * To use this adapter:
+     *   1. Configure embedding.enabled: true in _config.yml
+     *   2. Load the generated config and selected query-embedder script first
+     *   3. Use the same model and preprocessing at build and query time
+     *
+     * The embedder may return an array, typed array, or Promise of either.
+     */
+    var SIMILARITY_THRESHOLD = 0.3;
+    var MAX_QUERY_CACHE_ENTRIES = 100;
+    var queryEmbeddingCache = new Map();
+
+    function cacheQueryEmbedding(query, value) {
+        queryEmbeddingCache.delete(query);
+        queryEmbeddingCache.set(query, value);
+        if (queryEmbeddingCache.size > MAX_QUERY_CACHE_ENTRIES) {
+            queryEmbeddingCache.delete(queryEmbeddingCache.keys().next().value);
+        }
+    }
+
+    function normalizeVector(value) {
+        var vector = null;
+        if (Array.isArray(value)) {
+            vector = value;
+        } else if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(value)) {
+            vector = Array.from(value);
+        }
+        if (!vector || vector.length === 0 || !vector.every(function (entry) {
+            return typeof entry === "number" && Number.isFinite(entry);
+        })) {
+            return null;
+        }
+        return vector;
+    }
+
+    function cosineSimilarity(a, b) {
+        if (!a || !b || a.length !== b.length) {
+            return 0;
+        }
+        var dot = 0;
+        var normA = 0;
+        var normB = 0;
+        for (var i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        var denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dot / denom;
+    }
+
+    window.ClientSearchAdapters = window.ClientSearchAdapters || {};
+    window.ClientSearchAdapters.semantic = {
+        name: "semantic",
+
+        available: function () {
+            return typeof window.ClientSearchQueryEmbedder === "function";
+        },
+
+        buildIndex: function (documents) {
+            var expectedDimension = null;
+            return documents.filter(function (doc) {
+                var embedding = normalizeVector(doc.embedding);
+                if (!embedding) {
+                    return false;
+                }
+                if (expectedDimension === null) {
+                    expectedDimension = embedding.length;
+                } else if (embedding.length !== expectedDimension) {
+                    throw new RangeError("Document embedding dimensions do not match");
+                }
+                return true;
+            });
+        },
+
+        search: function (index, query, _options) {
+            if (typeof window.ClientSearchQueryEmbedder !== "function" || index.length === 0) {
+                return [];
+            }
+
+            var cached = queryEmbeddingCache.get(query);
+            if (cached) {
+                cacheQueryEmbedding(query, cached);
+                return cached && typeof cached.then === "function"
+                    ? cached.then(function (embedding) { return rank(index, embedding); })
+                    : rank(index, cached);
+            }
+
+            var result = window.ClientSearchQueryEmbedder(query);
+            if (result && typeof result.then === "function") {
+                var pending = result.then(function (queryEmbedding) {
+                    var normalized = normalizeVector(queryEmbedding);
+                    if (!normalized) {
+                        throw new TypeError("Query embedding must contain finite numeric values");
+                    }
+                    cacheQueryEmbedding(query, normalized);
+                    return normalized;
+                }).catch(function (error) {
+                    queryEmbeddingCache.delete(query);
+                    throw error;
+                });
+                cacheQueryEmbedding(query, pending);
+                return pending.then(function (embedding) { return rank(index, embedding); });
+            }
+            var normalized = normalizeVector(result);
+            if (!normalized) {
+                throw new TypeError("Query embedding must contain finite numeric values");
+            }
+            cacheQueryEmbedding(query, normalized);
+            return rank(index, normalized);
+        }
+    };
+
+    function rank(index, queryEmbedding) {
+        var expectedDimension = index[0] && index[0].embedding.length;
+        if (expectedDimension && queryEmbedding.length !== expectedDimension) {
+            throw new RangeError(
+                "Query embedding dimension " + queryEmbedding.length +
+                " does not match document dimension " + expectedDimension
+            );
+        }
+        return index.map(function (doc) {
+            return {
+                ref: doc.id,
+                score: cosineSimilarity(queryEmbedding, doc.embedding)
+            };
+        }).filter(function (match) {
+            return match.score >= SIMILARITY_THRESHOLD;
+        }).sort(function (a, b) {
+            return b.score - a.score;
+        });
+    }
+
+    if (window.ClientSearch) {
+        window.ClientSearch.run(window.ClientSearchAdapters.semantic);
+    }
+}());

data/assets/client-search-base.js

@@ -0,0 +1,294 @@
+(function () {
+    "use strict";
+
+    /**
+     * ClientSearch base runtime — engine-agnostic shell.
+     *
+     * Owns the uniform query model and the two-stage search strategy:
+     *   1. Exact AND search with prefix matching.
+     *   2. Fuzzy OR fallback when AND yields no results.
+     *
+     * The search engine itself is supplied by an adapter that translates
+     * the uniform query into the engine's native format and translates
+     * results back. The adapter interface is:
+     *
+     *   adapter.name        — string identifier
+     *   adapter.available() — returns true when the engine library is loaded
+     *   adapter.buildIndex(documents) — returns an engine-specific index
+     *   adapter.search(index, query, options) — translates the uniform
+     *       query { combineWith: "AND"|"OR", fuzzy: bool, prefix: bool }
+     *       into the engine's native call and returns [{ ref, score }] or a
+     *       Promise of that array in descending score order
+     *
+     * This keeps the invocation contract and rendering uniform across adapters.
+     */
+    window.ClientSearch = {
+        run: function (adapter) {
+            var options = Object.assign({
+                form: "#search-form",
+                input: "#search-query",
+                status: "#search-status",
+                results: "#search-results",
+                sortControl: "#search-sort",
+                sort: "relevance",
+                indexUrl: window.searchIndexUrl
+            }, window.clientSearchConfig || {});
+            options.liveSearch = Object.assign({
+                enabled: false,
+                minChars: 2,
+                debounceMs: 150,
+                updateUrl: true
+            }, options.liveSearch || {});
+
+            var form = document.querySelector(options.form);
+            var input = document.querySelector(options.input);
+            var status = document.querySelector(options.status);
+            var results = document.querySelector(options.results);
+            var index = null;
+            var documentsById = new Map();
+            var liveSearchTimer = null;
+            var renderVersion = 0;
+            var activeStatusVersion = 0;
+
+            if (!form || !input || !status || !results || !options.indexUrl) {
+                return;
+            }
+            if (!adapter.available()) {
+                status.textContent = "Search is temporarily unavailable.";
+                return;
+            }
+
+            function normalize(entry) {
+                var id = entry.id || entry.url;
+                if (!id) {
+                    return null;
+                }
+                var categories = Array.isArray(entry.categories) ? entry.categories : [];
+                var tags = Array.isArray(entry.tags) ? entry.tags : [];
+                var normalized = {
+                    id: id,
+                    title: entry.title || "Untitled",
+                    url: entry.url || "#",
+                    excerpt: entry.excerpt || "",
+                    content: entry.content || "",
+                    date: entry.date || "",
+                    date_timestamp: Number(entry.date_timestamp) || 0,
+                    categories: categories,
+                    tags: tags,
+                    categoriesText: categories.join(" "),
+                    tagsText: tags.join(" ")
+                };
+                if (Array.isArray(entry.embedding) && entry.embedding.length > 0) {
+                    normalized.embedding = entry.embedding;
+                }
+                return normalized;
+            }
+
+            function buildIndex(data) {
+                if (!Array.isArray(data)) {
+                    throw new TypeError("Search index must be an array");
+                }
+
+                var documents = data.map(normalize).filter(Boolean);
+                documentsById = new Map(documents.map(function (entry) {
+                    return [entry.id, entry];
+                }));
+                index = adapter.buildIndex(documents);
+            }
+
+            async function search(query) {
+                if (!index) {
+                    return [];
+                }
+                var exact = await adapter.search(index, query, {
+                    combineWith: "AND",
+                    fuzzy: false,
+                    prefix: true
+                });
+                if (exact.length > 0) {
+                    return exact;
+                }
+                return await adapter.search(index, query, {
+                    combineWith: "OR",
+                    fuzzy: true,
+                    prefix: true
+                });
+            }
+
+            function safeUrl(value) {
+                if (value === "#") {
+                    return "#";
+                }
+                try {
+                    var url = new URL(value, window.location.origin);
+                    if (url.origin === window.location.origin && ["http:", "https:"].includes(url.protocol)) {
+                        return url.pathname + url.search + url.hash;
+                    }
+                } catch (_error) {
+                    return "#";
+                }
+                return "#";
+            }
+
+            function resultElement(match) {
+                var entry = documentsById.get(match.ref);
+                if (!entry) {
+                    return null;
+                }
+                var article = document.createElement("article");
+                var heading = document.createElement("h2");
+                var titleLink = document.createElement("a");
+                var excerpt = document.createElement("p");
+                var readMore = document.createElement("a");
+                var url = safeUrl(entry.url);
+
+                article.className = "box client-search-result";
+                heading.className = "title is-4";
+                titleLink.href = url;
+                titleLink.textContent = entry.title;
+                excerpt.textContent = entry.excerpt;
+                readMore.href = url;
+                readMore.textContent = "Read more";
+                heading.appendChild(titleLink);
+                article.append(heading, excerpt, readMore);
+                return article;
+            }
+
+            function sortMatches(matches) {
+                var sortControl = document.querySelector(options.sortControl);
+                var sortOrder = sortControl ? sortControl.value : options.sort;
+                if (sortOrder !== "date") {
+                    return matches;
+                }
+                return matches.slice().sort(function (a, b) {
+                    var first = documentsById.get(a.ref);
+                    var second = documentsById.get(b.ref);
+                    return (second ? second.date_timestamp : 0) - (first ? first.date_timestamp : 0) ||
+                        (b.score || 0) - (a.score || 0);
+                });
+            }
+
+            function updateUrl() {
+                var url = new URL(window.location.href);
+                if (input.value.trim()) {
+                    url.searchParams.set("q", input.value.trim());
+                } else {
+                    url.searchParams.delete("q");
+                }
+                window.history.replaceState({}, "", url);
+            }
+
+            function showSearchError() {
+                status.textContent = "Search is temporarily unavailable.";
+                results.replaceChildren();
+            }
+
+            async function render() {
+                var query = input.value.trim();
+                var version = ++renderVersion;
+                activeStatusVersion = version;
+                if (!query) {
+                    activeStatusVersion = 0;
+                    status.textContent = "Search articles by title, text, category, or tag.";
+                    results.replaceChildren();
+                    return;
+                }
+
+                status.textContent = "Searching…";
+                var matches;
+                try {
+                    matches = await search(query);
+                } catch (error) {
+                    if (version !== renderVersion) {
+                        return;
+                    }
+                    activeStatusVersion = 0;
+                    throw error;
+                }
+                if (version !== renderVersion) {
+                    return;
+                }
+                activeStatusVersion = 0;
+                matches = sortMatches(matches);
+                status.textContent = matches.length + " result" + (matches.length === 1 ? "" : "s");
+                if (matches.length === 0) {
+                    var empty = document.createElement("div");
+                    empty.className = "notification is-info";
+                    empty.textContent = "No articles found.";
+                    results.replaceChildren(empty);
+                    return;
+                }
+                results.replaceChildren.apply(
+                    results,
+                    matches.map(resultElement).filter(Boolean)
+                );
+            }
+
+            function runRender() {
+                render().catch(showSearchError);
+            }
+
+            window.addEventListener("client-search:status", function (event) {
+                if (activeStatusVersion === renderVersion && event.detail && event.detail.message) {
+                    status.textContent = event.detail.message;
+                }
+            });
+
+            input.addEventListener("input", function () {
+                renderVersion += 1;
+                activeStatusVersion = 0;
+                clearTimeout(liveSearchTimer);
+                if (!options.liveSearch.enabled || !index) {
+                    return;
+                }
+
+                var query = input.value.trim();
+                if (options.liveSearch.updateUrl) {
+                    updateUrl();
+                }
+                if (!query) {
+                    runRender();
+                    return;
+                }
+                if (query.length < options.liveSearch.minChars) {
+                    status.textContent = "Type at least " + options.liveSearch.minChars + " characters.";
+                    results.replaceChildren();
+                    return;
+                }
+
+                status.textContent = "Waiting to search…";
+                liveSearchTimer = setTimeout(runRender, options.liveSearch.debounceMs);
+            });
+
+            form.addEventListener("submit", function (event) {
+                event.preventDefault();
+                clearTimeout(liveSearchTimer);
+                updateUrl();
+                runRender();
+            });
+
+            var sortControl = document.querySelector(options.sortControl);
+            if (sortControl) {
+                sortControl.addEventListener("change", runRender);
+            }
+
+            status.textContent = "Loading search index…";
+            fetch(options.indexUrl, { headers: { Accept: "application/json" } })
+                .then(function (response) {
+                    if (!response.ok) {
+                        throw new Error("Unable to load search index");
+                    }
+                    return response.json();
+                })
+                .then(function (data) {
+                    buildIndex(data);
+                    input.value = new URLSearchParams(window.location.search).get("q") || "";
+                    return render();
+                })
+                .catch(function () {
+                    status.textContent = "Search is temporarily unavailable.";
+                    results.replaceChildren();
+                });
+        }
+    };
+}());