@aurodesignsystem-dev/auro-formkit 0.0.0-pr1451.13 → 0.0.0-pr1451.14

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

@@ -12,6 +12,15 @@
 <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>
@@ -43,16 +52,13 @@
 <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 -->
-## Custom Component Registration for Version Management
-
-There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
-
-When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
-
-However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
-
-You can do this by importing only the component class and using the `register(name)` method with a unique name:
-
+<!-- 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';
 ​
@@ -61,22 +67,6 @@ 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.
 
-<div class="exampleWrapper exampleWrapper--flex">
-<custom-combobox>
-<span slot="bib.fullscreen.headline">Bib Header</span>
-<span slot="label">Name</span>
-<auro-menu>
-<auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
-<auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
-<auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
-<auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
-<auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
-<auro-menuoption static nomatch>No matching option</auro-menuoption>
-</auro-menu>
-</custom-combobox>
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
 <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;
@@ -89,7 +79,6 @@ This will create a new custom element `<custom-combobox>` that behaves exactly l
     &lt;auro-menuoption static nomatch&gt;No matching option&lt;/auro-menuoption&gt;
   &lt;/auro-menu&gt;
 &lt;/custom-combobox&gt;</code></pre>
-</auro-accordion>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 </auro-accordion>
@@ -103,8 +92,8 @@ This will create a new custom element `<custom-combobox>` that behaves exactly l
 <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/pages/getting-started/defaultRegistration.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/defaultRegistration.md -->
+<!-- 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>
@@ -124,8 +113,8 @@ This will create a new custom element `<custom-combobox>` that behaves exactly l
 <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/pages/getting-started/cdnRegistration.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/cdnRegistration.md -->
+<!-- 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>
@@ -143,15 +132,15 @@ This will create a new custom element `<custom-combobox>` that behaves exactly l
 </auro-accordion-group>
 </section>
 <section>
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/pages/getting-started/frameworks.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/frameworks.md -->
+<!-- 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/pages/getting-started/react.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/react.md -->
+<!-- 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>
@@ -234,8 +223,8 @@ Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript c
 <auro-accordion class="section" id="svelte">
 <span slot="trigger">Svelte</span>
 <div class="accordion-content">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/pages/getting-started/svelte.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/svelte.md -->
+<!-- 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>
@@ -330,8 +319,8 @@ Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript c
 <!-- AURO-GENERATED-CONTENT:END -->
 </section>
 <section>
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/pages/getting-started/minimal-config.md) -->
-<!-- The below content is automatically added from ./../docs/pages/getting-started/minimal-config.md -->
+<!-- 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:
 
@@ -351,6 +340,29 @@ Every <code>&lt;auro-combobox&gt;</code> implementation requires three things:
 <!-- 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>