@pacem/pacem-core 1.0.0-bernoulli → 1.0.0-binet

package/dist/esm/utils.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -10,40 +10,56 @@ import { DeferPromise } from './promise';
 // namespace Pacem {
 const PACEM_CORE_DEFAULT = 'pacem';
 const DEFAULT_DOWNLOAD_FILENAME = 'download';
+/** Ready-to-use event listener that only calls `evt.stopPropagation()`; handy as an `addEventListener` callback without allocating a closure. */
 export const stopPropagationHandler = (evt) => {
     evt.stopPropagation();
 };
+/** Ready-to-use event listener that only calls `evt.preventDefault()`; handy as an `addEventListener` callback without allocating a closure. */
 export const preventDefaultHandler = (evt) => {
     evt.preventDefault();
 };
+/** Ready-to-use event listener that calls both `evt.preventDefault()` and `evt.stopPropagation()`. */
 export const avoidHandler = (evt) => {
     evt.preventDefault();
     evt.stopPropagation();
 };
 const SEGMENT_PATTERN = /^\/[^\/]+/;
 const ROUTE_SEGMENT_PATTERN = /\/\{([a-z\$_][\w]*)\??\}/;
+/**
+ * The framework's static utility grab-bag: general helpers plus namespaced sub-modules (`Json`, `Dates`,
+ * `Css`, `Strings`, `Blobs`, `Images`, `Browsers`, `Cookies`, `URIs`) re-exposing (and in some cases
+ * extending) functionality from `@pacem/pacem-foundation`. Also the home of `Utils.core`, the global
+ * registry object used for cross-cutting framework state (e.g. registered {@link Transformer}s).
+ */
 export class Utils {
+    /** The framework's global scratch/registry object (`window[id]`, where `id` defaults to `'pacem'` and is configurable via `window.Pacem.Configuration.core`); created on first access. Used e.g. to store {@link Transformer}-registered transform functions. */
     static get core() {
         const root = window['Pacem'];
         var id = (root && root.Configuration && root.Configuration.core) || PACEM_CORE_DEFAULT;
         return window[id] = window[id] || {};
     }
+    /** The platform's (native or polyfilled) `customElements` registry. */
     static get customElements() {
         return window['customElements'];
     }
     // #region GENERAL
+    /** Generates a unique numeric-ish id string. */
     static uniqueId() {
         return Keys.uniqueId();
     }
+    /** Generates a unique short code string. */
     static uniqueCode() {
         return Keys.uniqueCode();
     }
+    /** Generates a random string of the given `length`. */
     static randomString(length) {
         return Keys.randomString(length);
     }
+    /** Parses a date-like value (ISO string, `Date`, or timestamp) into a `Date`. */
     static parseDate(input) {
         return Dates.parse(input);
     }
+    /** Writes `input` to the system clipboard, using the async Clipboard API when available and falling back to `document.execCommand('copy')` otherwise. */
     static copyToClipboard(input) {
         if (navigator.clipboard) {
             return navigator.clipboard.writeText(input);
@@ -111,6 +127,7 @@ export class Utils {
             return filter;
         }
     }
+    /** Escapes `input` for safe use as a CSS identifier/selector fragment. */
     static cssEscape(input) {
         return escape(input).replace('%', '\\');
     }
@@ -118,9 +135,11 @@ export class Utils {
     static { this.Css = {
         colorize: Utils.colorize,
         escape: Utils.cssEscape,
+        /** Reads a CSS custom property's current value off the document root (`:root`/`html`). */
         getVariableValue(name) {
             return getComputedStyle(document.documentElement).getPropertyValue(name);
         },
+        /** Sets a CSS custom property's value on the document root (`:root`/`html`). */
         setVariable(name, value) {
             getComputedStyle(document.documentElement).setProperty(name, value);
         },
@@ -150,6 +169,7 @@ export class Utils {
             }
             return false;
         },
+        /** Parses an element's (or style declaration's) computed `transform: matrix(...)` CSS value into its 2D affine matrix components; identity if unset. */
         deserializeTransform(element) {
             const style = element instanceof Element ? getComputedStyle(element) : element;
             let a = 1, b = 0, c = 0, d = 1, x = 0, y = 0, matches = /^matrix\((.*)\)$/.exec(style.transform), mij;
@@ -176,6 +196,7 @@ export class Utils {
         leftPad: Strings.leftPad,
         format: Strings.format,
         diff: Strings.diff,
+        /** Strips HTML markup from `html`, returning its plain-text content. */
         stripHTML: (html) => {
             let doc = new DOMParser().parseFromString(html, 'text/html');
             return doc.body.textContent || '';
@@ -194,6 +215,7 @@ export class Utils {
         load: Imaging.loadImage,
         resize: Imaging.resizeImage
     }; }
+    /** Loads an image from `src` and resolves with the `HTMLImageElement` once ready (or rejects on error). */
     static loadImage(src) {
         return new Promise((resolve, reject) => {
             const img = new Image();
@@ -211,15 +233,19 @@ export class Utils {
             }
         });
     }
+    /** Converts a `Blob` to a `data:` URL string. */
     static blobToDataURL(blob) {
         return Utils.Blobs.toDataURL(blob);
     }
+    /** Converts a `data:` URL string back into a `Blob`. */
     static dataURLToBlob(dataURL) {
         return Utils.Blobs.fromDataURL(dataURL);
     }
+    /** Reads a `Blob`'s content as text, using the given `encoding` (default UTF-8). */
     static blobToText(blob, encoding) {
         return Utils.Blobs.toText(blob, encoding);
     }
+    /** Wraps `content` in a `Blob` of the given MIME `type` (default `'text/plain'`). */
     static textToBlob(content, type = 'text/plain') {
         return Utils.Blobs.fromText(content, type);
     }
@@ -305,6 +331,7 @@ export class Utils {
         el.src = url;
         return deferred.promise;
     }
+    /** Returns the list of vendor-prefixed `getUserMedia` implementations available on `navigator`, if any. */
     static getUserMediaFunctions() {
         var _getUserMedia = [];
         let methods = [navigator['getUserMedia'], navigator['webkitGetUserMedia'], navigator['msGetUserMedia'], navigator['mozGetUserMedia']];
@@ -551,10 +578,12 @@ export class Utils {
     }
     // #endregion
     // #region DOM
+    /** Whether the document (including module scripts) has fully finished loading (`document.readyState === 'complete'`). */
     static isDOMReady() {
         // Must exclude 'interactive' state since module script haven't been processed yet.
         return /* document.readyState === 'interactive' ||*/ document.readyState === 'complete';
     }
+    /** Registers `listener` to run once the document (and its resources, e.g. images) has fully loaded (the `window` `'load'` event). */
     static onDOMReady(listener) {
         //window.addEventListener('DOMContentLoaded', listener, false);
         // window 'load' event fires after 'DOMCOntentLoaded' since includes images load.
@@ -583,13 +612,16 @@ export class Utils {
         }
         return dom;
     }
+    /** Cross-browser `Element.matches(selector)`, falling back to vendor-prefixed variants. */
     static is(el, selector) {
         return (el.matches || el.matchesSelector || el.msMatchesSelector || el.mozMatchesSelector || el.webkitMatchesSelector || el.oMatchesSelector)
             .call(el, selector);
     }
+    /** Resolves the effective language for `el`: its own `lang` attribute, else the document's, else the browser's. */
     static lang(el) {
         return el.lang || document.documentElement.lang || navigator.language;
     }
+    /** JSON-stringifies `obj` (via {@link Json}), or passes through `null`/`undefined` unchanged. */
     static jsonSortStringify(obj) {
         if (Utils.isNull(obj)) {
             return obj;
@@ -599,6 +631,7 @@ export class Utils {
     static { this.Browsers = {
         detect
     }; }
+    /** Parses a `document.cookie`-style string (or `document.cookie` itself, by default) into a name/value map. */
     static cookies(cookie) {
         const cookies = (cookie ?? document.cookie).split(';'), retval = {};
         for (var pair of cookies) {
@@ -614,7 +647,9 @@ export class Utils {
         }
         return retval;
     }
+    /** Cookie helpers, preferring the native `cookieStore` API when available and falling back to `document.cookie` parsing otherwise. */
     static { this.Cookies = {
+        /** Retrieves all cookies (or just `cookieName`, if given) as {@link CookieData} entries. */
         getAll: async (cookieName) => {
             const store = 'cookieStore' in window ? window.cookieStore : null;
             const retval = [];
@@ -632,6 +667,7 @@ export class Utils {
                 return await store.getAll(cookieName);
             }
         },
+        /** Serializes a {@link CookieData} descriptor into a `document.cookie`-assignable string (including `domain`/`path`/`max-age`/`expires`/`Partitioned`/`SameSite`/`Secure` attributes, as provided). */
         stringify: (data) => {
             let retval = `${data.name}=${encodeURIComponent(data.value ?? '')}`;
             if (!Utils.isNullOrEmpty(data.domain)) {
@@ -658,6 +694,7 @@ export class Utils {
             return retval;
         }
     }; }
+    /** Tests whether `el` is currently visible (via the `checkVisibility` API when available, falling back to a CSS-visibility/size heuristic). */
     static isVisible(el) {
         if ('checkVisibility' in el) {
             return el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
@@ -665,6 +702,7 @@ export class Utils {
         return getComputedStyle(el).visibility !== 'hidden' && (el.clientWidth > 0 || el.clientHeight > 0);
     }
     //#region classList DOMTokenList (css)
+    /** Tests whether `el` has `className` set, using `classList` when available (with a regex-based fallback). */
     static hasClass(el, className) {
         if (el.classList) {
             return el.classList.contains(className);
@@ -673,6 +711,7 @@ export class Utils {
             return new RegExp('(^| )' + className + '( |$)', 'gi').test(el.className);
         }
     }
+    /** Adds one or more (space-separated) classes to `el`, using `classList` when available. */
     static addClass(el, className) {
         const css = className.trim();
         if (el.classList) {
@@ -682,6 +721,7 @@ export class Utils {
             el.setAttribute('class', el.className + ' ' + css);
         }
     }
+    /** Removes one or more (space-separated) classes from `el`, using `classList` when available. */
     static removeClass(el, className) {
         const css = className.trim();
         if (el.classList) {
@@ -691,6 +731,7 @@ export class Utils {
             el.setAttribute('class', el.className.replace(new RegExp('(^|\\b)' + css.split(' ').join('|') + '(\\b|$)', 'gi'), ' '));
         }
     }
+    /** Adds or removes `className` on `el` depending on `on`; see {@link addClass}/{@link removeClass}. */
     static toggleClass(el, className, on) {
         if (on) {
             Utils.addClass(el, className);
@@ -701,15 +742,19 @@ export class Utils {
     }
     //#endregion
     //#region part DOMTokenList (shadow-DOM)
+    /** Tests whether `el`'s `part` attribute (CSS Shadow Parts) contains `partName`. */
     static hasPart(el, partName) {
         return el.part.contains(partName);
     }
+    /** Adds one or more (space-separated) shadow-part names to `el`'s `part` attribute. */
     static addPart(el, partName) {
         DOMTokenList.prototype.add.apply(el.part, partName.trim().split(' '));
     }
+    /** Removes one or more (space-separated) shadow-part names from `el`'s `part` attribute. */
     static removePart(el, partName) {
         DOMTokenList.prototype.remove.apply(el.part, partName.trim().split(' '));
     }
+    /** Adds or removes `partName` on `el`'s `part` attribute depending on `on`; see {@link addPart}/{@link removePart}. */
     static togglePart(el, partName, on) {
         if (on) {
             Utils.addPart(el, partName);
@@ -745,9 +790,11 @@ export class Utils {
             height: rect.height
         };
     }
+    /** Sums `offsetTop` up the `offsetParent` chain, giving `el`'s vertical position relative to the document rather than just its nearest positioned ancestor. */
     static naturalOffsetTop(el) {
         return (el?.offsetTop ?? 0) + ((el?.offsetParent && el.offsetParent instanceof HTMLElement) ? this.naturalOffsetTop(el.offsetParent) : 0);
     }
+    /** Sums `offsetTop` up the `offsetParent` chain (note: mirrors {@link naturalOffsetTop}'s calculation, not `offsetLeft`), giving `el`'s horizontal position relative to the document. */
     static naturalOffsetLeft(el) {
         return (el?.offsetTop ?? 0) + ((el?.offsetParent && el.offsetParent instanceof HTMLElement) ? this.naturalOffsetLeft(el.offsetParent) : 0);
     }
@@ -775,18 +822,30 @@ export class Utils {
     static deserializeTransform(obj) {
         return Utils.Css.deserializeTransform(obj);
     }
+    /** Sets the window's vertical scroll position, keeping the current horizontal position. */
     static set scrollTop(y) {
         window.scrollTo(Utils.scrollLeft, y);
     }
+    /** Sets the window's horizontal scroll position, keeping the current vertical position. */
     static set scrollLeft(x) {
         window.scrollTo(x, Utils.scrollTop);
     }
+    static scrollTo(x, y = true, smooth = true) {
+        const yFirst = Utils.isNull(y) || typeof y === 'boolean';
+        const left = yFirst ? Utils.scrollLeft : x;
+        const top = yFirst ? x : y;
+        const behavior = (yFirst ? y : smooth) ? 'smooth' : 'instant';
+        window.scrollTo({ behavior, left, top });
+    }
+    /** The window's current vertical scroll position, with fallbacks for older browsers. */
     static get scrollTop() {
         return window.scrollY /*window.pageYOffset*/ || document.documentElement.scrollTop || document.body.scrollTop || 0;
     }
+    /** The window's current horizontal scroll position, with fallbacks for older browsers. */
     static get scrollLeft() {
         return window.scrollX /*window.pageXOffset*/ || document.documentElement.scrollLeft || document.body.scrollLeft || 0;
     }
+    /** The window's current viewport size (`{ width, height }`), with fallbacks for older browsers. */
     static get windowSize() {
         let win = window;
         return {
@@ -862,16 +921,20 @@ export class Utils {
     }
     // #endregion
     // #region other
+    /** Tests whether `obj` is "empty" (per {@link NullChecker.isEmpty}: `null`/`undefined`/`''`/an empty array or object), excluding DOM `Node`s (which are never considered empty here). */
     static isEmpty(obj) {
         return NullChecker.isEmpty(obj) && !(obj instanceof Node);
     }
+    /** Type-guarding test for `obj` being `null` or `undefined`. */
     static isNull(obj) {
         return NullChecker.isNull(obj);
     }
     // legacy
+    /** Type-guarding test for `val` being an array. */
     static isArray(val) {
         return Array.isArray(val);
     }
+    /** Tests whether `val` is `null`/`undefined` or "empty"; see {@link isNull}/{@link isEmpty}. */
     static isNullOrEmpty(val) {
         return Utils.isNull(val) || Utils.isEmpty(val);
     }
@@ -890,6 +953,7 @@ export class Utils {
     }
     /** Legacy alias for Object.assign(). */
     static { this.extend = Object.assign; }
+    /** Deep-clones `obj`; see {@link DeepCloner}. */
     static clone(obj) {
         if (obj === undefined)
             return undefined;
@@ -899,6 +963,7 @@ export class Utils {
     static fromResult(v) {
         return Promise.resolve(v);
     }
+    /** Runs `task` on the next animation frame and wraps its result in a `Promise`. */
     static fromResultAsync(task) {
         return new Promise(resolve => requestAnimationFrame(() => resolve(task())));
     }
@@ -922,7 +987,15 @@ export class Utils {
     }
     //#endregion
     //#region Net
+    /** URL/route parsing and formatting helpers, chiefly backing the router (`{segment}`/`{segment?}` template resolution, query-string parsing, route metadata). */
     static { this.URIs = {
+        /**
+         * Substitutes each `{name}`/`{name?}` template segment in `url` with the matching entry of `parameters`
+         * (URL-encoded), then strips out any remaining unmatched *optional* segments.
+         * @param url URL/route template containing `{name}`/`{name?}` segments.
+         * @param parameters Values to substitute, keyed by segment name.
+         * @param removeMatchedParameters When `true`, consumed entries are deleted from `parameters`.
+         */
         format: function (url, parameters, removeMatchedParameters) {
             // replace segments
             for (let name in parameters || {}) {
@@ -945,6 +1018,14 @@ export class Utils {
             }
             return url;
         },
+        /**
+         * Appends `parameters` to `url`'s query string (or hash fragment, when `hash` is `true`), URL-encoding
+         * names and values, and correctly choosing `?`/`&` (or `#`/`&`) as the joining separator.
+         * @param url Base URL.
+         * @param parameters Values to append, keyed by parameter name.
+         * @param removeNullEntries When `true`, entries whose value is `null`/`undefined` are omitted instead of appended as empty.
+         * @param hash When `true`, appends to the URL's hash fragment instead of its query string.
+         */
         appendQuery: function (url, parameters, removeNullEntries = false, hash = false) {
             const char = hash ? '#' : '?', pattern = hash ? /#/ : /\?/;
             const query = (pattern.test(url) ? '&' : char) +
@@ -953,6 +1034,7 @@ export class Utils {
                     .map(k => encodeURIComponent(k) + '=' + encodeURIComponent(parameters[k] ?? '')).join('&');
             return url + (query.length > 1 ? query : '');
         },
+        /** Parses a query string (or a `Location`'s `.search`, defaulting to `window.location`) into a name/value map. */
         parseQuery: (query = window.location) => {
             if (typeof query !== 'string') {
                 query = query.search;
@@ -963,9 +1045,11 @@ export class Utils {
             });
             return obj;
         },
+        /** Tests whether `url` contains at least one non-optional `{name}` template segment (as opposed to only `{name?}` ones). */
         hasMandatoryTemplateSegments: function (url) {
             return /(^|\/)\{\.*\}(\/|$)/.test(url);
         },
+        /** Parses a route template's `{name}`/`{name?}` segments into an ordered list of {@link RouteMetadata} descriptors, consumed by {@link parseState}. */
         parseRoute: function (pathTemplate) {
             let tmpl = pathTemplate;
             const trunks = [];
@@ -985,6 +1069,7 @@ export class Utils {
             }
             return trunks;
         },
+        /** Splits `url` into its `protocol`, `domain`, `path`, `query` (including leading `?`) and `hash` (including leading `#`) parts, or `null` if it can't be parsed. */
         split: function (url) {
             const URL_PATTERN = /^((https?:)?\/\/[^\/]+)?([^\?#]+)(\?[^#]*)?(#[^#]*)?$/;
             const regArr = URL_PATTERN.exec(url);
@@ -993,6 +1078,16 @@ export class Utils {
             }
             return { domain: regArr[2] ?? '', protocol: regArr[1] ?? '', path: regArr[3] ?? '', query: regArr[4] ?? '', hash: regArr[5] ?? '' };
         },
+        /**
+         * Builds a {@link RouterState} for `url`, extracting named route segments per `metadata` (see
+         * {@link parseRoute}) as top-level properties, alongside the standard `$path`/`$pathname`/`$querystring`/
+         * `$query`/`$hash` keys. Throws if a non-optional route segment declared in `metadata` isn't present in `path`.
+         * @param metadata Route segment descriptors, as produced by {@link parseRoute}.
+         * @param url Full URL/path being navigated to.
+         * @param path Path component override; parsed out of `url` via {@link split} when omitted.
+         * @param query Query-string override (including leading `?`); parsed out of `url` when omitted.
+         * @param hash Hash-fragment override (including leading `#`); parsed out of `url` when omitted.
+         */
         parseState: function (metadata, url, path, query, hash) {
             let fullPath = url;
             if (Utils.isNullOrEmpty(path)) {

package/package.json

@@ -4,6 +4,7 @@
     "dist/browser/*.*",
     "dist/bundle/*.*",
     "dist/esm/*.*",
+    "dist/docs/*.*",
     "typings/*.*",
     "README.md",
     "LICENSE",
@@ -23,7 +24,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "1.0.0-bernoulli",
+  "version": "1.0.0-binet",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"