@shortfuse/materialdesignweb 0.9.0 → 0.9.2

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,6 +165,7 @@ export default CustomElement
       this._resizing = false;
       // if (this.placeholder) textarea.setAttribute('placeholder', this.placeholder);
     },
+    /** Called by the ResizeObserver mixin; triggers a resize unless active. */
     onResizeObserved() {
       if (this.matches(':active')) return;
       this.resize();

package/components/Title.js

@@ -1,5 +1,9 @@
 import Display from './Display.js';
 
+/**
+ * Material Design Type scale: Title.
+ * @see https://m3.material.io/styles/typography/type-scale-tokens
+ */
 export default Display
   .extend()
   .set({

package/components/Tooltip.js

@@ -3,17 +3,24 @@ import AriaReflectorMixin from '../mixins/AriaReflectorMixin.js';
 import ShapeMixin from '../mixins/ShapeMixin.js';
 import ThemableMixin from '../mixins/ThemableMixin.js';
 
-/* https://m3.material.io/components/tooltips/specs */
-
+/**
+ * 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) {

package/components/TopAppBar.js

@@ -15,6 +15,11 @@ import ThemableMixin from '../mixins/ThemableMixin.js';
  * 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)
@@ -23,14 +28,21 @@ export default CustomElement
   .mixin(SemiStickyMixin)
   .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) },
+    /** 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 }) {
@@ -39,8 +51,10 @@ export default CustomElement
          + `{background-color:rgb(var(--mdw-color__${raisedColor}))`
          + '}';
         }
+        return null;
       },
     },
+    /** Animation config for the headline element when companion is visible. */
     _headlineStyle: {
       ...ELEMENT_ANIMATION_TYPE,
       get({ size, _headlineOpacity }) {
@@ -58,6 +72,7 @@ export default CustomElement
     },
   })
   .expressions({
+    /** True when the companion region should be rendered (medium/large). */
     _companionIf({ size }) {
       return size === 'medium' || size === 'large';
     },

package/core/Composition.js

@@ -30,6 +30,15 @@ import { generateUID } from './uid.js';
  * @prop {any} [injections]
  */
 
+/**
+ * @template T
+ * @typedef {{
+ *  target: Element|DocumentFragment,
+ *  byProp: (prop: keyof T & string, value:any, data?:Partial<T>) => void,
+ *  state: InitializationState,
+ * } &  ((changes:Partial<T>, data:T) => void)} RenderDraw
+ */
+
 /** @typedef {HTMLElementEventMap & { input: InputEvent; } } HTMLElementEventMapFixed */
 
 /**
@@ -74,7 +83,7 @@ import { generateUID } from './uid.js';
  * @typedef {(
  *   HTMLElementEventMapFixed
  *   & {[P in keyof HTMLElementCancellableEventMap as `~${P}`]: HTMLElementCancellableEventMap[P]}
- *   & Record<string, Event|CustomEvent>
+ *   & Record<string, Event|CustomEvent<any>>
  * )} CompositionEventMap
  */
 
@@ -83,7 +92,7 @@ import { generateUID } from './uid.js';
  * @template {keyof CompositionEventMap} [K = keyof CompositionEventMap]
  * @typedef {{
  * type?: K
- * tag?: string,
+ * tag?: string|symbol,
  * capture?: boolean;
  * once?: boolean;
  * passive?: boolean;
@@ -132,6 +141,8 @@ import { generateUID } from './uid.js';
  *  @prop {number}  cacheIndex
  *  @prop {number}  searchIndex
  *  @prop {string | Function | string[]}  query
+ *  @prop {boolean} [negate]
+ *  @prop {boolean} [doubleNegate]
  *  @prop {Function}  [expression]
  *  @prop {string}  prop
  *  @prop {string[]}  deepProp
@@ -150,6 +161,7 @@ import { generateUID } from './uid.js';
  * @prop {string} [attrName]
  * @prop {any} [defaultValue]
  * @prop {RenderGraphSearch} search
+ * @prop {InterpolateOptions['injections']} [injections]
  */
 
 /**
@@ -158,8 +170,7 @@ import { generateUID } from './uid.js';
  */
 function writeDOMAttribute({ nodes }, value) {
   const { nodeIndex, attrName } = this;
-  /** @type {Element} */
-  const element = nodes[nodeIndex];
+  const element = /** @type {Element} */ (nodes[nodeIndex]);
   switch (value) {
     case undefined:
     case null:
@@ -215,7 +226,7 @@ function writeDynamicNode({ nodeStates, comments, nodes }, value) {
     // eslint-disable-next-line no-bitwise
     nodeStates[nodeIndex] &= ~0b0010;
   } else {
-    node.data = value;
+    /** @type {Text} */ (node).data = value;
   }
 
   // Updated, now set hidden state
@@ -361,7 +372,7 @@ function searchWithDeepProp(state, changes, data) {
 /**
  * @typedef InterpolateOptions
  * @prop {Record<string,any>} [defaults] Default values to use for interpolation
- * @prop {{iterable:string} & Record<string,any>} [injections] Context-specific injected properties. (Experimental)
+ * @prop {{iterable:string} & Record<string,any> & {index:number}} [injections] Context-specific injected properties. (Experimental)
  */
 
 /**
@@ -373,7 +384,7 @@ function searchWithDeepProp(state, changes, data) {
  * @prop {Comment[]} comments
  * @prop {Uint8Array} nodeStates
  * @prop {Uint8Array} searchStates
- * @prop {Element[]} refs
+ * @prop {HTMLElement[]} refs
  * @prop {number} lastChildNodeIndex
  * @prop {RenderOptions<?>} options
  */
@@ -518,7 +529,7 @@ export default class Composition {
    * Only store metadata, not actual data. Currently only needs length.
    * TBD if more is needed later
    * Referenced by property key (string)
-   * @type {CompositionAdapter}
+   * @type {CompositionAdapter<T>}
    */
   adapter;
 
@@ -661,10 +672,9 @@ export default class Composition {
    * @param {Partial<T>} changes what specifically
    * @param {T} [data]
    * @param {RenderOptions<T>} [options]
-   * @return {Function & {target:Element}} anchor
+   * @return {RenderDraw<T>} anchor
    */
   render(changes, data, options = {}) {
-    // console.log('render', changes, options);
     if (!this.interpolated) {
       this.interpolate({
         defaults: data ?? changes,
@@ -703,20 +713,20 @@ export default class Composition {
         console.warn('found empty tag??');
         refs.push(null);
         nodes.push(null);
-        textNode = instanceFragment.firstChild;
+        textNode = /** @type {Text} */ (instanceFragment.firstChild);
       } else {
         const element = instanceFragment.getElementById(tag);
         refs.push(element);
         nodes.push(element);
         this.#bindCompositionEventListeners(tag, element, options.context);
         if (!textNodes.length) continue;
-        textNode = element.firstChild;
+        textNode = /** @type {Text} */ (element.firstChild);
       }
 
       let currentIndex = 0;
       for (const index of textNodes) {
         while (index !== currentIndex) {
-          textNode = textNode.nextSibling;
+          textNode = /** @type {Text} */ (textNode.nextSibling);
           currentIndex++;
         }
         nodes.push(textNode);
@@ -734,6 +744,7 @@ export default class Composition {
      * @param {T} data
      */
     const draw = (changes, data) => {
+      if (!changes) return;
       let ranSearch = false;
       for (const prop of this.props) {
         if (!this.actionsByPropsUsed?.has(prop)) continue;
@@ -801,12 +812,14 @@ export default class Composition {
         searchStates[search.searchIndex] = 0b0011;
       }
 
+      /** @type {Partial<T>} */
       let changes;
       const actions = this.actionsByPropsUsed.get(prop);
       for (const action of actions) {
         if (action.search.query === prop) {
           action.invocation(initState, value);
         } else {
+          // @ts-expect-error Skip cast
           changes ??= { [prop]: value };
           data ??= changes;
           ranSearch = true;
@@ -1150,11 +1163,22 @@ export default class Composition {
         defaultValue,
         search,
       };
-      text.data = typeof defaultValue === 'string' ? defaultValue : '';
+      switch (typeof defaultValue) {
+        case 'string':
+          text.data = defaultValue;
+          break;
+        case 'number':
+          // Manually coerce to string (0 will be empty otherwise)
+          text.data = `${defaultValue}`;
+          break;
+        default:
+          text.data = '';
+          break;
+      }
     } else if (subnode) {
       action = {
         nodeIndex: this._interpolationState.nodeIndex,
-        attrName: subnode,
+        attrName: /** @type {string} */ (subnode),
         defaultValue,
         invocation: writeDOMAttribute,
         search,
@@ -1255,6 +1279,7 @@ export default class Composition {
     const newComposition = new Composition();
     newComposition.template.append(element);
     // Move uninterpolated element to new composition template.
+    /** @type {InterpolateOptions['injections']} */
     const injections = {
       ...options.injections,
       [valueName]: null,
@@ -1266,6 +1291,9 @@ export default class Composition {
     const search = {
       cacheIndex: this._interpolationState.cacheIndex++,
       searchIndex: this._interpolationState.searchIndex++,
+      query: null,
+      prop: null,
+      deepProp: null,
       propsUsed,
       deepPropsUsed: [[iterableName]],
       defaultValue: {},
@@ -1416,6 +1444,7 @@ export default class Composition {
             this.#interpolateIterable(element, options);
             continue;
           } else {
+            // @ts-expect-error Bad typings
             const idAttr = element.attributes.id;
             if (idAttr) {
               this.#interpolateNode(idAttr, element, options);
@@ -1432,7 +1461,7 @@ export default class Composition {
           element = node.parentElement;
           if (this.#interpolateNode(/** @type {Text} */ (node), element, options)) {
             const nextNode = treeWalker.nextNode();
-            node.remove();
+            /** @type {Text} */ (node).remove();
             node = nextNode;
             continue;
           }

package/core/CompositionAdapter.js

@@ -1,9 +1,22 @@
 import { createEmptyComment } from './optimizations.js';
 
 /**
+ * @template T
+ * @typedef {import('./Composition.js').default<T>} Composition
+ */
+
+/**
+ * @template T
+ * @typedef {import('./Composition.js').RenderOptions<T>} RenderOptions
+ */
+
+/**
+ * @template T
  * @typedef {Object} DomAdapterCreateOptions
  * @prop {Comment} anchorNode
  * @prop {(...args:any[]) => HTMLElement} [create]
+ * @prop {Composition<T>} composition
+ * @prop {RenderOptions<T>} renderOptions
  */
 
 /**
@@ -16,8 +29,9 @@ import { createEmptyComment } from './optimizations.js';
  * @prop {Comment} [comment]
  */
 
+/** @template T */
 export default class CompositionAdapter {
-  /** @param {DomAdapterCreateOptions} options */
+  /** @param {DomAdapterCreateOptions<T>} options */
   constructor(options) {
     this.anchorNode = options.anchorNode;
 
@@ -37,12 +51,11 @@ export default class CompositionAdapter {
      */
     this.needsArrayKeyFastPath = false;
 
+    /** @type {Composition<T>} */
     this.composition = options.composition;
+    /** @type {RenderOptions<T>} */
     this.renderOptions = options.renderOptions;
 
-    this.pendingRemoves = [];
-    // Batch objects
-
     /** @type {Map<any, ItemMetadata>} */
     this.metadataCache = null;
 
@@ -55,6 +68,11 @@ export default class CompositionAdapter {
     this.batchEndIndex = null;
   }
 
+  /**
+   * @param {Partial<T>} changes
+   * @param {T} data
+   * @return {import('./Composition.js').RenderDraw<T>}
+   */
   render(changes, data) {
     return this.composition.render(changes, data, this.renderOptions);
   }
@@ -66,7 +84,7 @@ export default class CompositionAdapter {
 
   writeBatch() {
     if (!this.queuedElements.length) return;
-    /** @type {Comment|Element} */
+    /** @type {Comment|Element|Document} */
     const previousSibling = this.metadata[this.batchStartIndex - 1]?.domNode ?? this.anchorNode;
     previousSibling.after(...this.queuedElements);
     this.queuedElements.length = 0;
@@ -226,7 +244,7 @@ export default class CompositionAdapter {
     }
 
     const render = this.render(changes, data);
-    const element = render.target;
+    const element = /** @type {Element} */ (render.target);
 
     this.metadata[newIndex] = {
       render,