feat(VDatePicker): re-introduce first-day-of-year prop (#21760)

resolves #20270

Author: J-Sek

packages/api-generator/src/locale/en/VCalendar.json

@@ -1,7 +1,6 @@
 {
   "props": {
     "allowedDates": "Determines which dates are selectable.",
-    "firstDayOfWeek": "Sets the first day of the week, starting with 0 for Sunday.",
     "hideHeader": "Determines whether the header is hidden in the calendar view.",
     "hideWeekNumber": "Toggles the display of week numbers in a calendar view.",
     "intervals": "Total number of intervals in a day view.",

packages/api-generator/src/locale/en/generic.json

@@ -18,7 +18,8 @@
     "end": "Applies margin at the start of the component.",
     "falseIcon": "The icon used when inactive.",
     "falseValue": "Sets value for falsy state.",
-    "firstDayOfWeek": "Sets the first day of the week, starting with 0 for Sunday.",
+    "firstDayOfWeek": "Sets the first day of the week, starting with 0 for Sunday. (Note: not guaranteed to work when using custom date adapters.)",
+    "firstDayOfYear": "Sets the day that determines the first week of the year, starting with 0 for Sunday. For ISO 8601 this should be 4. (Note: not guaranteed to work when using custom date adapters.)",
     "fullWidth": "Sets the component width to 100%.",
     "height": "Sets the height for the component.",
     "hideNoData": "Hides the menu when there are no options to show.  Useful for preventing the menu from opening before results are fetched asynchronously.  Also has the effect of opening the menu when the `items` array changes if not already open.",

packages/docs/src/data/new-in.json

@@ -57,6 +57,7 @@
   "VDatePicker": {
     "props": {
       "controlHeight": "3.8.0",
+      "firstDayOfYear": "3.9.3",
       "headerColor": "3.8.0"
     }
   },

packages/vuetify/src/composables/calendar.ts

@@ -23,6 +23,7 @@ export interface CalendarProps {
   year: number | string | undefined
   weeksInMonth: 'dynamic' | 'static'
   firstDayOfWeek: number | string | undefined
+  firstDayOfYear: number | string | undefined
   weekdayFormat: 'long' | 'short' | 'narrow' | undefined
 
   'onUpdate:modelValue': ((value: unknown[]) => void) | undefined
@@ -77,6 +78,10 @@ export const makeCalendarProps = propsFactory({
     type: [Number, String],
     default: undefined,
   },
+  firstDayOfYear: {
+    type: [Number, String],
+    default: undefined,
+  },
   weekdayFormat: String as PropType<'long' | 'short' | 'narrow' | undefined>,
 }, 'calendar')
 
@@ -206,7 +211,7 @@ export function useCalendar (props: CalendarProps) {
 
   const weekNumbers = computed(() => {
     return weeksInMonth.value.map(week => {
-      return week.length ? adapter.getWeek(week[0], props.firstDayOfWeek) : null
+      return week.length ? adapter.getWeek(week[0], props.firstDayOfWeek, props.firstDayOfYear) : null
     })
   })
 

packages/vuetify/src/composables/date/DateAdapter.ts

@@ -37,7 +37,7 @@ export interface DateAdapter<T = unknown> {
   getDiff (date: T, comparing: T | string, unit?: string): number
   getWeekArray (date: T, firstDayOfWeek?: number | string): T[][]
   getWeekdays (firstDayOfWeek?: number | string, weekdayFormat?: 'long' | 'short' | 'narrow'): string[]
-  getWeek (date: T, firstDayOfWeek?: number | string, firstWeekMinSize?: number): number
+  getWeek (date: T, firstDayOfWeek?: number | string, firstDayOfYear?: number | string): number
   getMonth (date: T): number
   setMonth (date: T, month: number): T
   getDate (date: T): number

packages/vuetify/src/composables/date/__tests__/date.spec.ts

@@ -178,6 +178,16 @@ describe('VuetifyDateAdapter', () => {
       expect(adapter.getWeek(adapter.parseISO('2025-11-03'))).toBe(45)
     })
   })
+
+  describe('week numbers with first-day-of-week', () => {
+    it('should calculate weeks correctly when adapting for UK', () => {
+      const adapterUS = new VuetifyDateAdapter({ locale: 'en-US' })
+      const adapterGB = new VuetifyDateAdapter({ locale: 'en-GB' })
+      expect(adapterUS.getWeek(adapterUS.parseISO('2025-03-16'))).toBe(12)
+      expect(adapterGB.getWeek(adapterGB.parseISO('2025-03-16'))).toBe(11)
+      expect(adapterUS.getWeek(adapterUS.parseISO('2025-03-16'), 1, 4)).toBe(11)
+    })
+  })
 })
 
 describe('StringDateAdapter', () => {

packages/vuetify/src/composables/date/adapters/string.ts

@@ -112,8 +112,8 @@ export class StringDateAdapter implements DateAdapter<string> {
     return this.base.getMonth(this.base.date(date)!)
   }
 
-  getWeek (date: string, firstDayOfWeek?: number | string, firstWeekMinSize?: number): number {
-    return this.base.getWeek(this.base.date(date)!, firstDayOfWeek, firstWeekMinSize)
+  getWeek (date: string, firstDayOfWeek?: number | string, firstDayOfYear?: number | string): number {
+    return this.base.getWeek(this.base.date(date)!, firstDayOfWeek, firstDayOfYear)
   }
 
   getNextMonth (date: string): string {

packages/vuetify/src/composables/date/adapters/vuetify.ts

@@ -315,17 +315,48 @@ function getMonth (date: Date) {
   return date.getMonth()
 }
 
-function getWeek (date: Date, locale: string, firstDayOfWeek?: number, firstWeekMinSize?: number) {
+function getWeek (date: Date, locale: string, firstDayOfWeek?: number, firstDayOfYear?: number) {
   const weekInfoFromLocale = weekInfo(locale)
   const weekStart = firstDayOfWeek ?? weekInfoFromLocale?.firstDay ?? 0
-  const minWeekSize = firstWeekMinSize ?? weekInfoFromLocale?.firstWeekSize ?? 1
+  const minWeekSize = weekInfoFromLocale?.firstWeekSize ?? 1
+
+  return firstDayOfYear !== undefined
+    ? calculateWeekWithFirstDayOfYear(date, locale, weekStart, firstDayOfYear)
+    : calculateWeekWithMinWeekSize(date, locale, weekStart, minWeekSize)
+}
+
+function calculateWeekWithFirstDayOfYear (date: Date, locale: string, weekStart: number, firstDayOfYear: number) {
+  const firstDayOfYearOffset = (7 + firstDayOfYear - weekStart) % 7
+  const currentWeekStart = startOfWeek(date, locale, weekStart)
+  const currentWeekEnd = addDays(currentWeekStart, 6)
+
+  function yearStartWeekdayOffset (year: number) {
+    return (7 + new Date(year, 0, 1).getDay() - weekStart) % 7
+  }
+
+  let year = getYear(date)
+  if (year < getYear(currentWeekEnd) && yearStartWeekdayOffset(year + 1) <= firstDayOfYearOffset) {
+    year++
+  }
+
+  const yearStart = new Date(year, 0, 1)
+  const offset = yearStartWeekdayOffset(year)
+  const d1w1 = offset <= firstDayOfYearOffset
+    ? addDays(yearStart, -offset)
+    : addDays(yearStart, 7 - offset)
+
+  return 1 + getDiff(endOfDay(date), startOfDay(d1w1), 'weeks')
+}
+
+function calculateWeekWithMinWeekSize (date: Date, locale: string, weekStart: number, minWeekSize: number) {
+  const currentWeekEnd = addDays(startOfWeek(date, locale, weekStart), 6)
+
   function firstWeekSize (year: number) {
     const yearStart = new Date(year, 0, 1)
     return 7 - getDiff(yearStart, startOfWeek(yearStart, locale, weekStart), 'days')
   }
 
   let year = getYear(date)
-  const currentWeekEnd = addDays(startOfWeek(date, locale, weekStart), 6)
   if (year < getYear(currentWeekEnd) && firstWeekSize(year + 1) >= minWeekSize) {
     year++
   }
@@ -335,7 +366,6 @@ function getWeek (date: Date, locale: string, firstDayOfWeek?: number, firstWeek
   const d1w1 = size >= minWeekSize
     ? addDays(yearStart, size - 7)
     : addDays(yearStart, size)
-
   return 1 + getDiff(endOfDay(date), startOfDay(d1w1), 'weeks')
 }
 
@@ -616,9 +646,10 @@ export class VuetifyDateAdapter implements DateAdapter<Date> {
     return getMonth(date)
   }
 
-  getWeek (date: Date, firstDayOfWeek?: number | string, firstWeekMinSize?: number) {
+  getWeek (date: Date, firstDayOfWeek?: number | string, firstDayOfYear?: number | string) {
     const firstDay = firstDayOfWeek !== undefined ? Number(firstDayOfWeek) : undefined
-    return getWeek(date, this.locale, firstDay, firstWeekMinSize)
+    const firstWeekStart = firstDayOfYear !== undefined ? Number(firstDayOfYear) : undefined
+    return getWeek(date, this.locale, firstDay, firstWeekStart)
   }
 
   getDate (date: Date) {