# wts-scroll

> A dependency-free, framework-agnostic TypeScript scrolling toolkit with custom scrollbars, infinite and virtual scrolling, synchronized views, Web Components, RTL support, and accessible native scrolling.

wts-scroll version 3 exposes an imperative `WtsScroll` controller and an optional `<wts-scroll>` custom element. It has no Angular or other framework runtime dependency. The package keeps the browser's native scroll container as the source of truth and supports ESM, CommonJS, TypeScript declarations, and SSR-safe imports.

Important usage notes:

- Give the mount target or `<wts-scroll>` element a definite height. Horizontal scrollers also need a definite width and content wider than the viewport.
- Import `wts-scroll/styles.css` when using the controller. The custom element injects its structural styles into its shadow root.
- Call `destroy()` when removing a controller-owned view. Do not mount multiple controllers on the same target.
- Use the existing `onReachStart` and `onReachEnd` callbacks for pagination. Use `preservePosition()` when prepending content.
- Optional capabilities are separate entry points so applications only load what they use.

## Documentation

- [README](./README.md): Installation, API reference, examples, accessibility, styling, browser behavior, and framework integration guidance.
- [Migration guide](./MIGRATION.md): Breaking changes and migration instructions from the Angular-only v2 package.
- [Complete LLM context](./llms-full.txt): Generated release documentation, package metadata, declarations, styles, migration guidance, and license in one file.

## Package entry points

- [Core controller types](./dist/index.d.ts): `WtsScroll`, controller options, events, state persistence, reach callbacks, and position preservation.
- [Web Component types](./dist/element.d.ts): `<wts-scroll>`, registration helpers, attributes, properties, methods, and typed events.
- [Timeline types](./dist/timeline.d.ts): Native `ScrollTimeline` capability detection and construction helpers.
- [Synchronization types](./dist/sync.d.ts): Logical-progress synchronization for two or more scrollers.
- [Virtual list types](./dist/virtual.d.ts): Fixed-size vertical virtualization with overscan and focus preservation.
- [Published styles](./dist/styles.css): Structural scrollbar styles and supported CSS custom properties.

## Optional

- [License](./LICENSE): MIT license.
