Document the new Date Time property editors

17/umbraco-cms/SUMMARY.md

@@ -56,7 +56,11 @@
       * [Content Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/content-picker.md)
       * [Document Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/document-picker.md)
       * [DateTime](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md)
-      * [Date](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date.md)
+      * [Date Time Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md)
+        * [Date Only](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md)
+        * [Time Only](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/time-only.md)
+        * [Date Time (with Time Zone)](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-with-time-zone.md)
+        * [Date Time (Unspecified)](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md)
       * [Decimal](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/decimal.md)
       * [Email Address](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/email-address.md)
       * [Eye Dropper Color Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/eye-dropper-color-picker.md)

17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md

@@ -0,0 +1,16 @@
+# Date Time Editors
+
+The Date Time property editors provide interfaces for selecting dates, times, and time zones. Each editor is designed for specific use cases, from basic date selection to comprehensive date/time handling with time zone support.
+
+{% hint style="info" %}
+These property editors supersede the [Date Time](../date-time.md) property editor, offering more focused functionality and specific return types (like `DateOnly`, `TimeOnly`, `DateTime`, or `DateTimeOffset`). You can switch from the legacy Date Time editor by changing your properties to use the new editors.
+{% endhint %}
+
+Umbraco CMS currently ships with four Date Time editors:
+
+| Editor | Purpose | Use Cases | Return Type | Preview |
+|--------|---------|-----------|-------------|---------|
+| [Date Only](date-only.md) | Date selection | Birthdays, deadlines, event dates | `DateOnly` | ![Date Only editor](./images/date-only-editor.png) |
+| [Time Only](time-only.md) | Time selection | Business hours, schedules, time-based events | `TimeOnly` | ![Time Only editor](./images/time-only-time-format-hhmm.png) |
+| [Date Time (with Time Zone)](date-time-with-time-zone.md) | Full date, time, and timezone support | International apps, timezone-aware scheduling | `DateTimeOffset` | ![Date Time with Time Zone editor](./images/date-time-with-time-zone-editor.png) |
+| [Date Time (Unspecified)](date-time-unspecified.md) | Date and time without a defined time zone | Local events, compatibility with [Date Time](../date-time.md) | `DateTime` | ![Date Time Unspecified editor](./images/date-time-time-format-hhmm.png) |

17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md

@@ -0,0 +1,110 @@
+# Date Only
+
+`Schema Alias: Umbraco.DateOnly`
+
+`UI Alias: Umb.PropertyEditorUi.DateOnlyPicker`
+
+`Returns: DateOnly?`
+
+The Date Only property editor provides an interface for selecting dates without time or time zone information. It focuses purely on date selection and returns `DateOnly` values.
+
+## Configuration
+You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface.
+
+To set up a property using this editor, create a new *Data Type* and select **Date Only** from the list of available property editors.
+
+This editor has no configuration options.
+
+## Editing experience
+
+### Adding or editing a value
+
+You will be presented with a date input.
+
+![Date Only property editor interface](./images/date-only-editor-open.png)
+
+## Rendering
+
+The value returned will have the type `DateOnly?`.
+
+### Display the value
+
+With Models Builder:
+```csharp
+@Model.EventDate
+```
+
+Without Models Builder:
+```csharp
+@Model.Value<DateOnly?>("eventDate")
+```
+
+## Add values programmatically
+
+This property editor stores values as a JSON object. The object contains the date as an ISO 8601 string with midnight time and UTC offset.
+
+### Storage format
+
+The property editor stores values in this JSON format:
+```json
+{
+    "date": "2025-01-01T00:00:00+00:00"
+}
+```
+
+The property editor handles date-only values. Time is set to 00:00:00 and offset to +00:00 for storage consistency. These time components are ignored in Date Only context.
+
+1. Create a C# model that matches the JSON schema.
+
+    ```csharp
+    using System.Text.Json.Serialization;
+
+    namespace UmbracoProject;
+
+    public class DateOnlyValue
+    {
+        /// <summary>
+        /// The date value, represented as a <see cref="DateTimeOffset"/> for storage compatibility.
+        /// </summary>
+        [JsonPropertyName("date")]
+        public DateTimeOffset Date { get; init; }
+    }
+    ```
+2. Convert your existing date value to `DateTimeOffset` for storage.
+
+   If you have a `DateOnly`:
+   ```csharp
+   DateOnly dateOnly = DateOnly.FromDateTime(DateTime.Today); // Your existing DateOnly value
+   DateTimeOffset dateTimeOffset = dateOnly.ToDateTime(TimeOnly.MinValue);
+   ```
+
+   If you have a `DateTime`:
+   ```csharp
+   DateTime dateTime = DateTime.Today; // Your existing DateTime value
+   DateOnly dateOnly = DateOnly.FromDateTime(dateTime);
+   DateTimeOffset dateTimeOffset = dateOnly.ToDateTime(TimeOnly.MinValue);
+   ```
+
+3. Create an instance of the class with the `DateTimeOffset` value.
+    ```csharp
+    DateOnlyValue value = new DateOnlyValue
+    {
+        Date = dateTimeOffset
+    };
+    ```
+
+4. Inject the `IJsonSerializer` and use it to serialize the object.
+   ```csharp
+   string jsonValue = _jsonSerializer.Serialize(value);
+   ```
+
+5. Inject the `IContentService` to retrieve and update the value of a property of the desired content item.
+   ```csharp
+   IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");
+
+   // Set the value of the property with alias 'eventDate'. 
+   content.SetValue("eventDate", jsonValue);
+
+   // Save the change
+   _contentService.Save(content);
+   ```

17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md

@@ -0,0 +1,115 @@
+# Date Time (Unspecified)
+
+`Schema Alias: Umbraco.DateTimeUnspecified`
+
+`UI Alias: Umb.PropertyEditorUi.DateTimePicker`
+
+`Returns: DateTime?`
+
+The Date Time (Unspecified) property editor provides a comprehensive interface for selecting dates and times. It excludes time zone information.
+
+## Configuration
+You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface.
+
+To set up a property using this editor, create a new *Data Type* and select **Date Time (unspecified)** from the list of available property editors.
+
+You will see the configuration options as shown below.
+
+![Date Time Unspecified property editor configuration](./images/date-time-unspecified-property-editor-config.png)
+
+- **Time format** - Specifies the level of precision for time values shown and stored by the editor.
+
+### Time format
+
+- **HH:mm** - Displays hours and minutes (e.g., `14:30`).  
+Suitable for most general use cases.  
+![Date Time Unspecified property editor showing time format in HH:mm format (hours and minutes only)](./images/date-time-time-format-hhmm.png)
+- **HH:mm:ss** - Displays hours, minutes, and seconds (e.g., `14:30:45`).  
+Use this when you need more precise timing.  
+![Date Time Unspecified property editor showing time format in HH:mm:ss format (hours, minutes, and seconds)](./images/date-time-time-format-hhmmss.png)
+
+## Editing experience
+
+### Adding or editing a value
+
+You will be presented with a date and time input. This editor focuses only on the date and time components, unlike the time zone version.
+
+![Date Time Unspecified property editor interface](./images/date-time-unspecified-editor.png)
+
+## Rendering
+
+The value returned will have the type `DateTime?`.
+
+### Display the value
+
+With Models Builder:
+```csharp
+@Model.EventDateTime.Value
+```
+
+Without Models Builder:
+```csharp
+@Model.Value<DateTime?>("eventDateTime")
+```
+
+## Add values programmatically
+
+This property editor stores values as a JSON object. The object contains the date as an ISO 8601 string.
+
+### Storage format
+
+The property editor stores values in this JSON format:
+```json
+{
+    "date": "2025-01-01T00:00:00+00:00"
+}
+```
+
+The property editor handles unspecified date times with no time zone information. The value is stored with offset +00:00 for consistency. The offset is ignored unless you replace this editor with the Date Time (with time zone) version.
+
+1. Create a C# model that matches the JSON schema.
+
+    ```csharp
+    using System.Text.Json.Serialization;
+
+    namespace UmbracoProject;
+
+    public class DateTimeUnspecified
+    {
+        /// <summary>
+        /// The date and time value, represented as a <see cref="DateTimeOffset"/> for storage compatibility.
+        /// </summary>
+        [JsonPropertyName("date")]
+        public DateTimeOffset Date { get; init; }
+    }
+    ```
+
+2. Convert your existing DateTime value to `DateTimeOffset` for storage.
+   ```csharp
+   DateTime dateTime = DateTime.Now; // Your existing DateTime value
+   DateTimeOffset dateTimeOffset = dateTime; // Explicit conversion
+   ```
+
+3. Create an instance of the class with the `DateTimeOffset` value.
+   ```csharp
+   var value = new DateTimeUnspecified
+   {
+       Date = dateTimeOffset
+   };
+   ```
+
+4. Inject the `IJsonSerializer` and use it to serialize the object.
+   ```csharp
+   string jsonValue = _jsonSerializer.Serialize(value);
+   ```
+
+5. Inject the `IContentService` to retrieve and update the value of a property of the desired content item.
+   ```csharp
+   IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found");
+
+   // Set the value of the property with alias 'eventDateTime'. 
+   content.SetValue("eventDateTime", jsonValue);
+
+   // Save the change
+   _contentService.Save(content);
+   ```