@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/mixins/RTLObserverMixin.js

@@ -4,11 +4,13 @@ const registeredElements = new Set();
 let rtlObserver;
 
 /**
+ * Observes document `dir` changes and updates `pageIsRTL` on hosts.
  * @param {typeof import('../core/CustomElement.js').default} Base
  */
 export default function RTLObserverMixin(Base) {
   return Base
     .observe({
+      /** Whether the page/document direction is RTL; kept in sync */
       pageIsRTL: {
         type: 'boolean',
         value: document.documentElement.dir === 'rtl',

package/mixins/ResizeObserverMixin.js

@@ -6,12 +6,17 @@ const resizeObserver = new ResizeObserver((entries) => {
 });
 
 /**
+ * Attaches a shared ResizeObserver to the element and provides lifecycle helpers.
  * @param {typeof import('../core/CustomElement.js').default} Base
  */
 export default function ResizeObserverMixin(Base) {
   return Base
-    .set({
-      observeResizeOnConnected: true,
+    .observe({
+      /** Enable or disable automatic ResizeObserver attachment (defaults true) */
+      _resizeObserverEnabled: {
+        type: 'boolean',
+        value: true,
+      },
     })
     .methods({
       /** @param {ResizeObserverEntry} entry */
@@ -19,7 +24,9 @@ export default function ResizeObserverMixin(Base) {
         // Virtual function
       },
       observeResize() {
-        resizeObserver.observe(this);
+        resizeObserver.observe(this, {
+          box: 'border-box',
+        });
       },
       unobserveResize() {
         resizeObserver.unobserve(this);
@@ -27,11 +34,18 @@ export default function ResizeObserverMixin(Base) {
     })
     .on({
       connected() {
-        if (!this.observeResizeOnConnected) return;
+        if (!this._resizeObserverEnabled) return;
         this.observeResize();
       },
       disconnected() {
         this.unobserveResize();
       },
+      _resizeObserverEnabledChanged(previous, enabled) {
+        if (enabled) {
+          this.observeResize();
+        } else {
+          this.unobserveResize();
+        }
+      },
     });
 }

package/mixins/RippleMixin.js

@@ -3,14 +3,16 @@ import Ripple from '../components/Ripple.js';
 /** @typedef {import('../components/Ripple.js').default} Ripple */
 
 /**
+ * Provides visual ripple effects (pointer/press ripples) and helpers to add/remove them.
  * @param {ReturnType<import('./StateMixin.js').default>} Base
  */
 export default function RippleMixin(Base) {
   return Base
     .set({
+      /** WeakRef to the last appended Ripple instance (used to release/hold) */
       /** @type {WeakRef<InstanceType<Ripple>>} */
       _lastRippleWeakRef: null,
-      /** Flag set if ripple was added this event loop. */
+      /** Flag set if ripple was added this event loop to avoid duplicate ripples */
       _rippleAdded: false,
     })
     .define({
@@ -67,8 +69,8 @@ export default function RippleMixin(Base) {
         if (lastRipple) {
           lastRipple.holdRipple = false;
         }
-        console.debug('ripple from pointerdown');
-        this.addRipple(x, y);
+        // Ripple from pointerdown
+        this.addRipple(x, y, true);
       },
       '~click'(e) {
         if (this._rippleAdded) {
@@ -77,17 +79,17 @@ export default function RippleMixin(Base) {
         }
         if (e.pointerType || e.detail) return;
         if (this.disabledState) return;
-        if (this._pressed) return;
+        if (this.pressedState || this._keyReleased) return;
         const lastRipple = this._lastRipple;
         if (lastRipple) {
           lastRipple.holdRipple = false;
         }
-        console.debug('ripple from programmatic click');
+        // Ripple from programmatic click
         this.addRipple();
       },
     })
     .on({
-      _pressedChanged(oldValue, pressed) {
+      pressedStateChanged(oldValue, pressed) {
         const ripple = this._lastRipple;
         if (!pressed) {
           if (ripple) {
@@ -100,7 +102,7 @@ export default function RippleMixin(Base) {
             // Sometimes pointer events may be out of order
             return;
           }
-          console.debug('ripple from press state');
+          // Ripple from pressed state
           this.addRipple(null, null, true);
           return;
         }
@@ -120,6 +122,8 @@ export default function RippleMixin(Base) {
         overflow: hidden;
       
         pointer-events: none;
+
+        border-radius: inherit;
       }
     `;
 }

package/mixins/ScrollListenerMixin.js

@@ -1,24 +1,34 @@
 const IDLE_TIMEOUT_MS = 500;
 
 /**
+ * Tracks scroll/resize positions and exposes scroll-related lifecycle helpers.
  * @param {typeof import('../core/CustomElement.js').default} Base
  */
 export default function ScrollListenerMixin(Base) {
   return Base
     .observe({
+      /** Current horizontal scroll position (px) */
       _scrollListenerPositionX: { type: 'float', empty: 0, reflect: false },
+      /** Current vertical scroll position (px) */
       _scrollListenerPositionY: { type: 'float', empty: 0, reflect: false },
+      /** Timestamp of the last idle period (ms) */
       _scrollListenerLastIdle: { type: 'float', empty: 0 },
+      /** Timestamp of the last scroll event (ms) */
       _scrollListenerLastScroll: { type: 'float', empty: 0 },
+      /** Timestamp of the last resize event (ms) */
       _scrollListenerLastResize: { type: 'float', empty: 0 },
     })
     .set({
-      /** @type {WeakRef<EventTarget>} */
+      /** WeakRef to the current scroller (HTMLElement or window) */
+      /** @type {WeakRef<HTMLElement|Window>} */
       _scroller: null,
+      /** Listener bound to scroller 'scroll' events */
       /** @type {EventListener} */
       _scrollerScrollListener: null,
+      /** Listener bound to scroller 'resize' events */
       /** @type {EventListener} */
       _scrollerResizeListener: null,
+      /** Internal debounce timer id used for idle detection */
       _scrollDebounce: null,
     })
     .methods({
@@ -51,7 +61,7 @@ export default function ScrollListenerMixin(Base) {
        * @return {boolean}
        */
       startScrollListener(scroller) {
-        scroller ??= this.offsetParent;
+        scroller ??= window;
         if (!scroller) return false;
 
         if (scroller === document.body) {
@@ -59,6 +69,7 @@ export default function ScrollListenerMixin(Base) {
           scroller = window;
         }
 
+        // @ts-expect-error Only HTMLElement or Window can scroll
         this._scroller = new WeakRef(scroller);
         this._scrollerScrollListener = this._scrollListenerOnScrollerScroll.bind(this);
         this._scrollerResizeListener = this._scrollListenerOnScrollerResize.bind(this);
@@ -82,6 +93,7 @@ export default function ScrollListenerMixin(Base) {
         if (scroller === window) {
           return document.documentElement.scrollHeight;
         }
+        // @ts-ignore Already checked for window
         return scroller.scrollHeight;
       },
       _scrollListenerScrollerClientHeight() {

package/mixins/SemiStickyMixin.js

@@ -1,4 +1,4 @@
-import { ELEMENT_STYLER_TYPE } from '../core/customTypes.js';
+import { ELEMENT_ANIMATION_TYPE } from '../core/customTypes.js';
 
 import ScrollListenerMixin from './ScrollListenerMixin.js';
 
@@ -10,42 +10,42 @@ export default function SemiStickyMixin(Base) {
   return Base
     .mixin(ScrollListenerMixin)
     .observe({
+      /** Measured full height of the element used for hiding calculations (px) */
       _semiStickyHeight: { type: 'float', empty: 0 },
+      /** Measured top offset used as reveal threshold (px) */
       _semiStickyOffsetY: { type: 'float', empty: 0 },
-      _semiStickyWidth: { type: 'float', empty: 0 },
-      _semiStickyOffsetX: { type: 'float', empty: 0 },
+      /** Current translateY applied to the element (px) */
       _semiStickyTranslateY: { type: 'float', empty: 0 },
-      _semiStickyTranslateX: { type: 'float', empty: 0 },
+      /** Animation duration when transitioning translateY (ms) */
       _semiStickyDuration: { type: 'float', empty: 0 },
+      /** Animation easing function for transitions */
       _semiStickyEasing: { empty: 'ease-in' },
-      _semiStickyAnchor: {
-        /** @type {'top'|'start'|'end'|'bottom'|'left'|'right'} */
-        empty: 'top',
-      },
+      /** Whether measurements have been performed */
+      _semiStickyMeasured: 'boolean',
+      /** When true, element remains always visible */
       stickyAlways: 'boolean',
+      /** Stick to offsetParent instead of window */
+      stickyParent: 'boolean',
     })
     .methods({
-      /** @return {HTMLElement} */
-      _getSemiStickyElement() { return this; },
       _refreshSemiStickyMetrics() {
-        const semiStickyElement = this._getSemiStickyElement();
-        this._semiStickyHeight = semiStickyElement.offsetHeight;
-        this._semiStickyWidth = semiStickyElement.offsetWidth;
-        // No way to measure offset when stickied ?
-        semiStickyElement.style.position = 'relative';
-        this._semiStickyOffsetY = semiStickyElement.offsetTop;
-        this._semiStickyOffsetX = semiStickyElement.offsetLeft;
-        semiStickyElement.style.position = 'sticky';
+        const styles = window.getComputedStyle(this);
+        this._semiStickyHeight = this.offsetHeight
+          + Number.parseFloat(styles.marginTop) + Number.parseFloat(styles.marginBottom);
+        this._semiStickyOffsetY = Number.parseFloat(styles.marginTop);
+        this._semiStickyMeasured = true;
       },
     })
     .observe({
       _semiStickyStyleStyle: {
-        ...ELEMENT_STYLER_TYPE,
-        get({ _semiStickyTranslateX, _semiStickyTranslateY, _semiStickyDuration, _semiStickyEasing }) {
+        ...ELEMENT_ANIMATION_TYPE,
+        get({
+          _semiStickyMeasured, _semiStickyTranslateY, _semiStickyDuration, _semiStickyEasing,
+        }) {
+          if (!_semiStickyMeasured) return null;
           return {
-            target: this._getSemiStickyElement(),
             styles: {
-              transform: `translateX(${_semiStickyTranslateX}px) translateY(${_semiStickyTranslateY}px)`,
+              transform: `translateY(${_semiStickyTranslateY}px)`,
             },
             timing: {
               duration: _semiStickyDuration,
@@ -56,93 +56,46 @@ export default function SemiStickyMixin(Base) {
       },
     })
     .on({
-      _scrollListenerLastResizeChanged() {
-        if (this._semiStickyAnchor !== 'bottom') return;
-        // Chrome Bug: When window resizes bottom sticky needs to be recomputed
-        // Force style recalculation
-        const semiStickyElement = this._getSemiStickyElement();
-        semiStickyElement.style.setProperty('bottom', 'auto');
-        // eslint-disable-next-line no-unused-expressions
-        semiStickyElement.clientHeight;
-        semiStickyElement.style.removeProperty('bottom');
-        this.propChangedCallback('_scrollListenerPositionY', this._scrollListenerPositionY, this._scrollListenerPositionY);
-      },
       _scrollListenerPositionYChanged(oldValue, newValue) {
         const delta = newValue - oldValue;
-        if (this._semiStickyAnchor === 'top') {
-          this._semiStickyDuration = 0;
-          this._semiStickyTranslateY = (this.stickyAlways || newValue < this._semiStickyOffsetY)
-            ? 0
-            : Math.min(0, Math.max(this._semiStickyTranslateY - delta, -this._semiStickyHeight));
-        } else if (this._semiStickyAnchor === 'bottom') {
-          this._semiStickyDuration = 0;
-          const anchor = this._scrollListenerScrollerClientHeight + newValue;
-          const distanceFromAnchor = this._semiStickyOffsetY - anchor;
-          this._semiStickyTranslateY = this.stickyAlways
-            ? 0
-            : Math.max(0, Math.min(
-              this._semiStickyTranslateY + delta,
-              this._semiStickyHeight + Math.min(0, distanceFromAnchor),
-            ));
+        if (!this._semiStickyMeasured) {
+          this._refreshSemiStickyMetrics();
         }
+        this._semiStickyDuration = 0;
+        // 0 if disabled or if has not scroll passed height
+        // Valid range = -100% < x < 0
+        this._semiStickyTranslateY = (this.stickyAlways || newValue < this._semiStickyOffsetY)
+          ? 0
+          : Math.min(Math.max(-this._semiStickyHeight, this._semiStickyTranslateY - delta), 0);
       },
       _scrollListenerLastIdleChanged() {
         if (this.stickyAlways) return;
         this._refreshSemiStickyMetrics();
-        if (this._semiStickyAnchor === 'top') {
-          const { offsetTop } = this.refs.surface;
-          const offset = this._scrollListenerPositionY - offsetTop;
-          const delta = offset - this._semiStickyTranslateY;
-          const visibility = delta / this._semiStickyHeight;
+        const offsetTop = this.offsetTop;
+        const offset = this._scrollListenerPositionY - offsetTop;
+        const delta = offset - this._semiStickyTranslateY;
+        const visibility = delta / this._semiStickyHeight;
 
-          if (visibility <= 0) return;
-          if (visibility >= 1) return;
-          if (visibility <= 0.5 || offsetTop < this._semiStickyHeight) {
-            // Reveal all
-            this._semiStickyDuration = 250;
-            this._semiStickyEasing = 'ease-in';
-            this._semiStickyTranslateY = 0;
-            // this._semiStickyHeadlineOpacity = 1;
-          } else {
-            this._semiStickyDuration = 200;
-            this._semiStickyEasing = 'ease-out';
-            // Don't hide past origin
-            this._semiStickyTranslateY = Math.max(
-              this._semiStickyOffsetY - this._scrollListenerPositionY,
-              -this._semiStickyHeight,
-            );
-          }
-        } else if (this._semiStickyAnchor === 'bottom') {
-          const max = this._semiStickyHeight;
-          const visibility = (max - this._semiStickyTranslateY) / max;
-          if (visibility <= 0) return;
-          if (visibility >= 1) return;
-          if (visibility >= 0.5) {
-            // Reveal all
-            this._semiStickyDuration = 250;
-            this._semiStickyEasing = 'ease-in';
-            this._semiStickyTranslateY = 0;
-            // this._semiStickyHeadlineOpacity = 1;
-          } else {
-            this._semiStickyDuration = 200;
-            this._semiStickyEasing = 'ease-out';
-            const anchor = this._scrollListenerScrollerClientHeight + this._scrollListenerPositionY;
-            const distanceFromAnchor = this._semiStickyOffsetY - anchor;
-            // Don't hide past origin
-            this._semiStickyTranslateY = this._semiStickyHeight + Math.min(0, distanceFromAnchor);
-          }
+        if (visibility <= 0) return;
+        if (visibility >= 1) return;
+        if (visibility <= 0.5 || offsetTop < this._semiStickyHeight) {
+          // Reveal all
+          this._semiStickyDuration = 250;
+          this._semiStickyEasing = 'ease-in';
+          this._semiStickyTranslateY = 0;
+          // this._semiStickyHeadlineOpacity = 1;
+        } else {
+          this._semiStickyDuration = 200;
+          this._semiStickyEasing = 'ease-out';
+          // Don't hide past origin
+          this._semiStickyTranslateY = Math.max(
+            this._semiStickyOffsetY - this._scrollListenerPositionY,
+            -this._semiStickyHeight,
+          );
         }
       },
       connected() {
-        const semiStickyElement = this._getSemiStickyElement();
-        // Connect scroll when element gets first size
-        const resizeObserver = new ResizeObserver(() => {
-          this.startScrollListener(semiStickyElement.offsetParent ?? window);
-          resizeObserver.disconnect();
-          this._refreshSemiStickyMetrics();
-        });
-        resizeObserver.observe(semiStickyElement);
-        this._refreshSemiStickyMetrics();
+        this.startScrollListener(this.stickyParent ? this.offsetParent : window);
       },
       disconnected() {
         this._scrollListenerClear();

package/mixins/ShapeMaskedMixin.js

@@ -0,0 +1,125 @@
+/**
+ * Provides shape masking utilities and logical shape attributes (shape-top/start/end/bottom).
+ * @param {typeof import('../core/CustomElement.js').default} Base
+ */
+export default function ShapeMaskedMixin(Base) {
+  return Base
+    .observe({
+      /** Show top cut/shape on the element */
+      shapeTop: 'boolean',
+      /** Show bottom cut/shape on the element */
+      shapeBottom: 'boolean',
+      /** Show start-side cut/shape (logical start) */
+      shapeStart: 'boolean',
+      /** Show end-side cut/shape (logical end) */
+      shapeEnd: 'boolean',
+      /** Predefined shape size/style name (none|extra-small|small|medium|large|extra-large|full|inherit) */
+      shapeStyle: 'string',
+    })
+    .css`
+    :host {
+      --mdw-shape__size: 0px;
+      --mdw-shape__ltr: calc(0.5 * var(--mdw-dir, 1) + 0.5); /* 1 if LTR, 0 if RTL */
+      --mdw-shape__rtl: calc(-0.5 * var(--mdw-dir, 1) + 0.5); /* 0 if LTR, 1 if RTL */
+      --mdw-shape__mask: none;
+
+      /** By default, fallback to border-radius */
+      --mdw-shape__rounded: 1;
+      --mdw-shape__inline-start-deg: calc(var(--mdw-dir, 1) * -90deg);
+
+      --mdw-shape__size__top-start-size: var(--mdw-shape__size);
+      --mdw-shape__size__top-end-size: var(--mdw-shape__size);
+      --mdw-shape__size__bottom-start-size: var(--mdw-shape__size);
+      --mdw-shape__size__bottom-end-size: var(--mdw-shape__size);
+      /* (1/2n + 1/2)L + (-1/2n + 1/2)R  */
+      
+      --mdw-shape__size__top-left-size: calc((var(--mdw-shape__ltr) * var(--mdw-shape__size__top-start-size)) + (var(--mdw-shape__rtl) * var(--mdw-shape__size__top-end-size)));
+      --mdw-shape__size__top-right-size: calc((var(--mdw-shape__rtl) * var(--mdw-shape__size__top-start-size)) + (var(--mdw-shape__ltr) * var(--mdw-shape__size__top-end-size)));
+      --mdw-shape__size__bottom-left-size: calc((var(--mdw-shape__ltr) * var(--mdw-shape__size__bottom-start-size)) + (var(--mdw-shape__rtl) * var(--mdw-shape__size__bottom-end-size)));
+      --mdw-shape__size__bottom-right-size: calc((var(--mdw-shape__rtl) * var(--mdw-shape__size__bottom-start-size)) + (var(--mdw-shape__ltr) * var(--mdw-shape__size__bottom-end-size)));
+
+      border-start-start-radius: calc(var(--mdw-shape__rounded) * var(--mdw-shape__size__top-start-size));
+      border-start-end-radius: calc(var(--mdw-shape__rounded) * var(--mdw-shape__size__top-end-size));
+      border-end-start-radius: calc(var(--mdw-shape__rounded) * var(--mdw-shape__size__bottom-start-size));
+      border-end-end-radius: calc(var(--mdw-shape__rounded) * var(--mdw-shape__size__bottom-end-size));
+    }
+
+    :host([shape-style="none"]) {
+      --mdw-shape__size: 0px;
+    }
+    
+    :host([shape-style="extra-small"]) {
+      --mdw-shape__size: var(--mdw-shape__extra-small);
+    }
+    
+    :host([shape-style="small"]) {
+      --mdw-shape__size: var(--mdw-shape__small);
+    }
+    
+    :host([shape-style="medium"]) {
+      --mdw-shape__size: var(--mdw-shape__medium);
+    }
+    
+    :host([shape-style="large"]) {
+      --mdw-shape__size: var(--mdw-shape__large);
+    }
+    
+    :host([shape-style="extra-large"]) {
+      --mdw-shape__size: var(--mdw-shape__extra-large);
+    }
+    
+    :host([shape-style="full"]) {
+      --mdw-shape__size: var(--mdw-shape__full);
+    }
+    
+    :host([shape-style="inherit"]) {
+      --mdw-shape__size: inherit;
+    }
+    
+    :host([shape-top]) {
+      --mdw-shape__size__bottom-start-size: 0px;
+      --mdw-shape__size__bottom-end-size: 0px;
+      --mdw-shape__mask: linear-gradient(transparent 50%, black 50%);
+    }
+    
+    :host([shape-bottom]) {
+      --mdw-shape__size__top-start-size: 0px;
+      --mdw-shape__size__top-end-size: 0px;
+      --mdw-shape__mask: linear-gradient(black 50%, transparent 50%);
+    }
+    
+    :host([shape-start]) {
+      --mdw-shape__size__top-end-size: 0px;
+      --mdw-shape__size__bottom-end-size: 0px;
+      --mdw-shape__mask: linear-gradient(var(--mdw-shape__inline-start-deg), black 50%, transparent 50%);
+    }
+    
+    :host([shape-end]) {
+      --mdw-shape__size__top-start-size: 0px;
+      --mdw-shape__size__bottom-start-size: 0px;
+      --mdw-shape__mask: linear-gradient(var(--mdw-shape__inline-start-deg), transparent 50%, black 50%);
+    }
+
+    @supports(-webkit-mask-box-image: none) {
+      :host {
+        /* Inherit all the way up to :root */
+        --mdw-shape__rounded: inherit;
+      }
+    }
+
+    @supports(-webkit-mask-box-image: none) {
+      :host {
+        -webkit-mask-box-image: var(--mdw-shape__mask-border-source)
+          8 fill /
+          var(--mdw-shape__size)
+          stretch;
+
+        -webkit-mask: var(--mdw-shape__mask);
+
+        transition-duration: 200ms;
+        transition-property: -webkit-mask-box-image-width;
+        will-change: -webkit-mask-box-image;
+      }
+    }
+  `;
+}