@arbor-education/design-system.components 4.0.0-react19-alpha.0 → 4.0.0

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

@@ -0,0 +1,339 @@
+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 { useState } from 'react';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import { FormField } from '../../FormField.js';
+import { SingleFileInput } from './SingleFileInput.js';
+
+const DESCRIPTION_INTRO = [
+  'The **SingleFileInput** lets a user pick exactly one file for a conventional form POST.',
+  'It shows the chosen file name in a read-only text field, with a button that opens the native file picker.',
+  'The selected file is submitted under the `name` you give it, like any other form control.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Attaching one document to a form that is submitted with a normal `<form>` POST: a consent letter, a photo, a CSV import',
+  '- Anywhere a legacy single-file field needs a Design System equivalent',
+  '- Inside `FormField` with `inputType="singleFile"` (the recommended pattern in real forms)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of SingleFileInput... | Use... | Why |',
+  '|---|---|---|',
+  '| Several files, drag and drop, upload progress or per-file delete | [`FileUpload`](?path=/docs/components-fileupload--docs) | Async multi-file dropzone |',
+  '| Free-form text | [`TextInput`](?path=/docs/components-formfield-inputs-textinput--docs) | No file is involved |',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '- **Width is always 100%** of its container: size the wrapper, not the input.',
+  '- **Use FormField in real forms** so the label, description, helper link and error text are wired up for you.',
+  '- **hasError + disabled is an anti-pattern** because a user cannot correct an error on a field they cannot edit.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**1. Reading the selected `File`.** `onChange` receives the native change event from the hidden file input.',
+  'Read `event.currentTarget.files?.[0]` **inside the handler** (React clears `currentTarget` afterwards) to validate',
+  'type or size, then show the result through `FormField`\'s `errorText`.',
+  '',
+  '**2. Form submission.** `name`, `accept` and `required` are applied to the native `<input type="file">`, which is',
+  'the only control that carries a `name`, so only the file itself is submitted.',
+  'The visible read-only field never submits.',
+  '',
+  '**3. `ref`.** The forwarded ref points at the native file input, so `ref.current.files` works as usual.',
+  'To reset the selection, submit a form containing the field or dispatch a DOM `reset` event on that form —',
+  'setting `ref.current.value = ""` clears the native input but leaves the displayed file name stale,',
+  'because a programmatic value change does not fire `change`.',
+  '',
+  '**4. Always provide `id` inside FormField.** The label targets the visible read-only field, which is what',
+  'assistive technology lands on.',
+  '',
+  '**5. Single file only.** `multiple` is not supported.',
+  '',
+  '**6. No focus or key handlers.** `onFocus`, `onBlur` and `onKeyDown` are not accepted: the native input never receives focus.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Keyboard: `Tab` moves from the read-only field to the **Choose file** button; `Enter` or `Space` opens the picker.',
+  '- The hidden native input is removed from the tab order and the accessibility tree, so the field is not announced twice.',
+  '- The chosen file name is the value of the labelled read-only field, so it is announced on focus.',
+  '- Pair `hasError` with `aria-invalid={true}` when used standalone. `FormField` does this automatically.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs) · [FileUpload](?path=/docs/components-fileupload--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+function SingleFileInputDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <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>
+    </>
+  );
+}
+
+const meta = {
+  title: 'Components/FormField/Inputs/SingleFileInput',
+  component: SingleFileInput,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SingleFileInputDocsPage,
+    },
+  },
+  args: {
+    'aria-label': 'Attachment',
+    'onChange': fn(),
+  },
+  argTypes: {
+    'hasError': {
+      description: 'Applies error-state styling. Does not set `aria-invalid`: pair it when used standalone.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    'disabled': {
+      description: 'Disables the field, the button and the native file input.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    'required': {
+      description: 'Marks the native file input as required for form validation and the visible field as required for assistive technology.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' } },
+    },
+    'name': {
+      description: 'Name the selected file is submitted under.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'accept': {
+      description: 'Comma-separated list of accepted file types, passed to the native file input (for example `.pdf,image/*`).',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'buttonLabel': {
+      description: 'Label of the button that opens the native file picker.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: "'Choose file'" } },
+    },
+    'placeholder': {
+      description: 'Text shown in the read-only field while no file is chosen.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: "'No file chosen'" } },
+    },
+    'id': {
+      description: 'Set on the visible read-only field, so a `<label htmlFor>` targets it. `FormField` passes this automatically.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'className': {
+      description: 'Extra class name(s) added to the wrapper element, alongside `ds-single-file-input`.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'aria-label': {
+      description: 'Accessible name for the visible read-only field when there is no visible label.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'aria-labelledby': {
+      description: 'ID(s) of the element(s) that label the visible read-only field.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'aria-describedby': {
+      description: 'ID(s) of the element(s) that describe the visible read-only field, such as helper or error text. `FormField` sets this automatically.',
+      control: 'text',
+      table: { type: { summary: 'string' } },
+    },
+    'aria-invalid': {
+      description: 'Marks the visible read-only field as invalid for assistive technology. `FormField` sets this automatically from `errorText`.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' } },
+    },
+    'onChange': {
+      description: 'Fired with the native change event. Read `event.currentTarget.files?.[0]` to get the selected `File`.',
+      control: false,
+      table: { type: { summary: '(event: ChangeEvent<HTMLInputElement>) => void' } },
+    },
+  },
+} satisfies Meta<typeof SingleFileInput>;
+
+export default meta;
+type Story = StoryObj<typeof SingleFileInput>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: { story: description },
+    },
+  },
+});
+
+const sampleFile = () => new File(['%PDF-1.4'], 'consent-letter.pdf', { type: 'application/pdf' });
+
+const wrap = (node: React.ReactNode) => (
+  <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>{node}</div>
+);
+
+export const Default: Story = withDescription(
+  {
+    render: args => wrap(<SingleFileInput {...args} />),
+  },
+  'No file chosen yet. The read-only field shows its placeholder and the **Choose file** button opens the native picker.',
+);
+
+export const Selected: Story = withDescription(
+  {
+    render: args => wrap(<SingleFileInput {...args} />),
+    play: async ({ canvasElement, args }) => {
+      const canvas = within(canvasElement);
+      const nativeInput = canvasElement.querySelector<HTMLInputElement>('input[type="file"]');
+      await userEvent.upload(nativeInput as HTMLInputElement, sampleFile());
+
+      await expect(canvas.getByRole('textbox', { name: 'Attachment' })).toHaveValue('consent-letter.pdf');
+      await expect(args.onChange).toHaveBeenCalled();
+    },
+  },
+  'After a file is chosen its name replaces the placeholder in the read-only field.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    args: { disabled: true },
+    render: args => wrap(<SingleFileInput {...args} />),
+  },
+  'The field, button and native input are all disabled.',
+);
+
+export const WithError: Story = withDescription(
+  {
+    render: () => wrap(
+      <FormField
+        id="attachment-error"
+        label="Attachment"
+        inputType="singleFile"
+        errorText="Attach a file to continue"
+        inputProps={{ name: 'attachment', required: true }}
+      />,
+    ),
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement);
+      const field = canvas.getByRole('textbox', { name: 'Attachment' });
+
+      await expect(field).toBeInvalid();
+      await expect(field).toHaveAccessibleDescription('Attach a file to continue');
+    },
+  },
+  'Inside `FormField`, `errorText` turns on the error styling, `aria-invalid` and the described-by link to the message.',
+);
+
+const ValidationTemplate = () => {
+  const [error, setError] = useState<string>();
+  const maxBytes = 1024;
+
+  return (
+    <FormField
+      id="attachment-validated"
+      label="Attachment"
+      inputType="singleFile"
+      fieldDescription="PDF, 1KB maximum"
+      errorText={error}
+      inputProps={{
+        name: 'attachment',
+        accept: '.pdf',
+        onChange: (event) => {
+          const file = event.currentTarget.files?.[0];
+          setError(file && file.size > maxBytes ? `${file.name} is larger than 1KB` : undefined);
+        },
+      }}
+    />
+  );
+};
+
+export const WithValidation: Story = withDescription(
+  {
+    render: () => wrap(<ValidationTemplate />),
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement);
+      const nativeInput = canvasElement.querySelector<HTMLInputElement>('input[type="file"]');
+      const oversized = new File([new Uint8Array(2048)], 'big.pdf', { type: 'application/pdf' });
+
+      await userEvent.upload(nativeInput as HTMLInputElement, oversized);
+
+      await expect(canvas.getByText('big.pdf is larger than 1KB')).toBeInTheDocument();
+      await expect(canvas.getByRole('textbox', { name: 'Attachment' })).toBeInvalid();
+    },
+  },
+  'The consumer reads the selected `File` in `onChange`, validates it, and reports the result through `errorText`.',
+);
+
+export const InAForm: Story = withDescription(
+  {
+    render: () => wrap(
+      <form>
+        <FormField
+          id="attachment-form"
+          label="Consent letter"
+          inputType="singleFile"
+          fieldDescription="Attach the signed letter"
+          helperLinkText="Letter template"
+          helperLinkUrl="https://example.com/template"
+          inputProps={{ name: 'consentLetter', accept: '.pdf' }}
+        />
+      </form>,
+    ),
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement);
+      const form = canvasElement.querySelector('form') as HTMLFormElement;
+      const nativeInput = form.querySelector('input[type="file"]') as HTMLInputElement;
+
+      // user-event only stubs `files`, so build a real FileList for FormData to read.
+      const transfer = new DataTransfer();
+      transfer.items.add(sampleFile());
+      nativeInput.files = transfer.files;
+      nativeInput.dispatchEvent(new Event('change', { bubbles: true }));
+
+      const submitted = new FormData(form).get('consentLetter');
+      await expect(submitted).toBeInstanceOf(File);
+      await expect((submitted as File).name).toBe('consent-letter.pdf');
+      await expect(canvas.getByRole('textbox', { name: 'Consent letter' })).toHaveValue('consent-letter.pdf');
+    },
+  },
+  'Within a native `<form>`, the chosen file is submitted under the file input\'s `name`.',
+);

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;
+}