@rcarls/rc-select 0.2.0 → 0.3.1

package/dist/custom-elements.json

@@ -46,7 +46,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A fully-accessible, form-associated select/combobox component.\n\nWraps a native `<select slot=\"select\">` as the form value reflector while\nrendering a custom trigger and popup listbox. Follows the WAI-ARIA APG\nCombobox pattern (select-only variant) with JS-computed popup placement\nand `aria-activedescendant` for virtual keyboard navigation.",
+          "description": "Select-only combobox backed by a native <select>, following the WAI-ARIA Combobox\npattern.\n\nWraps a native `<select>` (default slot) as the form value reflector while\nrendering a custom button trigger and popup listbox. Popup placement\nand `aria-activedescendant` virtual keyboard navigation are supported.",
           "name": "RCSelect",
           "cssProperties": [
             {
@@ -108,6 +108,11 @@
               "description": "Multi-select chip inline-axis padding.",
               "name": "--rc-select-chip-padding-inline",
               "default": "0.3em"
+            },
+            {
+              "description": "Inline size of the toggle indicator container.",
+              "name": "--rc-select-toggle-indicator-size",
+              "default": "1.1em"
             }
           ],
           "cssParts": [
@@ -140,22 +145,22 @@
               "name": "value-display"
             },
             {
-              "description": "The chevron/arrow icon container.",
-              "name": "toggle-icon"
+              "description": "The open/close indicator container.",
+              "name": "toggle-indicator"
             }
           ],
           "slots": [
             {
               "description": "Required. A native `<select>` element used for form submission and as the source of truth for options, multiple, and disabled state.",
-              "name": "select"
+              "name": ""
             },
             {
               "description": "Optional. Replaces the default value label in the trigger.",
               "name": "display"
             },
             {
-              "description": "Optional. Replaces the default chevron icon.",
-              "name": "toggle-icon"
+              "description": "Optional. Replaces the default chevron indicator. Accepts any element(s); the container shifts to inline-start in RTL via flex direction.",
+              "name": "toggle-indicator"
             }
           ],
           "members": [
@@ -166,6 +171,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Reflects whether the popup listbox is open.",
               "attribute": "open",
               "reflects": true
             },
@@ -176,6 +182,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Enables selection of multiple options simultaneously.",
               "attribute": "multiple",
               "reflects": true
             },
@@ -186,6 +193,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Disables the trigger and prevents the popup from opening.",
               "attribute": "disabled",
               "reflects": true
             },
@@ -196,6 +204,7 @@
                 "text": "string"
               },
               "default": "''",
+              "description": "Text shown in the trigger when no value is selected.",
               "attribute": "placeholder"
             },
             {
@@ -205,6 +214,7 @@
                 "text": "'auto' | 'chips' | 'compact'"
               },
               "default": "'auto'",
+              "description": "Controls how selected values appear in the trigger.\n\n- `'chips'` — each selected value renders as a removable chip.\n- `'compact'` — selected values are summarized as \"First, +N more\".\n- `'auto'` — uses `'chips'` on pointer devices and `'compact'` on touch.",
               "attribute": "display"
             },
             {
@@ -213,7 +223,8 @@
               "type": {
                 "text": "HTMLElement"
               },
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "Flex container used by `_anchorCtrl` as the positioning reference for the popup."
             },
             {
               "kind": "field",
@@ -221,7 +232,8 @@
               "type": {
                 "text": "HTMLElement"
               },
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "The combobox trigger div.\n\nOwns `role=\"combobox\"`, `aria-activedescendant`,\n`aria-expanded`, and receives focus during keyboard navigation."
             },
             {
               "kind": "field",
@@ -229,7 +241,8 @@
               "type": {
                 "text": "RCListbox"
               },
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "The `<rc-listbox>` popup. Receives option lists and selected-value updates from the host."
             },
             {
               "kind": "field",
@@ -238,7 +251,8 @@
                 "text": "Set<string>"
               },
               "privacy": "protected",
-              "default": "new Set()"
+              "default": "new Set()",
+              "description": "Reactive set of currently selected option values.\n\nDrive changes through `_applySelection` rather than mutating this directly\nso the listbox and native `<select>` stay in sync."
             },
             {
               "kind": "field",
@@ -246,8 +260,9 @@
               "type": {
                 "text": "number"
               },
-              "privacy": "private",
-              "default": "-1"
+              "privacy": "protected",
+              "default": "-1",
+              "description": "Index into the chip button array for roving-tabindex chip navigation.\n\n`-1` means focus is on the trigger."
             },
             {
               "kind": "field",
@@ -255,8 +270,9 @@
               "type": {
                 "text": "ListboxOption[]"
               },
-              "privacy": "private",
-              "default": "[]"
+              "privacy": "protected",
+              "default": "[]",
+              "description": "The resolved option list, as rendered in the listbox.\n\n`_options` is sourced from the `options` property or the slotted `<select>`."
             },
             {
               "kind": "field",
@@ -265,7 +281,15 @@
                 "text": "WeakRef<HTMLSelectElement> | null"
               },
               "privacy": "protected",
-              "default": "null"
+              "default": "null",
+              "description": "WeakRef to the slotted `<select>`. Refreshed on every `slotchange`; `null` when absent."
+            },
+            {
+              "kind": "field",
+              "name": "_selectController",
+              "privacy": "protected",
+              "readonly": true,
+              "default": "new NativeChildController<HTMLSelectElement>(this, { selector: ':scope > select', observe: true, onChange: ($select) => this._setupSelect($select), onMissing: () => { if (import.meta.env.DEV) { warnMissingDirectChild(this, { selector: ':scope > select', message: '[rc-select] No direct child <select> found. Place a native <select> inside <rc-select>.', }); } }, })"
             },
             {
               "kind": "field",
@@ -273,8 +297,9 @@
               "type": {
                 "text": "MutationObserver | null"
               },
-              "privacy": "private",
-              "default": "null"
+              "privacy": "protected",
+              "default": "null",
+              "description": "Watches the slotted `<select>` for `childList`, `subtree`, and `attributes` changes\nso the option list and disabled/multiple state stay in sync with author mutations."
             },
             {
               "kind": "field",
@@ -315,8 +340,9 @@
               "type": {
                 "text": "string"
               },
-              "privacy": "private",
-              "default": "''"
+              "privacy": "protected",
+              "default": "''",
+              "description": "Accumulated printable characters for type-ahead matching; cleared after 500 ms idle."
             },
             {
               "kind": "field",
@@ -324,24 +350,28 @@
               "type": {
                 "text": "number"
               },
-              "privacy": "private",
-              "default": "0"
+              "privacy": "protected",
+              "default": "0",
+              "description": "`window.setTimeout` handle for resetting `_typeAheadBuffer`; cancel before modifying."
             },
             {
               "kind": "field",
-              "name": "_adc",
+              "name": "_activeDescendantCtrl",
               "privacy": "protected",
-              "default": "new ActiveDescendantController(this, { host: () => this._$trigger ?? null, items: () => this._$listbox?.navigableItems ?? [], })"
+              "default": "new ActiveDescendantController(this, { host: () => this._$trigger ?? null, items: () => this._$listbox?.navigableItems ?? [], })",
+              "description": "Manages `aria-activedescendant` on `_$trigger` and keyboard cursor position\nwithin `_$listbox.navigableItems`."
             },
             {
               "kind": "field",
               "name": "_anchorCtrl",
               "privacy": "protected",
-              "default": "new AnchorController(this, { anchor: () => this._$anchor ?? null, floating: () => this._$listbox ?? null, shadowHost: () => this, placement: 'bottom-start', offset: 2, })"
+              "default": "new AnchorController(this, { anchor: () => this._$anchor ?? null, floating: () => this._$listbox ?? null, shadowHost: () => this, placement: 'bottom-start', offset: 2, })",
+              "description": "Manages CSS-anchored (or JS-fallback) placement of `_$listbox` relative to `_$anchor`."
             },
             {
               "kind": "method",
-              "name": "openPopup"
+              "name": "openPopup",
+              "description": "Opens the popup listbox if not already open or disabled."
             },
             {
               "kind": "method",
@@ -349,9 +379,11 @@
               "parameters": [
                 {
                   "name": "returnFocus",
-                  "default": "true"
+                  "default": "true",
+                  "description": "When `true` (default), returns focus to the trigger."
                 }
-              ]
+              ],
+              "description": "Closes the popup listbox."
             },
             {
               "kind": "field",
@@ -390,9 +422,10 @@
               "kind": "field",
               "name": "selectedOptions",
               "type": {
-                "text": "ListboxOption[]"
+                "text": "ListboxSelectableOption[]"
               },
               "privacy": "protected",
+              "description": "`ListboxOption` objects for the current selection; falls back to label-only stubs for unknown values.",
               "readonly": true
             },
             {
@@ -411,27 +444,36 @@
                     "text": "string[]"
                   }
                 }
-              ]
+              ],
+              "description": "Applies an already-normalized array of values as the current selection.\n\nIn single-select mode only the first value is kept. Syncs `_$listbox` and the\nnative `<select>` but does NOT dispatch `rc-select-change`."
             },
             {
               "kind": "field",
               "name": "_onDocClick",
-              "privacy": "private"
+              "privacy": "protected",
+              "description": "Document-capture click handler that closes the popup when a click lands outside `this`."
             },
             {
               "kind": "field",
               "name": "_onDocKeyDown",
-              "privacy": "private"
+              "privacy": "protected",
+              "description": "Document-capture keydown handler; closes the popup on `Escape`."
             },
             {
               "kind": "method",
               "name": "_handleSelectSlotChange",
               "privacy": "protected",
+              "description": "Resolves the slotted `<select>` on every `slotchange`, wires `_mutationObserver`,\nand seeds initial state via `queueMicrotask` to stay safe inside framework reactive passes."
+            },
+            {
+              "kind": "method",
+              "name": "_setupSelect",
+              "privacy": "protected",
               "parameters": [
                 {
-                  "name": "e",
+                  "name": "$select",
                   "type": {
-                    "text": "Event"
+                    "text": "HTMLSelectElement | null"
                   }
                 }
               ]
@@ -442,27 +484,29 @@
               "privacy": "protected",
               "parameters": [
                 {
-                  "name": "sel",
+                  "name": "$select",
                   "type": {
                     "text": "HTMLSelectElement"
                   }
                 }
-              ]
+              ],
+              "description": "Derives options from `$select` (or defers to `_propertyOptions` when set)\nand re-applies selection from the current authoritative source."
             },
             {
               "kind": "method",
               "name": "_applySelectionFromCurrentSource",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "description": "Picks the correct selection source in priority order:\ncontrolled `_value` → `_defaultValue` → native `<select>` default/current state."
             },
             {
               "kind": "method",
               "name": "_syncOptions",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "void"
@@ -475,22 +519,24 @@
                     "text": "ListboxOption[]"
                   }
                 }
-              ]
+              ],
+              "description": "Writes `_options` and pushes the list to `_$listbox` when it is mounted."
             },
             {
               "kind": "method",
               "name": "_currentOptions",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "ListboxOption[]"
                 }
-              }
+              },
+              "description": "Returns `_propertyOptions` when set; otherwise reads live from the slotted `<select>`."
             },
             {
               "kind": "method",
               "name": "_optionsFromSelect",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "ListboxOption[]"
@@ -498,42 +544,46 @@
               },
               "parameters": [
                 {
-                  "name": "sel",
+                  "name": "$select",
                   "type": {
                     "text": "HTMLSelectElement"
                   }
                 }
-              ]
+              ],
+              "description": "Maps non-empty native `<option>` nodes to `ListboxOption` objects.\n\nOptions with empty `value` are skipped (placeholder guard)."
             },
             {
               "kind": "method",
               "name": "_selectedValuesFromNativeSelect",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "string[]"
                 }
-              }
+              },
+              "description": "Returns values of currently selected `<option>` nodes; falls back to `selectedValues` when no native select is present."
             },
             {
               "kind": "method",
               "name": "_defaultSelectedValuesFromNativeSelect",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "string[]"
                 }
-              }
+              },
+              "description": "Returns values of `defaultSelected` `<option>` nodes (author `selected` attribute); falls back to `selectedValues`."
             },
             {
               "kind": "method",
               "name": "_mirrorOptionsToNativeSelect",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "description": "Rebuilds native `<select>` options from `_propertyOptions`.\n\nOnly runs when `_propertyOptions` is set; pauses then resumes `_mutationObserver`\nwhile writing to avoid re-entrant sync."
             },
             {
               "kind": "method",
@@ -551,12 +601,13 @@
                     "text": "ListboxOption"
                   }
                 }
-              ]
+              ],
+              "description": "Upserts a single option into `_options` (and `_propertyOptions` when set)\nand adds the corresponding `<option>` to the native `<select>` if absent."
             },
             {
               "kind": "method",
               "name": "_normalizeValue",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "string[]"
@@ -569,12 +620,13 @@
                     "text": "RCSelectValue"
                   }
                 }
-              ]
+              ],
+              "description": "Coerces `RCSelectValue` (string or string[]) to `string[]`; returns `[]` for empty-string singles."
             },
             {
               "kind": "method",
               "name": "_syncAccessibleName",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "void"
@@ -582,12 +634,13 @@
               },
               "parameters": [
                 {
-                  "name": "sel",
+                  "name": "$sel",
                   "type": {
                     "text": "HTMLSelectElement"
                   }
                 }
-              ]
+              ],
+              "description": "Copies `aria-label` or first-label text from the native `<select>` to `_$trigger`.\n\nNo-op when the trigger already has an explicit `aria-label`."
             },
             {
               "kind": "method",
@@ -600,7 +653,8 @@
                     "text": "CustomEvent"
                   }
                 }
-              ]
+              ],
+              "description": "Handles `rc-listbox-change` from the popup.\n\nStops propagation, mutates `_selectedValues`, syncs state, and fires\n`rc-select-change`."
             },
             {
               "kind": "method",
@@ -613,12 +667,14 @@
                     "text": "string"
                   }
                 }
-              ]
+              ],
+              "description": "Removes a single value from `_selectedValues`, syncs the listbox and native select, and dispatches `rc-select-change`."
             },
             {
               "kind": "method",
               "name": "_syncNativeSelect",
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "Flips `selected` on each `<option>` in the native `<select>` to match `_selectedValues`; no-op when no native select is present."
             },
             {
               "kind": "method",
@@ -628,15 +684,16 @@
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "description": "Constructs and dispatches `rc-select-change` with current `value`, `selectedValues`, and `selectedOptions`."
             },
             {
               "kind": "method",
               "name": "_selectedOptionsFor",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
-                  "text": "ListboxOption[]"
+                  "text": "ListboxSelectableOption[]"
                 }
               },
               "parameters": [
@@ -646,7 +703,8 @@
                     "text": "string[]"
                   }
                 }
-              ]
+              ],
+              "description": "Maps value strings to `ListboxOption` objects from `_options`; creates label-only fallback stubs for unknown values."
             },
             {
               "kind": "field",
@@ -655,6 +713,7 @@
                 "text": "'chips' | 'compact'"
               },
               "privacy": "protected",
+              "description": "Resolved display mode after `auto` pointer-detection: `'chips'` on fine-pointer devices, `'compact'` on coarse.",
               "readonly": true
             },
             {
@@ -673,7 +732,8 @@
                     "text": "string"
                   }
                 }
-              ]
+              ],
+              "description": "Looks up the display label for `value` from native `<select>` option text; returns `value` itself as a fallback."
             },
             {
               "kind": "field",
@@ -682,6 +742,7 @@
                 "text": "string"
               },
               "privacy": "protected",
+              "description": "Text shown in the trigger's value-display area; returns placeholder when chips are active or nothing is selected.",
               "readonly": true
             },
             {
@@ -695,17 +756,19 @@
                     "text": "KeyboardEvent"
                   }
                 }
-              ]
+              ],
+              "description": "APG Combobox keyboard handler on the trigger.\n\nArrow keys navigate/open, Space/Enter activate, Tab closes without focus return,\nArrowLeft enters chip navigation, and printable chars forward to type-ahead."
             },
             {
               "kind": "method",
               "name": "_activateActive",
-              "privacy": "private"
+              "privacy": "protected",
+              "description": "Dispatches a synthetic `pointerdown` on the active listbox item to activate it.\n\nPrefers `pointerdown` over a direct call so listbox item click logic\n(which is bound to `pointerdown`) fires through its normal path."
             },
             {
               "kind": "method",
               "name": "_handleTypeAhead",
-              "privacy": "private",
+              "privacy": "protected",
               "parameters": [
                 {
                   "name": "char",
@@ -713,22 +776,25 @@
                     "text": "string"
                   }
                 }
-              ]
+              ],
+              "description": "Accumulates characters in `_typeAheadBuffer` and either immediately selects\nthe first match (closed single-select) or moves the virtual cursor (open popup)."
             },
             {
               "kind": "method",
               "name": "_enterChipNav",
-              "privacy": "private"
+              "privacy": "protected",
+              "description": "Focuses the last chip button and sets `_chipNavIndex` to begin roving-tabindex navigation within the chip group."
             },
             {
               "kind": "method",
-              "name": "_getChipButtons",
-              "privacy": "private",
+              "name": "_$chipButtons",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "HTMLButtonElement[]"
                 }
-              }
+              },
+              "description": "Queries all `button[part~=\"chip\"]` elements in `renderRoot`; order matches DOM order."
             },
             {
               "kind": "method",
@@ -747,17 +813,20 @@
                     "text": "string"
                   }
                 }
-              ]
+              ],
+              "description": "Keyboard handler for chip buttons.\n\nArrowLeft/Right rove chip focus, Escape returns to trigger,\nDelete/Backspace/Enter/Space remove the chip's value\nand return focus to the trigger."
             },
             {
               "kind": "method",
               "name": "_handleTriggerClick",
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "Toggles the popup open or closed on trigger click."
             },
             {
               "kind": "method",
               "name": "_renderChips",
-              "privacy": "protected"
+              "privacy": "protected",
+              "description": "Renders the chip group `<span>` with one `<button>` per selected value for multi-select chip display mode."
             }
           ],
           "events": [
@@ -784,12 +853,17 @@
             }
           ],
           "attributes": [
+            {
+              "description": "Present when one or more options are selected. Use with CSS selectors (e.g. `rc-select[has-value]`) for floating-label wrappers.",
+              "name": "has-value"
+            },
             {
               "name": "open",
               "type": {
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Reflects whether the popup listbox is open.",
               "fieldName": "open"
             },
             {
@@ -798,6 +872,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Enables selection of multiple options simultaneously.",
               "fieldName": "multiple"
             },
             {
@@ -806,6 +881,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Disables the trigger and prevents the popup from opening.",
               "fieldName": "disabled"
             },
             {
@@ -814,6 +890,7 @@
                 "text": "string"
               },
               "default": "''",
+              "description": "Text shown in the trigger when no value is selected.",
               "fieldName": "placeholder"
             },
             {
@@ -822,6 +899,7 @@
                 "text": "'auto' | 'chips' | 'compact'"
               },
               "default": "'auto'",
+              "description": "Controls how selected values appear in the trigger.\n\n- `'chips'` — each selected value renders as a removable chip.\n- `'compact'` — selected values are summarized as \"First, +N more\".\n- `'auto'` — uses `'chips'` on pointer devices and `'compact'` on touch.",
               "fieldName": "display"
             }
           ],