autoscroll_sdk Free

Register-and-scroll-to-widget-location SDK. Register a named location's GlobalKey once during build, then scroll to it on demand from anywhere in the app (e.g. a deep-link handler) via Scrollable.ensureVisible. String-keyed, in-memory, no generation-time variables.

Version: 1.0.0

Variables

This brick has no generation-time variables.

Usage

Interactive

archipelago generate autoscroll_sdk

Non-interactive (CI)

archipelago generate autoscroll_sdk --config my_config.json

Generated Structure

features/
└── autoscroll_sdk/
    ├── autoscroll_sdk_api/
    │   └── lib/src/
    │       └── autoscroll_sdk.dart
    └── autoscroll_sdk_impl/
        └── lib/src/
            ├── autoscroll_sdk_impl.dart
            └── di/

DI Wiring

The post-gen hook automatically:

1. Adds both packages to the workspace pubspec.yaml.
2. Adds autoscroll_sdk_impl to apps/template_app/pubspec.yaml.
3. Injects AutoscrollSdkImplPackageModule into apps/template_app/lib/di/injector.dart.
4. Runs dart format on touched files.
5. Records autoscroll_sdk in archipelago.yaml.

Integration

final autoscroll = getIt<AutoscrollSdk>();

// In the screen that owns the target widget, during build:
ListTile(
  key: autoscroll.getOrCreateKey('transaction-42'),
  title: const Text('Transaction #42'),
);

// Later, from anywhere else (e.g. a deep-link handler), once the screen
// above is expected to already be built:
await autoscroll.scrollTo('transaction-42');

API

abstract interface class AutoscrollSdk implements FeatureSDK {
  GlobalKey getOrCreateKey(String id);
  GlobalKey? keyFor(String id);
  void release(String id);
  void reset();
  Future<bool> scrollTo(
    String id, {
    Duration duration = const Duration(milliseconds: 300),
    Curve curve = Curves.easeInOut,
    double alignment = 0.5,
    ScrollPositionAlignmentPolicy alignmentPolicy =
        ScrollPositionAlignmentPolicy.explicit,
  });
}

Method	Purpose
getOrCreateKey(id)	Call once per build on the widget you want scrollable-to: key: autoscroll.getOrCreateKey(id). Returns the same key instance on repeated calls.
keyFor(id)	Returns the registered key, or null if id was never registered.
release(id)	Removes the registration for id. A later getOrCreateKey call creates a fresh key.
reset()	Clears every registration — useful for tests or a full state reset (e.g. sign-out).
scrollTo(id, ...)	Resolves id's widget through its key and asks the nearest Scrollable to bring it into view.

No-op by Design

scrollTo never throws. If id was never registered, or its widget is not currently mounted, it returns false and does nothing further. This SDK is a best-effort UX nicety — a stale or malformed deep link should never crash the app. Write your own fallback (e.g. do nothing, or navigate to a default location) when scrollTo returns false.

Not a Virtualized-List Scroller

scrollTo requires the target widget to already be built — on screen, within a lazy list's cache extent, or inside a non-lazy scrollable such as a Column wrapped in a SingleChildScrollView. There is deliberately no height-preservation cache for scrolling to items far outside a virtualized list's currently-built range (unlike some in-house implementations of this idea). Keep registered ids to content that is realistically already laid out — sections of a single screen are the primary use case, not arbitrary rows deep in a 10,000-item ListView.builder.

If you need guaranteed reachability into a long virtualized list, consider a dedicated package such as scrollable_positioned_list instead.

Platform Setup

None. This SDK wraps no plugin and requires no Info.plist or AndroidManifest.xml changes.