# stutrek/scrollmonitor architecture

> Architecture diagram of the GitHub repository stutrek/scrollmonitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stutrek/scrollmonitor
- Repository: https://github.com/stutrek/scrollmonitor

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% TypeScript Source
    subgraph "TypeScript Source"
        direction TB
        Constants["constants.ts"]:::core
        ContainerSrc["container.ts"]:::core
        WatcherSrc["watcher.ts"]:::core
        Types["types.ts"]:::core
        EntrySrc["index.ts"]:::core
        PackageJson["package.json"]:::core
    end

    %% Distribution Outputs
    subgraph "Distribution"
        direction TB
        subgraph "ES Module Build"
            direction TB
            DistModuleIndex["index.js/.d.ts"]:::dist
            DistModuleConstants["constants.js"]:::dist
            DistModuleContainer["container.js"]:::dist
            DistModuleWatcher["watcher.js"]:::dist
            DistModuleTypes["types.js"]:::dist
        end
        subgraph "UMD Build"
            direction TB
            UMDIndex["index.js/.d.ts"]:::dist
            UMDConstants["constants.js"]:::dist
            UMDContainer["container.js"]:::dist
            UMDWatcher["watcher.js"]:::dist
            UMDTypes["types.js"]:::dist
        end
    end

    %% Core Components
    subgraph "Core Library Runtime"
        direction TB
        ModuleAPI["scrollMonitor Module\n(create, update,\nrecalculateLocations,\nviewport state)"]:::core
        ContainerRuntime["ScrollMonitorContainer\n(listens to custom scroll)"]:::core
        WatcherRuntime["Watcher Class\n(on/off, lock/unlock,\nstate props)"]:::core
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        Demos["demos/"]:::consumer
        Tests["test/"]:::consumer
    end

    %% Browser Event
    BrowserScroll["Browser Scroll Event"]:::external

    %% Relationships
    BrowserScroll -->|triggers| ModuleAPI
    BrowserScroll -->|triggers| ContainerRuntime
    ModuleAPI -->|iterates watchers| WatcherRuntime
    ContainerRuntime -->|delegates to| WatcherRuntime
    WatcherRuntime -->|triggers callbacks| ModuleAPI

    EntrySrc -->|compiled via tsconfig| DistModuleIndex
    EntrySrc -->|compiled via tsconfig| UMDIndex
    PackageJson -->|points main/module| DistModuleIndex
    PackageJson -->|points main/module| UMDIndex

    Constants --> DistModuleConstants
    ContainerSrc --> DistModuleContainer
    WatcherSrc --> DistModuleWatcher
    Types --> DistModuleTypes

    Constants --> UMDConstants
    ContainerSrc --> UMDContainer
    WatcherSrc --> UMDWatcher
    Types --> UMDTypes

    Demos -->|load UMD build| UMDIndex
    Tests -->|run tests on| UMDIndex

    %% Click Events
    click EntrySrc "https://github.com/stutrek/scrollmonitor/blob/master/index.ts"
    click PackageJson "https://github.com/stutrek/scrollmonitor/blob/master/package.json"
    click ContainerSrc "https://github.com/stutrek/scrollmonitor/blob/master/src/container.ts"
    click DistModuleContainer "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/src/container.js"
    click UMDContainer "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/src/container.js"
    click WatcherSrc "https://github.com/stutrek/scrollmonitor/blob/master/src/watcher.ts"
    click DistModuleWatcher "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/src/watcher.js"
    click UMDWatcher "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/src/watcher.js"
    click Constants "https://github.com/stutrek/scrollmonitor/blob/master/src/constants.ts"
    click DistModuleConstants "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/src/constants.js"
    click UMDConstants "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/src/constants.js"
    click Types "https://github.com/stutrek/scrollmonitor/blob/master/src/types.ts"
    click DistModuleTypes "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/src/types.js"
    click UMDTypes "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/src/types.js"
    click DistModuleIndex "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/index.js"
    click DistModuleIndex "https://github.com/stutrek/scrollmonitor/blob/master/dist/module/index.d.ts"
    click UMDIndex "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/index.js"
    click UMDIndex "https://github.com/stutrek/scrollmonitor/blob/master/dist/umd/index.d.ts"
    click Demos "https://github.com/stutrek/scrollmonitor/tree/master/demos/"
    click Tests "https://github.com/stutrek/scrollmonitor/blob/master/test/index.js"
    click Tests "https://github.com/stutrek/scrollmonitor/blob/master/test/tests.js"
    click Tests "https://github.com/stutrek/scrollmonitor/blob/master/testEntry.ts"
    click Tests "https://github.com/stutrek/scrollmonitor/blob/master/test/polyfills.js"
    click Tests "https://github.com/stutrek/scrollmonitor/blob/master/testem.json"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef dist fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef consumer fill:#e0e0e0,stroke:#9e9e9e,color:#424242
    classDef external fill:#ffecb3,stroke:#ffa000,color:#e65100
```
