@arbor-education/design-system.components 4.9.2 → 5.0.0

package/src/components/dateTimePicker/DateTimePicker.stories.tsx

@@ -77,6 +77,11 @@ const DEVELOPER_NOTES = [
   '**`timeOptions` switches the embedded time input to combobox mode.** Instead of a free-form',
   'time input, the user picks from a predefined list. Use for fixed appointment slots.',
   '',
+  '**Typed times commit on blur, Enter or closing the popup.** In free-form mode the embedded time',
+  'input holds what the user types, and the date changes only once a complete, in-range time is',
+  'committed. Partial or out-of-range text never changes the date. In combobox mode, choosing an',
+  'option commits immediately.',
+  '',
   '**`hasError` is visual-only when used standalone.** It applies the red border but does NOT',
   'set `aria-invalid`. Always pair both when outside `<FormField>`:',
   '',

package/src/components/dateTimePicker/DateTimePicker.test.tsx

@@ -188,6 +188,142 @@ describe('DateTimePicker', () => {
     expect(lastDate.getMinutes()).toBe(30);
   });
 
+  test('partial text typed into the popup time field does not change the date', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 14, 30)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14');
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('out-of-range text in the popup time field does not change the date on Enter', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 14, 30)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '25:00{Enter}');
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('typing in the popup time field does not emit until the time is committed', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 9, 0)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14:30');
+
+    expect(onChange).not.toHaveBeenCalled();
+    expect(timeInput).toHaveValue('14:30');
+  });
+
+  test('Enter in the popup time field commits the typed time once', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 9, 0)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14:30{Enter}');
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const emitted: Date = onChange.mock.lastCall![0];
+    expect(emitted.getDate()).toBe(1);
+    expect(emitted.getHours()).toBe(14);
+    expect(emitted.getMinutes()).toBe(30);
+  });
+
+  test('leaving the popup time field commits the typed time', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 9, 0)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14:30');
+    await user.tab();
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const emitted: Date = onChange.mock.lastCall![0];
+    expect(emitted.getHours()).toBe(14);
+    expect(emitted.getMinutes()).toBe(30);
+  });
+
+  test('closing the popup with Escape commits the typed time', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 9, 0)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14:30');
+    await user.keyboard('{Escape}');
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const emitted: Date = onChange.mock.lastCall![0];
+    expect(emitted.getHours()).toBe(14);
+    expect(emitted.getMinutes()).toBe(30);
+  });
+
+  test('a partial time that fails to commit is replaced with the selected time on blur', async () => {
+    const user = userEvent.setup();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 14, 30)} />);
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14');
+    await user.tab();
+
+    expect(timeInput).toHaveValue('14:30');
+  });
+
+  test('picking a day keeps the selected time when the popup time text is partial', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 9, 15)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const timeInput = screen.getByLabelText('Select time', { selector: 'input' });
+    await user.clear(timeInput);
+    await user.type(timeInput, '14');
+    await user.click(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ }));
+
+    const emitted: Date = onChange.mock.lastCall![0];
+    expect(emitted.getDate()).toBe(20);
+    expect(emitted.getHours()).toBe(9);
+    expect(emitted.getMinutes()).toBe(15);
+  });
+
   test('opening the picker after typing a valid combined value syncs month, year, and time controls', async () => {
     const user = userEvent.setup();
     const { container } = render(<DateTimePicker />);
@@ -245,6 +381,17 @@ describe('DateTimePicker', () => {
       render(<DateTimePicker defaultValue={new Date(2024, 5, 15, 14, 30)} onChange={onChange} />);
       expect(onChange).not.toHaveBeenCalled();
     });
+
+    test('keeps the user-entered value across re-renders', () => {
+      const { rerender } = render(
+        <DateTimePicker aria-label="Start" defaultValue={new Date(2024, 5, 15, 14, 30)} />,
+      );
+
+      fireEvent.change(screen.getByLabelText('Start'), { target: { value: '2024-12-25T09:45' } });
+      rerender(<DateTimePicker aria-label="Start" defaultValue={new Date(2024, 5, 15, 14, 30)} />);
+
+      expect(screen.getByLabelText('Start')).toHaveValue('2024-12-25T09:45');
+    });
   });
 
   describe('onChange call-count correctness', () => {
@@ -289,6 +436,45 @@ describe('DateTimePicker', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  test('clearing a controlled value empties the date, time and calendar selection without firing onChange', () => {
+    const onChange = vi.fn();
+    const { rerender } = render(
+      <DateTimePicker aria-label="Start" value={new Date(2026, 3, 14, 14, 27)} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    const calendar = screen.getByRole('application');
+    expect(within(calendar).getByRole('gridcell', { selected: true })).toBeInTheDocument();
+    onChange.mockClear();
+
+    rerender(<DateTimePicker aria-label="Start" value={undefined} onChange={onChange} />);
+
+    expect(screen.getByLabelText('Start')).toHaveValue('');
+    expect(screen.getByLabelText('Select time', { selector: 'input' })).toHaveValue('');
+    expect(within(calendar).queryByRole('gridcell', { selected: true })).not.toBeInTheDocument();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('a cleared controlled picker still accepts a new date from the user', () => {
+    const onChange = vi.fn();
+    const { rerender } = render(
+      <DateTimePicker aria-label="Start" value={new Date(2026, 3, 14, 14, 27)} onChange={onChange} />,
+    );
+    rerender(<DateTimePicker aria-label="Start" value={undefined} onChange={onChange} />);
+
+    fireEvent.change(screen.getByLabelText('Start'), { target: { value: '2026-05-01T08:15' } });
+
+    expect(screen.getByLabelText('Start')).toHaveValue('2026-05-01T08:15');
+    expect(onChange).toHaveBeenLastCalledWith(new Date(2026, 4, 1, 8, 15));
+  });
+
+  test('a controlled value that starts empty displays a value supplied later', () => {
+    const { rerender } = render(<DateTimePicker aria-label="Start" value={undefined} />);
+
+    rerender(<DateTimePicker aria-label="Start" value={new Date(2026, 3, 14, 14, 27)} />);
+
+    expect(screen.getByLabelText('Start')).toHaveValue('2026-04-14T14:27');
+  });
+
   test('Today preserves the current time and closes the picker', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/components/dateTimePicker/DateTimePicker.tsx

@@ -9,6 +9,7 @@ import {
   getDateTimePlaceholder,
   getNativeDateTimePlaceholder,
   mergeDateAndTime,
+  parseCompleteTime,
   parseDateTimeInputValue,
   parseNativeDateTimeInputValue,
   type DateDisplayFormat,
@@ -30,8 +31,10 @@ import {
   useRef,
   useState,
   type ChangeEvent,
+  type KeyboardEvent,
   type PointerEvent,
 } from 'react';
+import { useIsControlledOnceSet } from 'Utils/hooks/useIsControlledOnceSet';
 import { PopupParentContext } from 'Utils/popupParent/PopupParentContext';
 
 export type DateTimePickerProps = {
@@ -109,7 +112,7 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
           ));
 
   const initialValue = value ?? defaultValue;
-  const isControlled = value !== undefined;
+  const isControlled = useIsControlledOnceSet(value);
   const [month, setMonth] = useState(initialValue ?? new Date());
   const [selectedDateTime, setSelectedDateTime] = useState<Date | undefined>(
     initialValue,
@@ -189,16 +192,23 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
     }
   };
 
-  const handleTimeChange = (nextTimeValue: string) => {
-    setTimeInputValue(nextTimeValue);
+  const selectedTimeText = selectedDateTime ? formatTimeInputValue(selectedDateTime, granularity) : '';
 
-    if (!selectedDateTime) {
+  const commitTimeInput = (nextTimeValue: string) => {
+    const completeTime = parseCompleteTime(nextTimeValue, granularity);
+    if (completeTime === null) {
+      if (selectedDateTime) {
+        setTimeInputValue(selectedTimeText);
+      }
+      return;
+    }
+    if (!selectedDateTime || completeTime === selectedTimeText) {
       return;
     }
 
     const nextDateTime = mergeDateAndTime(
       selectedDateTime,
-      nextTimeValue,
+      completeTime,
       granularity,
     );
     setSelectedDateTime(nextDateTime);
@@ -206,6 +216,19 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
     onChange?.(nextDateTime);
   };
 
+  const handleTimeChange = (nextTimeValue: string) => {
+    setTimeInputValue(nextTimeValue);
+    if (timeOptions) {
+      commitTimeInput(nextTimeValue);
+    }
+  };
+
+  const handleTimeInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') {
+      commitTimeInput(timeInputValue);
+    }
+  };
+
   const handleDayPickerSelect = (nextDate?: Date) => {
     if (!nextDate) {
       setSelectedDateTime(undefined);
@@ -217,7 +240,7 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
 
     const nextDateTime = mergeDateAndTime(
       nextDate,
-      timeInputValue,
+      parseCompleteTime(timeInputValue, granularity) ?? selectedTimeText,
       granularity,
     );
     setSelectedDateTime(nextDateTime);
@@ -230,7 +253,7 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
   };
 
   const handleTodayClick = () => {
-    const nextDate = mergeDateAndTime(new Date(), timeInputValue, granularity);
+    const nextDate = mergeDateAndTime(new Date(), parseCompleteTime(timeInputValue, granularity) ?? selectedTimeText, granularity);
     setSelectedDateTime(nextDate);
     setMonth(nextDate);
     setInputValue(formatInputValue(nextDate));
@@ -276,7 +299,12 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
       </div>
       <Popover.Root
         open={isPickerOpen}
-        onOpenChange={open => setIsPickerOpen(open)}
+        onOpenChange={(open) => {
+          if (!open) {
+            commitTimeInput(timeInputValue);
+          }
+          setIsPickerOpen(open);
+        }}
       >
         <Popover.Trigger asChild>
           <Button
@@ -303,6 +331,8 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
                 aria-label="Select time"
                 value={timeInputValue as TimeValue | ''}
                 onValueChange={handleTimeChange}
+                onBlur={() => commitTimeInput(timeInputValue)}
+                onKeyDown={handleTimeInputKeyDown}
                 granularity={granularity}
                 options={timeOptions}
                 searchType={searchType}

package/src/components/formField/FormField.stories.tsx

@@ -815,13 +815,12 @@ export default TextAreaExample;
     ),
   },
   [
-    '`inputType="textarea"` renders a `TextArea` — a multi-line input that grows automatically as',
-    'the user types (`autoSize={true}` is the default). The initial height is controlled by the',
-    '`rows` prop in `inputProps`.',
+    '`inputType="textarea"` renders a `TextArea` — a multi-line input that sizes itself to its content',
+    '(`autoSize={true}` is the default). The `rows` prop in `inputProps` sets the minimum starting height.',
     '',
     '**Use for:** pastoral notes, medical conditions, free-text feedback, long descriptions.',
     '',
-    '**Auto-sizing:** the textarea expands vertically as the user types — it does not scroll.',
+    '**Auto-sizing:** the textarea fits its content on mount, when the controlled `value` changes, and as the user types — it does not scroll.',
     'To opt out, pass `autoSize: false` in `inputProps`.',
     '',
     '**All shared wiring still applies:** `errorText`, `fieldDescription`, and `id` work identically.',

package/src/components/formField/FormField.test.tsx

@@ -48,7 +48,7 @@ describe('FormField component', () => {
   test('renders a time input when inputType is time', () => {
     render(<FormField id="niceid" inputType="time" inputProps={{ 'aria-label': 'Start time' }} />);
     const input = screen.getByLabelText('Start time');
-    expect(input).toHaveAttribute('type', 'time');
+    expect(input).toHaveClass('ds-time-input__input');
   });
 
   test('renders a colour picker dropdown when inputType is colourPicker', () => {

package/src/components/formField/inputs/textArea/TextArea.stories.tsx

@@ -9,7 +9,8 @@ import {
   Title,
 } from '@storybook/addon-docs/blocks';
 import { useState } from 'react';
-import { fn } from 'storybook/test';
+import { expect, fn, within } from 'storybook/test';
+import { Button } from 'Components/button/Button';
 import { FormField } from 'Components/formField/FormField';
 import { TextArea } from './TextArea.js';
 
@@ -57,11 +58,11 @@ const DEVELOPER_NOTES = [
   '### Critical gotchas',
   '',
   '#### 1. `autoSize` mechanics',
-  'When `autoSize={true}` (the default), the component reads `scrollHeight` on every `onChange` event',
-  'and sets `height = scrollHeight + 4px` (vertical padding compensation).',
-  'The textarea still starts at the height implied by the `rows` prop — growth begins after the first keystroke.',
-  'Importantly, `autoSize` is triggered by `onChange`, which means it only fires when the user types.',
-  'Setting a large `defaultValue` at mount will NOT auto-grow; call layout imperatively if needed.',
+  'When `autoSize={true}` (the default), the component reads `scrollHeight` and sets',
+  '`height = scrollHeight + 4px` (vertical padding compensation).',
+  'It does this on mount, whenever the controlled `value` changes, and on every `onChange` event,',
+  'so a field pre-populated through `value` or `defaultValue` opens fitted to its content.',
+  '`rows` is the minimum starting height for empty or short content.',
   '',
   '#### 2. CSS `resize` is NOT controlled by this component',
   'The browser default (`resize: both` or `resize: vertical` depending on browser) applies.',
@@ -75,11 +76,9 @@ const DEVELOPER_NOTES = [
   '<TextArea className="my-fixed-textarea" />',
   '```',
   '',
-  '#### 3. No `forwardRef` — consumers cannot attach a ref',
-  'TextArea uses an internal `ref` for `autoSize` calculations.',
-  'It is NOT a `forwardRef` component — you cannot attach a `ref` to it from the outside.',
-  'If you need imperative focus control, wrap the TextArea and use a separate DOM query,',
-  'or request `forwardRef` support as a library enhancement.',
+  '#### 3. `ref` resolves to the native `<textarea>`',
+  'TextArea is a `forwardRef` component. A `ref` you pass resolves to the underlying `HTMLTextAreaElement`,',
+  'for example to call `focus()` or `select()`. Attaching a ref does not interfere with `autoSize`.',
   '',
   '#### 4. `size` prop is intentionally omitted',
   'The HTML `size` attribute is omitted from the props (the TypeScript type uses `Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size">`).',
@@ -277,8 +276,7 @@ const meta = {
       description: [
         'Uncontrolled initial value. The textarea manages its own state after mount.',
         'Do not combine with `value` — use one or the other.',
-        'Note: setting a large `defaultValue` at mount will NOT trigger `autoSize`.',
-        'The textarea starts at the height set by `rows` regardless of the initial value length.',
+        'With `autoSize` enabled, the textarea grows on mount to fit a long `defaultValue`.',
       ].join(' '),
       table: {
         type: { summary: 'string' },
@@ -642,6 +640,56 @@ export const ReadOnly: Story = withDescription(
   ].join(' '),
 );
 
+const PRE_POPULATED_NOTES = 'Pupil has a documented nut allergy (anaphylaxis risk). EpiPen is held in the school office and a second pen travels with the pupil on trips. All catering staff have been briefed. Parents have supplied an updated care plan, which is reviewed each term with the school nurse.';
+
+export const PrePopulated: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <label htmlFor="medical-notes-prepopulated" style={{ color: 'var(--color-grey-600)' }}>
+          Medical notes
+        </label>
+        <TextArea id="medical-notes-prepopulated" rows={2} defaultValue={PRE_POPULATED_NOTES} />
+      </div>
+    ),
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement);
+      const textArea = canvas.getByRole('textbox', { name: 'Medical notes' });
+
+      await expect(textArea.scrollHeight).toBeLessThanOrEqual(textArea.clientHeight);
+    },
+  },
+  [
+    'A field opened with stored content longer than its `rows` height.',
+    'With `autoSize` enabled (the default) the textarea fits the content on mount, so nothing is hidden behind an internal scrollbar.',
+  ].join(' '),
+);
+
+const ExternallyUpdatedValueTemplate = () => {
+  const [notes, setNotes] = useState('Allergy reviewed.');
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <label htmlFor="care-plan-notes" style={{ color: 'var(--color-grey-600)' }}>
+        Care plan notes
+      </label>
+      <TextArea id="care-plan-notes" rows={2} value={notes} onChange={e => setNotes(e.currentTarget.value)} />
+      <Button variant="secondary" size="S" onClick={() => setNotes(PRE_POPULATED_NOTES)}>
+        Load care plan template
+      </Button>
+    </div>
+  );
+};
+
+export const ExternallyUpdatedValue: Story = withDescription(
+  {
+    render: () => <ExternallyUpdatedValueTemplate />,
+  },
+  [
+    'A controlled textarea whose `value` is replaced from outside, here by loading a template.',
+    'With `autoSize` enabled the height refits to the new content without the user typing.',
+  ].join(' '),
+);
+
 export const WithFormField: Story = withDescription(
   {
     render: () => (

package/src/components/formField/inputs/textArea/TextArea.test.tsx

@@ -1,9 +1,26 @@
-import { expect, describe, test, vi } from 'vitest';
-import { fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, expect, describe, test, vi } from 'vitest';
+import { createRef } from 'react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { TextArea } from './TextArea.js';
 import '@testing-library/jest-dom/vitest';
 
+const SHORT_TEXT = 'Short note';
+const LONG_TEXT = 'Pupil receives 1:1 literacy support three times per week. Extra time applies in all timed assessments.';
+const SHORT_SCROLL_HEIGHT = 40;
+const LONG_SCROLL_HEIGHT = 120;
+const VERTICAL_PADDING = 4;
+
 describe('TextArea component', () => {
+  beforeEach(() => {
+    vi.spyOn(HTMLTextAreaElement.prototype, 'scrollHeight', 'get').mockImplementation(function (this: HTMLTextAreaElement) {
+      return this.value.length > SHORT_TEXT.length ? LONG_SCROLL_HEIGHT : SHORT_SCROLL_HEIGHT;
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test('TextArea says hello', () => {
     render(<TextArea placeholder="Hello I'm a TextArea!" />);
     expect(screen.getByPlaceholderText("Hello I'm a TextArea!")).toBeInTheDocument();
@@ -16,4 +33,79 @@ describe('TextArea component', () => {
     expect(onChange).toHaveBeenCalled();
     expect((screen.getByPlaceholderText('Enter text') as HTMLInputElement).value).toBe('Hello');
   });
+
+  test('fits its height to a long defaultValue on mount', () => {
+    render(<TextArea aria-label="Notes" rows={2} defaultValue={LONG_TEXT} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+  });
+
+  test('fits its height to a long controlled value on mount', () => {
+    render(<TextArea aria-label="Notes" rows={2} value={LONG_TEXT} onChange={vi.fn()} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+  });
+
+  test('refits its height when the controlled value changes externally', () => {
+    const { rerender } = render(<TextArea aria-label="Notes" value={SHORT_TEXT} onChange={vi.fn()} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: `${SHORT_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+
+    rerender(<TextArea aria-label="Notes" value={LONG_TEXT} onChange={vi.fn()} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+  });
+
+  test('keeps its rows height on mount when autoSize is false', () => {
+    render(<TextArea aria-label="Notes" rows={2} autoSize={false} defaultValue={LONG_TEXT} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' }).style.height).toBe('');
+  });
+
+  test('resizes while typing and still calls onChange', () => {
+    const onChange = vi.fn();
+    render(<TextArea aria-label="Notes" onChange={onChange} />);
+    const textArea = screen.getByRole('textbox', { name: 'Notes' });
+
+    fireEvent.change(textArea, { target: { value: LONG_TEXT } });
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(textArea).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+  });
+
+  test('forwards a ref to the underlying textarea element', () => {
+    const textAreaRef = createRef<HTMLTextAreaElement>();
+    render(<TextArea aria-label="Notes" ref={textAreaRef} />);
+    expect(textAreaRef.current).toBe(screen.getByRole('textbox', { name: 'Notes' }));
+  });
+
+  test('keeps its rows height when mounted while not rendered', () => {
+    vi.spyOn(HTMLTextAreaElement.prototype, 'scrollHeight', 'get').mockReturnValue(0);
+    render(<TextArea aria-label="Notes" rows={2} defaultValue={LONG_TEXT} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: 'auto' });
+  });
+
+  test('refits its height once web fonts have loaded', async () => {
+    let resolveFontsReady: () => void = () => {};
+    const fontsReady = new Promise<void>((resolve) => {
+      resolveFontsReady = resolve;
+    });
+    Object.defineProperty(document, 'fonts', { value: { ready: fontsReady }, configurable: true });
+    const scrollHeightSpy = vi.spyOn(HTMLTextAreaElement.prototype, 'scrollHeight', 'get').mockReturnValue(LONG_SCROLL_HEIGHT);
+
+    try {
+      render(<TextArea aria-label="Notes" defaultValue={LONG_TEXT} />);
+      const textArea = screen.getByRole('textbox', { name: 'Notes' });
+      expect(textArea).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+
+      scrollHeightSpy.mockReturnValue(SHORT_SCROLL_HEIGHT);
+      resolveFontsReady();
+
+      await waitFor(() => expect(textArea).toHaveStyle({ height: `${SHORT_SCROLL_HEIGHT + VERTICAL_PADDING}px` }));
+    }
+    finally {
+      Reflect.deleteProperty(document, 'fonts');
+    }
+  });
+
+  test('still autosizes when a consumer passes a ref', () => {
+    const textAreaRef = createRef<HTMLTextAreaElement>();
+    render(<TextArea aria-label="Notes" ref={textAreaRef} defaultValue={LONG_TEXT} />);
+    expect(screen.getByRole('textbox', { name: 'Notes' })).toHaveStyle({ height: `${LONG_SCROLL_HEIGHT + VERTICAL_PADDING}px` });
+  });
 });

package/src/components/formField/inputs/textArea/TextArea.tsx

@@ -1,24 +1,56 @@
-import { useRef } from 'react';
+import { forwardRef, useImperativeHandle, useLayoutEffect, useRef } from 'react';
 import classNames from 'classnames';
 import type { ChangeEvent, TextareaHTMLAttributes } from 'react';
+import { useComponentDidMount } from 'Utils/hooks/useComponentDidMount';
 
 export type TextAreaProps = {
   hasError?: boolean;
   autoSize?: boolean;
 } & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'>;
 
-export const TextArea = (props: TextAreaProps) => {
+const VERTICAL_PADDING = 4;
+
+const autosizeTextArea = (textArea: HTMLTextAreaElement | null) => {
+  if (!textArea) {
+    return;
+  }
+  textArea.style.height = 'auto';
+  const contentHeight = textArea.scrollHeight;
+  // A textarea that is not rendered (e.g. inside a hidden tab) measures 0; keep its rows height instead of collapsing it
+  if (contentHeight > 0) {
+    textArea.style.height = `${contentHeight + VERTICAL_PADDING}px`;
+  }
+};
+
+export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>((props, ref) => {
   const {
     hasError,
     className = '',
     disabled = false,
     autoSize = true,
     onChange,
+    value,
     ...rest
   } = props;
 
   const inputRef = useRef<HTMLTextAreaElement | null>(null);
 
+  useImperativeHandle(ref, () => inputRef.current as HTMLTextAreaElement, []);
+
+  useLayoutEffect(() => {
+    if (autoSize) {
+      autosizeTextArea(inputRef.current);
+    }
+  }, [autoSize, value]);
+
+  // Text measured before web fonts load wraps differently, so measure again once they are ready
+  useComponentDidMount(() => {
+    if (!autoSize || !document.fonts) {
+      return;
+    }
+    void document.fonts.ready.then(() => autosizeTextArea(inputRef.current));
+  });
+
   const inputClasses = classNames(
     'ds-textarea',
     'ds-input',
@@ -28,19 +60,10 @@ export const TextArea = (props: TextAreaProps) => {
     className,
   );
 
-  const autosizeTextArea = () => {
-    if (inputRef.current) {
-      inputRef.current.style.height = 'auto';
-      const verticalPadding = 4;
-      const newHeight = inputRef.current.scrollHeight;
-      inputRef.current.style.height = `${newHeight + verticalPadding}px`;
-    }
-  };
-
   const handleOnChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
     onChange?.(e);
     if (autoSize) {
-      autosizeTextArea();
+      autosizeTextArea(inputRef.current);
     }
   };
 
@@ -50,10 +73,13 @@ export const TextArea = (props: TextAreaProps) => {
       className={inputClasses}
       disabled={disabled}
       onChange={handleOnChange}
+      value={value}
       {...rest}
     />
   );
-};
+});
+
+TextArea.displayName = 'TextArea';
 
 export namespace TextArea {
   export type Props = TextAreaProps;