From 20c819ee634df5814a5a1cb57873226c3143effc Mon Sep 17 00:00:00 2001
From: mricoul <mricoul@beapi.fr>
Date: Fri, 14 Aug 2026 14:25:18 +0200
Subject: [PATCH] feat(Datetime): add Datetime helper

---
 functions.php                       |  1 +
 inc/Helpers/Formatting/Datetime.php | 86 +++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 inc/Helpers/Formatting/Datetime.php

diff --git a/functions.php b/functions.php
index 1793228..1497288 100644
--- a/functions.php
+++ b/functions.php
@@ -24,6 +24,7 @@ function () {
 );
 
 require_once __DIR__ . '/inc/Helpers/Svg.php';
+require_once __DIR__ . '/inc/Helpers/Formatting/Datetime.php';
 require_once __DIR__ . '/inc/Helpers/Formatting/Escape.php';
 require_once __DIR__ . '/inc/Helpers/Formatting/Image.php';
 require_once __DIR__ . '/inc/Helpers/Formatting/Link.php';
diff --git a/inc/Helpers/Formatting/Datetime.php b/inc/Helpers/Formatting/Datetime.php
new file mode 100644
index 0000000..bd8cb4a
--- /dev/null
+++ b/inc/Helpers/Formatting/Datetime.php
@@ -0,0 +1,86 @@
+<?php
+namespace BEA\Theme\Framework\Helpers\Formatting\Datetime;
+
+/**
+ * Echo accessible <time> markup.
+ *
+ * @usage BEA\Theme\Framework\Helpers\Formatting\Datetime\the_datetime( get_the_date( 'd.m.Y' ), [ 'datetime' => get_the_date( 'Y-m-d' ), 'class' => 'crd__date' ] );
+ *
+ * @param string $display_date Formatted date string shown to users.
+ * @param array  $settings {
+ *     Optional. Settings for the datetime markup.
+ *
+ *     @type string $before           Markup before the <time> element. Default empty.
+ *     @type string $after            Markup after the <time> element. Default empty.
+ *     @type string $class            CSS class on the <time> element. Default empty.
+ *     @type string $label            Screen-reader label prepended to the date. Default "Published on".
+ *     @type string $datetime         Value for the datetime attribute. Required.
+ *     @type bool   $show_label       Whether to output the screen-reader label. Default true.
+ * }
+ *
+ * @return void
+ */
+function the_datetime( string $display_date, array $settings = [] ): void {
+	echo get_the_datetime( $display_date, $settings ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+}
+
+/**
+ * Build accessible <time> markup.
+ *
+ * @usage BEA\Theme\Framework\Helpers\Formatting\Datetime\get_the_datetime( get_the_date( 'd.m.Y' ), [ 'datetime' => get_the_date( 'Y-m-d' ), 'class' => 'crd__date' ] );
+ *
+ * @param string $display_date Formatted date string shown to users.
+ * @param array  $settings {
+ *     Optional. Settings for the datetime markup.
+ *
+ *     @type string $before           Markup before the <time> element. Default empty.
+ *     @type string $after            Markup after the <time> element. Default empty.
+ *     @type string $class            CSS class on the <time> element. Default empty.
+ *     @type string $label            Screen-reader label prepended to the date. Default "Published on".
+ *     @type string $datetime         Value for the datetime attribute. Required.
+ *     @type bool   $show_label       Whether to output the screen-reader label. Default true.
+ * }
+ *
+ * @return string
+ */
+function get_the_datetime( string $display_date, array $settings = [] ): string {
+	$settings = wp_parse_args(
+		$settings,
+		[
+			'before'     => '',
+			'after'      => '',
+			'class'      => '',
+			'label'      => __( 'Published on', 'beapi-blocks-theme' ),
+			'datetime'   => '',
+			'show_label' => true,
+		]
+	);
+
+	if ( empty( $display_date ) || empty( $settings['datetime'] ) ) {
+		return '';
+	}
+
+	$settings = apply_filters( 'bea_theme_framework_datetime_settings', $settings, $display_date, $settings['datetime'] );
+
+	$class_attr = $settings['class'] ? sprintf( ' class="%s"', esc_attr( $settings['class'] ) ) : '';
+
+	$label_markup = '';
+	if ( $settings['show_label'] && ! empty( $settings['label'] ) ) {
+		$label_markup = sprintf(
+			'<span class="sr-only">%s </span>',
+			esc_html( $settings['label'] )
+		);
+	}
+
+	$datetime_markup = sprintf(
+		'<time%s datetime="%s">%s%s</time>',
+		$class_attr,
+		esc_attr( $settings['datetime'] ),
+		$label_markup,
+		esc_html( $display_date )
+	);
+
+	$datetime_markup = apply_filters( 'bea_theme_framework_datetime_markup', $datetime_markup, $settings, $display_date, $settings['datetime'] );
+
+	return $settings['before'] . $datetime_markup . $settings['after'];
+}