@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/Button.js

@@ -1,52 +1,89 @@
 import './Icon.js';
 import CustomElement from '../core/CustomElement.js';
 import DensityMixin from '../mixins/DensityMixin.js';
+import ElevationMixin from '../mixins/ElevationMixin.js';
+import HyperlinkMixin from '../mixins/HyperlinkMixin.js';
 import InputMixin from '../mixins/InputMixin.js';
 import RippleMixin from '../mixins/RippleMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
-import SurfaceMixin from '../mixins/SurfaceMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/* https://m3.material.io/components/buttons/specs */
+
+/**
+ * Buttons prompt most actions in a UI.
+ * @see https://m3.material.io/components/buttons/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(DensityMixin)
-  .mixin(SurfaceMixin)
-  .mixin(ShapeMixin)
   .mixin(StateMixin)
+  .mixin(ElevationMixin)
+  .mixin(ShapeMixin)
   .mixin(RippleMixin)
   .mixin(InputMixin)
+  .mixin(HyperlinkMixin)
   .define({
+    /**
+     * Returns the element used as the state target for visual states
+     * (e.g., pressed/hover). Typically the internal control element.
+     * @return {HTMLElement}
+     */
     stateTargetElement() { return this.refs.control; },
   })
   .set({
     stateLayer: true,
-    delegatesFocus: true,
+    _allowedTypes: ['button', 'submit', 'reset', 'file'],
   })
   .observe({
-    type: { empty: 'button' },
+    /** The underlying control `type` (button, submit, reset, file). */
+    type: {
+      empty: 'button',
+      /**
+       * @param {string} value
+       * @param {*} internalSet
+       */
+      set(value, internalSet) {
+        const enumeratedValue = value?.toLowerCase() ?? 'button';
+        internalSet(
+          this._allowedTypes.includes(enumeratedValue)
+            ? enumeratedValue
+            : 'button',
+        );
+      },
+    },
+    /** Bound to [elevated] specifying whether the element should be elevated. */
     elevated: 'boolean',
+    /** Visual filled variant; may be "tonal" or boolean-filled token. */
     filled: 'string',
-    href: 'string',
+    /** Whether the button should render an outline. */
     outlined: 'boolean',
+    /** Icon name (uses internal `mdw-icon` when set). */
     icon: 'string',
+    /** Ink color override for the icon. */
     iconInk: 'string',
+    // Overrides to string instead of DOMString
+    /** Image source URL for an icon. */
     src: 'string',
+    /** Inline SVG markup to render as icon. */
     svg: 'string',
+    /** SVG `viewBox` attribute for inline SVG icons. */
     viewBox: 'string',
+    /** Path data for an inline SVG icon. */
     svgPath: 'string',
-    _slotInnerText: 'string',
   })
   .expressions({
-    hasIcon({ icon, svg, src, svgPath }) {
+    hasIcon({ icon, svg, src, svgPath } = this) {
       return icon ?? svg ?? src ?? svgPath;
     },
-    computedAriaLabel({ ariaLabel, _slotInnerText }) {
-      return ariaLabel?.trim() || _slotInnerText?.trim() || null;
+    iconVariation({ outlined } = this) {
+      return outlined ? null : 'filled';
     },
   })
   .methods({
+    /** @type {HTMLElement['focus']} */
     focus(...options) {
       if (this.href) {
         this.refs.anchor.focus(...options);
@@ -56,39 +93,19 @@ export default CustomElement
     },
   })
   .html`
-    <mdw-icon mdw-if={hasIcon} id=icon ink={iconInk} disabled={disabledState} outlined={outlined} aria-hidden=true svg={svg} src={src} svg-path={svgPath} view-box={viewBox}>{icon}</mdw-icon>
-    <a mdw-if={href} id=anchor href={href} aria-label="{computedAriaLabel}"></a>
-    <slot id=slot disabled={disabledState} aria-hidden=false></slot>
+    <mdw-icon mdw-if={hasIcon} id=icon ink={iconInk} disabled={disabledState}
+      outlined={outlined} variation={iconVariation} aria-hidden=true svg={svg} src={src}
+      svg-path={svgPath} view-box={viewBox} icon={icon}></mdw-icon>
+    <slot id=slot disabled={disabledState} aria-hidden=true>{_defaultValue}</slot>
   `
-  .childEvents({
-    slot: {
-      slotchange() {
-        // Firefox and Webkit will not apply label from slots.
-        // https://bugs.webkit.org/show_bug.cgi?id=254934
-        // https://bugzilla.mozilla.org/show_bug.cgi?id=1826194
-        if (navigator.userAgent.includes('Firefox')
-        || (navigator.userAgent.includes('Safari') && !navigator.userAgent.includes('Chrom'))) {
-          this._slotInnerText = this.textContent;
-        }
-      },
-    },
-  })
-  .on({
-    composed() {
-      const {
-        shape, state, rippleContainer, surface, control,
-      } = this.refs;
-      surface.append(shape);
-      shape.append(state, rippleContainer);
-      shape.setAttribute('filled', '{filled}');
-      control.setAttribute('aria-label', '{computedAriaLabel}');
-      control.setAttribute('hidden', '{href}');
-      control.setAttribute('role', 'button');
-    },
+  .recompose(({ refs: { anchor, control } }) => {
+    control.setAttribute('mdw-if', '{!href}');
+    control.setAttribute('role', 'button');
+    anchor.setAttribute('mdw-if', '{href}');
+    anchor.setAttribute('aria-label', '{_computedAriaLabel}');
+    anchor.setAttribute('aria-labelledby', '{_computedAriaLabelledby}');
   })
   .css`
-    /* https://m3.material.io/components/buttons/specs */
-
     :host {
       --mdw-shape__size: var(--mdw-shape__full);
       --mdw-ink: var(--mdw-color__primary);
@@ -121,23 +138,39 @@ export default CustomElement
     }
 
     :host(:where([elevated],[filled])) {
-      will-change: filter;
+      transition: box-shadow 200ms;
+      will-change: box-shadow;
     }
 
     /** Elevated Color Defaults */
     :host(:where([elevated])) {
       --mdw-bg: var(--mdw-color__surface-container-low);
       --mdw-ink: var(--mdw-color__primary);
-      --mdw-surface__shadow__resting: var(--mdw-surface__shadow__1);
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__2);
+      box-shadow: var(--mdw-elevation__box-shadow__1);
     }
     /** Filled Color Defaults */
     :host(:where([filled])) {
       --mdw-bg: var(--mdw-color__primary);
       --mdw-ink: var(--mdw-color__on-primary);
-      --mdw-surface__shadow__resting: var(--mdw-surface__shadow__0);
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__1);
+      box-shadow: var(--mdw-elevation__box-shadow__0);
+    }
+
+    :host(:where([elevated]:hover:not(:active))) {
+      box-shadow: var(--mdw-elevation__box-shadow__2);
     }
+
+    :host(:where([filled]:hover:not(:active))) {
+      box-shadow: var(--mdw-elevation__box-shadow__1);
+    }
+
+    :host(:where([elevated]:disabled)) {
+      box-shadow: var(--mdw-elevation__box-shadow__0);
+    }
+
+    :host(:where([filled]:disabled)) {
+      box-shadow: var(--mdw-elevation__box-shadow__0);
+    }
+
     /** Filled Tonal Color Defaults */
     :host(:where([filled="tonal"])) {
       --mdw-bg: var(--mdw-color__secondary-container);
@@ -164,7 +197,7 @@ export default CustomElement
       padding-inline: calc(16px + (var(--mdw-density) * 2px)) calc(24px + (var(--mdw-density) * 2px));
     }
 
-    #shape:where([elevated],[filled],[color]) {
+    :host(:where([elevated],[filled],[color])) {
       background-color: rgb(var(--mdw-bg));
     }
 
@@ -192,7 +225,7 @@ export default CustomElement
       color: rgba(var(--mdw-color__on-surface), 0.38);
     }
 
-    #shape[disabled]:is([elevated], [filled]) {
+    :host([disabled]:is([elevated], [filled])) {
       background-color: rgba(var(--mdw-color__on-surface), 0.12);
       color: rgba(var(--mdw-color__on-surface), 0.38);
     }
@@ -203,11 +236,6 @@ export default CustomElement
 
     #icon {
       font-size: calc(18/14 * 1em);
-      font-variation-settings: 'FILL' 1;
-    }
-
-    #icon[outlined] {
-      font-variation-settings: 'FILL' 0;
     }
 
     #icon[disabled] {
@@ -222,37 +250,8 @@ export default CustomElement
 
     @media (any-pointer: coarse) {
       #touch-target {
-        visibility: visible;
+        visibility: inherit;
       }
     }
   `
-  .childEvents({
-    control: {
-      /**
-       * Duplicates button for form submission
-       * @see https://github.com/WICG/webcomponents/issues/814
-       * @param {{currentTarget:HTMLInputElement}} event
-       * @type {any}
-       */
-      '~click'({ currentTarget }) {
-        if (currentTarget.disabled) return;
-        if (currentTarget.type !== 'submit') return;
-        if (this.disabled) return;
-        const { value } = currentTarget;
-        const form = this.elementInternals?.form;
-        if (!form) return;
-        this.elementInternals.setFormValue(value);
-        if ((currentTarget.type ?? 'submit') !== 'submit') return;
-        const duplicatedButton = /** @type {HTMLInputElement} */ (currentTarget.cloneNode());
-        duplicatedButton.hidden = true;
-        form.append(duplicatedButton);
-        if ('requestSubmit' in form) {
-          form.requestSubmit(duplicatedButton);
-        } else {
-          duplicatedButton.click();
-        }
-        duplicatedButton.remove();
-      },
-    },
-  })
   .autoRegister('mdw-button');

package/components/Card.js

@@ -1,111 +1,124 @@
-import CustomElement from '../core/CustomElement.js';
 import { EVENT_HANDLER_TYPE } from '../core/customTypes.js';
 import AriaReflectorMixin from '../mixins/AriaReflectorMixin.js';
-import FlexableMixin from '../mixins/FlexableMixin.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
+import ElevationMixin from '../mixins/ElevationMixin.js';
 import FormAssociatedMixin from '../mixins/FormAssociatedMixin.js';
+import HyperlinkMixin from '../mixins/HyperlinkMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import StateMixin from '../mixins/StateMixin.js';
-import SurfaceMixin from '../mixins/SurfaceMixin.js';
-import ThemableMixin from '../mixins/ThemableMixin.js';
+
+import Box from './Box.js';
 
 const SUPPORTS_INERT = 'inert' in HTMLElement.prototype;
 
-export default CustomElement
+/**
+ * Cards display content and actions about a single subject.
+ * @see https://m3.material.io/components/cards/specs
+ */
+export default Box
   .extend()
-  .mixin(ThemableMixin)
-  .mixin(FlexableMixin)
-  .mixin(SurfaceMixin)
+  .mixin(StateMixin)
+  .mixin(ElevationMixin)
   .mixin(ShapeMixin)
   .mixin(FormAssociatedMixin) // Tap into FormAssociated for disabledState
-  .mixin(StateMixin)
   .mixin(AriaReflectorMixin)
-  .setStatic({
-    delegatesFocus: true,
-  })
+  .mixin(DelegatesFocusMixin)
+  .mixin(HyperlinkMixin)
   .set({
     _ariaRole: 'figure',
   })
   .observe({
+    /** Whether the card displays an elevated surface. */
+    elevated: 'boolean',
+    /** Whether the card uses a filled surface style. */
     filled: 'boolean',
+    /** When true, card renders an actionable control (clickable). */
     actionable: 'boolean',
+    /** Label for the action control used for accessibility. */
     actionLabel: 'string',
+    /** Event handler called when the card action is triggered. */
     onaction: EVENT_HANDLER_TYPE,
   })
   .define({
+    /**
+     * Element used as the target for state styling (pressed/focus).
+     * Returns the internal action control when actionable, otherwise the host.
+     * @return {HTMLElement}
+     */
     stateTargetElement() { return this.actionable ? this.refs.action : this; },
   })
   .expressions({
-    showBlocker: ({ disabledState }) => !SUPPORTS_INERT && disabledState,
+    showBlocker: ({ disabledState, disabled }) => disabledState && (!disabled || !SUPPORTS_INERT),
+    showButton: ({ actionable, href }) => Boolean(actionable || href),
   })
   .methods({
+    /**
+     * Focuses the internal action control if the card is actionable and not disabled.
+     * @return {void}
+     */
     focus() {
       if (this.disabledState) return;
-      if (this.actionable) this.refs.action.focus();
+      if (!this.actionable) return;
+      this.refs.action.focus();
     },
   })
   .html`
-    <mdw-button mdw-if={actionable} aria-label={actionLabel} id=action disabled={disabledState}></mdw-button>
+    <mdw-button mdw-if={showButton} aria-label={actionLabel} href={href}
+      target={target}
+      download={download}
+      ping={ping}
+      rel={rel}
+      hreflang={hreflang}
+      referrerpolicy={referrerPolicy} id=action disabled={disabledState}></mdw-button>
     <div mdw-if={showBlocker} id=inert-blocker></div>
-    <slot id=slot disabled={disabledState}></slot>
   `
+  .recompose(({ refs: { anchor, inertBlocker, slot } }) => {
+    anchor.remove();
+    slot.setAttribute('disabled', '{disabledState}');
+    inertBlocker.before(slot);
+  })
   .css`
-    /* https://m3.material.io/components/cards/specs */
-
     :host {
-      --mdw-shape__size: 12px;
+      --mdw-shape__size: var(--mdw-shape__medium);
 
-      --mdw-surface__shadow__resting: none;
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__resting);
       /* padding-inline: 12px; */
 
-      --mdw-bg: var(--mdw-color__surface-container);
+      --mdw-bg: var(--mdw-color__surface);
       --mdw-ink: var(--mdw-color__on-surface);
       position: relative;
 
-      display: block;
-
-      color: rgb(var(--mdw-ink));
-
       font: var(--mdw-type__font);
       letter-spacing: var(--mdw-type__letter-spacing);
-    }
 
-    #shape:where([elevated],[filled],[color]) {
-      background-color: rgb(var(--mdw-bg));
+      transition: filter 200ms;
+      will-change: filter;
     }
 
-    :host(:where([filled])) {
-      --mdw-bg: var(--mdw-color__surface-container-highest);
-      --mdw-ink: var(--mdw-color__on-surface-variant);
+    :host(:where([elevated],[filled],[outlined])) {
+      background-color: rgb(var(--mdw-bg));
     }
 
     :host(:where([elevated])) {
       --mdw-bg: var(--mdw-color__surface-container-low);
       --mdw-ink: var(--mdw-color__on-surface);
+      filter: var(--mdw-elevation__drop-shadow__1);
     }
 
-    :host([filled]) {
-      --mdw-surface__shadow__resting: var(--mdw-surface__shadow__0);
-    }
-
-    :host([filled][actionable]) {
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__1);
+    :host(:where([filled])) {
+      --mdw-bg: var(--mdw-color__surface-container-highest);
+      --mdw-ink: var(--mdw-color__on-surface-variant);
     }
 
-    :host([elevated]) {
-      --mdw-surface__shadow__resting: var(--mdw-surface__shadow__1);
+    :host(:where([filled][actionable])) {
+      filter: var(--mdw-elevation__drop-shadow__0);
     }
 
-    :host([elevated][actionable]) {
-      --mdw-surface__shadow__raised: var(--mdw-surface__shadow__2);
+    :host(:where([elevated][actionable]:hover:not(:active))) {
+      filter: var(--mdw-elevation__drop-shadow__2);
     }
 
-    #shape[disabled] {
-
-      /* Works on images */
-      filter: grayscale();
-
-      color: rgb(var(--mdw-color__on-surface));
+    :host(:where([filled][actionable]:hover:not(:active))) {
+      filter: var(--mdw-elevation__drop-shadow__1);
     }
 
     :host([disabled]) {
@@ -113,6 +126,8 @@ export default CustomElement
 
       filter: grayscale();
       opacity: 0.38;
+
+      color: rgb(var(--mdw-color__on-surface));
     }
 
     #slot[disabled] {
@@ -135,10 +150,14 @@ export default CustomElement
       z-index: 99;
     }
 
-    #shape[disabled][elevated] {
+    :host([disabled][elevated]) {
       background-color: rgba(var(--mdw-color__surface-container-highest));
     }
 
+    :host([disabled][filled]) {
+      background-color: rgba(var(--mdw-color__surface));
+    }
+
     #action {
       --mdw-ink: inherit;
       --mdw-shape__size: inherit;
@@ -153,19 +172,12 @@ export default CustomElement
       color: inherit
     }
   `
-  .on({
-    composed() {
-      const { slot, surface, shape, outline } = this.refs;
-      surface.append(shape);
-      outline.removeAttribute('pressed');
-      outline.removeAttribute('focused');
-
-      shape.setAttribute('filled', '{filled}');
-      slot.setAttribute('inert', '{disabledState}');
-      slot.setAttribute('disabled', '{disabledState}');
-      // shape.setAttribute('disabled', '{disabledState}');
-      // shape.setAttribute('filled', '{filled}');
-    },
+  .recompose(({ refs: { slot, outline } }) => {
+    outline.removeAttribute('pressed');
+    outline.removeAttribute('focused');
+
+    slot.setAttribute('inert', '{disabledState}');
+    slot.setAttribute('disabled', '{disabledState}');
   })
   .childEvents({
     action: {

package/components/Checkbox.js

@@ -7,6 +7,10 @@ import StateMixin from '../mixins/StateMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 import TouchTargetMixin from '../mixins/TouchTargetMixin.js';
 
+/**
+ * Checkboxes let users select one or more items from a list, or turn an item on or off.
+ * @see https://m3.material.io/components/checkbox/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
@@ -15,49 +19,35 @@ export default CustomElement
   .mixin(InputMixin)
   .mixin(TouchTargetMixin)
   .set({
+    /** Whether the element renders a state layer for interaction feedback. */
     stateLayer: true,
+    /** The underlying control input `type` value. */
     type: 'checkbox',
   })
   .observe({
+    /** Icon name to show for the checked state. */
     icon: { value: 'check' },
+    /** Icon name to show when the control is indeterminate. */
     indeterminateIcon: { value: 'check_indeterminate_small' },
-    /** Reflected property */
-    indeterminate: 'boolean',
   })
-  .observe({
-    _ariaChecked({ indeterminate, checked }) {
-      return (indeterminate ? 'mixed' : `${!!checked}`);
-    },
+  .expressions({
     _determinateIcon({ indeterminate, indeterminateIcon, icon }) {
       return (indeterminate ? indeterminateIcon : icon);
     },
+    _iconSelectedState({ checked, indeterminate }) {
+      return checked || indeterminate;
+    },
   })
   .html`
     <div id=checkbox errored={erroredState} selected={checked}>
       <mdw-checkbox-icon id=icon errored={erroredState} disabled={disabledState}
-        icon={_determinateIcon} selected={checked}>
+        icon={_determinateIcon} selected={_iconSelectedState}>
       </mdw-checkbox-icon>
     </div>
     <slot id=slot></slot>
   `
-  .rootEvents({
-    click(event) {
-      const { control } = this.refs;
-      if (event.target !== control) {
-        // Label-like click
-        event.stopPropagation();
-        control.click();
-      }
-    },
-  })
-  .on({
-    composed() {
-      const { control, checkbox, state, rippleContainer } = this.refs;
-      checkbox.append(state, rippleContainer);
-
-      // Indeterminate must be manually expressed for ARIA
-      control.setAttribute('aria-checked', '{_ariaChecked}');
-    },
+  .recompose(({ refs: { checkbox, state, rippleContainer } }) => {
+    checkbox.append(state, rippleContainer);
   })
   .css`
     /* https://m3.material.io/components/checkbox/specs */

package/components/CheckboxIcon.js

@@ -3,26 +3,32 @@ import CustomElement from '../core/CustomElement.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * CheckboxIcon is a visual helper for checkboxes, rendering the box and checkmark.
+ * @see https://m3.material.io/components/checkbox/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
   .mixin(ShapeMixin)
   .observe({
+    /** Whether the icon is selected (checked). */
     selected: 'boolean',
+    /** Icon name to render inside the checkbox icon. */
     icon: 'string',
+    /** Whether the associated control is in an error state. */
     errored: 'boolean',
+    /** Whether the associated control is disabled. */
     disabled: 'boolean',
   })
   .define({
-    /** Alias for Selected (QoL) */
+    /** Alias for `selected` (quality-of-life property). */
     checked: {
       get() { return this.selected; },
       set(value) { this.selected = value; },
     },
   })
   .css`
-    /* https://m3.material.io/components/checkbox/specs */
-
     :host {
       --mdw-ink: var(--mdw-color__on-primary);
       --mdw-bg: var(--mdw-color__primary);
@@ -42,16 +48,6 @@ export default CustomElement
       line-height: 18px;
     }
 
-    #shape {
-      --mdw-shape__size: inherit;
-      position: absolute;
-      inset: 0;
-
-      z-index: auto;
-
-      background-color: transparent;
-    }
-
     #icon {
       position: absolute;
       inset: 0;
@@ -59,6 +55,7 @@ export default CustomElement
       opacity: 0;
 
       background-color: rgb(var(--mdw-bg));
+      border-radius: inherit;
       color: rgb(var(--mdw-ink));
 
       transition-duration: 200ms;
@@ -67,11 +64,7 @@ export default CustomElement
     }
 
     #outline {
-      filter:
-        drop-shadow(1px 0px 0px currentColor)
-        drop-shadow(0px 1px 0px currentColor)
-        drop-shadow(-1px 0px 0px currentColor)
-        drop-shadow(0px -1px 0px currentColor);
+      border-width: 2px;
 
       color: rgb(var(--mdw-color__on-surface));
 
@@ -112,18 +105,13 @@ export default CustomElement
       color: rgb(var(--mdw-color__on-surface), var(--disabled-opacity));
     }
   `
-  .on({
-    composed({ html }) {
-      const { outline, shape } = this.refs;
-      outline.removeAttribute('mdw-if');
-      outline.setAttribute('selected', '{selected}');
-      outline.setAttribute('errored', '{errored}');
-      outline.setAttribute('disabled', '{disabled}');
-      // outlineLeft.remove();
-      // outlineRight.remove();
-      shape.append(html`
-        <mdw-icon id=icon selected={selected} errored={errored} disabled={disabled}>{icon}</mdw-icon>
-      `);
-    },
+  .html`
+    <mdw-icon id=icon selected={selected} errored={errored} disabled={disabled} icon={icon}></mdw-icon>
+  `
+  .recompose(({ refs: { outline } }) => {
+    outline.removeAttribute('mdw-if');
+    outline.setAttribute('selected', '{selected}');
+    outline.setAttribute('errored', '{errored}');
+    outline.setAttribute('disabled', '{disabled}');
   })
   .autoRegister('mdw-checkbox-icon');