@pacem/pacem-core 2.0.0-goldbach → 2.0.0-hadamard

package/typings/index.d.ts

@@ -1375,7 +1375,11 @@ declare class PacemBodyProxyElement extends PacemTransferProxyElement {
     protected get proxy(): HTMLElement;
 }
 
-/** Wraps a {@link BroadcastChannel}, sending/receiving messages to/from other same-origin browsing contexts. */
+/**
+ * Wraps a {@link BroadcastChannel}, sending/receiving messages to/from other same-origin browsing contexts.
+ * @fires receive {@link CustomEvent} - when a message arrives from another channel of the same name: `detail` is the message (also in `result`).
+ * @fires error {@link CustomEvent} - when an arrived message couldn't be deserialized.
+ */
 declare class PacemBroadcastChannelProxyElement extends PacemEventTarget {
     #private;
     /** Gets or sets the message to be sent through the channel. */
@@ -1465,21 +1469,40 @@ declare abstract class PacemCrossItemsContainerElement<TItem extends PacemItemEl
     unregister(item: TItem): boolean;
 }
 
-/** Holds an arbitrary data model, optionally persisting it to local storage and debouncing/throttling change notifications. */
+/**
+ * Holds an arbitrary data model, optionally persisting it to local storage and debouncing/throttling change notifications.
+ * @fires propertychange {@link PropertyChangeEvent} - when `model` changes (debounced or throttled as set by `debounce` and `throttle`).
+ */
 declare class PacemDataElement extends PacemEventTarget {
     private storage;
     constructor(storage?: Storage_2);
-    /** Gets or sets the data model held by this element. */
+    /** Gets or sets the data model held by this element. As an attribute, it gets evaluated as a JavaScript expression (`"0"`, `"[1, 2]"`, `"{ a: 1 }"`). */
     model: any;
-    /** Gets or sets the storage key under which `model` is persisted. */
+    /** Gets or sets the storage key under which `model` is persisted (local storage): restored on load, removed when the key changes. */
     persistAs: string;
-    /** Debounces the model change */
-    debounce: number;
-    /** Throttles the model change if debounce is > 0 */
+    /**
+     * Gets or sets how the model change notifications get debounced: a number of milliseconds, `true` (once per
+     * animation frame), or `false`/`0` (right away, the default).
+     */
+    debounce: number | boolean;
+    /** Gets or sets whether the notifications get throttled rather than debounced (the first change of each `debounce` window is notified, the others are dropped). */
     throttle: boolean;
-    private _handle;
-    private _flag;
+    /** Cancels the pending (debounced) notification, if any. */
+    private _cancelPending;
+    /** Whether a throttling window is open (changes are dropped meanwhile). */
+    private _throttling;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Notifies a model change: right away, debounced or throttled (see {@link debounce} and {@link throttle}). */
+    private _notifyModelChange;
+    /** Notifies the first change of a window, and drops the others until the window closes. */
+    private _throttle;
+    /**
+     * Runs a callback on the next animation frame, or after a delay.
+     * @returns A function cancelling it.
+     */
+    private _schedule;
+    /** Persists the model under {@link persistAs}, if set (a `null` model removes it). */
+    private _persist;
 }
 
 /** @deprecated */
@@ -1502,6 +1525,13 @@ declare class PacemDockElement extends PacemEventTarget {
 /**
  * Pacem Drag & Drop element adapter: implements {@link DragDropper} on top of {@link PacemBehavior} to make
  * registered elements draggable and, optionally, sortable/droppable onto {@link dropTargets}.
+ * @fires draginit {@link DragDropEvent} - on press, before anything moves: cancelable (`preventDefault()` refuses the drag).
+ * @fires dragstart {@link DragDropEvent} - when the drag actually starts (the press lasted `lockTimeout`).
+ * @fires drag {@link DragDropEvent} - on every move: cancelable.
+ * @fires dragover {@link DragDropEvent} - when hovering one of the `dropTargets`: cancelable (`preventDefault()` refuses that target).
+ * @fires dragout {@link DragDropEvent} - when leaving a drop target.
+ * @fires drop {@link DragDropEvent} - on release over a drop target: `detail.target` is the target, `detail.element` the dragged element.
+ * @fires dragend {@link DragDropEvent} - when it's all over (dropped or not).
  */
 declare class PacemDragDropElement extends PacemBehavior implements DragDropper {
     private _startHandler;
@@ -1575,7 +1605,10 @@ declare class PacemElementProxyElement extends PacemTransferProxyElement {
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
-/** Listens for an arbitrary DOM event on a `target` element (or `window`) and re-dispatches it as its own `emit` event. */
+/**
+ * Listens for an arbitrary DOM event on a `target` element (or `window`) and re-dispatches it as its own `emit` event.
+ * @fires emit {@link Event} - for every `event` caught on `target`: the caught one is `originalEvent`.
+ */
 declare class PacemEventProxyElement extends PacemEventTarget {
     /** Gets or sets the element (or `window`, via the special `"$window"` value) to listen on. */
     target: HTMLElement | Window;
@@ -1652,7 +1685,12 @@ export declare abstract class PacemEventTarget extends HTMLElement implements No
     protected refreshBindings(): void;
 }
 
-/** Declarative wrapper around the `fetch()` API, debouncing/aborting requests as its properties change and exposing the parsed `result`. */
+/**
+ * Declarative wrapper around the `fetch()` API, debouncing/aborting requests as its properties change and exposing the parsed `result`.
+ * @fires success {@link CustomEvent} - when a response is OK (2xx), before its body gets parsed: `detail` is the `Response`.
+ * @fires fetchresult {@link CustomEvent} - when the body got parsed (as set by `as`): `detail` is the new `result`.
+ * @fires error {@link CustomEvent} - when a response is not OK: `detail` is the `Response` (network failures reject `fetch()` instead).
+ */
 declare class PacemFetchElement extends PacemEventTarget implements Fetcher {
     #private;
     /** Gets or sets the request URL, optionally templated (e.g. `/api/{id}`) against `parameters`. */
@@ -1683,7 +1721,7 @@ declare class PacemFetchElement extends PacemEventTarget implements Fetcher {
     type: 'json' | 'raw';
     /** Gets or sets the debounce delay (in milliseconds) applied before auto-triggered fetches (default `100`). */
     debounce: number;
-    /** Gets or sets whether to throttle (rather than debounce) auto-triggered fetches. */
+    /** Gets or sets whether a fetch requested while another one is in flight is skipped (it gets the ongoing request) rather than aborting it (default false). */
     throttle: boolean;
     /** Gets or sets whether to compare parameter and header single values prior to trigger a new fetch execution (default false). */
     diffByValues: boolean;
@@ -1699,7 +1737,13 @@ declare class PacemFetchElement extends PacemEventTarget implements Fetcher {
     private _acceptFetchResult;
 }
 
-/** Keeps track of an undo/redo-capable history of an arbitrary state. */
+/**
+ * Keeps track of an undo/redo-capable history of an arbitrary state.
+ * @fires push {@link StateEvent} - when a new state got recorded: `detail` has `state`, `canUndo` and `canRedo`.
+ * @fires undo {@link StateEvent} - after a step back.
+ * @fires redo {@link StateEvent} - after a step forward.
+ * @fires reset {@link StateEvent} - when the history got cleared (the current state stays).
+ */
 declare class PacemHistoryElement extends PacemEventTarget {
     #private;
     /** Gets or sets the current state; assigning a new value pushes it onto the history stack. */
@@ -1826,7 +1870,10 @@ declare class PacemNumberAnimationElement extends TweenAnimationElement<number>
     protected tweenInterpolationCallback(time: number, progress: number): number;
 }
 
-/** Tracks the browser's network connectivity (`navigator.onLine`), updating `online` on `online`/`offline` events. */
+/**
+ * Tracks the browser's network connectivity (`navigator.onLine`), updating `online` on `online`/`offline` events.
+ * @fires propertychange {@link PropertyChangeEvent} - when `online` changes (the connection dropped or came back).
+ */
 declare class PacemOnlineStatusElement extends PacemEventTarget {
     /** @readonly Gets whether the browser currently reports itself as online. */
     online: boolean;
@@ -1852,6 +1899,10 @@ declare class PacemPointAnimationElement extends TweenAnimationElement<Point> {
 
 /**
  * Repeats its `<template>` content once per `datasource` item, keeping the rendered items in sync as the datasource changes.
+ * @fires repeateritemcreate {@link RepeaterItemCreateEvent} - when an item got rendered (and is in the DOM): `detail` has its `index`, `item` and `dom`.
+ * @fires repeateritemremove {@link RepeaterItemRemoveEvent} - when an item got removed (the datasource shrank).
+ * @fires itemcommand {@link CustomEvent} - when an element of an item dispatches a command (e.g. a `<pacem-button command-name>`): `detail` has `commandName` and `commandArgument`.
+ * @fires item{command} {@link CustomEvent} - right after `itemcommand`, named after the command (e.g. `itemdelete` for `command-name="delete"`): `detail` is the `commandArgument`.
  * @example
  * <pacem-repeater datasource="[{id:'first', items:['a','b','c']}, ...]">
  * <ol>
@@ -1894,6 +1945,11 @@ declare class PacemRepeaterElement extends PacemEventTarget implements Repeater
 /**
  * Pacem Rescale element adapter: implements {@link Rescaler} on top of {@link PacemBehavior}, decorating
  * registered elements with draggable resize handles (see {@link RescaleHandle}).
+ * A move beyond the size constraints (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`) is clamped to them; with
+ * `keepProportions`, such a move is ignored instead (clamping one side would break the ratio).
+ * @fires rescalestart {@link RescaleEvent} - when a handle gets grabbed: `detail.handle` tells which.
+ * @fires rescale {@link RescaleEvent} - on every move: `detail.targetRect` is the size about to be applied; cancelable (`preventDefault()` applies nothing, e.g. to apply it your way).
+ * @fires rescaleend {@link RescaleEvent} - when the handle gets released: `detail.targetRect` is the final size.
  */
 declare class PacemRescaleElement extends PacemBehavior implements Rescaler {
     /** Adds the resize-handle frame (see {@link RescaleHandle}) around the given element. */
@@ -1951,6 +2007,9 @@ declare class PacemResizeElement extends PacemEventTarget {
 /**
  * Pacem Rotate element adapter: implements {@link Rotator} on top of {@link PacemBehavior} to make
  * registered elements rotatable around a pivot point via mouse/touch drag.
+ * @fires rotatestart {@link RotateEvent} - on press: cancelable (`preventDefault()` refuses the gesture).
+ * @fires rotate {@link RotateEvent} - whenever the (stepped) angle changes: `detail.rotation`, in radians; cancelable (nothing gets rendered).
+ * @fires rotateend {@link RotateEvent} - on release: `detail.rotation` is the final angle.
  */
 declare class PacemRotateElement extends PacemBehavior implements Rotator {
     /** Wires up the `mousedown`/`touchstart` listeners that arm the rotate gesture on the given element. */
@@ -1968,7 +2027,12 @@ declare class PacemRotateElement extends PacemBehavior implements Rotator {
     private _startHandler;
 }
 
-/** Client-side router: parses/generates paths against a template and drives the browser History API. */
+/**
+ * Client-side router: parses/generates paths against a template and drives the browser History API.
+ * @fires propertychange {@link PropertyChangeEvent} - when `state` changes (every committed navigation).
+ * @fires navigating {@link RouterNavigatingEvent} - on `window`, right before a navigation: cancelable (`preventDefault()` aborts it), `detail` is the target path.
+ * @fires navigate {@link RouterNavigateEvent} - on `window`, once a navigation is committed: `detail` has `path`, `referrer` and `title`.
+ */
 declare class PacemRouterElement extends PacemEventTarget {
     #private;
     /** Gets or sets the route template, e.g. `/{controller}/{action}/{id?}`. */
@@ -2011,9 +2075,11 @@ declare class PacemRouterElement extends PacemEventTarget {
     private _parseState;
 }
 
-/** {@link PacemContentElement} variant that strips out `<script>` blocks (and, for `Node` content, `<script>` elements) before rendering `content`. */
+/**
+ * {@link PacemContentElement} variant that renders `content` without what could run script: `<script>` elements,
+ * `on*` event-handler attributes and `javascript:` URLs get removed (HTML strings are parsed, never executed, first).
+ */
 declare class PacemSafeContentElement extends PacemContentElement {
-    private _sanitizeLegacy;
     protected sanitize(html: string | Node): string | Node;
 }
 
@@ -2030,7 +2096,13 @@ declare class PacemScrollAwareElement extends PacemEventTarget {
     };
 }
 
-/** Registers a service worker and manages its (optional) Push API subscription. */
+/**
+ * Registers a service worker and manages its (optional) Push API subscription.
+ * @fires register {@link CustomEvent} - once the service worker got registered: `detail` is the `ServiceWorkerRegistration`.
+ * @fires unregister {@link CustomEvent} - when a previous registration got replaced: `detail` is the old one.
+ * @fires subscribe {@link CustomEvent} - when a push subscription is in place (found at start, or just made): `detail` is the `PushSubscription`.
+ * @fires unsubscribe {@link CustomEvent} - when the push subscription went away: `detail` is the old `PushSubscription`.
+ */
 declare class PacemServiceWorkerProxyElement extends PacemEventTarget {
     /** @readonly Gets the active service worker registration, once available. */
     registration: ServiceWorkerRegistration;
@@ -2053,6 +2125,8 @@ declare class PacemServiceWorkerProxyElement extends PacemEventTarget {
     /**
      * Subscribes to push notifications through the registered service worker.
      * @param publicKey VAPID public key (base64url or raw bytes); defaults to `publicKey`
+     * @returns The subscription (`null` without a push manager, or when notifications are denied); rejects when the
+     * browser refuses to subscribe (no push service, an invalid key…).
      */
     subscribe(publicKey?: string | Uint8Array<ArrayBuffer>): Promise<PushSubscription>;
 }
@@ -2062,7 +2136,10 @@ declare class PacemShellProxyElement extends PacemTransferProxyElement {
     protected get proxy(): HTMLElement;
 }
 
-/** Listens for a keyboard shortcut (optionally chorded, e.g. `"ctrl+k, s"`) on a target and fires an `execute` event when matched. */
+/**
+ * Listens for a keyboard shortcut (optionally chorded, e.g. `"ctrl+k, s"`) on a target and fires an `execute` event when matched.
+ * @fires execute {@link Event} - when the whole combination got typed (the matching key's default action is prevented).
+ */
 declare class PacemShortcutElement extends PacemEventTarget {
     /** Gets or sets the key combination to listen for (e.g. `"ctrl+s"`, or a comma-separated sequence like `"ctrl+k, s"`). */
     combination: string;
@@ -2132,6 +2209,11 @@ declare class PacemStyleProxyElement extends PacemEventTarget {
 /**
  * Pacem Swipe element adapter: implements {@link Swiper} on top of {@link PacemBehavior} to make
  * registered elements draggable along one axis, with snap points and fling/bounce-back detection.
+ * @fires pan {@link SwipeEvent} - while the element follows the pointer: cancelable.
+ * @fires swipe {@link SwipeEvent} - on release, once a swipe is detected (dragged past a snap, or flung): cancelable (stops the chain).
+ * @fires swipe{direction} {@link SwipeEvent} - right after `swipe`, named after the direction (`swipeleft`, `swiperight`, `swipeup`, `swipedown`): cancelable.
+ * @fires swipeanimationend {@link SwipeEvent} - when the element reached its snap: cancelable (`preventDefault()` keeps it there instead of returning).
+ * @fires swipe{direction}animationend {@link SwipeEvent} - right after `swipeanimationend`, named after the direction.
  */
 declare class PacemSwipeElement extends PacemBehavior implements Swiper {
     #private;
@@ -2247,7 +2329,11 @@ declare class PacemViewportAwareElement extends PacemEventTarget {
     disconnectedCallback(): void;
 }
 
-/** Wraps a {@link Worker}, sending/receiving messages to/from a web worker script. */
+/**
+ * Wraps a {@link Worker}, sending/receiving messages to/from a web worker script.
+ * @fires receive {@link CustomEvent} - when the worker posts a message back: `detail` is the message (also in `result`).
+ * @fires error {@link CustomEvent} - when the worker script fails: `detail` is the error, when the browser can pass it over.
+ */
 declare class PacemWebWorkerProxyElement extends PacemEventTarget {
     /** Gets or sets the message to be posted to the worker. */
     message: any;
@@ -2835,6 +2921,8 @@ declare type SwipeEventArgs = {
         position: Point;
     };
     vertical?: boolean;
+    /** The snap the element is going to rest at (known on release; `0` = back home). */
+    snap?: number;
 };
 
 /**
@@ -2857,6 +2945,12 @@ declare class SwipeEventArgsClass {
     get predictedDuration(): number;
     /** @readonly Gets the element being swiped. */
     get element(): HTMLElement | SVGElement;
+    /**
+     * @readonly Gets the snap the element is going to rest at, relative to where the gesture started: `0` means it
+     * bounces back home (the release didn't make it). Known on release (`swipe`, `swipe<direction>` and the
+     * animation-end events); `undefined` while panning.
+     */
+    get snap(): number | undefined;
     /** Builds a new {@link SwipeEventArgsClass} out of a plain {@link SwipeEventArgs} builder. */
     static fromArgs(builder: SwipeEventArgs): SwipeEventArgsClass;
 }