@arbor-education/design-system.components 4.7.1 → 4.9.0

package/src/components/fileUpload/FileList.tsx

@@ -0,0 +1,125 @@
+import classNames from 'classnames';
+import { Button } from 'Components/button/Button';
+import { Card } from 'Components/card/Card';
+import { Icon } from 'Components/icon/Icon';
+import { Progress } from 'Components/progress/Progress';
+import { Separator } from 'Components/separator/Separator';
+import type { UploadedFile } from 'Components/fileUpload/FileUpload';
+import type { ReactNode } from 'react';
+
+export type FileListProps = {
+  uploadedFiles: UploadedFile[];
+  onEditFile?: (index: number) => void;
+};
+
+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 FileList = (props: FileListProps) => {
+  const {
+    uploadedFiles,
+    onEditFile,
+  } = props;
+
+  return (
+    <Card className="ds-file-upload__file-list">
+      {uploadedFiles.map((file, index) => {
+        const {
+          fileName,
+          fileSize,
+          fileType,
+          href,
+          onEdit,
+          onDelete,
+          onDownload,
+          hasUploadFailed,
+          progressPercentage,
+          errorMessage,
+        } = 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">
+              <span className="ds-file-upload__icon-wrapper">
+                <Icon size={24} name={icon} color="var(--color-brand-600)" />
+              </span>
+              <span className="ds-file-upload__file-details">
+                {href ? renderFileLink(file, nameNode) : nameNode}
+                {
+                  hasUploadFailed || errorMessage
+                    ? (
+                        <span className="ds-file-upload__upload-failed">
+                          <Icon name="circle-alert" />
+                          {' '}
+                          {errorMessage ?? 'Upload failed'}
+                        </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 && onEditFile && onEdit && (
+                <Button
+                  variant="secondary"
+                  isRound
+                  onClick={() => onEditFile(index)}
+                >
+                  <Icon name="pencil" screenReaderText="Edit link" />
+                </Button>
+              )}
+              {onDownload && (
+                <Button
+                  variant="secondary"
+                  isRound
+                  onClick={onDownload}
+                >
+                  <Icon name="download" screenReaderText="Download file" />
+                </Button>
+              )}
+              {onDelete && (
+                <Button
+                  variant="secondary"
+                  isRound
+                  onClick={onDelete}
+                >
+                  <Icon name="trash" screenReaderText={href ? 'Delete link' : 'Delete file'} />
+                </Button>
+              )}
+            </span>
+            {typeof progressPercentage === 'number' && progressPercentage < 100
+              && (
+                <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,
+                  })}
+                />
+              )}
+            {index < uploadedFiles.length - 1 && <Separator />}
+          </div>
+        );
+      })}
+    </Card>
+  );
+};

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

@@ -189,6 +189,15 @@ const meta = {
         },
       },
     },
+    errorMessage: {
+      description:
+        'Error message rendered beneath the dropzone with an alert icon. Use it for errors that apply to the upload as a whole. '
+        + 'For an error on a single file, set `errorMessage` on that file object instead.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
     className: {
       description: 'Additional CSS class name(s) applied to the root element.',
       control: 'text',
@@ -742,6 +751,76 @@ export default FailedDuringUploadExample;
 
 // ─────────────────────────────────────────────────────────────────────────────
 
+export const WithErrorMessage: Story = withDescription(
+  {
+    args: {
+      uploadedFiles: completedFiles,
+      errorMessage: 'File limit exceeded',
+    },
+    render: args => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload {...args} />
+      </div>
+    ),
+  },
+  'An `errorMessage` renders beneath the dropzone with an alert icon. Use it for errors '
+  + 'that apply to the upload as a whole. Edit the message in the Controls panel to try your own copy.',
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const ErrorMessageWithoutFiles: Story = withDescription(
+  {
+    args: {
+      uploadedFiles: [],
+      errorMessage: 'Your upload could not be started. Refresh the page and try again.',
+    },
+    render: args => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload {...args} />
+      </div>
+    ),
+  },
+  'The upload-level `errorMessage` also renders when no files are attached, '
+  + 'directly beneath the empty dropzone.',
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const FileWithErrorMessage: Story = withDescription(
+  {
+    args: {
+      uploadedFiles: [
+        {
+          fileName: 'oversized-photo.png',
+          fileType: 'PNG',
+          fileSize: '18 MB',
+          onDelete: noop,
+          hasUploadFailed: true,
+          errorMessage: 'This file is larger than the 10 MB limit.',
+        },
+        {
+          fileName: 'spring-term-report-2024.pdf',
+          fileType: 'PDF',
+          fileSize: '1.2 MB',
+          onDownload: noop,
+          onDelete: noop,
+        },
+      ],
+    },
+    render: args => (
+      <div style={{ maxWidth: '560px', padding: 'var(--spacing-large)' }}>
+        <FileUpload {...args} />
+      </div>
+    ),
+  },
+  'A file-level `errorMessage` explains why one specific file failed. It is set on the '
+  + 'file object and is separate from the upload-level `errorMessage`. The second file is '
+  + 'unaffected.',
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 export const CustomDropzoneContent: Story = withDescription(
   {
     render: () => (

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

@@ -122,6 +122,88 @@ describe('FileUpload', () => {
     });
   });
 
+  describe('error messages', () => {
+    test('renders the upload-level errorMessage with the error class', () => {
+      const { container } = render(
+        <FileUpload
+          uploadedFiles={[]}
+          uploadFiles={vi.fn()}
+          errorMessage="Some files could not be attached."
+        />,
+      );
+      expect(screen.getByText('Some files could not be attached.')).toBeInTheDocument();
+      expect(container.querySelector('.ds-file-upload__error')).toBeInTheDocument();
+    });
+
+    test('does not render the upload-level error when errorMessage is not set', () => {
+      const { container } = render(<FileUpload uploadedFiles={[]} uploadFiles={vi.fn()} />);
+      expect(container.querySelector('.ds-file-upload__error')).not.toBeInTheDocument();
+    });
+
+    test('renders the upload-level errorMessage alongside the file list', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[baseFile]}
+          uploadFiles={vi.fn()}
+          errorMessage="Some files could not be attached."
+        />,
+      );
+      expect(screen.getByText('Some files could not be attached.')).toBeInTheDocument();
+      expect(screen.getByText('report.pdf')).toBeInTheDocument();
+    });
+
+    test('replaces file meta with the file-level errorMessage', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{ ...baseFile, errorMessage: 'This file is larger than the 10 MB limit.' }]}
+          uploadFiles={vi.fn()}
+        />,
+      );
+      expect(screen.getByText('This file is larger than the 10 MB limit.')).toBeInTheDocument();
+      expect(screen.queryByText('PDF, 1.2 MB')).not.toBeInTheDocument();
+    });
+
+    test('shows the file-level errorMessage instead of "Upload failed" when both are set', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{ ...baseFile, hasUploadFailed: true, errorMessage: 'File is corrupt.' }]}
+          uploadFiles={vi.fn()}
+        />,
+      );
+      expect(screen.getByText('File is corrupt.')).toBeInTheDocument();
+      expect(screen.queryByText('Upload failed')).not.toBeInTheDocument();
+    });
+
+    test('shows the upload-level and file-level errors together', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{ ...baseFile, errorMessage: 'File is corrupt.' }]}
+          uploadFiles={vi.fn()}
+          errorMessage="Some files could not be attached."
+        />,
+      );
+      expect(screen.getByText('Some files could not be attached.')).toBeInTheDocument();
+      expect(screen.getByText('File is corrupt.')).toBeInTheDocument();
+    });
+
+    test('keeps the link anchor and replaces the href meta with the file-level errorMessage', () => {
+      render(
+        <FileUpload
+          uploadedFiles={[{
+            fileName: 'Pastoral policy',
+            href: 'https://example.com/policy',
+            errorMessage: 'This link could not be reached.',
+            onDelete: vi.fn(),
+          }]}
+          uploadFiles={vi.fn()}
+        />,
+      );
+      expect(screen.getByRole('link', { name: 'Pastoral policy' })).toHaveAttribute('href', 'https://example.com/policy');
+      expect(screen.getByText('This link could not be reached.')).toBeInTheDocument();
+      expect(screen.queryByText('https://example.com/policy')).not.toBeInTheDocument();
+    });
+  });
+
   describe('progress bar', () => {
     test('renders progress bar when progressPercentage is less than 100', () => {
       const { container } = render(

package/src/components/fileUpload/FileUpload.tsx

@@ -3,18 +3,17 @@ import { Button } from 'Components/button/Button';
 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 { 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';
+import { FileList, type FileListProps as ListProps } from './FileList.js';
 
 export type { FileUploadLink };
 
 type LinkAnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'className' | 'children'>;
 
-type UploadedFile = {
+export type UploadedFile = {
   fileName: string;
   icon?: IconName;
   fileType?: string;
@@ -24,9 +23,10 @@ type UploadedFile = {
   renderLink?: (args: WidgetRenderLinkArgs) => ReactElement;
   onEdit?: (link: FileUploadLink) => void;
   onDownload?: () => void;
-  onDelete: () => void;
+  onDelete?: () => void;
   progressPercentage?: number;
   hasUploadFailed?: boolean;
+  errorMessage?: string;
 };
 
 export type FileUploadProps = {
@@ -35,28 +35,18 @@ export type FileUploadProps = {
   uploadFiles: (files: File[]) => void;
   dropzoneContent?: ReactNode;
   onAddLink?: (link: FileUploadLink) => void;
+  errorMessage?: string;
 };
 
 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) => {
   const {
     className,
     uploadedFiles,
     uploadFiles,
     onAddLink,
+    errorMessage,
   } = props;
 
   const [linkPopup, setLinkPopup] = useState<LinkPopupState>(null);
@@ -88,7 +78,7 @@ export const FileUpload = (props: FileUploadProps) => {
     </>
   );
 
-  const editedFile = linkPopup?.mode === 'edit' ? uploadedFiles[linkPopup.index] : undefined;
+  const fileToEdit = linkPopup?.mode === 'edit' ? uploadedFiles[linkPopup.index] : undefined;
 
   return (
     <div
@@ -125,6 +115,13 @@ export const FileUpload = (props: FileUploadProps) => {
           </Card>
         )}
       </Dropzone>
+      {errorMessage && (
+        <span className="ds-file-upload__error">
+          <Icon name="alert-triangle" />
+          {' '}
+          {errorMessage}
+        </span>
+      )}
       {linkPopup?.mode === 'add' && onAddLink && (
         <FileUploadLinkModal
           title="Add URL attachment"
@@ -136,108 +133,32 @@ export const FileUpload = (props: FileUploadProps) => {
           onCancel={() => setLinkPopup(null)}
         />
       )}
-      {editedFile?.href && editedFile.onEdit && (
+      {fileToEdit?.href && fileToEdit.onEdit && (
         <FileUploadLinkModal
           title="Update URL attachment"
           submitLabel="Update"
-          initialLink={{ url: editedFile.href, name: editedFile.fileName }}
+          initialLink={{ url: fileToEdit.href, name: fileToEdit.fileName }}
           onSubmit={(link) => {
-            editedFile.onEdit?.(link);
+            fileToEdit.onEdit?.(link);
             setLinkPopup(null);
           }}
           onCancel={() => setLinkPopup(null)}
         />
       )}
       {uploadedFiles.length > 0 && (
-        <Card className="ds-file-upload__file-list">
-          {uploadedFiles.map((file, index) => {
-            const {
-              fileName,
-              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">
-                  <span className="ds-file-upload__icon-wrapper">
-                    <Icon size={24} name={icon} color="var(--color-brand-600)" />
-                  </span>
-                  <span className="ds-file-upload__file-details">
-                    {href ? renderFileLink(file, nameNode) : nameNode}
-                    {
-                      hasUploadFailed
-                        ? (
-                            <span className="ds-file-upload__upload-failed">
-                              <Icon name="circle-alert" />
-                              {' '}
-                              Upload failed
-                            </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"
-                      isRound
-                      onClick={onDownload}
-                    >
-                      <Icon name="download" screenReaderText="Download file" />
-                    </Button>
-                  )}
-                  {onDelete && (
-                    <Button
-                      variant="secondary"
-                      isRound
-                      onClick={onDelete}
-                    >
-                      <Icon name="trash" screenReaderText={href ? 'Delete link' : 'Delete file'} />
-                    </Button>
-                  )}
-                </span>
-                {typeof progressPercentage === 'number' && progressPercentage < 100
-                  && (
-                    <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,
-                      })}
-                    />
-                  )}
-                {index < uploadedFiles.length - 1 && <Separator />}
-              </div>
-            );
-          })}
-        </Card>
+        <FileList
+          uploadedFiles={uploadedFiles}
+          onEditFile={index => setLinkPopup({ mode: 'edit', index })}
+        />
       )}
     </div>
   );
 };
+
+FileUpload.FileList = FileList;
+
+export namespace FileUpload {
+  export type Props = FileUploadProps;
+  export type FileListProps = ListProps;
+  export type File = UploadedFile;
+}

package/src/components/fileUpload/fileUpload.scss

@@ -3,6 +3,14 @@
   flex-direction: column;
   gap: var(--spacing-small);
 
+  &__error {
+    color: var(--form-field-text-error-color-error-text);
+
+    .ds-icon {
+      color: var(--form-field-text-error-color-error-icon);
+    }
+  }
+
   &__file {
     display: flex;
     flex-direction: row;

package/src/components/heading/Heading.stories.tsx

@@ -256,6 +256,17 @@ const meta = {
         type: { summary: 'string' },
       },
     },
+    errorMessage: {
+      control: 'text',
+      description: [
+        'Error message shown beneath the heading with the error icon, matching the FormField error style.',
+        'Setting it also sets `aria-describedby` on the heading so screen readers announce the message with it.',
+        'Write it as what went wrong plus how to fix it.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
   },
 } satisfies Meta<typeof Heading>;
 
@@ -447,6 +458,18 @@ export const Default: Story = withDescription(
   'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to change `level` (1–4) and see the heading typography scale live. The `children` control is disabled because complex JSX cannot be round-tripped through Storybook\'s serialiser — use the named stories below to explore composition patterns.',
 );
 
+export const WithError: Story = withDescription(
+  {
+    args: {
+      level: 1,
+      children: 'Student records',
+      errorMessage: 'Select a school before saving these records',
+    },
+    render: args => <Heading {...args} />,
+  },
+  'Error state — setting `errorMessage` shows the message beneath the heading with the error icon, and links it to the heading through `aria-describedby`. Use it for a page-level problem that the user must fix, such as a missing required selection.',
+);
+
 export const AllLevels: Story = withDescription(
   {
     render: AllLevelsTemplate,

package/src/components/heading/Heading.test.tsx

@@ -26,4 +26,42 @@ describe('Heading', () => {
 
     expect(screen.getByText('foobar').tagName).toBe('H2');
   });
+
+  test('renders the error message when errorMessage is set', () => {
+    render(<Heading errorMessage="Enter a student name">Student</Heading>);
+
+    expect(screen.getByText('Enter a student name')).toBeInTheDocument();
+  });
+
+  test('links the heading to the error message with aria-describedby', () => {
+    render(<Heading errorMessage="Enter a student name">Student</Heading>);
+
+    const heading = screen.getByRole('heading', { name: 'Student' });
+    const message = screen.getByText('Enter a student name');
+    expect(heading).toHaveAttribute('aria-describedby', message.id);
+  });
+
+  test('preserves an existing aria-describedby alongside the error message id', () => {
+    render(
+      <Heading errorMessage="Enter a student name" aria-describedby="hint">
+        Student
+      </Heading>,
+    );
+
+    const message = screen.getByText('Enter a student name');
+    expect(screen.getByRole('heading')).toHaveAttribute('aria-describedby', `hint ${message.id}`);
+  });
+
+  test('does not render an error or aria-describedby when errorMessage is not set', () => {
+    render(<Heading>Student</Heading>);
+
+    expect(screen.getByRole('heading')).not.toHaveAttribute('aria-describedby');
+    expect(document.querySelector('.ds-heading__error-message')).not.toBeInTheDocument();
+  });
+
+  test('does not forward errorMessage to the DOM element', () => {
+    render(<Heading errorMessage="Enter a student name">Student</Heading>);
+
+    expect(screen.getByRole('heading')).not.toHaveAttribute('errormessage');
+  });
 });

package/src/components/heading/Heading.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
-import { createElement, type HTMLAttributes, type HTMLProps } from 'react';
+import { createElement, useId, type HTMLAttributes, type HTMLProps } from 'react';
+import { Icon } from 'Components/icon/Icon';
 
 type HeadingSubContainerProps = HTMLAttributes<HTMLSpanElement>;
 
@@ -21,10 +22,12 @@ export type HeadingLevel = 1 | 2 | 3 | 4;
 
 type HeadingProps = {
   level?: HeadingLevel;
+  errorMessage?: string;
 } & HTMLProps<HTMLHeadingElement>;
 
 export const Heading = (props: HeadingProps) => {
-  const { level = 1, children } = props;
+  const { level = 1, children, errorMessage, ...rest } = props;
+  const generatedId = useId();
   const Component = {
     1: 'h1',
     2: 'h2',
@@ -32,7 +35,28 @@ export const Heading = (props: HeadingProps) => {
     4: 'h4',
   }[level];
 
-  return createElement(Component, { ...props, className: classNames('ds-heading', props.className) }, children);
+  const errorId = `${generatedId}-error`;
+  const describedBy = classNames(rest['aria-describedby'], errorMessage && errorId) || undefined;
+
+  const heading = createElement(
+    Component,
+    { ...rest, 'aria-describedby': describedBy, 'className': classNames('ds-heading', rest.className) },
+    children,
+  );
+
+  if (!errorMessage) {
+    return heading;
+  }
+
+  return (
+    <div className="ds-heading__wrapper">
+      {heading}
+      <span className="ds-heading__error-message" id={errorId}>
+        <Icon size={12} name="triangle-alert" />
+        {errorMessage}
+      </span>
+    </div>
+  );
 };
 
 Heading.InnerContainer = HeadingInnerContainer;