Add TemporalUnit overloads to timeAndDate(), deprecate TimeUnit variants

[LouisDeconinck]

Closes #1911

What

timeAndDate().past(10, TimeUnit.of(ChronoUnit.YEARS)) fails today because java.util.concurrent.TimeUnit maxes out at days. Per the approach agreed in the issue: the twelve future/past overloads taking TimeUnit are deprecated (@Deprecated(since = "3.0.0", forRemoval = true), delegating via unit.toChronoUnit()), and twelve equivalents taking java.time.temporal.TemporalUnit are added — so ChronoUnit.YEARS, MONTHS, etc. now work.

Bounds are computed via referenceDate.atZone(ZoneId.systemDefault()).plus/minus(atMost, unit) so calendar units are handled correctly (Instant.plus would reject units above days); the random instant still comes from the existing between(from, to) helper, preserving the uniform distribution and strict-before/after invariants.

Testing

• ./mvnw test -Dtest=TimeAndDateTest — 1930 tests pass, including new ChronoUnit.YEARS bounds cases and TemporalUnit variants of the bounds/minimum/reference-date tests
• FakerTest + DateAndTimeTest pass — existing TimeUnit behavior and #{date.past '15','SECONDS'} expressions unaffected
• ./mvnw spotless:check clean

Docs (date-format.md) examples updated to ChronoUnit.

[what-the-diff]

PR Summary

• Updated Date Formatting in Documentation
  This Pull Request updates how we show dates in our documentation. Previously, we used a method called TimeUnit. However, now we are switching to a different method called ChronoUnit. This is pertaining to methods that deal with dates in the future and the past.

• Increased Test Coverage
  We've added multiple new tests in a file called TimeAndDateTest.java. These tests are to ensure our date functionalities (those dealing with future and past dates) using ChronoUnit are working as expected. These tests check various scenarios, like future dates with different units (such as seconds, and years) and past dates with various units and reference dates. We've also added tests to check date operations involving masking.

• Warning Suppression Annotation
  There's an update in TimeAndDateTest class where we have introduced a suppression annotation. This annotation is mainly used to suppress or mute any warnings that arise due to code removal in this class.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.28%. Comparing base (36536ad) to head (93ff100).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1912      +/-   ##
============================================
- Coverage     92.38%   92.28%   -0.10%     
- Complexity     3601     3608       +7     
============================================
  Files           348      348              
  Lines          7115     7127      +12     
  Branches        695      695              
============================================
+ Hits           6573     6577       +4     
- Misses          373      377       +4     
- Partials        169      173       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bodiam]

Looks good to me! Thanks for the contribution! Anyone else feedback?

[kingthorin]

LGTM

[asolntsev]

Looks good!