@aurodesignsystem/auro-formkit 5.9.1 → 5.9.2

package/components/menu/demo/api.min.js

@@ -21,49 +21,6 @@ function auroMenuMatchWordExample() {
   matchWordInput.addEventListener('keyup', updateMatch);
 }
 
-function auroMenuCustomEventExample() {
-  let menuCustomEventEl = document.querySelector('auro-menu#customEvent');
-
-  if (menuCustomEventEl) {
-    menuCustomEventEl.addEventListener('mycustomevent', () => {
-      console.warn('My Custom Event Fired');
-      alert(`My Custom Event Fired`);
-    });
-  }
-}
-
-function auroMenuLoadingExample() {
-  document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => {
-    document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading"));
-  });
-}
-
-const initSelectAllMatchingOptionsExample = () => {
-
-  const selectAllBtn = document.getElementById('selectAllBtn');
-  const selectAllMenu = document.getElementById('selectAllMenu');
-  const selectFirstBtn = document.getElementById('selectFirstBtn');
-  const selectFirstMenu = document.getElementById('selectFirstMenu');
-  const resetAllBtn = document.getElementById('resetAllBtn');
-  const resetFirstBtn = document.getElementById('resetFirstBtn');
-
-  selectAllBtn.addEventListener('click', () => {
-    selectAllMenu.value = 'stops';
-  });
-
-  resetAllBtn.addEventListener('click', () => {
-    selectAllMenu.reset();
-  });
-
-  selectFirstBtn.addEventListener('click', () => {
-    selectFirstMenu.value = 'stops';
-  });
-
-  resetFirstBtn.addEventListener('click', () => {
-    selectFirstMenu.reset();
-  });
-};
-
 function initKeysExample() {
   const menu = document.getElementById('keys-menu');
   const stopsButton = document.getElementById('stopsButton');
@@ -101,6 +58,38 @@ function initKeysExample() {
   });
 }
 
+function auroMenuLoadingExample() {
+  document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => {
+    document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading"));
+  });
+}
+
+const initSelectAllMatchingOptionsExample = () => {
+
+  const selectAllBtn = document.getElementById('selectAllBtn');
+  const selectAllMenu = document.getElementById('selectAllMenu');
+  const selectFirstBtn = document.getElementById('selectFirstBtn');
+  const selectFirstMenu = document.getElementById('selectFirstMenu');
+  const resetAllBtn = document.getElementById('resetAllBtn');
+  const resetFirstBtn = document.getElementById('resetFirstBtn');
+
+  selectAllBtn.addEventListener('click', () => {
+    selectAllMenu.value = 'stops';
+  });
+
+  resetAllBtn.addEventListener('click', () => {
+    selectAllMenu.reset();
+  });
+
+  selectFirstBtn.addEventListener('click', () => {
+    selectFirstMenu.value = 'stops';
+  });
+
+  resetFirstBtn.addEventListener('click', () => {
+    selectFirstMenu.reset();
+  });
+};
+
 /**
  * @license
  * Copyright 2019 Google LLC
@@ -480,12 +469,9 @@ function dispatchMenuEvent(element, eventName, detail = null) {
 
 
 /**
- * The auro-menu element provides users a way to define a menu option.
+ * The `auro-menuoption` element provides users a way to define a menu option.
+ * @customElement auro-menuoption
  *
- * @attr {String} value - Specifies the value to be sent to a server.
- * @attr {String} noCheckmark - When true, selected option will not show the checkmark.
- * @attr {Boolean} disabled - When true specifies that the menuoption is disabled.
- * @attr {Boolean} selected - Specifies that an option is selected.
  * @event auroMenuOption-mouseover - Notifies that this option has been hovered over.
  * @slot - Specifies text for an option, but is not the value.
  */
@@ -493,7 +479,7 @@ class AuroMenuOption extends AuroElement {
 
   /**
    * This will register this element with the browser.
-   * @param {string} [name="auro-menuoption"] - The name of element that you want to register to.
+   * @param {string} [name="auro-menuoption"] - The name of the element that you want to register.
    *
    * @example
    * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
@@ -557,38 +543,81 @@ class AuroMenuOption extends AuroElement {
   static get properties() {
     return {
       ...super.properties,
+
+      /**
+       * When true, disables the menu option.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * @private
+       */
       event: {
         type: String,
         reflect: true
       },
+
+      /**
+       * @private
+       */
+      layout: {
+        type: String
+      },
+
+      /**
+       * Allows users to set a unique key for the menu option for specified option selection. If no key is provided, the value property will be used.
+       */
       key: {
         type: String,
         reflect: true
       },
+
+      /**
+       * @private
+       */
       menuService: {
         type: Object,
         state: true
       },
+
+      /**
+       * @private
+       */
       matchWord: {
         type: String,
         state: true
       },
+
+      /**
+       * @private
+       */
       noCheckmark: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Specifies that an option is selected.
+       */
       selected: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Specifies the tab index of the menu option.
+       */
       tabIndex: {
         type: Number,
         reflect: true
       },
+
+      /**
+       * Specifies the value to be sent to a server.
+       */
       value: {
         type: String,
         reflect: true
@@ -1539,19 +1568,9 @@ const MenuContext = n$1('menu-context');
 
 
 /**
- * The auro-menu element provides users a way to select from a list of options.
- * @attr {HTMLElement|Array<HTMLElement>} optionSelected - An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
- * @attr {object} optionactive - Specifies the current active menuOption.
- * @attr {string} matchword - Specifies a string used to highlight matched string parts in options.
- * @attr {boolean} disabled - When true, the entire menu and all options are disabled;
- * @attr {boolean} nocheckmark - When true, selected option will not show the checkmark.
- * @attr {boolean} loading - When true, displays a loading state using the loadingIcon and loadingText slots if provided.
- * @attr {boolean} multiselect - When true, the selected option can be multiple options.
- * @attr {boolean} selectAllMatchingOptions - When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
- * @attr {string} value - The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
- * @prop {string} size - Sets the size of the menu. Accepted values are 'sm' and 'md'. Default is 'sm'.
- * @prop {string} shape - Sets the shape of the menu options. Accepted values are 'box' and 'round'. Default is 'box'.
- * @prop {boolean} hasLoadingPlaceholder - Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+ * The `auro-menu` element provides users a way to select from a list of options.
+ * @customElement auro-menu
+ *
  * @event {CustomEvent<Element>} auroMenu-activatedOption - Notifies that a menuoption has been made `active`.
  * @event {CustomEvent<any>} auroMenu-customEventFired - Notifies that a custom event has been fired.
  * @event {CustomEvent<{ loading: boolean; hasLoadingPlaceholder: boolean; }>} auroMenu-loadingChange - Notifies when the loading attribute is changed.
@@ -1642,58 +1661,87 @@ class AuroMenu extends AuroElement {
         type: Boolean,
         reflect: true,
       },
-      noCheckmark: {
-        type: Boolean,
-        reflect: true,
-        attribute: 'nocheckmark'
-      },
+
+      /**
+       * When true, the entire menu and all options are disabled.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+       */
+      hasLoadingPlaceholder: {
+        type: Boolean
+      },
+
+      /**
+       * @private
+       */
+      layout: {
+        type: String
+      },
+
+      /**
+       * Indent level for submenus.
+       * @private
+       */
+      level: {
+        type: Number,
+        reflect: false,
+        attribute: false
+      },
+
+      /**
+       * When true, displays a loading state using the loadingIcon and loadingText slots if provided.
+       */
       loading: {
         type: Boolean,
         reflect: true
       },
-      optionSelected: {
-        // Allow HTMLElement, HTMLElement[] arrays and undefined
-        type: Object
-      },
-      optionActive: {
-        type: Object,
-        attribute: 'optionactive'
-      },
+
+      /**
+       * Specifies a string used to highlight matched string parts in options.
+       */
       matchWord: {
         type: String,
         attribute: 'matchword'
       },
+
+      /**
+       * When true, the selected option can be multiple options.
+       */
       multiSelect: {
         type: Boolean,
         reflect: true,
         attribute: 'multiselect'
       },
-      selectAllMatchingOptions: {
+
+      /**
+       * When true, selected option will not show the checkmark.
+       */
+      noCheckmark: {
         type: Boolean,
         reflect: true,
+        attribute: 'nocheckmark'
       },
 
       /**
-       * Value selected for the component.
+       * Specifies the current active menuOption.
        */
-      value: {
-        type: String,
-        reflect: true,
-        attribute: 'value'
+      optionActive: {
+        type: Object,
+        attribute: 'optionactive'
       },
 
       /**
-       * Indent level for submenus.
-       * @private
+       * An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
        */
-      level: {
-        type: Number,
-        reflect: false,
-        attribute: false
+      optionSelected: {
+        // Allow HTMLElement, HTMLElement[] arrays and undefined
+        type: Object
       },
 
       /**
@@ -1704,6 +1752,43 @@ class AuroMenu extends AuroElement {
         type: Array,
         reflect: false,
         attribute: false
+      },
+
+      /**
+       * Sets the size of the menu.
+       * @type {'sm' | 'md'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        reflect: true
+      },
+
+      /**
+       * When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
+       */
+      selectAllMatchingOptions: {
+        type: Boolean,
+        reflect: true,
+      },
+
+      /**
+       * Sets the shape of the menu.
+       * @type {'box' | 'round'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        reflect: true
+      },
+
+      /**
+       * The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
+       */
+      value: {
+        type: String,
+        reflect: true,
+        attribute: 'value'
       }
     };
   }
@@ -1749,7 +1834,7 @@ class AuroMenu extends AuroElement {
 
   /**
    * This will register this element with the browser.
-   * @param {string} [name="auro-menu"] - The name of element that you want to register to.
+   * @param {string} [name="auro-menu"] - The name of the element that you want to register.
    *
    * @example
    * AuroMenu.register("custom-menu") // this will register this element to <custom-menu/>
@@ -2167,12 +2252,11 @@ function initExamples(initCount) {
 
   try {
     // javascript example function calls to be added here upon creation to test examples
-    auroMenuResetExample();
-    auroMenuMatchWordExample();
-    auroMenuCustomEventExample();
+    initKeysExample();
     auroMenuLoadingExample();
+    auroMenuMatchWordExample();
     initSelectAllMatchingOptionsExample();
-    initKeysExample();
+    auroMenuResetExample();
   } catch (err) {
     if (initCount <= 20) {
       // setTimeout handles issue where content is sometimes loaded after the functions get called

package/components/menu/demo/index.js

@@ -1,10 +1,7 @@
 /* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
 
-// import { auroMenuResetExample } from '../apiExamples/reset';
-
 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,8 +13,6 @@ 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

@@ -1,11 +1,11 @@
 <!--
-The demo.md file is a compiled document. No edits should be made directly to this file.
-README.md is created by running `npm run build:docs`.
-This file is generated based on a template fetched from `./docs/partials/demo.md`
+ THIS PAGE'S CONTENT SHOULD BE KEPT MINIMAL.
+ ONLY ADD EXAMPLES THAT ARE TRULY NECESSARY FOR THE INDEX PAGE — THE BASIC EXAMPLE IS USUALLY ENOUGH.
+ ALL OTHER EXAMPLES SHOULD GO IN THE API DOCUMENTATION.
 -->
 
-# Menu
-
+# Menu
+
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
 <!-- The below content is automatically added from ./../docs/partials/description.md -->
 The `<auro-menu>` element provides a list of options for a user to select from.
@@ -15,8 +15,8 @@ A list of options is created within the `<slot>` of the `<auro-menu>` element by
 The `<auro-menu>` element is designed for contextual menus, e.g. a dropdown menus. They are not intended to be used for navigation menus which have a different semantic meaning. The `<auro-menu>` element does not support hide/show functionality within its scope. This functionality will be managed by a wrapping element such as a drop-down menu composite element.
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## auro-menu use cases
-
+## Use Cases
+
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/useCases.md) -->
 <!-- The below content is automatically added from ./../docs/partials/useCases.md -->
 The `<auro-menu>` element should be used in situations where users may:
@@ -26,130 +26,47 @@ The `<auro-menu>` element should be used in situations where users may:
 
 ## Example(s)
 
-### Default
-
-A basic `auro-menu` element with nested `auro-menuoption` elements to generate a list.
-
+### Basic
+
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/basic.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/preselect.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/preselect.html -->
   <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="new tab">New tab</auro-menuoption>
+    <auro-menuoption value="new window" selected>New window</auro-menuoption>
+    <auro-menuoption value="open file">Open file</auro-menuoption>
+    <auro-menuoption value="open location">Open location</auro-menuoption>
+    <hr>
+    <auro-menuoption value="close window">Close window</auro-menuoption>
+    <auro-menuoption value="close tab" disabled>Close tab</auro-menuoption>
+    <auro-menuoption value="save page as...">Save page as...</auro-menuoption>
+    <hr>
+    <auro-menuoption value="share" disabled>Share</auro-menuoption>
+    <hr>
+    <auro-menuoption value="print">Print</auro-menuoption>
   </auro-menu>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/preselect.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/preselect.html -->
 
 ```html
 <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-menu>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-### 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>
+  <auro-menuoption value="new tab">New tab</auro-menuoption>
+  <auro-menuoption value="new window" selected>New window</auro-menuoption>
+  <auro-menuoption value="open file">Open file</auro-menuoption>
+  <auro-menuoption value="open location">Open location</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>
+  <auro-menuoption value="close window">Close window</auro-menuoption>
+  <auro-menuoption value="close tab" disabled>Close tab</auro-menuoption>
+  <auro-menuoption value="save page as...">Save page as...</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-menuoption value="share" disabled>Share</auro-menuoption>
+  <hr>
+  <auro-menuoption value="print">Print</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>
+</auro-accordion>