@descope-ui/descope-combo-box 0.0.1

package/e2e/descope-combo-box.spec.ts

@@ -0,0 +1,462 @@
+import { test, expect } from '@playwright/test';
+import { getStoryUrl, loopConfig, loopPresets } from 'e2e-utils';
+import { createComboBoxTestDriver } from 'test-drivers';
+
+const storyName = 'descope-combo-box';
+const componentName = 'descope-combo-box';
+
+const BooleanValues = ['true', 'false'];
+
+const componentAttributes = {
+  label: 'Number field label',
+  placeholder: 'Test placeholder',
+  size: ['xs', 'sm', 'md', 'lg'],
+  bordered: BooleanValues,
+  readonly: BooleanValues,
+  required: BooleanValues,
+  'full-width': BooleanValues,
+  disabled: 'true',
+  'default-value': 'itemId2',
+};
+
+const presets = {
+  'Render with alt item renderer': {
+    itemsSource: 'prop',
+    overrideRenderItem: 'true',
+  },
+  'Render with data property': { itemsSource: 'prop' },
+  'Render with data attribute': { itemsSource: 'attr' },
+  'Render with data property and default value': {
+    itemsSource: 'prop',
+    'default-value': 'itemId2',
+  },
+};
+
+const rtlPresets = {
+  'direction rtl': {
+    direction: 'rtl',
+    label: '-Test Label',
+    placeholder: '-Test Placeholder',
+    itemsSource: 'attr',
+    'data[0].displayName': '-Item 1',
+    'data[1].displayName': '-Item 2',
+    'data[1].label': '-Data Item 2',
+  },
+  'direction rtl required': {
+    direction: 'rtl',
+    label: '-Test Label',
+    placeholder: '-Test Placeholder',
+    itemsSource: 'attr',
+    'data[0].displayName': '-Item 1',
+    'data[1].displayName': '-Item 2',
+    'data[1].label': '-Data Item 2',
+    required: 'true',
+  },
+};
+
+const floatingLabelProps = {
+  'label-type': 'floating',
+  label: 'label-',
+  placeholder: 'placeholder',
+};
+
+export const floatingLabelTypePresets = {
+  'floating label ltr': floatingLabelProps,
+  'floating label rtl': {
+    ...floatingLabelProps,
+    direction: 'rtl',
+  },
+  'floating label ltr with value': {
+    ...floatingLabelProps,
+    'default-value': 'itemId2',
+    direction: 'ltr',
+  },
+  'floating label rtl with value': {
+    ...floatingLabelProps,
+    'default-value': 'itemId2',
+    direction: 'rtl',
+  },
+};
+
+test.describe('theme', () => {
+  const { placeholder, ...restConfig } = componentAttributes;
+
+  test.describe('with placeholder', () => {
+    test.beforeEach(async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, { placeholder }), {
+        waitUntil: 'networkidle',
+      });
+      await page.waitForSelector(componentName);
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.clear();
+    });
+
+    test('hover', async ({ page }) => {
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.hover();
+      expect(await component.screenshot()).toMatchSnapshot();
+    });
+
+    test('focus', async ({ page }) => {
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.focus();
+      expect(await component.screenshot()).toMatchSnapshot();
+    });
+  });
+
+  loopPresets(presets, (preset, name) => {
+    test.describe(name, () => {
+      test.beforeEach(async ({ page }) => {
+        await page.goto(getStoryUrl(storyName, preset), {
+          waitUntil: 'networkidle',
+        });
+      });
+
+      test('hover', async ({ page }) => {
+        const component = createComboBoxTestDriver(page.locator(componentName));
+        await component.hover();
+        expect(
+          await component.screenshot({ animations: 'disabled' }),
+        ).toMatchSnapshot();
+      });
+
+      test('focus', async ({ page }) => {
+        const component = createComboBoxTestDriver(page.locator(componentName));
+        await component.focus();
+        expect(
+          await component.screenshot({ animations: 'disabled' }),
+        ).toMatchSnapshot();
+      });
+    });
+  });
+
+  test.describe('with value', () => {
+    loopConfig(restConfig, (attr, value) => {
+      test.describe(`${attr}: ${value}`, () => {
+        test.beforeEach(async ({ page }) => {
+          await page.goto(getStoryUrl(storyName, { [attr]: value }), {
+            waitUntil: 'networkidle',
+          });
+
+          const component = createComboBoxTestDriver(
+            page.locator(componentName),
+          );
+          component.setValue('itemId4');
+        });
+
+        test('hover', async ({ page }) => {
+          const component = createComboBoxTestDriver(
+            page.locator(componentName),
+          );
+          await component.hover();
+          expect(await component.screenshot()).toMatchSnapshot();
+        });
+
+        test('focus', async ({ page }) => {
+          const component = createComboBoxTestDriver(
+            page.locator(componentName),
+          );
+          await component.focus();
+          expect(await component.screenshot()).toMatchSnapshot();
+        });
+      });
+    });
+  });
+
+  test.describe('dropDown', () => {
+    loopConfig(
+      {
+        size: componentAttributes.size,
+        'full-width': componentAttributes['full-width'],
+      },
+      (attr, value) => {
+        test.describe(`${attr}: ${value}`, () => {
+          test.beforeEach(async ({ page }) => {
+            await page.goto(getStoryUrl(storyName, { [attr]: value }), {
+              waitUntil: 'networkidle',
+            });
+
+            const component = createComboBoxTestDriver(
+              page.locator(componentName),
+            );
+            await component.openDropdown();
+          });
+          test('visible', async ({ page }) => {
+            const component = createComboBoxTestDriver(
+              page.locator(componentName),
+            );
+            await component.hover();
+            expect(await component.dropDown.screenshot()).toMatchSnapshot();
+          });
+        });
+      },
+    );
+  });
+
+  test.describe('direction rtl', () => {
+    loopPresets(rtlPresets, (preset, name) => {
+      test(name, async ({ page }) => {
+        await page.goto(getStoryUrl(storyName, preset));
+        await page.waitForSelector(componentName);
+        const component = page.locator(componentName);
+
+        expect(
+          await component.screenshot({
+            animations: 'disabled',
+            timeout: 3000,
+            caret: 'hide',
+          }),
+        ).toMatchSnapshot();
+      });
+    });
+    test('with error', async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, Object.values(rtlPresets)[1]), {
+        waitUntil: 'networkidle',
+      });
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await page.getByRole('button').getByText('Submit').click();
+      expect(await component.screenshot({ delay: 1000 })).toMatchSnapshot();
+    });
+
+    test('with open dropdown', async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, Object.values(rtlPresets)[1]), {
+        waitUntil: 'networkidle',
+      });
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.openDropdown();
+      await component.hover();
+      expect(await component.dropDown.screenshot()).toMatchSnapshot();
+    });
+
+    test('with open dropdown and value', async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, Object.values(rtlPresets)[1]), {
+        waitUntil: 'networkidle',
+      });
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.setValue('itemId2');
+      await component.openDropdown();
+      await component.hover();
+      expect(await component.dropDown.screenshot()).toMatchSnapshot();
+    });
+
+    test('with value', async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, Object.values(rtlPresets)[1]), {
+        waitUntil: 'networkidle',
+      });
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.setValue('itemId2');
+      expect(await component.screenshot()).toMatchSnapshot();
+    });
+  });
+});
+
+test.describe('logic', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { 'full-width': true }), {
+      waitUntil: 'networkidle',
+    });
+  });
+
+  test('select item', async ({ page }) => {
+    const component = createComboBoxTestDriver(page.locator(componentName));
+    await component.openDropdown();
+    await component.selectItem("Achilles' Fateful Wrath");
+
+    expect(await component.getValue()).toBe('itemId2');
+  });
+
+  // 'required' - not working as expected
+
+  test.describe('clear button', () => {
+    test('clear button visible when has value', async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, { 'default-value': 'itemId2' }), {
+        waitUntil: 'networkidle',
+      });
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.clearSelection();
+      expect(await component.getValue()).toBe('');
+    });
+  });
+
+  test('loading state', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, {}));
+    const componentLocator = page.locator(componentName);
+    const component = createComboBoxTestDriver(componentLocator);
+
+    await componentLocator.evaluate((node: HTMLElement) => {
+      node.setAttribute('loading', 'true');
+    });
+    await component.openDropdown();
+    expect(
+      await component.dropDown.screenshot({ animations: 'disabled' }),
+    ).toMatchSnapshot();
+
+    await componentLocator.evaluate((node: HTMLElement) => {
+      node.removeAttribute('loading');
+    });
+    await page.waitForTimeout(1000);
+    expect(
+      await component.dropDown.screenshot({ animations: 'disabled' }),
+    ).toMatchSnapshot();
+  });
+
+  test('allow custom value', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { 'allow-custom-value': true }));
+    const component = createComboBoxTestDriver(page.locator(componentName));
+    const value = 'new value';
+    await component.setValue(value);
+    expect(await component.screenshot()).toMatchSnapshot();
+    expect(await component.getValue()).toBe(value);
+  });
+
+  test.describe('reset value', () => {
+    const testResetValue = async (
+      page: any,
+      allowCustomValue: boolean,
+      extraSteps?: (component: any) => Promise<void>,
+    ) => {
+      const urlParams = allowCustomValue ? { 'allow-custom-value': true } : {};
+      await page.goto(getStoryUrl(storyName, urlParams));
+      const component = createComboBoxTestDriver(page.locator(componentName));
+      await component.setValue('itemId2');
+      expect(await component.getValue()).toBe('itemId2');
+      expect(await component.screenshot()).toMatchSnapshot();
+      await component.setValue('');
+      expect(await component.getValue()).toBe('');
+      expect(await component.screenshot()).toMatchSnapshot();
+
+      if (extraSteps) {
+        await extraSteps(component);
+      }
+    };
+
+    test('no custom value', async ({ page }) => {
+      await testResetValue(page, false);
+    });
+
+    test('allow custom value', async ({ page }) => {
+      await testResetValue(page, true, async (component) => {
+        await component.setValue('new value');
+        expect(await component.getValue()).toBe('new value');
+        expect(await component.screenshot()).toMatchSnapshot();
+        await component.setValue('');
+        expect(await component.getValue()).toBe('');
+        expect(await component.screenshot()).toMatchSnapshot();
+      });
+    });
+  });
+
+  test('error message with icon', async ({ page }) => {
+    await page.goto(
+      getStoryUrl(storyName, { required: true, errorMsgIcon: true }),
+    );
+
+    const component = createComboBoxTestDriver(page.locator(componentName));
+
+    await page.getByRole('button').getByText('Submit').click();
+
+    await component.blur();
+
+    expect(
+      await component.screenshot({
+        animations: 'disabled',
+        caret: 'hide',
+        delay: 3000,
+      }),
+    ).toMatchSnapshot();
+  });
+});
+
+test.describe('variants', () => {
+  loopPresets(floatingLabelTypePresets, (preset, name) => {
+    test.describe(name, () => {
+      test.beforeEach(async ({ page }) => {
+        await page.goto(getStoryUrl(storyName, preset), {
+          waitUntil: 'networkidle',
+        });
+      });
+
+      test('hover', async ({ page }) => {
+        const component = createComboBoxTestDriver(page.locator(componentName));
+        await component.setValue('itemId2');
+        await component.hover();
+        expect(
+          await component.screenshot({ animations: 'disabled' }),
+        ).toMatchSnapshot();
+      });
+      test('focus', async ({ page }) => {
+        const component = createComboBoxTestDriver(page.locator(componentName));
+        await component.focus();
+        expect(
+          await component.screenshot({ animations: 'disabled' }),
+        ).toMatchSnapshot();
+      });
+    });
+  });
+});
+
+test.describe('hide toggle button', () => {
+  test('hide toggle button', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { 'hide-toggle-button': true }));
+    const component = createComboBoxTestDriver(page.locator(componentName));
+    expect(await component.screenshot()).toMatchSnapshot();
+    await component.openDropdown();
+    expect(await component.dropDown.screenshot()).toMatchSnapshot();
+    await component.insertValue('itemname1');
+    expect(await component.screenshot()).toMatchSnapshot();
+    expect(await component.dropDown.screenshot()).toMatchSnapshot();
+  });
+});
+
+test.describe('data attribute', () => {
+  test('clear items', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { itemsSource: 'prop' }));
+    const componentLocator = page.locator(componentName);
+    const component = createComboBoxTestDriver(componentLocator);
+    await component.openDropdown();
+    let items = await component.getItems();
+    expect(items).toHaveLength(4);
+    // Reduce data items
+    await componentLocator.evaluate((node: HTMLElement & { data: any[] }) => {
+      node.data = [
+        { displayName: 'Item1', value: '1', label: 'data item 1' },
+        { displayName: 'Item2', value: '2', label: 'data item 2' },
+      ];
+    });
+    items = await component.getItems();
+    expect(items).toHaveLength(2);
+    // Clear data items
+    await componentLocator.evaluate((node: HTMLElement & { data: any[] }) => {
+      node.data = [];
+    });
+    items = await component.getItems();
+    expect(items).toHaveLength(0);
+  });
+
+  test('allow custom value with no items', async ({ page }) => {
+    await page.goto(
+      getStoryUrl(storyName, {
+        itemsSource: 'prop',
+        'allow-custom-value': true,
+      }),
+    );
+    const componentLocator = page.locator(componentName);
+    const component = createComboBoxTestDriver(componentLocator);
+    // Clear data items
+    await componentLocator.evaluate((node: HTMLElement & { data: any[] }) => {
+      node.data = [];
+    });
+    await component.setValue('new value');
+    expect(await component.getValue()).toBe('new value');
+    expect(await component.screenshot()).toMatchSnapshot();
+  });
+});
+
+test.describe('override renderer', () => {
+  test('custom background', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { overrideRenderer: true }));
+    const component = createComboBoxTestDriver(page.locator(componentName));
+    await component.openDropdown();
+    expect(await component.dropDown.screenshot()).toMatchSnapshot();
+  });
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@descope-ui/descope-combo-box",
+  "version": "0.0.1",
+  "exports": {
+    ".": {
+      "import": "./src/component/index.js"
+    },
+    "./theme": {
+      "import": "./src/theme.js"
+    },
+    "./class": {
+      "import": "./src/component/ComboBoxClass.js"
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "1.38.1",
+    "e2e-utils": "0.0.1",
+    "test-drivers": "0.0.1"
+  },
+  "dependencies": {
+    "@vaadin/combo-box": "24.3.4",
+    "@descope-ui/common": "0.0.1",
+    "@descope-ui/theme-globals": "0.0.1",
+    "theme-input-wrapper": "0.0.1"
+  },
+  "publishConfig": {
+    "link-workspace-packages": false
+  },
+  "scripts": {
+    "test": "echo 'No tests defined' && exit 0",
+    "test:e2e": "echo 'No e2e tests defined' && exit 0"
+  }
+}

package/project.json

@@ -0,0 +1,7 @@
+{
+  "name": "@descope-ui/descope-combo-box",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/web-components/components/descope-combo-box/src",
+  "projectType": "library",
+  "tags": []
+}

package/src/component/ComboBoxClass.js

@@ -0,0 +1,619 @@
+import { compose } from '@descope-ui/common/utils';
+import {
+  getComponentName,
+  observeAttributes,
+  observeChildren,
+} from '@descope-ui/common/components-helpers';
+import {
+  resetInputLabelPosition,
+  resetInputCursor,
+  resetInputPlaceholder,
+  resetInputReadonlyStyle,
+  useHostExternalPadding,
+  inputFloatingLabelStyle,
+} from '@descope-ui/common/theme-helpers';
+import {
+  createStyleMixin,
+  draggableMixin,
+  createProxy,
+  componentNameValidationMixin,
+  portalMixin,
+  proxyInputMixin,
+} from '@descope-ui/common/components-mixins';
+
+export const componentName = getComponentName('combo-box');
+
+const ComboBoxMixin = (superclass) =>
+  class ComboBoxMixinClass extends superclass {
+    static get observedAttributes() {
+      return ['label-type'];
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    #renderItem = ({ displayName, value, label }) => {
+      return `<span data-name="${label}" data-id="${value}">${
+        displayName || label
+      }</span>`;
+    };
+
+    #data;
+
+    get defaultValue() {
+      return this.getAttribute('default-value');
+    }
+
+    get renderItem() {
+      return this.#renderItem;
+    }
+
+    set renderItem(renderFn) {
+      this.#renderItem = renderFn;
+      this.renderItems();
+    }
+
+    set renderer(fn) {
+      // fn takes (root, comboBox, model) as arguments
+      this.baseElement.renderer = fn;
+    }
+
+    get loading() {
+      return this.getAttribute('loading') === 'true';
+    }
+
+    set loading(val) {
+      if (val) {
+        this.setAttribute('loading', 'true');
+      } else {
+        this.removeAttribute('loading');
+      }
+    }
+
+    get data() {
+      if (this.#data) return this.#data;
+
+      const dataAttr = this.getAttribute('data');
+
+      if (dataAttr) {
+        try {
+          const data = JSON.parse(dataAttr);
+          if (this.isValidDataType(data)) {
+            return data;
+          }
+        } catch (e) {
+          // eslint-disable-next-line no-console
+          console.error(
+            'could not parse data string from attribute "data" -',
+            e.message,
+          );
+        }
+      }
+
+      return [];
+    }
+
+    set data(data) {
+      if (this.isValidDataType(data)) {
+        this.#data = data;
+        this.renderItems();
+      }
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    isValidDataType(data) {
+      const isValid = Array.isArray(data);
+      if (!isValid) {
+        // eslint-disable-next-line no-console
+        console.error('data must be an array, received:', data);
+      }
+
+      return isValid;
+    }
+
+    getItemsTemplate() {
+      return this.data?.reduce?.(
+        (acc, item) => acc + (this.renderItem?.(item || {}) || ''),
+        '',
+      );
+    }
+
+    renderItems() {
+      if (this.#data || this.getAttribute('data')) {
+        const template = this.getItemsTemplate();
+        this.innerHTML = template;
+      }
+    }
+
+    handleSelectedItem() {
+      const { selectedItem } = this.baseElement;
+      const currentSelected = selectedItem?.['data-id'];
+
+      // If the selected item is still a child, there's no need to update the value
+      if (selectedItem && Array.from(this.children).includes(selectedItem)) {
+        return;
+      }
+
+      // if previously selected item ID exists in current children, set it as selected
+      if (currentSelected) {
+        this.value = currentSelected;
+      }
+
+      // otherwise, if default value is specified, set default value as selected item
+      if (!this.value) {
+        this.setDefaultValue();
+      }
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    customValueTransformFn(val) {
+      return val;
+    }
+
+    // We want to override Vaadin's Combo Box value setter. This is needed since Vaadin couples between the
+    // field that it searches the value, and the finaly display value of the input.
+    // We provide a custom transform function to override that behavior.
+    setComboBoxDescriptor() {
+      const valueDescriptor = Object.getOwnPropertyDescriptor(
+        this.inputElement.constructor.prototype,
+        'value',
+      );
+
+      const comboBox = this;
+
+      Object.defineProperties(this.inputElement, {
+        value: {
+          ...valueDescriptor,
+          set(val) {
+            if (
+              !comboBox.baseElement.items?.length &&
+              !comboBox.allowCustomValue
+            ) {
+              return;
+            }
+
+            const transformedValue = comboBox.customValueTransformFn(val) || '';
+
+            if (transformedValue === this.value) {
+              return;
+            }
+
+            valueDescriptor.set.call(this, transformedValue);
+          },
+        },
+      });
+    }
+
+    // vaadin api is to set props on their combo box node,
+    // in order to avoid it, we are passing the children of this component
+    // to the items & renderer props, so it will be used as the combo box items
+    #onChildrenChange() {
+      const items = Array.from(this.children);
+
+      // we want the data-name attribute to be accessible as an object attribute
+      items.forEach((node) => {
+        Object.defineProperty(node, 'data-name', {
+          value: node.getAttribute('data-name'),
+          configurable: true,
+          writable: true,
+        });
+        Object.defineProperty(node, 'data-id', {
+          value: node.getAttribute('data-id'),
+          configurable: true,
+          writable: true,
+        });
+      });
+
+      this.baseElement.items = items;
+      setTimeout(() => {
+        // set timeout to ensure this runs after customValueTransformFn had the chance to be overriden
+        this.handleSelectedItem();
+      }, 0);
+    }
+
+    // the default vaadin behavior is to attach the overlay to the body when opened
+    // we do not want that because it's difficult to style the overlay in this way
+    // so we override it to open inside the shadow DOM
+    #overrideOverlaySettings() {
+      const overlay = this.baseElement.shadowRoot.querySelector(
+        'vaadin-combo-box-overlay',
+      );
+      overlay._attachOverlay = () => {
+        overlay.bringToFront();
+      };
+      overlay._detachOverlay = () => {};
+      overlay._enterModalState = () => {};
+    }
+
+    #overrideRenderer() {
+      // use vaadin combobox custom renderer to render options as HTML
+      // and not via default renderer, which renders only the data-name's value
+      // in its own HTML template
+      this.baseElement.renderer = (root, combo, model) => {
+        // eslint-disable-next-line no-param-reassign
+        root.innerHTML = model.item.outerHTML;
+      };
+    }
+
+    init() {
+      super.init?.();
+
+      // eslint-disable-next-line func-names
+      this.getValidity = function () {
+        if (!this.value && this.isRequired) {
+          return {
+            valueMissing: true,
+          };
+        }
+        return {};
+      };
+
+      this.setComboBoxDescriptor();
+      this.#overrideOverlaySettings();
+      this.#overrideRenderer();
+
+      // Set up observers - order matters here since renderItems can clear innerHTML
+      observeAttributes(this, this.renderItems.bind(this), {
+        includeAttrs: ['data'],
+      });
+      observeChildren(this, this.#onChildrenChange.bind(this));
+
+      this.setDefaultValue();
+
+      this.baseElement.addEventListener('selected-item-changed', () => {
+        this.dispatchEvent(
+          new Event('input', { bubbles: true, composed: true }),
+        );
+      });
+    }
+
+    onLabelClick() {
+      if (this.isReadOnly || this.isDisabled) {
+        return;
+      }
+      this.focus();
+      this.setAttribute('opened', 'true');
+    }
+
+    attributeChangedCallback(attrName, oldValue, newValue) {
+      super.attributeChangedCallback?.(attrName, oldValue, newValue);
+
+      if (oldValue !== newValue) {
+        if (attrName === 'label-type') {
+          if (newValue === 'floating') {
+            this.addEventListener('click', this.onLabelClick);
+          } else {
+            this.removeEventListener('click', this.onLabelClick);
+          }
+        }
+      }
+    }
+
+    setDefaultValue() {
+      if (this.defaultValue) {
+        this.value = this.defaultValue;
+      }
+    }
+
+    #getChildToSelect(val) {
+      return this.baseElement.items?.find((item) => item['data-id'] === val);
+    }
+
+    #preventSelectedItemChangeEventIfNeeded(val, selectedChild) {
+      // If the actual value didn't change, but the selected item did (the element changed),
+      // we want to stop the event propagation since it's not a real change
+      const shouldPreventItemChangeEvent =
+        val === this.value && selectedChild !== this.baseElement.selectedItem;
+      if (shouldPreventItemChangeEvent) {
+        this.baseElement.addEventListener(
+          'selected-item-changed',
+          (e) => {
+            e.stopImmediatePropagation();
+          },
+          { once: true, capture: true },
+        );
+      }
+    }
+
+    set value(val) {
+      const selectedChild = this.#getChildToSelect(val);
+      this.#preventSelectedItemChangeEventIfNeeded(val, selectedChild);
+      if (val && selectedChild) {
+        this.baseElement.selectedItem = selectedChild;
+      } else if (!selectedChild && this.allowCustomValue) {
+        this.baseElement.value = val;
+      } else {
+        this.baseElement.selectedItem = undefined;
+      }
+    }
+
+    get value() {
+      return this.baseElement.selectedItem?.['data-id'] || this.allowCustomValue
+        ? this.baseElement.__data.value || ''
+        : '';
+    }
+
+    get allowCustomValue() {
+      return this.getAttribute('allow-custom-value') === 'true';
+    }
+  };
+
+const {
+  host,
+  inputField,
+  inputElement,
+  placeholder,
+  toggle,
+  clearButton,
+  label,
+  requiredIndicator,
+  helperText,
+  errorMessage,
+} = {
+  host: { selector: () => ':host' },
+  inputField: { selector: '::part(input-field)' },
+  inputElement: { selector: 'input' },
+  placeholder: { selector: '> input:placeholder-shown' },
+  toggle: { selector: '::part(toggle-button)' },
+  clearButton: { selector: '::part(clear-button)' },
+  label: { selector: '::part(label)' },
+  requiredIndicator: {
+    selector: '[required]::part(required-indicator)::after',
+  },
+  helperText: { selector: '::part(helper-text)' },
+  errorMessage: { selector: '::part(error-message)' },
+};
+
+export const ComboBoxClass = compose(
+  createStyleMixin({
+    mappings: {
+      hostWidth: { ...host, property: 'width' },
+      hostDirection: { ...host, property: 'direction' },
+      // we apply font-size also on the host so we can set its width with em
+      fontSize: [{}, host],
+      fontFamily: [label, placeholder, inputField, helperText, errorMessage],
+      labelFontSize: { ...label, property: 'font-size' },
+      labelFontWeight: { ...label, property: 'font-weight' },
+      labelTextColor: [
+        { ...label, property: 'color' },
+        { ...requiredIndicator, property: 'color' },
+      ],
+      errorMessageTextColor: { ...errorMessage, property: 'color' },
+      errorMessageIcon: { ...errorMessage, property: 'background-image' },
+      errorMessageIconSize: { ...errorMessage, property: 'background-size' },
+      errorMessageIconPadding: {
+        ...errorMessage,
+        property: 'padding-inline-start',
+      },
+      errorMessageIconRepeat: {
+        ...errorMessage,
+        property: 'background-repeat',
+      },
+      errorMessageIconPosition: {
+        ...errorMessage,
+        property: 'background-position',
+      },
+      inputHeight: { ...inputField, property: 'height' },
+      inputBackgroundColor: { ...inputField, property: 'background-color' },
+      inputBorderColor: { ...inputField, property: 'border-color' },
+      inputBorderWidth: { ...inputField, property: 'border-width' },
+      inputBorderStyle: { ...inputField, property: 'border-style' },
+      inputBorderRadius: { ...inputField, property: 'border-radius' },
+      labelRequiredIndicator: { ...requiredIndicator, property: 'content' },
+      inputValueTextColor: { ...inputField, property: 'color' },
+      inputPlaceholderTextColor: { ...placeholder, property: 'color' },
+      inputDropdownButtonCursor: [
+        { ...toggle, property: 'cursor' },
+        { ...clearButton, property: 'cursor' },
+      ],
+      inputDropdownButtonColor: [
+        { ...toggle, property: 'color' },
+        { ...clearButton, property: 'color' },
+      ],
+      inputDropdownButtonSize: [
+        { ...toggle, property: 'font-size' },
+        { ...clearButton, property: 'font-size' },
+      ],
+      inputDropdownButtonOffset: [
+        { ...toggle, property: 'margin-right' },
+        { ...toggle, property: 'margin-left' },
+      ],
+      inputOutlineColor: { ...inputField, property: 'outline-color' },
+      inputOutlineWidth: { ...inputField, property: 'outline-width' },
+      inputOutlineStyle: { ...inputField, property: 'outline-style' },
+      inputOutlineOffset: { ...inputField, property: 'outline-offset' },
+      inputHorizontalPadding: [
+        { ...inputElement, property: 'padding-left' },
+        { ...inputElement, property: 'padding-right' },
+      ],
+
+      labelPosition: { ...label, property: 'position' },
+      labelTopPosition: { ...label, property: 'top' },
+      labelHorizontalPosition: [
+        { ...label, property: 'left' },
+        { ...label, property: 'right' },
+      ],
+      inputTransformY: { ...label, property: 'transform' },
+      inputTransition: { ...label, property: 'transition' },
+      marginInlineStart: { ...label, property: 'margin-inline-start' },
+      placeholderOpacity: { ...placeholder, property: 'opacity' },
+      inputVerticalAlignment: { ...inputField, property: 'align-items' },
+      valueInputHeight: { ...inputElement, property: 'height' },
+      valueInputMarginBottom: { ...inputElement, property: 'margin-bottom' },
+
+      // we need to use the variables from the portal mixin
+      // so we need to use an arrow function on the selector
+      // for that to work, because ComboBox is not available
+      // at this time.
+      overlayBackground: {
+        property: () => ComboBoxClass.cssVarList.overlay.backgroundColor,
+      },
+      overlayTextColor: {
+        property: () => ComboBoxClass.cssVarList.overlay.textColor,
+      },
+      overlayBorder: {
+        property: () => ComboBoxClass.cssVarList.overlay.border,
+      },
+      overlayFontSize: {
+        property: () => ComboBoxClass.cssVarList.overlay.fontSize,
+      },
+      overlayFontFamily: {
+        property: () => ComboBoxClass.cssVarList.overlay.fontFamily,
+      },
+      overlayCursor: {
+        property: () => ComboBoxClass.cssVarList.overlay.cursor,
+      },
+      overlayItemBoxShadow: {
+        property: () => ComboBoxClass.cssVarList.overlay.itemBoxShadow,
+      },
+      overlayItemPaddingInlineStart: {
+        property: () => ComboBoxClass.cssVarList.overlay.itemPaddingInlineStart,
+      },
+      overlayItemPaddingInlineEnd: {
+        property: () => ComboBoxClass.cssVarList.overlay.itemPaddingInlineEnd,
+      },
+    },
+  }),
+  draggableMixin,
+  portalMixin({
+    name: 'overlay',
+    selector: '',
+    mappings: {
+      backgroundColor: [
+        { selector: 'vaadin-combo-box-scroller' },
+        { selector: 'vaadin-combo-box-overlay::part(overlay)' },
+      ],
+      minHeight: { selector: 'vaadin-combo-box-overlay' },
+      margin: { selector: 'vaadin-combo-box-overlay' },
+      cursor: { selector: 'vaadin-combo-box-item' },
+      fontFamily: { selector: 'vaadin-combo-box-item' },
+      textColor: { selector: 'vaadin-combo-box-item', property: 'color' },
+      fontSize: { selector: 'vaadin-combo-box-item' },
+      itemBoxShadow: {
+        selector: 'vaadin-combo-box-item',
+        property: 'box-shadow',
+      },
+      itemPaddingInlineStart: {
+        selector: 'vaadin-combo-box-item',
+        property: 'padding-inline-start',
+      },
+      itemPaddingInlineEnd: {
+        selector: 'vaadin-combo-box-item',
+        property: 'padding-inline-end',
+      },
+
+      loaderTop: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'top',
+      },
+      loaderLeft: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'left',
+      },
+      loaderRight: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'right',
+      },
+      loaderMargin: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'margin',
+      },
+      loaderWidth: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'width',
+      },
+      loaderHeight: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'height',
+      },
+      loaderBorder: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'border',
+      },
+      loaderBorderColor: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'border-color',
+      },
+      loaderBorderRadius: {
+        selector: 'vaadin-combo-box-overlay::part(loader)',
+        property: 'border-radius',
+      },
+      contentHeight: {
+        selector: 'vaadin-combo-box-overlay::part(content)',
+        property: 'height',
+      },
+      contentOpacity: {
+        selector: 'vaadin-combo-box-overlay::part(content)',
+        property: 'opacity',
+      },
+    },
+    forward: {
+      include: false,
+      attributes: ['size'],
+    },
+  }),
+  proxyInputMixin({
+    proxyProps: ['selectionStart'],
+    inputEvent: 'selected-item-changed',
+  }),
+  componentNameValidationMixin,
+  ComboBoxMixin,
+)(
+  createProxy({
+    slots: ['', 'prefix'],
+    wrappedEleName: 'vaadin-combo-box',
+    style: () => `
+		:host {
+			display: inline-flex;
+			box-sizing: border-box;
+			-webkit-mask-image: none;
+		}
+		${useHostExternalPadding(ComboBoxClass.cssVarList)}
+		${resetInputReadonlyStyle('vaadin-combo-box')}
+		${resetInputPlaceholder('vaadin-combo-box')}
+		${resetInputCursor('vaadin-combo-box')}
+
+		vaadin-combo-box {
+			padding: 0;
+			width: 100%;
+		}
+		vaadin-combo-box::before {
+			height: initial;
+		}
+		vaadin-combo-box [slot="input"] {
+			-webkit-mask-image: none;
+			min-height: 0;
+			box-sizing: border-box;
+		}
+
+		vaadin-combo-box::part(input-field) {
+			padding: 0;
+			box-shadow: none;
+		}
+
+    vaadin-combo-box::part(toggle-button),
+    vaadin-combo-box::part(clear-button) {
+      align-self: center;
+    }
+
+    vaadin-combo-box[hide-toggle-button="true"]::part(toggle-button) {
+      display: none;
+    }
+
+    vaadin-combo-box[label-type="floating"]:not([focused])[readonly] > input:placeholder-shown {
+      opacity: 0;
+    }
+    vaadin-combo-box[label-type="floating"]:not([focused])[disabled] > input:placeholder-shown {
+      opacity: 0;
+    }
+
+    ${resetInputLabelPosition('vaadin-combo-box')}
+    ${inputFloatingLabelStyle()}
+		`,
+    // Note: we exclude `size` to avoid overriding Vaadin's ComboBox property
+    // with the same name. Including it will cause Vaadin to calculate NaN size,
+    // and reset items to an empty array, and opening the list box with no items
+    // to display.
+    excludeAttrsSync: ['tabindex', 'size', 'data', 'loading'],
+    componentName,
+    includeForwardProps: ['items', 'renderer', 'selectedItem'],
+  }),
+);

package/src/component/index.js

@@ -0,0 +1,6 @@
+import '@vaadin/combo-box';
+import { componentName, ComboBoxClass } from './ComboBoxClass';
+
+customElements.define(componentName, ComboBoxClass);
+
+export { ComboBoxClass };

package/src/theme.js

@@ -0,0 +1,93 @@
+import globals from '@descope-ui/theme-globals';
+import { ComboBoxClass } from './component/ComboBoxClass';
+import { getThemeRefs } from '@descope-ui/common/theme-helpers';
+import { refs } from 'theme-input-wrapper';
+
+const globalRefs = getThemeRefs(globals);
+const vars = ComboBoxClass.cssVarList;
+
+export const comboBox = {
+  [vars.hostWidth]: refs.width,
+  [vars.hostDirection]: refs.direction,
+  [vars.fontSize]: refs.fontSize,
+  [vars.fontFamily]: refs.fontFamily,
+  [vars.labelFontSize]: refs.labelFontSize,
+  [vars.labelFontWeight]: refs.labelFontWeight,
+  [vars.labelTextColor]: refs.labelTextColor,
+  [vars.errorMessageTextColor]: refs.errorMessageTextColor,
+  [vars.inputBorderColor]: refs.borderColor,
+  [vars.inputBorderWidth]: refs.borderWidth,
+  [vars.inputBorderStyle]: refs.borderStyle,
+  [vars.inputBorderRadius]: refs.borderRadius,
+  [vars.inputOutlineColor]: refs.outlineColor,
+  [vars.inputOutlineOffset]: refs.outlineOffset,
+  [vars.inputOutlineWidth]: refs.outlineWidth,
+  [vars.inputOutlineStyle]: refs.outlineStyle,
+  [vars.labelRequiredIndicator]: refs.requiredIndicator,
+  [vars.inputValueTextColor]: refs.valueTextColor,
+  [vars.inputPlaceholderTextColor]: refs.placeholderTextColor,
+  [vars.inputBackgroundColor]: refs.backgroundColor,
+  [vars.inputHorizontalPadding]: refs.horizontalPadding,
+  [vars.inputHeight]: refs.inputHeight,
+  [vars.inputDropdownButtonColor]: globalRefs.colors.surface.dark,
+  [vars.inputDropdownButtonCursor]: 'pointer',
+  [vars.inputDropdownButtonSize]: refs.toggleButtonSize,
+  [vars.inputDropdownButtonOffset]: globalRefs.spacing.xs,
+  [vars.overlayItemPaddingInlineStart]: globalRefs.spacing.xs,
+  [vars.overlayItemPaddingInlineEnd]: globalRefs.spacing.lg,
+  [vars.labelPosition]: refs.labelPosition,
+  [vars.labelTopPosition]: refs.labelTopPosition,
+  [vars.labelHorizontalPosition]: refs.labelHorizontalPosition,
+  [vars.inputTransformY]: refs.inputTransformY,
+  [vars.inputTransition]: refs.inputTransition,
+  [vars.marginInlineStart]: refs.marginInlineStart,
+  [vars.placeholderOpacity]: refs.placeholderOpacity,
+  [vars.inputVerticalAlignment]: refs.inputVerticalAlignment,
+  [vars.valueInputHeight]: refs.valueInputHeight,
+  [vars.valueInputMarginBottom]: refs.valueInputMarginBottom,
+
+  // error message icon
+  [vars.errorMessageIcon]: refs.errorMessageIcon,
+  [vars.errorMessageIconSize]: refs.errorMessageIconSize,
+  [vars.errorMessageIconPadding]: refs.errorMessageIconPadding,
+  [vars.errorMessageIconRepeat]: refs.errorMessageIconRepeat,
+  [vars.errorMessageIconPosition]: refs.errorMessageIconPosition,
+
+  _readonly: {
+    [vars.inputDropdownButtonCursor]: 'default',
+  },
+
+  // Overlay theme exposed via the component:
+  [vars.overlayFontSize]: refs.fontSize,
+  [vars.overlayFontFamily]: refs.fontFamily,
+  [vars.overlayCursor]: 'pointer',
+  [vars.overlayItemBoxShadow]: 'none',
+  [vars.overlayBackground]: refs.backgroundColor,
+  [vars.overlayTextColor]: refs.valueTextColor,
+
+  // Overlay direct theme:
+  [vars.overlay.minHeight]: '400px',
+  [vars.overlay.margin]: '0',
+
+  [vars.overlay.contentHeight]: '100%',
+  [vars.overlay.contentOpacity]: '1',
+  _loading: {
+    [vars.overlay.loaderTop]: '50%',
+    [vars.overlay.loaderLeft]: '50%',
+    [vars.overlay.loaderRight]: 'auto',
+    // Margin has to be negative to center the loader, "transform" can't be used because the animation uses it
+    // Margin has to be half of the width/height of the loader to center it
+    [vars.overlay.loaderMargin]: '-15px 0 0 -15px',
+    [vars.overlay.loaderWidth]: '30px',
+    [vars.overlay.loaderHeight]: '30px',
+    [vars.overlay.loaderBorder]: '2px solid transparent',
+    [vars.overlay
+      .loaderBorderColor]: `${globalRefs.colors.primary.highlight} ${globalRefs.colors.primary.highlight} ${globalRefs.colors.primary.main} ${globalRefs.colors.primary.main}`,
+    [vars.overlay.loaderBorderRadius]: '50%',
+    [vars.overlay.contentHeight]: '100px',
+    [vars.overlay.contentOpacity]: '0',
+  },
+};
+
+export default comboBox;
+export { vars };

package/stories/descope-combo-box.stories.js

@@ -0,0 +1,180 @@
+/* eslint no-param-reassign: 0 */
+
+import { componentName } from '../src/component/ComboBoxClass';
+import { withForm } from '@descope-ui/common/sb-helpers';
+import {
+  labelControl,
+  placeholderControl,
+  sizeControl,
+  fullWidthControl,
+  directionControl,
+  disabledControl,
+  readOnlyControl,
+  requiredControl,
+  borderedControl,
+  loadingControl,
+  errorMissingValueControl,
+  overrideRenderItemControl,
+  itemsSourceControl,
+  inputLabelTypeControl,
+  errorMessageIconControl,
+  errorMessageIconAttrs,
+} from '@descope-ui/common/sb-controls';
+
+const Template = ({
+  label,
+  placeholder,
+  size,
+  bordered,
+  'full-width': fullWidth,
+  readonly,
+  required,
+  direction,
+  disabled,
+  data,
+  overrideRenderItem,
+  itemsSource,
+  loading,
+  'default-value': defaultValue,
+  'data-errormessage-value-missing': customErrorMissingValue,
+  'label-type': labelType,
+  'hide-toggle-button': hideToggleButton,
+  'allow-custom-value': allowCustomValue,
+  overrideRenderer,
+  errorMsgIcon,
+}) => {
+  let serializedData;
+
+  try {
+    serializedData = JSON.stringify(data);
+  } catch (e) {
+    // do nothing
+  }
+
+  // this is another way to pass data to the component (prop instead of attr)
+  const dataFromPropScript = `
+  <script>
+    document.querySelector("descope-combo-box").data = ${serializedData.replace(
+      /\n/g,
+      '',
+    )}
+  </script>`;
+
+  // eslint-disable-next-line no-shadow
+  const altRenderItem = ({ displayName, label, value }) =>
+    `<span data-name="${displayName}" data-value="${value}">${label}</span>`;
+
+  // this allows us to update the render item function
+  const overrideRenderItemScript = `
+  <script>
+    document.querySelector("descope-combo-box").renderItem = ${altRenderItem
+      .toString()
+      .replace(/\n/g, '')}
+  </script>`;
+
+  const altRenderer = (root, combo, model) => {
+    if (model.index === 1) {
+      root.style.backgroundColor = '#008000';
+      root.style.color = '#ffffff';
+    }
+    root.innerHTML = model.item.outerHTML;
+  };
+
+  const overrideRendererScript = `
+  <script>
+    document.querySelector("descope-combo-box").renderer = ${altRenderer
+      .toString()
+      .replace(/\n/g, '')}
+  </script>`;
+
+  return withForm(`
+    <descope-combo-box
+      clear-button-visible
+      data='${(itemsSource === 'attr' && serializedData) || ''}'
+      size="${size}"
+      bordered="${bordered}"
+      item-label-path="data-name"
+      item-value-path="data-id"
+      label="${label || ''}"
+      placeholder="${placeholder || ''}"
+      default-value="${defaultValue || ''}"
+      required="${required || false}"
+      full-width="${fullWidth || false}"
+      readonly="${readonly || false}"
+      disabled="${disabled || false}"
+      loading="${loading || false}"
+      data-errormessage-value-missing="${customErrorMissingValue || ''}"
+      st-host-direction="${direction ?? ''}"
+      label-type="${labelType || ''}"
+      hide-toggle-button="${hideToggleButton || false}"
+      allow-custom-value="${allowCustomValue || false}"
+      ${errorMsgIcon ? errorMessageIconAttrs : ''}
+    >
+      <span data-name="ItemName1" data-id="itemId1">Trojan War Heroes' Valor</span>
+      <span data-name="ItemName2" data-id="itemId2">Achilles' Fateful Wrath</span>
+      <span data-name="ItemName3" data-id="itemId3">Epic Battle of Gods</span>
+      <span data-name="ItemName4" data-id="itemId4">Hector's Brave Sacrifice</span>
+      <span data-name="ItemName5" data-id="itemId5">Trojan Horse Deception</span>
+      <span data-name="ItemName6" data-id="itemId6">Agamemnon's Royal Command</span>
+      <span data-name="ItemName7" data-id="itemId7">Odysseus' Cunning Strategy</span>
+      <span data-name="ItemName8" data-id="itemId8">Helen's Beauty's Curse</span>
+      <span data-name="ItemName9" data-id="itemId9">Achilles' Heel Weakness</span>
+      <span data-name="ItemName10" data-id="itemId10">Epic Poem of Ancient</span>
+    </descope-combo-box>
+    ${itemsSource === 'prop' ? dataFromPropScript : ''}
+    ${overrideRenderItem ? overrideRenderItemScript : ''}
+    ${overrideRenderer ? overrideRendererScript : ''}
+  `);
+};
+
+export default {
+  component: componentName,
+  title: 'descope-combo-box',
+  argTypes: {
+    ...labelControl,
+    ...placeholderControl,
+    ...inputLabelTypeControl,
+    ...sizeControl,
+    ...fullWidthControl,
+    ...disabledControl,
+    ...readOnlyControl,
+    ...requiredControl,
+    ...borderedControl,
+    ...errorMissingValueControl,
+    ...overrideRenderItemControl,
+    ...itemsSourceControl,
+    ...directionControl,
+    ...loadingControl,
+    ...errorMessageIconControl,
+    'default-value': {
+      name: 'Default Value',
+      control: { type: 'text' },
+    },
+    'hide-toggle-button': {
+      name: 'Hide Toggle Button',
+      control: { type: 'boolean' },
+    },
+    'allow-custom-value': {
+      name: 'Allow Custom Value',
+      control: { type: 'boolean' },
+    },
+    overrideRenderer: {
+      name: 'Override the default renderer function',
+      control: { type: 'boolean' },
+    },
+  },
+};
+
+export const Default = Template.bind({});
+
+Default.args = {
+  size: 'md',
+  bordered: true,
+  loading: false,
+  data: [
+    { displayName: 'Item1', value: '1', label: 'data item 1' },
+    { displayName: 'Item2', value: 'itemId2', label: 'data item 2' },
+    { displayName: 'Item3', value: '3', label: 'data item 3' },
+    { displayName: 'Item4', value: '4', label: 'data item 4' },
+  ],
+};