@heartlandone/vega 2.63.1 → 2.65.0

package/dist/collection/helpers/calendar/calendar-event.js

@@ -2,7 +2,8 @@ import calendarEventRepeatPatternFactory from '../../components/vega-calendar/sl
 import { generateUUID } from '../../utils/misc';
 import { VegaInternalTranslation } from '../translation';
 import { CalendarDate } from './calendar-date';
-import { formatDisplayTime, WeekdayLongNames } from './utils';
+import { formatDisplayTime, getSystemTimezone, WeekdayLongNames } from './utils';
+import { LogUtility } from '../../utils/log';
 const CalendarDateFormatReg = /^\d{1,2}\/\d{1,2}\/\d{4}/;
 const CalendarTimeFormatReg = /^\d{1,2}:\d{1,2}/;
 /** The `CalendarEvent` class in TypeScript represents a calendar event with methods to validate required fields, initialize dates and times, and determine if it is a group event. */
@@ -16,13 +17,15 @@ export class CalendarEvent {
    * @param {string} eventKey If a value is not provided for `eventKey`, a UUID (Universally
    * Unique Identifier) will be generated as a default value. This identifier is used to distinguish
    * different events and can be helpful for tracking
+   * @param {string} timezone - Optional timezone identifier for timezone-aware date calculations
    */
-  constructor(eventOptions, eventKey) {
+  constructor(eventOptions, eventKey, timezone) {
     // the default value is 1 when the event end date is same as start date
     this._eventSpansDays = 1;
     this.repeatPattern = null;
     this._event = eventOptions;
     this._eventKey = eventKey || generateUUID();
+    this._timezone = timezone || getSystemTimezone();
     this.checkEventRequireField(eventOptions);
     this.initDate(eventOptions);
     this.initEventSpansDays();
@@ -202,7 +205,7 @@ export class CalendarEvent {
   getEventDuration() {
     const [startHour, startMinutes] = this.startTime.split(':');
     const [endHour, endMinutes] = this.endTime.split(':');
-    const now = CalendarDate.from(new Date());
+    const now = CalendarDate.from(new Date(), this._timezone);
     const startDate = new Date(now.year, now.month, now.date, Number(startHour), Number(startMinutes));
     const endDate = new Date(now.year, now.month, now.date, Number(endHour) === 0 && Number(startHour) !== 0 ? 24 : Number(endHour), Number(endMinutes));
     return (endDate.valueOf() - startDate.valueOf()) / (60 * 1000);
@@ -222,6 +225,17 @@ export class CalendarEvent {
     }
     return [];
   }
+  /**
+   * Refresh event dates and related properties when timezone changes
+   *
+   * @param {string} timezone - The new timezone to apply to the event
+   */
+  updateTimezone(timezone) {
+    this._timezone = timezone;
+    this.initDate(this._event);
+    this.initEventSpansDays();
+    this.initRepeatPattern();
+  }
   /**
    * The function `convertTimeTo24Hour` converts a time string from 12-hour format to 24-hour format in TypeScript.
    *
@@ -279,42 +293,164 @@ export class CalendarEvent {
    */
   initDate(eventOptions) {
     const { startDate, startTime, endDate, endTime } = eventOptions;
+    const originalDateParts = this.processStartDate(startDate, startTime || '');
+    this._startTime = this.formatTimeForDisplay(this._startDate, startTime || '');
+    this.processEndDate(endDate || '', endTime || '', originalDateParts);
+    this._endTime = this.formatTimeForDisplay(this._endDate, endTime || '');
+  }
+  /**
+   * Process start date
+   *
+   * @param {string | Date} startDate - Start date (string or Date object)
+   * @param {string} startTime - Start time string
+   * @returns {DateParts | undefined} originalDateParts information
+   */
+  processStartDate(startDate, startTime) {
+    let originalDateParts;
+    let tempDate;
     if (startDate && typeof startDate === 'object') {
-      this._startDate = startDate;
+      originalDateParts = {
+        year: startDate.getFullYear(),
+        month: startDate.getMonth(),
+        date: startDate.getDate(),
+      };
+      tempDate = startDate;
     }
     else if (startDate && typeof startDate === 'string') {
       const [month, day, year] = startDate.split('/');
-      this._startDate = new Date(Number(year), Number(month) - 1, Number(day));
+      originalDateParts = {
+        year: Number(year),
+        month: Number(month) - 1,
+        date: Number(day),
+      };
+      tempDate = new Date(originalDateParts.year, originalDateParts.month, originalDateParts.date);
     }
-    if (!startTime) {
-      this._startTime = `${this._startDate.getHours()}:${this._startDate.getMinutes()}`;
+    if (startTime && originalDateParts && tempDate) {
+      const { timeHours, timeMinutes } = this.getCurrentHourAndMinutes(startTime);
+      tempDate = new Date(originalDateParts.year, originalDateParts.month, originalDateParts.date, timeHours, timeMinutes, 0);
     }
-    else {
-      this._startTime = this.convertTimeTo24Hour(startTime);
+    if (tempDate) {
+      this._startDate = this.convertDateToTimezone(tempDate);
     }
+    return originalDateParts;
+  }
+  /**
+   * Process end date
+   *
+   * @param {string | Date} endDate - End date (string or Date object)
+   * @param {string} endTime - End time string
+   * @param {DateParts | undefined} fallbackDateParts - Default date parts to use when endDate is empty
+   */
+  processEndDate(endDate, endTime, fallbackDateParts) {
+    let tempDate;
     if (endDate && typeof endDate === 'object') {
-      this._endDate = endDate;
+      tempDate = endDate;
     }
     else if (endDate && typeof endDate === 'string') {
       const [month, day, year] = endDate.split('/');
-      this._endDate = new Date(Number(year), Number(month) - 1, Number(day), 23, 59, 59);
+      tempDate = new Date(Number(year), Number(month) - 1, Number(day), 23, 59, 59);
     }
     else {
-      this._endDate = new Date(this._startDate.getFullYear(), this._startDate.getMonth(), this._startDate.getDate(), 23, 59, 59);
+      if (fallbackDateParts) {
+        tempDate = new Date(fallbackDateParts.year, fallbackDateParts.month, fallbackDateParts.date, 23, 59, 59);
+      }
+    }
+    if (endTime && tempDate) {
+      const { timeHours, timeMinutes } = this.getCurrentHourAndMinutes(endTime, 23, 59);
+      tempDate = new Date(tempDate.getFullYear(), tempDate.getMonth(), tempDate.getDate(), timeHours, timeMinutes, 59);
     }
-    if (!endTime) {
-      this._endTime = `${this._endDate.getHours()}:${this._endDate.getMinutes()}`;
+    if (tempDate) {
+      this._endDate = this.convertDateToTimezone(tempDate);
+    }
+  }
+  /**
+   * Format time for display
+   *
+   * @param {Date} date - Date object
+   * @param {string} originalTime - Original time string
+   * @returns {string} Formatted time string
+   */
+  formatTimeForDisplay(date, originalTime) {
+    const shouldUseOriginalTime = Boolean(originalTime) && this._timezone === getSystemTimezone();
+    if (shouldUseOriginalTime) {
+      const convertedTime = this.convertTimeTo24Hour(originalTime);
+      const [hour, minutes] = convertedTime.split(':');
+      return `${date.getHours().toString().padStart(hour.length, '0')}:${date
+        .getMinutes()
+        .toString()
+        .padStart(minutes.length, '0')}`;
     }
     else {
-      this._endTime = this.convertTimeTo24Hour(endTime);
+      return `${date.getHours()}:${date.getMinutes()}`;
+    }
+  }
+  /**
+   * Parses a time string and extracts hour and minute values.
+   * If the time string is empty or invalid, returns the provided default values.
+   *
+   * @param {string} time - The time string to parse (e.g., "14:30", "2:30 PM")
+   * @param {number} defaultHours - Default hour value to use when time is empty (default: 0)
+   * @param {number} defaultMinutes - Default minute value to use when time is empty (default: 0)
+   * @returns {CalendarTimeHourMinutes} An object containing timeHours and timeMinutes as numbers
+   */
+  getCurrentHourAndMinutes(time, defaultHours = 0, defaultMinutes = 0) {
+    let timeHours = defaultHours;
+    let timeMinutes = defaultMinutes;
+    if (time) {
+      const timeString = this.convertTimeTo24Hour(time).split(':');
+      timeHours = Number(timeString[0]);
+      timeMinutes = Number(timeString[1]);
+    }
+    return { timeHours, timeMinutes };
+  }
+  /**
+   * Converts a Date object to the target timezone
+   *
+   * @param {Date} date - The Date object to convert
+   * @returns {Date} A Date object representing the date/time in the target timezone
+   */
+  convertDateToTimezone(date) {
+    if (this._timezone && this._timezone !== getSystemTimezone()) {
+      try {
+        const targetFormatter = new Intl.DateTimeFormat([], {
+          timeZone: this._timezone,
+          year: 'numeric',
+          month: '2-digit',
+          day: '2-digit',
+          hour: '2-digit',
+          minute: '2-digit',
+          second: '2-digit',
+          hour12: false,
+        });
+        const targetParts = targetFormatter.formatToParts(date);
+        const getYear = targetParts.find((part) => part.type === 'year');
+        const getMonth = targetParts.find((part) => part.type === 'month');
+        const getDay = targetParts.find((part) => part.type === 'day');
+        const getHour = targetParts.find((part) => part.type === 'hour');
+        const getMinute = targetParts.find((part) => part.type === 'minute');
+        const getSecond = targetParts.find((part) => part.type === 'second');
+        if (getYear && getMonth && getDay && getHour && getMinute && getSecond) {
+          const year = parseInt(getYear.value, 10);
+          const month = parseInt(getMonth.value, 10);
+          const day = parseInt(getDay.value, 10);
+          const hour = parseInt(getHour.value, 10);
+          const minute = parseInt(getMinute.value, 10);
+          const second = parseInt(getSecond.value, 10);
+          return new Date(year, month - 1, day, hour, minute, second);
+        }
+      }
+      catch (error) {
+        LogUtility.warn('Invalid timezone:', this._timezone);
+      }
     }
+    return date;
   }
   /**
    * The function initializes a repeat pattern controller for a calendar event with specified start and end dates and repeat options.
    */
   initRepeatPattern() {
     if (this._event.repeatOptions && this._event.repeatOptions.frequency) {
-      this.repeatPattern = calendarEventRepeatPatternFactory.getPattern(this._startDate, this._event.repeatOptions);
+      this.repeatPattern = calendarEventRepeatPatternFactory.getPattern(this._startDate, this._event.repeatOptions, this._timezone);
     }
   }
   /**

package/dist/collection/helpers/calendar/calendar-period/calendar-period.abstract.js

@@ -1,12 +1,13 @@
 import { CalendarDate } from '../calendar-date';
-import { getWeekdays } from '../utils';
+import { getSystemTimezone, getWeekdays } from '../utils';
 /**
  * CalendarPeriod is an abstract class that represents a period of date for calendar.
  */
 export class CalendarPeriod {
-  constructor(count, current) {
+  constructor(count, current, timezone) {
     this._count = count;
-    this._current = current ? current : CalendarDate.from(new Date());
+    this._timezone = timezone || getSystemTimezone();
+    this._current = current ? current : CalendarDate.from(new Date(), this._timezone);
     this.calculatePeriod(this._current);
   }
   /**
@@ -57,6 +58,14 @@ export class CalendarPeriod {
   get showWeekends() {
     return this._showWeekends;
   }
+  /**
+   * The timezone of the period.
+   *
+   * @type {string | undefined}
+   */
+  get timezone() {
+    return this._timezone;
+  }
   /**
    * Go to a specific date.
    *
@@ -72,7 +81,7 @@ export class CalendarPeriod {
    * @returns {this} - The current period.
    */
   now() {
-    return this.createBy(CalendarDate.from(new Date()));
+    return this.createBy(CalendarDate.from(new Date(), this._timezone));
   }
   /**
    * Calculate the period start date and end date.

package/dist/collection/helpers/calendar/calendar-period/day-period.js

@@ -5,8 +5,8 @@ import { DateDirection, getClosestWorkday } from '../../../components/vega-calen
  * Period of day.
  */
 export class DayPeriod extends CalendarPeriod {
-  constructor(current, showWeekends) {
-    super(DayPeriod.DISPLAY_DATE_COUNT, current);
+  constructor(current, showWeekends, timezone) {
+    super(DayPeriod.DISPLAY_DATE_COUNT, current, timezone);
     this._type = 'day';
     this._showWeekends = true;
     this._showWeekends = showWeekends === false ? false : true;
@@ -41,7 +41,7 @@ export class DayPeriod extends CalendarPeriod {
    * @returns {this} - The current period.
    */
   now() {
-    let calendarDate = CalendarDate.from(new Date());
+    let calendarDate = CalendarDate.from(new Date(), this.timezone);
     if (this._showWeekends === false) {
       calendarDate = getClosestWorkday(calendarDate);
     }
@@ -51,7 +51,7 @@ export class DayPeriod extends CalendarPeriod {
    * @inheritDoc
    */
   createBy(current) {
-    return new DayPeriod(current, this._showWeekends);
+    return new DayPeriod(current, this._showWeekends, this.timezone);
   }
 }
 DayPeriod.DISPLAY_DATE_COUNT = 1;

package/dist/collection/helpers/calendar/calendar-period/month-period.js

@@ -5,8 +5,8 @@ import { getWeekdays } from '../utils';
  * Period of month
  */
 export class MonthPeriod extends CalendarPeriod {
-  constructor(current, showWeekends) {
-    super(MonthPeriod.DISPLAY_DATE_COUNT, current);
+  constructor(current, showWeekends, timezone) {
+    super(MonthPeriod.DISPLAY_DATE_COUNT, current, timezone);
     this._type = 'month';
     this._showWeekends = true;
     this._showWeekends = showWeekends === false ? false : true;
@@ -17,12 +17,13 @@ export class MonthPeriod extends CalendarPeriod {
    * @param {CalendarDate} [calendarDate] - The `calendarDate` parameter is an optional parameter of
    * type `CalendarDate`. It represents a specific date in the calendar. If a `calendarDate` is
    * provided, the function will use that date to determine the first day of the month. If no
-   * `calendarDate` is provided, the function
+   * `calendarDate` is provided, the function will use the current date considering timezone.
+   * @param {string} [timezone] - The timezone to use when no calendarDate is provided
    * @returns {CalendarDate} A new `CalendarDate` object representing the first day of the month from the provided
    * `calendarDate` parameter or the current date if no parameter is provided.
    */
-  static getMonthFirstDay(calendarDate) {
-    const date = calendarDate || CalendarDate.from(new Date());
+  static getMonthFirstDay(calendarDate, timezone) {
+    const date = calendarDate || CalendarDate.from(new Date(), timezone);
     return new CalendarDate(date.year, date.month, 1);
   }
   /**
@@ -58,7 +59,7 @@ export class MonthPeriod extends CalendarPeriod {
    * @inheritDoc
    */
   createBy(current) {
-    return new MonthPeriod(current, this._showWeekends);
+    return new MonthPeriod(current, this._showWeekends, this.timezone);
   }
 }
 MonthPeriod.DISPLAY_DATE_COUNT = 6 * 7;

package/dist/collection/helpers/calendar/calendar-period/week-period.js

@@ -4,8 +4,8 @@ import { CalendarDate } from '../calendar-date';
  * Period of the week
  */
 export class WeekPeriod extends CalendarPeriod {
-  constructor(current, showWeekends) {
-    super(WeekPeriod.DISPLAY_DATE_COUNT, current);
+  constructor(current, showWeekends, timezone) {
+    super(WeekPeriod.DISPLAY_DATE_COUNT, current, timezone);
     this._type = 'week';
     this._showWeekends = true;
     this._showWeekends = showWeekends === false ? false : true;
@@ -30,7 +30,7 @@ export class WeekPeriod extends CalendarPeriod {
    * @inheritDoc
    */
   createBy(current) {
-    return new WeekPeriod(current, this._showWeekends);
+    return new WeekPeriod(current, this._showWeekends, this.timezone);
   }
 }
 WeekPeriod.DISPLAY_DATE_COUNT = 7;

package/dist/collection/helpers/calendar/calendar-view-generator/week-view-generator.js

@@ -12,7 +12,7 @@ export class WeekViewGenerator extends CalendarViewGenerator {
     const dates = this.generateDates(period);
     const showWeekends = period.showWeekends;
     let weekDays = this.generateWeekHead();
-    let dateItems = [dates.map(CalendarDate.from)];
+    let dateItems = [dates.map((date) => CalendarDate.from(date))];
     if (showWeekends === false) {
       weekDays = weekDays.slice(1, 6);
       dateItems = dateItems.map((items) => items.slice(1, 6));

package/dist/collection/helpers/calendar/test/calendar-date.test.js

@@ -73,3 +73,27 @@ describe('calendar-date', () => {
     expect(new CalendarDate(2024, 2, 10).getMonthName(true)).toBe('Feb');
   });
 });
+describe('CalendarDate Timezone', () => {
+  it('should create calendar date', () => {
+    const calendarDate = new CalendarDate(2025, 10, 29);
+    expect(calendarDate.year).toBe(2025);
+    expect(calendarDate.month).toBe(10);
+    expect(calendarDate.date).toBe(29);
+  });
+  it('should check isToday with timezone', () => {
+    jest.useFakeTimers('modern');
+    jest.setSystemTime(new Date('2025-10-29T03:00:00Z'));
+    const calendarDate = new CalendarDate(2025, 10, 29);
+    expect(calendarDate.isToday('UTC')).toBe(true);
+    expect(calendarDate.isToday('Asia/Shanghai')).toBe(true);
+    expect(calendarDate.isToday('America/New_York')).toBe(false);
+    jest.useRealTimers();
+  });
+  it('should convert to Date object', () => {
+    const calendarDate = new CalendarDate(2025, 10, 29);
+    const dateObj = calendarDate.toDate();
+    expect(dateObj.getFullYear()).toBe(2025);
+    expect(dateObj.getMonth() + 1).toBe(10);
+    expect(dateObj.getDate()).toBe(29);
+  });
+});

package/dist/collection/helpers/calendar/test/calendar-event.test.js

@@ -1,6 +1,9 @@
 import { CalendarDate } from '../calendar-date';
 import { CalendarEvent } from '../calendar-event';
 import { MonthPeriod } from '../calendar-period/month-period';
+import { newSpecPage } from '@stencil/core/testing';
+import { VegaCalendar } from '../../../components/vega-calendar/vega-calendar';
+import { LogUtility } from '../../../utils/log';
 const mockDate = new Date(2024, 5, 13, 13, 44);
 const mockStringDate = '06/13/2024';
 const rawEvent = {
@@ -188,3 +191,71 @@ describe('calendar-event', () => {
     expect(calendarEvent11.generateRepeatString()).toBe('');
   });
 });
+describe('calendar event with timezone', () => {
+  it('should display correct event start time after timezone conversion', async () => {
+    const testEvents = [
+      {
+        key: 'event1',
+        title: 'Test Event 1',
+        startDate: '10/29/2025',
+        endDate: '10/29/2025',
+        startTime: '09:00',
+        endTime: '17:00',
+        isAllDay: false,
+      },
+    ];
+    const page = await newSpecPage({
+      components: [VegaCalendar],
+      html: `<vega-calendar timezone="UTC" view-mode="week"></vega-calendar>`,
+    });
+    const component = page.rootInstance;
+    const calendarElement = page.body.querySelector('vega-calendar');
+    calendarElement.events = testEvents;
+    await page.waitForChanges();
+    expect(component.calendarEvents).toHaveLength(1);
+    const calendarEvent = component.calendarEvents[0];
+    expect(calendarEvent.startTime).toBe('09:00');
+    calendarElement.timezone = 'Asia/Shanghai';
+    expect(calendarEvent.startTime).toBe('17:0');
+    expect(calendarEvent.endTime).toBe('1:0');
+    calendarElement.timezone = 'America/New_York';
+    expect(calendarEvent.startTime).toBe('5:0');
+    expect(calendarEvent.endTime).toBe('13:0');
+  });
+  it('should handle timezone conversion with invalid timezone gracefully', async () => {
+    const testEvents = [
+      {
+        key: 'event1',
+        title: 'Test Event 1',
+        startDate: '10/29/2025',
+        endDate: '10/29/2025',
+        startTime: '14:30',
+        endTime: '16:45',
+        isAllDay: false,
+      },
+    ];
+    const page = await newSpecPage({
+      components: [VegaCalendar],
+      html: `<vega-calendar timezone="Invalid/Timezone"></vega-calendar>`,
+    });
+    const calendarElement = page.body.querySelector('vega-calendar');
+    calendarElement.events = testEvents;
+    spyOn(LogUtility, 'warn');
+    await page.waitForChanges();
+    expect(LogUtility.warn).toHaveBeenCalledWith('Invalid timezone:', 'Invalid/Timezone');
+  });
+  it('should not call updateTimezone when no calendar events exist during timezone change', async () => {
+    const page = await newSpecPage({
+      components: [VegaCalendar],
+      html: `<vega-calendar timezone="UTC"></vega-calendar>`,
+    });
+    const component = page.rootInstance;
+    expect(component.calendarEvents).toHaveLength(0);
+    const calendarElement = page.body.querySelector('vega-calendar');
+    calendarElement.timezone = 'Asia/Shanghai';
+    expect(() => {
+      component.watchTimezoneChange();
+    }).not.toThrow();
+    expect(component.postOperationDate).toBeDefined();
+  });
+});

package/dist/collection/helpers/calendar/test/calendar-period/day-period.test.js

@@ -79,3 +79,31 @@ describe('day-period', () => {
     expect(dayPeriod.current.date).toEqual(8);
   });
 });
+describe('DayPeriod Timezone', () => {
+  beforeEach(() => {
+    jest.useFakeTimers('modern');
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+  it('should create day period for a specific date', () => {
+    const dayPeriod = new DayPeriod(new CalendarDate(2025, 10, 29));
+    expect(dayPeriod.current).toEqual(new CalendarDate(2025, 10, 29));
+    expect(dayPeriod.startDate).toEqual(new CalendarDate(2025, 10, 29));
+    expect(dayPeriod.endDate).toEqual(new CalendarDate(2025, 10, 29));
+  });
+  it('should create day period with timezone Asia/Shanghai', () => {
+    jest.setSystemTime(new Date('2025-10-29T16:00:00Z'));
+    const dayPeriod = new DayPeriod(undefined, true, 'Asia/Shanghai');
+    expect(dayPeriod.current).toEqual(new CalendarDate(2025, 10, 30));
+    expect(dayPeriod.startDate).toEqual(new CalendarDate(2025, 10, 30));
+    expect(dayPeriod.endDate).toEqual(new CalendarDate(2025, 10, 30));
+  });
+  it('should go to now with timezone America/Los_Angeles', () => {
+    jest.setSystemTime(new Date('2025-10-30T06:00:00Z'));
+    const nowPeriod = new DayPeriod(undefined, true, 'America/Los_Angeles');
+    expect(nowPeriod.current).toEqual(new CalendarDate(2025, 10, 29));
+    expect(nowPeriod.startDate).toEqual(new CalendarDate(2025, 10, 29));
+    expect(nowPeriod.endDate).toEqual(new CalendarDate(2025, 10, 29));
+  });
+});

package/dist/collection/helpers/calendar/test/calendar-period/month-period.test.js

@@ -66,3 +66,38 @@ describe('month-period', () => {
     });
   });
 });
+describe('MonthPeriod Timezone', () => {
+  beforeEach(() => {
+    jest.useFakeTimers('modern');
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+  it('should create month period for a specific date', () => {
+    const monthPeriod = new MonthPeriod(new CalendarDate(2025, 10, 29));
+    expect(monthPeriod.current).toEqual(new CalendarDate(2025, 10, 29));
+    expect(monthPeriod.startDate.month).toBe(9);
+    expect(monthPeriod.endDate.month).toBe(11);
+  });
+  it('should create month period with timezone Asia/Shanghai', () => {
+    jest.setSystemTime(new Date('2025-10-31T16:00:00Z'));
+    const monthPeriod = new MonthPeriod(undefined, true, 'Asia/Shanghai');
+    expect(monthPeriod.current).toEqual(new CalendarDate(2025, 11, 1));
+    expect(monthPeriod.startDate.month).toBe(10);
+    expect(monthPeriod.endDate.month).toBe(12);
+  });
+  it('should go to now with timezone America/Los_Angeles', () => {
+    jest.setSystemTime(new Date('2025-11-01T06:00:00Z'));
+    const monthPeriod = new MonthPeriod(undefined, true, 'America/Los_Angeles');
+    expect(monthPeriod.current).toEqual(new CalendarDate(2025, 10, 31));
+    expect(monthPeriod.startDate.month).toBe(9);
+    expect(monthPeriod.endDate.month).toBe(11);
+  });
+  it('should go to another month', () => {
+    const monthPeriod = new MonthPeriod(new CalendarDate(2025, 10, 29));
+    const nextMonth = monthPeriod.goTo(new CalendarDate(2025, 11, 1));
+    expect(nextMonth.current).toEqual(new CalendarDate(2025, 11, 1));
+    expect(nextMonth.startDate.month).toBe(10);
+    expect(nextMonth.endDate.month).toBe(12);
+  });
+});

package/dist/collection/helpers/calendar/test/calendar-period/week-period.test.js

@@ -58,3 +58,46 @@ describe('week-period', () => {
     });
   });
 });
+describe('WeekPeriod Timezone', () => {
+  beforeEach(() => {
+    jest.useFakeTimers('modern');
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+  it('should create week period for a specific date', () => {
+    jest.setSystemTime(new Date('2025-10-29T12:00:00Z'));
+    const weekPeriod = new WeekPeriod();
+    expect(weekPeriod.current).toEqual(new CalendarDate(2025, 10, 29));
+    expect(weekPeriod.startDate).toEqual(new CalendarDate(2025, 10, 26));
+    expect(weekPeriod.endDate).toEqual(new CalendarDate(2025, 11, 1));
+  });
+  it('should create week period with timezone Asia/Shanghai', () => {
+    jest.setSystemTime(new Date('2025-10-27T16:00:00Z'));
+    const weekPeriod = new WeekPeriod(undefined, true, 'Asia/Shanghai');
+    expect(weekPeriod.current).toEqual(new CalendarDate(2025, 10, 28));
+    expect(weekPeriod.startDate).toEqual(new CalendarDate(2025, 10, 26));
+    expect(weekPeriod.endDate).toEqual(new CalendarDate(2025, 11, 1));
+  });
+  it('should go to a date in another week', () => {
+    const weekPeriod = new WeekPeriod(new CalendarDate(2025, 10, 29));
+    const nextWeek = weekPeriod.goTo(new CalendarDate(2025, 11, 4));
+    expect(nextWeek.current).toEqual(new CalendarDate(2025, 11, 4));
+    expect(nextWeek.startDate).toEqual(new CalendarDate(2025, 11, 2));
+    expect(nextWeek.endDate).toEqual(new CalendarDate(2025, 11, 8));
+  });
+  it('should go to now with timezone America/New_York', () => {
+    jest.setSystemTime(new Date('2025-11-02T04:00:00Z'));
+    const weekPeriod = new WeekPeriod(undefined, true, 'America/New_York');
+    const nowPeriod = weekPeriod.now();
+    expect(nowPeriod.current).toEqual(new CalendarDate(2025, 11, 2));
+    expect(nowPeriod.startDate).toEqual(new CalendarDate(2025, 11, 2));
+    expect(nowPeriod.endDate).toEqual(new CalendarDate(2025, 11, 8));
+  });
+  it('should handle week period at year boundary', () => {
+    const weekPeriod = new WeekPeriod(new CalendarDate(2025, 12, 31));
+    expect(weekPeriod.current).toEqual(new CalendarDate(2025, 12, 31));
+    expect(weekPeriod.startDate).toEqual(new CalendarDate(2025, 12, 28));
+    expect(weekPeriod.endDate).toEqual(new CalendarDate(2026, 1, 3));
+  });
+});

package/dist/collection/helpers/calendar/test/utils.test.js

@@ -1,4 +1,4 @@
-import { getWeekdays } from '../utils';
+import { getWeekdays, getCurrentDatePartsInTimezone, getSystemTimezone } from '../utils';
 describe('utils', () => {
   it('should return weekdays as expected by default', () => {
     expect(getWeekdays()).toEqual([0, 1, 2, 3, 4, 5, 6]);
@@ -7,3 +7,31 @@ describe('utils', () => {
     expect(getWeekdays(1)).toEqual([1, 2, 3, 4, 5, 6, 0]);
   });
 });
+describe('timezone-utils', () => {
+  beforeEach(() => {
+    jest.useFakeTimers('modern');
+    jest.setSystemTime(new Date('2025-10-29T23:30:00Z'));
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+  it('should get correct date parts in UTC', () => {
+    const result = getCurrentDatePartsInTimezone('UTC', new Date('2025-10-29T23:30:00Z'));
+    expect(result.year).toBe(2025);
+    expect(result.month).toBe(10);
+    expect(result.date).toBe(29);
+  });
+  it('should get current date parts in specific timezone', () => {
+    const shanghaiParts = getCurrentDatePartsInTimezone('Asia/Shanghai', new Date('2025-10-29T23:30:00Z'));
+    expect(shanghaiParts.year).toBe(2025);
+    expect(shanghaiParts.month).toBe(10);
+    expect(shanghaiParts.date).toBe(30); // already next day
+  });
+  it('should fallback to system time for invalid timezone', () => {
+    const result = getCurrentDatePartsInTimezone('Invalid/Timezone', new Date('2025-10-29T23:30:00Z'));
+    const systemTimezoneResult = getCurrentDatePartsInTimezone(getSystemTimezone(), new Date('2025-10-29T23:30:00Z'));
+    expect(result.year).toBe(systemTimezoneResult.year);
+    expect(result.month).toBe(systemTimezoneResult.month);
+    expect(result.date).toBe(systemTimezoneResult.date);
+  });
+});