@pacem/pacem-ui 2.0.0-kepler → 2.0.0-lyapunov

package/dist/esm/view.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-ui v2.0.0-kepler (https://js.pacem.it)
+ * @pacem/pacem-ui v2.0.0-lyapunov (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -67,9 +67,95 @@ let PacemViewElement = class PacemViewElement extends PacemEventTarget {
             this._manageRef();
         }
     }
+    disconnectedCallback() {
+        this._dispose(this.url);
+        super.disconnectedCallback();
+    }
     _isReference(url) {
         return url instanceof HTMLElement || (typeof url === 'string' && url.trim().startsWith('#'));
     }
+    /**
+     * Resolves a reference source to its element, as {@link _manageRef} does: the element itself, or the
+     * `<template>` a `#id` string points to; `null` for anything else.
+     */
+    _resolveRef(source) {
+        if (source instanceof HTMLElement) {
+            return source;
+        }
+        if (typeof source !== 'string' || !this._isReference(source)) {
+            return null;
+        }
+        return document.querySelector('template' + source);
+    }
+    /**
+     * Whether `url` is the source of the initial content ({@link initialContentUrl}): urls match by their string,
+     * references by the element they resolve to. Any other source consumes it.
+     */
+    _isInitialContent(url) {
+        const initial = this.initialContentUrl;
+        if (Utils.isNull(initial)) {
+            return false;
+        }
+        let matches = false;
+        if (!this._isReference(url)) {
+            matches = typeof url === 'string' && url === initial;
+        }
+        else if (this._isReference(initial)) {
+            const target = this._resolveRef(url);
+            matches = !Utils.isNull(target) && target === this._resolveRef(initial);
+        }
+        if (!matches) {
+            this.initialContentUrl = null;
+        }
+        return matches;
+    }
+    /**
+     * Keeps the initial content: announced once, as a fresh content would be (a reference may be managed twice on
+     * activation: the second time, it was announced already).
+     */
+    _adoptInitialContent() {
+        clearTimeout(this._fetchHandle);
+        if (this.#renderVersion > 0) {
+            return;
+        }
+        this._render(null);
+    }
+    /**
+     * The rendering pipeline of every content: a new version, `prerender`, the content on the next frame, `render`
+     * (dropped when newer content came meanwhile).
+     * @param fill Writes the new content (the former one is cleared first); `null` keeps the content already there
+     * (the initial content), which also leaves {@link initialContentUrl} in place.
+     * @param waitForAnimation Whether `render` waits for the view's css transition (see `fetching`) instead of
+     * following the content right away.
+     */
+    _render(fill, waitForAnimation = false) {
+        cancelAnimationFrame(this._renderHandle);
+        const version = ++this.#renderVersion;
+        const replacing = !Utils.isNull(fill);
+        if (replacing) {
+            this.initialContentUrl = null;
+            // this way, `this._container.innerHTML = ''` instruction will eventually let the page "scroll up"...
+            this.innerHTML = '';
+        }
+        this._dispatchPrerender();
+        this._renderHandle = requestAnimationFrame(() => {
+            if (replacing) {
+                fill();
+            }
+            if (!waitForAnimation) {
+                this._dispatchRenderOf(version);
+                return;
+            }
+            Utils.addAnimationEndCallback(this, () => this._dispatchRenderOf(version), ANIM_TIMEOUT);
+        });
+    }
+    /** Dispatches `render` for the content of `version`, unless newer content superseded it. */
+    _dispatchRenderOf(version) {
+        if (version !== this.#renderVersion) {
+            return;
+        }
+        this._dispatchRender();
+    }
     _dispose(url) {
         if (url instanceof Components.PacemTemplateProxyElement) {
             url.removeEventListener('templatechange', this._templateChangeHandler);
@@ -80,26 +166,37 @@ let PacemViewElement = class PacemViewElement extends PacemEventTarget {
             return;
         }
         const debounce = this.debounce || 0, url = this.url;
-        ;
         if (this._isReference(url)) {
             // <template>-based
             clearTimeout(this._fetchHandle);
             this._fetchHandle = setTimeout((() => this._manageRef()), debounce);
         }
         else if (typeof url === 'string' && !Utils.isNullOrEmpty(url)) {
-            // url-based
+            // url-based (but the initial content: already there)
+            if (this._isInitialContent(url)) {
+                this._adoptInitialContent();
+                return;
+            }
             this.fetching = true;
             clearTimeout(this._fetchHandle);
             this._fetchHandle = setTimeout((() => this._manageUrl(url)), debounce);
         }
         else /* might be a reset */ {
             this.innerHTML = '';
+            this.initialContentUrl = null;
         }
     }
     _manageRef() {
-        const url = this.url, tmpl = url instanceof HTMLElement ? url : document.querySelector('template' + url);
+        const url = this.url, tmpl = this._resolveRef(url);
+        // (a proxy keeps notifying its template changes, the initial content too: listening twice is a no-op)
         if (tmpl instanceof Components.PacemTemplateProxyElement) {
             tmpl.addEventListener('templatechange', this._templateChangeHandler, false);
+        }
+        if (this._isInitialContent(url)) {
+            this._adoptInitialContent();
+            return;
+        }
+        if (tmpl instanceof Components.PacemTemplateProxyElement) {
             this._setTmpl(tmpl.target);
         }
         else if (tmpl instanceof HTMLTemplateElement) {
@@ -113,18 +210,13 @@ let PacemViewElement = class PacemViewElement extends PacemEventTarget {
         }
     }
     _setTmpl(tmpl) {
-        cancelAnimationFrame(this._renderHandle);
-        this.#renderVersion++;
-        // this way, `this._container.innerHTML = ''` instruction will eventually let the page "scroll up"...
-        this.innerHTML = '';
-        this._dispatchPrerender();
-        this._renderHandle = requestAnimationFrame(() => {
-            if (Utils.isNull(tmpl)) {
-                this.log(Logging.LogLevel.Error, `Template element not found.`);
-                return;
-            }
-            this.appendChild(tmpl.cloneNode(true).content);
-            this._dispatchRender();
+        if (Utils.isNull(tmpl)) {
+            this.log(Logging.LogLevel.Error, `Template element not found.`);
+            return;
+        }
+        this._render(() => {
+            const clone = tmpl.cloneNode(true);
+            this.appendChild(clone.content);
         });
     }
     #aborter;
@@ -185,25 +277,15 @@ let PacemViewElement = class PacemViewElement extends PacemEventTarget {
         });
     }
     _manageResult(result) {
-        // this way, `this._container.innerHTML = ''` instruction will eventually let the page "scroll up"...
-        cancelAnimationFrame(this._renderHandle);
-        const version = ++this.#renderVersion;
         this.scrollTo({ top: 0, left: 0, behavior: 'instant' });
-        this.innerHTML = '';
-        this._dispatchPrerender();
-        this._renderHandle = requestAnimationFrame(() => {
+        // setting fetching to `false` triggers a css class change that could/should cause a css transition to happen:
+        // `render` waits for it
+        // TODO: manage to switch to native in a near future (https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API or https://youtu.be/oDcb3fvtETs)
+        this._render(() => {
             this.innerHTML = result;
             this.fetching = false;
             this.progress = Number.NaN;
-            // setting fetching to `false` triggers a css class change that could/should cause a css transition to happen
-            // TODO: manage to switch to native in a near future (https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API or https://youtu.be/oDcb3fvtETs)
-            Utils.addAnimationEndCallback(this, () => {
-                if (version !== this.#renderVersion) {
-                    return;
-                }
-                this._dispatchRender();
-            }, ANIM_TIMEOUT);
-        });
+        }, true);
     }
     #resizeHandle;
     _dispatchRender() {
@@ -240,6 +322,9 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: PropertyConverters.Number })
 ], PacemViewElement.prototype, "debounce", void 0);
+__decorate([
+    Watch({ emit: false, converter: ElementOrStringPropertyConverter })
+], PacemViewElement.prototype, "initialContentUrl", void 0);
 PacemViewElement = __decorate([
     CustomElement({
         tagName: P + '-view'

package/dist/esm/window.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-ui v2.0.0-kepler (https://js.pacem.it)
+ * @pacem/pacem-ui v2.0.0-lyapunov (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/package.json

@@ -25,7 +25,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "2.0.0-kepler",
+  "version": "2.0.0-lyapunov",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"

package/typings/index.d.ts

@@ -1279,11 +1279,44 @@ declare class PacemViewElement extends PacemEventTarget {
     followRedirects: boolean;
     /** use it to ensure animation */
     debounce: number;
+    /**
+     * Gets or sets the source (same shapes as {@link url}) of the content the view starts with, i.e. already in its
+     * markup (e.g. server-rendered): the first `url` matching it is not loaded, the content is kept and announced with
+     * the usual `prerender`/`render` events. One-shot: consumed by any other source or by any rendering.
+     */
+    initialContentUrl: string | HTMLTemplateElement | Components_2.PacemTemplateProxyElement;
     private _fetchHandle;
     private _renderHandle;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
+    disconnectedCallback(): void;
     private _isReference;
+    /**
+     * Resolves a reference source to its element, as {@link _manageRef} does: the element itself, or the
+     * `<template>` a `#id` string points to; `null` for anything else.
+     */
+    private _resolveRef;
+    /**
+     * Whether `url` is the source of the initial content ({@link initialContentUrl}): urls match by their string,
+     * references by the element they resolve to. Any other source consumes it.
+     */
+    private _isInitialContent;
+    /**
+     * Keeps the initial content: announced once, as a fresh content would be (a reference may be managed twice on
+     * activation: the second time, it was announced already).
+     */
+    private _adoptInitialContent;
+    /**
+     * The rendering pipeline of every content: a new version, `prerender`, the content on the next frame, `render`
+     * (dropped when newer content came meanwhile).
+     * @param fill Writes the new content (the former one is cleared first); `null` keeps the content already there
+     * (the initial content), which also leaves {@link initialContentUrl} in place.
+     * @param waitForAnimation Whether `render` waits for the view's css transition (see `fetching`) instead of
+     * following the content right away.
+     */
+    private _render;
+    /** Dispatches `render` for the content of `version`, unless newer content superseded it. */
+    private _dispatchRenderOf;
     private _templateChangeHandler;
     private _dispose;
     private _manage;