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

package/dist/utils/hooks/useIsControlledOnceSet.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useIsControlledOnceSet.test.d.ts.map

package/dist/utils/hooks/useIsControlledOnceSet.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsControlledOnceSet.test.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/useIsControlledOnceSet.test.ts"],"names":[],"mappings":""}

package/dist/utils/hooks/useIsControlledOnceSet.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useIsControlledOnceSet } from './useIsControlledOnceSet.js';
+describe('useIsControlledOnceSet', () => {
+    test('is uncontrolled while no value has been received', () => {
+        const { result, rerender } = renderHook(({ value }) => useIsControlledOnceSet(value), { initialProps: { value: undefined } });
+        rerender({ value: undefined });
+        expect(result.current).toBe(false);
+    });
+    test('is controlled from the first render with a value', () => {
+        const { result } = renderHook(() => useIsControlledOnceSet(new Date(2026, 3, 14)));
+        expect(result.current).toBe(true);
+    });
+    test('becomes controlled when a value arrives after an empty mount', () => {
+        const { result, rerender } = renderHook(({ value }) => useIsControlledOnceSet(value), { initialProps: { value: undefined } });
+        rerender({ value: new Date(2026, 3, 14) });
+        expect(result.current).toBe(true);
+    });
+    test('stays controlled when the value is cleared', () => {
+        const { result, rerender } = renderHook(({ value }) => useIsControlledOnceSet(value), { initialProps: { value: new Date(2026, 3, 14) } });
+        rerender({ value: undefined });
+        expect(result.current).toBe(true);
+    });
+});
+//# sourceMappingURL=useIsControlledOnceSet.test.js.map

package/dist/utils/hooks/useIsControlledOnceSet.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsControlledOnceSet.test.js","sourceRoot":"","sources":["../../../src/utils/hooks/useIsControlledOnceSet.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CACrC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,EAC5C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,SAA6B,EAAE,EAAE,CAC3D,CAAC;QAEF,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAE/B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAEnF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACxE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CACrC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,EAC5C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,SAA6B,EAAE,EAAE,CAC3D,CAAC;QAEF,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAE3C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACtD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CACrC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,EAC5C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAqB,EAAE,EAAE,CACvE,CAAC;QAEF,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAE/B,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbor-education/design-system.components",
-  "version": "4.9.2",
+  "version": "5.1.0",
   "description": "The component library for the design system (the baby)",
   "main": "dist/index.js",
   "type": "module",

package/src/components/banner/banner.scss

@@ -7,6 +7,10 @@
   border-width: 1px;
   border-style: solid;
 
+  > svg {
+    flex: none;
+  }
+
   &__central-container {
     flex-grow: 1;
     display: flex;

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

@@ -94,9 +94,10 @@ const DEVELOPER_NOTES = [
   '**7. Always provide `label` when using `helperLinkText`.** The helper link `aria-label` is',
   'constructed as `"${label} helper link"`. Omit `label` and the aria-label becomes `"undefined helper link"`.',
   '',
-  '**8. Optional fields: use the label suffix convention.** There is no `required` prop and no',
-  'asterisk pattern. Mark optional fields by appending `"(optional)"` to the label text, e.g.',
-  '`label="Middle name (optional)"`. All fields without this suffix are implicitly required.',
+  '**8. Optional fields: pass `optional`.** FormField appends `"(optional)"` to the label for you,',
+  'e.g. `label="Middle name" optional` renders "Middle name (optional)". There is no asterisk pattern.',
+  'Omit `optional` and the label is rendered untouched. `optional` only changes the label;',
+  'pass native `required` via `inputProps` for form validation and assistive technology semantics.',
   '',
   '**9. `NumberInput` renders `type="text"` internally.** Do not pass `type` in `inputProps` when',
   '`inputType="number"` — it is ignored and may produce confusing behaviour. The component uses',
@@ -226,14 +227,23 @@ const meta = {
       control: 'text',
       description: [
         'Visible label rendered above the input via the `Label` component (`ds-label`).',
-        'Short, sentence case. Use `"Field name (optional)"` suffix for optional fields — there is',
-        'no `required` prop and no asterisk convention.',
+        'Short, sentence case. Do not add an `"(optional)"` suffix yourself — pass `optional`.',
         '**Also required when using `helperLinkText`** — the link\'s `aria-label` uses this value verbatim.',
       ].join(' '),
       table: {
         type: { summary: 'string' },
       },
     },
+    optional: {
+      control: 'boolean',
+      description: [
+        'Controls the label treatment. `true` appends `"(optional)"` to the label; `false` or omitted leaves',
+        'the label untouched. Does not affect the native `required` attribute — use `inputProps.required` for that.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+      },
+    },
     inputType: {
       control: 'select',
       options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox', 'checkbox', 'checkboxGroup', 'toggle', 'radio', 'singleFile', 'custom'],
@@ -815,13 +825,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.',
@@ -1291,17 +1300,19 @@ function OptionalAndRequiredFieldsExample() {
       />
       <FormField
         id="student-middle-name"
-        label="Middle name (optional)"
+        label="Middle name"
+        optional
         inputProps={{ placeholder: 'e.g. Marie' }}
       />
       <FormField
         id="student-surname"
         label="Surname"
-        inputProps={{ placeholder: 'e.g. Nylund' }}
+        inputProps={{ placeholder: 'e.g. Nylund', required: true }}
       />
       <FormField
         id="student-preferred-name"
-        label="Preferred name (optional)"
+        label="Preferred name"
+        optional
         fieldDescription="Used in class registers and parent communications"
         inputProps={{ placeholder: 'e.g. Rosie' }}
       />
@@ -1328,17 +1339,19 @@ export default OptionalAndRequiredFieldsExample;
         />
         <FormField
           id="student-middle-name"
-          label="Middle name (optional)"
+          label="Middle name"
+          optional
           inputProps={{ placeholder: 'e.g. Marie' }}
         />
         <FormField
           id="student-surname"
           label="Surname"
-          inputProps={{ placeholder: 'e.g. Nylund' }}
+          inputProps={{ placeholder: 'e.g. Nylund', required: true }}
         />
         <FormField
           id="student-preferred-name"
-          label="Preferred name (optional)"
+          label="Preferred name"
+          optional
           fieldDescription="Used in class registers and parent communications"
           inputProps={{ placeholder: 'e.g. Rosie' }}
         />
@@ -1352,10 +1365,11 @@ export default OptionalAndRequiredFieldsExample;
     ),
   },
   [
-    'Arbor uses the **label suffix convention** for optional fields — no asterisk, no `required` prop.',
-    'Append `"(optional)"` directly to the label text: `label="Middle name (optional)"`.',
+    'Arbor uses the **label suffix convention** for optional fields — no asterisk.',
+    'Pass `optional` and FormField appends `"(optional)"` to the label: `label="Middle name" optional`.',
     '',
-    'Fields without this suffix are implicitly required. This is a deliberate Confluence design',
+    'Fields rendered without `optional` carry no suffix and are implicitly required. Pass native',
+    '`required` via `inputProps` as well so form validation and assistive technology agree. This is a deliberate Confluence design',
     'decision: marking optional fields (the minority) is less visually noisy than marking required',
     'fields (the majority) with an asterisk that users learn to ignore anyway.',
     '',