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

package/src/components/datePicker/DatePicker.test.tsx

@@ -223,6 +223,15 @@ describe('DatePicker', () => {
       render(<DatePicker defaultValue={new Date(2024, 5, 15)} onChange={onChange} />);
       expect(onChange).not.toHaveBeenCalled();
     });
+
+    test('keeps the user-entered value across re-renders', () => {
+      const { rerender } = render(<DatePicker aria-label="Start date" defaultValue={new Date(2024, 5, 15)} />);
+
+      fireEvent.change(screen.getByLabelText('Start date'), { target: { value: '2024-12-25' } });
+      rerender(<DatePicker aria-label="Start date" defaultValue={new Date(2024, 5, 15)} />);
+
+      expect(screen.getByLabelText('Start date')).toHaveValue('2024-12-25');
+    });
   });
 
   describe('onChange call-count correctness', () => {
@@ -285,5 +294,44 @@ describe('DatePicker', () => {
       const lastDate: Date = onChange.mock.lastCall![0];
       expect(lastDate.getDate()).toBe(20);
     });
+
+    test('clearing the value empties the input and calendar selection without firing onChange', async () => {
+      const onChange = vi.fn();
+      const { rerender } = render(
+        <DatePicker aria-label="Start date" value={new Date(2024, 5, 15)} onChange={onChange} />,
+      );
+      await userEvent.click(screen.getByRole('button', { name: 'Open date picker' }));
+      const calendar = screen.getByRole('application');
+      expect(within(calendar).getByRole('gridcell', { selected: true })).toBeInTheDocument();
+      onChange.mockClear();
+
+      rerender(<DatePicker aria-label="Start date" value={undefined} onChange={onChange} />);
+
+      expect(screen.getByLabelText('Start date')).toHaveValue('');
+      expect(within(calendar).queryByRole('gridcell', { selected: true })).not.toBeInTheDocument();
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    test('a value that starts empty displays a value supplied later', () => {
+      const { rerender } = render(<DatePicker aria-label="Start date" value={undefined} />);
+
+      rerender(<DatePicker aria-label="Start date" value={new Date(2024, 11, 25)} />);
+
+      expect(screen.getByLabelText('Start date')).toHaveValue(formatNativeDateInputValue(new Date(2024, 11, 25)));
+    });
+
+    test('a cleared value still accepts a new date from the user', () => {
+      const onChange = vi.fn();
+      const { rerender } = render(
+        <DatePicker aria-label="Start date" value={new Date(2024, 5, 15)} onChange={onChange} />,
+      );
+      rerender(<DatePicker aria-label="Start date" value={undefined} onChange={onChange} />);
+
+      fireEvent.change(screen.getByLabelText('Start date'), { target: { value: '2024-12-25' } });
+
+      expect(screen.getByLabelText('Start date')).toHaveValue('2024-12-25');
+      const lastDate: Date = onChange.mock.lastCall![0];
+      expect([lastDate.getFullYear(), lastDate.getMonth(), lastDate.getDate()]).toEqual([2024, 11, 25]);
+    });
   });
 });

package/src/components/datePicker/DatePicker.tsx

@@ -11,6 +11,7 @@ import {
   type ChangeEvent,
   type PointerEvent,
 } from 'react';
+import { useIsControlledOnceSet } from 'Utils/hooks/useIsControlledOnceSet';
 import { PopupParentContext } from 'Utils/popupParent/PopupParentContext';
 import {
   formatNativeDateInputValue,
@@ -59,7 +60,7 @@ export const DatePicker = (props: DatePickerProps) => {
   } = props;
 
   const initialValue = value ?? defaultValue;
-  const isControlled = value !== undefined;
+  const isControlled = useIsControlledOnceSet(value);
   const [month, setMonth] = useState(initialValue ?? new Date());
   const [selectedDate, setSelectedDate] = useState<Date | undefined>(
     initialValue,

package/src/components/datePicker/dateInputUtils.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'vitest';
+import { parseCompleteTime } from './dateInputUtils.js';
+
+describe('parseCompleteTime', () => {
+  test.each([
+    ['14:30', 'minute', '14:30'],
+    ['9:05', 'minute', '09:05'],
+    ['00:00', 'minute', '00:00'],
+    ['23:59', 'minute', '23:59'],
+    ['14:30', 'second', '14:30:00'],
+    ['14:30:15', 'second', '14:30:15'],
+  ] as const)('normalises %s at %s granularity to %s', (value, granularity, expected) => {
+    expect(parseCompleteTime(value, granularity)).toBe(expected);
+  });
+
+  test.each([
+    ['', 'minute'],
+    ['905', 'minute'],
+    ['9', 'minute'],
+    ['14:', 'minute'],
+    ['14:3', 'minute'],
+    ['25:00', 'minute'],
+    ['14:75', 'minute'],
+    ['14:30:15', 'minute'],
+    ['14:30:60', 'second'],
+  ] as const)('rejects partial, out-of-range or wrong-precision %s at %s granularity', (value, granularity) => {
+    expect(parseCompleteTime(value, granularity)).toBeNull();
+  });
+});

package/src/components/datePicker/dateInputUtils.ts

@@ -105,6 +105,30 @@ export const formatTimeInputValue = (value: Date, granularity: TimeGranularity):
   format(value, getTimeFormatString(granularity)) as TimeValue
 );
 
+const COMPLETE_TIME_PATTERN = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+const MAX_HOURS = 23;
+const MAX_MINUTES_OR_SECONDS = 59;
+
+export const parseCompleteTime = (value: string, granularity: TimeGranularity): string | null => {
+  const match = COMPLETE_TIME_PATTERN.exec(value);
+  if (!match) {
+    return null;
+  }
+
+  const [, rawHours = '', minutes = '', rawSeconds] = match;
+  const hours = Number(rawHours);
+  const seconds = rawSeconds ?? '00';
+  if (granularity === 'minute' && rawSeconds !== undefined) {
+    return null;
+  }
+  if (hours > MAX_HOURS || Number(minutes) > MAX_MINUTES_OR_SECONDS || Number(seconds) > MAX_MINUTES_OR_SECONDS) {
+    return null;
+  }
+
+  const paddedTime = `${String(hours).padStart(2, '0')}:${minutes}`;
+  return granularity === 'second' ? `${paddedTime}:${seconds}` : paddedTime;
+};
+
 export const mergeDateAndTime = (date: Date, timeValue: string, granularity: TimeGranularity): Date => {
   const [rawHours = '0', rawMinutes = '0', rawSeconds = '0'] = timeValue.split(':');
   const hours = Number.parseInt(rawHours, 10) || 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: () => (