• 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 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 lint uploads-manager - runs 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

Per-locale i18n/*.js files are generated and committed by the Moji Jenkins pipeline. The shared-feature builder copies them into dist/i18n/ during build. Consuming applications list this package in i18n.config.js under translationDependencies.