@aurodesignsystem-dev/auro-formkit 0.0.0-pr1594.2 → 0.0.0-pr1595.0

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`          |               |           | `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. |
+| `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 }>`                | 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,15 @@ 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. |
 | `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
 

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

@@ -30,37 +30,37 @@ var colorCss$1 = i$5`:host ::slotted(hr){border-top-color:var(--ds-auro-menu-div
 
 var tokensCss = i$5`:host{--ds-auro-menu-divider-color: var(--ds-basic-color-border-divider, rgba(0, 0, 0, 0.15));--ds-auro-menu-loader-color: var(--ds-basic-color-brand-primary, #01426a);--ds-auro-menu-loader-text-color: var(--ds-basic-color-texticon-default, #2a2a2a);--ds-auro-menuoption-container-color: transparent;--ds-auro-menuoption-container-border-color: var(--ds-auro-menuoption-container-color);--ds-auro-menuoption-icon-color: transparent;--ds-auro-menuoption-text-color: var(--ds-basic-color-texticon-default, #2a2a2a)}`;
 
+/**
+ * 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 i$2 {
   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.
     };
   }
 
@@ -423,6 +423,7 @@ let menuInstanceIdCounter = 0;
  * @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.
+ * @event {CustomEvent<{ options: Array }>} auroMenu-optionsChange - Notifies that the set of available menu options has changed.
  * @event {CustomEvent<any>} auroMenu-selectValueFailure - Notifies that an attempt to select a menuoption by matching a value has failed.
  * @event {CustomEvent<any>} auroMenu-selectValueReset - Notifies that the component value has been reset.
  * @event {CustomEvent<any>} auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
@@ -437,15 +438,7 @@ class AuroMenu extends AuroElement {
 
     // State properties (reactive)
 
-    /**
-     * @private
-     */
-    this.shape = "box";
-
-    /**
-     * @private
-     */
-    this.size = "sm";
+    this.initializeArchitectureDefaults();
 
     // Value of the selected options
     this.value = undefined;
@@ -486,8 +479,6 @@ class AuroMenu extends AuroElement {
 
     // Instance properties (non-reactive)
 
-    menuInstanceIdCounter += 1;
-
     Object.assign(this, {
       // Root-level menu (true) or a nested submenu (false)
       rootMenu: true,
@@ -499,7 +490,7 @@ class AuroMenu extends AuroElement {
       loadingSlots: null,
       // Unique id for this menu instance; prefixes every auto-generated option
       // key so keys never collide across menus in the same document.
-      _menuInstanceId: `menu-${menuInstanceIdCounter}`,
+      _menuInstanceId: `menu-${menuInstanceIdCounter += 1}`,
       // Monotonically increasing counter for option key generation. Never
       // resets, so a key is never reused within this instance's lifetime.
       _optionKeyCounter: 0,
@@ -515,10 +506,50 @@ class AuroMenu extends AuroElement {
     });
   }
 
+  // Defaults for the layout/shape/size architecture props are set in a helper
+  // (not the constructor body) so the CEM analyzer keeps their `@type` unions
+  // instead of inferring `string` from a constructor-literal assignment.
+  // See AlaskaAirlines/discussions#653.
+  initializeArchitectureDefaults() {
+    this.shape = "box";
+    this.size = "sm";
+  }
+
   static get properties() {
     return {
       ...super.properties,
 
+      /**
+       * Applies a named layout variant to the menu. Free-form string consumed by the shared architecture helpers; menu defines no closed value set.
+       */
+      layout: {
+        type: String,
+        attribute: "layout",
+        reflect: true
+      },
+
+      /**
+       * Sets the shape of the menu options.
+       * @type {'box' | 'pill' | 'snowflake'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        attribute: "shape",
+        reflect: true
+      },
+
+      /**
+       * Sets the size of the menu options.
+       * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        attribute: "size",
+        reflect: true
+      },
+
       /**
        * When true, the entire menu and all options are disabled.
        */
@@ -1853,9 +1884,36 @@ class AuroMenuOption extends AuroElement {
   static get properties() {
     return {
       ...super.properties,
+
+      /**
+       * Sets the shape of the option. When unset, it inherits the shape of the parent `auro-menu`.
+       * @type {'box' | 'pill' | 'snowflake'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        attribute: "shape",
+        reflect: true
+      },
+
+      /**
+       * Sets the size of the option. When unset, it inherits the size of the parent `auro-menu`.
+       * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        attribute: "size",
+        reflect: true
+      },
+
+      /**
+       * When true, this option will not show the checkmark when selected.
+       */
       noCheckmark: {
         type: Boolean,
-        reflect: true
+        reflect: true,
+        attribute: 'nocheckmark'
       },
 
       /**
@@ -1867,17 +1925,30 @@ class AuroMenuOption extends AuroElement {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * When true, the option is disabled and cannot be selected.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * The value associated with this menu option.
+       */
       value: {
         type: String,
         reflect: true
       },
+
+      /**
+       * Sets the tab order of the menu option.
+       */
       tabIndex: {
         type: Number,
-        reflect: true
+        reflect: true,
+        attribute: 'tabindex'
       },
 
       /**

package/components/menu/dist/auro-menu.d.ts

@@ -5,6 +5,7 @@
  * @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.
+ * @event {CustomEvent<{ options: Array }>} auroMenu-optionsChange - Notifies that the set of available menu options has changed.
  * @event {CustomEvent<any>} auroMenu-selectValueFailure - Notifies that an attempt to select a menuoption by matching a value has failed.
  * @event {CustomEvent<any>} auroMenu-selectValueReset - Notifies that the component value has been reset.
  * @event {CustomEvent<any>} auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
@@ -14,6 +15,26 @@
  */
 export class AuroMenu extends AuroElement {
     static get properties(): {
+        /**
+         * Applies a named layout variant to the menu. Free-form string consumed by the shared architecture helpers; menu defines no closed value set.
+         */
+        layout: {
+            type: StringConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
+        /**
+         * Sets the shape of the menu options.
+         * @type {'box' | 'pill' | 'snowflake'}
+         * @default 'box'
+         */
+        shape: "box" | "pill" | "snowflake";
+        /**
+         * Sets the size of the menu options.
+         * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+         * @default 'sm'
+         */
+        size: "xs" | "sm" | "md" | "lg" | "xl";
         /**
          * When true, the entire menu and all options are disabled.
          */
@@ -77,11 +98,6 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
-        layout: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
@@ -93,14 +109,6 @@ export class AuroMenu extends AuroElement {
      *
      */
     static register(name?: string): void;
-    /**
-     * @private
-     */
-    private shape;
-    /**
-     * @private
-     */
-    private size;
     value: any;
     optionSelected: any;
     matchWord: any;
@@ -131,6 +139,9 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private handleSlotChange;
+    initializeArchitectureDefaults(): void;
+    shape: string | undefined;
+    size: string | undefined;
     /**
      * @readonly
      * @returns {Array<HTMLElement>} - Returns the array of available menu options.

package/components/menu/dist/auro-menuoption.d.ts

@@ -10,9 +10,25 @@
  */
 export class AuroMenuOption extends AuroElement {
     static get properties(): {
+        /**
+         * Sets the shape of the option. When unset, it inherits the shape of the parent `auro-menu`.
+         * @type {'box' | 'pill' | 'snowflake'}
+         * @default 'box'
+         */
+        shape: "box" | "pill" | "snowflake";
+        /**
+         * Sets the size of the option. When unset, it inherits the size of the parent `auro-menu`.
+         * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+         * @default 'sm'
+         */
+        size: "xs" | "sm" | "md" | "lg" | "xl";
+        /**
+         * When true, this option will not show the checkmark when selected.
+         */
         noCheckmark: {
             type: BooleanConstructor;
             reflect: boolean;
+            attribute: string;
         };
         /**
          * **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.
@@ -23,17 +39,27 @@ export class AuroMenuOption extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * When true, the option is disabled and cannot be selected.
+         */
         disabled: {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * The value associated with this menu option.
+         */
         value: {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * Sets the tab order of the menu option.
+         */
         tabIndex: {
             type: NumberConstructor;
             reflect: boolean;
+            attribute: string;
         };
         /**
          * @private

package/components/menu/dist/index.js

@@ -9,37 +9,37 @@ var colorCss$1 = css`:host ::slotted(hr){border-top-color:var(--ds-auro-menu-div
 
 var tokensCss = css`:host{--ds-auro-menu-divider-color: var(--ds-basic-color-border-divider, rgba(0, 0, 0, 0.15));--ds-auro-menu-loader-color: var(--ds-basic-color-brand-primary, #01426a);--ds-auro-menu-loader-text-color: var(--ds-basic-color-texticon-default, #2a2a2a);--ds-auro-menuoption-container-color: transparent;--ds-auro-menuoption-container-border-color: var(--ds-auro-menuoption-container-color);--ds-auro-menuoption-icon-color: transparent;--ds-auro-menuoption-text-color: var(--ds-basic-color-texticon-default, #2a2a2a)}`;
 
+/**
+ * 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.
     };
   }
 
@@ -430,6 +430,7 @@ let menuInstanceIdCounter = 0;
  * @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.
+ * @event {CustomEvent<{ options: Array }>} auroMenu-optionsChange - Notifies that the set of available menu options has changed.
  * @event {CustomEvent<any>} auroMenu-selectValueFailure - Notifies that an attempt to select a menuoption by matching a value has failed.
  * @event {CustomEvent<any>} auroMenu-selectValueReset - Notifies that the component value has been reset.
  * @event {CustomEvent<any>} auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
@@ -444,15 +445,7 @@ class AuroMenu extends AuroElement {
 
     // State properties (reactive)
 
-    /**
-     * @private
-     */
-    this.shape = "box";
-
-    /**
-     * @private
-     */
-    this.size = "sm";
+    this.initializeArchitectureDefaults();
 
     // Value of the selected options
     this.value = undefined;
@@ -493,8 +486,6 @@ class AuroMenu extends AuroElement {
 
     // Instance properties (non-reactive)
 
-    menuInstanceIdCounter += 1;
-
     Object.assign(this, {
       // Root-level menu (true) or a nested submenu (false)
       rootMenu: true,
@@ -506,7 +497,7 @@ class AuroMenu extends AuroElement {
       loadingSlots: null,
       // Unique id for this menu instance; prefixes every auto-generated option
       // key so keys never collide across menus in the same document.
-      _menuInstanceId: `menu-${menuInstanceIdCounter}`,
+      _menuInstanceId: `menu-${menuInstanceIdCounter += 1}`,
       // Monotonically increasing counter for option key generation. Never
       // resets, so a key is never reused within this instance's lifetime.
       _optionKeyCounter: 0,
@@ -522,10 +513,50 @@ class AuroMenu extends AuroElement {
     });
   }
 
+  // Defaults for the layout/shape/size architecture props are set in a helper
+  // (not the constructor body) so the CEM analyzer keeps their `@type` unions
+  // instead of inferring `string` from a constructor-literal assignment.
+  // See AlaskaAirlines/discussions#653.
+  initializeArchitectureDefaults() {
+    this.shape = "box";
+    this.size = "sm";
+  }
+
   static get properties() {
     return {
       ...super.properties,
 
+      /**
+       * Applies a named layout variant to the menu. Free-form string consumed by the shared architecture helpers; menu defines no closed value set.
+       */
+      layout: {
+        type: String,
+        attribute: "layout",
+        reflect: true
+      },
+
+      /**
+       * Sets the shape of the menu options.
+       * @type {'box' | 'pill' | 'snowflake'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        attribute: "shape",
+        reflect: true
+      },
+
+      /**
+       * Sets the size of the menu options.
+       * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        attribute: "size",
+        reflect: true
+      },
+
       /**
        * When true, the entire menu and all options are disabled.
        */
@@ -1847,9 +1878,36 @@ class AuroMenuOption extends AuroElement {
   static get properties() {
     return {
       ...super.properties,
+
+      /**
+       * Sets the shape of the option. When unset, it inherits the shape of the parent `auro-menu`.
+       * @type {'box' | 'pill' | 'snowflake'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        attribute: "shape",
+        reflect: true
+      },
+
+      /**
+       * Sets the size of the option. When unset, it inherits the size of the parent `auro-menu`.
+       * @type {'xs' | 'sm' | 'md' | 'lg' | 'xl'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        attribute: "size",
+        reflect: true
+      },
+
+      /**
+       * When true, this option will not show the checkmark when selected.
+       */
       noCheckmark: {
         type: Boolean,
-        reflect: true
+        reflect: true,
+        attribute: 'nocheckmark'
       },
 
       /**
@@ -1861,17 +1919,30 @@ class AuroMenuOption extends AuroElement {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * When true, the option is disabled and cannot be selected.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * The value associated with this menu option.
+       */
       value: {
         type: String,
         reflect: true
       },
+
+      /**
+       * Sets the tab order of the menu option.
+       */
       tabIndex: {
         type: Number,
-        reflect: true
+        reflect: true,
+        attribute: 'tabindex'
       },
 
       /**