@bspk/ui 1.1.33 → 1.2.0

package/src/components/Fab/Fab.tsx

@@ -1,17 +1,16 @@
-import { ElementType } from 'react';
+import { AriaAttributes, ElementType, isValidElement } from 'react';
 
-import { ElementProps } from '-';
 import { ButtonProps } from '-/components/Button';
-import { Tooltip } from '-/components/Tooltip';
-import { isValidIcon } from '-/utils/children';
-import { useErrorLogger } from '-/utils/errors';
+import { Tooltip, TooltipTriggerProps } from '-/components/Tooltip';
+import { ElementProps } from '-/types/common';
+
 import './fab.scss';
 
 export type FabVariant = 'neutral' | 'primary' | 'secondary';
 
 export type FabProps<As extends ElementType = 'button'> = Pick<
     ButtonProps<As>,
-    'as' | 'icon' | 'onClick' | 'showLabel' | 'toolTip'
+    'as' | 'icon' | 'iconOnly' | 'onClick' | 'toolTip'
 > &
     Required<Pick<ButtonProps<As>, 'label'>> & {
         /**
@@ -53,55 +52,66 @@ export type FabProps<As extends ElementType = 'button'> = Pick<
  *     }
  *
  * @name Fab
- * @phase DesignReview
+ * @phase UXReview
  */
-function Fab<As extends ElementType = 'button'>({
-    size = 'small',
-    variant = 'primary',
-    showLabel: showLabelProp = true,
-    as,
-    placement = 'bottom-right',
-    container = 'local',
-    label,
-    icon,
-    toolTip,
-    ...otherProps
-}: ElementProps<FabProps<As>, As>) {
-    // ignore showLabel=false if there is no icon
-    const hideLabel = showLabelProp === false && icon;
-
-    const { logError } = useErrorLogger();
-    logError(!!icon && !isValidIcon(icon), 'Button - The icon prop must be a valid icon element.');
+export function Fab<As extends ElementType = 'button'>(props: AriaAttributes & ElementProps<FabProps<As>, As>) {
+    const {
+        size = 'small',
+        variant = 'primary',
+        iconOnly: iconOnlyProp = false,
+        as: As = 'button',
+        placement = 'bottom-right',
+        container = 'local',
+        label,
+        icon,
+        toolTip,
+        ...otherProps
+    } = props;
 
-    const As: ElementType = as || 'button';
+    // ignore iconOnly=true if there is no icon
+    const iconOnly = iconOnlyProp === true && !!icon;
 
-    const button = (
+    const button = (triggerProps: TooltipTriggerProps) => (
         <As
             {...otherProps}
+            aria-describedby={triggerProps['aria-describedby'] || otherProps['aria-describedby']}
             aria-label={label}
             data-bspk="fab"
             data-container={container}
             data-placement={placement}
-            data-round={hideLabel || undefined}
+            data-round={iconOnly || undefined}
             data-size={size}
             data-variant={variant}
+            onFocus={(e) => {
+                triggerProps.onFocus?.();
+                otherProps.onFocus?.(e);
+            }}
+            onMouseLeave={(e) => {
+                triggerProps.onMouseLeave?.();
+                otherProps.onMouseLeave?.(e);
+            }}
+            onMouseOver={(e) => {
+                triggerProps.onMouseOver?.();
+                otherProps.onMouseOver?.(e);
+            }}
         >
-            {!!icon && <span data-fab-icon>{icon}</span>}
-            {!hideLabel && <span data-fab-label>{label}</span>}
+            {!!icon && isValidElement(icon) && (
+                <span aria-hidden={true} data-fab-icon>
+                    {icon}
+                </span>
+            )}
+            {!iconOnly && <span data-fab-label>{label}</span>}
         </As>
     );
 
-    return toolTip || hideLabel ? (
-        <Tooltip label={toolTip || label} placement="top">
-            {button}
-        </Tooltip>
-    ) : (
-        button
-    );
-}
-
-Fab.bspkName = 'Fab';
+    if (toolTip || iconOnly)
+        return (
+            <Tooltip label={toolTip || label} placement="top">
+                {button}
+            </Tooltip>
+        );
 
-export { Fab };
+    return button({});
+}
 
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Fab/fab.scss

@@ -11,7 +11,7 @@
     text-decoration: none;
     z-index: var(--z-index-fab);
     box-shadow: var(--drop-shadow-float);
-    border-radius: var(--radius-small);
+    border-radius: var(--radius-sm);
 
     &[data-container='page'] {
         position: fixed;
@@ -113,7 +113,7 @@
     }
 
     &[data-round] {
-        border-radius: var(--radius-circular);
+        border-radius: var(--radius-full);
         aspect-ratio: 1/1;
         padding: 0;
     }

package/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,285 @@
+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';
+
+import './file-upload.scss';
+
+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,91 @@
+import { useEffect, useState } from 'react';
+import { FileUpload, FileUploadProps } from '.';
+import { ComponentExampleFn } from '-/utils/demo';
+import { FileEntry } from '-/utils/fileUploads';
+import { randomNumber } from '-/utils/random';
+
+export const FileUploadExample: ComponentExampleFn<FileUploadProps> = ({ action }) => ({
+    render: ({ props, preset }) => {
+        return <FileUploadExampleMockUpload key={preset?.label} {...props} action={action} />;
+    },
+    presets: [
+        {
+            label: 'multiple files',
+            propState: {
+                dragAndDrop: false,
+                multipleFiles: true,
+            },
+        },
+        {
+            label: 'Drag and Drop Multiple Files',
+            propState: {
+                dragAndDrop: true,
+                multipleFiles: true,
+            },
+        },
+    ],
+    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.tsx

@@ -0,0 +1,121 @@
+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';
+
+import './file-upload-item.scss';
+
+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 */