@arbor-education/design-system.components 0.8.0 → 0.9.0

package/src/components/combobox/ComboboxTrigger.tsx

@@ -2,7 +2,7 @@ import classNames from 'classnames';
 import { Icon } from 'Components/icon/Icon';
 import { Tag } from 'Components/tag/Tag';
 import { Popover } from 'radix-ui';
-import type { ComboboxAriaInvalid, ComboboxOption } from './types';
+import type { ComboboxAriaInvalid, ComboboxOption, ComboboxSelectedValueDisplay } from './types';
 
 export type ComboboxTriggerProps = {
   'inputRef': React.RefObject<HTMLInputElement | null>;
@@ -21,6 +21,8 @@ export type ComboboxTriggerProps = {
   'aria-invalid'?: ComboboxAriaInvalid;
   'aria-label'?: string;
   'showDropdownTrigger': boolean;
+  'selectedValueDisplay': ComboboxSelectedValueDisplay;
+  'triggerEndContent'?: React.ReactNode;
   'selectedChips': ComboboxOption[];
   'selectedChipValuesSet': Set<string>;
   'focusedChipIndex': number | null;
@@ -52,6 +54,8 @@ export const ComboboxTrigger = (props: ComboboxTriggerProps): React.JSX.Element
     'aria-invalid': ariaInvalid,
     'aria-label': ariaLabel,
     showDropdownTrigger,
+    selectedValueDisplay,
+    triggerEndContent,
     selectedChips,
     selectedChipValuesSet,
     focusedChipIndex,
@@ -65,6 +69,12 @@ export const ComboboxTrigger = (props: ComboboxTriggerProps): React.JSX.Element
     handleChevronClick,
   } = props;
 
+  const selectedValueText = selectedChips.map(resolveTagLabel).join(', ');
+  const showSelectedValueText
+    = selectedValueDisplay === 'text'
+      && query.length === 0
+      && selectedValueText.length > 0;
+
   return (
     <Popover.Anchor asChild>
       <div
@@ -77,23 +87,32 @@ export const ComboboxTrigger = (props: ComboboxTriggerProps): React.JSX.Element
         onClick={handleTriggerClick}
       >
         <div className="ds-combobox__chips-and-input">
-          {selectedChips.map((opt, chipIdx) => (
-            <Tag
-              key={opt.value}
-              color="neutral"
-              selected={selectedChipValuesSet.has(opt.value) || focusedChipIndex === chipIdx}
-              slotStart={opt.iconName ? <Icon name={opt.iconName} size={12} /> : undefined}
-              onRemove={disabled ? undefined : () => removeValue(opt.value)}
-              removeLabel={`Remove ${resolveTagLabel(opt)}`}
-              removeButtonTabIndex={-1}
-            >
-              {resolveTagLabel(opt)}
-            </Tag>
-          ))}
+          {selectedValueDisplay === 'tags'
+            ? selectedChips.map((opt, chipIdx) => (
+                <Tag
+                  key={opt.value}
+                  color="neutral"
+                  selected={selectedChipValuesSet.has(opt.value) || focusedChipIndex === chipIdx}
+                  slotStart={opt.iconName ? <Icon name={opt.iconName} size={12} /> : undefined}
+                  onRemove={disabled ? undefined : () => removeValue(opt.value)}
+                  removeLabel={`Remove ${resolveTagLabel(opt)}`}
+                  removeButtonTabIndex={-1}
+                >
+                  {resolveTagLabel(opt)}
+                </Tag>
+              ))
+            : null}
+          {showSelectedValueText && (
+            <span className="ds-combobox__selected-value">
+              {selectedValueText}
+            </span>
+          )}
           <input
             ref={inputRef}
             id={comboboxId}
-            className="ds-combobox__input"
+            className={classNames('ds-combobox__input', {
+              'ds-combobox__input--with-selected-value': showSelectedValueText,
+            })}
             type="text"
             role="combobox"
             aria-autocomplete="list"
@@ -114,6 +133,11 @@ export const ComboboxTrigger = (props: ComboboxTriggerProps): React.JSX.Element
             autoComplete="off"
           />
         </div>
+        {triggerEndContent && (
+          <span className="ds-combobox__end-content" aria-hidden="true">
+            {triggerEndContent}
+          </span>
+        )}
         {showDropdownTrigger && (
           <button
             type="button"

package/src/components/combobox/combobox.scss

@@ -88,6 +88,13 @@
   white-space: nowrap;
 }
 
+.ds-combobox__button-value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .ds-combobox__button-ellipsis {
   flex-shrink: 0;
   font-size: var(--font-size-medium);
@@ -127,6 +134,10 @@
   }
 }
 
+.ds-combobox__input--with-selected-value {
+  min-width: 1ch;
+}
+
 // Chevron
 .ds-combobox__chevron {
   flex-shrink: 0;
@@ -144,6 +155,13 @@
   }
 }
 
+.ds-combobox__end-content {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
 // Popover
 .ds-combobox__popover {
   min-width: var(--radix-popper-anchor-width);

package/src/components/combobox/types.ts

@@ -16,6 +16,7 @@ export type ComboboxOption = {
 export type ComboboxCreateResult = string | ComboboxOption | void;
 export type ComboboxSearchFn = (option: ComboboxOption, query: string) => boolean;
 export type ComboboxSearchType = 'prefix' | 'substring' | ComboboxSearchFn;
+export type ComboboxSelectedValueDisplay = 'tags' | 'text';
 
 export type ComboboxProps = {
   'options': ComboboxOption[];
@@ -36,7 +37,9 @@ export type ComboboxProps = {
   'disabled'?: boolean;
   'dropdownOnFocus'?: boolean;
   'triggerVariant'?: 'input' | 'button';
+  'selectedValueDisplay'?: ComboboxSelectedValueDisplay;
   'showDropdownTrigger'?: boolean;
+  'triggerEndContent'?: React.ReactNode;
   'showSelectionCountBadge'?: boolean;
   'selectionCountA11yLabel'?: string | ((count: number) => string);
   'loading'?: boolean;

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

@@ -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');

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/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.');

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

@@ -0,0 +1,86 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { TimeInput } from './TimeInput';
+
+describe('TimeInput', () => {
+  beforeEach(() => {
+    globalThis.ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    } as unknown as typeof ResizeObserver;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('renders a native time input by default', () => {
+    render(<TimeInput aria-label="Start time" />);
+    const input = screen.getByLabelText('Start time');
+
+    expect(input).toHaveAttribute('type', 'time');
+    expect(input).toHaveAttribute('step', '60');
+  });
+
+  test('uses one-second stepping when granularity is second', () => {
+    render(<TimeInput aria-label="Start time" granularity="second" />);
+    expect(screen.getByLabelText('Start time')).toHaveAttribute('step', '1');
+  });
+
+  test('native mode emits the string value when changed', () => {
+    const onValueChange = vi.fn();
+    render(<TimeInput aria-label="Start time" onValueChange={onValueChange} />);
+
+    fireEvent.change(screen.getByLabelText('Start time'), {
+      target: { value: '14:30' },
+    });
+
+    expect(onValueChange).toHaveBeenCalledWith('14:30');
+  });
+
+  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(() => {});
+
+    render(<TimeInput aria-label="Start time" />);
+
+    await user.click(screen.getByRole('button', { name: 'Select time' }));
+
+    expect(screen.getByLabelText('Start time')).toHaveFocus();
+    expect(setSelectionRange).toHaveBeenCalledWith(0, 2);
+  });
+
+  test('options mode renders the combobox-backed time list with plain text selection', () => {
+    render(
+      <TimeInput
+        aria-label="Start time"
+        options={['13:00', '13:30', '14:00']}
+        value="13:30"
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Start time' })).toHaveTextContent('13:30');
+    expect(document.querySelector('.ds-tag')).not.toBeInTheDocument();
+  });
+
+  test('options mode emits the selected allowed time', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    render(
+      <TimeInput
+        aria-label="Start time"
+        options={['13:00', '13:30', '14:00']}
+        onValueChange={onValueChange}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Start time' }));
+    await user.click(screen.getByText('13:30'));
+
+    expect(onValueChange).toHaveBeenCalledWith('13:30');
+  });
+});

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

@@ -0,0 +1,168 @@
+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';
+
+/** Expected string `HH:MM` or `HH:MM:SS`; format-shaped versus strict time validation. */
+export type TimeValue = `${string}:${string}` | `${string}:${string}:${string}`;
+export type TimeGranularity = 'minute' | 'second';
+
+export type TimeInputProps = {
+  options?: TimeValue[];
+  granularity?: TimeGranularity;
+  hasError?: boolean;
+  onValueChange?: (value: string) => void;
+  searchType?: ComboboxSearchType;
+  highlightStringMatches?: boolean;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'defaultValue' | 'size' | 'type' | 'value'> & {
+  value?: TimeValue | '';
+  defaultValue?: TimeValue | '';
+};
+
+const clockIcon = <Icon name="clock-3" size={16} />;
+
+/** 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 {
+    options,
+    granularity = 'minute',
+    hasError = false,
+    onValueChange,
+    searchType = 'prefix',
+    highlightStringMatches = false,
+    onChange,
+    className,
+    disabled = false,
+    id,
+    name,
+    placeholder,
+    value: controlledValue,
+    defaultValue = '',
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    'aria-label': ariaLabel,
+    ...rest
+  } = props;
+
+  const isControlled = controlledValue !== undefined;
+  const [internalValue, setInternalValue] = useState<string>(defaultValue);
+  const currentValue = isControlled ? controlledValue ?? '' : internalValue;
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const setRefs = useCallback((node: HTMLInputElement | null) => {
+    inputRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    }
+    else if (ref) {
+      ref.current = node;
+    }
+  }, [ref]);
+
+  const updateValue = useCallback((nextValue: string, nativeEvent?: ChangeEvent<HTMLInputElement>) => {
+    if (!isControlled) {
+      setInternalValue(nextValue);
+    }
+    onValueChange?.(nextValue);
+    if (nativeEvent) {
+      onChange?.(nativeEvent);
+      return;
+    }
+    // Combobox-driven updates only provide compatibility with common form handlers.
+    onChange?.({
+      currentTarget: { value: nextValue } as EventTarget & HTMLInputElement,
+      target: { value: nextValue } as EventTarget & HTMLInputElement,
+    } as ChangeEvent<HTMLInputElement>);
+  }, [isControlled, onChange, onValueChange]);
+
+  const handleNativeChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+    updateValue(event.currentTarget.value, event);
+  }, [updateValue]);
+
+  const focusAndSelectHours = useCallback(() => {
+    const input = inputRef.current;
+    if (!input) return;
+
+    input.focus();
+
+    try {
+      input.setSelectionRange(0, 2);
+    }
+    catch {
+      // Some browsers do not expose selection APIs on time inputs.
+    }
+  }, []);
+
+  const timeOptions = useMemo<ComboboxOption[]>(
+    () => (options ?? []).map(time => ({ value: time, label: time })),
+    [options],
+  );
+
+  const selectedTimeValue = options?.includes(currentValue as TimeValue) ? [currentValue] : [];
+
+  const handleTimeListChange = useCallback((values: string[]) => {
+    const nextValue = values[0] ?? '';
+    updateValue(nextValue);
+  }, [updateValue]);
+
+  if (options) {
+    return (
+      <div className={classNames('ds-time-input', className)}>
+        {name && <input type="hidden" name={name} value={selectedTimeValue[0] ?? ''} />}
+        <Combobox
+          id={id}
+          options={timeOptions}
+          value={selectedTimeValue}
+          onValueChange={handleTimeListChange}
+          searchType={searchType}
+          highlightStringMatches={highlightStringMatches}
+          placeholder={placeholder ?? 'Select time'}
+          disabled={disabled}
+          hasError={hasError}
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={ariaInvalid}
+          aria-label={ariaLabel}
+          triggerVariant="button"
+          selectedValueDisplay="text"
+          showDropdownTrigger={false}
+          triggerEndContent={clockIcon}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className={classNames('ds-time-input', className)}>
+      <input
+        {...rest}
+        ref={setRefs}
+        id={id}
+        name={name}
+        type="time"
+        value={currentValue}
+        step={granularity === 'second' ? 1 : 60}
+        disabled={disabled}
+        aria-describedby={ariaDescribedBy}
+        aria-invalid={ariaInvalid}
+        aria-label={ariaLabel}
+        placeholder={placeholder}
+        className={classNames('ds-input', 'ds-input--M', 'ds-time-input__input', {
+          'ds-input--error': hasError,
+        })}
+        onChange={handleNativeChange}
+      />
+      <button
+        type="button"
+        className="ds-time-input__icon-button"
+        onClick={focusAndSelectHours}
+        aria-label="Select time"
+        disabled={disabled}
+      >
+        {clockIcon}
+      </button>
+    </div>
+  );
+});
+
+TimeInput.displayName = 'TimeInput';

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

@@ -0,0 +1,33 @@
+.ds-time-input {
+  position: relative;
+  width: 100%;
+}
+
+.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 {
+  position: absolute;
+  inset-block: 0;
+  inset-inline-end: 0;
+  width: var(--form-field-text-medium-height);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--form-field-icon-default-color-icon);
+  cursor: pointer;
+
+  &:disabled {
+    color: var(--form-field-icon-disabled-color-icon);
+    cursor: not-allowed;
+  }
+}