Add datetime field support

Author: ajaydsouza

README.md

@@ -111,7 +111,7 @@ Implement `get_registered_settings()` in your copied `Settings` class. Fields ar
 ),
 ```
 
-26 field types are available — text, url, csv, numbercsv, postids, color, number, textarea, css, html, wysiwyg, checkbox, toggle, multicheck, radio, radiodesc, select, posttypes, taxonomies, thumbsizes, file, password, sensitive, repeater, header, and descriptive_text. See the [field types reference](https://webberzone.github.io/Settings_API/docs/02-wzsa-core-classes/field-types-reference/).
+27 field types are available — text, url, csv, numbercsv, postids, datetime, color, number, textarea, css, html, wysiwyg, checkbox, toggle, multicheck, radio, radiodesc, select, posttypes, taxonomies, thumbsizes, file, password, sensitive, repeater, header, and descriptive_text. See the [field types reference](https://webberzone.github.io/Settings_API/docs/02-wzsa-core-classes/field-types-reference/).
 
 ### 5. Instantiate the Settings API
 

docs/02-wzsa-core-classes/field-types-reference.md

@@ -22,6 +22,7 @@ An unrecognized `type` falls through to `callback_missing()`, which prints a not
 | `csv` | Single-line input | A comma-separated list of strings; each item is trimmed. |
 | `numbercsv` | Single-line input | A comma-separated list of numbers. |
 | `postids` | Single-line input | A comma-separated list of post IDs. Renders as `text`. |
+| `datetime` | Local date/time input | Renders as `datetime-local` and accepts `Y-m-dTH:i` values in the site's timezone. |
 | `password` | Password input | Sanitized with `sanitize_text_field()`. Use `sensitive` for API keys. |
 | `sensitive` | Password-style input | Value is encrypted at rest and masked in the UI, showing only the last four characters. |
 | `number` | Number input | Uses `min`, `max`, and `step`. |

docs/02-wzsa-core-classes/sanitization-reference.md

@@ -34,6 +34,7 @@ Every callback receives the field configuration as its second argument, which is
 | `sanitize_csv_field()` | `csv` | Sanitizes the string, then trims each comma-separated item. |
 | `sanitize_numbercsv_field()` | `numbercsv` | Casts each item with `absint()` and drops empties. |
 | `sanitize_postids_field()` | `postids` | Casts each item with `absint()` and drops IDs that no longer resolve to a post. |
+| `sanitize_datetime_field()` | `datetime` | Accepts strict `Y-m-dTH:i` values and rejects malformed, calendar-invalid, and non-existent local times caused by daylight-saving transitions. |
 | `sanitize_checkbox_field()` | `checkbox`, `toggle` | Returns `1` or `0`. The hidden `-1` companion input is what makes an unchecked box save as `0`. |
 | `sanitize_multicheck_field()` | `multicheck` | Returns a comma-separated list of the checked keys; `-1` means nothing checked. |
 | `sanitize_posttypes_field()` | `posttypes` | Delegates to `sanitize_multicheck_field()`. |

docs/index.html

@@ -24,7 +24,7 @@ <h3>Settings_API reference</h3>
   </a>
   <a class="doc-card" href="{{ '/docs/02-wzsa-core-classes/field-types-reference/' | relative_url }}">
     <h3>Field types reference</h3>
-    <p>All 26 field types and the arguments each one understands.</p>
+    <p>All 27 field types and the arguments each one understands.</p>
   </a>
   <a class="doc-card" href="{{ '/docs/02-wzsa-core-classes/options-api-reference/' | relative_url }}">
     <h3>Options_API reference</h3>

settings/class-settings-form.php

@@ -553,6 +553,34 @@ public function callback_text( $args ) {
 		echo wp_kses( apply_filters( $this->prefix . '_after_setting_output', $html, $args ), $this->get_allowed_html() ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.DynamicHooknameFound
 	}
 
+	/**
+	 * Display local date/time fields.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @param array $args Field arguments.
+	 */
+	public function callback_datetime( $args ) {
+		$value            = $this->get_field_value( $args );
+		$class            = $this->get_field_class( $args );
+		$attributes       = $this->get_boolean_attributes( $args ) . $this->build_field_attributes( $args );
+		$placeholder      = $this->get_placeholder_attribute( $args );
+		$field_attributes = $this->get_field_attributes( $args );
+
+		$html  = sprintf(
+			'<input type="datetime-local" id="%1$s" name="%2$s" class="%3$s" value="%4$s" step="60" %5$s %6$s />',
+			$field_attributes['field_id'],
+			$field_attributes['field_name'],
+			$class . ' regular-text',
+			esc_attr( stripslashes( (string) $value ) ),
+			$attributes,
+			$placeholder
+		);
+		$html .= $this->get_field_description( $args );
+
+		echo wp_kses( apply_filters( $this->prefix . '_after_setting_output', $html, $args ), $this->get_allowed_html() ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.DynamicHooknameFound
+	}
+
 	/**
 	 * Display url fields.
 	 *

settings/class-settings-sanitize.php

@@ -109,6 +109,32 @@ public function sanitize_text_field( $value ) {
 		return $this->sanitize_textarea_field( $value );
 	}
 
+	/**
+	 * Sanitize site-local date/time fields.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @param string $value The date/time value.
+	 * @return string Sanitized date/time, or an empty string when invalid.
+	 */
+	public function sanitize_datetime_field( $value ) {
+		$value  = trim( sanitize_text_field( wp_unslash( (string) $value ) ), " \t\n\r\0\x0B" );
+		$format = '!Y-m-d\\TH:i';
+		$utc    = \DateTimeImmutable::createFromFormat( $format, $value, new \DateTimeZone( 'UTC' ) );
+		$errors = \DateTimeImmutable::getLastErrors();
+
+		if ( false === $utc || ( false !== $errors && ( $errors['warning_count'] > 0 || $errors['error_count'] > 0 ) ) || $utc->format( 'Y-m-d\\TH:i' ) !== $value ) {
+			return '';
+		}
+
+		$local = \DateTimeImmutable::createFromFormat( $format, $value, wp_timezone() );
+		if ( false === $local || $local->format( 'Y-m-d\\TH:i' ) !== $value ) {
+			return '';
+		}
+
+		return $value;
+	}
+
 	/**
 	 * Sanitize number fields
 	 *