@aurodesignsystem-dev/auro-formkit 0.0.0-pr1451.2 → 0.0.0-pr1451.21

package/components/combobox/demo/demo-support.js

@@ -0,0 +1,60 @@
+import {unified} from 'https://esm.sh/unified';
+import remarkParse from 'https://esm.sh/remark-parse';
+import remarkGfm from 'https://esm.sh/remark-gfm';
+import remarkRehype from 'https://esm.sh/remark-rehype';
+import rehypeRaw from 'https://esm.sh/rehype-raw';
+import rehypeHighlight from 'https://esm.sh/rehype-highlight';
+import rehypeStringify from 'https://esm.sh/rehype-stringify';
+
+export async function renderPage(mdPath) {
+  const response = await fetch(mdPath);
+  const text = await response.text();
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeHighlight)
+    .use(rehypeStringify)
+    .process(text);
+
+  document.querySelector('main').innerHTML = String(result);
+  addCopyButtons();
+}
+
+function addCopyButtons() {
+  document.querySelectorAll('pre code[class*="language-"], pre code[class*="hljs"]').forEach((code) => {
+    const pre = code.parentElement;
+    const wrapper = document.createElement('div');
+    wrapper.className = 'pre-wrapper';
+    pre.parentNode.insertBefore(wrapper, pre);
+    wrapper.appendChild(pre);
+    const btn = document.createElement('button');
+    btn.className = 'copy-btn';
+    btn.textContent = 'Copy';
+    btn.addEventListener('click', () => {
+      const raw = code.textContent;
+      const text = raw.replace(/\u200B/g, '').replace(/^\n+/, '').replace(/\n+$/, '\n').replace(/^\$ /, '');
+      navigator.clipboard.writeText(text).then(() => {
+        btn.textContent = 'Copied!';
+        setTimeout(() => { btn.textContent = 'Copy'; }, 1500);
+      });
+    });
+    wrapper.appendChild(btn);
+  });
+}
+
+export function openAccordion(id) {
+  document.querySelectorAll('auro-accordion').forEach((accordion) => {
+    accordion.removeAttribute('expanded');
+  });
+  const target = document.getElementById(id);
+  if (target) {
+    target.setAttribute('expanded', '');
+    setTimeout(() => {
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }, 550);
+  }
+}
+
+window.openAccordion = openAccordion;

package/components/combobox/demo/design.html

@@ -39,49 +39,8 @@
     <main></main>
 
     <script type="module">
-      import {unified} from 'https://esm.sh/unified';
-      import remarkParse from 'https://esm.sh/remark-parse';
-      import remarkGfm from 'https://esm.sh/remark-gfm';
-      import remarkRehype from 'https://esm.sh/remark-rehype';
-      import rehypeRaw from 'https://esm.sh/rehype-raw';
-      import rehypeHighlight from 'https://esm.sh/rehype-highlight';
-      import rehypeStringify from 'https://esm.sh/rehype-stringify';
-
-      const response = await fetch('./design.md');
-      const text = await response.text();
-      const result = await unified()
-        .use(remarkParse)
-        .use(remarkGfm)
-        .use(remarkRehype, { allowDangerousHtml: true })
-        .use(rehypeRaw)
-        .use(rehypeHighlight)
-        .use(rehypeStringify)
-        .process(text);
-
-      document.querySelector('main').innerHTML = String(result);
-      addCopyButtons();
-
-      function addCopyButtons() {
-        document.querySelectorAll('pre code[class*="language-"], pre code[class*="hljs"]').forEach((code) => {
-          const pre = code.parentElement;
-          const wrapper = document.createElement('div');
-          wrapper.className = 'pre-wrapper';
-          pre.parentNode.insertBefore(wrapper, pre);
-          wrapper.appendChild(pre);
-          const btn = document.createElement('button');
-          btn.className = 'copy-btn';
-          btn.textContent = 'Copy';
-          btn.addEventListener('click', () => {
-            const raw = code.textContent;
-            const text = raw.replace(/\u200B/g, '').replace(/^\n+/, '').replace(/\n+$/, '\n').replace(/^\$ /, '');
-            navigator.clipboard.writeText(text).then(() => {
-              btn.textContent = 'Copied!';
-              setTimeout(() => { btn.textContent = 'Copy'; }, 1500);
-            });
-          });
-          wrapper.appendChild(btn);
-        });
-      }
+      import { renderPage } from './demo-support.js';
+      await renderPage('./design.md');
     </script>
 
     <!-- If additional elements are needed for the demo, add them here. -->

package/components/combobox/demo/design.md

@@ -3,8 +3,8 @@
 <div class="mainContent">
 <div class="scrollWrapper">
 <auro-header level="3" id="anatomy">Component Anatomy</auro-header>
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/layout.md) -->
-<!-- The below content is automatically added from ./../docs/partials/layout.md -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/layout/layout.md) -->
+<!-- The below content is automatically added from ./../docs/partials/layout/layout.md -->
 <p>The component consists of the following elements:</p>
 <ul>
 <li>
@@ -87,7 +87,7 @@
 <!-- The below content is automatically added from ./../apiExamples/appearance-inverse.html -->
 <auro-combobox appearance="inverse">
 <span slot="bib.fullscreen.headline">Bib Header</span>
-<span slot="label">Name</span>
+<span slot="label">Inverse Appearance</span>
 <auro-menu>
 <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
 <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -105,7 +105,7 @@
 <!-- The below code snippet is automatically added from ./../apiExamples/appearance-inverse.html -->
 <pre class="language-html"><code class="language-html">&lt;auro-combobox appearance="inverse"&gt;
   &lt;span slot="bib.fullscreen.headline"&gt;Bib Header&lt;/span&gt;
-  &lt;span slot="label"&gt;Name&lt;/span&gt;
+  &lt;span slot="label"&gt;Inverse Appearance&lt;/span&gt;
   &lt;auro-menu&gt;
     &lt;auro-menuoption value="Apples" id="option-0"&gt;Apples&lt;/auro-menuoption&gt;
     &lt;auro-menuoption value="Oranges" id="option-1"&gt;Oranges&lt;/auro-menuoption&gt;

package/components/combobox/demo/getting-started.html

@@ -0,0 +1,53 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/getting-started.md
+
+  ----------------------- DO NOT EDIT -----------------------------
+
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Demo | auro-combobox | Getting Started</title>
+
+    <!-- highlight.js Stylesheet -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css"/>
+
+    <!-- Legacy reference is still needed to support auro-combobox's use of legacy token values at this time -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/legacy/auro-classic/CSSCustomProperties.css"/>
+
+    <!-- Design Token Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/themes/alaska/CSSCustomProperties--alaska.min.css"/>
+
+    <!-- Webcore Stylesheet Alaska Theme -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/themes/alaska.global.min.css" />
+
+    <!-- Demo Specific Styles -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="./styles.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-nav@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-header@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-hyperlink@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
+    <script type="module">
+      import { renderPage } from './demo-support.js';
+      await renderPage('./getting-started.md');
+      import { initExamples } from "./getting-started.min.js";
+      initExamples();
+    </script>
+    <script src="./getting-started.min.js" data-demo-script="true" type="module"></script>
+  </body>
+</html>

package/components/combobox/demo/{install.js → getting-started.js}

@@ -1,7 +1,5 @@
 /* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
 
-import { swapValueExample } from '../apiExamples/swap-value';
-
 import { AuroCombobox } from '../src/auro-combobox.js';
 import '../../menu/src/registered.js';
 
@@ -12,10 +10,9 @@ export function initExamples(initCount) {
   initCount = initCount || 0;
 
   try {
-    swapValueExample();
-  } catch {
+    // Add any example initialization code here.
+  } catch (err) {
     if (initCount <= 20) {
-      // setTimeout handles issue where content is sometimes loaded after the functions get called
       setTimeout(() => {
         initExamples(initCount + 1);
       }, 100);

package/components/combobox/demo/getting-started.md

@@ -0,0 +1,397 @@
+<auro-header level="1" id="overview">Combobox - Getting Started</auro-header>
+<div class="contentWrapper">
+<nav>
+<auro-nav anchorNavContent=".scrollWrapper">
+<span slot="mobileToggleCollapsed">View More</span>
+<span slot="mobileToggleExpanded">View Less</span>
+<auro-anchorlink fluid href="#setup">Setup</auro-anchorlink>
+<auro-anchorlink fluid href="#recommendedSetup" class="level2 body-xs" onclick="openAccordion('recommendedAccordion')">Recommended</auro-anchorlink>
+<auro-anchorlink fluid href="#autoSetup" class="level2 body-xs" onclick="openAccordion('autoAccordion')">Auto</auro-anchorlink>
+<auro-anchorlink fluid href="#cdnSetup" class="level2 body-xs" onclick="openAccordion('cdnAccordion')">CDN</auro-anchorlink>
+<auro-anchorlink fluid href="#frameworks">Frameworks</auro-anchorlink>
+<auro-anchorlink fluid href="#react" class="level2 body-xs" onclick="openAccordion('react')">React</auro-anchorlink>
+<auro-anchorlink fluid href="#svelte" class="level2 body-xs" onclick="openAccordion('svelte')">Svelte</auro-anchorlink>
+<auro-anchorlink fluid href="#minimalConfig">Minimal Config</auro-anchorlink>
+<auro-anchorlink fluid href="#slots">Slots</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-default" class="level2 body-xs">(default)</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-label" class="level2 body-xs">label</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-helpText" class="level2 body-xs">helpText</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-optionalLabel" class="level2 body-xs">optionalLabel</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-displayValue" class="level2 body-xs">displayValue</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-ariaLabel-input-clear" class="level2 body-xs">ariaLabel.input.clear</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-ariaLabel-bib-close" class="level2 body-xs">ariaLabel.bib.close</auro-anchorlink>
+<auro-anchorlink fluid href="#slot-bib-fullscreen-headline" class="level2 body-xs">bib.fullscreen.headline</auro-anchorlink>
+<auro-anchorlink fluid href="#stateManagement">State Management</auro-anchorlink>
+<auro-anchorlink fluid href="#inputValue" class="level2 body-xs">inputValue</auro-anchorlink>
+<auro-anchorlink fluid href="#optionSelected" class="level2 body-xs">optionSelected</auro-anchorlink>
+<auro-anchorlink fluid href="#typedValue" class="level2 body-xs">typedValue</auro-anchorlink>
+<auro-anchorlink fluid href="#validity" class="level2 body-xs">Validity</auro-anchorlink>
+<auro-anchorlink fluid href="#value" class="level2 body-xs">Value</auro-anchorlink>
+<auro-anchorlink fluid href="#publicFunctions">Functions</auro-anchorlink>
+<auro-anchorlink fluid href="#clear" class="level2 body-xs">clear()</auro-anchorlink>
+<auro-anchorlink fluid href="#focus" class="level2 body-xs">focus()</auro-anchorlink>
+<auro-anchorlink fluid href="#reset" class="level2 body-xs">reset()</auro-anchorlink>
+<auro-anchorlink fluid href="#validate" class="level2 body-xs">validate()</auro-anchorlink>
+<auro-anchorlink fluid href="#hideBib" class="level2 body-xs">hideBib()</auro-anchorlink>
+<auro-anchorlink fluid href="#showBib" class="level2 body-xs">showBib()</auro-anchorlink>
+</auro-nav>
+</nav>
+<div class="mainContent">
+<div class="scrollWrapper">
+<section>
+<auro-header level="2" id="setup">Setup</auro-header>
+<auro-accordion-group Emphasis>
+<auro-accordion expanded class="section" id="recommendedAccordion">
+<span slot="trigger">Recommended Installation and Implementation</span>
+<div class="accordion-content">
+<auro-header level="3">Install</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ./../../../docs/templates/componentInstall.md -->
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-formkit</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="3">Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/customRegistration.md -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/partials/customRegistrationDescription.md) -->
+<!-- The below content is automatically added from ./../../../docs/partials/customRegistrationDescription.md -->
+<p>Every Auro component consists of a JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and a <a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define">custom element registration</a>. The class defines the component's behavior, and the registration maps it to an HTML tag name so it can be used in markup.</p>
+<p>The default import (shown above) handles both steps automatically, registering the component under its standard tag name.</p>
+<p>If you need multiple versions of the same component on a single page — for example, when two projects depend on different versions — you can register the class under a custom tag name to avoid conflicts.</p>
+<p>To do this, import the component class directly and call its <code>register(name)</code> method with a unique name:</p>
+<!-- AURO-GENERATED-CONTENT:END -->
+<pre class="language-js"><code class="language-js">// Import the class only
+import { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+​
+// Register with a custom name if desired
+AuroCombobox.register('custom-combobox');</code></pre>
+
+This will create a new custom element `<custom-combobox>` that behaves exactly like `<auro-combobox>`, allowing both to coexist on the same page without interfering with each other.
+
+<pre class="language-html"><code class="language-html">&lt;custom-combobox&gt;
+  &lt;span slot="bib.fullscreen.headline"&gt;Bib Header&lt;/span&gt;
+  &lt;span slot="label"&gt;Name&lt;/span&gt;
+  &lt;auro-menu&gt;
+    &lt;auro-menuoption value="Apples" id="option-0"&gt;Apples&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="Oranges" id="option-1"&gt;Oranges&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="Peaches" id="option-2"&gt;Peaches&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="Grapes" id="option-3"&gt;Grapes&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="Cherries" id="option-4"&gt;Cherries&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption static nomatch&gt;No matching option&lt;/auro-menuoption&gt;
+  &lt;/auro-menu&gt;
+&lt;/custom-combobox&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+<auro-accordion class="section" id="autoAccordion">
+<span slot="trigger">Auto Installation and Implementation</span>
+<div class="accordion-content">
+<p class="warning"><strong>Warning:</strong> Default registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.</p>
+<auro-header level="3">Install</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ./../../../docs/templates/componentInstall.md -->
+<pre class="language-shell"><code class="language-shell">$ npm i @aurodesignsystem/auro-formkit</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+<auro-header level="3">Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/defaultRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/defaultRegistration.md -->
+<p>Once installed, the component can be used in your project by importing the component's registered module:</p>
+<pre class="language-js"><code class="language-js">import '@aurodesignsystem/auro-formkit/auro-combobox';</code></pre>
+<p>This import registers the <code>&lt;auro-combobox&gt;</code> custom element globally. You can then use it in your HTML:</p>
+<pre class="language-html"><code class="language-html">&lt;auro-combobox&gt;
+  &lt;span slot="label"&gt;Choose an option&lt;/span&gt;
+  &lt;auro-menu&gt;
+    &lt;auro-menuoption value="option1"&gt;Option 1&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="option2"&gt;Option 2&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption static nomatch&gt;No matching option&lt;/auro-menuoption&gt;
+  &lt;/auro-menu&gt;
+&lt;/auro-combobox&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+<auro-accordion class="section" id="cdnAccordion">
+<span slot="trigger">CDN Installation and Implementation</span>
+<div class="accordion-content">
+<p class="warning"><strong>Warning:</strong> CDN install & registration can cause conflicts if another package registers the same tag name using a different version of the component, leading to unexpected behavior. Use custom registration to avoid this risk.</p>
+<auro-header level="3">Install & Implementation</auro-header>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/cdnRegistration.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/cdnRegistration.md -->
+<p>Add the following script tag to your HTML to load the component directly from a CDN:</p>
+<pre class="language-html"><code class="language-html">&lt;script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@latest/auro-combobox/+esm"&gt;&lt;/script&gt;</code></pre>
+<p>This script registers the <code>&lt;auro-combobox&gt;</code> custom element globally. You can then use it in your HTML:</p>
+<pre class="language-html"><code class="language-html">&lt;auro-combobox&gt;
+  &lt;span slot="label"&gt;Choose an option&lt;/span&gt;
+  &lt;auro-menu&gt;
+    &lt;auro-menuoption value="option1"&gt;Option 1&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="option2"&gt;Option 2&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption static nomatch&gt;No matching option&lt;/auro-menuoption&gt;
+  &lt;/auro-menu&gt;
+&lt;/auro-combobox&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+</auro-accordion-group>
+</section>
+<section>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/frameworks.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/frameworks.md -->
+<auro-header level="2" id="frameworks">Frameworks</auro-header>
+<auro-accordion-group Emphasis>
+<auro-accordion class="section" id="react">
+<span slot="trigger">React</span>
+<div class="accordion-content">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/react.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/react.md -->
+React 19 includes <a href="https://react.dev/blog/2024/12/05/react-19#support-for-custom-elements">native support for custom elements</a>, so <code>&lt;auro-combobox&gt;</code> works directly in JSX without any wrapper library.
+
+<auro-header level="3" id="reactImport">Import the Component</auro-header>
+Import and register the components at the top level of your application (e.g. in your root `main.tsx` or `App.tsx`):
+
+<pre class="language-js"><code class="language-js">import { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+import { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-formkit/auro-menu/class';
+​
+AuroCombobox.register('[custom]-combobox');
+AuroMenu.register('[custom]-menu');
+AuroMenuOption.register('[custom]-menuoption');</code></pre>
+
+<auro-header level="3" id="reactTypeScript">TypeScript Declarations</auro-header>
+The component ships with TypeScript type definitions for the `AuroCombobox` class. However, React's JSX does not automatically map custom element tag names to their types. To get type checking for `<auro-combobox>` in JSX, add the following declaration to a `.d.ts` file in your project:
+
+<pre class="language-js"><code class="language-js">import type { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+import type { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-menu/auro-menu/class';
+​
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      '[custom]-combobox': React.HTMLAttributes&lt;AuroCombobox&gt; &amp; Partial&lt;AuroCombobox&gt;;
+      '[custom]-menu': React.HTMLAttributes&lt;AuroMenu&gt; &amp; Partial&lt;AuroMenu&gt;;
+      '[custom]-menuoption': React.HTMLAttributes&lt;AuroMenuOption&gt; &amp; Partial&lt;AuroMenuOption&gt;;
+    }
+  }
+}</code></pre>
+
+<auro-header level="3" id="reactEvents">Event Handling</auro-header>
+Auro components emit native `CustomEvent`s. Use a `ref` to attach event listeners in a `useEffect`:
+
+<pre class="language-js"><code class="language-js">import { useRef, useEffect } from 'react';
+​
+const options = [
+  { id: 'opt-1', value: 'SEA', label: 'Seattle-Tacoma International' },
+  { id: 'opt-2', value: 'LAX', label: 'Los Angeles International' },
+  { id: 'opt-3', value: 'JFK', label: 'John F. Kennedy International' },
+  { id: 'opt-4', value: 'ORD', label: "O'Hare International" },
+];
+​
+function MyCombobox() {
+  const comboboxRef = useRef&lt;HTMLElement&gt;(null);
+​
+  useEffect(() =&gt; {
+    const el = comboboxRef.current;
+    if (!el) return;
+​
+    const handleInput = () =&gt; {
+      console.log('Selected value:', (el as any).value);
+    };
+​
+    el.addEventListener('input', handleInput);
+    return () =&gt; el.removeEventListener('input', handleInput);
+  }, []);
+​
+  return (
+    &lt;custom-combobox ref={comboboxRef}&gt;
+      &lt;span slot="label"&gt;Search airports&lt;/span&gt;
+      &lt;custom-menu&gt;
+        {options.map(({ id, value, label }) =&gt; (
+          &lt;custom-menuoption key={id} value={value}&gt;{label}&lt;/custom-menuoption&gt;
+        ))}
+        &lt;custom-menuoption static nomatch&gt;No matching airport&lt;/custom-menuoption&gt;
+      &lt;/custom-menu&gt;
+    &lt;/custom-combobox&gt;
+  );
+}</code></pre>
+
+<auro-header level="3" id="reactModuleResolution">Module Resolution</auro-header>
+Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript can resolve the component's package exports:
+
+<pre class="language-js"><code class="language-js">{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+<auro-accordion class="section" id="svelte">
+<span slot="trigger">Svelte</span>
+<div class="accordion-content">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/svelte.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/svelte.md -->
+Svelte has <a href="https://svelte.dev/docs/svelte/custom-elements">native support for custom elements</a>, so <code>&lt;auro-combobox&gt;</code> works directly in Svelte templates without any wrapper or configuration.
+
+<auro-header level="3" id="svelteImport">Import the Component</auro-header>
+Import and register the components in the `<script>` block:
+
+<pre class="language-html"><code class="language-html">&lt;script lang="ts"&gt;
+  import { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+  import { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-formkit/auro-menu/class';
+​
+  AuroCombobox.register('[custom]-combobox');
+  AuroMenu.register('[custom]-menu');
+  AuroMenuOption.register('[custom]-menuoption');
+&lt;/script&gt;</code></pre>
+
+<auro-header level="3" id="svelteUsage">Basic Usage</auro-header>
+Use `<auro-combobox>` directly in your Svelte template. Properties can be bound using standard Svelte attribute syntax:
+
+<pre class="language-html"><code class="language-html">&lt;script lang="ts"&gt;
+  import { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+  import { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-formkit/auro-menu/class';
+​
+  AuroCombobox.register('[custom]-combobox');
+  AuroMenu.register('[custom]-menu');
+  AuroMenuOption.register('[custom]-menuoption');
+​
+  const options: [string, string][] = [
+    ['SEA', 'Seattle-Tacoma International'],
+    ['LAX', 'Los Angeles International'],
+    ['JFK', 'John F. Kennedy International'],
+  ];
+​
+  let comboboxValue = $state&lt;string&gt;('');
+&lt;/script&gt;
+&lt;custom-combobox value={comboboxValue}&gt;
+  &lt;span slot="label"&gt;Search airports&lt;/span&gt;
+  &lt;custom-menu&gt;
+    {#each options as [value, label]}
+      &lt;custom-menuoption {value}&gt;{label}&lt;/custom-menuoption&gt;
+    {/each}
+    &lt;custom-menuoption static nomatch&gt;No matching airport&lt;/custom-menuoption&gt;
+  &lt;/custom-menu&gt;
+&lt;/custom-combobox&gt;</code></pre>
+
+<auro-header level="3" id="svelteTypeScript">TypeScript Declarations</auro-header>
+Svelte does not automatically know about custom element attributes. To get autocomplete and type checking for `<auro-combobox>` props in templates, add the following to a `.d.ts` file in your project (e.g. `src/auro-elements.d.ts`):
+
+<pre class="language-js"><code class="language-js">import type { AuroCombobox } from '@aurodesignsystem/auro-formkit/auro-combobox/class';
+import type { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-formkit/auro-menu/class';
+​
+declare namespace svelteHTML {
+  interface IntrinsicElements {
+    '[custom]-combobox': Partial&lt;AuroCombobox&gt; &amp; svelteHTML.HTMLAttributes&lt;AuroCombobox&gt;;
+    '[custom]-menu': Partial&lt;AuroMenu&gt; &amp; svelteHTML.HTMLAttributes&lt;AuroMenu&gt;;
+    '[custom]-menuoption': Partial&lt;AuroMenuOption&gt; &amp; svelteHTML.HTMLAttributes&lt;AuroMenuOption&gt;;
+  }
+}</code></pre>
+
+This enables prop hinting for attributes like `value`, `disabled`, and others directly in Svelte templates.
+
+<auro-header level="3" id="svelteEvents">Event Handling</auro-header>
+Auro components emit native `CustomEvent`s. Use the `oninput` handler directly on the element:
+
+<pre class="language-html"><code class="language-html">&lt;script lang="ts"&gt;
+  let value = $state('');
+​
+  function handleInput(e: Event) {
+    value = (e.target as HTMLElement &amp; { value: string }).value;
+  }
+&lt;/script&gt;
+&lt;custom-combobox oninput={handleInput}&gt;
+  &lt;span slot="label"&gt;Search airports&lt;/span&gt;
+  &lt;custom-menu&gt;
+    &lt;custom-menuoption value="SEA"&gt;Seattle-Tacoma International&lt;/custom-menuoption&gt;
+    &lt;custom-menuoption value="LAX"&gt;Los Angeles International&lt;/custom-menuoption&gt;
+    &lt;custom-menuoption static nomatch&gt;No matching airport&lt;/custom-menuoption&gt;
+  &lt;/custom-menu&gt;
+&lt;/custom-combobox&gt;
+&lt;p&gt;Selected: {value}&lt;/p&gt;</code></pre>
+
+<auro-header level="3" id="svelteModuleResolution">Module Resolution</auro-header>
+Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript can resolve the component's package exports:
+
+<pre class="language-js"><code class="language-js">{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+</auro-accordion>
+</auro-accordion-group>
+<!-- AURO-GENERATED-CONTENT:END -->
+</section>
+<section>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/minimal-config.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/minimal-config.md -->
+<auro-header level="3" id="minimalConfig">Minimal Configuration</auro-header>
+Every <code>&lt;auro-combobox&gt;</code> implementation requires three things:
+
+1. **A unique `id` attribute** — Required when the combobox is used within a form so it can be properly identified during submission and validation.
+2. **A label in the `label` slot** — Provides an accessible label for the combobox element.
+3. **One or more `<auro-menuoption>` elements** — Placed inside an `<auro-menu>` in the default slot to define the available choices.
+
+<pre class="language-html"><code class="language-html">&lt;auro-combobox id="airportSearch"&gt;
+  &lt;span slot="label"&gt;Search airports&lt;/span&gt;
+  &lt;auro-menu&gt;
+    &lt;auro-menuoption value="SEA"&gt;Seattle-Tacoma International&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="LAX"&gt;Los Angeles International&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption value="JFK"&gt;John F. Kennedy International&lt;/auro-menuoption&gt;
+    &lt;auro-menuoption static nomatch&gt;No matching airport&lt;/auro-menuoption&gt;
+  &lt;/auro-menu&gt;
+&lt;/auro-combobox&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</section>
+<section>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/getting-started/slots.md) -->
+<!-- The below content is automatically added from ./../docs/partials/getting-started/slots.md -->
+<auro-header level="2" id="slots">Slots</auro-header>
+<p>The following slots are available on the <code>&lt;auro-combobox&gt;</code> element.</p>
+<auro-header level="3" id="slot-default">(default)</auro-header>
+<p>Default slot for the menu content. Place <code>&lt;auro-menuoption&gt;</code> elements here.</p>
+<auro-header level="3" id="slot-label">label</auro-header>
+<p>Defines the content of the label.</p>
+<auro-header level="3" id="slot-helpText">helpText</auro-header>
+<p>Defines the content of the help text displayed below the combobox.</p>
+<auro-header level="3" id="slot-optionalLabel">optionalLabel</auro-header>
+<p>Allows overriding the optional display text <code>"(optional)"</code>, which appears next to the label.</p>
+<auro-header level="3" id="slot-displayValue">displayValue</auro-header>
+<p>Allows custom HTML content to display the selected value when the combobox is not focused. Only works with <code>snowflake</code> and <code>emphasized</code> layouts.</p>
+<auro-header level="3" id="slot-ariaLabel-input-clear">ariaLabel.input.clear</auro-header>
+<p>Sets <code>aria-label</code> on the clear button.</p>
+<auro-header level="3" id="slot-ariaLabel-bib-close">ariaLabel.bib.close</auro-header>
+<p>Sets <code>aria-label</code> on the close button in the fullscreen bib.</p>
+<auro-header level="3" id="slot-bib-fullscreen-headline">bib.fullscreen.headline</auro-header>
+<p>Defines the headline to display above menu options in the fullscreen bib.</p>
+<!-- AURO-GENERATED-CONTENT:END -->
+</section>
+<section>
+<auro-header level="2" id="stateManagement">State Management</auro-header>
+<p>The following read-only properties reflect the current state of the component and can be accessed via JavaScript.</p>
+<auro-header level="3" id="inputValue">inputValue</auro-header>
+<p>Returns the current value of the internal HTML5 <code>input</code> element. This reflects exactly what the user has typed, regardless of whether it matches a menu option.</p>
+<auro-header level="3" id="optionSelected">optionSelected</auro-header>
+<p>Returns the currently selected <code>&lt;auro-menuoption&gt;</code> element, or <code>undefined</code> if no option is selected.</p>
+<auro-header level="3" id="typedValue">typedValue</auro-header>
+<p>Gets or sets the value of the internal input element. Unlike <code>value</code>, this represents what the user typed (or what was programmatically set in the input), not the selected option value.</p>
+<auro-header level="3" id="validity">validity</auro-header>
+<p>Returns the current <code>validityState</code> of the component as a string. Possible values include <code>"valid"</code>, <code>"valueMissing"</code>, and <code>"customError"</code>.</p>
+<auro-header level="3" id="value">value</auro-header>
+<p>Gets or sets the selected value of the combobox. When set programmatically, the component will attempt to match and select the corresponding menu option.</p>
+</section>
+<section>
+<auro-header level="2" id="publicFunctions">Functions</auro-header>
+<p>The following public methods are available on the <code>&lt;auro-combobox&gt;</code> element.</p>
+<auro-header level="3" id="clear">clear()</auro-header>
+<p>Clears the current value of the combobox, resetting both the input and the selected option.</p>
+<auro-header level="3" id="focus">focus()</auro-header>
+<p>Programmatically moves focus to the combobox trigger input.</p>
+<auro-header level="3" id="reset">reset()</auro-header>
+<p>Resets the component to its initial state, clearing the value, input text, and validation state.</p>
+<auro-header level="3" id="validate">validate()</auro-header>
+<p>Triggers validation on the component. Pass <code>true</code> to force validation even when <code>noValidate</code> is set.</p>
+<auro-header level="3" id="hideBib">hideBib()</auro-header>
+<p>Programmatically hides the dropdown bib if it is currently open.</p>
+<auro-header level="3" id="showBib">showBib()</auro-header>
+<p>Programmatically shows the dropdown bib if there are options to display.</p>
+</section>
+</div>
+</div>
+</div>