feat: Add folder upload support to dcc.Upload component

[LeticiaBN]

🗂️ Add Folder Upload Support to dcc.Upload Component

This PR adds folder upload capability to the dcc.Upload component, addressing issue #3464. Users can now select and upload entire folders (including nested subfolders) via both click-to-select and drag-and-drop methods, significantly reducing user effort when uploading multiple files from various directories.

✨ Key Features

• New useFsAccessApi prop enables folder selection in addition to files
• Click-to-select folder support using webkitdirectory HTML attribute
• Drag-and-drop folder support using FileSystem API (webkitGetAsEntry())
• Recursive folder traversal automatically extracts all files from nested directories
• Preserved folder hierarchy in filenames (e.g., folder/subfolder/file.txt)
• Full backward compatibility - default behavior unchanged (useFsAccessApi=False)
• Graceful degradation in browsers without folder support
• Same output API as multiple file uploads
• Comprehensive integration tests added

🌐 Browser Support

Browser	Click-to-Select	Drag-and-Drop
Chrome 86+	✅	✅
Edge 86+	✅	✅
Opera 72+	✅	✅
Safari	⚠️ Files only	⚠️ Files only
Firefox	⚠️ Files only	⚠️ Files only

Browsers without support automatically fall back to file-only mode

📝 Example Usage

import dash
from dash import dcc, html, Input, Output

app = dash.Dash(__name__)

app.layout = html.Div([
    dcc.Upload(
        id='upload-folder',
        children=html.Div(['Drag and Drop or Select Folder']),
        multiple=True,
        useFsAccessApi=True  # ⭐ Enable folder upload
    ),
    html.Div(id='output')
])

@app.callback(
    Output('output', 'children'),
    Input('upload-folder', 'contents'),
    Input('upload-folder', 'filename')
)
def display_files(contents, filenames):
    if filenames:
        return html.Ul([html.Li(f) for f in filenames])
    return "No files uploaded"

if __name__ == '__main__':
    app.run_server(debug=True)

🔧 Implementation Details

React Components:

• Added useFsAccessApi PropType with documentation
• Implemented traverseFileTree() for recursive folder traversal
• Added custom getDataTransferItems() handler for drag-and-drop
• Applied webkitdirectory attribute for file picker

Python Wrapper:

• Added useFsAccessApi parameter to dcc.Upload
• Updated docstring with feature documentation

Testing:

• Added integration tests for folder upload functionality
• Tests verify prop existence, rendering, and compatibility with multiple prop

Technical Note:
This implementation uses webkitdirectory (HTML attribute) and webkitGetAsEntry() (FileSystem API) instead of the newer File System Access API for the following reasons:

• Compatibility with react-dropzone v4.1.2: The current Dash codebase uses react-dropzone v4.1.2, which predates the File System Access API and doesn't have built-in support for it.

• Future upgrade path: If Dash upgrades to a newer version of react-dropzone (v14+), migrating to the full File System Access API would be straightforward, as the prop name (useFsAccessApi) already hints at this capability.

Contributor Checklist

• I have broken down my PR scope into the following TODO tasks
  • Add useFsAccessApi prop to React component
  • Implement click-to-select folder support with webkitdirectory
  • Implement drag-and-drop folder support with FileSystem API
  • Add recursive folder traversal logic
  • Update Python wrapper with new prop
  • Add integration tests
  • Update documentation
• I have run the tests locally and they passed

Optionals

• I have added entry in the CHANGELOG.md

---

Closes #3464

[gvwilson]

@T4rk1n @KoolADE85 what do you think?

[KoolADE85]

Hey @LeticiaBN, thanks for submitting this PR! I think this a great feature to add to the component. I have a couple of thoughts on the approach:

• Instead of adding a new useFsAccessApi prop, I think this could be a drop-in replacement/improvement for the existing multiple prop. So, any upload with multiple=True would automatically use this new code.
• The implementation does not respect the accept prop, but I think it should. So that users can drop a folder and only the accepted file types within that folder would be transferred.
• One of the submitted tests fails for me locally: test_upfd002_folder_upload_with_multiple_files. Is it also failing on your end?