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

package/dist/esm/adapter.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 { CustomTypedEvent } from './events';
+/** Dispatched by an {@link Iterative} container whenever its `index` changes. */
 export class CurrentIndexChangeEvent extends CustomTypedEvent {
     constructor(args) {
         super('currentindexchange', args);

package/dist/esm/command.js

@@ -1,12 +1,17 @@
 /*!
- * @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" />
 import { CustomTypedEvent } from './events';
 //namespace Pacem {
+/** Event name dispatched to signal a generic, named command invocation; see {@link CommandEvent}. */
 export const CommandEventName = 'command';
+/**
+ * Bubbling, cancelable event representing a generic UI command (e.g. a button's `command`/`command-argument`
+ * attributes), letting ancestor elements handle named actions without wiring a dedicated listener per command.
+ */
 export class CommandEvent extends CustomTypedEvent {
     constructor(args) {
         super(CommandEventName, args, { bubbles: true, cancelable: true });

package/dist/esm/comparers.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
  */

package/dist/esm/converters.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
  */
@@ -55,6 +55,11 @@ const RectPropertyConverter = {
     convert: (attr) => Rect.parse(attr),
     convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.width || 0} ${prop.height || 0}`
 };
+/**
+ * Built-in {@link PropertyConverter} implementations, keyed by the type they convert to/from. Passed as
+ * the `converter` option of a {@link Watch}-decorated property (e.g. `@Watch({ converter: PropertyConverters.Number })`)
+ * to control how that property's attribute string is parsed and, on change, reflected back.
+ */
 export const PropertyConverters /*: { [name: string]: PropertyConverter }*/ = {
     None: NonePropertyConverter,
     String: StringPropertyConverter,

package/dist/esm/decorators-next.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
  */

package/dist/esm/decorators.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
  */
@@ -133,6 +133,31 @@ function retrieveDescendantTemplateActivationPromises(host, root) {
     }
     return promises;
 }
+/**
+ * Class decorator that turns a class extending `HTMLElement` (typically {@link PacemEventTarget}) into a
+ * fully-fledged Pacem custom element: it registers the tag with the custom elements registry and wraps
+ * the standard `connectedCallback`/`disconnectedCallback`/`attributeChangedCallback`/`propertyChangedCallback`
+ * lifecycle hooks (calling through to any hooks already defined on the class) so that:
+ *
+ * - `observedAttributes` is computed automatically from the class's {@link Watch}-decorated properties
+ *   (in kebab-case), merged with any statically-declared `observedAttributes`.
+ * - On first connection, `config.template`/`config.templateUrl` (if provided) is fetched, parsed and
+ *   injected — into a Shadow Root when `config.shadow` is `true`, otherwise as light-DOM children,
+ *   splicing any pre-existing light-DOM content into a `<pacem-content>` placeholder if present.
+ * - Attribute changes are converted to property values via each watched property's {@link PropertyConverter},
+ *   and dispatched as an {@link AttributeChangeEvent}.
+ * - Property changes are dispatched as a {@link PropertyChangeEvent} (unless the property's `@Watch`
+ *   config sets `emit: false`) and, when `reflectBack` is enabled, written back onto the corresponding
+ *   attribute via the converter's `convertBack`.
+ * - Binding expression attributes (`{{ ... }}`) are parsed and kept live: dependent properties are
+ *   re-evaluated whenever one of the expression's upstream properties fires a {@link PropertyChangeEvent}.
+ * - Once the template (and all descendant templated custom elements) have finished rendering, the
+ *   `cloak` attribute is removed and `viewActivatedCallback` fires — this is the right place for logic
+ *   that depends on the element's full DOM (light or shadow) being in place.
+ *
+ * @param config Tag name, optional native `customElements.define` options, and optional template/templateUrl/shadow settings.
+ * @returns A class decorator to apply to the custom element's class declaration.
+ */
 export const CustomElement = (config) => {
     return (target) => {
         // might be already registered
@@ -471,6 +496,27 @@ export const CustomElement = (config) => {
 // #endregion
 // #region WATCH PROPERTIES
 const DefaultPropertyConverter = PropertyConverters.None;
+/**
+ * Property decorator that turns a plain class field (or accessor) into a Pacem "watched" property:
+ * a property whose changes are detected (via reference/value comparison, see {@link DefaultComparer}),
+ * optionally converted from/to its corresponding attribute string via a {@link PropertyConverter}
+ * (see {@link PropertyConverters}), and notified through `propertyChangedCallback` plus a
+ * {@link PropertyChangeEvent} (unless `config.emit` is `false`).
+ *
+ * Must be paired with the {@link CustomElement} class decorator, which is what actually reads the list
+ * of watched properties (via `WATCH_PROPS_VAR`) to compute `observedAttributes` and wire up attribute/
+ * property change plumbing — `@Watch` alone, on a class not decorated with `@CustomElement`, only sets
+ * up the getter/setter and change notification, with no attribute involvement.
+ *
+ * Array-valued properties are additionally instrumented: their mutating methods (`push`, `pop`, `splice`,
+ * `shift`, `unshift`, `copyWithin`) are patched so in-place mutations also trigger a change notification.
+ *
+ * @param config Optional behavior: `converter` (attribute↔property conversion, default `PropertyConverters.None`),
+ * `emit` (whether to dispatch a {@link PropertyChangeEvent}, default `true`), `debounce` (delay the
+ * change notification, either by a fixed number of milliseconds or `true` for one animation frame),
+ * and `reflectBack` (write the property value back onto the attribute on change, default `false`).
+ * @returns A property decorator to apply to the watched field/accessor.
+ */
 export function Watch(config) {
     return (target, prop, descriptor) => {
         var watchableProperties = GET_VAL(target.constructor, WATCH_PROPS_VAR, []);
@@ -591,6 +637,17 @@ export function Watch(config) {
         }
     };
 }
+/**
+ * Property decorator that turns a class field into a lazily-resolved, cached reference to a descendant
+ * element matching `selector`. Resolution happens on first read (via `shadowRoot.querySelectorAll` when
+ * available, falling back to the element itself), and only nodes whose `INSTANCE_HOST_VAR` points back
+ * at `this` are considered — this keeps the lookup scoped to the current element's own template output,
+ * skipping over descendants that belong to a nested custom element's own template. The cache is reset
+ * whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).
+ *
+ * @param selector CSS selector identifying the child element to bind to.
+ * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).
+ */
 export function ViewChild(selector) {
     return (target, prop, descriptor) => {
         const key = `${prop}_${Utils.uniqueCode()}`;
@@ -623,6 +680,15 @@ export function ViewChild(selector) {
 }
 // #endregion
 // #region CONCURRENT/DEBOUNCE EXECUTION
+/**
+ * Method decorator that serializes calls to an async (promise-returning) method on a per-instance basis:
+ * while an invocation is in flight, further calls are queued (their arguments buffered) instead of running
+ * concurrently, and each queued call gets its own promise that resolves/rejects once it eventually runs.
+ * Once the in-flight call settles, the oldest buffered call (if any) is dequeued and executed next.
+ * Methods that don't return a promise-like value are simply invoked synchronously with no queuing.
+ *
+ * @returns A method decorator to apply to an async instance method.
+ */
 export function Concurrent() {
     function isPromiseLike(obj) {
         return obj && typeof obj.then === 'function';
@@ -673,6 +739,15 @@ export function Concurrent() {
         };
     };
 }
+/**
+ * Method decorator that debounces calls to an instance method: repeated calls within the debounce window
+ * cancel the previously scheduled invocation and reschedule it, so only the last call in a rapid burst
+ * actually runs (with its own arguments), after the window elapses.
+ *
+ * @param msecs Debounce delay in milliseconds, or `true` to debounce to the next animation frame (`requestAnimationFrame`) instead of a fixed delay. Defaults to `50`.
+ * @param keyFactory Computes the per-instance timer key from the method name and call arguments; override to scope debouncing per argument (e.g. debounce separately per id) instead of per method. Defaults to a single shared key per method.
+ * @returns A method decorator to apply to the instance method to debounce.
+ */
 export function Debounce(msecs = 50, keyFactory = (key, ...args) => `pacem:debouncer:${key}`) {
     return function (target /* type, actually */, key, descriptor) {
         const originalMethod = descriptor.value;
@@ -698,6 +773,16 @@ export function Debounce(msecs = 50, keyFactory = (key, ...args) => `pacem:debou
         }
     };
 }
+/**
+ * Method decorator that throttles calls to an instance method: the first call in a window runs immediately;
+ * further calls arriving before the window elapses are not dropped but coalesced — only the most recent
+ * set of arguments is remembered and, once the window elapses, one trailing call runs with those arguments
+ * (mirroring a classic "leading + trailing" throttle).
+ *
+ * @param msecs Throttle window in milliseconds, or `true` to use a single animation frame (`requestAnimationFrame`) as the window. Defaults to `50`.
+ * @param keyFactory Computes the per-instance timer key from the method name and call arguments; override to scope throttling per argument instead of per method. Defaults to a single shared key per method.
+ * @returns A method decorator to apply to the instance method to throttle.
+ */
 export function Throttle(msecs = 50, keyFactory = (key, ...args) => `pacem:throttler:${key}`) {
     return function (target /* type, actually */, key, descriptor) {
         const originalMethod = descriptor.value;
@@ -747,6 +832,14 @@ class Transforms {
         }
     }
 }
+/**
+ * Method decorator that registers a static/instance method as a globally-named {@link TransformFunction},
+ * making it callable by name from template binding expressions (e.g. `{{ ^value | myTransform }}`).
+ * The registration is global (attached under `Utils.core`, dot-segmented by `name`), not per-instance.
+ *
+ * @param name Dot-separated registration path (e.g. `'strings.upper'`); segments before the last create/reuse nested namespaces under `Utils.core`. Defaults to the decorated method's own name when omitted.
+ * @returns A method decorator to apply to the transform function.
+ */
 export function Transformer(name) {
     return function (target, key, descriptor) {
         const method = descriptor.value;

package/dist/esm/defaults.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 {
+/** Framework-wide default settings. */
 export const Defaults = {
     USE_SHADOW_ROOT: /*'attachShadow' in Element.prototype &&*/ false /* <- wait until html-imports */
 };

package/dist/esm/events.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
  */
@@ -7,7 +7,17 @@
 import { Utils } from './utils';
 import { CustomEventUtils } from './utils-customevent';
 // namespace Pacem {
+/**
+ * Base class for framework custom events whose `detail` payload is strongly typed as `TDetail`.
+ * Thin wrapper around the native `CustomEvent<TDetail>` that also works around an old Edge bug
+ * (see {@link CustomEventUtils.fixEdgeCustomEventSubClassInstance}) affecting `CustomEvent` subclasses.
+ */
 export class CustomTypedEvent extends CustomEvent /* new in TypeScript v2.7.1 -> */ {
+    /**
+     * @param type Event name.
+     * @param detail Strongly-typed payload, exposed as `event.detail`.
+     * @param eventInit Standard `CustomEvent` initialization options (`bubbles`, `cancelable`, `composed`).
+     */
     constructor(type, detail, eventInit) {
         super(type, Utils.extend({ detail: detail }, eventInit || {}));
         CustomEventUtils.fixEdgeCustomEventSubClassInstance(this, this.constructor);
@@ -26,7 +36,20 @@ function isEventInit(obj) {
     return false;
 }
 // TODO: make inherit from CustomTypedEvent
+/**
+ * Base class for UI-originated custom events: like {@link CustomTypedEvent}, but additionally captures
+ * the mouse/touch/keyboard modifiers and coordinates of the originating native event (when supplied),
+ * exposing them through the {@link UIEventLike} surface (`which`, `altKey`, `pageX`, `clientY`, ...).
+ * Useful for events that are re-dispatched/synthesized (e.g. drag & drop) from an original pointer or
+ * keyboard event, so that consumers can still inspect that original event's modifiers/position.
+ */
 export class CustomUIEvent extends CustomEvent {
+    /**
+     * @param type Event name.
+     * @param detail Either the strongly-typed payload, or (when it satisfies `CustomEventInit`, i.e. has a `detail` key) the full event-init object.
+     * @param eventInit Either standard `CustomEvent` init options, or the original native event this custom event derives from (in which case its coordinates/modifiers get captured).
+     * @param orig The original native mouse/touch/keyboard event this custom event derives from, when `eventInit` is itself the init options.
+     */
     constructor(type, detail, eventInit, orig) {
         super(type, Utils.extend((isEventInit(detail || {}) ? detail : { detail: detail }), (!(eventInit instanceof Event) && eventInit) || {}));
         const originalEvent = orig || eventInit;
@@ -79,27 +102,44 @@ export class CustomUIEvent extends CustomEvent {
         return this.#coords?.screen.y;
     }
 }
+/** Event name dispatched whenever an observed attribute changes; see {@link AttributeChangeEvent}. */
 export const AttributeChangeEventName = 'attributechange';
+/**
+ * Dispatched by elements registered with the {@link CustomElement} decorator whenever one of their
+ * observed attributes changes, mirroring the native `attributeChangedCallback` as a DOM event.
+ */
 export class AttributeChangeEvent extends CustomTypedEvent {
     constructor(args) {
         super(AttributeChangeEventName, args);
     }
 }
+/** Event name dispatched whenever a `@Watch`-decorated property changes value; see {@link PropertyChangeEvent}. */
 export const PropertyChangeEventName = 'propertychange';
+/**
+ * Dispatched whenever a property decorated with {@link Watch} changes value (unless that decorator's
+ * `emit` option is set to `false`). This is the mechanism data-bound expressions listen to in order to
+ * re-evaluate themselves when one of their dependencies changes.
+ */
 export class PropertyChangeEvent extends CustomTypedEvent {
     constructor(args) {
         super(PropertyChangeEventName, args);
     }
 }
 // #region NAVIGATING
+/** Event name dispatched by a router *before* a navigation is committed; see {@link RouterNavigatingEvent}. Cancelable: calling `preventDefault()` aborts the navigation. */
 export const RouterNavigatingEventName = 'navigating';
+/** Event name dispatched by a router *after* a navigation has been committed; see {@link RouterNavigateEvent}. */
 export const RouterNavigateEventName = 'navigate';
+/** Dispatched by a router once it has navigated to a new `path` (not cancelable — the navigation already happened). */
 export class RouterNavigateEvent extends CustomTypedEvent {
+    /** @param path Either the destination path alone, or the full navigation args (path, title, referrer). */
     constructor(path) {
         super(RouterNavigateEventName, typeof path === 'string' ? { path } : path, { cancelable: false, bubbles: false });
     }
 }
+/** Dispatched by a router right before navigating to `path`; cancelable, so a listener can call `preventDefault()` to abort the navigation. */
 export class RouterNavigatingEvent extends CustomTypedEvent {
+    /** @param path Destination path about to be navigated to. */
     constructor(path) {
         super(RouterNavigatingEventName, path, { cancelable: true, bubbles: false });
     }

package/dist/esm/eventtarget.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
  */
@@ -20,6 +20,16 @@ import { CustomElementUtils } from './utils-customelement';
 import { Watch } from './decorators';
 import { PropertyConverters } from './converters';
 //namespace Pacem.Components {
+/**
+ * Base class for (almost) every Pacem custom element. Extends `HTMLElement` with the framework's
+ * common lifecycle/event plumbing: `on-{event-type}` attribute handlers (see {@link emit}), a
+ * {@link disabled} property that suppresses both outgoing (`dispatchEvent`) and incoming
+ * (`emitHandler`) events, an optional {@link logger} sink, and an {@link isReady} flag toggled once
+ * `viewActivatedCallback` has fired (see the {@link CustomElement} decorator for when that happens).
+ * Concrete elements are expected to be decorated with `@CustomElement` and typically override
+ * `propertyChangedCallback`/`viewActivatedCallback`/`connectedCallback`/`disconnectedCallback`,
+ * calling `super.xxxCallback()` first/last as documented on each.
+ */
 export class PacemEventTarget extends HTMLElement {
     constructor() {
         super();

package/dist/esm/expression.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
  */
@@ -45,32 +45,53 @@ const variablePattern = /(^|[\s\(\[\+\-\*\/!])(:host\.|\^+item[\s\.,;\)\]]|\^+it
 // * ...
 // */
 //const purePropertyPathPattern = /^[\w\.\$]+/; 
+/**
+ * A parsed, compiled binding expression (the content of a `{{ ... }}` attribute value). Parsing
+ * (see {@link parse}) rewrites special tokens found in the source text - `:host.`, `^item`/`^^item`/...,
+ * `^index`/`^^index`/..., `#id`, `::hostProp` - into references resolvable at evaluation time, and
+ * records each of them as a {@link PropertyDependency} so the owning element can be notified (via
+ * {@link PropertyChangeEvent}) and re-evaluate the expression whenever a dependency changes - this is
+ * what powers the two-way/live data binding wired up by the {@link CustomElement} decorator.
+ * Expressions with no dependencies are flagged `independent` (effectively a constant) and can be
+ * evaluated immediately without waiting for the DOM/scope to be ready.
+ */
 export class Expression {
     constructor() {
         this._pending = false;
         this._independent = false;
     }
+    /** The resolved property dependencies (element + property + path) this expression re-evaluates on change. Empty for {@link independent} expressions. */
     get dependencies() {
         return this._dependencies;
     }
+    /** The compiled function body used by {@link evaluate}/{@link evaluateAsync} (a `return <expr>;` statement, guarded by a try/catch). */
     get functionBody() {
         return this._fnBody;
     }
+    /** The compiled function body used by {@link evaluatePlus} (a bare, non-`return`ing statement, guarded by a try/catch) - suited for expressions run for their side effects, e.g. `on-*` event handlers. */
     get voidBody() {
         return this._voidBody;
     }
+    /**
+     * `true` when this expression couldn't be resolved against a scope yet (the element wasn't connected
+     * to a document/shadow-root at parse time) - a shared, inert placeholder singleton returned by
+     * {@link parse} in that case; evaluating it is a no-op. Callers should re-parse once the element is ready.
+     */
     get pending() {
         return this._pending;
     }
+    /** `true` when the expression has no dependencies (a constant) and can be evaluated immediately, without a resolved scope. */
     get independent() {
         return this._independent;
     }
+    /** Evaluates the expression and returns its result, swallowing any runtime error (returning `undefined`). */
     evaluate() {
         if (!this._fn) {
             this._fn = new Function('$pacem', CONTEXT_PREFIX, this._fnBody);
         }
         return this._fn.apply(null, [Utils.core, this._args]);
     }
+    /** Promise-wrapped variant of {@link evaluate} (resolves synchronously with the same result - kept for call-site uniformity with genuinely async evaluation paths). */
     evaluateAsync() {
         const deferred = DeferPromise.defer();
         if (!this._fn) {
@@ -79,6 +100,12 @@ export class Expression {
         deferred.resolve(this._fn.apply(null, [Utils.core, this._args]));
         return deferred.promise;
     }
+    /**
+     * Executes the expression for its side effects (using {@link voidBody}, so no value is returned),
+     * with extra named variables merged into scope alongside the expression's own dependencies -
+     * used to expose e.g. `$event` to `on-*` event handler expressions.
+     * @param args Extra name/value pairs made available to the expression, in addition to its resolved dependencies.
+     */
     evaluatePlus(args = {}) {
         if (!this._fn) {
             let argNames = [CONTEXT_PREFIX];
@@ -103,6 +130,15 @@ export class Expression {
         }
         return Expression._pendingExpression;
     }
+    /**
+     * Parses a binding expression's source text (the bare content of a `{{ ... }}` attribute, without the
+     * delimiters - see {@link CustomElementUtils.extractBindingAttributeExpression}) into an {@link Expression},
+     * resolving its special tokens against `element`'s scope (see {@link CustomElementUtils.findScopeContext}).
+     * Throws if the expression matches the unsafe-code guard (`new`, `window.`, `document.`, `eval(`).
+     * @param expression Bare expression source text.
+     * @param element Element the expression is bound to; provides the scope special tokens (`:host.`, `#id`, `^item`, ...) resolve against.
+     * @returns A constant expression if it has no dependencies; a shared pending placeholder if `element` isn't attached to a scope yet; otherwise a fully resolved expression.
+     */
     static parse(expression, element) {
         var context = CustomElementUtils.findScopeContext(element);
         var args = { '$this': element };

package/dist/esm/index-animations.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
  */

package/dist/esm/index-behaviors.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
  */

package/dist/esm/index-components.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
  */

package/dist/esm/index-iife.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
  */

package/dist/esm/index-logging.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
  */

package/dist/esm/index-net.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
  */

package/dist/esm/index-root.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
  */

package/dist/esm/index-ui.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
  */

package/dist/esm/index.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
  */

package/dist/esm/logger.js

@@ -1,16 +1,23 @@
 /*!
- * @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.Logging {
+/** Severity levels accepted by {@link Logger.log}, and used by {@link PacemEventTarget.log}. */
 export var LogLevel;
 (function (LogLevel) {
+    /** Fine-grained diagnostic detail. */
     LogLevel["Trace"] = "trace";
+    /** Development-time diagnostic detail. */
     LogLevel["Debug"] = "debug";
+    /** Recoverable but noteworthy condition. */
     LogLevel["Warn"] = "warn";
+    /** Unrecoverable or unexpected failure. */
     LogLevel["Error"] = "error";
+    /** General informational message. */
     LogLevel["Info"] = "info";
+    /** Generic/default-severity message. */
     LogLevel["Log"] = "log";
 })(LogLevel || (LogLevel = {}));
 //}

package/dist/esm/prefix.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
  */
@@ -7,5 +7,6 @@
 var root;
 /** the overall customelement prefix */
 export const P = (root = window['Pacem'])?.Configuration?.prefix ?? 'pacem';
+/** The prefix used for CSS custom properties and classes (e.g. `--{PCSS}-font-main`); configurable independently of the element tag prefix {@link P} via `window.Pacem.Configuration.css`, defaults to {@link P}. */
 export const PCSS = root?.Configuration?.css ?? P;
 //}

package/dist/esm/promise.js

@@ -1,9 +1,15 @@
 /*!
- * @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 {
+/**
+ * A `PromiseLike<T>` whose resolution is externalized: unlike a plain `Promise`, the executor isn't
+ * passed a callback up front - instead, `resolve`/`reject` are exposed for the caller to invoke later,
+ * via the {@link defer} static factory. Useful when the completion of an operation is driven by code
+ * that doesn't naturally live inside a `Promise` executor (e.g. event callbacks, decorator plumbing).
+ */
 export class DeferPromise {
     constructor() {
         this.deferred = null;
@@ -12,6 +18,7 @@ export class DeferPromise {
             me.deferred = { 'resolve': resolve, 'reject': reject, 'promise': me };
         });
     }
+    /** Standard `PromiseLike.then`, delegating to the underlying native `Promise`. */
     then(onCompleted, onFailed) {
         return this.promise.then(onCompleted, onFailed);
     }
@@ -23,14 +30,17 @@ export class DeferPromise {
         this.promise.then(callback, callback);
         return this;
     }
+    /** Registers a fulfillment-only callback (fluent, chainable alternative to `then(callback)`). */
     success(callback) {
         this.promise.then(callback, null);
         return this;
     }
+    /** Registers a rejection-only callback (fluent, chainable alternative to `then(null, callback)`). */
     error(callback) {
         this.promise.then(null, callback);
         return this;
     }
+    /** Creates a new deferred promise and returns its controller: `{ resolve, reject, promise }`. */
     static defer() {
         var q = new DeferPromise();
         return q.deferred;

package/dist/esm/regex.js

@@ -1,10 +1,12 @@
 /*!
- * @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.RegularExpressions {
+/** A pattern that can never match any string (`/a^/`); useful as a safe no-op default for optional matcher parameters. */
 export const EMPTY_MATCHER = /a^/;
+/** Static regular-expression helpers. */
 export class Regex {
     /**
      * Splits an input string into segments based on a matching pattern.

package/dist/esm/storage.js

@@ -1,11 +1,17 @@
 /*!
- * @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';
 //namespace Pacem {
 const EXPIRATION_FIELD = '_exp';
+/**
+ * JSON-serializing wrapper around `sessionStorage`/`localStorage` that transparently supports per-key
+ * expiration: values stored with a `duration` are stamped with an expiry timestamp and evicted lazily
+ * (checked on the next {@link getPropertyValue} call for that key, not via a timer). Session storage and
+ * local storage are treated as a single logical namespace - storing a key in one clears any same-named entry in the other.
+ */
 export class Storage {
     _getStorage(persistent) {
         return !!persistent ? window.localStorage : window.sessionStorage;
@@ -40,10 +46,16 @@ export class Storage {
         storage = this._getStorage(!persistent);
         storage.removeItem(name);
     }
+    /**
+     * Retrieves a previously stored value by `name`, checking session storage first, then local storage.
+     * Returns `null` if not found, or if found but past its expiration.
+     * @param name The unique key.
+     */
     getPropertyValue(name) {
         return this._parseValue(this._getStorage(false), name)
             || this._parseValue(this._getStorage(true), name);
     }
+    /** Clears both session and local storage entirely. */
     clear() {
         var storage = this._getStorage(true);
         storage.clear();
@@ -51,6 +63,7 @@ export class Storage {
         storage.clear();
     }
     ;
+    /** Removes a single entry by `name` from both session and local storage. */
     removeProperty(name) {
         var storage = this._getStorage(true);
         storage.removeItem(name);