mukiturrahman/locomotive-scroll

1. What this repo is

- This is a browser-side JavaScript library, not an application backend.

- Its core product is a scroll controller that combines viewport detection, smooth scrolling, parallax, sticky behavior, and programmatic scrolling.

2. Public package boundary

- The main entry points are in src/locomotive-scroll.js and the built artifacts in dist/.

- Consumers import the library as ES module or UMD, and optionally include the generated stylesheet dist/locomotive-scroll.css.

3. Runtime architecture

- The source is split into a shared core plus mode-specific implementations.

- Core.js appears to hold common lifecycle and element-tracking behavior.

- Main.js and NativeMain.js likely represent the top-level orchestration for smooth vs native scrolling modes.

- Smooth.js and Native.js split the actual scroll mechanics by mode.

4. Scroll modes and control flow

- In native mode, the library observes normal browser scrolling and focuses on element detection and events.

- In smooth mode, it intercepts scroll input, applies inertia/lerp, and manages a virtual scroll position.

- The mode choice is driven by instance options such as smooth, direction, lerp, gestureDirection, and device-specific overrides.

5. Element detection and in-view state

- The library scans DOM elements marked with data-scroll and related attributes.

- It computes viewport intersection, progress, offsets, and repeat behavior.

- Current in-view elements are exposed through the scroll event payload, and data-scroll-call triggers custom callbacks/events.

6. Parallax, sticky, and motion features

- Smooth mode adds animation-like behavior through attributes such as data-scroll-speed, data-scroll-delay, data-scroll-direction, data-scroll-sticky, and data-scroll-target.

- These features depend on transform calculations rather than layout reflow, which is why utilities like transform.js matter to the architecture.

7. Shared utilities and configuration

- options.js centralizes default option handling and likely normalizes user configuration.

- utils/html.js, utils/maths.js, and utils/transform.js provide DOM, math, and transform helpers used across the scroll implementations.

8. Event model

- The library exposes instance events such as scroll and call.

- That event surface is the main integration boundary for app code: animation libraries, UI state updates, analytics, or custom routing logic subscribe there rather than coupling directly to internals.

9. Styling subsystem

- The scroll behavior depends on stylesheet support in src/locomotive-scroll.scss and src/styles/_base.scss, plus scrollbar styles in _scrollbar.scss.

- These styles define the structural classes and container behavior required for the scrolling container and custom scrollbar in smooth mode.

10. Build and packaging pipeline

- The repo uses a Gulp-based build system in gulpfile.babel.js and the build/ scripts to compile, bundle, copy, serve, watch, and notify.

- Tooling includes Babel and Sass, with browser targeting defined by .browserslistrc and style formatting governed by .prettierrc.

- The release outputs are placed in dist/ as distributable JS/CSS bundles.

11. Docs/demo site as a separate front-end

- docs/ is a standalone demo/documentation site with its own source tree under docs/src/ and compiled assets in docs/dist/.

- It has separate scripts, styles, images, and HTML entry pages like docs/index.html and docs/horizontal.html, so the demo is architecturally distinct from the library itself.

12. External dependencies that shape architecture

- The scroll engine relies on virtual-scroll for momentum-like input handling, bezier-easing for animated scrollTo, and a viewport-detection approach derived from modularScroll.

- These dependencies reinforce that the library is entirely client-side and focused on DOM input/output, not data fetching or server interaction.