Usage Guide

Overview

The @knide/fs-prober package has only two main exports:

• useProbingDropzone
• ProbingDropzone - Convenience wrapper component for the useProbingDropzone hook

The package also exports a number of utility functions for working with file system objects, which are described here.

useProbingDropzone

The useProbingDropzone hook extends the functionality of useDropzone hook.

Parameters

useProbingDropzone hook accepts an object as a parameter containing optional configuration for the hook. It accepts the same configuration as useDropzone hook, but with the following additional parameters:

Name	Type	Description
isFolderSelectionMode	boolean	If set to true, the hook will enable folder selection mode, allowing users to select folders instead of files.

Return Value

The useProbingDropzone hook returns an object containing the same properties as useDropzone hook, but with the following additional properties:

Name	Type	Description
hierarchyDetails	HierarchyDetailsVariant	An object containing details about the hierarchy of files and folders.
isLoading	boolean	This property is set to true when the hook is busy generating the hierarchy details.

The return type is ProbingDropzoneState

Example

import { useProbingDropzone } from "@knide/fs-prober"

const App = () => {
  // Optional configuration parameter to enable folder selection mode
  const [isFolderSelectionMode, setIsFolderSelectMode] = useState(false)

  const { acceptedFiles, getRootProps, getInputProps, isLoading, hierarchyDetails } =
    useProbingDropzone({ isFolderSelectionMode })

  return (
    <>
      <SelectionModeSwitch {...{isFolderSelectionMode, setIsFolderSelectMode}} /> 

      <section className={style.dropzoneRoot}>
        <div {...getRootProps({ className: style.dropzone })}>
          <input {...getInputProps()} />
          <p>
            Drag 'n' drop some files & folders here, or click to select {isFolderSelectionMode ? "a folder" : "files"}
          </p>
        </div>
      </section>
    </>
  )
}

Demo

tip

Open your Browser DevTools console tab to see the output.

Selection Modes for File Selection Window:

Folder Selection Mode

Drag 'n' drop some files & folders here, or click to select files

Files

Nothing to display

ProbingDropzone

The ProbingDropzone component extends the functionality of Dropzone component.

It is a convenience wrapper component for the useProbingDropzone hook.

Component Props

The ProbingDropzone component accepts the same props as Dropzone component, but with the following additional props:

Name	Type	Description
children	(props: ProbingDropzoneState) => React.ReactNode	A function that returns the content to be rendered inside the component.
onProbingDrop	(props: ProbingDropzoneState) => void	A function that is called when the hierarchy details are available.

Example

import { ProbingDropzone } from "@knide/fs-prober"

const App = () => {
  return (
    <ProbingDropzone
      onProbingDrop={({ acceptedFiles, hierarchyDetails }) => {
        // Do something with the accepted files and hierarchy details
        console.log("acceptedFiles:", acceptedFiles)
        console.log("hierarchyDetails:", hierarchyDetails)
      }}
    >
      {({ acceptedFiles, getRootProps, getInputProps, isLoading, hierarchyDetails }) => (
        <section className={style.dropzoneRoot}>
          <div {...getRootProps({ className: style.dropzone })}>
            <input {...getInputProps()} />
            <p>
              Drag 'n' drop some files & folders here, or click to select a folder
            </p>
          </div>
        </section>
        
        <OutputPreview isLoading={isLoading} acceptedFiles={acceptedFiles} hierarchyDetails={hierarchyDetails} />
      )}
    </ProbingDropzone>
  )
}

Demo

tip

Open your Browser DevTools console tab to see the output.

Selection Modes for File Selection Window:

Folder Selection Mode

Drag 'n' drop some files & folders here, or click to select files

Files

Nothing to display

Utility Functions

getHierarchyDetailsFromFiles

The getHierarchyDetailsFromFiles function takes an array of files and returns an HierarchyDetailsWithoutHandles object containing details about the hierarchy of files and folders.

Parameters

Name	Type	Description
files	readonly FileWithPath[]	An array of files. Each file must have a path property

Example

const { getRootProps, getInputProps } = useProbingDropzone({
  onDrop: (acceptedFiles) => {
    const hierarchyDetails = getHierarchyDetailsFromFiles(acceptedFiles)
    handleUpload(acceptedFiles, hierarchyDetails)
  },
  noDrag: true,
})

getFilesArrFromHierarchyFiles

The getFilesArrFromHierarchyFiles function takes an array of FileNode objects and returns an array of File objects.

Parameters

Name	Type	Description
hierarchyFiles	FileNode[]	An array of FileNode objects.

Example

const files = await getFilesArrFromHierarchyFiles(hierarchyDetails?.allFiles)

addFileProperties

The addFileProperties function accepts a file and an object containing key-value pairs, then attaches those key-value pairs to the file object. It includes built-in error handling for Safari, Chrome, and Firefox.

Parameters

Name	Type	Description
file	File	The file to modify
propertiesObject	Record<string, any>	An object containing key-value pairs to add to the file object

Example

const newFile = addFileProperties(file, {
  myCustomProperty: "myCustomValue",
})

Types

FileNode

The FileNode type represents a file in the generated hierarchy details.

Properties

Name	Type	Description
name	string	The name of the file.
nameId	string	A unique identifier for the file.
pathIds	string[]	An array of nameId strings, sequentially representing the parent folder IDs and the file ID.
kind	"file"	Always "file".
isBranch	false	Always false. Added for compatibility when using the react-accessible-treeview library.
path	string	The path to the file.
handle	FileSystemFileHandle | FileSystemFileEntry (optional)	The file entry or file handle for the file. - Only available when the file drop event contains a DataTransfer object. - By default, the package uses the File and Directory Entries API, which returns FileSystemFileEntry objects. - If you opt to use the WICG File System Access API, it will return FileSystemFileHandle objects.

FolderNode

The FolderNode type represents a folder in the generated hierarchy details.

Properties

Name	Type	Description
name	string	The name of the folder.
nameId	string	A unique identifier for the folder.
pathIds	string[]	An array of nameId strings, sequentially representing the parent folder IDs and the folder ID.
kind	"directory"	Always "directory".
isBranch	true	Always true. Added for compatibility when using the react-accessible-treeview library.
path	string	The path to the folder.
children	(FolderNode | TFileNode)[]	An array of FolderNode or FileNode objects representing the children of the folder.
handle	FileSystemDirectoryEntry | FileSystemDirectoryHandle (optional)	The directory entry or directory handle for the folder. - Only available when the file drop event contains a DataTransfer object. - By default, the package uses the File and Directory Entries API, which returns FileSystemDirectoryEntry objects. - If you opt to use the WICG File System Access API, it will return FileSystemDirectoryHandle objects.

HierarchyDetailsVariant

The HierarchyDetailsVariant type is used to represent the hierarchy of files and folders in a folder structure. Its is a union of HierarchyDetails and HierarchyDetailsWithoutHandles types.

• HierarchyDetails - This type may be returned when using useProbingDropzone or ProbingDropzone to get the hierarchy details from an file drop event.
• HierarchyDetailsWithoutHandles - This type is returned when using getHierarchyDetailsFromFiles to get the hierarchy details from an array of files.

HierarchyDetails

The HierarchyDetails type is an object containing details about the hierarchy of files and folders.

This may be returned when using useProbingDropzone or ProbingDropzone to get the hierarchy details. If the file drop event contains DataTransfer object, this type is returned. Else HierarchyDetailsWithoutHandles is returned.

Properties

Name	Type	Description
emptyFolders	FolderNode[]	An array of FolderNode objects where each object contains information about empty folders
allFolders	FolderNode[]	An array of FolderNode objects where each object contains information about all folders
allFiles	FileNode[]	An array of FileNode objects where each object contains information about all files
rootFolders	FolderNode[]	An array of FolderNode objects where each object contains information about root-level folders
rootFiles	FileNode[]	An array of FileNode objects where each object contains information about root-level files
nameMap	Map<string, string>	A map where the keys are file or folder ID and the values are their corresponding names
objectMap	Map<string, FolderNode | FileNode>	A map where each key represents a file or folder ID, and each value is a FolderNode or FileNode object containing detailed information about the respective file or folder.
rootHandles	(FileSystemEntry | FileSystemHandle)[]	An array of FileSystemEntry or FileSystemHandle instances representing the root-level files. - By default, the package uses the File and Directory Entries API, which returns FileSystemEntry objects. - If you opt to use the WICG File System Access API, it will return FileSystemHandle objects.

HierarchyDetailsWithoutHandles

The HierarchyDetailsWithoutHandles type is a subset of the HierarchyDetails type that does not include the rootHandles property. It is returned when using getHierarchyDetailsFromFiles to get the hierarchy details from an array of files.

It has the same properties as HierarchyDetails, except for rootHandles. None of the FileNode or FolderNode objects have a handle property.