docs(ui_storage): add Firebase UI Storage docs

packages/firebase_ui_storage/README.md

@@ -4,171 +4,27 @@
 
 Firebase UI Storage is a set of Flutter widgets and utilities designed to help you build and integrate your user interface with Firebase Storage.
 
-## Installation
+## Documentation
 
-Install dependencies
+- [Getting started](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/getting-started.md)
+- Widgets
 
-```sh
-flutter pub add firebase_core firebase_storage firebase_ui_storage
-```
+  - [`UploadButton`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/upload-button.md)
+  - [`TaskProgressIndicator`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/task-progress-indicator.md)
+  - [`StorageImage`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/storage-image.md)
+  - [`StorageListView`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/list-view.md)
+  - [`StorageGridView`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/grid-view.md)
 
-Download Firebase project config
+- [`PaginatedLoadingController`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/paginated-loading-controller.md)
 
-```sh
-flutterfire configure
-```
+## Issues
 
-## Configuration
+Please file Firebase UI Storage specific issues, bugs, or feature requests in our [issue tracker].
 
-This section will walk you through the configuration process of the Firebase UI Storage
+## Contributing
 
-### macOS
+If you wish to contribute a change to any of the existing plugins in this repo, please review our [contribution guide] and open a [pull request].
 
-If you're building for macOS, you will need to add an entitlement for either read-only access if you only upload files:
-
-```xml
-  <key>com.apple.security.files.user-selected.read-only</key>
-  <true/>
-```
-
-or read/write access if you want to be able to download files as well:
-
-```xml
-  <key>com.apple.security.files.user-selected.read-write</key>
-  <true/>
-```
-
-Make sure to add network client entitlement as well:
-
-```xml
-<key>com.apple.security.network.client</key>
-<true/>
-```
-
-### FirebaseUIStorage.configure()
-
-To reduce boilerplate for widgets, `FirebaseUIStroage` has a top-level configuration:
-
-```dart
-import 'package:firebase_core/firebase_core.dart';
-import 'package:firebase_storage/firebase_storage.dart';
-import 'package:firebase_ui_storage/firebase_ui_storage.dart';
-import 'package:flutter/material.dart';
-
-import 'firebase_options.dart';
-
-Future<void> main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-
-  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
-
-  final storage = FirebaseStorage.instance;
-  final config = FirebaseUIStorageConfiguration(storage: storage);
-
-  await FirebaseUIStorage.configure(config);
-
-  runApp(const MyApp());
-}
-```
-
-See [API docs](https://pub.dev/documentation/firebase_ui_storage/latest/firebase_ui_storage/FirebaseUIStorageConfiguration-class.html) for more configuration options.
-
-### Overriding configuration
-
-It is possible to override a top-level configuration for a widget subtree:
-
-```dart
-class MyWidget extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    return FirebaseUIStorageConfigOverride(
-      config: FirebaseUIStorageConfiguration(
-        uploadRoot: storage.ref('${FirebaseAuth.instance.currentUser.uid}/'),
-        namingPolicy: const UuidFileUploadNamingPolicy(),
-        child: const MyUserPage(),
-      ),
-    );
-  }
-}
-```
-
-## Widgets
-
-### UploadButton
-
-```dart
-class MyUploadPage extends StatelessWidget {
-  const MyUploadPage({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      body: Center(
-        child: UploadButton(
-          mimeTypes: const ['image/png', 'image/jpeg'],
-          onError: (err, stackTrace) {
-            print(err.toString());
-          },
-          onUploadComplete: (ref) {
-            print('File uploaded to ${ref.fullPath}');
-          },
-        ),
-      ),
-    );
-  }
-}
-
-```
-
-### TaskProgressIndicator
-
-```dart
-class MyUploadProgress extends StatelessWidget {
-  final UploadTask task;
-
-  const MyUploadProgress({super.key, required this.task});
-
-  @override
-  Widget build(BuildContext context) {
-    return Card(
-      child: Column(children: [
-        Text('Uploading ${task.snapshot.ref.name}...'),
-        TaskProgressIndicator(task: task),
-      ]),
-    );
-  }
-}
-```
-
-### StorageListView
-
-```dart
-StorageListView(
-  ref: storage.ref('images'),
-  itemBuilder: (context, ref) {
-    return AspectRatio(
-      aspectRatio: 1,
-      child: StorageImage(ref: ref),
-    );
-  },
-  loadingBuilder: (context) {
-    return const Center(
-      child: CircularProgressIndicator(),
-    );
-  },
-  errorBuilder: (context, error, controller) {
-    return Center(
-      child: Column(
-        mainAxisSize: MainAxisSize.min,
-        children: [
-          Text('Error: $error'),
-          TextButton(
-            onPressed: () => controller.load(),
-            child: const Text('Retry'),
-          ),
-        ],
-      ),
-    );
-  },
-);
-```
+[issue tracker]: https://github.com/firebase/FirebaseUI-Flutter/issues/new/choose
+[contribution guide]: https://github.com/firebase/FirebaseUI-Flutter/blob/main/docs/contributing.md
+[pull request]: https://github.com/firebase/FirebaseUI-Flutter/pulls

packages/firebase_ui_storage/doc/getting-started.md

@@ -0,0 +1,134 @@
+# Getting started with Firebase UI Storage
+
+Firebase UI Storage is a set of Flutter widgets and utilities designed to help you build and integrate your user interface with Firebase Storage.
+
+## Installation
+
+Install dependencies
+
+```sh
+flutter pub add firebase_core firebase_storage firebase_ui_storage
+```
+
+Install the FlutterFire CLI by running the following command from any directory:
+
+```sh
+flutter pub global activate flutterfire_cli
+```
+
+Use the FlutterFire CLI to configure your Flutter apps to connect to Firebase.
+
+From your Flutter project directory, run the following command to start the app configuration workflow:
+
+```sh
+flutterfire configure
+```
+
+## Configuration
+
+This section will walk you through the configuration process for Firebase UI Storage
+
+### macOS
+
+If you're building for macOS, you will need to add an entitlement. 
+
+For read-only access if you only upload files:
+
+```xml
+  <key>com.apple.security.files.user-selected.read-only</key>
+  <true/>
+```
+
+For read/write access if you want to be able to download files as well:
+
+```xml
+  <key>com.apple.security.files.user-selected.read-write</key>
+  <true/>
+```
+
+Make sure to add network client entitlement as well:
+
+```xml
+<key>com.apple.security.network.client</key>
+<true/>
+```
+
+### Initialize Firebase
+
+```dart
+import 'package:firebase_core/firebase_core.dart';
+import 'firebase_options.dart';
+
+Future<void> main() async {
+    WidgetsFlutterBinding.ensureInitialized();
+
+    await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
+}
+```
+
+### Configure Firebase UI Storage
+
+`FirebaseUIStorage` has a top-level configuration, that reduces amount of widget properties needed
+to be passed to the widget constructors.
+
+```dart
+import 'package:firebase_storage/firebase_storage.dart';
+
+Future<void> main() async {
+  // configuration steps from above
+
+  final storage = FirebaseStorage.instance;
+
+  final config = FirebaseUIStorageConfiguration(
+    storage: storage,
+    uploadRoot: storage.ref('flutter-tests'),
+    namingPolicy: UuidFileUploadNamingPolicy(), // optional, will generate a UUID for each uploaded file
+  );
+
+  await FirebaseUIStorage.configure(config);
+}
+```
+
+Available file naming policies:
+
+- [`KeepOriginalNameUploadPolicy`] – keeps the original file name (default)
+- [`KeepPathUploadPolicy`] - keeps the original file path
+- [`UuidFileUploadNamingPolicy`] – generates a UUID for each uploaded file
+
+[`KeepOriginalNameUploadPolicy`]: https://pub.dev/documentation/firebase_ui_storage/latest/firebase_ui_storage/KeepOriginalNameUploadPolicy-class.html
+[`KeepPathUploadPolicy`]: https://pub.dev/documentation/firebase_ui_storage/latest/firebase_ui_storage/KeepPathUploadPolicy-class.html
+[`UuidFileUploadNamingPolicy`]: https://pub.dev/documentation/firebase_ui_storage/latest/firebase_ui_storage/UuidFileUploadNamingPolicy-class.html
+
+If you ever need to override this top-level configuration, you can do so by using `FirebaseUIStorageConfigOverride`:
+
+```dart
+import 'package:firebase_storage/firebase_storage.dart';
+import 'package:firebase_ui_storage/firebase_ui_storage.dart';
+
+class MyWidget extends StatelessWidget {
+  const MyWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return FirebaseUIStorageConfigOverride(
+      config: FirebaseUIStorageConfiguration(
+        uploadRoot: FirebaseStorage.instance.ref('other-location'),
+      ),
+      child: const OtherWidget(),
+    );
+  }
+}
+```
+
+### Firebase UI Storage widgets
+
+- [`UploadButton`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/upload-button.md)
+- [`TaskProgressIndicator`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/task-progress-indicator.md)
+- [`StorageImage`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/storage-image.md)
+- [`StorageListView`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/list-view.md)
+- [`StorageGridView`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/grid-view.md)
+- [`PaginatedLoadingController`](https://github.com/firebase/FirebaseUI-Flutter/tree/main/packages/firebase_ui_storage/doc/paginated-loading-controller.md)
+
+---
+
+> See [API reference](https://pub.dev/documentation/firebase_ui_storage/latest/firebase_ui_storage/firebase_ui_storage-library.html) for more details.