@patternfly/react-docs 7.6.0-prerelease.6 → 7.6.0-prerelease.8

package/patternfly-docs/generated/components/file-upload/multiple-file-upload/react.js

@@ -0,0 +1,398 @@
+import React from 'react';
+import { AutoLinkHeader, Example, Link as PatternflyThemeLink } from '@patternfly/documentation-framework/components';
+import { useEffect, useState } from 'react';
+import UploadIcon from '@patternfly/react-icons/dist/esm/icons/upload-icon';
+const pageData = {
+  "id": "Multiple file upload",
+  "section": "components",
+  "subsection": "file-upload",
+  "deprecated": false,
+  "template": false,
+  "beta": false,
+  "demo": false,
+  "newImplementationLink": false,
+  "source": "react",
+  "tabName": null,
+  "slug": "/components/file-upload/multiple-file-upload/react",
+  "sourceLink": "https://github.com/patternfly/patternfly-react/blob/main/packages/react-core/src/components/MultipleFileUpload/examples/MultipleFileUpload.md",
+  "relPath": "packages/react-core/src/components/MultipleFileUpload/examples/MultipleFileUpload.md",
+  "propComponents": [
+    {
+      "name": "MultipleFileUpload",
+      "description": "Acts as a container for all other MultipleFileUpload sub-components. This sub-component\nalso provides the functionality for file uploads, and access to the uploaded files via\na callback.",
+      "props": [
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside the multi upload field"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Class to add to outer div"
+        },
+        {
+          "name": "dropzoneProps",
+          "type": "DropzoneOptions",
+          "description": "Optional extra props to customize react-dropzone.",
+          "defaultValue": "{}"
+        },
+        {
+          "name": "isHorizontal",
+          "type": "boolean",
+          "description": "Flag setting the component to horizontal styling mode"
+        },
+        {
+          "name": "onFileDrop",
+          "type": "(event: DropEvent, data: File[]) => void",
+          "description": "When files are dropped or uploaded this callback will be called with all accepted files",
+          "defaultValue": "() => {}"
+        }
+      ]
+    },
+    {
+      "name": "MultipleFileUploadMain",
+      "description": "Creates the visual upload interface, including the area to drag and drop files,\nan optional upload button, and descriptive instructions.",
+      "props": [
+        {
+          "name": "browseButtonText",
+          "type": "string",
+          "description": "Visible text label for the upload button",
+          "defaultValue": "'Upload'"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Class to add to outer div"
+        },
+        {
+          "name": "infoText",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside the info div"
+        },
+        {
+          "name": "isUploadButtonHidden",
+          "type": "boolean",
+          "description": "Flag to prevent the upload button from being rendered"
+        },
+        {
+          "name": "titleIcon",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside the title icon div"
+        },
+        {
+          "name": "titleText",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside the title text div"
+        },
+        {
+          "name": "titleTextSeparator",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside the title text separator div"
+        }
+      ]
+    },
+    {
+      "name": "MultipleFileUploadStatus",
+      "description": "Acts as an expandable container for all uploaded file statuses.\nAn optional text and/or icon can also be passed into this sub-component.\nThis sub-component can be conditionally rendered when at least 1 file has been\nattempted to be uploaded.",
+      "props": [
+        {
+          "name": "aria-label",
+          "type": "string",
+          "description": "Adds an accessible label to the list of status items."
+        },
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "description": "Content rendered inside multi file upload status list"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Class to add to outer div"
+        },
+        {
+          "name": "statusToggleIcon",
+          "type": "'danger' | 'success' | 'inProgress' | React.ReactNode",
+          "description": "Icon to show in the status toggle"
+        },
+        {
+          "name": "statusToggleText",
+          "type": "string",
+          "description": "String to show in the status toggle"
+        }
+      ]
+    },
+    {
+      "name": "MultipleFileUploadStatusItem",
+      "description": "Automatically reads an uploaded file to render a visual representation of it, including\nits name, size, and read status. This sub-component also allows custom reading of files\nvia various callbacks which will override the automatic reading behavior.",
+      "props": [
+        {
+          "name": "buttonAriaLabel",
+          "type": "string",
+          "description": "Adds accessibility text to the status item deletion button",
+          "defaultValue": "'Remove from list'"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Class to add to outer div"
+        },
+        {
+          "name": "customFileHandler",
+          "type": "(file: File) => void",
+          "description": "A callback to process file reading in a custom way"
+        },
+        {
+          "name": "file",
+          "type": "File",
+          "description": "The file object being represented by the status item"
+        },
+        {
+          "name": "fileIcon",
+          "type": "React.ReactNode",
+          "description": "A custom icon to show in place of the generic file icon"
+        },
+        {
+          "name": "fileName",
+          "type": "string",
+          "description": "A custom name to display for the file rather than using built in functionality to auto-fill it"
+        },
+        {
+          "name": "fileSize",
+          "type": "number",
+          "description": "A custom file size to display for the file rather than using built in functionality to auto-fill it"
+        },
+        {
+          "name": "onClearClick",
+          "type": "React.MouseEventHandler<HTMLButtonElement>",
+          "description": "Clear button was clicked",
+          "defaultValue": "() => {}"
+        },
+        {
+          "name": "onReadFail",
+          "type": "(error: DOMException, onReadFail: File) => void",
+          "description": "A callback for when the FileReader API fails",
+          "defaultValue": "() => {}"
+        },
+        {
+          "name": "onReadFinished",
+          "type": "(fileHandle: File) => void",
+          "description": "A callback for when a selected file finishes loading",
+          "defaultValue": "() => {}"
+        },
+        {
+          "name": "onReadStarted",
+          "type": "(fileHandle: File) => void",
+          "description": "A callback for when a selected file starts loading",
+          "defaultValue": "() => {}"
+        },
+        {
+          "name": "onReadSuccess",
+          "type": "(data: string, file: File) => void",
+          "description": "A callback for when the FileReader successfully reads the file",
+          "defaultValue": "() => {}"
+        },
+        {
+          "name": "progressAriaDescribedBy",
+          "type": "string",
+          "description": "Adds an accessible description to the ProgressBar via space separated list of ids. Required when helperText is passed in."
+        },
+        {
+          "name": "progressAriaLabel",
+          "type": "string",
+          "description": "Adds accessible text to the progress bar. Required when title not used and there is not any label associated with the progress bar"
+        },
+        {
+          "name": "progressAriaLabelledBy",
+          "type": "string",
+          "description": "Associates the progress bar with it's label for accessibility purposes. Required when title not used"
+        },
+        {
+          "name": "progressAriaLiveMessage",
+          "type": "string | ((loadPercentage: number) => string)",
+          "description": "Modifies the text announced by assistive technologies when the progress bar updates."
+        },
+        {
+          "name": "progressHelperText",
+          "type": "React.ReactNode",
+          "description": "Additional content related to the status item."
+        },
+        {
+          "name": "progressId",
+          "type": "string",
+          "description": "Unique identifier for progress. Generated if not specified."
+        },
+        {
+          "name": "progressValue",
+          "type": "number",
+          "description": "A custom value to display for the progress component rather than using built in functionality to auto-fill it"
+        },
+        {
+          "name": "progressVariant",
+          "type": "'danger' | 'success' | 'warning'",
+          "description": "A custom variant to apply to the progress component rather than using built in functionality to auto-fill it"
+        }
+      ]
+    }
+  ],
+  "cssPrefix": [
+    "pf-v6-c-multiple-file-upload"
+  ],
+  "examples": [
+    "Basic"
+  ]
+};
+pageData.liveContext = {
+  useEffect,
+  useState,
+  UploadIcon
+};
+pageData.examples = {
+  'Basic': props => 
+    <Example {...pageData} {...props} {...{"code":"import { useEffect, useState } from 'react';\nimport {\n  MultipleFileUpload,\n  MultipleFileUploadMain,\n  MultipleFileUploadStatus,\n  MultipleFileUploadStatusItem,\n  Checkbox,\n  HelperText,\n  HelperTextItem,\n  DropEvent\n} from '@patternfly/react-core';\nimport UploadIcon from '@patternfly/react-icons/dist/esm/icons/upload-icon';\n\ninterface readFile {\n  fileName: string;\n  data?: string;\n  loadResult?: 'danger' | 'success';\n  loadError?: DOMException;\n}\n\nexport const MultipleFileUploadBasic: React.FunctionComponent = () => {\n  const [isHorizontal, setIsHorizontal] = useState(false);\n  const [fileUploadShouldFail, setFileUploadShouldFail] = useState(false);\n  const [currentFiles, setCurrentFiles] = useState<File[]>([]);\n  const [readFileData, setReadFileData] = useState<readFile[]>([]);\n  const [showStatus, setShowStatus] = useState(false);\n  const [statusIcon, setStatusIcon] = useState('inProgress');\n\n  // only show the status component once a file has been uploaded, but keep the status list component itself even if all files are removed\n  if (!showStatus && currentFiles.length > 0) {\n    setShowStatus(true);\n  }\n\n  // determine the icon that should be shown for the overall status list\n  useEffect(() => {\n    if (readFileData.length < currentFiles.length) {\n      setStatusIcon('inProgress');\n    } else if (readFileData.every((file) => file.loadResult === 'success')) {\n      setStatusIcon('success');\n    } else {\n      setStatusIcon('danger');\n    }\n  }, [readFileData, currentFiles]);\n\n  // remove files from both state arrays based on their name\n  const removeFiles = (namesOfFilesToRemove: string[]) => {\n    const newCurrentFiles = currentFiles.filter(\n      (currentFile) => !namesOfFilesToRemove.some((fileName) => fileName === currentFile.name)\n    );\n\n    setCurrentFiles(newCurrentFiles);\n\n    const newReadFiles = readFileData.filter(\n      (readFile) => !namesOfFilesToRemove.some((fileName) => fileName === readFile.fileName)\n    );\n\n    setReadFileData(newReadFiles);\n  };\n\n  /** Forces uploaded files to become corrupted if \"Demonstrate error reporting by forcing uploads to fail\" is selected in the example,\n   * only used in this example for demonstration purposes */\n  const updateCurrentFiles = (files: File[]) => {\n    if (fileUploadShouldFail) {\n      const corruptedFiles = files.map((file) => ({ ...file, lastModified: 'foo' as unknown as number }));\n\n      setCurrentFiles((prevFiles) => [...prevFiles, ...(corruptedFiles as any)]);\n    } else {\n      setCurrentFiles((prevFiles) => [...prevFiles, ...files]);\n    }\n  };\n\n  // callback that will be called by the react dropzone with the newly dropped file objects\n  const handleFileDrop = (_event: DropEvent, droppedFiles: File[]) => {\n    // identify what, if any, files are re-uploads of already uploaded files\n    const currentFileNames = currentFiles.map((file) => file.name);\n    const reUploads = droppedFiles.filter((droppedFile) => currentFileNames.includes(droppedFile.name));\n\n    /** this promise chain is needed because if the file removal is done at the same time as the file adding react\n     * won't realize that the status items for the re-uploaded files needs to be re-rendered */\n    Promise.resolve()\n      .then(() => removeFiles(reUploads.map((file) => file.name)))\n      .then(() => updateCurrentFiles(droppedFiles));\n  };\n\n  // callback called by the status item when a file is successfully read with the built-in file reader\n  const handleReadSuccess = (data: string, file: File) => {\n    setReadFileData((prevReadFiles) => [...prevReadFiles, { data, fileName: file.name, loadResult: 'success' }]);\n  };\n\n  // callback called by the status item when a file encounters an error while being read with the built-in file reader\n  const handleReadFail = (error: DOMException, file: File) => {\n    setReadFileData((prevReadFiles) => [\n      ...prevReadFiles,\n      { loadError: error, fileName: file.name, loadResult: 'danger' }\n    ]);\n  };\n\n  // add helper text to a status item showing any error encountered during the file reading process\n  const createHelperText = (file: File, fileIndex: number) => {\n    const fileResult = readFileData.find((readFile) => readFile.fileName === file.name);\n    if (fileResult?.loadError) {\n      return (\n        <HelperText id={`multiple-file-upload-basic-example-help-text-${fileIndex}`} isLiveRegion>\n          <HelperTextItem variant=\"error\">{fileResult.loadError.toString()}</HelperTextItem>\n        </HelperText>\n      );\n    }\n  };\n\n  const successfullyReadFileCount = readFileData.filter((fileData) => fileData.loadResult === 'success').length;\n\n  return (\n    <>\n      <MultipleFileUpload\n        onFileDrop={handleFileDrop}\n        dropzoneProps={{\n          accept: {\n            'image/jpeg': ['.jpg', '.jpeg'],\n            'application/msword': ['.doc'],\n            'application/pdf': ['.pdf'],\n            'image/png': ['.png']\n          }\n        }}\n        isHorizontal={isHorizontal}\n      >\n        <MultipleFileUploadMain\n          titleIcon={<UploadIcon />}\n          titleText=\"Drag and drop files here\"\n          titleTextSeparator=\"or\"\n          infoText=\"Accepted file types: JPEG, Doc, PDF, PNG\"\n        />\n        {showStatus && (\n          <MultipleFileUploadStatus\n            statusToggleText={`${successfullyReadFileCount} of ${currentFiles.length} files uploaded`}\n            statusToggleIcon={statusIcon}\n            aria-label=\"Current uploads\"\n          >\n            {currentFiles.map((file, index) => (\n              <MultipleFileUploadStatusItem\n                file={file}\n                key={file.name}\n                onClearClick={() => removeFiles([file.name])}\n                onReadSuccess={handleReadSuccess}\n                onReadFail={handleReadFail}\n                progressHelperText={createHelperText(file, index)}\n                progressAriaDescribedBy={`multiple-file-upload-basic-example-help-text-${index}`}\n              />\n            ))}\n          </MultipleFileUploadStatus>\n        )}\n      </MultipleFileUpload>\n      <Checkbox\n        id=\"horizontal-checkbox\"\n        label=\"Show as horizontal\"\n        isChecked={isHorizontal}\n        onChange={() => setIsHorizontal(!isHorizontal)}\n      />\n      <Checkbox\n        id=\"upload-should-fail-checkbox\"\n        label=\"Demonstrate error reporting by forcing uploads to fail\"\n        isChecked={fileUploadShouldFail}\n        onChange={() => setFileUploadShouldFail(!fileUploadShouldFail)}\n      />\n    </>\n  );\n};\n","title":"Basic","lang":"ts","className":""}}>
+      
+      <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+        {`The below example demonstrates a typical application of file upload - multiple, with a few tweaks from that typical application to enhance the convenience of the example.`}
+      </p>
+      
+      <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+        {`The "Show as horizontal" checkbox can be used to easily toggle the `}
+        
+        <code {...{"className":"ws-code "}}>
+          {`isHorizontal`}
+        </code>
+        {` prop, showing our available styling variations.`}
+      </p>
+      
+      <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+        {`The "Demonstrate error reporting by forcing uploads to fail" checkbox shows how our `}
+        
+        <code {...{"className":"ws-code "}}>
+          {`progressHelperText`}
+        </code>
+        {` prop can be used to provide status messages to users, such as when a file fails to upload. While this checkbox is checked it will cause any file uploaded to automatically fail the file reading process, and helper text will be dynamically rendered which informs the user of that error.`}
+      </p>
+    </Example>
+};
+
+const Component = () => (
+  <React.Fragment>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`Multiple file upload is able to:`}
+    </p>
+    <ul {...{"className":"pf-v6-c-content--ul pf-m-editorial ws-ul "}}>
+      <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+        {`Accept one or more files via browse or drag-and-drop`}
+      </li>
+      <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+        {`Provide their data to you using file objects via the `}
+        <code {...{"className":"ws-code "}}>
+          {`onFileDrop`}
+        </code>
+        {` callback prop`}
+      </li>
+      <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+        {`Read files as dataURLs, calling provided callbacks as needed when files start/finish being read, as well as when the read succeeds or fails`}
+      </li>
+      <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+        {`Display (in real time) the upload progress/status of each file`}
+        <ul {...{"className":"pf-v6-c-content--ul pf-m-editorial ws-ul "}}>
+          <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+            {`Uploaded files are represented by the multiple file upload status item component, this component includes the aforementioned built-in file reading logic`}
+          </li>
+          <li {...{"className":"pf-v6-c-content--li pf-m-editorial ws-li "}}>
+            {`If you prefer to supply your own file reading logic and strictly use multiple file upload status item as a display component, the `}
+            <code {...{"className":"ws-code "}}>
+              {`customFileHandler`}
+            </code>
+            {`, `}
+            <code {...{"className":"ws-code "}}>
+              {`fileName`}
+            </code>
+            {`, `}
+            <code {...{"className":"ws-code "}}>
+              {`fileSize`}
+            </code>
+            {`, `}
+            <code {...{"className":"ws-code "}}>
+              {`progressValue`}
+            </code>
+            {`, and `}
+            <code {...{"className":"ws-code "}}>
+              {`progressVariant`}
+            </code>
+            {` props exist to allow you to do that`}
+          </li>
+        </ul>
+      </li>
+    </ul>
+    <AutoLinkHeader {...{"id":"restricting-file-size-and-type","headingLevel":"h2","className":"ws-title ws-h2"}}>
+      {`Restricting file size and type`}
+    </AutoLinkHeader>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`As with singular file upload, any `}
+      <PatternflyThemeLink {...{"to":"https://react-dropzone.js.org/#!/Dropzone","className":""}}>
+        {`props accepted by react-dropzone's Dropzone component`}
+      </PatternflyThemeLink>
+      {` can be passed as a dropzoneProps object in order to customize the behavior of the Dropzone, such as restricting the type of files allowed. The following examples will only accept the files they list as accepted. Note that file type determination is not reliable across platforms (see the note on react-dropzone's docs about the accept prop), so be sure to test the behavior of your file upload restriction on all browsers and operating systems targeted by your application.`}
+    </p>
+    <AutoLinkHeader {...{"id":"important-a-note-about-security","headingLevel":"h3","className":"ws-title ws-h3"}}>
+      {`IMPORTANT: A note about security`}
+    </AutoLinkHeader>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`Restricting file sizes and types in this way is for user convenience only, and it cannot prevent a malicious user from submitting anything to your server. As with any user input, your application should also validate, sanitize and/or reject restricted files on the server side.`}
+    </p>
+    <AutoLinkHeader {...{"id":"composable-structure","headingLevel":"h2","className":"ws-title ws-h2"}}>
+      {`Composable structure`}
+    </AutoLinkHeader>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`File upload - multiple is designed in a composable manner to make customization easier. The standard sub-component relationships are arranged as follows:`}
+    </p>
+    <Example {...{"code":"<MultipleFileUpload>\n  <MultipleFileUploadMain />\n  <MultipleFileUploadStatus>\n    <MultipleFileUploadStatusItem />\n  </MultipleFileUploadStatus>\n</MultipleFileUpload>","lang":"noLive","className":""}}>
+    </Example>
+    <AutoLinkHeader {...{"id":"examples","headingLevel":"h2","className":"ws-title ws-h2"}}>
+      {`Examples`}
+    </AutoLinkHeader>
+    {React.createElement(pageData.examples["Basic"])}
+    <AutoLinkHeader {...{"id":"types","headingLevel":"h2","className":"ws-title ws-h2"}}>
+      {`Types`}
+    </AutoLinkHeader>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`Multiple file upload uses the `}
+      <code {...{"className":"ws-code "}}>
+        {`DropzoneOptions`}
+      </code>
+      {` type from react-dropzone. It is comprised of additional props with their own types. For more information on using `}
+      <code {...{"className":"ws-code "}}>
+        {`DropzoneOptions`}
+      </code>
+      {` visit `}
+      <PatternflyThemeLink {...{"to":"https://react-dropzone.js.org/#src","className":""}}>
+        {`react-dropzone props and methods`}
+      </PatternflyThemeLink>
+      {`.`}
+    </p>
+    <p {...{"className":"pf-v6-c-content--p pf-m-editorial ws-p "}}>
+      {`Additionally, it calls the `}
+      <code {...{"className":"ws-code "}}>
+        {`onFileDrop`}
+      </code>
+      {` callback with an event of type `}
+      <code {...{"className":"ws-code "}}>
+        {`DropEvent`}
+      </code>
+      {`. `}
+      <code {...{"className":"ws-code "}}>
+        {`DropEvent`}
+      </code>
+      {` is a union comprised of the following types:`}
+    </p>
+    <Example {...{"code":"React.DragEvent<HTMLElement>\n | React.ChangeEvent<HTMLInputElement>\n | DragEvent\n | Event","lang":"noLive","className":""}}>
+    </Example>
+  </React.Fragment>
+);
+Component.displayName = 'ComponentsFileUploadMultipleFileUploadReactDocs';
+Component.pageData = pageData;
+
+export default Component;