Merge pull request 'feat(flextable): reusable Civilytics flextable branding helpers' (#10 ) from feat/flextable-branding into feat/stamp-logo-png

Reviewed-on: #10
2026-06-22 17:00:08 -04:00
18 changed files with 90 additions and 160 deletions
@@ -1,7 +1,7 @@
 Package: civilytics
 Type: Package
 Title: Brand Themes, Color Palettes, and Utility Functions for Civilytics
-Version: 0.3.1
+Version: 0.2.0
 Authors@R:
    person("Jared", "E. Knowles", email = "jared@civilytics.com",
           role = c("aut", "cre"))
@@ -5,45 +5,32 @@ CV_FONT_SANS    <- "Inter"           # axis text, legends, UI elements
 CV_FONT_SERIF   <- "Source Serif 4"  # body prose / editorial long-form
 CV_FONT_MONO    <- "JetBrains Mono"  # code, data tables, numeric callouts
-# Mutable package state held in an environment so the binding itself stays
+# Internal flag so civilytics_load_fonts() is idempotent within a session.
-# locked (R locks all namespace bindings at load time) while the contents
+.cv_fonts_loaded <- FALSE
 # remain writable. See https://adv-r.hadley.nz/environments.html#environments-as-containers
 .cv_state <- new.env(parent = emptyenv())
 .cv_state$fonts_loaded <- FALSE
 #' Load Civilytics brand fonts
 #'
-#' Downloads Inter, Libre Franklin, Source Serif 4 and JetBrains Mono from
+#' Downloads Inter and Libre Franklin from Google Fonts via
-#' Google Fonts via [sysfonts::font_add_google()], then calls
+#' [sysfonts::font_add_google()], then calls [showtext::showtext_auto()] so
-#' [showtext::showtext_auto()] so that all graphics devices render text with
+#' that all graphics devices render text with those fonts. This is called
-#' those fonts. This is called automatically when the package loads; use this
+#' automatically when the package loads; use this function to retry if the
-#' function to retry if the initial load failed (e.g., the machine was offline
+#' initial load failed (e.g., the machine was offline at load time).
 #' at load time).
 #'
-#' Subsequent calls within the same session are no-ops unless `force = TRUE`.
+#' @return Invisibly returns `NULL`.
 #'
 #' @param force Logical. If `TRUE`, reload fonts even if they were already
 #'   loaded in this session. Default `FALSE`.
 #'
 #' @return Invisibly returns `TRUE` if fonts were loaded, `FALSE` if skipped
 #'   (already loaded and `force = FALSE`).
 #' @export
 #'
 #' @examples
 #' \dontrun{
 #' civilytics_load_fonts()
 #' }
-civilytics_load_fonts <- function(force = FALSE) {
+civilytics_load_fonts <- function() {
  if (.cv_state$fonts_loaded && !force) return(invisible(FALSE))
  sysfonts::font_add_google("Inter",          family = "Inter")
  sysfonts::font_add_google("Libre Franklin", family = "Libre Franklin")
  sysfonts::font_add_google("Source Serif 4", family = "Source Serif 4")
  sysfonts::font_add_google("JetBrains Mono", family = "JetBrains Mono")
  showtext::showtext_auto()
-
+  .cv_fonts_loaded <<- TRUE
-  .cv_state$fonts_loaded <- TRUE
+  invisible(NULL)
  invisible(TRUE)
 }
 .onLoad <- function(libname, pkgname) {
@@ -135,12 +135,12 @@ use_civilytics_theme <- function(path = ".", force = FALSE) {
    .copy_pkg_file(file.path("quarto/latex", f), file.path("latex", f), path, force)
  }
-  # Typst — shipped as template-partials so Quarto keeps its Skylighting
+  # Typst
-  # definitions and syntax-highlighted code blocks render (see issue #12)
+  .copy_pkg_file(
-  typst_files <- c("typst-template.typ", "typst-show.typ")
+    "quarto/typst/civilytics-typst.typ",
-  for (f in typst_files) {
+    "typst/civilytics-typst.typ",
-    .copy_pkg_file(file.path("quarto/typst", f), file.path("typst", f), path, force)
+    path, force
-  }
+  )
  # Logos — for _brand.yml (expects assets/logo/)
  .copy_logos("assets/logo", path, force)
@@ -158,9 +158,7 @@ use_civilytics_theme <- function(path = ".", force = FALSE) {
  message("    include-in-header: latex/civilytics.tex")
  message("    include-before-body: latex/civilytics-title.tex")
  message("  typst:")
-  message("    template-partials:")
+  message("    template: typst/civilytics-typst.typ")
  message("      - typst/typst-template.typ")
  message("      - typst/typst-show.typ")
  message("---")
  message("\nSee examples/report.qmd for a complete example.")
  invisible(NULL)
@@ -36,12 +36,10 @@
 #'   to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).
 #' @param grid Character. Which major gridlines to draw: `"y"` (default,
 #'   horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.
-#' @param paper_bg Logical. If `TRUE`, fill the plot and panel backgrounds
+#' @param paper_bg Logical. If `TRUE` (default), fill the plot and panel
-#'   with the warm `paper` color (Civilytics cream). Default is `FALSE`
+#'   backgrounds with the warm `paper` color. Set to `FALSE` for a
-#'   (transparent) so that figures composite cleanly onto any background.
+#'   transparent background (useful for slides or overlay on colored
-#'   Set to `TRUE` for the branded cream canvas. Note: a transparent device
+#'   surfaces).
 #'   background (e.g., `dev = "ragg_png"`, `dev.args = list(background =
 #'   "transparent")`) is also needed for fully-transparent PNG exports.
 #'
 #' @section Font size hierarchy:
 #' All text sizes are derived from `font_size` using relative scale factors.
@@ -70,7 +68,7 @@
 #' \dontrun{
 #' library(ggplot2)
 #'
-#' # Default — transparent background for embedding
+#' # Default editorial theme
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
 #'   theme_civilytics()
@@ -81,10 +79,10 @@
 #'   scale_color_civilytics() +
 #'   theme_civilytics(grid = "both")
 #'
-#' # Branded cream background (opt-in)
+#' # Transparent background for embedding
 #' ggplot(mpg, aes(displ, hwy)) +
 #'   geom_point() +
-#'   theme_civilytics(paper_bg = TRUE)
+#'   theme_civilytics(paper_bg = FALSE)
 #'
 #' # Larger text for poster or display
 #' ggplot(mpg, aes(displ, hwy)) +
@@ -104,7 +102,7 @@ theme_civilytics <- function(
    accent       = unname(civilytics_colors["ember_600"]),
    strip_color  = unname(civilytics_colors["paper_2"]),
    grid         = c("y", "x", "both", "none"),
-    paper_bg     = FALSE) {
+    paper_bg     = TRUE) {
  grid <- match.arg(grid)
  half_line  <- font_size / 2
@@ -2,7 +2,7 @@
 title: "Who pays when rent outpaces wages?"
 subtitle: "A 12-county analysis of cost-burdened renter households, 2019–2024."
 author:
-  - name: "Jared Knowles"
+  - name: "Civilytics Research"
    affiliation: "Civilytics Consulting"
 date: "2026-04-15"
 abstract: |
@@ -19,9 +19,7 @@ format:
    toc: true
    toc-location: right
  typst:
-    template-partials:
+    template: ../typst/civilytics-typst.typ
      - ../typst/typst-template.typ
      - ../typst/typst-show.typ
  pdf:
    include-in-header: ../latex/civilytics.tex
    include-before-body: ../latex/civilytics-title.tex
@@ -55,11 +55,11 @@ Big idea goes here.
 > Rent has outpaced wages in every county we studied.
-Civilytics Consulting, 2026
+Civilytics Research, 2026
 ## Thank you {.thank-you}
 Questions?
 - jared@civilytics.com
- civilytics.com
+- civilytics.consulting
@@ -2,16 +2,11 @@
 % Replaces Quarto's default \maketitle. Uses values from YAML
 % (\thetitle, \theauthor, \thedate) plus an \ifabstract block.
 % Guard: \thesubtitle is normally defined by civilytics.tex's subtitle
 % capture; provide a fallback so this partial degrades gracefully if used
 % without that preamble. See civilyticsR issue #13.
 \providecommand{\thesubtitle}{}
 \begin{titlepage}
  \pagecolor{paper}
  \color{ink}
  \vspace*{0.5in}
-  {\sffamily\bfseries\scriptsize\color{ember}\MakeUppercase{— Civilytics Consulting}\par}
+  {\sffamily\bfseries\scriptsize\color{ember}\MakeUppercase{— Civilytics Research}\par}
  \vspace{12pt}
  {\displayfont\fontsize{32pt}{34pt}\selectfont\bfseries\color{ink}\thetitle\par}
  \vspace{8pt}
@@ -38,6 +33,8 @@
  % Pulse mark, in ember
  \begin{center}
    \begin{tikzpicture}[overlay, remember picture]
    \end{tikzpicture}
    {\color{ember}\rule{40pt}{2pt}}
  \end{center}
 \end{titlepage}
@@ -40,40 +40,17 @@
 \color{ink}
 % --- Fonts (require local install or fontspec lookup) ---
 % Bold uses the family's native Bold weight (present in every Source Serif 4
 % install). Do NOT hard-require a "SemiBold" face: the package installs no
 % system fonts for the PDF path, and standard Source Serif 4 ships only
 % Regular/Bold/Italic/BoldItalic. See civilyticsR issue #14.
 \setmainfont{Source Serif 4}[
  UprightFont = *,
  ItalicFont = * Italic,
  BoldFont = * SemiBold,
  BoldItalicFont = * SemiBold Italic,
  Ligatures = TeX,
 ]
 \setsansfont{Inter}[Ligatures = TeX]
 \setmonofont{JetBrains Mono}[Scale = 0.92]
 \newfontfamily\displayfont{Libre Franklin}[Ligatures = TeX]
 % --- Subtitle capture ---
 % Quarto/pandoc defines \subtitle (which appends to \@title) but never
 % \thesubtitle, which the title page uses. This preamble is emitted before
 % pandoc's \providecommand{\subtitle}, so our definition wins: capture the
 % subtitle into \thesubtitle instead. See civilyticsR issue #13.
 \makeatletter
 \providecommand{\thesubtitle}{}
 \def\subtitle#1{\renewcommand{\thesubtitle}{#1}}
 \makeatother
 % --- Use the Civilytics title page, not pandoc's default ---
 % civilytics-title.tex (include-before-body) IS the title page. Quarto emits
 % its default \maketitle + abstract *before* include-before-body, which would
 % print a second, unstyled title. Neutralise both here, in the preamble
 % (runs at \begin{document}, before the default title). The branded title page
 % does not display the abstract. See civilyticsR issue #13.
 \AtBeginDocument{%
  \renewcommand{\maketitle}{}%
  \renewenvironment{abstract}{\setbox0=\vbox\bgroup}{\egroup}%
 }
 % --- Hyperlinks ---
 \hypersetup{
  colorlinks = true,
@@ -100,7 +77,7 @@
 \renewcommand{\footrulewidth}{0pt}
 \fancyhead[L]{\sffamily\scriptsize\color{ink3}\MakeUppercase{Civilytics Consulting}}
 \fancyhead[R]{\sffamily\scriptsize\color{ink3}\thetitle}
-\fancyfoot[L]{\sffamily\scriptsize\color{ink3}civilytics.com}
+\fancyfoot[L]{\sffamily\scriptsize\color{ink3}civilytics.consulting}
 \fancyfoot[C]{\sffamily\scriptsize\color{ink3}\thepage}
 \fancyfoot[R]{\sffamily\scriptsize\color{ink3}\textcopyright\ 2026}
@@ -1,15 +1,9 @@
 // =============================================================
-// Civilytics — Typst template partial for Quarto PDF (typst-template.typ).
+// Civilytics — Typst template for Quarto PDF
 // Shipped as a Quarto template-partial (paired with typst-show.typ) rather
 // than a full `template:` so Quarto keeps its own `definitions` partial —
 // which defines Skylighting/token functions needed for syntax-highlighted
 // code blocks. See civilyticsR issue #12.
 // Usage in YAML:
 //   format:
 //     typst:
-//       template-partials:
+//       template: quarto/typst/civilytics-typst.typ
 //         - quarto/typst/typst-template.typ
 //         - quarto/typst/typst-show.typ
 // =============================================================
 #let paper-bg   = rgb("#FAF7F2")
@@ -60,7 +54,7 @@
      grid(
        columns: (1fr, auto, 1fr),
        align: (left, center, right),
-        [civilytics.com],
+        [civilytics.consulting],
        counter(page).display("1 / 1", both: true),
        [© 2026]
      )
@@ -164,7 +158,7 @@
  if title != none {
    block[
      #set text(font: sans-stack, size: 8pt, weight: 600, fill: ember, tracking: 0.1em)
-      #upper[— Civilytics Consulting]
+      #upper[— Civilytics Research]
    ]
    v(8pt)
    block[
@@ -235,3 +229,16 @@
  doc
 }
 // Quarto entry point
 #show: doc => civilytics(
  title: $title$,
  $if(subtitle)$subtitle: $subtitle$,$endif$
  $if(by-author)$authors: ($for(by-author)$"$it.name.literal$",$endfor$),$endif$
  $if(date)$date: $date$,$endif$
  $if(abstract)$abstract: [$abstract$],$endif$
  toc: $if(toc)$true$else$false$endif$,
  doc
 )
 $body$
@@ -1,17 +0,0 @@
 // Civilytics — Typst show/entry partial for Quarto (typst-show.typ).
 // Pairs with typst-template.typ. Quarto appends the rendered document body
 // after this partial, so this file intentionally ends with the show rule and
 // no trailing body token. (Do not write that token in a comment here: Quarto
 // interpolates its template variables even inside comments.)
 // Title/subtitle/date are wrapped in [ ] so arbitrary text (including words
 // that are Typst keywords like "for"/"in") is treated as content, not code.
 // See civilyticsR issue #12.
 #show: doc => civilytics(
  title: [$title$],
  $if(subtitle)$subtitle: [$subtitle$],$endif$
  $if(by-author)$authors: ($for(by-author)$"$it.name.literal$",$endfor$),$endif$
  $if(date)$date: [$date$],$endif$
  $if(abstract)$abstract: [$abstract$],$endif$
  toc: $if(toc)$true$else$false$endif$,
  doc
 )
@@ -4,25 +4,17 @@
 \alias{civilytics_load_fonts}
 \title{Load Civilytics brand fonts}
 \usage{
-civilytics_load_fonts(force = FALSE)
+civilytics_load_fonts()
 }
 \arguments{
 \item{force}{Logical. If \code{TRUE}, reload fonts even if they were already
 loaded in this session. Default \code{FALSE}.}
 }
 \value{
-Invisibly returns \code{TRUE} if fonts were loaded, \code{FALSE} if skipped
+Invisibly returns `NULL`.
 (already loaded and \code{force = FALSE}).
 }
 \description{
-Downloads Inter, Libre Franklin, Source Serif 4 and JetBrains Mono from
+Downloads Inter and Libre Franklin from Google Fonts via
-Google Fonts via \code{sysfonts::font_add_google()}, then calls
+[sysfonts::font_add_google()], then calls [showtext::showtext_auto()] so
-\code{showtext::showtext_auto()} so that all graphics devices render text with
+that all graphics devices render text with those fonts. This is called
-those fonts. This is called automatically when the package loads; use this
+automatically when the package loads; use this function to retry if the
-function to retry if the initial load failed (e.g., the machine was offline
+initial load failed (e.g., the machine was offline at load time).
 at load time).
 Subsequent calls within the same session are no-ops unless \code{force = TRUE}.
 }
 \examples{
 \dontrun{
@@ -17,7 +17,7 @@ theme_civilytics(
  accent = unname(civilytics_colors["ember_600"]),
  strip_color = unname(civilytics_colors["paper_2"]),
  grid = c("y", "x", "both", "none"),
-  paper_bg = FALSE
+  paper_bg = TRUE
 )
 }
 \arguments{
@@ -56,12 +56,10 @@ to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
 \item{grid}{Character. Which major gridlines to draw: `"y"` (default,
 horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas. Note: a transparent device
+surfaces).}
 background (e.g., `dev = "ragg_png"`, `dev.args = list(background =
 "transparent")`) is also needed for fully-transparent PNG exports.}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -107,7 +105,7 @@ shrinkage.
 \dontrun{
 library(ggplot2)
-# Default — transparent background for embedding
+# Default editorial theme
 ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme_civilytics()
@@ -118,10 +116,10 @@ ggplot(mpg, aes(displ, hwy, colour = class)) +
  scale_color_civilytics() +
  theme_civilytics(grid = "both")
-# Branded cream background (opt-in)
+# Transparent background for embedding
 ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
-  theme_civilytics(paper_bg = TRUE)
+  theme_civilytics(paper_bg = FALSE)
 # Larger text for poster or display
 ggplot(mpg, aes(displ, hwy)) +
@@ -56,10 +56,10 @@ to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
 \item{grid}{Character. Which major gridlines to draw: `"y"` (default,
 horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas.}
+surfaces).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -52,10 +52,10 @@ design system.}
 \item{strip_color}{Character. Hex code for facet strip background. Defaults
 to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas.}
+surfaces).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -52,10 +52,10 @@ design system.}
 \item{strip_color}{Character. Hex code for facet strip background. Defaults
 to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas.}
+surfaces).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -56,10 +56,10 @@ to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
 \item{grid}{Character. Which major gridlines to draw: `"y"` (default,
 horizontal only), `"x"` (vertical only), `"both"`, or `"none"`.}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas.}
+surfaces).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -52,10 +52,10 @@ design system.}
 \item{strip_color}{Character. Hex code for facet strip background. Defaults
 to [civilytics_colors]`["paper_2"]` (`#F2EDE4`).}
-\item{paper_bg}{Logical. If `TRUE`, fill the plot and panel backgrounds
+\item{paper_bg}{Logical. If `TRUE` (default), fill the plot and panel
-with the warm `paper` color (Civilytics cream). Default is `FALSE`
+backgrounds with the warm `paper` color. Set to `FALSE` for a
-(transparent) so that figures composite cleanly onto any background.
+transparent background (useful for slides or overlay on colored
-Set to `TRUE` for the branded cream canvas.}
+surfaces).}
 }
 \value{
 A complete ggplot2 [ggplot2::theme()] object.
@@ -133,13 +133,8 @@ test_that("theme_civilytics uses brand ink color for text", {
  expect_equal(th$text$colour, unname(civilytics_colors["ink"]))
 })
-test_that("theme_civilytics has transparent background by default", {
+test_that("theme_civilytics uses brand paper color for plot background", {
  th <- theme_civilytics()
  expect_true(is.na(th$plot.background$fill))
 })
 test_that("theme_civilytics uses brand paper color when paper_bg = TRUE", {
  th <- theme_civilytics(paper_bg = TRUE)
  expect_equal(th$plot.background$fill, unname(civilytics_colors["paper"]))
 })