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

package/dist/esm/array-extensions.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/arrays.js

@@ -1,10 +1,11 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 //namespace Pacem {
 import { NullChecker } from "./null-checker";
+/** Array manipulation utilities. */
 export class Arrays {
     static range(min, max, items = 2) {
         let x = min;
@@ -23,6 +24,12 @@ export class Arrays {
         }
         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 [];

package/dist/esm/blobs.js

@@ -1,10 +1,16 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 //namespace Pacem {
+/** Conversion utilities between `Blob`, base64/data URLs and plain text. */
 export 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();
@@ -20,10 +26,21 @@ export 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) {
@@ -35,6 +52,12 @@ export 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 });

package/dist/esm/browser.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -10,6 +10,11 @@ const browserVersion = (userAgent, regex) => {
     return match ? match[2] : null;
 };
 // https://stackoverflow.com/77095874
+/**
+ * Detects the browser name and version from a user-agent string.
+ * @param userAgent User-agent string to parse (defaults to `navigator.userAgent`).
+ * @returns An object with the detected browser `name` (e.g. `Chrome`, `Firefox`, `Safari`, `Edge`, `IE`, `unknown`, ...) and its `version`.
+ */
 export function detect(userAgent = navigator.userAgent) {
     let browser = 'unknown';
     let version = null;

package/dist/esm/colors.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -142,9 +142,13 @@ function hexify(v) {
     return v.toString(16).padStart(2, '0');
     //return Pacem.Strings.leftPad(v.toString(16), 2, '0');
 }
+/** Color parsing, conversion (RGB/HSL/CIE XYZ) and manipulation utilities. */
 export class Colors {
+    /** Minimum WCAG contrast ratio recommended for large-scale text/graphical objects. */
     static { this.WCAG_MINIMUM_CONTRAST = 3.0; }
+    /** Minimum WCAG (AA) contrast ratio recommended for normal-sized text. */
     static { this.WCAG_NORMAL_TEXT_CONTRAST = 4.5; }
+    /** Minimum WCAG (AAA) contrast ratio recommended for enhanced accessibility. */
     static { this.WCAG_SAFE_CONTRAST = 7.0; }
     static _clampRGB(rgb) {
         const clmp = (n) => Math.min(1.0, Math.max(0, n));
@@ -156,6 +160,11 @@ export class Colors {
     static _normalize(rgb) {
         return [rgb[0] / 255.0, rgb[1] / 255.0, rgb[2] / 255.0, 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();
         /* rgb(255,255,255) */
@@ -192,6 +201,11 @@ export 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 };

package/dist/esm/dates.js

@@ -1,11 +1,18 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 //namespace Pacem {
 const JSON_DATE_PATTERN = /^\/Date\([\d]+\)\/$/i;
+/** Date parsing and arithmetic utilities. */
 export 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') {
@@ -21,9 +28,19 @@ export 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];
     }
@@ -41,6 +58,13 @@ export 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) {
@@ -53,9 +77,21 @@ export 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 * 86400000);
     }
+    /**
+     * 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()) / 86400000;
     }

package/dist/esm/deepmerger.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -30,9 +30,18 @@ function deepMerge(target, source) {
     }
     return output;
 }
+/** Deep-merging utility for plain objects. */
 export class DeepMerger {
     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);

package/dist/esm/geom.js

@@ -1,11 +1,16 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 import { NullChecker } from "./null-checker";
 // 1.7763568394002505e-15 -20.4551920341394 40 40
 const FLOAT_PATTERN = /[-+]?([\d]+(\.[\d]+(e-[\d]+)?)?|[\d]*(\.[\d]+(e-[\d]+)?))/g;
+/**
+ * Extracts all the floating point numbers found in a string (e.g. `"10px 20px"` => `[10, 20]`).
+ * @param input String to parse.
+ * @returns Array of the numbers found, in order of appearance.
+ */
 export function parseAsNumericalArray(input) {
     const arr = [];
     let reg = input.match(FLOAT_PATTERN);
@@ -14,7 +19,12 @@ export function parseAsNumericalArray(input) {
     }
     return arr;
 }
+/** Angle-related utilities. */
 export 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'])
@@ -49,7 +59,14 @@ export class Angle {
     }
 }
 ;
+/** Size-related utilities. */
 export class Size {
+    /**
+     * 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) {
@@ -57,13 +74,24 @@ export class Size {
         }
         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';
     }
 }
+/** Point-related utilities. */
 export class Point {
+    /**
+     * 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) {
@@ -71,6 +99,10 @@ export class Point {
         }
         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'

package/dist/esm/history-svc.js

@@ -1,11 +1,15 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 // namespace Pacem {
 /** Grants undo/redo functionalities for given state. */
 export class HistoryService {
+    /**
+     * @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;
@@ -23,9 +27,11 @@ export class HistoryService {
     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;
     }
@@ -34,6 +40,7 @@ export class HistoryService {
     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;
@@ -41,6 +48,7 @@ export class HistoryService {
             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;
@@ -48,6 +56,11 @@ export class HistoryService {
             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);
@@ -57,6 +70,7 @@ export class HistoryService {
             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);

package/dist/esm/imaging.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -12,7 +12,13 @@ const DefaultImagingResizeOptions = {
     quality: 1,
     type: 'image/jpeg'
 };
+/** Image loading and resizing utilities, based on `OffscreenCanvas`. */
 export 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) {

package/dist/esm/index-compile-markdown.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/index-compile.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/index-iife.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/index.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/keygenerator.js

@@ -1,19 +1,33 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 // namespace Pacem {
+/** Unique key/id generation utilities. */
 export 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 {

package/dist/esm/matrix2d.js

@@ -1,26 +1,46 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 /// <reference path="geom.ts" />
 ;
+/** 2D affine matrix ([a b; c d] linear part, [e f] translation) manipulation utilities. */
 export 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 });
@@ -48,9 +68,18 @@ export 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) {
@@ -74,6 +103,12 @@ export 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);

package/dist/esm/null-checker.js

@@ -1,15 +1,26 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 /// <reference path="dates.ts" />
 import { Dates } from "./dates";
 // namespace Pacem {
+/** Null/empty value-checking utilities. */
 export 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)
@@ -21,6 +32,10 @@ export 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);
     }

package/dist/esm/number-extensions.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (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/esm/numbers.js

@@ -1,16 +1,35 @@
 /*!
- * @pacem/pacem-foundation v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-foundation v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 // namespace Pacem {
+/** Numeric utilities. */
 export class Numbers {
+    /**
+     * 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.0) {
         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);