ankurah-virtual-scroll 0.7.5

Platform-agnostic virtual scroll state machine with pagination for Ankurah
Documentation

ankurah-virtual-scroll

Platform-agnostic virtual scroll state machine with pagination for Ankurah.

Overview

ankurah-virtual-scroll provides smooth infinite scrolling through database-backed lists without loading everything into memory. It maintains a sliding window of items, expanding or sliding the window as the user scrolls, while preserving scroll position stability through intersection anchoring.

Features

  • Bidirectional pagination: Load older and newer content seamlessly
  • Scroll position stability: Maintain scroll position when loading new items via intersection anchoring
  • Reactive integration: Works with Ankurah's LiveQuery for real-time updates
  • Platform-agnostic: Core logic in Rust with WASM bindings (UniFFI in development)
  • Variable item heights: Handles items of different sizes correctly

Installation

[dependencies]
ankurah-virtual-scroll = "0.7"

Usage

Leptos / Dioxus (Pure Rust)

Use ScrollManager<V> directly - no macro needed:

React Web (WASM) / React Native (UniFFI)

For JavaScript/TypeScript frontends, use the generate_scroll_manager! macro in your bindings crate to generate platform-specific wrappers:

This generates MessageScrollManager with the appropriate bindings based on feature flags:

  • wasm feature: generates #[wasm_bindgen] bindings for React web apps
  • uniffi feature: generates UniFFI bindings for React Native apps (in development)

React Component Example

Modes

  • Live: At the newest edge, receiving real-time updates with auto-scroll
  • Backward: User scrolled toward older items, loading historical content
  • Forward: User scrolling back toward newer items, transitions to Live when reaching the edge

Architecture

The scroll manager handles:

  • Query construction (predicate + cursor + ordering + limit)
  • Mode tracking (Live / Backward / Forward)
  • Boundary detection (at earliest/latest based on result count)
  • Intersection anchoring for scroll stability

Platform layers handle:

  • DOM/FlatList binding and scroll events
  • Visible item detection (by EntityId)
  • Scroll position measurement and adjustment

Crates

  • ankurah-virtual-scroll - Core scroll manager implementation
  • ankurah-virtual-scroll-derive - Derive macro for generating typed scroll managers

Version Compatibility

Minor versions align with ankurah (e.g., 0.7.x works with ankurah 0.7.x). Patch versions are independent.

License

MIT OR Apache-2.0