@arbor-education/design-system.components 0.25.3 → 0.25.5

package/dist/components/fileUpload/FileUpload.stories.js

@@ -0,0 +1,736 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '../button/Button.js';
+import { FileUpload } from './FileUpload.js';
+// ─── Content strings ──────────────────────────────────────────────────────────
+const DESCRIPTION_INTRO = `
+The \`FileUpload\` component provides a drag-and-drop file upload area combined
+with a managed list of uploaded (or uploading) files. It is built on top of
+[react-dropzone](https://react-dropzone.js.org/) and handles the visual
+presentation of the upload state machine — idle dropzone, in-progress upload
+with a progress bar, upload failure, and completed file with download/delete
+actions.
+
+Use it wherever school staff need to attach documents to records: term reports,
+policy PDFs, student photographs, spreadsheet imports, and so on.
+`.trim();
+const USAGE_GUIDANCE = `
+### When to use
+
+- Uploading one or more files as part of a form flow (e.g. attaching a
+  behaviour letter to a student record).
+- Displaying the progress of an ongoing upload alongside files that have
+  already completed.
+- Giving staff a clear way to remove or re-download files they have attached.
+
+---
+
+### When NOT to use
+
+| Situation | Prefer instead |
+|-----------|---------------|
+| You need a plain \`<input type="file">\` without drag-and-drop | A \`FormField\` wrapping a native file input |
+| The user can only ever upload a single file and progress feedback is not needed | A simple \`<input type="file">\` or a \`Button\` that opens a file picker |
+| The upload is hidden from the user (background sync) | No UI component needed — handle it silently in a service layer |
+`.trim();
+const DEVELOPER_NOTES = `
+### Critical usage patterns
+
+The component is **not stateful by itself** — it is a controlled component. You
+are responsible for:
+
+1. Calling your upload API inside \`uploadFiles\` and pushing the new
+   file (with \`progressPercentage: 0\`) into your own state.
+2. Updating \`progressPercentage\` as the upload progresses (e.g. via an
+   \`XMLHttpRequest\` progress event or polling).
+3. Setting \`progressPercentage: 100\` (or removing the property) when the
+   upload completes — the progress bar is hidden automatically at 100.
+4. Setting \`hasUploadFailed: true\` if the upload errors — this replaces the
+   file-type/size metadata with a red "Upload failed" message and turns the
+   progress bar red.
+
+The progress bar is rendered **only** when \`progressPercentage\` is a number
+and is strictly less than 100. At exactly 100 the bar disappears.
+
+---
+
+### Accessibility
+
+The dropzone area is rendered by \`react-dropzone\` and is fully keyboard
+accessible: it receives focus, responds to \`Enter\` and \`Space\` to open the
+file picker, and announces itself to screen readers. The file list uses
+semantic \`<span>\` elements for layout; make sure the \`fileName\` values
+you pass are human-readable rather than GUIDs.
+
+---
+
+### TypeScript types
+
+The \`UploadedFile\` type is **not exported** from the component module. Until
+it is exported you can inline the shape or declare your own local type:
+
+\`\`\`tsx
+type UploadedFile = {
+  fileName: string;
+  icon?: string;          // any IconName from the design system Icon component
+  fileType: string;       // e.g. 'PDF', 'XLSX', 'DOCX'
+  fileSize: string;       // human-readable, e.g. '1.2 MB'
+  onDownload?: () => void;
+  onDelete: () => void;
+  progressPercentage?: number;  // 0–100; hidden at exactly 100
+  hasUploadFailed?: boolean;
+};
+\`\`\`
+`.trim();
+const RELATED_COMPONENTS = `
+## Related components
+
+- [Progress](?path=/docs/components-progress--docs) — the progress bar used
+  inside each file row to indicate upload completion.
+- [Button](?path=/docs/components-button--docs) — the "click to upload",
+  download, and delete buttons inside the component.
+- [Card](?path=/docs/components-card--docs) — the visual wrapper for both the
+  dropzone area and the file list.
+- [FormField](?path=/docs/components-formfield--docs) — use when you need a
+  labelled file input without drag-and-drop behaviour.
+- [Icon](?path=/docs/components-icon--docs) — all file-type and action icons
+  rendered inside the component.
+`.trim();
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+// ─── Docs page ────────────────────────────────────────────────────────────────
+function FileUploadDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+const meta = {
+    title: 'Components/FileUpload',
+    component: FileUpload,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            page: FileUploadDocsPage,
+        },
+    },
+    argTypes: {
+        uploadedFiles: {
+            description: 'Array of file objects to display in the file list. Each object describes '
+                + 'a file that has been selected, is uploading, has completed, or has failed. '
+                + 'See the **TypeScript types** section for the full shape.',
+            control: false,
+            table: {
+                type: { summary: 'UploadedFile[]' },
+            },
+        },
+        uploadFiles: {
+            description: 'Callback fired when the user drops files onto the dropzone or selects them '
+                + 'via the file picker. Receives the native `File[]` array. You are responsible '
+                + 'for starting the upload and adding the files to `uploadedFiles` state.',
+            control: false,
+            table: {
+                type: { summary: '(files: File[]) => void' },
+            },
+        },
+        dropzoneContent: {
+            description: 'Custom content rendered inside the dropzone area. Defaults to a '
+                + '"Drag and drop, or click to upload" paragraph. Pass a `ReactNode` to '
+                + 'replace this with your own copy or layout.',
+            control: false,
+            table: {
+                type: { summary: 'ReactNode' },
+                defaultValue: {
+                    summary: '<p>Drag and drop, or <Button variant="text-link">click to upload</Button></p>',
+                },
+            },
+        },
+        className: {
+            description: 'Additional CSS class name(s) applied to the root element.',
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+    },
+    args: {
+        uploadedFiles: [],
+        uploadFiles: fn(),
+    },
+};
+export default meta;
+// ─── Helper ───────────────────────────────────────────────────────────────────
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
+    },
+});
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+const noop = () => { };
+const completedFiles = [
+    {
+        fileName: 'spring-term-report-2024.pdf',
+        icon: 'file',
+        fileType: 'PDF',
+        fileSize: '1.2 MB',
+        onDownload: noop,
+        onDelete: noop,
+    },
+    {
+        fileName: 'attendance-summary-jan.xlsx',
+        icon: 'file',
+        fileType: 'XLSX',
+        fileSize: '348 KB',
+        onDownload: noop,
+        onDelete: noop,
+    },
+    {
+        fileName: 'behaviour-policy-2024.docx',
+        icon: 'file',
+        fileType: 'DOCX',
+        fileSize: '89 KB',
+        onDownload: noop,
+        onDelete: noop,
+    },
+];
+// ─── Stories ──────────────────────────────────────────────────────────────────
+export const Default = withDescription({
+    args: {
+        uploadedFiles: [],
+        uploadFiles: fn(),
+    },
+    render: args => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { ...args }) })),
+}, 'The default state shows the dropzone area with no files attached. '
+    + 'Drop files onto the area or click it to open the native file picker.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const WithUploadedFiles = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: completedFiles, uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+function UploadWithFilesExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove from state */ },
+        },
+        {
+          fileName: 'attendance-summary-jan.xlsx',
+          fileType: 'XLSX',
+          fileSize: '348 KB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove from state */ },
+        },
+        {
+          fileName: 'behaviour-policy-2024.docx',
+          fileType: 'DOCX',
+          fileSize: '89 KB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove from state */ },
+        },
+      ]}
+      uploadFiles={(files) => { /* start upload */ }}
+    />
+  );
+}
+export default UploadWithFilesExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Multiple completed files with both download and delete actions. '
+    + 'Each file shows its type and size. The download button only appears when '
+    + '`onDownload` is provided.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const SingleFile = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [{
+                    fileName: 'spring-term-report-2024.pdf',
+                    fileType: 'PDF',
+                    fileSize: '1.2 MB',
+                    onDownload: noop,
+                    onDelete: noop,
+                }], uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+function SingleFileExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove from state */ },
+        },
+      ]}
+      uploadFiles={(files) => { /* start upload */ }}
+    />
+  );
+}
+export default SingleFileExample;
+`.trim(),
+            },
+        },
+    },
+}, 'A single completed file. When there is only one file in the list the '
+    + '`Separator` between rows is not rendered.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const WithoutDownloadButton = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [
+                {
+                    fileName: 'spring-term-report-2024.pdf',
+                    fileType: 'PDF',
+                    fileSize: '1.2 MB',
+                    onDelete: noop,
+                },
+                {
+                    fileName: 'attendance-summary-jan.xlsx',
+                    fileType: 'XLSX',
+                    fileSize: '348 KB',
+                    onDelete: noop,
+                },
+            ], uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+function NoDownloadExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          // onDownload omitted — download button will not render
+          onDelete: () => { /* remove from state */ },
+        },
+        {
+          fileName: 'attendance-summary-jan.xlsx',
+          fileType: 'XLSX',
+          fileSize: '348 KB',
+          onDelete: () => { /* remove from state */ },
+        },
+      ]}
+      uploadFiles={(files) => { /* start upload */ }}
+    />
+  );
+}
+export default NoDownloadExample;
+`.trim(),
+            },
+        },
+    },
+}, 'When `onDownload` is omitted from a file object the download button is not '
+    + 'rendered for that row. Only the delete (trash) button appears. Use this when '
+    + 'the uploaded file should not be retrievable after submission.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const UploadInProgress = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [
+                {
+                    fileName: 'spring-term-report-2024.pdf',
+                    fileType: 'PDF',
+                    fileSize: '1.2 MB',
+                    onDelete: noop,
+                    progressPercentage: 25,
+                },
+                {
+                    fileName: 'attendance-summary-jan.xlsx',
+                    fileType: 'XLSX',
+                    fileSize: '348 KB',
+                    onDelete: noop,
+                    progressPercentage: 72,
+                },
+                {
+                    fileName: 'behaviour-policy-2024.docx',
+                    fileType: 'DOCX',
+                    fileSize: '89 KB',
+                    onDownload: noop,
+                    onDelete: noop,
+                },
+            ], uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+// progressPercentage < 100 shows the progress bar.
+// progressPercentage === 100 (or undefined) hides it.
+function UploadInProgressExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          onDelete: () => { /* cancel / remove */ },
+          progressPercentage: 25,
+        },
+        {
+          fileName: 'attendance-summary-jan.xlsx',
+          fileType: 'XLSX',
+          fileSize: '348 KB',
+          onDelete: () => { /* cancel / remove */ },
+          progressPercentage: 72,
+        },
+        {
+          fileName: 'behaviour-policy-2024.docx',
+          fileType: 'DOCX',
+          fileSize: '89 KB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove */ },
+          // No progressPercentage — this file finished earlier
+        },
+      ]}
+      uploadFiles={(files) => { /* start upload */ }}
+    />
+  );
+}
+export default UploadInProgressExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Multiple files at different stages of upload. A progress bar appears beneath '
+    + 'each row where `progressPercentage` is a number between 0 and 99 (inclusive). '
+    + 'The third file has no `progressPercentage` — it completed earlier and shows '
+    + 'only the download and delete actions.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const FailedUpload = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [
+                {
+                    fileName: 'corrupted-report.pdf',
+                    fileType: 'PDF',
+                    fileSize: '540 KB',
+                    onDelete: noop,
+                    hasUploadFailed: true,
+                },
+                {
+                    fileName: 'spring-term-report-2024.pdf',
+                    fileType: 'PDF',
+                    fileSize: '1.2 MB',
+                    onDownload: noop,
+                    onDelete: noop,
+                },
+            ], uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+function FailedUploadExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'corrupted-report.pdf',
+          fileType: 'PDF',
+          fileSize: '540 KB',
+          onDelete: () => { /* remove from state */ },
+          hasUploadFailed: true,
+        },
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          onDownload: () => { /* download logic */ },
+          onDelete: () => { /* remove from state */ },
+        },
+      ]}
+      uploadFiles={(files) => { /* retry or start new upload */ }}
+    />
+  );
+}
+export default FailedUploadExample;
+`.trim(),
+            },
+        },
+    },
+}, "When `hasUploadFailed` is `true` the file's type/size metadata is replaced "
+    + 'with a red "Upload failed" message. A completed file alongside the failed one '
+    + 'shows the contrast between the two states.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const FailedDuringUpload = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [
+                {
+                    fileName: 'oversized-photo.png',
+                    fileType: 'PNG',
+                    fileSize: '18 MB',
+                    onDelete: noop,
+                    hasUploadFailed: true,
+                    progressPercentage: 63,
+                },
+                {
+                    fileName: 'corrupted-report.pdf',
+                    fileType: 'PDF',
+                    fileSize: '540 KB',
+                    onDelete: noop,
+                    hasUploadFailed: true,
+                },
+            ], uploadFiles: noop }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload } from '@arbor-education/design-system.components';
+
+// Both hasUploadFailed: true AND progressPercentage < 100 renders
+// a red progress bar in addition to the "Upload failed" message.
+function FailedDuringUploadExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[
+        {
+          fileName: 'oversized-photo.png',
+          fileType: 'PNG',
+          fileSize: '18 MB',
+          onDelete: () => { /* remove from state */ },
+          hasUploadFailed: true,
+          progressPercentage: 63,
+        },
+        {
+          fileName: 'corrupted-report.pdf',
+          fileType: 'PDF',
+          fileSize: '540 KB',
+          onDelete: () => { /* remove from state */ },
+          hasUploadFailed: true,
+          // No progressPercentage — failed before any progress was recorded
+        },
+      ]}
+      uploadFiles={(files) => { /* start upload */ }}
+    />
+  );
+}
+export default FailedDuringUploadExample;
+`.trim(),
+            },
+        },
+    },
+}, 'When both `hasUploadFailed: true` **and** `progressPercentage < 100` are set '
+    + 'together the progress bar is rendered in its error (red) state below the '
+    + '"Upload failed" message. The first file shows this combined state; the second '
+    + 'failed before any progress was recorded so no bar appears.');
+// ─────────────────────────────────────────────────────────────────────────────
+export const CustomDropzoneContent = withDescription({
+    render: () => (_jsx("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)' }, children: _jsx(FileUpload, { uploadedFiles: [], uploadFiles: noop, dropzoneContent: (_jsxs(_Fragment, { children: [_jsx("p", { className: "ds-text", children: "Attach a PDF or spreadsheet (max\u00A010\u00A0MB per file)" }), _jsx(Button, { variant: "secondary", children: "Browse files" })] })) }) })),
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FileUpload, Button } from '@arbor-education/design-system.components';
+
+function CustomDropzoneExample() {
+  return (
+    <FileUpload
+      uploadedFiles={[]}
+      uploadFiles={(files) => { /* start upload */ }}
+      dropzoneContent={
+        <>
+          <p>Attach a PDF or spreadsheet (max 10 MB per file)</p>
+          <Button variant="secondary">Browse files</Button>
+        </>
+      }
+    />
+  );
+}
+export default CustomDropzoneExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Pass a `ReactNode` to `dropzoneContent` to replace the default '
+    + '"Drag and drop, or click to upload" copy. This is useful when you need '
+    + 'context-specific instructions or a branded call-to-action button.');
+const DEMO_FILENAME = 'spring-term-report-2024.pdf';
+const SimulatedUploadLifecycleTemplate = () => {
+    const [files, setFiles] = useState([]);
+    const [isRunning, setIsRunning] = useState(false);
+    const intervalRef = useRef(null);
+    const clearTimer = () => {
+        if (intervalRef.current !== null) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+        }
+    };
+    const startUpload = () => {
+        clearTimer();
+        setIsRunning(true);
+        setFiles([{ fileName: DEMO_FILENAME, fileType: 'PDF', fileSize: '1.2 MB', progressPercentage: 0 }]);
+    };
+    const restart = () => {
+        clearTimer();
+        setIsRunning(false);
+        setFiles([]);
+    };
+    useEffect(() => {
+        if (!isRunning) {
+            return;
+        }
+        intervalRef.current = setInterval(() => {
+            setFiles((prev) => {
+                const current = prev[0];
+                if (!current || typeof current.progressPercentage !== 'number') {
+                    return prev;
+                }
+                const next = current.progressPercentage + 8;
+                if (next >= 100) {
+                    clearTimer();
+                    setIsRunning(false);
+                    return [{ ...current, progressPercentage: 100 }];
+                }
+                return [{ ...current, progressPercentage: next }];
+            });
+        }, 250);
+        return () => {
+            clearTimer();
+        };
+    }, [isRunning]);
+    return (_jsxs("div", { style: { maxWidth: '560px', padding: 'var(--spacing-large)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsxs("div", { style: { display: 'flex', gap: 'var(--spacing-medium)' }, children: [_jsx(Button, { variant: "primary", onClick: startUpload, disabled: isRunning, children: "Simulate upload" }), _jsx(Button, { variant: "secondary", onClick: restart, disabled: files.length === 0 && !isRunning, children: "Restart" })] }), _jsx(FileUpload, { uploadedFiles: files.map(f => ({
+                    ...f,
+                    onDelete: restart,
+                    ...(typeof f.progressPercentage === 'number' && f.progressPercentage >= 100
+                        ? { onDownload: noop }
+                        : {}),
+                })), uploadFiles: startUpload })] }));
+};
+export const SimulatedUploadLifecycle = withDescription({
+    render: SimulatedUploadLifecycleTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState, useEffect, useRef } from 'react';
+import { FileUpload, Button } from '@arbor-education/design-system.components';
+
+type ManagedFile = {
+  fileName: string;
+  fileType: string;
+  fileSize: string;
+  progressPercentage?: number;
+};
+
+function UploadLifecycleDemo() {
+  const [files, setFiles] = useState<ManagedFile[]>([]);
+  const [isRunning, setIsRunning] = useState(false);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const clearTimer = () => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+  };
+
+  const startUpload = () => {
+    clearTimer();
+    setIsRunning(true);
+    setFiles([{
+      fileName: 'spring-term-report-2024.pdf',
+      fileType: 'PDF',
+      fileSize: '1.2 MB',
+      progressPercentage: 0,
+    }]);
+  };
+
+  useEffect(() => {
+    if (!isRunning) return;
+
+    intervalRef.current = setInterval(() => {
+      setFiles((prev) => {
+        const current = prev[0];
+        if (!current || typeof current.progressPercentage !== 'number') return prev;
+
+        const next = current.progressPercentage + 8;
+        if (next >= 100) {
+          clearTimer();
+          setIsRunning(false);
+          return [{ ...current, progressPercentage: 100 }];
+        }
+        return [{ ...current, progressPercentage: next }];
+      });
+    }, 250);
+
+    return () => {
+      clearTimer();
+    };
+  }, [isRunning]);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', gap: 'var(--spacing-medium)' }}>
+        <Button variant="primary" onClick={startUpload} disabled={isRunning}>
+          Simulate upload
+        </Button>
+        <Button
+          variant="secondary"
+          onClick={() => { clearTimer(); setIsRunning(false); setFiles([]); }}
+          disabled={files.length === 0 && !isRunning}
+        >
+          Restart
+        </Button>
+      </div>
+      <FileUpload
+        uploadedFiles={files.map((f) => ({
+          ...f,
+          onDelete: () => { clearTimer(); setIsRunning(false); setFiles([]); },
+          ...(typeof f.progressPercentage === 'number' && f.progressPercentage >= 100
+            ? { onDownload: () => { /* download */ } }
+            : {}),
+        }))}
+        uploadFiles={startUpload}
+      />
+    </div>
+  );
+}
+export default UploadLifecycleDemo;
+`.trim(),
+            },
+        },
+    },
+}, 'An interactive demo of the full upload lifecycle. Click **"Simulate upload"** '
+    + '(or drop a real file) to watch a file enter the list at 0%, tick up through '
+    + 'the progress bar, and complete at 100% — at which point the bar disappears '
+    + 'and the download button becomes available. Click **"Restart"** to reset and '
+    + 'run the demo again.');
+//# sourceMappingURL=FileUpload.stories.js.map