@wordpress/dataviews 10.3.1-next.2f1c7c01b.0 → 10.4.1-next.dc3f6d3c1.0

package/src/types/field-api.ts

@@ -308,9 +308,36 @@ export type Field< Item > = {
 	 * Used for editing operations to update field values.
 	 */
 	setValue?: ( args: { item: Item; value: any } ) => DeepPartial< Item >;
+
+	/**
+	 * Display format configuration for fields.
+	 */
+	format?: FormatDate;
 };
 
-export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
+/**
+ * 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 ('sunday', 'monday', etc.).
+ *
+ * If not provided, defaults to WordPress date format settings.
+ */
+type FormatDate = {
+	date?: string;
+	weekStartsOn?: DayString;
+};
+export type DayNumber = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type DayString =
+	| 'sunday'
+	| 'monday'
+	| 'tuesday'
+	| 'wednesday'
+	| 'thursday'
+	| 'friday'
+	| 'saturday';
+
+type NormalizedFieldBase< Item > = Omit< Field< Item >, 'Edit' > & {
 	label: string;
 	header: string | ReactElement;
 	getValue: ( args: { item: Item } ) => any;
@@ -326,6 +353,20 @@ export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
 	readOnly: boolean;
 };
 
+type NormalizedFieldDate< Item > = NormalizedFieldBase< Item > & {
+	type: 'date';
+	format: Required< FormatDate >;
+};
+
+type NormalizedFieldGeneric< Item > = NormalizedFieldBase< Item > & {
+	type?: Exclude< FieldType, 'date' >;
+	format: {};
+};
+
+export type NormalizedField< Item > =
+	| NormalizedFieldGeneric< Item >
+	| NormalizedFieldDate< Item >;
+
 /**
  * A collection of dataview fields for a data type.
  */

package/src/utils/normalize-fields.ts

@@ -3,11 +3,17 @@
  */
 import type { FunctionComponent } from 'react';
 
+/**
+ * WordPress dependencies
+ */
+import { getSettings } from '@wordpress/date';
+
 /**
  * Internal dependencies
  */
 import getFieldTypeDefinition from '../field-types';
 import type {
+	DayString,
 	DataViewRenderFieldProps,
 	Field,
 	FieldTypeDefinition,
@@ -21,6 +27,7 @@ import {
 	SINGLE_SELECTION_OPERATORS,
 } from '../constants';
 import hasElements from './has-elements';
+import { numberToWeekStartsOn, DAYS_OF_WEEK } from './week-starts-on';
 
 const getValueFromId =
 	( id: string ) =>
@@ -182,8 +189,22 @@ export default function normalizeFields< Item >(
 
 		const filterBy = getFilterBy( field, fieldTypeDefinition );
 
-		return {
-			...field,
+		/**
+		 * NormalizedField is a discriminated union type: the shape of the format property
+		 * depends on the type property. For example, for the 'date' type, the format
+		 * contains date or weekStartsOn — which are not valid for other types.
+		 *
+		 * Being type and format interdependent, we need to write the code
+		 * in a way that TypeScript is able to statically infer the types.
+		 * That's why we have a return branch for every item in the union type.
+		 *
+		 * See a longer explanation with examples at
+		 * https://github.com/WordPress/gutenberg/pull/72999#discussion_r2523145453
+		 */
+		const { type, ...fieldWithoutType } = field;
+
+		const baseField = {
+			...fieldWithoutType,
 			label: field.label || field.id,
 			header: field.header || field.label || field.id,
 			getValue,
@@ -200,6 +221,34 @@ export default function normalizeFields< Item >(
 				true,
 			filterBy,
 			readOnly: field.readOnly ?? fieldTypeDefinition.readOnly ?? false,
+			format: {},
 		};
+
+		if ( field.type === 'date' ) {
+			const format = {
+				date:
+					field.format?.date !== undefined &&
+					typeof field.format.date === 'string'
+						? field.format.date
+						: getSettings().formats.date,
+				weekStartsOn:
+					field.format?.weekStartsOn !== undefined &&
+					DAYS_OF_WEEK.includes(
+						field.format?.weekStartsOn as DayString
+					)
+						? field.format.weekStartsOn
+						: numberToWeekStartsOn(
+								getSettings().l10n.startOfWeek
+						  ),
+			};
+
+			return {
+				...baseField,
+				type: 'date',
+				format,
+			};
+		}
+
+		return { ...baseField, type: field.type, format: {} };
 	} );
 }

package/src/utils/week-starts-on.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal dependencies
+ */
+import type { DayNumber, DayString } from '../types/field-api';
+
+export const DAYS_OF_WEEK: DayString[] = [
+	'sunday',
+	'monday',
+	'tuesday',
+	'wednesday',
+	'thursday',
+	'friday',
+	'saturday',
+];
+const DEFAULT_DAY_STRING = 'sunday';
+const DEFAULT_DAY_NUMBER = 0;
+
+/**
+ * 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: DayString ): DayNumber {
+	const index = DAYS_OF_WEEK.indexOf( day );
+	if ( index === -1 ) {
+		return DEFAULT_DAY_NUMBER;
+	}
+
+	return index as DayNumber;
+}
+
+/**
+ * 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: DayNumber ): DayString {
+	const result = DAYS_OF_WEEK[ day ];
+	if ( result === undefined ) {
+		return DEFAULT_DAY_STRING;
+	}
+
+	return result;
+}