Enhance documentation for ScrollToSmooth

- Updated architecture documentation with a detailed table of contents and expanded sections on design principles, animation engine, document expanders, scroll queue, plugin system, event system, build system, and output formats.
- Revised easing functions documentation to include a comprehensive table of contents, improved import instructions, and detailed descriptions of available easings and their use cases.
- Expanded plugins documentation to provide a structured overview of plugin registration, examples of horizontal scrolling, section snapping, touch momentum, and guidelines for writing custom plugins.
- Comprehensive usage guide added, covering basic setup, easing selection, custom triggers, scroll targets, programmatic scrolling, scroll queue management, fixed header offsets, custom scroll containers, duration control, native browser fallback, tracking scroll progress, CSS custom properties, and instance management.

Author: bfiessinger

README.md

@@ -1,164 +1,291 @@
-# ScrollToSmooth
-
-[![CodeFactor](https://img.shields.io/codefactor/grade/github/bfiessinger/scrolltosmooth?style=for-the-badge)](https://www.codefactor.io/repository/github/bfiessinger/scrolltosmooth)
-[![Filesize](https://img.shields.io/bundlephobia/minzip/scrolltosmooth?style=for-the-badge)](https://bundlephobia.com/result?p=scrolltosmooth)
-![Version](https://img.shields.io/github/v/release/bfiessinger/scrollToSmooth?include_prereleases&style=for-the-badge)
-[![](https://img.shields.io/jsdelivr/gh/hy/bfiessinger/scrolltosmooth?style=for-the-badge)](https://www.jsdelivr.com/package/gh/bfiessinger/scrollToSmooth)
-
-Lightweight **Vanilla JavaScript smooth scrolling library** with zero dependencies.
-
-ScrollToSmooth provides fully customizable scroll animations powered by `requestAnimationFrame`.  
-The core stays minimal while advanced functionality can be added through a **tree-shakeable plugin system**.
+<p align="center">
+  <br />
+  <strong style="font-size: 2em;">ScrollToSmooth</strong>
+  <br />
+  <em>Buttery-smooth scroll animations for the web — zero dependencies, fully tree-shakeable, plugin-powered.</em>
+  <br /><br />
+</p>
+
+<p align="center">
+  <a href="https://www.codefactor.io/repository/github/bfiessinger/scrolltosmooth"><img src="https://img.shields.io/codefactor/grade/github/bfiessinger/scrolltosmooth?style=for-the-badge" alt="CodeFactor" /></a>
+  <a href="https://bundlephobia.com/result?p=scrolltosmooth"><img src="https://img.shields.io/bundlephobia/minzip/scrolltosmooth?style=for-the-badge" alt="Bundle Size" /></a>
+  <img src="https://img.shields.io/github/v/release/bfiessinger/scrollToSmooth?include_prereleases&style=for-the-badge" alt="Version" />
+  <a href="https://www.jsdelivr.com/package/gh/bfiessinger/scrollToSmooth"><img src="https://img.shields.io/jsdelivr/gh/hy/bfiessinger/scrolltosmooth?style=for-the-badge" alt="jsDelivr" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> · <a href="docs/api.md">API</a> · <a href="docs/plugins.md">Plugins</a> · <a href="docs/easings.md">Easings</a> · <a href="https://bfiessinger.github.io/scrollToSmooth/">Live Demo</a>
+</p>
 
 ---
 
-## Features
-
-- Smooth animated scrolling
-- Custom easing functions (import only what you need)
-- Programmatic scrolling API
-- Fixed header offset support
-- Scroll lifecycle callbacks
-- Plugin architecture
-- Tree-shakeable modules
-- No dependencies
+ScrollToSmooth gives you complete control over scroll animations using `requestAnimationFrame`. Pick from **31 built-in easing functions**, scroll in any direction, queue animations, snap to sections, add touch-momentum — and ship only the code you actually use.
+
+## Highlights
+
+| | Feature | What it does |
+|-|---------|-------------|
+| **🎯** | **Scroll anywhere** | Scroll to elements, CSS selectors, pixel offsets, percentages (`'50%'`), viewport units (`'25vh'`), or `{ x, y }` coordinates |
+| **🎨** | **31 easing functions** | From subtle `easeOutCubic` to bouncy `easeOutBounce` — import only the ones you need |
+| **📐** | **Horizontal & 2D scrolling** | Scroll on the x-axis, y-axis, or both simultaneously via the Horizontal plugin |
+| **📸** | **Section snapping** | Auto-snap to the nearest section after the user stops scrolling |
+| **📱** | **Touch momentum** | Inertia scrolling on touch devices — swipe and let momentum carry you |
+| **🔗** | **Scroll queue** | Chain multiple scroll targets and execute them in sequence |
+| **🧩** | **Plugin system** | Add only what you need — every plugin is tree-shakeable |
+| **⚡** | **CSS custom properties** | `--sts-scroll-y` and `--sts-scroll-x` update every frame — drive progress bars, parallax, or any reactive styling from scroll position |
+| **🎛** | **Callbacks & events** | `onScrollStart` / `onScrollUpdate` / `onScrollEnd` callbacks + `scrolltosmooth:*` CustomEvents that bubble up |
+| **📏** | **Smart offsets** | Fixed-header offset via element selector, pixels, `%`, or `vh` — auto-recalculates on resize |
+| **🌐** | **Native fallback** | Set `useNative: true` to delegate to the browser's `scroll-behavior: smooth` when supported |
+| **🪶** | **Tiny core** | ~3 KB min+gzip with zero dependencies |
 
 ---
 
-## Demo
+## Live Demo
+
+**[→ bfiessinger.github.io/scrollToSmooth](https://bfiessinger.github.io/scrollToSmooth/)**
 
-https://bfiessinger.github.io/scrollToSmooth/
+See vertical scrolling, horizontal scrolling, 2D board navigation, section snapping, scroll queuing, and progress tracking in action.
 
 ---
 
 ## Installation
 
-### NPM
-
 ```bash
 npm install scrolltosmooth
 ```
 
-### CDN
-
-All‑in‑one build (Do not use for production):
+Or use a CDN — pick the build that fits your needs:
 
 ```html
+<!-- Minimal core (linear easing only, ~3 KB) -->
+<script src="https://cdn.jsdelivr.net/npm/scrolltosmooth/dist/scrolltosmooth.min.js"></script>
+
+<!-- Full bundle with all easings + plugins pre-registered -->
 <script src="https://cdn.jsdelivr.net/npm/scrolltosmooth/dist/scrolltosmooth.pkgd.min.js"></script>
 ```
 
-Minimal build (linear easing only):
+> **Tip:** The core IIFE only includes the `linear` easing. Use the `pkgd` build for quick prototyping; for production, import individual easings and plugins to keep bundles lean.
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/scrolltosmooth/dist/scrolltosmooth.min.js"></script>
+---
+
+## Quick Start
+
+```js
+import ScrollToSmooth from 'scrolltosmooth'
+import { easeOutCubic } from 'scrolltosmooth/easings/easeOutCubic'
+
+const scroller = new ScrollToSmooth('a', {
+  duration: 600,
+  easing: easeOutCubic,
+  offset: '#header',        // compensate for a fixed nav
+})
+
+scroller.init()
+```
+
+That's it — every `<a href="#...">` on the page now scrolls smoothly, offset by the height of `#header`.
+
+### Programmatic scrolling
+
+```js
+// Scroll to an element
+scroller.scrollTo('#features')
+
+// Scroll to a pixel position
+scroller.scrollTo(500)
+
+// Scroll to 50% of the document
+scroller.scrollTo('50%')
+
+// Scroll by a relative offset
+scroller.scrollBy(200)
 ```
 
-> **Note:** the iife/minified core file only includes the linear easing and
-> the class itself.  the `pkgd` build exposes every easing on `window` but
-> is much larger; use it only when you need the full set with one script tag.
+### Scroll queue
+
+Chain targets and let them play one after another:
+
+```js
+scroller.queueScroll('#section-1')
+scroller.queueScroll('#section-2')
+scroller.queueScroll('#section-3')
+// Scrolls to each section in sequence
+```
 
 ---
 
-## Quick Start
+## Plugins
 
-### Easing import example
+Plugins keep the core lean. Import only what you need:
 
-By default the core class only ships with a single `linear` easing.  import
-other functions explicitly to keep your bundle small:
+### Horizontal & 2D Scrolling
 
 ```js
-import ScrollToSmooth from 'scrolltosmooth';
-import { easeOutCubic } from 'scrolltosmooth/easings/easeOutCubic';
+import { HorizontalScrollPlugin } from 'scrolltosmooth/plugins/horizontal'
 
-const scroller = new ScrollToSmooth('a', {
-  duration: 600,
-  easing: easeOutCubic
-});
+ScrollToSmooth.use(HorizontalScrollPlugin)
+
+const scroller = new ScrollToSmooth('.nav-link', { axis: 'x' })
+scroller.init()
+
+scroller.scrollToX('#slide-3')           // horizontal
+scroller.scrollToBoth(800, 400)          // both axes at once
 ```
 
-If you still prefer passing a string name you can resolve it yourself:
+### Section Snapping
 
 ```js
-import { getEasing } from 'scrolltosmooth/easings';
+import { SnapPlugin } from 'scrolltosmooth/plugins/snap'
+
+ScrollToSmooth.use(SnapPlugin)
 
 const scroller = new ScrollToSmooth('a', {
-  easing: getEasing('easeOutCubic')
-});
+  snap: true,
+  snapSelector: '.section',   // which elements to snap to
+  snapDebounce: 150,           // ms of inactivity before snapping
+})
+scroller.init()
 ```
 
-(The core will warn and fall back to `linear` if a string is given.)
+### Touch Momentum
 
-## Quick Start
+```js
+import { TouchMomentumPlugin } from 'scrolltosmooth/plugins/touch-momentum'
 
-```javascript
-import ScrollToSmooth from 'scrolltosmooth'
+ScrollToSmooth.use(TouchMomentumPlugin)
 
 const scroller = new ScrollToSmooth('a', {
-  duration: 400
+  touchMomentum: true,
+  touchMomentumFactor: 300,
+  touchMomentumMinVelocity: 0.3,
 })
-
 scroller.init()
 ```
 
-Scroll to element:
+[→ Full plugin docs](docs/plugins.md)
+
+---
+
+## Easing Functions
+
+31 easing functions, all individually importable:
 
-```javascript
-scroller.scrollTo('#section')
+```js
+import { easeOutBounce } from 'scrolltosmooth/easings/easeOutBounce'
 ```
 
-Scroll by distance:
+| Family | In | Out | InOut |
+|--------|----|-----|-------|
+| Quad | `easeInQuad` | `easeOutQuad` | `easeInOutQuad` |
+| Cubic | `easeInCubic` | `easeOutCubic` | `easeInOutCubic` |
+| Quart | `easeInQuart` | `easeOutQuart` | `easeInOutQuart` |
+| Quint | `easeInQuint` | `easeOutQuint` | `easeInOutQuint` |
+| Sine | `easeInSine` | `easeOutSine` | `easeInOutSine` |
+| Expo | `easeInExpo` | `easeOutExpo` | `easeInOutExpo` |
+| Circ | `easeInCirc` | `easeOutCirc` | `easeInOutCirc` |
+| Elastic | `easeInElastic` | `easeOutElastic` | `easeInOutElastic` |
+| Back | `easeInBack` | `easeOutBack` | `easeInOutBack` |
+| Bounce | `easeInBounce` | `easeOutBounce` | `easeInOutBounce` |
 
-```javascript
-scroller.scrollBy(200)
+Plus `linear`. Or bring your own: `easing: (t) => t * t`
+
+[→ Full easing reference](docs/easings.md)
+
+---
+
+## Reactive CSS Custom Properties
+
+ScrollToSmooth writes `--sts-scroll-y` (and `--sts-scroll-x` with the Horizontal plugin) to the scroll container on every animation frame. Use them in CSS for zero-JS reactive styling:
+
+```css
+/* Parallax background tied to scroll */
+.hero-bg {
+  transform: translateY(calc(var(--sts-scroll-y, 0) * 0.3px));
+}
+
+/* Progress bar driven by scroll position */
+.progress-bar {
+  width: calc(var(--sts-scroll-y, 0) / var(--doc-height) * 100%);
+}
 ```
 
 ---
 
-## Documentation
+## Events & Callbacks
 
-Full documentation is located in the `/docs` directory.
+Track every phase of a scroll animation:
 
-- [Usage](docs/usage.md)
-- [API Reference](docs/api.md)
-- [Plugins](docs/plugins.md)
-- [Easing Functions](docs/easings.md)
-- [Architecture](docs/architecture.md)
+```js
+const scroller = new ScrollToSmooth('a', {
+  onScrollStart: ({ startPosition, endPosition }) => {
+    console.log(`Scrolling from ${startPosition}px to ${endPosition}px`)
+  },
+  onScrollUpdate: ({ currentPosition, progress }) => {
+    progressBar.style.width = `${progress * 100}%`
+  },
+  onScrollEnd: ({ endPosition }) => {
+    analytics.track('scroll_complete', { position: endPosition })
+  },
+})
+```
+
+Or use CustomEvents that bubble through the DOM:
+
+```js
+document.addEventListener('scrolltosmooth:start', (e) => {
+  console.log(e.detail.startPosition, '→', e.detail.endPosition)
+})
+```
 
 ---
 
-## Why not just CSS smooth scrolling?
+## Why not just CSS `scroll-behavior: smooth`?
 
-Native CSS smooth scrolling works well for simple cases.  
-ScrollToSmooth adds functionality when you need:
+CSS smooth scrolling is great for simple use cases. ScrollToSmooth steps in when you need more control:
 
-- custom easing functions
-- scroll lifecycle events
-- dynamic duration control
-- fixed header offsets
-- programmatic scroll control
-- extendable plugin system
+| Feature | CSS Native | ScrollToSmooth |
+|---------|-----------|----------------|
+| Custom easing curves | ❌ | ✅ 31 built-in + custom |
+| Scroll lifecycle events | ❌ | ✅ start / update / end |
+| Dynamic duration | ❌ | ✅ fixed, relative, min/max |
+| Fixed header offset | ❌ | ✅ element, px, %, vh |
+| Horizontal / 2D scrolling | ❌ | ✅ via plugin |
+| Section snapping | Partial | ✅ customizable debounce |
+| Touch momentum | ❌ | ✅ via plugin |
+| Scroll queue | ❌ | ✅ chained animations |
+| CSS custom properties | ❌ | ✅ per-frame updates |
 
 ---
 
-## Contributing
+## Documentation
 
-Contributions are welcome.
+- **[Usage Guide](docs/usage.md)** — Setup, triggers, offsets, containers, and common patterns
+- **[API Reference](docs/api.md)** — Every method, option, event, and type
+- **[Plugins](docs/plugins.md)** — Horizontal, Snap, Touch Momentum + writing your own
+- **[Easing Functions](docs/easings.md)** — All 31 easings with import examples
+- **[Architecture](docs/architecture.md)** — Build system, internals, and design decisions
 
-Project structure:
+---
 
-```text
-src
-  core
-  easings
-  plugins
-```
+## Contributing
 
-Architecture documentation: `docs/architecture.md`
+Contributions are welcome! See the [architecture docs](docs/architecture.md) for project structure and build details.
+
+```bash
+npm run build        # build everything
+npm run lint         # lint TypeScript
+```
 
 ---
 
 ## Support
 
-If you find this project useful:
+If you find this project useful, consider supporting it:
+
+[→ paypal.me/bfiessinger](https://www.paypal.me/bfiessinger)
+
+---
+
+## License
 
-https://www.paypal.me/bfiessinger
+[MIT](LICENSE)