jekyll-client-search 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 749a1708fe34bce1624db0eb4d91ea58a569f2663f8d78b8200365188faf7ae4
-  data.tar.gz: 833b1c87a57b2f78a05f42103efef6f9aa2ec09ee0726cad734e0f28f268fc50
+  metadata.gz: 3e0accecae865157aa09bda9bf9df5060bcad7a45eeb55555137f963fe1cca93
+  data.tar.gz: 8bb447d56a507fb5c7a632ae38433606317bccfda3e2cb01388c129617a49b8a
 SHA512:
-  metadata.gz: 169936c38c680b2f4ec657243909aaad0a902b6bbbc52e9c586d3d986651e1529fdfb2d2a9dcde69f997075b8c901c5178b7148d86f064242ee018a228b2e457
-  data.tar.gz: 3e75798e1b41dac7982ca34e83e61e8b28b03b347f6ca60b6e527570a72d4a69a9f5ddf6293197410c6935a699b54a7001b601145c57c7e09302e4f1edf4d426
+  metadata.gz: bcb6ee7ce75d7b75facd5c69db2f0c8479f4e70c0d5e6830b92f65cec936235596f3eb8e97db6621e9b6ec3559868b1f34d3b3ea1b8f5610464b880b88261104
+  data.tar.gz: 1c35127143ea928d0156ba202c0c4e6a485729de69afd69e3203f45d5625e0f00848a17e2f4cfe50f9085b8c61e76d16f81b36e05ffa8f27352cb655a42f5eaf

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.5.0 — 2026-11-08
+
+### Added
+
+- `rake docs:demo` — captures the checked-in illustrative overview as
+  animated AVIF + WebP + static PNG (headless Chrome + ffmpeg + img2webp;
+  build-host tools), embedded in README via `<picture>`. Examples are
+  schematic, not generated from a live Jekyll build.
+
+- Dev-tooling bumps: `markdownlint-cli2` 0.24.0, `eslint` ~10.14.0,
+  `globals` 17.14.0, `rubocop` 1.92.2, `ollama-ruby` 1.26.0,
+  `excon` 1.11.0, `sass-embedded` 1.108.1, `addressable` 2.9.2,
+  `csv` 3.3.7, `io-console` 0.9.5, `parser` 3.3.13.0,
+  `irb` 1.19.0, `tins` 1.62.0; `BUNDLED WITH` 4.0.9 → 4.0.24.
+
+### Changed
+
+- The live dropdown now follows the ARIA combobox/listbox pattern:
+  focused input with `aria-activedescendant`, uniquely identified plain
+  text options, and no nested links inside listbox options.
+- CI Node.js matrix is now `24` / `26` — matching the `engines:
+  >=24` floor. Node 22 dropped (maintenance-only).
+- CI action pins bumped: `ruby/setup-ruby` v1.338.0,
+  `sonarqube-scan-action` v8.4.1, `semgrep` image 1.183.0.
+- `spec/search_index_page_spec.rb` expanded — now covers the default
+  root-level output path (`search-index.json`), an empty document
+  list, and field/order preservation.
+- `test/meta.test.js` cross-engine check split into one named `test()`
+  per exact-match query — a single failure no longer hides the
+  remaining queries.
+
+### Fixed
+
+- Benchmark scripts access environment via `ENV.fetch("KEY", default)`
+  instead of `ENV["KEY"] || default` (SonarQube: environment variable
+  access without a default value).
+- SonarQube coverage denominator no longer counts `benchmarks/**` —
+  the ~850 lines of manual benchmark tooling are not instrumented by
+  SimpleCov, which diluted the reported project coverage to ~50%.
+
+### Security
+
+- `overrides` pins `re2js` 2.8.8 — markdownlint 0.42.0 (via
+  markdownlint-cli2 0.24.0) pins the vulnerable 2.8.6 (ReDoS in
+  lookbehind matching, GHSA-gg6h-894w-4m9c).
+- `nokogiri` 1.19.7 (dev-only, via `ollama-ruby`) — fixes
+  GHSA-3w22-6jfg-527w (use-after-free), GHSA-4p39-36wj-23h4
+  (mutation XSS), GHSA-v995-44v6-5fqm (JRuby SSRF).
+
 ## 0.4.0 — 2026-10-24
 
 - Dev-tooling bump: `jsdom` 30.1.3 (patch).

data/README.developer.md

@@ -20,12 +20,27 @@ Both test suites pass with only the committed Wikipedia fixtures and the
 committed baseline JSON artifacts. No network access or external services
 are required for the default test run.
 
+Specs that need a Jekyll site use `jekyll-test-harness` (`jekyll_build` +
+`jekyll_files` DSL, installed in `spec/spec_helper.rb`) instead of hand-rolled
+`Dir.mktmpdir`/`Jekyll::Site.new` scaffolding — see
+`spec/support/site_helpers.rb` and `spec/generator_spec.rb` for the pattern.
+Note that the gem's `Jekyll::ClientSearch::Generator` subclasses
+`Jekyll::Generator`, so it runs automatically inside `jekyll_build`'s
+`site.process`; specs should assert on the built site directly and stub
+`build_embedding_adapter` (see `stub_embedding_adapter`) before building
+rather than calling `generate` manually. Specs that rebuild the same source
+directory multiple times (`spec/embedding_cache_spec.rb`,
+`spec/system_spec.rb`, Ollama integration) still use their own helpers,
+since the harness builds each site in a fresh temporary directory.
+
 ## Quality checks and git hooks
 
 The project uses a focused quality stack: RuboCop (style), bundler-audit
 (security), RSpec (Ruby tests), `npm test` (JavaScript tests), and Semgrep
 (security scanning). This covers the actionable ground without the
 maintenance burden of additional code-smell tools on a small focused gem.
+`npm test` also runs ESLint, Markdownlint, and jsdom tests for the browser
+runtime, including the dropdown combobox/listbox keyboard and ARIA contract.
 
 External automated code review services:
 
@@ -112,7 +127,7 @@ CI. Skip either with `git commit --no-verify` or `git push --no-verify`.
 ### CI checks
 
 The [CI workflow](.github/workflows/ci.yml) runs on every push and pull
-request across Ruby 3.3/3.4 and Node 22/24:
+request across Ruby 3.3/3.4 and Node 24/26:
 
 - `bundle exec rake ci` (rspec, rubocop, syntax checks, npm test, gem build)
 - `bundle exec bundle-audit check --update` (Ruby dependency security)

data/README.md

@@ -23,6 +23,19 @@ via pre-computed embeddings from a local [Ollama](https://ollama.ai) server.
 Related articles can be generated at build time from shared tags, categories,
 and vector similarity.
 
+<!-- markdownlint-disable MD033 -->
+<picture>
+  <source
+    srcset="docs/assets/jekyll-client-search-demo.avif"
+    type="image/avif">
+  <source
+    srcset="docs/assets/jekyll-client-search-demo.webp"
+    type="image/webp">
+  <img src="docs/assets/jekyll-client-search-demo.png"
+       alt="jekyll-client-search demo">
+</picture>
+<!-- markdownlint-enable MD033 -->
+
 ## Table of contents
 
 - [Lightning start](#lightning-start)
@@ -268,7 +281,8 @@ Tag modes:
   `/search/`) with `?q=...` for full results on the search page
 - Arrow Up/Down → highlight items, Enter on highlighted → navigate
 - Click an item → navigate to that document's URL
-- Escape or click outside → close dropdown
+- Escape → close the popup and keep focus in the combobox; click outside
+  → close the dropdown
 - Index is lazy-loaded on first keystroke (no cost on pages where the
   visitor doesn't search)
 
@@ -289,24 +303,32 @@ and the search index includes that field (e.g. from jekyll-documents),
 an `<img>` icon is rendered before each result title. Set `icon_field:
 null` to disable.
 
-**CSS styling:** The dropdown emits no framework classes. Style with:
+**CSS styling:** The dropdown emits no framework classes. Its input uses
+the ARIA combobox pattern; the popup is a listbox whose options are plain
+text containers (not nested links or controls). Style with:
 
 ```css
 .client-search-dropdown { position: relative; }
-.client-search-dropdown ul[role="listbox"] {
+.client-search-dropdown [role="listbox"] {
   position: absolute; top: 100%; right: 0;
   min-width: 300px; z-index: 30;
   background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+  margin: 0; padding: 0;
+}
+.client-search-dropdown [role="listbox"] ul[role="presentation"] {
   list-style: none; margin: 0; padding: 0;
 }
-.client-search-dropdown li { padding: 0.5rem 1rem; }
-.client-search-dropdown li:hover,
-.client-search-dropdown li[aria-selected="true"] { background: #f5f5f5; }
-.client-search-dropdown li a { text-decoration: none; color: inherit; }
+.client-search-dropdown [role="option"] {
+  cursor: pointer; padding: 0.5rem 1rem;
+}
+.client-search-dropdown [role="option"]:hover,
+.client-search-dropdown [role="option"][aria-selected="true"] {
+  background: #f5f5f5;
+}
 
 /* Type-based styling via data attributes */
-.client-search-dropdown li[data-source="documents"] { border-left: 3px solid #48c774; }
-.client-search-dropdown li[data-file-type="pdf"]::before {
+.client-search-dropdown [role="option"][data-source="documents"] { border-left: 3px solid #48c774; }
+.client-search-dropdown [role="option"][data-file-type="pdf"]::before {
   content: "PDF"; background: #ff0000; color: white;
   padding: 0 0.3em; font-size: 0.7em; margin-right: 0.3em;
 }

data/assets/client-search-dropdown.js

@@ -9,8 +9,8 @@
      * Features:
      *   - Lazy index loading (fetches search-index.json on first keystroke)
      *   - Two-stage search (AND first, fuzzy OR fallback) via engine adapter
-     *   - Compact <li><a> items with optional icon rendering
-     *   - Keyboard navigation (Arrow Up/Down, Enter, Escape)
+     *   - ARIA combobox + listbox with plain-text options and optional icons
+     *   - Active-descendant keyboard navigation (Arrow Up/Down, Enter, Escape)
      *   - Enter with no selection → redirect to redirect_url (?q=...)
      *   - Click outside or Escape → close dropdown
      *   - Multi-instance via [data-client-search-dropdown] attributes
@@ -20,6 +20,8 @@
     var sharedIndex = null;
     var sharedDocuments = null;
     var indexLoadPromise = null;
+    var nextDropdownInstanceId = 0;
+    var initializedRoots = new WeakSet();
 
     function safeUrl(value) {
         if (value === "#") {
@@ -116,25 +118,27 @@
         });
     }
 
-    function createResultItem(match, documents, iconField) {
+    function createResultItem(match, documents, iconField, optionId) {
         var entry = documents.get(match.ref);
         if (!entry) {
             return null;
         }
 
-        var li = document.createElement("li");
-        li.setAttribute("role", "option");
-        li.className = "client-search-dropdown-item";
-        li.dataset.url = safeUrl(entry.url);
+        var option = document.createElement("li");
+        option.id = optionId;
+        option.setAttribute("role", "option");
+        option.setAttribute("aria-selected", "false");
+        option.className = "client-search-dropdown-item";
+        option.dataset.url = safeUrl(entry.url);
 
         if (entry.source) {
-            li.dataset.source = entry.source;
+            option.dataset.source = entry.source;
         }
         if (entry.categories && entry.categories.length) {
-            li.dataset.categories = entry.categories.join(" ");
+            option.dataset.categories = entry.categories.join(" ");
         }
         if (entry.tags && entry.tags.length) {
-            li.dataset.tags = entry.tags.join(" ");
+            option.dataset.tags = entry.tags.join(" ");
         }
         Object.keys(entry).forEach(function (key) {
             var skip = ["id", "title", "url", "excerpt", "content",
@@ -145,7 +149,7 @@
             }
             var value = entry[key];
             if (typeof value === "string" || typeof value === "number") {
-                li.dataset[toCamelCase(key)] = String(value);
+                option.dataset[toCamelCase(key)] = String(value);
             }
         });
 
@@ -153,22 +157,21 @@
             var icon = document.createElement("img");
             icon.className = "client-search-dropdown-icon";
             icon.src = safeUrl(entry[iconField]);
-            icon.alt = entry.file_type || entry.source || "";
+            icon.alt = "";
+            icon.setAttribute("aria-hidden", "true");
             icon.loading = "lazy";
             icon.style.width = "1em";
             icon.style.height = "1em";
             icon.style.verticalAlign = "middle";
-            icon.style.marginRight = "0.3em";
-            li.appendChild(icon);
+            option.appendChild(icon);
         }
 
-        var link = document.createElement("a");
-        link.href = safeUrl(entry.url);
-        link.textContent = entry.title;
-        link.className = "client-search-dropdown-link";
-        li.appendChild(link);
+        var title = document.createElement("span");
+        title.className = "client-search-dropdown-link";
+        title.textContent = entry.title;
+        option.appendChild(title);
 
-        return li;
+        return option;
     }
 
     function DropdownInstance(root, config) {
@@ -176,6 +179,7 @@
         this.form = root.querySelector("[data-cs-dropdown-form]");
         this.input = root.querySelector("[data-cs-dropdown-input]");
         this.results = root.querySelector("[data-cs-dropdown-results]");
+        this.listbox = this.results.closest('[role="listbox"]') || this.results;
         this.config = config;
         this.maxItems = Number.parseInt(this.results.dataset.maxItems, 10) || config.maxItems || 5;
         this.selectedIndex = -1;
@@ -183,6 +187,9 @@
         this.debounceTimer = null;
         this.renderVersion = 0;
         this.adapter = null;
+        this.optionIdPrefix = this.results.id
+            ? this.results.id + "-option"
+            : "cs-dropdown-" + (++nextDropdownInstanceId) + "-option";
     }
 
     DropdownInstance.prototype.init = function () {
@@ -190,6 +197,11 @@
             return;
         }
 
+        this.results.setAttribute("aria-hidden", "true");
+        this.listbox.setAttribute("aria-hidden", "true");
+        this.input.setAttribute("aria-expanded", "false");
+        this.input.removeAttribute("aria-activedescendant");
+
         var self = this;
 
         this.input.addEventListener("input", function () {
@@ -212,9 +224,9 @@
         });
 
         this.results.addEventListener("click", function (event) {
-            var li = event.target.closest("li");
-            if (li && li.dataset.url && li.dataset.url !== "#") {
-                window.location.href = li.dataset.url;
+            var option = event.target.closest('[role="option"]');
+            if (option && option.dataset.url && option.dataset.url !== "#") {
+                window.location.href = option.dataset.url;
             }
         });
     };
@@ -223,10 +235,10 @@
         var self = this;
         this.renderVersion += 1;
         clearTimeout(this.debounceTimer);
+        this.hide();
 
         var query = this.input.value.trim();
         if (!query || query.length < this.config.minChars) {
-            this.hide();
             return;
         }
 
@@ -264,7 +276,6 @@
                 break;
             case "Escape":
                 this.hide();
-                this.input.blur();
                 break;
             case "Tab":
                 this.hide();
@@ -318,6 +329,7 @@
         this.results.replaceChildren();
         this.currentItems = [];
         this.selectedIndex = -1;
+        this.input.removeAttribute("aria-activedescendant");
 
         if (!matches || matches.length === 0) {
             this.hide();
@@ -328,7 +340,12 @@
         var count = Math.min(matches.length, this.maxItems);
 
         for (var i = 0; i < count; i++) {
-            var item = createResultItem(matches[i], documents, iconField);
+            var item = createResultItem(
+                matches[i],
+                documents,
+                iconField,
+                this.optionIdPrefix + "-" + i
+            );
             if (item) {
                 this.results.appendChild(item);
                 this.currentItems.push(item);
@@ -353,18 +370,26 @@
             }
         }
         if (this.currentItems[index]) {
-            this.currentItems[index].scrollIntoView({ block: "nearest" });
+            this.input.setAttribute("aria-activedescendant", this.currentItems[index].id);
+            if (typeof this.currentItems[index].scrollIntoView === "function") {
+                this.currentItems[index].scrollIntoView({ block: "nearest" });
+            }
+        } else {
+            this.input.removeAttribute("aria-activedescendant");
         }
     };
 
     DropdownInstance.prototype.show = function () {
         this.results.setAttribute("aria-hidden", "false");
+        this.listbox.setAttribute("aria-hidden", "false");
         this.input.setAttribute("aria-expanded", "true");
     };
 
     DropdownInstance.prototype.hide = function () {
         this.results.setAttribute("aria-hidden", "true");
+        this.listbox.setAttribute("aria-hidden", "true");
         this.input.setAttribute("aria-expanded", "false");
+        this.input.removeAttribute("aria-activedescendant");
         this.results.replaceChildren();
         this.currentItems = [];
         this.selectedIndex = -1;
@@ -389,6 +414,11 @@
 
         var roots = document.querySelectorAll("[data-client-search-dropdown]");
         roots.forEach(function (root) {
+            if (initializedRoots.has(root)) {
+                return;
+            }
+            initializedRoots.add(root);
+
             var instance = new DropdownInstance(root, mergedConfig);
             instance.init();
         });

data/lib/jekyll/client_search/dropdown_tag.rb

@@ -87,13 +87,17 @@ module Jekyll
           <div class="client-search-dropdown" data-client-search-dropdown>
             <form role="search" autocomplete="off" data-cs-dropdown-form>
               <label class="sr-only" for="#{@input_id}">Search</label>
-              <input id="#{@input_id}" type="search" name="q"
+              <input id="#{@input_id}" type="search" name="q" role="combobox"
+                     aria-autocomplete="list" aria-haspopup="listbox"
                      placeholder="Search…" autocomplete="off"
                      aria-expanded="false" aria-controls="#{@results_id}"
                      data-cs-dropdown-input>
             </form>
-            <ul id="#{@results_id}" role="listbox" aria-hidden="true"
-                data-cs-dropdown-results data-max-items="#{max}"></ul>
+            <div id="#{@results_id}" role="listbox" aria-label="Search suggestions"
+                 aria-hidden="true">
+              <ul role="presentation" aria-hidden="true"
+                  data-cs-dropdown-results data-max-items="#{max}"></ul>
+            </div>
           </div>
         HTML
       end

data/lib/jekyll/client_search/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module ClientSearch
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-client-search
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Svend Gundestrup