[dynamic_layouts] Add Staggered Layout (#2520)

* Added SliverGridStaggeredTileLayout and staggered constructor for DynamicGridView * Added documentation, tests and bug fixes for DynamicSliverGridGeometry and others * Added simple demo and fixed formating * Added copyright * Fixed formatting * Added const constructor to DynamicSliverGridDelegateWithFixedCrossAxisCount * Updated tests with new sizes * Updated readme * Fixed formatting and documentation * Modified types and functionality for main axis counts and extents * Updated readme * Added test * Fixed TODO * Fixed readme * Added example (needed for code excerpts) * Added build_runner * Test excerpts * Changed sdk version for example * Changed sdk version again * Removed example * Removed assets * Final rebase * Formatting * Formatting * Fixed test Co-authored-by: Luis López <davidlopezm@google.com>
flutter · Aug 31, 2022 · 3a48ebc · 3a48ebc
1 parent cf3f676
commit 3a48ebc
Show file tree

Hide file tree

Showing 6 changed files with 821 additions and 24 deletions.
diff --git a/packages/dynamic_layouts/README.md b/packages/dynamic_layouts/README.md
@@ -1,20 +1,4 @@
-<!--
-TODO(DavBot02 & snat-s):
-
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
-
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
-
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages).
--->
-
-<!-- TODO(DavBot02): Put a short description of the package here that helps potential users
-know whether this package might be useful for them.-->
+A package that provides two dynamic grid layouts: wrap and staggered.
 
 ## Features
 This package provides support for multi sized tiles and different layouts.
@@ -54,11 +38,22 @@ This layout can be used with `DynamicGridView.wrap` and with
 
 ## Getting started
 
-<!-- TODO(DavBot02): List prerequisites and provide or point to information on how to start using the package. -->
+### Depend on it
 
+Run this command with Flutter:
+```sh
+$ flutter pub add dynamic_layouts
+```
+### Import it
+
+Now in your Dart code, you can use:
+
+```sh
+import 'package:dynamic_layouts/dynamic_layouts.dart';
+```
 ## Usage
 
-Use `DynamicGridView`s to access this layouts.
+Use `DynamicGridView`s to access these layouts.
 `DynamicGridView` has some constructors that use  `SliverChildListDelegate` like
 `.wrap` and `.stagger`. For a more efficient option that uses `SliverChildBuilderDelegate` use
 `.builder`, it works the same as `GridView.builder`.
@@ -88,6 +83,10 @@ like `SliverGridDelegateWithMaxCrossAxisExtent` and
 
 ## Additional information
 
-<!-- TODO(DavBot02): Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more. -->
+The staggered layout is similar to Android's [StaggeredGridLayoutManager](https://developer.android.com/reference/androidx/recyclerview/widget/StaggeredGridLayoutManager), while the wrap layout
+emulates iOS' [UICollectionView](https://developer.apple.com/documentation/uikit/uicollectionview).
+
+The inner functionality of this package is exposed, meaning that other dynamic layouts
+can be created on top of it and added to the collection. If you want to contribute to
+this package, you can open a pull request in [Flutter Packages](https://github.com/flutter/packages)
+and add the tag "p: dynamic_layouts".
diff --git a/packages/dynamic_layouts/lib/dynamic_layouts.dart b/packages/dynamic_layouts/lib/dynamic_layouts.dart
@@ -5,4 +5,5 @@
 export 'src/base_grid_layout.dart';
 export 'src/dynamic_grid.dart';
 export 'src/render_dynamic_grid.dart';
+export 'src/staggered_layout.dart';
 export 'src/wrap_layout.dart';
diff --git a/packages/dynamic_layouts/lib/src/dynamic_grid.dart b/packages/dynamic_layouts/lib/src/dynamic_grid.dart
@@ -5,6 +5,7 @@
 import 'package:flutter/widgets.dart';
 
 import 'render_dynamic_grid.dart';
+import 'staggered_layout.dart';
 import 'wrap_layout.dart';
 
 /// A scrollable, 2D array of widgets.
@@ -97,7 +98,58 @@ class DynamicGridView extends GridView {
           ),
         );
 
-  // TODO(DavBot09): DynamicGridView.stagger?
+  /// Creates a scrollable, 2D array of widgets where each tile's main axis
+  /// extent will be determined by the child's corresponding finite size and
+  /// the cross axis extent will be fixed, generating a staggered layout.
+  ///
+  /// Either a [crossAxisCount] or a [maxCrossAxisExtent] must be provided.
+  /// The constructor will then use a
+  /// [DynamicSliverGridDelegateWithFixedCrossAxisCount] or a
+  /// [DynamicSliverGridDelegateWithMaxCrossAxisExtent] as its [gridDelegate],
+  /// respectively.
+  ///
+  /// This sample code shows how to use the constructor with a
+  /// [maxCrossAxisExtent] and a simple layout:
+  ///
+  /// ```dart
+  /// DynamicGridView.staggered(
+  ///   maxCrossAxisExtent: 100,
+  ///   crossAxisSpacing: 2,
+  ///   mainAxisSpacing: 2,
+  ///   children: List.generate(
+  ///     50,
+  ///     (int index) => Container(
+  ///       height: index % 3 * 50 + 20,
+  ///       color: Colors.amber[index % 9 * 100],
+  ///       child: Center(child: Text("Index $index")),
+  ///     ),
+  ///   ),
+  /// );
+  /// ```
+  DynamicGridView.staggered({
+    super.key,
+    super.scrollDirection,
+    super.reverse,
+    int? crossAxisCount,
+    double? maxCrossAxisExtent,
+    double mainAxisSpacing = 0.0,
+    double crossAxisSpacing = 0.0,
+    super.children = const <Widget>[],
+  })  : assert(crossAxisCount != null || maxCrossAxisExtent != null),
+        assert(crossAxisCount == null || maxCrossAxisExtent == null),
+        super(
+          gridDelegate: crossAxisCount != null
+              ? DynamicSliverGridDelegateWithFixedCrossAxisCount(
+                  crossAxisCount: crossAxisCount,
+                  mainAxisSpacing: mainAxisSpacing,
+                  crossAxisSpacing: crossAxisSpacing,
+                )
+              : DynamicSliverGridDelegateWithMaxCrossAxisExtent(
+                  maxCrossAxisExtent: maxCrossAxisExtent!,
+                  mainAxisSpacing: mainAxisSpacing,
+                  crossAxisSpacing: crossAxisSpacing,
+                ),
+        );
 
   @override
   Widget buildChildLayout(BuildContext context) {