@pacem/pacem 1.0.0-bernoulli → 1.0.0-bessel

package/dist/typings/index.d.ts

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem v1.0.0-bessel (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -675,11 +675,6 @@ export declare namespace Components {
         ResizeEventArgs,
         ResizeEvent,
         PacemResizeElement,
-        RouterNavigatingEventName,
-        RouterNavigateEventName,
-        RouterNavigateEventArgs,
-        RouterNavigateEvent,
-        RouterNavigatingEvent,
         PacemRouterElement,
         ScrollEventName,
         ScrollEventArgs,
@@ -743,6 +738,7 @@ export declare namespace Components {
         PacemGalleryElement,
         PacemModalFormElement,
         PacemRouterHashStateElement,
+        PacemRouterViewScrollElement,
         PacemSearchElement,
         DataCellMetadataContentFactory,
         DataCellMetadataCssClassFactory,
@@ -7104,6 +7100,8 @@ declare class PacemRouterElement extends PacemEventTarget {
     template: string;
     state: RouterState;
     path: string;
+    /** Whether to restore the scroll position of a page visited via the back/forward buttons, and scroll newly-visited pages to top. Default `true`; set to `false` to fall back to the browser's own (native) scroll restoration. */
+    scrollRestoration: boolean;
     parseState(state?: {
         [key: string]: string;
     }): RouterState;
@@ -7115,6 +7113,7 @@ declare class PacemRouterElement extends PacemEventTarget {
     connectedCallback(): void;
     viewActivatedCallback(): void;
     disconnectedCallback(): void;
+    private _onScroll;
     private _onPopState;
     /**
      * Merged to provided state into the current one and returns the resulting path (including current querystring and hash).
@@ -7161,6 +7160,50 @@ declare class PacemRouterHashStateElement extends PacemEventTarget_2 {
     set(key: string, value: any): void;
 }
 
+/**
+ * Bridges a {@link Components.PacemRouterElement}'s persisted scroll position (`state.$scrollY`, populated
+ * when `PacemRouterElement.scrollRestoration` is enabled) with a {@link ComponentsUI.UI.PacemViewElement}'s
+ * content lifecycle: navigating to a new page starts at the top, navigating back restores where the user
+ * left off - without either the router or the view needing to know about the other.
+ *
+ * This listens to the *view*'s `prerender`/`render` events rather than the router's own navigation events,
+ * because `render` only fires once the view's content has stopped resizing (it's debounced against the
+ * view's own resize detection, not just "content was inserted"). That mitigates - though doesn't fully
+ * eliminate - restoring to a scrollTop the page isn't tall enough to reach yet (e.g. images or async
+ * content still loading in): content changes that don't affect the view's own box size won't retrigger it.
+ */
+declare class PacemRouterViewScrollElement extends PacemEventTarget_2 {
+    /** The {@link Components.PacemRouterElement} instance orchestrating the app's navigation; its `state.$scrollY` is what gets restored. */
+    router: Components_2.PacemRouterElement;
+    /** The {@link ComponentsUI.UI.PacemViewElement} whose `prerender`/`render` events drive when the scroll position gets reset/restored. */
+    view: Components_3.UI.PacemViewElement;
+    /**
+     * Whether to animate the restoring scroll (`'smooth'`) or jump directly to it (`'instant'`). Unset defaults
+     * to smooth (only an explicit `'instant'` disables the animation) - see `_renderHandler`. Only affects the
+     * *restore* on `render`; the reset-to-top on `prerender` is always instant, since there's nothing to animate
+     * from (the old content is already cleared).
+     */
+    scrollBehavior: 'instant' | 'smooth';
+    viewActivatedCallback(): void;
+    propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    disconnectedCallback(): void;
+    /** Turns on the router's own scroll-position bookkeeping (capturing `state.$scrollY` per history entry); see `PacemRouterElement.scrollRestoration`. */
+    private _setupRouter;
+    /** No-op: `_setupRouter` only flips a flag on the router, there's no subscription to tear down. Kept for symmetry with `_disposeView`, and in case this grows one later. */
+    private _disposeRouter;
+    private _setupView;
+    private _disposeView;
+    /** The old content is already gone and the new content hasn't landed yet - jump to the top now, instantly, so the transition never shows a scrolled-down blank/stale view. */
+    private _prerenderHandler;
+    /**
+     * New content has landed and its size has settled (see class remarks on `render`'s debounce). Restores the
+     * router's persisted scroll position for this entry, if any: `$scrollY` is `undefined` (or `0`) for a
+     * freshly-pushed page - never explicitly set on push, only captured when *leaving* a page - so this
+     * correctly leaves new pages at the top without any special-casing.
+     */
+    private _renderHandler;
+}
+
 declare class PacemSafeContentElement extends PacemContentElement {
     private _sanitizeLegacy;
     protected sanitize(html: string | Node): string | Node;
@@ -8065,7 +8108,9 @@ declare class PacemViewElement extends PacemEventTarget_2 {
     private _setTmpl;
     private _manageUrl;
     private _manageResult;
+    private _debounceDispatchHandler;
     private _dispatchRender;
+    private _dispatchPrerender;
 }
 
 /** @deprecated */
@@ -8872,23 +8917,23 @@ declare type RouteMetadata = {
     index: number;
 };
 
-declare class RouterNavigateEvent extends CustomTypedEvent<RouterNavigateEventArgs> {
+export declare class RouterNavigateEvent extends CustomTypedEvent<RouterNavigateEventArgs> {
     constructor(path: string | RouterNavigateEventArgs);
 }
 
-declare type RouterNavigateEventArgs = {
+export declare type RouterNavigateEventArgs = {
     path: string;
     title?: string;
     referrer?: string;
 };
 
-declare const RouterNavigateEventName = "navigate";
+export declare const RouterNavigateEventName = "navigate";
 
-declare class RouterNavigatingEvent extends CustomTypedEvent<string> {
+export declare class RouterNavigatingEvent extends CustomTypedEvent<string> {
     constructor(path: string);
 }
 
-declare const RouterNavigatingEventName = "navigating";
+export declare const RouterNavigatingEventName = "navigating";
 
 export declare type RouterState = {
     [key: string]: string;
@@ -8900,6 +8945,7 @@ export declare type RouterState = {
         [key: string]: string;
     };
     $hash?: string;
+    $scrollY?: number;
 };
 
 declare interface Rule {
@@ -9881,6 +9927,8 @@ export declare class Utils {
     static deserializeTransform(style: CSSStyleDeclaration): Matrix2D_2;
     static set scrollTop(y: number);
     static set scrollLeft(x: number);
+    static scrollTo(y: number, smooth?: boolean): void;
+    static scrollTo(x: number, y: number, smooth?: boolean): void;
     static get scrollTop(): number;
     static get scrollLeft(): number;
     static get windowSize(): {
@@ -10511,6 +10559,11 @@ declare global {
             Repeater,
             RepeaterItem,
             Rgba,
+            RouterNavigateEvent,
+            RouterNavigateEventArgs,
+            RouterNavigateEventName,
+            RouterNavigatingEvent,
+            RouterNavigatingEventName,
             RouterState,
             Scaffolding,
             Size,

package/dist/vscode.html-custom.json

@@ -3564,6 +3564,18 @@
         },
         {
           "name": "path"
+        },
+        {
+          "name": "scroll-restoration",
+          "description": "Whether to restore the scroll position of a page visited via the back/forward buttons, and scroll newly-visited pages to top. Default `true`; set to `false` to fall back to the browser's own (native) scroll restoration.",
+          "values": [
+            {
+              "name": "true"
+            },
+            {
+              "name": "false"
+            }
+          ]
         }
       ]
     },
@@ -3588,6 +3600,27 @@
         }
       ]
     },
+    {
+      "name": "pacem-router-view-scroll",
+      "description": {
+        "kind": "markdown",
+        "value": "**@pacem/pacem-plus**\n\nBridges a {@link Components.PacemRouterElement}'s persisted scroll position (`state.$scrollY`, populated when `PacemRouterElement.scrollRestoration` is enabled) with a {@link ComponentsUI.UI.PacemViewElement}'s content lifecycle: navigating to a new page starts at the top, navigating back restores where the user left off - without either the router or the view needing to know about the other. This listens to the *view*'s `prerender`/`render` events rather than the router's own navigation events, because `render` only fires once the view's content has stopped resizing (it's debounced against the view's own resize detection, not just \"content was inserted\"). That mitigates - though doesn't fully eliminate - restoring to a scrollTop the page isn't tall enough to reach yet (e.g. images or async content still loading in): content changes that don't affect the view's own box size won't retrigger it."
+      },
+      "attributes": [
+        {
+          "name": "router",
+          "description": "The {@link Components.PacemRouterElement} instance orchestrating the app's navigation; its `state.$scrollY` is what gets restored."
+        },
+        {
+          "name": "view",
+          "description": "The {@link Components.PacemRouterElement} instance orchestrating the app's navigation; its `state.$scrollY` is what gets restored. */ @Watch({ converter: PropertyConverters.Element, emit: false }) router: Components.PacemRouterElement; /** The {@link ComponentsUI.UI.PacemViewElement} whose `prerender`/`render` events drive when the scroll position gets reset/restored."
+        },
+        {
+          "name": "scroll-behavior",
+          "description": "The {@link Components.PacemRouterElement} instance orchestrating the app's navigation; its `state.$scrollY` is what gets restored. */ @Watch({ converter: PropertyConverters.Element, emit: false }) router: Components.PacemRouterElement; /** The {@link ComponentsUI.UI.PacemViewElement} whose `prerender`/`render` events drive when the scroll position gets reset/restored. */ @Watch({ converter: PropertyConverters.Element, emit: false }) view: ComponentsUI.UI.PacemViewElement; /** Whether to animate the restoring scroll (`'smooth'`) or jump directly to it (`'instant'`). Unset defaults to smooth (only an explicit `'instant'` disables the animation) - see `_renderHandler`. Only affects the *restore* on `render`; the reset-to-top on `prerender` is always instant, since there's nothing to animate from (the old content is already cleared)."
+        }
+      ]
+    },
     {
       "name": "pacem-schedule",
       "description": {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-bernoulli",
+  "version": "1.0.0-bessel",
   "name": "@pacem/pacem",
   "workspaces": [
     "packages/*"