Super Sliver List

https://github.com/superlistapp/super_sliver_list
Admin
SuperSliverList and SuperListView are high-performance drop-in replacements for SliverList and...
Tokens:46,646
Snippets:297
Trust Score:8.6
License:MIT
Update:16 hours ago
Show doc for...
Tokens:
Raw
### Installation rules for Windows Flutter example

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/windows/CMakeLists.txt

Defines installation rules to copy support files next to the executable so the app can run in place from Visual Studio. It sets the install prefix to the build bundle directory, installs the executable, ICU data, Flutter library, and plugin libraries. It also re-copies the assets directory on each build and installs the AOT library only for Profile and Release configurations.

```cmake
# === Installation ===
# Support files are copied into place next to the executable, so that it can
# run in place. This is done instead of making a separate bundle (as on Linux)
# so that building and running from within Visual Studio will work.
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
# Make the "install" step default, as it's required to run.
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)

```

--------------------------------

### Install Binary, ICU Data, and Flutter Library

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Defines installation destinations for the application binary, the Flutter ICU data file, and the Flutter library. All are installed under the Runtime component, with the binary going to the install prefix, ICU data to the data directory, and the Flutter library to the lib directory.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Clean Build Bundle Directory Before Install

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Adds an install rule that removes the entire build bundle directory before installation, ensuring a clean bundle every time.

```cmake
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

--------------------------------

### Install Plugin Bundled Libraries

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Iterates over PLUGIN_BUNDLED_LIBRARIES and installs each bundled library into the lib directory under the Runtime component.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Configure Installation Bundle Directory

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Sets the build bundle directory to ${PROJECT_BINARY_DIR}/bundle and, if the install prefix is still at its default, forces CMAKE_INSTALL_PREFIX to that bundle directory. This makes 'installing' produce a relocatable bundle in the build directory.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()
```

--------------------------------

### Install Flutter assets and AOT library in CMakeLists.txt

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Configures installation of Flutter assets and the AOT library for Linux builds. Removes stale assets before copying, and installs the AOT library only on non-Debug builds.

```cmake
# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Test setup assigning a custom layout budget

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/layout-budget.md

Shows how to assign a custom budget in a test setUp to make precalculation deterministic. The test suite uses a counter-based _TestLayoutBudget for this purpose.

```dart
setUp(() {
  SuperSliverList.layoutBudget = MyTestLayoutBudget();
});
```

--------------------------------

### ItemCountBudget frame-count-based budget usage example

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/layout-budget.md

Custom budget that precalculates at most 8 item extents per layout pass. Install it globally via SuperSliverList.layoutBudget before building lists.

```dart
import "package:super_sliver_list/super_sliver_list.dart";

/// Precalculate at most 8 item extents per layout pass.
class ItemCountBudget extends SuperSliverListLayoutBudget {
  int _count = 0;
  static const limit = 8;

  @override
  void reset() {
    _count = 0;
  }

  @override
  void beginLayout() {}

  @override
  void endLayout() {}

  @override
  bool shouldLayoutNextItem() {
    ++_count;
    return _count <= limit;
  }
}

void main() {
  // Install globally before building lists.
  SuperSliverList.layoutBudget = ItemCountBudget();
}
```

--------------------------------

### CMake setup for Flutter managed directory and GTK dependency

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Sets up the Flutter managed build directory and finds the GTK+ 3 package using PkgConfig. This is required for building the Linux desktop application.

```cmake
# Flutter library and tool build rules.
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

# System-level dependencies.
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
```

--------------------------------

### Project-level CMake configuration for Windows Flutter example

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/windows/CMakeLists.txt

Configures the CMake project for a Windows Flutter application, setting the minimum CMake version, project name, binary name, and enabling modern CMake policies. It defines build configurations (Debug, Profile, Release) and sets linker/compiler flags for the Profile mode. Also adds Unicode definitions and a function to apply standard compilation settings to targets.

```cmake
# Project-level configuration.
cmake_minimum_required(VERSION 3.14)
project(example LANGUAGES CXX)

# The name of the executable created for the application. Change this to change
# the on-disk name of your application.
set(BINARY_NAME "example")

# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
# versions of CMake.
cmake_policy(SET CMP0063 NEW)

# Define build configuration option.
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
  set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
else()
  if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set(CMAKE_BUILD_TYPE "Debug" CACHE
      STRING "Flutter build mode" FORCE)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
      "Debug" "Profile" "Release")
  endif()
endif()
# Define settings for the Profile build mode.
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")

# Use Unicode for all projects.
add_definitions(-DUNICODE -D_UNICODE)

# Compilation settings that should be applied to most targets.
#
# Be cautious about adding new options here, as plugins use this function by
# default. In most cases, you should add new options to specific targets instead
# of modifying this function.
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE "$<$<CONFIG:Debug>:_DEBUG>")
endfunction()

# Flutter library and tool build rules.
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

# Application build; see runner/CMakeLists.txt.
add_subdirectory("runner")

# Generated plugin build rules, which manage building the plugins and adding
# them to the application.
include(flutter/generated_plugins.cmake)

```

--------------------------------

### Default layoutBudget static field assignment

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/layout-budget.md

Installs the default budget as a static field on SuperSliverList, using _TimeSuperSliverListLayoutBudget with a budget of 3 milliseconds.

```dart
static SuperSliverListLayoutBudget layoutBudget =
    _TimeSuperSliverListLayoutBudget(
  budget: const Duration(milliseconds: 3),
);
```

--------------------------------

### Wiring into a scroll physics chain

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/scroll-physics.md

Example of how to integrate SuperRangeMaintainingScrollPhysics into a custom ScrollBehavior and apply it to a widget tree using ScrollConfiguration.

```dart
class _MyScrollBehavior extends ScrollBehavior {
  const _MyScrollBehavior();

  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return SuperRangeMaintainingScrollPhysics(
        parent: super.getScrollPhysics(context));
  }
}

Widget build(BuildContext context) {
  return ScrollConfiguration(
    behavior: _MyScrollBehavior(),
    child: CustomScrollView(
      slivers: [
        SuperSliverList(
          delegate: SliverChildBuilderDelegate(
            (context, index) => ListTile(title: Text('Item $index')),
            childCount: 10000,
          ),
        ),
      ],
    ),
  );
}
```

--------------------------------

### Builder form with custom extent estimation and a list controller

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Use SuperSliverList.builder for large lists with a ListController and a constant extentEstimation to keep estimation cost O(1). The example sets itemCount to 100000 and provides a constant estimate of 100px per item.

```Dart
class _MyState extends State<MyWidget> {
  final _listController = ListController();

  @override
  Widget build(BuildContext context) {
    return CustomScrollView(
      slivers: [
        SuperSliverList.builder(
          listController: _listController,
          itemCount: 100000,
          itemBuilder: (context, index) {
            return ListTile(title: Text('Item $index'));
          },
          // All items are approximately 100px tall; provide a constant
          // estimate so estimation cost is O(1) for very large lists.
          extentEstimation: (int? index, double crossAxisExtent) => 100.0,
        ),
      ],
    );
  }
}
```

--------------------------------

### Custom ExtentPrecalculationPolicy for eager precalculation

Source: https://github.com/superlistapp/super_sliver_list/blob/main/README.md

Subclass ExtentPrecalculationPolicy to control when extents are precalculated asynchronously. In this example, extents are eagerly precalculated for lists with fewer than 100 items. The threshold is arbitrary; precalculating for large lists has diminishing returns.

```dart
class MyPrecalculationPolicy extends ExtentPrecalculationPolicy {
  @override
  bool shouldPrecaculateExtents(ExtentPrecalculationContext context)  {
    return context.numberOfItems < 100;
  }
}

return SuperSliverList(
    delegate: /*...*/,
    extentPrecalculationPolicy: myPolicy,
)
```

--------------------------------

### _TimeSuperSliverListLayoutBudget default implementation

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/layout-budget.md

Private default implementation using a Stopwatch. beginLayout starts the stopwatch, endLayout stops it, and shouldLayoutNextItem returns true while elapsed time is less than the budget. reset restarts the stopwatch.

```dart
class _TimeSuperSliverListLayoutBudget extends SuperSliverListLayoutBudget {
  _TimeSuperSliverListLayoutBudget({
    required this.budget,
  });

  @override
  void reset() {
    _stopwatch.reset();
  }

  @override
  void beginLayout() {
    _stopwatch.start();
  }

  @override
  void endLayout() {
    _stopwatch.stop();
  }

  @override
  bool shouldLayoutNextItem() {
    return _stopwatch.elapsed < budget;
  }

  final _stopwatch = Stopwatch();

  final Duration budget;
}
```

--------------------------------

### Policy with external condition that changes at runtime

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/extent-precalculation-policy.md

Eagerly precalculates for lists with fewer than 100 items and re-triggers precalculation when the underlying configuration changes. The pattern is used in the example app's DefaultExtentPrecalculationPolicy. Call valueDidChange() after changing the condition to let attached lists re-check on next layout.

```dart
import "package:super_sliver_list/super_sliver_list.dart";

class MyPrecalculationPolicy extends ExtentPrecalculationPolicy {
  bool enabled = false;

  @override
  void onAttached() {
    super.onAttached();
    // e.g. listen to an external ValueNotifier that updates `enabled`.
  }

  @override
  void onDetached() {
    super.onDetached();
  }

  @override
  bool shouldPrecalculateExtents(ExtentPrecalculationContext context) {
    // The threshold is arbitrary; diminishing returns for large lists.
    return enabled && context.numberOfItems < 100;
  }

  void setEnabled(bool value) {
    if (enabled != value) {
      enabled = value;
      valueDidChange(); // let attached lists re-check on next layout
    }
  }
}
```

--------------------------------

### Jumping / animating with a precalculation policy

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Shows a custom ExtentPrecalculationPolicy that precalculates extents only when the list has fewer than 100 items, and a method animateToItemAtHalf that uses ListController.animateToItem with a ScrollController, alignment 0.5, and dynamic duration/curve based on estimated distance.

```Dart
class MyPrecalculationPolicy extends ExtentPrecalculationPolicy {
  @override
  bool shouldPrecalculateExtents(ExtentPrecalculationContext context) {
    return context.numberOfItems < 100;
  }
}

class _MyState extends State<MyWidget> {
  final _listController = ListController();
  final _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return CustomScrollView(
      controller: _scrollController,
      slivers: [
        SuperSliverList.builder(
          listController: _listController,
          extentPrecalculationPolicy: MyPrecalculationPolicy(),
          itemCount: 1000,
          itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
        ),
      ],
    );
  }

  void animateToItemAtHalf(int index) {
    _listController.animateToItem(
      index: () => index,
      scrollController: _scrollController,
      alignment: 0.5,
      duration: (estimatedDistance) => const Duration(milliseconds: 300),
      curve: (estimatedDistance) => Curves.easeOutCubic,
    );
  }
}
```

--------------------------------

### SuperSliverList Constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/configuration.md

Configuration for the SuperSliverList widget is provided through its constructor options. This snippet documents the available parameters for the primary constructor and its named constructors (builder, separated, list).

```APIDOC
## SuperSliverList Constructor

### Description
Configuration for the SuperSliverList widget is provided through its constructor options. This snippet documents the available parameters for the primary constructor and its named constructors (builder, separated, list).

### Parameters
- **key** (`Key?`) - Optional - Flutter widget key (super parameter).
- **delegate** (`SliverChildDelegate`) - Required (primary constructor) - Child delegate (`SliverChildListDelegate` / `SliverChildBuilderDelegate` / custom).
- **itemBuilder** (`NullableIndexedWidgetBuilder`) - Required (`builder`, `separated`) - `Widget? Function(BuildContext, int)` building each child.
- **separatorBuilder** (`NullableIndexedWidgetBuilder`) - Required (`separated`) - Builder for separators between items; must never return `null`.
- **children** (`List<Widget>`) - Required (`list`) - Static child widgets.
- **findChildIndexCallback** (`ChildIndexGetter?`) - Optional - Maps child widget → index.
- **itemCount** (`int?`) - Optional - Child count (`builder`); `null` = unbounded. For `separated`, total children are `max(0, itemCount * 2 - 1)`.
- **listController** (`ListController?`) - Optional - Controller for extent queries and jump/animate. One controller per list.
- **extentEstimation** (`ExtentEstimationProvider?`) - Optional - Custom extent estimation: `double Function(int? index, double crossAxisExtent)`.
- **extentPrecalculationPolicy** (`ExtentPrecalculationPolicy?`) - Optional - Policy for asynchronous extent precalculation.
- **delayPopulatingCacheArea** (`bool`) - Optional - Build cache-area items only after scrolling slows down.
- **layoutKeptAliveChildren** (`bool`) - Optional - Lay out kept-alive children and apply paint transforms.
- **addAutomaticKeepAlives** (`bool`) - Optional - Add automatic keep-alives to children (named constructors).
- **addRepaintBoundaries** (`bool`) - Optional - Add repaint boundaries to children (named constructors).
- **addSemanticIndexes** (`bool`) - Optional - Add semantic indexes to children (named constructors).

### Notes
- Defaults differ per constructor only for the super parameters.
- See api-reference/super-sliver-list.md for full signatures.
```

--------------------------------

### ListController constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/configuration.md

Creates a ListController with optional callbacks for attach and detach events. The controller can be attached to a single SuperSliverList at a time and provides methods to manage item extents and items.

```APIDOC
## ListController constructor

### Description
Creates a ListController with optional callbacks for attach and detach events. The controller can be attached to a single SuperSliverList at a time and provides methods to manage item extents and items.

### Constructor
`ListController({VoidCallback? onAttached, VoidCallback? onDetached})`

### Parameters
- **onAttached** (`VoidCallback?`) - Optional - Called when attached to a `SuperSliverList`.
- **onDetached** (`VoidCallback?`) - Optional - Called when detached from a `SuperSliverList`.

### Behavioral Contract
- Attachable to a single list at a time.
- All members except `isAttached` assert when detached.
- Mutators (`invalidateExtent`, `invalidateAllExtents`, `addItem`, `removeItem`) reject calls while `isLocked` (during layout).
```

--------------------------------

### SuperSliverList Public Fields

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Configuration fields for the SuperSliverList widget, including list controller, extent estimation, precalculation policy, and layout budget.

```APIDOC
## Public Fields

### listController
- **Type**: `ListController?`
- **Default**: `null`
- **Description**: Access to extents of individual children and jump-to/animate-to-item functionality.

### extentEstimation
- **Type**: `ExtentEstimationProvider?`
- **Default**: `null` (default estimate of `100.0`)
- **Description**: Custom per-item extent estimation callback.

### extentPrecalculationPolicy
- **Type**: `ExtentPrecalculationPolicy?`
- **Default**: `null`
- **Description**: Policy for asynchronously precalculating extents.

### delayPopulatingCacheArea
- **Type**: `bool`
- **Default**: `true`
- **Description**: Delay building cache-area items during fast scrolling.

### layoutKeptAliveChildren
- **Type**: `bool`
- **Default**: `false`
- **Description**: Lay out (and paint-transform) kept-alive children.

### layoutBudget (static)
- **Type**: `SuperSliverListLayoutBudget`
- **Default**: `_TimeSuperSliverListLayoutBudget(budget: const Duration(milliseconds: 3))`
- **Description**: Shared layout budget controlling how much build time may be spent on extent precalculation per layout pass. Assignable; see [layout-budget.md](layout-budget.md).
```

--------------------------------

### SuperSliverList Constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Creates a SuperSliverList widget, a drop-in replacement for SliverList that handles large lists with variable extents efficiently. It accepts a delegate for children and optional parameters for extent estimation, list control, and layout optimization.

```APIDOC
## SuperSliverList Constructor

### Description
Creates a SuperSliverList widget, a drop-in replacement for SliverList that handles large lists with variable extents efficiently. It accepts a delegate for children and optional parameters for extent estimation, list control, and layout optimization.

### Constructor
```dart
const SuperSliverList({
  super.key,
  required super.delegate,
  this.extentPrecalculationPolicy,
  this.listController,
  this.extentEstimation,
  this.delayPopulatingCacheArea = true,
  this.layoutKeptAliveChildren = false,
});
```

### Parameters
- **key** (`Key?`) - Optional - Flutter widget key.
- **delegate** (`SliverChildDelegate`) - Required - Delegate providing the children of the list. Any delegate accepted by `SliverList` works (`SliverChildListDelegate` for a `List<Widget>`, `SliverChildBuilderDelegate` for lazily built children).
- **extentPrecalculationPolicy** (`ExtentPrecalculationPolicy?`) - Optional - Optional policy controlling asynchronous extent precalculation. See `ExtentPrecalculationPolicy`.
- **listController** (`ListController?`) - Optional - Optional `ListController`. When set, provides access to extents of individual children and the ability to jump to / animate to a specific item. A controller can only be attached to a single `SuperSliverList` at a time.
- **extentEstimation** (`ExtentEstimationProvider?`) - Optional - Optional callback overriding the estimated extent of items. Signature: `double Function(int? index, double crossAxisExtent)`. Return non-zero for a `null` index when all estimated items share the same extent (this saves calls for large lists); return zero for a `null` index when each item has a different extent.
- **delayPopulatingCacheArea** (`bool`) - Optional - Default: `true` - When `true`, the items in the cache area are only built after scrolling slows down. Optimization that kicks in during fast scrolling when all items are replaced on every frame.
- **layoutKeptAliveChildren** (`bool`) - Optional - Default: `false` - When `true`, children with keep-alive are laid out (not just kept alive), so their layout is maintained and a proper paint transform is applied.
```

--------------------------------

### SliverGeometry.childObstructionExtent

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/sliver-extensions.md

Gets the child obstruction extent from the sliver geometry, or null if no obstruction metadata is present. This property is used to determine the offset when revealing a child sliver.

```APIDOC
## GET SliverGeometry.childObstructionExtent

### Description
Returns the extent from the edges in which this sliver obstructs its child, or `null` if the geometry carries no obstruction metadata. This is similar to `maxScrollObstructionExtent`, with the key difference that `maxScrollObstructionExtent` affects slivers *after* this one, while this property affects *child* slivers (e.g. a `SuperSliverList` nested inside a pinned header sliver). The value is used to determine the offset when revealing a child and should not be affected by the scroll offset.

### Method
GET

### Endpoint
SliverGeometry.childObstructionExtent

### Parameters
None

### Response
#### Success Response (200)
- **childObstructionExtent** (ChildObstructionExtent?) - The obstruction extent, or null if no metadata.

#### Response Example
```json
{
  "childObstructionExtent": null
}
```
```

--------------------------------

### SuperSliverList.builder(...)

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Creates a SuperSliverList from a widget builder. This constructor mirrors SliverList.builder and allows building children on demand via a callback.

```APIDOC
## SuperSliverList.builder(...)

### Description
Creates a `SuperSliverList` from a widget builder. See `SliverList.builder` for details.

### Constructor
`SuperSliverList.builder({...})`

### Parameters
#### Required Parameters
- **itemBuilder** (`NullableIndexedWidgetBuilder`) - Required - Called as `Widget? Function(BuildContext context, int index)` to build each child. A `null` return means "no child at this index".

#### Optional Parameters
- **findChildIndexCallback** (`ChildIndexGetter?`) - Optional - Default: `null` - Maps a child widget to its index (used when child order/identity matters).
- **itemCount** (`int?`) - Optional - Default: `null` - Number of children. `null` means unknown/ambivalent.
- **addAutomaticKeepAlives** (`bool`) - Optional - Default: `true` - Whether automatic keep-alive is added to children.
- **addRepaintBoundaries** (`bool`) - Optional - Default: `true` - Whether repaint boundaries are added to children.
- **addSemanticIndexes** (`bool`) - Optional - Default: `true` - Whether semantic indexes are added to children.

### Example
```dart
SuperSliverList.builder(
  itemBuilder: (context, index) => Text('Item $index'),
  itemCount: 10,
)
```

```

--------------------------------

### Basic drop-in replacement for ListView.builder

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-list-view.md

Shows how to use SuperListView.builder as a direct replacement for ListView.builder, rendering 1000 items with a simple ListTile.

```dart
import "package:super_sliver_list/super_sliver_list.dart";

class _MyState extends State<MyWidget> {
  @override
  Widget build(BuildContext context) {
    return SuperListView.builder(
      itemCount: 1000,
      itemBuilder: (context, index) {
        return ListTile(title: Text('Item $index'));
      },
    );
  }
}
```

--------------------------------

### SuperListView Constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/configuration.md

Constructs a SuperListView widget with configurable options for children, lazy building, separators, and list behavior. Inherits parameters from BoxScrollView and supports both static and lazy child models.

```APIDOC
## SuperListView Constructor

### Description
Creates a SuperListView widget with configurable options for children, lazy building, separators, and list behavior. Inherits parameters from BoxScrollView and supports both static and lazy child models.

### Parameters

#### Constructor Parameters
- **children** (`List<Widget>`) - Optional - Static children (primary constructor). Default: `const <Widget>[]`.
- **itemBuilder** (`NullableIndexedWidgetBuilder`) - Required for `builder` - Lazy child builder.
- **separatorBuilder** (`IndexedWidgetBuilder`) - Required for `separated` - Separator builder (must return non-null widget).
- **itemCount** (`int?`) - Optional - Child count for `builder`; required `int` for `separated` (must be ≥ 0). Default: `null`.
- **findChildIndexCallback** (`ChildIndexGetter?`) - Optional - Child widget → index mapping. Default: `null`.
- **childrenDelegate** (`SliverChildDelegate`) - Required for `custom` - Explicit child model.
- **semanticChildCount** (`int?`) - Optional - Semantic child count; in `builder` must satisfy `semanticChildCount <= itemCount` when both are set. Default: `children.length` (primary) or `itemCount` (`builder`).
- **addAutomaticKeepAlives** (`bool`) - Optional - Child wrapping option. Default: `true`.
- **addRepaintBoundaries** (`bool`) - Optional - Child wrapping option. Default: `true`.
- **addSemanticIndexes** (`bool`) - Optional - Child wrapping option. Default: `true`.
- **listController** (`ListController?`) - Optional - See `SuperSliverList`. Default: `null`.
- **extentEstimation** (`ExtentEstimationProvider?`) - Optional - See `SuperSliverList`. Default: `null` → `100.0`.
- **extentPrecalculationPolicy** (`ExtentPrecalculationPolicy?`) - Optional - See `SuperSliverList`. Default: `null`.
- **delayPopulatingCacheArea** (`bool`) - Optional - Differs from `SuperSliverList` (default `true`). Default: `false`.

#### Inherited Parameters (from `BoxScrollView`)
- **scrollDirection** - Optional - Scroll direction.
- **reverse** - Optional - Reverse scroll direction.
- **controller** - Optional - Scroll controller.
- **primary** - Optional - Primary scroll view.
- **physics** - Optional - Scroll physics.
- **shrinkWrap** - Optional - Shrink-wrap content.
- **padding** - Optional - Padding.
- **cacheExtent** - Optional - Cache extent.
- **dragStartBehavior** - Optional - Drag start behavior.
- **keyboardDismissBehavior** - Optional - Keyboard dismiss behavior.
- **restorationId** - Optional - Restoration ID.
- **clipBehavior** - Optional - Clip behavior.

### Notes
- All inherited parameters are optional with no local defaults.
- The `delayPopulatingCacheArea` default differs from `SuperSliverList` (which defaults to `true`).
```

--------------------------------

### SuperSliverList.list(...)

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Creates a SuperSliverList from a fixed list of child widgets (wrapped in a SliverChildListDelegate).

```APIDOC
## SuperSliverList.list(...)

### Description
Creates a `SuperSliverList` from a fixed list of child widgets (wrapped in a `SliverChildListDelegate`).

### Constructor
`SuperSliverList.list({...})`

### Parameters
#### Required Parameters
- **children** (`List<Widget>`) - Required - The child widgets of the list.

#### Optional Parameters
- **addAutomaticKeepAlives** (`bool`) - Optional - Default: `true` - See `builder`.
- **addRepaintBoundaries** (`bool`) - Optional - Default: `true` - See `builder`.
- **addSemanticIndexes** (`bool`) - Optional - Default: `true` - See `builder`.

### Example
```dart
SuperSliverList.list(
  children: [
    Text('Item 1'),
    Text('Item 2'),
  ],
)
```

```

--------------------------------

### SuperRangeMaintainingScrollPhysics constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/configuration.md

Creates a SuperRangeMaintainingScrollPhysics instance with an optional parent physics. This physics is used to maintain range during scrolling.

```APIDOC
## SuperRangeMaintainingScrollPhysics constructor

### Description
Creates a SuperRangeMaintainingScrollPhysics instance with an optional parent physics. This physics is used to maintain range during scrolling.

### Constructor
`SuperRangeMaintainingScrollPhysics({ScrollPhysics? parent})`

### Parameters
- **parent** (`ScrollPhysics?`) - Optional - Next element in the physics chain (super parameter).
```

--------------------------------

### CMake executable target definition and linking

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Defines the application executable target with source files and applies standard settings. Links the Flutter library and GTK, and adds a dependency on flutter_assemble. The executable name must match BINARY_NAME for flutter run to work.

```cmake
# Define the application target. To change its name, change BINARY_NAME above,
# not the value here, or `flutter run` will no longer work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)

# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})

# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)

# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Overridden Lifecycle Methods

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Lifecycle methods overridden by SuperSliverList to create and update its element and render object.

```APIDOC
## Overridden Lifecycle Methods

### createElement
- **Signature**: `@override SliverMultiBoxAdaptorElement createElement() => SuperSliverMultiBoxAdaptorElement(this, replaceMovedChildren: true);`
- **Purpose**: Creates the associated element (`SuperSliverMultiBoxAdaptorElement`).

### createRenderObject
- **Signature**: `@override RenderSliverMultiBoxAdaptor createRenderObject(BuildContext context)`
- **Purpose**: Creates the `RenderSuperSliverList` render object, wiring in `extentPrecalculationPolicy`, `estimateExtent` (or `_defaultEstimateExtent`), `delayPopulatingCacheArea`, and `layoutKeptAliveChildren`.

### updateRenderObject
- **Signature**: `@override void updateRenderObject(BuildContext context, covariant RenderObject renderObject)`
- **Purpose**: Propagates the current widget field values into the existing render object on update.
```

--------------------------------

### Include Generated Plugin Build Rules

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Includes the generated CMake file flutter/generated_plugins.cmake, which manages building the plugins and adding them to the application.

```cmake
include(flutter/generated_plugins.cmake)
```

--------------------------------

### CMake function APPLY_STANDARD_SETTINGS for compile options

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Defines a CMake function that applies standard compile features, warnings, and optimization settings to a target. It sets C++14, enables -Wall and -Werror, and adds -O3 and NDEBUG for non-Debug configurations.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_14)
  target_compile_options(${TARGET} PRIVATE -Wall -Werror)
  target_compile_options(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:-O3>")
  target_compile_definitions(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
endfunction()
```

--------------------------------

### SuperSliverList.separated(...)

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Creates a SuperSliverList from a widget builder plus a separator builder that produces the separator between consecutive items. The builder wraps both into a single delegate in which even indices are items and odd indices are separators.

```APIDOC
## SuperSliverList.separated(...)

### Description
Creates a `SuperSliverList` from a widget builder plus a separator builder that produces the separator between consecutive items. The builder wraps both into a single delegate in which even indices are items and odd indices are separators (item `index` appears at list index `2 * index`; the child count is `max(0, itemCount * 2 - 1)`).

### Constructor
`SuperSliverList.separated({...})`

### Parameters
#### Required Parameters
- **itemBuilder** (`NullableIndexedWidgetBuilder`) - Required - Builds the item at `index ~/ 2`.
- **separatorBuilder** (`NullableIndexedWidgetBuilder`) - Required - Builds the separator at `index ~/ 2`. Must not return `null` — returning `null` triggers a `FlutterError`.

#### Optional Parameters
- **findChildIndexCallback** (`ChildIndexGetter?`) - Optional - Default: `null` - See `builder`.
- **itemCount** (`int?`) - Optional - Default: `null` - Number of items; total children are `max(0, itemCount * 2 - 1)`.
- **addAutomaticKeepAlives** (`bool`) - Optional - Default: `true` - See `builder`.
- **addRepaintBoundaries** (`bool`) - Optional - Default: `true` - See `builder`.
- **addSemanticIndexes** (`bool`) - Optional - Default: `true` - See `builder`.

### Example
```dart
SuperSliverList.separated(
  itemBuilder: (context, index) => Text('Item $index'),
  separatorBuilder: (context, index) => Divider(),
  itemCount: 10,
)
```

```

--------------------------------

### Attaching the policy to a SuperListView

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/extent-precalculation-policy.md

Shows how to attach a policy instance to SuperListView.builder via the extentPrecalculationPolicy parameter.

```dart
SuperListView.builder(
  extentPrecalculationPolicy: MyPrecalculationPolicy(),
  itemCount: 500,
  itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
)
```

--------------------------------

### getOffsetToReveal method signature

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/list-controller.md

Testing-only method that computes the scroll offset to reveal an item at a given alignment. Marked @visibleForTesting, not for application code.

```dart
@visibleForTesting
double getOffsetToReveal(int index, double alignment, {Rect? rect})
```

--------------------------------

### SuperListView.builder basic usage

Source: https://github.com/superlistapp/super_sliver_list/blob/main/README.md

Drop-in replacement for ListView.builder. Use it the same way as ListView.builder with itemCount and itemBuilder.

```dart
SuperListView.builder(
  itemCount: 1000,
  itemBuilder: (context, index) {
    return ListTile(title: Text('Item $index'));
  },
)
```

--------------------------------

### numberOfItems

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/list-controller.md

Returns the total number of items in the list.

```APIDOC
## numberOfItems

### Description
Returns the total number of items in the list.

### Return Value
- **int** - The total number of items.

### Assertions
- Throws an assertion if the controller is not attached.

### Example
```dart
int count = controller.numberOfItems;
```
```

--------------------------------

### Basic usage: attach, jump, and observe visible range

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/list-controller.md

Shows attaching a ListController to a SuperSliverList, jumping to an item, and reading the visible range. Requires a ScrollController and a StatefulWidget.

```dart
import "package:super_sliver_list/super_sliver_list.dart";

class _MyState extends State<MyWidget> {
  final _listController = ListController(
    onAttached: () => print("attached"),
    onDetached: () => print("detached"),
  );
  final _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return CustomScrollView(
      controller: _scrollController,
      slivers: [
        SuperSliverList.builder(
          listController: _listController,
          itemCount: 1000,
          itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
        ),
      ],
    );
  }

  void onJumpPressed() {
    final range = _listController.visibleRange;
    if (range != null) {
      final (first, last) = range;
      print('showing items $first..$last');
    }
    _listController.jumpToItem(
      index: 500,
      scrollController: _scrollController,
      alignment: 0.5, // center the item in the viewport
    );
  }
}
```

--------------------------------

### Using the context for a viewport-relative threshold

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/extent-precalculation-policy.md

Precalculates while the estimated content is still within 10 viewports or when the item count is below 100. The myList function shows how to pass the policy to SuperSliverList.builder.

```dart
class ThresholdPolicy extends ExtentPrecalculationPolicy {
  @override
  bool shouldPrecalculateExtents(ExtentPrecalculationContext context) {
    // Precalculate while the estimated content is still within 10 viewports.
    final content = context.contentTotalExtent ?? 0;
    final viewport = context.viewportMainAxisExtent ?? 0;
    return content < viewport * 10 || context.numberOfItems < 100;
  }
}

Widget myList(ExtentPrecalculationPolicy policy) {
  return SuperSliverList.builder(
    extentPrecalculationPolicy: policy,
    itemCount: 1000,
    itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
  );
}
```

--------------------------------

### SuperSliverList constructor

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Primary constructor for SuperSliverList, a drop-in replacement for SliverList that handles large lists with variable extents. Accepts a delegate, optional extent precalculation policy, list controller, extent estimation callback, and flags for cache area delay and keep-alive layout.

```dart
const SuperSliverList({
  super.key,
  required super.delegate,
  this.extentPrecalculationPolicy,
  this.listController,
  this.extentEstimation,
  this.delayPopulatingCacheArea = true,
  this.layoutKeptAliveChildren = false,
});
```

--------------------------------

### ListController jumpToItem and animateToItem

Source: https://github.com/superlistapp/super_sliver_list/blob/main/README.md

Provide ListController to SuperSliverList/SuperListView to jump or animate to a specific item. jumpToItem uses alignment 0.5; animateToItem accepts duration and curve functions based on estimated distance.

```dart
class _MyState extends State<MyWidget> {
  final _listController = ListController();
  final _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return SuperListView.builder(
      listController: _listController,
      controller: _scrollController,
      itemCount: 1000,
      itemBuilder: (context, index) {
        return ListTile(title: Text('Item $index'));
      },
    );
  }

  void jumpToItem(int index) {
    _listController.jumpToItem(
      index: index,
      scrollController: _scrollController,
      alignment: 0.5,
    );
  }

  void animateToItem(int index) {
    _listController.animateToItem(
      index: index,
      scrollController: _scrollController,
      alignment: 0.5,
      // You can provide duration and curve depending on the estimated
      // distance between currentPosition and the target item position.
      duration: (estimatedDistance) => Duration(milliseconds: 250),
      curve: (estimatedDistance) => Curves.easeInOut,
    );
  }
}
```

--------------------------------

### Jumping / animating to a specific item with ListController

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-list-view.md

Demonstrates using ListController with SuperListView.builder to jump or animate to a specific item. jumpToItem uses an index directly, while animateToItem uses callbacks for index, duration, and curve.

```dart
class _MyState extends State<MyWidget> {
  final _listController = ListController();
  final _scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return SuperListView.builder(
      listController: _listController,
      controller: _scrollController,
      itemCount: 1000,
      itemBuilder: (context, index) {
        return ListTile(title: Text('Item $index'));
      },
    );
  }

  void jumpToItem(int index) {
    _listController.jumpToItem(
      index: index,
      scrollController: _scrollController,
      alignment: 0.5,
    );
  }

  void animateToItem(int index) {
    _listController.animateToItem(
      index: () => index,
      scrollController: _scrollController,
      alignment: 0.5,
      duration: (estimatedDistance) => const Duration(milliseconds: 250),
      curve: (estimatedDistance) => Curves.easeInOut,
    );
  }
}
```

--------------------------------

### Set Runtime Output Directory to intermediates_do_not_run

Source: https://github.com/superlistapp/super_sliver_list/blob/main/example/linux/CMakeLists.txt

Configures the CMake target property RUNTIME_OUTPUT_DIRECTORY to place the built binary in a subdirectory named intermediates_do_not_run. This prevents users from running the unbundled copy directly, ensuring resources are in the correct relative locations.

```cmake
set_target_properties(${BINARY_NAME}
  PROPERTIES
  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

--------------------------------

### Basic drop-in replacement for SliverList inside a CustomScrollView

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/super-sliver-list.md

Use SuperSliverList as a direct replacement for SliverList within a CustomScrollView. Wraps a SliverChildListDelegate with a fixed list of children inside SliverPadding.

```Dart
import "package:flutter/foundation.dart";
import "package:super_sliver_list/super_sliver_list.dart";

Widget build(BuildContext context) {
  return CustomScrollView(
    slivers: <Widget>[
      SliverPadding(
        padding: const EdgeInsets.all(20.0),
        sliver: SuperSliverList(
          delegate: SliverChildListDelegate(
            <Widget>[
              const Text("I'm dedicating every day to you"),
              const Text('Domestic life was never quite my style'),
              const Text('When you smile, you knock me out, I fall apart'),
              const Text('And I thought I was so smart'),
            ],
          ),
        ),
      ),
    ],
  );
}
```

--------------------------------

### applyTo

Source: https://github.com/superlistapp/super_sliver_list/blob/main/_autodocs/api-reference/scroll-physics.md

Rebuilds the physics chain when the scroll view reconfigures. Returns a new SuperRangeMaintainingScrollPhysics whose parent chain is rebuilt via buildParent(ancestor).

```APIDOC
## Method: applyTo

### Description
Rebuilds the physics chain when the scroll view reconfigures. Returns a new SuperRangeMaintainingScrollPhysics whose parent chain is rebuilt via buildParent(ancestor).

### Signature
```dart
@override
SuperRangeMaintainingScrollPhysics applyTo(ScrollPhysics? ancestor) {
  return SuperRangeMaintainingScrollPhysics(parent: buildParent(ancestor));
}
```

### Parameters
- **ancestor** (`ScrollPhysics?`) - The ancestor physics element to build the parent chain from.

### Return Value
- `SuperRangeMaintainingScrollPhysics` - A new instance with the rebuilt parent chain.
```
Tokens:
Raw