feat: add StringDateAdapter (#21174)

closes #20967

Author: KaelWD

packages/docs/src/pages/en/features/dates.md

@@ -370,3 +370,19 @@ declare module 'vuetify' {
   }
 }
 ```
+
+## String adapter
+
+<DocIntroduced version="3.9.0" />
+
+Date objects can be inconvenient to work with, especially if you're just passing the value straight to a fetch request. Vuetify also exports a StringDateAdapter that will cause date components to emit strings instead.
+
+```ts { resource="src/plugins/vuetify.js" }
+import { StringDateAdapter } from 'vuetify/date/adapters/string'
+
+export default createVuetify({
+  date: {
+    adapter: StringDateAdapter,
+  },
+})
+```

packages/vuetify/dev/vuetify/date.js

@@ -1,3 +1,4 @@
+import { StringDateAdapter } from '@/composables/date/adapters/string'
 // import DateFnsAdapter from '@date-io/date-fns'
 // import { enAU, enUS, ja, sv } from 'date-fns/locale'
 
@@ -9,6 +10,7 @@
 
 export default {
   // adapter: DateFnsAdapter,
+  adapter: StringDateAdapter,
   formats: {
     // dayOfMonth: date => date.getDate(),
   },

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

@@ -15,11 +15,11 @@ export interface DateAdapter<T = unknown> {
   endOfYear (date: T): T
 
   isAfter (date: T, comparing: T): boolean
-  isAfterDay(value: T, comparing: T): boolean
+  isAfterDay(date: T, comparing: T): boolean
 
   isSameDay (date: T, comparing: T): boolean
   isSameMonth (date: T, comparing: T): boolean
-  isSameYear(value: T, comparing: T): boolean
+  isSameYear(date: T, comparing: T): boolean
 
   isBefore (date: T, comparing: T): boolean
   isEqual (date: T, comparing: T): boolean

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

@@ -1,4 +1,5 @@
 // Utilities
+import { StringDateAdapter } from '../adapters/string'
 import { VuetifyDateAdapter } from '../adapters/vuetify'
 
 // Types
@@ -7,12 +8,16 @@ import type { DateAdapter } from '../DateAdapter'
 
 function expectAssignable<T, T2 extends T = T> (value: T2): void {}
 
-describe('date.ts', () => {
-  // Cannot define properties that don't exist in date-io
-  expectAssignable<DateAdapter>({} as IUtils<Date, string>)
-  // @ts-expect-error Can implement a subset of date-io
-  expectAssignable<IUtils<Date>>({} as DateAdapter)
+describe('date', () => {
+  it('types', () => {
+    // Cannot define properties that don't exist in date-io
+    expectAssignable<DateAdapter>({} as IUtils<Date, string>)
+    // @ts-expect-error Can implement a subset of date-io
+    expectAssignable<IUtils<Date>>({} as DateAdapter)
+  })
+})
 
+describe('VuetifyDateAdapter', () => {
   it('should have the correct days in a month', () => {
     const adapter = new VuetifyDateAdapter({ locale: 'en-US' })
 
@@ -90,3 +95,82 @@ describe('date.ts', () => {
     expect(adapter2.getWeek(new Date('2025-01-06'))).toBe(2) // monday
   })
 })
+
+describe('StringDateAdapter', () => {
+  it('should have the correct days in a month', () => {
+    const adapter = new StringDateAdapter({ locale: 'en-US' })
+
+    expect(adapter.getWeek('2023-10-10')).toBe(41)
+  })
+
+  it('should correctly calculate weeks between years', () => {
+    const adapter = new StringDateAdapter({ locale: 'en-US' })
+
+    expect(adapter.getWeek('2024-12-28')).toBe(52)
+    expect(adapter.getWeek('2024-12-29')).toBe(1)
+    expect(adapter.getWeek('2024-12-30')).toBe(1)
+    expect(adapter.getWeek('2024-12-31')).toBe(1)
+    expect(adapter.getWeek('2025-01-01')).toBe(1)
+    expect(adapter.getWeek('2025-01-02')).toBe(1)
+    expect(adapter.getWeek('2025-01-03')).toBe(1)
+    expect(adapter.getWeek('2025-01-04')).toBe(1)
+    expect(adapter.getWeek('2025-01-05')).toBe(2)
+  })
+
+  it('should correctly calculate when year starts with a full week', () => {
+    const adapter1 = new StringDateAdapter({ locale: 'en-US' }) // first day = 7 | minimal days = 1
+
+    expect(adapter1.getWeek('2022-12-25')).toBe(53)
+    expect(adapter1.getWeek('2022-12-31')).toBe(53)
+    expect(adapter1.getWeek('2023-01-01')).toBe(1)
+    expect(adapter1.getWeek('2023-01-07')).toBe(1)
+
+    const adapter2 = new StringDateAdapter({ locale: 'pt' }) // first day = 7 | minimal days = 4
+
+    expect(adapter2.getWeek('2022-12-25')).toBe(52)
+    expect(adapter2.getWeek('2022-12-31')).toBe(52)
+    expect(adapter2.getWeek('2023-01-01')).toBe(1)
+    expect(adapter2.getWeek('2023-01-07')).toBe(1)
+  })
+
+  it('should adjust for start of a week', () => {
+    const adapter = new StringDateAdapter({ locale: 'en-US' }) // first day = 7 | minimal days = 1
+
+    expect(adapter.getWeek('2028-12-25', 1)).toBe(53)
+    expect(adapter.getWeek('2028-12-31', 1)).toBe(53)
+    expect(adapter.getWeek('2029-01-01', 1)).toBe(1)
+    expect(adapter.getWeek('2029-01-07', 1)).toBe(1)
+
+    const adapter2 = new StringDateAdapter({ locale: 'pt-PT' }) // first day = 7 | minimal days = 4
+
+    expect(adapter2.getWeek('2024-12-28', 1)).toBe(52)
+    expect(adapter2.getWeek('2024-12-29', 1)).toBe(52)
+    expect(adapter2.getWeek('2024-12-30', 1)).toBe(1)
+    expect(adapter2.getWeek('2024-12-31', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-01', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-02', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-03', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-04', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-05', 1)).toBe(1)
+    expect(adapter2.getWeek('2025-01-06', 1)).toBe(2)
+    expect(adapter2.getWeek('2025-01-07', 1)).toBe(2)
+
+    expect(adapter2.getWeek('2028-12-25', 1)).toBe(52)
+    expect(adapter2.getWeek('2028-12-31', 1)).toBe(52)
+    expect(adapter2.getWeek('2029-01-01', 1)).toBe(1)
+    expect(adapter2.getWeek('2029-01-07', 1)).toBe(1)
+
+    const adapter3 = new StringDateAdapter({ locale: 'pl-PL' })
+    expect(adapter3.getWeek('2024-12-29', 1)).toBe(52)
+  })
+
+  it('should adjust fallback to week start from locale', () => {
+    const adapter1 = new StringDateAdapter({ locale: 'en-US' })
+    expect(adapter1.getWeek('2025-01-04')).toBe(1) // saturday
+    expect(adapter1.getWeek('2025-01-05')).toBe(2) // sunday
+
+    const adapter2 = new StringDateAdapter({ locale: 'fr' })
+    expect(adapter2.getWeek('2025-01-05')).toBe(1) // sunday
+    expect(adapter2.getWeek('2025-01-06')).toBe(2) // monday
+  })
+})