@12-apps/ui 1.0.0 → 1.3.1

package/src/components/form/Calendar/Calendar.dates.ts

@@ -0,0 +1,100 @@
+import type { MonthMatrix, MonthMatrixDay } from './Calendar.types';
+
+const DAYS_PER_WEEK = 7;
+// Six rows always cover a month, whichever weekday it starts on.
+const MAX_CELLS = 42;
+const NOON = 12;
+
+// Every comparison happens at noon so daylight-saving shifts can never move a
+// date across a day boundary.
+export const normalizeDate = (date: Date): Date => {
+  const normalized = new Date(date);
+  normalized.setHours(NOON, 0, 0, 0);
+  return normalized;
+};
+
+export const isSameDay = (date1: Date, date2: Date): boolean =>
+  date1.getFullYear() === date2.getFullYear() &&
+  date1.getMonth() === date2.getMonth() &&
+  date1.getDate() === date2.getDate();
+
+export const isBetween = (date: Date, start: Date, end: Date): boolean => {
+  const normalized = normalizeDate(date);
+  return normalized >= normalizeDate(start) && normalized <= normalizeDate(end);
+};
+
+export const addDays = (date: Date, days: number): Date => {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+};
+
+export const addMonths = (date: Date, months: number): Date => {
+  const result = new Date(date);
+  result.setMonth(result.getMonth() + months);
+  return result;
+};
+
+export const startOfWeek = (date: Date, firstDayOfWeek = 0): Date => {
+  const result = new Date(date);
+  const day = result.getDay();
+  const diff = (day < firstDayOfWeek ? DAYS_PER_WEEK : 0) + day - firstDayOfWeek;
+  result.setDate(result.getDate() - diff);
+  return result;
+};
+
+// Day 0 of the next month is the last day of this one.
+const endOfMonth = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth() + 1, 0);
+
+const dayKey = (date: Date): string =>
+  `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+
+export const generateMonthMatrix = (
+  month: number,
+  year: number,
+  firstDayOfWeek = 0,
+): MonthMatrix => {
+  const firstDay = new Date(year, month, 1);
+  const lastDay = endOfMonth(firstDay);
+  const currentDate = startOfWeek(firstDay, firstDayOfWeek);
+
+  const weeks: MonthMatrixDay[][] = [];
+  let currentWeek: MonthMatrixDay[] = [];
+
+  for (let i = 0; i < MAX_CELLS; i++) {
+    currentWeek.push({
+      date: new Date(currentDate),
+      inCurrentMonth: currentDate.getMonth() === month,
+      key: dayKey(currentDate),
+    });
+
+    if (currentWeek.length === DAYS_PER_WEEK) {
+      weeks.push(currentWeek);
+      currentWeek = [];
+    }
+
+    currentDate.setDate(currentDate.getDate() + 1);
+
+    // Stop on a week boundary once the month is behind us, so a month that fits
+    // in five rows does not get a trailing sixth.
+    if (currentWeek.length === 0 && currentDate > lastDay) break;
+  }
+
+  return { weeks, month, year };
+};
+
+export const getWeekdayNames = (locale = 'en-US', firstDayOfWeek = 0): string[] => {
+  const baseDate = new Date(2025, 0, 5); // A Sunday
+  const weekdays: string[] = [];
+
+  for (let i = 0; i < DAYS_PER_WEEK; i++) {
+    const date = addDays(baseDate, (i + firstDayOfWeek) % DAYS_PER_WEEK);
+    weekdays.push(date.toLocaleDateString(locale, { weekday: 'narrow' }));
+  }
+
+  return weekdays;
+};
+
+export const getMonthName = (month: number, year: number, locale = 'en-US'): string =>
+  new Date(year, month, 1).toLocaleDateString(locale, { month: 'long', year: 'numeric' });

package/src/components/form/Calendar/Calendar.helpers.ts

@@ -0,0 +1,32 @@
+import type { CalendarProps, ResolvedCalendarProps } from './Calendar.types';
+
+const CALENDAR_DEFAULTS = {
+  selectionMode: 'single',
+  value: null,
+  range: { start: null, end: null },
+  firstDayOfWeek: 0,
+  locale: 'en-US',
+  showOutsideDays: true,
+  minRangeLength: 1,
+  allowSameDayRange: true,
+  autoFocus: false,
+} as const satisfies Partial<CalendarProps>;
+
+// Strips explicitly-undefined props before the merge, so `prop={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: CalendarProps): Partial<CalendarProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<CalendarProps>;
+
+// Applied as a merge rather than destructuring defaults, which would otherwise
+// put nine branches into the component's own complexity budget.
+export const resolveCalendarProps = (props: CalendarProps): ResolvedCalendarProps => {
+  const merged = { ...CALENDAR_DEFAULTS, ...definedProps(props) } as ResolvedCalendarProps;
+
+  // A range needs two months side by side to be picked comfortably; a single
+  // date does not.
+  const defaultMonths = merged.selectionMode === 'range' ? 2 : 1;
+
+  return { ...merged, monthsToShow: merged.numberOfMonths ?? defaultMonths };
+};

package/src/components/form/Calendar/Calendar.hooks.ts

@@ -0,0 +1,278 @@
+import type React from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { addMonths, generateMonthMatrix, getWeekdayNames, normalizeDate } from './Calendar.dates';
+import { ACTIVATION_KEYS, navigateFocus } from './Calendar.keyboard';
+import { isDateDisabledBy, nextRangeStep } from './Calendar.selection';
+import type { MonthMatrix, ResolvedCalendarProps } from './Calendar.types';
+
+const startOfMonth = (date: Date): Date => new Date(date.getFullYear(), date.getMonth(), 1);
+
+// Which day the calendar opens on: whatever is already chosen, else today.
+const initialFocus = (props: ResolvedCalendarProps, today: Date): Date => {
+  if (props.selectionMode === 'single' && props.value) return normalizeDate(props.value);
+  if (props.selectionMode === 'range' && props.range.start) return normalizeDate(props.range.start);
+  return today;
+};
+
+const useCalendarState = (props: ResolvedCalendarProps, today: Date) => {
+  const [focusedDate, setFocusedDate] = useState<Date>(() => initialFocus(props, today));
+  const [hoveredDate, setHoveredDate] = useState<Date | null>(null);
+  const [currentMonth, setCurrentMonth] = useState<Date>(() => startOfMonth(focusedDate));
+
+  return {
+    focusedDate,
+    setFocusedDate,
+    hoveredDate,
+    setHoveredDate,
+    currentMonth,
+    setCurrentMonth,
+  };
+};
+
+const useAutoFocusGrid = (autoFocus: boolean) => {
+  const gridRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (autoFocus && gridRef.current) gridRef.current.focus();
+  }, [autoFocus]);
+
+  return gridRef;
+};
+
+const useVisibleMonths = ({
+  currentMonth,
+  monthsToShow,
+  firstDayOfWeek,
+}: {
+  currentMonth: Date;
+  monthsToShow: number;
+  firstDayOfWeek: number;
+}): MonthMatrix[] =>
+  useMemo(() => {
+    const matrices: MonthMatrix[] = [];
+    let cursor = currentMonth;
+
+    for (let i = 0; i < monthsToShow; i++) {
+      matrices.push(generateMonthMatrix(cursor.getMonth(), cursor.getFullYear(), firstDayOfWeek));
+      cursor = addMonths(cursor, 1);
+    }
+
+    return matrices;
+  }, [currentMonth, monthsToShow, firstDayOfWeek]);
+
+// A click either sets a single date or advances the range by one step; the range
+// rules themselves live in nextRangeStep.
+const useDateClick = ({
+  props,
+  isDisabled,
+  setFocusedDate,
+}: {
+  props: ResolvedCalendarProps;
+  isDisabled: (date: Date) => boolean;
+  setFocusedDate: (date: Date) => void;
+}) => {
+  const {
+    selectionMode,
+    range,
+    onChange,
+    onRangeChange,
+    onIntermediateRangeChange,
+    allowSameDayRange,
+    minRangeLength,
+    maxRangeLength,
+  } = props;
+
+  return useCallback(
+    (date: Date) => {
+      if (isDisabled(date)) return;
+
+      const candidate = normalizeDate(date);
+      setFocusedDate(candidate);
+
+      if (selectionMode === 'single') {
+        onChange?.(candidate);
+        return;
+      }
+
+      const step = nextRangeStep({
+        start: range.start,
+        end: range.end,
+        candidate,
+        allowSameDayRange,
+        minRangeLength,
+        maxRangeLength,
+      });
+
+      if (step.kind === 'rejected') return;
+
+      if (step.kind === 'complete') onRangeChange?.(step.range);
+      onIntermediateRangeChange?.(step.range);
+    },
+    [
+      selectionMode,
+      range,
+      onChange,
+      onRangeChange,
+      onIntermediateRangeChange,
+      isDisabled,
+      allowSameDayRange,
+      minRangeLength,
+      maxRangeLength,
+      setFocusedDate,
+    ],
+  );
+};
+
+// Hovering only means something while a range is half-chosen.
+const useHoverHandlers = ({
+  selectionMode,
+  range,
+  isDisabled,
+  setHoveredDate,
+}: {
+  selectionMode: ResolvedCalendarProps['selectionMode'];
+  range: ResolvedCalendarProps['range'];
+  isDisabled: (date: Date) => boolean;
+  setHoveredDate: (date: Date | null) => void;
+}) => {
+  const handleDateMouseEnter = useCallback(
+    (date: Date) => {
+      if (selectionMode === 'range' && range.start && !range.end && !isDisabled(date)) {
+        setHoveredDate(normalizeDate(date));
+      }
+    },
+    [selectionMode, range, isDisabled, setHoveredDate],
+  );
+
+  const handleDateMouseLeave = useCallback(() => setHoveredDate(null), [setHoveredDate]);
+
+  return { handleDateMouseEnter, handleDateMouseLeave };
+};
+
+const useKeyboardHandler = ({
+  focusedDate,
+  firstDayOfWeek,
+  currentMonth,
+  handleDateClick,
+  setFocusedDate,
+  setCurrentMonth,
+  setHoveredDate,
+}: {
+  focusedDate: Date;
+  firstDayOfWeek: number;
+  currentMonth: Date;
+  handleDateClick: (date: Date) => void;
+  setFocusedDate: (date: Date) => void;
+  setCurrentMonth: (date: Date) => void;
+  setHoveredDate: (date: Date | null) => void;
+}) =>
+  useCallback(
+    (event: React.KeyboardEvent) => {
+      const { key } = event;
+      const moved = navigateFocus(key, focusedDate, { firstDayOfWeek, shiftKey: event.shiftKey });
+
+      if (moved) {
+        event.preventDefault();
+        setFocusedDate(normalizeDate(moved));
+
+        // Follow focus into a month that is not on screen.
+        const month = startOfMonth(moved);
+        if (month.getTime() !== currentMonth.getTime()) setCurrentMonth(month);
+        return;
+      }
+
+      if (ACTIVATION_KEYS.includes(key)) {
+        event.preventDefault();
+        handleDateClick(focusedDate);
+        return;
+      }
+
+      if (key === 'Escape') {
+        event.preventDefault();
+        setHoveredDate(null);
+      }
+    },
+    [
+      focusedDate,
+      firstDayOfWeek,
+      currentMonth,
+      handleDateClick,
+      setFocusedDate,
+      setCurrentMonth,
+      setHoveredDate,
+    ],
+  );
+
+export const useCalendar = (props: ResolvedCalendarProps) => {
+  const { monthsToShow, firstDayOfWeek, locale, minDate, maxDate, isDateDisabled } = props;
+
+  const today = useMemo(() => normalizeDate(new Date()), []);
+  const state = useCalendarState(props, today);
+  const gridRef = useAutoFocusGrid(props.autoFocus);
+
+  const monthMatrices = useVisibleMonths({
+    currentMonth: state.currentMonth,
+    monthsToShow,
+    firstDayOfWeek,
+  });
+
+  const weekdayNames = useMemo(
+    () => getWeekdayNames(locale, firstDayOfWeek),
+    [locale, firstDayOfWeek],
+  );
+
+  const isDisabled = useCallback(
+    (date: Date) => isDateDisabledBy({ date, minDate, maxDate, isDateDisabled }),
+    [minDate, maxDate, isDateDisabled],
+  );
+
+  const { setCurrentMonth } = state;
+  const goToPreviousMonth = useCallback(
+    () => setCurrentMonth((prev) => addMonths(prev, -1)),
+    [setCurrentMonth],
+  );
+  const goToNextMonth = useCallback(
+    () => setCurrentMonth((prev) => addMonths(prev, 1)),
+    [setCurrentMonth],
+  );
+
+  const handleDateClick = useDateClick({
+    props,
+    isDisabled,
+    setFocusedDate: state.setFocusedDate,
+  });
+
+  const { handleDateMouseEnter, handleDateMouseLeave } = useHoverHandlers({
+    selectionMode: props.selectionMode,
+    range: props.range,
+    isDisabled,
+    setHoveredDate: state.setHoveredDate,
+  });
+
+  const handleKeyDown = useKeyboardHandler({
+    focusedDate: state.focusedDate,
+    firstDayOfWeek,
+    currentMonth: state.currentMonth,
+    handleDateClick,
+    setFocusedDate: state.setFocusedDate,
+    setCurrentMonth: state.setCurrentMonth,
+    setHoveredDate: state.setHoveredDate,
+  });
+
+  return {
+    gridRef,
+    today,
+    focusedDate: state.focusedDate,
+    hoveredDate: state.hoveredDate,
+    monthMatrices,
+    weekdayNames,
+    isDisabled,
+    goToPreviousMonth,
+    goToNextMonth,
+    handleDateClick,
+    handleDateMouseEnter,
+    handleDateMouseLeave,
+    handleKeyDown,
+  };
+};

package/src/components/form/Calendar/Calendar.keyboard.ts

@@ -0,0 +1,32 @@
+import { addDays, addMonths, startOfWeek } from './Calendar.dates';
+
+const DAYS_PER_WEEK = 7;
+const MONTHS_PER_YEAR = 12;
+
+interface NavigationContext {
+  firstDayOfWeek: number;
+  shiftKey: boolean;
+}
+
+// A lookup rather than a switch: each entry is one move, and adding a key does
+// not add a branch to the handler.
+const NAVIGATION: Record<string, (date: Date, context: NavigationContext) => Date> = {
+  ArrowLeft: (date) => addDays(date, -1),
+  ArrowRight: (date) => addDays(date, 1),
+  ArrowUp: (date) => addDays(date, -DAYS_PER_WEEK),
+  ArrowDown: (date) => addDays(date, DAYS_PER_WEEK),
+  Home: (date, { firstDayOfWeek }) => startOfWeek(date, firstDayOfWeek),
+  End: (date, { firstDayOfWeek }) => addDays(startOfWeek(date, firstDayOfWeek), DAYS_PER_WEEK - 1),
+  // Shift jumps a year rather than a month.
+  PageUp: (date, { shiftKey }) => addMonths(date, shiftKey ? -MONTHS_PER_YEAR : -1),
+  PageDown: (date, { shiftKey }) => addMonths(date, shiftKey ? MONTHS_PER_YEAR : 1),
+};
+
+export const ACTIVATION_KEYS = ['Enter', ' '];
+
+// Returns where focus moves for a navigation key, or null if the key is not one.
+export const navigateFocus = (
+  key: string,
+  date: Date,
+  context: NavigationContext,
+): Date | null => NAVIGATION[key]?.(date, context) ?? null;

package/src/components/form/Calendar/Calendar.selection.ts

@@ -0,0 +1,156 @@
+import { isBetween, isSameDay, normalizeDate } from './Calendar.dates';
+import type {
+  CalendarProps,
+  DateRange,
+  DayRenderArgs,
+  MonthMatrixDay,
+  SelectionMode,
+} from './Calendar.types';
+
+const MS_PER_DAY = 1000 * 60 * 60 * 24;
+
+type RangeUpdate =
+  | { kind: 'start'; range: DateRange }
+  | { kind: 'complete'; range: Required<DateRange> }
+  | { kind: 'rejected' };
+
+// The endpoints carry their own styling, so "in range" means the interior only.
+const strictlyBetween = (date: Date, start: Date, end: Date): boolean =>
+  isBetween(date, start, end) && !isSameDay(date, start) && !isSameDay(date, end);
+
+const violatesLength = (
+  nights: number,
+  minRangeLength?: number,
+  maxRangeLength?: number,
+): boolean => {
+  if (minRangeLength && nights < minRangeLength - 1) return true;
+  if (maxRangeLength && nights > maxRangeLength - 1) return true;
+  return false;
+};
+
+// Decides what a click on `candidate` does to the current range: opens a new one,
+// closes the open one, or is refused because the result would break a constraint.
+export const nextRangeStep = ({
+  start,
+  end,
+  candidate,
+  allowSameDayRange,
+  minRangeLength,
+  maxRangeLength,
+}: {
+  start?: Date | null;
+  end?: Date | null;
+  candidate: Date;
+  allowSameDayRange: boolean;
+  minRangeLength?: number;
+  maxRangeLength?: number;
+}): RangeUpdate => {
+  // Nothing started, or a finished range: this click opens a new one.
+  if (!start || end) return { kind: 'start', range: { start: candidate, end: null } };
+
+  // Clicking before the start picks the range backwards.
+  const [rangeStart, rangeEnd] = candidate < start ? [candidate, start] : [start, candidate];
+
+  if (!allowSameDayRange && isSameDay(rangeStart, rangeEnd)) return { kind: 'rejected' };
+
+  const nights = Math.ceil((rangeEnd.getTime() - rangeStart.getTime()) / MS_PER_DAY);
+  if (violatesLength(nights, minRangeLength, maxRangeLength)) return { kind: 'rejected' };
+
+  return { kind: 'complete', range: { start: rangeStart, end: rangeEnd } };
+};
+
+const isDateSelected = ({
+  selectionMode,
+  value,
+  range,
+  date,
+}: {
+  selectionMode: SelectionMode;
+  value: Date | null;
+  range: DateRange;
+  date: Date;
+}): boolean => {
+  if (selectionMode === 'single') return value ? isSameDay(date, value) : false;
+
+  const { start, end } = range;
+  return Boolean((start && isSameDay(date, start)) || (end && isSameDay(date, end)));
+};
+
+const isDateInRange = ({
+  selectionMode,
+  range,
+  hoveredDate,
+  date,
+  isDisabled,
+}: {
+  selectionMode: SelectionMode;
+  range: DateRange;
+  hoveredDate: Date | null;
+  date: Date;
+  isDisabled: (date: Date) => boolean;
+}): boolean => {
+  if (selectionMode !== 'range') return false;
+
+  const { start, end } = range;
+  if (start && end) return strictlyBetween(date, start, end);
+
+  // With only one end chosen, hovering previews the range the next click makes.
+  if (!start || !hoveredDate || isDisabled(hoveredDate)) return false;
+
+  const [previewStart, previewEnd] =
+    start < hoveredDate ? [start, hoveredDate] : [hoveredDate, start];
+  return strictlyBetween(date, previewStart, previewEnd);
+};
+
+export const isDateDisabledBy = ({
+  date,
+  minDate,
+  maxDate,
+  isDateDisabled,
+}: {
+  date: Date;
+  minDate?: Date;
+  maxDate?: Date;
+  isDateDisabled?: CalendarProps['isDateDisabled'];
+}): boolean => {
+  // Bounds are normalized to noon so a min/max given at midnight does not
+  // exclude its own day.
+  if (minDate && date < normalizeDate(minDate)) return true;
+  if (maxDate && date > normalizeDate(maxDate)) return true;
+  return Boolean(isDateDisabled?.(date));
+};
+
+// Everything a day cell needs to know about itself, derived in one place so the
+// custom renderDay hook and the built-in cell see exactly the same facts.
+export const buildDayArgs = ({
+  day,
+  selectionMode,
+  value,
+  range,
+  hoveredDate,
+  today,
+  isDisabled,
+}: {
+  day: MonthMatrixDay;
+  selectionMode: SelectionMode;
+  value: Date | null;
+  range: DateRange;
+  hoveredDate: Date | null;
+  today: Date;
+  isDisabled: (date: Date) => boolean;
+}): DayRenderArgs => {
+  const { date, inCurrentMonth } = day;
+  const inRangeMode = selectionMode === 'range';
+
+  return {
+    date,
+    inCurrentMonth,
+    selected: isDateSelected({ selectionMode, value, range, date }),
+    inRange: isDateInRange({ selectionMode, range, hoveredDate, date, isDisabled }),
+    rangeStart: Boolean(inRangeMode && range.start && isSameDay(date, range.start)),
+    rangeEnd: Boolean(inRangeMode && range.end && isSameDay(date, range.end)),
+    disabled: isDisabled(date),
+    today: isSameDay(date, today),
+    hovered: hoveredDate ? isSameDay(date, hoveredDate) : false,
+  };
+};