@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/MenuItem.js

@@ -1,16 +1,27 @@
 // https://www.w3.org/TR/wai-aria-practices/#menu
 
+import { isFocused } from '../core/dom.js';
 import FormAssociatedMixin from '../mixins/FormAssociatedMixin.js';
 
 import './Icon.js';
 import ListOption from './ListOption.js';
 
-export default class MenuItem extends ListOption
+/**
+ * Menu items represent selectable options within a menu. They can trigger
+ * actions, toggle state, or open nested submenus.
+ * @see https://m3.material.io/components/menus/specs
+ */
+export default ListOption
   .extend()
   .mixin(FormAssociatedMixin)
   .set({
+    /** Timeout handle used to schedule submenu cascade. */
     _cascadeTimeout: null,
+
+    /** Milliseconds to delay before opening a cascaded submenu. */
     CASCADE_TIMEOUT: 500,
+
+    /** Internal flag indicating a cascade is in progress. */
     _cascading: false,
   })
   .define({
@@ -21,9 +32,13 @@ export default class MenuItem extends ListOption
     },
   })
   .observe({
-    /** ID of menu to cascade */
+    /** ID of the submenu to open when this item cascades. */
     cascades: 'string',
-    /** Can be null */
+
+    /**
+     * Backing field for the menu item's value attribute. Can be `null` to
+     * indicate no explicit value; reflected to the `value` attribute.
+     */
     _defaultValue: {
       attr: 'value',
       reflect: true,
@@ -32,7 +47,10 @@ export default class MenuItem extends ListOption
     },
   })
   .observe({
-    /** Never returns null */
+    /**
+     * Non-null string representation of the default value used for form
+     * association. Getter never returns null; setter writes to `_defaultValue`.
+     */
     defaultValue: {
       reflect: false,
       get() {
@@ -70,12 +88,7 @@ export default class MenuItem extends ListOption
       const [name, value] = event.detail;
       if (this.name !== name) return;
       if (value === this.value) return;
-      if (this.value === '1') {
-        console.log('unchecking', this.name, this.value);
-        this.selected = false;
-      } else {
-        this.selected = false;
-      }
+      this.selected = false;
     },
   })
   .expressions({
@@ -121,7 +134,7 @@ export default class MenuItem extends ListOption
   .events({
     mouseenter() {
       if (this.disabledState) return;
-      if (document.activeElement !== this) {
+      if (!isFocused(this)) {
         this.focus();
       }
       if (!this.cascades) return;
@@ -157,7 +170,9 @@ export default class MenuItem extends ListOption
           if (!this.cascades) break;
           if (getComputedStyle(this).direction === 'rtl') {
             if (event.key === 'ArrowRight') break;
-          } else if (event.key === 'ArrowLeft') break;
+          } else if (event.key === 'ArrowLeft') {
+            break;
+          }
           event.stopPropagation();
           event.preventDefault();
           this.cascade();
@@ -175,33 +190,32 @@ export default class MenuItem extends ListOption
       this.dispatchEvent(new CustomEvent('mdw-menu-item:cascader-blur', { detail: this.cascades, bubbles: true }));
     },
   })
-  .on({
-    composed({ inline, html }) {
-      const { checkbox: checkboxRef, radio: radioRef, anchor, trailing, trailingIcon } = this.refs;
-      checkboxRef.remove();
-      radioRef.remove();
+  .recompose(({ inline, html, refs: { checkbox: checkboxRef, radio: radioRef, anchor, trailing, trailingIcon } }) => {
+    checkboxRef.remove();
+    radioRef.remove();
 
-      anchor.setAttribute('role', inline(({ checkbox, radio }) => {
-        if (checkbox != null) return 'menuitemcheckbox';
-        if (radio != null) return 'menuitemradio';
-        return 'menuitem';
-      }));
+    anchor.setAttribute('role', inline(({ checkbox, radio }) => {
+      if (checkbox != null) return 'menuitemcheckbox';
+      if (radio != null) return 'menuitemradio';
+      return 'menuitem';
+    }));
 
-      // MenuItems use checked instead of selected as in list items.
-      anchor.setAttribute('ariaChecked', anchor.getAttribute('aria-selected'));
+    // MenuItems use checked instead of selected as in list items.
+    anchor.setAttribute('ariaChecked', anchor.getAttribute('aria-selected'));
 
-      anchor.after(html`
-        <mdw-icon id=selection
-          mdw-if=${({ checkbox, radio }) => checkbox ?? radio ?? false}
-          class=${({ checkbox, radio }) => checkbox || radio || 'leading'}
-          selected={selected}>check</mdw-icon>
-      `);
+    anchor.after(html`
+      <mdw-icon id=selection
+        mdw-if=${({ checkbox, radio }) => checkbox ?? radio ?? false}
+        class=${({ checkbox, radio }) => checkbox || radio || 'leading'}
+        selected={selected} icon=check></mdw-icon>
+    `);
 
-      trailing.setAttribute('type-style', 'label-large');
+    trailing.setAttribute('type-style', 'label-large');
 
-      trailingIcon.setAttribute('mdw-if', '{computeTrailingIcon}');
-      trailingIcon.textContent = '{computeTrailingIcon}';
-    },
+    trailingIcon.setAttribute('mdw-if', '{computeTrailingIcon}');
+    trailingIcon.setAttribute('icon', '{computeTrailingIcon}');
+  })
+  .on({
     _formResetChanged(oldValue, newValue) {
       if (!newValue) return;
       this._selected = this.defaultSelected;
@@ -262,5 +276,4 @@ export default class MenuItem extends ListOption
       color: inherit;
     }
   `
-  .autoRegister('mdw-menu-item')
-  .tsClassFix() {}
+  .autoRegister('mdw-menu-item');

package/components/NavBar.js

@@ -1,29 +1,48 @@
-import SemiStickyMixin from '../mixins/SemiStickyMixin.js';
+import CustomElement from '../core/CustomElement.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
+import ThemableMixin from '../mixins/ThemableMixin.js';
 
-import Nav from './Nav.js';
+import NavItem from './NavItem.js';
 
-export default Nav
+/**
+ * Navigation bars let people switch between UI views on smaller devices
+ * @see https://m3.material.io/components/navigation-bar/specs
+ */
+export default CustomElement
   .extend()
-  .mixin(SemiStickyMixin)
+  .mixin(DelegatesFocusMixin)
+  .mixin(ThemableMixin)
   .observe({
-    _semiStickyAnchor: { empty: 'bottom' },
+    /** When true, the navigation bar is expanded and visible on small viewports. */
+    open: 'boolean',
+
+    /**
+     * Pixel threshold for auto-closing the nav bar based on viewport width.
+     * A value of `-1` disables auto-close. Default: 728.
+     */
+    autoClose: {
+      type: 'float',
+      empty: 728,
+    },
   })
-  .css`
-    /* https://m3.material.io/components/navigation-bar/specs */
+  .set({
+    /** Color token used for the nav surface (defaults to `surface-container`). */
+    color: 'surface-container',
 
+    /** ARIA role applied to the host element (default: 'navigation'). */
+    _ariaRole: 'navigation',
+  })
+  .html`<slot id=slot></slot>`
+  .css`
     :host {
       --mdw-bg: var(--mdw-color__surface-container);
-      
-      position: sticky;
-      inset-block-end: 0;
-      order:1; /* Nav Bars are at top of tab order, but bottom of page */
+      --mdw-ink: var(--mdw-color__on-surface);
+      display: none;
 
-      display: grid;
       align-content: flex-start;
       align-items: flex-start;
       gap: 8px;
 
-      grid-area: nav-bar;
       grid-auto-columns: minmax(48px, 1fr);
       grid-auto-flow: column;
 
@@ -33,20 +52,46 @@ export default Nav
       min-block-size: 80px;
       inline-size: 100%;
 
-      flex-shrink: 0;
+      pointer-events: auto;
 
-      transform: translateY(0);
+      background-color: rgb(var(--mdw-bg));
 
-      box-shadow: none;
+      color: rgb(var(--mdw-ink));
 
-      text-align: center;
+      font: var(--mdw-typescale__label-medium__font);
+      letter-spacing: var(--mdw-typescale__label-medium__letter-spacing);
 
-      will-change: transform;
+      text-align: center;
     }
 
-    #slot {
-      pointer-events: auto;
+    :host(:where([open])) {
+      display: grid;
     }
-
   `
+  .methods({
+    onWindowResize() {
+      const { autoClose } = this;
+      const containerWidth = window.innerWidth;
+      this.open = (autoClose === -1 || containerWidth < autoClose);
+    },
+  })
+  .events({
+    '~click'(event) {
+      // Abort if not child
+      if (event.target === this) return;
+      if (event.target instanceof NavItem === false) return;
+      for (const el of this.querySelectorAll('*')) {
+        if (el instanceof NavItem === false) continue;
+        /** @type {InstanceType<typeof NavItem>} */ (el).active = (el === event.target);
+      }
+    },
+  })
+  .on({
+    constructed() {
+      window.addEventListener('resize', this.onWindowResize.bind(this));
+    },
+    connected() {
+      this.onWindowResize();
+    },
+  })
   .autoRegister('mdw-nav-bar');

package/components/NavBarItem.js

@@ -1,5 +1,10 @@
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation bar item represents a destination within a navigation bar,
+ * providing an icon and optional label to help users move between app sections.
+ * @see https://m3.material.io/components/navigation-bar/specs
+ */
 export default NavItem
   .extend()
   .css`

package/components/NavDrawer.js

@@ -1,18 +1,44 @@
-import NavRail from './NavRail.js';
-
-export default NavRail
+import SideSheet from './SideSheet.js';
+
+/**
+ * Navigation drawers provide access to destinations and app-level navigation
+ * in a side panel. They can be modal, dismissible, or permanent depending on
+ * viewport and application needs.
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
+export default SideSheet
   .extend()
   .observe({
+    /** When true, apply drawer shape at the end edge (RTL-aware). */
     shapeEnd: {
       type: 'boolean',
       empty: true,
     },
+
+    /**
+     * Viewport width in pixels at or above which the drawer auto-opens.
+     * Use `-1` to disable auto-open. Default: 1248.
+     */
+    autoOpen: {
+      type: 'float',
+      empty: 1248,
+    },
+
+    /**
+     * Fixed layout breakpoint in pixels for permanent/dismissible drawer modes.
+     * Default: 1248.
+     */
+    fixedBreakpoint: {
+      type: 'float',
+      empty: 1248,
+    },
   })
   .css`
     /* https://m3.material.io/components/navigation-drawer/specs */
     :host {
       --mdw-shape__size: var(--mdw-shape__large, 16px);
       --mdw-shape__size__top-start-size: 0px;
+      --mdw-shape__size__bottom-start-size: 0px;
 
       --mdw-nav-item__badge__position: static;
       --mdw-nav-item__badge__transform: none;
@@ -21,25 +47,16 @@ export default NavRail
       --mdw-nav-item__label__padding-inline: 52px 0;
       --mdw-nav-item__anchor__display: block;
       --mdw-nav-item__indicator__grid-area: auto;
-      --mdw-bg: var(--mdw-color__surface-container-low);
 
-      display: grid;
-      grid-template-columns: 1fr;
+      display:inline-block;
 
-      min-block-size: 100vh;
-      max-block-size: 100vh;
       inline-size: 360px;
       max-inline-size: calc(100vw - 56px);
-      padding-inline: 0;
-
-      box-shadow: none;
+      padding-inline: 12px;
     }
 
-    #slot {
-      gap: 0;
-
-      inline-size: auto;
-      padding-inline: 12px;
+    ::slotted(mdw-divider) {
+      padding-inline: 16px;
     }
 
   `

package/components/NavDrawerItem.js

@@ -1,5 +1,10 @@
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation drawer item represents a destination inside a navigation drawer,
+ * showing an icon, label, and optional badge to help users navigate app sections.
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
 export default NavItem
   .extend()
   .css`
@@ -47,9 +52,7 @@ export default NavItem
       z-index: 1;
     }
   `
-  .on({
-    composed({ html }) {
-      this.refs.badge.replaceWith(html`<span id="badge-text">{badge}</span>`);
-    },
+  .recompose(({ html, refs: { badge } }) => {
+    badge.replaceWith(html`<span id="badge-text">{badge}</span>`);
   })
   .autoRegister('mdw-nav-drawer-item');

package/components/NavItem.js

@@ -1,63 +1,86 @@
 import './Icon.js';
 import './Ripple.js';
 import './Badge.js';
+import './Shape.js';
 
 import CustomElement from '../core/CustomElement.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
+import HyperlinkMixin from '../mixins/HyperlinkMixin.js';
 import RippleMixin from '../mixins/RippleMixin.js';
-import ShapeMixin from '../mixins/ShapeMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
 /** @typedef {'charset'|'coords'|'name'|'shape'} DeprecatedHTMLAnchorElementProperties */
 
-export default class NavItem extends CustomElement
+/**
+ * A navigation item represents a single destination used by navigation bars,
+ * navigation drawers, and navigation rails. It provides an icon, optional
+ * label, and optional badge to help users move between app sections.
+ * @see https://m3.material.io/components/navigation-bar/specs
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
+export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(StateMixin)
   .mixin(RippleMixin)
-  .mixin(ShapeMixin)
+  .mixin(HyperlinkMixin)
+  .mixin(DelegatesFocusMixin)
   .set({
-    delegatesFocus: true,
     stateLayer: true,
   })
   .observe({
+    /** Whether the label slot is visible. When true the label is shown. */
     showLabel: 'string',
+    /** Whether the item is active/selected; affects styling and aria-current. */
     active: 'boolean',
+    /** Name of the icon to display (e.g. 'home'); ignored when `src` is provided. */
     icon: 'string',
+    /** URL of an icon image; takes precedence over `icon` when present. */
     src: 'string',
-    href: 'string',
+    /** Badge content to display on the item (e.g. notification count). */
     badge: 'string',
+    /** Accessible label for the anchor; when present it is used instead of the slot text. */
     ariaLabel: 'string', // watch attribute and emit callback
   })
   .methods({
+    /** Focus the internal anchor element. */
     /** @type {HTMLElement['focus']} */
     focus(...args) {
       this.refs.anchor.focus(...args);
     },
   })
+  .expressions({
+    _anchorAriaCurrent({ active }) {
+      return active ? 'page' : null;
+    },
+    _anchorAriaLabelledby({ ariaLabel }) {
+      return ariaLabel ? null : 'slot';
+    },
+    _anchorHref({ href }) { return href ?? '#'; },
+    iconVariation({ active }) {
+      return active ? 'filled' : null;
+    },
+  })
   .html`
-    <mdw-icon id=icon aria-hidden=true src={src} active={active}>{icon}</mdw-icon>
-    <a id=anchor
-      aria-current=${({ active }) => (active ? 'page' : null)}
-      aria-describedby=badge
-      aria-label={ariaLabel}
-      aria-labelledby=${({ ariaLabel }) => (ariaLabel ? null : 'slot')}
-      href=${({ href }) => href ?? '#'}>
-    </a>
+    <mdw-icon id=icon aria-hidden=true src={src} active={active} icon={icon} variation={iconVariation}></mdw-icon>
     <slot id=slot active={active} show-label={showLabel} aria-hidden=true></slot>
     <mdw-badge part=badge id=badge badge={badge} show-label={showLabel} aria-hidden=true>{badge}</mdw-badge>
   `
-  .on({
-    composed({ html }) {
-      const { shape, state, rippleContainer } = this.refs;
-      shape.append(html`
+  .recompose(({ html, refs: { anchor, state, rippleContainer } }) => {
+    anchor.setAttribute('aria-current', '{_anchorAriaCurrent}');
+    anchor.setAttribute('aria-describedby', 'badge');
+    anchor.setAttribute('aria-label', '{ariaLabel}');
+    anchor.setAttribute('aria-labelledby', '{_anchorAriaLabelledby}');
+    anchor.setAttribute('href', '{_anchorHref}');
+    anchor.before(html`
+      <mdw-shape id=shape active={active} shape-style=full>
         <mdw-ripple id=ripple ripple-origin=center keep-alive hold-ripple ripple-state=${({ active }) => ((active) ? null : 'complete')}></mdw-ripple>
         ${state}
         ${rippleContainer}
-      `);
-      shape.setAttribute('active', '{active}');
-      shape.removeAttribute('color');
-    },
+      </mdw-shape>
+    `);
   })
   .css`
     /* https://m3.material.io/components/navigation-bar/specs */
@@ -86,7 +109,7 @@ export default class NavItem extends CustomElement
       padding-inline: 0;
 
       cursor: pointer;
-      /* stylelint-disable-next-line plugin/no-unsupported-browser-features */
+
       user-select: none;
 
       font: var(--mdw-typescale__label-large__font);
@@ -149,6 +172,8 @@ export default class NavItem extends CustomElement
       /* stylelint-disable-next-line liberty/use-logical-spec */
       left: 50%;
 
+      overflow: hidden;
+
       block-size: 100%;
       inline-size: 100%;
       max-inline-size: 56px;
@@ -157,7 +182,6 @@ export default class NavItem extends CustomElement
       grid-row: 1 / 1;
 
       transform: translateX(-50%) translateY(-50%) translateY(var(--mdw-nav-item__offset-y));
-      z-index: 0;
 
       background-color: transparent;
 
@@ -177,7 +201,6 @@ export default class NavItem extends CustomElement
       color: rgb(var(--mdw-color__on-surface-variant));
 
       font-size: 24px;
-      font-variation-settings: 'FILL' 0;
 
       transition: transform 200ms;
       will-change: transform;
@@ -235,8 +258,6 @@ export default class NavItem extends CustomElement
 
     #icon[active] {
       color: rgb(var(--mdw-ink));
-
-      font-variation-settings: 'FILL' 1;
     }
 
     #slot[active] {
@@ -259,15 +280,21 @@ export default class NavItem extends CustomElement
       },
       keydown({ key, repeat }) {
         if (key !== ' ') return true;
-        if (!repeat) this.click();
+        if (!repeat) {
+          this.click();
+        }
         return false;
       },
     },
   })
-  .autoRegister('mdw-nav-item')
-  .tsClassFix() {
-  addRipple(...args) {
-    if (!this.active) return null;
-    return super.addRipple(...args);
-  }
-}
+  .extend((Base) => class NavItem extends Base {
+    /**
+     * Add a ripple effect only when the item is active.
+     * @type {InstanceType<ReturnType<RippleMixin>>['addRipple']}
+     */
+    addRipple(...args) {
+      if (!this.active) return null;
+      return super.addRipple(...args);
+    }
+  })
+  .autoRegister('mdw-nav-item');

package/components/NavRail.js

@@ -1,39 +1,52 @@
-import Nav from './Nav.js';
+import SideSheet from './SideSheet.js';
 
-export default Nav
+/**
+ * Navigation rails provide access to app destinations and destinations-level
+ * navigation in a vertical rail, suited for larger screens and desktop layouts.
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
+export default SideSheet
   .extend()
   .observe({
+    /** Horizontal alignment for rail content: 'start', 'center', or 'end'. */
     align: { value: /** @type {'start'|'center'|'end'} */ (null) },
-  })
-  .on({
-    composed({ html }) {
-      const { slot } = this.refs;
-      slot.before(html`<slot id=start name=start></slot>`);
-      slot.setAttribute('align', '{align}');
+    /** Viewport width (pixels) threshold at or above which the rail will auto-open. */
+    autoOpen: {
+      type: 'float',
+      empty: 728,
+    },
+    /** Viewport width (pixels) threshold at or below which the rail will auto-close. */
+    autoClose: {
+      type: 'float',
+      empty: 1248,
+    },
+    /** Viewport width (pixels) at which the rail becomes fixed (non-collapsible). */
+    fixedBreakpoint: {
+      type: 'float',
+      empty: 728,
     },
   })
+  .recompose(({ html, refs: { slot } }) => {
+    slot.before(html`<slot id=start name=start></slot>`);
+    slot.setAttribute('align', '{align}');
+  })
   .css`
     /* https://m3.material.io/components/navigation-rail/specs */
 
     :host{
-      position: relative;
-      
-      inset-block-start: 0;
-      inset-inline-start: 0;
       align-self: flex-start;
 
-      display: grid;
+      display: inline-grid;
       align-content: flex-start;
       flex-direction: column;
       gap:0;
-      grid-template-rows: auto minmax(0,1fr);
+      grid-template-rows: auto minmax(auto,1fr);
       grid-template-columns: 100%;
       justify-items: stretch;
+      overscroll-behavior: none;
+      overscroll-behavior: contain;
 
-      min-block-size: 100vh;
-      max-block-size: 100vh;
-      min-inline-size: 80px;
-      max-inline-size: 80px;
+      min-block-size: 0;
 
       text-align: center;
     }
@@ -43,6 +56,7 @@ export default Nav
       align-items: center;
       flex-direction: column;
       gap: 12px;
+      justify-content: center;
     }
 
     #slot {
@@ -52,8 +66,6 @@ export default Nav
       align-items: stretch;
       flex-direction: column;
       gap: 12px;
-      overflow-x: clip;
-      overflow-y: auto;
 
       box-sizing: border-box;
       max-block-size: 100%;
@@ -68,6 +80,5 @@ export default Nav
     #slot[align="end"] {
       align-self: flex-end;
     }
-
   `
   .autoRegister('mdw-nav-rail');

package/components/NavRailItem.js

@@ -2,6 +2,11 @@
 
 import NavItem from './NavItem.js';
 
+/**
+ * A navigation rail item represents a destination within a navigation rail,
+ * showing an icon and optional label for vertical navigation on larger screens.
+ * @see https://m3.material.io/components/navigation-rail/specs
+ */
 export default NavItem
   .extend()
   .css`
@@ -9,11 +14,14 @@ export default NavItem
       grid-auto-flow: row;
       grid-auto-rows: minmax(20px, auto);
       grid-template-rows: [icon] minmax(32px, 1fr);
-      grid-template-columns: [icon] minmax(56px, 1fr);
+      grid-template-columns: [icon] minmax(72px, 1fr);
 
       min-block-size: 56px;
       flex: none;
-      padding-inline: 12px;
+      padding-inline: 4px;
+
+      font: var(--mdw-typescale__label-medium__font);
+      letter-spacing: var(--mdw-typescale__label-medium__letter-spacing);
     }
 
     #slot {