@aurodesignsystem/auro-formkit 6.1.0 → 6.2.0

package/components/layoutElement/dist/auroElement.d.ts

@@ -1,24 +1,17 @@
+/**
+ * AuroElement is the shared base class for layout-aware Auro form components.
+ *
+ * It defines the common `layout`, `shape`, `size`, and `ondark` reactive
+ * properties and the architecture helpers (`renderLayout`, `resetShapeClasses`,
+ * `resetLayoutClasses`) that subclasses use to render a chosen layout and apply
+ * the matching `shape-*` / `layout-*` wrapper classes. Subclasses supply their
+ * own default and valid value set for `layout`, `shape`, and `size`.
+ */
 export class AuroElement extends LitElement {
     static get properties(): {
         /**
-         * Defines the language of an element.
-         * @default {'default'}
+         * When true, renders the component styled for use on a dark background.
          */
-        layout: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
-        shape: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
-        size: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
         onDark: {
             type: BooleanConstructor;
             attribute: string;

package/components/layoutElement/dist/index.js

@@ -1,36 +1,36 @@
 import { LitElement } from 'lit';
 
+/**
+ * AuroElement is the shared base class for layout-aware Auro form components.
+ *
+ * It defines the common `layout`, `shape`, `size`, and `ondark` reactive
+ * properties and the architecture helpers (`renderLayout`, `resetShapeClasses`,
+ * `resetLayoutClasses`) that subclasses use to render a chosen layout and apply
+ * the matching `shape-*` / `layout-*` wrapper classes. Subclasses supply their
+ * own default and valid value set for `layout`, `shape`, and `size`.
+ */
 class AuroElement extends LitElement {
   static get properties() {
     return {
 
       /**
-       * Defines the language of an element.
-       * @default {'default'}
+       * When true, renders the component styled for use on a dark background.
        */
-      layout: {
-        type: String,
-        attribute: "layout",
-        reflect: true
-      },
-
-      shape: {
-        type: String,
-        attribute: "shape",
-        reflect: true
-      },
-
-      size: {
-        type: String,
-        attribute: "size",
-        reflect: true
-      },
-
       onDark: {
         type: Boolean,
         attribute: "ondark",
         reflect: true
       }
+
+      // NOTE: `layout`, `shape`, and `size` are intentionally NOT declared here.
+      // Their valid value sets differ per component, and the CEM analyzer roots
+      // an inherited property's `type` in the class that declares it — a base
+      // declaration would force every subclass's `@type` to be discarded and
+      // emitted as plain `string`. Each subclass declares its own `layout` /
+      // `shape` / `size` with an exact `@type` union instead. AuroElement still
+      // consumes `this.layout` / `this.shape` / `this.size` in its render and
+      // architecture helpers below (subclasses guarantee the reactive props).
+      // See AlaskaAirlines/discussions#653.
     };
   }
 

package/components/layoutElement/dist/registered.js

@@ -1,36 +1,36 @@
 import { LitElement } from 'lit';
 
+/**
+ * AuroElement is the shared base class for layout-aware Auro form components.
+ *
+ * It defines the common `layout`, `shape`, `size`, and `ondark` reactive
+ * properties and the architecture helpers (`renderLayout`, `resetShapeClasses`,
+ * `resetLayoutClasses`) that subclasses use to render a chosen layout and apply
+ * the matching `shape-*` / `layout-*` wrapper classes. Subclasses supply their
+ * own default and valid value set for `layout`, `shape`, and `size`.
+ */
 class AuroElement extends LitElement {
   static get properties() {
     return {
 
       /**
-       * Defines the language of an element.
-       * @default {'default'}
+       * When true, renders the component styled for use on a dark background.
        */
-      layout: {
-        type: String,
-        attribute: "layout",
-        reflect: true
-      },
-
-      shape: {
-        type: String,
-        attribute: "shape",
-        reflect: true
-      },
-
-      size: {
-        type: String,
-        attribute: "size",
-        reflect: true
-      },
-
       onDark: {
         type: Boolean,
         attribute: "ondark",
         reflect: true
       }
+
+      // NOTE: `layout`, `shape`, and `size` are intentionally NOT declared here.
+      // Their valid value sets differ per component, and the CEM analyzer roots
+      // an inherited property's `type` in the class that declares it — a base
+      // declaration would force every subclass's `@type` to be discarded and
+      // emitted as plain `string`. Each subclass declares its own `layout` /
+      // `shape` / `size` with an exact `@type` union instead. AuroElement still
+      // consumes `this.layout` / `this.shape` / `this.size` in its render and
+      // architecture helpers below (subclasses guarantee the reactive props).
+      // See AlaskaAirlines/discussions#653.
     };
   }
 

package/components/menu/demo/api.md

@@ -7,32 +7,35 @@ The `auro-menu` element provides users a way to select from a list of options.
 
 ## Properties
 
-| Property                | Attribute     | Modifiers | Type                  | Default     | Description                                      |
-|-------------------------|---------------|-----------|-----------------------|-------------|--------------------------------------------------|
-| `currentLabel`          |               | readonly  | `string`              |             |                                                  |
-| `disabled`              | `disabled`    |           | `boolean`             |             | When true, the entire menu and all options are disabled. |
-| `hasLoadingPlaceholder` |               | readonly  | `boolean`             |             | Getter for loading placeholder state.            |
-| `index`                 |               |           | `number`              |             |                                                  |
-| `layout`                |               |           | `string`              |             |                                                  |
-| `loading`               | `loading`     |           | `boolean`             | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
-| `matchWord`             | `matchword`   |           | `string`              | "undefined" | Specifies a string used to highlight matched string parts in options. |
-| `multiSelect`           | `multiselect` |           | `boolean`             | false       | When true, the selected option can be multiple options. |
-| `noCheckmark`           | `nocheckmark` |           | `boolean`             | false       | When true, selected option will not show the checkmark. |
-| `optionActive`          |               |           | `object`              | "undefined" | Specifies the current active menuOption.         |
-| `optionSelected`        |               |           | `object`              | "undefined" | The currently selected menu option(s). In single-select mode this is a single `HTMLElement` (or `undefined` when nothing is selected). In multi-select mode this is an array of `HTMLElement`s. |
-| `options`               |               | readonly  | `HTMLElement[]`       |             |                                                  |
-| `selectedOption`        |               | readonly  | `HTMLElement \| null` |             | Gets the first selected option, or null if none. |
-| `selectedOptions`       |               | readonly  | `HTMLElement[]`       |             | Gets the currently selected options as an array. |
-| `value`                 | `value`       |           | `string`              | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.<br />Options marked `disabled` or `static` are not selectable by value; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared (`optionSelected` becomes `undefined`) and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped from the value and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. |
+| Property                | Attribute     | Modifiers | Type                                   | Default     | Description                                      |
+|-------------------------|---------------|-----------|----------------------------------------|-------------|--------------------------------------------------|
+| `currentLabel`          |               | readonly  | `string`                               |             |                                                  |
+| `disabled`              | `disabled`    |           | `boolean`                              |             | When true, the entire menu and all options are disabled. |
+| `hasLoadingPlaceholder` |               | readonly  | `boolean`                              |             | Getter for loading placeholder state.            |
+| `index`                 |               |           | `number`                               |             |                                                  |
+| `layout`                | `layout`      |           | `string`                               |             | Applies a named layout variant to the menu. Free-form string consumed by the shared architecture helpers; menu defines no closed value set. |
+| `loading`               | `loading`     |           | `boolean`                              | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
+| `matchWord`             | `matchword`   |           | `string`                               | "undefined" | Specifies a string used to highlight matched string parts in options. |
+| `multiSelect`           | `multiselect` |           | `boolean`                              | false       | When true, the selected option can be multiple options. |
+| `noCheckmark`           | `nocheckmark` |           | `boolean`                              | false       | When true, selected option will not show the checkmark. |
+| `optionActive`          |               |           | `HTMLElement`                          | "undefined" | Specifies the current active menuOption.         |
+| `optionSelected`        |               |           | `HTMLElement \| HTMLElement[]`         | "undefined" | The currently selected menu option(s). In single-select mode this is a single `HTMLElement` (or `undefined` when nothing is selected). In multi-select mode this is an array of `HTMLElement`s. |
+| `options`               |               | readonly  | `HTMLElement[]`                        |             |                                                  |
+| `selectedOption`        |               | readonly  | `HTMLElement \| null`                  |             | Gets the first selected option, or null if none. |
+| `selectedOptions`       |               | readonly  | `HTMLElement[]`                        |             | Gets the currently selected options as an array. |
+| `shape`                 | `shape`       |           | `'box' \| 'pill' \| 'snowflake'`       | "'box'"     | Sets the shape of the menu options.              |
+| `size`                  | `size`        |           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | "'sm'"      | Sets the size of the menu options.               |
+| `value`                 | `value`       |           | `string`                               | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.<br />Options marked `disabled` or `static` are not selectable by value; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared (`optionSelected` becomes `undefined`) and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped from the value and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. |
 
 ## Methods
 
-| Method               | Type                                             | Description                                      |
-|----------------------|--------------------------------------------------|--------------------------------------------------|
-| `navigateOptions`    | `(direction: string): void`                      | Navigates through options using keyboard.<br /><br />**direction**: 'up' or 'down'. |
-| `reset`              | `(): void`                                       | Resets the menu to its initial state.<br />This is the only way to return value to undefined. |
-| `selectByValue`      | `(value: string \| string[] \| null \| undefined): void` | Selects options by value. Options marked `disabled` or `static` are not selectable; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. Passing `undefined`, `null`, an empty string, or an empty array clears the selection without dispatching a failure.<br /><br />**value**: The value(s) to select. |
-| `updateActiveOption` | `(indexOrOption: number \| HTMLElement): void`   | Updates the active option state and dispatches events.<br />Accepts either a numeric index or an HTMLElement option.<br /><br />**indexOrOption**: Index of the option or the option element to make active. |
+| Method                           | Type                                             | Description                                      |
+|----------------------------------|--------------------------------------------------|--------------------------------------------------|
+| `initializeArchitectureDefaults` | `(): void`                                       |                                                  |
+| `navigateOptions`                | `(direction: string): void`                      | Navigates through options using keyboard.<br /><br />**direction**: 'up' or 'down'. |
+| `reset`                          | `(): void`                                       | Resets the menu to its initial state.<br />This is the only way to return value to undefined. |
+| `selectByValue`                  | `(value: string \| string[] \| null \| undefined): void` | Selects options by value. Options marked `disabled` or `static` are not selectable; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. Passing `undefined`, `null`, an empty string, or an empty array clears the selection without dispatching a failure.<br /><br />**value**: The value(s) to select. |
+| `updateActiveOption`             | `(indexOrOption: number \| HTMLElement): void`   | Updates the active option state and dispatches events.<br />Accepts either a numeric index or an HTMLElement option.<br /><br />**indexOrOption**: Index of the option or the option element to make active. |
 
 ## Events
 
@@ -41,7 +44,7 @@ The `auro-menu` element provides users a way to select from a list of options.
 | `auroMenu-activatedOption`    | `CustomEvent<Element>`                           | Notifies that a menuoption has been made `active`. |
 | `auroMenu-customEventFired`   | `CustomEvent<any>`                               | Notifies that a custom event has been fired.     |
 | `auroMenu-loadingChange`      | `CustomEvent<{ loading: boolean; hasLoadingPlaceholder: boolean; }>` | Notifies when the loading attribute is changed.  |
-| `auroMenu-optionsChange`      | `CustomEvent<{ options: Element[] \| undefined; }>` |                                                  |
+| `auroMenu-optionsChange`      | `CustomEvent<{ options: Array<HTMLElement> }>`   | Notifies that the set of available menu options has changed. |
 | `auroMenu-selectValueFailure` | `CustomEvent<any>`                               | Notifies that an attempt to select a menuoption by matching a value has failed. |
 | `auroMenu-selectValueReset`   | `CustomEvent<any>`                               | Notifies that the component value has been reset. |
 | `auroMenu-selectedOption`     | `CustomEvent<any>`                               | Notifies that a new menuoption selection has been made. |
@@ -68,15 +71,16 @@ The `auro-menuoption` element provides users a way to define a menu option.
 
 | Property      | Attribute     | Modifiers | Type      | Default | Description                                      |
 |---------------|---------------|-----------|-----------|---------|--------------------------------------------------|
-| `disabled`    | `disabled`    |           | `boolean` | false   |                                                  |
+| `disabled`    | `disabled`    |           | `boolean` | false   | When true, the option is disabled and cannot be selected. |
+| `event`       | `event`       |           | `string`  |         | When set, selecting this option dispatches a custom event of the given name from the parent `auro-menu` (and an `auroMenu-customEventFired` event) instead of selecting the option. |
 | `iconTag`     |               |           |           |         |                                                  |
 | `isActive`    |               | readonly  | `boolean` |         | Returns whether the menu option is currently active and selectable. |
 | `layout`      |               |           | `string`  |         |                                                  |
-| `noCheckmark` | `noCheckmark` |           | `boolean` | false   |                                                  |
+| `noCheckmark` | `nocheckmark` |           | `boolean` | false   | When true, this option will not show the checkmark when selected. |
 | `noMatch`     | `nomatch`     |           | `boolean` | false   | When true, marks this option as the "no matching results" placeholder shown by combobox<br />when the user's input does not match any available options. |
 | `persistent`  | `persistent`  |           | `boolean` | false   | When true, this option is excluded from `matchWord` DOM rewriting — useful for utility rows (e.g., "Add new…") that must render identically regardless of the current filter. |
 | `selected`    | `selected`    |           | `boolean` | false   | **Deprecated.** Use the `value` attribute on `auro-menu` to set the selected option when the menu renders (or call `menu.selectByValue(value)` programmatically). Support for the child-level `selected` attribute will be removed in a future major release. |
-| `value`       | `value`       |           | `string`  |         |                                                  |
+| `value`       | `value`       |           | `string`  |         | The value associated with this menu option.      |
 
 ## Methods