custom-select-web-component 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# Custom Select Web Component
+
+Reusable Web Component for select inputs with optional superuser editing and optional IndexedDB persistence.
+
+## Quick start
+
+### Use directly in a page
+
+```html
+<script type="module" src="./src/custom-select.js"></script>
+
+<custom-select label="Soil type">
+  <option value="">Pick one...</option>
+  <option value="clay">Clay</option>
+  <option value="sandy">Sandy</option>
+</custom-select>
+```
+
+### Use as a package
+
+```js
+import 'custom-select-web-component';
+```
+
+## API reference
+
+### Element
+
+- Tag: `<custom-select>`
+
+### Attributes
+
+- `label`: Label text shown above or left of the control.
+- `editable`: Enables Edit... mode, add option, and delete selected option.
+- `label-position="left"`: Places label to the left. Default is top layout.
+- `storage-key`: Optional persistence key override.
+- `id` / `name`: Used as persistence key fallback when `storage-key` is not set.
+
+### Properties
+
+- `value: string`: Gets or sets selected value.
+
+### Methods
+
+- `clearPersistedOptions(): Promise<void>`: Deletes this component's saved options from IndexedDB.
+- `resetToInitialOptions(): Promise<void>`: Restores options from initial markup snapshot and persists that state when enabled.
+
+### Events
+
+- `change`: Fired when selected value changes.
+  - `event.detail.value`
+- `editmodechange`: Fired when edit mode toggles.
+  - `event.detail.editMode`
+- `optionadded`: Fired when a new option is added from editor input.
+  - `event.detail.value`
+  - `event.detail.text`
+
+## Styling hooks
+
+Set these CSS custom properties on `custom-select`:
+
+- `--control-font-size`: Shared size for select and editor. Default `1rem`.
+- `--label-font-size`: Optional label override. Defaults to `--control-font-size`.
+- `--label-width`: Label column width for left layout. Default `8rem`.
+
+Example:
+
+```css
+custom-select {
+  --control-font-size: 1rem;
+}
+
+custom-select.left-label {
+  --label-width: 6rem;
+}
+```
+
+## Persistence behavior
+
+Persistence is enabled only when `editable` is present and browser IndexedDB is available.
+
+Storage key resolution order:
+
+1. `storage-key`
+2. `id`
+3. `name`
+
+Stored record key format:
+
+- `dropdown-options:<resolved-key>`
+
+## Packaging and publish
+
+Project is configured as a no-build ESM package.
+
+- Entry point: `custom-select.js`
+- Source: `src/custom-select.js`
+- Manifest: `package.json`
+
+Create local package tarball:
+
+```powershell
+npm pack
+```
+
+Install tarball in another project:
+
+```powershell
+npm install ../path/to/custom-select-web-component-0.1.0.tgz
+```
+
+Publish to npm:
+
+```powershell
+npm login
+npm publish --access public
+```
+
+Before publishing, update in `package.json`:
+
+- `name` (must be unique on npm)
+- `version`
+- `license`
+
+## Development
+
+Run locally with a static server:
+
+```powershell
+python -m http.server 5500
+```
+
+Open:
+
+- `http://localhost:5500`
+
+## Versioning and release checklist
+
+Use semantic versioning:
+
+- `MAJOR`: Breaking API changes
+- `MINOR`: New backward-compatible features
+- `PATCH`: Backward-compatible fixes
+
+Suggested release flow:
+
+1. Ensure working tree is clean and all changes are committed.
+2. Update `package.json` version.
+3. Run local sanity test:
+
+```powershell
+npm pack
+```
+
+4. Test package install in a separate project:
+
+```powershell
+npm install ../path/to/custom-select-web-component-<version>.tgz
+```
+
+5. Verify import and basic behaviors:
+- component registration
+- `editable` flow
+- persistence restore
+- reset/clear methods
+
+6. Publish:
+
+```powershell
+npm publish --access public
+```
+
+7. Create a git tag for the published version (recommended):
+
+```powershell
+git tag v<version>
+git push origin v<version>
+```

package/custom-select.js

@@ -0,0 +1 @@
+export { CustomSelect } from './src/custom-select.js';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "custom-select-web-component",
+  "version": "0.1.0",
+  "description": "Editable custom-select Web Component with optional IndexedDB persistence",
+  "type": "module",
+  "main": "./custom-select.js",
+  "module": "./custom-select.js",
+  "exports": {
+    ".": "./custom-select.js",
+    "./custom-select": "./custom-select.js",
+    "./src/custom-select.js": "./src/custom-select.js"
+  },
+  "files": [
+    "custom-select.js",
+    "src/custom-select.js",
+    "README.md"
+  ],
+  "keywords": [
+    "web-component",
+    "custom-element",
+    "select",
+    "dropdown",
+    "indexeddb"
+  ],
+  "license": "MIT"
+}

package/src/custom-select.js

@@ -0,0 +1,672 @@
+const template = document.createElement('template');
+const EDIT_OPTION_VALUE = 'makeEditable';
+const EDIT_OPTION_LABEL = 'Edit...';
+const DB_NAME = 'custom-select-db';
+const DB_VERSION = 1;
+const STORE_NAME = 'options';
+
+template.innerHTML = `
+  <style>
+    :host {
+      display: inline-block;
+      font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
+      min-width: 220px;
+      --label-width: 8rem;
+      --control-font-size: 1rem;
+    }
+
+    .wrapper {
+      display: grid;
+      grid-template-columns: 1fr;
+      row-gap: 0.375rem;
+    }
+
+    .control {
+      position: relative;
+    }
+
+    .label {
+      display: block;
+      margin-bottom: 0;
+      font-size: var(--label-font-size, var(--control-font-size));
+      color: #334155;
+    }
+
+    :host([label-position="left"]) .wrapper {
+      grid-template-columns: var(--label-width) minmax(0, 1fr);
+      column-gap: 0.75rem;
+      row-gap: 0.5rem;
+      align-items: center;
+    }
+
+    :host([label-position="left"]) .label {
+      grid-column: 1;
+      grid-row: 1;
+    }
+
+    :host([label-position="left"]) .control {
+      grid-column: 2;
+      grid-row: 1;
+    }
+
+    select {
+      width: 100%;
+      padding: 0.625rem 0.75rem;
+      border: 1px solid #94a3b8;
+      border-radius: 0.5rem;
+      background: #ffffff;
+      font-family: inherit;
+      font-size: var(--control-font-size);
+      color: #0f172a;
+      outline: none;
+      transition: border-color 120ms ease, box-shadow 120ms ease;
+      appearance: none;
+    }
+
+    select:focus {
+      border-color: #0ea5e9;
+      box-shadow: 0 0 0 3px rgba(14, 165, 233, 0.2);
+    }
+
+    .editor {
+      width: 100%;
+      margin-top: 0.5rem;
+      padding: 0.625rem 0.75rem;
+      border: 1px dashed #0ea5e9;
+      border-radius: 0.5rem;
+      background: #f0f9ff;
+      font-family: inherit;
+      font-size: var(--control-font-size);
+      color: #0f172a;
+      outline: none;
+    }
+
+    :host([label-position="left"]) .editor {
+      grid-column: 2;
+      grid-row: 2;
+      margin-top: 0;
+    }
+
+    .editor:focus {
+      box-shadow: 0 0 0 3px rgba(14, 165, 233, 0.2);
+    }
+
+    .chevron {
+      position: absolute;
+      right: 0.75rem;
+      top: 50%;
+      transform: translateY(-50%);
+      pointer-events: none;
+      color: #64748b;
+      font-size: 0.75rem;
+    }
+  </style>
+
+  <div class="wrapper">
+    <label class="label" part="label"></label>
+    <div class="control">
+      <select part="select"></select>
+      <span class="chevron" aria-hidden="true">▼</span>
+    </div>
+    <input class="editor" type="text" placeholder="Type a new option and press Enter" hidden />
+  </div>
+`;
+
+export class CustomSelect extends HTMLElement {
+  static dbPromise = null;
+
+  static get observedAttributes() {
+    return ['label', 'editable'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.appendChild(template.content.cloneNode(true));
+
+    this.labelEl = this.shadowRoot.querySelector('.label');
+    this.selectEl = this.shadowRoot.querySelector('select');
+    this.editorEl = this.shadowRoot.querySelector('.editor');
+    this.editMode = false;
+    this.lastNonEditValue = '';
+    this.initialOptionsSnapshot = [];
+  }
+
+  connectedCallback() {
+    this.renderLabel();
+    this.bootstrapOptions();
+    this.captureInitialOptionsSnapshot();
+
+    this.selectEl.addEventListener('change', this.onChange);
+    this.selectEl.addEventListener('click', this.onSelectClick);
+    this.selectEl.addEventListener('keydown', this.onKeyDown);
+    this.editorEl.addEventListener('keydown', this.onEditorKeyDown);
+
+    this.restorePersistedOptions();
+  }
+
+  disconnectedCallback() {
+    this.selectEl.removeEventListener('change', this.onChange);
+    this.selectEl.removeEventListener('click', this.onSelectClick);
+    this.selectEl.removeEventListener('keydown', this.onKeyDown);
+    this.editorEl.removeEventListener('keydown', this.onEditorKeyDown);
+  }
+
+  attributeChangedCallback(name) {
+    if (name === 'label') {
+      this.renderLabel();
+    }
+
+    if (name === 'editable') {
+      this.applyEditableState();
+    }
+  }
+
+  get value() {
+    return this.selectEl.value;
+  }
+
+  set value(nextValue) {
+    this.selectEl.value = nextValue;
+  }
+
+  onChange = () => {
+    if (this.selectEl.value === EDIT_OPTION_VALUE) {
+      if (!this.isEditable()) {
+        this.selectFirstRegularOption();
+        return;
+      }
+
+      if (this.editMode) {
+        this.setEditMode(false);
+        this.closeEditor();
+        this.selectFirstRegularOption();
+
+        return;
+      }
+
+      this.setEditMode(true);
+      this.selectFirstRegularOption();
+
+      this.openEditor();
+
+      return;
+    }
+
+    this.lastNonEditValue = this.selectEl.value;
+
+    // Re-dispatch a change event from the custom element itself.
+    this.dispatchEvent(
+      new CustomEvent('change', {
+        detail: { value: this.value },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  };
+
+  onKeyDown = (event) => {
+    const isDeleteKey = event.key === 'Delete' || event.key === 'Backspace';
+
+    if (!isDeleteKey || !this.editMode || !this.isEditable()) {
+      return;
+    }
+
+    this.deleteSelectedOption();
+  };
+
+  onSelectClick = () => {
+    const onlyEditOptionLeft = this.getRegularOptions().length === 0;
+
+    if (!this.isEditable() || this.editMode || !onlyEditOptionLeft) {
+      return;
+    }
+
+    if (this.selectEl.value === EDIT_OPTION_VALUE) {
+      this.setEditMode(true);
+      this.openEditor();
+    }
+  };
+
+  onEditorKeyDown = (event) => {
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      this.addOptionFromEditor();
+      return;
+    }
+
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      this.setEditMode(false);
+      this.closeEditor();
+    }
+  };
+
+  renderLabel() {
+    const label = this.getAttribute('label') ?? '';
+    this.labelEl.textContent = label;
+    this.labelEl.hidden = label.length === 0;
+  }
+
+  bootstrapOptions() {
+    // Seed options from any light-DOM <option> children.
+    const lightDomOptions = this.getLightDomRegularOptions();
+
+    if (lightDomOptions.length === 0) {
+      this.selectEl.innerHTML = `
+        <option value="">Choose one...</option>
+        <option value="one">Option One</option>
+        <option value="two">Option Two</option>
+      `;
+    } else {
+      this.selectEl.replaceChildren(
+        ...lightDomOptions.map((option) => {
+          const clonedOption = option.cloneNode(true);
+          return clonedOption;
+        })
+      );
+    }
+
+    this.applyEditableState();
+    this.syncSelectionState();
+  }
+
+  getStorageIdentity() {
+    return this.getAttribute('storage-key') || this.id || this.getAttribute('name') || null;
+  }
+
+  getStorageKey() {
+    const identity = this.getStorageIdentity();
+    if (!identity) {
+      return null;
+    }
+
+    return `dropdown-options:${identity}`;
+  }
+
+  canPersist() {
+    return this.isEditable() && Boolean(this.getStorageKey()) && typeof indexedDB !== 'undefined';
+  }
+
+  static getDb() {
+    if (CustomSelect.dbPromise) {
+      return CustomSelect.dbPromise;
+    }
+
+    CustomSelect.dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME, { keyPath: 'key' });
+        }
+      };
+
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+
+    return CustomSelect.dbPromise;
+  }
+
+  async getPersistedRecord() {
+    if (!this.canPersist()) {
+      return null;
+    }
+
+    const storageKey = this.getStorageKey();
+    const db = await CustomSelect.getDb();
+
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(STORE_NAME, 'readonly');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.get(storageKey);
+
+      request.onsuccess = () => resolve(request.result || null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async persistCurrentOptions() {
+    if (!this.canPersist()) {
+      return;
+    }
+
+    const storageKey = this.getStorageKey();
+    const options = this.getRegularOptions().map((option) => ({
+      value: option.value,
+      text: option.textContent ?? '',
+      selected: option.selected,
+    }));
+
+    const db = await CustomSelect.getDb();
+    await new Promise((resolve, reject) => {
+      const transaction = db.transaction(STORE_NAME, 'readwrite');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.put({ key: storageKey, options });
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async clearPersistedOptions() {
+    if (!this.canPersist()) {
+      return;
+    }
+
+    const storageKey = this.getStorageKey();
+    const db = await CustomSelect.getDb();
+
+    await new Promise((resolve, reject) => {
+      const transaction = db.transaction(STORE_NAME, 'readwrite');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.delete(storageKey);
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  captureInitialOptionsSnapshot() {
+    if (this.initialOptionsSnapshot.length > 0) {
+      return;
+    }
+
+    this.initialOptionsSnapshot = this.getLightDomRegularOptions().map((option) => ({
+      value: option.value,
+      text: option.textContent ?? '',
+      selected: option.selected,
+    }));
+  }
+
+  applyOptions(options) {
+    const normalizedOptions = options.map((item) => {
+      const option = document.createElement('option');
+      option.value = item.value;
+      option.textContent = item.text;
+      option.selected = Boolean(item.selected);
+      return option;
+    });
+
+    this.selectEl.replaceChildren(...normalizedOptions);
+
+    const lightDomOptions = this.getLightDomRegularOptions();
+    lightDomOptions.forEach((option) => option.remove());
+
+    normalizedOptions.forEach((option) => {
+      const lightDomOption = option.cloneNode(true);
+      this.appendChild(lightDomOption);
+    });
+
+    this.applyEditableState();
+    this.syncSelectionState();
+  }
+
+  async resetToInitialOptions() {
+    if (this.initialOptionsSnapshot.length === 0) {
+      return;
+    }
+
+    this.applyOptions(this.initialOptionsSnapshot);
+
+    if (this.canPersist()) {
+      await this.persistCurrentOptions();
+    }
+  }
+
+  async restorePersistedOptions() {
+    if (!this.canPersist()) {
+      return;
+    }
+
+    try {
+      const record = await this.getPersistedRecord();
+      if (!record || !Array.isArray(record.options) || record.options.length === 0) {
+        return;
+      }
+
+      this.applyOptions(record.options);
+    } catch (error) {
+      // Ignore persistence failures and keep component usable.
+      console.error('Failed to restore custom-select options', error);
+    }
+  }
+
+  isEditable() {
+    return this.hasAttribute('editable');
+  }
+
+  applyEditableState() {
+    if (this.isEditable()) {
+      this.ensureEditOption();
+      return;
+    }
+
+    if (this.editMode) {
+      this.setEditMode(false);
+      this.closeEditor();
+    }
+
+    this.removeEditOption();
+
+    if (this.selectEl.value === EDIT_OPTION_VALUE) {
+      this.selectFirstRegularOption();
+    }
+  }
+
+  selectFirstRegularOption() {
+    if (
+      this.lastNonEditValue &&
+      this.getRegularOptions().some((option) => option.value === this.lastNonEditValue)
+    ) {
+      this.selectEl.value = this.lastNonEditValue;
+      return;
+    }
+
+    const firstRegularOption = this.getRegularOptions()[0];
+    if (firstRegularOption) {
+      this.selectEl.value = firstRegularOption.value;
+      this.lastNonEditValue = firstRegularOption.value;
+    }
+  }
+
+  syncSelectionState() {
+    const selectedRegularOption = this.getRegularOptions().find((option) => option.selected);
+    if (selectedRegularOption) {
+      this.selectEl.value = selectedRegularOption.value;
+      this.lastNonEditValue = selectedRegularOption.value;
+      return;
+    }
+
+    this.selectFirstRegularOption();
+  }
+
+  setEditMode(enabled) {
+    this.editMode = enabled;
+    this.toggleAttribute('edit-mode', enabled);
+
+    this.dispatchEvent(
+      new CustomEvent('editmodechange', {
+        detail: { editMode: enabled },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  openEditor() {
+    this.editorEl.hidden = false;
+    this.editorEl.value = '';
+    this.editorEl.focus();
+  }
+
+  closeEditor() {
+    this.editorEl.hidden = true;
+    this.editorEl.value = '';
+    this.selectEl.focus();
+  }
+
+  ensureEditOption() {
+    let editOption = this.selectEl.querySelector(`option[value="${EDIT_OPTION_VALUE}"]`);
+
+    if (!editOption) {
+      editOption = document.createElement('option');
+      editOption.value = EDIT_OPTION_VALUE;
+    }
+
+    editOption.textContent = EDIT_OPTION_LABEL;
+    this.selectEl.appendChild(editOption);
+  }
+
+  removeEditOption() {
+    const editOption = this.selectEl.querySelector(`option[value="${EDIT_OPTION_VALUE}"]`);
+    if (editOption) {
+      editOption.remove();
+    }
+  }
+
+  getRegularOptions() {
+    return Array.from(this.selectEl.options).filter(
+      (option) => option.value !== EDIT_OPTION_VALUE
+    );
+  }
+
+  getLightDomRegularOptions() {
+    return Array.from(this.querySelectorAll('option')).filter(
+      (option) => option.value !== EDIT_OPTION_VALUE
+    );
+  }
+
+  deleteSelectedOption() {
+    const selectedOption = this.selectEl.selectedOptions[0];
+
+    if (!selectedOption || selectedOption.value === EDIT_OPTION_VALUE) {
+      return;
+    }
+
+    const selectedValue = selectedOption.value;
+    const selectedText = selectedOption.textContent;
+
+    selectedOption.remove();
+
+    const lightDomOption = this.getLightDomRegularOptions().find(
+      (option) => option.value === selectedValue && option.textContent === selectedText
+    );
+
+    if (lightDomOption) {
+      lightDomOption.remove();
+    }
+
+    const remainingOptions = this.getRegularOptions();
+    if (remainingOptions.length > 0) {
+      this.selectEl.value = remainingOptions[0].value;
+      this.lastNonEditValue = this.selectEl.value;
+
+      this.persistCurrentOptions();
+      this.setEditMode(false);
+      this.closeEditor();
+
+      this.dispatchEvent(
+        new CustomEvent('change', {
+          detail: { value: this.value },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      return;
+    }
+
+    this.selectEl.value = EDIT_OPTION_VALUE;
+    this.lastNonEditValue = '';
+    this.persistCurrentOptions();
+    this.setEditMode(false);
+    this.closeEditor();
+  }
+
+  addOptionFromEditor() {
+    if (!this.isEditable()) {
+      return;
+    }
+
+    const typedText = this.editorEl.value.trim();
+
+    if (!typedText) {
+      return;
+    }
+
+    const nextValue = this.createUniqueValueFromText(typedText);
+
+    const shadowOption = document.createElement('option');
+    shadowOption.value = nextValue;
+    shadowOption.textContent = typedText;
+
+    const editOption = this.selectEl.querySelector(`option[value="${EDIT_OPTION_VALUE}"]`);
+    if (editOption) {
+      this.selectEl.insertBefore(shadowOption, editOption);
+    } else {
+      this.selectEl.appendChild(shadowOption);
+      this.ensureEditOption();
+    }
+
+    const lightDomOption = document.createElement('option');
+    lightDomOption.value = nextValue;
+    lightDomOption.textContent = typedText;
+    this.appendChild(lightDomOption);
+
+    this.selectEl.value = nextValue;
+    this.lastNonEditValue = nextValue;
+    this.editorEl.value = '';
+
+    this.persistCurrentOptions();
+
+    this.dispatchEvent(
+      new CustomEvent('change', {
+        detail: { value: this.value },
+        bubbles: true,
+        composed: true,
+      })
+    );
+
+    this.dispatchEvent(
+      new CustomEvent('optionadded', {
+        detail: { value: nextValue, text: typedText },
+        bubbles: true,
+        composed: true,
+      })
+    );
+
+    this.setEditMode(false);
+    this.closeEditor();
+  }
+
+  createUniqueValueFromText(text) {
+    const baseValue =
+      text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '') || 'option';
+
+    const existingValues = new Set(
+      this.getRegularOptions().map((option) => option.value.toLowerCase())
+    );
+
+    if (!existingValues.has(baseValue)) {
+      return baseValue;
+    }
+
+    let counter = 2;
+    let candidate = `${baseValue}-${counter}`;
+    while (existingValues.has(candidate)) {
+      counter += 1;
+      candidate = `${baseValue}-${counter}`;
+    }
+
+    return candidate;
+  }
+}
+
+if (!customElements.get('custom-select')) {
+  customElements.define('custom-select', CustomSelect);
+}