@keenmate/web-multiselect 1.12.0-rc02 → 1.12.0-rc04

package/docs/usage.md

@@ -0,0 +1,311 @@
+# Usage & API reference
+
+This document covers the public surface of `<web-multiselect>` — declarative HTML usage, the full attribute / property / method / event tables, and the data shape.
+
+## Declarative (no JavaScript)
+
+Perfect for simple forms — just use standard HTML `<option>` and `<optgroup>` 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 -->
+<web-multiselect
+  id="my-select"
+  search-placeholder="Search options..."
+  initial-values='["js","ts"]'>
+</web-multiselect>
+```
+
+```typescript
+// Import the component (includes styles)
+import '@keenmate/web-multiselect';
+
+// Or import styles separately if needed
+import '@keenmate/web-multiselect/style.css';
+
+const multiselect = document.querySelector('web-multiselect');
+
+// Set options programmatically
+multiselect.options = [
+  { value: 'js', label: 'JavaScript', icon: '🟨' },
+  { value: 'ts', label: 'TypeScript', icon: '🔷' },
+  { value: 'py', label: 'Python', icon: '🐍' }
+];
+
+// Listen for events
+multiselect.addEventListener('change', (e) => {
+  console.log('Selected:', e.detail.selectedOptions);
+  console.log('Values:', e.detail.selectedValues);
+});
+
+// Public API
+const selected = multiselect.getSelected();
+multiselect.setSelected(['js', 'ts']);
+```
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `multiple` | `boolean` | `true` | Allow multiple selections |
+| `search-placeholder` | `string` | `'Search...'` | Placeholder text shown while search is usable |
+| `select-placeholder` | `string` | `'Pick an option...'` | Placeholder shown when search is disabled (`enable-search="false"`, or `search-input-mode` `readonly`/`hidden`) — the input acts as a picker, not a search box |
+| `no-data-placeholder` | `string` | - | Opt-in placeholder shown when the option list is empty, so users see there's no data without opening. Highest priority when the list is empty. Useful for cascade multiselects (a child whose parent isn't resolved yet) |
+| `search-hint` | `string` | - | Hint text shown above input when focused |
+| `allow-groups` | `boolean` | `true` | Enable option grouping |
+| `show-checkboxes` | `boolean` | `true` | Show checkboxes next to options |
+| `close-on-select` | `boolean` | `false` | Close dropdown after selecting |
+| `dropdown-min-width` | `string` | - | Min width for dropdown (e.g., `'20rem'`) |
+| `badges-display-mode` | `'pills' \| 'count' \| 'compact' \| 'partial' \| 'none'` | `'pills'` | How to display selected items. `compact`: first item + count. `none`: no display |
+| `badges-threshold` | `number` | - | Auto-switch mode when exceeded (see `badges-threshold-mode`) |
+| `badges-threshold-mode` | `'count' \| 'partial'` | `'count'` | Mode after threshold: `count` shows badge, `partial` shows limited badges + more badge |
+| `badges-max-visible` | `number` | `3` | Max badges shown in partial mode |
+| `badges-position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Position of badges container |
+| `show-counter` | `boolean` | `false` | Show `[3]` badge next to toggle icon |
+| `enable-badge-tooltips` | `boolean` | `false` | Enable tooltips on selected badges |
+| `badge-tooltip-placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Tooltip placement relative to badge |
+| `badge-tooltip-delay` | `number` | `100` | Delay in ms before showing tooltip |
+| `badge-tooltip-offset` | `number` | `8` | Distance in pixels between badge and tooltip |
+| `max-height` | `string` | `'20rem'` | Maximum height of dropdown |
+| `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 |
+| `search-debounce` | `number` | `0` | Debounce (ms) before the async `searchCallback` fires; coalesces keystroke bursts into one request. Resets on each keystroke. Async callback only — local filtering stays instant. `0` = no debounce |
+| `keep-options-on-search` | `boolean` | `true` | Keep initial options visible when `searchCallback` is active (hybrid search) |
+| `should-keep-search-on-close` | `boolean` | `true` | Preserve search text and filtered results when dropdown closes |
+| `sticky-actions` | `boolean` | `true` | Keep action buttons fixed at top while scrolling |
+| `actions-layout` | `'nowrap' \| 'wrap'` | `'nowrap'` | Layout mode for action buttons: `nowrap` (single row) or `wrap` (multi-row) |
+| `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 |
+| `search-value-member` | `string` | - | Property name for search text extraction from custom objects |
+| `icon-member` | `string` | - | Property name for icon extraction from custom objects |
+| `subtitle-member` | `string` | - | Property name for subtitle extraction from custom objects |
+| `group-member` | `string` | - | Property name for group extraction from custom objects |
+| `disabled-member` | `string` | - | Property name for disabled state extraction from custom objects |
+| `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
+
+```typescript
+// Get/set options
+multiselect.options = [
+  { value: 'js', label: 'JavaScript' },
+  { value: 'ts', label: 'TypeScript' }
+];
+
+// Async data loading
+multiselect.onSearch = async (searchTerm) => {
+  const response = await fetch(`/api/search?q=${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(/[̀-ͯ]/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);
+};
+
+multiselect.onDeselect = (option) => {
+  console.log('Deselected:', option);
+};
+
+multiselect.onChange = (selectedOptions) => {
+  console.log('Changed:', selectedOptions);
+};
+
+// Badge display customization (show different text in badges vs dropdown)
+multiselect.getBadgeDisplayCallback = (item) => {
+  // Show shorter text in badges (e.g., just name instead of "name (email)")
+  return item.name; // Dropdown might show "John Doe (john@example.com)"
+};
+
+// Badge tooltip customization
+multiselect.getBadgeTooltipCallback = (item) => {
+  return `${item.label} - ${item.subtitle}`;
+};
+
+// Action buttons (Select All, Clear All, custom actions)
+multiselect.actionButtons = [
+  {
+    action: 'select-all',
+    text: 'Select All',
+    tooltip: 'Select all items',
+    cssClass: 'my-custom-class',
+    isVisibleCallback: (multiselect) => multiselect.getSelected().length < 5  // Hide if 5+ selected
+  },
+  {
+    action: 'clear-all',
+    text: 'Clear All',
+    tooltip: 'Clear selection',
+    isVisible: true,  // Static visibility
+    isDisabled: false // Static disabled state
+  },
+  {
+    action: 'custom',
+    text: 'Invert',
+    tooltip: 'Invert selection',
+    onClick: (multiselect) => {
+      // Custom action - invert selection
+      const allValues = multiselect.options.map(opt => opt.value);
+      const selectedValues = multiselect.getValue();
+      const inverted = allValues.filter(v => !selectedValues.includes(v));
+      multiselect.setSelected(inverted);
+    },
+    // Dynamic callbacks (take priority over static properties)
+    isDisabledCallback: (multiselect) => multiselect.getSelected().length === 0,
+    getTextCallback: (multiselect) => multiselect.getSelected().length > 0 ? 'Invert' : 'Select Items First',
+    getClassCallback: (multiselect) => multiselect.getSelected().length > 0 ? 'active' : 'inactive'
+  }
+];
+
+// Counter i18n/pluralization
+multiselect.getCounterCallback = (count, moreCount) => {
+  if (moreCount !== undefined) {
+    return `+${moreCount} more`; // Partial mode badge
+  }
+  return `${count} selected`; // Count mode display
+};
+
+// Data extraction - Member properties (for simple property names)
+multiselect.valueMember = 'id';
+multiselect.displayValueMember = 'name';
+multiselect.iconMember = 'icon';
+multiselect.subtitleMember = 'description';
+multiselect.groupMember = 'category';
+multiselect.disabledMember = 'isDisabled';
+
+// Data extraction - Callback functions (for complex logic)
+multiselect.getValueCallback = (item) => item.id || item.value;
+multiselect.getDisplayValueCallback = (item) => item.label || item.name;
+multiselect.getSearchValueCallback = (item) => `${item.name} ${item.tags.join(' ')}`;
+multiselect.getIconCallback = (item) => item.icon || '📄';
+multiselect.getSubtitleCallback = (item) => `${item.price} - ${item.stock} in stock`;
+multiselect.getGroupCallback = (item) => item.category;
+multiselect.getDisabledCallback = (item) => item.stock === 0;
+
+// Custom rendering - Full HTML control
+multiselect.renderGroupLabelContentCallback = (groupName) => {
+  return `<strong>📦 ${groupName.toUpperCase()}</strong>`;
+};
+
+multiselect.renderOptionContentCallback = (item, context) => {
+  return `<strong>${item.name}</strong> <span class="badge">${item.status}</span>`;
+};
+
+multiselect.renderBadgeContentCallback = (item, context) => {
+  return context.isInPopover
+    ? `${item.icon} ${item.name} - ${item.description}`
+    : `${item.icon} ${item.name}`;
+};
+
+multiselect.renderSelectedContentCallback = (item) => {
+  // Customize selected item text in single-select mode (plain text only)
+  return item.firstName;
+};
+
+// Form integration
+multiselect.name = 'selected_items';
+multiselect.valueFormat = 'json'; // 'json' | 'csv' | 'array'
+multiselect.getValueFormatCallback = (values) => values.join('|'); // Custom format
+
+// Read-only properties
+const selectedValue = multiselect.selectedValue; // string | number | array | null
+const selectedItem = multiselect.selectedItem;   // First selected item object
+
+// Add new option callback
+multiselect.addNewCallback = async (value) => {
+  const newOption = await fetch('/api/options', {
+    method: 'POST',
+    body: JSON.stringify({ name: value })
+  }).then(r => r.json());
+  return newOption;
+};
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `getSelected()` | Get currently selected options as array of option objects |
+| `setSelected(values: (string \| number)[])` | Set selected values by ID/value |
+| `getValue()` | Get selected value(s) — returns single value in single-select mode, array in multi-select mode |
+| `setAttributes(attrs: Record<string, string \| number \| boolean \| null>)` | Set several attributes in a single in-place update (one re-render instead of one per attribute). Keys are kebab-case attribute names, as `setAttribute`; `null`/`undefined`/`false` removes the attribute, `true` sets it to `""`. Handy for i18n switches that change multiple strings at once |
+| `destroy()` | Clean up and destroy instance |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `select` | `{ option, selectedOptions }` | Fired when an option is selected |
+| `deselect` | `{ option, selectedOptions }` | Fired when an option is deselected |
+| `change` | `{ selectedOptions, selectedValues }` | Fired when selection changes |
+
+## Option structure
+
+```typescript
+interface MultiSelectOption {
+  value: string;           // Required: Unique identifier
+  label: string;           // Required: Display text
+  icon?: string;           // Optional: Icon or emoji
+  subtitle?: string;       // Optional: Subtitle/description
+  group?: string;          // Optional: Group name
+  disabled?: boolean;      // Optional: Disable selection
+}
+```
+
+The component also accepts:
+
+- **Tuple arrays** like `[['js', 'JavaScript'], ['ts', 'TypeScript']]` — first element becomes value, second becomes display text.
+- **Arbitrary custom objects** via member attributes (`value-member`, `display-value-member`, etc.) or callbacks (`getValueCallback`, `getDisplayValueCallback`, etc.). See [examples.md → Flexible Data Handling](./examples.md#flexible-data-handling).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-multiselect",
-  "version": "1.12.0-rc02",
+  "version": "1.12.0-rc04",
   "description": "Lightweight multiselect web component with typeahead search, rich content support, and excellent keyboard navigation",
   "type": "module",
   "main": "./dist/multiselect.umd.js",
@@ -30,6 +30,10 @@
   "files": [
     "dist",
     "src/css",
+    "docs/usage.md",
+    "docs/theming.md",
+    "docs/examples.md",
+    "docs/accessibility.md",
     "component-variables.manifest.json"
   ],
   "scripts": {
@@ -41,6 +45,9 @@
     "package": "npm run build && npm pack",
     "clean": "rimraf dist --glob \"*.tgz\"",
     "clean:dist": "rimraf dist",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:headed": "playwright test --headed",
@@ -71,10 +78,12 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
+    "happy-dom": "^15.11.7",
     "rimraf": "^5.0.5",
     "typescript": "^5.3.3",
     "vite": "^5.0.8",
-    "vite-plugin-dts": "^4.5.4"
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.1.9"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.5.3"