@mateosuarezdev/react-ui 1.0.29 → 1.0.30

package/dist/index.d.ts

@@ -19,6 +19,7 @@ import { ForwardRefExoticComponent } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { Locale } from 'date-fns';
+import { MotionValue } from 'motion/react';
 import { MouseEventHandler } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
@@ -201,6 +202,34 @@ export declare const DateTimePicker: () => JSX.Element;
  */
 export declare function debounce<T extends (...args: any[]) => any>(func: T, delay?: number): (...args: Parameters<T>) => void;
 
+/**
+ * ElasticHeader - Creates a pull-to-zoom effect on scroll
+ *
+ * When the user scrolls/pulls down past the top of the page (negative scrollY),
+ * this component scales up and translates the element to create a natural
+ * "stretchy" parallax effect commonly seen in mobile apps.
+ *
+ * The scaling factor is proportional to the element's height - pulling the full
+ * height of the element will result in 2x scale (doubled size).
+ *
+ * @example
+ * const y = useMotionValue(0);
+ *
+ * <ElasticHeader scrollY={y} height={300} className="header-image">
+ *   <img src="profile.jpg" />
+ * </ElasticHeader>
+ */
+export declare const ElasticHeader: ({ scrollY, height, className, children, }: {
+    scrollY: MotionValue<number>;
+    /**
+     * Height of the element in pixels
+     * defaults to 300
+     */
+    height: number;
+    className?: string;
+    children?: React.ReactNode;
+}) => JSX.Element;
+
 /**
  * Extracts only the dirty fields from form data
  * @param data The complete form data
@@ -447,6 +476,11 @@ declare type OverflowInfo = {
 export declare const PageScroller: default_2.FC<PageScrollerProps>;
 
 declare interface PageScrollerProps {
+    /**
+     * Scroller or page/route specific id
+     * can be get from const { id } = useRoute() in my routers
+     */
+    id: string;
     tabPage?: boolean;
     /**
      * If to position the outer page element as absolute
@@ -462,6 +496,10 @@ declare interface PageScrollerProps {
     contentClassName?: string;
     bounceBackDuration?: number;
     showScrollbar?: boolean;
+    /**
+     * Custom MotionValue to track externally
+     */
+    onScroll?: (currentY: number) => void;
 }
 
 export declare const PageTitle: ({ title, description, size, descriptionClassName, className, }: {
@@ -863,4 +901,67 @@ export declare const useRipple: <T extends HTMLElement>(enabled?: boolean, contr
     styles: CSSProperties;
 };
 
+export declare function useScroller<T extends HTMLElement>({ id, showScrollbar, onRefresh, bounceBackDuration, isolate, onScroll, }: UseScrollerProps): UseScrollerReturn<T>;
+
+export declare interface UseScrollerProps {
+    id?: string;
+    showScrollbar?: boolean;
+    onRefresh?: () => Promise<void>;
+    bounceBackDuration?: number;
+    /**
+     * When to use isolate: true
+     * ✅ Page/Route level scrollers with absolute positioning
+     * ✅ When implementing the native mobile stack navigation pattern
+     * ✅ When you need to prevent z-index conflicts between different "pages"
+     * When to use isolate: false (default)
+     * ✅ Nested scrollers within a page (like a scrollable section)
+     * ✅ Modal/dialog content scrollers
+     * ✅ Dropdown/popover scrollers
+     * ✅ Any scroller where child elements need to participate in parent stacking contexts (e.g., tooltips, dropdowns that need to escape)
+     */
+    isolate?: boolean;
+    onScroll?: (currentY: number) => void;
+}
+
+export declare interface UseScrollerReturn<T extends HTMLElement> {
+    container: {
+        props: {
+            id?: string;
+            ref: default_2.RefObject<T | null>;
+            key: string;
+        };
+        /**
+         * Base className to extend from
+         * <div {...container.props} className={container.classNames}></div>
+         */
+        classNames: string;
+    };
+    content: {
+        props: {
+            ref: default_2.RefObject<T | null>;
+        };
+        /**
+         * Base styles to extend from
+         * <div {...content.props} style={container.styles}></div>
+         */
+        styles: default_2.CSSProperties;
+    };
+    pullToRefresh: {
+        props: {
+            ref: default_2.RefObject<T | null>;
+        };
+        styles: default_2.CSSProperties;
+    };
+    scrollbar: {
+        props: {
+            ref: default_2.RefObject<T | null>;
+        };
+    };
+    refreshing: boolean;
+    updateMaxScroll: () => void;
+    rubberBandEffect: (y: number) => number;
+    updateScrollbarPosition: () => void;
+    setPosition: (y: number) => void;
+}
+
 export { }