@vialiq/web-components 0.19.0 → 0.20.0

package/README.md

@@ -298,6 +298,130 @@ vi-input {
 
 ---
 
+### Select ([vi-select](./src/select/vi-select.ts))
+
+> [!NOTE]
+> **Performance Notice:** The `vi-select` component automatically calculates its width to perfectly fit its content by measuring all rendered options. Because it renders all options directly into the DOM without virtualization, it is **not intended for large lists** (e.g., thousands of items). For massive datasets, use a combobox with virtualization and async filtering instead.
+
+The [ViSelect](./src/select/vi-select.ts) is a custom listbox component that replaces the native `<select>` element. It supports custom templating, dynamic wrapping, form integration, and floating dropdowns using Floating UI.
+
+#### Properties & Attributes
+
+| Attribute          | Property          | Type                            | Default     | Description                                      |
+| :----------------- | :---------------- | :------------------------------ | :---------- | :----------------------------------------------- |
+| `value`            | `value`           | `string`                        | `''`        | The currently selected option's value.           |
+| `placeholder`      | `placeholder`     | `string`                        | `'Select...'` | Text shown when no option is selected.           |
+| `name`             | `name`            | `string`                        | `''`        | Form field name.                                 |
+| `disabled`         | `disabled`        | `boolean`                       | `false`     | Disables the select component entirely.          |
+| `required`         | `required`        | `boolean`                       | `false`     | Makes selecting an option mandatory.             |
+| `clearable`        | `clearable`       | `boolean`                       | `false`     | Shows a clear button ("×") when an option is selected. |
+| `status`           | `status`          | `'default'\|'valid'\|'invalid'` | `'default'` | Controls validation visual border colors.        |
+| `validity-message` | `validityMessage` | `string`                        | `''`        | Custom error message to display in UI.           |
+| `wrap-text`        | `wrapText`        | `boolean`                       | `false`     | Allows text within the dropdown options to wrap instead of truncating. |
+| `match-width`      | `matchWidth`      | `boolean`                       | `true`      | Forces the listbox dropdown to match the trigger's width. |
+| `placement`        | `placement`       | `DropdownPlacement`             | `'bottom-start'` | Preferred positioning of the listbox dropdown. |
+| `hoist`            | `hoist`           | `boolean`                       | `true`      | Uses a fixed positioning strategy to escape clipping containers. |
+| `flip-boundary`    | `flipBoundary`    | `string`                        | `''`        | CSS selector for a boundary element used in collision detection. |
+
+#### Slots
+
+- **Default Slot**: Used for placing `<vi-select-option>` and `<vi-select-group>` child elements.
+- **`helper` Slot**: Location to insert description text below the select component.
+
+#### Child Components (`<vi-select-option>` and `<vi-select-group>`)
+
+Options are created using the `<vi-select-option>` tag inside the select.
+- **`value`**: The value to submit when selected.
+- **`label`**: The plain text label used for the trigger and type-ahead filtering.
+- **Default Slot**: You can place any complex HTML template inside the option (e.g., avatars, icons, badges) and it will render inside the listbox!
+
+You can group options logically using `<vi-select-group>`:
+- **`label`**: The heading text for the option group.
+
+#### CSS Custom Properties
+
+- `--vi-select-width`: Controls the width of the select trigger and the dropdown (default: `100%`).
+- `--vi-typeahead-highlight-bg`: Background color of the text match when using keyboard type-ahead (default: `#ebf5ff` / `blue-100`).
+- `--vi-typeahead-highlight-color`: Text color of the type-ahead match (default: `#3676d0` / `primary`).
+
+#### Events
+
+- `vialiq-change`: Fires when an option is selected. Detail: `{ value: string, label: string }`.
+- `vialiq-clear`: Fires when the clear button is clicked.
+
+#### Snippets
+
+**Basic Usage:**
+
+```html
+<vi-select name="country" placeholder="Select a country...">
+  <vi-select-option value="us" label="United States"></vi-select-option>
+  <vi-select-option value="uk" label="United Kingdom"></vi-select-option>
+  <vi-select-option value="ca" label="Canada"></vi-select-option>
+</vi-select>
+```
+
+**Custom Templates & Width:**
+
+```html
+<vi-select style="--vi-select-width: 300px;" placeholder="Select a user...">
+  <vi-select-option value="user1" label="Jane Doe">
+    <div style="display: flex; gap: 8px;">
+      <img src="avatar.png" alt="" />
+      <span>Jane Doe</span>
+    </div>
+  </vi-select-option>
+</vi-select>
+```
+
+**Option Groups:**
+
+```html
+<vi-select name="fruits" placeholder="Select a fruit...">
+  <vi-select-group label="Citrus">
+    <vi-select-option value="orange" label="Orange"></vi-select-option>
+    <vi-select-option value="lemon" label="Lemon"></vi-select-option>
+  </vi-select-group>
+  <vi-select-group label="Berries">
+    <vi-select-option value="strawberry" label="Strawberry"></vi-select-option>
+    <vi-select-option value="blueberry" label="Blueberry"></vi-select-option>
+  </vi-select-group>
+</vi-select>
+```
+
+**Placement & Fit Width (`match-width="false"`):**
+
+By default, the dropdown matches the width of the trigger. To allow the dropdown to grow based on its content width, and change the floating direction:
+
+```html
+<vi-select placement="top-start" match-width="false" placeholder="Select a user...">
+  <vi-select-option value="user1" label="Jane Doe">
+    <div style="display: flex; white-space: nowrap;">
+      Jane Doe (jane.doe@example.com - Senior Software Engineer)
+    </div>
+  </vi-select-option>
+</vi-select>
+```
+
+**Form Integration & Reset:**
+
+The `<vi-select>` responds properly to native form resets and submit interactions.
+
+```html
+<form>
+  <vi-select name="status" value="pending" required>
+    <vi-select-option value="pending" label="Pending"></vi-select-option>
+    <vi-select-option value="approved" label="Approved"></vi-select-option>
+  </vi-select>
+
+  <!-- This native reset will restore the select back to "pending" -->
+  <vi-button type="reset" variant="ghost">Clear Changes</vi-button>
+  <vi-button type="submit" variant="primary">Submit</vi-button>
+</form>
+```
+
+---
+
 ### Checkbox ([vi-checkbox](./src/checkbox/vi-checkbox.ts))
 
 The [ViCheckbox](./src/checkbox/vi-checkbox.ts) is a customizable form-associated checkbox control using SVG graphics for checkmarks and supporting the indeterminate (mixed) validation state.

package/base/controllers/floating-controller.d.ts

@@ -24,7 +24,7 @@ export interface FloatingControllerOptions {
     /** Element or selector string to constrain flipping. */
     boundary?: () => HTMLElement | string | null;
     /** Whether the floating element should be forced to match the reference element's width. */
-    matchWidth?: boolean;
+    matchWidth?: boolean | (() => boolean);
 }
 /**
  * FloatingController

package/base/controllers/floating-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"floating-controller.d.ts","sourceRoot":"","sources":["../../../../../libs/web-components/src/base/controllers/floating-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,KAAK,CAAC;AACjE,OAAO,EAAmD,KAAK,SAAS,EAAmB,MAAM,kBAAkB,CAAC;AAGpH;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,SAAS,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACpC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACnC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,SAAS,CAAC;IAC5B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAKzD,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,cAAc,CAAuB;gBAGnC,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,yBAAyB;IAK5C,gBAAgB;IAIhB;;;;;OAKG;IACH,KAAK;IAyBL;;;;;OAKG;IACH,IAAI;IAgBJ;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CAmDtC"}
+{"version":3,"file":"floating-controller.d.ts","sourceRoot":"","sources":["../../../../../libs/web-components/src/base/controllers/floating-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,KAAK,CAAC;AACjE,OAAO,EAAmD,KAAK,SAAS,EAAmB,MAAM,kBAAkB,CAAC;AAGpH;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,SAAS,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACpC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACnC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,SAAS,CAAC;IAC5B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAKzD,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,cAAc,CAAuB;gBAGnC,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,yBAAyB;IAK5C,gBAAgB;IAIhB;;;;;OAKG;IACH,KAAK;IAyBL;;;;;OAKG;IACH,IAAI;IAgBJ;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CA0DtC"}

package/button/vi-button.d.ts

@@ -53,6 +53,8 @@ export declare class ViButton extends ViButton_base {
     accessor iconOnly: boolean;
     /** Disables the button. */
     accessor disabled: boolean;
+    /** The button type — 'button', 'submit', or 'reset'. Forwarded to the inner native button. */
+    accessor type: 'button' | 'submit' | 'reset';
     /** Accessible label forwarded to the inner native button. */
     accessor ariaLabel: string | null;
     private accessor _hasIcon;

package/button/vi-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vi-button.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/button/vi-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAG9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9F;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,KAAK,CAAC;;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,QAAS,SAAQ,aAAyB;IACrD,OAAgB,MAAM,0BAAmC;IAEzD,cAAuB,iBAAiB,IAAI,iBAAiB,GAAG,IAAI,CAEnE;IAED,sBAAsB;IACqB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAa;IAEvF,mDAAmD;IACR,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAQ;IAE5E,sHAAsH;IAC9C,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAW;IAE9H,0EAA0E;IACL,QAAQ,CAAC,SAAS,UAAS;IAEhG,kGAAkG;IAC9B,QAAQ,CAAC,QAAQ,UAAS;IAE9F,2BAA2B;IACiB,QAAQ,CAAC,QAAQ,UAAS;IAEtE,6DAA6D;IAC7D,SAAyD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEhF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAe/C,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,OAAO;IAON,MAAM,IAAI,cAAc;CAwBlC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,QAAQ,CAAC;KACvB;CACF"}
+{"version":3,"file":"vi-button.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/button/vi-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAG9F,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9F;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,KAAK,CAAC;;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,QAAS,SAAQ,aAAyB;IACrD,OAAgB,MAAM,0BAAmC;IAEzD,cAAuB,iBAAiB,IAAI,iBAAiB,GAAG,IAAI,CAEnE;IAED,sBAAsB;IACqB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAa;IAEvF,mDAAmD;IACR,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAQ;IAE5E,sHAAsH;IAC9C,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAW;IAE9H,0EAA0E;IACL,QAAQ,CAAC,SAAS,UAAS;IAEhG,kGAAkG;IAC9B,QAAQ,CAAC,QAAQ,UAAS;IAE9F,2BAA2B;IACiB,QAAQ,CAAC,QAAQ,UAAS;IAEtE,8FAA8F;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAEnG,6DAA6D;IAC7D,SAAyD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEhF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAe/C,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,OAAO;IAwBN,MAAM,IAAI,cAAc;CAwBlC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,QAAQ,CAAC;KACvB;CACF"}

package/button/vi-button.js

@@ -380,7 +380,7 @@ function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
 function _identity(x) {
     return x;
 }
-var _dec, _initClass, _FocusableMixin, _dec1, _dec2, _dec3, _dec4, _dec5, _dec6, _dec7, _dec8, /** Visual variant. */ _init_variant, /** Size scale — controls padding and font-size. */ _init_size, /** Icon placement: 'start' (before label) or 'end' (after label). CSS order handles it — no DOM changes on toggle. */ _init_iconPlacement, /** When true, stretches the button to fill the width of its container. */ _init_fullWidth, /** When true, styles the button for an icon-only layout (typically square with equal padding). */ _init_iconOnly, /** Disables the button. */ _init_disabled, /** Accessible label forwarded to the inner native button. */ _init_ariaLabel, _init__hasIcon, _initProto;
+var _dec, _initClass, _FocusableMixin, _dec1, _dec2, _dec3, _dec4, _dec5, _dec6, _dec7, _dec8, _dec9, /** Visual variant. */ _init_variant, /** Size scale — controls padding and font-size. */ _init_size, /** Icon placement: 'start' (before label) or 'end' (after label). CSS order handles it — no DOM changes on toggle. */ _init_iconPlacement, /** When true, stretches the button to fill the width of its container. */ _init_fullWidth, /** When true, styles the button for an icon-only layout (typically square with equal padding). */ _init_iconOnly, /** Disables the button. */ _init_disabled, /** The button type — 'button', 'submit', or 'reset'. Forwarded to the inner native button. */ _init_type, /** Accessible label forwarded to the inner native button. */ _init_ariaLabel, _init__hasIcon, _initProto;
 let _ViButton;
 _dec = customElement('vi-button'), _dec1 = property({
     type: String,
@@ -404,8 +404,11 @@ _dec = customElement('vi-button'), _dec1 = property({
     type: Boolean,
     reflect: true
 }), _dec7 = property({
+    type: String,
+    reflect: true
+}), _dec8 = property({
     attribute: 'aria-label'
-}), _dec8 = state();
+}), _dec9 = state();
 new class extends _identity {
     constructor(){
         super(_ViButton), _initClass();
@@ -413,7 +416,7 @@ new class extends _identity {
     static{
         class ViButton extends (_FocusableMixin = FocusableMixin(ViElement)) {
             static{
-                ({ e: [_init_variant, _init_size, _init_iconPlacement, _init_fullWidth, _init_iconOnly, _init_disabled, _init_ariaLabel, _init__hasIcon, _initProto], c: [_ViButton, _initClass] } = _apply_decs_2203_r(this, [
+                ({ e: [_init_variant, _init_size, _init_iconPlacement, _init_fullWidth, _init_iconOnly, _init_disabled, _init_type, _init_ariaLabel, _init__hasIcon, _initProto], c: [_ViButton, _initClass] } = _apply_decs_2203_r(this, [
                     [
                         _dec1,
                         1,
@@ -447,11 +450,16 @@ new class extends _identity {
                     [
                         _dec7,
                         1,
-                        "ariaLabel"
+                        "type"
                     ],
                     [
                         _dec8,
                         1,
+                        "ariaLabel"
+                    ],
+                    [
+                        _dec9,
+                        1,
                         "_hasIcon"
                     ]
                 ], [
@@ -504,19 +512,26 @@ new class extends _identity {
             set disabled(_v) {
                 this.#___private_disabled_6 = _v;
             }
-            #___private_ariaLabel_7 = _init_ariaLabel(this, null);
+            #___private_type_7 = _init_type(this, 'button');
+            get type() {
+                return this.#___private_type_7;
+            }
+            set type(_v) {
+                this.#___private_type_7 = _v;
+            }
+            #___private_ariaLabel_8 = _init_ariaLabel(this, null);
             get ariaLabel() {
-                return this.#___private_ariaLabel_7;
+                return this.#___private_ariaLabel_8;
             }
             set ariaLabel(_v) {
-                this.#___private_ariaLabel_7 = _v;
+                this.#___private_ariaLabel_8 = _v;
             }
-            #___private__hasIcon_8 = _init__hasIcon(this, false);
+            #___private__hasIcon_9 = _init__hasIcon(this, false);
             get _hasIcon() {
-                return this.#___private__hasIcon_8;
+                return this.#___private__hasIcon_9;
             }
             set _hasIcon(_v) {
-                this.#___private__hasIcon_8 = _v;
+                this.#___private__hasIcon_9 = _v;
             }
             updated(changed) {
                 super.updated(changed);
@@ -542,6 +557,20 @@ new class extends _identity {
                 if (this.disabled) {
                     event.preventDefault();
                     event.stopImmediatePropagation();
+                    return;
+                }
+                // Shadow DOM isolation: a <button type="reset|submit"> inside a shadow root
+                // cannot natively interact with the parent form. We must do it manually.
+                if (this.type === 'reset' || this.type === 'submit') {
+                    const form = event.composedPath().find((n)=>n instanceof HTMLFormElement);
+                    if (form) {
+                        if (this.type === 'reset') {
+                            form.reset();
+                        } else {
+                            const submitter = event.currentTarget instanceof HTMLButtonElement ? event.currentTarget : undefined;
+                            form.requestSubmit(submitter);
+                        }
+                    }
                 }
             }
             render() {
@@ -550,7 +579,7 @@ new class extends _identity {
       <button
         class="button"
         part="button"
-        type="button"
+        type=${this.type}
         tabindex="0"
         ?disabled=${disabled}
         aria-label=${this.ariaLabel ?? nothing}

package/index.d.ts

@@ -38,4 +38,7 @@ export { ViTag } from './tag/vi-tag.js';
 export type { TagVariant, TagAppearance, TagSize } from './tag/vi-tag.js';
 export { ViSwitch } from './switch/vi-switch.js';
 export type { SwitchSize, LabelPlacement } from './switch/vi-switch.js';
+export { ViSelect } from './select/vi-select.js';
+export { ViSelectOption } from './select/vi-select-option.js';
+export { ViSelectGroup } from './select/vi-select-group.js';
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -20,3 +20,6 @@ export { ViChipGroup } from './chip/vi-chip-group.js';
 export { ViAnimation } from './animation/vi-animation.js';
 export { ViTag } from './tag/vi-tag.js';
 export { ViSwitch } from './switch/vi-switch.js';
+export { ViSelect } from './select/vi-select.js';
+export { ViSelectOption } from './select/vi-select-option.js';
+export { ViSelectGroup } from './select/vi-select-group.js';

package/keyboard-controller-DqpJtUuK.js

@@ -0,0 +1,320 @@
+import { autoUpdate, offset, flip, size, computePosition } from '@floating-ui/dom';
+import { O as OverlayManager } from './overlay-manager-Ch_6fr_D.js';
+
+/**
+ * FloatingController
+ * 
+ * A Lit Reactive Controller that manages `@floating-ui/dom` positioning logic.
+ * It abstracts away the complex math and event listeners (autoUpdate) required to 
+ * keep a popup/dropdown anchored to a reference element during scrolling/resizing.
+ * 
+ * It also automatically registers the floating element with the `OverlayManager` 
+ * to ensure correct z-index stacking when `hoist` is true.
+ */ class FloatingController {
+    host;
+    options;
+    _cleanup;
+    _overlayZIndex = null;
+    constructor(host, options){
+        this.host = host;
+        this.options = options;
+        this.host.addController(this);
+    }
+    hostDisconnected() {
+        this.stop();
+    }
+    /**
+   * Starts the floating UI `autoUpdate` listener cycle.
+   * This should be called when the popover physically opens (e.g., in `updated()`).
+   * 
+   * If `hoist` is true, it also acquires a high z-index from the `OverlayManager`.
+   */ start() {
+        const ref = this.options.reference();
+        const floating = this.options.floating();
+        if (!ref || !floating) return;
+        // autoUpdate automatically cleans up previous listeners if called multiple times,
+        // but it's safer to just track and call cleanup manually.
+        if (this._cleanup) this.stop();
+        const hoist = this.options.hoist?.() ?? false;
+        // Register with OverlayManager if hoisted
+        if (hoist) {
+            this._overlayZIndex = OverlayManager.register(floating, 'dropdown');
+            floating.style.zIndex = this._overlayZIndex.toString();
+        }
+        this._cleanup = autoUpdate(ref, floating, ()=>this.updatePosition(), {
+            animationFrame: false
+        });
+    }
+    /**
+   * Stops the floating UI `autoUpdate` listener cycle.
+   * This should be called when the popover closes, or when the host component disconnects.
+   * 
+   * It also releases its z-index back to the `OverlayManager`.
+   */ stop() {
+        if (this._cleanup) {
+            this._cleanup();
+            this._cleanup = undefined;
+        }
+        const floating = this.options.floating();
+        if (floating && this._overlayZIndex !== null) {
+            OverlayManager.unregister(floating);
+            this._overlayZIndex = null;
+            // Remove inline z-index only if we managed it
+            floating.style.removeProperty('z-index');
+        }
+    }
+    /**
+   * Imperatively calculates and applies the new coordinates (`x`, `y`) using Floating UI.
+   * 
+   * This method applies various CSS property resets (`margin`, `bottom`, `right`, `minWidth`) 
+   * to ensure that the base CSS of the floating element does not distort the absolute coordinates 
+   * provided by Floating UI.
+   */ async updatePosition() {
+        const ref = this.options.reference();
+        const floating = this.options.floating();
+        if (!ref || !floating) return;
+        const placementStr = this.options.placement?.() ?? 'bottom-start';
+        const hoist = this.options.hoist?.() ?? false;
+        const boundaryOpt = this.options.boundary?.();
+        let boundaryElement = 'clippingAncestors';
+        if (boundaryOpt instanceof HTMLElement) {
+            boundaryElement = boundaryOpt;
+        } else if (typeof boundaryOpt === 'string' && boundaryOpt) {
+            const customBoundary = document.querySelector(boundaryOpt);
+            if (customBoundary) boundaryElement = customBoundary;
+        }
+        const middlewares = [
+            offset(this.options.offset ?? 4),
+            flip({
+                boundary: boundaryElement,
+                fallbackPlacements: [
+                    'top-start',
+                    'bottom-start',
+                    'top-end',
+                    'bottom-end'
+                ]
+            })
+        ];
+        const matchWidthVal = typeof this.options.matchWidth === 'function' ? this.options.matchWidth() : this.options.matchWidth;
+        middlewares.push(size({
+            apply: ({ rects })=>{
+                if (matchWidthVal !== false) {
+                    Object.assign(floating.style, {
+                        width: `${rects.reference.width}px`,
+                        minWidth: 'auto'
+                    });
+                } else {
+                    Object.assign(floating.style, {
+                        width: 'auto',
+                        minWidth: `${rects.reference.width}px`
+                    });
+                }
+            }
+        }));
+        const { x, y, placement } = await computePosition(ref, floating, {
+            placement: placementStr,
+            strategy: hoist ? 'fixed' : 'absolute',
+            middleware: middlewares
+        });
+        floating.setAttribute('data-placement', placement);
+        Object.assign(floating.style, {
+            left: `${x}px`,
+            top: `${y}px`,
+            right: 'auto',
+            bottom: 'auto',
+            position: hoist ? 'fixed' : 'absolute',
+            margin: '0'
+        });
+    }
+}
+
+class ListboxKeyboardController {
+    host;
+    config;
+    _searchString = '';
+    _searchTimeout;
+    constructor(host, config){
+        this.host = host;
+        this.config = config;
+        this.host.addController(this);
+    }
+    hostConnected() {}
+    handleKeyDown(e) {
+        if (this.host.disabled) return;
+        const options = this.config.getFilteredOptions();
+        const isSlotted = this.config.getSlottedItems().length > 0;
+        const activeIndex = this.config.getActiveIndex();
+        switch(e.key){
+            case 'ArrowDown':
+                e.preventDefault();
+                if (!this.host.open) this.config.openDropdown();
+                this._navigate(1);
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                if (!this.host.open) this.config.openDropdown();
+                this._navigate(-1);
+                break;
+            case 'Enter':
+                e.preventDefault();
+                if (this.host.open) {
+                    if (isSlotted) {
+                        const visible = this.config.getVisibleSlottedItems();
+                        if (activeIndex >= 0 && activeIndex < visible.length) {
+                            const item = visible[activeIndex];
+                            this.config.selectOption({
+                                value: item.value,
+                                label: item.label || item.value,
+                                searchText: item.searchText.length > 0 ? item.searchText.join(' ') : undefined,
+                                group: item.group || undefined,
+                                disabled: item.disabled,
+                                icon: item.icon || undefined,
+                                description: item.description || undefined,
+                                data: item.data
+                            });
+                        } else if (this.host.mode === 'tags' || this.host.mode === 'creatable') {
+                            this.config.handleCreate();
+                        }
+                    } else if (activeIndex >= 0 && activeIndex < options.length) {
+                        this.config.selectOption(options[activeIndex]);
+                    } else if (this.host.mode === 'tags' || this.host.mode === 'creatable') {
+                        this.config.handleCreate();
+                    }
+                } else if (this.host.mode === 'tags' || this.host.mode === 'creatable') {
+                    this.config.handleCreate();
+                } else {
+                    this.config.openDropdown();
+                }
+                break;
+            case ',':
+                if (this.host.mode === 'tags') {
+                    e.preventDefault();
+                    this.config.handleCreate();
+                }
+                break;
+            case 'Escape':
+                if (this.host.open) {
+                    e.preventDefault();
+                    this.config.close();
+                }
+                break;
+            case 'Backspace':
+                if (this.host.isSearchable && !this.config.getQuery() && (this.host.mode === 'multi' || this.host.mode === 'tags')) {
+                    const selected = this.config.getSelectedValues();
+                    if (selected.length > 0) {
+                        this.config.removeTag(selected[selected.length - 1]);
+                    }
+                }
+                break;
+            case 'Home':
+                if (this.host.open) {
+                    e.preventDefault();
+                    const len = isSlotted ? this.config.getVisibleSlottedItems().length : options.length;
+                    if (len > 0) this._navigate(1, 0);
+                }
+                break;
+            case 'End':
+                if (this.host.open) {
+                    e.preventDefault();
+                    const len = isSlotted ? this.config.getVisibleSlottedItems().length : options.length;
+                    if (len > 0) this._navigate(-1, len - 1);
+                }
+                break;
+            case ' ':
+                if (!this.host.isSearchable && !this.host.open) {
+                    e.preventDefault();
+                    this.config.openDropdown();
+                } else if (!this.host.isSearchable && this.host.open && this._searchString.length > 0) {
+                    e.preventDefault();
+                    this._handleTypeAhead(' ');
+                }
+                break;
+            default:
+                if (!this.host.isSearchable && e.key.length === 1 && !e.ctrlKey && !e.altKey && !e.metaKey) {
+                    e.preventDefault();
+                    this._handleTypeAhead(e.key);
+                }
+                break;
+        }
+    }
+    _handleTypeAhead(char) {
+        if (this._searchTimeout) {
+            clearTimeout(this._searchTimeout);
+        }
+        this._searchTimeout = setTimeout(()=>{
+            this._searchString = '';
+            this.config.onTypeAheadChange?.(this._searchString);
+        }, 1000);
+        this._searchString += char.toLowerCase();
+        this.config.onTypeAheadChange?.(this._searchString);
+        const options = this.config.getFilteredOptions();
+        const isSlotted = this.config.getSlottedItems().length > 0;
+        const visible = isSlotted ? this.config.getVisibleSlottedItems() : [];
+        const len = isSlotted ? visible.length : options.length;
+        if (len === 0) return;
+        const getLabel = (i)=>{
+            if (isSlotted) {
+                return (visible[i]?.label || visible[i]?.textContent || '').toLowerCase();
+            }
+            return (options[i]?.label || options[i]?.value || '').toLowerCase();
+        };
+        const isDisabled = (i)=>(isSlotted ? visible[i]?.disabled : options[i]?.disabled) ?? false;
+        // Start searching from current active index + 1
+        const startIdx = Math.max(0, this.config.getActiveIndex());
+        let matchIdx = -1;
+        // Search after current index
+        for(let i = startIdx + 1; i < len; i++){
+            if (!isDisabled(i) && getLabel(i).startsWith(this._searchString)) {
+                matchIdx = i;
+                break;
+            }
+        }
+        // Wrap around to start
+        if (matchIdx === -1) {
+            for(let i = 0; i <= startIdx; i++){
+                if (!isDisabled(i) && getLabel(i).startsWith(this._searchString)) {
+                    matchIdx = i;
+                    break;
+                }
+            }
+        }
+        if (matchIdx !== -1) {
+            this.config.setActiveIndex(matchIdx);
+            if (isSlotted) this.config.updateSlottedActiveState(matchIdx);
+            this.config.scrollToActiveIndex();
+        }
+    }
+    _navigate(direction, startFrom) {
+        const options = this.config.getFilteredOptions();
+        const isSlotted = this.config.getSlottedItems().length > 0;
+        const visible = isSlotted ? this.config.getVisibleSlottedItems() : [];
+        const len = isSlotted ? visible.length : options.length;
+        const isDisabled = (i)=>(isSlotted ? visible[i]?.disabled : options[i]?.disabled) ?? false;
+        if (len === 0) {
+            this.config.setActiveIndex(-1);
+            if (isSlotted) this.config.updateSlottedActiveState(-1);
+            return;
+        }
+        let next = startFrom !== undefined ? startFrom : this.config.getActiveIndex();
+        if (startFrom === undefined && next === -1) {
+            next = direction === 1 ? -1 : 0;
+        } else if (startFrom !== undefined) {
+            if (!isDisabled(next)) {
+                this.config.setActiveIndex(next);
+                if (isSlotted) this.config.updateSlottedActiveState(next);
+                this.config.scrollToActiveIndex();
+                return;
+            }
+        }
+        for(let step = 0; step < len; step++){
+            next = (next + direction + len) % len;
+            if (!isDisabled(next)) break;
+        }
+        if (isDisabled(next)) next = -1;
+        this.config.setActiveIndex(next);
+        if (isSlotted) this.config.updateSlottedActiveState(next);
+        this.config.scrollToActiveIndex();
+    }
+}
+
+export { FloatingController as F, ListboxKeyboardController as L };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vialiq/web-components",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
   },
   "peerDependencies": {
     "@floating-ui/dom": ">=1.0.0",
-    "@vialiq/flux-ui": "^0.15.0",
+    "@vialiq/flux-ui": "^0.16.0",
     "@vialiq/icons": ">=0.0.3 <0.1.0",
     "lit": "^3.0.0"
   },