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

package/src/components/datePicker/DatePicker.tsx

@@ -1,86 +1,155 @@
 import classNames from 'classnames';
 import { Button } from 'Components/button/Button';
 import { TextInput } from 'Components/formField/inputs/text/TextInput';
-import { format, isValid, parse } from 'date-fns';
 import { Popover } from 'radix-ui';
-import { useContext, useRef, useState, type ChangeEvent } from 'react';
+import { useContext, useEffect, useRef, useState, type ChangeEvent, type PointerEvent } from 'react';
 import { DayPicker } from 'react-day-picker';
-import { useComponentDidUpdate } from 'Utils/hooks/useComponentDidUpdate';
 import { PopupParentContext } from 'Utils/PopupParentContext';
+import {
+  formatNativeDateInputValue,
+  formatTimeInputValue,
+  getDatePlaceholder,
+  mergeDateAndTime,
+  parseNativeDateInputValue,
+  type DateDisplayFormat,
+} from './dateInputUtils';
+import { DatePickerCalendarHeader } from './DatePickerCalendarHeader';
+
+const TIME_PRESERVATION_GRANULARITY = 'minute' as const;
 
 export type DatePickerProps = {
   'className'?: string;
-  'dateFormat'?: string;
+  'displayFormat'?: DateDisplayFormat;
+  'placeholder'?: string;
   'onChange'?: (newDate?: Date) => void;
   'id'?: string;
   'hasError'?: boolean;
   'aria-describedby'?: string;
   'aria-invalid'?: boolean;
   'value'?: Date;
+  'defaultValue'?: Date;
 };
 
 export const DatePicker = (props: DatePickerProps) => {
   const {
     className,
-    dateFormat = 'dd/MM/yyyy',
+    displayFormat = 'default',
     onChange,
     id,
     hasError,
     'aria-describedby': ariaDescribedBy,
     'aria-invalid': ariaInvalid,
     value,
+    defaultValue,
+    placeholder,
   } = props;
 
-  const [month, setMonth] = useState(value ?? new Date());
-
-  const [selectedDate, setSelectedDate] = useState<Date | undefined>(value);
+  const initialValue = value ?? defaultValue;
+  const isControlled = value !== undefined;
+  const [month, setMonth] = useState(initialValue ?? new Date());
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(initialValue);
+  const [inputValue, setInputValue] = useState(
+    initialValue ? formatNativeDateInputValue(initialValue) : '',
+  );
+  const [isPickerOpen, setIsPickerOpen] = useState(false);
 
-  const [inputValue, setInputValue] = useState(value ? format(value, dateFormat) : '');
+  const inputRef = useRef<HTMLInputElement>(null);
+  const selectedDateRef = useRef(selectedDate);
+  selectedDateRef.current = selectedDate;
 
-  const isExternalSyncRef = useRef(false);
+  const resolvedPlaceholder = placeholder ?? getDatePlaceholder(displayFormat);
+  const showFieldHint = selectedDate === undefined && inputValue === '';
+  const overlayHint = resolvedPlaceholder;
+  const hasCustomEmptyHint = showFieldHint && placeholder !== undefined;
 
-  useComponentDidUpdate(() => {
-    if (value && value.getTime() !== selectedDate?.getTime()) {
-      isExternalSyncRef.current = true;
+  useEffect(() => {
+    if (!isControlled) {
+      return;
+    }
+    const valueTime = value?.getTime();
+    const selectedTime = selectedDateRef.current?.getTime();
+    if (valueTime !== selectedTime) {
       setSelectedDate(value);
-      setMonth(value);
+      setMonth(value ?? new Date());
+      setInputValue(value ? formatNativeDateInputValue(value) : '');
     }
-  }, [value]);
-
-  const [isPickerOpen, setIsPickerOpen] = useState(false);
+  }, [value, isControlled]);
+
+  const mergeParsedDateWithExistingTime = (parsedDay: Date) => (
+    selectedDate
+      ? mergeDateAndTime(
+          parsedDay,
+          formatTimeInputValue(selectedDate, TIME_PRESERVATION_GRANULARITY),
+          TIME_PRESERVATION_GRANULARITY,
+        )
+      : parsedDay
+  );
 
   const onInputChange = (e: ChangeEvent<HTMLInputElement>) => {
-    setInputValue(e.target.value);
+    const nextInputValue = e.target.value;
+    setInputValue(nextInputValue);
 
-    const parsedDate = parse(e.target.value, dateFormat, new Date());
+    const parsedDay = parseNativeDateInputValue(nextInputValue);
 
-    if (isValid(parsedDate)) {
-      setSelectedDate(parsedDate);
-      setMonth(parsedDate);
+    if (parsedDay) {
+      const next = mergeParsedDateWithExistingTime(parsedDay);
+      setSelectedDate(next);
+      setMonth(next);
+      onChange?.(next);
     }
     else {
       setSelectedDate(undefined);
+      onChange?.(undefined);
     }
   };
 
-  const onDayPickerSelect = (date?: Date) => {
-    setSelectedDate(date);
-    setIsPickerOpen(false);
+  const mergePreservingTime = (calendarDay: Date) => {
+    const timeSource = selectedDate ?? calendarDay;
+    return mergeDateAndTime(
+      calendarDay,
+      formatTimeInputValue(timeSource, TIME_PRESERVATION_GRANULARITY),
+      TIME_PRESERVATION_GRANULARITY,
+    );
   };
 
-  useComponentDidUpdate(() => {
-    if (selectedDate) {
-      setInputValue(format(selectedDate, dateFormat));
-    }
-    else {
+  const onDayPickerSelect = (date?: Date) => {
+    if (!date) {
+      setSelectedDate(undefined);
       setInputValue('');
+      setIsPickerOpen(false);
+      onChange?.(undefined);
+      return;
     }
 
-    if (!isExternalSyncRef.current && onChange) {
-      onChange(selectedDate);
+    const next = mergePreservingTime(date);
+    setSelectedDate(next);
+    setMonth(next);
+    setInputValue(formatNativeDateInputValue(next));
+    setIsPickerOpen(false);
+    onChange?.(next);
+  };
+
+  const handleTodayClick = () => {
+    const day = new Date();
+    const next = mergeDateAndTime(
+      day,
+      formatTimeInputValue(selectedDate ?? day, TIME_PRESERVATION_GRANULARITY),
+      TIME_PRESERVATION_GRANULARITY,
+    );
+    setSelectedDate(next);
+    setMonth(next);
+    setInputValue(formatNativeDateInputValue(next));
+    setIsPickerOpen(false);
+    onChange?.(next);
+  };
+
+  /** Custom empty hint: open only on pointer (not Tab focus) so keyboard users are not surprised by the popover. */
+  const onFieldHintInputPointerDown = (e: PointerEvent<HTMLInputElement>) => {
+    if (hasCustomEmptyHint) {
+      e.preventDefault();
+      setIsPickerOpen(true);
     }
-    isExternalSyncRef.current = false;
-  }, [selectedDate, dateFormat, onChange]);
+  };
 
   const popupParentRef = useContext(PopupParentContext);
 
@@ -91,20 +160,37 @@ export const DatePicker = (props: DatePickerProps) => {
         className,
       )}
     >
-      <TextInput
-        value={inputValue}
-        onChange={onInputChange}
-        id={id}
-        hasError={hasError}
-        aria-describedby={ariaDescribedBy}
-        aria-invalid={ariaInvalid}
-      />
+      <div
+        className={classNames(
+          'ds-date-picker__field',
+          { 'ds-date-picker__field--show-hint': showFieldHint },
+        )}
+      >
+        <TextInput
+          ref={inputRef}
+          type="date"
+          value={inputValue}
+          onChange={onInputChange}
+          onPointerDown={onFieldHintInputPointerDown}
+          readOnly={hasCustomEmptyHint}
+          id={id}
+          placeholder={showFieldHint ? '' : resolvedPlaceholder}
+          hasError={hasError}
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={ariaInvalid}
+          className="ds-date-picker__input"
+        />
+        {showFieldHint
+          ? (
+              <span className="ds-date-picker__field-hint" aria-hidden="true">
+                {overlayHint}
+              </span>
+            )
+          : null}
+      </div>
       <Popover.Root open={isPickerOpen} onOpenChange={open => setIsPickerOpen(open)}>
         <Popover.Trigger asChild>
           <Button
-            onClick={() => {
-              setIsPickerOpen(!isPickerOpen);
-            }}
             className="ds-date-picker__button"
             variant="text-link"
             iconLeftName="date"
@@ -112,30 +198,38 @@ export const DatePicker = (props: DatePickerProps) => {
           />
         </Popover.Trigger>
         <Popover.Portal container={popupParentRef.current}>
-          <Popover.Content align="end" sideOffset={5}>
-            <DayPicker
-              className="ds-date-picker__popup"
-              month={month}
-              onMonthChange={setMonth}
-              autoFocus
-              role="application"
-              mode="single"
-              selected={selectedDate}
-              onSelect={onDayPickerSelect}
-              captionLayout="dropdown"
-              footer={(
-                <Button
-                  variant="text-link"
-                  onClick={() => {
-                    setSelectedDate(new Date());
-                    setIsPickerOpen(false);
-                  }}
-                  className="ds-date-picker__today-button"
-                >
-                  Today
-                </Button>
-              )}
-            />
+          <Popover.Content
+            align="end"
+            sideOffset={5}
+            onOpenAutoFocus={e => e.preventDefault()}
+            onCloseAutoFocus={(e) => {
+              e.preventDefault();
+              inputRef.current?.focus();
+            }}
+          >
+            <div className="ds-date-picker__popup">
+              <DatePickerCalendarHeader month={month} onMonthChange={setMonth} />
+              <DayPicker
+                className="ds-date-picker__calendar"
+                month={month}
+                onMonthChange={setMonth}
+                autoFocus
+                role="application"
+                mode="single"
+                selected={selectedDate}
+                onSelect={onDayPickerSelect}
+                hideNavigation
+                footer={(
+                  <Button
+                    variant="text-link"
+                    onClick={handleTodayClick}
+                    className="ds-date-picker__today-button"
+                  >
+                    Today
+                  </Button>
+                )}
+              />
+            </div>
           </Popover.Content>
         </Popover.Portal>
       </Popover.Root>

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