Added FOAM_DATE_WEEK_YEAR template variable (#1532)

* Updated resolver to include FOAM_DATE_WEEK_YEAR
* Updated docs

Author: ChThH

docs/user/features/templates.md

@@ -258,6 +258,7 @@ Supported variables include:
 - `FOAM_DATE_YEAR`: 4-digit year (e.g. 2025)
 - `FOAM_DATE_MONTH`: 2-digit month (e.g. 09)
 - `FOAM_DATE_WEEK`: ISO 8601 week number (e.g. 37)
+- `FOAM_DATE_WEEK_YEAR`: the year of the ISO 8601 week number. The year that contains the Thursday of the current week, may vary from calendar year near Jan 1. Often used with `FOAM_DATE_WEEK`.
 - `FOAM_DATE_DAY_ISO`: ISO 8601 weekday number (1-7, where Monday=1, Sunday=7)
 - `FOAM_DATE_DATE`: 2-digit day of month (e.g. 15)
 - `FOAM_DATE_DAY_NAME`: Full weekday name (e.g. Monday)

packages/foam-vscode/src/dated-notes.spec.ts

@@ -111,6 +111,7 @@ Month: \${FOAM_DATE_MONTH} (name: \${FOAM_DATE_MONTH_NAME}, short: \${FOAM_DATE_
 Date: \${FOAM_DATE_DATE}
 Day: \${FOAM_DATE_DAY_NAME} (short: \${FOAM_DATE_DAY_NAME_SHORT})
 Week: \${FOAM_DATE_WEEK}
+Week Year: \${FOAM_DATE_WEEK_YEAR}
 Unix: \${FOAM_DATE_SECONDS_UNIX}`,
         DAILY_NOTE_TEMPLATE
       );
@@ -127,6 +128,7 @@ Unix: \${FOAM_DATE_SECONDS_UNIX}`,
       expect(content).toContain('Date: 12');
       expect(content).toContain('Day: Sunday (short: Sun)');
       expect(content).toContain('Week: 36');
+      expect(content).toContain('Week Year: 2021');
 
       await deleteFile(template.uri);
       await deleteFile(result.uri);

packages/foam-vscode/src/services/variable-resolver.spec.ts

@@ -156,6 +156,13 @@ describe('variable-resolver, variable resolution', () => {
     expect(await resolver.resolveAll(variables)).toEqual(expected);
   });
 
+  function getISOWeekYear(date: Date): number {
+    const temp = new Date(date.getTime());
+    // Set to Thursday of this week (ISO 8601 defines week based on Thursday)
+    temp.setDate(temp.getDate() + 3 - ((temp.getDay() + 6) % 7));
+    return temp.getFullYear();
+  }
+
   it('should resolve FOAM_DATE_* properties with current day by default', async () => {
     const variables = [
       new Variable('FOAM_DATE_YEAR'),
@@ -171,6 +178,7 @@ describe('variable-resolver, variable resolution', () => {
       new Variable('FOAM_DATE_SECOND'),
       new Variable('FOAM_DATE_SECONDS_UNIX'),
       new Variable('FOAM_DATE_DAY_ISO'),
+      new Variable('FOAM_DATE_WEEK_YEAR'),
     ];
 
     const expected = new Map<string, string>();
@@ -188,6 +196,8 @@ describe('variable-resolver, variable resolution', () => {
       now.toLocaleString('default', { day: '2-digit' })
     );
     expected.set('FOAM_DATE_DAY_ISO', String(((now.getDay() + 6) % 7) + 1));
+    expected.set('FOAM_DATE_WEEK_YEAR', String(getISOWeekYear(now)));
+
     const givenValues = new Map<string, string>();
     const resolver = new Resolver(givenValues, new Date());
 
@@ -213,6 +223,7 @@ describe('variable-resolver, variable resolution', () => {
       new Variable('FOAM_DATE_SECONDS_UNIX'),
       new Variable('FOAM_DATE_WEEK'),
       new Variable('FOAM_DATE_DAY_ISO'),
+      new Variable('FOAM_DATE_WEEK_YEAR'),
     ];
 
     const expected = new Map<string, string>();
@@ -233,6 +244,7 @@ describe('variable-resolver, variable resolution', () => {
       (targetDate.getTime() / 1000).toString()
     );
     expected.set('FOAM_DATE_DAY_ISO', '5'); // Friday is 5 in ISO 8601
+    expected.set('FOAM_DATE_WEEK_YEAR', '2021');
 
     const givenValues = new Map<string, string>();
     const resolver = new Resolver(givenValues, targetDate);
@@ -265,6 +277,44 @@ describe('variable-resolver, variable resolution', () => {
     });
   });
 
+  test.each([
+    [new Date(2025, 0, 1), '2025', '01'], // Jan 1 2025 (Wed) - week 1 of 2025
+    [new Date(2024, 11, 30), '2025', '01'], // Dec 30 2024 (Mon) - week 1 of 2025
+    [new Date(2024, 0, 1), '2024', '01'], // Jan 1 2024 (Mon) - week 1 of 2024
+    [new Date(2023, 0, 1), '2022', '52'], // Jan 1 2023 (Sun) - week 52 of 2022
+    [new Date(2022, 0, 1), '2021', '52'], // Jan 1 2022 (Sat) - week 52 of 2021
+  ])(
+    'should resolve FOAM_DATE_WEEK_YEAR correctly',
+    async (date, expectedWeekYear, expectedWeek) => {
+      const resolver = new Resolver(new Map(), date);
+      const weekYear = await resolver.resolve(
+        new Variable('FOAM_DATE_WEEK_YEAR')
+      );
+      const week = await resolver.resolve(new Variable('FOAM_DATE_WEEK'));
+
+      expect(weekYear).toBe(expectedWeekYear);
+      expect(week).toBe(expectedWeek);
+    }
+  );
+
+  it('should resolve FOAM_DATE_WEEK_YEAR with FOAM_DATE_WEEK in template', async () => {
+    // Example: 2024-W01 format where Dec 30, 2024 is in week 1 of 2025
+    const date = new Date(2024, 11, 30); // Dec 30, 2024 (Monday)
+    const resolver = new Resolver(new Map(), date);
+
+    const variables = [
+      new Variable('FOAM_DATE_WEEK_YEAR'),
+      new Variable('FOAM_DATE_WEEK'),
+      new Variable('FOAM_DATE_YEAR'),
+    ];
+
+    const result = await resolver.resolveAll(variables);
+
+    expect(result.get('FOAM_DATE_WEEK_YEAR')).toBe('2025');
+    expect(result.get('FOAM_DATE_WEEK')).toBe('01');
+    expect(result.get('FOAM_DATE_YEAR')).toBe('2024');
+  });
+
   describe('FOAM_CURRENT_DIR', () => {
     it('should resolve to workspace root when no active editor', async () => {
       const resolver = new Resolver(new Map<string, string>(), new Date());

packages/foam-vscode/src/services/variable-resolver.ts

@@ -23,6 +23,7 @@ const knownFoamVariables = new Set([
   'FOAM_DATE_DATE',
   'FOAM_DATE_DAY_ISO',
   'FOAM_DATE_WEEK',
+  'FOAM_DATE_WEEK_YEAR',
   'FOAM_DATE_DAY_NAME',
   'FOAM_DATE_DAY_NAME_SHORT',
   'FOAM_DATE_HOUR',
@@ -216,6 +217,18 @@ export class Resolver implements VariableResolver {
           value = Promise.resolve(String(weekDay.valueOf()).padStart(2, '0'));
           break;
         }
+        case 'FOAM_DATE_WEEK_YEAR': {
+          // ISO 8601 week-numbering year
+          // The year that contains the Thursday of the current week
+          const date = new Date(this.foamDate);
+
+          // Find Thursday of this week starting on Monday
+          date.setDate(date.getDate() + 4 - (date.getDay() || 7));
+
+          // The year of this Thursday is the ISO week year
+          value = Promise.resolve(String(date.getFullYear()));
+          break;
+        }
         case 'FOAM_DATE_DAY_NAME':
           value = Promise.resolve(
             this.foamDate.toLocaleString('default', { weekday: 'long' })