From 7132262303621b0ee35ac103e7c63144a9a0704e Mon Sep 17 00:00:00 2001
From: Michael Falk <michael@co-pilot.ca>
Date: Wed, 17 Jun 2026 11:37:17 -0700
Subject: [PATCH] =?UTF-8?q?feat:=20disabled=20options,=20required=20valida?=
 =?UTF-8?q?tion,=20+=20Tier=203=20polish=20=E2=80=94=20v3.3.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tier 2 (minus multi-select) plus all Tier 3 polish from the roadmap:

- Disabled options: per-option `disabled: true` → non-selectable (dimmed,
  aria-disabled, skipped by keyboard nav, ignored on click/Enter).
- Required validation: enforced via the Constraint Validation API on the
  visible input, so an empty required control blocks submit with a focusable,
  on-screen bubble. Makes enhance()'s required actually enforce (a display:none
  <select> can't be focused). Message via texts.required.
- Match highlighting: `highlight: true` wraps the matched substring in <mark>
  (built from text nodes → still XSS-safe). Ignored for renderOption rows.
- "Showing N of M" footer: array sources compute total; async sources may
  return { items, total }. Customize via texts.more(shown, total).
- Lifecycle events: bubbling liveselect:open / liveselect:close /
  liveselect:search ({ query }).
- Async result caching: `cache: true` keys by query+scope+limit; cleared by
  setSource()/setScope().

6 new jsdom tests (36 total), CSS for disabled/mark/more + dark-mode mark,
README (options table, Events table, Validation section, Features bullet),
example updated (highlight + a disabled row), CHANGELOG/version bump to 3.3.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md          |  25 +++++++
 README.md             |  34 +++++++--
 dist/liveselect.css   |  20 +++++
 dist/liveselect.js    | 167 +++++++++++++++++++++++++++++++++++++-----
 examples/vanilla.html |   4 +-
 package.json          |   2 +-
 test/client.test.js   | 116 ++++++++++++++++++++++++++++-
 7 files changed, 343 insertions(+), 25 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dfd134f..374580a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,31 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [3.3.0] - 2026-06-17
+
+### Added
+- **Disabled options.** A per-option `disabled: true` makes a row non-selectable:
+  dimmed, `aria-disabled`, skipped by keyboard navigation, and ignored on click/Enter.
+- **`required` form validation.** Required controls now enforce selection via the
+  Constraint Validation API on the *visible* input, so an empty required control
+  blocks form submit with a focusable, on-screen validation bubble (message via
+  `texts.required`). This also makes `enhance()`’s `required` actually enforce —
+  previously it was dropped because a `display:none` `<select>` isn’t focusable.
+- **Match highlighting.** `highlight: true` wraps the matched query substring in
+  each result’s label/sublabel with `<mark class="liveselect__mark">` (built from
+  text nodes — still XSS-safe). Ignored for `renderOption` rows.
+- **“Showing N of M” footer.** When results are capped by `limit`, a footer shows
+  the count. Array sources compute the total automatically; async sources can
+  return `{ items, total }`. Customize via `texts.more(shown, total)`.
+- **Lifecycle events.** Bubbling `liveselect:open`, `liveselect:close`, and
+  `liveselect:search` ({ query }) CustomEvents, alongside `liveselect:change`.
+- **Async result caching.** `cache: true` memoizes async results by
+  query+scope+limit so repeat queries skip the network. Cleared by
+  `setSource()` / `setScope()`.
+
+### Changed
+- `normalizeOption` output now includes a `disabled` field (`false` when absent).
+
 ## [3.2.0] - 2026-06-17
 
 ### Added
diff --git a/README.md b/README.md
index e7be33b..48256e0 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,7 @@ Node/Express, EJS templates, and Blaze**.
 - 🎨 **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.
+- 🧰 **Polish where it counts** — real `required` form validation, disabled (non-selectable) options, match highlighting, a “Showing N of M” hint, async result caching, and `open`/`close`/`search` lifecycle events.
 - 🔒 **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`.
 
@@ -175,16 +176,21 @@ per-framework integration (HTML, Express, EJS, Blaze).
 | `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). |
+| `highlight` | `boolean` | `false` | Wrap the matched query substring in each result with `<mark>`. Ignored for `renderOption` rows. |
+| `cache` | `boolean` | `false` | Cache async results by query+scope+limit so repeats skip the network. Cleared by `setSource()`/`setScope()`. |
 | `classPrefix` | `string` | `'liveselect'` | CSS class prefix. |
-| `texts` | `object` | — | `{ searching, noResults, searchFailed }`. |
+| `texts` | `object` | — | `{ searching, noResults, searchFailed, required }`, plus optional `more(shown, total) => string`. |
 
-**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`.
+**Option shape:** `{ value, label, sublabel?, group?, disabled?, raw? }`. Loose input
+is normalized — a bare string becomes `{ value, label }`; `_id`/`id` map to `value`;
+`name`/`title`/`text` map to `label`. `disabled: true` makes a row non-selectable
+(dimmed, skipped by keyboard nav).
 
 **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.
+to `fetch` (the built-in `remoteSource` already does) to cancel stale requests. An
+async source may resolve to a bare array **or** `{ items, total }` — the `total`
+drives the “Showing N of M” footer when results are capped by `limit`.
 
 ## Custom item templates
 
@@ -283,6 +289,24 @@ form.addEventListener('liveselect:change', (e) => {
 });
 ```
 
+It also emits bubbling lifecycle events for integration hooks:
+
+| Event | Detail | Fires when |
+|---|---|---|
+| `liveselect:open` | `{ name }` | the menu opens |
+| `liveselect:close` | `{ name }` | the menu closes |
+| `liveselect:search` | `{ name, query }` | a search runs (after debounce / `minChars`) |
+| `liveselect:change` | `{ name, value, option }` | a selection or clear happens |
+
+## Validation
+
+A `required` LiveSelect enforces selection through the **Constraint Validation
+API on its visible input** — so an empty required control blocks form submit with
+a focusable, on-screen validation bubble (override the message via
+`texts.required`). This also fixes `enhance()`: a `display:none` required
+`<select>` can’t be focused (browsers reject submit with “An invalid form control
+is not focusable”), so `enhance()` moves enforcement to the visible control.
+
 ## Theming
 
 Override any token, globally or scoped to one control:
diff --git a/dist/liveselect.css b/dist/liveselect.css
index 2600376..deee3c6 100644
--- a/dist/liveselect.css
+++ b/dist/liveselect.css
@@ -105,9 +105,27 @@
   flex-direction: row; align-items: center; gap: 8px;
 }
 
+/* Non-selectable option (per-option `disabled: true`). */
+.liveselect__opt--disabled {
+  opacity: 0.5; cursor: not-allowed;
+}
+.liveselect__opt--disabled:hover { background: transparent; }
+
 .liveselect__opt-label { font-weight: 600; }
 .liveselect__opt-sub   { font-size: 0.82rem; color: var(--liveselect-text-muted); }
 
+/* Matched-substring highlight (opt-in via `highlight: true`). */
+.liveselect__mark {
+  background: var(--liveselect-mark, #fde68a); color: inherit;
+  border-radius: 2px; padding: 0 1px;
+}
+
+/* "Showing N of M" footer when results are capped by `limit`. */
+.liveselect__more {
+  padding: 6px 12px; text-align: center;
+  color: var(--liveselect-text-muted); font-size: 0.8rem;
+}
+
 /* Group heading (from groupBy / option.group): non-selectable, sticky label. */
 .liveselect__group {
   position: sticky; top: -6px;
@@ -130,4 +148,6 @@
   --liveselect-hover:       #1f2c39;
   --liveselect-border:      #2b3947;
   --liveselect-shadow:      0 8px 28px rgba(0, 0, 0, 0.5);
+  --liveselect-mark:        #7c5b00;
 }
+.liveselect--dark .liveselect__mark { color: #ffe9a8; }
diff --git a/dist/liveselect.js b/dist/liveselect.js
index 3fe6b07..e5466c6 100644
--- a/dist/liveselect.js
+++ b/dist/liveselect.js
@@ -60,8 +60,22 @@
  *   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).
+ *   highlight     boolean — wrap the matched query substring in each result's
+ *                 label/sublabel with <mark class="prefix__mark"> (default false).
+ *                 Ignored for rows produced by renderOption.
+ *   cache         boolean — cache async source results by query+scope+limit so
+ *                 repeat queries skip the network (default false). Cleared by
+ *                 setSource()/setScope().
  *   classPrefix   CSS class prefix (default 'liveselect')
- *   texts         { searching, noResults, searchFailed } message overrides
+ *   texts         { searching, noResults, searchFailed, required } overrides, plus
+ *                 optional more(shown, total) => string for the "Showing N of M" footer
+ *
+ * Per-option `disabled: true` makes a row non-selectable (skipped by keyboard nav).
+ * An async source may return `{ items, total }` (instead of a bare array) to drive
+ * the "Showing N of M" footer.
+ *
+ * Besides `liveselect:change`, the root dispatches bubbling `liveselect:open`,
+ * `liveselect:close`, and `liveselect:search` ({ query }) CustomEvents.
  *
  * The option shape the control works in:  { value, label, sublabel?, raw? }
  * Input options are normalized leniently: a bare string becomes
@@ -85,6 +99,8 @@
     searching:    'Searching…',
     noResults:    'No matches.',
     searchFailed: 'Search failed.',
+    required:     'Please select an option.',
+    // more: (shown, total) => string — overridable "Showing N of M" footer text.
   };
 
   // ---- helpers -------------------------------------------------------------
@@ -99,7 +115,7 @@
   function normalizeOption(o) {
     if (o == null) return null;
     if (typeof o === 'string' || typeof o === 'number') {
-      return { value: String(o), label: String(o), sublabel: '', group: '', raw: o };
+      return { value: String(o), label: String(o), sublabel: '', group: '', disabled: false, raw: o };
     }
     var value = o.value != null ? o.value
       : (o._id != null ? o._id : (o.id != null ? o.id : ''));
@@ -110,6 +126,7 @@
       label:    label == null || label === '' ? '(unnamed)' : String(label),
       sublabel: o.sublabel != null ? String(o.sublabel) : '',
       group:    o.group != null ? String(o.group) : '',
+      disabled: !!o.disabled,
       raw:      Object.prototype.hasOwnProperty.call(o, 'raw') ? o.raw : o,
     };
   }
@@ -156,6 +173,8 @@
     this._blurTimer  = null;
     this._reqSeq     = 0;
     this._abort      = null;   // AbortController for the in-flight async search
+    this._total      = null;   // total matches behind a capped result set (or null)
+    this._cache      = {};     // async result cache (used only when opts.cache)
 
     this._build();
     this._bind();
@@ -166,6 +185,7 @@
         ? { value: this.opts.value, label: this.opts.valueLabel, sublabel: this.opts.valueSublabel || '' }
         : undefined);
     }
+    this._syncValidity();   // required controls start invalid until a pick is made
   }
 
   LiveSelect.prototype._c = function (suffix) {
@@ -279,11 +299,13 @@
 
     if (q.length < minChars) {
       this.results = [];
+      this._total = null;
       this.activeIndex = -1;
       this._renderMenu();
       return;
     }
 
+    this._dispatch('search', { query: q });
     var src = this.opts.source;
 
     // Array source → filter locally (synchronous).
@@ -295,6 +317,7 @@
           || (o.sublabel && o.sublabel.toLowerCase().indexOf(ql) !== -1);
       });
       this.error = '';
+      this._total = filtered.length;
       this.results = this._group(filtered.slice(0, limit));
       this.activeIndex = -1;
       this._renderMenu();
@@ -303,6 +326,22 @@
 
     // Async source → call function, guard against out-of-order responses.
     if (typeof src === 'function') {
+      var key = this._cacheKey(q, limit);
+
+      // Cache hit → serve synchronously, skip the network entirely.
+      if (this.opts.cache && this._cache[key]) {
+        this._reqSeq++;                               // invalidate any in-flight
+        if (this._abort) { this._abort.abort(); this._abort = null; }
+        var c = this._cache[key];
+        this.loading = false;
+        this.error = '';
+        this._total = c.total;
+        this.results = this._group(c.items.slice(0, limit));
+        this.activeIndex = -1;
+        this._renderMenu();
+        return;
+      }
+
       var seq = ++this._reqSeq;
       // Cancel the previous in-flight request, then hand this one a fresh signal.
       if (this._abort) this._abort.abort();
@@ -318,9 +357,16 @@
       };
       Promise.resolve(src(q, ctx))
         .then(function (res) {
+          // A source may return a bare array OR { items, total }.
+          var arr = Array.isArray(res) ? res : ((res && res.items) || []);
+          var norm = normalizeList(arr);
+          var total = (res && typeof res.total === 'number') ? res.total
+            : (norm.length > limit ? norm.length : null);
+          if (self.opts.cache) self._cache[key] = { items: norm, total: total };
           if (seq !== self._reqSeq) return; // a newer search superseded this one
           self.loading = false;
-          self.results = self._group(normalizeList(res).slice(0, limit));
+          self._total = total;
+          self.results = self._group(norm.slice(0, limit));
           self.activeIndex = -1;
           self._renderMenu();
         })
@@ -329,6 +375,7 @@
           if (err && err.name === 'AbortError') return; // we cancelled it → ignore
           self.loading = false;
           self.results = [];
+          self._total = null;
           self.error = (err && (err.message || err.reason)) || self.texts.searchFailed;
           self._renderMenu();
           self._renderError();
@@ -338,9 +385,15 @@
 
     // No usable source.
     this.results = [];
+    this._total = null;
     this._renderMenu();
   };
 
+  /** Cache key for an async query: query + scope + limit. */
+  LiveSelect.prototype._cacheKey = function (q, limit) {
+    return JSON.stringify([q, this.opts.scope || {}, limit]);
+  };
+
   /** 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') {
@@ -404,6 +457,26 @@
 
   // -- keyboard --------------------------------------------------------------
 
+  /** Is the row at `idx` selectable? The create row (idx === results.length) is. */
+  LiveSelect.prototype._isEnabled = function (idx) {
+    if (idx < 0) return false;
+    if (idx >= this.results.length) return true;       // create row
+    return !this.results[idx].disabled;
+  };
+
+  /** Next selectable index from `from` in direction `dir`, wrapping; -1 if none. */
+  LiveSelect.prototype._step = function (from, dir, max) {
+    if (max < 0) return -1;
+    var idx = from;
+    for (var n = 0; n <= max; n++) {
+      idx += dir;
+      if (idx > max) idx = 0;
+      else if (idx < 0) idx = max;
+      if (this._isEnabled(idx)) return idx;
+    }
+    return -1;   // nothing selectable (all rows disabled)
+  };
+
   LiveSelect.prototype._handleKeydown = function (e) {
     var canCreate = this._canCreate();
     var max = this.results.length + (canCreate ? 1 : 0) - 1;
@@ -411,20 +484,18 @@
     if (e.key === 'ArrowDown') {
       e.preventDefault();
       this._setOpen(true);
-      if (max < 0) return;
-      var d = this.activeIndex + 1; if (d > max) d = 0;
-      this.activeIndex = d; this._renderMenu();
+      var d = this._step(this.activeIndex, 1, max);
+      if (d >= 0) { this.activeIndex = d; this._renderMenu(); }
     } else if (e.key === 'ArrowUp') {
       e.preventDefault();
-      if (max < 0) return;
-      var u = this.activeIndex - 1; if (u < 0) u = max;
-      this.activeIndex = u; this._renderMenu();
+      var u = this._step(this.activeIndex, -1, max);
+      if (u >= 0) { this.activeIndex = u; this._renderMenu(); }
     } else if (e.key === 'Enter') {
       if (!this.isOpen) return;
       e.preventDefault();
       var i = this.activeIndex;
       if (canCreate && i === this.results.length) this._openCreate();
-      else if (i >= 0 && this.results[i]) this._select(this.results[i]);
+      else if (i >= 0 && this.results[i] && !this.results[i].disabled) this._select(this.results[i]);
     } else if (e.key === 'Escape') {
       this._setOpen(false);
       this.activeIndex = -1;
@@ -435,6 +506,7 @@
   // -- selection / value -----------------------------------------------------
 
   LiveSelect.prototype._select = function (opt) {
+    if (opt && opt.disabled) { this.input.focus(); return; }   // non-selectable row
     this.selected = opt;
     this.query = '';
     this._setOpen(false);
@@ -456,13 +528,24 @@
     }));
   };
 
+  /** Dispatch a bubbling liveselect:<type> lifecycle event (open/close/search). */
+  LiveSelect.prototype._dispatch = function (type, detail) {
+    this.root.dispatchEvent(new CustomEvent('liveselect:' + type, {
+      bubbles: true,
+      detail: Object.assign({ name: this.opts.name || '' }, detail || {}),
+    }));
+  };
+
   // -- rendering -------------------------------------------------------------
 
   LiveSelect.prototype._setOpen = function (open) {
+    var was = this.isOpen;
     this.isOpen = open;
     this.root.classList.toggle(this.cp + '--open', open);
     this.input.setAttribute('aria-expanded', open ? 'true' : 'false');
     this.menu.hidden = !open;
+    if (open && !was) this._dispatch('open');
+    if (!open && was) this._dispatch('close');
     if (open) {
       // Show the live query (empty when freshly opened); placeholder hints the
       // current selection so the user knows what they're replacing.
@@ -482,10 +565,24 @@
   LiveSelect.prototype._syncHidden = function () {
     this.hidden.value = this.selected ? this.selected.value : '';
     this.clearEl.hidden = !(this.selected && this.opts.clearable !== false && !this.opts.disabled);
+    this._syncValidity();
     // Fire a native change so plain-form listeners / validators react.
     this.hidden.dispatchEvent(new Event('change', { bubbles: true }));
   };
 
+  /**
+   * Enforce `required` on the *visible* input via the Constraint Validation API.
+   * The visible input is on-screen and focusable, so the browser can show its
+   * validation bubble and block form submit — unlike the display:none hidden
+   * <select> in enhance(), which is barred from validation. Driven by selection
+   * state, not the input's text. No-op when not required / disabled / unsupported.
+   */
+  LiveSelect.prototype._syncValidity = function () {
+    if (!this.input || typeof this.input.setCustomValidity !== 'function') return;
+    var enforce = this.opts.required && !this.opts.disabled && !this.selected;
+    this.input.setCustomValidity(enforce ? (this.texts.required || 'Please select an option.') : '');
+  };
+
   LiveSelect.prototype._renderError = function () {
     this.errorEl.textContent = this.error || '';
     this.errorEl.hidden = !this.error;
@@ -530,6 +627,22 @@
     return false;                                  // unknown return → default render
   };
 
+  /**
+   * Fill `el` with `text`, wrapping the first case-insensitive occurrence of `q`
+   * in <mark>. Built from text nodes + a <mark> element (no innerHTML) so it's
+   * XSS-safe regardless of the data.
+   */
+  LiveSelect.prototype._highlightInto = function (el, text, q) {
+    var i = q ? text.toLowerCase().indexOf(q.toLowerCase()) : -1;
+    if (i < 0) { el.textContent = text; return; }
+    el.appendChild(document.createTextNode(text.slice(0, i)));
+    var mark = document.createElement('mark');
+    mark.className = this.cp + '__mark';
+    mark.textContent = text.slice(i, i + q.length);
+    el.appendChild(mark);
+    el.appendChild(document.createTextNode(text.slice(i + q.length)));
+  };
+
   /** Fill a result <button> with custom (renderOption) or default content. */
   LiveSelect.prototype._fillOption = function (btn, o, index) {
     var cp = this.cp;
@@ -542,15 +655,16 @@
       };
       if (this._applyRendered(btn, this.opts.renderOption(o, ctx))) return;
     }
-    // Default: escaped two-line label / sublabel.
+    // Default: escaped two-line label / sublabel (with optional match highlight).
+    var q = this.opts.highlight ? this.query.trim() : '';
     var lab = document.createElement('span');
     lab.className = cp + '__opt-label';
-    lab.textContent = o.label;
+    this._highlightInto(lab, o.label, q);
     btn.appendChild(lab);
     if (o.sublabel) {
       var sub = document.createElement('span');
       sub.className = cp + '__opt-sub';
-      sub.textContent = o.sublabel;
+      this._highlightInto(sub, o.sublabel, q);
       btn.appendChild(sub);
     }
   };
@@ -605,9 +719,12 @@
       btn.id = optId;
       btn.setAttribute('role', 'option');
       btn.setAttribute('aria-selected', isActive ? 'true' : 'false');
-      btn.className = cp + '__opt' + (isActive ? ' ' + cp + '__opt--active' : '');
+      btn.className = cp + '__opt'
+        + (isActive ? ' ' + cp + '__opt--active' : '')
+        + (o.disabled ? ' ' + cp + '__opt--disabled' : '');
       btn.setAttribute('data-liveselect-opt', '');
       btn.setAttribute('data-liveselect-index', String(i));
+      if (o.disabled) { btn.disabled = true; btn.setAttribute('aria-disabled', 'true'); }
       this._fillOption(btn, o, i);
       this.menu.appendChild(btn);
       if (isActive) activeId = optId;
@@ -632,6 +749,18 @@
       if (createOn) activeId = createId;
     }
 
+    // "Showing N of M" footer when the result set is capped.
+    var shown = this.results.length;
+    if (this._total != null && this._total > shown) {
+      var more = document.createElement('div');
+      more.className = cp + '__more';
+      more.setAttribute('role', 'presentation');
+      more.textContent = typeof this.texts.more === 'function'
+        ? this.texts.more(shown, this._total)
+        : 'Showing ' + shown + ' of ' + this._total;
+      this.menu.appendChild(more);
+    }
+
     if (activeId) this.input.setAttribute('aria-activedescendant', activeId);
     this.menu.hidden = false;
     this._announceResults(canCreate);
@@ -697,6 +826,7 @@
   /** Swap the data source (e.g. after pushing a new item to an array). */
   LiveSelect.prototype.setSource = function (source) {
     this.opts.source = source;
+    this._cache = {};   // results from the old source are no longer valid
     if (this.isOpen) this._runSearch();
   };
 
@@ -704,6 +834,7 @@
   LiveSelect.prototype.setScope = function (scope) {
     this.opts.scope = scope || {};
     this.results = [];
+    this._cache = {};   // scope is part of the cache key — drop stale entries
     if (this.isOpen) this._runSearch();
   };
 
@@ -712,6 +843,7 @@
     this.input.disabled = !!disabled;
     this.root.classList.toggle(this.cp + '--disabled', !!disabled);
     this.clearEl.hidden = !(this.selected && this.opts.clearable !== false && !disabled);
+    this._syncValidity();   // disabling clears the required constraint
   };
 
   LiveSelect.prototype.destroy = function () {
@@ -763,9 +895,10 @@
     sel.setAttribute('data-liveselect-enhanced', '');
     // A `required` control that is display:none is NOT focusable, which makes
     // browsers (e.g. Chrome) silently block form submit with "An invalid form
-    // control is not focusable." Drop required from the now-hidden select; we
-    // keep the `*` marker on the visible control and recommend validating via
-    // the liveselect:change event or on the server.
+    // control is not focusable." Drop required from the now-hidden select and let
+    // the LiveSelect enforce it on its *visible* input via the Constraint
+    // Validation API (see _syncValidity) — so submit is actually blocked, with a
+    // focusable, on-screen validation bubble, when nothing is selected.
     if (wasRequired) sel.required = false;
 
     var opts = Object.assign({
diff --git a/examples/vanilla.html b/examples/vanilla.html
index 7f6840b..31b47ef 100644
--- a/examples/vanilla.html
+++ b/examples/vanilla.html
@@ -78,15 +78,17 @@ <h2>5 · Grouped options (optgroup-style headings)</h2>
       { value: 'banana', label: 'Banana', sublabel: 'Berry, technically' },
       { value: 'cherry', label: 'Cherry', sublabel: 'Stone fruit' },
       { value: 'date',   label: 'Date',   sublabel: 'Palm fruit' },
+      { value: 'durian', label: 'Durian', sublabel: 'Out of stock', disabled: true },
       { value: 'fig',    label: 'Fig' },
     ];
 
-    // 1 · Array source + create flow.
+    // 1 · Array source + create flow, with match highlighting + a disabled row.
     var dd1 = new LiveSelect('#picker1', {
       name: 'fruit',
       label: 'Favourite fruit',
       placeholder: 'Search fruit…',
       source: fruits,
+      highlight: true,        // bold the matched substring
       allowCreate: true,
       // onCreate can do ANYTHING. Here we just push to the array and return the
       // new option so it's auto-selected. In a real app you'd POST to a server
diff --git a/package.json b/package.json
index a2725ff..40cac4e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@michaeljfalk/liveselect",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "publishConfig": {
     "access": "public"
   },
diff --git a/test/client.test.js b/test/client.test.js
index 1bc8340..8b4a863 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: '', group: '', raw: 'apple' });
+    { value: 'apple', label: 'apple', sublabel: '', group: '', disabled: false, raw: 'apple' });
   const n = LiveSelect.normalizeOption({ _id: 'x1', name: 'Acme' });
   assert.equal(n.value, 'x1');
   assert.equal(n.label, 'Acme');
@@ -268,3 +268,117 @@ test('groupBy function takes precedence over option.group', { skip: !domAvailabl
   assert.deepEqual(heads, ['A', 'B']);
   dd.destroy();
 });
+
+test('disabled option: not selectable by click/Enter, skipped by keyboard nav', { skip: !domAvailable }, () => {
+  const host = mount();
+  let changed = 0;
+  const dd = new LiveSelect(host, {
+    source: [
+      { value: 'a', label: 'Alpha' },
+      { value: 'b', label: 'Bravo', disabled: true },
+      { value: 'c', label: 'Charlie' },
+    ],
+    onChange: () => { changed++; },
+  });
+  dd.query = ''; dd.isOpen = true; dd._runSearch(); dd._renderMenu();
+
+  const rows = dd.menu.querySelectorAll('[data-liveselect-opt]');
+  assert.equal(rows[1].getAttribute('aria-disabled'), 'true');
+  assert.ok(rows[1].disabled, 'disabled row is a disabled button');
+
+  // Direct select of a disabled option is a no-op.
+  dd._select(dd.results[1]);
+  assert.equal(dd.getValue(), '');
+  assert.equal(changed, 0);
+
+  // ArrowDown from -1 lands on Alpha (0), next ArrowDown skips Bravo → Charlie (2).
+  dd._handleKeydown({ key: 'ArrowDown', preventDefault() {} });
+  assert.equal(dd.activeIndex, 0);
+  dd._handleKeydown({ key: 'ArrowDown', preventDefault() {} });
+  assert.equal(dd.activeIndex, 2, 'disabled Bravo skipped');
+  dd.destroy();
+});
+
+test('required: visible input enforces selection via Constraint Validation', { skip: !domAvailable }, () => {
+  const host = mount();
+  const dd = new LiveSelect(host, {
+    required: true,
+    source: [{ value: 'a', label: 'Alpha' }],
+  });
+  // Nothing selected → invalid with the required message.
+  assert.equal(dd.input.validity.valid, false);
+  assert.match(dd.input.validationMessage, /select/i);
+
+  dd._select({ value: 'a', label: 'Alpha', sublabel: '' });
+  assert.equal(dd.input.validity.valid, true, 'valid once a selection exists');
+
+  dd.clear();
+  assert.equal(dd.input.validity.valid, false, 'invalid again after clear');
+  dd.destroy();
+});
+
+test('highlight: matched substring wrapped in <mark> (and stays XSS-safe)', { skip: !domAvailable }, () => {
+  const host = mount();
+  const dd = new LiveSelect(host, {
+    highlight: true,
+    source: [{ value: '1', label: 'Banana' }, { value: '2', label: '<b>nano</b>' }],
+  });
+  dd.query = 'nan'; dd.isOpen = true; dd._runSearch(); dd._renderMenu();
+
+  const marks = dd.menu.querySelectorAll('.liveselect__mark');
+  assert.ok(marks.length >= 1, 'a match is highlighted');
+  assert.equal(marks[0].textContent.toLowerCase(), 'nan');
+  assert.equal(dd.menu.querySelector('b'), null, 'markup in label is still escaped, not parsed');
+  dd.destroy();
+});
+
+test('Showing N of M footer from array source capped by limit', { skip: !domAvailable }, () => {
+  const host = mount();
+  const source = Array.from({ length: 10 }, (_, i) => ({ value: String(i), label: 'Item ' + i }));
+  const dd = new LiveSelect(host, { source, limit: 3 });
+  dd.query = ''; dd.isOpen = true; dd._runSearch(); dd._renderMenu();
+
+  assert.equal(dd.menu.querySelectorAll('[data-liveselect-opt]').length, 3);
+  const more = dd.menu.querySelector('.liveselect__more');
+  assert.ok(more, 'footer rendered');
+  assert.equal(more.textContent, 'Showing 3 of 10');
+  dd.destroy();
+});
+
+test('async source: { items, total } drives the footer; cache skips refetch', { skip: !domAvailable }, async () => {
+  const host = mount();
+  let calls = 0;
+  const dd = new LiveSelect(host, {
+    debounce: 0,
+    cache: true,
+    source: (q) => { calls++; return Promise.resolve({ items: [{ value: 'x', label: 'X' }], total: 42 }); },
+  });
+  dd.query = 'ab'; dd.isOpen = true; dd._runSearch();
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(calls, 1);
+  assert.equal(dd._total, 42);
+  assert.equal(dd.menu.querySelector('.liveselect__more').textContent, 'Showing 1 of 42');
+
+  // Same query again → served from cache, no second call.
+  dd.results = []; dd._runSearch();
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(calls, 1, 'cache hit, source not called again');
+  assert.equal(dd.results.length, 1);
+  dd.destroy();
+});
+
+test('lifecycle events: open / close / search bubble', { skip: !domAvailable }, () => {
+  const host = mount();
+  const seen = [];
+  ['open', 'close', 'search'].forEach((t) =>
+    host.addEventListener('liveselect:' + t, (e) => seen.push([t, e.detail.query])));
+  const dd = new LiveSelect(host, { debounce: 0, source: [{ value: 'a', label: 'Alpha' }] });
+
+  dd._setOpen(true);
+  dd.query = 'al'; dd._runSearch();
+  dd._setOpen(false);
+
+  assert.deepEqual(seen.map((s) => s[0]), ['open', 'search', 'close']);
+  assert.equal(seen.find((s) => s[0] === 'search')[1], 'al');
+  dd.destroy();
+});