@adia-ai/web-components 0.6.33 → 0.6.34

package/components/combobox/combobox.a2ui.json

@@ -0,0 +1,363 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Combobox.json",
+  "title": "Combobox",
+  "description": "Typeahead-filterable single-select primitive — the constrained-choice\ncombobox per WAI-APG \"Combobox With List Autocomplete (manual\nselection)\". The committed value MUST come from the options list\nunless `[free-text]` is set. Distinct from `<select-ui searchable>`\n(button-first dropdown) and `<autocomplete-input-ui>` (free-form).\nForm-bearing via UIFormElement: `[name]`, `[value]`, `[required]`,\n`[disabled]`, fires `change`. Options via native `<option>` /\n`<optgroup>` children OR programmatic `.options` array.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "required": {
+      "description": "Marks the field as required for form validation",
+      "type": "boolean",
+      "default": false
+    },
+    "clearable": {
+      "description": "Renders an `x` clear button when value is set",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Combobox"
+    },
+    "creatable": {
+      "description": "Implies `[free-text]`; on Enter with unmatched typed text fires a\n`create` event with detail.value so the consumer can run a\nbackend create-then-refresh-options flow.",
+      "type": "boolean",
+      "default": false
+    },
+    "disabled": {
+      "description": "Disables interaction and dims the control",
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "description": "Validation error message",
+      "type": "string",
+      "default": ""
+    },
+    "filter-mode": {
+      "description": "Client-side filter algorithm.",
+      "type": "string",
+      "enum": [
+        "substring",
+        "prefix",
+        "fuzzy"
+      ],
+      "default": "substring"
+    },
+    "free-text": {
+      "description": "Allow typed text not in the options list. Blurs the distinction\nwith <autocomplete-input-ui>; prefer the dedicated primitive\nunless the value model truly needs both modes (tag-with-suggestions,\nemail-with-recent-recipients).",
+      "type": "boolean",
+      "default": false
+    },
+    "highlight-match": {
+      "description": "Wraps the matched substring in `<mark>` inside option labels",
+      "type": "boolean",
+      "default": true
+    },
+    "hint": {
+      "description": "Caption text below the field; wires `aria-describedby` on the host\nso screen readers announce it as a description.",
+      "type": "string",
+      "default": ""
+    },
+    "label": {
+      "description": "Inline label rendered above the field. Wrap with <field-ui> for\nproper `<label for>` association in form-row compositions.",
+      "type": "string",
+      "default": ""
+    },
+    "loading": {
+      "description": "Shows a loading spinner inside the popover; consumer drives async fetch",
+      "type": "boolean",
+      "default": false
+    },
+    "max-options": {
+      "description": "Cap on rendered options. Overflow shows a \"scroll for more\" hint",
+      "type": "number",
+      "default": 100
+    },
+    "name": {
+      "description": "Form control name for form data submission",
+      "type": "string",
+      "default": ""
+    },
+    "open": {
+      "description": "Reflects popover open / closed state",
+      "type": "boolean",
+      "default": false
+    },
+    "options": {
+      "description": "Programmatic option list. Array of {value, label, disabled?, group?} or grouped {label, options:[…]}. Alternative to declarative <option> / <optgroup> children.",
+      "type": "array",
+      "default": []
+    },
+    "placeholder": {
+      "description": "Placeholder text in the input when value is empty",
+      "type": "string",
+      "default": "Select..."
+    },
+    "readonly": {
+      "description": "Prevents selection changes while keeping the field focusable + popover-open allowed",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Sizing scale via universal `[size]` attribute system. Matches Input + Select sizing tokens so a Combobox rendered alongside either feels coherent in a form row.",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "value": {
+      "description": "Currently selected option value. Must be a member of `options[].value` unless `[free-text]` is set. With declarative <option> children, a child carrying the native `selected` attribute sets the initial value when this attribute is absent.",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Combobox\", \"value\": \"us\", \"options\": [{\"value\": \"us\", \"label\": \"United States\"}]}\n",
+        "why": "`value` is \"xx\" but only \"us\" is in options. With free-text:false (default), this is an invalid\nmid-state — set value: \"us\" or add an option with value: \"xx\".\n",
+        "wrong": "{\"component\": \"Combobox\", \"value\": \"xx\", \"options\": [{\"value\": \"us\", \"label\": \"United States\"}]}\n"
+      },
+      {
+        "fix": "{\"component\": \"SegmentedControl\", \"options\": [{\"value\": \"a\", \"label\": \"A\"}, {\"value\": \"b\", \"label\": \"B\"}]}\n",
+        "why": "Only 2 options. Combobox is overkill — use SegmentedControl or Radio.\n",
+        "wrong": "{\"component\": \"Combobox\", \"options\": [{\"value\": \"a\", \"label\": \"A\"}, {\"value\": \"b\", \"label\": \"B\"}]}\n"
+      },
+      {
+        "fix": "{\"component\": \"MultiSelect\", \"options\": [...]}\n",
+        "why": "Combobox is single-select. Multi-select goes through MultiSelect.\n",
+        "wrong": "{\"component\": \"Combobox\", \"multiple\": true, \"options\": [...]}\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "icon-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired when value is committed — option clicked, Enter on active\noption, or programmatic `.value =`. Detail.option resolves to the\nmatching `{label,value,...}` or null in free-text/cleared paths.",
+        "detail": {
+          "option": {
+            "description": "Resolved option object or null when free-text / cleared.",
+            "type": "object"
+          },
+          "source": {
+            "description": "One of `click` / `keyboard` / `programmatic`.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Committed value.",
+            "type": "string"
+          }
+        }
+      },
+      "close": {
+        "description": "Popover closed.",
+        "detail": {
+          "reason": {
+            "description": "One of `escape` / `outside` / `select` / `blur`.",
+            "type": "string"
+          }
+        }
+      },
+      "create": {
+        "description": "Fired when `[creatable]` is set and the user presses Enter on\ntyped text that doesn't match any option. Consumer wires this to\na backend create flow and then refreshes `.options`.",
+        "detail": {
+          "value": {
+            "description": "The typed text the user is trying to create.",
+            "type": "string"
+          }
+        }
+      },
+      "input": {
+        "description": "Fired on each keystroke (filter typing); not a commit. Detail carries the typed query.",
+        "detail": {
+          "query": {
+            "description": "Lowercased filter query.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Current input text (the user's typed query).",
+            "type": "string"
+          }
+        }
+      },
+      "invalid": {
+        "description": "Fired when `[free-text]` is false and the user presses Enter on\ntyped text that doesn't match any option. The value is NOT\ncommitted; the input is restored to the last committed value.",
+        "detail": {
+          "query": {
+            "description": "The unmatched typed text.",
+            "type": "string"
+          }
+        }
+      },
+      "open": {
+        "description": "Popover opened.",
+        "detail": {
+          "trigger": {
+            "description": "One of `click` / `keyboard` / `typing`.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Country picker — canonical declarative <option> children inside a <field-ui>.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"children\": [\"country\"]},\n  {\n    \"id\": \"country\",\n    \"component\": \"Combobox\",\n    \"name\": \"country\",\n    \"label\": \"Country\",\n    \"placeholder\": \"Select country…\",\n    \"options\": [\n      {\"value\": \"us\", \"label\": \"United States\"},\n      {\"value\": \"gb\", \"label\": \"United Kingdom\"},\n      {\"value\": \"de\", \"label\": \"Germany\"},\n      {\"value\": \"fr\", \"label\": \"France\"},\n      {\"value\": \"es\", \"label\": \"Spain\"}\n    ],\n    \"value\": \"us\"\n  }\n]",
+        "name": "country-picker"
+      },
+      {
+        "description": "Tag picker with create-new affordance — fires `create` event on unmatched Enter.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"children\": [\"tag\"]},\n  {\n    \"id\": \"tag\",\n    \"component\": \"Combobox\",\n    \"name\": \"tag\",\n    \"label\": \"Tag\",\n    \"creatable\": true,\n    \"placeholder\": \"Pick or create a tag…\",\n    \"options\": [\n      {\"value\": \"bug\", \"label\": \"bug\"},\n      {\"value\": \"feature\", \"label\": \"feature\"},\n      {\"value\": \"chore\", \"label\": \"chore\"}\n    ]\n  }\n]",
+        "name": "creatable-tag-picker"
+      }
+    ],
+    "keywords": [
+      "combobox",
+      "autocomplete",
+      "typeahead",
+      "select",
+      "filter",
+      "picker",
+      "country-picker",
+      "timezone-picker",
+      "member-picker"
+    ],
+    "name": "UICombobox",
+    "related": [
+      "select",
+      "search",
+      "input",
+      "field"
+    ],
+    "slots": {
+      "default": {
+        "description": "Native <option> / <optgroup> children for declarative authoring"
+      },
+      "empty": {
+        "description": "Custom no-matches content (defaults to \"No matches\")"
+      },
+      "footer": {
+        "description": "Footer area inside the popover (e.g. \"Press Enter to create…\" affordance)"
+      },
+      "loading": {
+        "description": "Custom loading content (defaults to a spinner)"
+      },
+      "prefix": {
+        "description": "Leading icon / element inside the input chrome"
+      },
+      "suffix": {
+        "description": "Trailing icon / element (defaults to `caret-down`)"
+      }
+    },
+    "states": [
+      {
+        "description": "Closed; not focused.",
+        "name": "idle"
+      },
+      {
+        "description": "Input focused; popover closed.",
+        "attribute": ":focus-within",
+        "name": "focused"
+      },
+      {
+        "description": "Popover visible; filtered options listed.",
+        "attribute": "open",
+        "name": "open"
+      },
+      {
+        "description": "Spinner shown; options stale (consumer-driven async fetch).",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "Focusable + popover-open allowed; commits blocked.",
+        "attribute": "readonly",
+        "name": "readonly"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "autocomplete": [
+        "combobox",
+        "typeahead",
+        "suggest"
+      ],
+      "combobox": [
+        "autocomplete",
+        "typeahead",
+        "filter",
+        "picker"
+      ],
+      "picker": [
+        "combobox",
+        "select",
+        "dropdown"
+      ],
+      "typeahead": [
+        "combobox",
+        "autocomplete",
+        "search"
+      ]
+    },
+    "tag": "combobox-ui",
+    "tokens": {
+      "--combobox-bg": {
+        "description": "Input background color"
+      },
+      "--combobox-fg": {
+        "description": "Input text color"
+      },
+      "--combobox-match-bg": {
+        "description": "Background for `<mark>` spans that highlight matched substrings"
+      },
+      "--combobox-option-bg-active": {
+        "description": "Background for the currently active (arrow-navigated) option"
+      },
+      "--combobox-option-bg-selected": {
+        "description": "Background for the currently committed option"
+      },
+      "--combobox-option-fg-active": {
+        "description": "Foreground for the currently active option"
+      },
+      "--combobox-popover-bg": {
+        "description": "Popover background color"
+      },
+      "--combobox-popover-border": {
+        "description": "Popover border color"
+      },
+      "--combobox-popover-radius": {
+        "description": "Popover border radius"
+      },
+      "--combobox-popover-shadow": {
+        "description": "Popover elevation shadow"
+      },
+      "--combobox-radius": {
+        "description": "Input border radius"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/combobox/combobox.css

@@ -0,0 +1,244 @@
+@scope (combobox-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --combobox-gap-default:                 var(--a-space-2);
+    --combobox-field-gap-default:           var(--a-space-1);
+    --combobox-height-default:              var(--a-size);
+    --combobox-px-default:                  var(--a-ui-px);
+    --combobox-radius-default:              var(--a-radius);
+
+    /* ── Typography ── */
+    --combobox-font-size-default:           var(--a-ui-size);
+    --combobox-label-size-default:          var(--a-label-size);
+
+    /* ── Colors — field ── */
+    --combobox-bg-default:                  var(--a-ui-bg);
+    --combobox-bg-hover-default:            var(--a-ui-bg-hover);
+    --combobox-border-default:              var(--a-ui-border);
+    --combobox-border-hover-default:        var(--a-ui-border-hover);
+    --combobox-focus-ring-default:          var(--a-focus-ring);
+    --combobox-focus-ring-invalid-default:  var(--a-focus-ring-invalid);
+    --combobox-fg-default:                  var(--a-ui-text);
+    --combobox-fg-muted-default:            var(--a-ui-text-muted);
+    --combobox-fg-subtle-default:           var(--a-ui-text-subtle);
+    --combobox-fg-disabled-default:         var(--a-ui-text-disabled);
+    --combobox-label-fg-default:            var(--a-ui-text-muted);
+    --combobox-placeholder-fg-default:      var(--a-ui-text-placeholder);
+    --combobox-caret-fg-default:            var(--a-ui-text-muted);
+
+    /* ── Transition ── */
+    --combobox-duration-default:            var(--a-duration-fast);
+    --combobox-easing-default:              var(--a-easing);
+
+    /* ── Popover ── */
+    --combobox-popover-bg-default:          var(--a-canvas-bright);
+    --combobox-popover-border-default:      var(--a-ui-border);
+    --combobox-popover-radius-default:      var(--a-radius);
+    --combobox-popover-shadow-default:      var(--a-shadow-lg);
+
+    /* ── Options ── */
+    --combobox-option-px-default:           var(--a-ui-px);
+    --combobox-option-py-default:           var(--a-space-1);
+    --combobox-option-bg-active-default:    var(--a-ui-bg-hover);
+    --combobox-option-fg-active-default:    var(--a-ui-text-hover);
+    --combobox-option-bg-selected-default:  var(--a-ui-bg-selected);
+    --combobox-option-fg-selected-default:  var(--a-ui-text-selected);
+
+    /* ── Match highlight ── */
+    --combobox-match-bg-default:            var(--a-accent-muted);
+    --combobox-match-fg-default:            var(--a-accent-strong);
+
+    text-align: start;  /* §text-align-reset — block ancestor centering */
+  }
+
+  :scope {
+    /* ── Base ── */
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--combobox-gap, var(--combobox-gap-default));
+    position: relative;
+    min-width: 0;
+    font-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+
+  :scope[disabled] {
+    pointer-events: none;
+    color: var(--combobox-fg-disabled, var(--combobox-fg-disabled-default));
+    opacity: 0.6;
+  }
+
+  /* ── Label ── */
+  [data-label] {
+    display: block;
+    font-size: var(--combobox-label-size, var(--combobox-label-size-default));
+    color: var(--combobox-label-fg, var(--combobox-label-fg-default));
+  }
+
+  /* ── Field ── */
+  [data-field] {
+    display: flex;
+    align-items: center;
+    gap: var(--combobox-field-gap, var(--combobox-field-gap-default));
+    min-height: var(--combobox-height, var(--combobox-height-default));
+    padding: 0 var(--combobox-px, var(--combobox-px-default));
+    border: 1px solid var(--combobox-border, var(--combobox-border-default));
+    border-radius: var(--combobox-radius, var(--combobox-radius-default));
+    background: var(--combobox-bg, var(--combobox-bg-default));
+    color: var(--combobox-fg, var(--combobox-fg-default));
+    transition:
+      background  var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      border-color var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      color       var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      box-shadow  var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default));
+  }
+
+  :scope:not([disabled]) [data-field]:hover {
+    background: var(--combobox-bg-hover, var(--combobox-bg-hover-default));
+    border-color: var(--combobox-border-hover, var(--combobox-border-hover-default));
+  }
+
+  :scope:focus-within [data-field] {
+    box-shadow: var(--combobox-focus-ring, var(--combobox-focus-ring-default));
+  }
+  :scope[aria-invalid="true"]:focus-within [data-field],
+  :scope[error]:focus-within [data-field] {
+    box-shadow: var(--combobox-focus-ring-invalid, var(--combobox-focus-ring-invalid-default));
+  }
+
+  [data-prefix],
+  [data-suffix] {
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+    color: var(--combobox-caret-fg, var(--combobox-caret-fg-default));
+    --a-icon-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+  [data-prefix]:empty { display: none; }
+  [data-suffix] {
+    cursor: pointer;
+  }
+
+  [data-input] {
+    flex: 1;
+    min-width: 0;
+    outline: none;
+    background: transparent;
+    color: var(--combobox-fg, var(--combobox-fg-default));
+    font: inherit;
+    font-size: var(--combobox-font-size, var(--combobox-font-size-default));
+    line-height: 1.4;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  [data-input][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--combobox-placeholder-fg, var(--combobox-placeholder-fg-default));
+    pointer-events: none;
+  }
+
+  [data-clear] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    margin: 0;
+    border: 0;
+    background: transparent;
+    color: var(--combobox-fg-muted, var(--combobox-fg-muted-default));
+    cursor: pointer;
+    --a-icon-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+  [data-clear]:hover {
+    color: var(--combobox-fg, var(--combobox-fg-default));
+  }
+}
+
+/* ── Top-layer popover: cannot inherit @scope component tokens ── */
+
+combobox-ui [data-listbox] {
+  margin: 0;
+  padding: var(--a-space-1);
+  border: 1px solid var(--a-ui-border);
+  border-radius: var(--a-radius);
+  background: var(--a-canvas-bright);
+  box-shadow: var(--a-shadow-lg);
+  max-height: 18rem;
+  overflow-y: auto;
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-ui-text);
+  width: max-content;
+
+  opacity: 1;
+  translate: 0 0;
+  transition: opacity var(--a-duration-fast) var(--a-easing-out),
+              translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+combobox-ui [data-listbox]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  combobox-ui [data-listbox] { transition: none; }
+}
+
+combobox-ui [data-listbox] [role="option"] {
+  display: flex;
+  align-items: center;
+  padding: var(--a-space-1) var(--a-ui-px);
+  border-radius: var(--a-radius-sm);
+  white-space: nowrap;
+  color: var(--a-ui-text-subtle);
+  cursor: pointer;
+  transition:
+    background var(--a-duration-fast) var(--a-easing),
+    color      var(--a-duration-fast) var(--a-easing);
+}
+
+combobox-ui [data-listbox] [role="option"][data-active] {
+  background: var(--a-ui-bg-hover);
+  color: var(--a-ui-text-hover);
+}
+
+combobox-ui [data-listbox] [role="option"][aria-selected="true"] {
+  background: var(--a-ui-bg-selected);
+  color: var(--a-ui-text-selected);
+  font-weight: var(--a-ui-weight);
+}
+
+combobox-ui [data-listbox] [role="option"][aria-disabled="true"] {
+  color: var(--a-ui-text-disabled);
+  cursor: not-allowed;
+}
+
+combobox-ui [data-listbox] [role="option"] mark {
+  background: var(--a-accent-muted);
+  color: var(--a-accent-strong);
+  padding: 0 0.1em;
+  border-radius: var(--a-radius-sm);
+}
+
+combobox-ui [data-listbox] [role="group"] [data-group-label] {
+  padding: var(--a-space-1) var(--a-ui-px);
+  font-size: var(--a-ui-tiny);
+  font-weight: var(--a-ui-weight);
+  color: var(--a-ui-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+}
+
+combobox-ui [data-empty],
+combobox-ui [data-loading],
+combobox-ui [data-footer] {
+  padding: var(--a-space-2) var(--a-ui-px);
+  color: var(--a-ui-text-muted);
+  font-size: var(--a-ui-size);
+}
+
+combobox-ui [data-footer]:empty { display: none; }