@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/Page.js

@@ -0,0 +1,119 @@
+/* https://m3.material.io/foundations/layout/applying-layout/window-size-classes */
+
+import CustomElement from '../core/CustomElement.js';
+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 }) {
+        if (_isMultipane) {
+          return `:host{grid-template-columns:${paneOne === 'fixed' ? '360px' : '1fr'} ${this.paneTwo === 'fixed' ? '360px' : '1fr'}}`;
+        }
+        if (paneTwoActive) {
+          return ':host{grid-template-columns:1fr 0}#slot{display:none}';
+        }
+        return ':host{grid-template-columns:1fr 0}#two{display:none}';
+      },
+    },
+  })
+  .html`
+    <slot id=slot mutli-pane={_isMultipane}></slot>
+    <slot id=two name=two mutli-pane={_isMultipane}></slot>
+  `
+  .css`
+    :host {
+      --mdw-pane__max-width: 1040px;
+      --mdw-pane__margin-inline: 16px;
+      --mdw-pane__padding-inline: max(var(--mdw-pane__margin-inline), calc((100% - var(--mdw-pane__max-width)) / 2));
+      --mdw-pane__shape__size: 0;
+      display: grid;
+      column-gap: var(--mdw-page__margin);
+      grid-auto-columns: 1fr;
+      grid-auto-flow: column;
+
+      block-size: 100%;
+
+      padding: 0;
+
+      font: var(--mdw-typescale__body-large__font);
+      letter-spacing: var(--mdw-typescale__body-large__letter-spacing);
+    }
+
+    @media (min-width: 648px) {
+      :host {
+        --mdw-pane__margin-inline: 24px;
+      }
+    }
+
+    @media (min-width: 728px) {
+      :host {
+        --mdw-pane__shape__size: var(--mdw-shape__large);
+      }
+    }
+
+    #slot[multi-pane] {
+      --mdw-pane__padding-inline: 24px;
+    }
+
+    #two[mutli-pane] {
+      --mdw-pane__padding-inline: 0 24px;
+      position: sticky;
+      inset-block:0;
+
+      display: flex;
+      flex-direction: column;
+
+      overflow-y:auto;
+
+      block-size: 100vh;
+      block-size: 100dvh;
+    }
+  `
+  .overrides({
+    /** Handle resize observer entries; update measured inline size for layout logic. */
+    onResizeObserved(entry) {
+      this._lastComputedInlineSize = entry.borderBoxSize[0]?.inlineSize;
+    },
+  })
+  .autoRegister('mdw-page');

package/components/Pane.js

@@ -0,0 +1,24 @@
+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)
+  .css`
+    :host {
+      --mdw-shape__size: var(--mdw-pane__shape__size, 0);
+      --mdw-bg: var(--mdw-color__surface);
+      --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

@@ -1,20 +1,35 @@
 import CustomElement from '../core/CustomElement.js';
+import ElevationMixin from '../mixins/ElevationMixin.js';
 import PopupMixin from '../mixins/PopupMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
-import SurfaceMixin from '../mixins/SurfaceMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * 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)
-  .mixin(SurfaceMixin)
+  .mixin(ElevationMixin)
   .mixin(ShapeMixin)
   .mixin(PopupMixin)
-  .on({
-    composed() {
-      const { shape, surface, dialog } = this.refs;
-      surface.append(shape);
-      dialog.prepend(surface);
-    },
+  .observe({
+    /** Elevation level (0–5) controlling the drop-shadow depth of the popup. */
+    elevation: 'integer',
   })
+  .css`
+    :host {
+      filter: var(--mdw-elevation__drop-shadow__0);
+
+      transition: filter 200ms;
+    }
+
+    :host(:where([elevation="1"])) { filter: var(--mdw-elevation__drop-shadow__1); }
+    :host(:where([elevation="2"])) { filter: var(--mdw-elevation__drop-shadow__2); }
+    :host(:where([elevation="3"])) { filter: var(--mdw-elevation__drop-shadow__3); }
+    :host(:where([elevation="4"])) { filter: var(--mdw-elevation__drop-shadow__4); }
+    :host(:where([elevation="5"])) { filter: var(--mdw-elevation__drop-shadow__5); }
+  `
   .autoRegister('mdw-popup');

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`
@@ -37,11 +41,8 @@ export default CustomElement
       }
     },
   })
-  .on({
-    composed() {
-      const { radio, rippleContainer, state } = this.refs;
-      radio.append(state, rippleContainer);
-    },
+  .recompose(({ refs: { radio, rippleContainer, state } }) => {
+    radio.append(state, rippleContainer);
   })
   .css`
     /* stylelint-disable liberty/use-logical-spec */

package/components/RadioIcon.js

@@ -1,34 +1,47 @@
+import './Shape.js';
+
 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; },
     },
   })
   .html`
-    <div id=inner-shape class=shape selected={selected}></div>
-  `.on({
-    composed() {
-      const { outline } = this.refs;
-      outline.removeAttribute('mdw-if');
-      outline.setAttribute('selected', '{selected}');
-    },
+    <mdw-shape id=inner-shape selected={selected}></div>
+  `
+  .recompose(({ refs: { outline } }) => {
+    outline.removeAttribute('mdw-if');
+    outline.setAttribute('selected', '{selected}');
   })
   .css`
     /* https://m3.material.io/components/radio-button/specs */
@@ -52,16 +65,11 @@ export default CustomElement
     }
 
     #outline {
-      filter:
-        drop-shadow(1px 0px 0px var(--color))
-        drop-shadow(0px 1px 0px var(--color))
-        drop-shadow(-1px 0px 0px var(--color))
-        drop-shadow(0px -1px 0px var(--color))
-        ;
+      border-width: 2px;
 
       color: var(--color);
 
-      will-change: filter, color;
+      will-change: color;
     }
 
     #inner-shape {
@@ -71,6 +79,7 @@ export default CustomElement
       transform: scale(0);
 
       background-color: var(--color);
+      border-radius: inherit;
 
       transition: transform 200ms, background-color 100ms;
     }

package/components/Ripple.js

@@ -1,6 +1,12 @@
 import CustomElement from '../core/CustomElement.js';
-import { ELEMENT_STYLER_TYPE } from '../core/customTypes.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,13 +38,16 @@ export default CustomElement
     },
   })
   .observe({
+    /** Computed animation/style object used to position and size the ripple. */
     _positionStyle: {
-      ...ELEMENT_STYLER_TYPE,
+      ...ELEMENT_ANIMATION_TYPE,
       get({ _positionX, _positionY, _radius }) {
+        // Skip if not measured
+        if (_radius == null) return null;
         return {
           styles: {
-            minBlockSize: `${_radius}px`,
-            minInlineSize: `${_radius}px`,
+            minHeight: `${_radius}px`,
+            minWidth: `${_radius}px`,
             boxShadow: `0 0 calc(0.10 * ${_radius}px) calc(0.10 * ${_radius}px) currentColor`,
             top: `calc(50% + ${_positionY}px)`,
             left: `calc(50% + ${_positionX}px)`,
@@ -53,14 +68,16 @@ export default CustomElement
       // Use offset to calculate parent size;
 
       let hypotenuse = size;
-      const { clientWidth: parentWidth, clientHeight: parentHeight } = this.offsetParent;
+      const { offsetParent } = this;
+      if (!offsetParent) return;
+      const { clientWidth: parentWidth, clientHeight: parentHeight } = offsetParent;
 
       x ??= parentWidth / 2;
       y ??= parentHeight / 2;
       if (!hypotenuse) {
         const width = (x >= parentWidth / 2) ? x : (parentWidth - x);
         const height = (y >= parentHeight / 2) ? y : (parentHeight - y);
-        hypotenuse = 2 * Math.sqrt((width * width) + (height * height));
+        hypotenuse = 2 * Math.hypot(width, height);
       }
 
       // const expandDuration = Math.min(
@@ -78,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');
@@ -99,7 +117,7 @@ export default CustomElement
     animationend({ animationName }) {
       switch (animationName) {
         case 'ripple-fade-in':
-          this.setAttribute('ripple-state', 'filled');
+          this.rippleState = 'filled';
           break;
         case 'ripple-fade-out':
           this.handleRippleComplete();

package/components/Root.js

@@ -0,0 +1,225 @@
+/* https://m3.material.io/foundations/layout/applying-layout/window-size-classes */
+
+import CustomElement from '../core/CustomElement.js';
+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)
+  .mixin(DelegatesFocusMixin)
+  .set({
+    /** @type {ResizeObserver} */
+    _bottomResizeObserver: null,
+  })
+  .html`
+    <slot id=start name=start></slot>
+    <div id=bottom>
+      <slot id=bottom-slot name=bottom></slot>
+    </div>
+    <div id=bottom-fixed>
+      <slot id=bottom-fixed-slot name=bottom-fixed></slot>
+    </div>
+    <slot id=slot></slot>
+    <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 {
+        styles: {
+          transform: `translateY(${_bottomOffsetY}px)`,
+        },
+        timing: {
+          duration: _bottomDuration,
+          easing: _bottomEasing,
+        },
+      };
+    },
+  })
+  .observe({
+    /** Animation/style object targeting the bottom slot element. */
+    _bottomSlotStyle: {
+      ...ELEMENT_ANIMATION_TYPE,
+      get({ _sharedBottomStyle }) {
+        if (!_sharedBottomStyle) return null;
+        return {
+          target: 'bottom-slot',
+          ..._sharedBottomStyle,
+        };
+      },
+    },
+    /** Animation/style object targeting the bottom-fixed-slot element. */
+    _bottomFixedSlotStyle: {
+      ...ELEMENT_ANIMATION_TYPE,
+      get({ _sharedBottomStyle }) {
+        if (!_sharedBottomStyle) return null;
+        return {
+          target: 'bottom-fixed-slot',
+          ..._sharedBottomStyle,
+        };
+      },
+    },
+  })
+  .on({
+    _scrollListenerPositionYChanged(oldValue, newValue) {
+      const delta = newValue - oldValue;
+
+      this._bottomDuration = 0;
+      // 0 if disabled or has scrolled upto element
+      // Valid range : 0 > x > (100% - required)
+      const bottomStartsAt = (document.documentElement.scrollHeight - window.innerHeight - 1);
+      const distanceFromBottom = bottomStartsAt - newValue;
+      const scrollVisible = this._bottomHeight - distanceFromBottom;
+      let mustIncludeSpace = 0;
+      if (scrollVisible > 0) {
+        mustIncludeSpace = scrollVisible;
+      }
+
+      this._bottomOffsetY = (newValue === 0 || distanceFromBottom < 0)
+        ? 0
+        : Math.max(0, Math.min(
+          this._bottomOffsetY + delta,
+          this._bottomHeight - mustIncludeSpace,
+        ));
+    },
+    _scrollListenerLastIdleChanged() {
+      const { _bottomHeight, _bottomOffsetY } = this;
+      const visibility = (_bottomHeight - _bottomOffsetY) / _bottomHeight;
+      if (visibility <= 0) return;
+      if (visibility >= 1) return;
+      if (visibility < 0.5) {
+        const bottomStartsAt = (document.documentElement.scrollHeight - window.innerHeight - 1);
+        const { _scrollListenerPositionY } = this;
+        const distanceFromBottom = bottomStartsAt - _scrollListenerPositionY;
+        const scrollVisible = _bottomHeight - distanceFromBottom;
+
+        if (_scrollListenerPositionY !== 0 && distanceFromBottom >= 0 && scrollVisible <= 0) {
+          this._bottomDuration = 200;
+          this._bottomEasing = 'ease-out';
+          this._bottomOffsetY = _bottomHeight;
+          return;
+        }
+      }
+
+      // Reveal all
+      this._bottomDuration = 250;
+      this._bottomEasing = 'ease-in';
+      this._bottomOffsetY = 0;
+    },
+    connected() {
+      // eslint-disable-next-line no-multi-assign
+      const observer = (this._bottomResizeObserver ??= new ResizeObserver((entries) => {
+        for (const { borderBoxSize } of entries) {
+          this._bottomHeight = borderBoxSize[0].blockSize;
+        }
+      }));
+      observer.observe(this.refs.bottom);
+      this.startScrollListener(window);
+    },
+    disconnected() {
+      this._scrollListenerClear();
+      this._bottomResizeObserver.unobserve(this.refs.bottom);
+    },
+  })
+  .css`
+    :host {
+      position: relative;
+
+      display: grid;
+      grid-template:
+        "start top     end" auto
+        "start content end" minmax(auto, 1fr)
+        "start bottom  end" auto
+        / minmax(0px, auto) minmax(0px, 100%) minmax(0px, auto);
+
+      min-block-size: 100vh;
+      min-block-size: 100dvh;
+
+      font: var(--mdw-typescale__body-large__font);
+      letter-spacing: var(--mdw-typescale__body-large__letter-spacing);
+    }
+
+    #start {
+      display: flex;
+      grid-area: start;
+    }
+
+    #slot {
+      display: block;
+      grid-area: content;
+      overflow-x: clip;
+
+    }
+
+    #end {
+      display: none;
+
+      grid-area: end;
+
+      block-size: 0;
+    }
+
+    #bottom {
+      position: sticky;
+      inset-block-end: 0;
+
+      display: block;
+      grid-area: bottom;
+      overflow-y: hidden;
+
+      pointer-events: none;
+
+      z-index: 1;
+    }
+
+    #bottom-slot {
+      position: sticky;
+      inset-block-end: 0;
+
+      display: flex;
+      /* Tab order flows from bottom-up */
+      flex-direction: column-reverse;
+    }
+
+    #bottom-fixed {
+      position: sticky;
+      inset-block-end: 0;
+
+      display: block;
+      grid-area: bottom; /* Takes but does not dictate size of bottom area */
+
+      pointer-events: none;
+
+      z-index: 2;
+    }
+
+    #bottom-fixed-slot {
+      position: absolute;
+      inset-block-end: 100%;
+
+      display: block;
+    }
+  `
+  .autoRegister('mdw-root');