Add jump options interface and implement customizable scroll behavior in VTour component

Author: AdamDrewsTR

docs/guide/jump-options.md

@@ -0,0 +1,169 @@
+# Jump Options
+
+VueJS Tour now supports customizable scroll animation options via the [jump.js](https://github.com/callmecavs/jump.js) library.
+
+## Available Options
+
+```typescript
+interface JumpOptions {
+  /** Duration of scroll animation in milliseconds (default: 500) */
+  duration?: number;
+
+  /** Vertical offset in pixels from target element (default: -100) */
+  offset?: number;
+
+  /** Callback function to execute after scroll completes */
+  callback?: () => void;
+
+  /** Easing function name or custom function (default: 'easeInOutQuad') */
+  easing?: (t: number, b: number, c: number, d: number) => number | string;
+
+  /** Whether to focus the element for accessibility (default: false) */
+  a11y?: boolean;
+}
+```
+
+## Global Configuration
+
+Set default jump options for all steps in the tour:
+
+```vue
+<template>
+  <VTour
+    :steps="steps"
+    :jump-options="{
+      duration: 1000,
+      offset: -50,
+      easing: 'easeInOutQuad',
+      a11y: true,
+    }"
+  />
+</template>
+```
+
+## Per-Step Configuration
+
+Override global options for specific steps:
+
+```typescript
+const steps = [
+  {
+    target: '#step1',
+    content: 'This step uses global jump options',
+  },
+  {
+    target: '#step2',
+    content: 'This step uses custom scroll duration',
+    jumpOptions: {
+      duration: 300, // Faster scroll
+      offset: -200, // More space at top
+    },
+  },
+];
+```
+
+## Custom Easing
+
+Provide a custom easing function:
+
+```vue
+<script setup lang="ts">
+import { VTour } from '@globalhive/vuejs-tour';
+
+const customEasing = (t: number, b: number, c: number, d: number) => {
+  // Linear easing
+  return (c * t) / d + b;
+};
+
+const jumpOptions = {
+  duration: 800,
+  easing: customEasing,
+};
+</script>
+
+<template>
+  <VTour :steps="steps" :jump-options="jumpOptions" />
+</template>
+```
+
+## Disabling Scroll
+
+You can disable scrolling globally or per-step using the existing `noScroll` prop:
+
+```vue
+<!-- Disable scrolling for entire tour -->
+<VTour :steps="steps" :no-scroll="true" />
+```
+
+```typescript
+// Disable scrolling for specific step
+const steps = [
+  {
+    target: '#step1',
+    content: 'This step will not scroll',
+    noScroll: true,
+  },
+];
+```
+
+## Priority
+
+When multiple jump option sources are provided, they are merged with the following priority:
+
+1. **Step-specific options** (highest priority)
+2. **Global prop options**
+3. **Default values** (lowest priority)
+
+Example:
+
+```typescript
+// Global defaults
+const globalJumpOptions = {
+  duration: 1000,
+  offset: -100,
+  a11y: true,
+};
+
+// Step overrides
+const steps = [
+  {
+    target: '#step1',
+    content: 'Step 1',
+    jumpOptions: {
+      duration: 300, // Only override duration
+      // offset: still -100 from global
+      // a11y: still true from global
+    },
+  },
+];
+```
+
+## Available Easing Functions
+
+jump.js supports the following built-in easing function names:
+
+- `'easeInQuad'`
+- `'easeOutQuad'`
+- `'easeInOutQuad'` (default)
+- `'easeInCubic'`
+- `'easeOutCubic'`
+- `'easeInOutCubic'`
+- `'easeInQuart'`
+- `'easeOutQuart'`
+- `'easeInOutQuart'`
+- `'easeInQuint'`
+- `'easeOutQuint'`
+- `'easeInOutQuint'`
+
+Or provide your own custom easing function following the signature:
+
+```typescript
+(t: number, b: number, c: number, d: number) => number;
+```
+
+Where:
+
+- `t` = current time
+- `b` = beginning value
+- `c` = change in value
+- `d` = duration

src/Types.ts

@@ -1,5 +1,31 @@
 import type { NanoPopPosition } from 'nanopop';
 
+/**
+ * Scroll animation options for jump.js
+ * @see https://github.com/callmecavs/jump.js
+ */
+export interface JumpOptions {
+  /** Duration of scroll animation in milliseconds (default: 500) */
+  readonly duration?: number;
+
+  /** Vertical offset in pixels from target element (default: -100) */
+  readonly offset?: number;
+
+  /** Callback function to execute after scroll completes */
+  readonly callback?: () => void;
+
+  /** Easing function name (default: 'easeInOutQuad') */
+  readonly easing?: (
+    t: number,
+    b: number,
+    c: number,
+    d: number
+  ) => number | string;
+
+  /** Whether to focus the element for accessibility (default: false) */
+  readonly a11y?: boolean;
+}
+
 /**
  * Configuration for a single step in a tour
  */
@@ -27,6 +53,9 @@ export interface ITourStep {
 
   /** Whether to disable auto-scrolling for this step */
   readonly noScroll?: boolean;
+
+  /** Custom scroll animation options for this step (overrides global jumpOptions) */
+  readonly jumpOptions?: Partial<JumpOptions>;
 }
 
 /**
@@ -89,6 +118,9 @@ export interface VTourProps {
 
   /** Default tooltip placement when step doesn't specify one */
   readonly defaultPlacement?: NanoPopPosition;
+
+  /** Default scroll animation options (can be overridden per step) */
+  readonly jumpOptions?: Partial<JumpOptions>;
 }
 
 /**

src/components/VTour.vue

@@ -82,8 +82,14 @@ const _Backdrop = ref<HTMLElement>();
 
 // Constants for timing and positioning
 const TELEPORT_RENDER_DELAY = 100; // ms to wait for Vue Teleport to render DOM elements
-const SCROLL_DURATION = 500; // ms for smooth scroll animation
-const SCROLL_OFFSET = -100; // px offset from top when scrolling to element
+
+// Default jump.js scroll options (can be overridden via props)
+const DEFAULT_JUMP_OPTIONS = {
+  duration: 500,
+  offset: -100,
+  easing: 'easeInOutQuad' as const,
+  a11y: false,
+};
 
 // Helper to check if tour was completed and saved to localStorage
 const isTourCompleted = (): boolean => {
@@ -330,11 +336,16 @@ const updatePosition = async (): Promise<void> => {
   // Scroll to target first if needed
   if (!props.noScroll && !currentStepData.noScroll) {
     await new Promise<void>((resolve) => {
-      jump(targetElement, {
-        duration: SCROLL_DURATION,
-        offset: SCROLL_OFFSET,
+      // Merge default options with global and step-specific options
+      // Priority: step options > global options > defaults
+      const scrollOptions = {
+        ...DEFAULT_JUMP_OPTIONS,
+        ...props.jumpOptions,
+        ...currentStepData.jumpOptions,
         callback: () => resolve(),
-      });
+      } as any; // jump.js has incomplete type definitions
+
+      jump(targetElement, scrollOptions);
     });
   }
 

src/vuejs-tour.ts

@@ -10,6 +10,7 @@ export type {
   VTourExposedMethods,
   ButtonLabels,
   SaveToLocalStorage,
+  JumpOptions,
 } from './Types';
 
 // Re-export NanoPopPosition from nanopop for user convenience