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

package/src/components/datePicker/DatePickerCalendarHeader.tsx

@@ -0,0 +1,82 @@
+import classNames from 'classnames';
+import { SelectDropdown } from 'Components/formField/inputs/selectDropdown/SelectDropdown';
+import { Icon } from 'Components/icon/Icon';
+import { addMonths, format } from 'date-fns';
+import { useMemo } from 'react';
+
+type DatePickerCalendarHeaderProps = {
+  month: Date;
+  onMonthChange: (month: Date) => void;
+  className?: string;
+};
+
+const monthOptions = Array.from({ length: 12 }, (_, index) => ({
+  label: format(new Date(2000, index, 1), 'MMMM'),
+  value: String(index),
+}));
+
+export const DatePickerCalendarHeader = ({
+  month,
+  onMonthChange,
+  className,
+}: DatePickerCalendarHeaderProps) => {
+  // Computed once per mount ([]): anchor year is the calendar header mount time, not the month being viewed
+  // nor a controlled value's year. Remounting when the popover opens keeps this practical; edge cases include
+  // a very long-lived mount across New Year's, or a controlled date far outside mountYear ± 100 until remount.
+  const yearOptions = useMemo(() => {
+    const thisYear = new Date().getFullYear();
+    return Array.from({ length: 201 }, (_, index) => {
+      const year = thisYear - 100 + index;
+      return { label: String(year), value: String(year) };
+    });
+  }, []);
+
+  const handleMonthSelection = (selectedValues: string[]) => {
+    const nextMonthIndex = Number.parseInt(selectedValues[0] ?? String(month.getMonth()), 10);
+    if (Number.isNaN(nextMonthIndex)) return;
+
+    onMonthChange(new Date(month.getFullYear(), nextMonthIndex, 1));
+  };
+
+  const handleYearSelection = (selectedValues: string[]) => {
+    const nextYear = Number.parseInt(selectedValues[0] ?? String(month.getFullYear()), 10);
+    if (Number.isNaN(nextYear)) return;
+
+    onMonthChange(new Date(nextYear, month.getMonth(), 1));
+  };
+
+  return (
+    <div className={classNames('ds-date-picker-calendar-header', className)}>
+      <div className="ds-date-picker-calendar-header__selectors">
+        <SelectDropdown
+          options={monthOptions}
+          selectedValues={[String(month.getMonth())]}
+          onSelectionChange={handleMonthSelection}
+        />
+        <SelectDropdown
+          options={yearOptions}
+          selectedValues={[String(month.getFullYear())]}
+          onSelectionChange={handleYearSelection}
+        />
+      </div>
+      <div className="ds-date-picker-calendar-header__nav">
+        <button
+          type="button"
+          className="ds-date-picker-calendar-header__nav-button"
+          aria-label="Go to the Previous Month"
+          onClick={() => onMonthChange(addMonths(month, -1))}
+        >
+          <Icon name="chevron-left" size={16} />
+        </button>
+        <button
+          type="button"
+          className="ds-date-picker-calendar-header__nav-button"
+          aria-label="Go to the Next Month"
+          onClick={() => onMonthChange(addMonths(month, 1))}
+        >
+          <Icon name="chevron-right" size={16} />
+        </button>
+      </div>
+    </div>
+  );
+};

package/src/components/datePicker/date-field-hint.scss

@@ -0,0 +1,152 @@
+@mixin ds-date-picker-shell-field($block-suffix) {
+  $b: 'ds-#{$block-suffix}';
+
+  .#{$b}__field {
+    position: relative;
+    min-width: 0;
+    width: 100%;
+
+    .#{$b}__input {
+      min-width: 0;
+      width: 100%;
+      padding-right: calc(var(--form-field-text-medium-height) + var(--spacing-small));
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      appearance: none;
+
+      &::-webkit-calendar-picker-indicator {
+        display: none;
+        appearance: none;
+      }
+
+      &::-webkit-inner-spin-button {
+        display: none;
+      }
+    }
+
+    &.#{$b}__field--show-hint:not(:focus-within) .#{$b}__input {
+      color: transparent;
+      -webkit-text-fill-color: transparent;
+      caret-color: var(--form-field-text-placeholder-color-text);
+    }
+
+    &.#{$b}__field--show-hint:not(:focus-within) .#{$b}__input::-webkit-datetime-edit,
+    &.#{$b}__field--show-hint:not(:focus-within) .#{$b}__input::-webkit-datetime-edit-fields-wrapper {
+      color: transparent;
+      -webkit-text-fill-color: transparent;
+    }
+
+    .#{$b}__field-hint {
+      position: absolute;
+      inset-block-start: 0;
+      inset-inline-start: var(--form-field-spacing-horizontal);
+      display: flex;
+      align-items: center;
+      block-size: var(--form-field-text-medium-height);
+      max-inline-size: calc(
+        100% - var(--form-field-spacing-horizontal) * 2 - var(--form-field-text-medium-height) - var(--spacing-small)
+      );
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      color: var(--form-field-text-placeholder-color-text);
+      pointer-events: none;
+      z-index: 1;
+    }
+
+    &.#{$b}__field--show-hint:focus-within .#{$b}__field-hint {
+      opacity: 0;
+    }
+  }
+}
+
+@mixin ds-date-picker-shell-button($block-suffix) {
+  $b: 'ds-#{$block-suffix}';
+
+  .#{$b}__button {
+    position: absolute;
+    right: 0;
+    top: 0;
+
+    svg {
+      stroke: var(--form-field-icon-default-color-icon);
+    }
+  }
+
+  .#{$b}__button.ds-button--text-link {
+    &:focus-visible {
+      color: var(--button-medium-text-link-focus-color-text);
+      outline: var(--focus-border) solid var(--button-medium-text-link-focus-color-focus);
+    }
+
+    &:focus:not(:focus-visible) {
+      outline: none;
+      color: var(--button-medium-text-link-default-color-text);
+      background-color: var(--button-medium-text-link-default-color-background);
+    }
+  }
+}
+
+@mixin ds-date-picker-shell-popup($block-suffix) {
+  $b: 'ds-#{$block-suffix}';
+
+  .#{$b}__popup {
+    display: grid;
+    gap: var(--spacing-medium);
+    width: max-content;
+    min-width: max(var(--radix-popover-trigger-width), 16rem);
+    max-width: min(100vw - var(--spacing-medium) * 2, 28rem);
+    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);
+  }
+}
+
+@mixin ds-date-picker-shell-calendar($block-suffix) {
+  $b: 'ds-#{$block-suffix}';
+
+  .#{$b}__calendar {
+    --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-month_caption {
+      display: none;
+    }
+
+    .rdp-selected {
+      font-size: unset;
+
+      .rdp-day_button {
+        background-color: var(--rdp-accent-background-color);
+      }
+    }
+
+    .rdp-day_button {
+      &:focus {
+        outline: none;
+      }
+
+      &:focus-visible {
+        outline: var(--focus-border) solid var(--color-brand-500);
+        outline-offset: 0;
+      }
+
+      &:focus:not(:focus-visible) {
+        outline: none;
+        box-shadow: none;
+      }
+    }
+
+    .rdp-selected .rdp-day_button:focus:not(:focus-visible) {
+      outline: none;
+      box-shadow: none;
+    }
+
+    .rdp-footer {
+      display: flex;
+      justify-content: flex-end;
+    }
+  }
+}

package/src/components/datePicker/dateInputUtils.ts

@@ -0,0 +1,117 @@
+import type { TimeGranularity, TimeValue } from 'Components/formField/inputs/time/TimeInput';
+import { format, isValid, parse, startOfDay } from 'date-fns';
+
+export type DateDisplayFormat = 'default' | 'friendly';
+
+/** `DateTimePicker` only: `native` uses `datetime-local`; `default` / `friendly` use `type="text"` with formatted date+time strings. */
+export type DateTimePickerDisplayFormat = DateDisplayFormat | 'native';
+
+/** Date format. */
+const DATE_FORMAT_PATTERNS: Record<DateDisplayFormat, string> = {
+  default: 'dd/MM/yyyy',
+  friendly: 'MMMM do, yyyy',
+};
+
+/** Placeholder copy for each DATE_FORMAT_PATTERNS. */
+const DATE_PLACEHOLDERS: Record<DateDisplayFormat, string> = {
+  default: 'DD/MM/YYYY',
+  friendly: 'Pick a date',
+};
+
+export const getDateFormatString = (displayFormat: DateDisplayFormat = 'default') => DATE_FORMAT_PATTERNS[displayFormat];
+
+export const getTimeFormatString = (granularity: TimeGranularity) => (
+  granularity === 'second' ? 'HH:mm:ss' : 'HH:mm'
+);
+
+export const getDateTimeFormatString = (
+  displayFormat: DateDisplayFormat = 'default',
+  granularity: TimeGranularity = 'minute',
+) => `${getDateFormatString(displayFormat)} ${getTimeFormatString(granularity)}`;
+
+export const getDatePlaceholder = (displayFormat: DateDisplayFormat = 'default') => DATE_PLACEHOLDERS[displayFormat];
+
+export const getDateTimePlaceholder = (
+  displayFormat: DateDisplayFormat = 'default',
+  granularity: TimeGranularity = 'minute',
+) => {
+  const timeHint = granularity === 'second' ? 'HH:mm:ss' : 'HH:mm';
+  const dateHint = getDatePlaceholder(displayFormat);
+  if (displayFormat === 'friendly') {
+    return `${dateHint}, ${timeHint}`;
+  }
+  return `${dateHint} ${timeHint}`;
+};
+
+/** Placeholder hint for native `datetime-local` values (not tied to `displayFormat`). */
+export const getNativeDateTimePlaceholder = (granularity: TimeGranularity = 'minute') => (
+  granularity === 'second' ? 'YYYY-MM-DDTHH:mm:ss' : 'YYYY-MM-DDTHH:mm'
+);
+
+/** Placeholder hint for native `type="date"` (`DatePicker`). */
+export const getNativeDatePlaceholder = () => 'YYYY-MM-DD';
+
+const NATIVE_DATE_FORMAT = 'yyyy-MM-dd';
+
+export const formatNativeDateInputValue = (value: Date) => format(value, NATIVE_DATE_FORMAT);
+
+export const parseNativeDateInputValue = (value: string): Date | undefined => {
+  const parsedDate = parse(value, NATIVE_DATE_FORMAT, new Date());
+  return isValid(parsedDate) ? startOfDay(parsedDate) : undefined;
+};
+
+export const getNativeDateTimeFormatString = (granularity: TimeGranularity = 'minute') => (
+  granularity === 'second' ? "yyyy-MM-dd'T'HH:mm:ss" : "yyyy-MM-dd'T'HH:mm"
+);
+
+export const parseDateInputValue = (value: string, displayFormat: DateDisplayFormat = 'default'): Date | undefined => {
+  const parsedDate = parse(value, getDateFormatString(displayFormat), new Date());
+  return isValid(parsedDate) ? startOfDay(parsedDate) : undefined;
+};
+
+export const parseDateTimeInputValue = (
+  value: string,
+  displayFormat: DateDisplayFormat = 'default',
+  granularity: TimeGranularity = 'minute',
+): Date | undefined => {
+  const parsedDate = parse(value, getDateTimeFormatString(displayFormat, granularity), new Date());
+  return isValid(parsedDate) ? parsedDate : undefined;
+};
+
+export const parseNativeDateTimeInputValue = (
+  value: string,
+  granularity: TimeGranularity = 'minute',
+): Date | undefined => {
+  const parsedDate = parse(value, getNativeDateTimeFormatString(granularity), new Date());
+  return isValid(parsedDate) ? parsedDate : undefined;
+};
+
+export const formatDateInputValue = (value: Date, displayFormat: DateDisplayFormat = 'default') => (
+  format(value, getDateFormatString(displayFormat))
+);
+
+export const formatDateTimeInputValue = (
+  value: Date,
+  displayFormat: DateDisplayFormat = 'default',
+  granularity: TimeGranularity = 'minute',
+) => format(value, getDateTimeFormatString(displayFormat, granularity));
+
+export const formatNativeDateTimeInputValue = (
+  value: Date,
+  granularity: TimeGranularity = 'minute',
+) => format(value, getNativeDateTimeFormatString(granularity));
+
+export const formatTimeInputValue = (value: Date, granularity: TimeGranularity): TimeValue => (
+  format(value, getTimeFormatString(granularity)) as TimeValue
+);
+
+export const mergeDateAndTime = (date: Date, timeValue: string, granularity: TimeGranularity): Date => {
+  const [rawHours = '0', rawMinutes = '0', rawSeconds = '0'] = timeValue.split(':');
+  const hours = Number.parseInt(rawHours, 10) || 0;
+  const minutes = Number.parseInt(rawMinutes, 10) || 0;
+  const seconds = granularity === 'second' ? (Number.parseInt(rawSeconds, 10) || 0) : 0;
+  const merged = new Date(date);
+
+  merged.setHours(hours, minutes, seconds, 0);
+  return merged;
+};

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} />,
+};