Add Custom Week Number Calculation Support

[PekingSpades]

Add Custom Week Number Calculation Support

Hi there 👋

Thanks for taking the time to review this pull request. I've implemented support for custom week number calculation to address the needs of applications using non-standard calendar systems (academic calendars, fiscal years, etc.).

Related Issue

This PR addresses the feature request in Issue #308 #294 - Support for Custom Week Number Calculation

Overview of Changes

Core Feature Implementation

I've added the ability to customize week number calculation through a new beginWeekCalendar property in WeekView. This allows applications to specify a custom start date for week numbering, which is particularly useful for:

• Academic calendars (starting in September)
• Fiscal year calendars
• Custom organizational calendar systems

Key Classes Modified

1. WeekView.kt

   • Added beginWeekCalendar property with @PublicApi annotation
   • Property accepts a Calendar object representing the custom start date
   • Passes the property to HeaderRenderer for week number calculation
   • Maintains backward compatibility (null by default uses standard week numbering)

2. HeaderRenderer.kt

   • Modified constructor to accept beginWeekCalendar parameter
   • Implemented custom week number calculation logic in drawWeekNumber() method
   • Calculates weeks from the specified start date when beginWeekCalendar is set
   • Falls back to standard week numbering when property is null
   • Important: Refactored from Java 8 time API to Calendar API for better compatibility with older Android versions

Implementation Details

The week number calculation works as follows:

• When beginWeekCalendar is null: Uses standard ISO week numbering (current behavior)
• When beginWeekCalendar is set: Calculates the number of weeks between the custom start date and the current displayed date
• The calculation uses millisecond differences divided by week duration for accuracy

API Compatibility Improvements

Initially implemented with Java 8 time API (Instant, LocalDateTime, ChronoUnit), but refactored to use the standard Calendar API to ensure compatibility with older Android versions (pre-API 26). This eliminates the need for @RequiresApi annotations and makes the feature available to all users.

Screenshots

Before (Standard Week Numbering)

Week numbers start from January 1st following ISO standard.

After (Custom Week Numbering)

When beginWeekCalendar is set to September 1st, week numbers start from that date:

weekView.beginWeekCalendar = Calendar.getInstance().apply {
    set(2024, Calendar.SEPTEMBER, 1)
}

Testing

• Tested with various start dates (beginning, middle, and end of months)
• Verified backward compatibility when beginWeekCalendar is null
• Tested year transitions (start date in previous year)
• Confirmed compatibility with older Android versions (API 21+)

Additional Notes

• The implementation is fully backward compatible
• No breaking changes for existing users
• The feature is opt-in through the beginWeekCalendar property
• Documentation can be added to the wiki once this PR is approved

Thank you for considering this contribution! I'm happy to make any adjustments based on your feedback.