[dynamic_layouts] Add base classes for building dynamic grids (flutte…

…r#2488)

packages/dynamic_layouts/.gitignore

@@ -0,0 +1,30 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.packages
+build/

packages/dynamic_layouts/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: fe0beec6d44c689837a46cd4962a998d77e332ff
+  channel: master
+
+project_type: package

packages/dynamic_layouts/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+* Initial release

packages/dynamic_layouts/LICENSE

@@ -0,0 +1,25 @@
+Copyright 2013 The Flutter Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/dynamic_layouts/README.md

@@ -0,0 +1,37 @@
+<!--
+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: Put a short description of the package here that helps potential users
+know whether this package might be useful for them.
+
+## Features
+
+TODO: List what your package can do. Maybe include images, gifs, or videos.
+
+## Getting started
+
+TODO: List prerequisites and provide or point to information on how to
+start using the package.
+
+## Usage
+
+TODO: Include short and useful examples for package users. Add longer examples
+to `/example` folder.
+
+## Additional information
+
+TODO: 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.

packages/dynamic_layouts/lib/dynamic_layouts.dart

@@ -0,0 +1,7 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+export 'src/base_grid_layout.dart';
+export 'src/dynamic_grid.dart';
+export 'src/render_dynamic_grid.dart';

packages/dynamic_layouts/lib/src/base_grid_layout.dart

@@ -0,0 +1,103 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/rendering.dart';
+
+/// Describes the placement of a child in a [RenderDynamicSliverGrid].
+class DynamicSliverGridGeometry extends SliverGridGeometry {
+  /// Creates an object that describes the placement of a child in a
+  /// [RenderDynamicSliverGrid].
+  const DynamicSliverGridGeometry({
+    required super.scrollOffset,
+    required super.crossAxisOffset,
+    required super.mainAxisExtent,
+    required super.crossAxisExtent,
+  });
+
+  /// Returns [BoxConstraints] that will be tight if the
+  /// [DynamicSliverGridLayout] has provided fixed extents, forcing the child to
+  /// have the required size.
+  ///
+  /// If the [mainAxisExtent] is [double.infinity] the child will be allowed to
+  /// choose its own size in the main axis. Similarly, an infinite
+  /// [crossAxisExtent] will result in the child sizing itself in the cross
+  /// axis. Otherwise, the provided cross axis size or the
+  /// [SliverConstraints.crossAxisExtent] will be used to create tight
+  /// constraints in the cross axis.
+  ///
+  /// This differs from [SliverGridGeometry.getBoxConstraints] in that it allows
+  /// loose constraints, allowing the child to be its preferred size, or within
+  /// a range of minimum and maximum extents.
+  @override
+  BoxConstraints getBoxConstraints(SliverConstraints constraints) {
+    final double mainMinExtent = mainAxisExtent.isFinite ? mainAxisExtent : 0;
+    final double crossMinExtent =
+        crossAxisExtent.isInfinite ? 0.0 : crossAxisExtent;
+
+    switch (constraints.axis) {
+      case Axis.horizontal:
+        return BoxConstraints(
+          minHeight: mainMinExtent,
+          maxHeight: mainAxisExtent,
+          minWidth: crossMinExtent,
+          maxWidth: crossAxisExtent,
+        );
+      case Axis.vertical:
+        return BoxConstraints(
+          minHeight: crossMinExtent,
+          maxHeight: crossAxisExtent,
+          minWidth: mainMinExtent,
+          maxWidth: mainAxisExtent,
+        );
+    }
+  }
+}
+
+// TODO(all): A bit more docs here
+/// Manages the size and position of all the tiles in a [RenderSliverGrid].
+///
+/// Rather than providing a grid with a [SliverGridLayout] directly, you instead
+/// provide the grid with a [SliverGridDelegate], which can compute a
+/// [SliverGridLayout] given the current [SliverConstraints].
+abstract class DynamicSliverGridLayout extends SliverGridLayout {
+  /// The  estimated size and position of the child with the given index.
+  ///
+  /// The [DynamicSliverGridGeometry] that is returned will
+  /// provide looser constraints to the child, whose size after layout can be
+  /// reported back to the layout object in [updateGeometryForChildIndex].
+  @override
+  SliverGridGeometry getGeometryForChildIndex(int index);
+
+  /// Update the size and position of the child with the given index,
+  /// considering the size of the child after layout.
+  ///
+  /// This is used to update the layout object after the child has laid out,
+  /// allowing the layout pattern to adapt to the child's size.
+  SliverGridGeometry updateGeometryForChildIndex(int index, Size childSize);
+
+  /// Called by [RenderDynamicSliverGrid] to validate the layout pattern has
+  /// filled the screen.
+  ///
+  /// A given child may have reached the target scroll offset of the current
+  /// layout pass, but there may still be more children to lay out based on the
+  /// pattern.
+  bool reachedTargetScrollOffset(double targetOffset);
+
+  // These methods are not relevant to dynamic grid building, but extending the
+  // base [SliverGridLayout] class allows us to re-use existing
+  // [SliverGridDelegate]s like [SliverGridDelegateWithFixedCrossAxisCount] and
+  // [SliverGridDelegateWithMaxCrossAxisExtent].
+  @override
+  @mustCallSuper
+  double computeMaxScrollOffset(int childCount) => throw UnimplementedError();
+  @override
+  @mustCallSuper
+  int getMaxChildIndexForScrollOffset(double scrollOffset) =>
+      throw UnimplementedError();
+  @override
+  @mustCallSuper
+  int getMinChildIndexForScrollOffset(double scrollOffset) =>
+      throw UnimplementedError();
+}

packages/dynamic_layouts/lib/src/dynamic_grid.dart

@@ -0,0 +1,77 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/widgets.dart';
+
+import 'render_dynamic_grid.dart';
+
+/// A scrollable, 2D array of widgets.
+///
+// TODO(all): Add more documentation & sample code
+class DynamicGridView extends GridView {
+  /// Creates a scrollable, 2D array of widgets with a custom
+  /// [SliverGridDelegate].
+  ///
+  // TODO(all): what other parameters should we add to these
+  // constructors, here, builder, etc.?
+  // + reverse
+  // + scrollDirection
+  DynamicGridView({
+    super.key,
+    required super.gridDelegate,
+    // This creates a SliverChildListDelegate in the super class.
+    super.children = const <Widget>[],
+  });
+
+  /// Creates a scrollable, 2D array of widgets that are created on demand.
+  DynamicGridView.builder({
+    super.key,
+    required super.gridDelegate,
+    // This creates a SliverChildBuilderDelegate in the super class.
+    required IndexedWidgetBuilder itemBuilder,
+    super.itemCount,
+  }) : super.builder(itemBuilder: itemBuilder);
+
+  // TODO(snat-s): DynamicGridView.wrap?
+
+  // TODO(DavBot09): DynamicGridView.stagger?
+
+  @override
+  Widget buildChildLayout(BuildContext context) {
+    return DynamicSliverGrid(
+      delegate: childrenDelegate,
+      gridDelegate: gridDelegate,
+    );
+  }
+}
+
+/// A sliver that places multiple box children in a two dimensional arrangement.
+class DynamicSliverGrid extends SliverMultiBoxAdaptorWidget {
+  /// Creates a sliver that places multiple box children in a two dimensional
+  /// arrangement.
+  const DynamicSliverGrid({
+    super.key,
+    required super.delegate,
+    required this.gridDelegate,
+  });
+
+  /// The delegate that manages the size and position of the children.
+  final SliverGridDelegate gridDelegate;
+
+  @override
+  RenderDynamicSliverGrid createRenderObject(BuildContext context) {
+    final SliverMultiBoxAdaptorElement element =
+        context as SliverMultiBoxAdaptorElement;
+    return RenderDynamicSliverGrid(
+        childManager: element, gridDelegate: gridDelegate);
+  }
+
+  @override
+  void updateRenderObject(
+    BuildContext context,
+    RenderDynamicSliverGrid renderObject,
+  ) {
+    renderObject.gridDelegate = gridDelegate;
+  }
+}