@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.21

package/dist/packages/combobox/combobox.d.ts

@@ -1,4 +1,4 @@
-import { LitElement, PropertyValues } from 'lit';
+import { LitElement, PropertyValues } from "lit";
 export interface ComboboxOption {
     value: string;
     label?: string;
@@ -12,79 +12,94 @@ declare const WarpCombobox_base: import("@open-wc/form-control").Constructor<imp
  */
 export declare class WarpCombobox extends WarpCombobox_base {
     #private;
-    /** The available options to select from
-     * @summary
-     * @description
+    /**
+     * The available options to select from.
+     *
+     * Use this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.
      */
     options: ComboboxOption[];
-    /** Label above input
-     * @summary
-     * @description
+    /**
+     * The label displayed above the input.
+     *
+     * Use this to give the combobox a visible and accessible name.
      */
     label?: string;
-    /** Input placeholder
-     * @summary
-     * @description
+    /**
+     * Placeholder text displayed when the input is empty.
+     *
+     * Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
      */
     placeholder?: string;
-    /** The input value
-     * @summary
-     * @description
+    /**
+     * The selected or typed value.
+     *
+     * When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
      */
     value: string;
-    /** Whether the popover opens when focus is on the text field
-     * @summary
-     * @description
+    /**
+     * Whether the option list opens when the input receives focus.
+     *
+     * Use this when users should see available options before they start typing.
      */
     openOnFocus: boolean;
-    /** Select active option on blur
-     * @summary
-     * @description
+    /**
+     * Whether the active option is selected when the input loses focus.
+     *
+     * When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.
      */
     selectOnBlur: boolean;
-    /** Whether the matching text segments in the options should be highlighted
-     * @summary
-     * @description
+    /**
+     * Whether matching text segments in options are highlighted.
+     *
+     * Use this to visually emphasize the part of each option that matches the current input value.
      */
     matchTextSegments: boolean;
-    /** Disable client-side static filtering
-     * @summary
-     * @description
+    /**
+     * Whether built-in client-side filtering is disabled.
+     *
+     * Use this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.
      */
     disableStaticFiltering: boolean;
-    /** Renders the input field in an invalid state
-     * @summary
-     * @description
+    /**
+     * Whether the combobox is visually invalid.
+     *
+     * Use this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.
      */
     invalid: boolean;
-    /** The content to display as the help text
-     * @summary
-     * @description
+    /**
+     * Help text displayed below the input.
+     *
+     * Use this for supporting guidance or validation feedback.
      */
     helpText?: string;
-    /** Whether the element is disabled
-     * @summary
-     * @description
+    /**
+     * Whether the combobox is disabled.
+     *
+     * Disabled comboboxes cannot be focused, changed, or submitted with form data.
      */
     disabled: boolean;
-    /** Whether the element is required
-     * @summary
-     * @description
+    /**
+     * Whether the combobox is required before form submission.
+     *
+     * Use this when the user must provide a value before submitting the form.
      */
     required: boolean;
-    /** Whether to show optional text
-     * @summary
-     * @description
+    /**
+     * Whether to show optional text next to the label.
+     *
+     * Use this to indicate that the combobox is not required.
      */
     optional: boolean;
-    /** Name attribute for form submission
-     * @summary
-     * @description
+    /**
+     * The name submitted with the combobox value.
+     *
+     * Use this when the combobox belongs to a form and its value should be included in form data.
      */
     name?: string;
-    /** Autocomplete attribute for the input field
-     * @summary
-     * @description
+    /**
+     * The autocomplete attribute passed to the internal input.
+     *
+     * Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
      */
     autocomplete?: string;
     /** @internal Options list open boolean */
@@ -93,18 +108,23 @@ export declare class WarpCombobox extends WarpCombobox_base {
     private _navigationOption;
     /** @internal Available options based on user's input value */
     private _currentOptions;
+    /** @internal Options parsed from light-DOM <option> children */
+    private _lightDomOptions;
     /** @internal Unique identifier counter for options */
     private _optionIdCounter;
     /** @internal The text displayed in the input field (may differ from value when option has label) */
     private _displayValue;
     static styles: import("lit").CSSResult[];
     constructor();
-    firstUpdated(changedProps: Map<string, unknown>): void;
+    firstUpdated(): void;
     updated(changedProperties: Map<string, unknown>): void;
     resetFormControl(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     private get _listboxId();
     private get _id();
     private get _helpId();
+    private get _sourceOptions();
     /** Get the display text for the navigation option or current display value */
     private get _navigationLabelOrDisplayValue();
     /** Get the actual value for the navigation option or current value */

package/dist/packages/combobox/combobox.hydration.test.d.ts

@@ -1 +1 @@
-import './combobox.js';
+import "./combobox.js";

package/dist/packages/combobox/combobox.hydration.test.js

@@ -1,70 +1,70 @@
-import { describe, expect, test, beforeEach, afterEach } from 'vitest';
-import React from 'react';
-import { hydrateRoot } from 'react-dom/client';
-import { setupHydrationWarningCapture, testHydration } from '../../tests/react-hydration';
-import './combobox.js';
-describe('w-combobox React SSR hydration', () => {
+import React from "react";
+import { hydrateRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { setupHydrationWarningCapture, testHydration, } from "../../tests/react-hydration";
+import "./combobox.js";
+describe("w-combobox React SSR hydration", () => {
     beforeEach(() => setupHydrationWarningCapture());
     afterEach(() => {
         window.__HYDRATION_WARNINGS__ = [];
     });
-    test('default (no attributes) hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {});
+    test("default (no attributes) hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {});
         expect(warnings).toEqual([]);
     });
-    test('with label hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {
-            label: 'Search',
+    test("with label hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {
+            label: "Search",
         });
         expect(warnings).toEqual([]);
     });
-    test('with placeholder hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {
-            placeholder: 'Type to search...',
+    test("with placeholder hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {
+            placeholder: "Type to search...",
         });
         expect(warnings).toEqual([]);
     });
-    test('with value hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {
-            value: 'test',
+    test("with value hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {
+            value: "test",
         });
         expect(warnings).toEqual([]);
     });
-    test('disabled combobox hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {
+    test("disabled combobox hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {
             disabled: true,
         });
         expect(warnings).toEqual([]);
     });
-    test('invalid combobox hydrates without warnings', async () => {
-        const warnings = await testHydration('w-combobox', {
+    test("invalid combobox hydrates without warnings", async () => {
+        const warnings = await testHydration("w-combobox", {
             invalid: true,
         });
         expect(warnings).toEqual([]);
     });
-    test('options array prop hydrates without runtime errors', async () => {
+    test("options array prop hydrates without runtime errors", async () => {
         const unhandledRejections = [];
         const onUnhandledRejection = (event) => {
             unhandledRejections.push(String(event.reason));
             event.preventDefault();
         };
-        window.addEventListener('unhandledrejection', onUnhandledRejection);
+        window.addEventListener("unhandledrejection", onUnhandledRejection);
         try {
-            await testHydration('w-combobox', {
+            await testHydration("w-combobox", {
                 options: [
-                    { value: 'apple', label: 'Apple' },
-                    { value: 'banana', label: 'Banana' },
+                    { value: "apple", label: "Apple" },
+                    { value: "banana", label: "Banana" },
                 ],
             });
             expect(unhandledRejections).toEqual([]);
         }
         finally {
-            window.removeEventListener('unhandledrejection', onUnhandledRejection);
+            window.removeEventListener("unhandledrejection", onUnhandledRejection);
         }
     });
-    test('dangerouslySetInnerHTML wrapper hydrates without attribute mismatch warnings', async () => {
-        const container = document.createElement('div');
-        container.id = 'hydration-innerhtml-root';
+    test("dangerouslySetInnerHTML wrapper hydrates without attribute mismatch warnings", async () => {
+        const container = document.createElement("div");
+        container.id = "hydration-innerhtml-root";
         document.body.appendChild(container);
         const innerHtml = '<w-combobox id="demo-combobox" placeholder="Search"></w-combobox>';
         try {
@@ -73,8 +73,8 @@ describe('w-combobox React SSR hydration', () => {
             // before React hydrates the tree.
             await new Promise((resolve) => setTimeout(resolve, 50));
             function App() {
-                return React.createElement('section', {
-                    className: 'example',
+                return React.createElement("section", {
+                    className: "example",
                     // biome-ignore lint/security/noDangerouslySetInnerHtml: test reproduces React hydration mismatch path
                     dangerouslySetInnerHTML: { __html: innerHtml },
                 });
@@ -82,9 +82,47 @@ describe('w-combobox React SSR hydration', () => {
             hydrateRoot(container, React.createElement(App), {
                 onRecoverableError: (error) => {
                     const msg = error instanceof Error ? error.message : String(error);
-                    if (msg.includes('Hydration') ||
-                        msg.includes('hydrat') ||
-                        msg.includes('did not match') ||
+                    if (msg.includes("Hydration") ||
+                        msg.includes("hydrat") ||
+                        msg.includes("did not match") ||
+                        msg.includes("didn't match")) {
+                        window.__HYDRATION_WARNINGS__.push(msg);
+                    }
+                },
+            });
+            await new Promise((resolve) => setTimeout(resolve, 200));
+            expect(window.__HYDRATION_WARNINGS__).toEqual([]);
+        }
+        finally {
+            document.body.removeChild(container);
+        }
+    });
+    test("declarative option children hydrate without attribute mismatch warnings", async () => {
+        const container = document.createElement("div");
+        container.id = "hydration-options-root";
+        document.body.appendChild(container);
+        const innerHtml = [
+            '<w-combobox id="demo-combobox" label="Search">',
+            '<option value="apple">Apple</option>',
+            '<option value="banana">Banana</option>',
+            "</w-combobox>",
+        ].join("");
+        try {
+            container.innerHTML = `<section class="example">${innerHtml}</section>`;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            function App() {
+                return React.createElement("section", {
+                    className: "example",
+                    // biome-ignore lint/security/noDangerouslySetInnerHtml: test reproduces React hydration mismatch path
+                    dangerouslySetInnerHTML: { __html: innerHtml },
+                });
+            }
+            hydrateRoot(container, React.createElement(App), {
+                onRecoverableError: (error) => {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    if (msg.includes("Hydration") ||
+                        msg.includes("hydrat") ||
+                        msg.includes("did not match") ||
                         msg.includes("didn't match")) {
                         window.__HYDRATION_WARNINGS__.push(msg);
                     }