From 76341b543c5ea529faa47823aa72922a9bb82e18 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Fri, 1 Dec 2023 15:53:13 +0100
Subject: [PATCH] restore `@uppy/file-input` documentation

---
 docs/sources/file-input.mdx | 166 ++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 docs/sources/file-input.mdx

diff --git a/docs/sources/file-input.mdx b/docs/sources/file-input.mdx
new file mode 100644
index 000000000..41d7ad6cf
--- /dev/null
+++ b/docs/sources/file-input.mdx
@@ -0,0 +1,166 @@
+---
+sidebar_position: 3
+slug: /file-input
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+import UppyCdnExample from '/src/components/UppyCdnExample';
+
+# File input
+
+The `@uppy/file-input` plugin is the most barebones UI for selecting files — it
+shows a single button that, when clicked, opens up the browser’s file selector.
+
+## When should I use it?
+
+When you want users to select files from their local machine with a minimal UI.
+
+## Install
+
+<Tabs>
+  <TabItem value="npm" label="NPM" default>
+
+```shell
+npm install @uppy/file-input
+```
+
+  </TabItem>
+
+  <TabItem value="yarn" label="Yarn">
+
+```shell
+yarn add @uppy/file-input
+```
+
+  </TabItem>
+
+  <TabItem value="cdn" label="CDN">
+    <UppyCdnExample>
+      {`
+        import { Uppy, FileInput } from "{{UPPY_JS_URL}}"
+        const uppy = new Uppy()
+        uppy.use(FileInput, { target: document.body })
+      `}
+    </UppyCdnExample>
+  </TabItem>
+</Tabs>
+
+## Use
+
+```js showLineNumbers
+import Uppy from '@uppy/core';
+import FileInput from '@uppy/file-input';
+
+import '@uppy/core/dist/style.min.css';
+import '@uppy/file-input/dist/style.css';
+
+new Uppy().use(FileInput, { target: '#uppy-file-input' });
+```
+
+:::note
+
+The `@uppy/file-input` plugin includes some basic styles for use with the
+[`pretty`](#pretty-true) option, like shown in the
+[example](/examples/xhrupload). You can also choose not to use it and provide
+your own styles instead.
+
+Import general Core styles from `@uppy/core/dist/style.css` first, then add the
+File Input styles from `@uppy/file-input/dist/style.css`. A minified version is
+also available as `style.min.css` at the same path. The way to do import depends
+on your build system.
+
+:::
+
+## API
+
+### Options
+
+#### `id`
+
+A unique identifier for this plugin (`string`, default: `'FileInput'`).
+
+#### `title`
+
+Configures the title / name shown in the UI, for instance, on Dashboard tabs
+(`string`, default: `'File Input'`).
+
+#### `target`
+
+DOM element, CSS selector, or plugin to place the audio into (`string` or
+`Element`, default: `null`).
+
+#### `pretty`
+
+When true, display a styled button (see [example](/examples/xhrupload)) that,
+when clicked, opens the file selector UI. When false, a plain old browser
+`<input type="file">` element is shown (`boolean`, default: `true`).
+
+#### `inputName`
+
+The `name` attribute for the `<input type="file">` element (`string`, default:
+`'files[]'`).
+
+#### `locale`
+
+```js
+export default {
+	strings: {
+		// The same key is used for the same purpose by @uppy/robodog's `form()` API, but our
+		// locale pack scripts can't access it in Robodog. If it is updated here, it should
+		// also be updated there!
+		chooseFiles: 'Choose files',
+	},
+};
+```
+
+## Custom file inpt
+
+If you don’t like the look/feel of the button rendered by `@uppy/file-input`,
+feel free to forgo the plugin and use your own custom button on a page, like so:
+
+```html
+<input type="file" id="my-file-input" />
+```
+
+Then add this JS to attach it to Uppy:
+
+```js
+const uppy = new Uppy(/* ... */);
+const fileInput = document.querySelector('#my-file-input');
+
+fileInput.addEventListener('change', (event) => {
+	const files = Array.from(event.target.files);
+
+	files.forEach((file) => {
+		try {
+			uppy.addFile({
+				source: 'file input',
+				name: file.name,
+				type: file.type,
+				data: file,
+			});
+		} catch (err) {
+			if (err.isRestriction) {
+				// handle restrictions
+				console.log('Restriction error:', err);
+			} else {
+				// handle other errors
+				console.error(err);
+			}
+		}
+	});
+});
+
+// it’s probably a good idea to clear the `<input>`
+// after the upload or when the file was removed
+// (see https://github.com/transloadit/uppy/issues/2640#issuecomment-731034781)
+uppy.on('file-removed', () => {
+	fileInput.value = null;
+});
+
+uppy.on('complete', () => {
+	fileInput.value = null;
+});
+```