@mindlogic-ai/logician-ui 2.0.0-alpha.0

package/src/components/MonthRangePicker/MonthRangePicker.stories.tsx

@@ -0,0 +1,164 @@
+import { useState } from 'react';
+import { Box, VStack } from '@chakra-ui/react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { addMonths, subMonths } from 'date-fns';
+
+import { Text } from '@/components/Typography';
+
+import { MonthRangePicker } from './MonthRangePicker';
+import { MonthRange } from './MonthRangePicker.types';
+
+const meta: Meta<typeof MonthRangePicker> = {
+  title: 'Components/MonthRangePicker',
+  component: MonthRangePicker,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    selectedRange: {
+      control: false,
+    },
+    onChange: {
+      control: false,
+    },
+  },
+  decorators: [
+    (Story, context) => {
+      const [selectedRange, setSelectedRange] = useState<MonthRange | null>(
+        context.parameters?.initialRange || null
+      );
+
+      return (
+        <VStack spacing={4} align="start" width="400px">
+          {context.parameters?.additionalContent}
+          <Story
+            args={{
+              ...context.args,
+              selectedRange,
+              onChange: setSelectedRange,
+            }}
+          />
+          {selectedRange && (
+            <Box
+              p={3}
+              bg="green.50"
+              borderRadius="md"
+              width="100%"
+              border="1px solid"
+              borderColor="green.200"
+            >
+              <Text fontSize="sm" fontWeight="semibold" color="green.700">
+                ✓ Range Selected:
+              </Text>
+              <Text fontSize="sm" color="green.600">
+                {selectedRange.startMonth.toLocaleDateString()}
+                {selectedRange.endMonth ? (
+                  <> - {selectedRange.endMonth.toLocaleDateString()}</>
+                ) : (
+                  ' - (selecting...)'
+                )}
+              </Text>
+            </Box>
+          )}
+        </VStack>
+      );
+    },
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof MonthRangePicker>;
+
+export const Default: Story = {};
+
+export const WithInitialValue: Story = {
+  parameters: {
+    initialRange: {
+      startMonth: subMonths(new Date(), 2),
+      endMonth: addMonths(new Date(), 1),
+    },
+  },
+};
+
+export const WithConstraints: Story = {
+  args: {
+    minMonth: subMonths(new Date(), 6),
+    maxMonth: addMonths(new Date(), 6),
+  },
+  parameters: {
+    additionalContent: (
+      <Box>
+        <Text fontSize="md" fontWeight="semibold" mb={2}>
+          With Date Constraints
+        </Text>
+        <Text fontSize="sm" color="gray.600" mb={4}>
+          Only allows selection 6 months before/after current date
+        </Text>
+      </Box>
+    ),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  parameters: {
+    additionalContent: (
+      <Box>
+        <Text fontSize="md" fontWeight="semibold" mb={2}>
+          Disabled State
+        </Text>
+        <Text fontSize="sm" color="gray.600" mb={4}>
+          The picker is disabled and cannot be interacted with
+        </Text>
+      </Box>
+    ),
+  },
+};
+
+export const CustomFormat: Story = {
+  args: {
+    format: 'MMMM yyyy',
+    placeholder: 'Select month range (full month names)',
+  },
+  parameters: {
+    additionalContent: (
+      <Box>
+        <Text fontSize="md" fontWeight="semibold" mb={2}>
+          Custom Date Format
+        </Text>
+        <Text fontSize="sm" color="gray.600" mb={4}>
+          Uses full month names (MMMM yyyy) instead of abbreviated
+        </Text>
+      </Box>
+    ),
+  },
+};
+
+export const CrossYearSelection: Story = {
+  parameters: {
+    additionalContent: (
+      <Box>
+        <Text fontSize="md" fontWeight="semibold" mb={2}>
+          Cross-Year Range Selection
+        </Text>
+        <Text fontSize="sm" color="gray.600" mb={4}>
+          Demonstrates selecting ranges across different years with immediate
+          feedback.
+        </Text>
+        <Box fontSize="sm" color="gray.700">
+          <Text>
+            • Click a month to start selection (shows immediately in input)
+          </Text>
+          <Text>
+            • Use year navigation arrows to navigate to different years
+          </Text>
+          <Text>• Click a month in another year to complete the range</Text>
+          <Text>• Try selecting from Dec 2024 to Mar 2025</Text>
+        </Box>
+      </Box>
+    ),
+  },
+};

package/src/components/MonthRangePicker/MonthRangePicker.tsx

@@ -0,0 +1,274 @@
+'use client';
+
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  Box,
+  Button,
+  Grid,
+  HStack,
+  Input,
+  InputGroup,
+  InputLeftElement,
+  Popover,
+  PopoverBody,
+  PopoverContent,
+  PopoverTrigger,
+  Portal,
+  useDisclosure,
+  VStack,
+} from '@chakra-ui/react';
+import { format, isAfter, isSameMonth } from 'date-fns';
+
+import { Text } from '@/components/Typography';
+import useLocale from '@/hooks/useLocale';
+import { useTranslate } from '@/hooks/useTranslate';
+
+import { Icon } from '../Icon';
+import { hasEnabledMonthsInYear, isMonthDisabled } from './_utils';
+import {
+  getDateFnsLocale,
+  getDefaultDateFormat,
+  getMonthNames,
+} from './constants';
+import { MonthButton } from './MonthButton/MonthButton';
+import { MonthRange, MonthRangePickerProps } from './MonthRangePicker.types';
+
+export const MonthRangePicker: React.FC<MonthRangePickerProps> = ({
+  selectedRange,
+  onChange,
+  minMonth,
+  maxMonth,
+  disabled = false,
+  placeholder,
+  format: dateFormat, // Remove default here, will be set dynamically
+  usePortal = true,
+  popoverProps,
+  name,
+  ...boxProps
+}) => {
+  const { isOpen, onOpen, onClose } = useDisclosure();
+  const { language: locale } = useLocale();
+  const translate = useTranslate();
+
+  const [currentYear, setCurrentYear] = useState(() =>
+    new Date().getFullYear()
+  );
+  const [selectionStart, setSelectionStart] = useState<Date | null>(null);
+  const [hoveredMonth, setHoveredMonth] = useState<{
+    month: number;
+    year: number;
+  } | null>(null);
+
+  // Get localized month names, date-fns locale, and default format
+  const monthNames = useMemo(() => getMonthNames(locale), [locale]);
+  const dateFnsLocale = useMemo(() => getDateFnsLocale(locale), [locale]);
+  const effectiveDateFormat = useMemo(
+    () => dateFormat || getDefaultDateFormat(locale),
+    [dateFormat, locale]
+  );
+
+  // Use translated placeholder if not provided
+  const effectivePlaceholder =
+    placeholder || (translate('month_range_placeholder') as string);
+
+  const displayValue = useMemo(() => {
+    // If we have a complete range, show start - end
+    if (selectedRange?.endMonth) {
+      const start = format(selectedRange.startMonth, effectiveDateFormat, {
+        locale: dateFnsLocale,
+      });
+      const end = format(selectedRange.endMonth, effectiveDateFormat, {
+        locale: dateFnsLocale,
+      });
+      return `${start} - ${end}`;
+    }
+
+    // If we have a partial range (selectedRange with only startMonth) or selection start, show just the start date
+    if (selectedRange?.startMonth || selectionStart) {
+      const startDate = selectedRange?.startMonth || selectionStart;
+      if (startDate) {
+        const start = format(startDate, effectiveDateFormat, {
+          locale: dateFnsLocale,
+        });
+        return `${start} -`;
+      }
+    }
+
+    // No selection at all
+    return '';
+  }, [selectedRange, selectionStart, effectiveDateFormat, dateFnsLocale]);
+
+  // Check if navigation to previous/next year is possible
+  const canNavigateToPrevYear = useMemo(() => {
+    return hasEnabledMonthsInYear(currentYear - 1, minMonth, maxMonth);
+  }, [currentYear, minMonth, maxMonth]);
+
+  const canNavigateToNextYear = useMemo(() => {
+    return hasEnabledMonthsInYear(currentYear + 1, minMonth, maxMonth);
+  }, [currentYear, minMonth, maxMonth]);
+
+  const handleYearChange = useCallback(
+    (direction: 'prev' | 'next') => {
+      const targetYear =
+        direction === 'prev' ? currentYear - 1 : currentYear + 1;
+
+      // Only navigate if the target year has enabled months
+      if (hasEnabledMonthsInYear(targetYear, minMonth, maxMonth)) {
+        setCurrentYear(targetYear);
+        // Keep selectionStart to allow cross-year range selection
+      }
+    },
+    [currentYear, minMonth, maxMonth]
+  );
+
+  const handleMonthClick = useCallback(
+    (month: number, year: number) => {
+      if (isMonthDisabled(month, year, minMonth, maxMonth)) return;
+
+      const clickedMonth = new Date(year, month, 1);
+
+      if (!selectionStart) {
+        // If there's an existing complete range, clear it and start fresh
+        if (selectedRange) {
+          onChange?.(null);
+        }
+        // Start new selection and notify parent with partial range
+        setSelectionStart(clickedMonth);
+        // Call onChange with partial range to update parent state
+        onChange?.({ startMonth: clickedMonth, endMonth: null });
+      } else {
+        // Complete the selection
+        const startMonth = selectionStart;
+        const endMonth = clickedMonth;
+
+        if (isSameMonth(startMonth, endMonth)) {
+          // Same month selected, create single-month range
+          onChange?.({
+            startMonth,
+            endMonth,
+          });
+        } else {
+          // Different months, ensure proper order
+          const range: MonthRange = isAfter(startMonth, endMonth)
+            ? { startMonth: endMonth, endMonth: startMonth }
+            : { startMonth, endMonth };
+
+          onChange?.(range);
+        }
+
+        setSelectionStart(null);
+        onClose();
+      }
+    },
+    [selectionStart, selectedRange, onChange, onClose, minMonth, maxMonth]
+  );
+
+  const handleMonthHover = useCallback((month: number, year: number) => {
+    setHoveredMonth({ month, year });
+  }, []);
+
+  const handleMonthHoverLeave = useCallback(() => {
+    setHoveredMonth(null);
+  }, []);
+
+  const handleClear = useCallback(() => {
+    onChange?.(null);
+    setSelectionStart(null);
+  }, [onChange]);
+
+  const popoverContent = (
+    <PopoverContent width="320px">
+      <PopoverBody>
+        <VStack spacing={4} align="stretch">
+          {/* Year Navigation */}
+          <HStack justify="space-between" align="center">
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={() => handleYearChange('prev')}
+              disabled={!canNavigateToPrevYear}
+              opacity={!canNavigateToPrevYear ? 0.4 : 1}
+            >
+              <Icon icon="IoIosArrowBack" />
+            </Button>
+
+            <Text fontWeight="semibold" fontSize="lg">
+              {currentYear}
+            </Text>
+
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={() => handleYearChange('next')}
+              disabled={!canNavigateToNextYear}
+              opacity={!canNavigateToNextYear ? 0.4 : 1}
+            >
+              <Icon icon="IoChevronForward" />
+            </Button>
+          </HStack>
+
+          {/* Months Grid */}
+          <Grid templateColumns="repeat(3, 1fr)" gap={2}>
+            {monthNames.map((monthName, monthIndex) => (
+              <MonthButton
+                key={monthIndex}
+                month={monthIndex}
+                year={currentYear}
+                monthName={monthName}
+                selectedRange={selectedRange}
+                selectionStart={selectionStart}
+                hoveredMonth={hoveredMonth}
+                minMonth={minMonth}
+                maxMonth={maxMonth}
+                onClick={handleMonthClick}
+                onMouseEnter={handleMonthHover}
+                onMouseLeave={handleMonthHoverLeave}
+              />
+            ))}
+          </Grid>
+
+          {/* Action Buttons */}
+          <HStack spacing={2} justify="flex-end">
+            <Button size="sm" variant="ghost" onClick={handleClear}>
+              {translate('clear')}
+            </Button>
+          </HStack>
+        </VStack>
+      </PopoverBody>
+    </PopoverContent>
+  );
+
+  return (
+    <Box {...boxProps}>
+      <Popover
+        isOpen={isOpen}
+        onOpen={onOpen}
+        onClose={onClose}
+        placement="bottom-start"
+        {...popoverProps}
+      >
+        <PopoverTrigger>
+          <InputGroup>
+            <InputLeftElement>
+              <Icon
+                icon="MdOutlineCalendarToday"
+                boxSize="xs"
+                color="gray.800"
+              />
+            </InputLeftElement>
+            <Input
+              name={name}
+              value={displayValue}
+              placeholder={effectivePlaceholder}
+              readOnly
+              disabled={disabled}
+              cursor={disabled ? 'not-allowed' : 'pointer'}
+              onClick={disabled ? undefined : onOpen}
+            />
+          </InputGroup>
+        </PopoverTrigger>
+        {usePortal ? <Portal>{popoverContent}</Portal> : popoverContent}
+      </Popover>
+    </Box>
+  );
+};

package/src/components/MonthRangePicker/MonthRangePicker.types.ts

@@ -0,0 +1,38 @@
+import { BoxProps, PopoverProps } from '@chakra-ui/react';
+
+export interface MonthRange {
+  startMonth: Date;
+  endMonth: Date | null;
+}
+
+export interface MonthRangePickerProps extends Omit<BoxProps, 'onChange'> {
+  /** The selected month range */
+  selectedRange?: MonthRange | null;
+
+  /** Callback when the month range changes */
+  onChange?: (range: MonthRange | null) => void;
+
+  /** Minimum selectable month */
+  minMonth?: Date;
+
+  /** Maximum selectable month */
+  maxMonth?: Date;
+
+  /** Whether the picker is disabled */
+  disabled?: boolean;
+
+  /** Placeholder text for the input */
+  placeholder?: string;
+
+  /** Format for displaying the selected range */
+  format?: string;
+
+  /** Whether to use portal for the popover */
+  usePortal?: boolean;
+
+  /** Props for the popover */
+  popoverProps?: Partial<PopoverProps>;
+
+  /** Name attribute for form usage */
+  name?: string;
+}

package/src/components/MonthRangePicker/_utils/hasEnabledMonthsInYear.ts

@@ -0,0 +1,15 @@
+import { isMonthDisabled } from './isMonthDisabled';
+
+export const hasEnabledMonthsInYear = (
+  year: number,
+  minMonth?: Date,
+  maxMonth?: Date
+): boolean => {
+  // Check all 12 months (0-11) to see if any are enabled
+  for (let month = 0; month < 12; month++) {
+    if (!isMonthDisabled(month, year, minMonth, maxMonth)) {
+      return true;
+    }
+  }
+  return false;
+};

package/src/components/MonthRangePicker/_utils/index.ts

@@ -0,0 +1,6 @@
+export { hasEnabledMonthsInYear } from './hasEnabledMonthsInYear';
+export { isMonthDisabled } from './isMonthDisabled';
+export { isMonthInPreviewRange } from './isMonthInPreviewRange';
+export { isMonthInRange } from './isMonthInRange';
+export { isMonthSelected } from './isMonthSelected';
+export { isSelectionStart } from './isSelectionStart';

package/src/components/MonthRangePicker/_utils/isMonthDisabled.ts

@@ -0,0 +1,20 @@
+import { isAfter, isBefore, startOfMonth } from 'date-fns';
+
+export const isMonthDisabled = (
+  month: number,
+  year: number,
+  minMonth?: Date,
+  maxMonth?: Date
+): boolean => {
+  const monthDate = new Date(year, month, 1);
+
+  if (minMonth && isBefore(monthDate, startOfMonth(minMonth))) {
+    return true;
+  }
+
+  if (maxMonth && isAfter(monthDate, startOfMonth(maxMonth))) {
+    return true;
+  }
+
+  return false;
+};

package/src/components/MonthRangePicker/_utils/isMonthInPreviewRange.ts

@@ -0,0 +1,32 @@
+import { isAfter, isBefore, isSameMonth } from 'date-fns';
+
+export const isMonthInPreviewRange = (
+  month: number,
+  year: number,
+  selectionStart: Date | null,
+  hoveredMonth: { month: number; year: number } | null
+): boolean => {
+  if (!selectionStart || !hoveredMonth) return false;
+
+  const monthDate = new Date(year, month, 1);
+  const hoveredDate = new Date(hoveredMonth.year, hoveredMonth.month, 1);
+
+  // Don't highlight if hovering the same month as selection start
+  if (
+    isSameMonth(monthDate, selectionStart) ||
+    isSameMonth(monthDate, hoveredDate)
+  ) {
+    return false;
+  }
+
+  // Determine range boundaries (start could be before or after hovered)
+  const rangeStart = isBefore(selectionStart, hoveredDate)
+    ? selectionStart
+    : hoveredDate;
+  const rangeEnd = isAfter(selectionStart, hoveredDate)
+    ? selectionStart
+    : hoveredDate;
+
+  // Check if month is between start and end (exclusive)
+  return isAfter(monthDate, rangeStart) && isBefore(monthDate, rangeEnd);
+};

package/src/components/MonthRangePicker/_utils/isMonthInRange.ts

@@ -0,0 +1,17 @@
+import { startOfMonth } from 'date-fns';
+
+import { MonthRange } from '../MonthRangePicker.types';
+
+export const isMonthInRange = (
+  month: number,
+  year: number,
+  selectedRange?: MonthRange | null
+): boolean => {
+  if (!selectedRange || !selectedRange.endMonth) return false;
+
+  const monthDate = new Date(year, month, 1);
+  const start = startOfMonth(selectedRange.startMonth);
+  const end = startOfMonth(selectedRange.endMonth);
+
+  return monthDate >= start && monthDate <= end;
+};

package/src/components/MonthRangePicker/_utils/isMonthSelected.ts

@@ -0,0 +1,19 @@
+import { isSameMonth } from 'date-fns';
+
+import { MonthRange } from '../MonthRangePicker.types';
+
+export const isMonthSelected = (
+  month: number,
+  year: number,
+  selectedRange?: MonthRange | null
+): boolean => {
+  if (!selectedRange) return false;
+
+  const monthDate = new Date(year, month, 1);
+  return (
+    isSameMonth(monthDate, selectedRange.startMonth) ||
+    (selectedRange.endMonth
+      ? isSameMonth(monthDate, selectedRange.endMonth)
+      : false)
+  );
+};

package/src/components/MonthRangePicker/_utils/isSelectionStart.ts

@@ -0,0 +1,12 @@
+import { isSameMonth } from 'date-fns';
+
+export const isSelectionStart = (
+  month: number,
+  year: number,
+  selectionStart?: Date | null
+): boolean => {
+  if (!selectionStart) return false;
+
+  const monthDate = new Date(year, month, 1);
+  return isSameMonth(monthDate, selectionStart);
+};

package/src/components/MonthRangePicker/constants.ts

@@ -0,0 +1,63 @@
+import { format } from 'date-fns';
+import { enUS, es, ja, ko, zhCN } from 'date-fns/locale';
+
+// Map language codes to date-fns locales
+const LOCALE_MAP = {
+  ko: ko,
+  en: enUS,
+  zh: zhCN,
+  ja: ja,
+  es: es,
+} as const;
+
+// Map language codes to culturally appropriate date formats
+const DEFAULT_FORMAT_MAP = {
+  ko: 'yyyy년 MMM', // 2024년 3월
+  en: 'MMM yyyy', // Mar 2024
+  zh: 'yyyy年MMM', // 2024年3月
+  ja: 'yyyy年MMM', // 2024年3月
+  es: 'MMM yyyy', // mar 2024
+} as const;
+
+/**
+ * Get the default date format for a given locale
+ * @param language Language code (ko, en, zh, ja, es)
+ * @returns Appropriate date format string for the locale
+ */
+export const getDefaultDateFormat = (language: string = 'en'): string => {
+  return (
+    DEFAULT_FORMAT_MAP[language as keyof typeof DEFAULT_FORMAT_MAP] ||
+    DEFAULT_FORMAT_MAP.en
+  );
+};
+
+/**
+ * Generate month names for the given locale
+ * @param language Language code (ko, en, zh, ja, es)
+ * @param monthFormat Format string for month names (default: 'MMM' for abbreviated)
+ * @returns Array of month names in the specified locale
+ */
+export const getMonthNames = (
+  language: string = 'en',
+  monthFormat: string = 'MMM'
+): string[] => {
+  const locale =
+    LOCALE_MAP[language as keyof typeof LOCALE_MAP] || LOCALE_MAP.en;
+
+  return Array.from({ length: 12 }, (_, monthIndex) => {
+    const date = new Date(2024, monthIndex, 1); // Use 2024 as a reference year
+    return format(date, monthFormat, { locale });
+  });
+};
+
+/**
+ * Get date-fns locale object for the given language
+ * @param language Language code (ko, en, zh, ja, es)
+ * @returns date-fns locale object
+ */
+export const getDateFnsLocale = (language: string = 'en') => {
+  return LOCALE_MAP[language as keyof typeof LOCALE_MAP] || LOCALE_MAP.en;
+};
+
+// Legacy export for backward compatibility (English abbreviated months)
+export const MONTHS = getMonthNames('en', 'MMM');

package/src/components/MonthRangePicker/index.ts

@@ -0,0 +1,2 @@
+export { MonthRangePicker } from './MonthRangePicker';
+export type { MonthRangePickerProps } from './MonthRangePicker.types';