@pallasoft/ps-core-components 2.42.0 → 2.43.0

package/dist/components/ps-button.js

@@ -5,5 +5,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const ps_design_system_1 = require("@pallasoft/ps-design-system");
 const ps_button_classes_1 = require("../constants/ps-button-classes");
 const ps_spinner_1 = require("./ps-spinner");
-const PsButton = ({ children, className, disabled, isLabelHiddenOnMobile = false, isLoading = false, leadingIcon, loadingLabel, size = 'default', trailingIcon, type = 'button', variant = 'secondary', ...props }) => ((0, jsx_runtime_1.jsxs)("button", { className: ps_design_system_1.PallasoftClassNameService.merge(ps_button_classes_1.PsButtonBaseClassName, 'disabled:cursor-not-allowed disabled:opacity-50', ps_button_classes_1.PsButtonSizeClassNames[size], isLabelHiddenOnMobile && leadingIcon ? 'min-w-11 max-sm:px-0' : '', ps_button_classes_1.PsButtonVariantClassNames[variant], className), "aria-busy": isLoading || undefined, disabled: disabled || isLoading, type: type, ...props, children: [isLoading ? ((0, jsx_runtime_1.jsx)(ps_spinner_1.PsSpinner, { className: 'absolute inset-0 m-auto', color: 'current', label: loadingLabel !== null && loadingLabel !== undefined ? loadingLabel : 'Loading', size: 'small' })) : null, (0, jsx_runtime_1.jsxs)("span", { "aria-hidden": isLoading || undefined, className: ps_design_system_1.PallasoftClassNameService.merge('inline-flex min-w-0 items-center gap-2', isLoading ? 'invisible' : ''), children: [leadingIcon ? (0, jsx_runtime_1.jsx)("span", { className: 'shrink-0', children: leadingIcon }) : null, (0, jsx_runtime_1.jsx)("span", { className: isLabelHiddenOnMobile && leadingIcon ? 'sr-only sm:not-sr-only sm:truncate' : 'truncate', children: children }), trailingIcon ? (0, jsx_runtime_1.jsx)("span", { className: 'shrink-0', children: trailingIcon }) : null] })] }));
+const PsButton = ({ children, className, disabled, isLabelHiddenOnMobile = false, isLoading = false, leadingIcon, loadingLabel, size = 'default', trailingIcon, type = 'button', variant = 'secondary', ...props }) => ((0, jsx_runtime_1.jsxs)("button", { className: ps_design_system_1.PallasoftClassNameService.merge(ps_button_classes_1.PsButtonBaseClassName, isLoading && disabled !== true
+        ? 'cursor-progress'
+        : 'disabled:cursor-not-allowed disabled:opacity-50', ps_button_classes_1.PsButtonSizeClassNames[size], isLabelHiddenOnMobile && leadingIcon ? 'min-w-11 max-sm:px-0' : '', ps_button_classes_1.PsButtonVariantClassNames[variant], className), "aria-busy": isLoading || undefined, disabled: disabled || isLoading, type: type, ...props, children: [isLoading ? ((0, jsx_runtime_1.jsx)(ps_spinner_1.PsSpinner, { className: 'absolute inset-0 m-auto', color: 'current', label: loadingLabel !== null && loadingLabel !== undefined ? loadingLabel : 'Loading', size: 'small' })) : null, (0, jsx_runtime_1.jsxs)("span", { "aria-hidden": isLoading || undefined, className: ps_design_system_1.PallasoftClassNameService.merge('inline-flex min-w-0 items-center gap-2', isLoading ? 'invisible' : ''), children: [leadingIcon ? (0, jsx_runtime_1.jsx)("span", { className: 'shrink-0', children: leadingIcon }) : null, (0, jsx_runtime_1.jsx)("span", { className: isLabelHiddenOnMobile && leadingIcon ? 'sr-only sm:not-sr-only sm:truncate' : 'truncate', children: children }), trailingIcon ? (0, jsx_runtime_1.jsx)("span", { className: 'shrink-0', children: trailingIcon }) : null] })] }));
 exports.PsButton = PsButton;

package/dist/components/ps-reflective-app-shell.d.ts

@@ -4,9 +4,11 @@ export interface PsReflectiveAppShellProps {
     className?: string;
     contentClassName?: string;
     frameClassName?: string;
+    scrollPreventReset?: boolean;
     scrollResetKey?: string;
+    scrollRestoreKey?: string;
     sidebar: ReactNode;
     sidebarWidth?: string;
     topbar: ReactNode;
 }
-export declare const PsReflectiveAppShell: ({ children, className, contentClassName, frameClassName, scrollResetKey, sidebar, sidebarWidth, topbar, }: PsReflectiveAppShellProps) => import("react").JSX.Element;
+export declare const PsReflectiveAppShell: ({ children, className, contentClassName, frameClassName, scrollPreventReset, scrollResetKey, scrollRestoreKey, sidebar, sidebarWidth, topbar, }: PsReflectiveAppShellProps) => import("react").JSX.Element;

package/dist/components/ps-reflective-app-shell.js

@@ -4,14 +4,21 @@ exports.PsReflectiveAppShell = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const ps_design_system_1 = require("@pallasoft/ps-design-system");
-const PsReflectiveAppShell = ({ children, className, contentClassName, frameClassName, scrollResetKey, sidebar, sidebarWidth = '17rem', topbar, }) => {
+const use_ps_scroll_restoration_1 = require("../hooks/use-ps-scroll-restoration");
+const PsReflectiveAppShell = ({ children, className, contentClassName, frameClassName, scrollPreventReset, scrollResetKey, scrollRestoreKey, sidebar, sidebarWidth = '17rem', topbar, }) => {
     const contentRef = (0, react_1.useRef)(null);
+    (0, use_ps_scroll_restoration_1.usePsScrollRestoration)({
+        elementRef: contentRef,
+        preventScrollReset: scrollPreventReset,
+        resetKey: scrollResetKey,
+        restoreKey: scrollRestoreKey,
+    });
     (0, react_1.useLayoutEffect)(() => {
-        if (scrollResetKey === undefined)
+        if (scrollResetKey === undefined || scrollRestoreKey !== undefined)
             return;
         contentRef.current?.scrollTo({ top: 0, left: 0 });
         window.scrollTo({ top: 0, left: 0 });
-    }, [scrollResetKey]);
+    }, [scrollResetKey, scrollRestoreKey]);
     return ((0, jsx_runtime_1.jsx)("section", { className: ps_design_system_1.PallasoftClassNameService.merge('ps-reflective-frame h-[100dvh] overflow-hidden text-ink', className), children: (0, jsx_runtime_1.jsxs)("div", { className: ps_design_system_1.PallasoftClassNameService.merge('ps-liquid-strong grid h-full min-h-0 w-full overflow-hidden border-line/70 bg-white/70 backdrop-blur-2xl transition-[grid-template-columns] duration-200 dark:border-white/10 dark:bg-surface/70 md:grid-cols-[var(--ps-sidebar-width)_minmax(0,1fr)]', frameClassName), style: { ['--ps-sidebar-width']: sidebarWidth }, children: [sidebar, (0, jsx_runtime_1.jsxs)("div", { className: 'flex min-h-0 min-w-0 flex-col bg-white/32 dark:bg-white/[0.02]', children: [topbar, (0, jsx_runtime_1.jsx)("main", { ref: contentRef, className: ps_design_system_1.PallasoftClassNameService.merge('ps-scrollbar min-h-0 flex-1 overflow-y-auto px-4 ps-page-enter sm:px-5 lg:px-6 xl:px-7', contentClassName), children: (0, jsx_runtime_1.jsx)("div", { className: 'py-5', children: children }) })] })] }) }));
 };
 exports.PsReflectiveAppShell = PsReflectiveAppShell;

package/dist/components/ps-scroll-restoration.d.ts

@@ -0,0 +1,6 @@
+export interface PsScrollRestorationProps {
+    preventScrollReset?: boolean;
+    resetKey?: string;
+    restoreKey: string;
+}
+export declare const PsScrollRestoration: ({ preventScrollReset, resetKey, restoreKey, }: PsScrollRestorationProps) => null;

package/dist/components/ps-scroll-restoration.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsScrollRestoration = void 0;
+const use_ps_scroll_restoration_1 = require("../hooks/use-ps-scroll-restoration");
+const PsScrollRestoration = ({ preventScrollReset, resetKey, restoreKey, }) => {
+    (0, use_ps_scroll_restoration_1.usePsScrollRestoration)({ preventScrollReset, resetKey, restoreKey });
+    return null;
+};
+exports.PsScrollRestoration = PsScrollRestoration;

package/dist/constants/ps-scroll-restoration-config.d.ts

@@ -0,0 +1,10 @@
+export declare const PsScrollRestorationConfig: {
+    readonly elementScope: "element:";
+    readonly inputEvents: readonly ["wheel", "touchstart", "keydown", "mousedown"];
+    readonly maxEntries: 100;
+    readonly persistThrottleMs: 150;
+    readonly restoreTimeoutMs: 4000;
+    readonly storageKey: "ps-scroll-restoration";
+    readonly tolerancePx: 2;
+    readonly windowScope: "window:";
+};

package/dist/constants/ps-scroll-restoration-config.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsScrollRestorationConfig = void 0;
+exports.PsScrollRestorationConfig = {
+    elementScope: 'element:',
+    inputEvents: ['wheel', 'touchstart', 'keydown', 'mousedown'],
+    maxEntries: 100,
+    persistThrottleMs: 150,
+    restoreTimeoutMs: 4000,
+    storageKey: 'ps-scroll-restoration',
+    tolerancePx: 2,
+    windowScope: 'window:',
+};

package/dist/esm/components/ps-button.js

@@ -2,4 +2,6 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { PallasoftClassNameService } from '@pallasoft/ps-design-system';
 import { PsButtonBaseClassName, PsButtonSizeClassNames, PsButtonVariantClassNames, } from '../constants/ps-button-classes.js';
 import { PsSpinner } from './ps-spinner.js';
-export const PsButton = ({ children, className, disabled, isLabelHiddenOnMobile = false, isLoading = false, leadingIcon, loadingLabel, size = 'default', trailingIcon, type = 'button', variant = 'secondary', ...props }) => (_jsxs("button", { className: PallasoftClassNameService.merge(PsButtonBaseClassName, 'disabled:cursor-not-allowed disabled:opacity-50', PsButtonSizeClassNames[size], isLabelHiddenOnMobile && leadingIcon ? 'min-w-11 max-sm:px-0' : '', PsButtonVariantClassNames[variant], className), "aria-busy": isLoading || undefined, disabled: disabled || isLoading, type: type, ...props, children: [isLoading ? (_jsx(PsSpinner, { className: 'absolute inset-0 m-auto', color: 'current', label: loadingLabel !== null && loadingLabel !== undefined ? loadingLabel : 'Loading', size: 'small' })) : null, _jsxs("span", { "aria-hidden": isLoading || undefined, className: PallasoftClassNameService.merge('inline-flex min-w-0 items-center gap-2', isLoading ? 'invisible' : ''), children: [leadingIcon ? _jsx("span", { className: 'shrink-0', children: leadingIcon }) : null, _jsx("span", { className: isLabelHiddenOnMobile && leadingIcon ? 'sr-only sm:not-sr-only sm:truncate' : 'truncate', children: children }), trailingIcon ? _jsx("span", { className: 'shrink-0', children: trailingIcon }) : null] })] }));
+export const PsButton = ({ children, className, disabled, isLabelHiddenOnMobile = false, isLoading = false, leadingIcon, loadingLabel, size = 'default', trailingIcon, type = 'button', variant = 'secondary', ...props }) => (_jsxs("button", { className: PallasoftClassNameService.merge(PsButtonBaseClassName, isLoading && disabled !== true
+        ? 'cursor-progress'
+        : 'disabled:cursor-not-allowed disabled:opacity-50', PsButtonSizeClassNames[size], isLabelHiddenOnMobile && leadingIcon ? 'min-w-11 max-sm:px-0' : '', PsButtonVariantClassNames[variant], className), "aria-busy": isLoading || undefined, disabled: disabled || isLoading, type: type, ...props, children: [isLoading ? (_jsx(PsSpinner, { className: 'absolute inset-0 m-auto', color: 'current', label: loadingLabel !== null && loadingLabel !== undefined ? loadingLabel : 'Loading', size: 'small' })) : null, _jsxs("span", { "aria-hidden": isLoading || undefined, className: PallasoftClassNameService.merge('inline-flex min-w-0 items-center gap-2', isLoading ? 'invisible' : ''), children: [leadingIcon ? _jsx("span", { className: 'shrink-0', children: leadingIcon }) : null, _jsx("span", { className: isLabelHiddenOnMobile && leadingIcon ? 'sr-only sm:not-sr-only sm:truncate' : 'truncate', children: children }), trailingIcon ? _jsx("span", { className: 'shrink-0', children: trailingIcon }) : null] })] }));

package/dist/esm/components/ps-reflective-app-shell.js

@@ -1,13 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef } from 'react';
 import { PallasoftClassNameService } from '@pallasoft/ps-design-system';
-export const PsReflectiveAppShell = ({ children, className, contentClassName, frameClassName, scrollResetKey, sidebar, sidebarWidth = '17rem', topbar, }) => {
+import { usePsScrollRestoration } from '../hooks/use-ps-scroll-restoration.js';
+export const PsReflectiveAppShell = ({ children, className, contentClassName, frameClassName, scrollPreventReset, scrollResetKey, scrollRestoreKey, sidebar, sidebarWidth = '17rem', topbar, }) => {
     const contentRef = useRef(null);
+    usePsScrollRestoration({
+        elementRef: contentRef,
+        preventScrollReset: scrollPreventReset,
+        resetKey: scrollResetKey,
+        restoreKey: scrollRestoreKey,
+    });
     useLayoutEffect(() => {
-        if (scrollResetKey === undefined)
+        if (scrollResetKey === undefined || scrollRestoreKey !== undefined)
             return;
         contentRef.current?.scrollTo({ top: 0, left: 0 });
         window.scrollTo({ top: 0, left: 0 });
-    }, [scrollResetKey]);
+    }, [scrollResetKey, scrollRestoreKey]);
     return (_jsx("section", { className: PallasoftClassNameService.merge('ps-reflective-frame h-[100dvh] overflow-hidden text-ink', className), children: _jsxs("div", { className: PallasoftClassNameService.merge('ps-liquid-strong grid h-full min-h-0 w-full overflow-hidden border-line/70 bg-white/70 backdrop-blur-2xl transition-[grid-template-columns] duration-200 dark:border-white/10 dark:bg-surface/70 md:grid-cols-[var(--ps-sidebar-width)_minmax(0,1fr)]', frameClassName), style: { ['--ps-sidebar-width']: sidebarWidth }, children: [sidebar, _jsxs("div", { className: 'flex min-h-0 min-w-0 flex-col bg-white/32 dark:bg-white/[0.02]', children: [topbar, _jsx("main", { ref: contentRef, className: PallasoftClassNameService.merge('ps-scrollbar min-h-0 flex-1 overflow-y-auto px-4 ps-page-enter sm:px-5 lg:px-6 xl:px-7', contentClassName), children: _jsx("div", { className: 'py-5', children: children }) })] })] }) }));
 };

package/dist/esm/components/ps-scroll-restoration.js

@@ -0,0 +1,5 @@
+import { usePsScrollRestoration } from '../hooks/use-ps-scroll-restoration.js';
+export const PsScrollRestoration = ({ preventScrollReset, resetKey, restoreKey, }) => {
+    usePsScrollRestoration({ preventScrollReset, resetKey, restoreKey });
+    return null;
+};

package/dist/esm/constants/ps-scroll-restoration-config.js

@@ -0,0 +1,10 @@
+export const PsScrollRestorationConfig = {
+    elementScope: 'element:',
+    inputEvents: ['wheel', 'touchstart', 'keydown', 'mousedown'],
+    maxEntries: 100,
+    persistThrottleMs: 150,
+    restoreTimeoutMs: 4000,
+    storageKey: 'ps-scroll-restoration',
+    tolerancePx: 2,
+    windowScope: 'window:',
+};

package/dist/esm/hooks/use-ps-browser-layout-effect.js

@@ -0,0 +1,2 @@
+import { useEffect, useLayoutEffect } from 'react';
+export const usePsBrowserLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;

package/dist/esm/hooks/use-ps-scroll-restoration.js

@@ -0,0 +1,103 @@
+import { useEffect, useRef } from 'react';
+import { PsScrollRestoreService } from '../services/ps-scroll-restore-service.js';
+import { PsScrollStorageService } from '../services/ps-scroll-storage-service.js';
+import { PsScrollTargetService } from '../services/ps-scroll-target-service.js';
+import { usePsBrowserLayoutEffect } from './use-ps-browser-layout-effect.js';
+export const usePsScrollRestoration = ({ elementRef, preventScrollReset, resetKey, restoreKey, }) => {
+    const keyRef = useRef(restoreKey);
+    const hasSavedRef = useRef(false);
+    const appliedKeyRef = useRef(undefined);
+    const appliedResetKeyRef = useRef(undefined);
+    const isRestoringRef = useRef(false);
+    const pendingRef = useRef(null);
+    const isEnabled = restoreKey !== undefined;
+    useEffect(() => {
+        if (!isEnabled ||
+            typeof window === 'undefined' ||
+            typeof history === 'undefined' ||
+            !('scrollRestoration' in history))
+            return;
+        const previous = history.scrollRestoration;
+        history.scrollRestoration = 'manual';
+        return () => {
+            history.scrollRestoration = previous;
+        };
+    }, [isEnabled]);
+    usePsBrowserLayoutEffect(() => {
+        keyRef.current = restoreKey;
+        if (typeof window === 'undefined')
+            return;
+        PsScrollStorageService.flush();
+        if (restoreKey === undefined)
+            return;
+        const element = elementRef === undefined ? null : elementRef.current;
+        const saved = PsScrollStorageService.read(PsScrollTargetService.storageKey(element, restoreKey));
+        hasSavedRef.current = saved !== undefined;
+        if (saved === undefined)
+            return;
+        isRestoringRef.current = true;
+        const stop = PsScrollRestoreService.start(element, saved, () => {
+            isRestoringRef.current = false;
+        });
+        return () => {
+            stop();
+            isRestoringRef.current = false;
+        };
+    }, [restoreKey, elementRef]);
+    usePsBrowserLayoutEffect(() => {
+        const previousKey = appliedKeyRef.current;
+        const previousResetKey = appliedResetKeyRef.current;
+        appliedKeyRef.current = restoreKey;
+        appliedResetKeyRef.current = resetKey;
+        if (restoreKey === undefined || typeof window === 'undefined')
+            return;
+        const hasChanged = previousResetKey !== undefined && previousResetKey !== resetKey;
+        const isRestored = previousKey !== restoreKey && hasSavedRef.current;
+        if (!hasChanged || isRestored || preventScrollReset === true)
+            return;
+        PsScrollTargetService.scrollTo(elementRef === undefined ? null : elementRef.current, 0);
+    }, [resetKey, restoreKey, elementRef, preventScrollReset]);
+    useEffect(() => {
+        if (!isEnabled || typeof window === 'undefined')
+            return;
+        const element = elementRef === undefined ? null : elementRef.current;
+        const target = PsScrollTargetService.eventTarget(element);
+        let frame = 0;
+        const flushPending = () => {
+            const pending = pendingRef.current;
+            pendingRef.current = null;
+            if (pending !== null)
+                PsScrollStorageService.write(pending.key, pending.top);
+        };
+        const onScroll = () => {
+            const key = keyRef.current;
+            if (key === undefined || isRestoringRef.current)
+                return;
+            pendingRef.current = {
+                key: PsScrollTargetService.storageKey(element, key),
+                top: PsScrollTargetService.top(element),
+            };
+            if (frame !== 0)
+                return;
+            frame = window.requestAnimationFrame(() => {
+                frame = 0;
+                flushPending();
+            });
+        };
+        const onPageHide = () => {
+            const key = keyRef.current;
+            pendingRef.current = null;
+            if (key !== undefined && !isRestoringRef.current)
+                PsScrollStorageService.write(PsScrollTargetService.storageKey(element, key), PsScrollTargetService.top(element));
+            PsScrollStorageService.flush();
+        };
+        target.addEventListener('scroll', onScroll, { passive: true });
+        window.addEventListener('pagehide', onPageHide);
+        return () => {
+            target.removeEventListener('scroll', onScroll);
+            window.removeEventListener('pagehide', onPageHide);
+            window.cancelAnimationFrame(frame);
+            flushPending();
+        };
+    }, [isEnabled, elementRef]);
+};

package/dist/esm/index.js

@@ -192,3 +192,13 @@ export * from './components/ps-divider.js';
 export * from './models/ps-divider-orientation.js';
 export * from './components/ps-rating-display.js';
 export * from './constants/ps-rating-display-size.js';
+export * from './constants/ps-scroll-restoration-config.js';
+export * from './models/ps-scroll-offsets-data.js';
+export * from './models/ps-scroll-restoration-options.js';
+export * from './services/ps-scroll-storage-service.js';
+export * from './services/ps-scroll-target-service.js';
+export * from './services/ps-scroll-restore-service.js';
+export * from './hooks/use-ps-scroll-restoration.js';
+export * from './components/ps-scroll-restoration.js';
+export * from './hooks/use-ps-browser-layout-effect.js';
+export * from './models/ps-scroll-pending-save-data.js';

package/dist/esm/models/ps-scroll-offsets-data.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/models/ps-scroll-pending-save-data.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/models/ps-scroll-restoration-options.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/services/ps-scroll-restore-service.js

@@ -0,0 +1,52 @@
+import { PsScrollRestorationConfig } from '../constants/ps-scroll-restoration-config.js';
+import { PsScrollTargetService } from './ps-scroll-target-service.js';
+export class PsScrollRestoreService {
+    static start(element, top, onDone) {
+        let isDone = false;
+        let observer = null;
+        let mutations = null;
+        let timer = 0;
+        const finish = () => {
+            if (isDone)
+                return;
+            isDone = true;
+            window.clearTimeout(timer);
+            observer?.disconnect();
+            mutations?.disconnect();
+            for (const name of PsScrollRestorationConfig.inputEvents)
+                window.removeEventListener(name, onInput, true);
+            onDone();
+        };
+        const onInput = () => finish();
+        const attempt = () => {
+            if (isDone)
+                return;
+            if (PsScrollTargetService.maxTop(element) >= top - PsScrollRestorationConfig.tolerancePx) {
+                PsScrollTargetService.scrollTo(element, top);
+                finish();
+            }
+        };
+        for (const name of PsScrollRestorationConfig.inputEvents)
+            window.addEventListener(name, onInput, { capture: true, passive: true });
+        timer = window.setTimeout(() => {
+            if (isDone)
+                return;
+            PsScrollTargetService.scrollTo(element, top);
+            finish();
+        }, PsScrollRestorationConfig.restoreTimeoutMs);
+        attempt();
+        if (!isDone && typeof MutationObserver !== 'undefined') {
+            mutations = new MutationObserver(attempt);
+            mutations.observe(element === null ? document.body : element, {
+                childList: true,
+                subtree: true,
+            });
+        }
+        if (!isDone && typeof ResizeObserver !== 'undefined') {
+            observer = new ResizeObserver(attempt);
+            for (const node of PsScrollTargetService.observed(element))
+                observer.observe(node);
+        }
+        return finish;
+    }
+}

package/dist/esm/services/ps-scroll-storage-service.js

@@ -0,0 +1,66 @@
+import { PsScrollRestorationConfig } from '../constants/ps-scroll-restoration-config.js';
+export class PsScrollStorageService {
+    static read(key) {
+        const offsets = PsScrollStorageService.memory();
+        return Object.prototype.hasOwnProperty.call(offsets, key) ? offsets[key] : undefined;
+    }
+    static write(key, top) {
+        const offsets = PsScrollStorageService.memory();
+        delete offsets[key];
+        offsets[key] = top;
+        const keys = Object.keys(offsets);
+        const overflow = keys.length - PsScrollRestorationConfig.maxEntries;
+        for (const oldest of keys.slice(0, overflow > 0 ? overflow : 0))
+            delete offsets[oldest];
+        if (PsScrollStorageService.timer !== 0 || typeof window === 'undefined')
+            return;
+        PsScrollStorageService.timer = window.setTimeout(PsScrollStorageService.flush, PsScrollRestorationConfig.persistThrottleMs);
+    }
+    static flush() {
+        if (typeof window === 'undefined')
+            return;
+        window.clearTimeout(PsScrollStorageService.timer);
+        PsScrollStorageService.timer = 0;
+        if (PsScrollStorageService.offsets === null)
+            return;
+        try {
+            window.sessionStorage.setItem(PsScrollRestorationConfig.storageKey, JSON.stringify(PsScrollStorageService.offsets));
+        }
+        catch {
+            return;
+        }
+    }
+    static reset() {
+        if (typeof window !== 'undefined')
+            window.clearTimeout(PsScrollStorageService.timer);
+        PsScrollStorageService.timer = 0;
+        PsScrollStorageService.offsets = null;
+    }
+    static memory() {
+        if (PsScrollStorageService.offsets === null)
+            PsScrollStorageService.offsets = PsScrollStorageService.load();
+        return PsScrollStorageService.offsets;
+    }
+    static load() {
+        if (typeof window === 'undefined')
+            return {};
+        try {
+            const raw = window.sessionStorage.getItem(PsScrollRestorationConfig.storageKey);
+            if (raw === null)
+                return {};
+            const parsed = JSON.parse(raw);
+            return PsScrollStorageService.isOffsets(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    static isOffsets(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            Object.values(value).every((entry) => typeof entry === 'number' && Number.isFinite(entry)));
+    }
+}
+PsScrollStorageService.offsets = null;
+PsScrollStorageService.timer = 0;

package/dist/esm/services/ps-scroll-target-service.js

@@ -0,0 +1,29 @@
+import { PsScrollRestorationConfig } from '../constants/ps-scroll-restoration-config.js';
+export class PsScrollTargetService {
+    static storageKey(element, restoreKey) {
+        return `${element === null ? PsScrollRestorationConfig.windowScope : PsScrollRestorationConfig.elementScope}${restoreKey}`;
+    }
+    static top(element) {
+        return element === null ? window.scrollY : element.scrollTop;
+    }
+    static maxTop(element) {
+        if (element !== null)
+            return element.scrollHeight - element.clientHeight;
+        return document.documentElement.scrollHeight - window.innerHeight;
+    }
+    static scrollTo(element, top) {
+        if (element === null) {
+            window.scrollTo({ behavior: 'instant', left: 0, top });
+            return;
+        }
+        element.scrollTo({ behavior: 'instant', left: 0, top });
+    }
+    static eventTarget(element) {
+        return element === null ? window : element;
+    }
+    static observed(element) {
+        if (element === null)
+            return [document.documentElement, document.body];
+        return [element, ...Array.from(element.children)];
+    }
+}

package/dist/hooks/use-ps-browser-layout-effect.d.ts

@@ -0,0 +1,2 @@
+import { useEffect } from 'react';
+export declare const usePsBrowserLayoutEffect: typeof useEffect;

package/dist/hooks/use-ps-browser-layout-effect.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePsBrowserLayoutEffect = void 0;
+const react_1 = require("react");
+exports.usePsBrowserLayoutEffect = typeof window === 'undefined' ? react_1.useEffect : react_1.useLayoutEffect;

package/dist/hooks/use-ps-scroll-restoration.d.ts

@@ -0,0 +1,2 @@
+import type { PsScrollRestorationOptions } from '../models/ps-scroll-restoration-options';
+export declare const usePsScrollRestoration: ({ elementRef, preventScrollReset, resetKey, restoreKey, }: PsScrollRestorationOptions) => void;

package/dist/hooks/use-ps-scroll-restoration.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePsScrollRestoration = void 0;
+const react_1 = require("react");
+const ps_scroll_restore_service_1 = require("../services/ps-scroll-restore-service");
+const ps_scroll_storage_service_1 = require("../services/ps-scroll-storage-service");
+const ps_scroll_target_service_1 = require("../services/ps-scroll-target-service");
+const use_ps_browser_layout_effect_1 = require("./use-ps-browser-layout-effect");
+const usePsScrollRestoration = ({ elementRef, preventScrollReset, resetKey, restoreKey, }) => {
+    const keyRef = (0, react_1.useRef)(restoreKey);
+    const hasSavedRef = (0, react_1.useRef)(false);
+    const appliedKeyRef = (0, react_1.useRef)(undefined);
+    const appliedResetKeyRef = (0, react_1.useRef)(undefined);
+    const isRestoringRef = (0, react_1.useRef)(false);
+    const pendingRef = (0, react_1.useRef)(null);
+    const isEnabled = restoreKey !== undefined;
+    (0, react_1.useEffect)(() => {
+        if (!isEnabled ||
+            typeof window === 'undefined' ||
+            typeof history === 'undefined' ||
+            !('scrollRestoration' in history))
+            return;
+        const previous = history.scrollRestoration;
+        history.scrollRestoration = 'manual';
+        return () => {
+            history.scrollRestoration = previous;
+        };
+    }, [isEnabled]);
+    (0, use_ps_browser_layout_effect_1.usePsBrowserLayoutEffect)(() => {
+        keyRef.current = restoreKey;
+        if (typeof window === 'undefined')
+            return;
+        ps_scroll_storage_service_1.PsScrollStorageService.flush();
+        if (restoreKey === undefined)
+            return;
+        const element = elementRef === undefined ? null : elementRef.current;
+        const saved = ps_scroll_storage_service_1.PsScrollStorageService.read(ps_scroll_target_service_1.PsScrollTargetService.storageKey(element, restoreKey));
+        hasSavedRef.current = saved !== undefined;
+        if (saved === undefined)
+            return;
+        isRestoringRef.current = true;
+        const stop = ps_scroll_restore_service_1.PsScrollRestoreService.start(element, saved, () => {
+            isRestoringRef.current = false;
+        });
+        return () => {
+            stop();
+            isRestoringRef.current = false;
+        };
+    }, [restoreKey, elementRef]);
+    (0, use_ps_browser_layout_effect_1.usePsBrowserLayoutEffect)(() => {
+        const previousKey = appliedKeyRef.current;
+        const previousResetKey = appliedResetKeyRef.current;
+        appliedKeyRef.current = restoreKey;
+        appliedResetKeyRef.current = resetKey;
+        if (restoreKey === undefined || typeof window === 'undefined')
+            return;
+        const hasChanged = previousResetKey !== undefined && previousResetKey !== resetKey;
+        const isRestored = previousKey !== restoreKey && hasSavedRef.current;
+        if (!hasChanged || isRestored || preventScrollReset === true)
+            return;
+        ps_scroll_target_service_1.PsScrollTargetService.scrollTo(elementRef === undefined ? null : elementRef.current, 0);
+    }, [resetKey, restoreKey, elementRef, preventScrollReset]);
+    (0, react_1.useEffect)(() => {
+        if (!isEnabled || typeof window === 'undefined')
+            return;
+        const element = elementRef === undefined ? null : elementRef.current;
+        const target = ps_scroll_target_service_1.PsScrollTargetService.eventTarget(element);
+        let frame = 0;
+        const flushPending = () => {
+            const pending = pendingRef.current;
+            pendingRef.current = null;
+            if (pending !== null)
+                ps_scroll_storage_service_1.PsScrollStorageService.write(pending.key, pending.top);
+        };
+        const onScroll = () => {
+            const key = keyRef.current;
+            if (key === undefined || isRestoringRef.current)
+                return;
+            pendingRef.current = {
+                key: ps_scroll_target_service_1.PsScrollTargetService.storageKey(element, key),
+                top: ps_scroll_target_service_1.PsScrollTargetService.top(element),
+            };
+            if (frame !== 0)
+                return;
+            frame = window.requestAnimationFrame(() => {
+                frame = 0;
+                flushPending();
+            });
+        };
+        const onPageHide = () => {
+            const key = keyRef.current;
+            pendingRef.current = null;
+            if (key !== undefined && !isRestoringRef.current)
+                ps_scroll_storage_service_1.PsScrollStorageService.write(ps_scroll_target_service_1.PsScrollTargetService.storageKey(element, key), ps_scroll_target_service_1.PsScrollTargetService.top(element));
+            ps_scroll_storage_service_1.PsScrollStorageService.flush();
+        };
+        target.addEventListener('scroll', onScroll, { passive: true });
+        window.addEventListener('pagehide', onPageHide);
+        return () => {
+            target.removeEventListener('scroll', onScroll);
+            window.removeEventListener('pagehide', onPageHide);
+            window.cancelAnimationFrame(frame);
+            flushPending();
+        };
+    }, [isEnabled, elementRef]);
+};
+exports.usePsScrollRestoration = usePsScrollRestoration;

package/dist/index.d.ts

@@ -192,3 +192,13 @@ export * from './components/ps-divider';
 export * from './models/ps-divider-orientation';
 export * from './components/ps-rating-display';
 export * from './constants/ps-rating-display-size';
+export * from './constants/ps-scroll-restoration-config';
+export * from './models/ps-scroll-offsets-data';
+export * from './models/ps-scroll-restoration-options';
+export * from './services/ps-scroll-storage-service';
+export * from './services/ps-scroll-target-service';
+export * from './services/ps-scroll-restore-service';
+export * from './hooks/use-ps-scroll-restoration';
+export * from './components/ps-scroll-restoration';
+export * from './hooks/use-ps-browser-layout-effect';
+export * from './models/ps-scroll-pending-save-data';

package/dist/index.js

@@ -208,3 +208,13 @@ __exportStar(require("./components/ps-divider"), exports);
 __exportStar(require("./models/ps-divider-orientation"), exports);
 __exportStar(require("./components/ps-rating-display"), exports);
 __exportStar(require("./constants/ps-rating-display-size"), exports);
+__exportStar(require("./constants/ps-scroll-restoration-config"), exports);
+__exportStar(require("./models/ps-scroll-offsets-data"), exports);
+__exportStar(require("./models/ps-scroll-restoration-options"), exports);
+__exportStar(require("./services/ps-scroll-storage-service"), exports);
+__exportStar(require("./services/ps-scroll-target-service"), exports);
+__exportStar(require("./services/ps-scroll-restore-service"), exports);
+__exportStar(require("./hooks/use-ps-scroll-restoration"), exports);
+__exportStar(require("./components/ps-scroll-restoration"), exports);
+__exportStar(require("./hooks/use-ps-browser-layout-effect"), exports);
+__exportStar(require("./models/ps-scroll-pending-save-data"), exports);

package/dist/models/ps-scroll-offsets-data.d.ts

@@ -0,0 +1 @@
+export type PsScrollOffsetsData = Record<string, number>;

package/dist/models/ps-scroll-offsets-data.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/ps-scroll-pending-save-data.d.ts

@@ -0,0 +1,4 @@
+export interface PsScrollPendingSaveData {
+    key: string;
+    top: number;
+}

package/dist/models/ps-scroll-pending-save-data.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/ps-scroll-restoration-options.d.ts

@@ -0,0 +1,7 @@
+import type { RefObject } from 'react';
+export interface PsScrollRestorationOptions {
+    elementRef?: RefObject<HTMLElement | null>;
+    preventScrollReset?: boolean;
+    resetKey?: string;
+    restoreKey?: string;
+}

package/dist/models/ps-scroll-restoration-options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/ps-scroll-restore-service.d.ts

@@ -0,0 +1,3 @@
+export declare class PsScrollRestoreService {
+    static start(element: HTMLElement | null, top: number, onDone: () => void): () => void;
+}

package/dist/services/ps-scroll-restore-service.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsScrollRestoreService = void 0;
+const ps_scroll_restoration_config_1 = require("../constants/ps-scroll-restoration-config");
+const ps_scroll_target_service_1 = require("./ps-scroll-target-service");
+class PsScrollRestoreService {
+    static start(element, top, onDone) {
+        let isDone = false;
+        let observer = null;
+        let mutations = null;
+        let timer = 0;
+        const finish = () => {
+            if (isDone)
+                return;
+            isDone = true;
+            window.clearTimeout(timer);
+            observer?.disconnect();
+            mutations?.disconnect();
+            for (const name of ps_scroll_restoration_config_1.PsScrollRestorationConfig.inputEvents)
+                window.removeEventListener(name, onInput, true);
+            onDone();
+        };
+        const onInput = () => finish();
+        const attempt = () => {
+            if (isDone)
+                return;
+            if (ps_scroll_target_service_1.PsScrollTargetService.maxTop(element) >= top - ps_scroll_restoration_config_1.PsScrollRestorationConfig.tolerancePx) {
+                ps_scroll_target_service_1.PsScrollTargetService.scrollTo(element, top);
+                finish();
+            }
+        };
+        for (const name of ps_scroll_restoration_config_1.PsScrollRestorationConfig.inputEvents)
+            window.addEventListener(name, onInput, { capture: true, passive: true });
+        timer = window.setTimeout(() => {
+            if (isDone)
+                return;
+            ps_scroll_target_service_1.PsScrollTargetService.scrollTo(element, top);
+            finish();
+        }, ps_scroll_restoration_config_1.PsScrollRestorationConfig.restoreTimeoutMs);
+        attempt();
+        if (!isDone && typeof MutationObserver !== 'undefined') {
+            mutations = new MutationObserver(attempt);
+            mutations.observe(element === null ? document.body : element, {
+                childList: true,
+                subtree: true,
+            });
+        }
+        if (!isDone && typeof ResizeObserver !== 'undefined') {
+            observer = new ResizeObserver(attempt);
+            for (const node of ps_scroll_target_service_1.PsScrollTargetService.observed(element))
+                observer.observe(node);
+        }
+        return finish;
+    }
+}
+exports.PsScrollRestoreService = PsScrollRestoreService;

package/dist/services/ps-scroll-storage-service.d.ts

@@ -0,0 +1,11 @@
+export declare class PsScrollStorageService {
+    private static offsets;
+    private static timer;
+    static read(key: string): number | undefined;
+    static write(key: string, top: number): void;
+    static flush(): void;
+    static reset(): void;
+    private static memory;
+    private static load;
+    private static isOffsets;
+}

package/dist/services/ps-scroll-storage-service.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsScrollStorageService = void 0;
+const ps_scroll_restoration_config_1 = require("../constants/ps-scroll-restoration-config");
+class PsScrollStorageService {
+    static read(key) {
+        const offsets = PsScrollStorageService.memory();
+        return Object.prototype.hasOwnProperty.call(offsets, key) ? offsets[key] : undefined;
+    }
+    static write(key, top) {
+        const offsets = PsScrollStorageService.memory();
+        delete offsets[key];
+        offsets[key] = top;
+        const keys = Object.keys(offsets);
+        const overflow = keys.length - ps_scroll_restoration_config_1.PsScrollRestorationConfig.maxEntries;
+        for (const oldest of keys.slice(0, overflow > 0 ? overflow : 0))
+            delete offsets[oldest];
+        if (PsScrollStorageService.timer !== 0 || typeof window === 'undefined')
+            return;
+        PsScrollStorageService.timer = window.setTimeout(PsScrollStorageService.flush, ps_scroll_restoration_config_1.PsScrollRestorationConfig.persistThrottleMs);
+    }
+    static flush() {
+        if (typeof window === 'undefined')
+            return;
+        window.clearTimeout(PsScrollStorageService.timer);
+        PsScrollStorageService.timer = 0;
+        if (PsScrollStorageService.offsets === null)
+            return;
+        try {
+            window.sessionStorage.setItem(ps_scroll_restoration_config_1.PsScrollRestorationConfig.storageKey, JSON.stringify(PsScrollStorageService.offsets));
+        }
+        catch {
+            return;
+        }
+    }
+    static reset() {
+        if (typeof window !== 'undefined')
+            window.clearTimeout(PsScrollStorageService.timer);
+        PsScrollStorageService.timer = 0;
+        PsScrollStorageService.offsets = null;
+    }
+    static memory() {
+        if (PsScrollStorageService.offsets === null)
+            PsScrollStorageService.offsets = PsScrollStorageService.load();
+        return PsScrollStorageService.offsets;
+    }
+    static load() {
+        if (typeof window === 'undefined')
+            return {};
+        try {
+            const raw = window.sessionStorage.getItem(ps_scroll_restoration_config_1.PsScrollRestorationConfig.storageKey);
+            if (raw === null)
+                return {};
+            const parsed = JSON.parse(raw);
+            return PsScrollStorageService.isOffsets(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    static isOffsets(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            Object.values(value).every((entry) => typeof entry === 'number' && Number.isFinite(entry)));
+    }
+}
+exports.PsScrollStorageService = PsScrollStorageService;
+PsScrollStorageService.offsets = null;
+PsScrollStorageService.timer = 0;

package/dist/services/ps-scroll-target-service.d.ts

@@ -0,0 +1,8 @@
+export declare class PsScrollTargetService {
+    static storageKey(element: HTMLElement | null, restoreKey: string): string;
+    static top(element: HTMLElement | null): number;
+    static maxTop(element: HTMLElement | null): number;
+    static scrollTo(element: HTMLElement | null, top: number): void;
+    static eventTarget(element: HTMLElement | null): HTMLElement | Window;
+    static observed(element: HTMLElement | null): Element[];
+}

package/dist/services/ps-scroll-target-service.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsScrollTargetService = void 0;
+const ps_scroll_restoration_config_1 = require("../constants/ps-scroll-restoration-config");
+class PsScrollTargetService {
+    static storageKey(element, restoreKey) {
+        return `${element === null ? ps_scroll_restoration_config_1.PsScrollRestorationConfig.windowScope : ps_scroll_restoration_config_1.PsScrollRestorationConfig.elementScope}${restoreKey}`;
+    }
+    static top(element) {
+        return element === null ? window.scrollY : element.scrollTop;
+    }
+    static maxTop(element) {
+        if (element !== null)
+            return element.scrollHeight - element.clientHeight;
+        return document.documentElement.scrollHeight - window.innerHeight;
+    }
+    static scrollTo(element, top) {
+        if (element === null) {
+            window.scrollTo({ behavior: 'instant', left: 0, top });
+            return;
+        }
+        element.scrollTo({ behavior: 'instant', left: 0, top });
+    }
+    static eventTarget(element) {
+        return element === null ? window : element;
+    }
+    static observed(element) {
+        if (element === null)
+            return [document.documentElement, document.body];
+        return [element, ...Array.from(element.children)];
+    }
+}
+exports.PsScrollTargetService = PsScrollTargetService;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pallasoft/ps-core-components",
-	"version": "2.42.0",
+	"version": "2.43.0",
 	"private": false,
 	"main": "./dist/index.js",
 	"module": "./dist/esm/index.js",