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

[J-Sek]

Description

• re-introduces first-day-of-year from v2 (without locale-* prefix)
• users won't be forced to use a specific locale when they want the week numbers to align with the target audience
  • e.g. I will be able to have en messages, and won't be forced to either en-GB or en-US for week-related configuration

Note: ⚠️ This first-day-of-year is working fine only when combined with first-day-of-week="1".

---

• make it work with first-day-of-week
• refactoring
• unit tests
• week-min-size prop as a recommended alternative

resolves #20270

Playground

<template>
  <v-app theme="dark">
    <v-container max-width="800">
      <div class="d-flex flex-wrap ga-3 justify-space-between">
        <v-locale-provider locale="de">
          <!-- both pickers should show the same week values when firstDayOfYear is defined -->
          <v-date-picker
            :first-day-of-week="firstDayOfWeek"
            :first-day-of-year="firstDayOfYear"
            :model-value="`${year}-01-01`"
            elevation="4"
            title="with custom locale (de)"
            show-adjacent-months
            show-week
          />
        </v-locale-provider>

        <v-date-picker
          :first-day-of-week="firstDayOfWeek"
          :first-day-of-year="firstDayOfYear"
          :model-value="`${year}-01-01`"
          elevation="4"
          title="with default locale (en)"
          show-adjacent-months
          show-week
        />
      </div>
      <br>

      <v-number-input v-model="year" :max="2040" :min="2000" control-variant="split" />

      <div class="d-flex ga-3 align-center">
        <v-switch v-model="customFirstDayOfWeek" label="custom" hide-details />
        <v-slider
          v-if="customFirstDayOfWeek"
          v-model="firstDayOfWeek"
          :step="1"
          :ticks="'SMTWTFS'.split('').reduce((o,v,i) => ({ ...o, [i]: v}), {})"
          label="first day of week"
          max="6"
          min="0"
          show-ticks="always"
          hide-details
        />

      </div>

      <div class="d-flex ga-3 align-center">
        <v-switch v-model="customFirstDayOfYear" label="custom" hide-details />
        <v-slider
          v-if="customFirstDayOfYear"
          v-model="firstDayOfYear"
          :step="1"
          :ticks="'SMTWTFS'.split('').reduce((o,v,i) => ({ ...o, [i]: v}), {})"
          label="first day of year"
          max="6"
          min="0"
          show-ticks="always"
          hide-details
        />
      </div>
    </v-container>
  </v-app>
</template>

<script setup lang="ts">
  import { computed, onBeforeMount, shallowRef } from 'vue'
  import { useDate } from 'vuetify'

  const year = shallowRef(2032)

  const firstDayOfWeek = shallowRef<number | undefined>(0)

  const customFirstDayOfWeek = computed<boolean>({
    get: () => firstDayOfWeek.value !== undefined,
    set: v => firstDayOfWeek.value = v ? 0 : undefined,
  })

  const firstDayOfYear = shallowRef<number | undefined>()

  const customFirstDayOfYear = computed<boolean>({
    get: () => firstDayOfYear.value !== undefined,
    set: v => firstDayOfYear.value = v ? 0 : undefined,
  })

  const adapter = useDate()
  onBeforeMount(() => {
    adapter.locale = { en: 'en-GB' }
  })
</script>