@shortfuse/materialdesignweb 0.9.0 → 0.9.2

package/components/Headline.js

@@ -1,5 +1,9 @@
 import Display from './Display.js';
 
+/**
+ * Material Design Type scale: Headline.
+ * @see https://m3.material.io/styles/typography/type-scale-tokens
+ */
 export default Display
   .extend()
   .set({

package/components/Icon.js

@@ -1,5 +1,3 @@
-// import fontStyles from 'https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:FILL@0..1&display=block' assert { type: 'css'};
-
 import CustomElement from '../core/CustomElement.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 import { svgAliasMap, unaliased } from '../services/svgAlias.js';
@@ -10,7 +8,12 @@ const documentLoadedStyleSheets = new Set();
 
 // https://html.spec.whatwg.org/multipage/embedded-content.html#htmlimageelement
 
-/** -implements {Omit<HTMLImageElement,DeprecatedHTMLImageElementProperties>} */
+/**
+ * Material system icons represent actions, objects, and concepts; prefer
+ * the Material icon system (SVG or Material Symbols) for consistent visual language.
+ * implements {Omit<HTMLImageElement,DeprecatedHTMLImageElementProperties>}
+ * @see https://m3.material.io/styles/icons
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -27,27 +30,48 @@ export default CustomElement
     decode() { return this._img.decode; },
   })
   .observe({
+    /** Icon name used with SVG aliases or font glyphs. */
     icon: 'string',
+    /** Whether the icon is disabled; affects image appearance. */
     disabled: 'boolean',
+    /** Alternative text for image-backed icons. */
     alt: 'string',
+    /** Image source URL for an icon. */
     src: 'string',
+    /** URL to an external SVG resource. */
     svg: 'string',
+    /** Inline SVG path data to render as the icon. */
     svgPath: 'string',
+    /** Image `srcset` attribute for responsive icon images. */
     srcset: 'string',
+    /** Image `sizes` attribute for responsive icon images. */
     sizes: 'string',
+    /** Variation suffix used when resolving icon aliases (e.g., 'filled'). */
     variation: 'string',
+    /** `crossorigin` attribute for image requests. */
     crossOrigin: { attr: 'crossorigin' },
+    /** `usemap` attribute for image maps. */
     useMap: { attr: 'usemap' },
+    /** `ismap` boolean attribute for image maps. */
     isMap: { type: 'boolean', attr: 'ismap' },
+    /** `referrerpolicy` attribute for image requests. */
     referrerPolicy: { attr: 'referrerpolicy' },
+    /** Preferred image decoding mode: 'async' | 'sync' | 'auto'. */
     decoding: { value: /** @type {'async'|'sync'|'auto'} */ (null) },
+    /** Image loading hint: 'eager' | 'lazy'. */
     loading: { value: /** @type {'eager'|'lazy'} */ (null) },
+    /** Rendered width in CSS pixels. */
     width: 'integer',
+    /** Rendered height in CSS pixels. */
     height: 'integer',
+    /** Force using font glyphs instead of SVG when true. */
     forceFont: 'boolean',
     _linkLoaded: 'boolean',
+    /** viewBox used for SVG rendering. */
     viewBox: 'string',
+    /** CSS class applied to font-based icons. */
     fontClass: { empty: 'material-symbols-outlined' },
+    /** URL to Material Symbols CSS when using font-based icons. */
     fontLibrary: { empty: 'https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:FILL@0..1&display=block' },
     _isConnected: 'boolean',
   })

package/components/IconButton.js

@@ -3,8 +3,10 @@ import TooltipTriggerMixin from '../mixins/TooltipTriggerMixin.js';
 
 import Button from './Button.js';
 
-/* https://m3.material.io/components/icon-buttons/specs */
-
+/**
+ * Icon buttons are compact buttons that use an icon to represent an action.
+ * @see https://m3.material.io/components/icon-buttons/specs
+ */
 export default Button
   .extend()
   .mixin(TooltipTriggerMixin)
@@ -12,15 +14,19 @@ export default Button
     _allowedTypes: ['button', 'submit', 'reset', 'checkbox', 'file'],
   })
   .observe({
+    /** ARIA pressed state for toggle buttons (checkbox type). */
     _ariaPressed: {
       get({ type, checked, indeterminate }) {
         if (type !== 'checkbox') return null;
         return indeterminate ? 'mixed' : (checked ? 'true' : 'false');
       },
     },
+    /** True when the underlying control behaves as a toggle (checkbox). */
     _isToggle({ type }) {
       return type === 'checkbox';
     },
+
+    /** When present, enables automatic tooltip behavior from the mixin. */
     autoTooltip: { empty: true },
   })
   .expressions({

package/components/Input.js

@@ -1,4 +1,3 @@
-/* https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ */
 /* https://learn.microsoft.com/en-us/dotnet/api/system.windows.controls.combobox.iseditable?view=windowsdesktop-7.0#remarks */
 
 import CustomElement from '../core/CustomElement.js';
@@ -12,6 +11,8 @@ import Popup from './Popup.js';
 
 /** @typedef {import('./Listbox.js').default} Listbox */
 
+/** @typedef {import('../mixins/RippleMixin.js').default} RippleMixin */
+
 /** @type {InstanceType<import('./Popup.js').default>} */
 let sharedPopup;
 
@@ -29,6 +30,12 @@ function getSharedPopup() {
   return sharedPopup;
 }
 
+/**
+ * Text fields let users enter and edit text. This component implements
+ * autocomplete, suggestions, and listbox behaviors where applicable.
+ * @see https://m3.material.io/components/text-fields/specs
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -37,31 +44,76 @@ export default CustomElement
   .mixin(TextFieldMixin)
   .mixin(ResizeObserverMixin)
   .observe({
+    /**
+     * When true, the component inserts the best suggestion into the input field
+     * as inline text. The appended portion of the suggestion is selected so the
+     * user can accept it (e.g. press Enter) or continue typing to replace it.
+     * Typically combined with `autosuggestInline` to display candidates while
+     * typing.
+     * @see https://w3c.github.io/aria/#aria-autocomplete
+     */
     autocompleteInline: 'boolean',
+
+    /**
+     * When set and not `'custom'`, `applyAutocompleteList()` filters the
+     * listbox options to items that start * with the typed text. This controls
+     * dropdown filtering but does not itself cause inline insertion.
+     * @see https://w3c.github.io/aria/#aria-autocomplete
+     */
     autocompleteList: 'string',
+
+    /**
+     * When true, the component advances/searches suggestion candidates as the
+     * user types (calls `changeSuggestion({ startsWith })`). If
+     * `autosuggestInline` is true and `autocompleteInline` is also true the
+     * current candidate will be shown inline; if `autocompleteInline` is false
+     * only the candidate selection changes (no inline text insertion).
+     */
     autosuggestInline: 'boolean',
+
     /** If true, when listbox is open, arrow navigation will automatically select options. */
     autoSelect: 'boolean',
+
+    /** True when the listbox popup is currently expanded. */
     _expanded: 'boolean',
-    /** If true, when listbox is open, <ESC> accepts current suggestion, same as <Enter>. */
+
+    /** If true, when listbox is open, <Esc> accepts current suggestion (same as Enter). */
     acceptOnEscape: 'boolean',
+
     _listbox: {
       type: 'object',
       /** @type {InstanceType<Listbox>} */
       value: null,
     },
+
+    /** Currently focused suggestion value in the listbox. */
     _focusedValue: 'string',
+
+    /** Focus position in set (1-based) for aria-posinset. */
     _focusedPosInSet: { value: -1 },
+
+    /** Computed size of the listbox (number of options). */
     _listboxSize: { value: -1 },
+
+    /** Draft input text while composing suggestions. */
     _draftInput: { type: 'string', nullable: false },
+
+    /** Whether a suggestion is currently available. */
     _hasSuggestion: 'boolean',
+
+    /** The current selected/committed listbox value. */
     _listboxValue: 'string',
+
+    /** Last computed listbox value (non-nullable string). */
     _lastComputedListboxValue: { type: 'string', nullable: false },
+
     _values: {
       type: 'array',
       /** @type {string[]} */
       value: [],
     },
+
+    /** Whether an input chip is currently selected in multi-select mode. */
     _chipSelected: 'boolean',
   })
   .observe({
@@ -86,7 +138,7 @@ export default CustomElement
     _onPopupFocusoutListener: null,
     _suggestionText: '',
     _suggestionValue: '',
-    /** @type {HTMLOptionElement} */
+    /** @type {Pick<HTMLOptionElement, 'label'|'value'|'selected'>} */
     _suggestionOption: null,
   })
   .define({
@@ -203,7 +255,7 @@ export default CustomElement
       }
     },
     /**
-     * @param {{label:string, value:string}} option
+     * @param {Pick<HTMLOptionElement, 'label'|'value'|'selected'>} option
      * @return {void}
      */
     suggestOption(option) {
@@ -381,8 +433,7 @@ export default CustomElement
         this.refs.chips.replaceChildren();
         return;
       }
-      /** @type {InstanceType<import('./InputChip.js').default>} */
-      let element = this.refs.chips.firstElementChild;
+      let element = /** @type {InstanceType<import('./InputChip.js').default>} */ (this.refs.chips.firstElementChild);
 
       for (let i = 0; i < _values.length; i++) {
         const currentValue = _values[i];
@@ -396,7 +447,7 @@ export default CustomElement
           }
         }
 
-        element ??= this.refs.chips.appendChild(document.createElement('mdw-input-chip'));
+        element ??= /** @type {InstanceType<import('./InputChip.js').default>} */ (this.refs.chips.appendChild(document.createElement('mdw-input-chip')));
         element.closeButton = true;
         element.textContent = foundOption?.label || currentValue;
         element.textContent = foundOption?.label || currentValue;
@@ -404,11 +455,11 @@ export default CustomElement
         element.readOnly = this.readOnly;
         // eslint-disable-next-line unicorn/prefer-add-event-listener
         element.onclose ??= this.onChipClose.bind(this);
-        element = element.nextElementSibling;
+        element = /** @type {InstanceType<import('./InputChip.js').default>} */ (element.nextElementSibling);
       }
       while (element) {
         const prev = element;
-        element = element.nextElementSibling;
+        element = /** @type {InstanceType<import('./InputChip.js').default>} */ (element.nextElementSibling);
         prev.remove();
       }
       this._chipSelected = false;
@@ -436,7 +487,9 @@ export default CustomElement
         this._draftInput = option.label;
       }
     },
+    /** @param {CloseEvent & {currentTarget: HTMLElement}} event */
     onChipClose({ currentTarget }) {
+      /** @type {Node} */
       let prev = currentTarget;
       let elementIndex = 0;
       while ((prev = prev.previousSibling)) {
@@ -601,8 +654,7 @@ export default CustomElement
        */
       slotchange({ currentTarget }) {
         if (this._expanded) return;
-        /** @type {InstanceType<Listbox>[]} */
-        const [listbox] = currentTarget.assignedElements();
+        const [listbox] = /** @type {InstanceType<Listbox>[]} */ (currentTarget.assignedElements());
         const _listbox = this._listbox;
         if (_listbox === listbox) {
           // Internal already matches
@@ -621,7 +673,7 @@ export default CustomElement
             listbox.required = true; // Don't allow unclick
           }
 
-          _listbox._handleFormReset = false;
+          listbox._handleFormReset = false;
           listbox.addEventListener('change', this._onListboxChangeListener);
           listbox.addEventListener('click', this._onListboxChangeListener);
           this.populateInputFromListbox();
@@ -686,7 +738,26 @@ export default CustomElement
       if (!_hasListbox) return null;
       return 'aria-listbox';
     },
-    ariaAutocompleteAttrValue({ _hasListbox, autocompleteList, _isSelect }) {
+    /**
+     * Compute `aria-autocomplete` to describe the widget's behavior to AT.
+     *
+     * ARIA values:
+     * - `none`  : no autocomplete behavior is provided
+     * - `inline`: the textbox shows an inline completion the user can accept
+     * - `list`  : a popup listbox provides choices (no inline insertion)
+     * - `both`  : both inline completion and a listbox are available
+     *
+     * Component mapping:
+     * - `autocompleteInline` -> inline completion behavior
+     * - `autocompleteList` (non-null) -> listbox filtering / dropdown present
+     * - `autosuggestInline` -> drives candidate selection as user types
+     *
+     * Note: the current implementation reports `'both'` when a named
+     * `autocompleteList` is present (even if `autocompleteInline` is false).
+     * A stricter mapping would return `list` when only a listbox is present
+     * and `both` only when both `autocompleteInline` and a listbox exist.
+     */
+    ariaAutocompleteAttrValue({ _hasListbox, autocompleteList, _isSelect, autocompleteInline }) {
       if (!_hasListbox) return null;
       if (_isSelect) return null;
       if (autocompleteList != null) {
@@ -763,7 +834,7 @@ export default CustomElement
     },
     _chipSelectedChanged(previous, current) {
       if (!this.multiple) return;
-      const element = this.refs.chips.lastElementChild;
+      const element = /** @type {HTMLOptionElement} */ (this.refs.chips.lastElementChild);
       if (element) {
         element.selected = current;
       }
@@ -867,7 +938,9 @@ export default CustomElement
   .extend((Base) => class Input extends Base {
     /** @type {InstanceType<ReturnType<RippleMixin>>['addRipple']} */
     addRipple(...args) {
+      // @ts-ignore TODO: Fix invalid cast
       if (!this.active) return null;
+      // @ts-ignore TODO: Fix invalid cast
       return super.addRipple(...args);
     }
   })

package/components/InputChip.js

@@ -8,25 +8,56 @@ import './Button.js';
 import './Icon.js';
 import './IconButton.js';
 
+/**
+ * Input chips allow users to enter or edit information as a chip (tag-like).
+ * @see https://m3.material.io/components/chips/specs
+ */
 export default Box
   .extend()
   .mixin(ShapeMixin)
   .mixin(DelegatesFocusMixin)
   .mixin(HyperlinkMixin)
   .observe({
+    /** Render the chip in avatar (larger) style. */
     avatar: 'boolean',
+
+    /** Show a close action button inside the chip. */
     closeButton: 'boolean',
+
+    /** Icon name to use for the close button (default: 'close'). */
     closeIcon: { empty: 'close' },
+
+    /** Ink color used for the close icon (default: inherit). */
     closeInk: { empty: 'inherit' },
+
+    /** Reflects the `readonly` attribute; prevents editing/closing when true. */
     readOnly: { attr: 'readonly', type: 'boolean' },
+
+    /** Whether the chip is disabled. */
     disabled: 'boolean',
+
+    /** Leading icon name for the chip. */
     icon: 'string',
+
+    /** Ink color for the leading icon. */
     iconInk: 'string',
+
+    /** Image `src` for an avatar or image-backed icon. */
     src: 'string',
+
+    /** External SVG URL to render as the icon. */
     svg: 'string',
+
+    /** SVG `viewBox` used for inline SVG rendering. */
     viewBox: 'string',
+
+    /** SVG path data to render as the icon. */
     svgPath: 'string',
+
+    /** Event handler/callback for the `close` event. */
     onclose: EVENT_HANDLER_TYPE,
+
+    /** Selection state used by chip-selection patterns. */
     selected: 'boolean',
   })
   .set({
@@ -144,7 +175,8 @@ export default Box
   })
   .on({
     selectedChanged(previous, current) {
-      this.refs.action._focused = current;
+      const action = /** @type {InstanceType<typeof import('./Button.js').default>} */ (this.refs.action);
+      action._focused = current;
     },
   })
   .recompose(({ refs: { anchor, slot, icon, outline } }) => {

package/components/Label.js

@@ -2,6 +2,10 @@ import TypographyMixin from '../mixins/TypographyMixin.js';
 
 import Box from './Box.js';
 
+/**
+ * Material Design Type scale: Label.
+ * @see https://m3.material.io/styles/typography/type-scale-tokens
+ */
 export default Box
   .extend()
   .mixin(TypographyMixin)

package/components/List.js

@@ -5,12 +5,22 @@ import Box from './Box.js';
 
 /** @typedef {'compact'} DeprecatedHTMLMenuElementProperties */
 
+/**
+ * Lists present a single column of related content, such as options or navigation.
+ * @see https://m3.material.io/components/lists/specs
+ */
 export default Box
   .extend()
   .mixin(DensityMixin)
   .mixin(AriaReflectorMixin)
   .set({
+    /** ARIA role applied to the host element (default: 'list'). */
     _ariaRole: 'list',
+
+    /**
+     * Visual color token for list surfaces. Default is `surface` to match
+     * Material surface theming.
+     */
     color: { empty: 'surface' },
   })
   .css`

package/components/ListItem.js

@@ -13,6 +13,11 @@ import RippleMixin from '../mixins/RippleMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * List item representing a single row in a list; supports leading/trailing
+ * content, selection, and accessibility features.
+ * @see https://m3.material.io/components/lists/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -21,32 +26,80 @@ export default CustomElement
   .mixin(AriaReflectorMixin)
   .mixin(HyperlinkMixin)
   .set({
+    /** ARIA role applied to the host element (default: 'listitem'). */
     _ariaRole: 'listitem',
+
+    /** When true, draw the Material state layer for interactive feedback. */
     stateLayer: true,
   })
   .observe({
+    /** Leading slot content or shorthand string. */
     leading: 'string',
+
+    /** Avatar label or shorthand content for a leading avatar. */
     avatar: 'string',
+
+    /** Color token used for the avatar container (default: primary-container). */
     avatarColor: { value: 'primary-container' },
+
+    /** Image source for the avatar. */
     avatarSrc: 'string',
+
+    /** Image source URL for a leading image in the list item. */
     src: 'string',
+
+    /** Alt text for the leading image. */
     alt: 'string',
+
+    /** Icon name for a leading icon. */
     icon: 'string',
+
+    /** Ink/color token used for the leading icon. */
     iconInk: 'string',
+
+    /** External image/SVG source for the leading icon. */
     iconSrc: 'string',
+
+    /** Icon variation (e.g., 'filled'). */
     iconVariation: 'string',
+
+    /** Checkbox shorthand name or placement class for a selectable leading checkbox. */
     checkbox: 'string',
+
+    /** Radio shorthand name or placement class for a selectable leading radio. */
     radio: 'string',
+
+    /** Selection color token used when item is selected (default: primary). */
     selectionColor: { value: 'primary' },
+
+    /** Selection state for the item. */
     selected: 'boolean',
+
+    /** Supporting text (secondary line) for the list item. */
     supporting: 'string',
+
+    /** Trailing text slot or shorthand. */
     trailing: 'string',
+
+    /** Trailing icon name. */
     trailingIcon: 'string',
+
+    /** Ink/color token for the trailing icon. */
     trailingIconInk: 'string',
+
+    /** External image/SVG source for the trailing icon. */
     trailingIconSrc: 'string',
+
+    /** Divider style identifier (e.g., 'inset'). */
     divider: 'string',
+
+    /** If true, indicates the list item contains video content and adjusts layout. */
     video: 'boolean',
+
+    /** Number of text lines the item should reserve for content (integer). */
     lines: 'integer',
+
+    /** Internal flag set when supporting content is provided via slot. */
     _supportingSlotted: 'boolean',
   })
   .observe({

package/components/ListOption.js

@@ -6,6 +6,10 @@ import ListItem from './ListItem.js';
 
 // https://html.spec.whatwg.org/multipage/form-elements.html#htmloptionelement
 
+/**
+ * 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)
@@ -13,17 +17,48 @@ export default ListItem
     formAssociated: true,
   })
   .set({
+    /** ARIA role applied to the option container (anchor receives role 'option'). */
     _ariaRole: 'none',
+
+    /** 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({
@@ -46,15 +81,41 @@ export default ListItem
     },
   })
   .define({
+    /** Numeric index of the option inside the parent listbox. */
     index() { return this._index; },
+
+    /** 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 */