@lekoala/combobox 0.1.0

package/custom-elements.json

@@ -0,0 +1,247 @@
+{
+  "schemaVersion": "2.1.0",
+  "readme": "README.md",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/combo-box.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ComboBoxElement",
+          "description": "Autonomous custom element (no Shadow DOM) wrapping the Combobox enhancement engine for a child <select> or <input list>.",
+          "tagName": "combo-box",
+          "attributes": [
+            {
+              "name": "create"
+            },
+            {
+              "name": "placeholder"
+            },
+            {
+              "name": "search"
+            },
+            {
+              "name": "min-chars"
+            },
+            {
+              "name": "max-items"
+            },
+            {
+              "name": "max-options"
+            },
+            {
+              "name": "selection-order"
+            },
+            {
+              "name": "separators"
+            },
+            {
+              "name": "create-on-blur"
+            },
+            {
+              "name": "close-on-select"
+            },
+            {
+              "name": "autoselect-first"
+            },
+            {
+              "name": "tab-select"
+            },
+            {
+              "name": "search-fields"
+            },
+            {
+              "name": "label-field"
+            },
+            {
+              "name": "value-field"
+            },
+            {
+              "name": "load-on-empty"
+            },
+            {
+              "name": "allow-empty-option"
+            },
+            {
+              "name": "debounce"
+            }
+          ],
+          "members": [
+            {
+              "kind": "getter",
+              "name": "source",
+              "description": "The enhanced source element, discovering it lazily when needed."
+            },
+            {
+              "kind": "getter",
+              "name": "combobox",
+              "description": "The underlying Combobox engine instance, or null before upgrade."
+            },
+            {
+              "kind": "getter",
+              "name": "options",
+              "description": "The merged JavaScript options currently applied to the element."
+            },
+            {
+              "kind": "method",
+              "name": "configure",
+              "description": "Merge JavaScript-only behavior such as load/create/render callbacks."
+            },
+            {
+              "kind": "method",
+              "name": "upgrade",
+              "description": "Enhance the native child source. Safe to call repeatedly. child exists."
+            },
+            {
+              "kind": "method",
+              "name": "whenReady",
+              "description": "Resolves once the engine has upgraded the source child."
+            },
+            {
+              "kind": "method",
+              "name": "dispose",
+              "description": "Tear the engine down and restore the native source."
+            }
+          ],
+          "events": [
+            {
+              "name": "beforefilter"
+            },
+            {
+              "name": "combobox:beforeclear"
+            },
+            {
+              "name": "combobox:beforeclose"
+            },
+            {
+              "name": "combobox:beforecreate"
+            },
+            {
+              "name": "combobox:beforeload"
+            },
+            {
+              "name": "combobox:beforeopen"
+            },
+            {
+              "name": "combobox:beforeremove"
+            },
+            {
+              "name": "combobox:beforereorder"
+            },
+            {
+              "name": "combobox:beforeselect"
+            },
+            {
+              "name": "combobox:clear"
+            },
+            {
+              "name": "combobox:create"
+            },
+            {
+              "name": "combobox:createerror"
+            },
+            {
+              "name": "combobox:guarderror"
+            },
+            {
+              "name": "combobox:load"
+            },
+            {
+              "name": "combobox:loaderror"
+            },
+            {
+              "name": "combobox:remove"
+            },
+            {
+              "name": "combobox:reorder"
+            },
+            {
+              "name": "combobox:select"
+            },
+            {
+              "name": "filter"
+            }
+          ],
+          "cssProperties": [
+            {
+              "name": "--cb-bg"
+            },
+            {
+              "name": "--cb-color"
+            },
+            {
+              "name": "--cb-border-color"
+            },
+            {
+              "name": "--cb-border-radius"
+            },
+            {
+              "name": "--cb-focus-color"
+            },
+            {
+              "name": "--cb-chip-bg"
+            },
+            {
+              "name": "--cb-chip-color"
+            },
+            {
+              "name": "--cb-chip-border-color"
+            },
+            {
+              "name": "--cb-chip-border-width"
+            },
+            {
+              "name": "--cb-chip-font-size"
+            },
+            {
+              "name": "--cb-chip-border-radius"
+            },
+            {
+              "name": "--cb-picker-bg"
+            },
+            {
+              "name": "--cb-option-active-bg"
+            },
+            {
+              "name": "--cb-option-selected-bg"
+            },
+            {
+              "name": "--cb-muted-color"
+            },
+            {
+              "name": "--cb-error-color"
+            },
+            {
+              "name": "--cb-control-height"
+            },
+            {
+              "name": "--cb-option-min-height"
+            },
+            {
+              "name": "--cb-check-size"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ComboBoxElement",
+          "declaration": {
+            "name": "ComboBoxElement",
+            "module": "src/combo-box.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineCombobox",
+          "declaration": {
+            "name": "defineCombobox",
+            "module": "src/combo-box.js"
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/combobox.css

@@ -0,0 +1,447 @@
+/* Structural CSS for the combobox enhancement. No Bootstrap JS dependency.
+   Tune appearance through the --cb-* variables below; defaults are neutral and
+   Bootstrap-compatible. Markup stays framework-agnostic. */
+
+:root {
+  --cb-bg: #fff;
+  --cb-color: #212529;
+  --cb-border-color: #adb5bd;
+  --cb-border-radius: 0.375rem;
+  --cb-focus-color: #0d6efd;
+  --cb-chip-bg: #e9ecef;
+  --cb-chip-color: inherit;
+  --cb-chip-border-color: transparent;
+  --cb-chip-border-width: 0px;
+  --cb-chip-font-size: 0.875em;
+  --cb-chip-border-radius: 0.4286em;
+  --cb-picker-bg: Canvas;
+  --cb-option-active-bg: #0d6efd;
+  --cb-option-selected-bg: #e9ecef;
+  --cb-muted-color: #6c757d;
+  --cb-error-color: #dc3545;
+  --cb-control-height: 2.75rem;
+  --cb-option-min-height: 2.5rem;
+  --cb-check-size: 1em;
+}
+
+.cb-source-hidden {
+  position: absolute !important;
+  inline-size: 1px !important;
+  block-size: 1px !important;
+  margin: -1px !important;
+  padding: 0 !important;
+  overflow: hidden !important;
+  clip: rect(0 0 0 0) !important;
+  clip-path: inset(50%) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Control geometry — single, multiple and input comboboxes share one system */
+/* ------------------------------------------------------------------------- */
+
+.cb-control,
+.cb-text-control,
+.cb-fallback-input,
+.cb-fallback-add {
+  box-sizing: border-box;
+  min-block-size: var(--cb-control-height);
+  border: 1px solid var(--cb-border-color);
+  border-radius: var(--cb-border-radius);
+  background: var(--cb-bg);
+  color: var(--cb-color);
+  font: inherit;
+}
+
+.cb-text-control,
+.cb-fallback-input {
+  display: block;
+  inline-size: 100%;
+  max-inline-size: 100%;
+  padding-block: calc((var(--cb-control-height) - 1.625rem) / 2);
+  padding-inline: 0.75rem;
+}
+
+.cb-text-control:disabled {
+  cursor: not-allowed;
+}
+
+.cb-control {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  min-inline-size: 0;
+  max-inline-size: 100%;
+  padding-block: 0.375rem;
+  padding-inline: 0.5rem;
+  cursor: text;
+}
+
+.cb-control-single {
+  flex-wrap: nowrap;
+  padding-block: 0;
+  padding-inline: 0.75rem;
+}
+
+.cb-control:hover,
+.cb-text-control:hover {
+  border-color: #9aa3ad;
+}
+
+/* Chips participate directly in the control flex layout so the inter-item gap
+   is identical everywhere (including before the search field). */
+.cb-chips {
+  display: contents;
+}
+
+.cb-chips:empty {
+  display: none;
+}
+
+/* The search input disappears into the control */
+.cb-input {
+  flex: 1 1 4ch;
+  min-inline-size: 4ch;
+  max-inline-size: 100%;
+  inline-size: auto;
+  border: 0;
+  outline: 0;
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-overflow: ellipsis;
+}
+
+.cb-control-single .cb-input {
+  flex-basis: 100%;
+  min-inline-size: 0;
+}
+
+.cb-input::placeholder,
+.cb-text-control::placeholder,
+.cb-fallback-input::placeholder {
+  color: var(--cb-muted-color);
+  opacity: 1;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Chips                                                                    */
+/* ------------------------------------------------------------------------- */
+
+.cb-chip {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2857em;
+  flex: 0 1 auto;
+  min-inline-size: 0;
+  min-block-size: 1.7143em;
+  max-inline-size: 100%;
+  padding-block: 0;
+  padding-inline-start: 0.5714em;
+  padding-inline-end: 0.1429em;
+  border: var(--cb-chip-border-width) solid var(--cb-chip-border-color);
+  border-radius: var(--cb-chip-border-radius);
+  background: var(--cb-chip-bg);
+  color: var(--cb-chip-color);
+  font-size: var(--cb-chip-font-size);
+  line-height: 1.4;
+}
+
+.cb-chip-label {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cb-chip .cb-chip-remove {
+  appearance: none;
+  display: inline-grid;
+  place-items: center;
+  flex: 0 0 auto;
+  inline-size: 1.4286em;
+  block-size: 1.4286em;
+  margin-inline-start: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.cb-chip .cb-chip-remove > svg {
+  inline-size: 1em;
+  block-size: 1em;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+}
+
+@supports (color: color-mix(in srgb, red 50%, blue)) {
+  .cb-chip .cb-chip-remove:hover,
+  .cb-chip .cb-chip-remove:focus-visible {
+    background: color-mix(in srgb, currentColor 12%, transparent);
+  }
+}
+
+@supports not (color: color-mix(in srgb, red 50%, blue)) {
+  .cb-chip .cb-chip-remove:hover,
+  .cb-chip .cb-chip-remove:focus-visible {
+    background: rgb(0 0 0 / 0.08);
+  }
+}
+
+.cb-chip:focus-visible {
+  outline: 2px solid var(--cb-focus-color);
+  outline-offset: 1px;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Focus — whole control, no ring around the internal input                 */
+/* ------------------------------------------------------------------------- */
+
+.cb-text-control:focus,
+.cb-control:focus-within {
+  border-color: var(--cb-focus-color);
+  outline: 2px solid rgb(13 110 253 / 0.35);
+  outline-offset: 2px;
+}
+
+@supports (color: color-mix(in srgb, red 50%, blue)) {
+  .cb-text-control:focus,
+  .cb-control:focus-within {
+    outline-color: color-mix(in srgb, var(--cb-focus-color) 40%, transparent);
+  }
+}
+
+@supports not (color: color-mix(in srgb, red 50%, blue)) {
+  .cb-text-control:focus,
+  .cb-control:focus-within {
+    outline-color: var(--cb-focus-color);
+  }
+}
+
+.cb-fallback-input:focus {
+  border-color: var(--cb-focus-color);
+}
+
+/* Open state reflection without a parallel JS state model */
+.cb-control:has([aria-expanded="true"]) {
+  border-color: var(--cb-focus-color);
+}
+
+/* ------------------------------------------------------------------------- */
+/* Picker / popover — natural continuation of the control                   */
+/* ------------------------------------------------------------------------- */
+
+.cb-popover {
+  box-sizing: border-box;
+  inset: auto;
+  margin: 0.25rem 0;
+  position: fixed;
+  position-area: bottom;
+  position-try: flip-block;
+  position-try-fallbacks: flip-block;
+  inline-size: anchor-size(width);
+  max-block-size: min(20rem, 50vh);
+  padding: 0.25rem;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  border: 1px solid var(--cb-border-color);
+  border-radius: var(--cb-border-radius);
+  background: var(--cb-picker-bg);
+  color: var(--cb-color);
+  box-shadow: 0 0.5rem 1rem rgb(0 0 0 / 15%);
+}
+
+.cb-popover::backdrop {
+  background: transparent;
+}
+
+.cb-listbox {
+  display: grid;
+  min-inline-size: 0;
+  gap: 0.125rem;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Options — stable geometry, active vs selected distinctly                  */
+/* ------------------------------------------------------------------------- */
+
+.cb-option,
+.cb-empty,
+.cb-group {
+  box-sizing: border-box;
+  inline-size: 100%;
+  min-inline-size: 0;
+  padding-block: 0.5rem;
+  padding-inline: 0.6rem;
+}
+
+.cb-option,
+.cb-empty {
+  min-block-size: var(--cb-option-min-height);
+  border-radius: 0.25rem;
+}
+
+.cb-option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75em;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+  user-select: none;
+}
+
+.cb-option-label {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cb-option:is(:hover, [data-active]) {
+  background: var(--cb-option-active-bg);
+  color: #fff;
+}
+
+.cb-option[aria-selected="true"] {
+  background: var(--cb-option-selected-bg);
+}
+
+.cb-option[aria-selected="true"]::after {
+  content: "";
+  flex: 0 0 auto;
+  inline-size: var(--cb-check-size);
+  block-size: var(--cb-check-size);
+  margin-inline-start: auto;
+  background: currentColor;
+  -webkit-mask:
+    url("data:image/svg+xml,%3Csvg%20viewBox='0%200%2024%2024'%20xmlns='http://www.w3.org/2000/svg'%3E%3Cpath%20d='M5%2012l4%204L19%206'%20fill='none'%20stroke='%23000'%20stroke-width='2.25'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3C/svg%3E")
+    center / contain no-repeat;
+  mask:
+    url("data:image/svg+xml,%3Csvg%20viewBox='0%200%2024%2024'%20xmlns='http://www.w3.org/2000/svg'%3E%3Cpath%20d='M5%2012l4%204L19%206'%20fill='none'%20stroke='%23000'%20stroke-width='2.25'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3C/svg%3E")
+    center / contain no-repeat;
+}
+
+.cb-option[aria-selected="true"]:is(:hover, [data-active]) {
+  background: var(--cb-option-active-bg);
+  color: #fff;
+}
+
+.cb-option[aria-disabled="true"],
+.cb-option[disabled] {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Empty / loading / error / create states — treated as real picker rows     */
+/* ------------------------------------------------------------------------- */
+
+.cb-empty {
+  display: flex;
+  align-items: center;
+  color: var(--cb-muted-color);
+  overflow-wrap: anywhere;
+}
+
+.cb-empty.cb-error {
+  color: var(--cb-error-color);
+}
+
+.cb-group {
+  color: var(--cb-muted-color);
+  font-size: 0.875em;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cb-create {
+  font-style: italic;
+}
+
+.cb-create .cb-option-label {
+  color: var(--cb-focus-color);
+}
+
+.cb-status {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* ------------------------------------------------------------------------- */
+/* States reflected from the native source                                  */
+/* ------------------------------------------------------------------------- */
+
+.cb-text-control[aria-invalid="true"],
+.cb-control:has([aria-invalid="true"]) {
+  border-color: var(--cb-error-color);
+}
+
+.cb-text-control[aria-invalid="true"]:focus,
+.cb-control:has([aria-invalid="true"]):focus-within {
+  outline-color: var(--cb-error-color);
+}
+
+.cb-control:has(.cb-input:disabled) {
+  opacity: 0.65;
+  cursor: not-allowed;
+}
+
+.cb-input:read-only,
+.cb-input:disabled {
+  cursor: default;
+}
+
+/* ------------------------------------------------------------------------- */
+/* Fallback creation control — same system, no second engine                 */
+/* ------------------------------------------------------------------------- */
+
+.cb-fallback-create {
+  display: flex;
+  gap: 0.5rem;
+  margin-block-start: 0.5rem;
+}
+
+.cb-fallback-input {
+  flex: 1 1 auto;
+}
+
+.cb-fallback-add {
+  flex: 0 0 auto;
+  padding-inline: 0.875rem;
+  cursor: pointer;
+}
+
+.cb-fallback-add:hover {
+  border-color: var(--cb-focus-color);
+}
+
+/* The custom element is an enhancement/lifecycle boundary, not a shadow tree. */
+combo-box {
+  display: block;
+  min-inline-size: 0;
+}