Merge pull request #181 from wp-graphql/feat/161-update-datetime-field-descriptions

feat: update docs Date fields to link to the RFC3339 spec

Author: jasonbahl

src/FieldConfig.php

@@ -135,6 +135,9 @@ protected function is_supported_field_type(): bool {
 	 */
 	public function get_field_description(): string {
 
+		$graphql_field_type = $this->get_graphql_field_type();
+		$field_type_config  = ( $graphql_field_type instanceof AcfGraphQLFieldType ) ? $graphql_field_type->get_config() : [];
+
 		// Use the explicit graphql_description, if set
 		if ( ! empty( $this->acf_field['graphql_description'] ) ) {
 			$description = $this->acf_field['graphql_description'];
@@ -153,6 +156,14 @@ public function get_field_description(): string {
 			);
 		}
 
+		if ( isset( $field_type_config['graphql_description_after'] ) ) {
+			if ( is_callable( $field_type_config['graphql_description_after'] ) ) {
+				$description .= ' ' . call_user_func( $field_type_config['graphql_description_after'], $this );
+			} else {
+				$description .= ' ' . $field_type_config['graphql_description_after'];
+			}
+		}
+
 		return $description;
 	}
 

src/FieldType/DatePicker.php

@@ -12,8 +12,16 @@ public static function register_field_type(): void {
 		register_graphql_acf_field_type(
 			'date_picker',
 			[
-				'graphql_type' => 'String',
-				'resolve'      => static function ( $root, $args, $context, $info, $field_type, FieldConfig $field_config ) {
+				'graphql_type'              => 'String',
+				// Apply a description to be appended to the field description.
+				// @todo: consider removing when CustomScalar types are supported along with the @specifiedBy directive
+				'graphql_description_after' => static function ( FieldConfig $field_config ) {
+					$field_type = $field_config->get_acf_field()['type'] ?? null;
+
+					// translators: The $s is the name of the acf field type that is returning a date string according to the RFC3339 spec.
+					return '(' . sprintf( __( 'ACF Fields of the %s type return a date string according to the RFC3339 spec: https://datatracker.ietf.org/doc/html/rfc3339.', 'wpgraphql-acf' ), $field_type ) . ')';
+				},
+				'resolve'                   => static function ( $root, $args, $context, $info, $field_type, FieldConfig $field_config ) {
 					$value = $field_config->resolve_field( $root, $args, $context, $info );
 
 					if ( empty( $value ) ) {

src/FieldType/DateTimePicker.php

@@ -13,8 +13,16 @@ public static function register_field_type(): void {
 		register_graphql_acf_field_type(
 			'date_time_picker',
 			[
-				'graphql_type' => 'String',
-				'resolve'      => static function ( $root, $args, $context, $info, $field_type, FieldConfig $field_config ) {
+				'graphql_type'              => 'String',
+				// Apply a description to be appended to the field description.
+				// @todo: consider removing when CustomScalar types are supported along with the @specifiedBy directive
+				'graphql_description_after' => static function ( FieldConfig $field_config ) {
+					$field_type = $field_config->get_acf_field()['type'] ?? null;
+
+					// translators: The $s is the name of the acf field type that is returning a date string according to the RFC3339 spec.
+					return '(' . sprintf( __( 'ACF Fields of the "%s" type return a date string according to the RFC3339 spec: https://datatracker.ietf.org/doc/html/rfc3339.', 'wpgraphql-acf' ), $field_type ) . ')';
+				},
+				'resolve'                   => static function ( $root, $args, $context, $info, $field_type, FieldConfig $field_config ) {
 					$value = $field_config->resolve_field( $root, $args, $context, $info );
 
 					if ( empty( $value ) ) {

src/FieldType/FlexibleContent.php

@@ -73,7 +73,9 @@ static function ( $field ) use ( $layout ) {
 								)
 							);
 
-							$layout['sub_fields'] = array_merge( $sub_fields, $layout['sub_fields'] );
+							$layout_sub_fields = ! empty( $layout['sub_fields'] ) && is_array( $layout['sub_fields'] ) ? $layout['sub_fields'] : [];
+
+							$layout['sub_fields'] = array_merge( $sub_fields, $layout_sub_fields );
 
 							$layouts[] = $layout;
 						}

src/ThirdParty/AcfExtended/AcfExtended.php

@@ -339,12 +339,12 @@ public function register_initial_types(): void {
 					'startDate' => [
 						// @todo: DATETIME Scalar
 						'type'        => 'String',
-						'description' => __( 'The start date of a date range returned as an RFC 3339 time string', 'wpgraphql-acf' ),
+						'description' => __( 'The start date of a date range returned as an RFC 3339 time string (https://datatracker.ietf.org/doc/html/rfc3339)', 'wpgraphql-acf' ),
 					],
 					'endDate'   => [
 						// @todo: DATETIME Scalar
 						'type'        => 'String',
-						'description' => __( 'The start date of a date range RFC 3339 time string', 'wpgraphql-acf' ),
+						'description' => __( 'The start date of a date range RFC 3339 time string (https://datatracker.ietf.org/doc/html/rfc3339)', 'wpgraphql-acf' ),
 					],
 				],
 			]

tests/_support/WPUnit/AcfFieldTestCase.php

@@ -672,11 +672,14 @@ public function testFieldDescriptionUsesInstructionsIfGraphqlDescriptionNotProvi
 			// the instructions should be used for the description
 			// if "graphql_description" is not provided
 			$this->expectedNode( '__type.fields', [
-				'name' => $this->get_formatted_field_name(),
-				'description' => $instructions
+				$this->expectedField( 'name', $this->get_formatted_field_name() ),
+				$this->expectedField( 'description', self::NOT_NULL ),
 			]),
+
 		] );
 
+		$this->assertStringContainsString( $instructions, $actual['data']['__type']['fields'][0]['description'] );
+
 		// remove the local field
 		acf_remove_local_field( $field_key );
 
@@ -720,11 +723,14 @@ public function testFieldDescriptionUsesGraphqlDescriptionIfProvided(): void {
 			// the instructions should be used for the description
 			// if "graphql_description" is not provided
 			$this->expectedNode( '__type.fields', [
-				'name' => $this->get_formatted_field_name(),
-				'description' => $graphql_description
+				$this->expectedField( 'name', $this->get_formatted_field_name() ),
+				$this->expectedField( 'description', self::NOT_NULL ),
 			]),
 		] );
 
+		$this->assertStringContainsString( $graphql_description, $actual['data']['__type']['fields'][0]['description'] );
+
+
 		// remove the local field
 		acf_remove_local_field( $field_key );