@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/Tab.js

@@ -3,67 +3,102 @@
 import './Icon.js';
 
 import CustomElement from '../core/CustomElement.js';
+import { CHROME_VERSION } from '../core/dom.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
+import HyperlinkMixin from '../mixins/HyperlinkMixin.js';
 import RippleMixin from '../mixins/RippleMixin.js';
 import ScrollListenerMixin from '../mixins/ScrollListenerMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
 
+/**
+ * Tabs organize content into separate views where only one view is visible
+ * at a time; tabs provide navigation between those views.
+ * @see https://m3.material.io/components/tabs/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ShapeMixin)
   .mixin(StateMixin)
   .mixin(RippleMixin)
   .mixin(ScrollListenerMixin)
+  .mixin(HyperlinkMixin)
+  .mixin(DelegatesFocusMixin)
   .define({
     stateTargetElement() { return this.refs.anchor; },
-    /**
-     * Used to compute primary indicator size.
-     * Default to 24.
-     */
-    labelMetrics() {
-      const { slot, icon } = this.refs;
-      const target = slot.clientWidth ? slot : icon;
-      return {
-        width: target.clientWidth,
-        left: target.offsetLeft,
-      };
-    },
   })
   .set({
-    delegatesFocus: true,
+    /** Enable state-layer visual treatment for pressed/hover states. */
     stateLayer: true,
   })
   .observe({
+    /** Whether this tab is currently active/selected. */
     active: 'boolean',
+    /** Named icon to display above the label. */
     icon: 'string',
+    /** Image `src` for the icon when used instead of a named icon. */
     src: 'string',
-    href: 'string',
+    /** Optional aria-label for the tab's anchor element. */
     ariaLabel: 'string',
   })
   .methods({
+    /** Move focus to the tab's anchor. */
     /** @type {HTMLElement['focus']} */
     focus(options) {
       this.refs.anchor.focus(options);
     },
+    /**
+     * Compute the label metrics used for indicator alignment.
+     * Returns an object with `width` and `left` in pixels.
+     */
+    computeLabelMetrics() {
+      const { slot, icon } = this.refs;
+      const target = slot.clientWidth ? slot : icon;
+      return {
+        width: target.clientWidth,
+        left: target.offsetLeft,
+      };
+    },
+  })
+  .expressions({
+    /** Derive the `aria-controls` value from `href` if it references an id. */
+    anchorAriaControls({ href }) {
+      return href?.startsWith('#') ? href.slice(1) : null;
+    },
+    /** Stringified `aria-selected` for the anchor. */
+    anchorAriaSelected({ active }) {
+      return `${active}`;
+    },
+    /** Stringified `aria-disabled` for the anchor. */
+    anchorAriaDisabled({ disabledState }) {
+      return `${disabledState}`;
+    },
+    /** Ensure anchor `href` defaults to `#` when unset. */
+    anchorHref({ href }) {
+      return href ?? '#';
+    },
+    /** True when an icon or src is provided and should render. */
+    iconIf({ icon, src }) {
+      return icon || src;
+    },
+    /** Icon variation to use when active. */
+    iconVariation({ active }) {
+      return active ? 'filled' : null;
+    },
   })
   .html`
-    <a id=anchor role=tab
-      aria-label={ariaLabel}
-      aria-controls=${({ href }) => (href?.startsWith('#') ? href.slice(1) : null)}
-      aria-selected=${({ active }) => (active ? 'true' : 'false')}
-      aria-disabled=${({ disabledState }) => `${disabledState}`}
-      disabled={disabledState}
-      href=${({ href }) => href ?? '#'}>
-      <mdw-icon mdw-if=${(data) => data.icon || data.src} id=icon aria-hidden=true src={src} active={active}>{icon}</mdw-icon>
-      <slot id=slot></slot>
-    </a>
+    <mdw-icon mdw-if={iconIf} id=icon aria-hidden=true src={src} active={active} icon={icon} variation={iconVariation}></mdw-icon>
+    <slot id=slot></slot>
   `
-  .on({
-    composed() {
-      const { shape, rippleContainer, state } = this.refs;
-      shape.append(state, rippleContainer);
-      state.setAttribute('state-disabled', 'focus');
-    },
+  .recompose(({ refs: { anchor, icon, slot, state } }) => {
+    anchor.setAttribute('role', 'tab');
+    anchor.setAttribute('aria-label', '{ariaLabel}');
+    anchor.setAttribute('aria-controls', '{anchorAriaControls}');
+    anchor.setAttribute('aria-selected', '{anchorAriaSelected}');
+    anchor.setAttribute('aria-disabled', '{anchorAriaDisabled}');
+    anchor.setAttribute('disabled', '{disabledState}');
+    anchor.append(icon, slot);
+    state.setAttribute('state-disabled', 'focus');
   })
   .events({
     keydown(event) {
@@ -87,14 +122,24 @@ export default CustomElement
           return;
         }
         if (href.startsWith('#')) {
-          const root = /** @type {HTMLElement} */ this.getRootNode();
+          const root = /** @type {HTMLElement} */ (this.getRootNode());
+          /** @type {HTMLElement} */
           const el = root.querySelector(href);
           if (!el) {
             console.warn('Unknown element', href);
             return;
           }
           event.preventDefault();
-          el.scrollIntoView({ block: 'nearest', inline: 'start' });
+          // Chrome does not support scrolling two elements at the same time
+          // https://bugs.chromium.org/p/chromium/issues/detail?id=1430426
+          const behavior = CHROME_VERSION ? 'instant' : 'smooth';
+
+          el.scrollTo({ top: 0, behavior });
+          el.offsetParent.scrollTo({
+            // Scroll-snap will adjust with subpixel precision
+            left: el.offsetLeft,
+            behavior: 'smooth',
+          });
         }
       },
     },
@@ -106,6 +151,7 @@ export default CustomElement
       display: inline-flex;
 
       min-inline-size: 64px;
+      flex: none;
 
       cursor: pointer;
     }
@@ -136,8 +182,6 @@ export default CustomElement
       padding-block: 4px;
 
       font-size: 24px;
-      font-variation-settings: 'FILL' 0;
-
     }
 
     #shape[disabled],
@@ -152,10 +196,6 @@ export default CustomElement
       color: rgb(var(--mdw-ink));
     }
 
-    #icon[active] {
-      font-variation-settings: 'FILL' 1;
-    }
-
     #slot {
       display: block;
       overflow-x: hidden;

package/components/TabContent.js

@@ -4,25 +4,33 @@ import ResizeObserverMixin from '../mixins/ResizeObserverMixin.js';
 
 import TabPanel from './TabPanel.js';
 
+/**
+ * Tab content hosts tab panels and manages which panel is visible based on
+ * scroll position or selected tab.
+ * @see https://m3.material.io/components/tabs/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ResizeObserverMixin)
   .set({
-    /** @type {InstanceType<TabPanel>[]} */
+    /**
+     * Internal list of `TabPanel` nodes currently assigned to the slot.
+     * @type {InstanceType<TabPanel>[]}
+     */
     _panelNodes: [],
     /**
-     * @type {{
-     *  left:number,
-     *  width:number,
-     *  right:number,
-     *  center: number,
-     *  index: number,
-     * }[]}
+     * Cached metrics for each panel used to determine visibility and
+     * which panel is active based on scroll position. Each entry contains
+     * `{ left, width, right, center, index }` in pixels.
+     * @type {{left:number,width:number,right:number,center:number,index:number}[]|null}
      */
     _panelMetrics: null,
   })
   .observe({
-    /** Internal observed property */
+    /**
+     * Internal index of the currently selected panel. `-1` when none.
+     * This is maintained alongside panel `active` states.
+     */
     _selectedIndex: {
       type: 'integer',
       empty: -1,
@@ -44,7 +52,12 @@ export default CustomElement
     },
   })
   .define({
+    /**
+     * Modifiable index of the currently-selected panel. 0-based index.
+     * Setting this updates panel `active` states accordingly.
+     */
     selectedIndex: {
+
       get() {
         let index = 0;
         for (const panel of this.panels) {
@@ -68,16 +81,18 @@ export default CustomElement
     },
   })
   .define({
-    selectedPanel: {
     /**
-     * @return {InstanceType<TabPanel>}
+     * Modifiable currently selected panel.
+     * Setting this updates panel `active` states accordingly.
      */
+    selectedPanel: {
+      /** @return {InstanceType<TabPanel>|undefined} */
       get() {
         return this.panels.find((panel) => panel.active);
       },
       /**
        * @param {InstanceType<TabPanel>} value
-       * @return {InstanceType<TabPanel>}
+       * @return {InstanceType<TabPanel>|null}
        */
       set(value) {
         const index = this.panels.indexOf(value);
@@ -89,11 +104,16 @@ export default CustomElement
   })
   .html`<slot id=slot></slot>`
   .methods({
+    /** Called when the component observes a resize; clears cached metrics. */
     onResizeObserved() {
       this._panelMetrics = null;
       this.updatePanels();
       // Resize should not change panel visibility (Chrome Bug?)
     },
+    /**
+     * Recompute which panels are visible based on scroll position and
+     * activate the panel whose visible percentage is >= 50%.
+     */
     updatePanels() {
       const start = this.scrollLeft;
       const width = this.clientWidth;
@@ -121,6 +141,7 @@ export default CustomElement
         // @ts-ignore Skip cast
         this._panelNodes = slot.assignedElements()
           .filter((el) => el.tagName === TabPanel.elementName.toUpperCase());
+        this._panelMetrics = null;
         this.updatePanels();
       },
     },

package/components/TabList.js

@@ -4,11 +4,17 @@ import CustomElement from '../core/CustomElement.js';
 import KeyboardNavMixin from '../mixins/KeyboardNavMixin.js';
 import RTLObserverMixin from '../mixins/RTLObserverMixin.js';
 import ResizeObserverMixin from '../mixins/ResizeObserverMixin.js';
+import SemiStickyMixin from '../mixins/SemiStickyMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
 import Tab from './Tab.js';
 
+/**
+ * Tab list is the container for `mdw-tab` elements and renders the active
+ * indicator and keyboard navigation behavior.
+ * @see https://m3.material.io/components/tabs/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -16,9 +22,15 @@ export default CustomElement
   .mixin(ResizeObserverMixin)
   .mixin(RTLObserverMixin)
   .mixin(ShapeMixin)
+  .mixin(SemiStickyMixin)
+  .observe({
+    /** When true the tablist is scrollable (renders differently). */
+    scrollable: 'boolean',
+  })
   .set({
     /** @type {WeakRef<HTMLElement>} */
     _tabContentRef: null,
+    /** Listener function attached to the tab content's `scroll` event. */
     _tabContentScrollListener: null,
     /** @type {HTMLCollectionOf<InstanceType<Tab>>} */
     _tabCollection: null,
@@ -29,6 +41,7 @@ export default CustomElement
      *  right:number,
      *  center: number,
      *  label: {left:number, width:number},
+     *  tab: InstanceType<Tab>,
      *  index: number,
      * }[]}
      */
@@ -48,8 +61,10 @@ export default CustomElement
         }
         if (value) {
           this._tabContentRef = new WeakRef(value);
+          // @ts-expect-error this lacks forward declaration
           this._tabContentScrollListener = this.observeTabContent.bind(this);
           value.addEventListener('scroll', this._tabContentScrollListener);
+          // @ts-expect-error this lacks forward declaration
           this.observeTabContent();
         } else {
           this._tabContentRef = null;
@@ -58,19 +73,15 @@ export default CustomElement
     },
   })
   .observe({
-    tabContentId: {
-      /**
-       * @param {string} oldValue
-       * @param {string} newValue
-       */
-      changedCallback(oldValue, newValue) {
-        // @ts-ignore Skip cast
-        this.tabContent = newValue ? document.getElementById(newValue) : null;
-      },
-    },
+    /** Id of an external `TabContent` element to bind and observe. */
+    tabContentId: 'string',
+    /** Whether the tablist is visually active (has a selected tab). */
     active: 'boolean',
+    /** Render the secondary (label-width) indicator style when true. */
     secondary: 'boolean',
+    /** Inline style used to position and size the indicator. */
     _indicatorStyle: { value: 'opacity: 0' },
+    /** Color token used for the tab ink. */
     color: { empty: 'surface-primary' },
   })
   .define({
@@ -108,15 +119,25 @@ export default CustomElement
     },
     tabMetrics() {
       // eslint-disable-next-line no-return-assign
-      return this._tabMetrics ??= [...this.tabs].map((tab, index) => ({
-        left: tab.offsetLeft,
-        width: tab.offsetWidth,
-        right: tab.offsetLeft + tab.offsetWidth,
-        center: tab.offsetLeft + (tab.offsetWidth / 2),
-        label: tab.labelMetrics,
-        index,
-      }));
+      return this._tabMetrics ??= [...this.tabs].map((tab, index) => {
+        if (!(tab instanceof Tab)) {
+          customElements.upgrade(tab);
+        }
+        return {
+          left: tab.offsetLeft,
+          width: tab.offsetWidth,
+          right: tab.offsetLeft + tab.offsetWidth,
+          center: tab.offsetLeft + (tab.offsetWidth / 2),
+          label: tab.computeLabelMetrics(),
+          tab,
+          index,
+        };
+      });
     },
+    /**
+     * Modifiable index of the currently selected tab. 0-based index.
+     * Setting this updates tab `active` states accordingly.
+     */
     selectedIndex: {
       get() {
         let index = 0;
@@ -141,6 +162,10 @@ export default CustomElement
     },
   })
   .define({
+    /**
+     * Modifiable currently selected tab.
+     * Setting this updates tab `active` states accordingly.
+     */
     selectedItem: {
       /**
        * @return {InstanceType<Tab>}
@@ -169,24 +194,40 @@ export default CustomElement
     },
   })
   .methods({
+    /** Clear cached tab metrics (widths/positions). */
     clearCache() {
       this._tabMetrics = null;
     },
+    /** Find and bind to the external `TabContent` element by id. */
+    searchForTabContent() {
+      const { tabContentId, isConnected } = this;
+      if (!tabContentId) return;
+      if (!isConnected) return;
+      const root = /** @type {ShadowRoot|Document} */ (this.getRootNode());
+      this.tabContent = root.getElementById(tabContentId);
+    },
+    /** Update the indicator position based on a specific `Tab`. */
     /** @param {InstanceType<Tab>} [tab] */
     updateIndicatorByTab(tab) {
       tab ??= this.selectedItem ?? this.tabs.item(0);
-
-      const width = this.secondary ? tab.clientWidth : tab.labelMetrics.width;
-      const position = this.secondary ? tab.offsetLeft : tab.offsetLeft + tab.labelMetrics.left;
+      const metrics = this.tabMetrics.find((m) => m.tab === tab);
+      if (!metrics) return;
+      const width = this.secondary ? metrics.width : metrics.label.width;
+      const position = this.secondary ? metrics.left : metrics.left + metrics.label.left;
       this._indicatorStyle = `--width: ${width}; --offset: ${position}px`;
     },
+    /** Recompute and apply indicator; optionally disable animation when `animate` is false. */
     updateIndicator(animate = false) {
       this.updateIndicatorByTab();
       if (!animate) {
         this.refs.indicator.style.setProperty('--transition-ratio', '0');
       }
     },
-    /** @param {number} percentage */
+    /**
+     * Update the indicator position by a floating `percentage` between 0..1
+     * representing the scroll progress across tab panels.
+     * @param {number} percentage
+     */
     updateIndicatorByPosition(percentage) {
       const metrics = this.tabMetrics;
 
@@ -208,7 +249,7 @@ export default CustomElement
       let center;
       if (leftMetrics === rightMetrics) {
         width = this.secondary ? leftMetrics.width : leftMetrics.label.width;
-        activeTab = this.tabs.item(leftIndex);
+        activeTab = leftMetrics.tab;
         center = leftMetrics.center;
       } else {
         const leftRatio = 1 - (decimalIndex - leftIndex);
@@ -218,7 +259,7 @@ export default CustomElement
         const activeIndex = leftRatio > rightRatio ? leftIndex : rightIndex;
         const distance = rightMetrics.center - leftMetrics.center;
         width = leftWidth + rightWidth;
-        activeTab = this.tabs.item(activeIndex);
+        activeTab = this.tabMetrics[activeIndex].tab;
         center = leftMetrics.center + (distance * rightRatio);
       }
 
@@ -232,10 +273,12 @@ export default CustomElement
       this._indicatorStyle = `--width: ${width}; --offset: ${center - (width / 2)}px`;
       this.refs.indicator.style.setProperty('--transition-ratio', '0');
     },
+    /** Update the indicator using a discrete tab index. */
     /** @param {number} index */
     updateIndicatorByIndex(index) {
       this.updateIndicatorByTab(this.tabs.item(index ?? this._selectedIndex));
     },
+    /** Observe the bound TabContent scroll and update indicator accordingly. */
     observeTabContent() {
       const tabContent = this.tabContent;
       if (!tabContent) return;
@@ -248,6 +291,7 @@ export default CustomElement
       const percentage = max === 0 ? 0 : start / max;
       this.updateIndicatorByPosition(percentage);
     },
+    /** Handler called when the element is resized; refresh cache and indicator. */
     onResizeObserved() {
       this.clearCache();
       this.updateIndicator();
@@ -258,7 +302,7 @@ export default CustomElement
     ariaRole: 'tablist',
   })
   .html`
-    <slot id=slot ink={ink} type-style={typeStyle}></slot>
+    <slot id=slot ink={ink} type-style={typeStyle} scrollable={scrollable}></slot>
     <div id=indicator aria-hidden=true style={_indicatorStyle} active={active} secondary={secondary}>
       <div id=indicator-start class=indicator-piece></div>
       <div id=indicator-center class=indicator-piece></div>
@@ -266,9 +310,11 @@ export default CustomElement
     </div>
   `
   .on({
-    composed() {
-      const { shape, indicator } = this.refs;
-      shape.append(indicator);
+    constructed() {
+      document.addEventListener('DOMContentLoaded', () => this.searchForTabContent(), { once: true });
+    },
+    connected() {
+      this.searchForTabContent();
     },
     pageIsRTLChanged() {
       this.clearCache();
@@ -286,6 +332,9 @@ export default CustomElement
     _selectedIndexChanged(oldValue, newValue) {
       this.updateIndicatorByIndex(newValue);
     },
+    tabContentIdChanged() {
+      this.searchForTabContent();
+    },
   })
   .events({
     '~click'({ target }) {
@@ -301,6 +350,7 @@ export default CustomElement
       slotchange() {
         this.clearCache();
         this.updateIndicator();
+        this.searchForTabContent();
       },
     },
   })
@@ -309,9 +359,8 @@ export default CustomElement
 
     :host {
       --mdw-ink: var(--mdw-color__primary);
-      --mdw-shape__bg: rgb(var(--mdw-color__surface));
+      --mdw-bg: var(--mdw-color__surface);
       position: relative;
-      position: sticky;
       inset-block-start: 0;
       inset-inline: 0;
 
@@ -327,6 +376,8 @@ export default CustomElement
       inline-size: 100%;
       flex:none;
 
+      z-index: 4;
+
       color: inherit;
 
       text-align: center;
@@ -334,6 +385,10 @@ export default CustomElement
       will-change: transform;
     }
 
+    :host(:where([color])) {
+      background-color: rgb(var(--mdw-bg));
+    }
+
     #indicator {
       --corner: 3;
       --width: 24;
@@ -428,11 +483,17 @@ export default CustomElement
     }
 
     :host([scrollable]) {
-      grid-auto-columns: max-content;
-      justify-content: flex-start;
-      overflow-x: auto;
+      display: flex;
+      justify-content: initial;
+    }
+
+    #slot[scrollable] {
+      display: inline-flex;
+
+      inline-size: 0;
+      flex: 1;
 
-      padding-inline: 48px
+      padding-inline: 48px;
     }
   `
   .autoRegister('mdw-tab-list');

package/components/TabPanel.js

@@ -2,19 +2,28 @@ import AriaReflectorMixin from '../mixins/AriaReflectorMixin.js';
 
 import Box from './Box.js';
 
+/**
+ * TabPanel represents the content area for a single tab and updates ARIA
+ * when activated.
+ * @see https://m3.material.io/components/tabs/specs
+ */
 export default Box
   .extend()
   .mixin(AriaReflectorMixin)
   .set({
+    /** ARIA role applied by the AriaReflectorMixin (defaults to `tabpanel`). */
     _ariaRole: 'tabpanel',
   })
   .observe({
+    /** Whether this panel is active/visible; updates ARIA `aria-hidden`. */
     active: {
       type: 'boolean',
+      /** Update `aria-hidden` when `active` changes. */
       changedCallback(oldValue, newValue) {
         this.updateAriaProperty('ariaHidden', newValue ? 'false' : 'true');
       },
     },
+    /** True when the panel is partially visible (peeking). */
     peeking: 'boolean',
   })
   .css`
@@ -34,7 +43,7 @@ export default Box
 
     :host(:is([active],[peeking])) {
       /* Safari bug: Visiblity not changing without !important or layout reflow */
-      visibility: visible !important;
+      visibility: inherit !important;
     }
   `
   .autoRegister('mdw-tab-panel');