How stutrek/scrollmonitor works
Project Type and Purpose
• This is a standalone JavaScript/TypeScript library (“scrollMonitor”) whose purpose is to let consumers register “watchers” on DOM elements (or numeric offsets) so they receive callbacks as those elements enter/exit a scrollable viewport.
• It is not a full-stack app but a reusable front-end component/library. The README and demos show usage patterns, event APIs, and configuration options.
File Structure Analysis
Top-level files
• package.json, tsconfig.json – npm package and TypeScript build config
• .eslintrc.json, .prettierrc – linting/formatting
• README.md, LICENSE
Source code
• src/
– constants.ts: numeric constants (e.g. event names)
– container.ts: ScrollMonitorContainer class (custom scroll container support)
– watcher.ts: Watcher class (core of viewport tracking)
– types.ts: TypeScript type definitions for watchers, offsets, events
Distribution
• dist/module and dist/umd – transpiled outputs (ES module and UMD builds), each with index.js/.d.ts and map files
Examples and Tests
• demos/ – HTML + JSON files demonstrating various use cases
• test/ – Mocha/Chai tests, testEntry.ts, polyfills, testem.json
README Insights
• Describes core responsibilities (create watchers, events, container support).
• Explains performance characteristics (minimal DOM touches, no allocations).
• Details API methods/properties and event lifecycle.
• Notes extension points (offsets, locking) and external variants (React wrappers).
Main Components
A. scrollMonitor Module (Entry Point)
• Exposes create(), createContainer(), update(), recalculateLocations()
• Holds global viewport/document state (viewportTop, viewportBottom, viewportHeight, documentHeight)
B. ScrollMonitorContainer
• Listens to scroll events on a custom container element
• Delegates to watchers within that container
C. Watcher
• Instances created via create(…) or container.create(…)
• Maintains .top, .bottom, .height, state booleans (isInViewport, isAboveViewport, etc.)
• Provides on/off methods to register callbacks for visibilityChange, enterViewport, exitViewport, etc.
• Has lock/unlock and recalculateLocation methods
D. Build Pipeline
• TypeScript source → tsconfig build → outputs in dist/module and dist/umd
• package.json points to “module” and “main” fields
E. Demos & Tests (Supporting Artifacts)
• demos/* – illustrate usage flows by including the UMD build and runtime callbacks
• test/* – unit tests executed via testem
Relationships and Interactions
• Browser issues scroll event → scrollMonitor or container’s scroll listener fires
• scrollMonitor.update() or container.update() iterates unlocked Watcher instances → recalc positions → evaluate state transitions → trigger callbacks
• Watcher instances hold references to DOM elements (or numeric offsets) but perform minimal reads per scroll
• Locking freezes a watcher’s location calculations
Architectural Patterns
• Module pattern (UMD + ES modules)
• Observer/Publish-Subscribe (Watchers emit events)
• Separation of concerns:
• scrollMonitor global state vs. containers vs. watchers
• build artifacts separated by format
• demos, tests isolated