From ea3004c96bc0ed907d4f16e8e216dca71d6ccf0b Mon Sep 17 00:00:00 2001
From: Andy Scherzinger <info@andy-scherzinger.de>
Date: Sat, 7 Nov 2026 15:50:14 +0100
Subject: [PATCH] feat(conditional): allow branches on date and time questions

A date or time question opens a branch when the answer lies within the
range of a condition, its bounds included. Bounds are stored in the
answer format (YYYY-MM-DD, HH:mm) and are optional. Deprecated datetime
questions get the same conditions.

The code comes from the original pull request #3123 by Micke Nordin
and TimedIn, with the review fixes applied.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
---
 docs/DataStructure.md                         |  17 +-
 lib/Constants.php                             |   4 +
 lib/Service/SubmissionService.php             |  30 ++++
 .../Conditional/BranchConditionEditor.vue     | 162 ++++++++++++++++++
 src/components/Questions/QuestionDate.vue     |   1 +
 src/utils/Branches.ts                         |  23 +++
 tests/Unit/Service/FormsServiceTest.php       |  10 ++
 tests/Unit/Service/SubmissionServiceTest.php  |  44 +++++
 8 files changed, 290 insertions(+), 1 deletion(-)

diff --git a/docs/DataStructure.md b/docs/DataStructure.md
index 4f02f7b48..28946a8a9 100644
--- a/docs/DataStructure.md
+++ b/docs/DataStructure.md
@@ -270,7 +270,7 @@ Optional extra settings for some [Question Types](#question-types)
 | `columns`               | `grid`                                         | Array            | -                                           | Array of column identifiers / labels for grid questions                     |
 | `rows`                  | `grid`                                         | Array            | -                                           | Array of row identifiers / labels for grid questions                        |
 | `questionType`          | `grid`                                         | String           | `checkbox`, `number`, `radio`               | Type of cell for grid questions (checkbox, numeric input, or radio)         |
-| `branches`              | `dropdown`, `multiple`, `multiple_unique`      | Array            | Array of [Branch objects](#branch-object)   | Branches with follow-up questions, see [Follow-up Questions](#follow-up-questions) |
+| `branches`              | see [Follow-up Questions](#follow-up-questions) | Array            | Array of [Branch objects](#branch-object)   | Branches with follow-up questions, see [Follow-up Questions](#follow-up-questions) |
 
 ### Option Types
 
@@ -304,6 +304,9 @@ Follow-up questions (subquestions) are questions of their own with additional pr
 | `multiple_unique` | `option_selected` | Radio buttons - the selected option |
 | `dropdown`        | `option_selected` | Dropdown - the selected option      |
 | `multiple`        | `options_combination` | Checkboxes - all options of a combination |
+| `date`            | `date_range`      | Date - range including its bounds (`YYYY-MM-DD`) |
+| `datetime`        | `date_range`      | Deprecated date and time (`YYYY-MM-DD HH:mm`) |
+| `time`            | `date_range`      | Time - range including its bounds (`HH:mm`) |
 
 A branch is shown when any of its conditions matches. Several branches can be shown at once.
 
@@ -353,6 +356,18 @@ Conditions determine when a branch is activated. The structure depends on the ty
 
 All options in `optionIds` must be selected for the condition to match.
 
+#### date_range (for date, datetime, time)
+
+```json
+{ "type": "date_range", "min": "2024-01-01", "max": "2024-12-31" }
+```
+
+```json
+{ "type": "date_range", "min": "09:00", "max": "17:00" }
+```
+
+`min` and `max` use the answer format of the question type and are optional.
+
 ### Example
 
 A dropdown question with a branch of follow-up questions:
diff --git a/lib/Constants.php b/lib/Constants.php
index 629ddcc6e..e46b83143 100644
--- a/lib/Constants.php
+++ b/lib/Constants.php
@@ -244,6 +244,7 @@ class Constants {
 	 */
 	public const CONDITION_TYPE_OPTION_SELECTED = 'option_selected';
 	public const CONDITION_TYPE_OPTIONS_COMBINATION = 'options_combination';
+	public const CONDITION_TYPE_DATE_RANGE = 'date_range';
 
 	/**
 	 * Question types that can have branches with follow-up questions in `extraSettings.branches`,
@@ -255,6 +256,9 @@ class Constants {
 		self::ANSWER_TYPE_MULTIPLEUNIQUE => [self::CONDITION_TYPE_OPTION_SELECTED],
 		self::ANSWER_TYPE_DROPDOWN => [self::CONDITION_TYPE_OPTION_SELECTED],
 		self::ANSWER_TYPE_MULTIPLE => [self::CONDITION_TYPE_OPTIONS_COMBINATION],
+		self::ANSWER_TYPE_DATE => [self::CONDITION_TYPE_DATE_RANGE],
+		self::ANSWER_TYPE_DATETIME => [self::CONDITION_TYPE_DATE_RANGE],
+		self::ANSWER_TYPE_TIME => [self::CONDITION_TYPE_DATE_RANGE],
 	];
 
 	/**
diff --git a/lib/Service/SubmissionService.php b/lib/Service/SubmissionService.php
index 288c4234c..86568ec4d 100644
--- a/lib/Service/SubmissionService.php
+++ b/lib/Service/SubmissionService.php
@@ -1077,6 +1077,36 @@ private function evaluateBranchConditions(string $triggerType, array $triggerAns
 					}
 				}
 				return false;
+			case Constants::ANSWER_TYPE_DATE:
+			case Constants::ANSWER_TYPE_DATETIME:
+			case Constants::ANSWER_TYPE_TIME:
+				// Date range conditions
+				$dateValue = $triggerAnswer[0] ?? '';
+				if (empty($dateValue)) {
+					return false;
+				}
+				$format = Constants::ANSWER_PHPDATETIME_FORMAT[$triggerType] ?? 'Y-m-d';
+				$date = \DateTime::createFromFormat('!' . $format, $dateValue);
+				if (!$date) {
+					return false;
+				}
+
+				foreach ($conditions as $condition) {
+					$min = isset($condition['min']) ? \DateTime::createFromFormat('!' . $format, $condition['min']) : null;
+					$max = isset($condition['max']) ? \DateTime::createFromFormat('!' . $format, $condition['max']) : null;
+
+					$inRange = true;
+					if ($min && $date < $min) {
+						$inRange = false;
+					}
+					if ($max && $date > $max) {
+						$inRange = false;
+					}
+					if ($inRange) {
+						return true;
+					}
+				}
+				return false;
 			default:
 				return false;
 		}
diff --git a/src/components/Conditional/BranchConditionEditor.vue b/src/components/Conditional/BranchConditionEditor.vue
index eb74f74b0..9b3b938a7 100644
--- a/src/components/Conditional/BranchConditionEditor.vue
+++ b/src/components/Conditional/BranchConditionEditor.vue
@@ -31,17 +31,39 @@
 					@update:modelValue="onMultipleOptionsSelect" />
 			</div>
 		</template>
+
+		<!-- Date/time-based conditions -->
+		<template v-else-if="isDateBasedTrigger">
+			<div class="condition-row">
+				<NcDateTimePicker
+					v-model="conditionDateMin"
+					:type="datePickerType"
+					:placeholder="t('forms', 'From')"
+					:ariaLabel="t('forms', 'From')"
+					class="condition-date-input" />
+				<span class="condition-range-separator">-</span>
+				<NcDateTimePicker
+					v-model="conditionDateMax"
+					:type="datePickerType"
+					:placeholder="t('forms', 'To')"
+					:ariaLabel="t('forms', 'To')"
+					class="condition-date-input" />
+			</div>
+		</template>
 	</div>
 </template>
 
 <script>
 import { t } from '@nextcloud/l10n'
+import moment from '@nextcloud/moment'
+import NcDateTimePicker from '@nextcloud/vue/components/NcDateTimePicker'
 import NcSelect from '@nextcloud/vue/components/NcSelect'
 
 export default {
 	name: 'BranchConditionEditor',
 
 	components: {
+		NcDateTimePicker,
 		NcSelect,
 	},
 
@@ -90,6 +112,13 @@ export default {
 			return ['multiple_unique', 'dropdown'].includes(this.triggerType)
 		},
 
+		/**
+		 * Check if trigger is date-based (date, datetime, time)
+		 */
+		isDateBasedTrigger() {
+			return ['date', 'datetime', 'time'].includes(this.triggerType)
+		},
+
 		/**
 		 * Label for option-based conditions
 		 */
@@ -132,9 +161,112 @@ export default {
 
 			return this.isSingleSelect ? selected[0] || null : selected
 		},
+
+		/**
+		 * Current condition type from branch
+		 */
+		conditionType: {
+			get() {
+				return this.branch.conditions?.[0]?.type || this.defaultConditionType
+			},
+
+			set(value) {
+				this.updateCondition({ type: value })
+			},
+		},
+
+		/**
+		 * Default condition type based on trigger
+		 */
+		defaultConditionType() {
+			if (this.isDateBasedTrigger) return 'date_range'
+			return null
+		},
+
+		/**
+		 * Storage format of date and time conditions, the same as for answers
+		 */
+		dateStorageFormat() {
+			return this.triggerType === 'time' ? 'HH:mm' : 'YYYY-MM-DD'
+		},
+
+		conditionDateMin: {
+			get() {
+				return this.parseDate(this.conditionMin)
+			},
+
+			set(value) {
+				this.conditionMin = this.formatDate(value)
+			},
+		},
+
+		conditionDateMax: {
+			get() {
+				return this.parseDate(this.conditionMax)
+			},
+
+			set(value) {
+				this.conditionMax = this.formatDate(value)
+			},
+		},
+
+		/**
+		 * Condition min value (for ranges)
+		 */
+		conditionMin: {
+			get() {
+				return this.branch.conditions?.[0]?.min || ''
+			},
+
+			set(value) {
+				this.updateCondition({ min: value })
+			},
+		},
+
+		/**
+		 * Condition max value (for ranges)
+		 */
+		conditionMax: {
+			get() {
+				return this.branch.conditions?.[0]?.max || ''
+			},
+
+			set(value) {
+				this.updateCondition({ max: value })
+			},
+		},
+
+		/**
+		 * Date picker type based on trigger type
+		 */
+		datePickerType() {
+			if (this.triggerType === 'time') return 'time'
+			if (this.triggerType === 'datetime') return 'datetime'
+			return 'date'
+		},
 	},
 
 	methods: {
+		/**
+		 * @param {string} value stored date or time
+		 * @return {Date|null} the date for the picker
+		 */
+		parseDate(value) {
+			if (!value) {
+				return null
+			}
+			const date = moment(value, this.dateStorageFormat, true)
+			return date.isValid() ? date.toDate() : null
+		},
+
+		/**
+		 * @param {Date|null} value date from the picker
+		 * @return {string} the date in the storage format of answers
+		 */
+		formatDate(value) {
+			return value ? moment(value).format(this.dateStorageFormat) : ''
+		},
+
 		/**
 		 * Handle single option selection (radio/dropdown)
 		 *
@@ -156,6 +288,21 @@ export default {
 			this.emitUpdate({ conditions })
 		},
 
+		/**
+		 * Update a condition property
+		 *
+		 * @param {object} updates The condition properties to update
+		 */
+		updateCondition(updates) {
+			const currentCondition = this.branch.conditions?.[0] || {}
+			const newCondition = {
+				...currentCondition,
+				type: this.conditionType,
+				...updates,
+			}
+			this.emitUpdate({ conditions: [newCondition] })
+		},
+
 		/**
 		 * Emit branch update
 		 *
@@ -179,4 +326,19 @@ export default {
 .condition-options {
 	max-width: 400px;
 }
+
+.condition-row {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	flex-wrap: wrap;
+}
+
+.condition-range-separator {
+	color: var(--color-text-maxcontrast);
+}
+
+.condition-date-input {
+	flex: 1;
+}
 </style>
diff --git a/src/components/Questions/QuestionDate.vue b/src/components/Questions/QuestionDate.vue
index 2c6671631..45e2711e6 100644
--- a/src/components/Questions/QuestionDate.vue
+++ b/src/components/Questions/QuestionDate.vue
@@ -105,6 +105,7 @@
 				@update:modelValue="onValueChange" />
 		</div>
 		<template #insert>
+			<slot name="branches" />
 			<slot name="insert" />
 		</template>
 	</Question>
diff --git a/src/utils/Branches.ts b/src/utils/Branches.ts
index 36d60384b..c179a4fa5 100644
--- a/src/utils/Branches.ts
+++ b/src/utils/Branches.ts
@@ -18,6 +18,9 @@ const BRANCH_MATCHERS: Record<string, BranchMatcher> = {
 	multiple_unique: matchOptionSelected,
 	dropdown: matchOptionSelected,
 	multiple: matchOptionsCombination,
+	date: matchDateRange,
+	datetime: matchDateRange,
+	time: matchDateRange,
 }
 
 /**
@@ -53,6 +56,26 @@ function matchOptionsCombination(
 	)
 }
 
+/**
+ * Dates and times match if they are within the range of any condition, including its bounds
+ *
+ * Answers and bounds use the same format (`YYYY-MM-DD`, `HH:mm`), so they compare as strings.
+ *
+ * @param conditions the conditions of the branch
+ * @param values the answer of the question
+ */
+function matchDateRange(
+	conditions: Record<string, unknown>[],
+	values: string[],
+): boolean {
+	const value = values[0]
+	return conditions.some(
+		(condition) =>
+			!(condition.min && value < String(condition.min))
+			&& !(condition.max && value > String(condition.max)),
+	)
+}
+
 /**
  * @param type the question type
  */
diff --git a/tests/Unit/Service/FormsServiceTest.php b/tests/Unit/Service/FormsServiceTest.php
index baef0627f..ea82f18a6 100644
--- a/tests/Unit/Service/FormsServiceTest.php
+++ b/tests/Unit/Service/FormsServiceTest.php
@@ -1925,6 +1925,16 @@ public static function dataAreExtraSettingsValid() {
 				'questionType' => Constants::ANSWER_TYPE_MULTIPLE,
 				'expected' => false
 			],
+			'valid-branches-date-range' => [
+				'extraSettings' => ['branches' => [['id' => 'branch-1', 'conditions' => [['type' => 'date_range', 'min' => '2024-01-01', 'max' => '2024-12-31']]]]],
+				'questionType' => Constants::ANSWER_TYPE_DATE,
+				'expected' => true
+			],
+			'valid-branches-time-range' => [
+				'extraSettings' => ['branches' => [['id' => 'branch-1', 'conditions' => [['type' => 'date_range', 'min' => '08:00', 'max' => '12:00']]]]],
+				'questionType' => Constants::ANSWER_TYPE_TIME,
+				'expected' => true
+			],
 			'valid-branches-with-own-settings' => [
 				'extraSettings' => ['shuffleOptions' => true, 'branches' => [['id' => 'branch-1', 'conditions' => [['type' => 'option_selected', 'optionId' => 1]]]]],
 				'questionType' => Constants::ANSWER_TYPE_DROPDOWN,
diff --git a/tests/Unit/Service/SubmissionServiceTest.php b/tests/Unit/Service/SubmissionServiceTest.php
index 3cb86ef1e..1908cf6ce 100644
--- a/tests/Unit/Service/SubmissionServiceTest.php
+++ b/tests/Unit/Service/SubmissionServiceTest.php
@@ -1711,6 +1711,50 @@ public static function dataValidateSubmission() {
 				// Expected Result
 				'Answer for non-existent question with ID 101.',
 			],
+			'invalid-branch-date-range-includes-its-bounds' => [
+				// Questions - date range of a single day
+				[
+					[
+						'id' => 100,
+						'type' => Constants::ANSWER_TYPE_DATE,
+						'text' => 'Date Q',
+						'isRequired' => false,
+						'extraSettings' => [
+							'branches' => [[
+								'id' => 'branch-day',
+								'conditions' => [['type' => 'date_range', 'min' => '2026-11-04', 'max' => '2026-11-04']],
+								'subQuestions' => [['id' => 101, 'type' => 'short', 'text' => 'On that day', 'isRequired' => true]],
+							]],
+						],
+					],
+				],
+				// Answers - the day itself, required subquestion not answered
+				['100' => ['2026-11-04']],
+				// Expected Result
+				'Question "On that day" is required.',
+			],
+			'valid-branch-date-outside-range' => [
+				// Questions - the follow-up question of a range the date is outside of is not required
+				[
+					[
+						'id' => 100,
+						'type' => Constants::ANSWER_TYPE_DATE,
+						'text' => 'Date Q',
+						'isRequired' => false,
+						'extraSettings' => [
+							'branches' => [[
+								'id' => 'branch-day',
+								'conditions' => [['type' => 'date_range', 'min' => '2026-11-04', 'max' => '2026-11-04']],
+								'subQuestions' => [['id' => 101, 'type' => 'short', 'text' => 'On that day', 'isRequired' => true]],
+							]],
+						],
+					],
+				],
+				// Answers
+				['100' => ['2026-11-05']],
+				// Expected Result
+				null,
+			],
 			'invalid-branch-unknown-option' => [
 				// Questions - The question is validated like any other question
 				[