scroll-system 1.0.1 → 1.1.0

package/README.md

@@ -13,15 +13,28 @@ Built for high-performance marketing sites, portfolios, and web apps that requir
 
 | Feature | Description |
 |---------|-------------|
-| **Snap Views** | 3 specialized view types: `FullView`, `ScrollLockedView`, `ControlledView` |
+| **Snap Views** | 4 view types: `FullView`, `ScrollLockedView`, `ControlledView`, `NestedScrollView` |
 | **1:1 Touch Physics** | Native-feeling drag interaction on mobile (like TikTok/Reels) |
 | **Deterministic Locking** | Smart state machine handles mixed content without bugs |
 | **Accessibility** | Focus management, keyboard navigation, screen reader announcements |
 | **Deep Linking** | URL hash synchronization (`#about`, `#contact`) |
 | **Horizontal Support** | Works in both vertical and horizontal orientations |
-| **Performance** | Lazy loading support and throttled event listeners |
+| **Performance** | Lazy loading, view preloading, throttled event listeners |
 | **Analytics** | Built-in view engagement tracking |
 
+### ✨ New in v1.1.0
+
+| Feature | Description |
+|---------|-------------|
+| **AutoScroll** | Automatic view advancement (carousel mode) |
+| **Infinite Scroll** | Loop from last to first view |
+| **Snap Points** | Multiple "stops" within a single view |
+| **Parallax Effects** | Smooth parallax animations |
+| **Gesture Customization** | Configurable swipe thresholds and velocities |
+| **Global Progress** | Track progress across all views |
+| **Programmatic Lock** | Lock/unlock navigation programmatically |
+| **Auto Mobile Optimization** | Automatically prevents pull-to-refresh |
+
 ---
 
 ## 📦 Installation
@@ -126,8 +139,14 @@ The root wrapper component. Manages viewport, event listeners, and global state.
 | `hashPushHistory` | `boolean` | `false` | Use `pushState` instead of `replaceState` |
 | `enableFocusManagement` | `boolean` | `true` | Move focus to active view for a11y |
 | `respectReducedMotion` | `boolean` | `true` | Disable animations if OS prefers |
-| `onViewChange` | `(from: number, to: number) => void` | - | Callback when view changes |
+| `onViewChange` | `(from, to) => void` | - | Callback when view changes |
 | `onInitialized` | `() => void` | - | Callback when system initializes |
+| `skipInitialAnimation` | `boolean` | `false` | Skip animation on first render |
+| `onProgress` | `(progress: number) => void` | - | Global progress callback (0-1) |
+| `gestureConfig` | `GestureConfig` | - | Customize swipe thresholds |
+| `autoScroll` | `AutoScrollConfig` | - | Enable automatic view advancement |
+| `infiniteScroll` | `boolean \| InfiniteScrollConfig` | `false` | Loop from last to first |
+| `preload` | `boolean \| PreloadConfig` | `true` | Preload adjacent views |
 
 ---
 
@@ -317,6 +336,122 @@ return (
 
 ---
 
+## 🆕 New Hooks (v1.1.0)
+
+### `useGlobalProgress(options)`
+
+Track global scroll progress across all views.
+
+```tsx
+const { progress, percentage, activeIndex } = useGlobalProgress({
+  onProgress: (p) => console.log(`${p * 100}% complete`)
+});
+
+return <ProgressBar value={percentage} />;
+```
+
+---
+
+### `useScrollLock()`
+
+Programmatic control for locking/unlocking navigation.
+
+```tsx
+const { lock, unlock, isLocked, lockView, unlockView } = useScrollLock();
+
+const openModal = () => {
+  lock(); // Prevents all navigation
+  setModalOpen(true);
+};
+```
+
+---
+
+### `useAutoScroll(config)`
+
+Enable automatic view advancement (carousel mode).
+
+```tsx
+const { isPlaying, pause, resume, toggle } = useAutoScroll({
+  enabled: true,
+  interval: 4000,
+  pauseOnInteraction: true,
+  resumeDelay: 3000,
+});
+
+return (
+  <button onClick={toggle}>
+    {isPlaying ? '⏸️ Pause' : '▶️ Play'}
+  </button>
+);
+```
+
+---
+
+### `useInfiniteScroll(config)`
+
+Enable looping from last view to first.
+
+```tsx
+const { isEnabled, toggle } = useInfiniteScroll({ enabled: true });
+
+// Or simply:
+useInfiniteScroll(true);
+```
+
+---
+
+### `useParallax(viewId, config)`
+
+Create parallax effects within views.
+
+```tsx
+function HeroSection() {
+  const { style } = useParallax("hero", { speed: 0.3 });
+  
+  return (
+    <div style={style}>
+      <img src="/background.jpg" alt="Background" />
+    </div>
+  );
+}
+```
+
+---
+
+### `useSnapPoints(options)`
+
+Manage multiple "stops" within a single view.
+
+```tsx
+const snapPoints = [
+  { id: 'intro', position: 0 },
+  { id: 'features', position: 0.33 },
+  { id: 'pricing', position: 0.66 },
+  { id: 'cta', position: 1 },
+];
+
+const { activePoint, goToNextPoint, points } = useSnapPoints({
+  viewId: 'landing',
+  points: snapPoints,
+});
+```
+
+---
+
+### `usePreload(config)`
+
+Control view preloading for smoother transitions.
+
+```tsx
+const { shouldPreload, preloadedViewIds } = usePreload({
+  ahead: 2,  // Preload 2 views ahead
+  behind: 1, // Preload 1 view behind
+});
+```
+
+---
+
 ## ⌨️ Keyboard Navigation
 
 Built-in keyboard support for accessibility:

package/dist/components/AriaLiveRegion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Scroll System - Aria Live Region
+ * ==================================
+ * Announces view changes to screen readers.
+ */
+export interface AriaLiveRegionProps {
+    /** Custom announcement template. Use {viewIndex} and {viewId} as placeholders */
+    template?: string;
+    /** Politeness level for announcements */
+    politeness?: "polite" | "assertive";
+}
+/**
+ * Invisible component that announces view changes to screen readers.
+ * Place inside ScrollContainer.
+ */
+export declare function AriaLiveRegion({ template, politeness, }: AriaLiveRegionProps): import("react/jsx-runtime").JSX.Element;
+export default AriaLiveRegion;
+//# sourceMappingURL=AriaLiveRegion.d.ts.map

package/dist/components/AriaLiveRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AriaLiveRegion.d.ts","sourceRoot":"","sources":["../../components/AriaLiveRegion.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,QAA6D,EAC7D,UAAqB,GACtB,EAAE,mBAAmB,2CA8CrB;AAED,eAAe,cAAc,CAAC"}

package/dist/components/ControlledView.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PABRIX Scroll System - Controlled View
+ * =======================================
+ * Vista controlada programáticamente.
+ * La navegación se controla mediante acciones explícitas al Store.
+ */
+import type { ControlledViewProps } from "../types";
+export declare function ControlledView({ id, children, className, scrollDirection, allowInternalScroll, canProceed, allowGoBack, onActivate, onDeactivate, onEnterStart, onEnterEnd, onExitStart, onExitEnd, }: ControlledViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function useViewControl(viewId: string): {
+    unlock: () => void;
+    lock: () => void;
+    goNext: () => void;
+    goPrev: () => void;
+    goTo: (to: number | string) => void;
+};
+//# sourceMappingURL=ControlledView.d.ts.map

package/dist/components/ControlledView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControlledView.d.ts","sourceRoot":"","sources":["../../components/ControlledView.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,UAAU,CAAC;AAE1E,wBAAgB,cAAc,CAAC,EAC7B,EAAE,EACF,QAAQ,EACR,SAAc,EACd,eAAwB,EACxB,mBAA2B,EAC3B,UAAkB,EAClB,WAAkB,EAClB,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE,mBAAmB,2CAqErB;AAMD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM;;;;;eAc5B,MAAM,GAAG,MAAM;EAI/B"}

package/dist/components/FullView.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Scroll System - Full View
+ * =================================
+ * Vista de pantalla completa sin scroll interno.
+ * Cualquier scroll pasa directamente a la siguiente vista.
+ */
+import type { FullViewProps } from "../types";
+/**
+ * Vista que ocupa el 100% del viewport sin scroll interno.
+ * Ideal para hero sections, splash screens, o secciones de impacto visual.
+ *
+ * @example
+ * ```tsx
+ * <FullView id="hero">
+ *   <h1>Welcome to PABRIX</h1>
+ * </FullView>
+ * ```
+ */
+export declare function FullView({ id, children, className, meta, onActivate, onDeactivate, onEnterStart, onEnterEnd, onExitStart, onExitEnd, }: FullViewProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FullView.d.ts.map

package/dist/components/FullView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FullView.d.ts","sourceRoot":"","sources":["../../components/FullView.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,UAAU,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EACvB,EAAE,EACF,QAAQ,EACR,SAAc,EACd,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE,aAAa,2CAyCf"}

package/dist/components/LazyView.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Scroll System - Lazy View Wrapper
+ * ===================================
+ * Wrapper that only renders children when the view is within the
+ * active range (current +/- buffer).
+ */
+import React from "react";
+export interface LazyViewProps {
+    /** The view ID to track */
+    viewId: string;
+    /** Number of views before/after active to render (default: 1) */
+    buffer?: number;
+    /** Content to render when lazy loading */
+    children: React.ReactNode;
+    /** Placeholder to show when not in range */
+    placeholder?: React.ReactNode;
+}
+/**
+ * Wraps view content to only render when within the active range.
+ * Improves performance for apps with many views.
+ *
+ * @example
+ * ```tsx
+ * <FullView id="section-3">
+ *   <LazyView viewId="section-3">
+ *     <HeavyComponent />
+ *   </LazyView>
+ * </FullView>
+ * ```
+ */
+export declare function LazyView({ viewId, buffer, children, placeholder, }: LazyViewProps): import("react/jsx-runtime").JSX.Element;
+export default LazyView;
+//# sourceMappingURL=LazyView.d.ts.map

package/dist/components/LazyView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyView.d.ts","sourceRoot":"","sources":["../../components/LazyView.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAkB,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,EACvB,MAAM,EACN,MAAU,EACV,QAAQ,EACR,WAAkB,GACnB,EAAE,aAAa,2CAmBf;AAED,eAAe,QAAQ,CAAC"}

package/dist/components/NestedScrollView.d.ts

@@ -0,0 +1,38 @@
+/**
+ * NestedScrollView Component
+ * ========================================
+ * Enables nested scroll areas within views.
+ * Handles scroll direction isolation to prevent interference with main navigation.
+ */
+import React from "react";
+import type { NestedScrollViewProps } from "../types";
+/**
+ * A view component that supports nested scrolling perpendicular to main navigation.
+ * Perfect for horizontal carousels within a vertical scroll system.
+ *
+ * @example
+ * ```tsx
+ * <NestedScrollView
+ *   id="gallery"
+ *   nestedDirection="horizontal"
+ *   enableSnap={true}
+ *   onItemChange={(index) => console.log('Active item:', index)}
+ * >
+ *   <div className="flex">
+ *     <div className="w-screen flex-shrink-0">Item 1</div>
+ *     <div className="w-screen flex-shrink-0">Item 2</div>
+ *     <div className="w-screen flex-shrink-0">Item 3</div>
+ *   </div>
+ * </NestedScrollView>
+ * ```
+ */
+export declare function NestedScrollView({ id, children, className, nestedDirection, enableSnap, onItemChange, onActivate, onDeactivate, onEnterStart, onEnterEnd, onExitStart, onExitEnd, }: NestedScrollViewProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Helper component for items within NestedScrollView.
+ * Ensures proper sizing and snap behavior.
+ */
+export declare function NestedScrollItem({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=NestedScrollView.d.ts.map

package/dist/components/NestedScrollView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NestedScrollView.d.ts","sourceRoot":"","sources":["../../components/NestedScrollView.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAmD,MAAM,OAAO,CAAC;AAGxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,QAAQ,EACR,SAAc,EACd,eAA8B,EAC9B,UAAiB,EACjB,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE,qBAAqB,2CAmIvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAc,GACf,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,2CAYA"}

package/dist/components/ScrollContainer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Scroll System - Scroll Container
+ * ========================================
+ * Contenedor principal del sistema de scroll.
+ * Maneja la disposición de vistas y eventos de navegación.
+ */
+import type { ScrollContainerProps } from "../types";
+export declare function ScrollContainer({ children, className, transitionDuration, transitionEasing, onViewChange, onInitialized, enableHashSync, hashPushHistory, hashPrefix, respectReducedMotion, enableFocusManagement, enableDragPhysics, orientation, skipInitialAnimation, onProgress, gestureConfig, autoScroll, infiniteScroll, preload, }: ScrollContainerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ScrollContainer.d.ts.map

package/dist/components/ScrollContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollContainer.d.ts","sourceRoot":"","sources":["../../components/ScrollContainer.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,OAAO,KAAK,EAAE,oBAAoB,EAAmC,MAAM,UAAU,CAAC;AAEtF,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,SAAc,EACd,kBAAgD,EAChD,gBAA4C,EAC5C,YAAY,EACZ,aAAa,EAEb,cAAsB,EACtB,eAAuB,EACvB,UAAe,EAEf,oBAA2B,EAC3B,qBAA4B,EAE5B,iBAAyB,EAEzB,WAAwB,EAExB,oBAA4B,EAC5B,UAAU,EACV,aAAa,EACb,UAAU,EACV,cAAsB,EACtB,OAAc,GACf,EAAE,oBAAoB,2CA6KtB"}

package/dist/components/ScrollDebugOverlay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Scroll System - Debug Overlay
+ * ===============================
+ * Visual debugging component for the scroll system.
+ * Shows internal state in real-time for development.
+ *
+ * Usage: <ScrollDebugOverlay /> inside ScrollContainer
+ */
+interface ScrollDebugOverlayProps {
+    /** Position of the overlay (default: "bottom-left") */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Show/hide the overlay (default: true) */
+    visible?: boolean;
+}
+export declare function ScrollDebugOverlay({ position, visible, }: ScrollDebugOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export default ScrollDebugOverlay;
+//# sourceMappingURL=ScrollDebugOverlay.d.ts.map

package/dist/components/ScrollDebugOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollDebugOverlay.d.ts","sourceRoot":"","sources":["../../components/ScrollDebugOverlay.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,UAAU,uBAAuB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;IACrE,4CAA4C;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAwB,EACxB,OAAc,GACf,EAAE,uBAAuB,kDAiEzB;AA8BD,eAAe,kBAAkB,CAAC"}

package/dist/components/ScrollLockedView.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Scroll System - Scroll Locked View
+ * ==========================================
+ * Vista con scroll interno.
+ * Responsabilidad ÚNICA: Medir y reportar métricas al Store (vía hook).
+ * NO decide si bloquear o no.
+ */
+import type { ScrollLockedViewProps } from "../types";
+export declare function ScrollLockedView({ id, children, className, scrollDirection, scrollEndThreshold, onScrollProgress, onActivate, onDeactivate, onEnterStart, onEnterEnd, onExitStart, onExitEnd, }: ScrollLockedViewProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ScrollLockedView.d.ts.map

package/dist/components/ScrollLockedView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollLockedView.d.ts","sourceRoot":"","sources":["../../components/ScrollLockedView.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,QAAQ,EACR,SAAc,EACd,eAA4B,EAC5B,kBAAyB,EACzB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE,qBAAqB,2CA8CvB"}

package/dist/components/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./ScrollContainer";
+export * from "./FullView";
+export * from "./ScrollLockedView";
+export * from "./ControlledView";
+export * from "./ScrollDebugOverlay";
+export * from "./AriaLiveRegion";
+export * from "./LazyView";
+export * from "./NestedScrollView";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../components/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PABRIX Scroll System - Constants
+ * =================================
+ */
+export declare const DEFAULT_TRANSITION_DURATION = 700;
+export declare const DEFAULT_TRANSITION_EASING = "cubic-bezier(0.645, 0.045, 0.355, 1.000)";
+export declare const DEFAULT_SCROLL_END_THRESHOLD = 0.99;
+export declare const DEFAULT_PROGRESS_DEBOUNCE = 16;
+export declare const NAVIGATION_COOLDOWN = 500;
+export declare const NAV_THRESHOLDS: {
+    WHEEL: number;
+    TOUCH: number;
+};
+export declare const MIN_SWIPE_DISTANCE = 50;
+export declare const MIN_SWIPE_VELOCITY = 0.3;
+export declare const SCROLL_INTENT_THRESHOLD = 40;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,yBAAyB,6CAA6C,CAAC;AAGpF,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAG5C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAGvC,eAAO,MAAM,cAAc;;;CAG1B,CAAC;AAGF,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,uBAAuB,KAAK,CAAC"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./useNavigation";
+export * from "./useViewProgress";
+export * from "./useWheelHandler";
+export * from "./useTouchHandler";
+export * from "./useKeyboardHandler";
+export * from "./useHashSync";
+export * from "./useDragHandler";
+export * from "./useFocusManagement";
+export * from "./useScrollAnalytics";
+export * from "./useViewRegistration";
+export * from "./useScrollSystem";
+export * from "./useMetricsReporter";
+export * from "./useGlobalProgress";
+export * from "./useScrollLock";
+export * from "./usePreload";
+export * from "./useAutoScroll";
+export * from "./useParallax";
+export * from "./useSnapPoints";
+export * from "./useInfiniteScroll";
+export * from "./useGestureConfig";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../hooks/index.ts"],"names":[],"mappings":"AACA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC"}

package/dist/hooks/useAutoScroll.d.ts

@@ -0,0 +1,41 @@
+/**
+ * useAutoScroll Hook
+ * ========================================
+ * Enables automatic view advancement (carousel/autoplay functionality).
+ * Respects user interaction and can be paused/resumed programmatically.
+ */
+import type { AutoScrollConfig } from "../types";
+export interface AutoScrollState {
+    /** Whether auto-scroll is currently active (not paused) */
+    isPlaying: boolean;
+    /** Whether auto-scroll is paused due to user interaction */
+    isPaused: boolean;
+    /** Manually pause auto-scroll */
+    pause: () => void;
+    /** Manually resume auto-scroll */
+    resume: () => void;
+    /** Toggle play/pause state */
+    toggle: () => void;
+    /** Reset the interval timer */
+    reset: () => void;
+}
+/**
+ * Hook to enable automatic view advancement.
+ *
+ * @example
+ * ```tsx
+ * const { isPlaying, pause, resume } = useAutoScroll({
+ *   enabled: true,
+ *   interval: 4000,
+ *   pauseOnInteraction: true,
+ * });
+ *
+ * return (
+ *   <button onClick={isPlaying ? pause : resume}>
+ *     {isPlaying ? 'Pause' : 'Play'}
+ *   </button>
+ * );
+ * ```
+ */
+export declare function useAutoScroll(config: AutoScrollConfig): AutoScrollState;
+//# sourceMappingURL=useAutoScroll.d.ts.map

package/dist/hooks/useAutoScroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAutoScroll.d.ts","sourceRoot":"","sources":["../../hooks/useAutoScroll.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAWjD,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,kCAAkC;IAClC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAmJvE"}

package/dist/hooks/useDragHandler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scroll System - Drag Handler (Touch Physics)
+ * ==============================================
+ * Implements 1:1 direct manipulation for touch devices.
+ *
+ * Features:
+ * - Real-time tracking of finger position
+ * - Outputs dragOffset for visual feedback
+ * - Spring-based release detection (snap vs. proceed)
+ *
+ * This hook works alongside useTouchHandler which handles discrete swipes.
+ */
+export interface DragState {
+    isDragging: boolean;
+    dragOffset: number;
+    dragDirection: "up" | "down" | null;
+}
+export interface UseDragHandlerOptions {
+    /** Enable/disable drag handling (default: true) */
+    enabled?: boolean;
+    /** Callback when drag state changes */
+    onDragUpdate?: (state: DragState) => void;
+    /** Callback when drag completes with navigation decision */
+    onDragEnd?: (shouldNavigate: boolean, direction: "up" | "down") => void;
+}
+export declare function useDragHandler(options?: UseDragHandlerOptions): DragState;
+export default useDragHandler;
+//# sourceMappingURL=useDragHandler.d.ts.map

package/dist/hooks/useDragHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDragHandler.d.ts","sourceRoot":"","sources":["../../hooks/useDragHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C,4DAA4D;IAC5D,SAAS,CAAC,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,KAAK,IAAI,CAAC;CACzE;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,aAoJjE;AAED,eAAe,cAAc,CAAC"}

package/dist/hooks/useFocusManagement.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Scroll System - Focus Management Hook
+ * ======================================
+ * Manages focus when navigating between views.
+ * Moves focus to the active view section for screen reader accessibility.
+ */
+export interface UseFocusManagementOptions {
+    /** Enable/disable focus management (default: true) */
+    enabled?: boolean;
+    /** Delay before moving focus (after transition) */
+    focusDelay?: number;
+}
+/**
+ * Hook that manages keyboard focus when views change.
+ * Should be called once in ScrollContainer.
+ */
+export declare function useFocusManagement(options?: UseFocusManagementOptions): void;
+export default useFocusManagement;
+//# sourceMappingURL=useFocusManagement.d.ts.map

package/dist/hooks/useFocusManagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusManagement.d.ts","sourceRoot":"","sources":["../../hooks/useFocusManagement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,QAiCzE;AAED,eAAe,kBAAkB,CAAC"}

package/dist/hooks/useGestureConfig.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useGestureConfig Hook
+ * ========================================
+ * Manages gesture configuration for scroll interactions.
+ * Allows customization of swipe thresholds, velocities, and input methods.
+ */
+import type { GestureConfig } from "../types";
+declare const DEFAULT_GESTURE_CONFIG: Required<GestureConfig>;
+export declare const GestureConfigContext: import("react").Context<Required<GestureConfig>>;
+/**
+ * Hook to access gesture configuration.
+ *
+ * @example
+ * ```tsx
+ * const { swipeThreshold, swipeVelocity } = useGestureConfig();
+ *
+ * // In touch handler:
+ * if (Math.abs(deltaY) > swipeThreshold || velocity > swipeVelocity) {
+ *   navigate();
+ * }
+ * ```
+ */
+export declare function useGestureConfig(): Required<GestureConfig>;
+/**
+ * Merge user config with defaults.
+ */
+export declare function mergeGestureConfig(config?: GestureConfig): Required<GestureConfig>;
+/**
+ * Check if a gesture exceeds the threshold.
+ */
+export declare function isGestureTriggered(config: GestureConfig, deltaX: number, deltaY: number, velocity: number, direction: "vertical" | "horizontal"): boolean;
+/**
+ * Calculate resistance factor for boundary dragging.
+ */
+export declare function calculateResistance(config: GestureConfig, offset: number, isAtBoundary: boolean): number;
+export { DEFAULT_GESTURE_CONFIG };
+//# sourceMappingURL=useGestureConfig.d.ts.map

package/dist/hooks/useGestureConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGestureConfig.d.ts","sourceRoot":"","sources":["../../hooks/useGestureConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,QAAA,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAOnD,CAAC;AAGF,eAAO,MAAM,oBAAoB,kDAAiE,CAAC;AAEnG;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAE1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,CAAC,EAAE,aAAa,GACrB,QAAQ,CAAC,aAAa,CAAC,CAKzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,UAAU,GAAG,YAAY,GACnC,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,GACpB,MAAM,CAQR;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/hooks/useGlobalProgress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useGlobalProgress Hook
+ * ========================================
+ * Reports global scroll progress across all views.
+ * Progress is calculated as: (activeIndex + viewProgress) / totalViews
+ */
+export interface UseGlobalProgressOptions {
+    /** Callback when progress changes */
+    onProgress?: (progress: number) => void;
+    /** Throttle updates in ms (default: 16 for 60fps) */
+    throttle?: number;
+}
+export interface GlobalProgressState {
+    /** Current global progress 0-1 */
+    progress: number;
+    /** Current active view index */
+    activeIndex: number;
+    /** Total number of views */
+    totalViews: number;
+    /** Progress percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Hook to track global scroll progress across all views.
+ *
+ * @example
+ * ```tsx
+ * const { progress, percentage } = useGlobalProgress({
+ *   onProgress: (p) => console.log(`Progress: ${p * 100}%`)
+ * });
+ *
+ * return <ProgressBar value={percentage} />;
+ * ```
+ */
+export declare function useGlobalProgress(options?: UseGlobalProgressOptions): GlobalProgressState;
+//# sourceMappingURL=useGlobalProgress.d.ts.map

package/dist/hooks/useGlobalProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGlobalProgress.d.ts","sourceRoot":"","sources":["../../hooks/useGlobalProgress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,mBAAmB,CA0BrB"}

package/dist/hooks/useHashSync.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Scroll System - Hash Sync Handler
+ * ==========================================
+ * Synchronizes active view with URL hash for deep linking.
+ *
+ * Features:
+ * - Updates URL hash when view changes (pushState or replaceState)
+ * - Navigates to view when URL hash changes (popstate)
+ * - Handles initial load navigation based on hash
+ *
+ * Usage:
+ *   useHashSync({ enabled: true, pushHistory: true })
+ */
+export interface UseHashSyncOptions {
+    /** Enable/disable hash syncing (default: true) */
+    enabled?: boolean;
+    /** Use pushState (true) or replaceState (false) for hash updates (default: false) */
+    pushHistory?: boolean;
+    /** Prefix for hash (e.g., "view-" creates "#view-0") (default: "") */
+    hashPrefix?: string;
+}
+export declare function useHashSync(options?: UseHashSyncOptions): void;
+export default useHashSync;
+//# sourceMappingURL=useHashSync.d.ts.map

package/dist/hooks/useHashSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHashSync.d.ts","sourceRoot":"","sources":["../../hooks/useHashSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,QAoF3D;AAED,eAAe,WAAW,CAAC"}