docs(storage): Add docs from firebase.google.com (#8248)

Author: kevinthecheung

docs/sidebars.js

@@ -140,7 +140,14 @@ module.exports = {
     ],
     "Cloud Storage": [
       "storage/overview",
-      "storage/usage",
+      "storage/start",
+      "storage/create-reference",
+      "storage/upload-files",
+      "storage/download-files",
+      "storage/file-metadata",
+      "storage/delete-files",
+      "storage/list-files",
+      "storage/handle-errors",
       toReferenceAPI("firebase_storage"),
       toGithubExample("firebase_storage"),
     ],

docs/storage/create-reference.mdx

@@ -0,0 +1,132 @@
+---
+title: Create a Cloud Storage reference on Flutter
+sidebar_label: Create a reference
+---
+
+Your files are stored in a
+[Cloud Storage](//cloud.google.com/storage) bucket. The
+files in this bucket are presented in a hierarchical structure, just like the
+file system on your local hard disk, or the data in the Firebase Realtime Database.
+By creating a reference to a file, your app gains access to it. These references
+can then be used to upload or download data, get or update metadata or delete
+the file. A reference can either point to a specific file or to a higher level
+node in the hierarchy.
+
+If you've used the [Firebase Realtime Database](/docs/database/overview), these paths should
+seem very familiar to you. However, your file data is stored in
+Cloud Storage, **not** in the Realtime Database.
+
+
+## Create a Reference
+
+Create a reference to upload, download, or delete a file,
+or to get or update its metadata. A reference
+can be thought of as a pointer to a file in the cloud. References are
+lightweight, so you can create as many as you need. They are also reusable for
+multiple operations.
+
+Create a reference using the `FirebaseStorage` singleton instance and
+calling its `ref()` method.
+
+```dart
+final storageRef = FirebaseStorage.instance.ref();
+```
+
+Next, you can create a reference to a location lower in the tree,
+say `"images/space.jpg"` by using the `child()` method on an existing reference.
+
+```dart
+// Create a child reference
+// imagesRef now points to "images"
+final imagesRef = storageRef.child("images");
+
+// Child references can also take paths
+// spaceRef now points to "images/space.jpg
+// imagesRef still points to "images"
+final spaceRef = storageRef.child("images/space.jpg");
+```
+
+## Navigate with References
+
+You can also use the `parent` and `root` properties to navigate up in our
+file hierarchy. `parent` navigates up one level,
+while `root` navigates all the way to the top.
+
+```dart
+// parent allows us to move our reference to a parent node
+// imagesRef2 now points to 'images'
+final imagesRef2 = spaceRef.parent;
+
+// root allows us to move all the way back to the top of our bucket
+// rootRef now points to the root
+final rootRef = spaceRef.root;
+```
+
+`child()`, `parent`, and `root` can be chained together multiple
+times, as each is a reference. But accessing `root.parent` results in `null`.
+
+```dart
+// References can be chained together multiple times
+// earthRef points to 'images/earth.jpg'
+final earthRef = spaceRef.parent?.child("earth.jpg");
+
+// nullRef is null, since the parent of root is null
+final nullRef = spaceRef.root.parent;
+```
+
+
+## Reference Properties
+
+You can inspect references to better understand the files they point to
+using the `fullPath`, `name`, and `bucket` properties. These properties
+get the file's full path, name and bucket.
+
+```dart
+// Reference's path is: "images/space.jpg"
+// This is analogous to a file path on disk
+spaceRef.fullPath;
+
+// Reference's name is the last segment of the full path: "space.jpg"
+// This is analogous to the file name
+spaceRef.name;
+
+// Reference's bucket is the name of the storage bucket that the files are stored in
+spaceRef.bucket;
+```
+
+## Limitations on References
+
+Reference paths and names can contain any sequence of valid Unicode characters,
+but certain restrictions are imposed including:
+
+1. Total length of reference.fullPath must be between 1 and 1024 bytes when UTF-8 encoded.
+1. No Carriage Return or Line Feed characters.
+1. Avoid using `#`, `[`, `]`, `*`, or `?`, as these do not work well with
+   other tools such as the [Firebase Realtime Database](/docs/database/overview)
+   or [gsutil](https://cloud.google.com/storage/docs/gsutil).
+
+## Full Example
+
+```dart
+// Points to the root reference
+final storageRef = FirebaseStorage.instance.ref();
+
+// Points to "images"
+Reference? imagesRef = storageRef.child("images");
+
+// Points to "images/space.jpg"
+// Note that you can use variables to create child values
+final fileName = "space.jpg";
+final spaceRef = imagesRef.child(fileName);
+
+// File path is "images/space.jpg"
+final path = spaceRef.fullPath;
+
+// File name is "space.jpg"
+final name = spaceRef.name;
+
+// Points to "images"
+imagesRef = spaceRef.parent;
+```
+
+Next, let's learn how to [upload files](upload-files) to Cloud Storage.

docs/storage/delete-files.mdx

@@ -0,0 +1,44 @@
+---
+title: Delete files with Cloud Storage on Flutter
+sidebar_label: Delete files
+---
+
+After uploading files to Cloud Storage, you can also delete them.
+
+:::note
+By default, a Cloud Storage bucket requires Firebase Authentication to
+perform any action on the bucket's data or files. You can
+[change your Firebase Security Rules for Cloud Storage](https://firebase.google.com/docs/storage/security/rules-conditions#public)
+to allow unauthenticated access. Since Firebase and your project's default
+App Engine app share this bucket, configuring public access may make newly
+uploaded App Engine files publicly accessible, as well. Be sure to restrict
+access to your Cloud Storage bucket again when you set up Authentication.
+:::
+
+
+## Delete a File
+
+To delete a file, first [create a reference](create-reference)
+to that file. Then call the `delete()` method on that reference.
+
+```dart
+// Create a reference to the file to delete
+final desertRef = storageRef.child("images/desert.jpg");
+
+// Delete the file
+await desertRef.delete();
+```
+
+:::note
+Deleting a file is a permanent action! If you care about restoring
+deleted files, make sure to back up your files, or
+[enable Object Versioning](https://cloud.google.com/storage/docs/using-object-versioning#set)
+on your Cloud Storage bucket.
+:::
+
+## Handle Errors
+
+There are a number of reasons why errors may occur on file deletes,
+including the file not existing, or the user not having permission
+to delete the desired file. More information on errors can be found in the
+[Handle Errors](handle-errors) section of the docs.

docs/storage/download-files.mdx

@@ -0,0 +1,163 @@
+---
+title: Download files with Cloud Storage on Flutter
+sidebar_label: Download files
+---
+
+Cloud Storage for Firebase allows you to quickly and easily download
+files from a [Cloud Storage](//cloud.google.com/storage)
+bucket provided and managed by Firebase.
+
+:::note
+By default, a Cloud Storage bucket requires Firebase Authentication to
+perform any action on the bucket's data or files. You can
+[change your Firebase Security Rules for Cloud Storage](https://firebase.google.com/docs/storage/security/rules-conditions#public)
+to allow unauthenticated access. Since Firebase and your project's default
+App Engine app share this bucket, configuring public access may make newly
+uploaded App Engine files publicly accessible, as well. Be sure to restrict
+access to your Cloud Storage bucket again when you set up Authentication.
+:::
+
+
+## Create a Reference
+
+To download a file, first [create a Cloud Storage reference](create-reference)
+to the file you want to download.
+
+You can create a reference by appending child paths to the root of your
+Cloud Storage bucket, or you can create a reference from an existing
+`gs://` or `https://` URL referencing an object in Cloud Storage.
+
+```dart
+// Create a storage reference from our app
+final storageRef = FirebaseStorage.instance.ref();
+
+// Create a reference with an initial file path and name
+final pathReference = storageRef.child("images/stars.jpg");
+
+// Create a reference to a file from a Google Cloud Storage URI
+final gsReference =
+    FirebaseStorage.instance.refFromURL("gs://YOUR_BUCKET/images/stars.jpg");
+
+// Create a reference from an HTTPS URL
+// Note that in the URL, characters are URL escaped!
+final httpsReference = FirebaseStorage.instance.refFromURL(
+    "https://firebasestorage.googleapis.com/b/YOUR_BUCKET/o/images%20stars.jpg");
+```
+
+
+## Download Files
+
+Once you have a reference, you can download files from Cloud Storage
+by calling the `getData()` or `getStream()`. If you prefer to download the file
+with another library, you can get a download URL with `getDownloadUrl()`.
+
+### Download in memory
+
+Download the file to a `UInt8List` with the `getData()` method. This is the
+easiest way to download a file, but it must load the entire contents of
+your file into memory. If you request a file larger than your app's available
+memory, your app will crash. To protect against memory issues, `getData()`
+takes a maximum amount of bytes to download. Set the maximum size to something
+you know your app can handle, or use another download method.
+
+```dart
+final islandRef = storageRef.child("images/island.jpg");
+
+try {
+  const oneMegabyte = 1024 * 1024;
+  final Uint8List? data = await islandRef.getData(oneMegabyte);
+  // Data for "images/island.jpg" is returned, use this as needed.
+} on FirebaseException catch (e) {
+  // Handle any errors.
+}
+```
+
+### Download to a local file
+
+The `writeToFile()` method downloads a file directly to a local device. Use this if
+your users want to have access to the file while offline or to share the file in a
+different app. `writeToFile()` returns a `DownloadTask` which you can use to manage
+your download and monitor the status of the download.
+
+```dart
+final islandRef = storageRef.child("images/island.jpg");
+
+final appDocDir = await getApplicationDocumentsDirectory();
+final filePath = "${appDocDir.absolute}/images/island.jpg";
+final file = File(filePath);
+
+final downloadTask = islandRef.writeToFile(file);
+downloadTask.snapshotEvents.listen((taskSnapshot) {
+  switch (taskSnapshot.state) {
+    case TaskState.running:
+      // TODO: Handle this case.
+      break;
+    case TaskState.paused:
+      // TODO: Handle this case.
+      break;
+    case TaskState.success:
+      // TODO: Handle this case.
+      break;
+    case TaskState.canceled:
+      // TODO: Handle this case.
+      break;
+    case TaskState.error:
+      // TODO: Handle this case.
+      break;
+  }
+});
+```
+
+## Download Data via URL
+
+If you already have download infrastructure based around URLs, or just want
+a URL to share, you can get the download URL for a file by calling the
+`getDownloadURL()` method on a Cloud Storage reference.
+
+```dart
+final imageUrl =
+    await storageRef.child("users/me/profile.png").getDownloadURL();
+```
+
+## Handle Errors
+
+There are a number of reasons why errors may occur on download, including the
+file not existing, or the user not having permission to access the desired file.
+More information on errors can be found in the [Handle Errors](handle-errors)
+section of the docs.
+
+## Full Example
+
+A full example of a download with error handling is shown below:
+
+```dart
+final islandRef = storageRef.child("images/island.jpg");
+
+final appDocDir = await getApplicationDocumentsDirectory();
+final filePath = "${appDocDir.absolute}/images/island.jpg";
+final file = File(filePath);
+
+final downloadTask = islandRef.writeToFile(file);
+downloadTask.snapshotEvents.listen((taskSnapshot) {
+  switch (taskSnapshot.state) {
+    case TaskState.running:
+      // TODO: Handle this case.
+      break;
+    case TaskState.paused:
+      // TODO: Handle this case.
+      break;
+    case TaskState.success:
+      // TODO: Handle this case.
+      break;
+    case TaskState.canceled:
+      // TODO: Handle this case.
+      break;
+    case TaskState.error:
+      // TODO: Handle this case.
+      break;
+  }
+});
+```
+
+You can also [get and update metadata](file-metadata) for files that are stored
+in Cloud Storage.