FileUploadInput: abandon middleware, render children, update examples

Author: msssk

src/examples/src/config.tsx

@@ -61,8 +61,9 @@ import ActionsDialog from './widgets/dialog/ActionsDialog';
 import BasicEmailInput from './widgets/email-input/Basic';
 import BasicFileUploadInput from './widgets/file-upload-input/Basic';
 import DisabledFileUploadInput from './widgets/file-upload-input/Disabled';
-import LabelledFileUploadInput from './widgets/file-upload-input/Labels';
+import LabelledFileUploadInput from './widgets/file-upload-input/Labelled';
 import MultipleFileUploadInput from './widgets/file-upload-input/Multiple';
+import NoDropFileUploadInput from './widgets/file-upload-input/NoDrop';
 import BasicFileUploader from './widgets/file-uploader/Basic';
 import DisabledFileUploader from './widgets/file-uploader/Disabled';
 import MultipleFileUploader from './widgets/file-uploader/Multiple';
@@ -723,12 +724,19 @@ export const config = {
 				{
 					title: 'Multiple FileUploadInput',
 					filename: 'Multiple',
-					module: MultipleFileUploadInput
+					module: MultipleFileUploadInput,
+					description:
+						'Demonstrates using child `content` property to render information about the uploaded files that is available to the `onValue` callback.'
 				},
 				{
-					title: 'FileUploadInput with custom labels',
-					filename: 'Labels',
+					title: 'FileUploadInput with label',
+					filename: 'Labelled',
 					module: LabelledFileUploadInput
+				},
+				{
+					title: 'FileUploadInput with no DnD',
+					filename: 'NoDrop',
+					module: NoDropFileUploadInput
 				}
 			]
 		},

src/examples/src/widgets/file-upload-input/Labelled.tsx

@@ -0,0 +1,25 @@
+import { create, tsx } from '@dojo/framework/core/vdom';
+import icache from '@dojo/framework/core/middleware/icache';
+import { FileUploadInput } from '@dojo/widgets/file-upload-input';
+import Example from '../../Example';
+
+const factory = create({ icache });
+
+export default factory(function Labelled({ middleware: { icache } }) {
+	const selectedFiles: File[] = icache.getOrSet('selectedFiles', []);
+
+	function onValue(files: File[]) {
+		icache.set('selectedFiles', files);
+	}
+
+	return (
+		<Example>
+			<FileUploadInput accept="image/*" onValue={onValue}>
+				{{
+					label: 'Upload a profile image'
+				}}
+			</FileUploadInput>
+			<div>Selected file: {selectedFiles.length ? selectedFiles[0].name : 'none'}</div>
+		</Example>
+	);
+});

src/examples/src/widgets/file-upload-input/Labels.tsx

@@ -1,7 +1,9 @@
 import { create, tsx } from '@dojo/framework/core/vdom';
+import icache from '@dojo/framework/core/middleware/icache';
 import { FileUploadInput } from '@dojo/widgets/file-upload-input';
 import Example from '../../Example';
-import icache from '@dojo/framework/core/middleware/icache';
+
+import * as css from './multiple.m.css';
 
 const factory = create({ icache });
 
@@ -14,29 +16,34 @@ export default factory(function Multiple({ middleware: { icache } }) {
 
 	return (
 		<Example>
-			<FileUploadInput onValue={onValue} multiple />
-			{selectedFiles.length > 0 && (
-				<table>
-					<thead>
-						<th>Name</th>
-						<th>Modified</th>
-						<th>Type</th>
-						<th>Bytes</th>
-					</thead>
-					<tbody>
-						{selectedFiles.map(function(file) {
-							return (
-								<tr key={file.name}>
-									<td>{file.name}</td>
-									<td>{new Date(file.lastModified).toLocaleString()}</td>
-									<td>{file.type}</td>
-									<td>{String(file.size)}</td>
-								</tr>
-							);
-						})}
-					</tbody>
-				</table>
-			)}
+			<FileUploadInput onValue={onValue} multiple>
+				{{
+					content: selectedFiles.length ? (
+						<table classes={[css.table]}>
+							<thead>
+								<th>Name</th>
+								<th>Modified</th>
+								<th>Type</th>
+								<th>Bytes</th>
+							</thead>
+							<tbody>
+								{selectedFiles.map(function(file) {
+									return (
+										<tr key={file.name}>
+											<td>{file.name}</td>
+											<td>{new Date(file.lastModified).toLocaleString()}</td>
+											<td>{file.type}</td>
+											<td>{String(file.size)}</td>
+										</tr>
+									);
+								})}
+							</tbody>
+						</table>
+					) : (
+						''
+					)
+				}}
+			</FileUploadInput>
 		</Example>
 	);
 });

src/examples/src/widgets/file-upload-input/Multiple.tsx

@@ -0,0 +1,21 @@
+import { create, tsx } from '@dojo/framework/core/vdom';
+import icache from '@dojo/framework/core/middleware/icache';
+import { FileUploadInput } from '@dojo/widgets/file-upload-input';
+import Example from '../../Example';
+
+const factory = create({ icache });
+
+export default factory(function NoDrop({ middleware: { icache } }) {
+	const selectedFiles: File[] = icache.getOrSet('selectedFiles', []);
+
+	function onValue(files: File[]) {
+		icache.set('selectedFiles', files);
+	}
+
+	return (
+		<Example>
+			<FileUploadInput allowDnd={false} onValue={onValue} />
+			<div>Selected file: {selectedFiles.length ? selectedFiles[0].name : 'none'}</div>
+		</Example>
+	);
+});

src/examples/src/widgets/file-upload-input/NoDrop.tsx

@@ -0,0 +1,3 @@
+.table {
+	width: 100%;
+}

src/examples/src/widgets/file-upload-input/multiple.m.css

@@ -0,0 +1 @@
+export const table: string;

src/examples/src/widgets/file-upload-input/multiple.m.css.d.ts

@@ -1,22 +1,21 @@
 # @dojo/widgets/file-upload-input
 
-Dojo's `FileUploadInput` provides an interface for managing file uploads using `<input type="file">`. This is a
-controlled component that only provides file selection. The `FileUploader` widget provides more full-featured file
-upload functionality. If you require more customization than `FileUploader` provides you can build a custom file
-uploader widget based on `FileUploadInput`. You can provide a callback function to the `onValue` property to receive
-a `File` array whenever files are selected.
+Dojo's `FileUploadInput` provides an interface for managing file uploads supporting both `<input type="file">` and the
+HTML Drag and Drop API. This is a controlled widget that only provides file selection. The `FileUploader` widget
+provides more full-featured file upload functionality. If you require more customization than `FileUploader` provides
+you can build a custom file uploader widget based on `FileUploadInput`. You can provide a callback function to the
+`onValue` property to receive a `File` array whenever files are selected.
 
 ## Features
 
 - Single or multiple file upload
 - Add files from OS-provided file selection dialog
 - Add files with drag and drop
-- Validation
 
 ### Keyboard features
 
 - Trigger file selection dialog with keyboard
 
 ### i18n features
 
-- Localized version of default labels for the button and DnD can be provided in nls resources
+- Localized version of labels for the button and DnD can be provided in nls resources

src/file-upload-input/README.md

@@ -0,0 +1,30 @@
+# DOM structure
+
+The only way to launch the operating system's file selection dialog is with the native `<input type="file">` element.
+This element renders a button in the UI which is not very customizable. A hidden input can still be used to open the
+dialog but you have to call its `click` method.
+
+The overlay `<div>` provides a visual indicator that a drag operation is in progress.
+
+# Drag and Drop
+
+https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API
+
+DOM events are used directly because writing reactive middleware for this use-case ends up either very specific and not
+widely useful, or if attempts are made to provide a general-purpose API the logic becomes very convoluted. Dealing with
+a conditionally rendered overlay becomes a hassle as well.
+
+The `dragenter` event must be listened for to detect when a drag enters the target area. At this point the overlay
+should be rendered and it must have no children and must be the highest layer. If `dragenter` and `dragleave` event
+listeners are added to an element with visible children then spurious enter/leave events are constantly triggered as
+the cursor moves over children (even letters in text).
+
+- `dragenter`: listened for on the root element at all times that DnD is allowed
+  - makes the overlay visible to indicate DnD is active
+- `dragover`: this event must be listened for, but nothing needs to be done with it other than `event.preventDefault()`
+(the default action for DragEvents is to cancel the drag operation)
+  - is listened for on the root since it bubbles from the overlay
+- `dragleave`: listened for on the overlay since it is unreliable on the root element
+  - when this event fires the overlay is hidden
+- `drop`: listened for on the root since it bubbles from the overlay
+  - get the files and update to indicate DnD is no longer active