Calc date functions

Author: anttiviljami

docs/templates/template-variables.md

@@ -412,3 +412,53 @@ Min/Max:
 - `ROUND(number, [places])` - Rounds a number to a specified number of decimal places. If places is omitted, it defaults to 0.
 - `SUM(number1, number2, ...)` - Returns the sum of a set of numbers.
 - `RAND()` - Returns a random number between 0 (inclusive) and 1 (exclusive).
+
+### Date functions
+
+All date functions work with ISO 8601 date strings (e.g., "2025-09-26" or "2025-09-26T12:00:00Z") and use UTC by default with optional timezone support.
+
+#### Current time
+- `NOW([timezone])` - Returns the current date and time in ISO format (e.g., "2025-09-26T12:00:00.000Z")
+- `TODAY([timezone])` - Returns the current date in ISO format (e.g., "2025-09-26")
+
+#### Date arithmetic
+- `DATEADD(date, value, unit, [timezone])` - Adds/subtracts time from a date
+  - Units: "years", "quarters", "months", "weeks", "days", "hours", "minutes", "seconds"
+- `DATEDIFF(start_date, end_date, unit, [timezone])` - Calculates difference between dates
+  - Returns floor of the difference (e.g., 1.9 months = 1)
+
+#### Date components
+- `YEAR(date, [timezone])` - Extract year (e.g., 2025)
+- `MONTH(date, [timezone])` - Extract month (1-12)
+- `DAY(date, [timezone])` - Extract day of month (1-31)
+- `HOUR(date, [timezone])` - Extract hour (0-23)
+- `MINUTE(date, [timezone])` - Extract minute (0-59)
+- `SECOND(date, [timezone])` - Extract second (0-59)
+- `WEEKDAY(date, [type], [timezone])` - Get day of week
+  - `type=1`: Sunday=1, Saturday=7 (Excel default)
+  - `type=2` or omitted: Monday=1, Sunday=7 (ISO)
+  - `type=3`: Monday=0, Sunday=6
+
+#### Week calculations
+- `WEEKNUM(date, [type], [timezone])` - Get ISO week number of the year
+
+#### Examples
+
+```handlebars
+<!-- Add 14 days to order date -->
+Delivery date: {{ calc "DATEADD(order.date, 14, \"days\")" }}
+
+<!-- Calculate age -->
+Age: {{ calc "DATEDIFF(birthDate, TODAY(), \"years\")" }} years old
+
+<!-- Extract components -->
+Year: {{ calc "YEAR(invoice.date)" }}
+Month: {{ calc "MONTH(invoice.date)" }}
+
+<!-- Business logic -->
+Due date: {{ calc "DATEADD(invoice.date, payment.terms, \"days\")" }}
+Overdue: {{ calc "DATEDIFF(invoice.dueDate, TODAY(), \"days\") < 0" }}
+
+<!-- Timezone handling -->
+Local date: {{ calc "TODAY(\"Europe/Helsinki\")" }}
+```