filtered-select-multiple-widget 0.0.3 → 0.0.6

package/README.md

@@ -1,5 +1,10 @@
 # Filtered Select Multiple Widget
 
+[![npm version](https://img.shields.io/npm/v/filtered-select-multiple-widget)](https://www.npmjs.com/package/filtered-select-multiple-widget)
+[![license](https://img.shields.io/npm/l/filtered-select-multiple-widget)](https://github.com/tombreit/filtered-select-multiple-widget/blob/main/LICENSE)
+[![Publish](https://github.com/tombreit/filtered-select-multiple-widget/actions/workflows/publish.yml/badge.svg)](https://github.com/tombreit/filtered-select-multiple-widget/actions/workflows/publish.yml)
+[![Deploy](https://github.com/tombreit/filtered-select-multiple-widget/actions/workflows/deploy.yml/badge.svg)](https://github.com/tombreit/filtered-select-multiple-widget/actions/workflows/deploy.yml)
+
 A dependency-free, JavaScript implementation of Django's dual-pane “FilteredSelectMultiple” widget. It transforms a native `<select multiple>` element into a picker with move buttons and client-side filtering.
 
 ![Screenshot Filtered Select Multiple Widget](./docs/filtered-select-multiple-widget-screenshot.png)
@@ -27,10 +32,14 @@ The Django widget is a thousand times better than mine. But I hope to gradually
 
 - Zero dependencies and ES module friendly.
 - Works with any native `<select multiple>` element.
-- Optional client-side filtering of the available choices.
-- Keyboard friendly and form-ready (synced back to the original select element).
+- Optional client-side filtering of the available choices (with debounce).
+- Keyboard friendly: select items and press Enter to transfer. Form-ready (synced back to the original select element).
+- Ships default CSS — no extra stylesheet needed for out-of-the-box styling.
 - Integrates with Bootstrap 5, DaisyUI, and Tailwind CSS (see live demo with theme switcher).
 - Automatically detects pane labels from associated `<label>` elements.
+- Items count indicator on each pane.
+- Accessible: `aria-labelledby`, `aria-label`, `aria-live` regions.
+- Disabled `<option>` elements are respected and excluded from bulk transfers.
 
 ## Demo
 
@@ -44,7 +53,7 @@ The demo includes a theme switcher to showcase integration with Bootstrap 5, Dai
 ## Installation
 
 ```bash
-npm install git+https://github.com/tombreit/filtered-select-multiple-widget.git
+npm install filtered-select-multiple-widget
 ```
 
 ## Usage
@@ -68,12 +77,17 @@ const widget = new FilteredSelectMultiple(select);
 
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
-| `showFilter` | `boolean` | `true` | Toggle the search box above the available list. |
-| `filterMatchMode` | `'contains' \| 'startsWith'` | `'contains'` | How filtering behaves. |
-| `size` | `number` | `select.size \|\| clamp(optionCount)` | Number of visible rows for each list. |
+| `showFilter` | `boolean` | `true` | Toggle the search box above each list. |
+| `filterMatchMode` | `'contains' \| 'startsWith'` | `'contains'` | How filtering behaves. `'contains'` supports multiple space-separated tokens. |
+| `size` | `number` | `select.size \|\| clamp(optionCount, 4, 12)` | Number of visible rows for each list. |
 | `preserveSelectionOrder` | `boolean` | `false` | Keep the order items were added in the chosen list rather than the original option order. |
 | `text` | `object` | see defaults | Override UI copy (`availableLabel`, `chosenLabel`, `filterPlaceholder`, `availableFilterPlaceholder`, `chosenFilterPlaceholder`, `addAll`, `addSelected`, `removeSelected`, `removeAll`). If `availableLabel` and `chosenLabel` are not provided, the widget will attempt to auto-detect them from an associated `<label>` element. |
-| `theme` | `Theme` | `defaultTheme` | CSS theme configuration for styling framework integration. |
+| `theme` | `object` | `defaultTheme` | CSS theme configuration for styling framework integration. |
+
+### Keyboard Support
+
+- **Enter** on either select list: transfers the currently selected items.
+- **Double-click** on an option: transfers that single item.
 
 ### Theming
 
@@ -99,32 +113,40 @@ new FilteredSelectMultiple(select, { theme: tailwindTheme });
 
 #### Custom Themes
 
-```js
-import { Theme } from "filtered-select-multiple-widget";
+A theme is a plain object mapping element roles to CSS class strings. Any keys you omit are filled in from `defaultTheme`:
 
-const customTheme = new Theme({
+```js
+const customTheme = {
   container: "my-widget-container",
   button: "my-button-class",
-  buttonAddSelected: "my-button-class my-primary-button",
+  buttonAddSelected: "my-primary-button",
   filter: "my-input-class",
   select: "my-select-class",
-  // ... customize any element
-});
+  // ... only override what you need
+};
 
 new FilteredSelectMultiple(select, { theme: customTheme });
 ```
 
-#### Available Theme Elements
-
-- `container` - Main widget wrapper
-- `column`, `availableColumn`, `chosenColumn` - Pane containers  
-- `label` - Pane labels
-- `filter` - Search input fields
-- `select` - Multi-select elements
-- `controls` - Button container
-- `button`, `buttonAddAll`, `buttonAddSelected`, `buttonRemoveSelected`, `buttonRemoveAll` - Control buttons
-- `buttonDisabled` - Disabled button modifier
-- `button_svg` - Button SVG icon
+#### Available Theme Keys
+
+| Key | Element |
+| --- | ------- |
+| `container` | Main widget wrapper |
+| `column` | Pane column |
+| `availableColumn` | Available pane column modifier |
+| `chosenColumn` | Chosen pane column modifier |
+| `label` | Pane labels |
+| `counter` | Item count indicator inside labels |
+| `filter` | Search input fields |
+| `select` | Multi-select elements |
+| `controls` | Button container |
+| `button` | Base button class (applied to all buttons) |
+| `buttonAddAll` | "Add all" button |
+| `buttonAddSelected` | "Add selected" button |
+| `buttonRemoveSelected` | "Remove selected" button |
+| `buttonRemoveAll` | "Remove all" button |
+| `buttonDisabled` | Disabled button modifier |
 
 ### Destroying the widget
 
@@ -132,7 +154,11 @@ new FilteredSelectMultiple(select, { theme: customTheme });
 widget.destroy();
 ```
 
-The original `<select>` is restored and remains in sync with user selections.
+The original `<select>` is restored and all event listeners are cleaned up.
+
+## Note on `<optgroup>`
+
+The widget currently flattens `<optgroup>` structures — all options are displayed in a single flat list regardless of their original grouping. Grouped display is not yet supported.
 
 ## Third-Party Assets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filtered-select-multiple-widget",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "ES module implementation of Django's FilteredSelectMultiple widget.",
   "license": "MIT",
   "author": {
@@ -21,14 +21,20 @@
   "homepage": "https://tombreit.github.io/filtered-select-multiple-widget/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tombreit/filtered-select-multiple-widget.git"
+    "url": "git+https://github.com/tombreit/filtered-select-multiple-widget.git"
   },
   "bugs": {
     "url": "https://github.com/tombreit/filtered-select-multiple-widget/issues"
   },
   "keywords": [
     "widget",
-    "multiselect"
+    "multiselect",
+    "select",
+    "multiple",
+    "dual-list",
+    "filter",
+    "django",
+    "transfer-list"
   ],
   "exports": {
     ".": {
@@ -40,10 +46,10 @@
     "http-server": "^14.1.1"
   },
   "scripts": {
-    "test": "node --check src/index.js && node --check src/FilteredSelectMultiple.js && node --check src/themes.js",
-    "pre-demo": "ln -sf ../src docs/src",
+    "test": "node --check src/index.js && node --check src/FilteredSelectMultiple.js && node --check src/themes.js && node --check src/icons.js",
+    "predemo": "ln -sfn ../src docs/src",
     "demo": "http-server docs/ -p 8000 -o",
-    "pre-ghpages": "rm -rf docs/src",
+    "preghpages": "rm -rf docs/src",
     "ghpages": "cp -r src docs/src"
   }
 }

package/src/FilteredSelectMultiple.js

@@ -1,31 +1,142 @@
 import { defaultTheme } from "./themes.js";
+import { icons } from "./icons.js";
+
+/**
+ * Default CSS injected once when the default theme is used.
+ * Avoids the need for users to ship a separate .css file.
+ */
+const DEFAULT_CSS = `
+.filtered-select-multiple {
+  display: flex;
+  gap: 1rem;
+  align-items: stretch;
+  flex-wrap: wrap;
+}
+.fsm-column {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  min-width: 220px;
+  flex: 1 1 220px;
+}
+.fsm-label {
+  font-weight: 600;
+}
+.fsm-counter {
+  font-size: 0.85em;
+  opacity: 0.7;
+  font-weight: normal;
+}
+.fsm-filter {
+  padding: 0.5rem;
+  border-radius: 6px;
+  border: 1px solid #d0d6e0;
+}
+.fsm-select {
+  min-width: 220px;
+  padding: 0.25rem;
+  border-radius: 6px;
+  border: 1px solid #d0d6e0;
+  background: #fff;
+  flex: 1 1 auto;
+}
+.fsm-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  justify-content: center;
+}
+.fsm-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  border: none;
+  background: #0052cc;
+  color: #fff;
+  cursor: pointer;
+  transition: background 0.2s ease-in-out;
+  white-space: nowrap;
+}
+.fsm-button svg {
+  height: 1.2em;
+  width: auto;
+  flex-shrink: 0;
+}
+.fsm-button:disabled,
+.fsm-button-disabled {
+  cursor: not-allowed;
+  background: #cbd5f5;
+  color: #49526f;
+}
+.fsm-button:not(:disabled):hover {
+  background: #0a66e6;
+}
+.fsm-add-all,
+.fsm-add-selected {
+  justify-content: flex-end;
+}
+.fsm-remove-selected,
+.fsm-remove-all {
+  justify-content: flex-start;
+}
+@media (max-width: 640px) {
+  .filtered-select-multiple {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  .fsm-controls {
+    flex-direction: row;
+    justify-content: center;
+  }
+}
+`;
+
+let defaultCssInjected = false;
+
+function injectDefaultCSS(doc) {
+  if (defaultCssInjected) return;
+  const style = doc.createElement("style");
+  style.setAttribute("data-fsm-default-theme", "");
+  style.textContent = DEFAULT_CSS;
+  doc.head.appendChild(style);
+  defaultCssInjected = true;
+}
 
 /**
  * Transform a native <select multiple> element into a dual-list transfer widget.
- * 
+ *
  * Usage:
  *   import { FilteredSelectMultiple } from "filtered-select-multiple-widget";
  *   const widget = new FilteredSelectMultiple(selectElement, options);
  */
 export class FilteredSelectMultiple {
+  /** @type {AbortController} – used to clean up all event listeners on destroy */
+  #abortController = new AbortController();
+
   constructor(selectElement, options = {}) {
-    // Validate
     if (!(selectElement instanceof HTMLSelectElement) || !selectElement.multiple) {
       throw new Error("FilteredSelectMultiple requires a <select multiple> element");
     }
 
     this.selectElement = selectElement;
     this.doc = selectElement.ownerDocument;
-    
-    // Parse options
+
+    // Merge the provided theme on top of defaults so missing keys are filled.
+    this.theme = { ...defaultTheme, ...(options.theme ?? {}) };
+
+    // Always inject default CSS — its .fsm-* selectors won't collide with
+    // framework themes that use their own class names.
+    injectDefaultCSS(this.doc);
+
     const optionCount = selectElement.options.length;
     this.showFilter = options.showFilter ?? true;
     this.filterMatchMode = options.filterMatchMode ?? "contains";
     this.size = options.size ?? (selectElement.size || Math.min(Math.max(optionCount, 4), 12));
     this.preserveSelectionOrder = options.preserveSelectionOrder ?? false;
-    this.theme = { ...defaultTheme, ...options.theme };
-    
-    // Parse text options
+
+    // Text / labels
     const textDefaults = {
       availableLabel: "Available",
       chosenLabel: "Chosen",
@@ -36,10 +147,12 @@ export class FilteredSelectMultiple {
       removeAll: "Remove all",
     };
     this.text = { ...textDefaults, ...(options.text || {}) };
-    
-    // Auto-detect labels from <label> element if defaults are used
-    if (this.text.availableLabel === textDefaults.availableLabel && 
-        this.text.chosenLabel === textDefaults.chosenLabel) {
+
+    // Auto-detect labels from an associated <label> element
+    if (
+      this.text.availableLabel === textDefaults.availableLabel &&
+      this.text.chosenLabel === textDefaults.chosenLabel
+    ) {
       const label = this.doc.querySelector(`label[for="${selectElement.id}"]`);
       if (label) {
         const baseLabel = label.textContent.trim();
@@ -47,42 +160,43 @@ export class FilteredSelectMultiple {
         this.text.chosenLabel = `Chosen ${baseLabel}`;
       }
     }
-    
-    // Set filter placeholder defaults
+
     const fallbackFilter = options.text?.filterPlaceholder ?? textDefaults.filterPlaceholder;
     this.text.availableFilterPlaceholder = this.text.availableFilterPlaceholder ?? fallbackFilter;
     this.text.chosenFilterPlaceholder = this.text.chosenFilterPlaceholder ?? fallbackFilter;
-    
-    // State
-    this.options = new Map(); // key -> {index, value, label, disabled, dataset, title, original}
+
+    // Internal state
+    this.options = new Map();
     this.available = [];
     this.chosen = [];
-    
-    // UI elements
+
+    // UI element references
     this.container = null;
     this.availableSelect = null;
     this.chosenSelect = null;
     this.availableFilter = null;
     this.chosenFilter = null;
+    this.availableCounter = null;
+    this.chosenCounter = null;
     this.buttons = {};
-    
+
+    // Filter debounce timer ids
+    this._filterTimers = { available: 0, chosen: 0 };
+
     this._init();
   }
 
+  // ---------------------------------------------------------------------------
+  // Initialisation
+  // ---------------------------------------------------------------------------
+
   _init() {
-    // Build state from original select
     this._buildState();
-    
-    // Hide original select
     this.selectElement.dataset.filteredSelectMultiple = "true";
     this.previousDisplay = this.selectElement.style.display;
     this.selectElement.style.display = "none";
-    
-    // Create placeholder comment for restoring position
     this.placeholder = this.doc.createComment("filtered-select-multiple");
     this.selectElement.parentNode.insertBefore(this.placeholder, this.selectElement);
-    
-    // Build and render UI
     this._buildUI();
     this._attachEvents();
     this._render();
@@ -90,8 +204,7 @@ export class FilteredSelectMultiple {
 
   _buildState() {
     const options = Array.from(this.selectElement.options);
-    const orderKeys = [];
-    
+
     options.forEach((option, index) => {
       const key = `fsm-${index}`;
       this.options.set(key, {
@@ -104,16 +217,14 @@ export class FilteredSelectMultiple {
         title: option.title,
         original: option,
       });
-      
-      orderKeys.push(key);
+
       if (option.selected) {
         this.chosen.push(key);
       } else {
         this.available.push(key);
       }
     });
-    
-    // Sort by original order
+
     this._sortByIndex(this.available);
     if (!this.preserveSelectionOrder) {
       this._sortByIndex(this.chosen);
@@ -122,18 +233,20 @@ export class FilteredSelectMultiple {
 
   _sortByIndex(keys) {
     keys.sort((a, b) => {
-      const aIndex = this.options.get(a)?.index ?? Number.MAX_SAFE_INTEGER;
-      const bIndex = this.options.get(b)?.index ?? Number.MAX_SAFE_INTEGER;
-      return aIndex - bIndex;
+      const ai = this.options.get(a)?.index ?? Number.MAX_SAFE_INTEGER;
+      const bi = this.options.get(b)?.index ?? Number.MAX_SAFE_INTEGER;
+      return ai - bi;
     });
   }
 
+  // ---------------------------------------------------------------------------
+  // UI construction
+  // ---------------------------------------------------------------------------
+
   _buildUI() {
-    // Main container
     this.container = this.doc.createElement("div");
     this.container.className = this.theme.container;
-    
-    // Available pane
+
     const availablePane = this._createPane({
       type: "available",
       label: this.text.availableLabel,
@@ -141,11 +254,10 @@ export class FilteredSelectMultiple {
     });
     this.availableSelect = availablePane.select;
     this.availableFilter = availablePane.filter;
-    
-    // Controls (buttons)
+    this.availableCounter = availablePane.counter;
+
     const controls = this._createControls();
-    
-    // Chosen pane
+
     const chosenPane = this._createPane({
       type: "chosen",
       label: this.text.chosenLabel,
@@ -153,8 +265,8 @@ export class FilteredSelectMultiple {
     });
     this.chosenSelect = chosenPane.select;
     this.chosenFilter = chosenPane.filter;
-    
-    // Assemble
+    this.chosenCounter = chosenPane.counter;
+
     this.container.append(availablePane.column, controls, chosenPane.column);
     this.placeholder.parentNode.insertBefore(this.container, this.placeholder);
   }
@@ -162,14 +274,28 @@ export class FilteredSelectMultiple {
   _createPane({ type, label, filterPlaceholder }) {
     const column = this.doc.createElement("div");
     const isAvailable = type === "available";
-    column.className = this.theme.column + " " + (isAvailable ? this.theme.availableColumn : this.theme.chosenColumn);
-    
-    // Label
+    column.className =
+      this.theme.column + " " +
+      (isAvailable ? this.theme.availableColumn : this.theme.chosenColumn);
+
+    // Unique ids for aria relationships
+    const labelId = `fsm-label-${type}-${Date.now()}`;
+
+    // Label + counter
     const labelEl = this.doc.createElement("div");
     labelEl.className = this.theme.label;
-    labelEl.textContent = label;
+    labelEl.id = labelId;
+
+    const labelText = this.doc.createTextNode(label + " ");
+    labelEl.appendChild(labelText);
+
+    const counter = this.doc.createElement("span");
+    counter.className = this.theme.counter;
+    counter.setAttribute("aria-live", "polite");
+    labelEl.appendChild(counter);
+
     column.appendChild(labelEl);
-    
+
     // Filter input (optional)
     let filter = null;
     if (this.showFilter) {
@@ -178,111 +304,106 @@ export class FilteredSelectMultiple {
       filter.className = this.theme.filter;
       filter.placeholder = filterPlaceholder;
       filter.dataset.paneType = type;
+      filter.setAttribute("aria-label", `${filterPlaceholder} ${label}`);
       column.appendChild(filter);
     }
-    
+
     // Select element
     const select = this.doc.createElement("select");
     select.multiple = true;
     select.size = this.size;
     select.className = this.theme.select;
     select.dataset.paneType = type;
+    select.setAttribute("aria-labelledby", labelId);
     column.appendChild(select);
-    
-    return { column, select, filter };
+
+    return { column, select, filter, counter };
   }
 
   _createControls() {
     const column = this.doc.createElement("div");
     column.className = this.theme.controls;
-    
-    const icons = {
-      addAll: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" style="height: 1.2em;">
-  <path stroke-linecap="round" stroke-linejoin="round" d="m5.25 4.5 7.5 7.5-7.5 7.5m6-15 7.5 7.5-7.5 7.5" />
-</svg>`,
-      addSelected: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" style="height: 1.2em;">
-  <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
-</svg>`,
-      removeSelected: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" style="height: 1.2em;">
-  <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 19.5 8.25 12l7.5-7.5" />
-</svg>`,
-      removeAll: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" style="height: 1.2em;">
-  <path stroke-linecap="round" stroke-linejoin="round" d="m18.75 4.5-7.5 7.5 7.5 7.5m-6-15L5.25 12l7.5 7.5" />
-</svg>`,
-    };
-    
-    const buttons = [
+    column.setAttribute("role", "group");
+    column.setAttribute("aria-label", "Transfer controls");
+
+    const buttonDefs = [
       { action: "addAll", label: this.text.addAll, icon: icons.addAll },
       { action: "addSelected", label: this.text.addSelected, icon: icons.addSelected },
       { action: "removeSelected", label: this.text.removeSelected, icon: icons.removeSelected },
       { action: "removeAll", label: this.text.removeAll, icon: icons.removeAll },
     ];
-    
-    buttons.forEach(({ action, label, icon }) => {
+
+    buttonDefs.forEach(({ action, label, icon }) => {
       const button = this.doc.createElement("button");
       button.type = "button";
-      const specificClass = this.theme[`button_${action}`] || "";
-      button.className = (this.theme.button + " " + specificClass).trim();
-      
+      const actionKey = `button${action.charAt(0).toUpperCase()}${action.slice(1)}`;
+      const actionClass = this.theme[actionKey] || "";
+      button.className = (this.theme.button + " " + actionClass).trim();
+      button.setAttribute("aria-label", label);
+
       const isRemove = action.startsWith("remove");
-      const svgClass = this.theme.button_svg ? ` class="${this.theme.button_svg}"` : '';
-      const modifiedIcon = icon.replace('<svg', `<svg${svgClass}`);
-      button.innerHTML = isRemove ? `${modifiedIcon} ${label}` : `${label} ${modifiedIcon}`;
+      button.innerHTML = isRemove ? `${icon} ${label}` : `${label} ${icon}`;
       button.dataset.action = action;
-      
       this.buttons[action] = button;
       column.appendChild(button);
     });
-    
+
     return column;
   }
 
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+
   _attachEvents() {
-    // Filter input events
+    const signal = this.#abortController.signal;
+
     if (this.availableFilter) {
-      this.availableFilter.addEventListener("input", () => this._renderPane("available"));
+      this.availableFilter.addEventListener("input", () => this._debouncedRender("available"), { signal });
     }
     if (this.chosenFilter) {
-      this.chosenFilter.addEventListener("input", () => this._renderPane("chosen"));
+      this.chosenFilter.addEventListener("input", () => this._debouncedRender("chosen"), { signal });
     }
-    
-    // Selection change events
-    this.availableSelect.addEventListener("change", () => this._updateButtons());
-    this.chosenSelect.addEventListener("change", () => this._updateButtons());
-    
-    // Double-click to move
+
+    this.availableSelect.addEventListener("change", () => this._updateButtons(), { signal });
+    this.chosenSelect.addEventListener("change", () => this._updateButtons(), { signal });
+
     this.availableSelect.addEventListener("dblclick", () => {
-      if (!this.availableSelect.disabled) {
-        this._moveSelected("available", "chosen");
-      }
-    });
+      if (!this.availableSelect.disabled) this._moveSelected("available", "chosen");
+    }, { signal });
     this.chosenSelect.addEventListener("dblclick", () => {
-      if (!this.chosenSelect.disabled) {
-        this._moveSelected("chosen", "available");
-      }
-    });
-    
-    // Button clicks
+      if (!this.chosenSelect.disabled) this._moveSelected("chosen", "available");
+    }, { signal });
+
+    // Keyboard shortcut: Enter to transfer selected items
+    this.availableSelect.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") { e.preventDefault(); this._moveSelected("available", "chosen"); }
+    }, { signal });
+    this.chosenSelect.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") { e.preventDefault(); this._moveSelected("chosen", "available"); }
+    }, { signal });
+
     Object.entries(this.buttons).forEach(([action, button]) => {
       button.addEventListener("click", () => {
         switch (action) {
-          case "addAll":
-            this._moveAll("available", "chosen");
-            break;
-          case "addSelected":
-            this._moveSelected("available", "chosen");
-            break;
-          case "removeSelected":
-            this._moveSelected("chosen", "available");
-            break;
-          case "removeAll":
-            this._moveAll("chosen", "available");
-            break;
+          case "addAll": this._moveAll("available", "chosen"); break;
+          case "addSelected": this._moveSelected("available", "chosen"); break;
+          case "removeSelected": this._moveSelected("chosen", "available"); break;
+          case "removeAll": this._moveAll("chosen", "available"); break;
         }
-      });
+      }, { signal });
     });
   }
 
+  _debouncedRender(type) {
+    clearTimeout(this._filterTimers[type]);
+    this._filterTimers[type] = setTimeout(() => this._renderPane(type), 120);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Rendering
+  // ---------------------------------------------------------------------------
+
   _render() {
     this._renderPane("available");
     this._renderPane("chosen");
@@ -292,111 +413,115 @@ export class FilteredSelectMultiple {
   _renderPane(type) {
     const select = type === "available" ? this.availableSelect : this.chosenSelect;
     const filter = type === "available" ? this.availableFilter : this.chosenFilter;
+    const counter = type === "available" ? this.availableCounter : this.chosenCounter;
     const keys = type === "available" ? this.available : this.chosen;
-    
-    // Get filter term
     const term = filter ? filter.value.trim().toLowerCase() : "";
-    
-    // Preserve selection
+
+    // Preserve selection across re-renders
     const previousSelection = new Set(
-      Array.from(select.selectedOptions, opt => opt.dataset.key)
+      Array.from(select.selectedOptions, (opt) => opt.dataset.key)
     );
-    
-    // Clear and rebuild
-    select.innerHTML = "";
-    
-    keys.forEach(key => {
+
+    const fragment = this.doc.createDocumentFragment();
+    let visibleCount = 0;
+
+    keys.forEach((key) => {
       const meta = this.options.get(key);
       if (!meta) return;
-      
-      // Apply filter
-      if (term && !this._passesFilter(meta.label, term)) {
-        return;
-      }
-      
+      if (term && !this._passesFilter(meta.label, term)) return;
+
+      visibleCount++;
       const option = this.doc.createElement("option");
       option.value = meta.value;
       option.textContent = meta.label;
       option.dataset.key = key;
       option.disabled = meta.disabled;
-      
-      if (meta.title) {
-        option.title = meta.title;
-      }
-      
+      // Always give every option a tooltip so long labels remain readable
+      // when a width-constrained parent truncates the visible text. Prefer an
+      // explicit title from the source markup, otherwise fall back to the label.
+      option.title = meta.title || meta.label;
       Object.entries(meta.dataset).forEach(([attr, value]) => {
         option.dataset[attr] = value;
       });
-      
-      if (previousSelection.has(key)) {
-        option.selected = true;
-      }
-      
-      select.appendChild(option);
+      if (previousSelection.has(key)) option.selected = true;
+      fragment.appendChild(option);
     });
+
+    select.replaceChildren(fragment);
+
+    // Update counter
+    if (counter) {
+      const total = keys.length;
+      counter.textContent = term
+        ? `(${visibleCount} / ${total})`
+        : `(${total})`;
+    }
+
+    this._updateButtons();
   }
 
   _passesFilter(label, term) {
     if (!term) return true;
-    
     const haystack = label.toLowerCase();
-    
-    if (this.filterMatchMode === "startsWith") {
-      return haystack.startsWith(term);
-    }
-    
-    // "contains" mode - all tokens must match
+    if (this.filterMatchMode === "startsWith") return haystack.startsWith(term);
+    // "contains" mode – every whitespace-separated token must match
     const tokens = term.split(/\s+/).filter(Boolean);
-    return tokens.every(token => haystack.includes(token));
+    return tokens.every((token) => haystack.includes(token));
   }
 
+  // ---------------------------------------------------------------------------
+  // Transfer logic
+  // ---------------------------------------------------------------------------
+
   _getSelectedKeys(select) {
-    return Array.from(select.selectedOptions, opt => opt.dataset.key);
+    return Array.from(select.selectedOptions, (opt) => opt.dataset.key);
   }
 
   _moveSelected(fromType, toType) {
     const fromSelect = fromType === "available" ? this.availableSelect : this.chosenSelect;
-    const keys = this._getSelectedKeys(fromSelect);
-    if (keys.length > 0) {
-      this._transfer(keys, fromType, toType);
-    }
+    const keys = this._getSelectedKeys(fromSelect).filter((key) => {
+      const meta = this.options.get(key);
+      return meta && !meta.disabled;
+    });
+    if (keys.length > 0) this._transfer(keys, fromType, toType);
   }
 
   _moveAll(fromType, toType) {
-    const keys = fromType === "available" ? [...this.available] : [...this.chosen];
-    if (keys.length > 0) {
-      this._transfer(keys, fromType, toType);
-    }
+    const source = fromType === "available" ? this.available : this.chosen;
+    const keys = source.filter((key) => {
+      const meta = this.options.get(key);
+      return meta && !meta.disabled;
+    });
+    if (keys.length > 0) this._transfer(keys, fromType, toType);
   }
 
   _transfer(keys, fromType, toType) {
     const from = fromType === "available" ? this.available : this.chosen;
     const to = toType === "available" ? this.available : this.chosen;
-    
     const keySet = new Set(keys);
-    
+
     // Remove from source
-    const remaining = from.filter(key => !keySet.has(key));
+    const remaining = from.filter((key) => !keySet.has(key));
     from.splice(0, from.length, ...remaining);
-    
+
     // Add to target
     to.push(...keys);
-    
+
     // Sort
     this._sortByIndex(from);
     if (!this.preserveSelectionOrder || toType === "available") {
       this._sortByIndex(to);
     }
-    
-    // Update and notify
-    this._render();
+
+    // Sync state to original <select> FIRST, then render, then notify.
     this._syncToOriginal();
+    this._render();
     this._dispatchChange();
   }
 
   _syncToOriginal() {
     const chosenSet = new Set(this.chosen);
-    this.options.forEach(meta => {
+    this.options.forEach((meta) => {
       meta.original.selected = chosenSet.has(meta.key);
     });
   }
@@ -406,12 +531,16 @@ export class FilteredSelectMultiple {
     this.selectElement.dispatchEvent(event);
   }
 
+  // ---------------------------------------------------------------------------
+  // Button state management
+  // ---------------------------------------------------------------------------
+
   _updateButtons() {
     const hasAvailableSelection = this.availableSelect.selectedOptions.length > 0;
     const hasChosenSelection = this.chosenSelect.selectedOptions.length > 0;
-    const hasAvailableItems = this.available.length > 0;
-    const hasChosenItems = this.chosen.length > 0;
-    
+    const hasAvailableItems = this.available.some((k) => !this.options.get(k)?.disabled);
+    const hasChosenItems = this.chosen.some((k) => !this.options.get(k)?.disabled);
+
     this._setButtonState("addSelected", !hasAvailableSelection);
     this._setButtonState("removeSelected", !hasChosenSelection);
     this._setButtonState("addAll", !hasAvailableItems);
@@ -424,21 +553,23 @@ export class FilteredSelectMultiple {
 
     button.disabled = disabled;
 
-    // Rebuild className from scratch to avoid classList issues with spaces
     const baseClasses = this.theme.button.split(/\s+/).filter(Boolean);
-    const actionClasses = (this.theme[`button_${action}`] || '').split(/\s+/).filter(Boolean);
-    const disabledClasses = (this.theme.buttonDisabled || '').split(/\s+/).filter(Boolean);
+    const actionKey = `button${action.charAt(0).toUpperCase()}${action.slice(1)}`;
+    const actionClasses = (this.theme[actionKey] || "").split(/\s+/).filter(Boolean);
+    const disabledClasses = (this.theme.buttonDisabled || "").split(/\s+/).filter(Boolean);
 
-    let finalClasses = [...baseClasses, ...actionClasses];
-    if (disabled) {
-      finalClasses.push(...disabledClasses);
-    }
-
-    button.className = [...new Set(finalClasses)].join(' ');
+    const finalClasses = [...baseClasses, ...actionClasses];
+    if (disabled) finalClasses.push(...disabledClasses);
+    button.className = [...new Set(finalClasses)].join(" ");
   }
 
-  /** Revert the widget and show the original select element */
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /** Revert the widget and restore the original <select> element. */
   destroy() {
+    this.#abortController.abort();
     this.container.remove();
     this.selectElement.style.display = this.previousDisplay;
     this.selectElement.removeAttribute("data-filtered-select-multiple");

package/src/icons.js

@@ -0,0 +1,18 @@
+/**
+ * SVG icon strings for transfer buttons (Heroicons, MIT license).
+ */
+
+export const icons = {
+  addAll: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" style="height:1.2em;width:auto;">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m5.25 4.5 7.5 7.5-7.5 7.5m6-15 7.5 7.5-7.5 7.5" />
+</svg>`,
+  addSelected: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" style="height:1.2em;width:auto;">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+</svg>`,
+  removeSelected: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" style="height:1.2em;width:auto;">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 19.5 8.25 12l7.5-7.5" />
+</svg>`,
+  removeAll: `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" style="height:1.2em;width:auto;">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m18.75 4.5-7.5 7.5 7.5 7.5m-6-15L5.25 12l7.5 7.5" />
+</svg>`,
+};

package/src/themes.js

@@ -1,6 +1,9 @@
 /**
- * Theme definitions for FilteredSelectMultiple widget
- * Simple objects mapping element types to CSS class strings
+ * Theme definitions for FilteredSelectMultiple widget.
+ * Plain objects mapping element roles to CSS class strings.
+ *
+ * All keys use camelCase. Every key listed in defaultTheme MUST be present
+ * in custom themes (missing keys are filled from defaultTheme at runtime).
  */
 
 /**
@@ -16,12 +19,12 @@ export const defaultTheme = {
   select: "fsm-select",
   controls: "fsm-controls",
   button: "fsm-button",
-  button_addAll: "fsm-add-all",
-  button_addSelected: "fsm-add-selected",
-  button_removeSelected: "fsm-remove-selected",
-  button_removeAll: "fsm-remove-all",
+  buttonAddAll: "fsm-add-all",
+  buttonAddSelected: "fsm-add-selected",
+  buttonRemoveSelected: "fsm-remove-selected",
+  buttonRemoveAll: "fsm-remove-all",
   buttonDisabled: "fsm-button-disabled",
-  button_svg: "fsm-button-svg",
+  counter: "fsm-counter",
 };
 
 /**
@@ -36,13 +39,13 @@ export const bootstrap5Theme = {
   filter: "form-control form-control-sm mb-2",
   select: "form-select flex-grow-1",
   controls: "d-flex flex-column justify-content-center gap-2 px-3",
-  button: "btn btn-sm btn-primary",
-  button_addAll: "",
-  button_addSelected: "",
-  button_removeSelected: "",
-  button_removeAll: "",
-  buttonDisabled: "disabled",
-  button_svg: "d-inline-block",
+  button: "btn btn-sm d-inline-flex align-items-center gap-1",
+  buttonAddAll: "btn-outline-primary justify-content-end",
+  buttonAddSelected: "btn-primary justify-content-end",
+  buttonRemoveSelected: "btn-primary justify-content-start",
+  buttonRemoveAll: "btn-outline-primary justify-content-start",
+  buttonDisabled: "btn-secondary",
+  counter: "text-muted small",
 };
 
 /**
@@ -57,13 +60,13 @@ export const daisyUITheme = {
   filter: "input input-bordered input-sm mb-2 w-full",
   select: "select select-bordered w-full flex-grow",
   controls: "flex flex-col justify-center gap-2 px-4",
-  button: "btn btn-sm",
-  button_addAll: "btn-secondary",
-  button_addSelected: "btn-primary",
-  button_removeSelected: "btn-primary",
-  button_removeAll: "btn-secondary",
+  button: "btn btn-sm inline-flex items-center gap-1",
+  buttonAddAll: "btn-outline btn-secondary justify-end",
+  buttonAddSelected: "btn-primary justify-end",
+  buttonRemoveSelected: "btn-primary justify-start",
+  buttonRemoveAll: "btn-outline btn-secondary justify-start",
   buttonDisabled: "btn-disabled",
-  button_svg: "",
+  counter: "text-sm opacity-70",
 };
 
 /**
@@ -78,11 +81,11 @@ export const tailwindTheme = {
   filter: "border border-slate-300 rounded px-3 py-2 text-sm mb-2 focus:outline-none focus:ring-2 focus:ring-blue-500",
   select: "border border-slate-300 rounded px-2 py-1 min-w-[200px] flex-grow",
   controls: "flex flex-col justify-center gap-2 px-4",
-  button: "inline-flex items-center gap-2 px-3 py-2 text-sm border rounded hover:bg-slate-50 transition-colors",
-  button_addAll: "border-slate-300",
-  button_addSelected: "bg-blue-600 text-white border-blue-600 hover:bg-blue-700",
-  button_removeSelected: "bg-blue-600 text-white border-blue-600 hover:bg-blue-700",
-  button_removeAll: "border-slate-300",
-  buttonDisabled: "opacity-50 cursor-not-allowed",
-  button_svg: "",
+  button: "inline-flex items-center gap-2 px-3 py-2 text-sm border rounded transition-colors disabled:opacity-50 disabled:cursor-not-allowed",
+  buttonAddAll: "border-slate-300 hover:bg-slate-50 justify-end",
+  buttonAddSelected: "bg-blue-600 text-white border-blue-600 hover:bg-blue-700 justify-end",
+  buttonRemoveSelected: "bg-blue-600 text-white border-blue-600 hover:bg-blue-700 justify-start",
+  buttonRemoveAll: "border-slate-300 hover:bg-slate-50 justify-start",
+  buttonDisabled: "",
+  counter: "text-xs text-slate-500",
 };