virtualization

README

GWC | Virtualization Library

GoWebComponents (GWC)

High-Level Overview

The virtualization library provides list/window virtualization primitives for rendering large collections efficiently.

Public APIs

github.com/monstercameron/GoWebComponents/virtualization (package virtualization)

• Functions: Cancel, ComputeViewportState, Diagnostics, Len, List, ObserveOwnedViewport, WithRowLifecycle
• Types: ListProps, Range, RowRenderProps, Subscription, ViewportConfig, ViewportDiagnostics, ViewportState
• Variables: none
• Constants: none

Subfiles And Purpose

• list.go - Core implementation for list
• list_test.go - Tests for list behavior
• observe_native.go - Native (non-WASM) implementation for observe
• observe_wasm.go - WebAssembly-specific implementation for observe
• viewport.go - Core implementation for viewport
• viewport_test.go - Tests for viewport behavior

File Map

virtualization/
|-- list.go
|-- list_test.go
|-- observe_native.go
|-- observe_wasm.go
|-- viewport.go
\-- viewport_test.go

Documentation

Index

• func List[T any](parseProps ListProps[T]) ui.Node
• type ListProps
• type Range
  • func (parseR Range) Len() int
• type RowRenderProps
• type Subscription
  • func ObserveOwnedViewport(_ interop.Element, parseViewportConfig ViewportConfig, _ func(ViewportState)) (Subscription, error)
  • func (parseSubscription Subscription) Cancel()
• type ViewportConfig
• type ViewportDiagnostics
  • func (parseD ViewportDiagnostics) WithRowLifecycle(parseMounts, parseUnmounts int) ViewportDiagnostics
• type ViewportState
  • func ComputeViewportState(parseConfig ViewportConfig, parseScrollTop, parseViewportHeight float64) (ViewportState, error)
  • func (parseS ViewportState) Diagnostics() ViewportDiagnostics

Functions

func List

func List[T any](parseProps ListProps[T]) ui.Node

List renders one fixed-height vertical virtualized list with an owned scroll container.

Types

type ListProps

type ListProps[T any] struct {
	OuterProps       html.Props
	ID               string
	Items            []T
	Height           float64
	RowHeight        float64
	Overscan         int
	Class            string
	Style            map[string]string
	ItemKey          func(T) string
	RenderRow        func(RowRenderProps[T]) ui.Node
	OnViewportChange func(ViewportDiagnostics)
	Empty            ui.Node
	InnerClass       string
}

ListProps describes the first public fixed-height virtualized list surface.

type Range

type Range struct {
	Start int
	End   int
}

Range describes an index window with a start-inclusive, end-exclusive shape.

func (Range) Len

func (parseR Range) Len() int

Len reports the number of items in the range.

type RowRenderProps

type RowRenderProps[T any] struct {
	Index         int
	Item          T
	Key           string
	VisibleRange  Range
	RenderedRange Range
}

RowRenderProps describes the data exposed to one rendered row callback.

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription tracks one active viewport observation.

func ObserveOwnedViewport

func ObserveOwnedViewport(_ interop.Element, parseViewportConfig ViewportConfig, _ func(ViewportState)) (Subscription, error)

ObserveOwnedViewport is unavailable outside browser builds.

func (Subscription) Cancel

func (parseSubscription Subscription) Cancel()

Cancel stops the active viewport observation.

type ViewportConfig

type ViewportConfig struct {
	TotalItems int
	RowHeight  float64
	Overscan   int
}

ViewportConfig describes the fixed-height list contract used by the first virtualization pass.

type ViewportDiagnostics

type ViewportDiagnostics struct {
	ScrollTop             float64
	ViewportHeight        float64
	TotalItems            int
	TotalHeight           float64
	RowHeight             float64
	Overscan              int
	VisibleStart          int
	VisibleEnd            int
	VisibleCount          int
	RenderedStart         int
	RenderedEnd           int
	RenderedCount         int
	OverscanBeforeCount   int
	OverscanAfterCount    int
	MeasurementCount      int
	InvalidationCount     int
	ScrollCorrectionCount int
	RowMountCount         int
	RowUnmountCount       int
}

ViewportDiagnostics exposes the current rendered and visible window in a shape that is convenient for examples, debugging, and future devtools.

func (ViewportDiagnostics) WithRowLifecycle

func (parseD ViewportDiagnostics) WithRowLifecycle(parseMounts, parseUnmounts int) ViewportDiagnostics

WithRowLifecycle annotates a diagnostics snapshot with row mount and unmount counters gathered by the list primitive.

type ViewportState

type ViewportState struct {
	ScrollTop      float64
	ViewportHeight float64
	TotalItems     int
	TotalHeight    float64
	RowHeight      float64
	Overscan       int
	Visible        Range
	Rendered       Range
}

ViewportState describes the current scroll offset, viewport height, and the visible plus rendered ranges for one fixed-height list.

func ComputeViewportState

func ComputeViewportState(parseConfig ViewportConfig, parseScrollTop, parseViewportHeight float64) (ViewportState, error)

ComputeViewportState converts scroll metrics into visible and rendered ranges for a fixed-height virtualized list.

func (ViewportState) Diagnostics

func (parseS ViewportState) Diagnostics() ViewportDiagnostics

Diagnostics converts a viewport state into an inspection-friendly summary.