@pacem/pacem-foundation 1.0.0-bessel → 1.0.0-binet

package/dist/browser/pacem-foundation.min.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-foundation.min.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-foundation.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -45,6 +45,12 @@ Number.prototype.toBase36 = function() {
 // packages/foundation/dist/esm/dates.js
 var JSON_DATE_PATTERN = /^\/Date\([\d]+\)\/$/i;
 var Dates = class _Dates {
+  /**
+   * Parses a value into a `Date`. Accepts ISO/parseable date strings, ASP.NET-style
+   * `/Date(ticks)/` JSON date strings, numeric timestamps, or a `Date` instance (returned as-is).
+   * @param input Value to parse.
+   * @returns The resulting `Date`.
+   */
   static parse(input) {
     let d;
     if (typeof input === "string") {
@@ -58,9 +64,19 @@ var Dates = class _Dates {
     } else
       return input;
   }
+  /**
+   * Gets whether the given year is a leap year.
+   * @param year Year to check.
+   */
   static isLeapYear(year) {
     return year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
   }
+  /**
+   * Gets the number of days in a given month of a given year.
+   * @param year Year (used to account for leap Februaries).
+   * @param month Zero-based month index (0 = January, ..., 11 = December).
+   * @returns Number of days in the month.
+   */
   static daysInMonth(year, month) {
     return [31, _Dates.isLeapYear(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month];
   }
@@ -78,6 +94,13 @@ var Dates = class _Dates {
   static dateOnly(datetime) {
     return new Date(datetime.getFullYear(), datetime.getMonth(), datetime.getDate());
   }
+  /**
+   * Returns a new date obtained by adding a (possibly negative) number of months to `input`,
+   * clamping the day-of-month to the target month's length (e.g. Jan 31 + 1 month => Feb 28/29).
+   * @param input Starting date.
+   * @param value Number of months to add.
+   * @returns The resulting date.
+   */
   static addMonths(input, value) {
     let n = input.getDate(), i = new Date(input), month = i.getMonth() + value, years = 0;
     while (month < 0) {
@@ -90,9 +113,21 @@ var Dates = class _Dates {
     i.setDate(Math.min(n, _Dates.daysInMonth(i.getFullYear(), i.getMonth())));
     return i;
   }
+  /**
+   * Returns a new date obtained by adding a (possibly negative) number of days to `input`.
+   * @param input Starting date.
+   * @param value Number of days to add.
+   * @returns The resulting date.
+   */
   static addDays(input, value) {
     return new Date(input.valueOf() + value * 864e5);
   }
+  /**
+   * Computes the number of days (possibly fractional) between two dates.
+   * @param start Start date.
+   * @param end End date.
+   * @returns Number of days between `start` and `end` (negative if `end` precedes `start`).
+   */
   static daysBetween(start, end) {
     return (end.valueOf() - start.valueOf()) / 864e5;
   }
@@ -100,9 +135,19 @@ var Dates = class _Dates {
 
 // packages/foundation/dist/esm/null-checker.js
 var NullChecker = class _NullChecker {
+  /**
+   * Returns whether the given value is `null` or `undefined`.
+   * @param o Value to check.
+   */
   static isNull(o) {
     return o === null || o === void 0;
   }
+  /**
+   * Returns whether the given value is "empty": an empty array, an empty string, or a
+   * plain object with no own enumerable keys (dates, regexes and file-system handles are never
+   * considered empty).
+   * @param o Value to check.
+   */
   static isEmpty(o) {
     try {
       return Array.isArray(o) && o.length === 0 || typeof o === "string" && o === "" || typeof o === "object" && Object.keys(o).length === 0 && !Dates.isDate(o) && !(o instanceof RegExp) && !(o instanceof FileSystemDirectoryHandle) && !(o instanceof FileSystemFileHandle);
@@ -110,6 +155,10 @@ var NullChecker = class _NullChecker {
       return false;
     }
   }
+  /**
+   * Returns whether the given value is `null`, `undefined`, or "empty" (see {@link NullChecker.isEmpty}).
+   * @param o Value to check.
+   */
   static isNullOrEmpty(o) {
     return _NullChecker.isNull(o) || _NullChecker.isEmpty(o);
   }
@@ -202,6 +251,14 @@ function deepMerge(target, source) {
 var DeepMerger = class {
   constructor() {
   }
+  /**
+   * Recursively merges `source` into `target`, in place: plain-object properties are merged
+   * recursively (into a fresh object, never adopted by reference), arrays are shallow-copied,
+   * and any other value overwrites the target's.
+   * @param source Object whose properties are merged into `target`.
+   * @param target Object to merge into (defaults to, and lazily creates, the global `Pacem` namespace object).
+   * @returns The mutated `target`, typed as the union of both inputs.
+   */
   static merge(source, target) {
     target ??= globalThis["Pacem"] ??= {};
     return deepMerge(target, source);
@@ -226,6 +283,12 @@ var Arrays = class {
     }
     return output;
   }
+  /**
+   * Splits an array into chunks of a given size.
+   * @param source Array to split.
+   * @param size Maximum size of each chunk (must be a positive integer).
+   * @returns Array of chunks; an empty array if `source` is null or empty.
+   */
   static chunkify(source, size) {
     if (NullChecker.isNullOrEmpty(source)) {
       return [];
@@ -243,6 +306,11 @@ var Arrays = class {
 
 // packages/foundation/dist/esm/blobs.js
 var Blobs = class _Blobs {
+  /**
+   * Reads a `Blob` and resolves it as a base64-encoded data URL.
+   * @param blob Blob to read.
+   * @returns A promise resolving with the data URL string.
+   */
   static blobToDataURL(blob) {
     return new Promise((resolve, _) => {
       const a = new FileReader();
@@ -260,10 +328,21 @@ var Blobs = class _Blobs {
     }
     return u8arr;
   }
+  /**
+   * Converts a base64-encoded string into a `Blob`.
+   * @param bstr Base64-encoded string (without the `data:...;base64,` prefix).
+   * @param options Blob options (e.g. MIME `type`).
+   * @returns The resulting `Blob`.
+   */
   static base64ToBlob(bstr, options) {
     const u8arr = _Blobs._b64ToUint8Array(atob(bstr));
     return new Blob([u8arr], options);
   }
+  /**
+   * Converts a data URL (`data:<mime>;base64,<data>`) into a `Blob`, inferring the MIME type when present.
+   * @param dataurl Data URL to convert.
+   * @returns The resulting `Blob`.
+   */
   static dataURLToBlob(dataurl) {
     const coma = dataurl.indexOf(",");
     if (coma === -1) {
@@ -274,6 +353,12 @@ var Blobs = class _Blobs {
       return _Blobs.base64ToBlob(bstr, { type: mime });
     }
   }
+  /**
+   * Reads a `Blob` and decodes it as text.
+   * @param blob Blob to read.
+   * @param encoding Text encoding to use for decoding (defaults to the platform's default, typically UTF-8).
+   * @returns A promise resolving with the decoded text.
+   */
   static async blobToText(blob, encoding) {
     const buffer = await blob.arrayBuffer();
     const decoder = new TextDecoder(encoding, { fatal: false });
@@ -532,6 +617,11 @@ var Colors = class _Colors {
   static _normalize(rgb) {
     return [rgb[0] / 255, rgb[1] / 255, rgb[2] / 255, rgb[3]];
   }
+  /**
+   * Parses a CSS color string (`rgb()`, `rgba()`, `#rrggbb`, `#rgb`, `hsl()` or `hsla()`) into an {@link Rgba} value.
+   * @param clr CSS color string.
+   * @returns The parsed color, or `undefined` if the string does not match any supported format.
+   */
   static parse(clr) {
     clr = (clr || "").toLowerCase();
     if (RGB_PATTERN.test(clr)) {
@@ -562,6 +652,11 @@ var Colors = class _Colors {
       return this.rgb(hsla);
     }
   }
+  /**
+   * Converts an {@link Rgba} color into its {@link Hsla} equivalent.
+   * @param rgb Color to convert.
+   * @returns The converted color.
+   */
   static hsl(rgb) {
     const l = luminance(rgb), s = saturation(rgb, l), h = hueCircle(rgb);
     return { h, s, l, a: rgb.a };
@@ -709,6 +804,10 @@ function parseAsNumericalArray(input) {
   return arr;
 }
 var Angle = class _Angle {
+  /**
+   * Type-guards a value as a valid {@link Angle} object.
+   * @param obj Value to check.
+   */
   static isAngle(obj) {
     return typeof obj === "object" && "vertex" in obj && Point.isPoint(obj["vertex"]) && "start" in obj && Point.isPoint(obj["start"]) && "end" in obj && Point.isPoint(obj["end"]);
   }
@@ -739,6 +838,12 @@ var Angle = class _Angle {
   }
 };
 var Size = class {
+  /**
+   * Parses a string containing exactly two numbers into a {@link Size}.
+   * @param sz String to parse (e.g. `"100 50"`).
+   * @returns The parsed size.
+   * @throws If `sz` does not contain exactly two numbers.
+   */
   static parse(sz) {
     let arr = parseAsNumericalArray(sz);
     if (arr && arr.length === 2) {
@@ -746,11 +851,21 @@ var Size = class {
     }
     throw new Error(`Cannot parse "${sz}" as a valid Size.`);
   }
+  /**
+   * Type-guards a value as a valid {@link Size} object.
+   * @param obj Value to check.
+   */
   static isSize(obj) {
     return typeof obj === "object" && "width" in obj && typeof obj["width"] === "number" && "height" in obj && typeof obj["height"] === "number";
   }
 };
 var Point = class {
+  /**
+   * Parses a string containing exactly two numbers into a {@link Point}.
+   * @param pt String to parse (e.g. `"10 20"`).
+   * @returns The parsed point.
+   * @throws If `pt` does not contain exactly two numbers.
+   */
   static parse(pt) {
     let arr = parseAsNumericalArray(pt);
     if (arr && arr.length === 2) {
@@ -758,6 +873,10 @@ var Point = class {
     }
     throw new Error(`Cannot parse "${pt}" as a valid Point.`);
   }
+  /**
+   * Type-guards a value as a valid {@link Point} object.
+   * @param obj Value to check.
+   */
   static isPoint(obj) {
     return typeof obj === "object" && "x" in obj && typeof obj["x"] === "number" && "y" in obj && typeof obj["y"] === "number";
   }
@@ -802,21 +921,40 @@ var Point = class {
 
 // packages/foundation/dist/esm/matrix2d.js
 var Matrix2D = class _Matrix2D {
+  /**
+   * Returns whether the given matrix is the identity matrix.
+   * @param m Matrix to check.
+   */
   static isIdentity(m) {
     return m.a === 1 && m.d === 1 && m.b === 0 && m.f === 0 && m.c === 0 && m.e === 0;
   }
+  /** Gets a fresh identity matrix. @readonly */
   static get identity() {
     return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
   }
+  /**
+   * Returns a shallow copy of the given matrix.
+   * @param m Matrix to copy.
+   */
   static copy(m) {
     return { a: m.a, b: m.b, c: m.c, d: m.d, e: m.e, f: m.f };
   }
   static scale(m, sx, sy = sx) {
     return { a: m.a * sx, b: m.b, c: m.c, d: m.d * sy, e: m.e, f: m.f };
   }
+  /**
+   * Returns a copy of `m` translated by the given vector.
+   * @param m Matrix to translate.
+   * @param t Translation vector.
+   */
   static translate(m, t) {
     return { a: m.a, b: m.b, c: m.c, d: m.d, e: m.e + t.x, f: m.f + t.y };
   }
+  /**
+   * Returns a copy of `m` rotated (about the origin) by the given angle.
+   * @param m Matrix to rotate.
+   * @param rad Rotation angle, in radians.
+   */
   static rotate(m, rad) {
     const cos = Math.cos(rad), sin = Math.sin(rad);
     return _Matrix2D.multiply(m, { a: cos, b: sin, c: -sin, d: cos, e: 0, f: 0 });
@@ -848,9 +986,18 @@ var Matrix2D = class _Matrix2D {
       f: m1.e * m2.b + m1.f * m2.d + m2.f
     };
   }
+  /**
+   * Computes the determinant of the matrix's linear part.
+   * @param m Matrix to compute the determinant of.
+   */
   static det(m) {
     return m.a * m.d - m.c * m.b;
   }
+  /**
+   * Computes the inverse of the given matrix.
+   * @param m Matrix to invert.
+   * @returns The inverse matrix, or `null` if `m` is singular (determinant is zero).
+   */
   static invert(m) {
     const det = this.det(m);
     if (det === 0) {
@@ -866,6 +1013,12 @@ var Matrix2D = class _Matrix2D {
       f: m.e * m.b - m.a * m.f
     }, invdet);
   }
+  /**
+   * Decomposes a matrix into its scale, rotation and translation components.
+   * @param m Matrix to decompose.
+   * @param transformOrigin Origin about which the rotation/scale are considered to be applied (defaults to `{x:0, y:0}`).
+   * @returns The decomposed `scaleX`, `scaleY`, `rotation` (radians) and `translation`.
+   */
   static toComponents(m, transformOrigin = { x: 0, y: 0 }) {
     const scaleX = Math.sqrt(m.a * m.a + m.c * m.c);
     const scaleY = Math.sqrt(m.b * m.b + m.d * m.d);
@@ -919,6 +1072,12 @@ var Matrix2D = class _Matrix2D {
 
 // packages/foundation/dist/esm/rect.js
 var Rect = class _Rect {
+  /**
+   * Parses a string containing exactly four numbers into a {@link Rect}.
+   * @param rect String to parse (e.g. `"0 0 100 50"`, in `x y width height` order).
+   * @returns The parsed rect.
+   * @throws If `rect` does not contain exactly four numbers.
+   */
   static parse(rect) {
     let arr = parseAsNumericalArray(rect);
     if (arr && arr.length === 4) {
@@ -926,6 +1085,10 @@ var Rect = class _Rect {
     }
     throw new Error(`Cannot parse "${rect}" as a valid Rect.`);
   }
+  /**
+   * Type-guards a value as a valid {@link Rect} object.
+   * @param obj Value to check.
+   */
   static isRect(obj) {
     return Point.isPoint(obj) && Size.isSize(obj);
   }
@@ -1039,6 +1202,10 @@ var Rect = class _Rect {
 
 // packages/foundation/dist/esm/history-svc.js
 var HistoryService = class {
+  /**
+   * @param state Initial state.
+   * @param maxlength Maximum number of stored states (undo queue + redo stack); unbounded when omitted.
+   */
   constructor(state, maxlength) {
     this.#current = state;
     this.#maxlength = maxlength;
@@ -1056,9 +1223,11 @@ var HistoryService = class {
   get current() {
     return this.#current;
   }
+  /** Gets whether there is a previous state to revert to. @readonly */
   get canUndo() {
     return this.#backwards.length > 0;
   }
+  /** Gets whether there is a subsequent state to reapply. @readonly */
   get canRedo() {
     return this.#forwards.length > 0;
   }
@@ -1067,6 +1236,7 @@ var HistoryService = class {
   set maxlength(v) {
     this.#maxlength = v;
   }
+  /** Reverts to the previous state, if any (see {@link canUndo}), moving the current state onto the redo stack. */
   undo() {
     if (this.canUndo) {
       const back = this.#backwards, fore = this.#forwards, current = this.#current;
@@ -1074,6 +1244,7 @@ var HistoryService = class {
       this.#current = back.pop();
     }
   }
+  /** Reapplies the next state, if any (see {@link canRedo}), moving the current state onto the undo queue. */
   redo() {
     if (this.canRedo) {
       const back = this.#backwards, fore = this.#forwards, current = this.#current;
@@ -1081,6 +1252,11 @@ var HistoryService = class {
       this.#current = fore.shift();
     }
   }
+  /**
+   * Pushes a new current state, clearing the redo stack and enqueuing the previous current state for undo.
+   * Trims the undo queue to `maxlength`, if set.
+   * @param state New current state.
+   */
   push(state) {
     this.#forwards.splice(0);
     this.#backwards.push(this.#current);
@@ -1090,6 +1266,7 @@ var HistoryService = class {
       queue.splice(0, queue.length - max);
     }
   }
+  /** Clears both the undo queue and the redo stack, leaving the current state untouched. */
   reset() {
     this.#forwards.splice(0);
     this.#backwards.splice(0);
@@ -1105,6 +1282,11 @@ var DefaultImagingResizeOptions = {
   type: "image/jpeg"
 };
 var Imaging = class _Imaging {
+  /**
+   * Fetches an image from a URL as a `Blob`.
+   * @param url URL of the image to load.
+   * @returns A promise resolving with the loaded `Blob`, or `null` if the fetch response was not OK.
+   */
   static async loadImage(url) {
     const response = await fetch(url);
     if (!response.ok) {
@@ -1144,14 +1326,27 @@ var Imaging = class _Imaging {
 // packages/foundation/dist/esm/keygenerator.js
 var Keys = class _Keys {
   static #seed;
+  /**
+   * Generates a process-wide monotonically increasing numeric id, seeded from the current timestamp.
+   * @returns A new unique numeric id.
+   */
   static uniqueId() {
     let seed = _Keys.#seed || Date.now();
     return _Keys.#seed = ++seed;
   }
+  /**
+   * Generates a process-wide unique id, base-62 encoded.
+   * @returns A new unique string code.
+   */
   static uniqueCode() {
     const newid = _Keys.uniqueId();
     return newid.toBase62();
   }
+  /**
+   * Generates a random base-62 string of at least the given length.
+   * @param length Minimum length of the generated string.
+   * @returns A random string.
+   */
   static randomString(length) {
     let retval = "";
     do {
@@ -1163,12 +1358,30 @@ var Keys = class _Keys {
 
 // packages/foundation/dist/esm/numbers.js
 var Numbers = class {
+  /**
+   * Rounds a number to the nearest multiple of `step`.
+   * @param x Value to round.
+   * @param step Rounding step/increment (defaults to 1).
+   * @returns The rounded value.
+   */
   static round(x, step = 1) {
     return Math.round(x / step) * step;
   }
+  /**
+   * Computes the logarithm of `x` in an arbitrary `base`.
+   * @param x Value to compute the logarithm of.
+   * @param base Logarithm base.
+   */
   static log(x, base) {
     return Math.log10(x) / Math.log10(base);
   }
+  /**
+   * Converts a number (or numeric string) from one base to another.
+   * @param v Value to convert, expressed in base `from`.
+   * @param from Source base (2-36).
+   * @param to Target base (2-36).
+   * @returns The value re-expressed in base `to`, as a string; `"NaN"` if `v` is not a valid number in base `from`.
+   */
   static rebase(v, from, to) {
     const vStr = v.toString();
     const firstPass = parseInt(vStr, from);
@@ -1264,6 +1477,14 @@ var Strings = class {
     let retval = v.toString();
     return retval.padStart(targetLength, padChar);
   }
+  /**
+   * Formats a template string, replacing `{0}`, `{1}`, ... placeholders with the corresponding arguments.
+   * Doubled braces (`{{`/`}}`) escape a placeholder.
+   * @param template Template string containing `{n}` placeholders.
+   * @param args Values to substitute into the placeholders, by index.
+   * @returns The formatted string.
+   * @throws If the template references an argument index that was not supplied.
+   */
   static format(template, ...args) {
     const array = Array.from(args);
     let retval = template;
@@ -1279,6 +1500,13 @@ var Strings = class {
     }
     return retval;
   }
+  /**
+   * Computes a diff between two strings, using the Longest Common Subsequence algorithm.
+   * @param a First (original) string.
+   * @param b Second (modified) string.
+   * @param mode Diffing granularity: `'char'` (default), `'word'` or `'line'`.
+   * @returns Array of {@link DiffToken}s describing unchanged, removed and added chunks.
+   */
   static diff(a, b, mode = "char") {
     switch (mode) {
       case "line":
@@ -1289,6 +1517,12 @@ var Strings = class {
         return diffChars(a, b);
     }
   }
+  /**
+   * Computes the cryptographic hash of a string using the SubtleCrypto API.
+   * @param input String to hash.
+   * @param algo Hash algorithm to use (defaults to `SHA-256`).
+   * @returns A promise resolving with the hash, hex-encoded.
+   */
   static async hash(input, algo = "SHA-256") {
     const hashBuffer = await crypto.subtle.digest(algo, new TextEncoder().encode(input));
     return Array.from(new Uint8Array(hashBuffer)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -1337,9 +1571,19 @@ var LexerClass = class {
   }
 };
 var Parser = class {
+  /**
+   * @param _lexer Lexer implementation to use (defaults to a built-in greedy, rule-ordered lexer).
+   */
   constructor(_lexer = new LexerClass()) {
     this._lexer = _lexer;
   }
+  /**
+   * Tokenizes `input` against `grammar` and renders the resulting token tree.
+   * @param input String to parse.
+   * @param grammar Ordered list of rules describing the grammar.
+   * @param renderer Renderer used to turn the token tree into the output string.
+   * @returns The rendered output.
+   */
   parse(input, grammar, renderer) {
     const tokens = this._lexer.tokenize(input, grammar);
     return renderer.render(tokens);
@@ -1975,6 +2219,13 @@ function isRenderer(obj) {
   return obj && typeof obj === "object" && typeof obj.render === "function";
 }
 var Parser2 = class extends Parser {
+  /**
+   * Parses Markdown `input` and renders it to an HTML string.
+   * @param input Markdown source.
+   * @param extraGrammar Additional grammar rules to extend the built-in Markdown syntax.
+   * @param extraItemRenderer Fallback renderer invoked for token types not natively handled (e.g. tokens produced by `extraGrammar`); defaults to returning the token's `text`.
+   * @returns The rendered HTML string.
+   */
   toHtml(input, extraGrammar, extraItemRenderer) {
     const renderer = new HtmlRenderer(extraItemRenderer);
     if (NullChecker.isNullOrEmpty(extraGrammar)) {
@@ -1982,6 +2233,12 @@ var Parser2 = class extends Parser {
     }
     return this.parse(input, getGrammar(extraGrammar), renderer);
   }
+  /**
+   * Parses Markdown `input` and returns its token tree as a plain (JSON-serializable) array, useful for inspection/debugging.
+   * @param input Markdown source.
+   * @param extraGrammar Additional grammar rules to extend the built-in Markdown syntax.
+   * @returns The parsed token tree.
+   */
   tokenize(input, extraGrammar) {
     const json = this.parse(input, getGrammar(extraGrammar), new TokenRenderer());
     return JSON.parse(json);