@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/components/Table.js

@@ -0,0 +1,151 @@
+import CustomElement from '../core/CustomElement.js';
+
+// https://html.spec.whatwg.org/multipage/tables.html#htmltableelement
+
+/**
+ * @param {Element} parent
+ * @param {string} tagName
+ * @return {Element?}
+ */
+function getByTagName(parent, tagName) {
+  for (const element of parent.children) {
+    if (element.tagName === tagName) {
+      return element;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Element} parent
+ * @param {string} tagName
+ * @param {Element|null} value
+ * @param {string} errorMessage
+ * @return {Element?}
+ */
+function setByTagName(parent, tagName, value, errorMessage) {
+  const current = getByTagName(parent, tagName);
+  if (!value) {
+    current?.remove();
+    return undefined;
+  }
+  if (value === current) return value;
+  if (value instanceof HTMLElement && value.tagName === tagName) {
+    if (current) {
+      current.replaceWith(value);
+    } else {
+      this.prepend(value);
+    }
+    return value;
+  }
+  throw new TypeError(errorMessage);
+}
+
+/**
+ * @param {Element} parent
+ * @param {string} tagName
+ * @return {Element?}
+ */
+function createByTagName(parent, tagName) {
+  let element = this.getByTagName(parent, tagName);
+  if (element) return element;
+  element = document.createElement(tagName);
+  this.prepend(element);
+  return element;
+}
+
+/**
+ * @param {Element} parent
+ * @param {string} tagName
+ * @return {void}
+ */
+function deleteByTagName(parent, tagName) {
+  this.setByTagName(parent, tagName, null);
+}
+
+/**
+ * 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');
+      },
+      set(value) {
+        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-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');
+      },
+      set(value) {
+        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>`
+  .css`
+    :host{
+      display:table;
+    }
+  `
+  .autoRegister('mdw-table');

package/components/TextArea.js

@@ -8,8 +8,11 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
 const DOMString = { nullParser: String, value: '' };
 
 /**
+ * TextArea is a multi-line text input that auto-resizes and integrates with
+ * text-field patterns for labels and validation.
+ * implements {HTMLTextAreaElement}
+ * @see https://m3.material.io/components/text-fields/specs
  * @see https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element
- * -implements {HTMLTextAreaElement}
  */
 export default CustomElement
   .extend()
@@ -19,33 +22,52 @@ export default CustomElement
   .mixin(TextFieldMixin)
   .mixin(ResizeObserverMixin)
   .set({
+    /** Whether the UA supports the `lh` CSS unit for line-height. */
     supportsCSSLineHeightUnit: CSS.supports('height', '1lh'),
+    /** The control type used by the component. */
     type: 'textarea',
+    /** Internal flag used while performing auto-resize logic. */
     _resizing: false,
   })
   .overrides({
+    /** Tag name used for the native control element. */
     controlTagName: 'textarea',
+    /** Textareas are not void elements. */
     controlVoidElement: false,
   })
   .observe({
+    /** When true the textarea is fixed-size and will not auto-resize. */
     fixed: { type: 'boolean' },
+    /** Minimum number of rows to display. Mirrors the `minrows` attribute. */
     minRows: { attr: 'minrows', type: 'integer', nullable: false },
+    /** Maximum number of rows to allow when auto-resizing. */
     maxRows: { attr: 'maxrows', type: 'integer', nullable: false },
+    /** Computed or measured line-height token used for resizing. */
     _lineHeight: 'string',
+    /** Number of columns (characters) for the control (integer). */
     cols: { type: 'integer', empty: 0 },
+    /** The `dirname` attribute value forwarded to the native control. */
     dirName: { attr: 'dirname', ...DOMString },
+    /** Maximum allowed characters for the control. */
     maxLength: { attr: 'maxlength', type: 'integer', empty: 0 },
+    /** Minimum required characters for the control. */
     minLength: { attr: 'minlength', type: 'integer', empty: 0 },
+    /** Placeholder text forwarded to the native control. */
     placeholder: DOMString,
+    /** Number of rows to render; updated when resizing. */
     rows: { type: 'integer', empty: 1 },
+    /** Wrapping behavior token forwarded to the native control. */
     wrap: DOMString,
     // Not in spec, but plays nice with HTML linters
+    /** Forwards a `value` attribute to the internal `defaultValue`. */
     defaultValueAttr: { attr: 'value', ...DOMString },
   })
   .define({
+    /** Return the underlying native `HTMLTextAreaElement` control. */
     _textarea() { return /** @type {HTMLTextAreaElement} */ (this.refs.control); },
   })
   .define({
+    /** The default value (initial value) of the internal textarea. */
     defaultValue: {
       get() { return this._textarea.defaultValue; },
       set(value) {
@@ -58,7 +80,9 @@ export default CustomElement
         this.textContent = this._textarea.defaultValue;
       },
     },
+    /** Number of characters currently in the textarea. */
     textLength() { return this._textarea.textLength; },
+    /** Focus + select helper forwarded to the native control. */
     select() { return this._textarea.select; },
 
     selectionDirection: {
@@ -76,12 +100,18 @@ export default CustomElement
       set(value) { this._textarea.selectionEnd = value; },
     },
 
+    /** Convenience passthrough to `HTMLTextAreaElement.setRangeText`. */
     setRangeText() { return this._textarea.setRangeText; },
 
+    /** Convenience passthrough to `HTMLTextAreaElement.setSelectionRange`. */
     setSelectionRange() { return this._textarea.setSelectionRange; },
 
   })
   .methods({
+    /**
+     * Resize the textarea to fit content up to `maxRows` and not below
+     * `minRows`. This updates the `rows` property and internal layout state.
+     */
     resize() {
       if (this._resizing) return;
       this._resizing = true;
@@ -135,9 +165,8 @@ export default CustomElement
       this._resizing = false;
       // if (this.placeholder) textarea.setAttribute('placeholder', this.placeholder);
     },
-
-    /** @param {ResizeObserverEntry} entry */
-    onResizeObserved(entry) {
+    /** Called by the ResizeObserver mixin; triggers a resize unless active. */
+    onResizeObserved() {
       if (this.matches(':active')) return;
       this.resize();
     },
@@ -167,19 +196,18 @@ export default CustomElement
       },
     },
   })
+  .recompose(({ refs: { control } }) => {
+    // Spec
+    control.removeAttribute('placeholder');
+    control.setAttribute('rows', '{rows}');
+
+    // Custom
+    control.setAttribute('input-prefix', '{inputPrefix}');
+    control.setAttribute('input-suffix', '{inputSuffix}');
+    control.setAttribute('fixed', '{fixed}');
+    control.setAttribute('icon', '{icon}');
+  })
   .on({
-    composed() {
-      const { control } = this.refs;
-      // Spec
-      control.removeAttribute('placeholder');
-      control.setAttribute('rows', '{rows}');
-
-      // Custom
-      control.setAttribute('input-prefix', '{inputPrefix}');
-      control.setAttribute('input-suffix', '{inputSuffix}');
-      control.setAttribute('fixed', '{fixed}');
-      control.setAttribute('icon', '{icon}');
-    },
     defaultValueAttrChanged(oldValue, newValue) {
       this.defaultValue = newValue;
     },
@@ -286,6 +314,10 @@ export default CustomElement
         max-block-size: calc((var(--max-rows) * var(--line-height)));
       }
 
+      #icon {
+        margin-inline-end: 16px;
+      }
+
       #control[icon] {
         padding-inline-start: 0;
       }

package/components/Title.js

@@ -1,14 +1,13 @@
-import Headline from './Headline.js';
+import Display from './Display.js';
 
-export default Headline
+/**
+ * Material Design Type scale: Title.
+ * @see https://m3.material.io/styles/typography/type-scale-tokens
+ */
+export default Display
   .extend()
-  .expressions({
-    computeAriaLevel({ ariaLevel, size }) {
-      if (ariaLevel) return ariaLevel;
-      if (size === 'medium') return '5';
-      if (size === 'small') return '6';
-      return '4';
-    },
+  .set({
+    _baseAriaLevel: 7,
   })
   .css`
     :host {

package/components/Tooltip.js

@@ -1,62 +1,91 @@
+import CustomElement from '../core/CustomElement.js';
 import AriaReflectorMixin from '../mixins/AriaReflectorMixin.js';
+import ShapeMixin from '../mixins/ShapeMixin.js';
+import ThemableMixin from '../mixins/ThemableMixin.js';
 
-import Surface from './Surface.js';
-
-export default Surface
+/**
+ * Tooltip displays brief helper text when hovering or focusing an element.
+ * @see https://m3.material.io/components/tooltips/specs
+ */
+export default CustomElement
   .extend()
+  .mixin(ThemableMixin)
+  .mixin(ShapeMixin)
   .mixin(AriaReflectorMixin)
   .set({
+    /** ARIA role applied by the AriaReflectorMixin (defaults to `tooltip`). */
     _ariaRole: 'tooltip',
   })
   .observe({
+    /**
+     * When true the tooltip is visible/open. This also updates ARIA
+     * `aria-hidden` for accessibility.
+     */
     open: {
       type: 'boolean',
       changedCallback(oldValue, newValue) {
         this.updateAriaProperty('ariaHidden', newValue ? 'true' : 'false');
       },
     },
-    touch: 'boolean',
   })
+  .html`
+    <div id=hover-target></div>
+    <slot id=slot></slot>
+    `
   .css`
-    /* https://m2.material.io/components/tooltips */
-
     :host {
       --mdw-shape__size: var(--mdw-shape__extra-small);
-      --mdw-ink: var(--mdw-color__on-surface-variant);
-      --mdw-shape__bg: rgb(var(--mdw-color__surface-container));
+      --mdw-ink: var(--mdw-color__inverse-on-surface);
+      --mdw-bg: var(--mdw-color__inverse-surface);
       display: block;
-      vertical-align: middle;
 
       box-sizing: border-box;
-      /* stylelint-disable-next-line declaration-property-value-disallowed-list */
-      margin-inline: auto;
-      padding-block: 4px;
+
+      /* Ensure 24px min-height while keeping display:block */
+      padding-block: calc(12px - var(--mdw-typescale__body-small__line-height) / 2);
       padding-inline: 8px;
 
       pointer-events: none;
 
       opacity: 0;
       transform: scale(0);
-      z-index: 24;
+      z-index: 28;
 
-      font: var(--mdw-typescale__label-medium__font);
-      letter-spacing: var(--mdw-typescale__label-medium__letter-spacing);
+      background-color: rgb(var(--mdw-bg));
+      color: rgb(var(--mdw-ink));
 
-      transition: transform 200ms, opacity 200ms;
+      font: var(--mdw-typescale__body-small__font);
+      letter-spacing: var(--mdw-typescale__body-small__letter-spacing);
 
+      transition: transform 200ms, opacity 200ms;
     }
 
-    :host([touch]) {
-      padding-block: 6px;
-      padding-inline: 16px;
-
-      font: var(--mdw-typescale__label-large__font);
-      letter-spacing: var(--mdw-typescale__label-large__letter-spacing);
+    @supports(width: 1lh) {
+      :host {
+        padding-block: calc(12px - 0.5lh);
+      }
     }
 
     :host([open]) {
+      pointer-events: auto;
+
       opacity: 1;
       transform: scale(1);
     }
+
+    #hover-target {
+      position: absolute;
+      inset-block-start: 50%;
+      inset-inline-start: 50%;
+
+      box-sizing: content-box;
+      block-size: 100%;
+      inline-size: 100%;
+      padding: 8px;
+
+      transform: translateX(-50%) translateY(-50%);
+      z-index: -1;
+      
+    }
   `
   .autoRegister('mdw-tooltip');

package/components/TopAppBar.js

@@ -1,36 +1,62 @@
 import CustomElement from '../core/CustomElement.js';
-import { ELEMENT_STYLER_TYPE } from '../core/customTypes.js';
+import { ELEMENT_ANIMATION_TYPE, ELEMENT_STYLE_TYPE } from '../core/customTypes.js';
 import AriaToolbarMixin from '../mixins/AriaToolbarMixin.js';
+import DelegatesFocusMixin from '../mixins/DelegatesFocusMixin.js';
 import SemiStickyMixin from '../mixins/SemiStickyMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
-import SurfaceMixin from '../mixins/SurfaceMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
+/**
+ * Top App Bars should have a background-color that is identical to
+ * `transparent`, though an explicit value allows updating the environment's
+ * to match the app bar (eg: color system bar).
+ *
+ * Top corners are shaped when not scrolling to allow matching with pane, but
+ * removed when raised
+ */
+
+/**
+ * Top app bar provides a consistent place for navigation and actions at the
+ * top of the screen. It supports small, medium, and large variants.
+ * @see https://m3.material.io/components/top-app-bar/specs
+ */
 export default CustomElement
   .extend()
   .mixin(ThemableMixin)
-  .mixin(SurfaceMixin)
   .mixin(ShapeMixin)
   .mixin(AriaToolbarMixin)
   .mixin(SemiStickyMixin)
-  .set({
-    elevated: true,
-  })
+  .mixin(DelegatesFocusMixin)
   .observe({
+    /** Whether the bar is currently raised/elevated (scrolled). */
     _raised: 'boolean',
+    /** Headline opacity used when companion region is visible (0..1). */
     _headlineOpacity: { type: 'float', default: 0 },
+    /** Headline text displayed in the center area. */
     headline: 'string',
+    /** Size variant: 'small' | 'medium' | 'large' or `null` to auto-select. */
     size: { value: /** @type {'small'|'medium'|'large'|null} */ (null) },
-    /** Convert native to observable */
-    ariaLabel: 'string',
-    color: { empty: 'surface' },
-  })
-  .overrides({
-    _getSemiStickyElement() { return this.refs.surface; },
+    /** Color token name used for ink/background. */
+    color: 'string',
+    /** Color token to use when the bar is raised. */
+    raisedColor: 'string',
   })
   .observe({
+    /** Computed style tokens injected for raised-background when `raisedColor` is set. */
+    _styles: {
+      ...ELEMENT_STYLE_TYPE,
+      get({ raisedColor }) {
+        if (raisedColor) {
+          return '#raised-background:where([raised])'
+         + `{background-color:rgb(var(--mdw-color__${raisedColor}))`
+         + '}';
+        }
+        return null;
+      },
+    },
+    /** Animation config for the headline element when companion is visible. */
     _headlineStyle: {
-      ...ELEMENT_STYLER_TYPE,
+      ...ELEMENT_ANIMATION_TYPE,
       get({ size, _headlineOpacity }) {
         if (size !== 'medium' && size !== 'large') return null;
         return {
@@ -45,32 +71,25 @@ export default CustomElement
       },
     },
   })
+  .expressions({
+    /** True when the companion region should be rendered (medium/large). */
+    _companionIf({ size }) {
+      return size === 'medium' || size === 'large';
+    },
+  })
   .html`
+    <div id=raised-background raised={_raised}></div>
     <slot id=leading name=leading on-slotchange={refreshTabIndexes}></slot>
     <div id=headline ink={ink} color={color} type-style={typeStyle} on-slotchange={refreshTabIndexes}>
       {headline}
       <slot id=headline-slot></slot>
     </div>
     <slot id=trailing name=trailing on-slotchange={refreshTabIndexes}></slot>
-    <div mdw-if=${({ size }) => size === 'medium' || size === 'large'} id=companion aria-hidden=true size={size} color={color} raised={_raised}>
+    <div mdw-if={_companionIf} id=companion aria-hidden=true size={size} color={color} raised={_raised}>
       <slot id=companion-slot name=companion size={size}>{headline}</span>
     </div>
   `
   .on({
-    composed({ inline }) {
-      const { surface, shape, leading, headline, trailing } = this.refs;
-      shape.append(leading, headline, trailing);
-      surface.append(shape);
-      surface.setAttribute('size', '{size}');
-      surface.setAttribute('role', 'toolbar');
-      surface.setAttribute('aria-label', '{ariaLabel}');
-      surface.setAttribute(
-        'aria-labelledby',
-        inline(({ ariaLabel }) => (ariaLabel ? null : 'headline')),
-      );
-      surface.setAttribute('raised', '{_raised}');
-      shape.setAttribute('raised', '{_raised}');
-    },
     _scrollListenerPositionYChanged(oldValue, newValue) {
       this._raised = (newValue > this._semiStickyOffsetY);
       if (this.size === 'medium' || this.size === 'large') {
@@ -91,60 +110,20 @@ export default CustomElement
       }
     },
   })
-  .define({
-    ariaActiveDescendantElement: {
-      get() {
-        // @ts-ignore Accessibility Object Model
-        return this.refs.surface.ariaActiveDescendantElement;
-      },
-      set(value) {
-        // @ts-ignore Accessibility Object Model
-        this.refs.surface.ariaActiveDescendantElement = value;
-      },
-    },
-  })
   .css`
     /* https://m3.material.io/components/bottom-app-bar/specs */
-
     :host {
       --mdw-bg: var(--mdw-color__surface);
       --mdw-ink: var(--mdw-color__on-surface);
-      display: contents;
 
-      z-index:2;
-    }
-
-    #surface {
       position: sticky;
-      inset-block-end: auto;
-
-      grid-area: app-bar;
-
-      margin: inherit; /** Pass through */
-
-      padding: inherit; /** Pass through */
-
-      filter: none; /* Never receive shadow */
-
-      transform: translateY(0);
-
-      z-index: 5;
-
-      background-color: rgb(var(--mdw-bg));
-
-      transition: grid-template-columns 100ms, background-color 100ms;
-
-      will-change: transform;
-    }
-
-    #shape{
-      position: initial;
-      inset: initial;
+      inset-block-start: 0;
 
       display: grid;
 
       align-items: center;
       gap: 12px;
+
       grid-auto-flow: row;
       grid-template-rows: minmax(64px,min-content);
       grid-template-columns: minmax(auto,1fr) minmax(0,auto) minmax(auto,1fr);
@@ -152,8 +131,6 @@ export default CustomElement
       overflow-y: visible;
 
       box-sizing: border-box;
-      max-inline-size: calc(var(--mdw-content__max-width, 100%) + (2 * var(--mdw-content__padding, 16px) -  4px));
-      margin-inline: auto;
 
       /* 16px from icon */
       /* inset = (button.width / 2) - (icon.width / 2) */
@@ -161,15 +138,33 @@ export default CustomElement
       /* paddingInlineStart = 16px - ((48px / 2) - (24px / 2)) */
       /* paddingInlineEnd = 16px - ((48px / 2) - (30px / 2)) */
 
-      padding-inline: calc(var(--mdw-content__padding, 16px) - 8px);
+      padding-inline: var(--mdw-pane__padding-inline, 16px);
 
       pointer-events: auto;
 
-      z-index: initial;
+      transform: translateY(0);
+      z-index: 5;
+
+      background-color: rgb(var(--mdw-bg));
+      color: rgb(var(--mdw-ink));
+
+      transition: grid-template-columns 100ms;
+      will-change: transform;
+    }
+
+    #raised-background {
+      position: absolute;
+      inset: 0;
+
+      z-index: -1;
 
       background-color: transparent;
 
-      color: rgb(var(--mdw-ink));
+      transition: background-color 200ms;
+    }
+
+    #raised-background:where([raised]) {
+      background-color: rgb(var(--mdw-color__surface-container));
     }
 
     #leading {
@@ -314,15 +309,13 @@ export default CustomElement
       will-change: opacity;
     }
 
-    #surface:where([color="none"], [color="transparent"]),
+    :host(:where([color="none"], [color="transparent"])),
     #companion:where([color="none"], [color="transparent"]) {
       background-color: transparent;
     }
 
-    #surface[raised]:where([color="surface"],[color="none"],[color="transparent"]),
     #companion[raised]:where([color="surface"],[color="none"],[color="transparent"]) {
       background-color: rgb(var(--mdw-color__surface-container));
     }
-
   `
   .autoRegister('mdw-top-app-bar');