@arbor-education/design-system.components 0.8.1 → 0.10.0

package/src/components/dateTimePicker/DateTimePicker.tsx

@@ -0,0 +1,293 @@
+import classNames from 'classnames';
+import { Button } from 'Components/button/Button';
+import type { ComboboxSearchType } from 'Components/combobox/types';
+import {
+  formatDateTimeInputValue,
+  formatNativeDateTimeInputValue,
+  formatTimeInputValue,
+  getDateTimePlaceholder,
+  getNativeDateTimePlaceholder,
+  mergeDateAndTime,
+  parseDateTimeInputValue,
+  parseNativeDateTimeInputValue,
+  type DateDisplayFormat,
+  type DateTimePickerDisplayFormat,
+} from 'Components/datePicker/dateInputUtils';
+import { DatePickerCalendarHeader } from 'Components/datePicker/DatePickerCalendarHeader';
+import { TextInput } from 'Components/formField/inputs/text/TextInput';
+import { TimeInput, type TimeGranularity, type TimeValue } from 'Components/formField/inputs/time/TimeInput';
+import { Popover } from 'radix-ui';
+import { useCallback, useContext, useEffect, useRef, useState, type ChangeEvent, type PointerEvent } from 'react';
+import { DayPicker } from 'react-day-picker';
+import { PopupParentContext } from 'Utils/PopupParentContext';
+
+export type DateTimePickerProps = {
+  'className'?: string;
+  'onChange'?: (newDate?: Date) => void;
+  'id'?: string;
+  'hasError'?: boolean;
+  'aria-describedby'?: string;
+  'aria-invalid'?: boolean;
+  'value'?: Date;
+  'defaultValue'?: Date;
+  'granularity'?: TimeGranularity;
+  'displayFormat'?: DateTimePickerDisplayFormat;
+  'timeOptions'?: TimeValue[];
+  'searchType'?: ComboboxSearchType;
+  'highlightStringMatches'?: boolean;
+  'placeholder'?: string;
+};
+
+export const DateTimePicker = (props: DateTimePickerProps) => {
+  const {
+    className,
+    onChange,
+    id,
+    hasError,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    value,
+    defaultValue,
+    displayFormat = 'native',
+    granularity = 'minute',
+    timeOptions,
+    searchType = 'prefix',
+    highlightStringMatches = false,
+    placeholder,
+  } = props;
+
+  const isNative = displayFormat === 'native';
+
+  const formatInputValue = useCallback(
+    (date: Date) =>
+      displayFormat === 'native'
+        ? formatNativeDateTimeInputValue(date, granularity)
+        : formatDateTimeInputValue(date, displayFormat as DateDisplayFormat, granularity),
+    [displayFormat, granularity],
+  );
+
+  const parseInputValue = useCallback(
+    (raw: string) =>
+      displayFormat === 'native'
+        ? parseNativeDateTimeInputValue(raw, granularity)
+        : parseDateTimeInputValue(raw, displayFormat as DateDisplayFormat, granularity),
+    [displayFormat, granularity],
+  );
+
+  const resolvedPlaceholder = placeholder ?? (
+    isNative
+      ? getNativeDateTimePlaceholder(granularity)
+      : getDateTimePlaceholder(displayFormat as DateDisplayFormat, granularity)
+  );
+
+  const initialValue = value ?? defaultValue;
+  const isControlled = value !== undefined;
+  const [month, setMonth] = useState(initialValue ?? new Date());
+  const [selectedDateTime, setSelectedDateTime] = useState<Date | undefined>(initialValue);
+  const [inputValue, setInputValue] = useState(
+    initialValue ? formatInputValue(initialValue) : '',
+  );
+  const [timeInputValue, setTimeInputValue] = useState(initialValue ? formatTimeInputValue(initialValue, granularity) : '');
+  const [isPickerOpen, setIsPickerOpen] = useState(false);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const selectedDateTimeRef = useRef(selectedDateTime);
+  selectedDateTimeRef.current = selectedDateTime;
+
+  const showFieldHint = isNative && selectedDateTime === undefined && inputValue === '';
+  const hasCustomEmptyHint = showFieldHint && placeholder !== undefined;
+
+  /** Custom empty hint in native mode: open only on pointer (not Tab focus). */
+  const onNativeFieldHintPointerDown = (e: PointerEvent<HTMLInputElement>) => {
+    if (hasCustomEmptyHint) {
+      e.preventDefault();
+      setIsPickerOpen(true);
+    }
+  };
+
+  useEffect(() => {
+    if (!isControlled) {
+      return;
+    }
+    const valueTime = value?.getTime();
+    const selectedTime = selectedDateTimeRef.current?.getTime();
+    if (valueTime !== selectedTime) {
+      setSelectedDateTime(value);
+      setMonth(value ?? new Date());
+      setInputValue(value ? formatInputValue(value) : '');
+      setTimeInputValue(value ? formatTimeInputValue(value, granularity) : '');
+    }
+  }, [value, isControlled, granularity, formatInputValue]);
+
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    // Skip reformat on initial mount (`useState` already seeded input/time strings). Only re-run when
+    // `granularity` or `displayFormat` changes after mount.
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    const current = selectedDateTimeRef.current;
+    if (current) {
+      setInputValue(formatInputValue(current));
+      setTimeInputValue(formatTimeInputValue(current, granularity));
+    }
+    else {
+      setInputValue('');
+      setTimeInputValue('');
+    }
+  }, [granularity, displayFormat, formatInputValue]);
+
+  const onInputChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const nextInputValue = event.target.value;
+    setInputValue(nextInputValue);
+
+    const parsedDate = parseInputValue(nextInputValue);
+
+    if (parsedDate) {
+      setSelectedDateTime(parsedDate);
+      setMonth(parsedDate);
+      setTimeInputValue(formatTimeInputValue(parsedDate, granularity));
+      onChange?.(parsedDate);
+    }
+    else {
+      setSelectedDateTime(undefined);
+      onChange?.(undefined);
+    }
+  };
+
+  const handleTimeChange = (nextTimeValue: string) => {
+    setTimeInputValue(nextTimeValue);
+
+    if (!selectedDateTime) {
+      return;
+    }
+
+    const nextDateTime = mergeDateAndTime(selectedDateTime, nextTimeValue, granularity);
+    setSelectedDateTime(nextDateTime);
+    setInputValue(formatInputValue(nextDateTime));
+    onChange?.(nextDateTime);
+  };
+
+  const handleDayPickerSelect = (nextDate?: Date) => {
+    if (!nextDate) {
+      setSelectedDateTime(undefined);
+      setInputValue('');
+      setIsPickerOpen(false);
+      onChange?.(undefined);
+      return;
+    }
+
+    const nextDateTime = mergeDateAndTime(nextDate, timeInputValue, granularity);
+    setSelectedDateTime(nextDateTime);
+    setMonth(nextDateTime);
+    setInputValue(formatInputValue(nextDateTime));
+    // UX trade-off: closing here means the user must reopen the popover to set time if they picked the day first.
+    // Alternatives (keep open until time is chosen) are a deliberate product change.
+    setIsPickerOpen(false);
+    onChange?.(nextDateTime);
+  };
+
+  const handleTodayClick = () => {
+    const nextDate = mergeDateAndTime(new Date(), timeInputValue, granularity);
+    setSelectedDateTime(nextDate);
+    setMonth(nextDate);
+    setInputValue(formatInputValue(nextDate));
+    setIsPickerOpen(false);
+    onChange?.(nextDate);
+  };
+
+  const popupParentRef = useContext(PopupParentContext);
+
+  return (
+    <div className={classNames('ds-date-time-picker', className)}>
+      <div
+        className={classNames(
+          'ds-date-time-picker__field',
+          { 'ds-date-time-picker__field--show-hint': showFieldHint },
+        )}
+      >
+        <TextInput
+          ref={inputRef}
+          type={isNative ? 'datetime-local' : 'text'}
+          value={inputValue}
+          onChange={onInputChange}
+          onPointerDown={onNativeFieldHintPointerDown}
+          readOnly={hasCustomEmptyHint}
+          id={id}
+          step={isNative ? (granularity === 'second' ? 1 : 60) : undefined}
+          placeholder={showFieldHint ? '' : resolvedPlaceholder}
+          hasError={hasError}
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={ariaInvalid}
+          className="ds-date-time-picker__input"
+        />
+        {showFieldHint
+          ? (
+              <span className="ds-date-time-picker__field-hint" aria-hidden="true">
+                {resolvedPlaceholder}
+              </span>
+            )
+          : null}
+      </div>
+      <Popover.Root open={isPickerOpen} onOpenChange={open => setIsPickerOpen(open)}>
+        <Popover.Trigger asChild>
+          <Button
+            className="ds-date-time-picker__button"
+            variant="text-link"
+            iconLeftName="date"
+            iconLeftScreenReaderText="Open date and time picker"
+          />
+        </Popover.Trigger>
+        <Popover.Portal container={popupParentRef.current}>
+          <Popover.Content
+            align="end"
+            sideOffset={5}
+            onOpenAutoFocus={e => e.preventDefault()}
+            onCloseAutoFocus={(e) => {
+              e.preventDefault();
+              inputRef.current?.focus();
+            }}
+          >
+            <div className="ds-date-time-picker__popup">
+              <TimeInput
+                className="ds-date-time-picker__time"
+                aria-label="Select time"
+                value={timeInputValue as TimeValue | ''}
+                onValueChange={handleTimeChange}
+                granularity={granularity}
+                options={timeOptions}
+                searchType={searchType}
+                highlightStringMatches={highlightStringMatches}
+                hasError={hasError}
+              />
+              <DatePickerCalendarHeader month={month} onMonthChange={setMonth} />
+              <DayPicker
+                className="ds-date-time-picker__calendar"
+                month={month}
+                onMonthChange={setMonth}
+                autoFocus
+                role="application"
+                mode="single"
+                selected={selectedDateTime}
+                onSelect={handleDayPickerSelect}
+                hideNavigation
+                footer={(
+                  <Button
+                    variant="text-link"
+                    onClick={handleTodayClick}
+                    className="ds-date-time-picker__today-button"
+                  >
+                    Today
+                  </Button>
+                )}
+              />
+            </div>
+          </Popover.Content>
+        </Popover.Portal>
+      </Popover.Root>
+    </div>
+  );
+};
+
+export type { DateTimePickerDisplayFormat } from 'Components/datePicker/dateInputUtils';

package/src/components/dateTimePicker/dateTimePicker.scss

@@ -0,0 +1,17 @@
+@use "../datePicker/date-field-hint" as shell;
+
+.ds-date-time-picker {
+  position: relative;
+  min-width: 0;
+
+  @include shell.ds-date-picker-shell-field("date-time-picker");
+  @include shell.ds-date-picker-shell-button("date-time-picker");
+}
+
+@include shell.ds-date-picker-shell-popup("date-time-picker");
+
+.ds-date-time-picker__time {
+  width: 100%;
+}
+
+@include shell.ds-date-picker-shell-calendar("date-time-picker");

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

@@ -42,7 +42,7 @@ export const Default = {
     },
     'inputType': {
       control: 'select',
-      options: ['text', 'textarea', 'number', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
+      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
       description: 'Input type',
     },
     'inputProps.size': {
@@ -114,6 +114,15 @@ export const FormExample: Story = {
           placeholder: 'Enter your age',
         }}
       />
+      <FormField
+        id="start-time"
+        label="Start time"
+        inputType="time"
+        inputProps={{
+          'aria-label': 'Start time',
+          'defaultValue': '14:30',
+        }}
+      />
       <FormField
         id="colour-dropdown"
         label="Colour"

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

@@ -1,7 +1,7 @@
-import { expect, test, describe } from 'vitest';
-import { FormField } from './FormField';
-import { render, screen } from '@testing-library/react';
 import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { FormField } from './FormField';
 
 describe('FormField component', () => {
   test('renders a form field', () => {
@@ -45,6 +45,12 @@ describe('FormField component', () => {
     expect(input).toHaveClass('ds-number-input');
   });
 
+  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');
+  });
+
   test('renders a colour picker dropdown when inputType is colourPicker', () => {
     render(<FormField id="niceid" inputType="colourPicker" />);
     const input = screen.getByRole('button');
@@ -58,8 +64,8 @@ describe('FormField component', () => {
   });
 
   test('renders a date picker when inputType is datePicker', () => {
-    render(<FormField id="niceid" inputType="datePicker" />);
-    expect(screen.getByRole('textbox')).toBeInTheDocument();
+    const { container } = render(<FormField id="niceid" inputType="datePicker" />);
+    expect(container.querySelector('input[type="date"]')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Open date picker' })).toBeInTheDocument();
   });
 

package/src/components/formField/FormField.tsx

@@ -7,6 +7,7 @@ import { ColourPickerDropdown, type ColourPickerDropdownProps } from './inputs/c
 import { NumberInput, type NumberInputProps } from './inputs/number/NumberInput';
 import { SelectDropdown, type SelectDropdownInputProps } from './inputs/selectDropdown/SelectDropdown';
 import { TextInput, type TextInputProps } from './inputs/text/TextInput';
+import { TimeInput, type TimeInputProps } from './inputs/time/TimeInput';
 import { TextArea, type TextAreaProps } from './inputs/textArea/TextArea';
 import { Label } from './label/Label';
 
@@ -22,6 +23,7 @@ type FormFieldProps = {
   | { inputType?: 'text'; inputProps?: TextInputProps }
   | { inputType?: 'textarea'; inputProps?: TextAreaProps }
   | { inputType?: 'number'; inputProps?: NumberInputProps }
+  | { inputType?: 'time'; inputProps?: TimeInputProps }
   | { inputType?: 'colourPicker'; inputProps?: ColourPickerDropdownProps }
   | { inputType?: 'selectDropdown'; inputProps?: SelectDropdownInputProps }
   | { inputType?: 'datePicker'; inputProps?: DatePickerProps }
@@ -65,6 +67,9 @@ export const FormField = (props: FormFieldProps) => {
       {inputType === 'number' && (
         <NumberInput {...sharedProps} {...(inputProps as NumberInputProps)} />
       )}
+      {inputType === 'time' && (
+        <TimeInput {...sharedProps} {...(inputProps as TimeInputProps)} />
+      )}
       {inputType === 'colourPicker' && (
         <ColourPickerDropdown {...sharedProps} {...(inputProps as ColourPickerDropdownProps)} />
       )}

package/src/components/formField/inputs/selectDropdown/SelectDropdown.test.tsx

@@ -182,4 +182,32 @@ describe('SelectDropdown component', () => {
     expect(await screen.findByText('Option 1')).toBeInTheDocument();
     expect(screen.getByText('header1')).toBeInTheDocument();
   });
+
+  test('updates the rendered selection when controlled selectedValues change', () => {
+    const { rerender } = render(
+      <SelectDropdown
+        options={[
+          { label: 'June', value: '5' },
+          { label: 'July', value: '6' },
+        ]}
+        selectedValues={['5']}
+        onSelectionChange={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: /june/i })).toBeInTheDocument();
+
+    rerender(
+      <SelectDropdown
+        options={[
+          { label: 'June', value: '5' },
+          { label: 'July', value: '6' },
+        ]}
+        selectedValues={['6']}
+        onSelectionChange={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: /july/i })).toBeInTheDocument();
+  });
 });

package/src/components/formField/inputs/selectDropdown/SelectDropdown.tsx

@@ -16,6 +16,7 @@ export type SelectDropdownInputProps = {
   'id'?: string;
   'alwaysShowPlaceholder'?: boolean;
   'initialSelectedValues'?: string[];
+  'selectedValues'?: string[];
   'open'?: boolean;
   'onOpenChange'?: (open: boolean) => void;
 };
@@ -33,11 +34,14 @@ export const SelectDropdown = (props: SelectDropdownInputProps) => {
     'aria-invalid': ariaInvalid,
     alwaysShowPlaceholder = false,
     initialSelectedValues = [],
+    selectedValues: controlledSelectedValues,
     open,
     onOpenChange,
   } = props;
 
-  const [selectedValues, setSelectedValues] = useState<string[]>(initialSelectedValues);
+  const isControlled = controlledSelectedValues !== undefined;
+  const [internalSelectedValues, setInternalSelectedValues] = useState<string[]>(initialSelectedValues);
+  const selectedValues = isControlled ? controlledSelectedValues : internalSelectedValues;
   const [renderedSelectContent, setRenderedSelectContent] = useState('');
   const selectedValuesRef = useRef(selectedValues);
   selectedValuesRef.current = selectedValues;
@@ -90,7 +94,9 @@ export const SelectDropdown = (props: SelectDropdownInputProps) => {
     else {
       nextValues = [...prev, value];
     }
-    setSelectedValues(nextValues);
+    if (!isControlled) {
+      setInternalSelectedValues(nextValues);
+    }
     onSelectionChange?.(nextValues);
   };
 

package/src/components/formField/inputs/text/TextInput.tsx

@@ -1,12 +1,12 @@
 import classNames from 'classnames';
-import { type InputHTMLAttributes } from 'react';
+import { forwardRef, type InputHTMLAttributes } from 'react';
 
 export type TextInputProps = {
   size?: 'M' | 'S';
   hasError?: boolean;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>;
 
-export const TextInput = (props: TextInputProps) => {
+export const TextInput = forwardRef<HTMLInputElement, TextInputProps>((props, ref) => {
   const {
     size = 'M',
     hasError,
@@ -27,9 +27,12 @@ export const TextInput = (props: TextInputProps) => {
 
   return (
     <input
+      ref={ref}
       className={inputClasses}
       disabled={disabled}
       {...rest}
     />
   );
-};
+});
+
+TextInput.displayName = 'TextInput';

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

@@ -0,0 +1,170 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from 'Components/button/Button';
+import { useEffect, useState } from 'react';
+import { fn } from 'storybook/test';
+import { TimeInput, type TimeInputProps, type TimeValue } from './TimeInput';
+
+const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'] as const;
+
+const meta = {
+  title: 'Components/FormField/Inputs/TimeInput',
+  component: TimeInput,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '`TimeInput` supports both native time entry and a combobox-backed time list. When you pass `value`, treat it as a controlled component and update it in `onValueChange`; use `defaultValue` for uncontrolled usage.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  args: {
+    onValueChange: fn(),
+  },
+  argTypes: {
+    granularity: {
+      control: 'inline-radio',
+      options: ['minute', 'second'],
+      description: 'Controls whether the native time input works in minute or second increments.',
+    },
+    options: {
+      control: 'object',
+      description: 'When provided, `TimeInput` switches from native `input[type="time"]` to the combobox-backed time list mode.',
+    },
+    value: {
+      control: 'text',
+      description: 'Controlled value. If you provide this, update it from `onValueChange` in your app or story state.',
+    },
+    defaultValue: {
+      control: 'text',
+      description: 'Uncontrolled initial value. Use this when you want the component to manage its own state.',
+    },
+    onValueChange: {
+      action: 'value changed',
+      description: 'Called with the next string value (`HH:MM` or `HH:MM:SS`).',
+    },
+  },
+} satisfies Meta<typeof TimeInput>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+const ControlledTimeInput = (args: TimeInputProps) => {
+  const [value, setValue] = useState<TimeValue | ''>(args.value ?? args.defaultValue ?? '');
+
+  useEffect(() => {
+    setValue(args.value ?? args.defaultValue ?? '');
+  }, [args.defaultValue, args.value]);
+
+  return (
+    <TimeInput
+      {...args}
+      value={value}
+      onValueChange={(nextValue) => {
+        setValue(nextValue as TimeValue | '');
+        args.onValueChange?.(nextValue);
+      }}
+    />
+  );
+};
+
+const NativeValidationDemo = (args: TimeInputProps) => {
+  const [value, setValue] = useState<TimeValue | ''>(args.value ?? '');
+
+  useEffect(() => {
+    setValue(args.value ?? '');
+  }, [args.value]);
+
+  return (
+    <form
+      style={{ display: 'grid', gap: 12, width: 280 }}
+      onSubmit={(event) => {
+        event.preventDefault();
+        const form = event.currentTarget;
+        if (!form.reportValidity()) {
+          return;
+        }
+      }}
+    >
+      <TimeInput
+        {...args}
+        value={value}
+        onValueChange={(nextValue) => {
+          setValue(nextValue as TimeValue | '');
+          args.onValueChange?.(nextValue);
+        }}
+      />
+      <Button variant="primary" size="M" type="submit">
+        Submit
+      </Button>
+    </form>
+  );
+};
+
+export const NativeMinute: Story = withDescription({
+  args: {
+    value: '14:30',
+    granularity: 'minute',
+  },
+  render: args => <ControlledTimeInput {...args} />,
+}, 'Controlled native time input in minute mode. This story keeps local state on purpose to demonstrate the correct `value` + `onValueChange` integration pattern.');
+
+export const NativeSecond: Story = withDescription({
+  args: {
+    value: '14:30:15',
+    granularity: 'second',
+  },
+  render: args => <ControlledTimeInput {...args} />,
+}, 'Controlled native time input in second mode, showing the same parent-managed state pattern with `HH:MM:SS` values.');
+
+export const NativeWithBounds: Story = withDescription({
+  args: {
+    value: '08:30',
+    granularity: 'minute',
+    min: '09:00',
+    max: '17:30',
+  },
+  render: args => <NativeValidationDemo {...args} />,
+}, 'Demonstrates the browser-native min/max validation flow. Enter a time outside the allowed range and submit the form to let the browser show its own native validation message.');
+
+export const TimeList: Story = withDescription({
+  args: {
+    options: [...timeOptions],
+    value: '10:00',
+    placeholder: 'Select time',
+  },
+  render: args => <ControlledTimeInput {...args} />,
+}, 'Controlled time-list mode using the combobox-backed variant. Selecting a time updates the local story state the same way an app component would.');
+
+export const TimeListHighlightedMatches: Story = withDescription({
+  args: {
+    options: [...timeOptions],
+    value: '',
+    placeholder: 'Search times',
+    searchType: 'substring',
+    highlightStringMatches: true,
+  },
+  render: args => <ControlledTimeInput {...args} />,
+}, 'Combobox-backed time-list mode with substring matching and highlighted text so consumers can review how search behaves when users type partial time fragments such as `30`.');
+
+export const UncontrolledNative: Story = withDescription({
+  args: {
+    defaultValue: '09:30',
+    granularity: 'minute',
+  },
+}, 'Uncontrolled native usage using `defaultValue`. This is useful when the parent does not need to drive the current value after initial render.');