# Shared visual constants for all MLB management analysis charts.
# Source this file at the top of every chart script (before any ggplot calls).

COL_LO      <- "#2166AC"   # blue  = efficient / good
COL_HI      <- "#D6604D"   # red   = expensive / poor
COL_ACCENT  <- "#1a3a6e"   # dark navy for titles / headers
PT_SIZE     <- 4            # standard point size
PT_ALPHA    <- 0.9          # standard point alpha
LBL_SIZE      <- 2.9          # geom_label_repel label text size
QUAD_LBL_SIZE <- 3.5          # quadrant corner label text size
AUTHOR_LINE <- "Analysis: David Lucey"   # append to every caption

# Canonical team short names — covers ALL Lahman teamIDs AND franchIDs.
# Every chart script must use this; never define a local lookup table.
# Includes all historical variants (FLO/FLA/MIA, ANA/CAL/LAA, ML4, MON, etc.)
# and franchID equivalents (NYY, LAD, CHC, STL, SFG, SDP, CHW, KCR, WSN).
TEAM_SHORT <- c(
  # AL East
  NYA = "Yankees",   NYY = "Yankees",
  NYN = "Mets",      NYM = "Mets",
  BOS = "Red Sox",
  BAL = "Orioles",
  TOR = "Blue Jays",
  TBA = "Rays",      TBD = "Rays",
  # AL Central
  CHA = "White Sox", CHW = "White Sox",
  CLE = "Guardians",
  DET = "Tigers",
  KCA = "Royals",    KCR = "Royals",
  MIN = "Twins",
  # AL West
  HOU = "Astros",
  OAK = "Athletics",
  SEA = "Mariners",
  TEX = "Rangers",
  ANA = "Angels",    CAL = "Angels",    LAA = "Angels",
  # NL East
  ATL = "Braves",
  LAN = "Dodgers",   LAD = "Dodgers",
  PHI = "Phillies",
  MIA = "Marlins",   FLA = "Marlins",   FLO = "Marlins",
  WAS = "Nationals", WSN = "Nationals",
  MON = "Expos",
  # NL Central
  CHN = "Cubs",      CHC = "Cubs",
  CIN = "Reds",
  MIL = "Brewers",   ML4 = "Brewers",
  PIT = "Pirates",
  SLN = "Cardinals", STL = "Cardinals",
  # NL West
  ARI = "D-Backs",
  COL = "Rockies",
  SDN = "Padres",    SDP = "Padres",
  SFN = "Giants",    SFG = "Giants"
)

# Quadrant scatter helper — computes axis limits and corner label positions.
# Eliminates ggplot's default 5% expansion that pushes labels inside data cloud.
#
# labels: character(4) in data-coord order:
#   [1] (low_x, high_y)  [2] (high_x, high_y)
#   [3] (low_x,  low_y)  [4] (high_x,  low_y)
# x_reversed: TRUE when using scale_x_reverse()
# pad_frac:   axis padding beyond data range (prevents edge clipping)
# corner_frac: label inset from axis edge
#
# Usage:
#   qs <- quad_setup(dt$x, dt$y, labels = c(...), x_reversed = TRUE)
#   scale_x_reverse(limits = qs$xlim, expand = expansion(0))
#   scale_y_continuous(limits = qs$ylim, expand = expansion(0))
#   geom_text(data = qs$quad_lbl, aes(x,y,label,hjust,vjust), ...)
quad_setup <- function(x_data, y_data, labels, x_reversed = FALSE,
                       pad_frac = 0.08, corner_frac = 0.03) {
  stopifnot(is.character(labels), length(labels) == 4L)
  xr <- range(x_data, na.rm = TRUE)
  yr <- range(y_data, na.rm = TRUE)
  xl <- c(xr[1] - diff(xr) * pad_frac, xr[2] + diff(xr) * pad_frac)
  yl <- c(yr[1] - diff(yr) * pad_frac, yr[2] + diff(yr) * pad_frac)
  xm <- diff(xl) * corner_frac
  ym <- diff(yl) * corner_frac
  # hjust: at data low_x → visual right when reversed (hjust=1), left when normal (hjust=0)
  hjust <- if (x_reversed) c(1L, 0L, 1L, 0L) else c(0L, 1L, 0L, 1L)
  list(
    xlim = xl,
    ylim = yl,
    quad_lbl = data.table::data.table(
      x     = c(xl[1] + xm, xl[2] - xm, xl[1] + xm, xl[2] - xm),
      y     = c(yl[2] - ym, yl[2] - ym, yl[1] + ym, yl[1] + ym),
      hjust = hjust,
      vjust = c(1L, 1L, 0L, 0L),
      label = labels
    )
  )
}

# Horizontal colourbar (8 cm wide) — for legend.position = "bottom"
std_colourbar <- function(...) {
  ggplot2::guide_colourbar(
    barwidth       = grid::unit(8, "cm"),
    barheight      = grid::unit(0.5, "cm"),
    title.position = "top",
    label.theme    = ggplot2::element_text(size = 9),
    ...
  )
}

# Standard chart theme — bottom legend, consistent spacing across all acts.
theme_story <- function(base = 13) {
  ggplot2::theme_minimal(base_size = base) +
    ggplot2::theme(
      plot.title    = ggplot2::element_text(face = "bold", size = base + 3, colour = COL_ACCENT,
                                            margin = ggplot2::margin(b = 4)),
      plot.subtitle = ggplot2::element_text(colour = "grey30", size = base - 1,
                                            lineheight = 1.3,
                                            margin = ggplot2::margin(b = 8)),
      plot.caption  = ggplot2::element_text(colour = "grey55", size = base - 3,
                                            hjust = 0, lineheight = 1.2,
                                            margin = ggplot2::margin(t = 8)),
      axis.title    = ggplot2::element_text(size = base - 1),
      legend.title  = ggplot2::element_text(size = base - 1, face = "bold"),
      legend.text   = ggplot2::element_text(size = base - 2),
      legend.position  = "bottom",
      legend.box       = "horizontal",
      legend.spacing.x = grid::unit(0.5, "cm"),
      panel.grid    = ggplot2::element_line(colour = "grey92"),
      plot.margin   = ggplot2::margin(t = 12, r = 20, b = 10, l = 12)
    )
}