From 6a2932fb5b816dee23ee155f427ff341ce8e406b Mon Sep 17 00:00:00 2001
From: Michael Falk <michael@co-pilot.ca>
Date: Wed, 17 Jun 2026 11:26:39 -0700
Subject: [PATCH] =?UTF-8?q?feat:=20a11y=20completion,=20AbortSignal=20for?=
 =?UTF-8?q?=20async=20sources,=20grouped=20options=20=E2=80=94=20v3.2.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tier 1 of the feature roadmap:

- Accessibility: ARIA combobox/listbox pattern. Options get stable ids; active
  row gets aria-selected and is referenced by the input's aria-activedescendant;
  input gains aria-controls/aria-haspopup; a visually-hidden aria-live region
  announces result counts, "Searching…", and the no-matches/create state.
- AbortSignal: async source ctx now carries a real `signal` (a newer search
  aborts the previous; remoteSource passes it to fetch; destroy() aborts too).
  Fixes the doc/code mismatch where `signal` was documented but never provided.
- Grouped options: groupBy(option) fn or per-option `group` field render
  optgroup-style headings (.liveselect__group); results stably reordered.

Includes 4 new jsdom tests (30 total), CSS for group headings, README sections
(Grouped options, Accessibility) + options-table rows, a grouped-options demo in
examples/vanilla.html, and CHANGELOG/version bump to 3.2.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md          |  20 +++++++
 README.md             |  46 ++++++++++++++-
 dist/liveselect.css   |   9 +++
 dist/liveselect.js    | 132 +++++++++++++++++++++++++++++++++++++-----
 examples/vanilla.html |  22 +++++++
 package.json          |   2 +-
 test/client.test.js   |  80 ++++++++++++++++++++++++-
 7 files changed, 295 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b865f77..dfd134f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,26 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [3.2.0] - 2026-06-17
+
+### Added
+- **Accessibility (ARIA combobox/listbox pattern).** Options now get stable `id`s;
+  the active row carries `aria-selected` and is referenced by the input's
+  `aria-activedescendant`; the input gains `aria-controls` / `aria-haspopup`; and a
+  visually-hidden `aria-live="polite"` region announces result counts, “Searching…”,
+  and the no-matches/create state. Keyboard nav is now announced to screen readers.
+- **AbortSignal for async sources.** The async `source` `ctx` now includes a real
+  `signal` (`{ scope, limit, query, signal }`). A newer search aborts the previous
+  one's signal, and the built-in `remoteSource` passes it to `fetch`, so stale
+  in-flight requests are cancelled rather than merely ignored. (`destroy()` also
+  aborts any in-flight request.)
+- **Grouped options.** Pass a `groupBy(option) => string` function or a per-option
+  `group` field to render `<optgroup>`-style headings (`.liveselect__group`).
+  Results are stably reordered so same-group items sit together.
+
+### Changed
+- `normalizeOption` output now includes a `group` field (`''` when absent).
+
 ## [3.1.0] - 2026-06-17
 
 ### Added
diff --git a/README.md b/README.md
index 1b1d755..e7be33b 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ Node/Express, EJS templates, and Blaze**.
 - 🔁 **Drop-in `<select>` replacement** — `LiveSelect.enhance(selectEl)` upgrades an existing `<select>` in place; a hidden `<input name>` means it submits inside a plain `<form>` like a native control.
 - 🎨 **Fully themeable** — restyle with `--liveselect-*` CSS custom properties or target the BEM-ish classes; ships a light and dark theme.
 - 🧩 **Custom item templates** — render each result row _and_ the `[+ Add]` row however you like with `renderOption` / `renderCreate`; return a DOM node (XSS-safe) or an HTML string. See [Custom item templates](#custom-item-templates).
+- ♿ **Accessible by default** — full ARIA combobox/listbox wiring (`aria-activedescendant`, `aria-selected`, live-region announcements) so keyboard nav is screen-reader friendly. Optional **grouped options** with `<optgroup>`-style headings.
 - 🔒 **Security-hardened server** — registry-gated collection access, field allow-listing, ReDoS-capped regex, scope filters, tenant isolation hook, prototype-pollution guards.
 - 📦 **Zero dependencies**, ~12 KB. Works as a `<script>` tag (`window.LiveSelect`), a CommonJS `require`, or an ES module `import`.
 
@@ -173,13 +174,18 @@ per-framework integration (HTML, Express, EJS, Blaze).
 | `renderCreate` | `(q, ctx) => Node\|string\|null` | — | Custom template for the `[+ Add]` row. |
 | `onCreate` | `async (q, ctx) => option\|null` | — | Do anything; return an option to auto-select. |
 | `onChange` | `(value, option) => void` | — | Fires on every selection/clear. |
+| `groupBy` | `(option) => string` | — | Group results under headings. See [Grouped options](#grouped-options). |
 | `classPrefix` | `string` | `'liveselect'` | CSS class prefix. |
 | `texts` | `object` | — | `{ searching, noResults, searchFailed }`. |
 
-**Option shape:** `{ value, label, sublabel?, raw? }`. Loose input is normalized —
+**Option shape:** `{ value, label, sublabel?, group?, raw? }`. Loose input is normalized —
 a bare string becomes `{ value, label }`; `_id`/`id` map to `value`;
 `name`/`title`/`text` map to `label`.
 
+**Async source `ctx`:** `{ scope, limit, query, signal }`. `signal` is an
+`AbortSignal` that fires when a newer search supersedes the current one — pass it
+to `fetch` (the built-in `remoteSource` already does) to cancel stale requests.
+
 ## Custom item templates
 
 By default each row renders an escaped two-line `label` / `sublabel`. To render
@@ -220,6 +226,44 @@ The normalized option passed in is `{ value, label, sublabel, raw }`, where
 label/sublabel. The `createLabel` option still works for a plain-text add row;
 `renderCreate` supersedes it when both are set.
 
+## Grouped options
+
+Render results under headings (like `<optgroup>`) by giving options a `group`
+field, or by passing a `groupBy(option) => string` function (which takes
+precedence). Results are **stably reordered** so same-group items sit together,
+preserving the order each group was first seen — so your source doesn't have to
+pre-sort.
+
+```js
+new LiveSelect('#picker', {
+  source: [
+    { value: 'ca', label: 'California', group: 'US' },
+    { value: 'on', label: 'Ontario',    group: 'Canada' },
+    { value: 'tx', label: 'Texas',      group: 'US' },
+  ],
+  // or, instead of per-option group:
+  // groupBy: (opt) => opt.raw.country,
+});
+```
+
+Group headings render as `.liveselect__group` (a non-selectable, sticky label) —
+style them like any other token.
+
+## Accessibility
+
+The control implements the [ARIA combobox/listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
+
+- the input is `role="combobox"` with `aria-expanded`, `aria-controls`, and
+  `aria-autocomplete="list"`;
+- the menu is `role="listbox"`; each row is `role="option"` with a stable `id`;
+- the active row carries `aria-selected="true"` and the input's
+  `aria-activedescendant` points at it, so arrow-key navigation is announced;
+- a visually-hidden `aria-live="polite"` region announces result counts,
+  “Searching…”, and the no-matches / create state.
+
+Full keyboard support: ↑/↓ to move, Enter to select (or trigger `[+ Add]`),
+Esc to close.
+
 ## Instance API
 
 ```
diff --git a/dist/liveselect.css b/dist/liveselect.css
index cf31e02..2600376 100644
--- a/dist/liveselect.css
+++ b/dist/liveselect.css
@@ -108,6 +108,15 @@
 .liveselect__opt-label { font-weight: 600; }
 .liveselect__opt-sub   { font-size: 0.82rem; color: var(--liveselect-text-muted); }
 
+/* Group heading (from groupBy / option.group): non-selectable, sticky label. */
+.liveselect__group {
+  position: sticky; top: -6px;
+  padding: 8px 12px 4px;
+  background: var(--liveselect-surface);
+  color: var(--liveselect-text-muted);
+  font-size: 0.72rem; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase;
+}
+
 .liveselect__msg   { padding: 10px 12px; color: var(--liveselect-text-muted); font-size: 0.92rem; }
 .liveselect__error { color: var(--liveselect-danger); font-size: 0.82rem; }
 .liveselect__error[hidden] { display: none; }
diff --git a/dist/liveselect.js b/dist/liveselect.js
index 177643e..3fe6b07 100644
--- a/dist/liveselect.js
+++ b/dist/liveselect.js
@@ -24,7 +24,10 @@
  *
  * OPTIONS (all optional unless noted):
  *   source        (required) Array<option|string> OR
- *                 async (query, ctx) => Array<option>.  ctx = { scope, limit, signal }
+ *                 async (query, ctx) => Array<option>.
+ *                 ctx = { scope, limit, query, signal } — `signal` is an
+ *                 AbortSignal that fires when a newer search supersedes this one,
+ *                 so an async source can cancel its in-flight request.
  *   name          hidden-input name for plain-form usage
  *   value         initial/controlled selected value
  *   valueLabel    label for `value` (skips a resolve round-trip in edit mode)
@@ -54,6 +57,9 @@
  *                 POST to a server, push to the array); return the new option to
  *                 auto-select it, or null to cancel.
  *   onChange      (value, option) => void — called on every selection/clear
+ *   groupBy       (option) => string — group results under headings. Falls back
+ *                 to each option's `group` field. Results are stably reordered so
+ *                 same-group items sit together (first-seen group order kept).
  *   classPrefix   CSS class prefix (default 'liveselect')
  *   texts         { searching, noResults, searchFailed } message overrides
  *
@@ -71,6 +77,10 @@
 
   var BLUR_CLOSE_MS = 150;
 
+  // Per-page counter → stable, unique ids for ARIA wiring (aria-activedescendant
+  // needs each option to have a DOM id the input can point at).
+  var uidSeq = 0;
+
   var DEFAULT_TEXTS = {
     searching:    'Searching…',
     noResults:    'No matches.',
@@ -89,7 +99,7 @@
   function normalizeOption(o) {
     if (o == null) return null;
     if (typeof o === 'string' || typeof o === 'number') {
-      return { value: String(o), label: String(o), sublabel: '', raw: o };
+      return { value: String(o), label: String(o), sublabel: '', group: '', raw: o };
     }
     var value = o.value != null ? o.value
       : (o._id != null ? o._id : (o.id != null ? o.id : ''));
@@ -99,6 +109,7 @@
       value:    value == null ? '' : String(value),
       label:    label == null || label === '' ? '(unnamed)' : String(label),
       sublabel: o.sublabel != null ? String(o.sublabel) : '',
+      group:    o.group != null ? String(o.group) : '',
       raw:      Object.prototype.hasOwnProperty.call(o, 'raw') ? o.raw : o,
     };
   }
@@ -129,6 +140,7 @@
     this.opts = options || {};
     this.host = host;
     this.cp   = this.opts.classPrefix || 'liveselect';
+    this.uid  = this.cp + '-' + (++uidSeq);
     this.texts = Object.assign({}, DEFAULT_TEXTS, this.opts.texts || {});
 
     // state
@@ -143,6 +155,7 @@
     this._debounce   = null;
     this._blurTimer  = null;
     this._reqSeq     = 0;
+    this._abort      = null;   // AbortController for the in-flight async search
 
     this._build();
     this._bind();
@@ -182,11 +195,16 @@
         '<input type="text" class="' + cp + '__input" autocomplete="off" spellcheck="false"' +
           (o.disabled ? ' disabled' : '') +
           ' placeholder="' + escapeHtml(o.placeholder || 'Search…') + '"' +
-          ' role="combobox" aria-expanded="false" aria-autocomplete="list" data-liveselect-input>' +
+          ' role="combobox" aria-expanded="false" aria-autocomplete="list"' +
+          ' aria-haspopup="listbox" aria-controls="' + this.uid + '-menu" data-liveselect-input>' +
         '<button type="button" class="' + cp + '__clear" data-liveselect-clear aria-label="Clear selection" hidden>&times;</button>' +
-        '<div class="' + cp + '__menu" role="listbox" data-liveselect-menu hidden></div>' +
+        '<div class="' + cp + '__menu" id="' + this.uid + '-menu" role="listbox" data-liveselect-menu hidden></div>' +
       '</div>' +
       '<span class="' + cp + '__error" data-liveselect-error hidden></span>' +
+      // Visually-hidden polite live region: announces result counts / states to
+      // screen readers without a visible change.
+      '<span class="' + cp + '__sr" data-liveselect-live aria-live="polite" role="status"' +
+        ' style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0"></span>' +
       '<input type="hidden" data-liveselect-hidden' +
         (o.name ? ' name="' + escapeHtml(o.name) + '"' : '') +
         (o.required ? ' required' : '') + ' value="">';
@@ -197,6 +215,7 @@
     this.clearEl = root.querySelector('[data-liveselect-clear]');
     this.menu    = root.querySelector('[data-liveselect-menu]');
     this.errorEl = root.querySelector('[data-liveselect-error]');
+    this.liveEl  = root.querySelector('[data-liveselect-live]');
     this.hidden  = root.querySelector('[data-liveselect-hidden]');
   };
 
@@ -276,7 +295,7 @@
           || (o.sublabel && o.sublabel.toLowerCase().indexOf(ql) !== -1);
       });
       this.error = '';
-      this.results = filtered.slice(0, limit);
+      this.results = this._group(filtered.slice(0, limit));
       this.activeIndex = -1;
       this._renderMenu();
       return;
@@ -285,20 +304,29 @@
     // Async source → call function, guard against out-of-order responses.
     if (typeof src === 'function') {
       var seq = ++this._reqSeq;
+      // Cancel the previous in-flight request, then hand this one a fresh signal.
+      if (this._abort) this._abort.abort();
+      this._abort = (typeof AbortController !== 'undefined') ? new AbortController() : null;
       this.loading = true;
       this.error = '';
       this._renderMenu();
-      var ctx = { scope: this.opts.scope || {}, limit: limit, query: q };
+      var ctx = {
+        scope: this.opts.scope || {},
+        limit: limit,
+        query: q,
+        signal: this._abort ? this._abort.signal : undefined,
+      };
       Promise.resolve(src(q, ctx))
         .then(function (res) {
           if (seq !== self._reqSeq) return; // a newer search superseded this one
           self.loading = false;
-          self.results = normalizeList(res).slice(0, limit);
+          self.results = self._group(normalizeList(res).slice(0, limit));
           self.activeIndex = -1;
           self._renderMenu();
         })
         .catch(function (err) {
-          if (seq !== self._reqSeq) return;
+          if (seq !== self._reqSeq) return;            // superseded → ignore
+          if (err && err.name === 'AbortError') return; // we cancelled it → ignore
           self.loading = false;
           self.results = [];
           self.error = (err && (err.message || err.reason)) || self.texts.searchFailed;
@@ -313,6 +341,38 @@
     this._renderMenu();
   };
 
+  /** The group label for an option: opts.groupBy wins, else the option's `group`. */
+  LiveSelect.prototype._groupOf = function (o) {
+    if (typeof this.opts.groupBy === 'function') {
+      var g = this.opts.groupBy(o);
+      return g == null ? '' : String(g);
+    }
+    return o.group || '';
+  };
+
+  /**
+   * Stably reorder a result list so same-group items sit together, preserving
+   * the order each group was first seen. No-op when nothing is grouped, so the
+   * common (ungrouped) path keeps its original order and cost.
+   */
+  LiveSelect.prototype._group = function (list) {
+    var grouped = typeof this.opts.groupBy === 'function';
+    if (!grouped) {
+      for (var i = 0; i < list.length; i++) { if (list[i].group) { grouped = true; break; } }
+    }
+    if (!grouped) return list;
+
+    var order = [], buckets = {}, self = this;
+    list.forEach(function (o) {
+      var g = self._groupOf(o);
+      if (!buckets[g]) { buckets[g] = []; order.push(g); }
+      buckets[g].push(o);
+    });
+    var out = [];
+    order.forEach(function (g) { out.push.apply(out, buckets[g]); });
+    return out;
+  };
+
   // -- create row ------------------------------------------------------------
 
   LiveSelect.prototype._canCreate = function () {
@@ -439,6 +499,23 @@
     return el;
   };
 
+  /** Push a message into the polite live region for screen readers. */
+  LiveSelect.prototype._announce = function (msg) {
+    if (this.liveEl) this.liveEl.textContent = msg || '';
+  };
+
+  /** Announce the result count (or empty/create state) after a render. */
+  LiveSelect.prototype._announceResults = function (canCreate) {
+    var n = this.results.length;
+    if (n > 0) {
+      this._announce(n + (n === 1 ? ' result available.' : ' results available.'));
+    } else if (canCreate) {
+      this._announce(this.texts.noResults + ' Press Enter to add.');
+    } else {
+      this._announce(this.texts.noResults);
+    }
+  };
+
   /**
    * Apply a renderOption/renderCreate return value to a row element.
    *   - DOM Node  → appended as-is (XSS-safe by construction)
@@ -498,24 +575,42 @@
     if (!this.isOpen) { this.menu.hidden = true; return; }
 
     this.menu.textContent = '';   // clear previous rows
+    this.input.removeAttribute('aria-activedescendant');
 
     if (this.loading) {
       this.menu.appendChild(this._msgEl(this.texts.searching));
       this.menu.hidden = false;
+      this._announce(this.texts.searching);
       this._renderError();
       return;
     }
 
+    var lastGroup = null, activeId = null;
     for (var i = 0; i < this.results.length; i++) {
       var o = this.results[i];
+      var g = this._groupOf(o);
+      if (g && g !== lastGroup) {
+        var head = document.createElement('div');
+        head.className = cp + '__group';
+        head.setAttribute('role', 'presentation');
+        head.textContent = g;          // textContent → group labels are escaped too
+        this.menu.appendChild(head);
+      }
+      lastGroup = g;
+
+      var isActive = this.activeIndex === i;
+      var optId = this.uid + '-opt-' + i;
       var btn = document.createElement('button');
       btn.type = 'button';
+      btn.id = optId;
       btn.setAttribute('role', 'option');
-      btn.className = cp + '__opt' + (this.activeIndex === i ? ' ' + cp + '__opt--active' : '');
+      btn.setAttribute('aria-selected', isActive ? 'true' : 'false');
+      btn.className = cp + '__opt' + (isActive ? ' ' + cp + '__opt--active' : '');
       btn.setAttribute('data-liveselect-opt', '');
       btn.setAttribute('data-liveselect-index', String(i));
       this._fillOption(btn, o, i);
       this.menu.appendChild(btn);
+      if (isActive) activeId = optId;
     }
 
     var canCreate = this._canCreate();
@@ -523,16 +618,23 @@
       this.menu.appendChild(this._msgEl(this.texts.noResults));
     }
     if (canCreate) {
-      var createActive = this.activeIndex === this.results.length ? (' ' + cp + '__opt--active') : '';
+      var createOn = this.activeIndex === this.results.length;
+      var createId = this.uid + '-create';
       var cbtn = document.createElement('button');
       cbtn.type = 'button';
-      cbtn.className = cp + '__opt ' + cp + '__opt--create' + createActive;
+      cbtn.id = createId;
+      cbtn.setAttribute('role', 'option');
+      cbtn.setAttribute('aria-selected', createOn ? 'true' : 'false');
+      cbtn.className = cp + '__opt ' + cp + '__opt--create' + (createOn ? ' ' + cp + '__opt--active' : '');
       cbtn.setAttribute('data-liveselect-create', '');
       this._fillCreate(cbtn, this.query.trim());
       this.menu.appendChild(cbtn);
+      if (createOn) activeId = createId;
     }
 
+    if (activeId) this.input.setAttribute('aria-activedescendant', activeId);
     this.menu.hidden = false;
+    this._announceResults(canCreate);
     this._renderError();
   };
 
@@ -615,6 +717,7 @@
   LiveSelect.prototype.destroy = function () {
     clearTimeout(this._debounce);
     clearTimeout(this._blurTimer);
+    if (this._abort) { this._abort.abort(); this._abort = null; }
     this.input.removeEventListener('input', this._onInput);
     this.input.removeEventListener('focus', this._onFocus);
     this.input.removeEventListener('blur', this._onBlur);
@@ -728,8 +831,11 @@
 
     var api = {
       source: function (query, ctx) {
-        return f(base + '/search?' + qs(query, ctx), { headers: headers, credentials: 'same-origin' })
-          .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); });
+        return f(base + '/search?' + qs(query, ctx), {
+          headers: headers,
+          credentials: 'same-origin',
+          signal: ctx && ctx.signal,   // cancels when a newer search supersedes this one
+        }).then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); });
       },
       resolve: function (value) {
         return f(base + '/option/' + encodeURIComponent(value), { headers: headers, credentials: 'same-origin' })
diff --git a/examples/vanilla.html b/examples/vanilla.html
index 498d171..7f6840b 100644
--- a/examples/vanilla.html
+++ b/examples/vanilla.html
@@ -65,6 +65,11 @@ <h2>4 · Custom item templates (avatar · email · tier badge)</h2>
   <div id="picker4"></div>
   <div class="out" id="out4">value: (none)</div>
 
+  <!-- ===== 5. Grouped options ===== -->
+  <h2>5 · Grouped options (optgroup-style headings)</h2>
+  <div id="picker5"></div>
+  <div class="out" id="out5">value: (none)</div>
+
   <!-- 2. The script — exposes window.LiveSelect. -->
   <script src="../dist/liveselect.js"></script>
   <script>
@@ -132,6 +137,23 @@ <h2>4 · Custom item templates (avatar · email · tier badge)</h2>
       return name.split(/\s+/).map(function (p) { return p[0]; }).slice(0, 2).join('').toUpperCase();
     }
 
+    // 5 · Grouped options — out-of-order source, stably grouped under headings.
+    new LiveSelect('#picker5', {
+      label: 'Region',
+      placeholder: 'Search regions…',
+      source: [
+        { value: 'ca', label: 'California',   group: 'United States' },
+        { value: 'on', label: 'Ontario',      group: 'Canada' },
+        { value: 'tx', label: 'Texas',        group: 'United States' },
+        { value: 'bc', label: 'British Columbia', group: 'Canada' },
+        { value: 'ny', label: 'New York',     group: 'United States' },
+      ],
+      onChange: function (value, option) {
+        document.getElementById('out5').textContent =
+          'value: ' + JSON.stringify(value) + (option ? '  ·  ' + option.group : '');
+      },
+    });
+
     new LiveSelect('#picker4', {
       name: 'assignee',
       label: 'Assignee',
diff --git a/package.json b/package.json
index 3905569..a2725ff 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@michaeljfalk/liveselect",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "publishConfig": {
     "access": "public"
   },
diff --git a/test/client.test.js b/test/client.test.js
index fefb10a..1bc8340 100644
--- a/test/client.test.js
+++ b/test/client.test.js
@@ -39,7 +39,7 @@ function mount() {
 
 test('normalizeOption coerces strings and id/name shapes', { skip: !domAvailable }, () => {
   assert.deepEqual(LiveSelect.normalizeOption('apple'),
-    { value: 'apple', label: 'apple', sublabel: '', raw: 'apple' });
+    { value: 'apple', label: 'apple', sublabel: '', group: '', raw: 'apple' });
   const n = LiveSelect.normalizeOption({ _id: 'x1', name: 'Acme' });
   assert.equal(n.value, 'x1');
   assert.equal(n.label, 'Acme');
@@ -190,3 +190,81 @@ test('renderCreate: custom template for the [+ Add] row', { skip: !domAvailable
   assert.equal(createBtn.querySelector('.mk').textContent, 'Create “Zeta”');
   dd.destroy();
 });
+
+test('a11y: options get ids, aria-selected + input aria-activedescendant track the active row', { skip: !domAvailable }, () => {
+  const host = mount();
+  const dd = new LiveSelect(host, {
+    source: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Bravo' }],
+  });
+  // input is wired to the listbox
+  assert.equal(dd.input.getAttribute('role'), 'combobox');
+  assert.equal(dd.input.getAttribute('aria-controls'), dd.menu.id);
+  assert.ok(dd.menu.id, 'menu has an id for aria-controls');
+
+  dd.query = ''; dd.isOpen = true; dd._runSearch();
+  dd.activeIndex = 1; dd._renderMenu();
+
+  const opts = dd.menu.querySelectorAll('[data-liveselect-opt]');
+  assert.equal(opts.length, 2);
+  assert.ok(opts[0].id && opts[1].id, 'each option has an id');
+  assert.equal(opts[1].getAttribute('aria-selected'), 'true');
+  assert.equal(opts[0].getAttribute('aria-selected'), 'false');
+  assert.equal(dd.input.getAttribute('aria-activedescendant'), opts[1].id);
+
+  // live region announces the result count
+  assert.match(dd.liveEl.textContent, /2 results available/);
+  dd.destroy();
+});
+
+test('AbortSignal: a superseding search aborts the previous request signal', { skip: !domAvailable }, () => {
+  if (typeof AbortController === 'undefined') return; // older runtime: feature absent by design
+  const host = mount();
+  let firstSignal = null;
+  const dd = new LiveSelect(host, {
+    debounce: 0,
+    source: (q, ctx) => {
+      if (firstSignal === null) firstSignal = ctx.signal;
+      return new Promise(() => {});   // never resolves → stays in-flight
+    },
+  });
+  dd.query = 'a';  dd._runSearch();   // first request
+  assert.ok(firstSignal, 'source received an AbortSignal in ctx');
+  assert.equal(firstSignal.aborted, false);
+
+  dd.query = 'ab'; dd._runSearch();   // supersedes → must abort the first
+  assert.equal(firstSignal.aborted, true);
+  dd.destroy();
+});
+
+test('grouped options: results are stably reordered and group headers rendered', { skip: !domAvailable }, () => {
+  const host = mount();
+  const dd = new LiveSelect(host, {
+    source: [
+      { value: '1', label: 'Apple',  group: 'Fruit' },
+      { value: '2', label: 'Carrot', group: 'Veg' },
+      { value: '3', label: 'Banana', group: 'Fruit' },
+    ],
+  });
+  dd.query = ''; dd.isOpen = true; dd._runSearch(); dd._renderMenu();
+
+  // Fruit items grouped together first (first-seen order), Veg after.
+  assert.deepEqual(dd.results.map((o) => o.value), ['1', '3', '2']);
+  const heads = Array.from(dd.menu.querySelectorAll('.liveselect__group')).map((h) => h.textContent);
+  assert.deepEqual(heads, ['Fruit', 'Veg']);
+  // Active-index navigation still maps to the (reordered) results array.
+  assert.equal(dd.menu.querySelectorAll('[data-liveselect-opt]').length, 3);
+  dd.destroy();
+});
+
+test('groupBy function takes precedence over option.group', { skip: !domAvailable }, () => {
+  const host = mount();
+  const dd = new LiveSelect(host, {
+    source: [{ value: 'a', label: 'Ann' }, { value: 'b', label: 'Bob' }, { value: 'c', label: 'Amy' }],
+    groupBy: (o) => o.label[0],   // group by first letter
+  });
+  dd.query = ''; dd.isOpen = true; dd._runSearch(); dd._renderMenu();
+  assert.deepEqual(dd.results.map((o) => o.value), ['a', 'c', 'b']); // A-group (Ann, Amy) then B (Bob)
+  const heads = Array.from(dd.menu.querySelectorAll('.liveselect__group')).map((h) => h.textContent);
+  assert.deepEqual(heads, ['A', 'B']);
+  dd.destroy();
+});