Use day names instead of numbers for the API

packages/dataviews/src/dataform-controls/date.tsx

@@ -51,6 +51,7 @@ import type {
 	NormalizedField,
 } from '../types';
 import getCustomValidity from './utils/get-custom-validity';
+import { weekStartsOnToNumber } from '../utils/week-starts-on';
 
 const { DateCalendar, DateRangeCalendar } = unlock( componentsPrivateApis );
 
@@ -395,7 +396,9 @@ function CalendarDateControl< Item >( {
 						month={ calendarMonth }
 						onMonthChange={ setCalendarMonth }
 						timeZone={ timezoneString || undefined }
-						weekStartsOn={ field.displayFormat.weekStartsOn }
+						weekStartsOn={ weekStartsOnToNumber(
+							field.displayFormat.weekStartsOn
+						) }
 					/>
 				</VStack>
 			</BaseControl>
@@ -608,7 +611,9 @@ function CalendarDateRangeControl< Item >( {
 						month={ calendarMonth }
 						onMonthChange={ setCalendarMonth }
 						timeZone={ timezone.string || undefined }
-						weekStartsOn={ field.displayFormat.weekStartsOn }
+						weekStartsOn={ weekStartsOnToNumber(
+							field.displayFormat.weekStartsOn
+						) }
 					/>
 				</VStack>
 			</BaseControl>

packages/dataviews/src/stories/field-types.story.tsx

@@ -839,7 +839,14 @@ export const DateComponent = ( {
 	Edit: ControlTypes;
 	asyncElements: boolean;
 	displayFormatDate?: string;
-	displayFormatWeekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+	displayFormatWeekStartsOn?:
+		| 'sunday'
+		| 'monday'
+		| 'tuesday'
+		| 'wednesday'
+		| 'thursday'
+		| 'friday'
+		| 'saturday';
 } ) => {
 	const dateFields = useMemo(
 		() =>
@@ -852,7 +859,14 @@ export const DateComponent = ( {
 					) {
 						const displayFormat: {
 							date?: string;
-							weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+							weekStartsOn?:
+								| 'sunday'
+								| 'monday'
+								| 'tuesday'
+								| 'wednesday'
+								| 'thursday'
+								| 'friday'
+								| 'saturday';
 						} = {};
 						if ( displayFormatDate ) {
 							displayFormat.date = displayFormatDate;
@@ -895,13 +909,13 @@ DateComponent.argTypes = {
 		control: 'select',
 		options: {
 			Default: undefined,
-			Sunday: 0,
-			Monday: 1,
-			Tuesday: 2,
-			Wednesday: 3,
-			Thursday: 4,
-			Friday: 5,
-			Saturday: 6,
+			Sunday: 'sunday',
+			Monday: 'monday',
+			Tuesday: 'tuesday',
+			Wednesday: 'wednesday',
+			Thursday: 'thursday',
+			Friday: 'friday',
+			Saturday: 'saturday',
 		},
 		description:
 			'Day that the week starts on. Leave as Default to use WordPress default.',

packages/dataviews/src/test/normalize-fields.ts

@@ -353,7 +353,7 @@ describe( 'normalizeFields: default getValue', () => {
 			).toBeDefined();
 			expect(
 				typeof normalizedFields[ 0 ].displayFormat.weekStartsOn
-			).toBe( 'number' );
+			).toBe( 'string' );
 		} );
 
 		it( 'preserves custom format when provided', () => {
@@ -363,14 +363,14 @@ describe( 'normalizeFields: default getValue', () => {
 					type: 'date',
 					displayFormat: {
 						date: 'F j, Y',
-						weekStartsOn: 1,
+						weekStartsOn: 'monday',
 					},
 				},
 			];
 			const normalizedFields = normalizeFields( fields );
 			expect( normalizedFields[ 0 ].displayFormat.date ).toBe( 'F j, Y' );
 			expect( normalizedFields[ 0 ].displayFormat.weekStartsOn ).toBe(
-				1
+				'monday'
 			);
 		} );
 

packages/dataviews/src/types/field-api.ts

@@ -319,13 +319,20 @@ export type Field< Item > = {
  * Format for date fields:
  *
  * - date: the format string (e.g., 'F j, Y' for WordPress default format like 'March 10, 2023')
- * - weekStartsOn: to specify the first day of the week (0 is Sunday).
+ * - weekStartsOn: to specify the first day of the week ('sunday', 'monday', etc.).
  *
  * If not provided, defaults to WordPress date format settings.
  */
 type DisplayFormatDate = {
 	date?: string;
-	weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+	weekStartsOn?:
+		| 'sunday'
+		| 'monday'
+		| 'tuesday'
+		| 'wednesday'
+		| 'thursday'
+		| 'friday'
+		| 'saturday';
 };
 
 export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {

packages/dataviews/src/utils/normalize-fields.ts

@@ -26,6 +26,7 @@ import {
 	SINGLE_SELECTION_OPERATORS,
 } from '../constants';
 import hasElements from './has-elements';
+import { numberToWeekStartsOn } from './week-starts-on';
 
 const getValueFromId =
 	( id: string ) =>
@@ -216,7 +217,9 @@ export default function normalizeFields< Item >(
 					field.type === 'date' &&
 					field.displayFormat?.weekStartsOn !== undefined
 						? field.displayFormat.weekStartsOn
-						: getSettings().l10n.startOfWeek,
+						: numberToWeekStartsOn(
+								getSettings().l10n.startOfWeek
+						  ),
 			},
 		};
 	} );

packages/dataviews/src/utils/week-starts-on.ts

@@ -0,0 +1,57 @@
+/**
+ * Converts a weekStartsOn string to a number (0-6).
+ *
+ * @param day - The day name ('sunday', 'monday', etc.)
+ * @return The corresponding number (0 for Sunday, 1 for Monday, etc.)
+ */
+export function weekStartsOnToNumber(
+	day:
+		| 'sunday'
+		| 'monday'
+		| 'tuesday'
+		| 'wednesday'
+		| 'thursday'
+		| 'friday'
+		| 'saturday'
+): 0 | 1 | 2 | 3 | 4 | 5 | 6 {
+	const mapping = {
+		sunday: 0,
+		monday: 1,
+		tuesday: 2,
+		wednesday: 3,
+		thursday: 4,
+		friday: 5,
+		saturday: 6,
+	} as const;
+
+	return mapping[ day ];
+}
+
+/**
+ * Converts a weekStartsOn number (0-6) to a string.
+ *
+ * @param day - The day number (0 for Sunday, 1 for Monday, etc.)
+ * @return The corresponding day name ('sunday', 'monday', etc.)
+ */
+export function numberToWeekStartsOn(
+	day: 0 | 1 | 2 | 3 | 4 | 5 | 6
+):
+	| 'sunday'
+	| 'monday'
+	| 'tuesday'
+	| 'wednesday'
+	| 'thursday'
+	| 'friday'
+	| 'saturday' {
+	const mapping = {
+		0: 'sunday',
+		1: 'monday',
+		2: 'tuesday',
+		3: 'wednesday',
+		4: 'thursday',
+		5: 'friday',
+		6: 'saturday',
+	} as const;
+
+	return mapping[ day ];
+}