@korsolutions/guidon 1.0.18 → 1.0.20

package/README.md

@@ -396,6 +396,69 @@ function GuidonStatus() {
 >
 ```
 
+## Auto-Scroll Behavior
+
+### Web
+On web, targets automatically scroll into view using the native `scrollIntoView()` API. You can customize this via theme:
+
+```tsx
+const config = {
+  theme: {
+    scrollOptions: {
+      behavior: 'smooth',  // 'smooth' | 'instant'
+      block: 'center',     // 'start' | 'center' | 'end' | 'nearest'
+      inline: 'nearest',   // 'start' | 'center' | 'end' | 'nearest'
+    },
+  },
+  tours: { ... },
+} satisfies GuidonToursConfig;
+```
+
+### Mobile (React Native)
+For mobile, use the `useGuidonScrollContainer` hook to enable auto-scrolling:
+
+```tsx
+import { useRef } from 'react';
+import { ScrollView } from 'react-native';
+import { useGuidon, useGuidonScrollContainer } from '@korsolutions/guidon';
+
+function MyScreen() {
+  const scrollRef = useRef<ScrollView>(null);
+  const { register } = useGuidon();
+
+  // Enable auto-scroll when steps change
+  useGuidonScrollContainer(scrollRef);
+
+  return (
+    <ScrollView ref={scrollRef}>
+      <View ref={register('step-1')}>First target</View>
+      <View ref={register('step-2')}>Second target</View>
+    </ScrollView>
+  );
+}
+```
+
+Options:
+```tsx
+useGuidonScrollContainer(scrollRef, {
+  padding: 150,    // Distance from top of viewport (default: 100)
+  enabled: false,  // Temporarily disable (default: true)
+});
+```
+
+### Disabling Scroll Per Step
+Disable auto-scroll for individual steps:
+
+```tsx
+{
+  id: 'modal-step',
+  targetId: 'modal-button',
+  title: 'Modal Content',
+  description: 'This element is already visible',
+  scrollIntoView: false,  // Don't scroll for this step
+}
+```
+
 ## Platform Support
 
 - iOS

package/dist/commonjs/hooks/index.js

@@ -9,5 +9,12 @@ Object.defineProperty(exports, "useGuidon", {
     return _useGuidonRef.useGuidon;
   }
 });
+Object.defineProperty(exports, "useGuidonScrollContainer", {
+  enumerable: true,
+  get: function () {
+    return _useGuidonScrollContainer.useGuidonScrollContainer;
+  }
+});
 var _useGuidonRef = require("./useGuidonRef.js");
+var _useGuidonScrollContainer = require("./useGuidonScrollContainer.js");
 //# sourceMappingURL=index.js.map

package/dist/commonjs/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_useGuidonRef","require"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;;;;;;;;;;AAAA,IAAAA,aAAA,GAAAC,OAAA","ignoreList":[]}
+{"version":3,"names":["_useGuidonRef","require","_useGuidonScrollContainer"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;;;;;;;;;;;;;;;;AAAA,IAAAA,aAAA,GAAAC,OAAA;AACA,IAAAC,yBAAA,GAAAD,OAAA","ignoreList":[]}

package/dist/commonjs/hooks/useGuidonScrollContainer.js

@@ -0,0 +1,60 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useGuidonScrollContainer = useGuidonScrollContainer;
+var _react = require("react");
+var _reactNative = require("react-native");
+var _store = require("../store.js");
+/**
+ * Scrollable container interface (ScrollView, FlatList, etc.)
+ */
+
+/**
+ * Hook that registers a ScrollView for auto-scrolling on mobile platforms.
+ * When a guidon step changes, automatically scrolls to bring the target into view.
+ *
+ * @param scrollViewRef - Ref to a ScrollView or FlatList
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const scrollRef = useRef<ScrollView>(null);
+ *   useGuidonScrollContainer(scrollRef);
+ *
+ *   return (
+ *     <ScrollView ref={scrollRef}>
+ *       <View ref={register('step-1')}>...</View>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+function useGuidonScrollContainer(scrollViewRef, options) {
+  const currentStepIndex = (0, _store.useGuidonStore)(s => s.currentStepIndex);
+  const config = (0, _store.useGuidonStore)(s => s.config);
+  const isActive = (0, _store.useGuidonStore)(s => s.isActive);
+  const targetMeasurements = (0, _store.useGuidonStore)(s => s.targetMeasurements);
+  const padding = options?.padding ?? 100;
+  const enabled = options?.enabled ?? true;
+  (0, _react.useEffect)(() => {
+    // Only handle mobile platforms - web uses native scrollIntoView
+    if (_reactNative.Platform.OS === "web" || !isActive || !config || !enabled) return;
+    const step = config.steps[currentStepIndex];
+    if (!step?.targetId || step.scrollIntoView === false) return;
+    const measurements = targetMeasurements[step.targetId];
+    if (!measurements) return;
+
+    // Small delay to ensure measurements are settled after step transition
+    const timeoutId = setTimeout(() => {
+      scrollViewRef.current?.scrollTo?.({
+        y: Math.max(0, measurements.y - padding),
+        animated: true
+      });
+    }, 50);
+    return () => clearTimeout(timeoutId);
+  }, [currentStepIndex, isActive, config, targetMeasurements, scrollViewRef, padding, enabled]);
+}
+//# sourceMappingURL=useGuidonScrollContainer.js.map

package/dist/commonjs/hooks/useGuidonScrollContainer.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_reactNative","_store","useGuidonScrollContainer","scrollViewRef","options","currentStepIndex","useGuidonStore","s","config","isActive","targetMeasurements","padding","enabled","useEffect","Platform","OS","step","steps","targetId","scrollIntoView","measurements","timeoutId","setTimeout","current","scrollTo","y","Math","max","animated","clearTimeout"],"sourceRoot":"../../../src","sources":["hooks/useGuidonScrollContainer.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAEA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,wBAAwBA,CACtCC,aAA8C,EAC9CC,OAAyC,EACzC;EACA,MAAMC,gBAAgB,GAAG,IAAAC,qBAAc,EAAEC,CAAC,IAAKA,CAAC,CAACF,gBAAgB,CAAC;EAClE,MAAMG,MAAM,GAAG,IAAAF,qBAAc,EAAEC,CAAC,IAAKA,CAAC,CAACC,MAAM,CAAC;EAC9C,MAAMC,QAAQ,GAAG,IAAAH,qBAAc,EAAEC,CAAC,IAAKA,CAAC,CAACE,QAAQ,CAAC;EAClD,MAAMC,kBAAkB,GAAG,IAAAJ,qBAAc,EAAEC,CAAC,IAAKA,CAAC,CAACG,kBAAkB,CAAC;EAEtE,MAAMC,OAAO,GAAGP,OAAO,EAAEO,OAAO,IAAI,GAAG;EACvC,MAAMC,OAAO,GAAGR,OAAO,EAAEQ,OAAO,IAAI,IAAI;EAExC,IAAAC,gBAAS,EAAC,MAAM;IACd;IACA,IAAIC,qBAAQ,CAACC,EAAE,KAAK,KAAK,IAAI,CAACN,QAAQ,IAAI,CAACD,MAAM,IAAI,CAACI,OAAO,EAAE;IAE/D,MAAMI,IAAI,GAAGR,MAAM,CAACS,KAAK,CAACZ,gBAAgB,CAAC;IAC3C,IAAI,CAACW,IAAI,EAAEE,QAAQ,IAAIF,IAAI,CAACG,cAAc,KAAK,KAAK,EAAE;IAEtD,MAAMC,YAAY,GAAGV,kBAAkB,CAACM,IAAI,CAACE,QAAQ,CAAC;IACtD,IAAI,CAACE,YAAY,EAAE;;IAEnB;IACA,MAAMC,SAAS,GAAGC,UAAU,CAAC,MAAM;MACjCnB,aAAa,CAACoB,OAAO,EAAEC,QAAQ,GAAG;QAChCC,CAAC,EAAEC,IAAI,CAACC,GAAG,CAAC,CAAC,EAAEP,YAAY,CAACK,CAAC,GAAGd,OAAO,CAAC;QACxCiB,QAAQ,EAAE;MACZ,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC;IAEN,OAAO,MAAMC,YAAY,CAACR,SAAS,CAAC;EACtC,CAAC,EAAE,CACDhB,gBAAgB,EAChBI,QAAQ,EACRD,MAAM,EACNE,kBAAkB,EAClBP,aAAa,EACbQ,OAAO,EACPC,OAAO,CACR,CAAC;AACJ","ignoreList":[]}

package/dist/commonjs/index.js

@@ -99,6 +99,12 @@ Object.defineProperty(exports, "useGuidonProgress", {
     return _store.useGuidonProgress;
   }
 });
+Object.defineProperty(exports, "useGuidonScrollContainer", {
+  enumerable: true,
+  get: function () {
+    return _index2.useGuidonScrollContainer;
+  }
+});
 Object.defineProperty(exports, "useGuidonStep", {
   enumerable: true,
   get: function () {

package/dist/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_index","require","_index2","_store","_adapters","_hooks"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,IAAAA,MAAA,GAAAC,OAAA;AASA,IAAAC,OAAA,GAAAD,OAAA;AAGA,IAAAE,MAAA,GAAAF,OAAA;AAmCA,IAAAG,SAAA,GAAAH,OAAA;AASA,IAAAI,MAAA,GAAAJ,OAAA","ignoreList":[]}
+{"version":3,"names":["_index","require","_index2","_store","_adapters","_hooks"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,IAAAA,MAAA,GAAAC,OAAA;AASA,IAAAC,OAAA,GAAAD,OAAA;AAOA,IAAAE,MAAA,GAAAF,OAAA;AAmCA,IAAAG,SAAA,GAAAH,OAAA;AASA,IAAAI,MAAA,GAAAJ,OAAA","ignoreList":[]}

package/dist/module/hooks/index.js

@@ -1,4 +1,5 @@
 "use strict";
 
 export { useGuidon } from "./useGuidonRef.js";
+export { useGuidonScrollContainer } from "./useGuidonScrollContainer.js";
 //# sourceMappingURL=index.js.map

package/dist/module/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["useGuidon"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;AAAA,SAASA,SAAS,QAAQ,mBAAgB","ignoreList":[]}
+{"version":3,"names":["useGuidon","useGuidonScrollContainer"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;AAAA,SAASA,SAAS,QAAQ,mBAAgB;AAC1C,SACEC,wBAAwB,QAEnB,+BAA4B","ignoreList":[]}

package/dist/module/hooks/useGuidonScrollContainer.js

@@ -0,0 +1,57 @@
+"use strict";
+
+import { useEffect } from "react";
+import { Platform } from "react-native";
+import { useGuidonStore } from "../store.js";
+
+/**
+ * Scrollable container interface (ScrollView, FlatList, etc.)
+ */
+
+/**
+ * Hook that registers a ScrollView for auto-scrolling on mobile platforms.
+ * When a guidon step changes, automatically scrolls to bring the target into view.
+ *
+ * @param scrollViewRef - Ref to a ScrollView or FlatList
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const scrollRef = useRef<ScrollView>(null);
+ *   useGuidonScrollContainer(scrollRef);
+ *
+ *   return (
+ *     <ScrollView ref={scrollRef}>
+ *       <View ref={register('step-1')}>...</View>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function useGuidonScrollContainer(scrollViewRef, options) {
+  const currentStepIndex = useGuidonStore(s => s.currentStepIndex);
+  const config = useGuidonStore(s => s.config);
+  const isActive = useGuidonStore(s => s.isActive);
+  const targetMeasurements = useGuidonStore(s => s.targetMeasurements);
+  const padding = options?.padding ?? 100;
+  const enabled = options?.enabled ?? true;
+  useEffect(() => {
+    // Only handle mobile platforms - web uses native scrollIntoView
+    if (Platform.OS === "web" || !isActive || !config || !enabled) return;
+    const step = config.steps[currentStepIndex];
+    if (!step?.targetId || step.scrollIntoView === false) return;
+    const measurements = targetMeasurements[step.targetId];
+    if (!measurements) return;
+
+    // Small delay to ensure measurements are settled after step transition
+    const timeoutId = setTimeout(() => {
+      scrollViewRef.current?.scrollTo?.({
+        y: Math.max(0, measurements.y - padding),
+        animated: true
+      });
+    }, 50);
+    return () => clearTimeout(timeoutId);
+  }, [currentStepIndex, isActive, config, targetMeasurements, scrollViewRef, padding, enabled]);
+}
+//# sourceMappingURL=useGuidonScrollContainer.js.map

package/dist/module/hooks/useGuidonScrollContainer.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useEffect","Platform","useGuidonStore","useGuidonScrollContainer","scrollViewRef","options","currentStepIndex","s","config","isActive","targetMeasurements","padding","enabled","OS","step","steps","targetId","scrollIntoView","measurements","timeoutId","setTimeout","current","scrollTo","y","Math","max","animated","clearTimeout"],"sourceRoot":"../../../src","sources":["hooks/useGuidonScrollContainer.ts"],"mappings":";;AAAA,SAASA,SAAS,QAAwB,OAAO;AACjD,SAASC,QAAQ,QAAQ,cAAc;AACvC,SAASC,cAAc,QAAQ,aAAU;;AAEzC;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,wBAAwBA,CACtCC,aAA8C,EAC9CC,OAAyC,EACzC;EACA,MAAMC,gBAAgB,GAAGJ,cAAc,CAAEK,CAAC,IAAKA,CAAC,CAACD,gBAAgB,CAAC;EAClE,MAAME,MAAM,GAAGN,cAAc,CAAEK,CAAC,IAAKA,CAAC,CAACC,MAAM,CAAC;EAC9C,MAAMC,QAAQ,GAAGP,cAAc,CAAEK,CAAC,IAAKA,CAAC,CAACE,QAAQ,CAAC;EAClD,MAAMC,kBAAkB,GAAGR,cAAc,CAAEK,CAAC,IAAKA,CAAC,CAACG,kBAAkB,CAAC;EAEtE,MAAMC,OAAO,GAAGN,OAAO,EAAEM,OAAO,IAAI,GAAG;EACvC,MAAMC,OAAO,GAAGP,OAAO,EAAEO,OAAO,IAAI,IAAI;EAExCZ,SAAS,CAAC,MAAM;IACd;IACA,IAAIC,QAAQ,CAACY,EAAE,KAAK,KAAK,IAAI,CAACJ,QAAQ,IAAI,CAACD,MAAM,IAAI,CAACI,OAAO,EAAE;IAE/D,MAAME,IAAI,GAAGN,MAAM,CAACO,KAAK,CAACT,gBAAgB,CAAC;IAC3C,IAAI,CAACQ,IAAI,EAAEE,QAAQ,IAAIF,IAAI,CAACG,cAAc,KAAK,KAAK,EAAE;IAEtD,MAAMC,YAAY,GAAGR,kBAAkB,CAACI,IAAI,CAACE,QAAQ,CAAC;IACtD,IAAI,CAACE,YAAY,EAAE;;IAEnB;IACA,MAAMC,SAAS,GAAGC,UAAU,CAAC,MAAM;MACjChB,aAAa,CAACiB,OAAO,EAAEC,QAAQ,GAAG;QAChCC,CAAC,EAAEC,IAAI,CAACC,GAAG,CAAC,CAAC,EAAEP,YAAY,CAACK,CAAC,GAAGZ,OAAO,CAAC;QACxCe,QAAQ,EAAE;MACZ,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC;IAEN,OAAO,MAAMC,YAAY,CAACR,SAAS,CAAC;EACtC,CAAC,EAAE,CACDb,gBAAgB,EAChBG,QAAQ,EACRD,MAAM,EACNE,kBAAkB,EAClBN,aAAa,EACbO,OAAO,EACPC,OAAO,CACR,CAAC;AACJ","ignoreList":[]}

package/dist/module/index.js

@@ -4,7 +4,7 @@
 export { GuidonTarget, GuidonOverlay, GuidonTooltip, GuidonProvider, useGuidonContext } from "./components/index.js";
 
 // Hooks
-export { useGuidon } from "./hooks/index.js";
+export { useGuidon, useGuidonScrollContainer } from "./hooks/index.js";
 
 // Store and API
 export { useGuidonStore, Guidon, useGuidonActive, useGuidonStep, useGuidonProgress, useTargetMeasurements, useWaitingState, useIsFloatingStep } from "./store.js";

package/dist/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["GuidonTarget","GuidonOverlay","GuidonTooltip","GuidonProvider","useGuidonContext","useGuidon","useGuidonStore","Guidon","useGuidonActive","useGuidonStep","useGuidonProgress","useTargetMeasurements","useWaitingState","useIsFloatingStep","createNoopAdapter","createMemoryAdapter","createLocalStorageAdapter","createAsyncStorageAdapter","createApiAdapter","createCompositeAdapter","useGuidonPersistence","useShouldShowGuidon"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;AACA,SACEA,YAAY,EACZC,aAAa,EACbC,aAAa,EACbC,cAAc,EACdC,gBAAgB,QACX,uBAAc;;AAErB;AACA,SAASC,SAAS,QAAQ,kBAAS;;AAEnC;AACA,SACEC,cAAc,EACdC,MAAM,EACNC,eAAe,EACfC,aAAa,EACbC,iBAAiB,EACjBC,qBAAqB,EACrBC,eAAe,EACfC,iBAAiB,QACZ,YAAS;;AAEhB;;AAuBA;AACA,SACEC,iBAAiB,EACjBC,mBAAmB,EACnBC,yBAAyB,EACzBC,yBAAyB,EACzBC,gBAAgB,EAChBC,sBAAsB,QACjB,2BAAwB;AAE/B,SAASC,oBAAoB,EAAEC,mBAAmB,QAAQ,wBAAqB","ignoreList":[]}
+{"version":3,"names":["GuidonTarget","GuidonOverlay","GuidonTooltip","GuidonProvider","useGuidonContext","useGuidon","useGuidonScrollContainer","useGuidonStore","Guidon","useGuidonActive","useGuidonStep","useGuidonProgress","useTargetMeasurements","useWaitingState","useIsFloatingStep","createNoopAdapter","createMemoryAdapter","createLocalStorageAdapter","createAsyncStorageAdapter","createApiAdapter","createCompositeAdapter","useGuidonPersistence","useShouldShowGuidon"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;AACA,SACEA,YAAY,EACZC,aAAa,EACbC,aAAa,EACbC,cAAc,EACdC,gBAAgB,QACX,uBAAc;;AAErB;AACA,SACEC,SAAS,EACTC,wBAAwB,QAEnB,kBAAS;;AAEhB;AACA,SACEC,cAAc,EACdC,MAAM,EACNC,eAAe,EACfC,aAAa,EACbC,iBAAiB,EACjBC,qBAAqB,EACrBC,eAAe,EACfC,iBAAiB,QACZ,YAAS;;AAEhB;;AAuBA;AACA,SACEC,iBAAiB,EACjBC,mBAAmB,EACnBC,yBAAyB,EACzBC,yBAAyB,EACzBC,gBAAgB,EAChBC,sBAAsB,QACjB,2BAAwB;AAE/B,SAASC,oBAAoB,EAAEC,mBAAmB,QAAQ,wBAAqB","ignoreList":[]}

package/dist/typescript/commonjs/hooks/index.d.ts

@@ -1,2 +1,3 @@
 export { useGuidon } from "./useGuidonRef";
+export { useGuidonScrollContainer, type UseGuidonScrollContainerOptions, } from "./useGuidonScrollContainer";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,4BAA4B,CAAC"}

package/dist/typescript/commonjs/hooks/useGuidonScrollContainer.d.ts

@@ -0,0 +1,41 @@
+import { type RefObject } from "react";
+/**
+ * Scrollable container interface (ScrollView, FlatList, etc.)
+ */
+type ScrollableRef = {
+    scrollTo?: (options: {
+        x?: number;
+        y: number;
+        animated?: boolean;
+    }) => void;
+};
+export interface UseGuidonScrollContainerOptions {
+    /** Padding from the top when scrolling to target (default: 100) */
+    padding?: number;
+    /** Whether scrolling is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Hook that registers a ScrollView for auto-scrolling on mobile platforms.
+ * When a guidon step changes, automatically scrolls to bring the target into view.
+ *
+ * @param scrollViewRef - Ref to a ScrollView or FlatList
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const scrollRef = useRef<ScrollView>(null);
+ *   useGuidonScrollContainer(scrollRef);
+ *
+ *   return (
+ *     <ScrollView ref={scrollRef}>
+ *       <View ref={register('step-1')}>...</View>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export declare function useGuidonScrollContainer(scrollViewRef: RefObject<ScrollableRef | null>, options?: UseGuidonScrollContainerOptions): void;
+export {};
+//# sourceMappingURL=useGuidonScrollContainer.d.ts.map

package/dist/typescript/commonjs/hooks/useGuidonScrollContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGuidonScrollContainer.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useGuidonScrollContainer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlD;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC9C,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,CAAC,EAC9C,OAAO,CAAC,EAAE,+BAA+B,QAsC1C"}

package/dist/typescript/commonjs/index.d.ts

@@ -1,5 +1,5 @@
 export { GuidonTarget, GuidonOverlay, GuidonTooltip, GuidonProvider, useGuidonContext, } from "./components";
-export { useGuidon } from "./hooks";
+export { useGuidon, useGuidonScrollContainer, type UseGuidonScrollContainerOptions, } from "./hooks";
 export { useGuidonStore, Guidon, useGuidonActive, useGuidonStep, useGuidonProgress, useTargetMeasurements, useWaitingState, useIsFloatingStep, } from "./store";
 export type { GuidonStep, GuidonConfig, GuidonTours, GuidonToursConfig, GuidonTourDefinition, GuidonTheme, GuidonScrollOptions, GuidonProgress, GuidonPersistenceAdapter, GuidonProviderProps, GuidonTargetProps, GuidonTooltipLabels, GuidonTooltipRenderProps, TooltipPosition, FloatingPosition, TargetMeasurements, GuidonState, GuidonActions, GuidonStore, } from "./types";
 export { createNoopAdapter, createMemoryAdapter, createLocalStorageAdapter, createAsyncStorageAdapter, createApiAdapter, createCompositeAdapter, } from "./persistence/adapters";

package/dist/typescript/commonjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/typescript/module/hooks/index.d.ts

@@ -1,2 +1,3 @@
 export { useGuidon } from "./useGuidonRef";
+export { useGuidonScrollContainer, type UseGuidonScrollContainerOptions, } from "./useGuidonScrollContainer";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,4BAA4B,CAAC"}

package/dist/typescript/module/hooks/useGuidonScrollContainer.d.ts

@@ -0,0 +1,41 @@
+import { type RefObject } from "react";
+/**
+ * Scrollable container interface (ScrollView, FlatList, etc.)
+ */
+type ScrollableRef = {
+    scrollTo?: (options: {
+        x?: number;
+        y: number;
+        animated?: boolean;
+    }) => void;
+};
+export interface UseGuidonScrollContainerOptions {
+    /** Padding from the top when scrolling to target (default: 100) */
+    padding?: number;
+    /** Whether scrolling is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Hook that registers a ScrollView for auto-scrolling on mobile platforms.
+ * When a guidon step changes, automatically scrolls to bring the target into view.
+ *
+ * @param scrollViewRef - Ref to a ScrollView or FlatList
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const scrollRef = useRef<ScrollView>(null);
+ *   useGuidonScrollContainer(scrollRef);
+ *
+ *   return (
+ *     <ScrollView ref={scrollRef}>
+ *       <View ref={register('step-1')}>...</View>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export declare function useGuidonScrollContainer(scrollViewRef: RefObject<ScrollableRef | null>, options?: UseGuidonScrollContainerOptions): void;
+export {};
+//# sourceMappingURL=useGuidonScrollContainer.d.ts.map

package/dist/typescript/module/hooks/useGuidonScrollContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGuidonScrollContainer.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useGuidonScrollContainer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlD;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC9C,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,CAAC,EAC9C,OAAO,CAAC,EAAE,+BAA+B,QAsC1C"}

package/dist/typescript/module/index.d.ts

@@ -1,5 +1,5 @@
 export { GuidonTarget, GuidonOverlay, GuidonTooltip, GuidonProvider, useGuidonContext, } from "./components";
-export { useGuidon } from "./hooks";
+export { useGuidon, useGuidonScrollContainer, type UseGuidonScrollContainerOptions, } from "./hooks";
 export { useGuidonStore, Guidon, useGuidonActive, useGuidonStep, useGuidonProgress, useTargetMeasurements, useWaitingState, useIsFloatingStep, } from "./store";
 export type { GuidonStep, GuidonConfig, GuidonTours, GuidonToursConfig, GuidonTourDefinition, GuidonTheme, GuidonScrollOptions, GuidonProgress, GuidonPersistenceAdapter, GuidonProviderProps, GuidonTargetProps, GuidonTooltipLabels, GuidonTooltipRenderProps, TooltipPosition, FloatingPosition, TargetMeasurements, GuidonState, GuidonActions, GuidonStore, } from "./types";
 export { createNoopAdapter, createMemoryAdapter, createLocalStorageAdapter, createAsyncStorageAdapter, createApiAdapter, createCompositeAdapter, } from "./persistence/adapters";

package/dist/typescript/module/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,SAAS,EACT,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korsolutions/guidon",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "A cross-platform walkthrough/onboarding component library for React Native with web support. Features spotlight effects, customizable tooltips, and flexible persistence options. ",
   "repository": "https://github.com/KorSoftwareSolutions/guidon.git",
   "author": "Christian Jimenez <christianjimenezfael@gmail.com>",

package/src/hooks/index.ts

@@ -1 +1,5 @@
 export { useGuidon } from "./useGuidonRef";
+export {
+  useGuidonScrollContainer,
+  type UseGuidonScrollContainerOptions,
+} from "./useGuidonScrollContainer";

package/src/hooks/useGuidonScrollContainer.ts

@@ -0,0 +1,80 @@
+import { useEffect, type RefObject } from "react";
+import { Platform } from "react-native";
+import { useGuidonStore } from "../store";
+
+/**
+ * Scrollable container interface (ScrollView, FlatList, etc.)
+ */
+type ScrollableRef = {
+  scrollTo?: (options: { x?: number; y: number; animated?: boolean }) => void;
+};
+
+export interface UseGuidonScrollContainerOptions {
+  /** Padding from the top when scrolling to target (default: 100) */
+  padding?: number;
+  /** Whether scrolling is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Hook that registers a ScrollView for auto-scrolling on mobile platforms.
+ * When a guidon step changes, automatically scrolls to bring the target into view.
+ *
+ * @param scrollViewRef - Ref to a ScrollView or FlatList
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const scrollRef = useRef<ScrollView>(null);
+ *   useGuidonScrollContainer(scrollRef);
+ *
+ *   return (
+ *     <ScrollView ref={scrollRef}>
+ *       <View ref={register('step-1')}>...</View>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function useGuidonScrollContainer(
+  scrollViewRef: RefObject<ScrollableRef | null>,
+  options?: UseGuidonScrollContainerOptions,
+) {
+  const currentStepIndex = useGuidonStore((s) => s.currentStepIndex);
+  const config = useGuidonStore((s) => s.config);
+  const isActive = useGuidonStore((s) => s.isActive);
+  const targetMeasurements = useGuidonStore((s) => s.targetMeasurements);
+
+  const padding = options?.padding ?? 100;
+  const enabled = options?.enabled ?? true;
+
+  useEffect(() => {
+    // Only handle mobile platforms - web uses native scrollIntoView
+    if (Platform.OS === "web" || !isActive || !config || !enabled) return;
+
+    const step = config.steps[currentStepIndex];
+    if (!step?.targetId || step.scrollIntoView === false) return;
+
+    const measurements = targetMeasurements[step.targetId];
+    if (!measurements) return;
+
+    // Small delay to ensure measurements are settled after step transition
+    const timeoutId = setTimeout(() => {
+      scrollViewRef.current?.scrollTo?.({
+        y: Math.max(0, measurements.y - padding),
+        animated: true,
+      });
+    }, 50);
+
+    return () => clearTimeout(timeoutId);
+  }, [
+    currentStepIndex,
+    isActive,
+    config,
+    targetMeasurements,
+    scrollViewRef,
+    padding,
+    enabled,
+  ]);
+}

package/src/index.ts

@@ -8,7 +8,11 @@ export {
 } from "./components";
 
 // Hooks
-export { useGuidon } from "./hooks";
+export {
+  useGuidon,
+  useGuidonScrollContainer,
+  type UseGuidonScrollContainerOptions,
+} from "./hooks";
 
 // Store and API
 export {