Interactive Gallery Scroller

Build a configurable scroll controller for an interactive image gallery that supports both locked and free scrolling behaviors.

Requirements

Create a module that initializes two different scroll instances for a gallery interface:

1. Locked Scroller: A vertical-only scroll container that prevents horizontal drift when users scroll vertically
2. Free Scroller: A bi-directional scroll container that allows smooth diagonal scrolling in any direction

The module should:

• Accept a container element selector and configuration options
• Initialize the appropriate scroll behavior based on the configuration
• Ensure smooth touch and mouse interactions
• Handle both horizontal and vertical scrolling axes
• Return the initialized scroll instance for further manipulation

Test Cases

• When initialized with locked mode on a vertically scrollable container, the scroller prevents horizontal movement during vertical scrolling @test
• When initialized with free mode on a bi-directionally scrollable container, the scroller allows diagonal movement @test
• The module correctly configures scroll axes based on the mode (locked mode enables one axis, free mode enables both axes) @test

Implementation

@generates

API

/**
 * Configuration options for the gallery scroller
 */
interface ScrollerConfig {
  /** The scroll mode: 'locked' for single-axis, 'free' for multi-axis */
  mode: 'locked' | 'free';
  /** The primary scroll direction for locked mode */
  direction?: 'vertical' | 'horizontal';
}

/**
 * Initialize a scroll instance with the specified configuration
 *
 * @param selector - CSS selector for the wrapper element
 * @param config - Configuration options for scroll behavior
 * @returns The initialized scroll instance
 */
export function initializeScroller(selector: string, config: ScrollerConfig): any;

Dependencies { .dependencies }

@better-scroll/core { .dependency }

Provides core scrolling functionality with configurable direction locking and free scrolling support.