@aurodesignsystem-dev/auro-formkit 0.0.0-pr755.1 → 0.0.0-pr756.1

package/components/dropdown/demo/index.md

@@ -36,14 +36,14 @@ To meet our accessibility requirement, all uses of `auro-dropdown` should have a
 
 Not including one of the above options will result in your UI being non-compliant with Alaska's accessibility policies.
 
-## Layouts
-
-### Classic
+## Classic Layouts
+
+This first common example uses the default `auro-dropdown` element with the attributes of `bordered` `rounded` `inset` `toggle` and `chevron`. Additionally the `aria-label` attribute is used to define a string value that labels an interactive element.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/classic/basic.html) -->
   <!-- The below content is automatically added from ./../apiExamples/classic/basic.html -->
-  <auro-dropdown id="classic" layout="classic" shape="classic" size="lg" chevron aria-label="Label content for screen reader">
+  <auro-dropdown id="classic" chevron aria-label="Label content for screen reader">
     <div style="padding: var(--ds-size-150);">
       Lorem ipsum solar
       <br />
@@ -66,7 +66,7 @@ Not including one of the above options will result in your UI being non-complian
 <!-- The below code snippet is automatically added from ./../apiExamples/classic/basic.html -->
 
 ```html
-<auro-dropdown id="classic" layout="classic" shape="classic" size="lg" chevron aria-label="Label content for screen reader">
+<auro-dropdown id="classic" chevron aria-label="Label content for screen reader">
   <div style="padding: var(--ds-size-150);">
     Lorem ipsum solar
     <br />
@@ -87,7 +87,7 @@ Not including one of the above options will result in your UI being non-complian
 <div class="exampleWrapper--ondark">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/classic/basic-ondark.html) -->
   <!-- The below content is automatically added from ./../apiExamples/classic/basic-ondark.html -->
-  <auro-dropdown onDark layout="classic" shape="classic" size="lg" id="classicOnDark" chevron aria-label="Label content for screen reader">
+  <auro-dropdown onDark id="classicOnDark" chevron aria-label="Label content for screen reader">
     <div style="padding: var(--ds-size-150);">
       Lorem ipsum solar
       <br />
@@ -110,7 +110,7 @@ Not including one of the above options will result in your UI being non-complian
 <!-- The below code snippet is automatically added from ./../apiExamples/classic/basic-ondark.html -->
 
 ```html
-<auro-dropdown onDark layout="classic" shape="classic" size="lg" id="classicOnDark" chevron aria-label="Label content for screen reader">
+<auro-dropdown onDark id="classicOnDark" chevron aria-label="Label content for screen reader">
   <div style="padding: var(--ds-size-150);">
     Lorem ipsum solar
     <br />
@@ -129,9 +129,7 @@ Not including one of the above options will result in your UI being non-complian
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Emphasized
-
-Only supports `ondark`.
+## Emphasized Layouts
 
 <div class="exampleWrapper--ondark">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/emphasized/basic.html) -->
@@ -165,80 +163,399 @@ Only supports `ondark`.
   </auro-dropdown>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
+
+## Snowflake Layouts
+
+<div class="exampleWrapper--ondark">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/snowflake/basic.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/snowflake/basic.html -->
+  <auro-dropdown aria-label="custom label" shape="snowflake" size="lg" layout="snowflake" style="width: 249px;" ondark>
+    Lorem ipsum solar
+    <div slot="trigger">
+      Trigger
+    </div>
+    <span slot="helpText">
+      Help text - Lorem ipsum solar lorem ipsum solar
+    </span>
+  </auro-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+
+## Common use with auro-label
+
+This first common example uses the default `auro-dropdown` element with the attributes of `bordered` `rounded` `inset` `toggle` and `chevron`. Additionally the `aria-label` attribute is used to define a string value that labels an interactive element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/common.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/common.html -->
+  <auro-dropdown id="common" common aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button onclick="document.querySelector('#common').hide()">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </auro-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<div class="exampleWrapper--ondark" aria-hidden>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkCommon.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/onDarkCommon.html -->
+  <auro-dropdown onDark common id="commonOnDark" aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button onclick="document.querySelector('#commonOnDark').hide()">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </auro-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/emphasized/basic.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/emphasized/basic.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/common.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/common.html -->
 
 ```html
-<auro-dropdown aria-label="custom label" shape="pill" size="xl" layout="emphasized" style="width: 249px;" ondark>
-  Lorem ipsum solar
-  <div slot="trigger">
-    Trigger
+<auro-dropdown id="common" common aria-label="Label content for screen reader">
+  <div style="padding: var(--ds-size-150);">
+    Lorem ipsum solar
+    <br />
+    <auro-button onclick="document.querySelector('#common').hide()">
+      Dismiss Dropdown
+    </auro-button>
   </div>
   <span slot="helpText">
-    Help text - Lorem ipsum solar lorem ipsum solar
+    Help text
   </span>
-</auro-dropdown>
-<auro-dropdown aria-label="custom label" shape="pill-left" size="xl" layout="emphasized" style="width: 249px;" ondark>
-  Lorem ipsum solar
   <div slot="trigger">
     Trigger
   </div>
+</auro-dropdown>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkCommon.html) -->
+<!-- The below content is automatically added from ./../apiExamples/onDarkCommon.html -->
+<auro-dropdown onDark common id="commonOnDark" aria-label="Label content for screen reader">
+  <div style="padding: var(--ds-size-150);">
+    Lorem ipsum solar
+    <br />
+    <auro-button onclick="document.querySelector('#commonOnDark').hide()">
+      Dismiss Dropdown
+    </auro-button>
+  </div>
   <span slot="helpText">
-    Help text - Lorem ipsum solar lorem ipsum solar
+    Help text
   </span>
-</auro-dropdown>
-<auro-dropdown aria-label="custom label" shape="pill-right" size="xl" layout="emphasized" style="width: 249px;" ondark>
-  Lorem ipsum solar
   <div slot="trigger">
     Trigger
   </div>
+</auro-dropdown>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Common use using the label content slot
+
+This common example uses the default `auro-dropdown` element with the attributes of `bordered` `rounded` `inset` `toggle` and `chevron`. Additionally the `slot` content container to define a string value that labels the interactive element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/commonSlot.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/commonSlot.html -->
+  <auro-dropdown id="commonSlot" common>
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button onclick="document.querySelector('#commonSlot').hide()">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <span slot="label">
+      Element label (default text will be read by screen reader)
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </auro-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<div class="exampleWrapper--ondark" aria-hidden>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkCommonSlot.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/onDarkCommonSlot.html -->
+  <auro-dropdown onDark common id="commonSlotOnDark">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button onclick="document.querySelector('#commonSlotOnDark').hide()">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
+    <span slot="label">
+      Element label (default text will be read by screen reader)
+    </span>
+    <div slot="trigger">
+      Trigger
+    </div>
+  </auro-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/commonSlot.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/commonSlot.html -->
+
+```html
+<auro-dropdown id="commonSlot" common>
+  <div style="padding: var(--ds-size-150);">
+    Lorem ipsum solar
+    <br />
+    <auro-button onclick="document.querySelector('#commonSlot').hide()">
+      Dismiss Dropdown
+    </auro-button>
+  </div>
   <span slot="helpText">
-    Help text - Lorem ipsum solar lorem ipsum solar
+    Help text
   </span>
+  <span slot="label">
+    Element label (default text will be read by screen reader)
+  </span>
+  <div slot="trigger">
+    Trigger
+  </div>
 </auro-dropdown>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkCommonSlot.html) -->
+<!-- The below content is automatically added from ./../apiExamples/onDarkCommonSlot.html -->
+<auro-dropdown onDark common id="commonSlotOnDark">
+  <div style="padding: var(--ds-size-150);">
+    Lorem ipsum solar
+    <br />
+    <auro-button onclick="document.querySelector('#commonSlotOnDark').hide()">
+      Dismiss Dropdown
+    </auro-button>
+  </div>
+  <span slot="helpText">
+    Help text
+  </span>
+  <span slot="label">
+    Element label (default text will be read by screen reader)
+  </span>
+  <div slot="trigger">
+    Trigger
+  </div>
+</auro-dropdown>
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Snowflake
+## Common use with popover content wider than the trigger
 
-Only supports `ondark`.
+This common example uses the default `auro-dropdown` element with the attributes of `bordered` `rounded` `inset` `toggle` and `chevron`. Additionally the trigger is full width of the containing element and the popover content is set to a width wider than the trigger.
 
-<div class="exampleWrapper--ondark">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/snowflake/basic.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/snowflake/basic.html -->
-  <auro-dropdown aria-label="custom label" shape="snowflake" size="lg" layout="snowflake" style="width: 249px;" ondark>
-    Lorem ipsum solar
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/widerPopover.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/widerPopover.html -->
+  <div style="width: 250px;">
+    <auro-dropdown common aria-label="Label content for screen reader">
+      <div style="padding: var(--ds-size-150); width: 500px;">
+        This is special content.
+      </div>
+      <span slot="helpText">
+        Help text
+      </span>
+      <div slot="trigger">
+        Trigger
+      </div>
+    </auro-dropdown>
+  </div>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/widerPopover.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/widerPopover.html -->
+
+```html
+<div style="width: 250px;">
+  <auro-dropdown common aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150); width: 500px;">
+      This is special content.
+    </div>
+    <span slot="helpText">
+      Help text
+    </span>
     <div slot="trigger">
       Trigger
     </div>
+  </auro-dropdown>
+</div>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## Common use with popover width matching the trigger
+
+This common example uses the default `auro-dropdown` element with the attributes of `bordered` `rounded` `inset` `toggle` and `chevron`. Additionally  `matchWidth` attribute is used to make the popover match the width of the trigger.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/commonMatchWidth.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/commonMatchWidth.html -->
+  <auro-dropdown id="common" common fluid matchWidth aria-label="Label content for screen reader">
+    <div style="padding: var(--ds-size-150);">
+      Lorem ipsum solar
+      <br />
+      <auro-button onclick="document.querySelector('#common').hide()">
+        Dismiss Dropdown
+      </auro-button>
+    </div>
     <span slot="helpText">
-      Help text - Lorem ipsum solar lorem ipsum solar
+      Help text
     </span>
+    <div slot="trigger">
+      Trigger
+    </div>
   </auro-dropdown>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/snowflake/basic.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/snowflake/basic.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/commonMatchWidth.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/commonMatchWidth.html -->
 
 ```html
-<auro-dropdown aria-label="custom label" shape="snowflake" size="lg" layout="snowflake" style="width: 249px;" ondark>
-  Lorem ipsum solar
-  <div slot="trigger">
-    Trigger
+<auro-dropdown id="common" common fluid matchWidth aria-label="Label content for screen reader">
+  <div style="padding: var(--ds-size-150);">
+    Lorem ipsum solar
+    <br />
+    <auro-button onclick="document.querySelector('#common').hide()">
+      Dismiss Dropdown
+    </auro-button>
   </div>
   <span slot="helpText">
-    Help text - Lorem ipsum solar lorem ipsum solar
+    Help text
   </span>
+  <div slot="trigger">
+    Trigger
+  </div>
 </auro-dropdown>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+## Common use with its width matching the trigger
+
+To make the dropdown to be just big as the trigger's content, style the `auro-dropdown` width `display: inline-block`.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inline.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/inline.html -->
+  <table style="text-align: center;">
+    <thead>
+      <tr>
+        <td>Icon Only</td>
+        <td>Text Only</td>
+        <td>Text with Icon</td>
+      </tr>
+    </thead>
+    <tr>
+      <td>
+        <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+          Icon Only Dropdown
+          <div slot="trigger">
+            <auro-icon category="interface" name="arrow-down"></auro-icon>
+          </div>
+        </auro-dropdown>
+      </td>
+      <td>
+        <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+          Text Only Dropdown
+          <div slot="trigger">
+            Trigger Text
+          </div>
+        </auro-dropdown>
+      </td>
+      <td>
+        <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+          Icon and Text Dropdown
+          <div slot="trigger">
+            <div style="white-space:nowrap">
+              Trigger Text
+              <auro-icon category="interface" name="arrow-down"></auro-icon>
+            </div>
+          </div>
+        </auro-dropdown>
+      </td>
+    </tr>
+  </table>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/inline.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/inline.html -->
+
+```html
+<table style="text-align: center;">
+  <thead>
+    <tr>
+      <td>Icon Only</td>
+      <td>Text Only</td>
+      <td>Text with Icon</td>
+    </tr>
+  </thead>
+  <tr>
+    <td>
+      <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+        Icon Only Dropdown
+        <div slot="trigger">
+          <auro-icon category="interface" name="arrow-down"></auro-icon>
+        </div>
+      </auro-dropdown>
+    </td>
+    <td>
+      <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+        Text Only Dropdown
+        <div slot="trigger">
+          Trigger Text
+        </div>
+      </auro-dropdown>
+    </td>
+    <td>
+      <auro-dropdown aria-div="custom div" inset style="display: inline-block;">
+        Icon and Text Dropdown
+        <div slot="trigger">
+          <div style="white-space:nowrap">
+            Trigger Text
+            <auro-icon category="interface" name="arrow-down"></auro-icon>
+          </div>
+        </div>
+      </auro-dropdown>
+    </td>
+  </tr>
+</table>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Triggering a fullscreen dropdown
 This example shows how to set a dropdown fullscreen breakpoint attribute. Most consuming components use `sm` by default, but
 dropdown supports `xs`, `sm`, `md`, `lg`, `xl` and `disabled`, with `disabled` ensuring that the dropdown will never be fullscreen.
@@ -247,7 +564,7 @@ dropdown supports `xs`, `sm`, `md`, `lg`, `xl` and `disabled`, with `disabled` e
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/fullscreen.html) -->
   <!-- The below content is automatically added from ./../apiExamples/fullscreen.html -->
   <h3>Never fullscreen</h3>
-  <auro-dropdown id="common-never-fullscreen" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader" fullscreenBreakpoint="disabled">
+  <auro-dropdown id="common-never-fullscreen" common aria-label="Label content for screen reader" fullscreenBreakpoint="disabled">
     <div style="padding: var(--ds-size-150);">
       Lorem ipsum solar
       <br />
@@ -263,7 +580,7 @@ dropdown supports `xs`, `sm`, `md`, `lg`, `xl` and `disabled`, with `disabled` e
     </div>
   </auro-dropdown>
   <h3>Always fullscreen</h3>
-  <auro-dropdown id="common-always-fullscreen" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader" fullscreenBreakpoint="xl">
+  <auro-dropdown id="common-always-fullscreen" common aria-label="Label content for screen reader" fullscreenBreakpoint="xl">
     <div style="padding: var(--ds-size-150);">
       Lorem ipsum solar
       <br />
@@ -287,7 +604,7 @@ dropdown supports `xs`, `sm`, `md`, `lg`, `xl` and `disabled`, with `disabled` e
 
 ```html
 <h3>Never fullscreen</h3>
-<auro-dropdown id="common-never-fullscreen" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader" fullscreenBreakpoint="disabled">
+<auro-dropdown id="common-never-fullscreen" common aria-label="Label content for screen reader" fullscreenBreakpoint="disabled">
   <div style="padding: var(--ds-size-150);">
     Lorem ipsum solar
     <br />
@@ -303,7 +620,7 @@ dropdown supports `xs`, `sm`, `md`, `lg`, `xl` and `disabled`, with `disabled` e
   </div>
 </auro-dropdown>
 <h3>Always fullscreen</h3>
-<auro-dropdown id="common-always-fullscreen" layout="classic" shape="classic" size="lg" aria-label="Label content for screen reader" fullscreenBreakpoint="xl">
+<auro-dropdown id="common-always-fullscreen" common aria-label="Label content for screen reader" fullscreenBreakpoint="xl">
   <div style="padding: var(--ds-size-150);">
     Lorem ipsum solar
     <br />
@@ -333,5 +650,6 @@ The dropdown can be opened with the following actions:
 The dropdown can be closed with the following actions:
 
 1. Clicking anywhere in the view outside of the dropdown.
+1. Clicking on the trigger when the `toggle` attribute is used.
 1. Using the `esc` key.
 1. Programmatically via another control in the UI calling the `hide()` method (see api).