HorizonCalendar

HorizonCalendar uses a custom layout solution designed for high performance and constant memory usage, regardless of the date range being displayed. Unlike UICollectionView, which scales memory usage linearly with the number of items, HorizonCalendar's memory footprint is dependent only on the number of items currently visible in the viewport.

Key architectural components include:

• CalendarView: The UIView subclass that acts as the central coordinator.
• VisibleItemsProvider: Determines which subset of calendar items is currently visible by checking adjacent items against the current viewport.
• LayoutItemTypeEnumerator: Used by the provider to traverse adjacent layout items.
• FrameProvider: Calculates item frames incrementally. It determines the position of an item (like a Month or a day) based on the frame of a known adjacent item, allowing for lazy layout at arbitrary date offsets.
• ItemViewReuseManager: Manages the creation and reuse of views, similar to UICollectionView's reuse mechanism, by calculating the difference between the current and previous sets of visible items.

HorizonCalendar is a declarative and performant calendar UI component for iOS that supports both SwiftUI and UIKit. It is designed to handle use cases ranging from simple date pickers to complex, fully-featured calendar applications.

Key Features

• Layouts: Supports both vertical and horizontal month layouts, including paging for horizontal layouts.
• Data Flow: Uses a declarative API that encourages unidirectional data flow.
• Customization: Highly customizable views for days, month headers, days of the week, and month grid backgrounds. Supports custom views for highlighting date ranges and overlays (e.g., tooltips).
• Selection: Includes handlers for single-day selection and multi-day selection via drag gestures.
• Flexibility: Supports virtually-infinite date ranges, all Foundation.Calendar types (Gregorian, Japanese, Hebrew, etc.), and right-to-left (RTL) layouts.
• Interaction: Supports scrolling to arbitrary dates/months with or without animation and pinning the days-of-the-week row.

In UIKit, use the CalendarView class. Visual configuration is managed via a CalendarViewContent object.

Important: CalendarView does not have an intrinsic content size. You must provide a valid frame using Auto Layout or manual frame setting. If using Auto Layout, ensure you set translatesAutoresizingMaskIntoConstraints = false and activate constraints.

// 1. Create the content
private func makeContent() -> CalendarViewContent {
  let calendar = Calendar.current
  let startDate = calendar.date(from: DateComponents(year: 2020, month: 01, day: 01))!
  let endDate = calendar.date(from: DateComponents(year: 2021, month: 12, day: 31))!

  return CalendarViewContent(
    calendar: calendar,
    visibleDateRange: startDate...endDate,
    monthsLayout: .vertical(options: VerticalMonthsLayoutOptions()))
}

// 2. Initialize and add to view
let calendarView = CalendarView(initialContent: makeContent())
view.addSubview(calendarView)
calendarView.translatesAutoresizingMaskIntoConstraints = false

NSLayoutConstraint.activate([
  calendarView.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),
  calendarView.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),
  calendarView.topAnchor.constraint(equalTo: view.layoutMarginsGuide.topAnchor),
  calendarView.bottomAnchor.constraint(equalTo: view.layoutMarginsGuide.bottomAnchor),
])

In UIKit, use the dayItemProvider(_:) method on CalendarViewContent. This method returns a new CalendarViewContent instance configured with a provider closure that returns a CalendarItemModel for a given DayComponents.

To use a custom view, implement the CalendarItemViewRepresentable protocol. This requires two static methods:

1. makeView(withInvariantViewProperties:): Creates the view using properties that don't change (e.g., font, colors).
2. setContent(_:on:): Updates data-dependent properties (e.g., the day number text) on the existing view instance.

// 1. Define the view representable
struct DayLabel: CalendarItemViewRepresentable {
  struct InvariantViewProperties: Hashable {
    let font: UIFont
    let textColor: UIColor
    let borderColor: UIColor
  }

  struct Content: Equatable {
    let day: DayComponents
  }

  static func makeView(withInvariantViewProperties invariantViewProperties: InvariantViewProperties) -> UILabel {
    let label = UILabel()
    label.font = invariantViewProperties.font
    label.textColor = invariantViewProperties.textColor
    label.layer.borderColor = invariantViewProperties.borderColor.cgColor
    label.layer.borderWidth = 1
    label.layer.cornerRadius = 12
    label.textAlignment = .center
    return label
  }

  static func setContent(_ content: Content, on view: UILabel) {
    view.text = "\(content.day.day)"
  }
}

// 2. Use it in content configuration
return CalendarViewContent(...)
  .dayItemProvider { day in
    DayLabel.calendarItemModel(
      invariantViewProperties: .init(font: .systemFont(ofSize: 18), textColor: .label, borderColor: .systemBlue),
      content: .init(day: day))
  }