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

package/src/components/formField/inputs/time/TimeInput.test.tsx

@@ -19,17 +19,22 @@ describe('TimeInput', () => {
     vi.restoreAllMocks();
   });
 
-  test('renders a native time input by default', () => {
+  test('renders a text input so no browser picker is drawn', () => {
     render(<TimeInput aria-label="Start time" />);
-    const input = screen.getByLabelText('Start time');
 
-    expect(input).toHaveAttribute('type', 'time');
-    expect(input).toHaveAttribute('step', '60');
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('type', 'text');
+  });
+
+  test('shows HH:mm as the placeholder by default', () => {
+    render(<TimeInput aria-label="Start time" />);
+
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('placeholder', 'HH:mm');
   });
 
-  test('uses one-second stepping when granularity is second', () => {
+  test('shows HH:mm:ss as the placeholder when granularity is second', () => {
     render(<TimeInput aria-label="Start time" granularity="second" />);
-    expect(screen.getByLabelText('Start time')).toHaveAttribute('step', '1');
+
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('placeholder', 'HH:mm:ss');
   });
 
   test('native mode emits the string value when changed', () => {
@@ -43,6 +48,70 @@ describe('TimeInput', () => {
     expect(onValueChange).toHaveBeenCalledWith('14:30');
   });
 
+  test('blocks keystrokes other than digits and colons', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimeInput aria-label="Start time" onValueChange={onValueChange} />);
+
+    await user.type(screen.getByLabelText('Start time'), '9.7x:a');
+
+    expect(onValueChange).toHaveBeenLastCalledWith('97:');
+    expect(screen.getByLabelText('Start time')).toHaveValue('97:');
+  });
+
+  test('strips non-time characters from pasted text', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimeInput aria-label="Start time" onValueChange={onValueChange} />);
+    const input = screen.getByLabelText('Start time');
+
+    await user.click(input);
+    await user.paste('abc14:30');
+
+    expect(onValueChange).toHaveBeenLastCalledWith('14:30');
+    expect(input).toHaveValue('14:30');
+  });
+
+  test('a typed colon is accepted', async () => {
+    const user = userEvent.setup();
+    render(<TimeInput aria-label="Start time" />);
+
+    await user.type(screen.getByLabelText('Start time'), '14:30');
+
+    expect(screen.getByLabelText('Start time')).toHaveValue('14:30');
+  });
+
+  test('does not set aria-invalid itself, so validation stays with the consumer', async () => {
+    const user = userEvent.setup();
+    render(<TimeInput aria-label="Start time" />);
+    const input = screen.getByLabelText('Start time');
+
+    await user.type(input, 'abc');
+
+    expect(input).not.toHaveAttribute('aria-invalid');
+  });
+
+  test('applies error styling from hasError and reflects aria-invalid passed by the consumer', () => {
+    render(<TimeInput aria-label="Start time" hasError aria-invalid />);
+    const input = screen.getByLabelText('Start time');
+
+    expect(input).toHaveClass('ds-input--error');
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  test('submits the typed text under the field name', async () => {
+    const user = userEvent.setup();
+    render(
+      <form aria-label="Schedule">
+        <TimeInput aria-label="Start time" name="start" />
+      </form>,
+    );
+
+    await user.type(screen.getByLabelText('Start time'), '9:05');
+
+    expect(new FormData(screen.getByRole<HTMLFormElement>('form')).get('start')).toBe('9:05');
+  });
+
   test('clicking the clock icon focuses the input and selects the hour segment when supported', async () => {
     const user = userEvent.setup();
     const setSelectionRange = vi.spyOn(HTMLInputElement.prototype, 'setSelectionRange').mockImplementation(() => {});

package/src/components/formField/inputs/time/TimeInput.tsx

@@ -2,7 +2,7 @@ import classNames from 'classnames';
 import { Combobox } from 'Components/combobox/Combobox';
 import type { ComboboxOption, ComboboxSearchType } from 'Components/combobox/types';
 import { Icon } from 'Components/icon/Icon';
-import { forwardRef, useCallback, useMemo, useRef, useState, type ChangeEvent, type InputHTMLAttributes } from 'react';
+import { forwardRef, useCallback, useMemo, useRef, useState, type ChangeEvent, type InputHTMLAttributes, type KeyboardEvent } from 'react';
 
 /** Expected string `HH:MM` or `HH:MM:SS`; format-shaped versus strict time validation. */
 export type TimeValue = `${string}:${string}` | `${string}:${string}:${string}`;
@@ -22,6 +22,14 @@ export type TimeInputProps = {
 
 const clockIcon = <Icon name="clock-3" size={16} />;
 
+const TIME_CHARACTER_PATTERN = /^[0-9:]$/;
+const NON_TIME_CHARACTERS_PATTERN = /[^0-9:]/g;
+
+const NATIVE_PLACEHOLDER_BY_GRANULARITY: Record<TimeGranularity, string> = {
+  minute: 'HH:mm',
+  second: 'HH:mm:ss',
+};
+
 /** The forwarded ref is attached in native mode but when `options` is provided, no input ref is exposed. */
 export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, ref) => {
   const {
@@ -32,6 +40,7 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     searchType = 'prefix',
     highlightStringMatches = false,
     onChange,
+    onKeyDown,
     className,
     disabled = false,
     id,
@@ -76,8 +85,22 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     } as ChangeEvent<HTMLInputElement>);
   }, [isControlled, onChange, onValueChange]);
 
+  const handleNativeKeyDown = useCallback((event: KeyboardEvent<HTMLInputElement>) => {
+    const isShortcut = event.ctrlKey || event.metaKey || event.altKey;
+    const isPrintable = event.key.length === 1;
+    if (isPrintable && !isShortcut && !TIME_CHARACTER_PATTERN.test(event.key)) {
+      event.preventDefault();
+    }
+    onKeyDown?.(event);
+  }, [onKeyDown]);
+
   const handleNativeChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
-    updateValue(event.currentTarget.value, event);
+    const { value } = event.currentTarget;
+    const timeCharacters = value.replace(NON_TIME_CHARACTERS_PATTERN, '');
+    if (timeCharacters !== value) {
+      event.currentTarget.value = timeCharacters;
+    }
+    updateValue(timeCharacters, event);
   }, [updateValue]);
 
   const focusAndSelectHours = useCallback(() => {
@@ -87,11 +110,7 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
     }
 
     input.focus();
-
-    try {
-      input.setSelectionRange(0, 2);
-    }
-    catch { /* Some browsers do not expose selection APIs on time inputs. */ }
+    input.setSelectionRange(0, 2);
   }, []);
 
   const timeOptions = useMemo<ComboboxOption[]>(
@@ -139,18 +158,18 @@ export const TimeInput = forwardRef<HTMLInputElement, TimeInputProps>((props, re
         ref={setRefs}
         id={id}
         name={name}
-        type="time"
+        type="text"
         value={currentValue}
-        step={granularity === 'second' ? 1 : 60}
         disabled={disabled}
         aria-describedby={ariaDescribedBy}
         aria-invalid={ariaInvalid}
         aria-label={ariaLabel}
-        placeholder={placeholder}
+        placeholder={placeholder ?? NATIVE_PLACEHOLDER_BY_GRANULARITY[granularity]}
         className={classNames('ds-input', 'ds-input--M', 'ds-time-input__input', {
           'ds-input--error': hasError,
         })}
         onChange={handleNativeChange}
+        onKeyDown={handleNativeKeyDown}
       />
       <button
         type="button"

package/src/components/formField/inputs/time/timeInput.scss

@@ -4,13 +4,7 @@
 }
 
 .ds-time-input__input {
-  appearance: none;
   padding-right: calc(var(--form-field-text-medium-height) + var(--spacing-small));
-
-  &::-webkit-calendar-picker-indicator {
-    display: none;
-    appearance: none;
-  }
 }
 
 .ds-time-input__icon-button {

package/src/components/kvpList/KVPList.stories.tsx

@@ -33,6 +33,7 @@ const TERM_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
   '| `children` | `ReactNode` | — | The key/label text |',
+  '| `prominence` | `\'neutral\' \\| \'strong\'` | `\'neutral\'` | `neutral` = body text; `strong` = bold body weight, e.g. a totals row label |',
   '| `className` | `string` | — | Additional CSS classes on the `<dt>` element |',
   '| `...HTMLAttributes<dt>` | | | All standard element attributes forwarded |',
 ].join('\n');
@@ -372,6 +373,59 @@ export default StrongProminenceExample;
   '`prominence="strong"` applies h2-scale typography to the definition — rendered as `<dd>` semantically but visually dominant. Use for the primary metric value in a list; `"neutral"` for supporting context.',
 );
 
+export const TotalsRow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KVPList } from '@arbor-education/design-system.components';
+
+function TotalsRowExample() {
+  return (
+    <KVPList aria-label="Basket totals">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Subtotal</KVPList.Term>
+        <KVPList.Definition>£40.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Delivery</KVPList.Term>
+        <KVPList.Definition>£2.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term prominence="strong">Total</KVPList.Term>
+        <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  );
+}
+export default TotalsRowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <KVPList aria-label="Basket totals">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>
+    ),
+  },
+  '`prominence="strong"` on `KVPList.Term` applies the bold body weight token (`--type-body-bold-weight`) so the label of a totals row balances a strong definition. Unemphasised terms are unchanged.',
+);
+
 export const IsRow: Story = withDescription(
   {
     parameters: {

package/src/components/kvpList/KVPList.test.tsx

@@ -51,6 +51,58 @@ describe('KVPList', () => {
     expect(container.querySelector('.ds-kvp-list__description--row')).toBeInTheDocument();
   });
 
+  test('applies the strong modifier to a term with strong prominence', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).toHaveClass('ds-kvp-list__term', 'ds-kvp-list__term--strong');
+  });
+
+  test('does not forward prominence to the term element', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).not.toHaveAttribute('prominence');
+  });
+
+  test('leaves a term without prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term className="custom-term">Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Subtotal')).toHaveAttribute('class', 'ds-kvp-list__term custom-term');
+  });
+
+  test('leaves a term with neutral prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="neutral">Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Delivery')).toHaveAttribute('class', 'ds-kvp-list__term');
+  });
+
   test('does not add group semantics when no accessible label is provided', () => {
     render(
       <KVPList>

package/src/components/kvpList/KVPList.tsx

@@ -11,6 +11,7 @@ export type KVPListRowProps = React.HTMLAttributes<HTMLDListElement> & {
 
 export type KVPListTermProps = React.HTMLAttributes<HTMLElement> & {
   children?: React.ReactNode;
+  prominence?: 'neutral' | 'strong';
 };
 
 export type KVPListDefinitionProps = React.HTMLAttributes<HTMLElement> & {
@@ -60,9 +61,17 @@ const KVPListRow = ({
 const KVPListTerm = ({
   children,
   className,
+  prominence = 'neutral',
   ...rest
 }: KVPListTermProps): React.JSX.Element => (
-  <dt className={classNames('ds-kvp-list__term', className)} {...rest}>
+  <dt
+    className={classNames(
+      'ds-kvp-list__term',
+      { 'ds-kvp-list__term--strong': prominence === 'strong' },
+      className,
+    )}
+    {...rest}
+  >
     {children}
   </dt>
 );

package/src/components/kvpList/kvpList.scss

@@ -21,6 +21,10 @@
   line-height: var(--type-body-line-height);
 }
 
+.ds-kvp-list__term--strong {
+  font-weight: var(--type-body-bold-weight);
+}
+
 .ds-kvp-list__description--strong {
   color: var(--kvp-list-color-text-strong);
   font-family: var(--type-headings-h2-family);

package/src/components/row/Row.stories.tsx

@@ -25,6 +25,7 @@ const DESCRIPTION_INTRO = [
   'Pass an `onClick` handler to make the row fully interactive — it enters the tab order, gains hover and focus styles, and renders a pair of animated directional icons.',
   'Pass `href` to turn the value into a native anchor link, supporting any protocol including `mailto:` and `tel:`.',
   'Pass `tooltipText` to show an explanatory tooltip when a user hovers the row — useful for read-only fields or values that need additional context.',
+  'Pass `isActive` to highlight the row as the one currently being worked on, for example the row a slideover was opened from.',
 ].join(' ');
 
 const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
@@ -60,6 +61,9 @@ const DEVELOPER_NOTES = [
   '| Static | `-1` (not in tab order) | — | None |',
   '| Clickable | `0` (in tab order) | `ds-row--clickable` | `chevron-right` + `arrow-right` |',
   '',
+  '`isActive` is independent of `onClick`: it adds the `ds-row--active` modifier and `aria-current="true"`, and can be combined with either state.',
+  'The active background is kept on hover so an active clickable row stays distinguishable from its siblings.',
+  '',
   '**Dual-icon swap:** Both icons are always in the DOM when `onClick` is provided. CSS controls visibility —',
   'at rest `chevron-right` shows; on hover/focus `arrow-right` shows. No JavaScript state is involved.',
   '',
@@ -109,6 +113,7 @@ const DEVELOPER_NOTES = [
   '|---|---|',
   '| `--section-list-row-default-color-background` | Resting background colour |',
   '| `--section-list-row-hover-hover-bg` | Hover background (clickable rows only) |',
+  '| `--section-list-row-active-active-bg` | Background of an active row (`isActive`), including on hover |',
   '| `--section-list-row-spacing-vertical` | Top/bottom padding |',
   '| `--section-list-row-spacing-horizontal` | Left/right padding |',
   '| `--section-list-row-radius` | Border radius |',
@@ -133,6 +138,7 @@ const DEVELOPER_NOTES = [
   '  note?: ReactNode;',
   '  placeholder?: string;',
   '  tooltipText?: string;',
+  '  isActive?: boolean;',
   '  onClick?: MouseEventHandler<HTMLDivElement>;',
   '};',
   '```',
@@ -256,6 +262,18 @@ const meta = {
         defaultValue: { summary: 'undefined' },
       },
     },
+    isActive: {
+      description: [
+        'Marks the row as the currently active or selected row, such as the row a slideover was opened from.',
+        'Adds the `ds-row--active` modifier and `aria-current="true"`, and applies the `--section-list-row-active-active-bg` background, which is kept on hover.',
+        'Combine with `onClick` for an active row that is also clickable.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
     onClick: {
       description: [
         'When provided, activates all clickable behaviour: the row enters the tab order (`tabIndex={0}`),',
@@ -757,6 +775,51 @@ export default GuardianRow;
   'Clickable row with all three right-side elements active: value, note, and the chevron/arrow icon pair. The note takes 20% flex-basis; the value narrows to 50%; the icon is flex-shrunk. The secondary context ("Primary contact") persists alongside the navigation affordance.',
 );
 
+export const Active: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Section } from '@arbor-education/design-system.components';
+
+function GuardianSection({ activeGuardianId, openGuardian }) {
+  return (
+    <Section title="Guardians">
+      <Row
+        label="Mother"
+        value="Sarah Okafor"
+        isActive={activeGuardianId === 'guardian-42'}
+        onClick={() => openGuardian('guardian-42')}
+      />
+      <Row
+        label="Father"
+        value="David Okafor"
+        isActive={activeGuardianId === 'guardian-43'}
+        onClick={() => openGuardian('guardian-43')}
+      />
+      <Row label="Emergency contact" value="Grace Mensah" isActive={false} />
+    </Section>
+  );
+}
+export default GuardianSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section title="Guardians">
+        <Row label="Mother" value="Sarah Okafor" isActive onClick={fn()} />
+        <Row label="Father" value="David Okafor" onClick={fn()} />
+        <Row label="Emergency contact" value="Grace Mensah" />
+      </Section>
+    ),
+  },
+  'Set `isActive` to highlight the row currently being worked on — for example the row a slideover was opened from. The first row is active **and** clickable: it keeps the active background on hover, retains its focus ring and keyboard activation, and exposes `aria-current="true"`. The other rows render exactly as they do without the prop.',
+);
+
 export const MixedClickableAndStatic: Story = withDescription(
   {
     parameters: {

package/src/components/row/Row.test.tsx

@@ -106,6 +106,65 @@ describe('Row component', () => {
     });
   });
 
+  describe('active behaviour', () => {
+    test('applies the active modifier when isActive is true', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row--active');
+    });
+
+    test('marks an active row as the current item for assistive technology', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveAttribute('aria-current', 'true');
+    });
+
+    test('does not apply the active modifier when isActive is omitted', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" />);
+
+      const row = container.querySelector('.ds-row');
+      expect(row).not.toHaveClass('ds-row--active');
+      expect(row).not.toHaveAttribute('aria-current');
+    });
+
+    test('does not apply the active modifier when isActive is false', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive={false} />);
+
+      expect(container.querySelector('.ds-row')).not.toHaveClass('ds-row--active');
+    });
+
+    test('keeps clickable behaviour on an active clickable row', async () => {
+      const handleClick = vi.fn();
+      const { container } = render(
+        <Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />,
+      );
+
+      const row = container.querySelector('.ds-row')!;
+      expect(row).toHaveClass('ds-row--active', 'ds-row--clickable');
+      expect(row).toHaveAttribute('tabindex', '0');
+
+      await userEvent.click(screen.getByText('Sarah Okafor'));
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('activates an active clickable row with the keyboard', async () => {
+      const handleClick = vi.fn();
+      render(<Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />);
+
+      await userEvent.tab();
+      await userEvent.keyboard('{Enter}');
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('combines the active modifier with a custom className', () => {
+      const { container } = render(<Row label="Guardian" className="custom-row" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row', 'ds-row--active', 'custom-row');
+    });
+  });
+
   describe('placeholder behaviour', () => {
     test('renders placeholder text when no value is provided', () => {
       render(<Row label="Medical condition" placeholder="Not recorded" />);

package/src/components/row/Row.tsx

@@ -13,6 +13,7 @@ export type RowProps = {
   note?: ReactNode;
   placeholder?: string;
   tooltipText?: string;
+  isActive?: boolean;
   onClick?: MouseEventHandler<HTMLDivElement>;
 };
 
@@ -26,6 +27,7 @@ export const Row = (props: RowProps) => {
     note,
     placeholder,
     tooltipText,
+    isActive = false,
     onClick,
   } = props;
 
@@ -47,10 +49,12 @@ export const Row = (props: RowProps) => {
         'ds-row',
         {
           'ds-row--clickable': isClickable,
+          'ds-row--active': isActive,
         },
         className,
       )}
       style={style}
+      aria-current={isActive ? 'true' : undefined}
       onClick={onClick}
       onKeyDown={(e) => {
         if (isClickable && [ENTER_KEY, SPACE_KEY].includes(e.key)) {

package/src/components/row/row.scss

@@ -11,7 +11,6 @@
   .ds-row__icon-click {
     flex-shrink: 0;
     stroke: var(--section-list-row-default-color-icon-arrow);
-    
 
     &.ds-icon-arrow-right {
       display: none;
@@ -26,6 +25,11 @@
     }
   }
 
+  &--active,
+  &--active:hover {
+    background-color: var(--section-list-row-active-active-bg);
+  }
+
   &:focus {
     box-shadow: 0 0 0 3px var(--color-brand-300);
     outline: none;
@@ -34,7 +38,6 @@
   &:hover {
     .ds-row__icon-click {
         stroke: var(--section-list-row-hover-color-icon-arrow);
-      
 
       &.ds-icon-chevron-right {
         display: none;

package/src/utils/hooks/useIsControlledOnceSet.test.ts

@@ -0,0 +1,44 @@
+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 as Date | 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 as Date | 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) as Date | undefined } },
+    );
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/utils/hooks/useIsControlledOnceSet.ts

@@ -0,0 +1,13 @@
+import { useRef } from 'react';
+
+/**
+ * Treats a component as controlled from the first render that receives a `value`, so a later
+ * `undefined` means "controlled and empty" rather than reverting to uncontrolled.
+ */
+export const useIsControlledOnceSet = <T>(value: T | undefined) => {
+  const hasReceivedValueRef = useRef(value !== undefined);
+  if (value !== undefined) {
+    hasReceivedValueRef.current = true;
+  }
+  return hasReceivedValueRef.current;
+};