#' Friendly labels for cyclical relationships
#'
#' This S7 generic function provides the labels for cyclical relationships 
#' between time granules. These functions should return locale specific labels.
#'
#' @param granule A time granule object representing the granule (e.g., `month(1L)`)
#' @param cycle A time granule object representing the cycle (e.g., `year(1L)`)
#' @param ... Additional arguments for methods.
#'
#' @return Character vector of labels for the time point within the cycle.
#' 
#' @examples
#' # Labels for months in a year
#' with(cal_gregorian, cyclical_labels(month(1L), year(1L), 1:12))
#' 
#' # Labels for days in a week
#' with(cal_isoweek, cyclical_labels(day(1L), week(1L), 1:7))
#' 
#' # Labels for weeks in a year, defaulted from time_unit_abbr()
#' with(cal_isoweek, cyclical_labels(week(1L), year(1L), 1:52))
#' 
#' @export
cyclical_labels <- S7::new_generic("cyclical_labels", c("granule", "cycle"))

# #' Default friendly labels for cyclical relationships
# #' 
# #' The default method for [cyclical_labels()] simply pastes together the time unit 
# #' label and the position within the cycle. This is a fallback method that will
# #' be used if no more specific method is defined for the given time units.
# #' 
# #' @inheritParams cyclical_labels
# #' @param i Integer vector representing the position within the cycle.
# #' @param label If `TRUE`, return labels for the positions within the cycle. If `FALSE`, return the integer positions as character.
# #' @param abbreviate If `TRUE`, return abbreviated labels (e.g. "Mon" for "Monday"). If `FALSE`, return full labels (e.g. "Monday").
# #' 
# #' @seealso [cyclical_labels()]
# #' 
# #' @returns A character vector of labelled granules
# #' @rdname cyclical_labels
method(cyclical_labels, list(mt_unit, mt_unit)) <- function(granule, cycle, i, label = FALSE, abbreviate = TRUE, ...) {
  if (!label) return(as.character(i))
  # TODO - pluralise the full time unit
  paste0(
    if (abbreviate) time_unit_abbr(granule) else time_unit_full(granule), 
    i
  )
}