refactor: clear calendar code

apps/build-docs/package.json

@@ -9,7 +9,7 @@
   "keywords": [],
   "author": "Elian Doran <contact@eliandoran.me>",
   "license": "AGPL-3.0-only",
-  "packageManager": "pnpm@10.28.1",
+  "packageManager": "pnpm@10.28.0",
   "devDependencies": {
     "@redocly/cli": "2.14.5",
     "archiver": "7.0.1",

apps/client/package.json

@@ -81,6 +81,6 @@
     "happy-dom": "20.3.3",
     "lightningcss": "1.30.2",
     "script-loader": "0.7.2",
-    "vite-plugin-static-copy": "3.1.5"
+    "vite-plugin-static-copy": "3.1.4"
   }
 }

apps/client/src/services/shortcuts.spec.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import shortcuts, { isIMEComposing, keyMatches, matchesShortcut } from "./shortcuts.js";
+import shortcuts, { isIMEComposing,keyMatches, matchesShortcut } from "./shortcuts.js";
 
 // Mock utils module
 vi.mock("./utils.js", () => ({
@@ -249,7 +249,7 @@ describe("shortcuts", () => {
             const handler = vi.fn();
             shortcuts.bindGlobalShortcut("ctrl+a", handler, "test-namespace");
 
-            expect(mockElement.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function));
+            expect(mockElement.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function), true);
         });
 
         it("should not bind shortcuts when handler is null", () => {
@@ -280,7 +280,7 @@ describe("shortcuts", () => {
             const handler = vi.fn();
             shortcuts.bindElShortcut(mockJQueryEl, "ctrl+a", handler, "test-namespace");
 
-            expect(mockEl.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function));
+            expect(mockEl.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function), true);
         });
 
         it("should fall back to document when element is empty", () => {
@@ -290,7 +290,7 @@ describe("shortcuts", () => {
             const handler = vi.fn();
             shortcuts.bindElShortcut(emptyJQuery, "ctrl+a", handler, "test-namespace");
 
-            expect(mockElement.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function));
+            expect(mockElement.addEventListener).toHaveBeenCalledWith("keydown", expect.any(Function), true);
         });
     });
 
@@ -301,7 +301,7 @@ describe("shortcuts", () => {
 
             shortcuts.removeGlobalShortcut("test-namespace");
 
-            expect(mockElement.removeEventListener).toHaveBeenCalledWith("keydown", expect.any(Function));
+            expect(mockElement.removeEventListener).toHaveBeenCalledWith("keydown", expect.any(Function), true);
         });
     });
 

apps/client/src/services/shortcuts.ts

@@ -110,8 +110,9 @@ function bindElShortcut($el: JQuery<ElementType | Element>, keyboardShortcut: st
                 }
             };
 
-            // Add the event listener
-            element.addEventListener('keydown', listener);
+            // Add the event listener in capture phase to intercept events before they reach
+            // child elements like CodeMirror
+            element.addEventListener('keydown', listener, true);
 
             // Store the binding for later cleanup
             const binding: ShortcutBinding = {
@@ -138,15 +139,16 @@ export function removeIndividualBinding(binding: ShortcutBinding) {
     if (activeBindingsInNamespace) {
         activeBindings.set(key, activeBindingsInNamespace.filter(aBinding => aBinding.handler === binding.handler));
     }
-    binding.element.removeEventListener("keydown", binding.listener);
+    // Remove listener with capture phase to match how it was added
+    binding.element.removeEventListener("keydown", binding.listener, true);
 }
 
 function removeNamespaceBindings(namespace: string) {
     const bindings = activeBindings.get(namespace);
     if (bindings) {
-        // Remove all event listeners for this namespace
         bindings.forEach(binding => {
-            binding.element.removeEventListener('keydown', binding.listener);
+            // Remove listener with capture phase to match how it was added
+            binding.element.removeEventListener('keydown', binding.listener, true);
         });
         activeBindings.delete(namespace);
     }

apps/client/src/widgets/launch_bar/Calendar.tsx

@@ -3,7 +3,7 @@ import clsx from "clsx";
 import server from "../../services/server";
 import { TargetedMouseEvent, VNode } from "preact";
 import { useEffect, useState } from "preact/hooks";
-import { Dayjs } from "@triliumnext/commons";
+import { Dayjs, getWeekInfo, WeekSettings } from "@triliumnext/commons";
 import { t } from "../../services/i18n";
 
 interface DateNotesForMonth {
@@ -22,6 +22,7 @@ const DAYS_OF_WEEK = [
 
 interface DateRangeInfo {
     weekNumbers: number[];
+    weekYears: number[];
     dates: Dayjs[];
 }
 
@@ -36,19 +37,27 @@ export interface CalendarArgs {
 
 export default function Calendar(args: CalendarArgs) {
     const [ rawFirstDayOfWeek ] = useTriliumOptionInt("firstDayOfWeek");
+    const [ firstWeekOfYear ] = useTriliumOptionInt("firstWeekOfYear");
+    const [ minDaysInFirstWeek ] = useTriliumOptionInt("minDaysInFirstWeek");
     const firstDayOfWeekISO = (rawFirstDayOfWeek === 0 ? 7 : rawFirstDayOfWeek);
 
+    const weekSettings = {
+        firstDayOfWeek: firstDayOfWeekISO,
+        firstWeekOfYear: firstWeekOfYear ?? 0,
+        minDaysInFirstWeek: minDaysInFirstWeek ?? 4
+    };
+
     const date = args.date;
     const firstDay = date.startOf('month');
     const firstDayISO = firstDay.isoWeekday();
-    const monthInfo = getMonthInformation(date, firstDayISO, firstDayOfWeekISO);
+    const monthInfo = getMonthInformation(date, firstDayISO, weekSettings);
 
     return (
         <>
             <CalendarWeekHeader rawFirstDayOfWeek={rawFirstDayOfWeek} />
             <div className="calendar-body" data-calendar-area="month">
-                {firstDayISO !== firstDayOfWeekISO && <PreviousMonthDays info={monthInfo.prevMonth} {...args} />}
-                <CurrentMonthDays firstDayOfWeekISO={firstDayOfWeekISO} {...args} />
+                {firstDayISO !== firstDayOfWeekISO && <PreviousMonthDays info={monthInfo.prevMonth} weekSettings={weekSettings} {...args} />}
+                <CurrentMonthDays weekSettings={weekSettings} {...args} />
                 <NextMonthDays dates={monthInfo.nextMonth.dates} {...args} />
             </div>
         </>
@@ -67,7 +76,7 @@ function CalendarWeekHeader({ rawFirstDayOfWeek }: { rawFirstDayOfWeek: number }
     )
 }
 
-function PreviousMonthDays({ date, info: { dates, weekNumbers }, ...args }: { date: Dayjs, info: DateRangeInfo } & CalendarArgs) {
+function PreviousMonthDays({ date, info: { dates, weekNumbers, weekYears }, weekSettings, ...args }: { date: Dayjs, info: DateRangeInfo, weekSettings: WeekSettings } & CalendarArgs) {
     const prevMonth = date.subtract(1, 'month').format('YYYY-MM');
     const [ dateNotesForPrevMonth, setDateNotesForPrevMonth ] = useState<DateNotesForMonth>();
 
@@ -77,27 +86,28 @@ function PreviousMonthDays({ date, info: { dates, weekNumbers }, ...args }: { da
 
     return (
         <>
-            <CalendarWeek date={date} weekNumber={weekNumbers[0]} {...args} />
+            <CalendarWeek date={date} weekNumber={weekNumbers[0]} weekYear={weekYears[0]} {...args} />
             {dates.map(date => <CalendarDay key={date.toISOString()} date={date} dateNotesForMonth={dateNotesForPrevMonth} className="calendar-date-prev-month" {...args} />)}
         </>
     )
 }
 
-function CurrentMonthDays({ date, firstDayOfWeekISO, ...args }: { date: Dayjs, firstDayOfWeekISO: number } & CalendarArgs) {
+function CurrentMonthDays({ date, weekSettings, ...args }: { date: Dayjs, weekSettings: WeekSettings } & CalendarArgs) {
     let dateCursor = date;
     const currentMonth = date.month();
     const items: VNode[] = [];
     const curMonthString = date.format('YYYY-MM');
     const [ dateNotesForCurMonth, setDateNotesForCurMonth ] = useState<DateNotesForMonth>();
+    const { firstDayOfWeek, firstWeekOfYear, minDaysInFirstWeek } = weekSettings;
 
     useEffect(() => {
         server.get<DateNotesForMonth>(`special-notes/notes-for-month/${curMonthString}`).then(setDateNotesForCurMonth);
     }, [ date ]);
 
     while (dateCursor.month() === currentMonth) {
-        const weekNumber = getWeekNumber(dateCursor, firstDayOfWeekISO);
-        if (dateCursor.isoWeekday() === firstDayOfWeekISO) {
-            items.push(<CalendarWeek key={`${dateCursor.year()}-W${weekNumber}`} date={dateCursor} weekNumber={weekNumber} {...args}/>)
+        const { weekYear, weekNumber } = getWeekInfo(dateCursor, weekSettings);
+        if (dateCursor.isoWeekday() === firstDayOfWeek) {
+            items.push(<CalendarWeek key={`${weekYear}-W${weekNumber}`} date={dateCursor} weekNumber={weekNumber} weekYear={weekYear} {...args}/>)
         }
 
         items.push(<CalendarDay key={dateCursor.toISOString()} date={dateCursor} dateNotesForMonth={dateNotesForCurMonth} {...args} />)
@@ -141,14 +151,8 @@ function CalendarDay({ date, dateNotesForMonth, className, activeDate, todaysDat
     );
 }
 
-function CalendarWeek({ date, weekNumber, weekNotes, onWeekClicked }: { weekNumber: number, weekNotes: string[] } & Pick<CalendarArgs, "date" | "onWeekClicked">) {
-    const localDate = date.local();
-
-    // Handle case where week is in between years.
-    let year = localDate.year();
-    if (localDate.month() === 11 && weekNumber === 1) year++;
-
-    const weekString = `${year}-W${String(weekNumber).padStart(2, '0')}`;
+function CalendarWeek({ date, weekNumber, weekYear, weekNotes, onWeekClicked }: { weekNumber: number, weekYear: number, weekNotes: string[] } & Pick<CalendarArgs, "date" | "onWeekClicked">) {
+    const weekString = `${weekYear}-W${String(weekNumber).padStart(2, '0')}`;
 
     if (onWeekClicked) {
         return (
@@ -169,33 +173,33 @@ function CalendarWeek({ date, weekNumber, weekNotes, onWeekClicked }: { weekNumb
         >{weekNumber}</span>);
 }
 
-export function getMonthInformation(date: Dayjs, firstDayISO: number, firstDayOfWeekISO: number) {
+export function getMonthInformation(date: Dayjs, firstDayISO: number, weekSettings: WeekSettings) {
     return {
-        prevMonth: getPrevMonthDays(date, firstDayISO, firstDayOfWeekISO),
-        nextMonth: getNextMonthDays(date, firstDayOfWeekISO)
+        prevMonth: getPrevMonthDays(date, firstDayISO, weekSettings),
+        nextMonth: getNextMonthDays(date, weekSettings.firstDayOfWeek)
     }
 }
 
-function getPrevMonthDays(date: Dayjs, firstDayISO: number, firstDayOfWeekISO: number): DateRangeInfo {
+function getPrevMonthDays(date: Dayjs, firstDayISO: number, weekSettings: WeekSettings): DateRangeInfo {
     const prevMonthLastDay = date.subtract(1, 'month').endOf('month');
-    const daysToAdd = (firstDayISO - firstDayOfWeekISO + 7) % 7;
+    const daysToAdd = (firstDayISO - weekSettings.firstDayOfWeek + 7) % 7;
     const dates: Dayjs[] = [];
 
     const firstDay = date.startOf('month');
-    const weekNumber = getWeekNumber(firstDay, firstDayOfWeekISO);
+    const { weekYear, weekNumber } = getWeekInfo(firstDay, weekSettings);
 
     // Get dates from previous month
     for (let i = daysToAdd - 1; i >= 0; i--) {
         dates.push(prevMonthLastDay.subtract(i, 'day'));
     }
 
-    return { weekNumbers: [ weekNumber ], dates };
+    return { weekNumbers: [ weekNumber ], weekYears: [ weekYear ], dates };
 }
 
-function getNextMonthDays(date: Dayjs, firstDayOfWeekISO: number): DateRangeInfo {
+function getNextMonthDays(date: Dayjs, firstDayOfWeek: number): DateRangeInfo {
     const lastDayOfMonth = date.endOf('month');
     const lastDayISO = lastDayOfMonth.isoWeekday();
-    const lastDayOfUserWeek = ((firstDayOfWeekISO + 6 - 1) % 7) + 1;
+    const lastDayOfUserWeek = ((firstDayOfWeek + 6 - 1) % 7) + 1;
     const nextMonthFirstDay = date.add(1, 'month').startOf('month');
     const dates: Dayjs[] = [];
 
@@ -206,16 +210,5 @@ function getNextMonthDays(date: Dayjs, firstDayOfWeekISO: number): DateRangeInfo
             dates.push(nextMonthFirstDay.add(i, 'day'));
         }
     }
-    return { weekNumbers: [], dates };
-}
-
-export function getWeekNumber(date: Dayjs, firstDayOfWeekISO: number): number {
-    const weekStart = getWeekStartDate(date, firstDayOfWeekISO);
-    return weekStart.isoWeek();
-}
-
-function getWeekStartDate(date: Dayjs, firstDayOfWeekISO: number): Dayjs {
-    const currentISO = date.isoWeekday();
-    const diff = (currentISO - firstDayOfWeekISO + 7) % 7;
-    return date.clone().subtract(diff, "day").startOf("day");
+    return { weekNumbers: [], weekYears: [], dates };
 }

apps/client/vite.config.mts

@@ -93,15 +93,7 @@ export default defineConfig(() => ({
                 print: join(__dirname, "src", "print.tsx")
             },
             output: {
-                entryFileNames: (chunk) => {
-                    // We enforce a hash in the main index file to avoid caching issues, this only works because we have the HTML entry point.
-                    if (chunk.name === "index") {
-                        return "src/[name]-[hash].js";
-                    }
-
-                    // For EJS-rendered pages (e.g. login) we need to have a stable name.
-                    return "src/[name].js";
-                },
+                entryFileNames: "src/[name].js",
                 chunkFileNames: "src/[name]-[hash].js",
                 assetFileNames: "src/[name]-[hash].[ext]",
                 manualChunks: {

apps/server/package.json

@@ -126,7 +126,7 @@
     "swagger-jsdoc": "6.2.8",
     "time2fa": "1.4.2",
     "tmp": "0.2.5",
-    "turnish": "1.8.0",
+    "turnish": "1.7.1",
     "unescape": "1.0.1",
     "vite": "7.3.1",
     "ws": "8.19.0",

apps/server/src/services/date_notes.ts

@@ -2,7 +2,7 @@ import type BNote from "../becca/entities/bnote.js";
 
 import attributeService from "./attributes.js";
 import cloningService from "./cloning.js";
-import { dayjs, Dayjs } from "@triliumnext/commons";
+import { dayjs, Dayjs, getFirstDayOfWeek1, getWeekInfo, WeekSettings } from "@triliumnext/commons";
 import hoistedNoteService from "./hoisted_note.js";
 import noteService from "./notes.js";
 import optionService from "./options.js";
@@ -63,7 +63,8 @@ function getJournalNoteTitle(
     rootNote: BNote,
     timeUnit: TimeUnit,
     dateObj: Dayjs,
-    number: number
+    number: number,
+    weekYear?: number  // Optional: the week year for cross-year weeks
 ) {
     const patterns = {
         year: rootNote.getOwnedLabelValue("yearPattern") || "{year}",
@@ -79,9 +80,14 @@ function getJournalNoteTitle(
     const numberStr = number.toString();
     const ordinalStr = ordinal(dateObj);
 
+    // For week notes, use the weekYear if provided (handles cross-year weeks)
+    const yearForDisplay = (timeUnit === "week" && weekYear !== undefined)
+        ? weekYear.toString()
+        : dateObj.format("YYYY");
+
     const allReplacements: Record<string, string> = {
         // Common date formats
-        "{year}": dateObj.format("YYYY"),
+        "{year}": yearForDisplay,
 
         // Month related
         "{isoMonth}": dateObj.format("YYYY-MM"),
@@ -286,6 +292,14 @@ function getMonthNote(dateStr: string, _rootNote: BNote | null = null): BNote {
     return monthNote as unknown as BNote;
 }
 
+function getWeekSettings(): WeekSettings {
+    return {
+        firstDayOfWeek: parseInt(optionService.getOptionOrNull("firstDayOfWeek") ?? "1", 10),
+        firstWeekOfYear: parseInt(optionService.getOptionOrNull("firstWeekOfYear") ?? "0", 10),
+        minDaysInFirstWeek: parseInt(optionService.getOptionOrNull("minDaysInFirstWeek") ?? "4", 10)
+    };
+}
+
 function getWeekStartDate(date: Dayjs): Dayjs {
     const firstDayISO = parseInt(optionService.getOptionOrNull("firstDayOfWeek") ?? "1", 10);
     const day = date.isoWeekday();
@@ -294,9 +308,8 @@ function getWeekStartDate(date: Dayjs): Dayjs {
 }
 
 function getWeekNumberStr(date: Dayjs): string {
-    const isoYear = date.isoWeekYear();
-    const isoWeekNum = date.isoWeek();
-    return `${isoYear}-W${isoWeekNum.toString().padStart(2, "0")}`;
+    const { weekYear, weekNumber } = getWeekInfo(date, getWeekSettings());
+    return `${weekYear}-W${weekNumber.toString().padStart(2, "0")}`;
 }
 
 function getWeekFirstDayNote(dateStr: string, rootNote: BNote | null = null) {
@@ -329,17 +342,19 @@ function getWeekNote(weekStr: string, _rootNote: BNote | null = null): BNote | n
 
     const [ yearStr, weekNumStr ] = weekStr.trim().split("-W");
     const weekNumber = parseInt(weekNumStr);
+    const weekYear = parseInt(yearStr);
 
-    const firstDayOfYear = dayjs().year(parseInt(yearStr)).month(0).date(1);
-    const weekStartDate = firstDayOfYear.add(weekNumber - 1, "week");
-    const startDate = getWeekStartDate(weekStartDate);
-    const endDate = dayjs(startDate).add(6, "day");
+    // Calculate week start date based on user's first week of year settings.
+    // This correctly handles cross-year weeks based on user preferences.
+    const firstDayOfWeek1 = getFirstDayOfWeek1(weekYear, getWeekSettings());
+    const startDate = firstDayOfWeek1.add(weekNumber - 1, "week");
+    const endDate = startDate.add(6, "day");
 
     const startMonth = startDate.month();
     const endMonth = endDate.month();
 
     const monthNote = getMonthNote(startDate.format("YYYY-MM-DD"), rootNote);
-    const noteTitle = getJournalNoteTitle(rootNote, "week", startDate, weekNumber);
+    const noteTitle = getJournalNoteTitle(rootNote, "week", startDate, weekNumber, weekYear);
 
     sql.transactional(() => {
         weekNote = createNote(monthNote, noteTitle);

package.json

@@ -93,7 +93,7 @@
     "url": "https://github.com/TriliumNext/Trilium/issues"
   },
   "homepage": "https://triliumnotes.org",
-  "packageManager": "pnpm@10.28.1",
+  "packageManager": "pnpm@10.28.0",
   "pnpm": {
     "patchedDependencies": {
       "@ckeditor/ckeditor5-mention": "patches/@ckeditor__ckeditor5-mention.patch",

packages/codemirror/src/index.ts

@@ -1,5 +1,5 @@
 import { defaultKeymap, history, historyKeymap } from "@codemirror/commands";
-import { EditorView, highlightActiveLine, keymap, lineNumbers, placeholder, ViewPlugin, ViewUpdate, type EditorViewConfig, KeyBinding } from "@codemirror/view";
+import { EditorView, highlightActiveLine, keymap, lineNumbers, placeholder, ViewPlugin, ViewUpdate, type EditorViewConfig } from "@codemirror/view";
 import { defaultHighlightStyle, StreamLanguage, syntaxHighlighting, indentUnit, bracketMatching, foldGutter, codeFolding } from "@codemirror/language";
 import { Compartment, EditorSelection, EditorState, type Extension } from "@codemirror/state";
 import { highlightSelectionMatches } from "@codemirror/search";
@@ -12,17 +12,6 @@ import { createSearchHighlighter, SearchHighlighter, searchMatchHighlightTheme }
 
 export { default as ColorThemes, type ThemeDefinition, getThemeById } from "./color_themes.js";
 
-// Custom keymap to prevent Ctrl+Enter from inserting a newline
-// This allows the parent application to handle the shortcut (e.g., for "Run Active Note")
-const preventCtrlEnterKeymap: readonly KeyBinding[] = [
-    {
-        key: "Ctrl-Enter",
-        mac: "Cmd-Enter",
-        run: () => true, // Return true to mark event as handled, preventing default newline insertion
-        preventDefault: true
-    }
-];
-
 type ContentChangedListener = () => void;
 
 export interface EditorConfig {
@@ -70,7 +59,6 @@ export default class CodeMirror extends EditorView {
             lineNumbers(),
             indentUnit.of(" ".repeat(4)),
             keymap.of([
-                ...preventCtrlEnterKeymap,
                 ...defaultKeymap,
                 ...historyKeymap,
                 ...smartIndentWithTab

packages/commons/src/index.ts

@@ -13,3 +13,4 @@ export * from "./lib/attribute_names.js";
 export * from "./lib/utils.js";
 export * from "./lib/dayjs.js";
 export * from "./lib/notes.js";
+export * from "./lib/week_utils.js";

packages/commons/src/lib/week_utils.spec.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import { dayjs } from "./dayjs.js";
+import { getWeekInfo, getFirstDayOfWeek1, getWeekString, WeekSettings, DEFAULT_WEEK_SETTINGS } from "./week_utils.js";
+
+describe("week_utils", () => {
+    describe("getWeekInfo", () => {
+        describe("with firstWeekOfYear=0 (first week contains first day of year)", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 0,
+                minDaysInFirstWeek: 4
+            };
+
+            it("2025-12-29 should be 2026-W01 (cross-year week)", () => {
+                // 2026-01-01 is Thursday, so the week containing it starts on 2025-12-29 (Monday)
+                // This week should be 2026-W01 because it contains 2026-01-01
+                const result = getWeekInfo(dayjs("2025-12-29"), settings);
+                expect(result.weekYear).toBe(2026);
+                expect(result.weekNumber).toBe(1);
+            });
+
+            it("2026-01-01 should be 2026-W01", () => {
+                const result = getWeekInfo(dayjs("2026-01-01"), settings);
+                expect(result.weekYear).toBe(2026);
+                expect(result.weekNumber).toBe(1);
+            });
+
+            it("2025-12-28 should be 2025-W52", () => {
+                // 2025-12-28 is Sunday, which is the last day of the week starting 2025-12-22
+                const result = getWeekInfo(dayjs("2025-12-28"), settings);
+                expect(result.weekYear).toBe(2025);
+                expect(result.weekNumber).toBe(52);
+            });
+
+            it("2026-01-05 should be 2026-W02", () => {
+                // 2026-01-05 is Monday, start of second week
+                const result = getWeekInfo(dayjs("2026-01-05"), settings);
+                expect(result.weekYear).toBe(2026);
+                expect(result.weekNumber).toBe(2);
+            });
+        });
+
+        describe("with firstWeekOfYear=1 (ISO standard, first week contains first Thursday)", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 1,
+                minDaysInFirstWeek: 4
+            };
+
+            it("2023-01-01 should be 2022-W52 (Jan 1 is Sunday)", () => {
+                // 2023-01-01 is Sunday, so the week starts on 2022-12-26
+                // Since this week doesn't contain Jan 4, it's 2022-W52
+                const result = getWeekInfo(dayjs("2023-01-01"), settings);
+                expect(result.weekYear).toBe(2022);
+                expect(result.weekNumber).toBe(52);
+            });
+
+            it("2023-01-02 should be 2023-W01 (first Monday)", () => {
+                const result = getWeekInfo(dayjs("2023-01-02"), settings);
+                expect(result.weekYear).toBe(2023);
+                expect(result.weekNumber).toBe(1);
+            });
+        });
+
+        describe("with firstWeekOfYear=2 (minimum days in first week)", () => {
+            // 2026-01-01 is Thursday
+            // The week containing Jan 1 starts on 2025-12-29 (Monday)
+            // This week has 4 days in 2026 (Thu, Fri, Sat, Sun = Jan 1-4)
+
+            describe("with minDaysInFirstWeek=1", () => {
+                const settings: WeekSettings = {
+                    firstDayOfWeek: 1,
+                    firstWeekOfYear: 2,
+                    minDaysInFirstWeek: 1
+                };
+
+                it("2025-12-29 should be 2026-W01 (4 days >= 1 minimum)", () => {
+                    // Week has 4 days in 2026, which is >= 1
+                    const result = getWeekInfo(dayjs("2025-12-29"), settings);
+                    expect(result.weekYear).toBe(2026);
+                    expect(result.weekNumber).toBe(1);
+                });
+
+                it("2026-01-01 should be 2026-W01", () => {
+                    const result = getWeekInfo(dayjs("2026-01-01"), settings);
+                    expect(result.weekYear).toBe(2026);
+                    expect(result.weekNumber).toBe(1);
+                });
+            });
+
+            describe("with minDaysInFirstWeek=7", () => {
+                const settings: WeekSettings = {
+                    firstDayOfWeek: 1,
+                    firstWeekOfYear: 2,
+                    minDaysInFirstWeek: 7
+                };
+
+                it("2025-12-29 should be 2025-W52 (4 days < 7 minimum, so this is last week of 2025)", () => {
+                    // Week has only 4 days in 2026, which is < 7
+                    // So this week belongs to 2025
+                    const result = getWeekInfo(dayjs("2025-12-29"), settings);
+                    expect(result.weekYear).toBe(2025);
+                    expect(result.weekNumber).toBe(52);
+                });
+
+                it("2026-01-01 should be 2025-W52 (still last week of 2025)", () => {
+                    const result = getWeekInfo(dayjs("2026-01-01"), settings);
+                    expect(result.weekYear).toBe(2025);
+                    expect(result.weekNumber).toBe(52);
+                });
+
+                it("2026-01-05 should be 2026-W01 (first full week of 2026)", () => {
+                    // 2026-01-05 is Monday, start of the first full week
+                    const result = getWeekInfo(dayjs("2026-01-05"), settings);
+                    expect(result.weekYear).toBe(2026);
+                    expect(result.weekNumber).toBe(1);
+                });
+            });
+        });
+    });
+
+    describe("getFirstDayOfWeek1", () => {
+        it("with firstWeekOfYear=0, returns the first day of the week containing Jan 1", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 0,
+                minDaysInFirstWeek: 4
+            };
+            // 2026-01-01 is Thursday, so week starts on 2025-12-29
+            const result = getFirstDayOfWeek1(2026, settings);
+            expect(result.format("YYYY-MM-DD")).toBe("2025-12-29");
+        });
+
+        it("with firstWeekOfYear=1, returns the first day of the week containing Jan 4", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 1,
+                minDaysInFirstWeek: 4
+            };
+            // 2023-01-04 is Wednesday, so week starts on 2023-01-02
+            const result = getFirstDayOfWeek1(2023, settings);
+            expect(result.format("YYYY-MM-DD")).toBe("2023-01-02");
+        });
+    });
+
+    describe("getWeekString", () => {
+        it("generates correct week string for cross-year week", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 0,
+                minDaysInFirstWeek: 4
+            };
+            expect(getWeekString(dayjs("2025-12-29"), settings)).toBe("2026-W01");
+        });
+
+        it("generates correct week string with padded week number", () => {
+            const settings: WeekSettings = {
+                firstDayOfWeek: 1,
+                firstWeekOfYear: 0,
+                minDaysInFirstWeek: 4
+            };
+            expect(getWeekString(dayjs("2026-01-05"), settings)).toBe("2026-W02");
+        });
+    });
+});

packages/commons/src/lib/week_utils.ts

@@ -0,0 +1,143 @@
+import { dayjs, Dayjs } from "./dayjs.js";
+
+/**
+ * Week settings for calculating week numbers.
+ */
+export interface WeekSettings {
+    /** First day of the week (1=Monday to 7=Sunday) */
+    firstDayOfWeek: number;
+    /**
+     * How to determine the first week of the year:
+     * - 0: First week contains first day of the year
+     * - 1: First week contains first Thursday (ISO 8601 standard)
+     * - 2: First week has minimum days
+     */
+    firstWeekOfYear: number;
+    /** Minimum days in first week (used when firstWeekOfYear=2) */
+    minDaysInFirstWeek: number;
+}
+
+/**
+ * Default week settings (first week contains first day of year, week starts on Monday).
+ */
+export const DEFAULT_WEEK_SETTINGS: WeekSettings = {
+    firstDayOfWeek: 1,
+    firstWeekOfYear: 0,
+    minDaysInFirstWeek: 4
+};
+
+/**
+ * Gets the first day of week 1 for a given year, based on user settings.
+ *
+ * @param year The year to calculate for
+ * @param settings Week calculation settings
+ * @returns The first day of week 1
+ */
+export function getFirstDayOfWeek1(year: number, settings: WeekSettings = DEFAULT_WEEK_SETTINGS): Dayjs {
+    const { firstDayOfWeek, firstWeekOfYear, minDaysInFirstWeek } = settings;
+
+    const jan1 = dayjs(`${year}-01-01`);
+    const jan1Weekday = jan1.isoWeekday(); // 1=Monday, 7=Sunday
+
+    // Calculate the first day of the week containing Jan 1
+    const daysToSubtract = (jan1Weekday - firstDayOfWeek + 7) % 7;
+    const weekContainingJan1Start = jan1.subtract(daysToSubtract, "day");
+
+    if (firstWeekOfYear === 0) {
+        // First week contains first day of the year
+        return weekContainingJan1Start;
+    } else if (firstWeekOfYear === 1) {
+        // First week contains first Thursday (ISO 8601 standard)
+        const jan4 = dayjs(`${year}-01-04`);
+        const jan4Weekday = jan4.isoWeekday();
+        const daysToSubtractFromJan4 = (jan4Weekday - firstDayOfWeek + 7) % 7;
+        return jan4.subtract(daysToSubtractFromJan4, "day");
+    } else {
+        // First week has minimum days
+        const daysInFirstWeek = 7 - daysToSubtract;
+        if (daysInFirstWeek >= minDaysInFirstWeek) {
+            return weekContainingJan1Start;
+        } else {
+            return weekContainingJan1Start.add(1, "week");
+        }
+    }
+}
+
+/**
+ * Gets the week year and week number for a given date based on user settings.
+ *
+ * @param date The date to calculate week info for
+ * @param settings Week calculation settings
+ * @returns Object with weekYear and weekNumber
+ */
+export function getWeekInfo(date: Dayjs, settings: WeekSettings = DEFAULT_WEEK_SETTINGS): { weekYear: number; weekNumber: number } {
+    const { firstDayOfWeek } = settings;
+
+    // Get the start of the week containing this date
+    const dateWeekday = date.isoWeekday();
+    const daysToSubtract = (dateWeekday - firstDayOfWeek + 7) % 7;
+    const weekStart = date.subtract(daysToSubtract, "day");
+
+    // Try current year first
+    let year = date.year();
+    let firstDayOfWeek1 = getFirstDayOfWeek1(year, settings);
+
+    // If the week start is before week 1 of current year, it belongs to previous year
+    if (weekStart.isBefore(firstDayOfWeek1)) {
+        year--;
+        firstDayOfWeek1 = getFirstDayOfWeek1(year, settings);
+    } else {
+        // Check if this might belong to next year's week 1
+        const nextYearFirstDayOfWeek1 = getFirstDayOfWeek1(year + 1, settings);
+        if (!weekStart.isBefore(nextYearFirstDayOfWeek1)) {
+            year++;
+            firstDayOfWeek1 = nextYearFirstDayOfWeek1;
+        }
+    }
+
+    // Calculate week number
+    const weekNumber = weekStart.diff(firstDayOfWeek1, "week") + 1;
+
+    return { weekYear: year, weekNumber };
+}
+
+/**
+ * Generates a week string in the format "YYYY-Www" (e.g., "2026-W01").
+ *
+ * @param date The date to generate the week string for
+ * @param settings Week calculation settings
+ * @returns Week string in format "YYYY-Www"
+ */
+export function getWeekString(date: Dayjs, settings: WeekSettings = DEFAULT_WEEK_SETTINGS): string {
+    const { weekYear, weekNumber } = getWeekInfo(date, settings);
+    return `${weekYear}-W${weekNumber.toString().padStart(2, "0")}`;
+}
+
+/**
+ * Gets the start date of the week containing the given date.
+ *
+ * @param date The date to find the week start for
+ * @param firstDayOfWeek First day of the week (1=Monday to 7=Sunday)
+ * @returns The start of the week
+ */
+export function getWeekStartDate(date: Dayjs, firstDayOfWeek: number = 1): Dayjs {
+    const dateWeekday = date.isoWeekday();
+    const diff = (dateWeekday - firstDayOfWeek + 7) % 7;
+    return date.clone().subtract(diff, "day").startOf("day");
+}
+
+/**
+ * Parses a week string and returns the start date of that week.
+ *
+ * @param weekStr Week string in format "YYYY-Www" (e.g., "2026-W01")
+ * @param settings Week calculation settings
+ * @returns The start date of the week
+ */
+export function parseWeekString(weekStr: string, settings: WeekSettings = DEFAULT_WEEK_SETTINGS): Dayjs {
+    const [yearStr, weekNumStr] = weekStr.trim().split("-W");
+    const weekNumber = parseInt(weekNumStr);
+    const weekYear = parseInt(yearStr);
+
+    const firstDayOfWeek1 = getFirstDayOfWeek1(weekYear, settings);
+    return firstDayOfWeek1.add(weekNumber - 1, "week");
+}

pnpm-lock.yaml

@@ -354,8 +354,8 @@ importers:
         specifier: 0.7.2
         version: 0.7.2
       vite-plugin-static-copy:
-        specifier: 3.1.5
-        version: 3.1.5(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(less@4.1.3)(lightningcss@1.30.2)(sass-embedded@1.91.0)(sass@1.91.0)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+        specifier: 3.1.4
+        version: 3.1.4(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(less@4.1.3)(lightningcss@1.30.2)(sass-embedded@1.91.0)(sass@1.91.0)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
 
   apps/db-compare:
     dependencies:
@@ -793,8 +793,8 @@ importers:
         specifier: 0.2.5
         version: 0.2.5
       turnish:
-        specifier: 1.8.0
-        version: 1.8.0
+        specifier: 1.7.1
+        version: 1.7.1
       unescape:
         specifier: 1.0.1
         version: 1.0.1
@@ -10962,6 +10962,10 @@ packages:
     resolution: {integrity: sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ==}
     engines: {node: '>=10'}
 
+  p-map@7.0.3:
+    resolution: {integrity: sha512-VkndIv2fIB99swvQoA65bm+fsmt6UNdGeIB0oxBs+WhAhdh08QA04JXpI7rbB9r08/nkbysKoya9rtDERYOYMA==}
+    engines: {node: '>=18'}
+
   p-map@7.0.4:
     resolution: {integrity: sha512-tkAQEw8ysMzmkhgw8k+1U/iPhWNhykKnSk4Rd5zLoPJCuJaGRPo6YposrZgaxHKzDHdDWWZvE/Sk7hsL2X/CpQ==}
     engines: {node: '>=18'}
@@ -13479,8 +13483,8 @@ packages:
   turndown@7.2.2:
     resolution: {integrity: sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ==}
 
-  turnish@1.8.0:
-    resolution: {integrity: sha512-r1K94mbU5FHwvHKsPrTejuxoQTyKrddeWNzxS53Dnu+33DJLZJzfAHmo7GhdxBvhrHYCfv/diYvpq2VCGSGa+w==}
+  turnish@1.7.1:
+    resolution: {integrity: sha512-NgyY7pIDABjKyg2isRgZyFPav6tOyvmqpTx3HROsKrOaE3JccP4C1P2IhAtkAZ8DkQb/O1R7HOFAkxY8uaJmcQ==}
 
   type-check@0.4.0:
     resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
@@ -13860,8 +13864,8 @@ packages:
       vite:
         optional: true
 
-  vite-plugin-static-copy@3.1.5:
-    resolution: {integrity: sha512-9pbZn9Vb+uUNg/Tr/f2MXmGvfSfLeWjscS4zTA3v+sWqKN+AjJ/ipTFwaqdopJkNkxG5DfgYrZXD80ljbNDxbg==}
+  vite-plugin-static-copy@3.1.4:
+    resolution: {integrity: sha512-iCmr4GSw4eSnaB+G8zc2f4dxSuDjbkjwpuBLLGvQYR9IW7rnDzftnUjOH5p4RYR+d4GsiBqXRvzuFhs5bnzVyw==}
     engines: {node: ^18.0.0 || >=20.0.0}
     peerDependencies:
       vite: ^5.0.0 || ^6.0.0 || ^7.0.0
@@ -15307,6 +15311,8 @@ snapshots:
       '@ckeditor/ckeditor5-utils': 47.4.0
       '@ckeditor/ckeditor5-watchdog': 47.4.0
       es-toolkit: 1.39.5
+    transitivePeerDependencies:
+      - supports-color
 
   '@ckeditor/ckeditor5-dev-build-tools@54.3.0(@swc/helpers@0.5.17)(tslib@2.8.1)(typescript@5.9.3)':
     dependencies:
@@ -27144,6 +27150,8 @@ snapshots:
     dependencies:
       aggregate-error: 3.1.0
 
+  p-map@7.0.3: {}
+
   p-map@7.0.4: {}
 
   p-queue@6.6.2:
@@ -30122,7 +30130,7 @@ snapshots:
     dependencies:
       '@mixmark-io/domino': 2.2.0
 
-  turnish@1.8.0:
+  turnish@1.7.1:
     dependencies:
       '@adobe/css-tools': 4.4.4
       '@mixmark-io/domino': 2.2.0
@@ -30495,10 +30503,10 @@ snapshots:
       - rollup
       - supports-color
 
-  vite-plugin-static-copy@3.1.5(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(less@4.1.3)(lightningcss@1.30.2)(sass-embedded@1.91.0)(sass@1.91.0)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)):
+  vite-plugin-static-copy@3.1.4(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(less@4.1.3)(lightningcss@1.30.2)(sass-embedded@1.91.0)(sass@1.91.0)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)):
     dependencies:
       chokidar: 3.6.0
-      p-map: 7.0.4
+      p-map: 7.0.3
       picocolors: 1.1.1
       tinyglobby: 0.2.15
       vite: 7.3.1(@types/node@24.10.9)(jiti@2.6.1)(less@4.1.3)(lightningcss@1.30.2)(sass-embedded@1.91.0)(sass@1.91.0)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)