Enhancement: Expand Safe Expression Date Helpers

[lattln]

Summary

Extend eSheet’s safe AST-based expression engine with a cleaner, unit-aware date API so authors can work with common date logic without falling back to dangerous JavaScript.

Background
The safe expression engine already supports basic date operations, including:

• addDays
• subDays
• diffDays
• today
• year

That covers simple day-based logic, but it leaves date workflows fragmented and forces authors to use either multiple helper names or dangerous JS for more natural date handling.

Goal
Make date logic in safe expressions more expressive, consistent, and easier to author by introducing generalized date helpers that accept a time unit.

Proposed Approach
Instead of adding many separate helpers like addWeeks, addMonths, and addYears, use a smaller unit-aware API.

Proposed Helpers

• addDate(date, amount, unit)
• subDate(date, amount, unit)
• diffDate(a, b, unit)
• startOf(date, unit)
• endOf(date, unit)

Supported Units

• day
• week
• month
• year

Optional later expansion:

• hour
• minute
• second

Examples

addDate({startDate}, 1, 'day')
addDate({startDate}, 2, 'week')
addDate({startDate}, 1, 'month')
addDate({startDate}, 1, 'year')

diffDate({endDate}, {startDate}, 'day')
diffDate({endDate}, {startDate}, 'month')

startOf({appointmentDate}, 'month')
endOf({appointmentDate}, 'week')

Use Cases

• Add a follow-up date based on an encounter date
• Check if a date falls inside a week or month window
• Compare dates by week, month, or year instead of only by days
• Normalize dates to the beginning or end of a time period
• Build richer date-based conditions and display logic without JS

Non-Goals

• Do not expose arbitrary Date methods
• Do not add unsafe runtime JavaScript to the safe path
• Do not expand the ticket into general non-date expression helpers
• Do not replace the existing safe day-based helpers immediately unless needed for backward compatibility

Implementation Notes

• Keep evaluation inside the existing tokenizer / parser / AST evaluator
• Validate the unit argument against a small allowed set
• Preserve backward compatibility for existing safe date expressions
• Add clear behavior for invalid dates and invalid units
• Ensure date helpers work in:
  • conditional expressions
  • display interpolation
  • expression validation

Acceptance Criteria

• Safe expressions support unit-aware date helpers
• Existing date helpers continue to work unchanged
• Invalid units fail safely and predictably
• Date helpers remain AST-evaluated, not eval or new Function
• Tests cover day, week, month, and year behaviors
• Documentation reflects the new date API with examples
• Builder/editor UX can surface the new helpers clearly

Suggested Priority

• P1: addDate, subDate, diffDate
• P2: startOf, endOf
• P3: time-based units like hour, minute, second if needed later