@arbor-education/design-system.components 3.5.0 → 3.6.0

package/src/components/formField/inputs/singleFile/SingleFileInput.test.tsx

@@ -0,0 +1,181 @@
+import '@testing-library/jest-dom/vitest';
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef, type ChangeEvent } from 'react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { SingleFileInput } from './SingleFileInput.js';
+
+const pdf = new File(['pdf'], 'report.pdf', { type: 'application/pdf' });
+
+describe('SingleFileInput', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('renders an empty read-only field with the default placeholder and a choose button', () => {
+    render(<SingleFileInput aria-label="Attachment" />);
+
+    const field = screen.getByLabelText('Attachment');
+    expect(field).toHaveAttribute('readonly');
+    expect(field).toHaveValue('');
+    expect(field).toHaveAttribute('placeholder', 'No file chosen');
+    expect(screen.getByRole('button', { name: 'Choose file' })).toBeInTheDocument();
+  });
+
+  test('uses a custom placeholder', () => {
+    render(<SingleFileInput aria-label="Attachment" placeholder="Pick a PDF" />);
+    expect(screen.getByLabelText('Attachment')).toHaveAttribute('placeholder', 'Pick a PDF');
+  });
+
+  test('clicking the button opens the native file picker', async () => {
+    const user = userEvent.setup();
+    const click = vi.spyOn(HTMLInputElement.prototype, 'click');
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" />);
+
+    await user.click(screen.getByRole('button', { name: 'Choose file' }));
+
+    expect(click).toHaveBeenCalledWith();
+    expect(click.mock.contexts).toContain(ref.current);
+  });
+
+  test('shows the chosen file name in the labelled read-only field', async () => {
+    const user = userEvent.setup();
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" />);
+
+    await user.upload(ref.current as HTMLInputElement, pdf);
+
+    expect(screen.getByRole('textbox', { name: 'Attachment' })).toHaveValue('report.pdf');
+  });
+
+  test('clears the file name when the selection is cleared', async () => {
+    const user = userEvent.setup();
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" />);
+
+    await user.upload(ref.current as HTMLInputElement, pdf);
+    await user.upload(ref.current as HTMLInputElement, []);
+
+    expect(screen.getByLabelText('Attachment')).toHaveValue('');
+  });
+
+  test('clears the file name when the surrounding form is reset', async () => {
+    const user = userEvent.setup();
+    const ref = createRef<HTMLInputElement>();
+    render(
+      <form aria-label="Upload">
+        <SingleFileInput ref={ref} aria-label="Attachment" />
+      </form>,
+    );
+
+    await user.upload(ref.current as HTMLInputElement, pdf);
+    expect(screen.getByLabelText('Attachment')).toHaveValue('report.pdf');
+
+    act(() => {
+      screen.getByRole('form', { name: 'Upload' }).dispatchEvent(new Event('reset'));
+    });
+
+    expect(screen.getByLabelText('Attachment')).toHaveValue('');
+  });
+
+  test('calls onChange with the native event so the consumer can read the File', async () => {
+    const user = userEvent.setup();
+    let selectedFile: File | undefined;
+    const onChange = vi.fn((event: ChangeEvent<HTMLInputElement>) => {
+      selectedFile = event.currentTarget.files?.[0];
+    });
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" onChange={onChange} />);
+
+    await user.upload(ref.current as HTMLInputElement, pdf);
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(selectedFile).toBe(pdf);
+  });
+
+  test('passes name, accept and required to the native file input', () => {
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" name="attachment" accept=".pdf" required />);
+
+    expect(ref.current).toHaveAttribute('type', 'file');
+    expect(ref.current).toHaveAttribute('name', 'attachment');
+    expect(ref.current).toHaveAttribute('accept', '.pdf');
+    expect(ref.current).toBeRequired();
+    expect(ref.current).not.toHaveAttribute('multiple');
+  });
+
+  test('exposes required to assistive technology on the visible field', () => {
+    render(<SingleFileInput aria-label="Attachment" required />);
+    expect(screen.getByLabelText('Attachment')).toBeRequired();
+  });
+
+  test('does not submit the visible read-only field', () => {
+    const { container } = render(
+      <form>
+        <SingleFileInput aria-label="Attachment" name="attachment" />
+      </form>,
+    );
+
+    const namedControls = container.querySelectorAll('[name]');
+    expect(namedControls).toHaveLength(1);
+    expect(namedControls[0]).toHaveAttribute('type', 'file');
+  });
+
+  test('disables the field, button and native input', () => {
+    const ref = createRef<HTMLInputElement>();
+    render(<SingleFileInput ref={ref} aria-label="Attachment" disabled />);
+
+    expect(screen.getByLabelText('Attachment')).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Choose file' })).toBeDisabled();
+    expect(ref.current).toBeDisabled();
+  });
+
+  test('applies error styling to the field and the button', () => {
+    render(<SingleFileInput aria-label="Attachment" hasError />);
+
+    expect(screen.getByLabelText('Attachment')).toHaveClass('ds-input--error');
+    expect(screen.getByRole('button', { name: 'Choose file' })).toHaveClass('ds-button--error');
+  });
+
+  test('forwards id and aria attributes to the visible field', () => {
+    render(<SingleFileInput id="attachment" aria-label="Attachment" aria-describedby="hint" aria-invalid />);
+
+    const field = screen.getByLabelText('Attachment');
+    expect(field).toHaveAttribute('id', 'attachment');
+    expect(field).toHaveAttribute('aria-describedby', 'hint');
+    expect(field).toBeInvalid();
+  });
+
+  test('tabs from the read-only field to the button and skips the hidden native input', async () => {
+    const user = userEvent.setup();
+    render(<SingleFileInput aria-label="Attachment" />);
+
+    await user.tab();
+    expect(screen.getByLabelText('Attachment')).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Choose file' })).toHaveFocus();
+  });
+
+  test('opens the file picker from the keyboard with Enter and Space', async () => {
+    const user = userEvent.setup();
+    const click = vi.spyOn(HTMLInputElement.prototype, 'click');
+    render(<SingleFileInput aria-label="Attachment" />);
+
+    await user.tab();
+    await user.tab();
+    await user.keyboard('{Enter}');
+    expect(click).toHaveBeenCalledTimes(1);
+
+    await user.keyboard(' ');
+    expect(click).toHaveBeenCalledTimes(2);
+  });
+
+  test('uses a custom button label', () => {
+    render(<SingleFileInput aria-label="Attachment" buttonLabel="Browse" />);
+
+    expect(screen.getByRole('button', { name: 'Browse' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Choose file' })).not.toBeInTheDocument();
+  });
+});

package/src/components/formField/inputs/singleFile/SingleFileInput.tsx

@@ -0,0 +1,101 @@
+import classNames from 'classnames';
+import { Button } from 'Components/button/Button';
+import { forwardRef, useCallback, useRef, useState, type ChangeEvent, type InputHTMLAttributes } from 'react';
+import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
+
+export type SingleFileInputProps = {
+  hasError?: boolean;
+  buttonLabel?: string;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type' | 'value' | 'defaultValue' | 'multiple' | 'onFocus' | 'onBlur' | 'onKeyDown'>;
+
+/** The forwarded ref targets the hidden native file input; `id` and ARIA props go on the visible read-only field. */
+export const SingleFileInput = forwardRef<HTMLInputElement, SingleFileInputProps>((props, ref) => {
+  const {
+    hasError = false,
+    buttonLabel = 'Choose file',
+    placeholder = 'No file chosen',
+    className,
+    disabled = false,
+    required,
+    id,
+    onChange,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    ...rest
+  } = props;
+
+  const [fileName, setFileName] = useState('');
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+
+  const setRefs = useCallback((node: HTMLInputElement | null) => {
+    fileInputRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    }
+    else if (ref) {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  useComponentDidMount(() => {
+    const form = fileInputRef.current?.form;
+    const clearFileName = () => setFileName('');
+    form?.addEventListener('reset', clearFileName);
+    return () => form?.removeEventListener('reset', clearFileName);
+  });
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    setFileName(event.currentTarget.files?.[0]?.name ?? '');
+    onChange?.(event);
+  };
+
+  return (
+    <div className={classNames('ds-single-file-input', className)}>
+      <input
+        {...rest}
+        ref={setRefs}
+        type="file"
+        className="sr-only"
+        tabIndex={-1}
+        aria-hidden="true"
+        required={required}
+        disabled={disabled}
+        onChange={handleChange}
+      />
+      <input
+        id={id}
+        type="text"
+        readOnly
+        value={fileName}
+        placeholder={placeholder}
+        disabled={disabled}
+        aria-required={required}
+        aria-describedby={ariaDescribedBy}
+        aria-invalid={ariaInvalid}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        className={classNames('ds-input', 'ds-input--M', 'ds-single-file-input__name', {
+          'ds-input--error': hasError,
+        })}
+      />
+      <Button
+        type="button"
+        variant="secondary"
+        error={hasError}
+        disabled={disabled}
+        className="ds-single-file-input__trigger"
+        onClick={() => fileInputRef.current?.click()}
+      >
+        {buttonLabel}
+      </Button>
+    </div>
+  );
+});
+
+SingleFileInput.displayName = 'SingleFileInput';
+
+export namespace SingleFileInput {
+  export type Props = SingleFileInputProps;
+}

package/src/components/formField/inputs/singleFile/singleFileInput.scss

@@ -0,0 +1,17 @@
+.ds-single-file-input {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-small);
+  width: 100%;
+}
+
+.ds-single-file-input__name {
+  flex: 1 1 auto;
+  min-width: 0;
+  text-overflow: ellipsis;
+}
+
+.ds-single-file-input__trigger {
+  flex: none;
+}

package/src/index.scss

@@ -17,6 +17,7 @@
 @use "components/formField/label/label.scss";
 @use "components/formField/inputs/number/numberInput.scss";
 @use "components/formField/inputs/time/timeInput.scss";
+@use "components/formField/inputs/singleFile/singleFileInput.scss";
 @use "components/formField/inputs/radio/radioButtonInput.scss";
 @use "components/formField/inputs/checkbox/checkboxInput.scss";
 @use "components/formField/inputs/selectDropdown/selectDropdown";

package/src/index.ts

@@ -35,6 +35,7 @@ export { NumberInput } from 'Components/formField/inputs/number/NumberInput';
 export { RadioButtonGroup } from 'Components/formField/inputs/radio/RadioButtonGroup';
 export { RadioButtonInput } from 'Components/formField/inputs/radio/RadioButtonInput';
 export { SelectDropdown } from 'Components/formField/inputs/selectDropdown/SelectDropdown';
+export { SingleFileInput } from 'Components/formField/inputs/singleFile/SingleFileInput';
 export { Skeleton } from 'Components/skeleton/Skeleton';
 export { TextInput } from 'Components/formField/inputs/text/TextInput';
 export { TextArea } from 'Components/formField/inputs/textArea/TextArea';