@aurodesignsystem/auro-formkit 2.0.0-beta.3 → 2.0.0-beta.31

package/components/select/demo/index.md

@@ -10,22 +10,7 @@ This file is generated based on a template fetched from `./docs/partials/demo.md
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
 <!-- The below content is automatically added from ./../docs/partials/description.md -->
-`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. See the <auro-hyperlink href="https://auro.alaskaair.com/components/auro/menu/api">auro-menu API docs</auro-hyperlink> for additional information.
-
-## About auro-select
-
-The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.
-
-## Install instructions
-
-The `<auro-select>` custom element is a combo-element using independent primitives for the most flexibility. To allow consumers the most control over the versioning their dependencies, `<auro-select>` requires the following peer dependencies along with `<auro-select>`.
-
-```shell
-$ npm i @aurodesignsystem/auro-select
-
-$ npm i @aurodesignsystem/auro-dropdown
-$ npm i @aurodesignsystem/auro-menu
-```
+`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Default example
@@ -67,6 +52,92 @@ A baseline `<auro-select>` using `<auro-menu>` and `<auro-menuoption>` elements.
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+## placeholder
+
+Use the `placeholder` slot to inject a custom placeholder option with the select element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customPlaceholder.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/customPlaceholder.html -->
+  <auro-select>
+    <label slot="placeholder">Please select your preferred option</label>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/customPlaceholder.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/customPlaceholder.html -->
+
+```html
+<auro-select>
+  <label slot="placeholder">Please select your preferred option</label>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Label, placeholder and help text slots
+
+The following example illustrates the use of the `label`, `placeholder` and `helptext` slots for additional placement of content around the select menu.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/slots.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/slots.html -->
+  <auro-select>
+    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Please choose a preference</span>
+    <span slot="helpText">Preferences are maintained for future use</span>
+    <auro-menu>
+      <auro-menuoption value="stops">Stops</auro-menuoption>
+      <auro-menuoption value="price">Price</auro-menuoption>
+      <auro-menuoption value="duration">Duration</auro-menuoption>
+      <auro-menuoption value="departure">Departure</auro-menuoption>
+      <auro-menuoption value="arrival">Arrival</auro-menuoption>
+      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/slots.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/slots.html -->
+
+```html
+<auro-select>
+  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Please choose a preference</span>
+  <span slot="helpText">Preferences are maintained for future use</span>
+  <auro-menu>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Example with auro-icons in options
 
 Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
@@ -75,6 +146,7 @@ Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/withIcons.html) -->
   <!-- The below content is automatically added from ./../apiExamples/withIcons.html -->
   <auro-select>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="air">
         <auro-icon label customColor category="health" name="air">Air</auro-icon>
@@ -102,6 +174,7 @@ Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
 
 ```html
 <auro-select>
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="air">
       <auro-icon label customColor category="health" name="air">Air</auro-icon>
@@ -132,6 +205,7 @@ This example shows nesting `<auro-menu>` elements to create submenus.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/withSubmenus.html) -->
   <!-- The below content is automatically added from ./../apiExamples/withSubmenus.html -->
   <auro-select>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -173,6 +247,7 @@ This example shows nesting `<auro-menu>` elements to create submenus.
 
 ```html
 <auro-select>
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -217,6 +292,7 @@ Applying the `noCheckmark` attribute will prevent the checkmark icon from being
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/noCheckmark.html) -->
   <!-- The below content is automatically added from ./../apiExamples/noCheckmark.html -->
   <auro-select nocheckmark>
+      <label slot="placeholder">Placeholder Text</label>
       <auro-menu>
           <auro-menuoption value="stops">Stops</auro-menuoption>
           <auro-menuoption value="price">Price</auro-menuoption>
@@ -235,6 +311,7 @@ Applying the `noCheckmark` attribute will prevent the checkmark icon from being
 
 ```html
 <auro-select nocheckmark>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
         <auro-menuoption value="stops">Stops</auro-menuoption>
         <auro-menuoption value="price">Price</auro-menuoption>
@@ -258,6 +335,7 @@ Custom height dimensions are set by using the `dropdownSize` CSS Part and then a
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/customBibHeight.html) -->
   <!-- The below content is automatically added from ../apiExamples/customBibHeight.html -->
   <auro-select id="customBibHeightExample">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -281,6 +359,7 @@ Custom height dimensions are set by using the `dropdownSize` CSS Part and then a
 
 ```html
 <auro-select id="customBibHeightExample">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -299,49 +378,6 @@ Custom height dimensions are set by using the `dropdownSize` CSS Part and then a
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-## Label and help text slots
-
-The following example illustrates the use of the `label` and `helptext` slots for additional placement of content around the select menu.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/slots.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/slots.html -->
-  <auro-select>
-    <span slot="label">Please choose a preference</span>
-    <span slot="helpText">Preferences are maintained for future use</span>
-    <auro-menu>
-      <auro-menuoption value="stops">Stops</auro-menuoption>
-      <auro-menuoption value="price">Price</auro-menuoption>
-      <auro-menuoption value="duration">Duration</auro-menuoption>
-      <auro-menuoption value="departure">Departure</auro-menuoption>
-      <auro-menuoption value="arrival">Arrival</auro-menuoption>
-      <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/slots.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/slots.html -->
-
-```html
-<auro-select>
-  <span slot="label">Please choose a preference</span>
-  <span slot="helpText">Preferences are maintained for future use</span>
-  <auro-menu>
-    <auro-menuoption value="stops">Stops</auro-menuoption>
-    <auro-menuoption value="price">Price</auro-menuoption>
-    <auro-menuoption value="duration">Duration</auro-menuoption>
-    <auro-menuoption value="departure">Departure</auro-menuoption>
-    <auro-menuoption value="arrival">Arrival</auro-menuoption>
-    <auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
 ## Error State
 
 Use the `error` boolean attribute to toggle the error UI.
@@ -350,6 +386,7 @@ Use the `error` boolean attribute to toggle the error UI.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/error.html) -->
   <!-- The below content is automatically added from ./../apiExamples/error.html -->
   <auro-select error="Custom error message">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -368,6 +405,7 @@ Use the `error` boolean attribute to toggle the error UI.
 
 ```html
 <auro-select error="Custom error message">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -389,6 +427,7 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
   <!-- The below content is automatically added from ./../apiExamples/disabled.html -->
   <auro-select disabled>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -407,6 +446,7 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 
 ```html
 <auro-select disabled>
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -438,6 +478,7 @@ This will create a new custom element that you can use in your HTML that will fu
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/custom.html) -->
   <!-- The below content is automatically added from ./../apiExamples/custom.html -->
   <custom-select>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -456,6 +497,7 @@ This will create a new custom element that you can use in your HTML that will fu
 
 ```html
 <custom-select>
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>