@codecademy/gamut 68.1.3-alpha.ce69cb.0 → 68.1.3-alpha.da9068.0

package/dist/DatePicker/Calendar/utils/dateGrid.js

@@ -0,0 +1,87 @@
+/**
+ * Builds a grid of days for a calendar month using native Date and Intl.
+ * Each row has 7 cells; leading/trailing cells may be null (padding from adjacent months).
+ */
+
+const DAYS_PER_WEEK = 7;
+
+/**
+ * Normalize to start of day in local time for comparison.
+ */
+const normalizeDate = date => {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+};
+
+/**
+ * Get the weekday for a date (0 = Sunday, 6 = Saturday).
+ * Optionally use weekStartsOn to compute "offset" for display (e.g. Monday = 0).
+ */
+export const getDayOfWeek = (date, weekStartsOn = 0) => {
+  const sundayBased = date.getDay();
+  if (weekStartsOn === 0) return sundayBased;
+  return (sundayBased + 6) % 7; // Monday = 0
+};
+
+/**
+ * Returns an array of weeks for the given month. Each week is an array of 7 items:
+ * each item is either a Date (that day) or null (padding from previous/next month).
+ *
+ * @param year - Full year (e.g. 2026)
+ * @param month - Month 0-11 (0 = January)
+ * @param weekStartsOn - 0 = Sunday, 1 = Monday
+ */
+export const getMonthGrid = (year, month, weekStartsOn = 0) => {
+  const first = new Date(year, month, 1);
+  const last = new Date(year, month + 1, 0);
+  const firstDayOfWeek = getDayOfWeek(first, weekStartsOn);
+  const daysInMonth = last.getDate();
+  const weeks = [];
+  let currentWeek = [];
+  for (let i = 0; i < firstDayOfWeek; i += 1) {
+    currentWeek.push(null);
+  }
+  for (let day = 1; day <= daysInMonth; day += 1) {
+    currentWeek.push(new Date(year, month, day));
+    if (currentWeek.length === DAYS_PER_WEEK) {
+      weeks.push(currentWeek);
+      currentWeek = [];
+    }
+  }
+
+  // Pad end of last week with nulls
+  if (currentWeek.length > 0) {
+    while (currentWeek.length < DAYS_PER_WEEK) {
+      currentWeek.push(null);
+    }
+    weeks.push(currentWeek);
+  }
+  return weeks;
+};
+
+/**
+ * Check if two dates are the same calendar day (ignoring time).
+ */
+export const isSameDay = (a, b) => {
+  if (a === null || b === null) return false;
+  return normalizeDate(a) === normalizeDate(b);
+};
+
+/**
+ * Check if `date` is between `start` and `end` (exclusive), ignoring time.
+ */
+export const isDateInRange = (date, start, end) => {
+  if (start === null) return false;
+  const normalizedDateTime = normalizeDate(date);
+  const normalizedStartDateTime = normalizeDate(start);
+  const normalizedEndDateTime = end !== null ? normalizeDate(end) : normalizedStartDateTime;
+  const low = Math.min(normalizedStartDateTime, normalizedEndDateTime);
+  const high = Math.max(normalizedStartDateTime, normalizedEndDateTime);
+  return normalizedDateTime > low && normalizedDateTime < high;
+};
+
+/**
+ * Check if `date` is in the `disabledDates` list (by calendar day).
+ */
+export const isDateDisabled = (date, disabledDates = []) => {
+  return disabledDates.some(d => isSameDay(date, d));
+};

package/dist/DatePicker/Calendar/utils/format.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Date formatting for the calendar using Intl.DateTimeFormat.
+ */
+/**
+ * Capitalize the first character of a string using the locale; rest unchanged (e.g. "next month" → "Next month").
+ */
+export declare const capitalizeFirst: (str: string, locale?: string) => string;
+/**
+ * Format month and year for the calendar header (e.g. "February 2026").
+ */
+export declare const formatMonthYear: (date: Date, locale?: string) => string;
+/**
+ * Get weekday names for column headers or abbr attributes.
+ * Order depends on weekStartsOn: 0 = Sunday first, 1 = Monday first.
+ * @param format - 'short' for abbreviated (e.g. "Su", "Mo"), 'long' for full (e.g. "Sunday", "Monday")
+ */
+export declare const getWeekdayNames: (format: 'short' | 'long', locale?: string, weekStartsOn?: 0 | 1) => string[];
+/**
+ * Get localized "next month" and "previous month" labels for calendar nav.
+ * Uses Intl.RelativeTimeFormat with numeric: "auto" (e.g. "next month", "last month").
+ */
+export declare const getRelativeMonthLabels: (locale?: string) => {
+    nextMonth: string;
+    lastMonth: string;
+};
+/**
+ * Get localized "today" label (e.g. "today").
+ */
+export declare const getRelativeTodayLabel: (locale?: string) => string;
+/**
+ * Get the locale's short date format pattern (e.g. "MM/DD/YYYY" for en-US,
+ * "DD/MM/YYYY" for en-GB). Uses Intl.DateTimeFormat formatToParts to infer
+ * order and separators. Useful for parsing or building locale-aware inputs.
+ */
+export declare const getDateFormatPattern: (locale?: string) => string;
+/**
+ * Format a date for display in the date picker input (e.g. "2/15/2026").
+ */
+export declare const formatDateForInput: (date: Date, locale?: string) => string;
+/**
+ * Parse a string from the date input into a Date, or null if invalid.
+ * Only returns a date when the input is a complete valid date (e.g. "2/15/2026").
+ * Partial input like "1" or "2/15" returns null even though Date("1") would parse.
+ */
+export declare const parseDateFromInput: (value: string, locale?: string) => Date | null;

package/dist/DatePicker/Calendar/utils/format.js

@@ -0,0 +1,123 @@
+/**
+ * Date formatting for the calendar using Intl.DateTimeFormat.
+ */
+
+import { isValidDate } from './validation';
+
+/**
+ * Capitalize the first character of a string using the locale; rest unchanged (e.g. "next month" → "Next month").
+ */
+export const capitalizeFirst = (str, locale) => str.length === 0 ? str : str[0].toLocaleUpperCase(locale) + str.slice(1);
+
+/**
+ * Format month and year for the calendar header (e.g. "February 2026").
+ */
+export const formatMonthYear = (date, locale) => {
+  return new Intl.DateTimeFormat(locale, {
+    month: 'long',
+    year: 'numeric'
+  }).format(date);
+};
+
+/**
+ * Get weekday names for column headers or abbr attributes.
+ * Order depends on weekStartsOn: 0 = Sunday first, 1 = Monday first.
+ * @param format - 'short' for abbreviated (e.g. "Su", "Mo"), 'long' for full (e.g. "Sunday", "Monday")
+ */
+export const getWeekdayNames = (format, locale, weekStartsOn = 0) => {
+  const formatter = new Intl.DateTimeFormat(locale, {
+    weekday: format
+  });
+  // Jan 7, 2024 is a Sunday; add 0..6 days to get Sun..Sat
+  const sunday = new Date(2024, 0, 7);
+  const names = Array.from({
+    length: 7
+  }, (_, i) => {
+    const date = new Date(sunday);
+    date.setDate(sunday.getDate() + i);
+    return formatter.format(date);
+  });
+  if (weekStartsOn === 1) {
+    return [...names.slice(1), names[0]];
+  }
+  return names;
+};
+
+/**
+ * Get localized "next month" and "previous month" labels for calendar nav.
+ * Uses Intl.RelativeTimeFormat with numeric: "auto" (e.g. "next month", "last month").
+ */
+export const getRelativeMonthLabels = locale => {
+  const rtf = new Intl.RelativeTimeFormat(locale, {
+    numeric: 'auto'
+  });
+  return {
+    nextMonth: capitalizeFirst(rtf.format(1, 'month'), locale),
+    lastMonth: capitalizeFirst(rtf.format(-1, 'month'), locale)
+  };
+};
+
+/**
+ * Get localized "today" label (e.g. "today").
+ */
+export const getRelativeTodayLabel = locale => {
+  const rtf = new Intl.RelativeTimeFormat(locale, {
+    numeric: 'auto'
+  });
+  return capitalizeFirst(rtf.format(0, 'day'), locale);
+};
+
+/**
+ * Get the locale's short date format pattern (e.g. "MM/DD/YYYY" for en-US,
+ * "DD/MM/YYYY" for en-GB). Uses Intl.DateTimeFormat formatToParts to infer
+ * order and separators. Useful for parsing or building locale-aware inputs.
+ */
+export const getDateFormatPattern = locale => {
+  const parts = new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit'
+  }).formatToParts(new Date(2025, 0, 15));
+  return parts.map(part => {
+    switch (part.type) {
+      case 'day':
+        return 'DD';
+      case 'month':
+        return 'MM';
+      case 'year':
+        return 'YYYY';
+      default:
+        return part.value;
+    }
+  }).join('');
+};
+
+/**
+ * Format a date for display in the date picker input (e.g. "2/15/2026").
+ */
+export const formatDateForInput = (date, locale) => {
+  return new Intl.DateTimeFormat(locale, {
+    month: 'numeric',
+    day: 'numeric',
+    year: 'numeric'
+  }).format(date);
+};
+
+/**
+ * Parse a string from the date input into a Date, or null if invalid.
+ * Only returns a date when the input is a complete valid date (e.g. "2/15/2026").
+ * Partial input like "1" or "2/15" returns null even though Date("1") would parse.
+ */
+
+// this logic needs some work
+export const parseDateFromInput = (value, locale) => {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const parsed = new Date(trimmed);
+  if (!isValidDate(parsed)) return null;
+  const formatted = formatDateForInput(parsed, locale);
+  if (formatted === trimmed) return parsed;
+  const parts = trimmed.split(/[/-]/);
+  if (parts.length >= 3) return parsed;
+  return null;
+};

package/dist/DatePicker/Calendar/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './dateGrid';
+export * from './format';
+export * from './validation';

package/dist/DatePicker/Calendar/utils/index.js

@@ -0,0 +1,3 @@
+export * from './dateGrid';
+export * from './format';
+export * from './validation';

package/dist/DatePicker/Calendar/utils/keyHandler.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clamp a day to the last day of the given month (e.g. Jan 31 -> Feb 28).
+ */
+export declare const clampToMonth: (year: number, month: number, day: number) => Date;
+/** Flat list of dates in grid order (row-major, non-null only) with row index for Home/End */
+export declare const getDatesWithRow: (weeks: (Date | null)[][]) => {
+    date: Date;
+    rowIndex: number;
+}[];
+export declare const keyHandler: (e: React.KeyboardEvent, date: Date, onFocusedDateChange: (date: Date | null) => void, datesWithRow: {
+    date: Date;
+    rowIndex: number;
+}[], month: number, year: number, disabledDates: Date[], onDateSelect: (date: Date) => void, onEscapeKeyPress?: () => void, onVisibleDateChange?: ((newDate: Date) => void) | undefined, hasAdjacentMonthRight?: boolean, hasAdjacentMonthLeft?: boolean) => void;

package/dist/DatePicker/Calendar/utils/keyHandler.js

@@ -0,0 +1,125 @@
+import { isDateDisabled } from './dateGrid';
+
+/**
+ * Clamp a day to the last day of the given month (e.g. Jan 31 -> Feb 28).
+ */
+export const clampToMonth = (year, month, day) => {
+  const last = new Date(year, month + 1, 0).getDate();
+  return new Date(year, month, Math.min(day, last));
+};
+
+/** Flat list of dates in grid order (row-major, non-null only) with row index for Home/End */
+export const getDatesWithRow = weeks => {
+  const result = [];
+  weeks.forEach((week, rowIndex) => {
+    week.forEach(date => {
+      if (date !== null) result.push({
+        date,
+        rowIndex
+      });
+    });
+  });
+  return result;
+};
+export const keyHandler = (e, date, onFocusedDateChange, datesWithRow, month, year, disabledDates, onDateSelect, onEscapeKeyPress, onVisibleDateChange, hasAdjacentMonthRight, hasAdjacentMonthLeft) => {
+  const idx = datesWithRow.findIndex(({
+    date: dateWithRow
+  }) => dateWithRow.getTime() === date.getTime());
+  if (idx < 0) return;
+  const currentRow = datesWithRow[idx].rowIndex;
+  const day = date.getDate();
+  const hasRight = !!hasAdjacentMonthRight;
+  const hasLeft = !!hasAdjacentMonthLeft;
+  let newDate = null;
+  let newVisibleDate = null;
+  switch (e.key) {
+    case 'ArrowLeft':
+      e.preventDefault();
+      if (idx > 0) {
+        newDate = datesWithRow[idx - 1].date;
+      } else {
+        const lastDayPrevMonth = new Date(year, month, 0);
+        newDate = lastDayPrevMonth;
+        if (!hasLeft) {
+          newVisibleDate = new Date(year, month - 1, 1);
+        }
+      }
+      break;
+    case 'ArrowRight':
+      e.preventDefault();
+      if (idx < datesWithRow.length - 1) {
+        newDate = datesWithRow[idx + 1].date;
+      } else {
+        newDate = new Date(year, month + 1, 1);
+        if (!hasRight) {
+          newVisibleDate = new Date(year, month + 1, 1);
+        }
+      }
+      break;
+    case 'ArrowUp':
+      e.preventDefault();
+      newDate = new Date(date);
+      newDate.setDate(newDate.getDate() - 7);
+      if (newDate.getMonth() !== month || newDate.getFullYear() !== year) {
+        if (!hasLeft) {
+          newVisibleDate = new Date(newDate.getFullYear(), newDate.getMonth(), 1);
+        }
+      }
+      break;
+    case 'ArrowDown':
+      e.preventDefault();
+      newDate = new Date(date);
+      newDate.setDate(newDate.getDate() + 7);
+      if (newDate.getMonth() !== month || newDate.getFullYear() !== year) {
+        if (!hasRight) {
+          newVisibleDate = new Date(newDate.getFullYear(), newDate.getMonth(), 1);
+        }
+      }
+      break;
+    case 'Home':
+      e.preventDefault();
+      newDate = datesWithRow.find(({
+        rowIndex
+      }) => rowIndex === currentRow)?.date ?? date;
+      break;
+    case 'End':
+      e.preventDefault();
+      newDate = [...datesWithRow].reverse().find(({
+        rowIndex
+      }) => rowIndex === currentRow)?.date ?? date;
+      break;
+    case 'PageDown':
+      e.preventDefault();
+      if (e.shiftKey) {
+        newDate = clampToMonth(year + 1, month, day);
+      } else {
+        newDate = clampToMonth(year, month + 1, day);
+      }
+      newVisibleDate = new Date(newDate.getFullYear(), newDate.getMonth(), 1);
+      break;
+    case 'PageUp':
+      e.preventDefault();
+      if (e.shiftKey) {
+        newDate = clampToMonth(year - 1, month, day);
+      } else {
+        newDate = clampToMonth(year, month - 1, day);
+      }
+      newVisibleDate = new Date(newDate.getFullYear(), newDate.getMonth(), 1);
+      break;
+    case 'Enter':
+    case ' ':
+      e.preventDefault();
+      if (!isDateDisabled(date, disabledDates)) onDateSelect(date);
+      return;
+    case 'Escape':
+      e.preventDefault();
+      onEscapeKeyPress?.();
+      return;
+    default:
+      return;
+  }
+  if (newDate !== null) {
+    onFocusedDateChange(newDate);
+    if (newVisibleDate !== null) onVisibleDateChange?.(newVisibleDate);
+  }
+};

package/dist/DatePicker/Calendar/utils/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation helpers for DatePicker (single-date).
+ * Used to mark invalid dates as unselectable and for manual entry validation.
+ */
+/**
+ * Check if a date is in the past (before today at start of day).
+ * Useful for disabling past dates in the calendar.
+ */
+export declare const isPastDate: (date: Date) => boolean;
+/**
+ * Check if a date is valid (finite and not NaN).
+ */
+export declare const isValidDate: (date: Date) => boolean;

package/dist/DatePicker/Calendar/utils/validation.js

@@ -0,0 +1,23 @@
+/**
+ * Validation helpers for DatePicker (single-date).
+ * Used to mark invalid dates as unselectable and for manual entry validation.
+ */
+
+/**
+ * Check if a date is in the past (before today at start of day).
+ * Useful for disabling past dates in the calendar.
+ */
+export const isPastDate = date => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const normalizedDate = new Date(date);
+  normalizedDate.setHours(0, 0, 0, 0);
+  return normalizedDate.getTime() < today.getTime();
+};
+
+/**
+ * Check if a date is valid (finite and not NaN).
+ */
+export const isValidDate = date => {
+  return date instanceof Date && !Number.isNaN(date.getTime());
+};

package/dist/DatePicker/DatePicker.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="react" />
+import { type DatePickerProps } from './types';
+/**
+ * DatePicker: single-date or range. Holds shared state and provides it via context.
+ * Single: selectedDate, setSelectedDate. Range: startDate, endDate, setStartDate, setEndDate.
+ * With no children, renders default layout (input + calendar popover).
+ */
+export declare const DatePicker: React.FC<DatePickerProps>;

package/dist/DatePicker/DatePicker.js

@@ -0,0 +1,128 @@
+import { MiniArrowRightIcon } from '@codecademy/gamut-icons';
+import { useCallback, useId, useMemo, useRef, useState } from 'react';
+import { Box, FlexBox } from '../Box';
+import { PopoverContainer } from '../PopoverContainer';
+import { DatePickerCalendar } from './DatePickerCalendar';
+import { DatePickerProvider } from './DatePickerContext';
+import { DatePickerInput } from './DatePickerInput';
+import { DEFAULT_DATE_PICKER_TRANSLATIONS } from './translations';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+function isRangeProps(props) {
+  return props.mode === 'range';
+}
+
+/**
+ * DatePicker: single-date or range. Holds shared state and provides it via context.
+ * Single: selectedDate, setSelectedDate. Range: startDate, endDate, setStartDate, setEndDate.
+ * With no children, renders default layout (input + calendar popover).
+ */
+export const DatePicker = props => {
+  const {
+    locale,
+    disabledDates = [],
+    placeholder,
+    mode,
+    children,
+    translations: translationsProp
+  } = props;
+  const [isCalendarOpen, setIsCalendarOpen] = useState(false);
+  const [activeRangePart, setActiveRangePart] = useState(null);
+  const inputRef = useRef(null);
+  const dialogId = useId();
+  const calendarDialogId = `datepicker-dialog-${dialogId.replace(/:/g, '')}`;
+  const openCalendar = useCallback(() => setIsCalendarOpen(true), []);
+  const closeCalendar = useCallback(() => {
+    setIsCalendarOpen(false);
+    setActiveRangePart(null);
+    inputRef.current?.focus();
+  }, []);
+  const startOrSelectedDate = isRangeProps(props) ? props.startDate : props.selectedDate;
+  const endDate = isRangeProps(props) ? props.endDate : null;
+  const setSelection = useCallback((start, end) => {
+    if (isRangeProps(props)) {
+      props.setStartDate(start);
+      props.setEndDate(end ?? null);
+    } else {
+      props.setSelectedDate(start);
+    }
+  }, [props]);
+  const contextValue = useMemo(() => {
+    const translations = {
+      ...DEFAULT_DATE_PICKER_TRANSLATIONS,
+      ...translationsProp
+    };
+    const base = {
+      startOrSelectedDate,
+      setSelection,
+      isCalendarOpen,
+      openCalendar,
+      closeCalendar,
+      locale,
+      disabledDates,
+      calendarDialogId,
+      translations
+    };
+    return mode === 'range' ? {
+      ...base,
+      mode: 'range',
+      endDate,
+      activeRangePart,
+      setActiveRangePart
+    } : {
+      ...base,
+      mode: 'single'
+    };
+  }, [mode, startOrSelectedDate, endDate, setSelection, activeRangePart, setActiveRangePart, isCalendarOpen, openCalendar, closeCalendar, locale, disabledDates, calendarDialogId, translationsProp]);
+  const content = children !== undefined ? children : /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(FlexBox, {
+      gap: 8,
+      width: "fit-content",
+      children: mode === 'range' ? /*#__PURE__*/_jsxs(_Fragment, {
+        children: [/*#__PURE__*/_jsx(DatePickerInput, {
+          label: props.startLabel,
+          placeholder: placeholder,
+          rangePart: "start",
+          ref: inputRef
+        }), /*#__PURE__*/_jsx(Box, {
+          alignSelf: "center",
+          mt: 32,
+          children: /*#__PURE__*/_jsx(MiniArrowRightIcon, {})
+        }), /*#__PURE__*/_jsx(DatePickerInput, {
+          label: props.endLabel,
+          placeholder: placeholder,
+          rangePart: "end"
+          // does this need a ref?
+        })]
+      }) : /*#__PURE__*/_jsx(DatePickerInput, {
+        label: props.label,
+        placeholder: placeholder,
+        ref: inputRef
+      })
+    }), /*#__PURE__*/_jsx(PopoverContainer, {
+      alignment: "bottom-left",
+      allowPageInteraction: true,
+      focusOnProps: {
+        autoFocus: false,
+        focusLock: false
+      },
+      invertAxis: "x",
+      isOpen: isCalendarOpen,
+      targetRef: inputRef,
+      x: -20,
+      y: -16,
+      onRequestClose: closeCalendar,
+      children: /*#__PURE__*/_jsx("div", {
+        "aria-label": contextValue.translations.calendarDialogAriaLabel,
+        id: calendarDialogId,
+        role: "dialog",
+        children: /*#__PURE__*/_jsx(DatePickerCalendar, {
+          dialogId: calendarDialogId
+        })
+      })
+    })]
+  });
+  return /*#__PURE__*/_jsx(DatePickerProvider, {
+    value: contextValue,
+    children: content
+  });
+};

package/dist/DatePicker/DatePickerCalendar.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="react" />
+export type DatePickerCalendarProps = {
+    /** id for the dialog (for aria-controls from input). */
+    dialogId: string;
+    /** Whether to start the calendar on Sunday (0) or Monday (1). Default is Sunday. */
+    weekStartsOn?: 0 | 1;
+};
+/**
+ * Calendar that composes Calendar, CalendarHeader, CalendarBody, CalendarFooter.
+ * When inside DatePicker: owns local visibleDate and focusedDate; updates shared
+ * state via context. Supports single-date and range modes.
+ */
+export declare const DatePickerCalendar: React.FC<DatePickerCalendarProps>;