snoopers-combobox-multi 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# `<combobox-multi>`
+
+Framework-agnostic multi-select combobox **web component**. Zero dependencies. All styles encapsulated in Shadow DOM. Works in plain HTML, React, Vue, Svelte, or any other framework.
+
+## Install
+
+Drop `src/combobox-multi.js` into your project, or install from npm once published:
+
+```bash
+npm install @modular365/combobox-multi
+```
+
+## Usage
+
+### Plain HTML
+
+```html
+<combobox-multi
+  name="colors"
+  label="Pick colours"
+  placeholder="Select..."
+  value="Red,Blue">
+  <script type="application/json">["Red","Green","Blue","Yellow"]</script>
+</combobox-multi>
+
+<script type="module">
+  import 'https://unpkg.com/@modular365/combobox-multi';
+</script>
+```
+
+### Setting options & value from JavaScript
+
+```js
+const el = document.querySelector('combobox-multi');
+el.options = ['Tel Aviv', 'Haifa', 'Jerusalem'];
+el.value   = ['Haifa'];   // array OR CSV string
+
+el.addEventListener('change', (e) => {
+  console.log(e.detail.value);  // ["Haifa"]
+});
+```
+
+### Inside a form
+
+The component is **form-associated** — its value serializes as a CSV string under the given `name`.
+
+```html
+<form>
+  <combobox-multi name="tags"><script type="application/json">["a","b","c"]</script></combobox-multi>
+  <button type="submit">Save</button>
+</form>
+```
+
+`new FormData(form).get('tags')` → `"a,c"` (CSV).
+
+---
+
+## API
+
+### Attributes
+
+| Attribute      | Type            | Default | Description                                                |
+|----------------|-----------------|---------|------------------------------------------------------------|
+| `name`         | string          | —       | Form field name (serializes as CSV via ElementInternals)   |
+| `label`        | string          | —       | Visible label above the trigger                            |
+| `placeholder`  | string          | `—`     | Text shown when nothing is selected                        |
+| `value`        | CSV string      | —       | Initial selected values, comma-separated                   |
+| `disabled`     | boolean         | `false` | Makes the control read-only                                |
+| `required`     | boolean         | `false` | Shows a red `*` next to the label                          |
+| `searchable`   | `"true"`/`"false"` | `"true"` | Show/hide the search input in the dropdown              |
+| `error`        | string          | —       | Error message shown under the control; adds red border     |
+| `dir`          | `ltr`/`rtl`     | inherit | Writing direction (uses CSS logical props under the hood)  |
+
+### Properties
+
+| Property   | Type        | Description                                        |
+|------------|-------------|----------------------------------------------------|
+| `options`  | `string[]`  | Full list of selectable options                    |
+| `value`    | `string[]`  | Currently selected options (setter accepts CSV)    |
+
+### Events
+
+| Event    | Detail                    | Fires                                |
+|----------|---------------------------|--------------------------------------|
+| `change` | `{ value: string[] }`     | When selection changes (any way)     |
+
+### CSS custom properties (overrides)
+
+All styles live in the Shadow DOM, but you can tweak the accent palette from the outside via CSS custom props on the host element:
+
+```css
+combobox-multi {
+  --cbx-accent: #10b981;        /* checkbox + chip accent */
+  --cbx-chip-bg: #ecfdf5;
+  --cbx-chip-text: #065f46;
+  --cbx-border: #d1d5db;
+  --cbx-border-focus: #10b981;
+  --cbx-radius: 8px;
+  --cbx-font: 'Inter', sans-serif;
+}
+```
+
+---
+
+## RTL / Hebrew
+
+The component is RTL-first. Set `dir="rtl"` anywhere up the tree (or on the element itself) and chips, chevron, and label will flip correctly — uses CSS logical properties (`margin-inline-start`, `inset-inline`, etc.).
+
+---
+
+## Demo
+
+```bash
+cd combobox-multi-package
+npm run demo
+# open http://localhost:5500/demo/
+```
+
+---
+
+## Why not just use `<select multiple>`?
+
+- `<select multiple>` is broken on iOS Safari (you can't deselect individual items without holding Cmd/Ctrl).
+- It doesn't support filtering/search.
+- Its styling is essentially untouchable across browsers.
+
+This component solves all three while keeping the standards-based feel: `value`, `name`, `change`, form submission — all work exactly like a native form control.
+
+---
+
+## Browser support
+
+- Chrome 90+ / Edge 90+
+- Safari 15+
+- Firefox 98+
+
+Uses: Custom Elements v1, Shadow DOM v1, `ElementInternals` (for form association).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "snoopers-combobox-multi",
+  "version": "0.1.0",
+  "description": "Framework-agnostic multi-select combobox web component with built-in search, chips, and form association. Zero dependencies.",
+  "type": "module",
+  "main": "src/combobox-multi.js",
+  "module": "src/combobox-multi.js",
+  "exports": {
+    ".": "./src/combobox-multi.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "combobox",
+    "multi-select",
+    "web-component",
+    "custom-element",
+    "dropdown",
+    "rtl",
+    "hebrew"
+  ],
+  "sideEffects": [
+    "./src/combobox-multi.js"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "demo": "npx --yes serve -l 5500 ."
+  }
+}

package/src/combobox-multi.js

@@ -0,0 +1,332 @@
+/**
+ * <combobox-multi> — framework-agnostic multi-select combobox web component.
+ *
+ * Usage:
+ *   <combobox-multi name="colors" label="Colors" placeholder="Select...">
+ *     <script type="application/json">["Red","Green","Blue"]</script>
+ *   </combobox-multi>
+ *
+ *   const el = document.querySelector('combobox-multi');
+ *   el.options = ['Red','Green','Blue'];
+ *   el.value   = ['Red'];                // array or CSV string
+ *   el.addEventListener('change', e => console.log(e.detail.value));
+ *
+ * Attributes:
+ *   name         — form field name (serializes as CSV via hidden input)
+ *   label        — visible label above the trigger
+ *   placeholder  — empty-state text (default: "—")
+ *   value        — initial CSV value
+ *   disabled     — readonly
+ *   dir          — "rtl" | "ltr" (inherits from document if omitted)
+ *   searchable   — "true" (default) | "false"
+ *
+ * Events:
+ *   change  — detail: { value: string[] }
+ */
+
+const ICON_CHEVRON = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>`;
+const ICON_X       = `<svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>`;
+const ICON_SEARCH  = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>`;
+
+const STYLES = `
+  :host {
+    --cbx-border: #d1d5db;
+    --cbx-border-focus: #3b82f6;
+    --cbx-bg: #ffffff;
+    --cbx-bg-hover: #f9fafb;
+    --cbx-text: #111827;
+    --cbx-text-muted: #9ca3af;
+    --cbx-text-label: #374151;
+    --cbx-chip-bg: #eff6ff;
+    --cbx-chip-text: #1d4ed8;
+    --cbx-accent: #2563eb;
+    --cbx-radius: 6px;
+    --cbx-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    --cbx-font-size: 14px;
+    display: block;
+    font-family: var(--cbx-font);
+    font-size: var(--cbx-font-size);
+    color: var(--cbx-text);
+    position: relative;
+  }
+  :host([disabled]) .trigger { background: #f9fafb; color: var(--cbx-text-muted); cursor: not-allowed; }
+
+  .field { display: flex; flex-direction: column; gap: 4px; }
+  .label { font-weight: 500; color: var(--cbx-text-label); font-size: 13px; }
+  .label .req { color: #ef4444; margin-inline-start: 2px; }
+
+  .trigger-wrap { position: relative; }
+  .trigger {
+    min-height: 38px; width: 100%;
+    display: flex; flex-wrap: wrap; align-items: center; gap: 4px;
+    padding: 6px 10px;
+    background: var(--cbx-bg);
+    border: 1px solid var(--cbx-border);
+    border-radius: var(--cbx-radius);
+    box-shadow: 0 1px 2px rgba(0,0,0,0.04);
+    cursor: pointer;
+    font: inherit; color: inherit;
+    text-align: start;
+  }
+  .trigger:focus-visible { outline: none; border-color: var(--cbx-border-focus); box-shadow: 0 0 0 1px var(--cbx-border-focus); }
+  .trigger.error { border-color: #fca5a5; }
+  .placeholder { color: var(--cbx-text-muted); }
+
+  .chip {
+    display: inline-flex; align-items: center; gap: 4px;
+    padding: 2px 6px;
+    background: var(--cbx-chip-bg); color: var(--cbx-chip-text);
+    border-radius: 4px;
+    font-size: 12px; line-height: 1.3;
+  }
+  .chip-x { display: inline-flex; cursor: pointer; opacity: .7; }
+  .chip-x:hover { opacity: 1; }
+
+  .chevron { margin-inline-start: auto; color: var(--cbx-text-muted); transition: transform .15s; flex-shrink: 0; }
+  :host([open]) .chevron { transform: rotate(180deg); }
+
+  .panel {
+    position: absolute; inset-inline: 0; top: 100%; margin-top: 4px;
+    background: var(--cbx-bg);
+    border: 1px solid #e5e7eb;
+    border-radius: var(--cbx-radius);
+    box-shadow: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1);
+    z-index: 1000;
+  }
+
+  .search {
+    display: flex; align-items: center; gap: 8px;
+    padding: 8px 10px;
+    border-bottom: 1px solid #f3f4f6;
+    color: var(--cbx-text-muted);
+  }
+  .search input {
+    flex: 1; background: transparent; border: 0; outline: none;
+    font: inherit; color: var(--cbx-text);
+  }
+  .search.hidden { display: none; }
+
+  .list {
+    max-height: min(60vh, 18rem);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    touch-action: pan-y;
+  }
+  .empty { padding: 8px 12px; color: var(--cbx-text-muted); }
+
+  .row {
+    display: flex; align-items: center; gap: 8px;
+    padding: 8px 12px;
+    cursor: pointer;
+    user-select: none;
+  }
+  .row:hover { background: var(--cbx-bg-hover); }
+  .row input[type="checkbox"] {
+    width: 16px; height: 16px;
+    accent-color: var(--cbx-accent);
+    flex-shrink: 0;
+  }
+  .row-label {
+    flex: 1;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+
+  .err { font-size: 12px; color: #dc2626; margin-top: 2px; }
+`;
+
+function parseOptions(input) {
+  if (Array.isArray(input)) return input.map(String);
+  if (typeof input === 'string' && input.trim()) {
+    try { const parsed = JSON.parse(input); if (Array.isArray(parsed)) return parsed.map(String); } catch {}
+    return input.split(',').map(s => s.trim()).filter(Boolean);
+  }
+  return [];
+}
+function parseValue(input) {
+  if (Array.isArray(input)) return input.map(String);
+  if (typeof input === 'string' && input) return input.split(',').map(s => s.trim()).filter(Boolean);
+  return [];
+}
+
+class ComboboxMulti extends HTMLElement {
+  static formAssociated = true;
+  static get observedAttributes() { return ['name', 'label', 'placeholder', 'value', 'disabled', 'searchable', 'error']; }
+
+  constructor() {
+    super();
+    this._options = [];
+    this._selected = [];
+    this._query = '';
+    this._open = false;
+    this._internals = typeof this.attachInternals === 'function' ? this.attachInternals() : null;
+    this.attachShadow({ mode: 'open' });
+    this._onDocDown = this._onDocDown.bind(this);
+  }
+
+  connectedCallback() {
+    const jsonChild = this.querySelector('script[type="application/json"]');
+    if (jsonChild && !this._options.length) this._options = parseOptions(jsonChild.textContent);
+
+    if (this.hasAttribute('value')) this._selected = parseValue(this.getAttribute('value'));
+
+    this._render();
+    document.addEventListener('mousedown', this._onDocDown);
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener('mousedown', this._onDocDown);
+  }
+
+  attributeChangedCallback(name, _old, val) {
+    if (name === 'value') this._selected = parseValue(val);
+    if (this.shadowRoot.firstChild) this._render();
+  }
+
+  get options() { return [...this._options]; }
+  set options(v) { this._options = parseOptions(v); this._render(); }
+
+  get value() { return [...this._selected]; }
+  set value(v) {
+    const next = parseValue(v);
+    this._selected = next;
+    this._syncFormValue();
+    this._render();
+  }
+
+  _syncFormValue() {
+    if (this._internals) this._internals.setFormValue(this._selected.join(','));
+  }
+
+  _onDocDown(e) {
+    if (!this._open) return;
+    if (e.composedPath().includes(this)) return;
+    this._open = false;
+    this._query = '';
+    this._render();
+  }
+
+  _toggle() {
+    if (this.hasAttribute('disabled')) return;
+    this._open = !this._open;
+    if (!this._open) this._query = '';
+    this._render();
+    if (this._open) {
+      const input = this.shadowRoot.querySelector('.search input');
+      if (input) setTimeout(() => input.focus(), 0);
+    }
+  }
+
+  _toggleOption(opt) {
+    const idx = this._selected.indexOf(opt);
+    if (idx >= 0) this._selected.splice(idx, 1);
+    else this._selected.push(opt);
+    this._syncFormValue();
+    this._emitChange();
+    this._render();
+  }
+
+  _removeOption(opt) {
+    this._selected = this._selected.filter(v => v !== opt);
+    this._syncFormValue();
+    this._emitChange();
+    this._render();
+  }
+
+  _emitChange() {
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: [...this._selected] },
+    }));
+  }
+
+  _filtered() {
+    const uniq = [...new Set(this._options)];
+    const q = this._query.trim().toLowerCase();
+    return q ? uniq.filter(o => o.toLowerCase().includes(q)) : uniq;
+  }
+
+  _render() {
+    if (this._open) this.setAttribute('open', ''); else this.removeAttribute('open');
+
+    const label = this.getAttribute('label');
+    const placeholder = this.getAttribute('placeholder') || '—';
+    const disabled = this.hasAttribute('disabled');
+    const required = this.hasAttribute('required');
+    const searchable = this.getAttribute('searchable') !== 'false';
+    const error = this.getAttribute('error');
+    const filtered = this._filtered();
+
+    const chipsHtml = this._selected.length === 0
+      ? `<span class="placeholder">${placeholder}</span>`
+      : this._selected.map(o => `
+          <span class="chip" data-opt="${encodeURIComponent(o)}">
+            <span class="chip-text">${escapeHtml(o)}</span>
+            ${disabled ? '' : `<span class="chip-x" data-remove="${encodeURIComponent(o)}">${ICON_X}</span>`}
+          </span>`).join('');
+
+    const listHtml = filtered.length === 0
+      ? `<div class="empty">—</div>`
+      : filtered.map(o => `
+          <label class="row" data-opt="${encodeURIComponent(o)}">
+            <input type="checkbox" ${this._selected.includes(o) ? 'checked' : ''}>
+            <span class="row-label">${escapeHtml(o)}</span>
+          </label>`).join('');
+
+    this.shadowRoot.innerHTML = `
+      <style>${STYLES}</style>
+      <div class="field">
+        ${label ? `<label class="label">${escapeHtml(label)}${required ? '<span class="req">*</span>' : ''}</label>` : ''}
+        <div class="trigger-wrap">
+          <button type="button" class="trigger${error ? ' error' : ''}" ${disabled ? 'disabled' : ''}>
+            ${chipsHtml}
+            ${disabled ? '' : `<span class="chevron">${ICON_CHEVRON}</span>`}
+          </button>
+          ${this._open ? `
+            <div class="panel">
+              <div class="search${searchable ? '' : ' hidden'}">
+                ${ICON_SEARCH}
+                <input type="text" value="${escapeAttr(this._query)}" />
+              </div>
+              <div class="list">${listHtml}</div>
+            </div>` : ''}
+        </div>
+        ${error ? `<p class="err">${escapeHtml(error)}</p>` : ''}
+      </div>
+    `;
+
+    const trigger = this.shadowRoot.querySelector('.trigger');
+    if (trigger) trigger.addEventListener('click', () => this._toggle());
+
+    this.shadowRoot.querySelectorAll('[data-remove]').forEach(el => {
+      el.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this._removeOption(decodeURIComponent(el.getAttribute('data-remove')));
+      });
+    });
+
+    this.shadowRoot.querySelectorAll('.row').forEach(row => {
+      row.addEventListener('click', (e) => {
+        if (e.target.tagName !== 'INPUT') e.preventDefault();
+        this._toggleOption(decodeURIComponent(row.getAttribute('data-opt')));
+      });
+    });
+
+    const searchInput = this.shadowRoot.querySelector('.search input');
+    if (searchInput) {
+      searchInput.addEventListener('input', (e) => { this._query = e.target.value; this._render(); });
+    }
+  }
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+function escapeAttr(s) { return escapeHtml(s); }
+
+if (typeof customElements !== 'undefined' && !customElements.get('combobox-multi')) {
+  customElements.define('combobox-multi', ComboboxMulti);
+}
+
+export { ComboboxMulti };
+export default ComboboxMulti;