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

package/src/components/fileUpload/FileUpload.stories.tsx

@@ -0,0 +1,920 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+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 'Components/button/Button';
+import { FileUpload } from './FileUpload.js';
+import type { FileUploadProps } 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 (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ─── 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(),
+  },
+} satisfies Meta<typeof FileUpload>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ─── Helper ───────────────────────────────────────────────────────────────────
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+const noop = () => {};
+
+const completedFiles: FileUploadProps['uploadedFiles'] = [
+  {
+    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: Story = withDescription(
+  {
+    args: {
+      uploadedFiles: [],
+      uploadFiles: fn(),
+    },
+    render: args => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload {...args} />
+      </div>
+    ),
+  },
+  '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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload uploadedFiles={completedFiles} uploadFiles={noop} />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload
+          uploadedFiles={[{
+            fileName: 'spring-term-report-2024.pdf',
+            fileType: 'PDF',
+            fileSize: '1.2 MB',
+            onDownload: noop,
+            onDelete: noop,
+          }]}
+          uploadFiles={noop}
+        />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <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}
+        />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <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}
+        />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <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}
+        />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <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}
+        />
+      </div>
+    ),
+    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: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload
+          uploadedFiles={[]}
+          uploadFiles={noop}
+          dropzoneContent={(
+            <>
+              <p className="ds-text">
+                Attach a PDF or spreadsheet (max&nbsp;10&nbsp;MB per file)
+              </p>
+              <Button variant="secondary">Browse files</Button>
+            </>
+          )}
+        />
+      </div>
+    ),
+    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.',
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SimulatedUploadLifecycle — named template component required for useState
+// ─────────────────────────────────────────────────────────────────────────────
+
+type SimulatedFile = {
+  fileName: string;
+  fileType: string;
+  fileSize: string;
+  progressPercentage?: number;
+  hasUploadFailed?: boolean;
+};
+
+const DEMO_FILENAME = 'spring-term-report-2024.pdf';
+
+const SimulatedUploadLifecycleTemplate = () => {
+  const [files, setFiles] = useState<SimulatedFile[]>([]);
+  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: 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 (
+    <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)', 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={restart} disabled={files.length === 0 && !isRunning}>
+          Restart
+        </Button>
+      </div>
+      <FileUpload
+        uploadedFiles={files.map(f => ({
+          ...f,
+          onDelete: restart,
+          ...(typeof f.progressPercentage === 'number' && f.progressPercentage >= 100
+            ? { onDownload: noop }
+            : {}),
+        }))}
+        uploadFiles={startUpload}
+      />
+    </div>
+  );
+};
+
+export const SimulatedUploadLifecycle: Story = 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.',
+);