• uploads-manager
  • API Overview
  • Types
    • UploadItemStatus
    • UploadItem
    • UploadsManagerProps
  • Usage
  • Running commands
  • Available commands
  • Ownership
  • Translations

uploads-manager

Displays upload progress for files and folders with a collapsible panel, per-item actions, and bulk operations. The component derives header state (overall progress, status text, counts) from the items array internally.

API Overview

The consuming app passes an items: UploadItem[] array and action callbacks. No data fetching, no external context dependencies (except IntlProvider).

<UploadsManager
    isExpanded={isExpanded}
    onToggle={() => setIsExpanded(prev => !prev)}
    items={items}
    onCancelAll={handleCancelAll}
    onRetryAll={handleRetryAll}
    onItemCancel={handleItemCancel}
    onItemRetry={handleItemRetry}
    onItemRemove={handleItemRemove}
    onItemOpen={handleItemOpen}
    onItemShare={handleItemShare}
/>

Types

UploadItemStatus

type UploadItemStatus = 'pending' | 'uploading' | 'staged' | 'complete' | 'error' | 'canceled';

UploadItem

| Prop | Type | Required | Description | | --------------- | ------------------ | -------- | -------------------------------------------------------------- | | id | string | Yes | Unique identifier for this upload | | name | string | Yes | Display name of the file or folder | | extension | string | Yes | File extension for the file-type icon | | progress | number | Yes | Upload progress percentage (0–100) | | status | UploadItemStatus | Yes | Current status | | isFolder | boolean | No | Whether this item is a folder (default: false) | | errorMessage | string | No | Error message to display when status is 'error' | | versionNumber | string | No | Version label for completed uploads (e.g. "V2") | | isRetryable | boolean | No | Whether retry is available for errored items (default: true) |

UploadsManagerProps

| Prop | Type | Required | Description | | -------------- | -------------------------- | -------- | --------------------------------------------- | | isExpanded | boolean | Yes | Whether the panel is expanded | | onToggle | () => void | Yes | Toggle expand/collapse | | items | UploadItem[] | Yes | Upload items to display | | onCancelAll | () => void | No | Cancel all pending/in-progress uploads | | onRetryAll | () => void | No | Retry all errored items (labeled "Retry All") | | onItemCancel | (itemId: string) => void | No | Cancel a single item | | onItemRetry | (itemId: string) => void | No | Retry a single item (labeled "Retry") | | onItemRemove | (itemId: string) => void | No | Remove a completed/errored/canceled item | | onItemOpen | (itemId: string) => void | No | Open file preview for a completed item | | onItemShare | (itemId: string) => void | No | Share a completed item via link |

Usage

import { UploadsManager } from '@box/uploads-manager';
import type { UploadItem } from '@box/uploads-manager';

const items: UploadItem[] = [
    { id: '1', name: 'report.pdf', extension: 'pdf', progress: 100, status: 'complete' },
    { id: '2', name: 'photo.png', extension: 'png', progress: 45, status: 'uploading' },
    {
        id: '3',
        name: 'data.csv',
        extension: 'csv',
        progress: 0,
        status: 'error',
        errorMessage: 'Upload failed',
        isRetryable: true,
    },
];

function App() {
    const [isExpanded, setIsExpanded] = useState(true);

    return (
        <UploadsManager
            isExpanded={isExpanded}
            onToggle={() => setIsExpanded(prev => !prev)}
            items={items}
            onCancelAll={() => {
                /* cancel pending + in-progress uploads */
            }}
            onRetryAll={() => {
                /* retry all errored items */
            }}
            onItemCancel={id => {
                /* cancel single item */
            }}
            onItemRetry={id => {
                /* retry single item */
            }}
            onItemRemove={id => {
                /* remove item from list */
            }}
        />
    );
}

Running commands

Your terminal should stay in location of root directory of repository, which is frontend-mono. That Allows Nx to run action against your project, or multiple project if that is necessary. Do not navigate to packages/group-shared-features/uploads-manager to run commands.

Commands for the project are run using syntax used by Nx:

Syntax: yarn nx <target name> <project name> <option overrides>
                      |              |                |
Example: yarn nx    test         products         --watch

Available commands

All commands used with Nx can be found in project.json file within your package.

• nx storybook uploads-manager - launches development environment for UI component.
• nx build-storybook uploads-manager - build static version of storybook with all stories.
• nx build uploads-manager - build package using shared-feature-builder executor from automation package.
• nx build uploads-manager --watch - build package with --watch flag enabled, which rebuilds dist content based on changes in src
• nx build-locales uploads-manager - generate i18n/*.js and i18n/*.properties files out of i18n/json/*.json files to be imported by react-intl.
• nx lint uploads-manager - run linter over package files,
• nx test uploads-manager - runs storybook tests (visual/interactions) and jest unit tests, producing coverage report at the end.
• nx test-storybook uploads-manager - runs storybook tests. You need first to start storybook in separate terminal for this to work.
• nx test-storybook-local-coverage uploads-manager - runs storybook tests, and produces coverage report at the end. Requires running instance of storybook.
• nx test-storybook-ci uploads-manager - build storybook and run storybook tests with coverage output. Designed for CI usage.
• nx test-jest uploads-manager - runs jest unit tests, producing code coverage at the end.
• nx sonar uploads-manager - performs static analysis of code using SonarQube tooling, to detect bugs and code smells. Integrated as one of the steps in CI process.
• nx chromatic uploads-manager - uploads storybook build for review to box chromatic , and performs visual comparison of the UI changes against baseline.
• nx prepare uploads-manager - command run during the package publication process orchestrated by Nx Release.

Ownership

Code of the feature belongs to home-web. Responsibilities of owning team include control over code quality, providing guidelines for changes, and alignment with other teams regarding changes. It would be a good practice to consult which team, owning or requesting, will be responsible for implementing changes to code.

Translations

For translations this package will be leveraging @box/frontend as it has the required scripts to do translations the Box way, for more information on this checkout their i18n docs.

The i18n/ dir is bundled with this package to enable the consuming app to use the translations included in this component it need to adjust it's TranslationsPlugin, see EUA's webpack.base.config.js and i18n.config.js for reference.