@elastic/eui-test-helpers 1.1.0-snapshot.1783939453438

package/LICENSE.txt

@@ -0,0 +1,6 @@
+Source code in this repository is covered by (i) a dual license under the Server
+Side Public License, v 1 and the Elastic License 2.0 or (ii) an Apache License
+2.0 compatible license or (iii) solely under the Elastic License 2.0, in each
+case, as noted in the applicable header. The default throughout the repository
+is a dual license under the Server Side Public License, v 1 and the Elastic
+License 2.0, unless the header specifies another license.

package/README.md

@@ -0,0 +1,56 @@
+# EUI Test Helpers
+
+`@elastic/eui-test-helpers` is a library of test helpers to use when testing EUI components
+with [Cypress], [React Testing Library], or [Scout]. It provides assertion, find, and query helpers to make interacting
+with EUI components easy and reliable. Say goodbye to finding CSS selectors to query that _seem_ right.
+
+> [!NOTE]
+> This library is in early stages of development and is missing many useful utilities. Please contribute or
+> [open a feature request](https://github.com/elastic/eui/issues/new?template=feature_request.md) if you notice
+> anything missing!
+
+This library provides utilities to EUI components that are non-trivial to write tests for. Please use the built-in
+methods for testing simple, native-like components that are provided by your testing framework of choice.
+
+## Installation
+
+This library is versioned independently from `@elastic/eui`. Because the helpers target EUI's component DOM and `data-test-subj`s, pick a version compatible with the `@elastic/eui` version you're testing against.
+
+```shell
+yarn add --dev @elastic/eui-test-helpers
+```
+
+## Playwright Component Objects
+
+For Playwright/Scout consumers, this package ships **Component Objects** —
+semantic wrappers around a single Playwright `Locator` that encapsulate
+user-like interactions for a specific EUI component.
+
+```ts
+import { EuiComboBoxObject } from '@elastic/eui-test-helpers';
+
+const comboBox = new EuiComboBoxObject(page, 'dataViewSelector');
+await comboBox.setSelectedOptions(['logs-*']);
+expect(await comboBox.getSelectedOptions()).toEqual(['logs-*']);
+```
+
+Every Component Object constructor takes `(scope, testSubj)`:
+- `scope` — a Playwright `Page` or `Locator` to search within
+- `testSubj` — the `data-test-subj` value you set on the component's root element in your app
+
+`@playwright/test` is declared as a `peerDependency` — consumers provide
+their own version at runtime.
+
+### Available Component Objects
+
+| Component | Documentation |
+|---|---|
+| `EuiComboBoxObject` | [src/components/combo_box/README.md](src/components/combo_box/README.md) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for design principles, directory structure, and how to add new Component Objects.
+
+[Cypress]: https://github.com/cypress-io/cypress
+[React Testing Library]: https://github.com/testing-library/react-testing-library
+[Scout]: https://github.com/elastic/kibana/tree/main/src/platform/packages/shared/kbn-scout

package/lib/cjs/components/combo_box/selectors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * List of available stable selectors for
+ * {@link https://eui.elastic.co/docs/components/forms/selection/combo-box/|EuiComboBox}
+ */
+export declare const EuiComboBoxSelectors: {
+    /**
+     * `data-test-subj` identifier of the inner input wrapper element
+     */
+    INPUT_WRAPPER_TEST_SUBJ: string;
+    /**
+     * `data-test-subj` identifier of the search input field
+     */
+    SEARCH_INPUT_TEST_SUBJ: string;
+    /**
+     * `data-test-subj` identifier of the options list
+     */
+    OPTIONS_LIST_TEST_SUBJ: string;
+    /**
+     * `data-test-subj` identifier of the options list toggle button
+     */
+    OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ: string;
+    /**
+     * `data-test-subj` identifier of the clear button
+     */
+    CLEAR_BUTTON_TEST_SUBJ: string;
+    /**
+     * CSS selector for the input wrapper in `singleSelection={{ asPlainText: true }}` mode.
+     * Present when the combo renders the selection inside the input instead of as pills.
+     */
+    PLAIN_TEXT_INPUT_WRAP_SELECTOR: string;
+    /**
+     * `data-test-subj` identifier of selected option pills.
+     * Only present in non-`asPlainText` mode — in `asPlainText` mode the
+     * selection is shown inside the input, not as pills.
+     */
+    PILL_TEST_SUBJ: string;
+    /**
+     * CSS selector for all options in a specific combo box's dropdown.
+     *
+     * `testSubj` is the consumer's `data-test-subj` on `<EuiComboBox>`. EUI
+     * propagates this to the options list as `${testSubj}-optionsList`,
+     * letting us disambiguate when multiple combo boxes coexist on one page.
+     *
+     * To target a specific option by label, compose with Playwright's
+     * `getByTitle` to avoid CSS-injection issues with labels that contain
+     * special characters (`"`, `]`, `\`):
+     *
+     * ```ts
+     * page
+     *   .locator(EuiComboBoxSelectors.optionFor(testSubj))
+     *   .and(page.getByTitle(label, { exact: true }))
+     * ```
+     *
+     * Note: the list may be virtualized — type the search string into the
+     * input before asserting on a specific option to ensure it is in DOM.
+     */
+    optionFor: (testSubj: string) => string;
+    /**
+     * CSS selector for all selected options in a specific combo box's dropdown.
+     * See `optionFor` for `testSubj` rationale and label-targeting guidance.
+     */
+    selectedOptionFor: (testSubj: string) => string;
+    /**
+     * CSS selector for a specific combo box's options list container (the
+     * dropdown portal). Matches whether the list has regular options or an
+     * empty-state entry (e.g. "Add X as a custom option" for `onCreateOption`).
+     *
+     * Use this when you only need to wait for the dropdown to open, not when
+     * you need to target a specific option inside it.
+     */
+    optionsListFor: (testSubj: string) => string;
+};

package/lib/cjs/components/combo_box/selectors.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EuiComboBoxSelectors = void 0;
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+/**
+ * List of available stable selectors for
+ * {@link https://eui.elastic.co/docs/components/forms/selection/combo-box/|EuiComboBox}
+ */
+const EuiComboBoxSelectors = exports.EuiComboBoxSelectors = {
+  /**
+   * `data-test-subj` identifier of the inner input wrapper element
+   */
+  INPUT_WRAPPER_TEST_SUBJ: 'comboBoxInput',
+  /**
+   * `data-test-subj` identifier of the search input field
+   */
+  SEARCH_INPUT_TEST_SUBJ: 'comboBoxSearchInput',
+  /**
+   * `data-test-subj` identifier of the options list
+   */
+  OPTIONS_LIST_TEST_SUBJ: 'comboBoxOptionsList',
+  /**
+   * `data-test-subj` identifier of the options list toggle button
+   */
+  OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ: 'comboBoxToggleListButton',
+  /**
+   * `data-test-subj` identifier of the clear button
+   */
+  CLEAR_BUTTON_TEST_SUBJ: 'comboBoxClearButton',
+  /**
+   * CSS selector for the input wrapper in `singleSelection={{ asPlainText: true }}` mode.
+   * Present when the combo renders the selection inside the input instead of as pills.
+   */
+  PLAIN_TEXT_INPUT_WRAP_SELECTOR: '.euiComboBox__inputWrap--plainText',
+  /**
+   * `data-test-subj` identifier of selected option pills.
+   * Only present in non-`asPlainText` mode — in `asPlainText` mode the
+   * selection is shown inside the input, not as pills.
+   */
+  PILL_TEST_SUBJ: 'euiComboBoxPill',
+  /**
+   * CSS selector for all options in a specific combo box's dropdown.
+   *
+   * `testSubj` is the consumer's `data-test-subj` on `<EuiComboBox>`. EUI
+   * propagates this to the options list as `${testSubj}-optionsList`,
+   * letting us disambiguate when multiple combo boxes coexist on one page.
+   *
+   * To target a specific option by label, compose with Playwright's
+   * `getByTitle` to avoid CSS-injection issues with labels that contain
+   * special characters (`"`, `]`, `\`):
+   *
+   * ```ts
+   * page
+   *   .locator(EuiComboBoxSelectors.optionFor(testSubj))
+   *   .and(page.getByTitle(label, { exact: true }))
+   * ```
+   *
+   * Note: the list may be virtualized — type the search string into the
+   * input before asserting on a specific option to ensure it is in DOM.
+   */
+  optionFor: testSubj => `[data-test-subj~="${testSubj}-optionsList"] [role="option"]`,
+  /**
+   * CSS selector for all selected options in a specific combo box's dropdown.
+   * See `optionFor` for `testSubj` rationale and label-targeting guidance.
+   */
+  selectedOptionFor: testSubj => `[data-test-subj~="${testSubj}-optionsList"] [role="option"][aria-selected="true"]`,
+  /**
+   * CSS selector for a specific combo box's options list container (the
+   * dropdown portal). Matches whether the list has regular options or an
+   * empty-state entry (e.g. "Add X as a custom option" for `onCreateOption`).
+   *
+   * Use this when you only need to wait for the dropdown to open, not when
+   * you need to target a specific option inside it.
+   */
+  optionsListFor: testSubj => `[data-test-subj~="${testSubj}-optionsList"]`
+};

package/lib/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export { BaseObject, type ObjectScope } from './playwright/base_object';
+export { EuiComboBoxObject } from './playwright/components/combo_box/object';

package/lib/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "BaseObject", {
+  enumerable: true,
+  get: function () {
+    return _base_object.BaseObject;
+  }
+});
+Object.defineProperty(exports, "EuiComboBoxObject", {
+  enumerable: true,
+  get: function () {
+    return _object.EuiComboBoxObject;
+  }
+});
+var _base_object = require("./playwright/base_object");
+var _object = require("./playwright/components/combo_box/object");

package/lib/cjs/playwright/base_object.d.ts

@@ -0,0 +1,31 @@
+import type { Locator, Page } from '@playwright/test';
+export type ObjectScope = Page | Locator | BaseObject;
+/**
+ * Base class for Playwright Component Objects — semantic wrappers around a
+ * single root `Locator` resolved from a `data-test-subj` inside the given
+ * scope. Subclasses compose: pass another Component Object as `scope` to
+ * nest one inside the other's DOM subtree.
+ *
+ * Requires `testIdAttribute: 'data-test-subj'` in the Playwright config.
+ */
+export declare abstract class BaseObject {
+    /**
+     * Available to subclasses for queries outside `root`'s subtree but within
+     * the original scope (e.g. siblings, related controls).
+     */
+    protected readonly scope: Page | Locator;
+    protected readonly root: Locator;
+    /**
+     * Retained so subclasses can disambiguate portal-rendered content per
+     * instance — e.g. EUI propagates this as `${testSubj}-optionsList` to a
+     * combo box's options list, letting us scope queries to the right combo
+     * when several exist on a page.
+     */
+    protected readonly testSubj: string;
+    constructor(scope: ObjectScope, testSubj: string);
+    /**
+     * Underlying `Locator` — escape hatch for assertions or scoping the
+     * Component Object's API doesn't cover.
+     */
+    get locator(): Locator;
+}

package/lib/cjs/playwright/base_object.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BaseObject = void 0;
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+/**
+ * Base class for Playwright Component Objects — semantic wrappers around a
+ * single root `Locator` resolved from a `data-test-subj` inside the given
+ * scope. Subclasses compose: pass another Component Object as `scope` to
+ * nest one inside the other's DOM subtree.
+ *
+ * Requires `testIdAttribute: 'data-test-subj'` in the Playwright config.
+ */
+class BaseObject {
+  /**
+   * Available to subclasses for queries outside `root`'s subtree but within
+   * the original scope (e.g. siblings, related controls).
+   */
+
+  /**
+   * Retained so subclasses can disambiguate portal-rendered content per
+   * instance — e.g. EUI propagates this as `${testSubj}-optionsList` to a
+   * combo box's options list, letting us scope queries to the right combo
+   * when several exist on a page.
+   */
+
+  constructor(scope, testSubj) {
+    this.scope = scope instanceof BaseObject ? scope.locator : scope;
+    this.root = this.scope.getByTestId(testSubj);
+    this.testSubj = testSubj;
+  }
+
+  /**
+   * Underlying `Locator` — escape hatch for assertions or scoping the
+   * Component Object's API doesn't cover.
+   */
+  get locator() {
+    return this.root;
+  }
+}
+exports.BaseObject = BaseObject;

package/lib/cjs/playwright/components/combo_box/object.d.ts

@@ -0,0 +1,88 @@
+import { BaseObject } from '../../base_object';
+/**
+ * Playwright Component Object for {@link
+ * https://eui.elastic.co/docs/components/forms/selection/combo-box/ EuiComboBox}.
+ *
+ * `testSubj` must match the `data-test-subj` set by the consumer on the
+ * `<EuiComboBox>` element (the outer `.euiComboBox` wrapper, not the inner
+ * `comboBoxInput`).
+ */
+export declare class EuiComboBoxObject extends BaseObject {
+    /**
+     * Replace the current selection with `labels`. Set-semantics: order-
+     * independent — already-selected labels are kept, missing ones are added,
+     * extras are removed. No-op if the current selection already matches.
+     *
+     * Throws with a descriptive message if any label never appears in the
+     * dropdown (catches test/data drift early).
+     */
+    setSelectedOptions(labels: string[]): Promise<void>;
+    /**
+     * Clear all selected options. No-op if nothing is selected.
+     *
+     * Auto-detects the combo box configuration and uses the appropriate strategy:
+     * - Pills present → {@link clickPillClearButtons}
+     * - `asPlainText` with a confirmed input selection → {@link deleteSearchInput}
+     * - Otherwise → {@link deselectAllFromDropdown}
+     *
+     * Use the explicit methods directly when you need full control over the
+     * clearing strategy (e.g. `onCreateOption` with selections not in the
+     * options list).
+     */
+    clear(): Promise<void>;
+    /**
+     * Currently selected option labels.
+     *
+     * - Multi-select / `singleSelection=true` → pill texts.
+     * - `singleSelection={{ asPlainText: true }}` → the input value. EUI
+     *   renders no pills in this mode; the input IS the selection display.
+     *   Works correctly with both `isClearable=true` (default) and
+     *   `isClearable=false`.
+     * - Nothing selected → `[]`.
+     */
+    getSelectedOptions(): Promise<string[]>;
+    private hasPills;
+    /**
+     * Clicks the `×` button on each selected pill individually.
+     * Works regardless of `isClearable` — pill close buttons are always present.
+     * No-op if no pills are rendered.
+     */
+    private clickPillClearButtons;
+    /**
+     * Opens the dropdown and clicks each `aria-selected="true"` option to
+     * deselect it. Works for all `isClearable` and `singleSelection`
+     * configurations when the selected options are present in the options list.
+     *
+     * Does not work when the selection was created via `onCreateOption` and the
+     * created option was not added back to the `options` array — use
+     * {@link clickPillClearButtons} instead.
+     */
+    private deselectAllFromDropdown;
+    private addOption;
+    /**
+     * Focuses the search input and presses Backspace to clear the selection.
+     * Only valid in `singleSelection={{ asPlainText: true }}` mode where
+     * {@link hasConfirmedInputSelection} is true — EUI's `onKeyDown` handler
+     * fires `onRemoveOption` when Backspace is pressed with an empty `searchValue`.
+     */
+    private deleteSearchInput;
+    /**
+     * Returns true when the combo is in `asPlainText` mode and the input
+     * contains a *confirmed* selection (not unconfirmed typed text).
+     *
+     * In `asPlainText` mode the input IS the selection display: EUI renders
+     * the selected option's label directly in the input (no pills). An empty
+     * input means nothing is selected.
+     *
+     * When the user types text that matches no option and blurs (without
+     * `onCreateOption`), EUI marks the combo box invalid by adding
+     * `euiComboBox-isInvalid` to the root element. An invalid combo with a
+     * non-empty input has unconfirmed text, not a confirmed selection.
+     */
+    private hasConfirmedInputSelection;
+    private isMarkedInvalid;
+    private get input();
+    private get searchInput();
+    private get pills();
+    private isPlainText;
+}

package/lib/cjs/playwright/components/combo_box/object.js

@@ -0,0 +1,220 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EuiComboBoxObject = void 0;
+var _test = require("@playwright/test");
+var _base_object = require("../../base_object");
+var _selectors = require("../../../components/combo_box/selectors");
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+/**
+ * Playwright Component Object for {@link
+ * https://eui.elastic.co/docs/components/forms/selection/combo-box/ EuiComboBox}.
+ *
+ * `testSubj` must match the `data-test-subj` set by the consumer on the
+ * `<EuiComboBox>` element (the outer `.euiComboBox` wrapper, not the inner
+ * `comboBoxInput`).
+ */
+class EuiComboBoxObject extends _base_object.BaseObject {
+  /**
+   * Replace the current selection with `labels`. Set-semantics: order-
+   * independent — already-selected labels are kept, missing ones are added,
+   * extras are removed. No-op if the current selection already matches.
+   *
+   * Throws with a descriptive message if any label never appears in the
+   * dropdown (catches test/data drift early).
+   */
+  async setSelectedOptions(labels) {
+    // Dedupe while preserving order.
+    const targetLabels = [...new Set(labels)];
+    // `[...arr].sort()` (not `arr.sort()`) — sort mutates in place; the copy
+    // avoids mutating either the consumer's input or our internal state.
+    const sortedTarget = [...targetLabels].sort();
+    const sortedCurrent = [...(await this.getSelectedOptions())].sort();
+
+    // Set-equality short-circuit (any order).
+    if (sortedCurrent.length === sortedTarget.length && sortedCurrent.every((label, i) => label === sortedTarget[i])) {
+      return;
+    }
+
+    // Naive replace — clear, then add each. A diff-based approach would do
+    // less DOM work but require a per-pill remove primitive we don't ship yet.
+    await this.clear();
+    for (const label of targetLabels) {
+      await this.addOption(label);
+    }
+    if (targetLabels.length > 0) {
+      // Blur the input to close the dropdown. Using blur() rather than a
+      // keyboard event avoids bubbling Escape to page-level handlers
+      // (modal/flyout close listeners) on the consumer page.
+      await this.searchInput.blur();
+    }
+    (0, _test.expect)([...(await this.getSelectedOptions())].sort()).toEqual(sortedTarget);
+  }
+
+  /**
+   * Clear all selected options. No-op if nothing is selected.
+   *
+   * Auto-detects the combo box configuration and uses the appropriate strategy:
+   * - Pills present → {@link clickPillClearButtons}
+   * - `asPlainText` with a confirmed input selection → {@link deleteSearchInput}
+   * - Otherwise → {@link deselectAllFromDropdown}
+   *
+   * Use the explicit methods directly when you need full control over the
+   * clearing strategy (e.g. `onCreateOption` with selections not in the
+   * options list).
+   */
+  async clear() {
+    if ((await this.getSelectedOptions()).length === 0) {
+      return;
+    }
+    if (await this.hasPills()) {
+      await this.clickPillClearButtons();
+      return;
+    }
+    if (await this.hasConfirmedInputSelection()) {
+      await this.deleteSearchInput();
+      return;
+    }
+    await this.deselectAllFromDropdown();
+  }
+
+  /**
+   * Currently selected option labels.
+   *
+   * - Multi-select / `singleSelection=true` → pill texts.
+   * - `singleSelection={{ asPlainText: true }}` → the input value. EUI
+   *   renders no pills in this mode; the input IS the selection display.
+   *   Works correctly with both `isClearable=true` (default) and
+   *   `isClearable=false`.
+   * - Nothing selected → `[]`.
+   */
+  async getSelectedOptions() {
+    if (await this.hasPills()) {
+      return this.pills.allInnerTexts();
+    }
+    if (await this.hasConfirmedInputSelection()) {
+      return [await this.searchInput.inputValue()];
+    }
+    return [];
+  }
+  async hasPills() {
+    return (await this.pills.count()) > 0;
+  }
+
+  /**
+   * Clicks the `×` button on each selected pill individually.
+   * Works regardless of `isClearable` — pill close buttons are always present.
+   * No-op if no pills are rendered.
+   */
+  async clickPillClearButtons() {
+    while (await this.hasPills()) {
+      const countBefore = await this.pills.count();
+      await this.pills.first().locator('button').click();
+      await (0, _test.expect)(this.pills).not.toHaveCount(countBefore);
+    }
+  }
+
+  /**
+   * Opens the dropdown and clicks each `aria-selected="true"` option to
+   * deselect it. Works for all `isClearable` and `singleSelection`
+   * configurations when the selected options are present in the options list.
+   *
+   * Does not work when the selection was created via `onCreateOption` and the
+   * created option was not added back to the `options` array — use
+   * {@link clickPillClearButtons} instead.
+   */
+  async deselectAllFromDropdown() {
+    await this.input.click();
+    const selected = this.root.page().locator(_selectors.EuiComboBoxSelectors.selectedOptionFor(this.testSubj));
+    while ((await selected.count()) > 0) {
+      const countBefore = await selected.count();
+      await selected.first().click();
+      await (0, _test.expect)(selected).not.toHaveCount(countBefore);
+    }
+    await this.searchInput.blur();
+  }
+  async addOption(label) {
+    // Clicking the outer wrapper does not reliably open the dropdown; the
+    // inner `comboBoxInput` element does.
+    await this.input.click();
+
+    // Don't type to filter: EUI only sets an option's `title` while the input
+    // is empty, and the getByTitle match below relies on it. setSelectedOptions
+    // clears the selection first, so the list is unfiltered and every option
+    // renders its title.
+    //
+    // Options list is rendered in a portal outside `this.root`, so locate
+    // from page level. Use .and(getByTitle) rather than embedding the label
+    // in the CSS string — CSS attribute selectors break on labels containing
+    // quotes, brackets, or backslashes. getByTitle alone would search
+    // descendants; .and() intersects so it matches the option element itself.
+    const option = this.root.page().locator(_selectors.EuiComboBoxSelectors.optionFor(this.testSubj)).and(this.root.page().getByTitle(label, {
+      exact: true
+    }));
+    await option.waitFor({
+      state: 'visible'
+    });
+    await option.click();
+  }
+
+  /**
+   * Focuses the search input and presses Backspace to clear the selection.
+   * Only valid in `singleSelection={{ asPlainText: true }}` mode where
+   * {@link hasConfirmedInputSelection} is true — EUI's `onKeyDown` handler
+   * fires `onRemoveOption` when Backspace is pressed with an empty `searchValue`.
+   */
+  async deleteSearchInput() {
+    await this.searchInput.press('Backspace');
+    // Backspace triggers onRemoveOption (removes the selection) but the
+    // browser also fires a native input event that sets searchValue to a
+    // partial label string. fill('') cleans that up without restoring the
+    // selection (selectedOptions is already empty at this point).
+    await this.searchInput.fill('');
+    await (0, _test.expect)(this.searchInput).toHaveValue('');
+  }
+
+  /**
+   * Returns true when the combo is in `asPlainText` mode and the input
+   * contains a *confirmed* selection (not unconfirmed typed text).
+   *
+   * In `asPlainText` mode the input IS the selection display: EUI renders
+   * the selected option's label directly in the input (no pills). An empty
+   * input means nothing is selected.
+   *
+   * When the user types text that matches no option and blurs (without
+   * `onCreateOption`), EUI marks the combo box invalid by adding
+   * `euiComboBox-isInvalid` to the root element. An invalid combo with a
+   * non-empty input has unconfirmed text, not a confirmed selection.
+   */
+  async hasConfirmedInputSelection() {
+    if (!(await this.isPlainText())) return false;
+    if (!(await this.searchInput.inputValue())) return false;
+    return !(await this.isMarkedInvalid());
+  }
+  async isMarkedInvalid() {
+    const classes = await this.root.getAttribute('class');
+    return classes?.includes('euiComboBox-isInvalid') ?? false;
+  }
+  get input() {
+    return this.root.getByTestId(_selectors.EuiComboBoxSelectors.INPUT_WRAPPER_TEST_SUBJ);
+  }
+  get searchInput() {
+    return this.root.getByTestId(_selectors.EuiComboBoxSelectors.SEARCH_INPUT_TEST_SUBJ);
+  }
+  get pills() {
+    return this.root.getByTestId(_selectors.EuiComboBoxSelectors.PILL_TEST_SUBJ);
+  }
+  async isPlainText() {
+    return (await this.root.locator(_selectors.EuiComboBoxSelectors.PLAIN_TEXT_INPUT_WRAP_SELECTOR).count()) > 0;
+  }
+}
+exports.EuiComboBoxObject = EuiComboBoxObject;

package/lib/cjs/selectors.d.ts

@@ -0,0 +1 @@
+export { EuiComboBoxSelectors } from './components/combo_box/selectors';

package/lib/cjs/selectors.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "EuiComboBoxSelectors", {
+  enumerable: true,
+  get: function () {
+    return _selectors.EuiComboBoxSelectors;
+  }
+});
+var _selectors = require("./components/combo_box/selectors");

package/lib/cjs/storybook.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns the Storybook iframe URL for a given story ID and optional args.
+ *
+ * @param id - The Storybook story ID (e.g. `'forms-euicombobox--playground'`)
+ * @param args - Optional semicolon-separated Storybook args string (e.g. `'data-test-subj:myCombo;singleSelection:true'`)
+ */
+export declare const storyUrl: (id: string, args?: string) => string;