@pacem/pacem-core 1.0.0-bessel → 1.0.0-dirac

package/dist/esm/template.js

@@ -1,9 +1,10 @@
 /*!
- * @pacem/pacem-core v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 //namespace Pacem {
+/** Marker base class for elements that behave like `<template>` (e.g. a custom template-proxy element), so template-detection logic can treat them the same as a native `HTMLTemplateElement`. */
 export class TemplateElement extends HTMLElement {
 }
 //}

package/dist/esm/transforms.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -41,7 +41,21 @@ function buildDiffOptions(modeOrOutput, outputOrCssAdd, cssAddOrRemove, cssRemov
         cssRemove: cssRemove ?? 'fill-red-container',
     };
 }
+/**
+ * The framework's built-in library of template-expression transform functions. Each static method here
+ * is registered, via the {@link Transformer} decorator, under `Utils.core` (mostly by its own method
+ * name - see each method's `@Transformer(...)` name override where present) so it becomes callable by
+ * name from binding expressions (e.g. `{{ ^value | size }}`). Not part of the module's exported surface -
+ * consumers use these by their registered transform name, not by importing this class.
+ */
 class Transforms {
+    /**
+     * Wraps every case-insensitive occurrence of each whitespace-separated token of `query` found in `src`
+     * (skipping matches inside HTML tags) with a `<span class="{css}">` highlight wrapper.
+     * @param src Source HTML/text to search within.
+     * @param query Whitespace-separated search terms.
+     * @param css CSS class applied to the highlight `<span>`. Defaults to `{PCSS}-highlight`.
+     */
     static highlight(src, query, css = PCSS + '-highlight') {
         if (!query || !src)
             return src;
@@ -84,9 +98,11 @@ class Transforms {
             return acc;
         }, '');
     }
+    /** Left-pads `src` (stringified) to `length` characters using `pad`; see {@link Utils.leftPad}. */
     static padleft(src, length, pad) {
         return Utils.leftPad('' + src, length, pad);
     }
+    /** Formats a byte count `src` as a human-readable size string (`B`/`kB`/`MB`/`GB`), or `'-'` if not a positive number. */
     static size(src) {
         // TODO: use logarithms
         if (!(src > 0))
@@ -99,12 +115,25 @@ class Transforms {
             return (src / 1_048_576).toFixed(2) + ' MB';
         return (src / 1_073_741_824).toFixed(2) + ' GB';
     }
+    /**
+     * Formats a decimal-degrees number `src` as degrees/minutes/seconds (e.g. `41° 53' 24"`).
+     * @param src Decimal degrees value (sign indicates direction).
+     * @param degSeparator Text following the degrees component.
+     * @param minSeparator Text following the minutes component.
+     * @param secSeparator Text following the seconds component.
+     */
     static decToDeg(src, degSeparator = '° ', minSeparator = '\' ', secSeparator = '"') {
         const sign = Math.sign(src);
         src = Math.abs(src);
         const deg = Math.floor(src), min0 = (src - deg) * 60, min = Math.floor(min0), sec0 = (min0 - min) * 60, sec = Math.floor(sec0);
         return (sign < 0 ? '-' : '') + deg + degSeparator + min + minSeparator + sec + secSeparator;
     }
+    /**
+     * Formats a date-like value `src` (parsed via {@link Utils.parseDate}) as text.
+     * @param src Date, timestamp, or parseable date string.
+     * @param format Either a named shorthand (`'iso'`, `'isodate'`, `'localdate'`, `'time'`/`'localtime'`, `'full'`, or the default locale date format) or an `Intl.DateTimeFormatOptions` object.
+     * @param culture BCP 47 locale to format with. Defaults to the browser's language.
+     */
     static date(src, format, culture) {
         var date = Utils.parseDate(src), lang = culture || navigator.language;
         if (Utils.isNull(format) || typeof format === 'string') {
@@ -132,6 +161,13 @@ class Transforms {
             return date.toLocaleString(culture, format);
         }
     }
+    /**
+     * Formats the elapsed time between `start` and `end`.
+     * @param start Start date-like value.
+     * @param end End date-like value.
+     * @param format Either an `Intl.DateTimeFormatOptions` (formatted as a UTC duration, optionally sign-prefixed via `sign: true`), or omitted for the legacy `"{d}d {h}h {m}m {s}s {ms}ms"` textual format.
+     * @param culture BCP 47 locale to format with (only used with `Intl.DateTimeFormatOptions`). Defaults to the browser's language.
+     */
     static timespan(start, end, format, culture) {
         const startDate = Utils.parseDate(start), endDate = Utils.parseDate(end), span = endDate.valueOf() - startDate.valueOf(), sign = span < 0 ? '-' : '', elapsed = Math.abs(span);
         if (typeof format === 'object') {
@@ -142,18 +178,26 @@ class Transforms {
         const msecsPerDay = 86400000, msecsPerHr = 3600000, msecsPerMin = 60000, days = Math.floor(elapsed / msecsPerDay), hrs = Math.floor((elapsed % msecsPerDay) / msecsPerHr), mins = Math.floor((elapsed % msecsPerHr) / msecsPerMin), secs = Math.floor((elapsed % msecsPerMin) / 1000), msecs = Math.floor(elapsed % 1000);
         return `${sign}${days}d ${hrs}h ${mins}m ${secs}s ${msecs}ms`;
     }
+    /** Formats `src` as a currency amount using `Intl.NumberFormat`. @param currency ISO 4217 currency code. @param culture BCP 47 locale. Defaults to the browser's language. */
     static currency(src, currency, culture) {
         return new Intl.NumberFormat(culture ?? navigator.language, { style: 'currency', currency: currency }).format(src);
     }
+    /**
+     * Formats `src` as a number using `Intl.NumberFormat`.
+     * @param formatOrCulture Either a BCP 47 locale string, or `Intl.NumberFormatOptions` (in which case `culture` supplies the locale).
+     * @param culture BCP 47 locale, used only when `formatOrCulture` is a format-options object. Defaults to the browser's language.
+     */
     static number(src, formatOrCulture, culture) {
         if (typeof formatOrCulture === 'string') {
             return new Intl.NumberFormat(formatOrCulture || navigator.language).format(src);
         }
         return new Intl.NumberFormat(culture ?? navigator.language, formatOrCulture).format(src);
     }
+    /** Filters `src` with `filter`; a thin wrapper over `Array.prototype.filter` usable from template expressions. */
     static filter(src, filter) {
         return src.filter(filter);
     }
+    /** Sorts `src` in place (ascending, via `>`/`<` comparison), optionally by a property path when items are objects. @param prop Property name to sort by; omit to compare items directly. */
     static orderby(src, prop) {
         return src.sort((a, b) => {
             if (!Utils.isNullOrEmpty(prop)) {
@@ -164,31 +208,39 @@ class Transforms {
         });
     }
     // #region RegExp
+    /** Tests `input` against a `RegExp` built from `pattern`/`flags`. Registered as `regex.isMatch`. */
     static isMatch(input, pattern, flags) {
         return new RegExp(pattern, flags).test(input);
     }
     // #endregion
     // #region shortcuts from 'Utils'
+    /** Template-expression shortcut for {@link Utils.isEmpty}. */
     static isEmpty(obj) {
         return Utils.isEmpty(obj);
     }
+    /** Template-expression shortcut for {@link Utils.isNull}. */
     static isNull(obj) {
         return Utils.isNull(obj);
     }
+    /** Template-expression shortcut for {@link Utils.isNullOrEmpty}. */
     static isNullOrEmpty(obj) {
         return Utils.isNullOrEmpty(obj);
     }
+    /** Reads a CSS custom property's value off the document; see {@link Utils.Css.getVariableValue}. Registered as `cssvar`. */
     static getCssVariable(name) {
         return Utils.Css.getVariableValue(name);
     }
+    /** Reads a query-string parameter's value off the current URL; see {@link Utils.URIs.parseQuery}. Registered as `querystring`. */
     static getQuerystring(name) {
         return Utils.URIs.parseQuery()[name];
     }
     // #endregion
     // #region shortcuts from 'CustomElementUtils'
+    /** Template-expression shortcut for {@link CustomElementUtils.Theme}'s `importWebFonts`. */
     static importThemeWebFonts() {
         return CustomElementUtils.Theme.importWebFonts();
     }
+    /** Template-expression shortcut for {@link CustomElementUtils.findHostContext}. Registered as `host`. */
     static findHostContext(element) {
         return CustomElementUtils.findHostContext(element);
     }

package/dist/esm/types.js

@@ -1,15 +1,20 @@
 /*!
- * @pacem/pacem-core v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 /// <reference path="events.ts" />
+/** Runtime value (aliasing the built-in `Function`) usable where a constructor reference is needed as a value, paired with the {@link Type} interface for typing it. */
 export const Type = Function;
 ;
 // #region CONSTS
+/** Key used to attach, on an element's constructor, the list of its `@Watch`-decorated (watched) property descriptors. */
 export const WATCH_PROPS_VAR = 'pacem:properties';
+/** Key used to attach, on an element instance, the list of attribute names currently holding a pending (not-yet-evaluable) binding expression. */
 export const INSTANCE_BINDINGS_VAR = 'pacem:custom-element:bindings';
+/** Key used to attach, on a templated node, a reference to the custom element instance ("host") whose template produced it — used to resolve binding expression scope. */
 export const INSTANCE_HOST_VAR = 'pacem:custom-element:host';
+/** Key used to attach, on an element instance, its binding-expression evaluation scope object. */
 export const INSTANCE_SCOPE_VAR = 'pacem:custom-element:scope';
 // #endregion
 //}

package/dist/esm/utils-customelement.js

@@ -1,13 +1,8 @@
 /*!
- * @pacem/pacem-core v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
-/// <reference path="expression.ts" />
-/// <reference path="promise.ts" />
-/// <reference path="prefix.ts" />
-/// <reference path="trees/json.ts" />
-/// <reference path="utils.ts" />
 import { Utils } from './utils';
 import { INSTANCE_SCOPE_VAR, WATCH_PROPS_VAR, INSTANCE_HOST_VAR, INSTANCE_BINDINGS_VAR } from './types';
 import { PCSS } from './prefix';
@@ -19,18 +14,50 @@ const PACEM_BAG = '__pacem__';
 const bindingPattern = /^\{\{(.|\n)+\}\}$/;
 // TODO: CSP-proof binding (no unsafe-eval)
 // binding syntax example: `{ binding: { source: ^item.property.path, binder: $pacem.func, parameters: [ ^index, 'foo', : host._baz], mode: 'twoway' } }`
+/**
+ * Static grab-bag of low-level helpers underpinning the {@link CustomElement}/{@link Watch} decorators
+ * and the binding-expression engine: attached-property storage (a per-instance, non-enumerable "bag"
+ * used instead of expando properties), attribute/property name conversion, DOM tree traversal, host/
+ * scope resolution for templated content, and binding-attribute parsing.
+ */
 export class CustomElementUtils {
+    /** `true` when the platform's `customElements` registry is the Custom Elements polyfill rather than a native implementation. */
     static get polyfilling() {
         return customElements instanceof window['CustomElementRegistry'];
     }
+    /** Converts a camelCase property name to its kebab-case attribute-name equivalent (e.g. `myProp` → `my-prop`). */
     static camelToKebab(camelCased) {
         return camelCased && camelCased.replace(/([A-Z])/g, '-$1').toLowerCase();
     }
+    /** Converts a kebab-case attribute name to its camelCase property-name equivalent (e.g. `my-prop` → `myProp`). */
     static kebabToCamel(kebabCased) {
         return kebabCased && kebabCased.replace(/(-[a-z])/g, (m) => {
             return m[1].toUpperCase();
         });
     }
+    /** Waits for the specified alement to be ready. */
+    static waitForReady(element) {
+        return new Promise((resolve, reject) => {
+            if (Utils.isNull(element)) {
+                reject('Not found.');
+            }
+            // if (element.isConnected && !(element instanceof PacemEventTarget)){
+            //     reject('Invalid element.');
+            // }
+            if (element.isReady) {
+                resolve();
+            }
+            const callback = () => {
+                element.removeEventListener('load', callback);
+                resolve();
+            };
+            element.addEventListener('load', callback);
+        });
+    }
+    /** Waits for the specified element to be ready, then executes the provided callback. */
+    static whenReady(element, callback) {
+        CustomElementUtils.waitForReady(element).then(callback);
+    }
     static getWatchedProperties(target, includeInherited = true) {
         var properties = [];
         var chain = target instanceof HTMLElement ? target.constructor : target;
@@ -41,9 +68,16 @@ export class CustomElementUtils {
         } while (includeInherited && (chain = Object.getPrototypeOf(chain)));
         return properties;
     }
+    /** Retrieves a single `@Watch`-decorated property descriptor by name; see {@link getWatchedProperties}. */
     static getWatchedProperty(target, name) {
         return this.getWatchedProperties(target, true).find(p => p.name === name);
     }
+    /**
+     * Loads a `<script>` tag once (deduplicated by `src`, cached via {@link import}), resolving when it fires `load`.
+     * @param src Script URL.
+     * @param integrity Optional Subresource Integrity hash.
+     * @param crossorigin Whether to set `crossorigin` on the tag.
+     */
     static importjs(src, integrity = null, crossorigin = false) {
         var attrs = { 'type': 'text\/javascript', 'src': src };
         if (!Utils.isNullOrEmpty(integrity))
@@ -52,6 +86,12 @@ export class CustomElementUtils {
             Utils.extend(attrs, { 'crossorigin': '' });
         return CustomElementUtils.import(src, 'script', attrs, (document.head || document.getElementsByTagName("head")[0]));
     }
+    /**
+     * Loads a `<link rel="stylesheet">` tag once (deduplicated by `src`, cached via {@link import}), resolving when it fires `load`.
+     * @param src Stylesheet URL.
+     * @param integrity Optional Subresource Integrity hash.
+     * @param crossorigin Whether to set `crossorigin="anonymous"` on the tag.
+     */
     static importcss(src, integrity = null, crossorigin = false) {
         var attrs = { 'rel': 'stylesheet', 'href': src };
         if (!Utils.isNullOrEmpty(integrity))
@@ -60,6 +100,15 @@ export class CustomElementUtils {
             Utils.extend(attrs, { 'crossorigin': 'anonymous' });
         return CustomElementUtils.import(src, 'link', attrs, (document.head || document.getElementsByTagName("head")[0]));
     }
+    /**
+     * Creates (or reuses an already-present, matching) element of `tagName` with the given attributes and
+     * appends it to the DOM, returning a promise that resolves once it loads (or rejects on error). Results
+     * are cached per `key` (under `Utils.core.imports`) so repeated calls with the same key are a no-op.
+     * @param key Cache/dedupe key (typically the resource URL).
+     * @param tagName Tag name of the element to create (e.g. `'script'`, `'link'`).
+     * @param attrs Attributes to set on the element, also used to build a matching CSS selector to detect a pre-existing element.
+     * @param appendTo Node to append the newly created element to, if none was found. Defaults to `document.body`.
+     */
     static import(key, tagName, attrs, appendTo = document.body) {
         const _p = Utils.core;
         var _imports = _p['imports'] = _p['imports'] || {};
@@ -89,7 +138,9 @@ export class CustomElementUtils {
             }
         });
     }
+    /** Theming-related helpers. */
     static { this.Theme = {
+        /** Downloads the web fonts referenced by the current theme's `--{@link PCSS}-font-*` CSS custom properties, resolving once at least one font face is ready (or after a short timeout). */
         importWebFonts() {
             function cleanupQuotes(input) {
                 // check if the string is wrapped around quotes to escape ';' chars
@@ -127,6 +178,14 @@ export class CustomElementUtils {
             return Promise.all(promises);
         }
     }; }
+    /**
+     * Stores an arbitrary value "attached" to `target` under `name`, in a private, non-enumerable bag
+     * (rather than as a plain expando property) so it doesn't show up in `for...in`/`Object.keys`/JSON
+     * serialization. Setting `value` to `null`/`undefined` removes the entry. See {@link getAttachedPropertyValue}.
+     * @param target Object to attach the value to.
+     * @param name Key under which the value is stored.
+     * @param value Value to store, or `null`/`undefined` to remove the entry.
+     */
     static setAttachedPropertyValue(target, name, value) {
         /*(target[PACEM_BAG] = target[PACEM_BAG] || {})[name] = value;*/
         if (Utils.isNull(target))
@@ -141,9 +200,16 @@ export class CustomElementUtils {
         else
             bag[name] = value;
     }
+    /** Removes a value previously stored via {@link setAttachedPropertyValue}. */
     static deleteAttachedPropertyValue(target, name) {
         CustomElementUtils.setAttachedPropertyValue(target, name, undefined);
     }
+    /**
+     * Reads a value previously stored via {@link setAttachedPropertyValue}.
+     * @param target Object the value is attached to.
+     * @param name Key the value is stored under.
+     * @param ensureValue If provided and no value is currently stored, this value is stored and returned (lazy-initialization).
+     */
     static getAttachedPropertyValue(target, name, ensureValue) {
         const propKey = Object.getOwnPropertyDescriptor(target, PACEM_BAG), bag = propKey && propKey.value;
         if (Utils.isNull(bag && bag[name]) && !Utils.isNull(ensureValue)) {
@@ -189,6 +255,17 @@ export class CustomElementUtils {
         }
         return { target: { value: ref, name: name }, parent: { value: parent || scope, path: path.substring(0, ndx) }, root: { value: root, property: core } };
     }
+    /**
+     * Writes `value` at the given dotted `path`, rooted at `element` (see {@link resolvePath}), triggering
+     * the appropriate `propertychange` notification. For paths nested more than one level deep (and not
+     * targeting an `HTMLElement`, which fires change notifications autonomously), the whole root property
+     * is cloned, mutated and reassigned so that a `propertychange` fires with meaningful old/new values -
+     * a plain nested assignment wouldn't otherwise be observed. Repeater-bound `item` paths are special-cased
+     * to update the owning {@link Repeater}'s `datasource` array in place.
+     * @param element Root element the path is resolved against.
+     * @param path Dotted path (e.g. `'foo.bar[0].baz'`) to the target property.
+     * @param value New value to assign.
+     */
     static set(element, path, value) {
         var obj = CustomElementUtils.resolvePath(path, element);
         var current = obj.target.value;
@@ -219,6 +296,7 @@ export class CustomElementUtils {
             }
         }
     }
+    /** Reads the value at the given dotted `path`, rooted at `element`; see {@link resolvePath}. */
     static get(element, path) {
         var obj = CustomElementUtils.resolvePath(path, element);
         return obj && obj.target && obj.target.value;
@@ -239,12 +317,27 @@ export class CustomElementUtils {
         //    logFn(`Element "${element.constructor.name}" isn't attached to any context yet.`);
         return retval;
     }
+    /**
+     * Finds the `Document` or `ShadowRoot` that `element` belongs to - used as the root for resolving
+     * scoped binding expressions (e.g. `$document`/`$host` lookups). Falls back to the previously-attached
+     * scope value (see `INSTANCE_SCOPE_VAR`, set on `connectedCallback`) when `element` is currently
+     * disconnected, and to a legacy manual-walk implementation as a last resort (needed under Jasmine tests,
+     * where `element.isConnected` never reports `true`).
+     * @param element Element to resolve the containing document/shadow-root scope for.
+     */
     static findScopeContext(element) {
         let retval = (element.isConnected) ?
             element.getRootNode()
             : CustomElementUtils.getAttachedPropertyValue(element, INSTANCE_SCOPE_VAR);
         return retval ?? /* in Jasmine TESTS `element.isConnected` always returns false (attached to #document-fragment) */ CustomElementUtils._findScopeContextLegacy(element);
     }
+    /**
+     * Walks up from `element` (crossing shadow-root boundaries via the host element) looking for the
+     * first ancestor matching `predicate`.
+     * @param element Element to start the upward search from.
+     * @param predicate Test invoked (as `this`-bound and argument-passed) against each ancestor.
+     * @returns The first matching ancestor, or `undefined` if none matches.
+     */
     static findAncestor(element, predicate) {
         let el = element;
         let retval;
@@ -258,12 +351,20 @@ export class CustomElementUtils {
         }
         return retval;
     }
+    /** Finds the nearest ancestor "shell" element - matching `.{@link PCSS}-body` - or falls back to `document.body`; see {@link findAncestor}. */
     static findAncestorShell(element) {
         return CustomElementUtils.findAncestor(element, el => Utils.is(el, `.${PCSS}-body`) || el === document.body);
     }
+    /** Finds the nearest ancestor that is an instance of `ctor`; see {@link findAncestor}. */
     static findAncestorOfType(element, ctor) {
         return CustomElementUtils.findAncestor(element, el => el instanceof ctor);
     }
+    /**
+     * Collects the descendants of `element` matching `predicate`, via a `TreeWalker` over element nodes.
+     * @param element Root element to search from (exclusive - the walker starts on its descendants).
+     * @param predicate Test invoked against each descendant element.
+     * @param firstOnly When `true`, stops and returns as soon as one match is found.
+     */
     static findDescendants(element, predicate, firstOnly = false) {
         const walker = document.createTreeWalker(element, NodeFilter.SHOW_ELEMENT);
         var retval = [];
@@ -278,10 +379,16 @@ export class CustomElementUtils {
         }
         return retval;
     }
+    /** Finds the first descendant of `element` matching `predicate`, or `undefined` if none matches; see {@link findDescendants}. */
     static findFirstDescendant(element, predicate) {
         const any = CustomElementUtils.findDescendants(element, predicate, true);
         return Utils.isNullOrEmpty(any) ? void 0 : any[0];
     }
+    /**
+     * Queries the whole document for elements matching `selector`, additionally filtered by `filter`.
+     * @param selector CSS selector to query for. Defaults to `'[pacem]'` (every Pacem custom element, which all carry that attribute once connected).
+     * @param filter Extra predicate applied to each matched element. Defaults to accepting everything.
+     */
     static findAll(selector = '[pacem]', filter = (e) => true) {
         const retval = [];
         document.querySelectorAll(selector).forEach((e, i, arr) => {
@@ -343,6 +450,14 @@ export class CustomElementUtils {
         } while (el != null);
         return retval;
     }
+    /**
+     * Tags every element/document-fragment node inside `template`'s content (that isn't already tagged)
+     * with `host` under `INSTANCE_HOST_VAR`, so that once cloned and inserted into the DOM, binding
+     * expressions in that fragment can resolve back to the custom element instance ("host") that owns
+     * this template. See {@link findHostContext}.
+     * @param host The custom element instance whose template this is.
+     * @param template Template whose content's descendants should be tagged.
+     */
     static assignHostContext(host, template) {
         // navigate through the DOM hierarchy
         const walker = document.createTreeWalker(template.content, NodeFilter.SHOW_ELEMENT + /* traverse templates' content */ NodeFilter.SHOW_DOCUMENT_FRAGMENT);
@@ -355,6 +470,13 @@ export class CustomElementUtils {
             }
         }
     }
+    /**
+     * Walks up from `element` looking for the nearest ancestor (inclusive) tagged with a host reference
+     * via {@link assignHostContext}; this is the custom element instance whose template produced `element`,
+     * used to resolve `$host`/scope references in binding expressions. Returns `undefined` (with a console
+     * warning) if `element` is disconnected or isn't part of any templated component.
+     * @param element Element to resolve the owning host for.
+     */
     static findHostContext(element) {
         let el = element;
         let retval;
@@ -377,6 +499,7 @@ export class CustomElementUtils {
             logFn(`Element "${element.constructor.name}" isn't a descendant of a templated component.`);
         return retval;
     }
+    /** Tests whether an attribute's raw string value has binding-expression syntax (`{{ ... }}`). */
     static isBindingAttribute(attr) {
         /*if (/^\s*\{\s*binding\s+.*\}\s*$/.test(attr)) {
 
@@ -396,6 +519,7 @@ export class CustomElementUtils {
         else*/
         return bindingPattern.test(attr);
     }
+    /** Strips the `{{ }}` delimiters off a binding attribute's raw value, returning the bare expression text. Throws if `attr` isn't a valid binding attribute; see {@link isBindingAttribute}. */
     static extractBindingAttributeExpression(attr) {
         if (CustomElementUtils.isBindingAttribute(attr)) {
             return attr.substr(2, attr.length - 4);
@@ -404,6 +528,13 @@ export class CustomElementUtils {
             throw `Invalid attribute: incorrect binding syntax.`;
         }
     }
+    /**
+     * Parses a `{{ ... }}` binding attribute value into an {@link Expression}, recognizing the optional
+     * trailing `, twoway` / `, once` modifier and stamping it onto the expression's dependencies (`twoway`
+     * only applies when the expression has exactly one dependency that itself allows two-way binding).
+     * @param attr Raw binding attribute value, including the `{{ }}` delimiters.
+     * @param element Element the expression is evaluated/bound against (used to resolve scope references).
+     */
     static parseBindingAttribute(attr, element) {
         // loose syntax {{ ... }}
         let expression = CustomElementUtils.extractBindingAttributeExpression(attr);
@@ -424,6 +555,14 @@ export class CustomElementUtils {
         });
         return expr;
     }
+    /**
+     * Defines an own property `name` on `o` with `attributes`, unless `o` already has an own property
+     * descriptor for that name (in which case the existing descriptor is returned untouched).
+     * @param o Object to define the property on.
+     * @param name Property name.
+     * @param attributes Property descriptor to apply if the property isn't already defined.
+     * @returns The (possibly pre-existing) property descriptor.
+     */
     static ensureMember(o, name, attributes) {
         let original = Object.getOwnPropertyDescriptor(o, name);
         if (original != undefined)
@@ -485,6 +624,7 @@ function avoidObservedAttributes(element, freeze = true) {
 const GET_VAL = CustomElementUtils.getAttachedPropertyValue;
 const SET_VAL = CustomElementUtils.setAttachedPropertyValue;
 const REPEATERITEM_PLACEHOLDER = 'pacem:repeater-item';
+/** Static lookup helpers for locating the {@link RepeaterItem} context a given element belongs to. */
 export class Repeater {
     /**
      * Seeks for a PacemRepeaterItem element upwards through the DOM tree, given a starting element and the number of nesting levels.
@@ -499,7 +639,22 @@ export class Repeater {
         return retval;
     }
 }
+/**
+ * Base class tracking a single rendered repetition of a {@link Repeater}'s template: it associates a
+ * DOM placeholder node with the `item`/`index` scope values that template's binding expressions
+ * evaluate against, and is itself attached to that placeholder (see {@link getRepeaterItem}) so
+ * descendant elements can find their way back to it via {@link findUpwards}.
+ */
 export class RepeaterItem {
+    /**
+     * Seeks upwards from `element` (previous siblings, then parent, repeated) for the nearest ancestor
+     * placeholder tagged as a {@link RepeaterItem}, skipping `upLevels` matches before returning one -
+     * this is how deeply-nested repeaters resolve which repetition (of which ancestor repeater) an
+     * expression's `^item`/`^^item`/... token refers to.
+     * @param element Element to start the upward search from.
+     * @param upLevels 0-based number of matching ancestors to skip before returning one (`0` = nearest).
+     * @param logFn Called with a warning message if no match is found and `element` is connected to the DOM.
+     */
     static findUpwards(element, upLevels = 0, logFn = console.warn) {
         if (Utils.isNull(element) || element.localName === 'template' || element instanceof /* template-like element? */ TemplateElement) {
             return null;
@@ -512,16 +667,20 @@ export class RepeaterItem {
         }
         return item;
     }
+    /** Tests whether `node` is the placeholder of some {@link RepeaterItem}. */
     static isRepeaterItem(node) {
         return !Utils.isNull(GET_VAL(node, REPEATERITEM_PLACEHOLDER));
     }
+    /** Retrieves the {@link RepeaterItem} attached to `node`, if `node` is a repeater-item placeholder; see {@link isRepeaterItem}. */
     static getRepeaterItem(node) {
         return GET_VAL(node, REPEATERITEM_PLACEHOLDER);
     }
+    /** @param _placeholder DOM node (typically a comment) that stands in for this repetition and gets tagged so {@link getRepeaterItem} can retrieve this instance back from it. */
     constructor(_placeholder) {
         this._placeholder = _placeholder;
         SET_VAL(_placeholder, REPEATERITEM_PLACEHOLDER, this);
     }
+    /** The DOM placeholder node standing in for this repetition. */
     get placeholder() {
         return this._placeholder;
     }

package/dist/esm/utils-customevent.js

@@ -1,9 +1,10 @@
 /*!
- * @pacem/pacem-core v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 import { Utils } from './utils';
+/** String tokens accepted by {@link CustomEventUtils.matchModifiers} to describe a keyboard/mouse modifier. */
 export var EventKeyModifier;
 (function (EventKeyModifier) {
     EventKeyModifier["AltKey"] = "Alt";
@@ -11,11 +12,24 @@ export var EventKeyModifier;
     EventKeyModifier["ShiftKey"] = "Shift";
     EventKeyModifier["MetaKey"] = "Cmd";
 })(EventKeyModifier || (EventKeyModifier = {}));
+/** Static helpers for inspecting and normalizing native/custom events (coordinates, keyboard modifiers, type checks). */
 export class CustomEventUtils {
+    /**
+     * Type-guarding check for whether `evt` is an instance of the given event `type`.
+     * @param evt Event to test.
+     * @param type Event constructor to test against.
+     * @returns `true` (narrowing `evt` to `TEvent`) if `evt instanceof type`.
+     */
     static isInstanceOf(evt, type) {
         return evt instanceof type;
         // || CustomElementUtils.getAttachedPropertyValue(evt, 'pacem:custom-event') === evt.type;
     }
+    /**
+     * Extracts page/client/screen coordinates from a mouse or (single-)touch event, using the first
+     * active touch (`touches[0]`, falling back to `changedTouches[0]`) for `TouchEvent`s.
+     * @param evt Source mouse/touch event, or an already-extracted {@link UIEventLike}.
+     * @returns The event's position in all three coordinate systems.
+     */
     static getEventCoordinates(evt) {
         var src;
         if ('touches' in evt) {
@@ -35,6 +49,11 @@ export class CustomEventUtils {
             client: { x: src.clientX, y: src.clientY }
         };
     }
+    /**
+     * Extracts the keyboard-modifier flags (and, for mouse events, the pressed button as `which`) from a native event.
+     * @param evt Source keyboard/mouse/touch event, or an already-extracted {@link KeyEventLike}.
+     * @returns The captured modifier flags.
+     */
     static getEventKeyModifiers(evt) {
         var which = evt.which;
         if (evt instanceof MouseEvent) {
@@ -55,6 +74,13 @@ export class CustomEventUtils {
         }
         return true;
     }
+    /**
+     * Works around a legacy Edge/ChakraCore bug (see {@link https://github.com/Microsoft/ChakraCore/issues/3952})
+     * where an instance built via `super(...)` from a `CustomEvent` subclass constructor doesn't correctly
+     * pass `instanceof` checks against that subclass; forcibly resets its prototype when so.
+     * @param evt Event instance to fix up.
+     * @param type The subclass constructor `evt` is supposed to be an instance of.
+     */
     static fixEdgeCustomEventSubClassInstance(evt, type) {
         // this an optimistic BUGGED workaround due to a damn' Edge bug: https://github.com/Microsoft/ChakraCore/issues/3952
         if (!(evt instanceof type)) {