@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/File.md

@@ -0,0 +1,653 @@
+# File
+
+## Overview
+
+
+> Image: Illustration of a File component.
+
+
+## When to use this component
+- When users are required to upload one or more files.
+- When file type or size needs to be enforced at upload.
+
+## When to use another component
+- If the user needs to provide information that is not a file, use the appropriate data entry components instead.
+
+## Usage
+
+### Labels and attributes
+Use clear labels and include a supporting message specifying accepted file types.
+
+> Image: In the first example with a heart eyes emoji, the File component includes a supporting message providing further context to the user. In the second example with a grimacing emoji, no supporting message is included in the File component.
+
+
+### Progress
+Whenever possible, display progress on the File.Item to avoid frustration.
+
+> Image: In the first example with a heart eyes emoji, the upload status of the File is visible to the user. In the second example with a grimacing emoji, the upload status is not visible to the user.
+
+
+### Error messaging
+Offer clear, actionable error messages to help users understand and fix the issue.
+
+Use when file upload is a required field. 
+> Image: In the first example with a heart eyes emoji, the user is given additional context on the error, that is, no file was uploaded. In the second example with a grimacing emoji, no further context is provided.
+
+
+Use when the type of file uploaded is not accepted. 
+> Image: In the first example with a heart eyes emoji, the user is given additional context on the error, that is, the uploaded file type was not accepted. In the second example with a grimacing emoji, no further context is provided.
+
+
+## Examples
+
+
+### Single File
+
+Here, selecting a new file will replace the existing file.
+
+```typescript
+import React, { Component } from 'react';
+
+import File, { FileRequestAddHandler } from '@splunk/react-ui/File';
+
+
+class Single extends Component<object, { filename?: string }> {
+    private fileReader: FileReader;
+
+    constructor(props: object) {
+        super(props);
+
+        this.state = {};
+
+        this.fileReader = new FileReader();
+    }
+
+    handleAddFiles: FileRequestAddHandler = (files) => {
+        if (files.length > 0) {
+            const file = files[0];
+
+            if (this.fileReader.readyState === 1) {
+                this.fileReader.abort();
+            }
+
+            this.fileReader.onload = () => {
+                // can access this.fileReader.result
+                this.setState({ filename: file.name });
+            };
+
+            this.fileReader.readAsDataURL(file);
+        }
+    };
+
+    handleRemoveFile = () => {
+        if (this.fileReader.readyState === 1) {
+            this.fileReader.abort();
+        }
+
+        this.setState({ filename: undefined });
+    };
+
+    render() {
+        return (
+            <div style={{ maxWidth: 300 }}>
+                <File onRequestAdd={this.handleAddFiles} onRequestRemove={this.handleRemoveFile}>
+                    {this.state.filename && <File.Item name={this.state.filename} />}
+                </File>
+            </div>
+        );
+    }
+}
+
+export default Single;
+```
+
+
+
+### Disabled
+
+```typescript
+import React, { Component } from 'react';
+
+import File, { FileRequestAddHandler } from '@splunk/react-ui/File';
+
+
+class Disabled extends Component<object, { filename?: string }> {
+    private fileReader: FileReader;
+
+    constructor(props: object) {
+        super(props);
+
+        this.state = {};
+
+        this.fileReader = new FileReader();
+    }
+
+    handleAddFiles: FileRequestAddHandler = (files) => {
+        const file = files[0];
+
+        if (this.fileReader.readyState === 1) {
+            this.fileReader.abort();
+        }
+
+        this.fileReader.onload = () => {
+            // can access this.fileReader.result
+            this.setState({ filename: file.name });
+        };
+
+        this.fileReader.readAsDataURL(file);
+    };
+
+    handleRemoveFile = () => {
+        if (this.fileReader.readyState === 1) {
+            this.fileReader.abort();
+        }
+
+        this.setState({ filename: undefined });
+    };
+
+    render() {
+        return (
+            <div style={{ width: 300 }}>
+                <File
+                    help="This is some help content suggesting a max size of 2MB."
+                    onRequestAdd={this.handleAddFiles}
+                    onRequestRemove={this.handleRemoveFile}
+                    disabled
+                >
+                    {this.state.filename && <File.Item name={this.state.filename} />}
+                </File>
+                <File
+                    help="This is some help content suggesting a max size of 2MB."
+                    onRequestAdd={this.handleAddFiles}
+                    onRequestRemove={this.handleRemoveFile}
+                    disabled
+                >
+                    <File.Item name="Apple" />
+                    <File.Item name="Cupcake" />
+                    <File.Item name="Banana" />
+                    <File.Item name="Orange" />
+                </File>
+            </div>
+        );
+    }
+}
+
+export default Disabled;
+```
+
+
+
+### Multifile
+
+By storing an array of items, multiple files can be supported.
+
+```typescript
+import React, { Component } from 'react';
+
+import File, { FileRequestAddHandler, FileRequestRemoveHandler } from '@splunk/react-ui/File';
+
+interface FileItem {
+    name: string;
+    value?: string | ArrayBuffer | null;
+}
+
+
+class Multi extends Component<object, { files: FileItem[] }> {
+    static loadFile(file: globalThis.File) {
+        const fileItem: FileItem = { name: file.name };
+
+        const fileReader = new FileReader();
+        fileReader.onload = () => {
+            fileItem.value = fileReader.result;
+        };
+        fileReader.readAsDataURL(file);
+
+        return fileItem;
+    }
+
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            files: [],
+        };
+    }
+
+    handleAddFiles: FileRequestAddHandler = (files) => {
+        const newItems = files.map(Multi.loadFile);
+
+        this.setState((state) => ({
+            files: [...state.files, ...newItems],
+        }));
+    };
+
+    handleRemoveFile: FileRequestRemoveHandler = ({ index }) => {
+        this.setState((state) => {
+            const files = state.files.slice(0);
+            files.splice(index, 1);
+            return { files };
+        });
+    };
+
+    render() {
+        const children = this.state.files.map((item) => (
+            <File.Item itemId={item.name} name={item.name} key={item.name} />
+        ));
+
+        return (
+            <div style={{ width: 300 }}>
+                <File
+                    onRequestAdd={this.handleAddFiles}
+                    onRequestRemove={this.handleRemoveFile}
+                    allowMultiple
+                >
+                    {children}
+                </File>
+            </div>
+        );
+    }
+}
+
+export default Multi;
+```
+
+
+
+### Customized supports message and help
+
+The default supports message can be customized. A help message can also be added.
+
+```typescript
+import React from 'react';
+
+import { noop } from 'lodash';
+
+import File from '@splunk/react-ui/File';
+import Link from '@splunk/react-ui/Link';
+
+
+export default function CustomizedMessages() {
+    return (
+        <div style={{ width: 300 }}>
+            <File
+                accept="image/*"
+                onRequestAdd={noop}
+                onRequestRemove={noop}
+                supportsMessage={<>Supports image file types: e.g. .jpg, .gif, or .png</>}
+                help={
+                    <>
+                        Learn more about <Link>supported image formats</Link>.
+                    </>
+                }
+            >
+                <File.Item name="Cupcake" uploadPercentage={40} />
+            </File>
+        </div>
+    );
+}
+```
+
+
+
+### Progress
+
+The File.Item can display its upload progress.
+
+```typescript
+import React from 'react';
+
+import { noop } from 'lodash';
+
+import File from '@splunk/react-ui/File';
+
+
+export default function Progress() {
+    return (
+        <div style={{ width: 300 }}>
+            <File onRequestAdd={noop} onRequestRemove={noop}>
+                <File.Item name="Cupcake" uploadPercentage={40} />
+            </File>
+        </div>
+    );
+}
+```
+
+
+
+### Drop Anywhere
+
+The File.Item can be dropped anywhere on the page. This example must open in a modal since the drop zone is the entire page and affects the other Files on this page.
+
+```typescript
+import React, { Component } from 'react';
+
+import Button from '@splunk/react-ui/Button';
+import File, { FileRequestAddHandler } from '@splunk/react-ui/File';
+
+
+class DropAnywhere extends Component<object, { filename?: string; open: boolean }> {
+    private fileReader: FileReader;
+
+    constructor(props: object) {
+        super(props);
+
+        this.state = {
+            open: false,
+        };
+
+        this.fileReader = new FileReader();
+    }
+
+    handleAddFiles: FileRequestAddHandler = (files) => {
+        if (files.length > 0) {
+            const file = files[0];
+
+            if (this.fileReader.readyState === 1) {
+                this.fileReader.abort();
+            }
+
+            this.fileReader.onload = () => {
+                // can access this.fileReader.result
+                this.setState({ filename: file.name });
+            };
+
+            this.fileReader.readAsDataURL(file);
+        }
+    };
+
+    handleRemoveFile = () => {
+        if (this.fileReader.readyState === 1) {
+            this.fileReader.abort();
+        }
+
+        this.setState({ filename: undefined });
+    };
+
+    handleOpen = () => {
+        this.setState({
+            open: true,
+        });
+    };
+
+    handleClose = () => {
+        this.setState({
+            open: false,
+        });
+    };
+
+    render() {
+        const modalStyles: React.CSSProperties = {
+            position: 'relative',
+            top: 0,
+            right: 0,
+            bottom: 0,
+            left: 0,
+            zIndex: 100,
+            padding: 10,
+            margin: '0 -10px 4px',
+            height: 140,
+        };
+
+        const closeStyles: React.CSSProperties = {
+            position: 'relative',
+            left: 'calc(50% - 60px)',
+            marginTop: 10,
+        };
+
+        return (
+            <div>
+                <Button onClick={this.handleOpen} label="Show drop anywhere example" />
+
+                {this.state.open && (
+                    <div style={modalStyles}>
+                        <File
+                            dropAnywhere
+                            help="This is some help content suggesting a max size of 2MB."
+                            onRequestAdd={this.handleAddFiles}
+                            onRequestRemove={this.handleRemoveFile}
+                        >
+                            {this.state.filename && <File.Item name={this.state.filename} />}
+                        </File>
+
+                        <Button
+                            onClick={this.handleClose}
+                            label="Close example"
+                            style={closeStyles}
+                        />
+                    </div>
+                )}
+            </div>
+        );
+    }
+}
+
+export default DropAnywhere;
+```
+
+
+
+### Full Screen
+
+```typescript
+import React, { useRef, useState } from 'react';
+
+import styled from 'styled-components';
+
+import Button from '@splunk/react-ui/Button';
+import File, { FileRequestAddHandler } from '@splunk/react-ui/File';
+import { variables } from '@splunk/themes';
+
+const StyledFullscreenOverlay = styled.div`
+    position: fixed;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    z-index: ${variables.zindexModal};
+    background-color: ${variables.backgroundColorPage};
+    display: flex;
+    justify-content: center;
+    align-items: center;
+`;
+
+const StyledButton = styled(Button)`
+    position: absolute;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+`;
+
+
+function Fullscreen() {
+    const fileReader = useRef(new FileReader());
+    const fullscreenToggle = useRef<HTMLButtonElement | null>(null);
+    const [open, setOpen] = useState<boolean>(false);
+    const [fileName, setFileName] = useState<string | undefined>(undefined);
+
+    const handleAddFiles: FileRequestAddHandler = (files) => {
+        const currentFileReader = fileReader.current;
+        if (files.length > 0) {
+            const file = files[0];
+
+            if (currentFileReader.readyState === 1) {
+                currentFileReader.abort();
+            }
+
+            currentFileReader.onload = () => {
+                // can access this.fileReader.result
+                setFileName(file.name);
+            };
+
+            currentFileReader.readAsDataURL(file);
+        }
+    };
+
+    const handleRemoveFile = () => {
+        const currentFileReader = fileReader.current;
+        if (currentFileReader.readyState === 1) {
+            currentFileReader.abort();
+        }
+
+        setFileName(undefined);
+    };
+
+    const handleOpen = () => {
+        setOpen(true);
+    };
+
+    const handleClose = () => {
+        fullscreenToggle.current?.focus();
+        setOpen(false);
+    };
+
+    return (
+        <div style={{ width: 300 }}>
+            <Button
+                elementRef={fullscreenToggle}
+                onClick={handleOpen}
+                label="Open full screen file example"
+            />
+
+            {open && (
+                <StyledFullscreenOverlay>
+                    <File
+                        fullscreen
+                        help="This is some help content suggesting a max size of 2MB."
+                        onRequestAdd={handleAddFiles}
+                        onRequestRemove={handleRemoveFile}
+                    >
+                        {fileName && <File.Item name={fileName} />}
+                    </File>
+
+                    <StyledButton onClick={handleClose} label="Close example" />
+                </StyledFullscreenOverlay>
+            )}
+        </div>
+    );
+}
+
+export default Fullscreen;
+```
+
+
+
+### Error
+
+The File and File.Item have separate error states. Generally, they should not be used together. Either the File is in error (for example, required field), or an Item is in error (for example, incorrect file type).
+
+```typescript
+import React from 'react';
+
+import { noop } from 'lodash';
+
+import File from '@splunk/react-ui/File';
+
+
+export default function FileErrors() {
+    return (
+        <div style={{ width: 300 }}>
+            <File onRequestAdd={noop} onRequestRemove={noop} error />
+            <br />
+            <br />
+            <File onRequestAdd={noop} onRequestRemove={noop} onRequestRetry={noop}>
+                <File.Item name="Apple" />
+                <File.Item name="Cupcake" error />
+                <File.Item name="Banana" />
+                <File.Item name="Orange" />
+            </File>
+        </div>
+    );
+}
+```
+
+
+
+
+## API
+
+
+### File API
+
+File provides the ability to accept files and present uploaded files. It does not provide
+file readers, only a reference to the file. This can be used to post binary content, or
+upload using an array buffer.
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| accept | string | no |  | The accept attribute for the file browser. This does not filter dropped items, which must be filtered manually. File will create a default "supports" message based on this value. |
+| allowMultiple | boolean | no |  | Allow the user to upload multiple files. |
+| children | React.ReactNode | no |  |  |
+| disabled | boolean | no |  | Prevents user from dropping files. |
+| dropAnywhere | boolean | no |  | File can be dropped anywhere on the page. |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
+| error | boolean | no |  | Show the component in an error state. This has no effect on the full-screen File. Note: File.Item has a separate error property. |
+| fullscreen | boolean | no |  | There can only be one File component on the page as it will take all files dropped on the page. |
+| help | React.ReactNode | no |  | Show help text. |
+| inputId | string | no |  | An id for the input, which may be necessary for accessibility, such as for aria attributes. |
+| name | string | no |  | The name is returned with onRequestAdd and onRequestRemove events, which can be used to identify the control when multiple controls share an onChange callback. |
+| onRequestAdd | FileRequestAddHandler | no |  | A callback for when the user selects one or more files. The function is passed a file reference, which can then be used to read the file. This may be used to enforce file constraints or upload the file. |
+| onRequestRemove | FileRequestRemoveHandler | no |  | A callback for when the user requests to remove a file. The function is passed the event and an object with the Item's index and name: `(event, {index, name})`. |
+| onRequestRetry | (data: {     event: { itemId?: string; name: string };     filename: string;     index: number;     itemId?: string;     name?: string; }) => void | no |  | A callback for when the user requests to retry the upload after upload resulted in error. The function is passed the event and an object with the Item's index and name: `(event, {index, name})`. |
+| supportsMessage | React.ReactNode | no |  |  |
+
+#### Types
+
+| Name | Type | Description |
+|------|------|------|
+| FileRequestAddHandler | (files: globalThis.File[], data: { name?: string }) => void |  |
+| FileRequestRemoveHandler | (data: {     event: {         itemId?: string;         name: string;     };     filename: string;     index: number;     itemId?: string;     name?: string; }) => void |  |
+
+
+
+### File.Item API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| disabled | boolean | no |  |  |
+| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| error | boolean | no | false | Show the Item in an error state. |
+| itemId | string | no |  | A unique for this file. |
+| name | string | yes |  | The name is displayed on the item. |
+| uploadPercentage | number | no |  | If the uploadPercentage is 0, the item is assumed to be queued. If the upload is complete or not applicable, uploadPercentage must be undefined. |
+
+
+
+
+
+## Accessibility
+
+## Visual Design
+- Color contrast ratio **MUST** be:
+    - &gt=4.5:1 for [SC 1.4.3][1]:
+        - Any text (static, link, etc.) to background color
+    - &gt=3:1 for [SC 1.4.11][2]
+        - Drop-area (usually a dotted line) to background color
+        - Any functional icon (refresh, close, delete) to background color
+
+## Content
+- **SHOULD** have a descriptive button, such as "Browse Files" or "Upload File"; avoid verb-only phrases such as "Browse".
+
+## States
+- Feedback mechanism **MUST** be provided for upload:
+    - In progress
+    - Success
+    - Error
+        - Single file
+        - One or more files in multi-upload
+
+## Interaction Model
+- **MUST** have keyboard navigation [SC 2.1][3]:
+    - <kbd>Tab</kbd> and <kbd>Shift+Tab</kbd>: focuses button to upload file and any icons associated with uploaded files, regardless of state.
+
+## Implementation
+- When more than one file is uploaded, screen reader **MUST** announce file count, i.e. "1 of n" [SC 4.1.2][4]
+
+[1]: https://www.w3.org/TR/WCAG21/#contrast-minimum
+[2]: https://www.w3.org/TR/WCAG21/#non-text-contrast
+[3]: https://www.w3.org/TR/WCAG21/#keyboard-accessible
+[4]: https://www.w3.org/TR/WCAG21/#name-role-value
+