@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/ListOption.js

@@ -1,27 +1,64 @@
 // https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
 
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
+
 import ListItem from './ListItem.js';
 
 // https://html.spec.whatwg.org/multipage/form-elements.html#htmloptionelement
 
-export default class ListOption extends ListItem
+/**
+ * List options represent selectable choices within a `mdw-listbox` or list.
+ * @see https://m3.material.io/components/lists/specs
+ */
+export default ListItem
   .extend()
+  .mixin(DelegatesFocusMixin)
   .setStatic({
     formAssociated: true,
   })
   .set({
+    /** ARIA role applied to the option container (anchor receives role 'option'). */
     _ariaRole: 'none',
-    delegatesFocus: true,
+
+    /** Index of this option within its list/listbox (managed externally). */
     _index: -1,
+
+    /** Internal flag indicating selection was modified via API rather than default. */
     _selectedDirty: false,
+
+    /** Whether this option behaves as an interactive selectable item. */
     isInteractive: true,
   })
   .observe({
     // ListOption.prototype._form = ListOption.prop('_form');
+
+    /**
+     * Explicit label for accessibility. Reflected to attribute `label`.
+     * Falls back to `textContent` when not provided.
+     */
     _label: { attr: 'label', reflect: true, nullParser: String },
+
+    /**
+     * Explicit text content for the option. Reflected to attribute `text`.
+     */
+    _text: { attr: 'text', reflect: true, nullParser: String },
+
+    /**
+     * Initial/default selection state (reflected to `selected` attribute).
+     * Use `selected` property to control runtime selection.
+     */
     defaultSelected: { attr: 'selected', reflect: true, type: 'boolean' },
+
+    /** Internal boolean representing the current selected state. */
     _selected: 'boolean',
+
+    /**
+     * Underlying option value (reflected to `value` attribute). Defaults to
+     * the option's text content when not provided.
+     */
     _value: { attr: 'value', reflect: true },
+
+    /** Set when form association disables the option. */
     _formDisabled: 'boolean',
   })
   .observe({
@@ -44,19 +81,45 @@ export default class ListOption extends ListItem
     },
   })
   .define({
+    /** Numeric index of the option inside the parent listbox. */
     index() { return this._index; },
-    form() { return (this.parentElement)?.form; },
+
+    /** Associated form owner (if any) for form-associated behavior. */
+    form() { return /** @type {HTMLInputElement} */ (this.parentElement)?.form; },
+
+    /**
+     * Text content for the option; setting updates the internal `_text` field.
+     * If not provided, the getter falls back to element textContent.
+     */
+    text: {
+      // Incomplete
+      get() { return this._text ?? this.textContent; },
+      /** @param {string} value */
+      set(value) {
+        this._text = value;
+      },
+    },
+
+    /**
+     * Accessible label for the option. Falls back to `text` or the element
+     * content when not explicitly set.
+     */
     label: {
-      get() { return this._label ?? this.textContent; },
+      get() { return this._label ?? this._text ?? this.textContent; },
       /** @param {string} value */
       set(value) {
         this._label = value;
       },
     },
+
+    /**
+     * Option `value` used when the option is selected in a form. Defaults to
+     * the option's text when not explicitly defined.
+     */
     value: {
       get() { return this._value ?? this.textContent; },
       /** @param {string} value */
-      set(value) { this._label = value; },
+      set(value) { this._value = value; },
     },
   })
   .methods({
@@ -69,38 +132,48 @@ export default class ListOption extends ListItem
       this.refs.anchor.focus(...options);
     },
   })
-  .on({
-    composed({ inline }) {
-      const { anchor, state, content } = this.refs;
-
-      // Form Associated elements cannot receive focus unless using delegatesFocus
-      // Workaround by redirecting focus to an inner element
-      // Reuse HTMLAnchorElement with no HREF
-      // Issues: Siblings (images) are not contained within tree
-
-      anchor.setAttribute('disabled', '{disabledState}');
-      anchor.setAttribute('role', 'option');
-      anchor.setAttribute('aria-disabled', inline(({ disabledState }) => `${disabledState}`));
-      anchor.setAttribute('tabindex', '0');
-      anchor.setAttribute('aria-selected', inline(({ selected }) => `${selected}`));
-      anchor.setAttribute('selected', '{selected}');
-      anchor.removeAttribute('href');
-      anchor.removeAttribute('mdw-if');
-
-      content.setAttribute('selected', '{selected}');
-
-      state.setAttribute('state-disabled', 'focus');
+  .expressions({
+    anchorAriaLabelledBy({ _label }) {
+      return _label ? null : 'content';
     },
-    _labelChanged(previous, current) {
-      const { anchor } = this.refs;
-      if (current == null) {
-        anchor.setAttribute('aria-labelledby', 'content');
-        anchor.removeAttribute('aria-label');
-      } else {
-        anchor.setAttribute('aria-label', current);
-        anchor.removeAttribute('aria-labelledby');
-      }
+    anchorAriaDescribedBy({ _label }) {
+      return _label ? 'content' : null;
     },
+    computedIconVariation({ iconVariation, selected }) {
+      if (iconVariation != null) return iconVariation;
+      return selected ? 'filled' : null;
+    },
+  })
+  .recompose(({ inline, refs: { checkbox, radio, anchor, state, content } }) => {
+    // Form Associated elements cannot receive focus unless using delegatesFocus
+    // Workaround by redirecting focus to an inner element
+    // Reuse HTMLAnchorElement with no HREF
+    // Issues: Siblings (images) are not contained within tree
+
+    anchor.setAttribute('disabled', '{disabledState}');
+    anchor.setAttribute('role', 'option');
+    anchor.setAttribute('aria-disabled', inline(({ disabledState }) => `${disabledState}`));
+    anchor.setAttribute('tabindex', '0');
+    anchor.setAttribute('aria-selected', inline(({ selected }) => `${selected}`));
+    anchor.setAttribute('selected', '{selected}');
+    anchor.setAttribute('aria-labelledby', '{anchorAriaLabelledBy}');
+    anchor.setAttribute('aria-describedby', '{anchorAriaDescribedBy}');
+    anchor.setAttribute('aria-label', '{_label}');
+    anchor.removeAttribute('href');
+    anchor.removeAttribute('mdw-if');
+
+    // eslint-disable-next-line no-shadow
+    checkbox.setAttribute('mdw-if', inline(({ checkbox, icon }) => !icon && checkbox));
+
+    // eslint-disable-next-line no-shadow
+    radio.setAttribute('mdw-if', inline(({ radio, icon }) => !icon && radio));
+
+    content.setAttribute('aria-hidden', 'true');
+    content.setAttribute('selected', '{selected}');
+
+    state.setAttribute('state-disabled', 'focus');
+  })
+  .on({
     selectedChanged(previous, current) {
       // Used by HTMLCollection
       this.classList.toggle('mdw-list-option__selected', current);
@@ -115,7 +188,11 @@ export default class ListOption extends ListItem
     
       z-index: 0;
     }
-    
+
+    :host([hidden]) {
+      display: none;
+    }
+
     :host([href]) {
       cursor: pointer;
     }
@@ -128,6 +205,7 @@ export default class ListOption extends ListItem
     #content {
       -webkit-user-select: none;
       user-select: none;
+      pointer-events: none;
     }
     
     #content[selected] {
@@ -142,35 +220,35 @@ export default class ListOption extends ListItem
       background-color: rgb(var(--mdw-bg));
       color: rgb(var(--mdw-ink));
     }
-  ` {
-  static { this.autoRegister('mdw-list-option'); }
-
-  /**
-   * @param {string} [text]
-   * @param {string} [value]
-   * @param {boolean} [defaultSelected]
-   * @param {boolean} [selected]
-   */
-  constructor(text, value, defaultSelected, selected) {
-    super();
-    if (text !== undefined) {
-      this.text = text;
-    }
-    if (value !== undefined) {
-      this._value = value;
-    }
-    if (defaultSelected !== undefined) {
-      this.defaultSelected = defaultSelected;
-    }
-    if (selected !== undefined) {
-      this._selected = selected;
+  `
+  .extend((BaseClass) => class extends BaseClass {
+    /**
+     * @param {string} [text]
+     * @param {string} [value]
+     * @param {boolean} [defaultSelected]
+     * @param {boolean} [selected]
+     */
+    constructor(text, value, defaultSelected, selected) {
+      super();
+      if (text !== undefined) {
+        this.text = text;
+      }
+      if (value !== undefined) {
+        this._value = value;
+      }
+      if (defaultSelected !== undefined) {
+        this.defaultSelected = defaultSelected;
+      }
+      if (selected !== undefined) {
+        this._selected = selected;
+      }
     }
-  }
 
-  connectedCallback() {
-    super.connectedCallback();
-    if (!this.hasAttribute('tabindex')) {
-      this.tabIndex = 0;
+    connectedCallback() {
+      super.connectedCallback();
+      if (!this.hasAttribute('tabindex')) {
+        this.tabIndex = 0;
+      }
     }
-  }
-}
+  })
+  .autoRegister('mdw-list-option');

package/components/Listbox.js

@@ -1,4 +1,5 @@
 import { constructHTMLOptionsCollectionProxy } from '../dom/HTMLOptionsCollectionProxy.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 import FormAssociatedMixin from '../mixins/FormAssociatedMixin.js';
 import KeyboardNavMixin from '../mixins/KeyboardNavMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
@@ -6,32 +7,53 @@ import StateMixin from '../mixins/StateMixin.js';
 import List from './List.js';
 import ListOption from './ListOption.js';
 
-/** @implements {HTMLSelectElement} */
-// @ts-expect-error Can't implement index signatures (use `item()`)
+/**
+ * Listbox: a selectable list of options, used for autocompletes and selects.
+ * implements {HTMLSelectElement}
+ * @see https://m3.material.io/components/lists/specs
+ */
 export default List
   .extend()
   .mixin(StateMixin)
   .mixin(FormAssociatedMixin)
   .mixin(KeyboardNavMixin)
+  .mixin(DelegatesFocusMixin)
   .observe({
+    /** When true, multiple options may be selected (select-multiple semantics). */
     multiple: 'boolean',
+
+    /** Visible size (number of rows) for the listbox; 0 means auto. */
     size: { type: 'integer', empty: 0 },
   })
   .set({
+    /** ARIA role applied to the host element (default: 'listbox'). */
     _ariaRole: 'listbox',
-    delegatesFocus: true,
-    /** @type {HTMLCollectionOf<ListOption> & HTMLOptionsCollection} */
+
+    /**
+     * Lazily-constructed options collection proxy exposing `add`, indexed
+     * access, and other `HTMLOptionsCollection` semantics.
+     * @type {HTMLCollectionOf<InstanceType<typeof ListOption>> & HTMLOptionsCollection}
+     */
     _optionsCollection: null,
-    /** @type {HTMLCollectionOf<ListOption>} */
+
+    /** Cached collection of selected options (HTMLCollection). */
     _selectedOptionsCollection: null,
+
+    /** Internal guard to avoid reentrant selectedness updates. */
     _handlingSelectedness: false,
+
+    /** When true, form resets are honored; toggled when form association changes. */
+    _handleFormReset: true,
   })
   .define({
     options() {
       if (!this._optionsCollection) {
+        // eslint-disable-next-line operator-linebreak
+        const collection = /** @type {HTMLCollectionOf<InstanceType<typeof ListOption>>} */
+          (this.getElementsByTagName(ListOption.elementName));
         this._optionsCollection = constructHTMLOptionsCollectionProxy({
           host: this,
-          collection: this.getElementsByTagName(ListOption.elementName),
+          collection,
           OptionConstructor: ListOption,
           GroupConstructor: ListOption,
         });
@@ -39,36 +61,46 @@ export default List
       return this._optionsCollection;
     },
 
-    /** @return {HTMLCollectionOf<ListOption>} */
+    /**
+     * Returns a live HTMLCollection of selected `mdw-list-option` elements.
+     * @return {HTMLCollectionOf<InstanceType<typeof ListOption>>}
+     */
     selectedOptions() {
       // eslint-disable-next-line no-return-assign
       return (this._selectedOptionsCollection
         ??= (
-          /** @type {HTMLCollectionOf<ListOption>} */
+          /** @type {HTMLCollectionOf<InstanceType<typeof ListOption>>} */
           (this.getElementsByClassName('mdw-list-option__selected')))
       );
     },
 
-    type() { return 'select'; },
+    /** Returns the control type string compatible with `input`/`select` semantics. */
+    type() { return this.multiple ? 'select-multiple' : 'select-one'; },
 
+    /** Query selector used by keyboard navigation mixin to find focusable options. */
     kbdNavQuery() { return ListOption.elementName; },
 
+    /** Allow keyboard navigation to focus disabled options in some patterns. */
     kbdNavFocusableWhenDisabled() { return true; },
   })
   .define({
     length() { return this.options.length; },
 
     selectedIndex: {
+      /** @return {number} */
       get() {
         const [selectedItem] = this.selectedOptions;
         if (!selectedItem) return -1;
         return Array.prototype.indexOf.call(this.options, selectedItem);
       },
+      /** @param {number} value */
       set(value) {
         const itemToSelect = this.options[value];
+        this._handlingSelectedness = true;
         for (const option of this.options) {
           option.selected = (option === itemToSelect);
         }
+        this._handlingSelectedness = false;
         this._value = this.value;
       },
     },
@@ -80,11 +112,13 @@ export default List
       set(v) {
         let newValue = '';
         const vString = `${v}`;
+        this._handlingSelectedness = true;
         for (const option of this.options) {
           if ((option.selected = (option.value === vString))) {
             newValue = vString;
           }
         }
+        this._handlingSelectedness = false;
         this._value = newValue;
       },
     },
@@ -99,7 +133,9 @@ export default List
       this.updateAriaProperty('ariaMultiSelectable', newValue ? 'true' : 'false');
     },
     _formResetChanged(oldValue, newValue) {
-      // TODO: Unset dirty
+      if (!newValue) return;
+      if (!this._handleFormReset) return;
+      this.value = this.defaultValue;
     },
     connected() {
       if (!this.hasAttribute('tabindex')) {
@@ -124,12 +160,12 @@ export default List
     },
     /**
      * @param {number} index
-     * @return {ListOption|null}
+     * @return {InstanceType<typeof ListOption>|null}
      */
     item(index) { return this.options[index]; },
     /**
      * @param {string} name ID of ListOption
-     * @return {ListOption|null}
+     * @return {InstanceType<typeof ListOption>|null}
      */
     namedItem(name) {
       for (const option of this.options) {
@@ -143,18 +179,21 @@ export default List
     onListboxClick(event) {
       const target = event.target;
       if (!(target instanceof ListOption)) return;
+      event.stopImmediatePropagation();
       event.stopPropagation();
-      if (target.disabledState) return;
+
+      const listOption = /** @type {InstanceType<ListOption>} */ (target);
+      if (listOption.disabledState) return;
 
       let sendUpdateNotifications = false;
       this._handlingSelectedness = true;
 
       // Perform unselect
-      if (target.selected) {
+      if (listOption.selected) {
         // Unselect condition
         if (!this.required || (this.multiple && this.selectedOptions.length > 1)) {
           sendUpdateNotifications = true;
-          target.selected = false;
+          listOption.selected = false;
         }
       } else {
         if (!this.multiple) {
@@ -164,12 +203,13 @@ export default List
           }
         }
 
-        target.selected = true;
+        listOption.selected = true;
         sendUpdateNotifications = true;
       }
 
       this._value = this.value;
       this._handlingSelectedness = false;
+      this._updateFormAssociatedValue();
 
       if (sendUpdateNotifications) {
         this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
@@ -194,7 +234,7 @@ export default List
       if (this.multiple) return;
       if (this._handlingSelectedness) return;
 
-      const target = /** @type {ListOption} */ (/** @type {unknown} */ (event.target));
+      const target = /** @type {InstanceType<typeof ListOption>} */ (event.target);
       if (target.selected) return;
       this._handlingSelectedness = true;
 

package/components/Menu.js

@@ -1,30 +1,43 @@
-// https://www.w3.org/TR/wai-aria-practices/#menu
-
-import './Surface.js';
 import CustomElement from '../core/CustomElement.js';
 import { attemptFocus } from '../core/dom.js';
 import DensityMixin from '../mixins/DensityMixin.js';
+import ElevationMixin from '../mixins/ElevationMixin.js';
 import KeyboardNavMixin from '../mixins/KeyboardNavMixin.js';
 import PopupMixin from '../mixins/PopupMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
-import SurfaceMixin from '../mixins/SurfaceMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Menus provide a list of choices or actions in a temporary surface.
+ * @see https://m3.material.io/components/menus/specs
+ * @see https://www.w3.org/TR/wai-aria-practices/#menu
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
-  .mixin(SurfaceMixin)
+  .mixin(ElevationMixin)
   .mixin(ShapeMixin)
   .mixin(PopupMixin)
   .mixin(DensityMixin)
   .mixin(KeyboardNavMixin)
   .set({
-    scrollable: true,
+    /** Placement strategy for the popup ('corner'). */
     flow: 'corner',
+
+    /** When true, show a scrim behind the menu (used by `showModal`). */
     _useScrim: false,
-    /** @type {WeakRef<HTMLElement>} */
+
+    /**
+     * Weak reference to the element that requested a submenu cascade. Stored
+     * as a WeakRef to avoid retaining DOM nodes.
+     * @type {WeakRef<HTMLElement>}
+     */
     _cascader: null,
-    /** @type {WeakRef<HTMLElement>} */
+
+    /**
+     * Weak reference to the currently opened submenu (if any).
+     * @type {WeakRef<HTMLElement>}
+     */
     _submenu: null,
   })
   .define({
@@ -34,9 +47,11 @@ export default CustomElement
       const submenuItems = [...this.querySelectorAll(':scope mdw-menu mdw-menu-item')];
       return items.filter((el) => !submenuItems.includes(el));
     },
+    /** Return the internal dialog element used for popup rendering (if any). */
     _dialog() {
       return /** @type {HTMLDialogElement} */ (this.refs.dialog);
     },
+    /** Element that cascaded this submenu (if present). */
     cascader: {
       get() {
         return this._cascader?.deref();
@@ -48,6 +63,7 @@ export default CustomElement
         this._cascader = value ? new WeakRef(value) : null;
       },
     },
+    /** Currently opened submenu element (if any). */
     submenu: {
       get() {
         return this._submenu?.deref();
@@ -60,15 +76,9 @@ export default CustomElement
       },
     },
   })
-  .on({
-    composed() {
-      const { shape, surface, dialog, scrim } = this.refs;
-      surface.append(shape);
-      dialog.prepend(surface);
-      scrim.setAttribute('invisible', '');
-
-      // Wrap slot in scroller
-    },
+  .recompose(({ refs: { scrim } }) => {
+    scrim.setAttribute('invisible', '');
+    // Wrap slot in scroller
   })
   .css`
     /* https://m3.material.io/components/menus/specs */
@@ -77,17 +87,14 @@ export default CustomElement
       --mdw-shape__size: var(--mdw-shape__extra-small);
       --mdw-bg: var(--mdw-color__surface-container);
       --mdw-ink: var(--mdw-color__on-surface);
-
-      --mdw-surface__shadow__resting: var(--mdw-surface__shadow__2);
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__resting);
       display: block;
 
       inline-size: auto;
       min-inline-size: calc(var(--mdw-menu__inline-base) * 2);
       max-inline-size: 100vw;
-    }
 
-    #shape {
+      filter: var(--mdw-elevation__drop-shadow__2);
+
       background-color: rgb(var(--mdw-bg));
     }
 
@@ -96,6 +103,7 @@ export default CustomElement
     }
   `
   .methods({
+    /** @param {Parameters<InstanceType<ReturnType<PopupMixin>>['showPopup']>} args */
     showModal(...args) {
       this._useScrim = true;
       const result = this.showPopup(...args);
@@ -118,16 +126,18 @@ export default CustomElement
   })
   .events({
     'mdw-menu-item:cascade'(event) {
-      const menuItem = event.target;
-      const subMenuId = event.detail;
+      const menuItem = /** @type {HTMLElement} */ (event.target);
+      const subMenuId = /** @type {CustomEvent<string>} */ (event).detail;
       event.stopPropagation();
 
-      const submenu = this.getRootNode().getElementById(subMenuId);
+      const root = /** @type {DocumentFragment|Document} */ (this.getRootNode());
+      const submenu = /** @type {typeof this} */ (root.getElementById(subMenuId));
       this.submenu = submenu;
       submenu.cascade(menuItem);
     },
     'mdw-menu-item:cascader-blur'() {
-      const submenu = this.submenu;
+      const submenu = /** @type {typeof this} */ (this.submenu);
+      if (!submenu) return;
       // Wait for focus event (if mouse focus on sub menu item)
       queueMicrotask(() => {
         // Stay open if submenu is focused
@@ -163,7 +173,9 @@ export default CustomElement
           // if (!this.submenu) break;
           if (getComputedStyle(this).direction === 'rtl') {
             if (event.key === 'ArrowLeft') break;
-          } else if (event.key === 'ArrowRight') break;
+          } else if (event.key === 'ArrowRight') {
+            break;
+          }
           // Fallthrough;
         case 'Escape':
         case 'Esc':