From 44d848c60d28f1b5905456bfe05137a6879108a9 Mon Sep 17 00:00:00 2001
From: metonym <ericyl.us@gmail.com>
Date: Mon, 21 Feb 2022 14:26:02 -0800
Subject: [PATCH] docs(file-uploader): improve `FileUploader` documentation
 (#1126)

- add `FileUploader` "Clear files" example
- document `validateFiles` prop for `FileUploaderDropContainer`
- add descriptions for `FileUploaderButton`, `FileUploader` examples
---
 docs/src/pages/components/FileUploader.svx    | 40 ++++++++++++++++++-
 .../FileUploaderClearFiles.svelte             | 32 +++++++++++++++
 2 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/pages/framed/FileUploader/FileUploaderClearFiles.svelte

diff --git a/docs/src/pages/components/FileUploader.svx b/docs/src/pages/components/FileUploader.svx
index cb7390a3..8f19f122 100644
--- a/docs/src/pages/components/FileUploader.svx
+++ b/docs/src/pages/components/FileUploader.svx
@@ -3,18 +3,39 @@ components: ["FileUploaderButton", "FileUploader", "FileUploaderDropContainer",
 ---
 
 <script>
-  import { FileUploaderButton, FileUploader, FileUploaderDropContainer, FileUploaderItem, FileUploaderSkeleton } from "carbon-components-svelte";
+  import { FileUploaderButton, FileUploader, FileUploaderDropContainer, FileUploaderItem, FileUploaderSkeleton, UnorderedList, ListItem } from "carbon-components-svelte";
   import Preview from "../../components/Preview.svelte";
 </script>
 
 ### File uploader (button-only)
 
+By default, the file uploader only accepts one file.
+
+Set `multiple` to `true` for multiple files to be uploaded.
+
 <FileUploaderButton labelText="Add files" />
 
 ### File uploader
 
+The `FileUploader` wraps `FileUploaderButton` and lists out uploaded files.
+
+The example below accepts multiple files with an extension of `.jpg` or `.jpeg`. It sets the status to `"complete"`; by default, the status is `"loading"`.
+
+See the [item examples below](#item-uploading) for different statuses.
+
 <FileUploader multiple labelTitle="Upload files" buttonLabel="Add files" labelDescription="Only JPEG files are accepted." accept="{['.jpg', '.jpeg']}" status="complete" />
 
+### Clear files
+
+There are two ways to clear files in `FileUploader`:
+
+<UnorderedList svx-ignore style="margin-bottom: var(--cds-spacing-08)">
+  <ListItem>programmatically using the <strong>clearFiles</strong> accessor</ListItem>
+  <ListItem>two-way binding by setting <strong>files</strong> to <strong>[]</strong></ListItem>
+</UnorderedList>
+
+<FileSource src="/framed/FileUploader/FileUploaderClearFiles" />
+
 ### File uploader (disabled state)
 
 <FileUploader disabled multiple labelTitle="Upload files" buttonLabel="Add files" labelDescription="Only JPEG files are accepted." accept="{['.jpg', '.jpeg']}" status="complete" />
@@ -41,7 +62,22 @@ The default `FileUploaderItem` size is "default".
 
 ### Drop container
 
-<FileUploaderDropContainer labelText="Drag and drop files here or click to upload" multiple />
+The `FileUploaderDropContainer` accepts files through click and drop events.
+
+Use the `validateFiles` prop to filter out files before they are set.
+
+The following example accepts files smaller than 1 kB.
+
+<FileUploaderDropContainer
+  multiple
+  labelText="Drag and drop files here or click to upload" 
+  validateFiles={files => {
+    return files.filter(file => file.size < 1_024)
+  }}
+  on:change={e=> {
+    console.log("files", e.detail)
+  }}
+/>
 
 ### Skeleton
 
diff --git a/docs/src/pages/framed/FileUploader/FileUploaderClearFiles.svelte b/docs/src/pages/framed/FileUploader/FileUploaderClearFiles.svelte
new file mode 100644
index 00000000..9b6aba34
--- /dev/null
+++ b/docs/src/pages/framed/FileUploader/FileUploaderClearFiles.svelte
@@ -0,0 +1,32 @@
+<script>
+  import { FileUploader, Button } from "carbon-components-svelte";
+
+  let fileUploader;
+  let files = [];
+</script>
+
+<FileUploader
+  bind:this="{fileUploader}"
+  multiple
+  labelTitle="Upload files"
+  buttonLabel="Add files"
+  status="complete"
+  bind:files
+/>
+
+<br />
+
+<Button
+  kind="tertiary"
+  disabled="{!files.length}"
+  on:click="{fileUploader.clearFiles}"
+>
+  Clear (programmatic)
+</Button>
+<Button
+  kind="tertiary"
+  disabled="{!files.length}"
+  on:click="{() => (files = [])}"
+>
+  Clear (two-way binding)
+</Button>