@keenmate/web-multiselect 1.0.0-rc05 → 1.0.0-rc08

package/README.md

@@ -7,7 +7,9 @@ A lightweight, accessible multiselect web component with typeahead search, RTL l
 
 ## Features
 
-- 🔍 **Typeahead Search** - Real-time filtering as you type
+- 📝 **Declarative HTML** - Use standard `<option>` and `<optgroup>` elements - no JavaScript required for simple cases!
+- ⚡ **Virtual Scrolling** - Handle 15,000+ options instantly (25× faster opening, 99.8% memory reduction)
+- 🔍 **Flexible Search Modes** - Filter (hide non-matches) or navigate (jump to matches, keep all visible)
 - ⌨️ **Keyboard Navigation** - Full keyboard support (arrows, Enter, Esc, Tab)
 - 🎨 **Rich Content** - Icons, subtitles, and multiline text support
 - 📊 **Multiple Display Modes** - Pills, count, compact, or partial (pills + threshold)
@@ -29,25 +31,51 @@ npm install @keenmate/web-multiselect
 
 ## Usage
 
-### Basic HTML
+### Declarative (No JavaScript!)
+
+Perfect for simple forms - just use standard HTML `<option>` elements:
+
+```html
+<!-- Simple choice -->
+<web-multiselect multiple="false">
+  <option value="yes">Yes</option>
+  <option value="no">No</option>
+  <option value="maybe" selected>Maybe</option>
+</web-multiselect>
+
+<!-- With icons -->
+<web-multiselect>
+  <option value="apple" data-icon="🍎">Apple</option>
+  <option value="banana" data-icon="🍌" selected>Banana</option>
+  <option value="orange" data-icon="🍊">Orange</option>
+</web-multiselect>
+
+<!-- With groups -->
+<web-multiselect>
+  <optgroup label="Frontend">
+    <option value="js" data-icon="🟨">JavaScript</option>
+    <option value="ts" data-icon="🔷">TypeScript</option>
+  </optgroup>
+  <optgroup label="Backend">
+    <option value="python" data-icon="🐍" selected>Python</option>
+    <option value="java" data-icon="☕">Java</option>
+  </optgroup>
+</web-multiselect>
+```
+
+### Programmatic (With JavaScript)
+
+For dynamic data and advanced features:
 
 ```html
 <!-- Multi-select -->
-<multi-select
+<web-multiselect
+  id="my-select"
   search-placeholder="Search options..."
   initial-values='["js","ts"]'>
-</multi-select>
-
-<!-- Single-select -->
-<multi-select
-  multiple="false"
-  search-placeholder="Select one..."
-  initial-values='["python"]'>
-</multi-select>
+</web-multiselect>
 ```
 
-### With JavaScript/TypeScript
-
 ```typescript
 // Import the component (includes styles)
 import '@keenmate/web-multiselect';
@@ -55,7 +83,7 @@ import '@keenmate/web-multiselect';
 // Or import styles separately if needed
 import '@keenmate/web-multiselect/style.css';
 
-const multiselect = document.querySelector('multi-select');
+const multiselect = document.querySelector('web-multiselect');
 
 // Set options programmatically
 multiselect.options = [
@@ -102,10 +130,12 @@ multiselect.setSelected(['js', 'ts']);
 | `empty-message` | `string` | `'No results found'` | Message when no options found |
 | `loading-message` | `string` | `'Loading...'` | Message while loading async data |
 | `min-search-length` | `number` | `0` | Minimum search length for async |
+| `keep-options-on-search` | `boolean` | `true` | Keep initial options visible when searchCallback is active (hybrid search) |
 | `sticky-actions` | `boolean` | `true` | Keep Select All/Clear All buttons fixed at top while scrolling |
 | `lock-placement` | `boolean` | `true` | Lock dropdown placement after first open to prevent flipping |
 | `enable-search` | `boolean` | `true` | Enable/disable search functionality |
 | `search-input-mode` | `'normal' \| 'readonly' \| 'hidden'` | `'normal'` | Search input display mode |
+| `search-mode` | `'filter' \| 'navigate'` | `'filter'` | Search behavior: 'filter' hides non-matches, 'navigate' jumps to matches |
 | `allow-add-new` | `boolean` | `false` | Allow adding new options not in the list |
 | `value-member` | `string` | - | Property name for value/ID extraction from custom objects |
 | `display-value-member` | `string` | - | Property name for display text extraction from custom objects |
@@ -117,6 +147,10 @@ multiselect.setSelected(['js', 'ts']);
 | `name` | `string` | - | HTML form field name for form integration (creates hidden input) |
 | `value-format` | `'json' \| 'csv' \| 'array'` | `'json'` | Format for form value serialization |
 | `initial-values` | `string` (JSON array) | - | Pre-selected values |
+| `enable-virtual-scroll` | `boolean` | `false` | Enable virtual scrolling for large datasets |
+| `virtual-scroll-threshold` | `number` | `100` | Minimum items before virtual scroll activates |
+| `option-height` | `number` | `50` | Fixed height for each option in pixels (required for virtual scroll) |
+| `virtual-scroll-buffer` | `number` | `10` | Buffer size - extra items rendered above/below viewport |
 
 ## Properties
 
@@ -133,6 +167,17 @@ multiselect.onSearch = async (searchTerm) => {
   return await response.json();
 };
 
+// Pre-process search terms before calling searchCallback
+multiselect.beforeSearchCallback = (searchTerm) => {
+  // Remove accents: "café" → "cafe"
+  const normalized = searchTerm.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+  // Block search if too short (return null to prevent search)
+  if (normalized.length < 2) return null;
+
+  return normalized; // Return transformed term
+};
+
 // Event callbacks
 multiselect.onSelect = (option) => {
   console.log('Selected:', option);
@@ -222,6 +267,7 @@ multiselect.addNewCallback = async (value) => {
 ## Keyboard Shortcuts
 
 - **↑ ↓** - Navigate up/down through options
+- **Ctrl+↑ Ctrl+↓** - Jump between matched items (navigate mode only)
 - **Enter** - Select focused option
 - **Escape** - Close dropdown
 - **Tab** - Close dropdown and move to next field
@@ -234,7 +280,7 @@ multiselect.addNewCallback = async (value) => {
 Icons support multiple formats - emojis, SVG markup, Font Awesome, images, or any HTML:
 
 ```html
-<multi-select id="frameworks"></multi-select>
+<web-multiselect id="frameworks"></web-multiselect>
 
 <script type="module">
   const select = document.getElementById('frameworks');
@@ -281,12 +327,12 @@ select.options = [
 ### Async Data Loading
 
 ```html
-<multi-select
+<web-multiselect
   id="async-select"
   min-search-length="2"
   loading-message="Searching..."
   empty-message="No products found">
-</multi-select>
+</web-multiselect>
 
 <script type="module">
   const select = document.getElementById('async-select');
@@ -299,33 +345,243 @@ select.options = [
 </script>
 ```
 
+### Hybrid Static + Dynamic Search
+
+Show popular items initially, then switch to full database search when the user types. Perfect for showing "Top 10" items while supporting comprehensive search:
+
+```html
+<web-multiselect
+  id="hybrid-select"
+  min-search-length="3"
+  keep-options-on-search="true">
+</web-multiselect>
+
+<script type="module">
+  const select = document.getElementById('hybrid-select');
+
+  // Set initial popular items (shown when dropdown opens)
+  select.options = [
+    { id: 1, name: 'React' },
+    { id: 2, name: 'Vue' },
+    { id: 3, name: 'Angular' },
+    { id: 4, name: 'Svelte' },
+    { id: 5, name: 'Solid' }
+  ];
+
+  // Pre-process search terms (remove accents, validate, etc.)
+  select.beforeSearchCallback = (searchTerm) => {
+    // Remove accents: "café" → "cafe"
+    const normalized = searchTerm.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+    // Block search if too short (return null to prevent search)
+    if (normalized.length < 2) return null;
+
+    return normalized;
+  };
+
+  // Search full database when user types 3+ characters
+  select.onSearch = async (searchTerm) => {
+    const response = await fetch(`/api/frameworks/search?q=${searchTerm}`);
+    return await response.json();
+  };
+</script>
+```
+
+**How it works:**
+1. **Dropdown opens** → Shows 5 popular frameworks
+2. **User types "rea"** → Calls API, shows all matching results from database
+3. **User clears search** → Shows 5 popular frameworks again
+4. **User types "café"** → `beforeSearchCallback` converts to "cafe", then searches
+
+**Key options:**
+- `keep-options-on-search="true"` (default) - Keep initial options visible when search is empty/short
+- `beforeSearchCallback` - Transform search text or block search by returning `null`
+- `min-search-length` - Minimum characters before triggering search (shows initial options below this)
+
+### Virtual Scrolling for Large Datasets
+
+Handle 10,000+ options with smooth 60fps performance by rendering only visible items:
+
+```html
+<web-multiselect
+  id="large-dataset"
+  enable-virtual-scroll="true"
+  virtual-scroll-threshold="100"
+  option-height="50"
+  virtual-scroll-buffer="10"
+  search-mode="filter"
+  max-height="400px">
+</web-multiselect>
+
+<script type="module">
+  import '@keenmate/web-multiselect';
+
+  const select = document.getElementById('large-dataset');
+
+  // Generate 15,000 options
+  const largeDataset = Array.from({ length: 15000 }, (_, i) => ({
+    value: i,
+    label: `Item ${i.toString().padStart(5, '0')}`
+  }));
+
+  select.options = largeDataset;
+</script>
+```
+
+**Performance Comparison (15,000 items):**
+
+| Metric | Without Virtual Scroll | With Virtual Scroll | Improvement |
+|--------|------------------------|---------------------|-------------|
+| Initial render | 750ms | 30ms | **25× faster** |
+| Search keystroke | 200-500ms | 15ms | **13-33× faster** |
+| DOM nodes | 15,000 | ~30 | **99.8% reduction** |
+| Memory usage | ~7.5 MB | ~15 KB | **500× less** |
+
+**Configuration:**
+
+- `enable-virtual-scroll="true"` - Enable virtual scrolling (default: `false`)
+- `virtual-scroll-threshold="100"` - Auto-activate when this many items are present (default: `100`)
+- `option-height="50"` - Fixed height per option in pixels (default: `50px`)
+- `virtual-scroll-buffer="10"` - Extra items rendered above/below viewport for smooth scrolling (default: `10`)
+
+**How it works:**
+- Only renders ~30 visible items instead of all 15,000 DOM elements
+- Uses absolute positioning with calculated offsets
+- Maintains 10-item buffer zones above/below viewport for smooth scrolling
+- Automatically calculates visible range based on scroll position
+- Works seamlessly with search filtering and selection
+
+**Requirements:**
+- All options must have the same fixed height (enforced via CSS)
+- Not compatible with grouped options (automatically falls back to normal rendering)
+- Works with both filter and navigate search modes
+
+**Example with search:**
+```html
+<!-- Virtual scroll + filter search for optimal large dataset performance -->
+<web-multiselect
+  id="products"
+  enable-virtual-scroll="true"
+  search-mode="filter"
+  value-member="id"
+  display-value-member="name"
+  max-height="400px">
+</web-multiselect>
+
+<script type="module">
+  const select = document.getElementById('products');
+
+  // Load from API
+  const response = await fetch('/api/products');
+  const products = await response.json();
+
+  select.options = products; // Could be 10,000+ items
+</script>
+```
+
+**Live Demo:**
+See [examples-performance.html](examples-performance.html) for a working demo with 15,000 randomly generated options.
+
+### Virtual Scrolling
+
+Handle massive datasets (10,000+ items) with instant performance using virtual scrolling. Only visible items (~30) are rendered in the DOM, dramatically reducing memory usage and improving responsiveness.
+
+**Enable virtual scrolling:**
+```html
+<web-multiselect
+  enable-virtual-scroll="true"
+  virtual-scroll-threshold="100"
+  option-height="50"
+  virtual-scroll-buffer="10">
+</web-multiselect>
+```
+
+**Performance improvements with 15,000 items:**
+- **Dropdown opening**: 750ms → 30ms (25× faster)
+- **Search performance**: 200-500ms → 15ms per keystroke (13-33× faster)
+- **Memory usage**: 7.5 MB → 15 KB (99.8% reduction)
+- **DOM nodes**: 15,000 → ~30 visible items
+
+**Configuration:**
+- `enable-virtual-scroll="true"` - Opt-in to virtual scrolling
+- `virtual-scroll-threshold="100"` - Auto-activates at 100+ items (default)
+- `option-height="50"` - Fixed height per option in pixels (default: 50px)
+- `virtual-scroll-buffer="10"` - Extra items rendered above/below viewport (default: 10)
+
+**Features:**
+- Full keyboard navigation (arrows, Page Up/Down, Home/End)
+- Smooth mouse wheel scrolling
+- Drag scrollbar support
+- Works with search in both filter and navigate modes
+- Automatic activation based on threshold
+
+**Limitations:**
+- Groups (`<optgroup>`) are disabled in virtual scroll mode (automatically falls back to standard rendering)
+- All options must have consistent height (enforced via CSS)
+
+**Live Demo:**
+See [examples-performance.html](examples-performance.html) for a working demo testing virtual scroll with 15,000 randomly generated options.
+
+### Search Modes: Filter vs Navigate
+
+Choose between two search behaviors:
+
+**Filter Mode** (default) - Hide non-matching options as you type:
+```html
+<web-multiselect search-mode="filter" id="countries"></web-multiselect>
+```
+
+**Navigate Mode** - Keep all options visible, jump to matches:
+```html
+<web-multiselect search-mode="navigate" id="states"></web-multiselect>
+
+<script>
+  const select = document.getElementById('states');
+  select.options = [...50 US states...];
+
+  // User types "cal" → Jumps to "California", shows all states
+  // Matching options are highlighted with left border
+</script>
+```
+
+**When to use each mode:**
+- **Filter Mode**: Large datasets where narrowing down is essential (product catalogs, user lists, search results)
+- **Navigate Mode**: Quick selection from familiar lists (countries, states, keyboard shortcuts, known options)
+
+**Key differences:**
+- Filter mode hides non-matches, navigate mode highlights matches with a left border
+- Navigate mode keeps previous focus if no match is found (type "xyz" → stays on current option)
+- Navigate mode only works with local data (automatically falls back to filter mode when using `searchCallback`)
+- Both modes respect `beforeSearchCallback` for search term preprocessing (accent removal, validation)
+- **Ctrl+↑/↓** jumps between matches only (navigate mode) - regular arrows navigate through all items
+
 ### Display Modes
 
 Perfect for different use cases and space constraints:
 
 ```html
 <!-- Pills mode (default) - Show all selections as removable pills -->
-<multi-select pills-display-mode="pills"></multi-select>
+<web-multiselect pills-display-mode="pills"></web-multiselect>
 
 <!-- Count mode - Show only count badge -->
-<multi-select pills-display-mode="count" show-count-badge="true"></multi-select>
+<web-multiselect pills-display-mode="count" show-count-badge="true"></web-multiselect>
 
 <!-- Compact mode - Show first item + count -->
-<multi-select pills-display-mode="compact"></multi-select>
+<web-multiselect pills-display-mode="compact"></web-multiselect>
 
 <!-- Auto-switch from pills to count at threshold -->
-<multi-select
+<web-multiselect
   pills-threshold="3"
   pills-threshold-mode="count"
   show-count-badge="true">
-</multi-select>
+</web-multiselect>
 
 <!-- Partial mode - Show limited pills + "+X more" badge -->
-<multi-select
+<web-multiselect
   pills-threshold="5"
   pills-threshold-mode="partial"
   pills-max-visible="3">
-</multi-select>
+</web-multiselect>
 ```
 
 ### Pills Positioning
@@ -334,16 +590,16 @@ Control where selected item badges appear relative to the input:
 
 ```html
 <!-- Pills below input (default) -->
-<multi-select pills-position="bottom"></multi-select>
+<web-multiselect pills-position="bottom"></web-multiselect>
 
 <!-- Pills above input -->
-<multi-select pills-position="top"></multi-select>
+<web-multiselect pills-position="top"></web-multiselect>
 
 <!-- Pills to the left of input -->
-<multi-select pills-position="left"></multi-select>
+<web-multiselect pills-position="left"></web-multiselect>
 
 <!-- Pills to the right of input -->
-<multi-select pills-position="right"></multi-select>
+<web-multiselect pills-position="right"></web-multiselect>
 ```
 
 **Note:** In RTL mode, left/right positions are automatically mirrored - `pills-position="left"` will appear on the physical right side in RTL languages.
@@ -354,19 +610,19 @@ Enable tooltips on selected item pills with customizable placement and delay:
 
 ```html
 <!-- Basic tooltips -->
-<multi-select
+<web-multiselect
   enable-pill-tooltips="true"
   pill-tooltip-placement="top">
-</multi-select>
+</web-multiselect>
 
 <!-- Fast tooltips with custom delay -->
-<multi-select
+<web-multiselect
   enable-pill-tooltips="true"
   pill-tooltip-delay="100">
-</multi-select>
+</web-multiselect>
 
 <script type="module">
-  const select = document.querySelector('multi-select');
+  const select = document.querySelector('web-multiselect');
 
   // Custom tooltip content
   select.getPillTooltipCallback = (item) => {
@@ -380,12 +636,12 @@ Enable tooltips on selected item pills with customizable placement and delay:
 Customize count pill text for proper pluralization and localization:
 
 ```html
-<multi-select
+<web-multiselect
   id="i18n-select"
   pills-threshold="5"
   pills-threshold-mode="partial"
   pills-max-visible="3">
-</multi-select>
+</web-multiselect>
 
 <script type="module">
   const select = document.getElementById('i18n-select');
@@ -408,11 +664,11 @@ Full RTL support for Arabic, Hebrew, Persian, Urdu, and other right-to-left lang
 
 ```html
 <!-- Automatic RTL detection from dir attribute -->
-<multi-select dir="rtl" search-placeholder="ابحث..."></multi-select>
+<web-multiselect dir="rtl" search-placeholder="ابحث..."></web-multiselect>
 
 <!-- RTL inherited from parent element -->
 <div dir="rtl">
-  <multi-select search-placeholder="חיפוש..."></multi-select>
+  <web-multiselect search-placeholder="חיפוש..."></web-multiselect>
 </div>
 
 <!-- RTL on page level -->
@@ -438,14 +694,14 @@ The component supports **any data structure** through a member/callback pattern,
 For objects with consistent property names, use member attributes:
 
 ```html
-<multi-select
+<web-multiselect
   id="products"
   value-member="productId"
   display-value-member="productName"
   icon-member="icon"
   subtitle-member="description"
   group-member="category">
-</multi-select>
+</web-multiselect>
 
 <script type="module">
   const select = document.getElementById('products');
@@ -473,7 +729,7 @@ For objects with consistent property names, use member attributes:
 For complex data extraction or conditional logic, use callbacks:
 
 ```javascript
-const select = document.querySelector('multi-select');
+const select = document.querySelector('web-multiselect');
 
 // Custom value extraction
 select.getValueCallback = (item) => item.id || item.code || item.value;
@@ -546,7 +802,7 @@ interface Product {
   category: string;
 }
 
-const select = document.querySelector<MultiSelectElement<Product>>('multi-select');
+const select = document.querySelector<MultiSelectElement<Product>>('web-multiselect');
 select.options = [
   { id: 'p1', name: 'Laptop', price: 999, category: 'Electronics' }
 ];
@@ -561,11 +817,11 @@ The component seamlessly integrates with standard HTML forms by automatically cr
 ```html
 <form id="userForm" action="/submit" method="POST">
   <label>Select Skills:</label>
-  <multi-select
+  <web-multiselect
     name="skills"
     value-format="json"
     multiple="true">
-  </multi-select>
+  </web-multiselect>
 
   <button type="submit">Submit</button>
 </form>
@@ -574,7 +830,7 @@ The component seamlessly integrates with standard HTML forms by automatically cr
   import '@keenmate/web-multiselect';
 
   const form = document.getElementById('userForm');
-  const select = form.querySelector('multi-select');
+  const select = form.querySelector('web-multiselect');
 
   select.options = [
     { value: 'js', label: 'JavaScript' },
@@ -600,19 +856,19 @@ Choose how selected values are serialized in forms:
 
 **JSON Format** (default):
 ```html
-<multi-select name="items" value-format="json"></multi-select>
+<web-multiselect name="items" value-format="json"></web-multiselect>
 <!-- FormData result: items = ["item1","item2","item3"] -->
 ```
 
 **CSV Format**:
 ```html
-<multi-select name="items" value-format="csv"></multi-select>
+<web-multiselect name="items" value-format="csv"></web-multiselect>
 <!-- FormData result: items = "item1,item2,item3" -->
 ```
 
 **Array Format** (multiple inputs):
 ```html
-<multi-select name="items" value-format="array"></multi-select>
+<web-multiselect name="items" value-format="array"></web-multiselect>
 <!-- FormData result:
      items[] = "item1"
      items[] = "item2"
@@ -625,7 +881,7 @@ Choose how selected values are serialized in forms:
 For advanced use cases, provide a custom formatting function:
 
 ```javascript
-const select = document.querySelector('multi-select');
+const select = document.querySelector('web-multiselect');
 
 select.name = 'product_ids';
 select.getValueFormatCallback = (values) => {
@@ -750,15 +1006,32 @@ You can customize the component using CSS variables even with just a `<script>`
 
 ### Available CSS Variables
 
-The component exposes 200+ SCSS variables as CSS custom properties with fallbacks. Below are the **50+ most commonly customized variables** organized by category.
+The component exposes **150+ CSS custom properties** defined at the `:host` level, making them inspectable and overridable. Below are the **50+ most commonly customized variables** organized by category.
+
+#### Inspecting Variables in DevTools
+
+All CSS custom properties are now defined at the `:host` level in the compiled CSS, making them visible in browser DevTools:
+
+1. Open DevTools (F12) and select the `<web-multiselect>` element
+2. In the **Styles** panel, look for the `:host` selector
+3. You'll see all 150+ variables with their default values
+4. Edit values live to preview changes instantly
+
+**CSS variables work with Shadow DOM** because they inherit through the shadow boundary. This means you can customize the component from outside:
+
+```html
+<style>
+  /* These variables will penetrate into the Shadow DOM */
+  multi-select {
+    --ml-accent-color: #10b981;  /* Changes primary color */
+    --ml-input-border-radius: 0.5rem;  /* Rounds input corners */
+  }
+</style>
+```
 
-For the complete list of all available CSS variables, see the SCSS source files:
-- [_variables.scss](./src/scss/_variables.scss) - Foundation variables (colors, spacing, typography)
-- [_input-dropdown.scss](./src/scss/_input-dropdown.scss) - Input and dropdown styles
-- [_pills-display.scss](./src/scss/_pills-display.scss) - Pills and count display
-- [_options.scss](./src/scss/_options.scss) - Options and groups
-- [_tooltip.scss](./src/scss/_tooltip.scss) - Tooltip styles
-- [_rtl.scss](./src/scss/_rtl.scss) - RTL overrides
+For the complete list of all available CSS variables, see:
+- [_css-variables.scss](./src/scss/_css-variables.scss) - All 150+ CSS custom properties at `:host` level
+- [_variables.scss](./src/scss/_variables.scss) - Foundation SCSS variables (colors, spacing, typography)
 
 #### Colors