From 43a7d69f90746aac6b1a6254e8bd63a7d4e3d1c2 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 10 Oct 2024 09:45:28 -0500
Subject: [PATCH] docs(VFileUpload): add documentation

---
 .../examples/v-file-upload/prop-content.vue   |  8 ++++
 .../examples/v-file-upload/prop-density.vue   | 19 ++++++++
 .../examples/v-file-upload/prop-disabled.vue  |  3 ++
 .../src/examples/v-file-upload/prop-scrim.vue |  3 ++
 .../src/examples/v-file-upload/slot-item.vue  | 26 ++++++++++
 .../docs/src/examples/v-file-upload/usage.vue | 10 ++--
 .../src/pages/en/components/file-upload.md    | 47 +++++++++++++++++--
 .../src/labs/VFileUpload/VFileUpload.sass     |  3 ++
 8 files changed, 112 insertions(+), 7 deletions(-)
 create mode 100644 packages/docs/src/examples/v-file-upload/prop-content.vue
 create mode 100644 packages/docs/src/examples/v-file-upload/prop-density.vue
 create mode 100644 packages/docs/src/examples/v-file-upload/prop-disabled.vue
 create mode 100644 packages/docs/src/examples/v-file-upload/prop-scrim.vue
 create mode 100644 packages/docs/src/examples/v-file-upload/slot-item.vue

diff --git a/packages/docs/src/examples/v-file-upload/prop-content.vue b/packages/docs/src/examples/v-file-upload/prop-content.vue
new file mode 100644
index 00000000000..8d9a6070318
--- /dev/null
+++ b/packages/docs/src/examples/v-file-upload/prop-content.vue
@@ -0,0 +1,8 @@
+<template>
+  <v-file-upload
+    browse-text="Local Filesystem"
+    divider-text="or choose locally"
+    icon="mdi-upload"
+    title="Drag and Drop Here"
+  ></v-file-upload>
+</template>
diff --git a/packages/docs/src/examples/v-file-upload/prop-density.vue b/packages/docs/src/examples/v-file-upload/prop-density.vue
new file mode 100644
index 00000000000..12e8556663f
--- /dev/null
+++ b/packages/docs/src/examples/v-file-upload/prop-density.vue
@@ -0,0 +1,19 @@
+<template>
+  <div class="text-center pa-2 mb-2">
+    <v-btn-toggle v-model="density" density="comfortable" border divided rounded>
+      <v-btn value="default">Default</v-btn>
+
+      <v-btn value="comfortable">Comfortable</v-btn>
+
+      <v-btn value="compact">Compact</v-btn>
+    </v-btn-toggle>
+  </div>
+
+  <v-file-upload :density="density"></v-file-upload>
+</template>
+
+<script setup>
+  import { shallowRef } from 'vue'
+
+  const density = shallowRef('default')
+</script>
diff --git a/packages/docs/src/examples/v-file-upload/prop-disabled.vue b/packages/docs/src/examples/v-file-upload/prop-disabled.vue
new file mode 100644
index 00000000000..af636f7f41d
--- /dev/null
+++ b/packages/docs/src/examples/v-file-upload/prop-disabled.vue
@@ -0,0 +1,3 @@
+<template>
+  <v-file-upload disabled></v-file-upload>
+</template>
diff --git a/packages/docs/src/examples/v-file-upload/prop-scrim.vue b/packages/docs/src/examples/v-file-upload/prop-scrim.vue
new file mode 100644
index 00000000000..56d88c513ad
--- /dev/null
+++ b/packages/docs/src/examples/v-file-upload/prop-scrim.vue
@@ -0,0 +1,3 @@
+<template>
+  <v-file-upload scrim="primary"></v-file-upload>
+</template>
diff --git a/packages/docs/src/examples/v-file-upload/slot-item.vue b/packages/docs/src/examples/v-file-upload/slot-item.vue
new file mode 100644
index 00000000000..65f4772a483
--- /dev/null
+++ b/packages/docs/src/examples/v-file-upload/slot-item.vue
@@ -0,0 +1,26 @@
+<template>
+  <v-file-upload
+    v-model="model"
+    clearable
+    multiple
+    show-size
+  >
+    <template v-slot:item="{ props: itemProps }">
+      <v-file-upload-item v-bind="itemProps" lines="one" nav>
+        <template v-slot:prepend>
+          <v-avatar size="32" rounded></v-avatar>
+        </template>
+
+        <template v-slot:clear="{ props: clearProps }">
+          <v-btn color="primary" v-bind="clearProps"></v-btn>
+        </template>
+      </v-file-upload-item>
+    </template>
+  </v-file-upload>
+</template>
+
+<script setup>
+  import { shallowRef } from 'vue'
+
+  const model = shallowRef(null)
+</script>
diff --git a/packages/docs/src/examples/v-file-upload/usage.vue b/packages/docs/src/examples/v-file-upload/usage.vue
index bcc55d496b1..417a9201e72 100644
--- a/packages/docs/src/examples/v-file-upload/usage.vue
+++ b/packages/docs/src/examples/v-file-upload/usage.vue
@@ -10,9 +10,11 @@
     </div>
 
     <template v-slot:configuration>
-      <v-checkbox v-model="clear" label="Clearable"></v-checkbox>
+      <v-text-field v-model="title" label="Title"></v-text-field>
 
       <v-checkbox v-model="disabled" label="Disabled"></v-checkbox>
+
+      <v-checkbox v-model="clear" label="Clearable"></v-checkbox>
     </template>
   </ExamplesUsageExample>
 </template>
@@ -20,16 +22,18 @@
 <script setup>
   const name = 'v-file-upload'
   const model = ref('default')
-  const options = []
+  const options = ['comfortable', 'compact']
   const clear = ref(false)
   const counter = ref(false)
   const disabled = ref(false)
+  const title = ref()
   const props = computed(() => {
     return {
       clearable: clear.value || undefined,
       counter: counter.value || undefined,
       disabled: disabled.value || undefined,
-      label: 'File upload',
+      density: model.value,
+      title: title.value || undefined,
       variant: model.value === 'default' ? undefined : model.value,
     }
   })
diff --git a/packages/docs/src/pages/en/components/file-upload.md b/packages/docs/src/pages/en/components/file-upload.md
index cb06c39a5d1..13506c501af 100644
--- a/packages/docs/src/pages/en/components/file-upload.md
+++ b/packages/docs/src/pages/en/components/file-upload.md
@@ -16,13 +16,11 @@ features:
 
 # File upload
 
-
-
 <PageFeatures />
 
 ::: warning
 
-This feature requires [v3.6.0](/getting-started/release-notes/?version=v3.6.0)
+This feature requires [v3.7.3](/getting-started/release-notes/?version=v3.7.3)
 
 :::
 
@@ -42,6 +40,8 @@ export default createVuetify({
 
 ## Usage
 
+The `v-file-upload` component is a drag and drop area for uploading files. It can be customized with slots and has support for density and multiple styles.
+
 <ExamplesUsage name="v-file-upload" />
 
 <PromotedEntry />
@@ -51,10 +51,49 @@ export default createVuetify({
 | Component | Description |
 | - | - |
 | [v-file-upload](/api/v-file-upload/) | Primary Component |
+| [v-file-upload-item](/api/v-file-upload-item/) | Item Component |
 | [v-file-input](/api/v-file-input/) | File input component |
 
 <ApiInline hide-links />
 
 ## Guide
 
-TODO
+The v-file-upload component is a more visual counterpart to the [v-file-input](/components/file-inputs/) component. It provides a drag and drop area for files, and can be customized with slots.
+
+### Props
+
+Utilize various properties to customize the look and feel of the `v-file-upload` component.
+
+#### Density
+
+The **density** prop is used to control the vertical space the upload takes up.
+
+<ExamplesExample file="v-file-upload/prop-density" />
+
+#### Content
+
+Use the **browse-text**, **divider-text**, **icon**, **title**, or **subtitle** props to customize the text displayed in the component.
+
+<ExamplesExample file="v-file-upload/prop-content" />
+
+#### Disabled
+
+The **disabled** property reduces the opacity of the component and prevents interaction.
+
+<ExamplesExample file="v-file-upload/prop-disabled" />
+
+#### Scrim
+
+The **scrim** property allows you to set a colored scrim when hovering over the component with files.
+
+<ExamplesExample file="v-file-upload/prop-scrim" />
+
+### Slots
+
+The `v-file-upload` component has several slots that can be used to customize the component.
+
+#### Item
+
+The **item** slot is used to customize the appearance of the file item.
+
+<ExamplesExample file="v-file-upload/slot-item" />
diff --git a/packages/vuetify/src/labs/VFileUpload/VFileUpload.sass b/packages/vuetify/src/labs/VFileUpload/VFileUpload.sass
index 1dec64f3ee4..eafca31e8e9 100644
--- a/packages/vuetify/src/labs/VFileUpload/VFileUpload.sass
+++ b/packages/vuetify/src/labs/VFileUpload/VFileUpload.sass
@@ -61,7 +61,10 @@
       margin-bottom: $file-upload-icon-margin-bottom - 1rem
 
   .v-file-upload-divider
+    align-items: center
+    display: flex
     margin: $file-upload-divider-margin
+    justify-content: center
     width: 100%
 
   .v-file-upload-items