Struct Virtualizer 

pub struct Virtualizer { /* private fields */ }

The core virtualization engine.

Maintains all state needed for virtualization: measurements cache, visible ranges, scroll position, lane assignments, and scroll state. It produces VirtualItem metadata that Yew components use to render only the items within (and near) the visible viewport.

This engine is headless – it does not interact with the DOM directly. Instead, it accepts inputs (scroll offset, container size, measurements) and produces outputs (virtual items, total size, scroll targets).

Implementations

impl Virtualizer

pub fn empty() -> Self

Creates an empty virtualizer with zero items and no scrollable content.

This constructor is infallible and always returns a valid instance. It is intended as a safe fallback when normal construction fails, ensuring no unwrap(), expect(), or panic!() is needed.

Returns

• Virtualizer: An empty virtualizer that produces no virtual items.

pub fn new(options: VirtualizerOptions) -> Result<Self, VirtualizerError>

Creates a new virtualizer with the given options.

Validates configuration, initializes internal arrays, and computes the initial layout.

Parameters

• options: Configuration for the virtualizer.

Returns

• Ok(Virtualizer): A fully initialized virtualizer.
• Err(VirtualizerError): If configuration is invalid.

Errors

• Returns InvalidItemSize if the base size is zero or negative.
• Returns InvalidConfiguration if padding, gap, or lanes is invalid.

pub fn set_options( &mut self, options: VirtualizerOptions, ) -> Result<(), VirtualizerError>

Updates all options at runtime without recreating the virtualizer.

Validates the new configuration and recalculates layout. Measurement state is preserved across option changes.

Parameters

• options: The new configuration options.

Returns

• Ok(()): If options were applied successfully.
• Err(VirtualizerError): If the new configuration is invalid.

Errors

• Returns InvalidItemSize if the base size is zero or negative.
• Returns InvalidConfiguration if padding, gap, or lanes is invalid.

pub fn update_scroll_offset(&mut self, scroll_offset: f64, is_scrolling: bool)

Updates the scroll offset and recalculates the visible range.

This is the primary method called during scroll events.

Parameters

• scroll_offset: The new scroll position in pixels.
• is_scrolling: Whether the user is actively scrolling.

pub fn update_container_size(&mut self, container_size: f64)

Updates the container viewport size and recalculates the visible range.

Called when the scroll container is resized.

Parameters

• container_size: The new viewport size in pixels.

pub fn measure_item( &mut self, index: usize, size: f64, ) -> Result<MeasureItemOutcome, VirtualizerError>

Records a measurement for a specific item and recalculates layout if changed.

Parameters

• index: The index of the item that was measured.
• size: The measured size in pixels.

Returns

• Ok(MeasureItemOutcome): Layout change flag and DOM scroll compensation.
• Err(VirtualizerError): If the index is out of bounds or size is invalid.

Errors

• Returns IndexOutOfBounds if index >= item_count.
• Returns MeasurementError if size is invalid.

pub fn update_item_count(&mut self, new_count: usize)

Updates the total item count and recalculates layout.

Handles dataset size changes (insertions, removals) without full reinitialization.

Parameters

• new_count: The new total number of items.

pub fn get_offset_for_index( &self, index: usize, align: ScrollAlignment, ) -> Option<(f64, ScrollAlignment)>

Calculates the scroll offset needed to bring a specific item into view.

Accounts for scroll padding and alignment. Does not actually scroll.

Parameters

• index: The index of the target item.
• align: How to align the item within the viewport.

Returns

• Option<(f64, ScrollAlignment)>: The target scroll offset and resolved alignment, or None if the index has no measurement.

pub fn get_offset_for_alignment( &self, to_offset: f64, align: ScrollAlignment, item_size: f64, ) -> f64

Calculates the aligned scroll offset for a given target.

Parameters

• to_offset: The raw target offset.
• align: The alignment strategy.
• item_size: The size of the target item (used for center alignment).

Returns

• f64: The clamped and aligned scroll offset.

pub fn scroll_to_index( &self, index: usize, alignment: ScrollAlignment, ) -> Result<f64, VirtualizerError>

Calculates the scroll offset to navigate to a specific item.

This is a convenience wrapper that returns just the offset.

Parameters

• index: The index of the target item.
• alignment: How to align the item within the viewport.

Returns

• Ok(f64): The scroll offset to navigate to.
• Err(VirtualizerError): If the index is out of bounds.

Errors

• Returns IndexOutOfBounds if index >= item_count.

pub fn prepare_scroll_to_index( &mut self, index: usize, options: ScrollToOptions, now_ms: f64, ) -> Result<ScrollState, VirtualizerError>

Prepares a scroll-to-index operation with full options.

Returns the target offset, resolved alignment, and behavior for the hook layer to apply to the DOM.

Parameters

• index: The target item index.
• options: Scroll options including alignment and behavior.
• now_ms: Monotonic or wall time in milliseconds for reconciliation timeouts.

Returns

• Ok(ScrollState): The scroll state to reconcile.
• Err(VirtualizerError): If the index is out of bounds.

Errors

• Returns IndexOutOfBounds if index >= item_count.

pub fn prepare_scroll_to_offset( &mut self, to_offset: f64, options: ScrollToOptions, now_ms: f64, ) -> ScrollState

Prepares a scroll-to-offset operation.

Returns the target scroll state for the hook layer to apply.

Parameters

• to_offset: The target scroll offset in pixels.
• options: Scroll options including alignment and behavior.
• now_ms: Timestamp in milliseconds for reconciliation timeouts.

Returns

• ScrollState: The scroll state to reconcile.

pub fn prepare_scroll_by( &mut self, delta: f64, behavior: ScrollBehavior, now_ms: f64, ) -> ScrollState

Prepares a scroll-by operation (relative scroll).

Parameters

• delta: The number of pixels to scroll by.
• behavior: The scroll animation behavior.
• now_ms: Timestamp in milliseconds for reconciliation timeouts.

Returns

• ScrollState: The scroll state to reconcile.

pub fn refresh_programmatic_scroll_target(&mut self)

Recomputes the programmatic scroll target after measurements change.

Call this during smooth scroll reconciliation so the target offset tracks dynamic item sizes.

pub fn scroll_reconciliation_tick( &mut self, current_scroll: f64, now_ms: f64, ) -> ScrollReconcileAction

Advances programmatic scroll reconciliation for one animation frame.

Parameters

• current_scroll: Observed scroll offset from the DOM.
• now_ms: Current time in milliseconds.

Returns

• ScrollReconcileAction: Whether to keep scheduling frames.

pub fn measure(&mut self)

Forces a re-measure of all items by clearing the size cache.

pub fn get_virtual_item_for_offset(&self, offset: f64) -> Option<&VirtualItem>

Returns the virtual item at a given scroll offset.

Parameters

• offset: The scroll offset to look up.

Returns

• Option<&VirtualItem>: The item at the given offset.

pub fn get_virtual_items(&self) -> Vec<VirtualItem>

Returns the list of virtual items in the current visible range.

Uses the custom range extractor if provided, otherwise returns items in the contiguous range with overscan applied.

Returns

• Vec<VirtualItem>: Metadata for each item in the visible range.

pub fn total_size(&self) -> f64

Returns the total scrollable size of the virtualized region.

Returns

• f64: Total size in pixels including padding.

pub fn scroll_offset(&self) -> f64

Returns the current scroll offset.

Returns

• f64: Current scroll position in pixels.

pub fn container_size(&self) -> f64

Returns the current container viewport size.

Returns

• f64: Current container size in pixels.

pub fn range_start(&self) -> usize

Returns the start index of the visible range (inclusive).

Returns

• usize: The first index in the visible range.

pub fn range_end(&self) -> usize

Returns the end index of the visible range (inclusive).

Returns

• usize: The last index in the visible range.

pub fn options(&self) -> &VirtualizerOptions

Returns the current virtualizer options.

Returns

• &VirtualizerOptions: Reference to the current options.

pub fn item_count(&self) -> usize

Returns the item count.

Returns

• usize: The total number of items.

pub fn measurement_cache(&self) -> &MeasurementCache

Returns the measurement cache.

Returns

• &MeasurementCache: Reference to the measurement cache.

pub fn measurements(&self) -> &[VirtualItem]

Returns the full measurements array.

Returns

• &[VirtualItem]: The precomputed measurements for all items.

pub fn requires_measurement(&self) -> bool

Returns whether the virtualizer requires item measurement.

Returns

• bool: True if the item size mode requires runtime measurement.

pub fn is_scrolling(&self) -> bool

Returns whether the user is currently scrolling.

Returns

• bool: True if a scroll event is in progress.

pub fn is_scroll_forward(&self) -> Option<bool>

Returns whether the last scroll was forward (down/right).

Returns

• Option<bool>: True if forward, false if backward, None if no scroll.

pub fn scroll_adjustments(&self) -> f64

Returns the accumulated scroll adjustments.

Returns

• f64: The accumulated adjustments in pixels.

pub fn scroll_state(&self) -> Option<&ScrollState>

Returns the active scroll state, if any.

Returns

• Option<&ScrollState>: The active scroll operation state.

pub fn clear_scroll_state(&mut self)

Clears the active scroll state.

pub fn is_enabled(&self) -> bool

Returns whether the virtualizer is enabled.

Returns

• bool: True if the virtualizer is enabled.

pub fn set_is_scrolling(&mut self, is_scrolling: bool)

Sets the is_scrolling state.

Parameters

• is_scrolling: The new scrolling state.

pub fn item_size(&self, index: usize) -> Option<f64>

Returns the size of a specific item.

Parameters

• index: The item index.

Returns

• Option<f64>: The item size if the index is valid.

pub fn item_offset(&self, index: usize) -> Option<f64>

Returns the offset of a specific item.

Parameters

• index: The item index.

Returns

• Option<f64>: The item offset if the index is valid.

Trait Implementations

impl Clone for Virtualizer

fn clone(&self) -> Virtualizer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Virtualizer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.