Core Scrolling

/**
 * Creates a new BScroll instance
 * @param el - DOM element or CSS selector string for the wrapper container
 * @param options - Configuration options object
 */
constructor BScroll(el: string | HTMLElement, options?: BScrollOptions);

import BScroll from "better-scroll";

// Using DOM element
const wrapper = document.querySelector('.wrapper');
const scroll = new BScroll(wrapper);

// Using CSS selector
const scroll = new BScroll('.wrapper');

// With options
const scroll = new BScroll('.wrapper', {
  scrollY: true,
  scrollX: false,
  momentum: true,
  bounce: {
    top: true,
    bottom: true,
    left: false,
    right: false
  },
  probeType: 2
});

/**
 * Scroll to specific coordinates
 * @param x - Target horizontal position (negative values scroll right)
 * @param y - Target vertical position (negative values scroll down) 
 * @param time - Animation duration in milliseconds (default: 0)
 * @param easing - Easing function for animation (default: ease.bounce)
 */
scrollTo(x: number, y: number, time?: number, easing?: EasingFunction): void;

/**
 * Scroll by relative offset from current position
 * @param x - Horizontal offset to scroll by
 * @param y - Vertical offset to scroll by  
 * @param time - Animation duration in milliseconds (default: 0)
 * @param easing - Easing function for animation (default: ease.bounce)
 */
scrollBy(x: number, y: number, time?: number, easing?: EasingFunction): void;

/**
 * Scroll to bring a specific element into view
 * @param el - Target element or CSS selector string
 * @param time - Animation duration in milliseconds
 * @param offsetX - Horizontal offset or true to center horizontally
 * @param offsetY - Vertical offset or true to center vertically
 * @param easing - Easing function for animation
 */
scrollToElement(
  el: HTMLElement | string, 
  time?: number, 
  offsetX?: number | boolean, 
  offsetY?: number | boolean, 
  easing?: EasingFunction
): void;

// Instant scrolling
scroll.scrollTo(0, -100);

// Animated scrolling
scroll.scrollTo(0, -100, 300);

// Relative scrolling
scroll.scrollBy(0, -50, 200);

// Scroll to element
scroll.scrollToElement('.target-item', 300);

// Center element in view
scroll.scrollToElement('.target-item', 300, true, true);

/**
 * Refresh scroll dimensions and boundaries
 * Call this after changing content size or wrapper dimensions
 */
refresh(): void;

/**
 * Enable scrolling functionality
 */
enable(): void;

/**
 * Disable scrolling functionality
 */
disable(): void;

/**
 * Stop current scrolling animation
 */
stop(): void;

/**
 * Destroy the BScroll instance and clean up resources
 * Removes all event listeners and stops animations
 */
destroy(): void;

/**
 * Reset to valid scroll position if outside boundaries
 * @param time - Animation duration for the reset (default: 0)
 * @param easing - Easing function for reset animation (default: ease.bounce)
 * @returns true if position was reset, false if already valid
 */
resetPosition(time?: number, easing?: EasingFunction): boolean;

// After adding/removing content
scroll.refresh();

// Temporarily disable scrolling
scroll.disable();
// Later re-enable
scroll.enable();

// Stop any current animation
scroll.stop();

// Clean up when done
scroll.destroy();

// Reset position with animation if out of bounds
scroll.resetPosition(300);

/**
 * Get current computed scroll position from DOM
 * Useful when in transition to get real-time position
 * @returns Current position coordinates
 */
getComputedPosition(): {x: number, y: number};

// Get current position during animation
const position = scroll.getComputedPosition();
console.log(`Current position: ${position.x}, ${position.y}`);

interface MovementOptions {
  startX?: number;              // Initial horizontal position (default: 0)
  startY?: number;              // Initial vertical position (default: 0)
  scrollX?: boolean;            // Enable horizontal scrolling (default: false)
  scrollY?: boolean;            // Enable vertical scrolling (default: true)
  freeScroll?: boolean;         // Allow free scrolling in both directions (default: false)
  directionLockThreshold?: number; // Direction lock sensitivity in pixels (default: 5)
}

interface MomentumOptions {
  momentum?: boolean;           // Enable momentum scrolling (default: true)
  momentumLimitTime?: number;   // Time threshold for momentum in ms (default: 300)
  momentumLimitDistance?: number; // Distance threshold for momentum in px (default: 15)
  deceleration?: number;        // Momentum deceleration rate (default: 0.0015)
  swipeTime?: number;           // Maximum swipe duration for momentum in ms (default: 2500)
  swipeBounceTime?: number;     // Bounce duration for swipe in ms (default: 500)
}

interface BounceConfiguration {
  bounce?: boolean | BounceOptions; // Enable bounce effects (default: true)
  bounceTime?: number;             // Bounce animation duration in ms (default: 800)
}

interface BounceOptions {
  top?: boolean;                   // Enable top boundary bounce
  bottom?: boolean;                // Enable bottom boundary bounce  
  left?: boolean;                  // Enable left boundary bounce
  right?: boolean;                 // Enable right boundary bounce
}

interface InteractionOptions {
  click?: boolean;              // Enable click events (default: false)
  tap?: boolean | string;       // Enable tap gesture, string for custom event (default: false)
  preventDefault?: boolean;     // Prevent default touch events (default: true)
  preventDefaultException?: {   // Elements to exclude from preventDefault
    tagName?: RegExp;           
    className?: RegExp;
    id?: RegExp;
  };
  stopPropagation?: boolean;    // Stop event propagation (default: false)
  eventPassthrough?: string;    // Allow native scrolling ('vertical' | 'horizontal')
}

interface ProbeOptions {
  probeType?: number;           // Event firing frequency (default: 0)
  // 0: No scroll events during animation
  // 1: Non-real-time events (debounced)
  // 2: Real-time events during momentum 
  // 3: Real-time events always
}

interface PerformanceOptions {
  useTransition?: boolean;      // Use CSS transitions (default: true)
  useTransform?: boolean;       // Use CSS transforms (default: true)
  HWCompositing?: boolean;      // Hardware acceleration (default: true)
  observeDOM?: boolean;         // Auto-detect DOM changes (default: true)
  resizePolling?: number;       // Resize detection interval in ms (default: 60)
  autoBlur?: boolean;           // Auto-blur inputs on scroll (default: true)
}

x: number;                      // Current horizontal position
y: number;                      // Current vertical position
directionX: number;             // Last horizontal direction (-1, 0, 1)
directionY: number;             // Last vertical direction (-1, 0, 1)
movingDirectionX: number;       // Current horizontal movement direction (-1, 0, 1)
movingDirectionY: number;       // Current vertical movement direction (-1, 0, 1)

minScrollX: number;             // Minimum horizontal scroll position
maxScrollX: number;             // Maximum horizontal scroll position
minScrollY: number;             // Minimum vertical scroll position  
maxScrollY: number;             // Maximum vertical scroll position

enabled: boolean;               // Whether scrolling is enabled
isInTransition: boolean;        // Whether in CSS transition
isAnimating: boolean;           // Whether in JavaScript animation
hasHorizontalScroll: boolean;   // Whether horizontal scrolling is possible
hasVerticalScroll: boolean;     // Whether vertical scrolling is possible
destroyed: boolean;             // Whether the instance has been destroyed
moved: boolean;                 // Whether movement has been detected in current gesture
pulling: boolean;               // Whether currently in pull-down state (when pullDownRefresh enabled)

wrapperWidth: number;           // Wrapper element width
wrapperHeight: number;          // Wrapper element height
scrollerWidth: number;          // Scroller element width
scrollerHeight: number;         // Scroller element height

wrapper: HTMLElement;           // Container DOM element
scroller: HTMLElement;          // First child element that scrolls
scrollerStyle: CSSStyleDeclaration; // Cached style object of scroller

interface EasingFunction {
  style: string;                // CSS timing function
  fn: (t: number) => number;    // JavaScript easing function
}

// Built-in easing functions available:
// ease.quadratic, ease.circular, ease.back, ease.bounce, ease.elastic