@arbor-education/design-system.components 4.7.0-alpha.0 → 4.7.1

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

@@ -12,6 +12,7 @@ import { fn } from 'storybook/test';
 import { useEffect, useRef, useState } from 'react';
 import { Button } from 'Components/button/Button';
 import { FileUpload } from './FileUpload.js';
+import type { FileUploadLink } from './FileUpload.js';
 import type { FileUploadProps } from './FileUpload.js';
 
 // ─── Content strings ──────────────────────────────────────────────────────────
@@ -88,8 +89,12 @@ it is exported you can inline the shape or declare your own local type:
 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'
+  fileType?: string;      // e.g. 'PDF', 'XLSX', 'DOCX'
+  fileSize?: string;      // human-readable, e.g. '1.2 MB'
+  href?: string;          // renders the row as a link; fileName becomes the link name
+  linkProps?: object;     // extra anchor attributes (target/rel default to new tab, noopener)
+  renderLink?: (args: WidgetRenderLinkArgs) => ReactElement; // e.g. router links
+  onEdit?: (link: { url: string; name: string }) => void;   // link rows only
   onDownload?: () => void;
   onDelete: () => void;
   progressPercentage?: number;  // 0–100; hidden at exactly 100
@@ -103,7 +108,7 @@ const 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",
+- [Button](?path=/docs/components-button--docs) — the "Browse files",
   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.
@@ -174,13 +179,13 @@ const meta = {
     dropzoneContent: {
       description:
         'Custom content rendered inside the dropzone area. Defaults to a '
-        + '"Drag and drop, or click to upload" paragraph. Pass a `ReactNode` to '
+        + '"Drag and drop, add a link or" paragraph with a "Browse files" button. 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>',
+          summary: '<p>Drag and drop, add a link or</p> + <Button variant="secondary">Browse files</Button>',
         },
       },
     },
@@ -325,6 +330,69 @@ export default UploadWithFilesExample;
 
 // ─────────────────────────────────────────────────────────────────────────────
 
+export const WithLinks: Story = withDescription(
+  {
+    render: () => {
+      const [links, setLinks] = useState<FileUploadLink[]>([
+        { name: 'Pastoral policy', url: 'https://example.com/pastoral-policy' },
+      ]);
+      return (
+        <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+          <FileUpload
+            uploadFiles={noop}
+            onAddLink={link => setLinks(previous => [...previous, link])}
+            uploadedFiles={[
+              {
+                fileName: 'spring-term-report-2024.pdf',
+                fileType: 'PDF',
+                fileSize: '1.2 MB',
+                onDownload: noop,
+                onDelete: noop,
+              },
+              ...links.map((link, index) => ({
+                fileName: link.name,
+                href: link.url,
+                onEdit: (updated: FileUploadLink) =>
+                  setLinks(previous => previous.map((item, i) => (i === index ? updated : item))),
+                onDelete: () => setLinks(previous => previous.filter((_, i) => i !== index)),
+              })),
+            ]}
+          />
+        </div>
+      );
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+<FileUpload
+  uploadFiles={(files) => { /* start upload */ }}
+  onAddLink={({ url, name }) => { /* save the new link */ }}
+  uploadedFiles={[
+    { fileName: 'report.pdf', fileType: 'PDF', fileSize: '1.2 MB', onDelete: () => {} },
+    {
+      fileName: 'Pastoral policy',
+      href: 'https://example.com/pastoral-policy',
+      onEdit: ({ url, name }) => { /* save the edited link */ },
+      onDelete: () => {},
+    },
+  ]}
+/>
+`.trim(),
+        },
+      },
+    },
+  },
+  'A mixed list of file rows and link rows. Passing `onAddLink` turns "add a link" into '
+  + 'a trigger for a modal form (name and URL). A row with `href` renders as a link that '
+  + 'opens in a new tab, with copy and delete actions; adding `onEdit` shows an edit action '
+  + 'that opens the same modal pre-filled.',
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 export const SingleFile: Story = withDescription(
   {
     render: () => (
@@ -721,7 +789,7 @@ export default CustomDropzoneExample;
     },
   },
   'Pass a `ReactNode` to `dropzoneContent` to replace the default '
-  + '"Drag and drop, or click to upload" copy. This is useful when you need '
+  + 'default "Drag and drop" copy. This is useful when you need '
   + 'context-specific instructions or a branded call-to-action button.',
 );
 

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

@@ -15,7 +15,13 @@ describe('FileUpload', () => {
   describe('dropzone', () => {
     test('renders default dropzone content', () => {
       render(<FileUpload uploadedFiles={[]} uploadFiles={vi.fn()} />);
-      expect(screen.getByText('click to upload')).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Browse files' })).toBeInTheDocument();
+      expect(screen.getByText('Drag and drop or')).toBeInTheDocument();
+    });
+
+    test('does not render the add a link trigger without onAddLink', () => {
+      render(<FileUpload uploadedFiles={[]} uploadFiles={vi.fn()} />);
+      expect(screen.queryByRole('button', { name: 'add a link' })).not.toBeInTheDocument();
     });
 
     test('renders custom dropzoneContent', () => {
@@ -169,4 +175,136 @@ describe('FileUpload', () => {
       expect(container.firstChild).toHaveClass('ds-file-upload', 'my-custom-class');
     });
   });
+  describe('link rows', () => {
+    const linkRow = {
+      fileName: 'Pastoral policy',
+      href: 'https://example.com/policy',
+      onDelete: vi.fn(),
+    };
+
+    test('renders a link row as an anchor opening in a new tab', () => {
+      render(<FileUpload uploadedFiles={[linkRow]} uploadFiles={vi.fn()} />);
+      const anchor = screen.getByRole('link', { name: 'Pastoral policy' });
+      expect(anchor).toHaveAttribute('href', 'https://example.com/policy');
+      expect(anchor).toHaveAttribute('target', '_blank');
+      expect(anchor).toHaveAttribute('rel', 'noopener noreferrer');
+      expect(screen.getByText('https://example.com/policy')).toBeInTheDocument();
+    });
+
+    test('merges linkProps onto the anchor', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{ ...linkRow, linkProps: { target: '_self' } }]}
+          uploadFiles={vi.fn()}
+        />,
+      );
+      expect(screen.getByRole('link', { name: 'Pastoral policy' })).toHaveAttribute('target', '_self');
+    });
+
+    test('uses renderLink when provided', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{
+            ...linkRow,
+            renderLink: ({ href, className, children }) => (
+              <a href={href} className={className} data-custom="true">{children}</a>
+            ),
+          }]}
+          uploadFiles={vi.fn()}
+        />,
+      );
+      expect(screen.getByRole('link', { name: 'Pastoral policy' })).toHaveAttribute('data-custom', 'true');
+    });
+
+    test('does not render a link for rows without href', () => {
+      render(<FileUpload uploadedFiles={[baseFile]} uploadFiles={vi.fn()} />);
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: 'Edit link' })).not.toBeInTheDocument();
+    });
+
+    test('calls onDelete without triggering other actions', async () => {
+      const onDelete = vi.fn();
+      const onEdit = vi.fn();
+      render(
+        <FileUpload uploadedFiles={[{ ...linkRow, onDelete, onEdit }]} uploadFiles={vi.fn()} />,
+      );
+      await userEvent.click(screen.getByRole('button', { name: 'Delete link' }));
+      expect(onDelete).toHaveBeenCalledOnce();
+      expect(onEdit).not.toHaveBeenCalled();
+    });
+
+    test('copies the link to the clipboard', async () => {
+      const user = userEvent.setup();
+      render(<FileUpload uploadedFiles={[linkRow]} uploadFiles={vi.fn()} />);
+      await user.click(screen.getByRole('button', { name: 'Copy link' }));
+      expect(await navigator.clipboard.readText()).toBe('https://example.com/policy');
+    });
+  });
+
+  describe('adding a link', () => {
+    test('opens the form from the add a link trigger and submits trimmed values', async () => {
+      const onAddLink = vi.fn();
+      const uploadFiles = vi.fn();
+      render(<FileUpload uploadedFiles={[]} uploadFiles={uploadFiles} onAddLink={onAddLink} />);
+
+      await userEvent.click(screen.getByRole('button', { name: 'add a link' }));
+      expect(screen.getByRole('dialog', { name: 'Add URL attachment' })).toBeInTheDocument();
+      await userEvent.type(screen.getByLabelText('Name of link'), '  Policy ');
+      await userEvent.type(screen.getByLabelText('Paste your link URL here'), ' https://example.com ');
+      await userEvent.click(screen.getByRole('button', { name: 'Add' }));
+
+      expect(onAddLink).toHaveBeenCalledWith({ name: 'Policy', url: 'https://example.com' });
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+
+    test('shows validation errors and does not submit invalid values', async () => {
+      const onAddLink = vi.fn();
+      render(<FileUpload uploadedFiles={[]} uploadFiles={vi.fn()} onAddLink={onAddLink} />);
+
+      await userEvent.click(screen.getByRole('button', { name: 'add a link' }));
+      await userEvent.click(screen.getByRole('button', { name: 'Add' }));
+      expect(screen.getByText('Name is required.')).toBeInTheDocument();
+      expect(screen.getByText('URL is required.')).toBeInTheDocument();
+
+      await userEvent.type(screen.getByLabelText('Name of link'), 'Policy');
+      await userEvent.type(screen.getByLabelText('Paste your link URL here'), 'ftp://example.com');
+      await userEvent.click(screen.getByRole('button', { name: 'Add' }));
+      expect(screen.getByText('Enter a valid URL starting with http:// or https://.')).toBeInTheDocument();
+      expect(onAddLink).not.toHaveBeenCalled();
+    });
+
+    test('closes the form on cancel', async () => {
+      render(<FileUpload uploadedFiles={[]} uploadFiles={vi.fn()} onAddLink={vi.fn()} />);
+      await userEvent.click(screen.getByRole('button', { name: 'add a link' }));
+      await userEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('editing a link', () => {
+    test('opens a pre-filled form and calls onEdit with the updated link', async () => {
+      const onEdit = vi.fn();
+      render(
+        <FileUpload
+          uploadFiles={vi.fn()}
+          uploadedFiles={[{
+            fileName: 'Policy',
+            href: 'https://example.com',
+            onEdit,
+            onDelete: vi.fn(),
+          }]}
+        />,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: 'Edit link' }));
+      expect(screen.getByLabelText('Name of link')).toHaveValue('Policy');
+      expect(screen.getByLabelText('Paste your link URL here')).toHaveValue('https://example.com');
+
+      await userEvent.clear(screen.getByLabelText('Name of link'));
+      await userEvent.type(screen.getByLabelText('Name of link'), 'Updated');
+      await userEvent.click(screen.getByRole('button', { name: 'Update' }));
+
+      expect(onEdit).toHaveBeenCalledWith({ name: 'Updated', url: 'https://example.com' });
+    });
+  });
 });

package/src/components/fileUpload/FileUpload.tsx

@@ -4,15 +4,25 @@ import { Card } from 'Components/card/Card';
 import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
 import { Separator } from 'Components/separator/Separator';
-import type { ReactNode } from 'react';
+import { useState, type AnchorHTMLAttributes, type ReactElement, type ReactNode } from 'react';
 import Dropzone from 'react-dropzone';
 import { Progress } from 'Components/progress/Progress';
+import type { WidgetRenderLinkArgs } from 'Components/widget/types';
+import { FileUploadLinkModal, type FileUploadLink } from './FileUploadLinkModal.js';
+
+export type { FileUploadLink };
+
+type LinkAnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
 
 type UploadedFile = {
   fileName: string;
   icon?: IconName;
-  fileType: string;
-  fileSize: string;
+  fileType?: string;
+  fileSize?: string;
+  href?: string;
+  linkProps?: LinkAnchorProps;
+  renderLink?: (args: WidgetRenderLinkArgs) => ReactElement;
+  onEdit?: (link: FileUploadLink) => void;
   onDownload?: () => void;
   onDelete: () => void;
   progressPercentage?: number;
@@ -24,6 +34,21 @@ export type FileUploadProps = {
   uploadedFiles: UploadedFile[];
   uploadFiles: (files: File[]) => void;
   dropzoneContent?: ReactNode;
+  onAddLink?: (link: FileUploadLink) => void;
+};
+
+type LinkPopupState = { mode: 'add' } | { mode: 'edit'; index: number } | null;
+
+const renderFileLink = ({ href = '', linkProps, renderLink }: UploadedFile, children: ReactNode) => {
+  const className = 'ds-file-upload__file-link';
+  if (renderLink) {
+    return renderLink({ href, className, children, linkProps });
+  }
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" className={className} {...linkProps}>
+      {children}
+    </a>
+  );
 };
 
 export const FileUpload = (props: FileUploadProps) => {
@@ -31,14 +56,39 @@ export const FileUpload = (props: FileUploadProps) => {
     className,
     uploadedFiles,
     uploadFiles,
-    dropzoneContent = (
+    onAddLink,
+  } = props;
+
+  const [linkPopup, setLinkPopup] = useState<LinkPopupState>(null);
+
+  const dropzoneContent = props.dropzoneContent ?? (
+    <>
       <p>
-        Drag and drop, or
-        {' '}
-        <Button variant="text-link">click to upload</Button>
+        {onAddLink
+          ? (
+              <>
+                Drag and drop,
+                {' '}
+                <Button
+                  variant="text-link"
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    setLinkPopup({ mode: 'add' });
+                  }}
+                >
+                  add a link
+                </Button>
+                {' '}
+                or
+              </>
+            )
+          : 'Drag and drop or'}
       </p>
-    ),
-  } = props;
+      <Button variant="secondary">Browse files</Button>
+    </>
+  );
+
+  const editedFile = linkPopup?.mode === 'edit' ? uploadedFiles[linkPopup.index] : undefined;
 
   return (
     <div
@@ -58,7 +108,7 @@ export const FileUpload = (props: FileUploadProps) => {
               {...getRootProps()}
               className="ds-file-upload__dropzone-input"
             >
-              <input {...getInputProps()} />
+              <input {...getInputProps({ 'aria-label': 'Upload files' })} />
               <div className="ds-file-upload__dropzone-content">
                 <span className="ds-file-upload__icon-wrapper">
                   <Icon
@@ -75,19 +125,45 @@ export const FileUpload = (props: FileUploadProps) => {
           </Card>
         )}
       </Dropzone>
+      {linkPopup?.mode === 'add' && onAddLink && (
+        <FileUploadLinkModal
+          title="Add URL attachment"
+          submitLabel="Add"
+          onSubmit={(link) => {
+            onAddLink(link);
+            setLinkPopup(null);
+          }}
+          onCancel={() => setLinkPopup(null)}
+        />
+      )}
+      {editedFile?.href && editedFile.onEdit && (
+        <FileUploadLinkModal
+          title="Update URL attachment"
+          submitLabel="Update"
+          initialLink={{ url: editedFile.href, name: editedFile.fileName }}
+          onSubmit={(link) => {
+            editedFile.onEdit?.(link);
+            setLinkPopup(null);
+          }}
+          onCancel={() => setLinkPopup(null)}
+        />
+      )}
       {uploadedFiles.length > 0 && (
         <Card className="ds-file-upload__file-list">
           {uploadedFiles.map((file, index) => {
             const {
               fileName,
-              icon = 'file',
               fileSize,
               fileType,
+              href,
+              onEdit,
               onDelete,
               onDownload,
               hasUploadFailed,
               progressPercentage,
             } = file;
+            const icon = file.icon ?? (href ? 'link' : 'file');
+            const nameNode = <span className="ds-file-upload__file-name">{fileName}</span>;
             return (
               <div key={fileName} className="ds-file-upload__file-outer">
                 <span className="ds-file-upload__file">
@@ -95,7 +171,7 @@ export const FileUpload = (props: FileUploadProps) => {
                     <Icon size={24} name={icon} color="var(--color-brand-600)" />
                   </span>
                   <span className="ds-file-upload__file-details">
-                    <span className="ds-file-upload__file-name">{fileName}</span>
+                    {href ? renderFileLink(file, nameNode) : nameNode}
                     {
                       hasUploadFailed
                         ? (
@@ -105,9 +181,27 @@ export const FileUpload = (props: FileUploadProps) => {
                               Upload failed
                             </span>
                           )
-                        : <span className="ds-file-upload__file-meta">{`${fileType}, ${fileSize}`}</span>
+                        : <span className="ds-file-upload__file-meta">{href ?? `${fileType}, ${fileSize}`}</span>
                     }
                   </span>
+                  {href && (
+                    <Button
+                      variant="secondary"
+                      isRound
+                      onClick={() => navigator.clipboard.writeText(href)}
+                    >
+                      <Icon name="copy" screenReaderText="Copy link" />
+                    </Button>
+                  )}
+                  {href && onEdit && (
+                    <Button
+                      variant="secondary"
+                      isRound
+                      onClick={() => setLinkPopup({ mode: 'edit', index })}
+                    >
+                      <Icon name="pencil" screenReaderText="Edit link" />
+                    </Button>
+                  )}
                   {onDownload && (
                     <Button
                       variant="secondary"
@@ -123,7 +217,7 @@ export const FileUpload = (props: FileUploadProps) => {
                       isRound
                       onClick={onDelete}
                     >
-                      <Icon name="trash" screenReaderText="Delete file" />
+                      <Icon name="trash" screenReaderText={href ? 'Delete link' : 'Delete file'} />
                     </Button>
                   )}
                 </span>
@@ -132,6 +226,7 @@ export const FileUpload = (props: FileUploadProps) => {
                     <Progress
                       value={progressPercentage}
                       className="ds-file-upload__progress-bar"
+                      aria-label="Upload progress bar"
                       indicatorClassName={classNames('ds-file-upload__progress-bar-indicator', {
                         'ds-file-upload__progress-bar-indicator--failed': hasUploadFailed,
                       })}

package/src/components/fileUpload/FileUploadLinkModal.tsx

@@ -0,0 +1,109 @@
+import { Button } from 'Components/button/Button';
+import { FormField } from 'Components/formField/FormField';
+import { Modal } from 'Components/modal/Modal';
+import { useId, useState, type FormEvent } from 'react';
+
+export type FileUploadLink = {
+  url: string;
+  name: string;
+};
+
+type FileUploadLinkModalProps = {
+  title: string;
+  submitLabel: string;
+  initialLink?: FileUploadLink;
+  onSubmit: (link: FileUploadLink) => void;
+  onCancel: () => void;
+};
+
+type LinkErrors = Partial<Record<keyof FileUploadLink, string>>;
+
+const isHttpUrl = (value: string) => {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === 'http:' || protocol === 'https:';
+  }
+  catch {
+    return false;
+  }
+};
+
+const validate = ({ url, name }: FileUploadLink): LinkErrors => {
+  const errors: LinkErrors = {};
+  if (!name) {
+    errors.name = 'Name is required.';
+  }
+  if (!url) {
+    errors.url = 'URL is required.';
+  }
+  else if (!isHttpUrl(url)) {
+    errors.url = 'Enter a valid URL starting with http:// or https://.';
+  }
+  return errors;
+};
+
+export const FileUploadLinkModal = (props: FileUploadLinkModalProps) => {
+  const { title, submitLabel, initialLink, onSubmit, onCancel } = props;
+  const formId = useId();
+  const nameId = useId();
+  const urlId = useId();
+  const [url, setUrl] = useState(initialLink?.url ?? '');
+  const [name, setName] = useState(initialLink?.name ?? '');
+  const [errors, setErrors] = useState<LinkErrors>({});
+
+  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const link = { url: url.trim(), name: name.trim() };
+    const validationErrors = validate(link);
+    setErrors(validationErrors);
+    if (Object.keys(validationErrors).length === 0) {
+      onSubmit(link);
+    }
+  };
+
+  return (
+    <Modal open title={title} closeHandler={onCancel}>
+      <Modal.Body>
+        <form
+          id={formId}
+          className="ds-file-upload__link-form"
+          onSubmit={handleSubmit}
+          noValidate
+        >
+          <FormField
+            inputType="text"
+            id={nameId}
+            label="Name of link"
+            errorText={errors.name}
+            inputProps={{
+              value: name,
+              onChange: (event) => {
+                setName(event.target.value);
+                setErrors(previous => ({ ...previous, name: undefined }));
+              },
+            }}
+          />
+          <FormField
+            inputType="text"
+            id={urlId}
+            label="Paste your link URL here"
+            errorText={errors.url}
+            inputProps={{
+              type: 'url',
+              value: url,
+              placeholder: 'https://',
+              onChange: (event) => {
+                setUrl(event.target.value);
+                setErrors(previous => ({ ...previous, url: undefined }));
+              },
+            }}
+          />
+        </form>
+      </Modal.Body>
+      <Modal.Footer>
+        <Button type="button" variant="secondary" onClick={onCancel}>Cancel</Button>
+        <Button type="submit" form={formId}>{submitLabel}</Button>
+      </Modal.Footer>
+    </Modal>
+  );
+};

package/src/components/fileUpload/fileUpload.scss

@@ -12,6 +12,7 @@
 
   &__file-details {
     flex-grow: 1;
+    min-width: 0;
     display: flex;
     flex-direction: column;
   }
@@ -22,10 +23,32 @@
   }
 
   &__file-meta {
-    color: var(--color-grey-500);
+    color: var(--color-grey-600);
     font-size: var(--font-size-2-13);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
+  &__file-link {
+    color: inherit;
+    text-decoration: none;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+
+    &:hover .ds-file-upload__file-name {
+      text-decoration: underline;
+    }
+  }
+
+  &__link-form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-medium);
+  }
+
+
   &__icon-wrapper {
     background-color: var(--color-brand-050);
     border-radius: var(--border-radius-small);