@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/Scrim.js

@@ -0,0 +1,95 @@
+import CustomElement from '../core/CustomElement.js';
+
+/**
+ * A scrim can bring focus to specific elements by increasing the visual contrast of a large layered surface.
+ * Use the scrim beneath elements like modals and expanded navigation menus.
+ * @see https://m3.material.io/styles/elevation/applying-elevation
+ */
+export default CustomElement
+  .extend()
+  .observe({
+    /** When true the scrim is hidden and will be removed after its fade-out animation. */
+    hidden: 'boolean',
+  })
+  .html`<div id=scroll-blocker></div>`
+  .css`
+    :host {
+      position: fixed;
+      inset: 0;
+
+      display: block;
+      overflow: overlay;
+
+      overscroll-behavior: none;
+      overscroll-behavior: contain;
+      scrollbar-color: transparent transparent;
+      scrollbar-width: none;
+
+      cursor: pointer;
+
+      outline: none; /* Older Chromium Builds */
+      
+      -webkit-tap-highlight-color: transparent;
+
+      opacity: 0;
+
+      z-index: 23;
+
+      background-color: rgb(var(--mdw-color__scrim));
+      
+      animation: fade-in 200ms forwards ease-out;
+      will-change: opacity;
+    }
+
+    :host::-webkit-scrollbar {
+      display: none;
+    }
+
+    :host([hidden]) {
+      animation-name: fade-out;
+      animation-timing-function: ease-in;
+    }
+
+    :host([invisible]) {
+      background: transparent;
+    }
+
+    #scroll-blocker {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-start: 0;
+
+      display: block;
+
+      block-size: 200%;
+      inline-size: 200%;
+    }
+
+    @keyframes fade-in {
+      from {
+        opacity: 0;
+      }
+
+      to {
+        opacity: 0.38;
+      }
+    }
+
+    @keyframes fade-out {
+      from {
+        opacity: 0.38;
+      }
+
+      to {
+        opacity: 0;
+      }
+    }
+  `
+  .events({
+    animationend() {
+      if (this.hidden) {
+        this.remove();
+      }
+    },
+  })
+  .autoRegister('mdw-scrim');

package/components/Search.js

@@ -1,6 +1,10 @@
 import TopAppBar from './TopAppBar.js';
 
-/* @implements {HTMLSelectElement} */
+/**
+ * Search provides an app bar integrated search field for querying content.
+ * implements {HTMLSelectElement}
+ * @see https://m3.material.io/components/search/overview
+ */
 export default TopAppBar
   .extend()
   .undefine('headline')
@@ -8,18 +12,27 @@ export default TopAppBar
   .undefine('size')
   .undefine('_headlineStyle')
   .observe({
+    /** Placeholder text shown in the search input. */
     placeholder: { type: 'string', empty: 'Search' },
+    /** Visual color token to apply to the search surface. */
     color: { empty: 'surface-container-high' },
+    /** Shape style token to apply (e.g. 'full', 'none'). */
     shapeStyle: { empty: 'full' },
+    /** Enable keyboard navigation mode for search results when true. */
     kbdNav: { empty: 'false' },
   })
   .define({
-    /** @return {HTMLInputElement} */
-    input() { return this.refs.input; },
+    /** Returns the current text value of the internal input. */
+    input() {
+      return /** @type {HTMLInputElement} */ (this.refs.input).value;
+    },
+    /** The `value` accessor proxies the internal input's value. */
     value: {
-      get() { return this.refs.input.value; },
+      get() {
+        return /** @type {HTMLInputElement} */ (this.refs.input).value;
+      },
       set(value) {
-        this.refs.input.value = value;
+        /** @type {HTMLInputElement} */ (this.refs.input).value = value;
       },
     },
   })
@@ -29,28 +42,25 @@ export default TopAppBar
   .css`
     :host {
       --mdw-bg: var(--mdw-color__surface-container-high);
-      padding-block: 16px;
-    }
-
-    #surface {
-      background-color: transparent;
-    }
-
-    #leading:not([slotted]),
-    #trailing:not([slotted]) {
-      display: none;
-    }
+      --mdw-shape__size: var(--mdw-shape__full);
+      inset-block-start: 8px;
 
-    #shape {
       display: flex;
       align-items: center;
       gap: 16px;
 
+      margin-block: 16px;
+
       padding-inline: 16px;
 
       background-color: rgb(var(--mdw-bg));
     }
 
+    #leading:not([slotted]),
+    #trailing:not([slotted]) {
+      display: none;
+    }
+
     #input {
       --mdw-state__hovered-opacity: 0;
       flex: 1;
@@ -73,13 +83,8 @@ export default TopAppBar
       },
     },
   })
-  .on({
-    composed() {
-      const { companion, headline, input, surface } = this.refs;
-      companion.remove();
-      headline.replaceWith(input);
-      surface.removeAttribute('aria-labelledby');
-    },
+  .recompose(({ refs: { companion, headline, input } }) => {
+    companion.remove();
+    headline.replaceWith(input);
   })
-
   .autoRegister('mdw-search');

package/components/SegmentedButton.js

@@ -2,52 +2,54 @@ import './Icon.js';
 
 import Button from './Button.js';
 
+/**
+ * Segmented buttons group individual related actions or options where
+ * multiple choices are presented inline; each segment acts like a toggle
+ * or option within a set.
+ * @see https://m3.material.io/components/segmented-buttons/specs
+ */
 export default Button
   .extend()
   .observe({
+    /** Interaction model for the segment: 'radio' (single select) or 'checkbox' (multi-select). */
     type: { empty: 'radio' },
+    /** When true this segment is rendered as an inner segment inside a segmented group. */
     innerSegmentedButton: 'boolean',
   })
   .set({
+    /** Render the button with an outline style. */
+    outlined: true,
+    /** Allow the control to receive focus even when disabled. */
     focusableOnDisabled: true,
   })
-  .on({
-    composed({ html, inline }) {
-      const { shape, icon, outline, control, slot, state } = this.refs;
-
-      slot.before(html`
-        <div id=icons>
-          ${icon}
-          <mdw-icon selected={checked} id=check-icon aria-hidden=true>check</mdw-icon>
-        </div>
-      `);
-      shape.setAttribute('selected', '{checked}');
-
-      icon.removeAttribute('mdw-if');
-      icon.setAttribute('has-icon', '{hasIcon}');
-      icon.setAttribute('selected', '{checked}');
-      outline.setAttribute('inner-segmented-button', '{innerSegmentedButton}');
-      outline.setAttribute('shape-start', '{shapeStart}');
-      outline.setAttribute('shape-end', '{shapeEnd}');
-      control.setAttribute('role', 'option');
-      control.setAttribute('aria-checked', inline(
-        ({ type, checked }) => (type === 'checkbox' ? `${(!!checked)}` : null),
-      ));
-      control.setAttribute('aria-selected', inline(
-        ({ type, checked }) => (type === 'checkbox' ? null : `${!!checked}`),
-      ));
-
-      state.setAttribute('state-disabled', 'focus');
-    },
-    constructed() {
-      this.outlined = true;
-    },
+  .recompose(({ html, inline, refs: { icon, outline, control, slot, state } }) => {
+    slot.before(html`
+      <div id=icons>
+        ${icon}
+        <mdw-icon selected={checked} id=check-icon aria-hidden=true icon=check variation=filled></mdw-icon>
+      </div>
+    `);
+
+    icon.removeAttribute('mdw-if');
+    icon.setAttribute('has-icon', '{hasIcon}');
+    icon.setAttribute('selected', '{checked}');
+    outline.setAttribute('selected', '{checked}');
+    outline.setAttribute('inner-segmented-button', '{innerSegmentedButton}');
+    outline.setAttribute('shape-start', '{shapeStart}');
+    outline.setAttribute('shape-end', '{shapeEnd}');
+    control.setAttribute('role', 'option');
+    control.setAttribute('aria-checked', inline(
+      ({ type, checked }) => (type === 'checkbox' ? `${(!!checked)}` : null),
+    ));
+    control.setAttribute('aria-selected', inline(
+      ({ type, checked }) => (type === 'checkbox' ? null : `${!!checked}`),
+    ));
+
+    state.setAttribute('state-disabled', 'focus');
   })
   .css`
-    /* https://m3.material.io/components/segmented-buttons/specs */
-
     :host {
-      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size: 0;
       --mdw-ink: var(--mdw-color__on-surface);
       gap: 8px;
 
@@ -58,19 +60,29 @@ export default Button
       color: rgb(var(--mdw-ink));
     }
 
-    :host([inner-segmented-button]) {
-      --mdw-shape__size: 0px;
+    :host(:first-of-type) {
+      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size__top-end-size: 0px;
+      --mdw-shape__size__bottom-end-size: 0px;
+    }
+
+    :host(:last-of-type) {
+      --mdw-shape__size: var(--mdw-shape__full);
+      --mdw-shape__size__top-start-size: 0px;
+      --mdw-shape__size__bottom-start-size: 0px;
     }
 
     #outline {
       inset-inline-end: -1px;
+
+      z-index: -1;
     }
 
-    #outline[shape-end] {
+    :host(:last-of-type) #outline {
       inset-inline-end: 0;
     }
 
-    #shape[selected] {
+    #outline[selected] {
       background-color: rgb(var(--mdw-bg));
     }
 
@@ -107,12 +119,13 @@ export default Button
 
       overflow: visible;
 
+      block-size: 100%;
+
       margin: 0;
 
       opacity: 0;
 
       font-size: 18px;
-      font-variation-settings: 'FILL' 1;
     }
 
     #check-icon[selected] {
@@ -125,7 +138,7 @@ export default Button
       color: rgba(var(--mdw-color__on-surface), 0.38);
     }
 
-    #shape[disabled][selected] {
+    #outline[disabled][selected] {
       background-color: rgba(var(--mdw-color__on-surface), 0.12);
     }
   `

package/components/SegmentedButtonGroup.js

@@ -1,4 +1,3 @@
-import AriaReflectorMixin from '../mixins/AriaReflectorMixin.js';
 import KeyboardNav from '../mixins/KeyboardNavMixin.js';
 
 import Box from './Box.js';
@@ -6,10 +5,14 @@ import SegmentedButton from './SegmentedButton.js';
 
 /** @typedef {'compact'} DeprecatedHTMLMenuElementProperties */
 
+/**
+ * A segmented button group arranges multiple `mdw-segmented-button` items
+ * so they behave as a related set of choices or toggles.
+ * @see https://m3.material.io/components/segmented-buttons/specs
+ */
 export default Box
   .extend()
   .mixin(KeyboardNav)
-  .mixin(AriaReflectorMixin)
   .define({
     kbdNavQuery() {
       return SegmentedButton.elementName;
@@ -20,15 +23,7 @@ export default Box
   })
   .childEvents({
     slot: {
-      slotchange() {
-        this.refreshTabIndexes();
-        const list = /** @type {NodeListOf<InstanceType<SegmentedButton>>} */ (this.kbdNavChildren);
-        for (const [index, child] of list.entries()) {
-          child.shapeStart = index === 0;
-          child.innerSegmentedButton = index > 0 && index < list.length - 1;
-          child.shapeEnd = index === list.length - 1;
-        }
-      },
+      slotchange: 'refreshTabIndexes',
     },
   })
   .css`
@@ -39,8 +34,15 @@ export default Box
       --mdw-ink: var(--mdw-color__on-secondary-container);
 
       display: inline-flex;
+      align-items: stretch;
+      flex-direction: row;
+      justify-content: initial;
       overflow-x: auto;
       overflow-y: hidden;
+
+      box-sizing: border-box;
+      min-inline-size: 100%;
+      flex: none;
     }
 
     :host([color]) {
@@ -49,6 +51,7 @@ export default Box
 
     #slot {
       display: grid;
+      grid-auto-columns: 1fr;
       grid-auto-flow: column;
 
       flex: none;
@@ -57,7 +60,7 @@ export default Box
   `
   .on({
     constructed() {
-      this.setAttribute('aria-orientation', 'horizontal');
+      this.updateAriaProperty('ariaOrientation', 'horizontal');
     },
   })
   .autoRegister('mdw-segmented-button-group');

package/components/Select.js

@@ -4,7 +4,11 @@ import StateMixin from '../mixins/StateMixin.js';
 import TextFieldMixin from '../mixins/TextFieldMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
-/* @implements {HTMLSelectElement} */
+/**
+ * Select provides a control for choosing an option from a list of options.
+ * implements {HTMLSelectElement}
+ * @see https://m3.material.io/components/text-fields/overview
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -12,6 +16,7 @@ export default CustomElement
   .mixin(ControlMixin)
   .mixin(TextFieldMixin)
   .observe({
+    /** Name of the trailing icon to render (defaults to the dropdown arrow). */
     trailingIcon: { empty: 'arrow_drop_down' },
   })
   .overrides({
@@ -20,11 +25,13 @@ export default CustomElement
     type: 'select-one',
   })
   .define({
+    /** Return the internal native <select> element used as the control. */
     _select() {
       return /** @type {HTMLSelectElement} */ (this.refs.control);
     },
-    /** Readonly values */
+    /** Readonly: whether the underlying control allows multiple selection. */
     multiple: { value: false },
+    /** Readonly: the rendered size of the native select control. */
     size: { value: 1 },
   })
   .html`<slot id=slot></slot>`
@@ -41,17 +48,19 @@ export default CustomElement
       },
     },
   })
+  .recompose(({ template, refs: { slot, prefix, suffix, control } }) => {
+    control.setAttribute('icon', '{icon}');
+    template.append(slot);
+    prefix.remove();
+    suffix.remove();
+  })
   .on({
-    composed({ template }) {
-      const { slot, prefix, suffix, control } = this.refs;
-      control.setAttribute('icon', '{icon}');
-      template.append(slot);
-      prefix.remove();
-      suffix.remove();
-    },
+    /** When the form resets, restore the select value from any option[selected]. */
     _formResetChanged(oldValue, newValue) {
       if (!newValue) return;
-      this._select.value = this.querySelector('option[selected]')?.value ?? '';
+      /** @type {HTMLSelectElement} */
+      const selectedOption = this.querySelector('option[selected]');
+      this._select.value = selectedOption?.value ?? '';
     },
   })
   .css`

package/components/Shape.js

@@ -1,68 +1,12 @@
-import ShapeMixin from '../mixins/ShapeMixin.js';
-
-import Box from './Box.js';
-
-export default Box
+import CustomElement from '../core/CustomElement.js';
+import ShapeMaskedMixin from '../mixins/ShapeMaskedMixin.js';
+
+/**
+ * Shape applies shape tokens (corner radius) to elements and surfaces.
+ * @see https://m3.material.io/styles/shape/overview-principles
+ */
+export default CustomElement
   .extend()
-  .mixin(ShapeMixin)
-  .on({
-    composed() {
-      const { shape, outline } = this.refs;
-      shape.before(outline);
-      shape.remove();
-    },
-  })
-  .css`
-    :host {
-      position: relative;
-
-      overflow: hidden;
-
-      z-index: auto;
-
-      background-color: var(--mdw-shape__bg, transparent);
-
-      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));
-
-      transition-delay: 1ms;
-      transition-duration: 200ms;
-      transition-property: background-color, color;
-      will-change: background-color, color;
-
-    }
-
-    :host([color]) {
-      background-color: rgb(var(--mdw-bg));
-    }
-
-    :host(:where([ink],[color])) {
-      color: rgb(var(--mdw-ink));
-    }
-
-    :host([outlined]) {
-      background-color: transparent;
-    }
-
-    :host(:is([color="none"], [color="transparent"])) {
-      background-color: transparent;
-    }
-
-    @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, 200ms, 200ms;
-        transition-property: background-color, color, -webkit-mask-box-image-width;
-        will-change: background-color, color, -webkit-mask-box-image;
-      }
-    }
-  `
+  .mixin(ShapeMaskedMixin)
+  .html`<slot id=slot></slot>`
   .autoRegister('mdw-shape');