@shortfuse/materialdesignweb 0.9.0 → 0.9.2

package/components/Progress.js

@@ -1,26 +1,38 @@
-/* https://m3.material.io/components/progress-indicators/specs */
-
 import CustomElement from '../core/CustomElement.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
-// https://html.spec.whatwg.org/multipage/form-elements.html#the-progress-element
-
+/**
+ * Progress indicators display the progress of an operation as a determinate
+ * bar or an indeterminate animation.
+ * @see https://m3.material.io/components/progress-indicators/specs
+ * @see https://html.spec.whatwg.org/multipage/form-elements.html#the-progress-element
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .observe({
+    /** Render the circular variant when true; otherwise render a linear bar. */
     circle: 'boolean',
+    /** Current progress value. When present the indicator is determinate. */
     value: 'float',
+    /** Maximum progress value (defaults to 100 when not set). */
     max: 'float',
+    /** When true, the progress will auto-hide when complete. */
     autoHide: 'boolean',
+    /** Internal inline style string used to animate the determinate bar. */
     _determinateStyle: 'string',
   })
   .observe({
+    /**
+     * Computed fractional progress (0.0–1.0) derived from `value` and `max`.
+     * Used to drive the determinate animation and CSS variables.
+     */
     _valueAsFraction: {
       type: 'float',
       get({ value, max }) {
         return (value / (max || 100));
       },
+      /** Update `_determinateStyle` CSS variables when the fraction changes. */
       changedCallback(oldValue, newValue) {
         this._determinateStyle = `
         --previous:${oldValue ?? newValue ?? 0};
@@ -29,10 +41,18 @@ export default CustomElement
       },
     },
   })
+  .expressions({
+    /** True when `value` is provided, indicating a determinate progress state. */
+    isDeterminate({ value }) {
+      return value != null;
+    },
+  })
   .define({
+    /** Proxy to the internal `<progress>` element's `position` property. */
     position() {
       return /** @type {HTMLProgressElement} */ (this.refs.progress).position;
     },
+    /** Proxy to the internal `<progress>` element's `labels` collection. */
     labels() {
       return /** @type {HTMLProgressElement} */ (this.refs.progress).labels;
     },
@@ -45,7 +65,7 @@ export default CustomElement
         <div id=semi2 class=semi></div>
       </div>
     </div>
-    <div mdw-if={!value} id=indeterminate>
+    <div mdw-if={!isDeterminate} id=indeterminate>
       <div mdw-if={!circle} id=indeterminate-line>
         <div id=line1 class=line value={value}></div>
         <div id=line2 class=line value={value}></div>

package/components/Radio.js

@@ -1,5 +1,3 @@
-/* https://m3.material.io/components/radio/specs */
-
 import './RadioIcon.js';
 
 import CustomElement from '../core/CustomElement.js';
@@ -9,6 +7,10 @@ import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 import TouchTargetMixin from '../mixins/TouchTargetMixin.js';
 
+/**
+ * Radio buttons allow selection of a single option within a set.
+ * @see https://m3.material.io/components/radio-button/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -17,7 +19,9 @@ export default CustomElement
   .mixin(InputMixin)
   .mixin(TouchTargetMixin)
   .set({
+    /** Native control `type` used for the underlying input; always 'radio'. */
     type: 'radio',
+    /** Forces Material state-layer overlay for pressed/hover states. */
     stateLayer: true,
   })
   .html`

package/components/RadioIcon.js

@@ -4,20 +4,33 @@ import CustomElement from '../core/CustomElement.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Visual helper for radio buttons, rendering the outer and inner rings.
+ * @see https://m3.material.io/components/radio-button/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(ShapeMixin)
   .observe({
+    /** Whether the radio icon is selected (checked). */
     selected: 'boolean',
+    /** Optional icon name to render inside the control (not normally used). */
     icon: 'string',
+    /** When true the control is shown in an error state. */
     errored: 'boolean',
+    /** When true the control is disabled. */
     disabled: 'boolean',
+    /** Hover state used for styling. */
     hovered: 'boolean',
+    /** Focus state used for styling. */
     focused: 'boolean',
   })
   .define({
-    /** Alias for Selected (QoL) */
+    /**
+     * Alias for `selected` to match common form terminology (`checked`).
+     * Reading/writing `checked` proxies to the `selected` state.
+     */
     checked: {
       get() { return this.selected; },
       set(value) { this.selected = value; },

package/components/Ripple.js

@@ -1,6 +1,12 @@
 import CustomElement from '../core/CustomElement.js';
 import { ELEMENT_ANIMATION_TYPE } from '../core/customTypes.js';
 
+/**
+ * Ripple is a visual touch feedback effect used by controls to indicate
+ * pointer/touch interaction. It renders and animates a circular ink ripple
+ * and exposes properties to control its position, size, and lifecycle.
+ * @see https://m3.material.io/foundations/interaction/states/applying-states
+ */
 export default CustomElement
   .extend()
   .set({
@@ -9,11 +15,17 @@ export default CustomElement
     rippleStarted: false,
   })
   .observe({
+    /** Current lifecycle state for the ripple (e.g. 'filled', 'complete'). */
     rippleState: 'string',
+    /** When true, keep the ripple in the DOM after animation ends. */
     keepAlive: 'boolean',
+    /** X offset (px) from center used to position the ripple. */
     _positionX: 'float',
+    /** Y offset (px) from center used to position the ripple. */
     _positionY: 'float',
+    /** Computed ripple radius (px) used for sizing/animation. */
     _radius: 'float',
+    /** Hold the ripple (e.g. for long-press); triggers hold/release tracking. */
     holdRipple: {
       type: 'boolean',
       changedCallback(oldValue, newValue) {
@@ -26,6 +38,7 @@ export default CustomElement
     },
   })
   .observe({
+    /** Computed animation/style object used to position and size the ripple. */
     _positionStyle: {
       ...ELEMENT_ANIMATION_TYPE,
       get({ _positionX, _positionY, _radius }) {
@@ -82,6 +95,7 @@ export default CustomElement
       this._positionY = y - (parentHeight / 2);
       this._radius = hypotenuse;
     },
+    /** Complete the ripple lifecycle: either mark complete or remove. */
     handleRippleComplete() {
       if (this.keepAlive) {
         this.setAttribute('ripple-state', 'complete');

package/components/Root.js

@@ -5,6 +5,11 @@ import { ELEMENT_ANIMATION_TYPE } from '../core/customTypes.js';
 import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 import ScrollListenerMixin from '../mixins/ScrollListenerMixin.js';
 
+/**
+ * Root is the application's top-level container that manages layout regions and
+ * shared floating areas such as bottom bars.
+ * @see https://m3.material.io/foundations/layout/applying-layout/window-size-classes
+ */
 export default CustomElement
   .extend()
   .mixin(ScrollListenerMixin)
@@ -25,12 +30,21 @@ export default CustomElement
     <slot id=end name=end></slot>
   `
   .observe({
+    /** Measured height (px) of the bottom area used to compute reveal offsets. */
     _bottomHeight: { type: 'float', empty: 0 },
+    /** Current vertical offset (px) applied to the bottom area for reveal/hide. */
     _bottomOffsetY: { type: 'float', empty: 0 },
+    /** Animation duration (ms) used when adjusting bottom offset. */
     _bottomDuration: { type: 'float', empty: 0 },
+    /** Animation easing name used when animating bottom reveal/hide. */
     _bottomEasing: { empty: 'ease-in' },
   })
   .observe({
+    /**
+     * Computed shared animation/style object for bottom areas used to
+     * translate and time reveal/hide animations. Returns null when height
+     * is zero (no bottom content measured).
+     */
     _sharedBottomStyle({ _bottomOffsetY, _bottomDuration, _bottomEasing, _bottomHeight }) {
       if (!_bottomHeight) return null;
       return {
@@ -45,6 +59,7 @@ export default CustomElement
     },
   })
   .observe({
+    /** Animation/style object targeting the bottom slot element. */
     _bottomSlotStyle: {
       ...ELEMENT_ANIMATION_TYPE,
       get({ _sharedBottomStyle }) {
@@ -55,6 +70,7 @@ export default CustomElement
         };
       },
     },
+    /** Animation/style object targeting the bottom-fixed-slot element. */
     _bottomFixedSlotStyle: {
       ...ELEMENT_ANIMATION_TYPE,
       get({ _sharedBottomStyle }) {

package/components/Scrim.js

@@ -1,8 +1,14 @@
 import CustomElement from '../core/CustomElement.js';
 
+/**
+ * A scrim can bring focus to specific elements by increasing the visual contrast of a large layered surface.
+ * Use the scrim beneath elements like modals and expanded navigation menus.
+ * @see https://m3.material.io/styles/elevation/applying-elevation
+ */
 export default CustomElement
   .extend()
   .observe({
+    /** When true the scrim is hidden and will be removed after its fade-out animation. */
     hidden: 'boolean',
   })
   .html`<div id=scroll-blocker></div>`
@@ -19,7 +25,7 @@ export default CustomElement
       scrollbar-color: transparent transparent;
       scrollbar-width: none;
 
-      cursor:pointer;
+      cursor: pointer;
 
       outline: none; /* Older Chromium Builds */
       
@@ -81,7 +87,9 @@ export default CustomElement
   `
   .events({
     animationend() {
-      if (this.hidden) this.remove();
+      if (this.hidden) {
+        this.remove();
+      }
     },
   })
   .autoRegister('mdw-scrim');

package/components/Search.js

@@ -1,6 +1,10 @@
 import TopAppBar from './TopAppBar.js';
 
-/* @implements {HTMLSelectElement} */
+/**
+ * Search provides an app bar integrated search field for querying content.
+ * implements {HTMLSelectElement}
+ * @see https://m3.material.io/components/search/overview
+ */
 export default TopAppBar
   .extend()
   .undefine('headline')
@@ -8,18 +12,27 @@ export default TopAppBar
   .undefine('size')
   .undefine('_headlineStyle')
   .observe({
+    /** Placeholder text shown in the search input. */
     placeholder: { type: 'string', empty: 'Search' },
+    /** Visual color token to apply to the search surface. */
     color: { empty: 'surface-container-high' },
+    /** Shape style token to apply (e.g. 'full', 'none'). */
     shapeStyle: { empty: 'full' },
+    /** Enable keyboard navigation mode for search results when true. */
     kbdNav: { empty: 'false' },
   })
   .define({
-    /** @return {HTMLInputElement} */
-    input() { return this.refs.input; },
+    /** Returns the current text value of the internal input. */
+    input() {
+      return /** @type {HTMLInputElement} */ (this.refs.input).value;
+    },
+    /** The `value` accessor proxies the internal input's value. */
     value: {
-      get() { return this.refs.input.value; },
+      get() {
+        return /** @type {HTMLInputElement} */ (this.refs.input).value;
+      },
       set(value) {
-        this.refs.input.value = value;
+        /** @type {HTMLInputElement} */ (this.refs.input).value = value;
       },
     },
   })

package/components/SegmentedButton.js

@@ -2,16 +2,24 @@ import './Icon.js';
 
 import Button from './Button.js';
 
-/* https://m3.material.io/components/segmented-buttons/specs */
-
+/**
+ * Segmented buttons group individual related actions or options where
+ * multiple choices are presented inline; each segment acts like a toggle
+ * or option within a set.
+ * @see https://m3.material.io/components/segmented-buttons/specs
+ */
 export default Button
   .extend()
   .observe({
+    /** Interaction model for the segment: 'radio' (single select) or 'checkbox' (multi-select). */
     type: { empty: 'radio' },
+    /** When true this segment is rendered as an inner segment inside a segmented group. */
     innerSegmentedButton: 'boolean',
   })
   .set({
+    /** Render the button with an outline style. */
     outlined: true,
+    /** Allow the control to receive focus even when disabled. */
     focusableOnDisabled: true,
   })
   .recompose(({ html, inline, refs: { icon, outline, control, slot, state } }) => {
@@ -41,7 +49,7 @@ export default Button
   })
   .css`
     :host {
-      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size: 0;
       --mdw-ink: var(--mdw-color__on-surface);
       gap: 8px;
 
@@ -52,8 +60,16 @@ export default Button
       color: rgb(var(--mdw-ink));
     }
 
-    :host([inner-segmented-button]) {
-      --mdw-shape__size: 0px;
+    :host(:first-of-type) {
+      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size__top-end-size: 0px;
+      --mdw-shape__size__bottom-end-size: 0px;
+    }
+
+    :host(:last-of-type) {
+      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size__top-start-size: 0px;
+      --mdw-shape__size__bottom-start-size: 0px;
     }
 
     #outline {
@@ -62,7 +78,7 @@ export default Button
       z-index: -1;
     }
 
-    #outline[shape-end] {
+    :host(:last-of-type) #outline {
       inset-inline-end: 0;
     }
 

package/components/SegmentedButtonGroup.js

@@ -5,6 +5,11 @@ import SegmentedButton from './SegmentedButton.js';
 
 /** @typedef {'compact'} DeprecatedHTMLMenuElementProperties */
 
+/**
+ * A segmented button group arranges multiple `mdw-segmented-button` items
+ * so they behave as a related set of choices or toggles.
+ * @see https://m3.material.io/components/segmented-buttons/specs
+ */
 export default Box
   .extend()
   .mixin(KeyboardNav)
@@ -18,15 +23,7 @@ export default Box
   })
   .childEvents({
     slot: {
-      slotchange() {
-        this.refreshTabIndexes();
-        const list = /** @type {NodeListOf<InstanceType<SegmentedButton>>} */ (this.kbdNavChildren);
-        for (const [index, child] of list.entries()) {
-          child.shapeStart = index === 0;
-          child.innerSegmentedButton = index > 0 && index < list.length - 1;
-          child.shapeEnd = index === list.length - 1;
-        }
-      },
+      slotchange: 'refreshTabIndexes',
     },
   })
   .css`
@@ -45,7 +42,7 @@ export default Box
 
       box-sizing: border-box;
       min-inline-size: 100%;
-      flex:none;
+      flex: none;
     }
 
     :host([color]) {

package/components/Select.js

@@ -4,7 +4,11 @@ import StateMixin from '../mixins/StateMixin.js';
 import TextFieldMixin from '../mixins/TextFieldMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
-/* @implements {HTMLSelectElement} */
+/**
+ * Select provides a control for choosing an option from a list of options.
+ * implements {HTMLSelectElement}
+ * @see https://m3.material.io/components/text-fields/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -12,6 +16,7 @@ export default CustomElement
   .mixin(ControlMixin)
   .mixin(TextFieldMixin)
   .observe({
+    /** Name of the trailing icon to render (defaults to the dropdown arrow). */
     trailingIcon: { empty: 'arrow_drop_down' },
   })
   .overrides({
@@ -20,11 +25,13 @@ export default CustomElement
     type: 'select-one',
   })
   .define({
+    /** Return the internal native <select> element used as the control. */
     _select() {
       return /** @type {HTMLSelectElement} */ (this.refs.control);
     },
-    /** Readonly values */
+    /** Readonly: whether the underlying control allows multiple selection. */
     multiple: { value: false },
+    /** Readonly: the rendered size of the native select control. */
     size: { value: 1 },
   })
   .html`<slot id=slot></slot>`
@@ -48,9 +55,12 @@ export default CustomElement
     suffix.remove();
   })
   .on({
+    /** When the form resets, restore the select value from any option[selected]. */
     _formResetChanged(oldValue, newValue) {
       if (!newValue) return;
-      this._select.value = this.querySelector('option[selected]')?.value ?? '';
+      /** @type {HTMLSelectElement} */
+      const selectedOption = this.querySelector('option[selected]');
+      this._select.value = selectedOption?.value ?? '';
     },
   })
   .css`

package/components/Shape.js

@@ -1,6 +1,10 @@
 import CustomElement from '../core/CustomElement.js';
 import ShapeMaskedMixin from '../mixins/ShapeMaskedMixin.js';
 
+/**
+ * Shape applies shape tokens (corner radius) to elements and surfaces.
+ * @see https://m3.material.io/styles/shape/overview-principles
+ */
 export default CustomElement
   .extend()
   .mixin(ShapeMaskedMixin)

package/components/SideSheet.js

@@ -28,6 +28,11 @@ const SUPPORTS_SCROLLEND = 'onscrollend' in window;
  * Modal side sheets must become "dialog-like", blocking access to all other elements on the screen.
  * Modal side sheets can display elevation
  */
+/**
+ * Side sheets present content in a surface that slides in from an edge; they
+ * support modal and static modes and can be themed and shaped.
+ * @see https://m3.material.io/components/side-sheets/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -38,40 +43,58 @@ export default CustomElement
   .mixin(DelegatesFocusMixin)
   .mixin(ResizeObserverMixin)
   .observe({
+    /** When true the side sheet is fixed (non-modal/static), occupying layout space. */
     fixed: 'boolean',
+    /** Whether the sheet is currently open (visible). */
     open: 'boolean',
+    /** When true, position the sheet at the inline end edge. */
     inlineEnd: 'boolean',
+    /** Last measured inline size (px) used for layout/translate calculations. */
     _lastComputedInlineSize: {
       type: 'float',
       nullable: false,
     },
+    /** Animation duration (ms) for sheet open/close transitions. */
     _animationDuration: {
       type: 'integer',
       value: 0,
     },
+    /** Animation easing keyword used for sheet transitions. */
     _animationEasing: {
       value: 'ease-out',
     },
+    /** Current drag delta X (px) while user is swiping the sheet. */
     _dragDeltaX: 'float',
+    /** Starting X coordinate (px) for a drag gesture. */
     _dragStartX: 'float',
+    /** CSS translateX value used to animate the sheet position. */
     _translateX: { value: '-100%' },
+    /** Timestamp of the last child scroll event (used to avoid gesture conflicts). */
     _lastChildScrollTime: 'float',
+    /** Event handler invoked when the sheet toggles. */
     ontoggle: EVENT_HANDLER_TYPE,
+    /** Event handler invoked when the sheet closes. */
     onclose: EVENT_HANDLER_TYPE,
+    /** Optional auto-open minimum viewport inline-size (px); -1 disables. */
     autoOpen: {
       type: 'float',
       empty: -1,
     },
+    /** Optional auto-close maximum viewport inline-size (px); -1 disables. */
     autoClose: {
       type: 'float',
       empty: -1,
     },
+    /** Inline-size breakpoint (px) at which the sheet becomes `fixed`. */
     fixedBreakpoint: {
       type: 'float',
       empty: 0,
     },
+    /** Internal flag computed from directionality and `inlineEnd`. */
     _isSideSheetRtl: 'boolean',
+    /** The theme color token used for the sheet background. */
     color: 'string',
+    /** Optional fixed-mode color token applied when sheet is fixed. */
     fixedColor: 'string',
   })
   .set({
@@ -79,6 +102,7 @@ export default CustomElement
     _scrim: null,
   })
   .observe({
+    /** Computed host style when `fixed` and `fixedColor` are set. */
     _styles: {
       ...ELEMENT_STYLE_TYPE,
       get({ fixed, fixedColor }) {
@@ -87,6 +111,7 @@ export default CustomElement
         }
       },
     },
+    /** Computed animation/style object applied to the host for open/close. */
     hostStyles: {
       ...ELEMENT_ANIMATION_TYPE,
       get({
@@ -110,6 +135,10 @@ export default CustomElement
   })
   .html`<slot id=slot></slot>`
   .methods({
+    /**
+     * Ensure a scrim is present when the sheet is modal (open && !fixed).
+     * When `animate` is true, keep the scrim around to run its fade-out.
+     */
     checkForScrim(animate = false) {
       let { open, fixed, _scrim } = this;
       if (open && !fixed) {
@@ -133,6 +162,7 @@ export default CustomElement
         _scrim.hidden = true;
       }
     },
+    /** Evaluate drag state and decide whether to close or snap open. */
     checkDragFinished() {
       const { open, _dragDeltaX, _lastComputedInlineSize, fixed, _isSideSheetRtl } = this;
       if (!open || fixed || _dragDeltaX == null) return;
@@ -150,9 +180,8 @@ export default CustomElement
         this._translateX = '0';
         this._animationEasing = 'ease-in';
       }
-      this._dragDeltaY = null;
-      this._dragStartY = null;
     },
+    /** Recompute `fixed`/`open` state based on the window width and breakpoints. */
     onWindowResize() {
       const { autoOpen, fixedBreakpoint, autoClose } = this;
       const containerWidth = window.innerWidth;

package/components/Slider.js

@@ -32,6 +32,10 @@ function valueAsFraction(value, min, max) {
   return (nValue - nMin) / (nMax - nMin);
 }
 
+/**
+ * Slider allows users to select a value from a range by dragging a thumb.
+ * @see https://m3.material.io/components/sliders/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -42,18 +46,26 @@ export default CustomElement
     type: 'range',
   })
   .observe({
-    ticks: 'string',
+    /** Number of tick marks to show along the track (integer). */
+    ticks: 'integer',
+    /** Internal string representation of the current value used for formatting. */
     _valueAsText: { nullable: false },
+    /** Text to show in the thumb label; when null the numeric value is shown. */
     thumbLabel: {
       type: 'string',
       reflect: 'read',
     },
+    /** Rounded numeric value (used while dragging) tracked as a float. */
     _roundedValue: 'float',
+    /** True while the pointer is hovering the thumb (used to show the label). */
     _isHoveringThumb: 'boolean',
+    /** Last `value` string that produced a dispatched `change` event; used to avoid duplicates. */
     _lastDispatchedChangeValue: 'string',
   })
   .methods({
     /**
+     * Handle pointer or touch interactions on the native control to compute
+     * position and update the intermediate rounded value while dragging.
      * @param {(MouseEvent|TouchEvent) & {currentTarget:HTMLInputElement}} event
      * @return {void}
      */
@@ -155,13 +167,18 @@ export default CustomElement
       this._isHoveringThumb = offsetX >= thumbMin && offsetX <= thumbMax;
     },
 
-    /** @param {Event} event */
+    /**
+     * Pointer leave/blur handler for the control; hides the thumb label when focus is lost.
+     * @param {Event} event
+     */
     onLeaveEvent({ currentTarget }) {
       if (isFocused(/** @type {Element} */ (currentTarget))) return;
       this._isHoveringThumb = false;
     },
 
     /**
+     * Finalize interaction with the control: commit the rounded value to the
+     * native input and dispatch a `change` event if the value changed.
      * @param {(MouseEvent|TouchEvent) & {currentTarget:HTMLInputElement}} event
      * @return {void}
      */
@@ -206,15 +223,18 @@ export default CustomElement
     },
   })
   .expressions({
+    /** Compute inline style variables for the track, including ticks and value fraction. */
     computeTrackStyle({ ticks, _valueAsText, min, max }) {
       return [
         ticks ? `--ticks:${ticks}` : null,
         `--value:${valueAsFraction(_valueAsText, min, max)}`,
       ].filter(Boolean).join(';') || null;
     },
+    /** True when the thumb label should be hidden (not hovering and not focused). */
     _thumbLabelHidden({ _isHoveringThumb, focusedState }) {
       return (!_isHoveringThumb && !focusedState);
     },
+    /** Compute the label text to show in the thumb: explicit `thumbLabel` or numeric value. */
     _computedThumbLabel({ thumbLabel, _valueAsText }) {
       return thumbLabel ?? _valueAsText;
     },