@aurodesignsystem/auro-formkit 5.8.1 → 5.9.1

package/components/menu/demo/index.html

@@ -50,6 +50,7 @@
     </script>
 
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/+esm" type="module"></script>
     <script type="module" data-demo-script="true">
       import { initExamples } from "./index.min.js"
       initExamples();

package/components/menu/demo/index.js

@@ -4,6 +4,7 @@
 
 import { AuroMenu } from '../src/auro-menu.js';
 import { AuroMenuOption } from '../src/auro-menuoption.js';
+import { initKeysExample } from '../apiExamples/keys.js';
 
 AuroMenu.register();
 AuroMenuOption.register();
@@ -16,6 +17,7 @@ export function initExamples(initCount) {
   try {
     // javascript example function calls to be added here upon creation to test examples
     // auroMenuResetExample();
+    initKeysExample();
   } catch (err) {
     if (initCount <= 20) {
       // setTimeout handles issue where content is sometimes loaded after the functions get called

package/components/menu/demo/index.md

@@ -58,4 +58,98 @@ A basic `auro-menu` element with nested `auro-menuoption` elements to generate a
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
-Having a closing statement about your example helps to really complete the thought with your reader.
+
+### Using Keys
+
+When setting the `value` property, matches are actually performed on the value of the `key` property of the `auro-menuoption` and not the `value` property. By default, the value of `key` is equal to the value of the `value` property. However, for advanced use cases, the `key` value can be overriden to allow for more specific matches.
+
+In the below example, there is a list of "popular" options at the top, with the same values repeated underneath. To allow more specific selections, we can add a `key` attribute to the top options to allow them to be more specifically selected, or to prevent them from interfering with matches on the lower options.
+
+In the below example, setting the value of the menu `'stops'` will select the bottom-most option with the value `'stops'`, and setting the value of menu to `'stops-top'` will select the top-most option with the value `'stops'` since the key now differs from the value. In either case, the resulting value of the menu will be `'stops'` because the resulting value of the menu is based on the `value` property and not the `key` property.
+
+Due to a limitation with Lit change detection to the `value` property, if multiple options with the same exist and one is selected, you must first clear the current value before attempting to select another option with the same value, even if the keys are unique. See code example below.
+
+_Note: Since the value passed to the `value` property when programmatically setting it is overwritten with the proper derived value once the menu has updated, note that it will take one lifecycle before the `value` property is updated to the value that represents the actual menu state._
+
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/keys.html) -->
+<!-- The below content is automatically added from ./../apiExamples/keys.html -->
+<auro-button id="stopsTopButton">Call `menu.value = 'stops-top'`</auro-button>
+<auro-button id="stopsButton">Call `menu.value = 'stops'`</auro-button>
+<auro-menu id="keys-menu">
+  <auro-menuoption value="stops" key="stops-top">Stops</auro-menuoption>
+  <auro-menuoption value="price" key="price-top">Price</auro-menuoption>
+  <hr>
+  <auro-menuoption value="duration">Duration</auro-menuoption>
+  <auro-menuoption value="departure">Departure</auro-menuoption>
+  <auro-menuoption value="arrival">Arrival</auro-menuoption>
+  <auro-menuoption value="stops">Stops</auro-menuoption>
+  <auro-menuoption value="price">Price</auro-menuoption>
+</auro-menu>
+<p id="output" class="body-sm"></p>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/keys.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/keys.html -->
+
+```html
+<auro-button id="stopsTopButton">Call `menu.value = 'stops-top'`</auro-button>
+<auro-button id="stopsButton">Call `menu.value = 'stops'`</auro-button>
+<auro-menu id="keys-menu">
+  <auro-menuoption value="stops" key="stops-top">Stops</auro-menuoption>
+  <auro-menuoption value="price" key="price-top">Price</auro-menuoption>
+  <hr>
+  <auro-menuoption value="duration">Duration</auro-menuoption>
+  <auro-menuoption value="departure">Departure</auro-menuoption>
+  <auro-menuoption value="arrival">Arrival</auro-menuoption>
+  <auro-menuoption value="stops">Stops</auro-menuoption>
+  <auro-menuoption value="price">Price</auro-menuoption>
+</auro-menu>
+<p id="output" class="body-sm"></p>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/keys.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/keys.js -->
+
+```js
+export function initKeysExample() {
+  const menu = document.getElementById('keys-menu');
+  const stopsButton = document.getElementById('stopsButton');
+  const stopsTopButton = document.getElementById('stopsTopButton');
+  const output = document.getElementById('output');
+
+  const createConsoleEntry = (message) => {
+    const node = document.createElement('span');
+    node.innerHTML = message;
+    output.appendChild(node);
+    output.appendChild(document.createElement('br'));
+  };
+
+  const resetConsole = () => {
+    output.innerHTML = '';
+  };
+
+  const updateMenuValue = (value) => {
+    resetConsole();
+    createConsoleEntry(`Setting menu.value: <em>"${value}"</em>`);
+    menu.value = '';
+    menu.value = value;
+    createConsoleEntry(`menu.value before next lifecycle: <em>"${menu.value}"</em>`);
+    setTimeout(() => {
+      createConsoleEntry(`menu.value after lifecycle: <em>"${menu.value}"</em>`);
+    });
+  };
+
+  stopsButton.addEventListener('click', () => {
+    updateMenuValue('stops');
+  });
+
+  stopsTopButton.addEventListener('click', () => {
+    updateMenuValue('stops-top');
+  });
+};
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>