kitzo 2.1.10 → 2.1.12

package/README.md

@@ -26,7 +26,7 @@ npm i kitzo
 or
 
 ```javascript
-<script src="https://cdn.jsdelivr.net/npm/kitzo@2.1.10/dist/kitzo.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/kitzo@2.1.12/dist/kitzo.umd.min.js"></script>
 ```
 
 > Vanilla: Attach this script tag in the html head tag and you are good to go.

package/dist/react.d.ts

@@ -1,8 +1,10 @@
-import { type ReactNode, type CSSProperties, type JSX, type PropsWithChildren } from 'react';
+import type { ReactNode, CSSProperties, JSX, PropsWithChildren, RefObject } from 'react';
+
+//! Toast API types declaration
+export type Positions = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
-// Toast API types declaration
 export interface ToastOptions {
-  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+  position?: Positions;
   duration?: number;
   style?: CSSProperties;
   showIcon?: boolean;
@@ -12,25 +14,29 @@ export type CustomContent = string | ReactNode | ((dismiss: () => void) => React
 
 export interface ToastAPI {
   (text?: string, options?: ToastOptions): void;
+
   success(text?: string, options?: ToastOptions): void;
+
   error(text?: string, options?: ToastOptions): void;
+
   promise<T>(
     callback: Promise<T>,
     msgs?: {
       loading?: string;
-      success?: string | ((res: T) => string);
-      error?: string | ((err: Error) => string);
+      success?: string | ((res: T) => string | Promise<string>);
+      error?: string | ((err: any) => string | Promise<string>);
     },
     options?: ToastOptions,
-  ): Promise<T>;
-  custom(content: CustomContent, options?: { duration?: number; exitDelay?: number; position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' }): void;
+  ): void;
+
+  custom(content: CustomContent, options?: { duration?: number; exitDelay?: number; position?: Positions }): void;
 }
 
 export declare const toast: ToastAPI;
 
-export declare function ToastContainer(props: { position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'; gap?: number }): JSX.Element;
+export declare function ToastContainer(props: { position?: Positions; gap?: number }): JSX.Element;
 
-// Tooltip API types declaration
+//! Tooltip API types declaration
 export interface TooltipCoreProps {
   content: string | ReactNode;
   position?: 'top' | 'right' | 'bottom' | 'left';
@@ -41,3 +47,16 @@ export interface TooltipCoreProps {
 export type TooltipProps = PropsWithChildren<TooltipCoreProps>;
 
 export declare function Tooltip(props: TooltipProps): JSX.Element;
+
+//! useScrollRestoration hook types declaration
+type ScrollHookOptions = {
+  behavior?: 'auto' | 'smooth' | 'instant';
+  delay?: number;
+};
+
+type LocationLike = {
+  pathname: string;
+  [key: string]: any;
+};
+
+export declare function useScrollRestoration(path: LocationLike | string, key: string | number, options?: ScrollHookOptions): RefObject<HTMLElement | null>;

package/dist/react.esm.js

@@ -690,4 +690,73 @@ function Tooltip({
   }, content) : /*#__PURE__*/React.createElement(React.Fragment, null, content)));
 }
 
-export { ToastContainer, Tooltip, toast };
+function useScrollRestoration(path, key, options = {}) {
+  if (!path || typeof path !== 'object' && typeof path !== 'string') {
+    throw new Error('kitzo/react: useScrollRestoration(path, ...) expect location object from the react useLocation hook or unique path string(location.pathname)');
+  }
+  if (!key || typeof key !== 'string' && typeof key !== 'number') {
+    throw new Error('kitzo/react: useScrollRestoration(..., key) expect unique string or number');
+  }
+  const pathname = typeof path === 'object' ? path.pathname : path;
+  const behavior = options?.behavior ? options.behavior : 'instant';
+  const delay = options?.delay ? isNaN(Number(options.delay)) ? 0 : Number(options.delay) : 0;
+
+  // hook management
+  const ref = useRef(null);
+  const history = useRef(new Map());
+
+  // hook logic
+  useEffect(() => {
+    const element = ref.current;
+    const target = element || window;
+    const isWindow = target === window;
+    const mapKey = `${pathname}::${key}`;
+    const saved = history.current.get(mapKey);
+    const restore = () => {
+      if (!saved) return;
+      if (isWindow) {
+        window.scrollTo({
+          top: saved.top,
+          left: saved.left,
+          behavior
+        });
+      } else if (element) {
+        element.scrollTo({
+          top: saved.top,
+          left: saved.left,
+          behavior
+        });
+      }
+    };
+    if (saved) {
+      if (delay > 0) {
+        const timeoutId = setTimeout(restore, delay);
+        return () => clearTimeout(timeoutId);
+      } else {
+        restore();
+      }
+    }
+    let timeoutId = null;
+    const save = () => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => {
+        const top = isWindow ? window.scrollY : element?.scrollTop ?? 0;
+        const left = isWindow ? window.scrollX : element?.scrollLeft ?? 0;
+        history.current.set(mapKey, {
+          top,
+          left
+        });
+      }, 50);
+    };
+    target.addEventListener('scroll', save, {
+      passive: true
+    });
+    return () => {
+      target.removeEventListener('scroll', save);
+      clearTimeout(timeoutId);
+    };
+  }, [pathname, key, behavior, delay]);
+  return ref;
+}
+
+export { ToastContainer, Tooltip, toast, useScrollRestoration };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitzo",
-  "version": "2.1.10",
+  "version": "2.1.12",
   "description": "A lightweight JavaScript UI micro-library.",
   "type": "module",
   "main": "./dist/kitzo.umd.js",