@scalepad/ui 0.1.0

package/src/components/DatePicker/DateNavigator.tsx

@@ -0,0 +1,486 @@
+/**
+ * DateNavigator Component
+ *
+ * TIMEZONE SAFETY:
+ * This component handles ISO date strings (e.g., "2026-01-25") from URL params.
+ * All date parsing uses toDate() from @scalepad/ui-utils/date which leverages dayjs to:
+ * - Parse ISO date strings as local timezone midnight (not UTC)
+ * - Avoid off-by-one day errors caused by timezone offsets
+ * - Maintain consistency: "2026-01-25" → parse → calculate → format → "2026-01-25"
+ *
+ * All date utilities (addMonths, startOfMonth, etc.) use dayjs internally,
+ * ensuring timezone-safe calculations throughout the component.
+ */
+import { useEffect, useMemo, useState } from 'react';
+
+import {
+  Calendar,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  X,
+} from 'lucide-react';
+
+import {
+  Box,
+  Flex,
+  Overlay,
+  Popover,
+  Portal,
+  UnstyledButton,
+  type PopoverProps,
+} from '@mantine/core';
+import type { DateValue } from '@mantine/dates';
+
+import {
+  addMonths,
+  addYears,
+  DateFormat,
+  endOfMonth,
+  endOfYear,
+  formatDate,
+  getCurrentDate,
+  getCurrentQuarter,
+  getNextQuarter,
+  getPreviousQuarter,
+  getQuarterRange,
+  isAfter,
+  startOfMonth,
+  startOfYear,
+  toDate,
+} from '@scalepad/ui-utils/date';
+
+import { zIndex } from '../../tokens';
+import { Button, type ButtonProps } from '../Button';
+import { IconButton } from '../IconButton';
+import { Title } from '../Typography';
+import { DatePicker } from './DatePicker';
+
+import type { DatePickerGranularity, DateRange } from './types';
+
+export interface DateNavigatorProps {
+  startDate: DateValue;
+  endDate: DateValue;
+  granularity: DatePickerGranularity;
+  onDateChange: (range: DateRange, granularity: DatePickerGranularity) => void;
+  /** Component variant: 'navigation' (with arrows) or 'button' (standalone button) */
+  variant?: 'navigation' | 'button';
+  /** Allowed range types to show in picker. If not specified, all types are allowed. */
+  allowedRangeTypes?: DatePickerGranularity[];
+  className?: string;
+  /** Show prev/next navigation buttons (only for 'navigation' variant) - defaults to true */
+  showNavigation?: boolean;
+  /** Show calendar icon beside the date - defaults to true */
+  showCalendarIcon?: boolean;
+  /** Show dropdown icon (only for 'button' variant) - defaults to true */
+  showDropdownIcon?: boolean;
+  /** Popover position - defaults to 'bottom-start' */
+  popoverPosition?: PopoverProps['position'];
+  /** Date format: 'short' (e.g., "Jan 2026") or 'long' (e.g., "January 2026") */
+  dateFormat?: 'short' | 'long';
+  /** Maximum historical date that can be selected */
+  maxDataHistory?: DateValue;
+  /** Button variant (only for 'button' variant) */
+  buttonVariant?: ButtonProps['variant'];
+  /** Button width (only for 'button' variant) */
+  buttonWidth?: string | number;
+  /** Button height (only for 'button' variant) */
+  buttonHeight?: string | number;
+  /** Show loading spinner inside the button (only for 'button' variant) */
+  loading?: boolean;
+  /** Custom right section content (only for 'button' variant) - overrides dropdown icon */
+  rightSection?: React.ReactNode;
+}
+
+/**
+ * Navigation strategies for different range types
+ * Extracted to avoid duplication and make logic testable
+ */
+type NavigationStrategy = {
+  getLabel: (start: Date, end: Date, format: 'short' | 'long') => string;
+  navigatePrevious: (start: Date, end: Date) => DateRange;
+  navigateNext: (start: Date, end: Date) => DateRange;
+};
+
+const navigationStrategies: Record<DatePickerGranularity, NavigationStrategy> =
+  {
+    monthly: {
+      getLabel: (start, _end, format) =>
+        formatDate(
+          start,
+          format === 'long'
+            ? DateFormat.MONTH_YEAR_LONG
+            : DateFormat.MONTH_YEAR,
+        ),
+      navigatePrevious: (start, _end) => {
+        const prev = addMonths(start, -1);
+        return {
+          startDate: startOfMonth(prev),
+          endDate: endOfMonth(prev),
+        };
+      },
+      navigateNext: (start, _end) => {
+        const next = addMonths(start, 1);
+        return {
+          startDate: startOfMonth(next),
+          endDate: endOfMonth(next),
+        };
+      },
+    },
+    quarterly: {
+      getLabel: (start, _end, _format) => {
+        // Quarterly format doesn't change with format option
+        const q = getCurrentQuarter(start);
+        return `Q${q.quarter + 1} ${q.year}`;
+      },
+      navigatePrevious: (start, _end) => {
+        const prevQ = getPreviousQuarter(start);
+        const range = getQuarterRange(prevQ.year, prevQ.quarter);
+        return {
+          startDate: range.start,
+          endDate: range.end,
+        };
+      },
+      navigateNext: (start, _end) => {
+        const nextQ = getNextQuarter(start);
+        const range = getQuarterRange(nextQ.year, nextQ.quarter);
+        return {
+          startDate: range.start,
+          endDate: range.end,
+        };
+      },
+    },
+    yearly: {
+      getLabel: (start, _end, _format) => formatDate(start, DateFormat.YEAR),
+      navigatePrevious: (start, _end) => {
+        const prev = addYears(start, -1);
+        return {
+          startDate: startOfYear(prev),
+          endDate: endOfYear(prev),
+        };
+      },
+      navigateNext: (start, _end) => {
+        const next = addYears(start, 1);
+        return {
+          startDate: startOfYear(next),
+          endDate: endOfYear(next),
+        };
+      },
+    },
+    custom: {
+      getLabel: (start, end, _format) => {
+        // Custom range format doesn't change with format option
+        const currentYear = getCurrentDate().getFullYear();
+        const includeYear =
+          start.getFullYear() !== currentYear ||
+          end.getFullYear() !== currentYear;
+
+        if (includeYear) {
+          return `${formatDate(start, DateFormat.SHORT_NO_COMMA)} - ${formatDate(
+            end,
+            DateFormat.SHORT_NO_COMMA,
+          )}`;
+        }
+        return `${formatDate(start, DateFormat.SHORT_NO_YEAR)} - ${formatDate(
+          end,
+          DateFormat.SHORT_NO_YEAR,
+        )}`;
+      },
+      navigatePrevious: (start, end) => {
+        // Calculate duration and create new dates from timestamps
+        // Timestamps are timezone-safe: getTime() returns UTC ms, Date constructor handles conversion
+        const duration = end.getTime() - start.getTime();
+        return {
+          startDate: new Date(start.getTime() - duration),
+          endDate: new Date(start.getTime()),
+        };
+      },
+      navigateNext: (start, end) => {
+        // Calculate duration and create new dates from timestamps
+        // Timestamps are timezone-safe: getTime() returns UTC ms, Date constructor handles conversion
+        const duration = end.getTime() - start.getTime();
+        return {
+          startDate: new Date(end.getTime()),
+          endDate: new Date(end.getTime() + duration),
+        };
+      },
+    },
+  };
+
+export function DateNavigator({
+  startDate,
+  endDate,
+  granularity,
+  onDateChange,
+  variant = 'navigation',
+  allowedRangeTypes,
+  className,
+  showNavigation = true,
+  showCalendarIcon = true,
+  showDropdownIcon = true,
+  popoverPosition = 'bottom-start',
+  dateFormat = 'short',
+  maxDataHistory,
+  buttonVariant = 'outline',
+  buttonWidth = 170,
+  buttonHeight = 36,
+  loading = false,
+  rightSection,
+}: DateNavigatorProps) {
+  const [opened, setOpened] = useState(false);
+
+  useEffect(() => {
+    if (opened) {
+      document.body.style.overflow = 'hidden';
+      return () => {
+        document.body.style.overflow = '';
+      };
+    }
+
+    return undefined;
+  }, [opened]);
+
+  // Temporary selection state while picker is open (before Apply is clicked)
+  const [tempStartDate, setTempStartDate] = useState<DateValue>(startDate);
+  const [tempEndDate, setTempEndDate] = useState<DateValue>(endDate);
+  const [tempRangeType, setTempRangeType] =
+    useState<DatePickerGranularity>(granularity);
+
+  // Convert DateValue to Date for calculations
+  // toDate() uses dayjs which correctly parses ISO date strings (e.g., "2026-01-25")
+  // as local timezone midnight, avoiding timezone offset issues
+  const currentStart = useMemo(
+    () => (startDate ? toDate(startDate) : new Date()),
+    [startDate],
+  );
+  const currentEnd = useMemo(
+    () => (endDate ? toDate(endDate) : new Date()),
+    [endDate],
+  );
+
+  // Get the strategy for current range type
+  const strategy = navigationStrategies[granularity];
+
+  // Get display label using strategy pattern
+  const displayLabel = useMemo(
+    () => strategy.getLabel(currentStart, currentEnd, dateFormat),
+    [strategy, currentStart, currentEnd, dateFormat],
+  );
+
+  // Check if navigating to next period would go into the future
+  const isNextDisabled = useMemo(() => {
+    if (!startDate || !endDate) return false;
+    const today = getCurrentDate();
+    const nextRange = strategy.navigateNext(currentStart, currentEnd);
+    // Disable if the next period's start date is after today
+    if (!nextRange.startDate) return false;
+    const nextStart =
+      nextRange.startDate instanceof Date
+        ? nextRange.startDate
+        : toDate(nextRange.startDate);
+    return isAfter(nextStart, today);
+  }, [startDate, endDate, strategy, currentStart, currentEnd]);
+
+  // Navigate to previous period using strategy
+  const handlePrevious = () => {
+    if (!startDate || !endDate) return;
+    const newRange = strategy.navigatePrevious(currentStart, currentEnd);
+    onDateChange(newRange, granularity);
+  };
+
+  // Navigate to next period using strategy
+  const handleNext = () => {
+    if (!startDate || !endDate || isNextDisabled) return;
+    const newRange = strategy.navigateNext(currentStart, currentEnd);
+    onDateChange(newRange, granularity);
+  };
+
+  // When opening picker, initialize temp state with current values
+  const handleOpen = () => {
+    setTempStartDate(startDate);
+    setTempEndDate(endDate);
+    setTempRangeType(granularity);
+    setOpened(true);
+  };
+
+  // Handle changes while picker is open (before Apply)
+  const handleChange = (
+    range: DateRange,
+    newRangeType: DatePickerGranularity,
+  ) => {
+    setTempStartDate(range.startDate);
+    setTempEndDate(range.endDate);
+    setTempRangeType(newRangeType);
+  };
+
+  // When Apply is clicked, commit the changes
+  const handleApply = (
+    range: DateRange,
+    newRangeType: DatePickerGranularity,
+  ) => {
+    setOpened(false);
+    onDateChange(range, newRangeType);
+  };
+
+  // Shared dropdown content for both variants
+  const renderDatePickerDropdown = () => (
+    <Popover.Dropdown w="860px" p="md">
+      <Box pos="relative">
+        <IconButton
+          variant="ghost"
+          color="gray"
+          onClick={() => setOpened(false)}
+          title="Close"
+          aria-label="Close date picker"
+          pos="absolute"
+          top={-8}
+          right={-8}
+          style={{ zIndex: zIndex.base }}
+        >
+          <X size={16} />
+        </IconButton>
+        <DatePicker
+          startDate={tempStartDate}
+          endDate={tempEndDate}
+          granularity={tempRangeType}
+          allowedRangeTypes={allowedRangeTypes}
+          maxDataHistory={maxDataHistory}
+          onChange={handleChange}
+          onApply={handleApply}
+        />
+      </Box>
+    </Popover.Dropdown>
+  );
+
+  // Shared overlay for both variants
+  const renderOverlay = () =>
+    opened ? (
+      <Portal>
+        <Overlay
+          opacity={0.5}
+          color="black"
+          zIndex={zIndex.dropdownOverlay}
+          fixed
+        />
+      </Portal>
+    ) : null;
+
+  // Shared Popover props for both variants
+  const popoverProps = {
+    opened,
+    onChange: setOpened,
+    trapFocus: true,
+    position: popoverPosition,
+    offset: 16,
+    transitionProps: { duration: 0 },
+  };
+
+  // Render button variant
+  if (variant === 'button') {
+    // Determine right section: custom rightSection takes precedence, then dropdown icon
+    const buttonRightSection =
+      rightSection ??
+      (showDropdownIcon ? <ChevronDown size={16} /> : undefined);
+
+    return (
+      <>
+        <Popover {...popoverProps}>
+          <Popover.Target>
+            <Button
+              variant={buttonVariant}
+              onClick={handleOpen}
+              aria-label="Select date range"
+              leftSection={
+                showCalendarIcon ? <Calendar size={20} /> : undefined
+              }
+              rightSection={buttonRightSection}
+              className={className}
+              h={buttonHeight}
+              px="xs"
+              fz="sm"
+              fw={400}
+              loading={loading}
+              styles={{
+                root: {
+                  width:
+                    typeof buttonWidth === 'number'
+                      ? `${buttonWidth}px`
+                      : buttonWidth,
+                  justifyContent: 'flex-start',
+                },
+              }}
+            >
+              {displayLabel}
+            </Button>
+          </Popover.Target>
+          {renderDatePickerDropdown()}
+        </Popover>
+        {renderOverlay()}
+      </>
+    );
+  }
+
+  // Render navigation variant (default)
+  return (
+    <>
+      <Flex gap={{ base: 'xs', sm: 'lg' }} align="center" className={className}>
+        {showNavigation && (
+          <IconButton
+            variant="ghost"
+            color="gray"
+            size="md"
+            radius="lg"
+            aria-label="Previous period"
+            onClick={handlePrevious}
+          >
+            <ChevronLeft size={16} />
+          </IconButton>
+        )}
+
+        <Popover {...popoverProps}>
+          <Popover.Target>
+            <UnstyledButton onClick={handleOpen}>
+              <Flex gap="xs" align="center">
+                {showCalendarIcon && (
+                  <Box
+                    component="span"
+                    style={{ display: 'flex', alignItems: 'center' }}
+                  >
+                    <Calendar size={20} />
+                  </Box>
+                )}
+                <Title
+                  variant="heading5"
+                  style={{
+                    cursor: 'pointer',
+                    userSelect: 'none',
+                    whiteSpace: 'nowrap',
+                  }}
+                >
+                  {displayLabel}
+                </Title>
+              </Flex>
+            </UnstyledButton>
+          </Popover.Target>
+          {renderDatePickerDropdown()}
+        </Popover>
+
+        {showNavigation && (
+          <IconButton
+            variant="ghost"
+            color="gray"
+            size={40}
+            radius="lg"
+            aria-label="Next period"
+            onClick={handleNext}
+            disabled={isNextDisabled}
+            style={{ opacity: isNextDisabled ? 0.3 : 1 }}
+          >
+            <ChevronRight size={16} />
+          </IconButton>
+        )}
+      </Flex>
+      {renderOverlay()}
+    </>
+  );
+}