@bspk/ui 1.1.34 → 1.3.0

package/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,284 @@
+import './file-upload.scss';
+import { SvgCloudUpload } from '@bspk/icons/CloudUpload';
+import { useRef, ChangeEvent, useState, useEffect } from 'react';
+import { Button } from '-/components/Button';
+import { FileUploadItem, FileUploadItemProps } from '-/components/FileUploadItem';
+import { InlineAlert } from '-/components/InlineAlert';
+import { Txt } from '-/components/Txt';
+import { DEFAULT_ERROR_MESSAGE, FileEntry, FileUploadStatus, MimeType } from '-/utils/fileUploads';
+import { randomString } from '-/utils/random';
+
+const MB = 1048576 as const;
+
+export type FileEntryUpload = FileEntry & { file: File };
+
+export type FileUploadProps = Pick<FileUploadItemProps, 'cancelButtonLabel' | 'onCancel'> & {
+    /**
+     * Whether to enable drag and drop functionality
+     *
+     * @default false
+     */
+    dragAndDrop?: boolean;
+    /**
+     * The subtitle for the upload area
+     *
+     * It is recommended to include the accepted file types and maximum file size in the subtitle.
+     */
+    uploadSubtitle?: string;
+    /**
+     * Whether to allow multiple file uploads
+     *
+     * @default false
+     */
+    multipleFiles?: boolean;
+    /**
+     * The accepted file types for upload, e.g. ['image/png', 'image/gif', 'image/svg+xml']
+     *
+     * If not provided, all file types are accepted.
+     *
+     * @type MimeType[]
+     */
+    acceptedFileTypes?: MimeType[];
+    /**
+     * The maximum file size allowed for upload in MB. If not provided, defaults to 2 MB.
+     *
+     * @default 2
+     */
+    maxFileSize?: number;
+    /**
+     * The files currently being uploaded. This is updated as files are being uploaded.
+     *
+     * If not provided, the component will not display any files upload items.
+     *
+     * @type FileEntry[]
+     */
+    files?: FileEntry[];
+    /**
+     * The function called when the upload starts
+     *
+     * @required
+     */
+    onUpload: (files: FileEntryUpload[]) => void;
+    /**
+     * The function called when an error occurs during upload
+     *
+     * @required
+     */
+    onError: (files: FileEntry[]) => void;
+};
+
+/**
+ * A widget that allows customers to upload and attach one or more files.
+ *
+ * @example
+ *     import { FileUpload } from '@bspk/ui/FileUpload';
+ *
+ *     function Example() {
+ *         const [files, setFiles] = useState([]);
+ *         return (
+ *             <FileUpload
+ *                 dragAndDrop
+ *                 multipleFiles
+ *                 acceptedFileTypes={['image/png', 'image/gif', 'image/svg+xml']}
+ *                 files={files}
+ *                 maxFileSize={5}
+ *                 onError={(errorFiles) => console.log('Upload error:', errorFiles)}
+ *                 onUpload={(uploadFiles) => setFiles(uploadFiles)}
+ *                 uploadSubtitle="SVG, PNG, JPG or GIF (max. 5MB)"
+ *             />
+ *         );
+ *     }
+ *
+ * @name FileUpload
+ * @phase UXReview
+ */
+export function FileUpload({
+    dragAndDrop = false,
+    multipleFiles = false,
+    uploadSubtitle,
+    maxFileSize = 2,
+    acceptedFileTypes = [],
+    files = [],
+    onUpload,
+    onError,
+    onCancel,
+    cancelButtonLabel = 'Cancel',
+}: FileUploadProps) {
+    const fileInputRef = useRef<HTMLInputElement>(null);
+    const maxFileSizeMB = maxFileSize * MB;
+    const [fileEntries, setFileEntries] = useState<FileEntry[]>(files || []);
+
+    useMergedFileEntries({ fileEntries, files, setFileEntries });
+
+    const handleBrowseClick = () => fileInputRef.current?.click();
+
+    const updateFiles = (nextFiles: File[]) => {
+        const nextFileEntries = nextFiles.map((file): FileEntryUpload => {
+            let status: FileUploadStatus = 'idle';
+            let errorMessage = '';
+
+            if (
+                Array.isArray(acceptedFileTypes) &&
+                acceptedFileTypes.length > 0 &&
+                !acceptedFileTypes.includes(file.type as MimeType)
+            ) {
+                status = 'error';
+                errorMessage = `File type not accepted: ${file.name}`;
+            }
+
+            if (file.size > maxFileSizeMB) {
+                status = 'error';
+                errorMessage = `File too large. Please upload a smaller file: ${file.name}`;
+            }
+
+            return {
+                id: randomString(8),
+                fileName: file.name,
+                status,
+                fileSize: file.size / MB,
+                progress: 0,
+                errorMessage,
+                file,
+            };
+        });
+
+        setFileEntries((prev) => [
+            ...prev,
+            ...nextFileEntries.map((entry) => ({
+                ...entry,
+                file: undefined, // Remove the file object to avoid saving large files in state
+            })),
+        ]);
+
+        const fileEntriesWithError = nextFileEntries.filter((entry) => entry.status === 'error');
+        if (fileEntriesWithError.length > 0) onError(fileEntriesWithError);
+
+        const fileEntriesToUpload = nextFileEntries.filter((entry) => entry.status === 'idle');
+        if (fileEntriesToUpload.length > 0) onUpload(fileEntriesToUpload);
+    };
+
+    // Automatically start upload when a file is selected
+    const handleFileChange = (e: ChangeEvent<HTMLInputElement>) => {
+        e.preventDefault();
+        updateFiles(Array.from(e.target.files ?? []));
+    };
+
+    // Add state for drag-over visual feedback
+    const [isDragOver, setIsDragOver] = useState(false);
+
+    const handleDrop = (e: React.DragEvent<HTMLDivElement>) => {
+        e.preventDefault();
+        setIsDragOver(false);
+
+        const droppedFiles = Array.from(e.dataTransfer.files ?? []);
+        updateFiles(droppedFiles);
+    };
+
+    const handleDrag = (action: 'leave' | 'over') => (e: React.DragEvent<HTMLDivElement>) => {
+        e.preventDefault();
+        setIsDragOver(action === 'over');
+    };
+
+    let title = 'Drag and Drop';
+    if (!dragAndDrop) title = multipleFiles ? 'Upload Files' : 'Upload a File';
+
+    return (
+        <>
+            <div
+                className={isDragOver ? 'drag-over' : ''}
+                data-bspk="file-upload"
+                onDragLeave={dragAndDrop ? handleDrag('leave') : undefined}
+                onDragOver={dragAndDrop ? handleDrag('over') : undefined}
+                onDrop={dragAndDrop ? handleDrop : undefined}
+            >
+                <SvgCloudUpload />
+                <Txt variant="body-large">{title}</Txt>
+                <Txt variant="body-small">{uploadSubtitle}</Txt>
+                <input
+                    accept={acceptedFileTypes?.join(', ')}
+                    hidden
+                    id="temp-id"
+                    multiple={multipleFiles}
+                    onChange={handleFileChange}
+                    ref={fileInputRef}
+                    type="file"
+                />
+                <Button label="Browse" onClick={handleBrowseClick} />
+                {files.length === 1 && files[0].status === 'error' && (
+                    <InlineAlert variant="error">{files[0].errorMessage || DEFAULT_ERROR_MESSAGE}</InlineAlert>
+                )}
+            </div>
+            <div data-bspk-owner="file-upload" data-file-entries>
+                {fileEntries
+                    .sort(
+                        // files with errors last
+                        (a, b) =>
+                            (a.status === 'error' ? 1 : -1) + (b.status === 'error' ? -1 : 1) ||
+                            // sort by file name
+                            a.fileName.localeCompare(b.fileName) ||
+                            0,
+                    )
+                    .map(({ errorMessage, status, fileName, fileSize, progress, id }) => (
+                        <FileUploadItem
+                            cancelButtonLabel={cancelButtonLabel}
+                            errorMessage={errorMessage}
+                            fileName={fileName}
+                            fileSize={fileSize}
+                            id={id}
+                            key={id}
+                            onCancel={() => onCancel({ fileName })}
+                            progress={progress}
+                            status={status}
+                        />
+                    ))}
+            </div>
+        </>
+    );
+}
+
+function useMergedFileEntries({
+    files,
+    setFileEntries,
+    fileEntries,
+}: {
+    files: FileEntry[];
+    setFileEntries: (entries: FileEntry[]) => void;
+    fileEntries: FileEntry[];
+}) {
+    useEffect(() => {
+        // merge new files with existing ones
+        const nextFileEntries: (FileEntry & { updated?: boolean })[] = [...fileEntries];
+
+        // first check if there are any changes to existing file entries
+        files.forEach((file) => {
+            const existingEntryIndex = fileEntries.findIndex((entry) => entry.id === file.id);
+
+            if (existingEntryIndex !== -1) {
+                const updated =
+                    fileEntries[existingEntryIndex].status !== file.status ||
+                    fileEntries[existingEntryIndex].progress !== file.progress ||
+                    fileEntries[existingEntryIndex].errorMessage !== file.errorMessage;
+
+                if (updated)
+                    nextFileEntries[existingEntryIndex] = {
+                        ...fileEntries[existingEntryIndex],
+                        status: file.status,
+                        progress: file.progress || 0,
+                        errorMessage: file.errorMessage,
+                        updated,
+                    };
+
+                return;
+            }
+
+            nextFileEntries.push({
+                ...file,
+                updated: true,
+            });
+        });
+
+        if (nextFileEntries.some((entry) => entry.updated)) setFileEntries(nextFileEntries);
+    }, [fileEntries, files, setFileEntries]);
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FileUpload/FileUploadExample.tsx

@@ -0,0 +1,93 @@
+import { useEffect, useState } from 'react';
+import { FileUpload, FileUploadProps } from '.';
+import { ComponentExampleFn, Preset } from '-/utils/demo';
+import { FileEntry } from '-/utils/fileUploads';
+import { randomNumber } from '-/utils/random';
+
+export const presets: Preset<FileUploadProps>[] = [
+    {
+        label: 'multiple files',
+        propState: {
+            dragAndDrop: false,
+            multipleFiles: true,
+        },
+    },
+    {
+        label: 'Drag and Drop Multiple Files',
+        propState: {
+            dragAndDrop: true,
+            multipleFiles: true,
+        },
+    },
+];
+
+export const FileUploadExample: ComponentExampleFn<FileUploadProps> = ({ action }) => ({
+    render: ({ props, preset }) => {
+        return <FileUploadExampleMockUpload key={preset?.label} {...props} action={action} />;
+    },
+    presets,
+    variants: false,
+});
+
+function FileUploadExampleMockUpload({
+    action,
+    files: presetFiles,
+    ...props
+}: FileUploadProps & { action: (message: string) => void }) {
+    const [files, setFiles] = useState<FileEntry[]>([]);
+
+    // Here we
+    const handleUpload = (nextFiles: FileEntry[]) => {
+        setFiles(nextFiles);
+        // mock the upload action by incrementally updating the progress and eventually setting the status to 'complete'
+
+        nextFiles.forEach((file, index) => {
+            setTimeout(() => {
+                const updatedFile: FileEntry = {
+                    ...file,
+                    status: 'uploading',
+                    progress: 0,
+                };
+                setFiles((prev) => prev.map((f) => (f.id === file.id ? updatedFile : f)));
+
+                // Simulate progress
+                const interval = setInterval(() => {
+                    updatedFile.progress = Math.min((updatedFile.progress || 0) + randomNumber(10, 15), 100);
+                    setFiles((prev) => prev.map((f) => (f.id === file.id ? { ...updatedFile } : f)));
+
+                    if (updatedFile.progress === 100) {
+                        clearInterval(interval);
+                        updatedFile.status = 'complete';
+                        setFiles((prev) => prev.map((f) => (f.id === file.id ? { ...updatedFile } : f)));
+                        action(`File upload complete: ${file.fileName}`);
+                    }
+                }, 350);
+            }, index * 400); // stagger uploads
+        });
+
+        action(`Files uploading: ${nextFiles.map((f) => f.fileName).join(', ')}`);
+    };
+
+    useEffect(() => {
+        if (Array.isArray(presetFiles) && presetFiles.length > 0) {
+            handleUpload(presetFiles);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [presetFiles]);
+
+    return (
+        <FileUpload
+            {...props}
+            acceptedFileTypes={['image/png', 'image/gif', 'image/svg+xml', 'image/jpeg']}
+            cancelButtonLabel="Cancel"
+            files={files.length > 0 ? files : undefined}
+            maxFileSize={1}
+            onCancel={(file) => action(`onCancel called for: ${file.fileName}`)}
+            onError={(filesWithErrors) => {
+                action(`Error occurred during file upload: ${filesWithErrors.map((f) => f.fileName).join(', ')}`);
+            }}
+            onUpload={handleUpload}
+            uploadSubtitle="SVG, PNG, JPG or GIF (max. 1MB)"
+        />
+    );
+}

package/src/components/FileUpload/file-upload.scss

@@ -0,0 +1,20 @@
+[data-bspk='file-upload'] {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    gap: var(--spacing-sizing-04);
+    width: 100%;
+    padding: var(--spacing-sizing-04);
+    border: 1px dashed var(--stroke-neutral-base);
+    border-radius: var(--spacing-sizing-02);
+    background-color: var(--surface-neutral-t2-lowest);
+}
+
+[data-bspk-owner='file-upload'][data-file-entries] {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FileUpload/index.tsx

@@ -0,0 +1 @@
+export * from './FileUpload';

package/src/components/FileUploadItem/FileUploadItem.rtl.test.tsx

@@ -0,0 +1,19 @@
+import { FileUploadItem } from './FileUploadItem';
+import { presets } from './FileUploadItemExample';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+describe('FileUploadItem (RTL)', () => {
+    presets.forEach((preset) => {
+        it(
+            `has no basic a11y issues - ${preset.label}`,
+            hasNoBasicA11yIssues(<FileUploadItem onCancel={() => {}} {...preset.propState} />),
+        );
+    });
+
+    it('renders', () => {
+        const { getByText } = render(<FileUploadItem onCancel={() => {}} {...presets[0].propState} />);
+
+        expect(getByText('Close')).toBeInTheDocument();
+    });
+});

package/src/components/FileUploadItem/FileUploadItem.tsx

@@ -0,0 +1,119 @@
+import './file-upload-item.scss';
+import { SvgDelete } from '@bspk/icons/Delete';
+import { SvgDraft } from '@bspk/icons/Draft';
+import { Button } from '-/components/Button';
+import { InlineAlert } from '-/components/InlineAlert';
+import { ProgressBar } from '-/components/ProgressBar';
+import { Truncated } from '-/components/Truncated';
+import { DEFAULT_ERROR_MESSAGE, FileEntry } from '-/utils/fileUploads';
+
+export type FileUploadItemProps = FileEntry & {
+    /**
+     * The function to call when the Cancel button is clicked.
+     *
+     * @required
+     */
+    onCancel: (file: Pick<FileEntry, 'fileName'>) => void;
+    /**
+     * The label used for tooltip text for the Cancel button.
+     *
+     * @default Cancel
+     */
+    cancelButtonLabel?: string;
+};
+
+/**
+ * A component that represents an uploaded item and its status.
+ *
+ * Usually used with FileUpload to display individual files being uploaded.
+ *
+ * @example
+ *     import { FileUploadItem } from '@bspk/ui/FileUploadItem';
+ *
+ *     function Example() {
+ *         return (
+ *             <FileUploadItem
+ *                 fileName="dunder-mifflin-paper-co.jpg"
+ *                 fileSize="1.43 mb"
+ *                 status="Uploading"
+ *                 onCancel={() => console.log('Cancel item clicked!')}
+ *             />
+ *         );
+ *     }
+ *
+ * @name FileUploadItem
+ * @phase UXReview
+ */
+export function FileUploadItem({
+    fileName = '',
+    status,
+    fileSize,
+    onCancel,
+    cancelButtonLabel: onCancelToolTip = 'Cancel',
+    progress = 0,
+    errorMessage = DEFAULT_ERROR_MESSAGE,
+}: FileUploadItemProps) {
+    const subText = [fileSizeFormat(fileSize), status].filter(Boolean).join(' • ');
+
+    return (
+        <div data-bspk="file-upload-item">
+            <div data-row>
+                <div data-icon>
+                    <SvgDraft />
+                </div>
+                <div data-info>
+                    <Truncated data-file-name>{fileName}</Truncated>
+                    <span data-file-details>{subText}</span>
+                </div>
+                <Button
+                    icon={<SvgDelete />}
+                    iconOnly
+                    label={onCancelToolTip || 'Cancel'}
+                    onClick={() => onCancel({ fileName })}
+                    size="large"
+                    variant="tertiary"
+                />
+            </div>
+            <div data-status>
+                {status === 'error' ? (
+                    <InlineAlert variant="error">{errorMessage}</InlineAlert>
+                ) : (
+                    <ProgressBar
+                        align="left"
+                        completion={progress}
+                        label={`${
+                            Math.max(0, Math.min(100, Math.round(progress))) // Ensure completion is between 0 and 100
+                        }%`}
+                    />
+                )}
+            </div>
+        </div>
+    );
+}
+
+const KB = 1024;
+const MB = 1024 * KB;
+const GB = 1024 * MB;
+
+/**
+ * This is a simple utility to format file sizes in a human-readable way
+ *
+ * Lets not support terrabytes or petabytes for now.
+ *
+ * - @param fileSize {number | null | undefined} - The size of the file in bytes.
+ * - @returns {string | null | undefined} A string representing the file size in a human-readable format or the original
+ *   value if it cannot be formatted.
+ */
+function fileSizeFormat(fileSize?: number): string | undefined {
+    if (!fileSize) return 'Unknown size';
+
+    const fileSizeMb = fileSize * MB; // Convert bytes to MB
+
+    const roundUp2 = (num: number) => Math.ceil(num * 100) / 100;
+
+    if (fileSizeMb < MB) return `${roundUp2(fileSizeMb / KB)} KB`;
+    if (fileSizeMb < GB) return `${roundUp2(fileSizeMb / MB)} MB`;
+    return `${roundUp2(fileSizeMb / GB)} GB`;
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FileUploadItem/FileUploadItemExample.tsx

@@ -0,0 +1,85 @@
+import { useState } from 'react';
+import { FileUploadItem } from './FileUploadItem';
+import { FileUploadItemProps } from '.';
+import { useTimeout } from '-/hooks/useTimeout';
+import { ComponentExampleFn, Preset } from '-/utils/demo';
+import { FileUploadStatus } from '-/utils/fileUploads';
+import { randomNumber } from '-/utils/random';
+
+export const presets: Preset<FileUploadItemProps>[] = [
+    {
+        label: 'long file name',
+        propState: {
+            fileName: 'I-think-this-is-a-long-file-name.txt',
+            status: 'uploading' as FileUploadStatus,
+            cancelButtonLabel: 'Close',
+            fileSize: 10,
+            id: '10',
+        },
+    },
+    {
+        label: 'state: uploading',
+        propState: {
+            fileName: 'basic-file.png',
+            status: 'uploading' as FileUploadStatus,
+            fileSize: 1.2,
+            cancelButtonLabel: 'Cancel',
+            id: '1.2',
+        },
+    },
+    {
+        label: 'state: success',
+        propState: {
+            fileName: 'success-story.pdf',
+            status: 'complete' as FileUploadStatus,
+            cancelButtonLabel: 'Bye',
+            fileSize: 42,
+            id: '42',
+        },
+    },
+    {
+        label: 'state: failed',
+        propState: {
+            fileName: 'file-name.txt',
+            status: 'error' as FileUploadStatus,
+            errorMessage: 'File too large. Please upload a smaller file.',
+            cancelButtonLabel: 'Escape',
+            fileSize: 10000000,
+            id: '10000000',
+        },
+    },
+];
+
+export const FileUploadItemExample: ComponentExampleFn<FileUploadItemProps> = ({ action }) => ({
+    render: ({ props, preset }) => {
+        let progress = props.progress;
+
+        if (preset?.label === 'state: success') progress = 100;
+
+        return (
+            <FileUploadItemExampleRender
+                key={preset?.label}
+                {...props}
+                onCancel={() => action('Cancel action clicked!')}
+                progress={progress}
+            />
+        );
+    },
+    presets,
+    variants: false,
+});
+
+function FileUploadItemExampleRender({ progress, ...props }: FileUploadItemProps) {
+    const [progressNum, setProgressNum] = useState(progress || 0);
+    const timeout = useTimeout();
+
+    const updateProgress = (previousProgress: number) => () => {
+        const next = Math.round(Math.min(previousProgress + randomNumber(0, 20), 100));
+        setProgressNum(next);
+        if (next < 100) timeout.set(updateProgress(next), 1000);
+    };
+
+    if (props.status === 'uploading') timeout.set(updateProgress(progressNum), 1000);
+
+    return <FileUploadItem {...props} progress={progressNum} />;
+}

package/src/components/FileUploadItem/file-upload-item.scss

@@ -0,0 +1,46 @@
+[data-bspk='file-upload-item'] {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+
+    [data-row] {
+        display: flex;
+        flex-direction: row;
+        width: 100%;
+        align-items: center;
+        padding: var(--spacing-sizing-02) var(--spacing-sizing-04);
+        gap: var(--spacing-sizing-04);
+    }
+
+    [data-icon] {
+        padding: var(--spacing-sizing-02);
+        width: fit-content;
+        display: flex;
+        flex: 0 0 auto;
+    }
+
+    [data-info] {
+        display: flex;
+        flex-direction: column;
+        flex: 1 1 0;
+        min-width: 0;
+    }
+
+    [data-file-name] {
+        width: 100%;
+        font: var(--body-small);
+    }
+
+    [data-file-details] {
+        color: var(--foreground-neutral-on-surface-variant-01);
+        font: var(--body-x-small);
+    }
+
+    @media (width >= 640px) {
+        [data-status] {
+            padding: 0 var(--spacing-sizing-18);
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/FileUploadItem/index.tsx

@@ -0,0 +1 @@
+export * from './FileUploadItem';