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

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

@@ -9,6 +9,33 @@ describe('FormField component', () => {
     expect(screen.getByLabelText('Email')).toBeInTheDocument();
   });
 
+  test('appends the optional suffix to the label when optional is true', () => {
+    render(<FormField label="Middle name" id="niceid" optional />);
+    expect(screen.getByLabelText('Middle name (optional)')).toBeInTheDocument();
+  });
+
+  test('leaves the label unchanged when optional is false', () => {
+    render(<FormField label="Surname" id="niceid" optional={false} />);
+    expect(screen.getByLabelText('Surname')).toBeInTheDocument();
+    expect(screen.queryByText(/optional/)).not.toBeInTheDocument();
+  });
+
+  test('leaves the label unchanged when optional is not provided', () => {
+    render(<FormField label="Surname" id="niceid" />);
+    expect(screen.getByLabelText('Surname')).toBeInTheDocument();
+    expect(screen.queryByText(/optional/)).not.toBeInTheDocument();
+  });
+
+  test('does not render an asterisk for fields that are not optional', () => {
+    render(<FormField label="Surname" id="niceid" />);
+    expect(screen.queryByText(/\*/)).not.toBeInTheDocument();
+  });
+
+  test('still passes native required from inputProps to the input', () => {
+    render(<FormField label="Surname" id="niceid" inputProps={{ required: true }} />);
+    expect(screen.getByLabelText('Surname')).toBeRequired();
+  });
+
   test('renders helper link when provided', () => {
     render(<FormField helperLinkText="This is helper text" helperLinkUrl="https://www.google.com" inputProps={{ placeholder: 'Enter text' }} />);
     expect(screen.getByText('This is helper text')).toBeInTheDocument();
@@ -48,7 +75,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/FormField.tsx

@@ -39,6 +39,7 @@ export type FormFieldProps = {
   helperLinkText?: string;
   helperLinkUrl?: string;
   errorText?: string;
+  optional?: boolean;
 } & (
   | { inputType?: 'text'; inputProps?: TextInput.Props }
   | { inputType?: 'textarea'; inputProps?: TextArea.Props }
@@ -58,7 +59,7 @@ export type FormFieldProps = {
 );
 
 export const FormField = (props: FormFieldProps) => {
-  const { className, label, id, inputType = 'text', helperLinkText, helperLinkUrl, errorText, inputProps, fieldDescription } = props;
+  const { className, label, id, inputType = 'text', helperLinkText, helperLinkUrl, errorText, inputProps, fieldDescription, optional } = props;
   const classes = classNames('ds-form-field', className);
   const describedByIds = [];
   if (fieldDescription) {
@@ -81,7 +82,7 @@ export const FormField = (props: FormFieldProps) => {
     <div className={classes}>
       {label && (
         <Label htmlFor={id} id={labelId}>
-          {label}
+          {optional ? `${label} (optional)` : label}
         </Label>
       )}
       {fieldDescription && (

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;

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

@@ -20,10 +20,11 @@ const DESCRIPTION_INTRO = [
   'TimeInput is a flexible time-entry field that operates in **two distinct modes** depending on',
   'whether the `options` prop is supplied.',
   '',
-  '**Native mode** (no `options`) renders a browser-native `<input type="time">` decorated with a',
-  'clock icon. The browser handles the picker UI, spin-button keyboard navigation, and locale-aware',
-  'display. This mode supports `min`, `max`, `granularity`, `className`, a forwarded `ref`, and the',
-  'native `onChange` event.',
+  '**Native mode** (no `options`) renders a plain text field decorated with a clock icon. Typed input is',
+  'limited to digits and colons, so no browser time picker appears and every browser shows the same',
+  'single control. Like the other input components, it does not validate the value: range checks and',
+  'error messages belong to the consuming code, which presents them through `hasError` and `aria-invalid`.',
+  'This mode supports `granularity`, `className`, a forwarded `ref`, and `onChange`.',
   '',
   '**Combobox mode** (`options` provided) replaces the native input with a searchable Combobox.',
   'The user can type to filter or click to select from a predefined list of time values. This mode',
@@ -37,8 +38,8 @@ const DESCRIPTION_INTRO = [
 const USAGE_GUIDANCE = [
   '### When to use',
   '',
-  '- **Any valid time** — use native mode (the default). The browser enforces valid time entry and',
-  '  supports `min`/`max` bounds for school hours (e.g. `min="08:00" max="17:00"`).',
+  '- **Free-text time entry** — use native mode (the default). Validate and normalise the typed text in',
+  '  your own code, and present errors with `hasError` and `aria-invalid`.',
   '- **Fixed set of allowed times** — use combobox mode with `options`. Ideal for lesson periods,',
   '  appointment slots, or any scenario where only specific times are valid.',
   '- **Inside a form** — always wrap in `<FormField inputType="time">` so label, error text, and',
@@ -52,7 +53,7 @@ const USAGE_GUIDANCE = [
   '|---|---|',
   '| Date + time combined | Separate `DateInput` and `TimeInput` fields |',
   '| Free-form duration entry | `TextInput` with format hint |',
-  '| More than ~50 time options | Native mode with `min`/`max` bounds |',
+  '| More than ~50 time options | Native mode, validating the range in your own code |',
   '| Status or category selection | `SelectDropdown` with meaningful labels |',
 ].join('\n');
 
@@ -64,44 +65,46 @@ const DEVELOPER_NOTES = [
   '',
   '| Prop | Native mode | Combobox mode |',
   '|---|---|---|',
-  '| `granularity` | Sets `step={1}` for second-level precision | **Ignored** |',
-  '| `min` / `max` | Restricts picker range | **Ignored** — filter `options` array instead |',
+  '| `granularity` | Sets the placeholder to `HH:mm` or `HH:mm:ss` | **Ignored** |',
+  '| `min` / `max` / `step` | Passed to the `<input>` but a text field ignores them. Enforce ranges in your own code | **Ignored** — filter `options` array instead |',
   '| `className` | Applied to the wrapper `<div>` | **Ignored** |',
-  '| `ref` (forwarded) | Attached to the `<input>` element | **Ignored** |',
+  '| `ref` (forwarded) | Attached to the visible text `<input>` | **Ignored** |',
   '| `onChange` | Native `ChangeEvent<HTMLInputElement>` | **Ignored** — use `onValueChange` |',
   '| `searchType` | **Ignored** | Controls `prefix`/`substring` matching |',
   '| `highlightStringMatches` | **Ignored** | Bolds matched characters in dropdown |',
   '| `onValueChange` | Fires with the string value | Fires with the string value |',
   '',
-  '**`aria-invalid` is NOT automatic.** When using TimeInput standalone (outside FormField),',
-  '`hasError` only applies visual error styling. It does NOT set `aria-invalid`:',
+  '### Validation (native mode)',
+  '',
+  'TimeInput only filters characters: keystrokes and pasted text are limited to digits and colons, so',
+  '`abc` and `9.05` never reach the field. It does not parse, normalise or validate the result, so `25:00`',
+  'is emitted as typed. The component never sets `aria-invalid`, so range validation is the consumer\'s job:',
   '',
   '```tsx',
-  '// Standalone — set aria-invalid yourself:',
-  '<TimeInput hasError aria-invalid={true} aria-label="Start time" />',
+  '// Standalone — validate in your code and present the result:',
+  '<TimeInput hasError={!isValid} aria-invalid={!isValid} aria-label="Start time" value={text} onValueChange={setText} />',
   '',
-  '// Inside FormField — aria-invalid is set automatically when errorText is present:',
-  '<FormField label="Start time" id="start" inputType="time" errorText="Required." inputProps={{}} />',
+  '// Inside FormField — pass errorText and FormField sets hasError and aria-invalid:',
+  '<FormField label="Start time" id="start" inputType="time" errorText="Enter a valid time." inputProps={{}} />',
   '```',
   '',
-  '**`onValueChange` is the preferred callback** — it works in both modes and receives the plain',
-  'string value (`HH:MM` or `HH:MM:SS`). The native `onChange` event is only available in native',
-  'mode and is not forwarded in combobox mode.',
+  '**`onValueChange` is the preferred callback** — it works in both modes and receives the string value.',
+  '`onChange` is only available in native mode and is not forwarded in combobox mode.',
   '',
-  '**`TimeValue` is format-shaped, not strictly validated.** The TypeScript type',
-  '`` `${string}:${string}` `` accepts `"99:99"` without complaint. The browser rejects it at render',
-  'time for `<input type="time">`, but the component itself does no validation.',
+  '**`TimeValue` is format-shaped.** The TypeScript type `` `${string}:${string}` `` accepts any string',
+  'containing a colon, so it does not guarantee a valid time.',
   '',
   '---',
   '',
   '### Accessibility',
   '',
   '- Always provide a visible label via `<FormField>` or `aria-label` / `aria-labelledby`.',
-  '- In native mode, the browser\'s built-in time picker is fully keyboard-navigable (arrow keys',
-  '  cycle through the hour/minute/second segments; AM/PM toggles with A/P).',
+  '- In native mode the field is a text input, so screen readers announce the text exactly as typed.',
+  '  Errors are announced only when the consumer sets `aria-invalid`. The clock button is a labelled',
+  '  button ("Select time") that moves focus to the field and selects the hours.',
   '- In combobox mode, the Combobox component implements the ARIA combobox pattern',
   '  (`role="combobox"`, `aria-expanded`, `aria-activedescendant`).',
-  '- The clock icon is decorative and carries `aria-hidden="true"`.',
+  '- The clock icon is decorative; the clock button is labelled "Select time".',
   '- Pair `hasError` with `aria-invalid={true}` when used standalone — one is visual, the other',
   '  is for screen readers. `<FormField>` handles this automatically when `errorText` is set.',
   '',
@@ -171,7 +174,7 @@ const meta = {
   argTypes: {
     'value': {
       description: [
-        'Controlled value in `HH:MM` or `HH:MM:SS` format.',
+        'Controlled text value, limited to digits and colons. Pass `HH:MM` or `HH:MM:SS` for a time.',
         'Pair with `onValueChange` to keep state in sync.',
         'If `undefined`, the component manages its own state (uncontrolled).',
       ].join(' '),
@@ -194,7 +197,8 @@ const meta = {
     },
     'onValueChange': {
       description: [
-        'Callback fired with the plain string value on every change.',
+        'Callback fired with the plain string value whenever the committed value changes.',
+        'In native mode it is the digits and colons entered, with no parsing or range validation.',
         'Works in **both** native and combobox modes.',
         'Prefer this over the native `onChange` event for cross-mode compatibility.',
       ].join(' '),
@@ -207,8 +211,8 @@ const meta = {
     'options': {
       description: [
         'Array of `TimeValue` strings to display as selectable options.',
-        'Providing this prop switches to **combobox mode** — the native `<input type="time">` is',
-        'replaced by a searchable Combobox. Omit to use the browser-native time picker.',
+        'Providing this prop switches to **combobox mode** — the text field is',
+        'replaced by a searchable Combobox. Omit to type a time into the text field.',
       ].join(' '),
       control: 'object',
       table: {
@@ -219,7 +223,7 @@ const meta = {
     'granularity': {
       description: [
         '**Native mode only.** Controls the precision of the time input.',
-        '`"second"` sets `step={1}` so the seconds segment is visible.',
+        '`"second"` sets the placeholder to `HH:mm:ss`.',
         'Silently ignored when `options` is provided.',
       ].join(' '),
       control: { type: 'select' },
@@ -257,7 +261,7 @@ const meta = {
     'hasError': {
       description: [
         'Applies error-state visual styling (red border).',
-        'Does **not** set `aria-invalid` automatically when used standalone outside FormField.',
+        'Does **not** set `aria-invalid` for errors you supply when used standalone outside FormField.',
         'Always pair with `aria-invalid={true}` for screen-reader coverage.',
       ].join(' '),
       control: 'boolean',
@@ -292,7 +296,7 @@ const meta = {
       },
     },
     'placeholder': {
-      description: 'Placeholder text shown when no value is selected. Most useful in combobox mode.',
+      description: 'Placeholder text shown while the field is empty, e.g. `HH:mm`. It disappears once a value is entered.',
       control: 'text',
       table: {
         type: { summary: 'string' },
@@ -311,8 +315,7 @@ const meta = {
     'aria-invalid': {
       description: [
         'Marks the input as invalid for screen readers.',
-        'Must be set manually when used standalone — FormField sets this automatically',
-        'when `errorText` is provided.',
+        'Never set by TimeInput. Set it when validating the text yourself, or let FormField set it when `errorText` is provided.',
       ].join(' '),
       control: 'boolean',
       table: {
@@ -409,26 +412,6 @@ const GranularitySecondTemplate = () => {
   );
 };
 
-const WithMinMaxBoundsTemplate = () => {
-  const [value, setValue] = useState<TimeValue | ''>('');
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)', maxWidth: '280px' }}>
-      <TimeInput
-        min="08:00"
-        max="17:00"
-        value={value}
-        onValueChange={v => setValue(v as TimeValue | '')}
-        id="bounded-time"
-        name="school-time"
-        aria-label="School hours time"
-      />
-      <p style={{ margin: 0, color: 'var(--color-grey-600)' }}>
-        Restricted to school hours: 08:00 – 17:00
-      </p>
-    </div>
-  );
-};
-
 const WithOptionsTemplate = () => {
   const [value, setValue] = useState<TimeValue | ''>('');
   return (
@@ -697,39 +680,7 @@ export default PreciseTimeInputExample;
     },
     render: () => <GranularitySecondTemplate />,
   },
-  'Setting `granularity="second"` adds a seconds segment to the native time input (`step={1}`). Use this for stopwatch-style timing or precise event logging. **Native mode only** — silently ignored when `options` is provided.',
-);
-
-export const WithMinMaxBounds: Story = withDescription(
-  {
-    parameters: {
-      controls: { disable: true },
-      docs: {
-        source: {
-          language: 'tsx',
-          code: `
-import { TimeInput, type TimeValue } from '@arbor-education/design-system.components';
-
-function BoundedTimeInputExample() {
-  return (
-    <TimeInput
-      min="08:00"
-      max="17:00"
-      id="school-time"
-      name="school-time"
-      aria-label="School hours time"
-    />
-  );
-}
-
-export default BoundedTimeInputExample;
-          `.trim(),
-        },
-      },
-    },
-    render: () => <WithMinMaxBoundsTemplate />,
-  },
-  'The `min` and `max` props restrict the selectable range in the native browser picker to school hours. **Native mode only** — in combobox mode, restrict available times by filtering the `options` array instead.',
+  'Setting `granularity="second"` sets the placeholder to `HH:mm:ss`. Seconds are typed by the user, and only digits and colons are accepted. **Native mode only** — silently ignored when `options` is provided.',
 );
 
 export const WithError: Story = withDescription(