chore: move docs to repo root

.github/PULL_REQUEST_TEMPLATE.md

@@ -30,7 +30,7 @@ Does your PR require plugin users to manually update their apps to accommodate y
 
 <!-- Links -->
 [issue database]: https://github.com/firebase/FirebaseUI-Flutter/issues
-[Contributor Guide]: https://github.com/firebase/FirebaseUI-Flutter/blob/main/docs/contributing.md
+[Contributor Guide]: https://github.com/firebase/FirebaseUI-Flutter/blob/main/CONTRIBUTING.md
 [Flutter Style Guide]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
 [pub versioning philosophy]: https://dart.dev/tools/pub/versioning
 [CLA]: https://cla.developers.google.com/

docs/contributing.md → CONTRIBUTING.md

@@ -181,7 +181,7 @@ Some things to keep in mind before publishing the release:
   from people that immediately adopt it, and uncovering and resolving those
   support issues will take more time if you're unavailable.
 
-### Run a release...
+### Run a release
 
 1. Switch to `main` branch locally.
 2. Run `git pull origin main`.

docs/README.md

@@ -0,0 +1,14 @@
+# Firebase UI Docs
+
+- Firebase UI Auth
+  - Auth providers
+    - [Email](./firebase-ui-auth/providers/email.md)
+    - [Email link](./firebase-ui-auth/providers/email-link.md)
+    - [Universal Email Sign In](./firebase-ui-auth/providers/universal-email-sign-in.md)
+    - [Phone](./firebase-ui-auth/providers/phone.md)
+    - [OAuth](./firebase-ui-auth/providers/oauth.md)
+  - [Email verification](./firebase-ui-auth/providers/email-verification.md)
+  - [Navigation](./firebase-ui-auth/navigation.md)
+  - [Theming](./firebase-ui-auth/theming.md)
+- [Firebase UI Localizations](./firebase_ui_localizations.md)
+- [Firebase UI Database](./firebase_ui_database.md)

packages/firebase_ui_auth/doc/README.md → docs/firebase-ui-auth/README.md

@@ -84,6 +84,6 @@ how to use the package within your Flutter app.
   - [UniversalEmailSignInProvider](./providers/universal-email-sign-in.md) - gets all connected auth providers for a given email.
   - [OAuth](./providers/oauth.md)
 
-- [Localization](../../firebase_ui_localizations/README.md)
+- [Localization](../firebase-ui-localizations.md)
 - [Theming](./theming.md)
 - [Navigation](./navigation.md)

packages/firebase_ui_auth/doc/navigation.md → docs/firebase-ui-auth/navigation.md

@@ -95,13 +95,3 @@ class MyApp extends StatelessWidget {
 ```
 
 To learn more about the available actions, check out the [FirebaseUIActions API reference](https://pub.dev/documentation/firebase_ui_auth/latest/firebase_ui_auth/FirebaseUIActions-class.html).
-
-## Other topics
-
-- [EmailAuthProvider](./providers/email.md) - allows registering and signing using email and password.
-- [EmailLinkAuthProvider](./providers/email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./providers/phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./providers/universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [OAuth](./providers/oauth.md)
-- [Localization](../../firebase_ui_localizations/README.md)
-- [Theming](./theming.md)

packages/firebase_ui_auth/doc/providers/email-link.md → docs/firebase-ui-auth/providers/email-link.md

@@ -245,14 +245,3 @@ class _CustomEmailLinkSignInState extends State<CustomEmailLinkSignIn>
   }
 }
 ```
-
-## Other topics
-
-- [EmailAuthProvider](./email.md) - allows registering and signing using email and password.
-- [Email verification](./email-verification.md)
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [OAuth](./oauth.md)
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/providers/email-verification.md → docs/firebase-ui-auth/providers/email-verification.md

@@ -100,14 +100,3 @@ class _MyEmailVerificationScreenState extends State<MyEmailVerificationScreen> {
   }
 }
 ```
-
-## Other topics
-
-- [EmailAuthProvider](./email.md) - allows registering and signing using email and password.
-- [EmailLinkAuthProvider](./email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [OAuth](./oauth.md)
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/providers/email.md → docs/firebase-ui-auth/providers/email.md

@@ -225,14 +225,3 @@ class _CustomEmailSignInState extends State<CustomEmailSignIn>
   }
 }
 ```
-
-## Other topics
-
-- [Email verification](./email-verification.md)
-- [EmailLinkAuthProvider](./email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [OAuth](./oauth.md)
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/providers/oauth.md → docs/firebase-ui-auth/providers/oauth.md

@@ -179,14 +179,3 @@ class MyCustomScreen extends StatelessWidget {
   }
 }
 ```
-
-## Other topics
-
-- [EmaiAuthProvider](./email.md) - allows registering and signing using email and password.
-- [Email verification](./email-verification.md)
-- [EmailLinkAuthProvider](./email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/providers/phone.md → docs/firebase-ui-auth/providers/phone.md

@@ -312,14 +312,3 @@ class _CustomPhoneVerificationState extends State<CustomPhoneVerification>
   }
 }
 ```
-
-## Other topics
-
-- [Email verification](./email-verification.md)
-- [EmailLinkAuthProvider](./email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [UniversalEmailSignInProvider](./universal-email-sign-in.md) - gets all connected auth providers for a given email.
-- [OAuth](./oauth.md)
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/providers/universal-email-sign-in.md → docs/firebase-ui-auth/providers/universal-email-sign-in.md

@@ -185,14 +185,3 @@ class _CustomUniversalEmailSignInState extends State<CustomUniversalEmailSignIn>
   }
 }
 ```
-
-## Other topics
-
-- [EmaiAuthProvider](./email.md) - allows registering and signing using email and password.
-- [Email verification](./email-verification.md)
-- [EmailLinkAuthProvider](./email-link.md) - allows registering and signing using a link sent to email.
-- [PhoneAuthProvider](./phone.md) - allows registering and signing using a phone number
-- [OAuth](./oauth.md)
-- [Localization](../../../firebase_ui_localizations/README.md)
-- [Theming](../theming.md)
-- [Navigation](../navigation.md)

packages/firebase_ui_auth/doc/theming.md → docs/firebase-ui-auth/theming.md

@@ -104,5 +104,5 @@ The button will now respect the updated theme data and display a styled button i
 - [UniversalEmailSignInProvider](./providers/universal-email-sign-in.md) - gets all connected auth providers for a given email.
 - [OAuth](./providers/oauth.md)
 
-- [Localization](../../firebase_ui_localizations/README.md)
+- [Localization](../firebase-ui-localizations.md)
 - [Navigation](./navigation.md)

docs/firebase-ui-database.md

@@ -0,0 +1,170 @@
+# Firebase UI for Realtime Database
+
+Firebase UI enables you to easily integrate your application UI with your Realtime database.
+
+## Installation
+
+```sh
+flutter pub add firebase_database
+flutter pub add firebase_ui_database
+```
+
+## Usage
+
+Import the Firebase UI for Realtime Database package.
+
+```dart
+import 'package:firebase_ui_database/firebase_ui_database.dart';
+```
+
+### Infinite scrolling
+
+Infinite scrolling is the concept of continuously loading more data from a database
+as the user scrolls through your application. This is useful when you have a large
+datasets, as it enables the application to render faster as well as reducing network
+overhead for data the user might never see.
+
+Firebase UI for Realtime Database provides a convenient way to implement infinite scrolling
+using the Realtime Database database with the `FirebaseDatabaseListView` widget.
+
+At a minimum, the widget accepts a Realtime Database query and an item builder. As the user scrolls
+down (or across) your list, more data will be automatically fetched from the database (whilst
+respecting query conditions such as ordering).
+
+To get started, create a query and provide an item builder. For this example, we'll display
+a list of users from the `users` collection:
+
+```dart
+final usersQuery = FirebaseDatabase.instance.ref('users').orderByChild('name');
+
+FirebaseDatabaseListView(
+  query: usersQuery,
+  itemBuilder: (context, snapshot) {
+    Map<String, dynamic> user = snapshot.value as Map<String, dynamic>;
+
+    return Text('User name is ${user['name']}');
+  },
+);
+```
+
+The `FirebaseDatabaseListView` widget is built on-top of Flutter's own [`ListView`](https://api.flutter.dev/flutter/widgets/ListView-class.html)
+widget, and accepts the same parameters which we can optionally provide. For example, to change the scroll-direction to horizontal:
+
+```dart
+FirebaseDatabaseListView(
+  scrollDirection: Axis.horizontal,
+  // ...
+);
+```
+
+### Controlling page size
+
+By default, the widget will fetch 10 items from the collection at a time. This can be changed by providing a `pageSize` parameter:
+
+```dart
+FirebaseDatabaseListView(
+  pageSize: 20,
+  // ...
+);
+```
+
+In general, it is good practice to keep this value as small as possible to reduce network overhead. If the height (or width)
+of an individual item is large, it is recommended to lower the page size.
+
+### Loading and error handling
+
+By default, the widget will display a loading indicator while data is being fetched from the database, and ignore any errors which might be thrown
+(such as permission denied). You can override this behavior by providing a `loadingBuilder` and `errorBuilder` parameters to the widget:
+
+```dart
+FirebaseDatabaseListView(
+  loadingBuilder: (context) => MyCustomLoadingIndicator(),
+  errorBuilder: (context, error, stackTrace) => MyCustomError(error, stackTrace),
+  // ...
+);
+```
+
+### Advanced configuration
+
+In many cases, the `FirebaseDatabaseListView` widget is enough to render simple lists of collection data.
+However, you may have specific requirements which require more control over the widget's behavior
+(such as using a [`GridView`](https://api.flutter.dev/flutter/widgets/GridView-class.html)).
+
+The `FirebaseDatabaseQueryBuilder` provides the building blocks for advanced configuration at the expense of
+requiring more boilerplate code. The widget does not provide any underlying list implementation, instead
+you are expected to provide this yourself.
+
+Much like the `FirebaseDatabaseListView` widget, provide a query and builder:
+
+```dart
+final usersQuery = FirebaseDatabase.instance.ref('users').orderByChild('name');
+
+FirebaseDatabaseQueryBuilder(
+  query: usersQuery,
+  builder: (context, snapshot, _) {
+    // ... TODO!
+  },
+);
+```
+
+The main difference to note here is that the `builder` property returns a `FirebaseQueryBuilderSnapshot`, rather
+than an individual document. The builder returns the current state of the entire query, such as whether
+data is loading, an error has occurred and the documents.
+
+This requires us to implement our own list based implementation. Firstly, let's handle the loading and error
+states:
+
+```dart
+FirebaseDatabaseQueryBuilder(
+  query: usersQuery,
+  builder: (context, snapshot, _) {
+    if (snapshot.isFetching) {
+      return const CircularProgressIndicator();
+    }
+
+    if (snapshot.hasError) {
+      return Text('Something went wrong! ${snapshot.error}');
+    }
+
+    // ...
+  },
+);
+```
+
+Next, we now need to return a list-view based implementation for our application to display the data. For example,
+to display a grid of users, we can use the [`GridView`](https://api.flutter.dev/flutter/widgets/GridView-class.html) widget:
+
+```dart
+FirebaseDatabaseQueryBuilder(
+  query: usersQuery,
+  builder: (context, snapshot, _) {
+    // ...
+
+    return GridView.builder(
+      itemCount: snapshot.docs.length,
+      itemBuilder: (context, index) {
+        // if we reached the end of the currently obtained items, we try to
+        // obtain more items
+        if (snapshot.hasMore && index + 1 == snapshot.docs.length) {
+          // Tell FirebaseDatabaseQueryBuilder to try to obtain more items.
+          // It is safe to call this function from within the build method.
+          snapshot.fetchMore();
+        }
+
+        final user = snapshot.docs[index].value as Map<String, dynamic>;
+
+        return Container(
+          padding: const EdgeInsets.all(8),
+          color: Colors.teal[100],
+          child: const Text("User name is ${user['name']}"),
+        );
+      },
+    );
+  },
+);
+```
+
+With more power comes more responsibility:
+
+1. Within the `itemBuilder` of our `GridView`, we have to manually ensure that we call the `fetchMore()` method on the snapshot when more data is required.
+1. The `FirebaseDatabaseQueryBuilder` does not provide a list-view based handler, instead you must provide your own implementation.