@shortfuse/materialdesignweb 0.9.0 → 0.9.2

package/components/Listbox.js

@@ -7,7 +7,11 @@ import StateMixin from '../mixins/StateMixin.js';
 import List from './List.js';
 import ListOption from './ListOption.js';
 
-/** -implements {HTMLSelectElement} */
+/**
+ * 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)
@@ -15,24 +19,41 @@ export default List
   .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',
-    /** @type {HTMLCollectionOf<InstanceType<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<InstanceType<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,
         });
@@ -40,31 +61,39 @@ export default List
       return this._optionsCollection;
     },
 
-    /** @return {HTMLCollectionOf<InstanceType<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<InstanceType<ListOption>>} */
+          /** @type {HTMLCollectionOf<InstanceType<typeof ListOption>>} */
           (this.getElementsByClassName('mdw-list-option__selected')))
       );
     },
 
+    /** 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;
@@ -131,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) {
@@ -152,17 +181,19 @@ export default List
       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) {
@@ -172,7 +203,7 @@ export default List
           }
         }
 
-        target.selected = true;
+        listOption.selected = true;
         sendUpdateNotifications = true;
       }
 
@@ -203,7 +234,7 @@ export default List
       if (this.multiple) return;
       if (this._handlingSelectedness) return;
 
-      const target = /** @type {InstanceType<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,5 +1,3 @@
-// https://www.w3.org/TR/wai-aria-practices/#menu
-
 import CustomElement from '../core/CustomElement.js';
 import { attemptFocus } from '../core/dom.js';
 import DensityMixin from '../mixins/DensityMixin.js';
@@ -9,6 +7,11 @@ import PopupMixin from '../mixins/PopupMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.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)
@@ -18,11 +21,23 @@ export default CustomElement
   .mixin(DensityMixin)
   .mixin(KeyboardNavMixin)
   .set({
+    /** 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({
@@ -32,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();
@@ -46,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();
@@ -85,6 +103,7 @@ export default CustomElement
     }
   `
   .methods({
+    /** @param {Parameters<InstanceType<ReturnType<PopupMixin>>['showPopup']>} args */
     showModal(...args) {
       this._useScrim = true;
       const result = this.showPopup(...args);
@@ -107,16 +126,17 @@ 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(() => {
@@ -153,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':

package/components/MenuItem.js

@@ -6,12 +6,22 @@ import FormAssociatedMixin from '../mixins/FormAssociatedMixin.js';
 import './Icon.js';
 import ListOption from './ListOption.js';
 
+/**
+ * Menu items represent selectable options within a menu. They can trigger
+ * actions, toggle state, or open nested submenus.
+ * @see https://m3.material.io/components/menus/specs
+ */
 export default ListOption
   .extend()
   .mixin(FormAssociatedMixin)
   .set({
+    /** Timeout handle used to schedule submenu cascade. */
     _cascadeTimeout: null,
+
+    /** Milliseconds to delay before opening a cascaded submenu. */
     CASCADE_TIMEOUT: 500,
+
+    /** Internal flag indicating a cascade is in progress. */
     _cascading: false,
   })
   .define({
@@ -22,9 +32,13 @@ export default ListOption
     },
   })
   .observe({
-    /** ID of menu to cascade */
+    /** ID of the submenu to open when this item cascades. */
     cascades: 'string',
-    /** Can be null */
+
+    /**
+     * Backing field for the menu item's value attribute. Can be `null` to
+     * indicate no explicit value; reflected to the `value` attribute.
+     */
     _defaultValue: {
       attr: 'value',
       reflect: true,
@@ -33,7 +47,10 @@ export default ListOption
     },
   })
   .observe({
-    /** Never returns null */
+    /**
+     * Non-null string representation of the default value used for form
+     * association. Getter never returns null; setter writes to `_defaultValue`.
+     */
     defaultValue: {
       reflect: false,
       get() {
@@ -71,12 +88,7 @@ export default ListOption
       const [name, value] = event.detail;
       if (this.name !== name) return;
       if (value === this.value) return;
-      if (this.value === '1') {
-        console.log('unchecking', this.name, this.value);
-        this.selected = false;
-      } else {
-        this.selected = false;
-      }
+      this.selected = false;
     },
   })
   .expressions({
@@ -158,7 +170,9 @@ export default ListOption
           if (!this.cascades) break;
           if (getComputedStyle(this).direction === 'rtl') {
             if (event.key === 'ArrowRight') break;
-          } else if (event.key === 'ArrowLeft') break;
+          } else if (event.key === 'ArrowLeft') {
+            break;
+          }
           event.stopPropagation();
           event.preventDefault();
           this.cascade();

package/components/NavBar.js

@@ -4,25 +4,36 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
 
 import NavItem from './NavItem.js';
 
+/**
+ * Navigation bars let people switch between UI views on smaller devices
+ * @see https://m3.material.io/components/navigation-bar/specs
+ */
 export default CustomElement
   .extend()
   .mixin(DelegatesFocusMixin)
   .mixin(ThemableMixin)
   .observe({
+    /** When true, the navigation bar is expanded and visible on small viewports. */
     open: 'boolean',
+
+    /**
+     * Pixel threshold for auto-closing the nav bar based on viewport width.
+     * A value of `-1` disables auto-close. Default: 728.
+     */
     autoClose: {
       type: 'float',
       empty: 728,
     },
   })
   .set({
+    /** Color token used for the nav surface (defaults to `surface-container`). */
     color: 'surface-container',
+
+    /** ARIA role applied to the host element (default: 'navigation'). */
     _ariaRole: 'navigation',
   })
   .html`<slot id=slot></slot>`
   .css`
-    /* https://m3.material.io/components/navigation-bar/specs */
-
     :host {
       --mdw-bg: var(--mdw-color__surface-container);
       --mdw-ink: var(--mdw-color__on-surface);
@@ -71,7 +82,7 @@ export default CustomElement
       if (event.target instanceof NavItem === false) return;
       for (const el of this.querySelectorAll('*')) {
         if (el instanceof NavItem === false) continue;
-        el.active = (el === event.target);
+        /** @type {InstanceType<typeof NavItem>} */ (el).active = (el === event.target);
       }
     },
   })

package/components/NavBarItem.js

@@ -1,5 +1,10 @@
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation bar item represents a destination within a navigation bar,
+ * providing an icon and optional label to help users move between app sections.
+ * @see https://m3.material.io/components/navigation-bar/specs
+ */
 export default NavItem
   .extend()
   .css`

package/components/NavDrawer.js

@@ -1,16 +1,33 @@
 import SideSheet from './SideSheet.js';
 
+/**
+ * Navigation drawers provide access to destinations and app-level navigation
+ * in a side panel. They can be modal, dismissible, or permanent depending on
+ * viewport and application needs.
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
 export default SideSheet
   .extend()
   .observe({
+    /** When true, apply drawer shape at the end edge (RTL-aware). */
     shapeEnd: {
       type: 'boolean',
       empty: true,
     },
+
+    /**
+     * Viewport width in pixels at or above which the drawer auto-opens.
+     * Use `-1` to disable auto-open. Default: 1248.
+     */
     autoOpen: {
       type: 'float',
       empty: 1248,
     },
+
+    /**
+     * Fixed layout breakpoint in pixels for permanent/dismissible drawer modes.
+     * Default: 1248.
+     */
     fixedBreakpoint: {
       type: 'float',
       empty: 1248,

package/components/NavDrawerItem.js

@@ -1,5 +1,10 @@
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation drawer item represents a destination inside a navigation drawer,
+ * showing an icon, label, and optional badge to help users navigate app sections.
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
 export default NavItem
   .extend()
   .css`

package/components/NavItem.js

@@ -12,6 +12,14 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
 
 /** @typedef {'charset'|'coords'|'name'|'shape'} DeprecatedHTMLAnchorElementProperties */
 
+/**
+ * A navigation item represents a single destination used by navigation bars,
+ * navigation drawers, and navigation rails. It provides an icon, optional
+ * label, and optional badge to help users move between app sections.
+ * @see https://m3.material.io/components/navigation-bar/specs
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -23,14 +31,21 @@ export default CustomElement
     stateLayer: true,
   })
   .observe({
+    /** Whether the label slot is visible. When true the label is shown. */
     showLabel: 'string',
+    /** Whether the item is active/selected; affects styling and aria-current. */
     active: 'boolean',
+    /** Name of the icon to display (e.g. 'home'); ignored when `src` is provided. */
     icon: 'string',
+    /** URL of an icon image; takes precedence over `icon` when present. */
     src: 'string',
+    /** Badge content to display on the item (e.g. notification count). */
     badge: 'string',
+    /** Accessible label for the anchor; when present it is used instead of the slot text. */
     ariaLabel: 'string', // watch attribute and emit callback
   })
   .methods({
+    /** Focus the internal anchor element. */
     /** @type {HTMLElement['focus']} */
     focus(...args) {
       this.refs.anchor.focus(...args);
@@ -265,13 +280,18 @@ export default CustomElement
       },
       keydown({ key, repeat }) {
         if (key !== ' ') return true;
-        if (!repeat) this.click();
+        if (!repeat) {
+          this.click();
+        }
         return false;
       },
     },
   })
   .extend((Base) => class NavItem extends Base {
-    /** @type {InstanceType<ReturnType<RippleMixin>>['addRipple']} */
+    /**
+     * Add a ripple effect only when the item is active.
+     * @type {InstanceType<ReturnType<RippleMixin>>['addRipple']}
+     */
     addRipple(...args) {
       if (!this.active) return null;
       return super.addRipple(...args);

package/components/NavRail.js

@@ -1,17 +1,26 @@
 import SideSheet from './SideSheet.js';
 
+/**
+ * Navigation rails provide access to app destinations and destinations-level
+ * navigation in a vertical rail, suited for larger screens and desktop layouts.
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
 export default SideSheet
   .extend()
   .observe({
+    /** Horizontal alignment for rail content: 'start', 'center', or 'end'. */
     align: { value: /** @type {'start'|'center'|'end'} */ (null) },
+    /** Viewport width (pixels) threshold at or above which the rail will auto-open. */
     autoOpen: {
       type: 'float',
       empty: 728,
     },
+    /** Viewport width (pixels) threshold at or below which the rail will auto-close. */
     autoClose: {
       type: 'float',
       empty: 1248,
     },
+    /** Viewport width (pixels) at which the rail becomes fixed (non-collapsible). */
     fixedBreakpoint: {
       type: 'float',
       empty: 728,

package/components/NavRailItem.js

@@ -2,6 +2,11 @@
 
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation rail item represents a destination within a navigation rail,
+ * showing an icon and optional label for vertical navigation on larger screens.
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
 export default NavItem
   .extend()
   .css`

package/components/Page.js

@@ -5,33 +5,45 @@ import { ELEMENT_STYLE_TYPE } from '../core/customTypes.js';
 import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 import ResizeObserverMixin from '../mixins/ResizeObserverMixin.js';
 
+/**
+ * Page is a top-level layout container that manages single or multi-pane
+ * application layouts, adapting to viewport size to show one or two panes.
+ * @see https://m3.material.io/foundations/layout/applying-layout/window-size-classes
+ */
 export default CustomElement
   .extend()
   .mixin(DelegatesFocusMixin)
   .mixin(ResizeObserverMixin)
   .observe({
+    /** Layout behavior for the first pane: 'fixed' keeps a fixed width, 'flexible' grows. */
     paneOne: {
       value: /** @type {'fixed'|'flexible'} */ ('flexible'),
     },
+    /** Layout behavior for the second pane; null disables the second pane. */
     paneTwo: {
       value: /** @type {'fixed'|'flexible'|null} */ (null),
     },
+    /** Whether the second pane is currently active/visible. */
     paneTwoActive: 'boolean',
+    /** Inline-size breakpoint (px) at which the second pane becomes visible. */
     paneTwoBreakpoint: {
       type: 'float',
       empty: 720,
     },
+    /** Internally tracked last measured inline size (pixels) used for layout decisions. */
     _lastComputedInlineSize: {
       type: 'float',
       nullable: false,
     },
   })
   .observe({
+    /** Computed: true when two-pane layout should be active based on measured size. */
     _isMultipane({ _lastComputedInlineSize, paneTwo, paneTwoBreakpoint }) {
       return Boolean(paneTwo && _lastComputedInlineSize >= paneTwoBreakpoint);
     },
   })
   .observe({
+    /** Computed inline CSS string that adjusts grid columns for single/multi-pane layouts. */
     _styles: {
       ...ELEMENT_STYLE_TYPE,
       get({ _isMultipane, paneOne, paneTwoActive }) {
@@ -89,7 +101,8 @@ export default CustomElement
       position: sticky;
       inset-block:0;
 
-      display: block;
+      display: flex;
+      flex-direction: column;
 
       overflow-y:auto;
 
@@ -98,6 +111,7 @@ export default CustomElement
     }
   `
   .overrides({
+    /** Handle resize observer entries; update measured inline size for layout logic. */
     onResizeObserved(entry) {
       this._lastComputedInlineSize = entry.borderBoxSize[0]?.inlineSize;
     },

package/components/Pane.js

@@ -2,6 +2,13 @@ import ShapeMixin from '../mixins/ShapeMixin.js';
 
 import Box from './Box.js';
 
+/**
+ * Pane is a layout surface used within `mdw-page` to provide shaped,
+ * padded content columns for app content. It is intended to be placed
+ * as a child of `mdw-page` to create consistent, shaped panes with the
+ * same padding and background surface used across the layout system.
+ * @see https://m3.material.io/foundations/layout/applying-layout/window-size-classes
+ */
 export default Box
   .extend()
   .mixin(ShapeMixin)
@@ -12,7 +19,6 @@ export default Box
       --mdw-ink: var(--mdw-color__on-surface);
       background-color: rgb(var(--mdw-bg));
       color: rgb(var(--mdw-ink));
-      
     }
   `
   .autoRegister('mdw-pane');

package/components/Popup.js

@@ -4,6 +4,11 @@ import PopupMixin from '../mixins/PopupMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Popup displays transient content such as menus or popovers and provides
+ * elevation, shape, and theming control for floating surfaces.
+ * @see https://m3.material.io/styles/elevation/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -11,6 +16,7 @@ export default CustomElement
   .mixin(ShapeMixin)
   .mixin(PopupMixin)
   .observe({
+    /** Elevation level (0–5) controlling the drop-shadow depth of the popup. */
     elevation: 'integer',
   })
   .css`