@shortfuse/materialdesignweb 0.9.0 → 0.9.2

package/components/BottomSheet.js

@@ -91,6 +91,10 @@ CustomElement
   })
   .autoRegister('mdw-bottom-sheet-handle');
 
+/**
+ * Bottom sheets show secondary content anchored to the bottom of the screen
+ * @see https://m3.material.io/components/bottom-sheets/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -100,35 +104,51 @@ export default CustomElement
   .mixin(DelegatesFocusMixin)
   .mixin(ResizeObserverMixin)
   .observe({
+    /** Overrides default of shape top to be true */
     shapeTop: {
       type: 'boolean',
       empty: true,
     },
+    /** Whether the bottom sheet displays as a modal and shows a scrim. */
     modal: 'boolean',
+    /** If true, the sheet is fixed (not translated) and anchors to layout. */
+    fixed: 'boolean',
+    /** Whether the bottom sheet is currently open. */
     open: 'boolean',
+    /** Whether the bottom sheet is expanded to show full content. */
     expanded: 'boolean',
+    /** Last measured block size in pixels (used for layout calculations). */
     _lastComputedBlockSize: {
       type: 'float',
       nullable: false,
     },
+    /** Last measured offsetTop in pixels. */
     _lastOffsetTop: {
       type: 'float',
       nullable: false,
     },
+    /** Current animation duration (milliseconds). */
     _animationDuration: {
       type: 'integer',
       value: 0,
     },
+    /** Current animation easing string for transitions. */
     _animationEasing: {
       value: 'ease-out',
     },
+    /** Current CSS translateY value applied to the sheet. */
     _translateY: { value: '100%' },
+    /** Timestamp of last child scroll event (used to debounce drag). */
     _lastChildScrollTime: 'float',
+    /** ARIA `valuenow` value used by the drag handle for accessibility. */
     _ariaValueNow: {
       type: 'integer',
     },
+    /** When true, a drag handle is rendered to allow pointer dragging. */
     dragHandle: 'boolean',
+    /** Event handler: called when the sheet opens. */
     onopen: EVENT_HANDLER_TYPE,
+    /** Event handler: called when the sheet closes. */
     onclose: EVENT_HANDLER_TYPE,
   })
   .set({
@@ -145,14 +165,14 @@ export default CustomElement
     hostStyles: {
       ...ELEMENT_ANIMATION_TYPE,
       get({
-        open, modal, _lastComputedBlockSize, _translateY,
+        open, fixed, _lastComputedBlockSize, _translateY,
         _animationDuration, _animationEasing,
       }) {
-        const computedMargin = (open || modal) ? 0 : `${-1 * _lastComputedBlockSize}px`;
+        const computedMargin = (fixed) ? `${-1 * _lastComputedBlockSize}px` : 0;
         return {
           styles: {
             marginBottom: computedMargin,
-            transform: modal ? `translateY(${_translateY})` : 'none',
+            transform: fixed ? 'none' : `translateY(${_translateY})`,
           },
           timing: {
             duration: _animationDuration,
@@ -168,6 +188,11 @@ export default CustomElement
     <slot id=slot></slot>
   `
   .methods({
+    /**
+     * Ensure a scrim is present when the sheet is modal and open.
+     * @param {boolean} [animate=false] - If true, animate scrim changes.
+     * @return {void}
+     */
     checkForScrim(animate = false) {
       let { open, modal, _scrim } = this;
       if (open && modal) {
@@ -191,9 +216,13 @@ export default CustomElement
         _scrim.hidden = true;
       }
     },
+    /**
+     * Evaluate drag state and settle the sheet (close or snap open).
+     * @return {void}
+     */
     checkDragFinished() {
-      const { open, _dragStartY, _dragDeltaY, _lastComputedBlockSize, modal, _lastOffsetTop } = this;
-      if (!open || !modal || _dragStartY == null || _dragDeltaY == null) return;
+      const { open, _dragStartY, _dragDeltaY, _lastComputedBlockSize, modal, fixed, _lastOffsetTop } = this;
+      if (!open || fixed || _dragStartY == null || _dragDeltaY == null) return;
       const containerHeight = _lastOffsetTop + _lastComputedBlockSize - 72;
       const min = (_lastComputedBlockSize > containerHeight)
         ? _lastComputedBlockSize - containerHeight
@@ -201,7 +230,7 @@ export default CustomElement
       // visiblity = (max - position) / range
       const visibility = (_lastComputedBlockSize - _dragDeltaY) / (_lastComputedBlockSize - min);
       this._dragStartY = null;
-      if (visibility < 0.5) {
+      if (modal && visibility < 0.5) {
         // Should close
         this._animationDuration = 200 * visibility;
         this._animationEasing = 'ease-out';
@@ -218,7 +247,11 @@ export default CustomElement
         this.expanded = true;
       }
     },
-    /** @param {PointerEvent} event */
+    /**
+     * Pointer active on the drag handle; registers the pointer for dragging.
+     * @param {PointerEvent} event
+     * @return {void}
+     */
     onDragHandleActive(event) {
       if (!event.isTrusted) return;
       if (!event.isPrimary) return;
@@ -226,7 +259,11 @@ export default CustomElement
       if (event.buttons !== 1) return;
       dragHandleEvent.add(event);
     },
-    /** @param {PointerEvent} event */
+    /**
+     * Pointer inactive on the drag handle; finalizes potential drag.
+     * @param {PointerEvent} event
+     * @return {void}
+     */
     onDragHandleInactive(event) {
       if (!event.isTrusted) return;
       if (!event.isPrimary) return;
@@ -234,7 +271,11 @@ export default CustomElement
       if (event.type !== 'pointerup' && event.buttons !== 1) return;
       this.checkDragFinished();
     },
-    /** @param {PointerEvent|TouchEvent} event */
+    /**
+     * Handle pointer or touch move events during dragging.
+     * @param {PointerEvent|TouchEvent} event
+     * @return {void}
+     */
     onPointerOrTouchMove(event) {
       /** @type {{clientY:number,pageY:number}} */
       let source;
@@ -277,6 +318,11 @@ export default CustomElement
     },
   })
   .overrides({
+    /**
+     * Called by ResizeObserverMixin when the element's size changes.
+     * @param {ResizeObserverEntry} entry
+     * @return {void}
+     */
     onResizeObserved(entry) {
       this._lastComputedBlockSize = entry.borderBoxSize[0]?.blockSize;
       this._lastOffsetTop = this.offsetTop;
@@ -310,7 +356,7 @@ export default CustomElement
     '~touchend': 'checkDragFinished',
     /** Scroll events do no bubble but can be captured, passively */
     '*~scroll'() {
-      if (!this.modal) return;
+      if (this.fixed) return;
       this.checkDragFinished();
       this._lastChildScrollTime = performance.now();
       // Wiping touch state
@@ -318,7 +364,7 @@ export default CustomElement
       this._dragDeltaY = null;
     },
     '*scrollend'() {
-      if (!this.modal) return;
+      if (this.fixed) return;
       this._lastChildScrollTime = null;
     },
   })
@@ -337,7 +383,7 @@ export default CustomElement
       this._animationDuration = open ? 250 : 200;
       if (open) {
         let y = 0;
-        if (this.modal) {
+        if (!this.fixed) {
           const { _lastComputedBlockSize } = this;
           const containerHeight = _lastOffsetTop + _lastComputedBlockSize;
           if (_lastComputedBlockSize > containerHeight / 2) {
@@ -353,7 +399,9 @@ export default CustomElement
       }
       this._animationEasing = open ? 'ease-in' : 'ease-out';
       this.checkForScrim(true);
-      if (open) this.focus();
+      if (open) {
+        this.focus();
+      }
     },
     modalChanged() {
       this._animationDuration = 0;
@@ -403,7 +451,7 @@ export default CustomElement
       transition: visibility 0s;
     }
 
-    :host(:where([modal])) {
+    :host(:where(:not([fixed]))) {
       position: fixed; 
 
       max-block-size: calc(100% - 72px);

package/components/Button.js

@@ -11,6 +11,10 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
 
 /* https://m3.material.io/components/buttons/specs */
 
+/**
+ * Buttons prompt most actions in a UI.
+ * @see https://m3.material.io/components/buttons/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -22,6 +26,11 @@ export default CustomElement
   .mixin(InputMixin)
   .mixin(HyperlinkMixin)
   .define({
+    /**
+     * Returns the element used as the state target for visual states
+     * (e.g., pressed/hover). Typically the internal control element.
+     * @return {HTMLElement}
+     */
     stateTargetElement() { return this.refs.control; },
   })
   .set({
@@ -29,6 +38,7 @@ export default CustomElement
     _allowedTypes: ['button', 'submit', 'reset', 'file'],
   })
   .observe({
+    /** The underlying control `type` (button, submit, reset, file). */
     type: {
       empty: 'button',
       /**
@@ -44,14 +54,24 @@ export default CustomElement
         );
       },
     },
+    /** Bound to [elevated] specifying whether the element should be elevated. */
     elevated: 'boolean',
+    /** Visual filled variant; may be "tonal" or boolean-filled token. */
     filled: 'string',
+    /** Whether the button should render an outline. */
     outlined: 'boolean',
+    /** Icon name (uses internal `mdw-icon` when set). */
     icon: 'string',
+    /** Ink color override for the icon. */
     iconInk: 'string',
+    // Overrides to string instead of DOMString
+    /** Image source URL for an icon. */
     src: 'string',
+    /** Inline SVG markup to render as icon. */
     svg: 'string',
+    /** SVG `viewBox` attribute for inline SVG icons. */
     viewBox: 'string',
+    /** Path data for an inline SVG icon. */
     svgPath: 'string',
   })
   .expressions({

package/components/Card.js

@@ -9,10 +9,12 @@ import StateMixin from '../mixins/StateMixin.js';
 
 import Box from './Box.js';
 
-/* https://m3.material.io/components/cards/specs */
-
 const SUPPORTS_INERT = 'inert' in HTMLElement.prototype;
 
+/**
+ * Cards display content and actions about a single subject.
+ * @see https://m3.material.io/components/cards/specs
+ */
 export default Box
   .extend()
   .mixin(StateMixin)
@@ -26,13 +28,23 @@ export default Box
     _ariaRole: 'figure',
   })
   .observe({
+    /** Whether the card displays an elevated surface. */
     elevated: 'boolean',
+    /** Whether the card uses a filled surface style. */
     filled: 'boolean',
+    /** When true, card renders an actionable control (clickable). */
     actionable: 'boolean',
+    /** Label for the action control used for accessibility. */
     actionLabel: 'string',
+    /** Event handler called when the card action is triggered. */
     onaction: EVENT_HANDLER_TYPE,
   })
   .define({
+    /**
+     * Element used as the target for state styling (pressed/focus).
+     * Returns the internal action control when actionable, otherwise the host.
+     * @return {HTMLElement}
+     */
     stateTargetElement() { return this.actionable ? this.refs.action : this; },
   })
   .expressions({
@@ -40,9 +52,14 @@ export default Box
     showButton: ({ actionable, href }) => Boolean(actionable || href),
   })
   .methods({
+    /**
+     * Focuses the internal action control if the card is actionable and not disabled.
+     * @return {void}
+     */
     focus() {
       if (this.disabledState) return;
-      if (this.actionable) this.refs.action.focus();
+      if (!this.actionable) return;
+      this.refs.action.focus();
     },
   })
   .html`

package/components/Checkbox.js

@@ -7,6 +7,10 @@ import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 import TouchTargetMixin from '../mixins/TouchTargetMixin.js';
 
+/**
+ * Checkboxes let users select one or more items from a list, or turn an item on or off.
+ * @see https://m3.material.io/components/checkbox/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -15,11 +19,15 @@ export default CustomElement
   .mixin(InputMixin)
   .mixin(TouchTargetMixin)
   .set({
+    /** Whether the element renders a state layer for interaction feedback. */
     stateLayer: true,
+    /** The underlying control input `type` value. */
     type: 'checkbox',
   })
   .observe({
+    /** Icon name to show for the checked state. */
     icon: { value: 'check' },
+    /** Icon name to show when the control is indeterminate. */
     indeterminateIcon: { value: 'check_indeterminate_small' },
   })
   .expressions({

package/components/CheckboxIcon.js

@@ -3,26 +3,32 @@ import CustomElement from '../core/CustomElement.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * CheckboxIcon is a visual helper for checkboxes, rendering the box and checkmark.
+ * @see https://m3.material.io/components/checkbox/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(ShapeMixin)
   .observe({
+    /** Whether the icon is selected (checked). */
     selected: 'boolean',
+    /** Icon name to render inside the checkbox icon. */
     icon: 'string',
+    /** Whether the associated control is in an error state. */
     errored: 'boolean',
+    /** Whether the associated control is disabled. */
     disabled: 'boolean',
   })
   .define({
-    /** Alias for Selected (QoL) */
+    /** Alias for `selected` (quality-of-life property). */
     checked: {
       get() { return this.selected; },
       set(value) { this.selected = value; },
     },
   })
   .css`
-    /* https://m3.material.io/components/checkbox/specs */
-
     :host {
       --mdw-ink: var(--mdw-color__on-primary);
       --mdw-bg: var(--mdw-color__primary);

package/components/Chip.js

@@ -1,8 +1,13 @@
 import Button from './Button.js';
 
+/**
+ * Chips help people enter information, make selections, filter content, or trigger actions.
+ * @see https://m3.material.io/components/chips/specs
+ */
 export default Button
   .extend()
   .observe({
+    /** When true, renders the chip as a suggestion variant. */
     suggestion: 'boolean',
   })
   .expressions({
@@ -11,8 +16,6 @@ export default Button
     },
   })
   .css`
-    /* https://m3.material.io/components/chips/specs */
-
     :host {
       --mdw-shape__size: 8px;
       --mdw-ink: var(--mdw-color__on-surface);

package/components/Dialog.js

@@ -59,20 +59,26 @@ function focusOnTree(root, autofocus, forward = true) {
           if (attemptFocus(el)) return true;
           continue;
         }
+        // @ts-ignore Valid as long tabIndex isn't negative
         if (el.tabIndex >= 0) {
           // Can focus, add to later in case we find an autofocusable
           if (autofocus || !forward) {
             focusables.push(node);
-          } else if (attemptFocus(node)) return true;
+          } else if (attemptFocus(node)) {
+            return true;
+          }
         }
         if (focusOnTree(el, autofocus, forward)) return true;
       }
       // Step through
     }
+    // @ts-ignore Valid as long tabIndex isn't negative
     if (node.tabIndex >= 0) {
       if (autofocus || !forward) {
         focusables.push(node);
-      } else if (attemptFocus(node)) return true;
+      } else if (attemptFocus(node)) {
+        return true;
+      }
     }
   }
   for (const el of forward ? focusables : focusables.reverse()) {
@@ -81,25 +87,36 @@ function focusOnTree(root, autofocus, forward = true) {
   return false;
 }
 
+/**
+ * Dialogs provide important prompts in a user flow.
+ * @see https://m3.material.io/components/dialogs/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(ShapeMixin)
   .mixin(PopupMixin)
   .define({
+    /** Return the `returnValue` from the internal dialog element. */
     returnValue() {
       return /** @type {HTMLDialogElement} */ (this.refs.dialog).returnValue;
     },
   })
   .observe({
+    /** Divider style for the dialog: 'full', 'inset', or empty. */
     dividers: {
       /** @type {'full'|''|'inset'} */
       value: null,
     },
+    /** Headline text displayed in the dialog header. */
     headline: 'string',
+    /** Optional icon name shown in the dialog header. */
     icon: 'string',
+    /** Default action (value) for the dialog when submitting. */
     default: { value: 'confirm' },
+    /** Label for the cancel action button. */
     cancel: { value: 'Cancel' },
+    /** Label for the confirm action button. */
     confirm: { value: 'Confirm' },
   })
   .define({
@@ -124,6 +141,7 @@ export default CustomElement
       || (node.nodeType === node.TEXT_NODE && node.nodeValue.trim().length));
       currentTarget.toggleAttribute('slotted', hasContent);
     },
+    /** Focus the first autofocusable or focusable element inside the dialog. */
     focus() {
       focusOnTree(this.shadowRoot, true, true);
     },
@@ -349,7 +367,8 @@ export default CustomElement
       const form = event.target;
       if (form instanceof HTMLFormElement === false) return;
       if (form.method !== 'dialog') return;
-      const returnValue = event.submitter?.value;
+      const submitter = /** @type {HTMLInputElement|HTMLButtonElement} */ (event.submitter);
+      const returnValue = submitter?.value;
       this.close(returnValue);
     },
   })

package/components/DialogActions.js

@@ -1,5 +1,9 @@
 import CustomElement from '../core/CustomElement.js';
 
+/**
+ * Dialog action regions contain primary and secondary actions for dialogs.
+ * @see https://m3.material.io/components/dialogs/specs
+ */
 export default CustomElement
   .extend()
   .css`

package/components/Display.js

@@ -3,16 +3,24 @@ import TypographyMixin from '../mixins/TypographyMixin.js';
 
 import Box from './Box.js';
 
+/**
+ * Material Design Type scale: Display
+ * @see https://m3.material.io/styles/typography/type-scale-tokens
+ */
 export default Box
   .extend()
   .mixin(AriaReflectorMixin)
   .mixin(TypographyMixin)
   .set({
+    /** ARIA role applied to the host (default: 'heading'). */
     _ariaRole: 'heading',
+    /** Base aria level used when computing the heading level. */
     _baseAriaLevel: 1,
   })
   .observe({
+    /** Explicit aria-level; if set, overrides the computed level. */
     ariaLevel: 'string',
+    /** Display size controlling typographic scale: 'large'|'medium'|'small'. */
     size: {
       type: 'string',
       /** @type {'large'|'medium'|'small'} */
@@ -20,6 +28,7 @@ export default Box
     },
   })
   .observe({
+    /** Computed aria-level (string) derived from `ariaLevel` and `size`. */
     _computedAriaLevel({ ariaLevel, size, _baseAriaLevel }) {
       if (ariaLevel) return ariaLevel;
       if (size === 'medium') return `${_baseAriaLevel + 1}`;

package/components/Divider.js

@@ -3,10 +3,15 @@
 import CustomElement from '../core/CustomElement.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Dividers are thin lines that group content in lists or other containers
+ * @see https://m3.material.io/components/divider/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .observe({
+    /** When true, render the divider vertically instead of horizontally. */
     vertical: 'boolean',
   })
   .css`

package/components/Fab.js

@@ -2,20 +2,31 @@ import TooltipTriggerMixin from '../mixins/TooltipTriggerMixin.js';
 
 import Button from './Button.js';
 
+/**
+ * Floating action buttons (FABs) help people take primary actions.
+ * @see https://m3.material.io/components/floating-action-button/specs
+ * @see https://m3.material.io/components/extended-fab/specs
+ */
 export default Button
   .extend()
   .mixin(TooltipTriggerMixin)
   .observe({
+    /** When true, render the lowered FAB variant (reduced elevation). */
     lowered: 'boolean',
+    /** When true, the FAB is extended and shows a text label. */
     extended: 'boolean',
+    /** FAB size: `null` (default), 'small' or 'large'. */
     fabSize: {
       /** @type {null|'small'|'large'} */
       value: null,
     },
+    /** Filled variant; default is 'tonal' when omitted. */
     filled: { empty: 'tonal' },
+    /** Whether the FAB uses elevated styling. */
     elevated: { type: 'boolean', empty: true },
   })
   .observe({
+    /** Whether to show the tooltip automatically (true when not extended). */
     autoTooltip({ extended }) {
       return !extended;
     },

package/components/FabContainer.js

@@ -2,13 +2,22 @@ import CustomElement from '../core/CustomElement.js';
 import { ELEMENT_STYLE_TYPE } from '../core/customTypes.js';
 import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 
+/**
+ * Container for Floating Action Buttons (FAB) used to position FABs.
+ * @see https://m3.material.io/components/floating-action-button/specs
+ */
 export default CustomElement
   .extend()
   .mixin(DelegatesFocusMixin)
   .observe({
+    /** Hide the FAB container at this min-width (pixels). */
     hideBreakpoint: { value: 728 },
   })
   .observe({
+    /**
+     * Computed element styles. Generates a media query that hides the
+     * container when `hideBreakpoint` is set.
+     */
     _styles: {
       ...ELEMENT_STYLE_TYPE,
       get({ hideBreakpoint }) {

package/components/FilterChip.js

@@ -2,12 +2,21 @@ import './Icon.js';
 
 import Chip from './Chip.js';
 
+/**
+ * Filter chips use tags or descriptive words to filter content.
+ * They can be a good alternative to toggle buttons or checkboxes.
+ * @see https://m3.material.io/components/chips/specs
+ */
 export default Chip
   .extend()
   .observe({
+    /** Type of the chip; defaults to 'checkbox' for filter behavior. */
     type: { empty: 'checkbox' },
+    /** When true, shows a dropdown caret as the trailing icon. */
     dropdown: 'boolean',
+    /** Source URL for a trailing image/icon. */
     trailingSrc: 'string',
+    /** Name of the trailing icon to show. */
     trailingIcon: 'string',
   })
   .expressions({

package/components/Grid.js

@@ -3,19 +3,28 @@ import ResizeObserverMixin from '../mixins/ResizeObserverMixin.js';
 
 import Box from './Box.js';
 
+/**
+ * Grid layout for arranging content into responsive columns.
+ * @see https://m3.material.io/foundations/layout/understanding-layout/parts-of-layout
+ */
 export default Box
   .extend()
   .mixin(ResizeObserverMixin)
   .observe({
+    /** Enable CSS grid layout for children. */
     grid: 'boolean',
+    /** Explicit number of columns; when set, disables auto column calculation. */
     columns: 'integer',
+    /** Auto-calculated column count when `columns` is not provided. */
     _autoColumns: {
       type: 'integer',
       empty: 4,
     },
+    /** Last measured inline size (px) from ResizeObserver. */
     _lastInlineSize: 'float',
   })
   .observe({
+    /** Whether resize observer should be active (disabled when explicit columns set). */
     _resizeObserverEnabled: {
       type: 'boolean',
       get({ columns }) {
@@ -24,6 +33,7 @@ export default Box
         return !columns;
       },
     },
+    /** Computed number of columns (either `columns` or `_autoColumns`). */
     _computedColumns({ columns, _autoColumns }) {
       if (columns) return columns;
       if (_autoColumns) return _autoColumns;
@@ -31,6 +41,7 @@ export default Box
     },
   })
   .overrides({
+    /** Update last observed inline size from ResizeObserver entry. */
     onResizeObserved(entry) {
       const { contentBoxSize } = entry;
       if (!contentBoxSize.length) return;