fix(calendar): adhere to ISO 8601 when calculating week number if the week starts on Monday (#15964)

Author: simeonoff

projects/igniteui-angular/src/lib/calendar/calendar.component.spec.ts

@@ -596,18 +596,13 @@ describe("IgxCalendar - ", () => {
                         By.css(`${HelperTestFunctions.CALENDAR_ROW_CSSCLASS}`),
                     );
 
+                    const expectedWeeks = ["W", "1", "2", "3", "4", "5", "6"];
+
                     calendarRows.forEach((row, idx) => {
                         const firstRowItem = row.nativeElement.children[0];
-
-                        if (idx === 0) {
-                            expect(firstRowItem.firstChild.innerText).toEqual(
-                                "W",
-                            );
-                        } else {
-                            expect(firstRowItem.firstChild.innerText).toEqual(
-                                idx.toString(),
-                            );
-                        }
+                        expect(firstRowItem.firstChild.innerText).toEqual(
+                            expectedWeeks[idx],
+                        );
                     });
                 });
 
@@ -626,12 +621,7 @@ describe("IgxCalendar - ", () => {
                         const firstRowItem = row.nativeElement.children[0];
                         if (idx === 5) {
                             expect(firstRowItem.firstChild.innerText).toEqual(
-                                "13",
-                            );
-                        }
-                        if (idx === 6) {
-                            expect(firstRowItem.firstChild.innerText).toEqual(
-                                "14",
+                                "12",
                             );
                         }
                     });
@@ -648,7 +638,7 @@ describe("IgxCalendar - ", () => {
                         const firstRowItem = row.nativeElement.children[0];
                         if (idx === 5) {
                             expect(firstRowItem.firstChild.innerText).toEqual(
-                                "44",
+                                "43",
                             );
                         }
                     });
@@ -664,6 +654,7 @@ describe("IgxCalendar - ", () => {
                     calendarRowsDec.forEach((row, idx) => {
                         const firstRowItem = row.nativeElement.children[0];
                         if (idx === 6) {
+                            // With simple counting for Sunday start, expect 53
                             expect(firstRowItem.firstChild.innerText).toEqual(
                                 "53",
                             );

projects/igniteui-angular/src/lib/calendar/common/model.spec.ts

@@ -20,9 +20,13 @@ describe("Calendar Day Model", () => {
             const { year, month, date } = firstOfJan;
             expect([year, month, date]).toEqual([2024, 0, 1]);
 
-            // First week of 2024
+            // First week of 2024 (ISO 8601 - January 1, 2024 is Monday, so Week 1)
             expect(firstOfJan.week).toEqual(1);
 
+            // Test week numbering with different week starts
+            expect(firstOfJan.getWeekNumber(1)).toEqual(1); // Monday start (ISO 8601)
+            expect(firstOfJan.getWeekNumber(0)).toBeGreaterThan(50); // Sunday start (belongs to prev year)
+
             // 2024/01/01 is a Monday
             expect(firstOfJan.day).toEqual(1);
             expect(firstOfJan.weekend).toBeFalse();
@@ -79,6 +83,124 @@ describe("Calendar Day Model", () => {
         });
     });
 
+    describe("Week numbering", () => {
+        it("should use ISO 8601 for Monday start and simple counting for others", () => {
+            // January 1, 2025 is a Wednesday
+            const jan1_2025 = new CalendarDay({ year: 2025, month: 0, date: 1 });
+            expect(jan1_2025.day).toEqual(3); // Wednesday
+
+            // Monday start: Uses ISO 8601 standard
+            expect(jan1_2025.getWeekNumber(1)).toEqual(1); // Week 1 contains Jan 1
+
+            // Sunday start: Uses simple counting - Jan 1 (Wed) belongs to prev year
+            expect(jan1_2025.getWeekNumber(0)).toBeGreaterThan(50); // Week 52 of 2024
+        });
+
+        it("should handle ISO 8601 year boundaries for Monday start", () => {
+            // January 1, 2026 is a Thursday
+            const jan1_2026 = new CalendarDay({ year: 2026, month: 0, date: 1 });
+            expect(jan1_2026.day).toEqual(4); // Thursday
+
+            // Monday start: ISO 8601 logic applies
+            expect(jan1_2026.getWeekNumber(1)).toEqual(1); // Week 1 of 2026
+        });
+
+        it("should handle previous year's last week for Monday start", () => {
+            // January 1, 2027 is a Friday
+            const jan1_2027 = new CalendarDay({ year: 2027, month: 0, date: 1 });
+            expect(jan1_2027.day).toEqual(5); // Friday
+
+            // Monday start: ISO 8601 logic - belongs to previous year
+            const actualWeek = jan1_2027.getWeekNumber(1);
+            expect(actualWeek).toBeGreaterThan(50); // Should be Week 52 or 53 of 2026
+        });
+
+        it("should work correctly with custom week starts using appropriate logic", () => {
+            const testDate = new CalendarDay({ year: 2024, month: 2, date: 15 }); // March 15, 2024 (Friday)
+
+            // Test different week start days
+            const mondayStart = testDate.getWeekNumber(1);     // ISO 8601
+            const tuesdayStart = testDate.getWeekNumber(2);    // Simple counting
+            const wednesdayStart = testDate.getWeekNumber(3);  // Simple counting
+            const thursdayStart = testDate.getWeekNumber(4);   // Simple counting
+            const fridayStart = testDate.getWeekNumber(5);     // Simple counting
+            const saturdayStart = testDate.getWeekNumber(6);   // Simple counting
+            const sundayStart = testDate.getWeekNumber(0);     // Simple counting
+
+            // All should be valid week numbers (positive integers)
+            expect(mondayStart).toBeGreaterThan(0);
+            expect(tuesdayStart).toBeGreaterThan(0);
+            expect(wednesdayStart).toBeGreaterThan(0);
+            expect(thursdayStart).toBeGreaterThan(0);
+            expect(fridayStart).toBeGreaterThan(0);
+            expect(saturdayStart).toBeGreaterThan(0);
+            expect(sundayStart).toBeGreaterThan(0);
+        });
+
+        it("should apply ISO 8601 logic only for Monday start", () => {
+            // January 4, 2024 is a Thursday - always Week 1 in ISO 8601
+            const jan4_2024 = new CalendarDay({ year: 2024, month: 0, date: 4 });
+            expect(jan4_2024.day).toEqual(4); // Thursday
+
+            // Only Monday start uses ISO 8601
+            expect(jan4_2024.getWeekNumber(1)).toEqual(1); // Monday start: ISO 8601
+
+            // Other starts use simple counting, so results may vary
+            const sundayWeek = jan4_2024.getWeekNumber(0);
+            const tuesdayWeek = jan4_2024.getWeekNumber(2);
+            expect(sundayWeek).toBeGreaterThan(0);
+            expect(tuesdayWeek).toBeGreaterThan(0);
+        });
+
+        it("should handle December dates that belong to next year's Week 1 for Monday start", () => {
+            // December 30, 2024 is a Monday
+            const dec30_2024 = new CalendarDay({ year: 2024, month: 11, date: 30 });
+            expect(dec30_2024.day).toEqual(1); // Monday
+
+            // Monday start: This should be Week 1 of 2025 in ISO 8601
+            expect(dec30_2024.getWeekNumber(1)).toEqual(1); // Week 1 of 2025
+        });
+
+        it("should default to Monday start when no parameter provided", () => {
+            const testDate = new CalendarDay({ year: 2024, month: 0, date: 1 });
+
+            // Should default to Monday start (ISO 8601 standard)
+            expect(testDate.getWeekNumber()).toEqual(testDate.getWeekNumber(1));
+            expect(testDate.week).toEqual(testDate.getWeekNumber(1));
+        });
+
+        it("should handle leap years correctly", () => {
+            // Test February 29, 2024 (leap year)
+            const feb29_2024 = new CalendarDay({ year: 2024, month: 1, date: 29 });
+            expect(feb29_2024.day).toEqual(4); // Thursday
+
+            // Should calculate week number correctly for leap year date
+            const weekNumber = feb29_2024.getWeekNumber(1);
+            expect(weekNumber).toBeGreaterThan(0);
+            expect(weekNumber).toBeLessThan(54); // Valid week range
+        });
+
+        it("should correctly handle the January 2024 Sunday start case", () => {
+            // January 1, 2024 is a Monday, with Sunday start (0)
+            const jan1_2024 = new CalendarDay({ year: 2024, month: 0, date: 1 });
+            const jan7_2024 = new CalendarDay({ year: 2024, month: 0, date: 7 }); // Sunday
+            const jan8_2024 = new CalendarDay({ year: 2024, month: 0, date: 8 }); // Monday
+
+            expect(jan1_2024.day).toEqual(1); // Monday
+            expect(jan7_2024.day).toEqual(0); // Sunday
+            expect(jan8_2024.day).toEqual(1); // Monday
+
+            // With Sunday start, Jan 1 should be in previous year's last week
+            expect(jan1_2024.getWeekNumber(0)).toBeGreaterThan(50); // Week 53 of 2023
+
+            // Jan 7 (first Sunday) should be Week 1
+            expect(jan7_2024.getWeekNumber(0)).toEqual(1);
+
+            // Jan 8 should also be Week 1 (same week as Jan 7)
+            expect(jan8_2024.getWeekNumber(0)).toEqual(1);
+        });
+    });
+
     describe("Date ranges", () => {
         start = new CalendarDay({ year: 2024, month: 0, date: 11 });
         const endFuture = start.add("day", 7);

projects/igniteui-angular/src/lib/calendar/common/model.ts

@@ -115,13 +115,104 @@ export class CalendarDay {
         return this._date.getTime();
     }
 
-    /** Returns the current week number. */
+    /** Returns the ISO 8601 week number. */
     public get week() {
-        const firstDay = new CalendarDay({ year: this.year, month: 0 })
-            .timestamp;
-        const currentDay =
-            (this.timestamp - firstDay + millisecondsInDay) / millisecondsInDay;
-        return Math.ceil(currentDay / daysInWeek);
+        return this.getWeekNumber();
+    }
+
+    /**
+     * Gets the week number based on week start day.
+     * Uses ISO 8601 (first Thursday rule) only when weekStart is Monday (1).
+     * For other week starts, uses simple counting from January 1st.
+     */
+    public getWeekNumber(weekStart: number = 1): number {
+        if (weekStart === 1) {
+            return this.calculateISO8601WeekNumber();
+        } else {
+            return this.calculateSimpleWeekNumber(weekStart);
+        }
+    }
+
+    /**
+     * Calculates week number using ISO 8601 standard (Monday start, first Thursday rule).
+     */
+    private calculateISO8601WeekNumber(): number {
+        const currentThursday = this.getThursdayOfWeek();
+        const firstWeekThursday = this.getFirstWeekThursday(currentThursday.year);
+
+        const weeksDifference = this.getWeeksDifference(currentThursday, firstWeekThursday);
+        const weekNumber = weeksDifference + 1;
+
+        // Handle dates that belong to the previous year's last week
+        if (weekNumber <= 0) {
+            return this.getPreviousYearLastWeek(currentThursday.year - 1);
+        }
+
+        return weekNumber;
+    }
+
+    /**
+     * Calculates week number using simple counting from January 1st.
+     */
+    private calculateSimpleWeekNumber(weekStart: number): number {
+        const yearStart = new CalendarDay({ year: this.year, month: 0, date: 1 });
+        const yearStartDay = yearStart.day;
+
+        const daysUntilFirstWeek = (weekStart - yearStartDay + 7) % 7;
+
+        if (daysUntilFirstWeek > 0) {
+            const firstWeekStart = yearStart.add('day', daysUntilFirstWeek);
+
+            if (this.timestamp < firstWeekStart.timestamp) {
+                const prevYear = this.year - 1;
+                const prevYearDec31 = new CalendarDay({ year: prevYear, month: 11, date: 31 });
+                return prevYearDec31.calculateSimpleWeekNumber(weekStart);
+            }
+
+            const daysSinceFirstWeek = Math.floor((this.timestamp - firstWeekStart.timestamp) / millisecondsInDay);
+            return Math.floor(daysSinceFirstWeek / 7) + 1;
+        } else {
+            const daysSinceYearStart = Math.floor((this.timestamp - yearStart.timestamp) / millisecondsInDay);
+            return Math.floor(daysSinceYearStart / 7) + 1;
+        }
+    }
+
+    /**
+     * Gets the Thursday of the current date's week (ISO 8601 helper).
+     */
+    private getThursdayOfWeek(): CalendarDay {
+        const dayOffset = (this.day - 1 + 7) % 7; // Monday start
+        const thursdayOffset = 3; // Thursday is 3 days from Monday
+        return this.add('day', thursdayOffset - dayOffset);
+    }
+
+    /**
+     * Gets the Thursday of the first week of the given year (ISO 8601 helper).
+     */
+    private getFirstWeekThursday(year: number): CalendarDay {
+        const january4th = new CalendarDay({ year, month: 0, date: 4 });
+        const dayOffset = (january4th.day - 1 + 7) % 7; // Monday start
+        const thursdayOffset = 3; // Thursday is 3 days from Monday
+        return january4th.add('day', thursdayOffset - dayOffset);
+    }
+
+    /**
+     * Calculates the number of weeks between two Thursday dates (ISO 8601 helper).
+     */
+    private getWeeksDifference(currentThursday: CalendarDay, firstWeekThursday: CalendarDay): number {
+        const daysDifference = Math.floor((currentThursday.timestamp - firstWeekThursday.timestamp) / millisecondsInDay);
+        return Math.floor(daysDifference / 7);
+    }
+
+    /**
+     * Gets the last week number of the previous year (ISO 8601 helper).
+     */
+    private getPreviousYearLastWeek(previousYear: number): number {
+        const december31st = new CalendarDay({ year: previousYear, month: 11, date: 31 });
+        const lastWeekThursday = december31st.getThursdayOfWeek();
+        const firstWeekThursday = this.getFirstWeekThursday(previousYear);
+
+        return this.getWeeksDifference(lastWeekThursday, firstWeekThursday) + 1;
     }
 
     /** Returns the underlying native date instance. */

projects/igniteui-angular/src/lib/calendar/days-view/days-view.component.ts

@@ -378,7 +378,7 @@ export class IgxDaysViewComponent extends IgxCalendarBaseDirective {
      * @hidden
      */
     public getWeekNumber(date: CalendarDay): number {
-        return date.week;
+        return date.getWeekNumber(this.weekStart);
     }
 
     /**

src/app/calendar/calendar.sample.ts

@@ -67,8 +67,29 @@ export class CalendarSampleComponent implements OnInit {
             label: 'Change Locale',
             control: {
                 type: 'button-group',
-                options: ['EN', 'BG', 'DE', 'FR', 'JP'],
-                defaultValue: 'EN'
+                options: [
+                    {
+                        value: 'en-US',
+                        label: 'EN'
+                    },
+                    {
+                        value: 'bg-BG',
+                        label: 'BG'
+                    },
+                    {
+                        value: 'de-DE',
+                        label: 'DE'
+                    },
+                    {
+                        value: 'fr-FR',
+                        label: 'FR'
+                    },
+                    {
+                        value: 'ja-JP',
+                        label: 'JP'
+                    }
+                ],
+                defaultValue: 'en-US'
             }
         },
         weekStart: {

src/app/properties-panel/properties-panel.component.html

@@ -79,8 +79,8 @@ <h5 class="properties-panel__title">Properties Panel</h5>
             <igx-buttongroup [selectionMode]="'single'">
                 @for (option of getControlOptions(key); track option) {
                     <button igxButton
-                            [selected]="form.controls[key].value === option"
-                            (click)="form.controls[key].setValue(option)">
+                            [selected]="form.controls[key].value === (option.value || option)"
+                            (click)="form.controls[key].setValue(option.value || option)">
                       {{ getControlLabels(key)[getControlOptions(key).indexOf(option)] }}
                     </button>
                 }

src/app/properties-panel/properties-panel.component.ts

@@ -124,11 +124,11 @@ export class PropertiesPanelComponent {
         return this.config[key].control.options;
     }
 
-    protected getControlLabels(key: string): string[] {
+    protected getControlLabels(key: string): string[] | { label: string, value: any }[] {
         const labels = this.config[key].control.labels || [];
         const options = this.getControlOptions(key);
         return labels.length > 0
             ? labels
-            : options.map((option) => option.toString());
+            : options.map((option) => option.label || option.toString());
     }
 }

src/app/properties-panel/property-change.service.ts

@@ -21,7 +21,7 @@ export type PropertyPanelConfig = {
         label?: string;
         control: {
             type: ControlType,
-            options?: string[];
+            options?: string[] | { label: string, value: any }[];
             labels?: string[];
             min?: number;
             max?: number;