@coreui/vue-pro 5.13.0 → 5.15.0

package/src/components/calendar/utils.ts

@@ -1,39 +1,528 @@
 import type { DisabledDate, SelectionTypes, ViewTypes } from './types'
 
+// Shared helper types for date parsing
+export type BaseGroups = {
+  year: string
+  month: string
+  day: string
+}
+
+export type WeekGroups = {
+  year: string
+  week: string
+}
+
+export type MonthGroups = {
+  year: string
+  month: string
+}
+
+export type YearGroups = {
+  year: string
+}
+
 /**
  * Converts an ISO week string to a Date object representing the Monday of that week.
  * @param isoWeek - The ISO week string (e.g., "2023W05" or "2023w05").
  * @returns The Date object for the Monday of the specified week, or null if invalid.
  */
+/**
+ * Helper function to calculate Monday of ISO week 1 for a given year.
+ * @param year - The year to calculate for.
+ * @returns The Monday of ISO week 1.
+ */
+const getMondayOfISOWeek1 = (year: number): Date => {
+  const jan4 = new Date(year, 0, 4)
+  const jan4DayOfWeek = jan4.getDay()
+  const daysFromMonday = jan4DayOfWeek === 0 ? 6 : jan4DayOfWeek - 1 // Sunday = 6 days from Monday
+  const mondayOfWeek1 = new Date(jan4)
+  mondayOfWeek1.setDate(jan4.getDate() - daysFromMonday)
+  return mondayOfWeek1
+}
+
+/**
+ * Helper function to calculate Monday of a specific ISO week.
+ * @param year - The year.
+ * @param week - The ISO week number.
+ * @returns The Monday of the specified ISO week.
+ */
+const getMondayOfISOWeek = (year: number, week: number): Date => {
+  const mondayOfWeek1 = getMondayOfISOWeek1(year)
+  const weekStart = new Date(mondayOfWeek1)
+  // prettier-ignore
+  weekStart.setDate(mondayOfWeek1.getDate() + ((week - 1) * 7))
+  return weekStart
+}
+
+/**
+ * Helper function to convert a date to a month number for comparison.
+ * @param date - The date to convert.
+ * @returns A number representing year*12 + month for easy comparison.
+ */
+const dateToMonthNumber = (date: Date): number => {
+  // prettier-ignore
+  return (date.getFullYear() * 12) + date.getMonth()
+}
+
+/**
+ * Helper function to check if a value is within min/max range.
+ * @param value - The value to check.
+ * @param min - Minimum allowed value (null means no minimum).
+ * @param max - Maximum allowed value (null means no maximum).
+ * @returns True if the value is outside the range, false if within range.
+ */
+const isOutsideRange = (value: number, min: number | null, max: number | null): boolean => {
+  if (min !== null && value < min) {
+    return true
+  }
+  if (max !== null && value > max) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Converts an ISO week string to a Date object representing the Monday of that week.
+ * @param isoWeek - The ISO week string (e.g., "2023W05" or "2023w05").
+ * @returns The Date object for the Monday of the specified week.
+ */
 export const convertIsoWeekToDate = (isoWeek: string): Date => {
   const [year, week] = isoWeek.split(/[Ww]/)
-  const date = new Date(Number(year), 0, 4) // 4th Jan is always in week 1
-  date.setDate(date.getDate() - (date.getDay() || 7) + 1 + (Number(week) - 1) * 7)
-  return date
+  const parsedYear = parseYearSmart(year)
+  const parsedWeek = Number.parseInt(week, 10)
+
+  // Create date from ISO week using helper function
+  return getMondayOfISOWeek(parsedYear, parsedWeek)
+}
+
+/**
+ * Parses a week string and returns a Date object for the Monday of that week.
+ * @param dateString - The week string to parse.
+ * @returns The Date object for the Monday of the week, or null if invalid.
+ */
+const parseWeekString = (dateString: string): Date | null => {
+  const weekPatterns = [
+    /^(\d{4})-W(\d{1,2})$/, // 2023-W05, 2023-W5
+    /^(\d{4})W(\d{1,2})$/, // 2023W05, 2023W5
+    /^(\d{4})\s+W(\d{1,2})$/, // 2023 W05, 2023 W5
+  ]
+
+  for (const pattern of weekPatterns) {
+    const match = dateString.trim().match(pattern)
+    if (match) {
+      const parsedYear = parseYearSmart(match[1])
+      const parsedWeek = Number.parseInt(match[2], 10)
+
+      // Create date from ISO week using helper function
+      return getMondayOfISOWeek(parsedYear, parsedWeek)
+    }
+  }
+
+  // Fallback to existing ISO week parsing
+  return convertIsoWeekToDate(dateString)
+}
+
+/**
+ * Parses a month string and returns a Date object for the first day of that month.
+ * @param dateString - The month string to parse.
+ * @returns The Date object for the first day of the month, or null if invalid.
+ */
+const parseMonthString = (dateString: string): Date | null => {
+  const monthPatterns = [
+    /^(\d{2,4})[-/.\s](\d{1,2})$/, // 2023-12, 23-12, 2023/12, 23/12, 2023 12, etc.
+    /^(\d{1,2})[-/.\s](\d{2,4})$/, // 12-2023, 12-23, 12/2023, 12/23, 12 2023, etc.
+  ]
+
+  for (const pattern of monthPatterns) {
+    const match = dateString.trim().match(pattern)
+    if (match) {
+      const firstGroup = match[1]
+      const secondGroup = match[2]
+
+      // Determine which group is year and which is month
+      const parsedFirst = Number.parseInt(firstGroup, 10)
+      const parsedSecond = Number.parseInt(secondGroup, 10)
+
+      let parsedYear: number
+      let parsedMonth: number
+
+      // Determine which group is year and which is month based on several heuristics
+      if (firstGroup.length >= 3 || parsedFirst >= 100) {
+        // First group is clearly a year (3+ digits or >= 100)
+        parsedYear = parseYearSmart(firstGroup)
+        parsedMonth = parsedSecond - 1
+      } else if (secondGroup.length >= 3 || parsedSecond >= 100) {
+        // Second group is clearly a year (3+ digits or >= 100)
+        parsedYear = parseYearSmart(secondGroup)
+        parsedMonth = parsedFirst - 1
+      } else {
+        // Both groups are 1-2 digits, use context clues
+        // If second group is a valid month (1-12), treat first as year
+        if (parsedSecond >= 1 && parsedSecond <= 12 && (parsedFirst > 12 || parsedFirst < 1)) {
+          parsedYear = parseYearSmart(firstGroup)
+          parsedMonth = parsedSecond - 1
+        } else {
+          // Default: treat second group as year
+          parsedYear = parseYearSmart(secondGroup)
+          parsedMonth = parsedFirst - 1
+        }
+      }
+
+      if (parsedMonth >= 0 && parsedMonth <= 11) {
+        return new Date(parsedYear, parsedMonth, 1)
+      }
+    }
+  }
+
+  // For month selection, don't use fallback parsing - return null if no pattern matches
+  return null
+}
+
+/**
+ * Parses a year string or number and returns a Date object for January 1st of that year.
+ * @param dateString - The year string or number to parse.
+ * @returns The Date object for January 1st of the year, or null if invalid.
+ */
+const parseYearString = (dateString: string | number): Date | null => {
+  const yearString = String(dateString)
+  const yearPattern = /^(\d{2,4})$/
+  const match = yearString.trim().match(yearPattern)
+
+  if (match) {
+    const groups: YearGroups = { year: match[1] }
+    return createDateFromYear(groups)
+  }
+
+  return parseLocalDateString(yearString)
+}
+
+/**
+ * Helper function to generate multiple date format patterns based on locale.
+ * @param locale - The locale to use for date format patterns.
+ * @param includeTime - Whether to include time in the patterns.
+ * @returns Array of date format patterns.
+ */
+const generateDatePatterns = (locale: string, includeTime: boolean): string[] => {
+  const referenceDate = new Date(2013, 11, 31, 17, 19, 22)
+  const patterns = []
+
+  try {
+    // Get the standard locale format
+    const standardFormat = includeTime
+      ? referenceDate.toLocaleString(locale)
+      : referenceDate.toLocaleDateString(locale)
+
+    patterns.push(standardFormat)
+  } catch {
+    // Fallback to default locale if invalid locale provided
+    const standardFormat = includeTime
+      ? referenceDate.toLocaleString('en-US')
+      : referenceDate.toLocaleDateString('en-US')
+    patterns.push(standardFormat)
+  }
+
+  // Generate common alternative formats by replacing separators
+  const separators = ['/', '-', '.', ' ']
+  const standardFormat = patterns[0]
+
+  // Detect the original separator
+  let originalSeparator = '/' // default
+  if (standardFormat.includes('/')) {
+    originalSeparator = '/'
+  } else if (standardFormat.includes('-')) {
+    originalSeparator = '-'
+  } else if (standardFormat.includes('.')) {
+    originalSeparator = '.'
+  }
+
+  for (const sep of separators) {
+    if (sep !== originalSeparator) {
+      // Escape the original separator for regex if it's a special character
+      const escapedSeparator = originalSeparator.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+      const altFormat = standardFormat.replaceAll(new RegExp(escapedSeparator, 'g'), sep)
+      patterns.push(altFormat)
+    }
+  }
+
+  return patterns
+}
+
+/**
+ * Helper function to build regex pattern for date parsing.
+ * @param formatString - The date format string.
+ * @param includeTime - Whether to include time patterns.
+ * @returns The regex pattern string.
+ */
+const buildDateRegexPattern = (formatString: string, includeTime: boolean): string => {
+  // First escape special regex characters
+  // eslint-disable-next-line unicorn/prefer-string-raw
+  let regexPattern = formatString.replaceAll(/[.*+?^${}()|[\\]\\]/g, '\\$&')
+
+  // Then replace the date/time components with regex groups
+  regexPattern = regexPattern
+    .replace('2013', String.raw`(?<year>\d{2,4})`)
+    .replace('12', String.raw`(?<month>\d{1,2})`)
+    .replace('31', String.raw`(?<day>\d{1,2})`)
+
+  if (includeTime) {
+    regexPattern = regexPattern
+      .replaceAll(/17|5/g, String.raw`(?<hour>\d{1,2})`)
+      .replace('19', String.raw`(?<minute>\d{1,2})`)
+      .replace('22', String.raw`(?<second>\d{1,2})`)
+      .replaceAll(/AM|PM/gi, '(?<ampm>[APap][Mm])')
+  }
+
+  return regexPattern
+}
+
+type TimeGroups = {
+  hour: string
+  minute?: string
+  second?: string
+  ampm?: string
+}
+
+type DateOnlyGroups = BaseGroups
+type DateTimeGroups = BaseGroups & TimeGroups
+type AnyGroups = DateOnlyGroups | DateTimeGroups | WeekGroups | MonthGroups | YearGroups
+
+/**
+ * Helper function to try parsing with multiple patterns.
+ * @param dateString - The date string to parse.
+ * @param patterns - Array of format patterns to try.
+ * @param includeTime - Whether time parsing is included.
+ * @returns Parsed groups or null if no match.
+ */
+const tryParseWithPatterns = (
+  dateString: string,
+  patterns: string[],
+  includeTime: boolean
+): AnyGroups | null => {
+  for (const pattern of patterns) {
+    const regexPattern = buildDateRegexPattern(pattern, includeTime)
+    const regex = new RegExp(`^${regexPattern}$`)
+    const match = dateString.trim().match(regex)
+
+    if (match?.groups) {
+      return match.groups as AnyGroups
+    }
+  }
+
+  return null
+}
+
+/**
+ * Helper function to convert 12-hour to 24-hour format.
+ * @param hour - Hour string.
+ * @param ampm - AM/PM indicator.
+ * @returns Hour in 24-hour format.
+ */
+const convertTo24Hour = (hour: string, ampm?: string): number => {
+  const parsedHour = Number.parseInt(hour, 10)
+
+  if (!ampm) {
+    return parsedHour
+  }
+
+  const isPM = ampm.toLowerCase() === 'pm'
+
+  if (isPM && parsedHour !== 12) {
+    return parsedHour + 12
+  }
+
+  if (!isPM && parsedHour === 12) {
+    return 0
+  }
+
+  return parsedHour
+}
+
+/**
+ * Helper function to validate time components.
+ * @param hour - Hour value.
+ * @param minute - Minute value.
+ * @param second - Second value.
+ * @returns True if time components are valid.
+ */
+const validateTimeComponents = (hour: number, minute: number, second: number): boolean => {
+  return hour >= 0 && hour <= 23 && minute >= 0 && minute <= 59 && second >= 0 && second <= 59
+}
+
+/**
+ * Helper function to validate date components.
+ * @param month - Month string.
+ * @param day - Day string.
+ * @returns True if date components are valid.
+ */
+const validateDateComponents = (month: string, day: string): boolean => {
+  const parsedMonth = Number.parseInt(month, 10) - 1
+  const parsedDay = Number.parseInt(day, 10)
+
+  return parsedMonth >= 0 && parsedMonth <= 11 && parsedDay >= 1 && parsedDay <= 31
+}
+
+/**
+ * Helper function to create date with time.
+ * @param groups - Parsed date and time groups.
+ * @returns Date object or null if invalid.
+ */
+const createDateWithTime = (groups: DateTimeGroups): Date | null => {
+  const { year, month, day, hour, minute, second, ampm } = groups
+
+  const parsedYear = parseYearSmart(year)
+  const parsedMonth = Number.parseInt(month, 10) - 1
+  const parsedDay = Number.parseInt(day, 10)
+  const parsedHour = convertTo24Hour(hour, ampm)
+  const parsedMinute = Number.parseInt(minute ?? '0', 10) || 0
+  const parsedSecond = Number.parseInt(second ?? '0', 10) || 0
+
+  if (!validateTimeComponents(parsedHour, parsedMinute, parsedSecond)) {
+    return null
+  }
+
+  return new Date(parsedYear, parsedMonth, parsedDay, parsedHour, parsedMinute, parsedSecond)
+}
+
+/**
+ * Helper function to create date without time.
+ * @param groups - Parsed date groups.
+ * @returns Date object or null if invalid.
+ */
+const createDateOnly = (groups: DateOnlyGroups): Date | null => {
+  const { year, month, day } = groups
+
+  if (!validateDateComponents(month, day)) {
+    return null
+  }
+
+  const parsedYear = parseYearSmart(year)
+  const parsedMonth = Number.parseInt(month, 10) - 1
+  const parsedDay = Number.parseInt(day, 10)
+
+  return new Date(parsedYear, parsedMonth, parsedDay)
+}
+
+/**
+ * Enhanced day parsing with locale-aware patterns.
+ * @param dateString - The day string to parse.
+ * @param locale - The locale to use for parsing.
+ * @param includeTime - Whether to include time parsing.
+ * @returns Date object or null if invalid.
+ */
+const parseDayString = (dateString: string, locale: string, includeTime: boolean): Date | null => {
+  const patterns = generateDatePatterns(locale, includeTime)
+  const groups = tryParseWithPatterns(dateString, patterns, includeTime)
+
+  if (!groups) {
+    // Check if input looks like a complete date (has separators and multiple parts)
+    // If so, use fallback parsing for formats like "2022/08/17", "2022-08-17"
+    // If not (like "1", "12"), return null
+    const trimmed = dateString.trim()
+    const hasDateSeparators = /[-/.:]/.test(trimmed)
+    const parts = trimmed.split(/[-/.\s:]+/).filter((part) => part.length > 0)
+    const hasMultipleParts = parts.length >= 2
+
+    if (hasDateSeparators && hasMultipleParts) {
+      // Use fallback for complete date strings that don't match locale patterns
+      return parseLocalDateString(dateString)
+    }
+
+    // For incomplete input like "1" or "12", return null
+    return null
+  }
+
+  // For day selection, require at least month and day to be present
+  if ('month' in groups && 'day' in groups) {
+    const { month, day } = groups
+    if (!validateDateComponents(month, day)) {
+      return null
+    }
+  } else {
+    // If incomplete date information, return null instead of guessing
+    return null
+  }
+
+  // Create and return appropriate date object
+  return includeTime
+    ? createDateWithTime(groups as DateTimeGroups)
+    : createDateOnly(groups as DateOnlyGroups)
+}
+
+/**
+ * Parses a date string into a local Date object.
+ * @param dateString - The date string to parse.
+ * @returns The Date object in local timezone, or null if invalid.
+ */
+const parseLocalDateString = (dateString: string): Date | null => {
+  const _date = new Date(Date.parse(dateString))
+  if (!Number.isNaN(_date.getTime())) {
+    return _date
+  }
+
+  return null
 }
 
 /**
  * Converts a date string or Date object to a Date object based on selection type.
  * @param date - The date to convert.
  * @param selectionType - The type of selection ('day', 'week', 'month', 'year').
+ * @param locale - The locale to use for date parsing (for day parsing).
+ * @param includeTime - Whether to include time parsing (for day parsing).
  * @returns The corresponding Date object or null if invalid.
  */
-export const convertToDateObject = (date: Date | string, selectionType?: SelectionTypes): Date => {
+export const convertToDateObject = (
+  date: Date | string,
+  selectionType?: SelectionTypes,
+  locale: string = 'en-US',
+  includeTime: boolean = false
+): Date | null => {
+  if (date === null) {
+    return null
+  }
+
   if (date instanceof Date) {
-    return date
+    return Number.isNaN(date.getTime()) ? null : date
   }
 
-  if (selectionType === 'week') {
-    return convertIsoWeekToDate(date as string)
+  const dateString = date as string
+
+  switch (selectionType) {
+    case 'week': {
+      return parseWeekString(dateString)
+    }
+    case 'month': {
+      return parseMonthString(dateString)
+    }
+    case 'year': {
+      return parseYearString(dateString)
+    }
+    default: {
+      // Enhanced day parsing with locale support
+      return parseDayString(dateString, locale, includeTime)
+    }
   }
+}
 
-  if (selectionType === 'month' || selectionType === 'year') {
-    const _date = new Date(Date.parse(date))
-    const userTimezoneOffset = _date.getTimezoneOffset() * 60_000
-    return new Date(_date.getTime() + userTimezoneOffset)
+/**
+ * Enhanced locale-aware date parsing function (replaces getLocalDateFromString).
+ * @param dateString - The date string to parse.
+ * @param locale - The locale to use for date format patterns.
+ * @param includeTime - Whether to include time parsing.
+ * @param selectionType - The selection type ('day', 'week', 'month', 'year').
+ * @returns A Date object if parsing succeeds, null if parsing fails.
+ */
+export const getLocalDateFromString = (
+  dateString: string,
+  locale: string = 'en-US',
+  includeTime: boolean = false,
+  selectionType: SelectionTypes = 'day'
+): Date | null => {
+  // Input validation
+  if (!dateString || typeof dateString !== 'string') {
+    return null
   }
 
-  return new Date(Date.parse(date))
+  return convertToDateObject(dateString, selectionType, locale, includeTime)
 }
 
 /**
@@ -66,7 +555,8 @@ export const getCalendarDate = (calendarDate: Date, order: number, view: ViewTyp
   }
 
   if (order !== 0 && view === 'years') {
-    return new Date(calendarDate.getFullYear() + 12 * order, calendarDate.getMonth(), 1)
+    // prettier-ignore
+    return new Date(calendarDate.getFullYear() + (12 * order), calendarDate.getMonth(), 1)
   }
 
   return calendarDate
@@ -277,7 +767,7 @@ export const getISOWeekNumberAndYear = (date: Date): { weekNumber: number; year:
   const week1 = new Date(tempDate.getFullYear(), 0, 4)
 
   // Calculate full weeks to the date
-  const weekNumber = 1 + Math.round((tempDate.getTime() - week1.getTime()) / 86_400_000 / 7)
+  const weekNumber = 1 + Math.round((tempDate.getTime() - week1.getTime()) / (86_400_000 * 7))
 
   return { weekNumber, year: tempDate.getFullYear() }
 }
@@ -313,10 +803,16 @@ export const getMonthDetails = (
 
     if ((index + 1) % 7 === 0) {
       const { weekNumber, year } = getISOWeekNumberAndYear(day.date)
-      weeks[weeks.length - 1].week = { number: weekNumber, year }
+      const lastWeek = weeks.at(-1)
+      if (lastWeek) {
+        lastWeek.week = { number: weekNumber, year }
+      }
     }
 
-    weeks[weeks.length - 1].days.push(day)
+    const lastWeek = weeks.at(-1)
+    if (lastWeek) {
+      lastWeek.days.push(day)
+    }
   })
 
   return weeks
@@ -387,7 +883,7 @@ export const isDateInRange = (date: Date, start: Date | null, end: Date | null):
   const _start = start ? removeTimeFromDate(start) : null
   const _end = end ? removeTimeFromDate(end) : null
 
-  return !!(_start && _end && _start <= _date && _date <= _end)
+  return Boolean(_start && _end && _start <= _date && _date <= _end)
 }
 
 /**
@@ -453,15 +949,11 @@ export const isMonthDisabled = (
   max?: Date | null,
   disabledDates?: DisabledDate | DisabledDate[]
 ) => {
-  const current = date.getFullYear() * 12 + date.getMonth()
-  const _min = min ? min.getFullYear() * 12 + min.getMonth() : null
-  const _max = max ? max.getFullYear() * 12 + max.getMonth() : null
-
-  if (_min && current < _min) {
-    return true
-  }
+  const current = dateToMonthNumber(date)
+  const _min = min ? dateToMonthNumber(min) : null
+  const _max = max ? dateToMonthNumber(max) : null
 
-  if (_max && current > _max) {
+  if (isOutsideRange(current, _min, _max)) {
     return true
   }
 
@@ -469,14 +961,14 @@ export const isMonthDisabled = (
     return false
   }
 
-  const start = min ? Math.max(date.getTime(), min.getTime()) : date
-  const end = max
+  const startTime = min ? Math.max(date.getTime(), min.getTime()) : date.getTime()
+  const endTime = max
     ? Math.min(date.getTime(), max.getTime())
-    : new Date(new Date().getFullYear(), 11, 31)
+    : new Date(new Date().getFullYear(), 11, 31).getTime()
 
   for (
-    const currentDate = new Date(start);
-    currentDate <= end;
+    const currentDate = new Date(startTime);
+    currentDate.getTime() <= endTime;
     currentDate.setDate(currentDate.getDate() + 1)
   ) {
     if (!isDateDisabled(currentDate, min, max, disabledDates)) {
@@ -517,13 +1009,11 @@ export const isMonthSelected = (date: Date, start: Date | null, end: Date | null
  * @returns True if the month is within the range, false otherwise.
  */
 export const isMonthInRange = (date: Date, start: Date | null, end: Date | null): boolean => {
-  const year = date.getFullYear()
-  const month = date.getMonth()
-  const _start = start ? start.getFullYear() * 12 + start.getMonth() : null
-  const _end = end ? end.getFullYear() * 12 + end.getMonth() : null
-  const _date = year * 12 + month
+  const _start = start ? dateToMonthNumber(start) : null
+  const _end = end ? dateToMonthNumber(end) : null
+  const _date = dateToMonthNumber(date)
 
-  return !!(_start && _end && _start <= _date && _date <= _end)
+  return Boolean(_start && _end && _start <= _date && _date <= _end)
 }
 
 /**
@@ -576,11 +1066,7 @@ export const isYearDisabled = (
   const minYear = min ? min.getFullYear() : null
   const maxYear = max ? max.getFullYear() : null
 
-  if (minYear && year < minYear) {
-    return true
-  }
-
-  if (maxYear && year > maxYear) {
+  if (isOutsideRange(year, minYear, maxYear)) {
     return true
   }
 
@@ -588,14 +1074,14 @@ export const isYearDisabled = (
     return false
   }
 
-  const start = min ? Math.max(date.getTime(), min.getTime()) : date
-  const end = max
+  const startTime = min ? Math.max(date.getTime(), min.getTime()) : date.getTime()
+  const endTime = max
     ? Math.min(date.getTime(), max.getTime())
-    : new Date(new Date().getFullYear(), 11, 31)
+    : new Date(new Date().getFullYear(), 11, 31).getTime()
 
   for (
-    const currentDate = new Date(start);
-    currentDate <= end;
+    const currentDate = new Date(startTime);
+    currentDate.getTime() <= endTime;
     currentDate.setDate(currentDate.getDate() + 1)
   ) {
     if (!isDateDisabled(currentDate, min, max, disabledDates)) {
@@ -639,7 +1125,7 @@ export const isYearInRange = (date: Date, start: Date | null, end: Date | null):
   const _start = start ? start.getFullYear() : null
   const _end = end ? end.getFullYear() : null
 
-  return !!(_start && _end && _start <= year && year <= _end)
+  return Boolean(_start && _end && _start <= year && year <= _end)
 }
 
 /**
@@ -679,3 +1165,65 @@ export const setTimeFromDate = (target: Date | null, source: Date | null): Date
 
   return result
 }
+
+/**
+ * Parses a year string with smart 2-digit handling.
+ * @param yearString - The year string to parse.
+ * @returns The parsed year as a number with intelligent century assignment.
+ */
+export const parseYearSmart = (yearString: string): number => {
+  let parsedYear = Number.parseInt(yearString, 10)
+
+  // Handle 2-digit years with intelligent century assignment
+  if (parsedYear < 100) {
+    const currentYear = new Date().getFullYear()
+    const currentCentury = Math.floor(currentYear / 100) * 100
+    parsedYear = currentCentury + parsedYear
+
+    // If the result is more than 50 years in the future, use previous century
+    // This creates a sliding window: for current year 2025, years 76-99 become 1976-1999
+    // and years 00-75 become 2000-2075
+    if (parsedYear > currentYear + 50) {
+      parsedYear -= 100
+    }
+  }
+
+  return parsedYear
+}
+
+/**
+ * Creates a date from year groups.
+ * @param groups - The year groups containing year string.
+ * @returns A Date object for January 1st of the year.
+ */
+export const createDateFromYear = (groups: YearGroups): Date => {
+  const { year } = groups
+  const parsedYear = parseYearSmart(year)
+  return new Date(parsedYear, 0, 1)
+}
+
+/**
+ * Creates a date from month groups.
+ * @param groups - The month groups containing year and month strings.
+ * @returns A Date object for the first day of the month.
+ */
+export const createDateFromMonth = (groups: MonthGroups): Date => {
+  const { year, month } = groups
+  const parsedYear = parseYearSmart(year)
+  const parsedMonth = Number.parseInt(month, 10) - 1
+  return new Date(parsedYear, parsedMonth, 1)
+}
+
+/**
+ * Creates a date from week groups.
+ * @param groups - The week groups containing year and week strings.
+ * @returns A Date object for the Monday of the specified week.
+ */
+export const createDateFromWeek = (groups: WeekGroups): Date => {
+  const { year, week } = groups
+  const parsedYear = parseYearSmart(year)
+  const parsedWeek = Number.parseInt(week, 10)
+
+  // Create date from ISO week using helper function
+  return getMondayOfISOWeek(parsedYear, parsedWeek)
+}