Update FileDropZone's documentation (#2899)

Co-authored-by: Josh Wooding <[email protected]>
Co-authored-by: mikearildbrown <[email protected]>

site/docs/components/file-drop-zone/examples.mdx

@@ -15,21 +15,26 @@ data:
     ### Default
 
     This component allows users to upload files they've selected from the native file browser interface or dragged-and-dropped. The component automatically uploads the files to your web application.
+
     You can customize the message in the file drop zone to suit your needs.
+    We recommend passing a header to the component to indicate the expected action, such as "Drop files here".
+    Communicate any requirements, such as maximum file size and type restrictions as validation text within the component.
 
   </LivePreview>
   <LivePreview componentName="file-drop-zone" exampleName="Error">
 
     ### Error
 
     Inform users when a file cannot be uploaded successfully. Error messages should provide feedback to guide the user resolve the issue.
+    When uploaded files fail to meet the validation criteria, change `state` prop to `"error"` so the file drop zone will display the error state.
 
   </LivePreview>
   <LivePreview componentName="file-drop-zone" exampleName="Success">
 
     ### Success
 
     Inform users when files successfully upload. Success messages should reassure users that the action has been completed.
+    When files uploaded successfully, change `state` prop to `"success"` so the file drop zone will display the success state.
 
   </LivePreview>
   <LivePreview componentName="file-drop-zone" exampleName="Disabled">

site/docs/components/file-drop-zone/usage.mdx

@@ -11,10 +11,22 @@ data:
 
 ### Using the component
 
-Make sure you communicate any limits, such as maximum file size and type restrictions, before the user uploads their file. If the upload fails, clearly explain the reason why and how to resolve it.
+#### Composition
+
+- When composing the file drop zone, consider using `FileDropZoneIcon` to inform users about the current status. You can show an upload icon when the user has not yet uploaded an item, or a status icon that communicates the current upload status.
+- We recommend passing a header to the component to indicate the expected action, such as "drop files here."
+- You can customize the `FileDropZoneTrigger`'s text by passing `children` into the component.
+- Communicate any requirements, such as maximum file size and type restrictions as validation text, before the user uploads their file. If the upload fails, clearly explain the reason why and how to resolve it.
+
+#### Validation and acceptance criteria
+
+- You can specify acceptable file types with `FileDropZoneTrigger`'s `accept` prop. The prop doesn't validate the selected files' types. Instead, it provides the acceptable types to the browser, which in turn can guide users towards selecting the correct file types.
+- Make sure that the acceptance criteria is backed up by appropriate validation. Use `FileDropZone`'s `onDrop` prop to validate the file types.
 
 Inform users when files successfully upload to reassure them that the action has completed.
 
+- To inform users of the criteria, you can display custom validation text on the file drop zone. When uploaded files fail to meet the validation criteria, change the `state` prop to `"error"` so the file drop zone displays the error state.
+
 #### When to use
 
 - To enable users to upload single or multiple files from a native file browser.

site/src/examples/file-drop-zone/Default.tsx

@@ -1,16 +1,23 @@
-import { ReactElement } from "react";
+import { ReactElement, DragEvent } from "react";
 import {
   FileDropZone,
   FileDropZoneIcon,
   FileDropZoneTrigger,
 } from "@salt-ds/lab";
 import { Text } from "@salt-ds/core";
 
+const validate = (event: DragEvent<HTMLDivElement>, files: File[]) => {
+  console.log("validate files", files);
+};
+
 export const Default = (): ReactElement => (
-  <FileDropZone style={{ width: 300 }}>
+  <FileDropZone
+    style={{ width: 300 }}
+    onDrop={(event, files) => validate(event, files)}
+  >
     <FileDropZoneIcon />
     <strong>Drop files here or</strong>
-    <FileDropZoneTrigger />
+    <FileDropZoneTrigger accept=".png" />
     <Text>Only .png files</Text>
   </FileDropZone>
 );

site/src/examples/file-drop-zone/Disabled.tsx

@@ -1,16 +1,24 @@
-import { ReactElement } from "react";
+import { DragEvent, ReactElement } from "react";
 import {
   FileDropZone,
   FileDropZoneIcon,
   FileDropZoneTrigger,
 } from "@salt-ds/lab";
 import { Text } from "@salt-ds/core";
 
+const validate = (event: DragEvent<HTMLDivElement>, files: File[]) => {
+  console.log("validate files", files);
+};
+
 export const Disabled = (): ReactElement => (
-  <FileDropZone style={{ width: 300 }} disabled>
+  <FileDropZone
+    style={{ width: 300 }}
+    onDrop={(event, files) => validate(event, files)}
+    disabled
+  >
     <FileDropZoneIcon />
     <strong>Drop files here or</strong>
-    <FileDropZoneTrigger disabled />
+    <FileDropZoneTrigger accept=".png" disabled />
     <Text disabled>Only .png files</Text>
   </FileDropZone>
 );

site/src/examples/file-drop-zone/Error.tsx

@@ -1,13 +1,21 @@
-import { ReactElement } from "react";
+import { DragEvent, ReactElement } from "react";
 import { Text } from "@salt-ds/core";
 import {
   FileDropZone,
   FileDropZoneIcon,
   FileDropZoneTrigger,
 } from "@salt-ds/lab";
 
+const validate = (event: DragEvent<HTMLDivElement>, files: File[]) => {
+  console.log("validate files", files);
+};
+
 export const Error = (): ReactElement => (
-  <FileDropZone style={{ width: 300 }} status="error">
+  <FileDropZone
+    style={{ width: 300 }}
+    onDrop={(event, files) => validate(event, files)}
+    status="error"
+  >
     <FileDropZoneIcon status="error" />
     <strong>File format is not allowed</strong>
     <FileDropZoneTrigger accept=".png" />

site/src/examples/file-drop-zone/Success.tsx

@@ -1,16 +1,24 @@
-import { ReactElement } from "react";
+import { DragEvent, ReactElement } from "react";
 import {
   FileDropZone,
   FileDropZoneIcon,
   FileDropZoneTrigger,
 } from "@salt-ds/lab";
 import { Text } from "@salt-ds/core";
 
+const validate = (event: DragEvent<HTMLDivElement>, files: File[]) => {
+  console.log("validate files", files);
+};
+
 export const Success = (): ReactElement => (
-  <FileDropZone style={{ width: 300 }} status="success">
+  <FileDropZone
+    style={{ width: 300 }}
+    onDrop={(event, files) => validate(event, files)}
+    status="success"
+  >
     <FileDropZoneIcon status="success" />
     <strong>Upload completed</strong>
-    <FileDropZoneTrigger />
+    <FileDropZoneTrigger accept=".png" />
     <Text>Only .png files</Text>
   </FileDropZone>
 );