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

package/src/components/datePicker/datePicker.scss

@@ -1,37 +1,61 @@
+@use "./date-field-hint" as shell;
+
 .ds-date-picker {
   position: relative;
+  min-width: 0;
+
+  @include shell.ds-date-picker-shell-field("date-picker");
+  @include shell.ds-date-picker-shell-button("date-picker");
+}
+
+@include shell.ds-date-picker-shell-popup("date-picker");
 
-  .ds-date-picker__button {
-    position: absolute;
-    right: 0;
-    top: 0;
+.ds-date-picker-calendar-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-medium);
+}
+
+.ds-date-picker-calendar-header__selectors {
+  display: flex;
+  gap: var(--spacing-small);
 
-    svg {
-      stroke: var(--form-field-icon-default-color-icon);
-    }
+  > * {
+    min-width: 0;
+    flex: 1 1 0;
   }
 }
 
-.ds-date-picker__popup {
-    box-shadow: var(--shadow-small);
-    padding: var(--date-picker-spacing-vertical) var(--date-picker-spacing-horizontal);
-    border-radius: var(--date-picker-radius);
-    background-color: var(--date-picker-color-background);
-
-    --rdp-accent-color: var(--date-picker-date-cell-today-default-color-text);
-    --rdp-accent-background-color: var(--date-picker-date-cell-today-default-color-background);
-    
-    .rdp-selected {
-      font-size: unset;
-
-      .rdp-day_button{
-        background-color: var(--rdp-accent-background-color);
-      }
-    }
-
-    .rdp-footer {
-      display: flex;
-      justify-content: flex-end;
-    }
+.ds-date-picker-calendar-header__nav {
+  display: flex;
+  gap: var(--spacing-small);
+}
+
+.ds-date-picker-calendar-header__nav-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--form-field-text-medium-height);
+  block-size: var(--form-field-text-medium-height);
+  border: none;
+  border-radius: var(--border-radius-small);
+  background: transparent;
+  color: var(--form-field-icon-default-color-icon);
+  cursor: pointer;
+
+  &:hover {
+    background: var(--color-grey-050);
+  }
+
+  &:focus-visible {
+    outline: var(--focus-border) solid var(--color-brand-500);
+    outline-offset: 0;
   }
-  
+
+  &:focus:not(:focus-visible) {
+    outline: none;
+  }
+}
+
+@include shell.ds-date-picker-shell-calendar("date-picker");

package/src/components/datePicker/datePickerTestUtils.test-helpers.ts

@@ -0,0 +1,6 @@
+/** Test-only; do not barrel-export or import from app/library code. */
+import { screen } from '@testing-library/react';
+
+export const getDropdownTrigger = (name: RegExp) => (
+  screen.getAllByRole('button', { name }).find(button => button.className.includes('ds-button--dropdown'))
+);

package/src/components/dateTimePicker/DateTimePicker.stories.tsx

@@ -0,0 +1,202 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { formatNativeDateTimeInputValue } from 'Components/datePicker/dateInputUtils';
+import { useEffect, useState } from 'react';
+import { fn } from 'storybook/test';
+import { DateTimePicker, type DateTimePickerProps } from './DateTimePicker';
+
+const timeOptions = ['09:00', '09:30', '10:00', '10:30', '11:00'] as const;
+
+const meta = {
+  title: 'Components/DateTimePicker',
+  component: DateTimePicker,
+  decorators: [
+    Story => (
+      <div style={{ maxWidth: '280px', width: '100%' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '`DateTimePicker` combines a date field with the existing `TimeInput`, keeping a single combined `Date` value. `displayFormat="native"` (default) uses a `datetime-local` input with a decorative empty-state hint span (browsers do not reliably show placeholders on native date/time fields). `"default"` and `"friendly"` use a plain text input with locale-style formatting and a real HTML placeholder.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  args: {
+    onChange: fn(),
+  },
+  argTypes: {
+    displayFormat: {
+      control: 'inline-radio',
+      options: ['native', 'default', 'friendly'],
+      description:
+        '`native`: ISO `datetime-local` (default). `default` / `friendly`: plain text field using the same date patterns as `DatePicker` plus time.',
+    },
+    granularity: {
+      control: 'inline-radio',
+      options: ['minute', 'second'],
+      description: 'Controls whether the native `datetime-local` input and embedded time input use minute or second precision.',
+    },
+    timeOptions: {
+      control: 'object',
+      description: 'When provided, the embedded time input switches to list-backed time selection.',
+    },
+    value: {
+      control: false,
+      description: 'Controlled combined datetime value for app-level state.',
+    },
+    defaultValue: {
+      control: false,
+      description: 'Uncontrolled initial combined datetime value.',
+    },
+    onChange: {
+      action: 'changed',
+      description: 'Called with the next combined `Date` value, or `undefined` when the date becomes invalid/cleared.',
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Optional override for the field placeholder (defaults from `displayFormat` and `granularity`).',
+    },
+  },
+} satisfies Meta<typeof DateTimePicker>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const ControlledDateTimePicker = ({
+  showCurrentValue = false,
+  ...args
+}: DateTimePickerProps & { showCurrentValue?: boolean }) => {
+  const [value, setValue] = useState<Date | undefined>(args.value);
+
+  useEffect(() => {
+    setValue(args.value);
+  }, [args.value]);
+
+  return (
+    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 320 }}>
+      <DateTimePicker
+        {...args}
+        value={value}
+        onChange={(nextValue) => {
+          setValue(nextValue);
+          args.onChange?.(nextValue);
+        }}
+      />
+      {showCurrentValue && (
+        <span>
+          Current value:
+          {' '}
+          {value ? formatNativeDateTimeInputValue(value, args.granularity) : 'None'}
+        </span>
+      )}
+    </div>
+  );
+};
+
+export const NativeTime: Story = {
+  args: {
+    value: new Date(2026, 3, 14, 14, 27),
+    granularity: 'minute',
+  },
+  render: args => <ControlledDateTimePicker {...args} />,
+};
+
+export const TimeList: Story = {
+  args: {
+    value: new Date(2026, 3, 14, 10, 0),
+    timeOptions: [...timeOptions],
+  },
+  render: args => <ControlledDateTimePicker {...args} />,
+};
+
+export const ControlledValuePreview: Story = {
+  args: {
+    value: new Date(2026, 3, 14, 14, 27),
+    granularity: 'minute',
+  },
+  render: args => <ControlledDateTimePicker {...args} showCurrentValue />,
+};
+
+export const PlaceholderNativeMinuteHint: Story = {
+  name: 'Placeholder · native minute hint',
+  args: {
+    granularity: 'minute',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Uncontrolled, no initial value — empty-state hint shows `YYYY-MM-DDTHH:mm` (decorative span for native mode).',
+      },
+    },
+  },
+};
+
+export const PlaceholderNativeSecondHint: Story = {
+  name: 'Placeholder · native second hint',
+  args: {
+    granularity: 'second',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Same as the minute story, but with `granularity="second"` so the hint includes seconds.',
+      },
+    },
+  },
+};
+
+export const DisplayFormatDefault: Story = {
+  name: 'Display format · default (text)',
+  args: {
+    displayFormat: 'default',
+    value: new Date(2026, 3, 14, 14, 27),
+    granularity: 'minute',
+  },
+  render: args => <ControlledDateTimePicker {...args} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Combined value is shown and edited as **15/04/2026 14:27** instead of the native ISO string.',
+      },
+    },
+  },
+};
+
+export const DisplayFormatFriendly: Story = {
+  name: 'Display format · friendly (text)',
+  args: {
+    displayFormat: 'friendly',
+    value: new Date(2026, 3, 14, 14, 27),
+    granularity: 'minute',
+  },
+  render: args => <ControlledDateTimePicker {...args} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Combined value uses friendly wording, e.g. **April 14th, 2026 14:27**.',
+      },
+    },
+  },
+};
+
+export const PlaceholderCustomOverride: Story = {
+  name: 'Placeholder · custom copy',
+  args: {
+    granularity: 'minute',
+    placeholder: 'Event start (local)',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pass `placeholder` to replace the default native empty-state hint.',
+      },
+    },
+  },
+  render: args => <ControlledDateTimePicker {...args} />,
+};

package/src/components/dateTimePicker/DateTimePicker.test.tsx

@@ -0,0 +1,295 @@
+import '@testing-library/jest-dom/vitest';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { DateTimePicker } from './DateTimePicker';
+import { getDropdownTrigger } from 'Components/datePicker/datePickerTestUtils.test-helpers';
+
+describe('DateTimePicker', () => {
+  beforeEach(() => {
+    globalThis.ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    } as unknown as typeof ResizeObserver;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('renders a date input and a picker toggle button', () => {
+    const { container } = render(<DateTimePicker />);
+
+    expect(container.querySelector('input[type="datetime-local"]')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Open date and time picker' })).toBeInTheDocument();
+  });
+
+  test('uses a native datetime-local input with minute stepping by default', () => {
+    const { container } = render(<DateTimePicker />);
+    const input = container.querySelector('input[type="datetime-local"]');
+
+    expect(input).toHaveAttribute('step', '60');
+  });
+
+  test('shows default native empty-state hint when empty', () => {
+    const { container } = render(<DateTimePicker />);
+    const input = container.querySelector('input[type="datetime-local"]');
+    expect(input).toHaveAttribute('placeholder', '');
+    expect(screen.getByText('YYYY-MM-DDTHH:mm')).toBeInTheDocument();
+  });
+
+  test('shows native second-granularity empty-state hint', () => {
+    const { container } = render(<DateTimePicker granularity="second" />);
+    const input = container.querySelector('input[type="datetime-local"]');
+    expect(input).toHaveAttribute('placeholder', '');
+    expect(screen.getByText('YYYY-MM-DDTHH:mm:ss')).toBeInTheDocument();
+  });
+
+  test('allows empty-state hint to be overridden', () => {
+    const { container } = render(<DateTimePicker placeholder="Choose..." />);
+    const input = container.querySelector('input[type="datetime-local"]');
+    expect(input).toHaveAttribute('placeholder', '');
+    expect(screen.getByText('Choose...')).toBeInTheDocument();
+  });
+
+  test('native mode with custom placeholder uses read-only date field and opens calendar on pointer down', () => {
+    const { container } = render(<DateTimePicker placeholder="Choose..." />);
+    const input = container.querySelector('input[type="datetime-local"]') as HTMLInputElement;
+    expect(input.readOnly).toBe(true);
+    fireEvent.pointerDown(input);
+    expect(screen.getByRole('application')).toBeInTheDocument();
+  });
+
+  test('native mode with custom placeholder does not open calendar on keyboard focus alone', () => {
+    const { container } = render(<DateTimePicker placeholder="Choose..." />);
+    const input = container.querySelector('input[type="datetime-local"]') as HTMLInputElement;
+    fireEvent.focus(input);
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+  });
+
+  describe('displayFormat branching', () => {
+    test('displayFormat="native" renders datetime-local', () => {
+      const { container } = render(<DateTimePicker displayFormat="native" />);
+      expect(container.querySelector('input[type="datetime-local"]')).toBeInTheDocument();
+    });
+
+    test('displayFormat="default" renders a text input with formatted placeholder', () => {
+      render(<DateTimePicker displayFormat="default" />);
+      const input = screen.getByRole('textbox');
+      expect(input).toHaveAttribute('placeholder', 'DD/MM/YYYY HH:mm');
+    });
+
+    test('displayFormat="friendly" renders a text input with friendly placeholder', () => {
+      render(<DateTimePicker displayFormat="friendly" />);
+      const input = screen.getByRole('textbox');
+      expect(input).toHaveAttribute('placeholder', 'Pick a date, HH:mm');
+    });
+
+    test('typing formatted text in default mode parses correctly', () => {
+      const onChange = vi.fn();
+      render(<DateTimePicker displayFormat="default" onChange={onChange} />);
+      const input = screen.getByRole('textbox');
+      fireEvent.change(input, { target: { value: '15/06/2024 14:30' } });
+
+      expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+      const lastDate: Date = onChange.mock.lastCall![0];
+      expect(lastDate.getFullYear()).toBe(2024);
+      expect(lastDate.getMonth()).toBe(5);
+      expect(lastDate.getDate()).toBe(15);
+      expect(lastDate.getHours()).toBe(14);
+      expect(lastDate.getMinutes()).toBe(30);
+    });
+
+    test('typing formatted text in friendly mode parses correctly', () => {
+      const onChange = vi.fn();
+      render(<DateTimePicker displayFormat="friendly" onChange={onChange} />);
+      const input = screen.getByRole('textbox');
+      fireEvent.change(input, { target: { value: 'June 15th, 2024 14:30' } });
+
+      expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+      const lastDate: Date = onChange.mock.lastCall![0];
+      expect(lastDate.getFullYear()).toBe(2024);
+      expect(lastDate.getMonth()).toBe(5);
+      expect(lastDate.getDate()).toBe(15);
+      expect(lastDate.getHours()).toBe(14);
+      expect(lastDate.getMinutes()).toBe(30);
+    });
+
+    test('controlled value displays in default format', () => {
+      render(<DateTimePicker displayFormat="default" value={new Date(2024, 5, 15, 14, 30)} />);
+      const input = screen.getByRole('textbox');
+      expect(input).toHaveValue('15/06/2024 14:30');
+    });
+
+    test('controlled value displays in friendly format', () => {
+      render(<DateTimePicker displayFormat="friendly" value={new Date(2024, 5, 15, 14, 30)} />);
+      const input = screen.getByRole('textbox');
+      expect(input).toHaveValue('June 15th, 2024 14:30');
+    });
+  });
+
+  test('typing a valid combined value emits a combined date and time value', () => {
+    const onChange = vi.fn();
+    const { container } = render(<DateTimePicker onChange={onChange} />);
+    const input = container.querySelector('input[type="datetime-local"]') as HTMLInputElement;
+
+    fireEvent.change(input, { target: { value: '2024-06-15T14:30' } });
+
+    expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+    const lastDate: Date = onChange.mock.lastCall![0];
+    expect(lastDate.getFullYear()).toBe(2024);
+    expect(lastDate.getMonth()).toBe(5);
+    expect(lastDate.getDate()).toBe(15);
+    expect(lastDate.getHours()).toBe(14);
+    expect(lastDate.getMinutes()).toBe(30);
+  });
+
+  test('uses one-second stepping when granularity is second', () => {
+    const { container } = render(<DateTimePicker granularity="second" />);
+    const input = container.querySelector('input[type="datetime-local"]');
+
+    expect(input).toHaveAttribute('step', '1');
+  });
+
+  test('selecting a day from the calendar preserves the existing time', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 1, 14, 30)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    await user.click(within(screen.getByRole('application')).getByRole('button', { name: /June 20/ }));
+
+    expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+    const lastDate: Date = onChange.mock.lastCall![0];
+    expect(lastDate.getFullYear()).toBe(2024);
+    expect(lastDate.getMonth()).toBe(5);
+    expect(lastDate.getDate()).toBe(20);
+    expect(lastDate.getHours()).toBe(14);
+    expect(lastDate.getMinutes()).toBe(30);
+  });
+
+  test('opening the picker after typing a valid combined value syncs month, year, and time controls', async () => {
+    const user = userEvent.setup();
+    const { container } = render(<DateTimePicker />);
+    const input = container.querySelector('input[type="datetime-local"]') as HTMLInputElement;
+
+    fireEvent.change(input, { target: { value: '2026-04-14T14:50' } });
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+
+    expect(getDropdownTrigger(/April/i)).toBeInTheDocument();
+    expect(getDropdownTrigger(/2026/i)).toBeInTheDocument();
+    expect(screen.getByLabelText('Select time', { selector: 'input' })).toHaveValue('14:50');
+  });
+
+  test('time-list mode emits a combined date when an allowed time is selected', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(
+      <DateTimePicker
+        value={new Date(2024, 5, 15, 13, 0)}
+        onChange={onChange}
+        timeOptions={['13:00', '13:30', '14:00']}
+      />,
+    );
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    await user.click(screen.getByText('13:00'));
+    await user.click(screen.getByText('13:30'));
+
+    expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+    const lastDate: Date = onChange.mock.lastCall![0];
+    expect(lastDate.getFullYear()).toBe(2024);
+    expect(lastDate.getMonth()).toBe(5);
+    expect(lastDate.getDate()).toBe(15);
+    expect(lastDate.getHours()).toBe(13);
+    expect(lastDate.getMinutes()).toBe(30);
+  });
+
+  describe('defaultValue prop', () => {
+    test('renders with the defaultValue when no value is provided', () => {
+      const { container } = render(<DateTimePicker defaultValue={new Date(2024, 5, 15, 14, 30)} />);
+      expect(container.querySelector('input[type="datetime-local"]')).toHaveValue('2024-06-15T14:30');
+    });
+
+    test('value prop takes precedence over defaultValue', () => {
+      const { container } = render(
+        <DateTimePicker value={new Date(2024, 11, 25, 9, 0)} defaultValue={new Date(2024, 5, 15, 14, 30)} />,
+      );
+      expect(container.querySelector('input[type="datetime-local"]')).toHaveValue('2024-12-25T09:00');
+    });
+
+    test('does not call onChange on mount with defaultValue', () => {
+      const onChange = vi.fn();
+      render(<DateTimePicker defaultValue={new Date(2024, 5, 15, 14, 30)} onChange={onChange} />);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onChange call-count correctness', () => {
+    test('does not call onChange on mount', () => {
+      const onChange = vi.fn();
+      render(<DateTimePicker onChange={onChange} />);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    test('does not call onChange on mount with an initial value', () => {
+      const onChange = vi.fn();
+      render(<DateTimePicker value={new Date(2024, 5, 15, 14, 30)} onChange={onChange} />);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    test('calls onChange exactly once per user input change', () => {
+      const onChange = vi.fn();
+      const { container } = render(<DateTimePicker onChange={onChange} />);
+      const input = container.querySelector('input[type="datetime-local"]') as HTMLInputElement;
+
+      fireEvent.change(input, { target: { value: '2024-06-15T14:30' } });
+      expect(onChange).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  test('controlled value updates sync the date and time fields without firing onChange', () => {
+    const onChange = vi.fn();
+    const { rerender, container } = render(
+      <DateTimePicker value={new Date(2024, 5, 15, 14, 30)} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+
+    expect(container.querySelector('input[type="datetime-local"]')).toHaveValue('2024-06-15T14:30');
+    expect(screen.getByLabelText('Select time', { selector: 'input' })).toHaveValue('14:30');
+
+    onChange.mockClear();
+
+    rerender(<DateTimePicker value={new Date(2024, 11, 25, 9, 45)} onChange={onChange} />);
+
+    expect(container.querySelector('input[type="datetime-local"]')).toHaveValue('2024-12-25T09:45');
+    expect(screen.getByLabelText('Select time', { selector: 'input' })).toHaveValue('09:45');
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('Today preserves the current time and closes the picker', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<DateTimePicker value={new Date(2024, 5, 15, 14, 30)} onChange={onChange} />);
+    onChange.mockClear();
+
+    await user.click(screen.getByRole('button', { name: 'Open date and time picker' }));
+    await user.click(screen.getByRole('button', { name: 'Today' }));
+
+    expect(screen.queryByRole('application')).not.toBeInTheDocument();
+    expect(onChange).toHaveBeenLastCalledWith(expect.any(Date));
+    const lastDate: Date = onChange.mock.lastCall![0];
+    const now = new Date();
+    expect(lastDate.getFullYear()).toBe(now.getFullYear());
+    expect(lastDate.getMonth()).toBe(now.getMonth());
+    expect(lastDate.getDate()).toBe(now.getDate());
+    expect(lastDate.getHours()).toBe(14);
+    expect(lastDate.getMinutes()).toBe(30);
+  });
+});