@shortfuse/materialdesignweb 0.9.0 → 0.9.2

package/components/Snackbar.js

@@ -11,6 +11,10 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
 import './Button.js';
 import './IconButton.js';
 
+/**
+ * Snackbars provide brief messages about app processes and optional actions.
+ * @see https://m3.material.io/components/snackbar/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -23,17 +27,32 @@ export default CustomElement
     elevated: true,
   })
   .observe({
+    /** Whether the snackbar is visible. */
     open: 'boolean',
+    /** When true the snackbar does not auto-dismiss. */
     persistent: 'boolean',
+    /** Optional action label to display as a button. */
     action: 'string',
+    /** Ink token used for the action button (defaults to inverse-primary). */
     actionInk: { empty: 'inverse-primary' },
+    /** Typographic style used for the action (e.g. 'label-large'). */
     actionTypeStyle: { empty: 'label-large' },
+    /** Render a close icon button when true. */
     closeButton: 'boolean',
+    /** Icon name used for the close button. */
     closeIcon: { empty: 'close' },
+    /** Ink token used for the close icon. */
     closeInk: { empty: 'inherit' },
+    /** Event handler invoked when the action is triggered. */
     onaction: EVENT_HANDLER_TYPE,
+    /** Event handler invoked when the snackbar toggles open/closed. */
+    ontoggle: EVENT_HANDLER_TYPE,
   })
   .methods({
+    /**
+     * Close the snackbar. Dispatches a cancelable `close` event; if not
+     * prevented the snackbar will hide and await the closing transition.
+     */
     async close() {
       if (!this.dispatchEvent(new Event('close', { cancelable: true }))) return;
       if (!this.open) return;
@@ -43,10 +62,14 @@ export default CustomElement
         this.addEventListener('transitionend', resolve, { once: true });
       });
     },
+    /** Show the snackbar (set `open` true). */
     show() {
       this.open = true;
     },
-    /** @param {string} text */
+    /**
+     * Update the snackbar text content.
+     * @param {string} text
+     */
     update(text) {
       this.textContent = text;
     },
@@ -54,7 +77,7 @@ export default CustomElement
   .html`
     <div id=content><slot id=slot></div>
     <mdw-button mdw-if={action} id=action class=button ink={actionInk} type-style={actionTypeStyle}>{action}</mdw-button>
-    <mdw-icon-button mdw-if={closeButton} id=close class=button icon={closeIcon} ink={closeInk}>Close</mdw-button>
+    <mdw-icon-button mdw-if={closeButton} id=close class=button icon={closeIcon} ink={closeInk}>Close</mdw-icon-button>
   `
   .childEvents({
     action: {
@@ -69,9 +92,12 @@ export default CustomElement
       },
     },
   })
+  .on({
+    openChanged() {
+      this.dispatchEvent(new Event('toggle'));
+    },
+  })
   .css`
-    /* https://m3.material.io/components/snackbar/specs */
-
     :host {
       --mdw-shape__size: var(--mdw-shape__small);
       --mdw-bg: var(--mdw-color__inverse-surface);

package/components/SnackbarContainer.js

@@ -1,6 +1,11 @@
 import CustomElement from '../core/CustomElement.js';
 import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 
+/**
+ * Snackbar container positions snackbars within the app window and manages
+ * layout and pointer-events for stacked snackbars.
+ * @see https://m3.material.io/components/snackbar/specs
+ */
 export default CustomElement
   .extend()
   .mixin(DelegatesFocusMixin)
@@ -38,5 +43,9 @@ export default CustomElement
       }
     }
 
+    #slot {
+      pointer-events: auto;
+    }
+
   `
   .autoRegister('mdw-snackbar-container');

package/components/Surface.js

@@ -4,6 +4,11 @@ import FlexableMixin from '../mixins/FlexableMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Surface represents a themed elevated surface used to display content with
+ * elevation, shape, and color tokens applied.
+ * @see https://m3.material.io/styles/elevation/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)

package/components/Switch.js

@@ -5,6 +5,10 @@ import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 import TouchTargetMixin from '../mixins/TouchTargetMixin.js';
 
+/**
+ * Switch is a binary control that toggles between on and off states.
+ * @see https://m3.material.io/components/switch/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -13,15 +17,23 @@ export default CustomElement
   .mixin(TouchTargetMixin)
   // Switches have their own pressed animation (No ripple)
   .set({
+    /** The control `type` used for the underlying input element (always 'checkbox'). */
     type: 'checkbox',
+    /** Enables the state-layer visual treatment for pressed/hover states. */
     stateLayer: true,
   })
   .observe({
+    /** The icon name to show inside the thumb when provided. */
     icon: 'string',
+    /** The icon name to show when the switch is selected/on. */
     selectedIcon: 'string',
+    /** The icon name to show when the switch is unselected/off. */
     unselectedIcon: 'string',
+    /** The image `src` to show inside the thumb when provided. */
     src: 'string',
+    /** The image `src` to show when the switch is selected/on. */
     selectedSrc: 'string',
+    /** The image `src` to show when the switch is unselected/off. */
     unselectedSrc: 'string',
   })
   .html`
@@ -44,6 +56,8 @@ export default CustomElement
   })
   .methods({
     /**
+     * Handle pointer/touch input on the native control to compute dragging
+     * position and update the thumb drag state.
      * @param {(MouseEvent|TouchEvent) & {currentTarget:HTMLInputElement}} event
      * @return {void}
      */
@@ -97,12 +111,14 @@ export default CustomElement
 
       // this._isHoveringThumb = true;
 
-      let currentValue = this.refs.switch.dragValue;
+      const switchIcon = /** @type {InstanceType<import('./SwitchIcon.js').default>} */ (this.refs.switch);
+
+      let currentValue = switchIcon.dragValue;
       if (currentValue == null) {
         currentValue = this.checked ? 1 : 0;
       }
       const pixels = offsetX - (clientWidth / 2);
-      const currentPixels = this.refs.switch.clientWidth - (this.refs.switch.clientHeight);
+      const currentPixels = switchIcon.clientWidth - (switchIcon.clientHeight);
       // console.log(pixels, currentPixels, currentPixels * currentValue, pixels / currentPixels);
       const newRatio = pixels / currentPixels;
       const newValue = Math.max(Math.min(currentValue + newRatio, 1), 0);

package/components/SwitchIcon.js

@@ -7,42 +7,63 @@ import { loadGlobalStyles } from '../services/rtl.js';
 
 loadGlobalStyles();
 
+/**
+ * Visual helper that renders the switch thumb and related visual states.
+ * @see https://m3.material.io/components/switch/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(ShapeMixin)
   .observe({
+    /** Whether the switch is selected/on. */
     selected: 'boolean',
+    /** Named icon to render inside the thumb. */
     icon: 'string',
+    /** Whether the control is visually in an errored state. */
     errored: 'boolean',
+    /** Whether the control is disabled. */
     disabled: 'boolean',
+    /** Icon name to show when selected/on. */
     selectedIcon: 'string',
+    /** Icon name to show when unselected/off. */
     unselectedIcon: 'string',
+    /** Image `src` to render inside the thumb. */
     src: 'string',
+    /** Image `src` to render when selected/on. */
     selectedSrc: 'string',
+    /** Image `src` to render when unselected/off. */
     unselectedSrc: 'string',
+    /** Hover state for the thumb. */
     hovered: 'boolean',
+    /** Pressed state for the thumb. */
     pressed: 'boolean',
+    /** Focused state for the thumb. */
     focused: 'boolean',
+    /** Temporary drag position value (0..1) while the thumb is being dragged. */
     dragValue: 'float',
+    /** Color token to use for the thumb (defaults to primary). */
     color: { empty: 'primary' },
   })
   .observe({
-    /** Alias for Selected (QoL) */
+    /** Alias for `selected` to match common control naming. */
     checked: {
       type: 'boolean',
       get({ selected }) { return selected; },
       /** @param {boolean} value */
       set(value) { this.selected = value; },
     },
+    /** Whether the thumb is in an active interactive state (not disabled). */
     _active({ disabled, pressed, focused, hovered }) {
       return !disabled && (pressed || focused || hovered);
     },
   })
   .observe({
+    /** Thumb fill token (e.g. "primary-container") when active. */
     _thumbColor({ color, _active }) {
       return _active ? `${color}-container` : '';
     },
+    /** Ink token used for icons inside the thumb based on state. */
     _iconInk({ disabled, selected, color }) {
       if (!selected) return 'surface-container-highest';
       if (disabled) return 'on-surface';

package/components/Tab.js

@@ -11,6 +11,11 @@ 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)
@@ -23,19 +28,29 @@ export default CustomElement
     stateTargetElement() { return this.refs.anchor; },
   })
   .set({
+    /** 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',
+    /** 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;
@@ -46,21 +61,27 @@ export default CustomElement
     },
   })
   .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;
     },

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;

package/components/TabList.js

@@ -10,6 +10,11 @@ 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)
@@ -19,11 +24,13 @@ export default CustomElement
   .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,
@@ -54,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;
@@ -64,10 +73,15 @@ export default CustomElement
     },
   })
   .observe({
+    /** 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({
@@ -120,6 +134,10 @@ export default CustomElement
         };
       });
     },
+    /**
+     * Modifiable index of the currently selected tab. 0-based index.
+     * Setting this updates tab `active` states accordingly.
+     */
     selectedIndex: {
       get() {
         let index = 0;
@@ -144,6 +162,10 @@ export default CustomElement
     },
   })
   .define({
+    /**
+     * Modifiable currently selected tab.
+     * Setting this updates tab `active` states accordingly.
+     */
     selectedItem: {
       /**
        * @return {InstanceType<Tab>}
@@ -172,15 +194,19 @@ 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;
-      this.tabContent = this.getRootNode().getElementById(tabContentId);
+      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);
@@ -190,13 +216,18 @@ export default CustomElement
       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;
 
@@ -242,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;
@@ -258,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();
@@ -327,7 +361,6 @@ export default CustomElement
       --mdw-ink: var(--mdw-color__primary);
       --mdw-bg: var(--mdw-color__surface);
       position: relative;
-      position: sticky;
       inset-block-start: 0;
       inset-inline: 0;
 

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`

package/components/Table.js

@@ -63,10 +63,21 @@ function deleteByTagName(parent, tagName) {
   this.setByTagName(parent, tagName, null);
 }
 
-/** -implements {HTMLTableElement} */
-CustomElement
+/**
+ * Table provides an HTML-like table API using mdw elements for rows and sections.
+ * Implements the {@link https://html.spec.whatwg.org/multipage/tables.html#htmltableelement | HTMLTableElement} API
+ * using `mdw-` prefixed sections and rows.
+ *
+ * Legacy. Modern UI does not use tables and no longer part of Material Design Web.
+ * Tables are generally not responsive and do not adapt well to different screen sizes.
+ */
+export default CustomElement
   .extend()
   .define({
+    /**
+     * The table caption element (`mdw-caption`) or `null` when not present.
+     * Mirrors `HTMLTableElement.caption` semantics.
+     */
     caption: {
       get() {
         return getByTagName(this, 'mdw-caption');
@@ -75,14 +86,21 @@ CustomElement
         return setByTagName(this, 'mdw-caption', value, "Failed to set the 'caption' property on 'MDWTableElement': Failed to convert value to 'MDWCaptionElement'.");
       },
     },
+    /**
+     * The table header section (`mdw-thead`) element or `null` when not present.
+     * Mirrors `HTMLTableElement.tHead` semantics.
+     */
     tHead: {
       get() {
-        return getByTagName(this, 'mdw-thread');
+        return getByTagName(this, 'mdw-thead');
       },
       set(value) {
         return setByTagName(this, 'mdw-thead', value, "Failed to set the 'tHead' property on 'MDWTableElement': Failed to convert value to 'MDWTHeadElement'.");
       },
     },
+    /**
+     * The table footer section (`mdw-tfoot`) element or `null` when not present.
+     */
     tFoot: {
       get() {
         return getByTagName(this, 'mdw-tfoot');
@@ -91,20 +109,37 @@ CustomElement
         return setByTagName(this, 'mdw-tfoot', value, "Failed to set the 'tFoot' property on 'MDWTableElement': Failed to convert value to 'MDWTFootElement'.");
       },
     },
+    /**
+     * Live `HTMLCollection` of `mdw-tbody` elements contained by the table.
+     * Mirrors `HTMLTableElement.tBodies`.
+     * @return {HTMLCollectionOf<Element>}
+     */
     tBodies() {
       return this.getElementsByTagName('mdw-tbody');
     },
+    /**
+     * Live `HTMLCollection` of row elements (`mdw-tr`) in the table.
+     * Mirrors `HTMLTableElement.rows`.
+     * @return {HTMLCollectionOf<Element>}
+     */
     rows() {
       return this.getElementsByTagName('mdw-tr');
     },
   })
   .methods({
+    /** Create and return a `mdw-caption` element, appending when necessary. */
     createCaption() { return createByTagName(this, 'mdw-caption'); },
+    /** Remove the table's caption element when present. */
     deleteCaption() { return deleteByTagName(this, 'mdw-caption'); },
+    /** Create and return a `mdw-thead` element for the table. */
     createTHead() { return createByTagName(this, 'mdw-thead'); },
+    /** Remove the table's `mdw-thead` element when present. */
     deleteTHead() { return deleteByTagName(this, 'mdw-thead'); },
+    /** Create and return a `mdw-tfoot` element for the table. */
     createTFoot() { return createByTagName(this, 'mdw-tfoot'); },
+    /** Remove the table's `mdw-tfoot` element when present. */
     deleteTFoot() { return deleteByTagName(this, 'mdw-tfoot'); },
+    /** Insert and return a new `mdw-tbody` element before the tFoot (if any). */
     createTBody() { return this.insertBefore(this.tFoot, document.createElement('mdw-tbody')); },
   })
   .html`<slot id=slot></slot>`