Merge pull request 'fix(quarto): repair LaTeX + Typst branded templates (#11 #12 #13 #14)' (#15) from fix/quarto-template-bugs into master

The single-file `template: civilytics-typst.typ` discarded Quarto's
auto-generated `definitions` partial, so any Typst document containing a
code block failed with `unknown variable: Skylighting`.

Ship the template as Quarto template-partials instead, so Quarto keeps its
definitions (Skylighting + token functions) and syntax-highlighted code
blocks render while the Civilytics branding still applies:

- split civilytics-typst.typ into typst-template.typ (the styling function)
  and typst-show.typ (the show/entry point, keyword-safe [ ] wrapping kept);
  remove the single-file template
- use_civilytics_theme() now copies both partials and prints the
  template-partials usage
- example report.qmd uses template-partials

Verified: a report with an R code block renders with working syntax
highlighting and full branding.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: civilytics
 Type: Package
 Title: Brand Themes, Color Palettes, and Utility Functions for Civilytics
-Version: 0.2.0
+Version: 0.3.0
 Authors@R:
     person("Jared", "E. Knowles", email = "jared@civilytics.com",
            role = c("aut", "cre"))

NAMESPACE

@@ -42,6 +42,7 @@ export(safe_ratio)
 export(scale_color_civilytics)
 export(scale_fill_civilytics)
 export(simpleCap)
+export(stamp_logo_png)
 export(star_subs)
 export(theme_civilytics)
 export(theme_civilytics_dark)
@@ -61,8 +62,12 @@ importFrom(ggplot2,annotation_custom)
 importFrom(ggplot2,ggplot)
 importFrom(ggplot2,theme)
 importFrom(ggplot2,theme_void)
+importFrom(grDevices,dev.off)
+importFrom(grDevices,png)
 importFrom(graphics,rasterImage)
 importFrom(grid,grid.draw)
+importFrom(grid,grid.newpage)
+importFrom(grid,grid.raster)
 importFrom(grid,rasterGrob)
 importFrom(gridExtra,arrangeGrob)
 importFrom(jpeg,readJPEG)

R/logo.R

@@ -361,3 +361,92 @@ civilytics_logo <- function(plot,
            position = position)
 }
 
+
+#' Stamp the Civilytics logo onto a saved raster (PNG) image
+#'
+#' The raster analogue of [civilytics_logo()] for outputs that are already
+#' rendered to a file rather than held as a ggplot/grob — e.g. a `flextable`
+#' exported to PNG, or any `grDevices::png()` / `ragg::agg_png()` output.
+#' Resolves the *same* brand asset that [make_logo_grob()] uses, so file-based
+#' tables stay visually consistent with logo-branded plots, and composites it
+#' into a corner of the image. Pure base-graphics + grid + png — no new
+#' package dependencies.
+#'
+#' @param path Character. Path to the PNG to stamp. The file is overwritten
+#'   in place at its original pixel dimensions.
+#' @param type Character. `"wordmark"` (default) or `"mark"`. As in
+#'   [make_logo_grob()].
+#' @param variant Character. `"light"` (default, dark logo for light
+#'   backgrounds) or `"dark"` (reverse logo for dark backgrounds).
+#' @param position Character. Corner placement: `"bottom-right"` (default),
+#'   `"bottom-left"`, `"top-right"`, or `"top-left"`.
+#' @param width_frac Numeric. Logo width as a fraction of the image width
+#'   (default `0.15`). Height follows from the logo's aspect ratio.
+#' @param margin_frac Numeric. Padding from the edges as a fraction of the
+#'   image width (default `0.02`).
+#'
+#' @return `path`, invisibly.
+#' @export
+#' @importFrom png readPNG
+#' @importFrom grid grid.newpage grid.raster
+#' @importFrom grDevices png dev.off
+#' @examples
+#' \dontrun{
+#' # Brand a table exported to PNG so it matches civilytics_logo()-branded plots
+#' ragg::agg_png("table.png", width = 8, height = 4, units = "in", res = 200)
+#' plot(flextable::flextable(head(mtcars)))
+#' dev.off()
+#' stamp_logo_png("table.png")                         # wordmark, bottom-right
+#' stamp_logo_png("table.png", type = "mark", position = "bottom-left")
+#' }
+stamp_logo_png <- function(path,
+                           type = c("wordmark", "mark"),
+                           variant = c("light", "dark"),
+                           position = c("bottom-right", "bottom-left",
+                                        "top-right", "top-left"),
+                           width_frac = 0.15,
+                           margin_frac = 0.02) {
+  type     <- match.arg(type)
+  variant  <- match.arg(variant)
+  position <- match.arg(position)
+  stopifnot(file.exists(path))
+
+  # Same asset selection as make_logo_grob() so files match branded plots.
+  img_file <- switch(
+    paste(type, variant, sep = "_"),
+    wordmark_light = "civilytics-wordmark.png",
+    wordmark_dark  = "civilytics-wordmark-reverse.png",
+    mark_light     = "civilytics-mark.png",
+    mark_dark      = "civilytics-mark-reverse.png"
+  )
+  logo_path <- system.file("img", img_file, package = "civilytics")
+  if (!nzchar(logo_path)) {
+    stop("Civilytics logo asset not found in the 'civilytics' package: ", img_file)
+  }
+
+  base_img <- png::readPNG(path)        # height x width x channels, values in [0, 1]
+  logo_img <- png::readPNG(logo_path)
+  h <- dim(base_img)[1]
+  w <- dim(base_img)[2]
+  aspect <- dim(logo_img)[1] / dim(logo_img)[2]   # logo height / width
+
+  # Sizes/margins are expressed relative to image WIDTH, then converted to the
+  # device's npc units (which scale with the viewport's own width and height).
+  lw <- width_frac
+  lh <- width_frac * aspect * (w / h)
+  mx <- margin_frac
+  my <- margin_frac * (w / h)
+
+  x <- if (grepl("right", position)) 1 - mx else mx
+  y <- if (grepl("top",   position)) 1 - my else my
+  just <- c(if (grepl("right", position)) "right" else "left",
+            if (grepl("top",   position)) "top"   else "bottom")
+
+  grDevices::png(path, width = w, height = h, units = "px")
+  on.exit(grDevices::dev.off(), add = TRUE)
+  grid::grid.newpage()
+  grid::grid.raster(base_img, width = 1, height = 1, interpolate = FALSE)
+  grid::grid.raster(logo_img, x = x, y = y, width = lw, height = lh,
+                    just = just, interpolate = TRUE)
+  invisible(path)
+}

R/quarto.R

@@ -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
-  .copy_pkg_file(
-    "quarto/typst/civilytics-typst.typ",
-    "typst/civilytics-typst.typ",
-    path, force
-  )
+  # Typst — shipped as template-partials so Quarto keeps its Skylighting
+  # definitions and syntax-highlighted code blocks render (see issue #12)
+  typst_files <- c("typst-template.typ", "typst-show.typ")
+  for (f in typst_files) {
+    .copy_pkg_file(file.path("quarto/typst", f), file.path("typst", f), path, force)
+  }
 
   # Logos — for _brand.yml (expects assets/logo/)
   .copy_logos("assets/logo", path, force)
@@ -158,7 +158,9 @@ 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: typst/civilytics-typst.typ")
+  message("    template-partials:")
+  message("      - typst/typst-template.typ")
+  message("      - typst/typst-show.typ")
   message("---")
   message("\nSee examples/report.qmd for a complete example.")
   invisible(NULL)

inst/quarto/examples/report.qmd

@@ -19,7 +19,9 @@ format:
     toc: true
     toc-location: right
   typst:
-    template: ../typst/civilytics-typst.typ
+    template-partials:
+      - ../typst/typst-template.typ
+      - ../typst/typst-show.typ
   pdf:
     include-in-header: ../latex/civilytics.tex
     include-before-body: ../latex/civilytics-title.tex

inst/quarto/examples/slides.qmd

@@ -62,4 +62,4 @@ Civilytics Research, 2026
 Questions?
 
 - jared@civilytics.com
-- civilytics.consulting
+- civilytics.com

inst/quarto/latex/civilytics-title.tex

@@ -2,6 +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}
@@ -33,8 +38,6 @@
 
   % Pulse mark, in ember
   \begin{center}
-    \begin{tikzpicture}[overlay, remember picture]
-    \end{tikzpicture}
     {\color{ember}\rule{40pt}{2pt}}
   \end{center}
 \end{titlepage}

inst/quarto/latex/civilytics.tex

@@ -40,17 +40,40 @@
 \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,
@@ -77,7 +100,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.consulting}
+\fancyfoot[L]{\sffamily\scriptsize\color{ink3}civilytics.com}
 \fancyfoot[C]{\sffamily\scriptsize\color{ink3}\thepage}
 \fancyfoot[R]{\sffamily\scriptsize\color{ink3}\textcopyright\ 2026}
 

inst/quarto/typst/typst-show.typ

@@ -0,0 +1,17 @@
+// 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
+)

inst/quarto/typst/typst-template.typ

@@ -1,9 +1,15 @@
 // =============================================================
-// Civilytics — Typst template for Quarto PDF
+// Civilytics — Typst template partial for Quarto PDF (typst-template.typ).
+// 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: quarto/typst/civilytics-typst.typ
+//       template-partials:
+//         - quarto/typst/typst-template.typ
+//         - quarto/typst/typst-show.typ
 // =============================================================
 
 #let paper-bg   = rgb("#FAF7F2")
@@ -54,7 +60,7 @@
       grid(
         columns: (1fr, auto, 1fr),
         align: (left, center, right),
-        [civilytics.consulting],
+        [civilytics.com],
         counter(page).display("1 / 1", both: true),
         [© 2026]
       )
@@ -229,16 +235,3 @@
 
   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$

man/stamp_logo_png.Rd

@@ -0,0 +1,56 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/logo.R
+\name{stamp_logo_png}
+\alias{stamp_logo_png}
+\title{Stamp the Civilytics logo onto a saved raster (PNG) image}
+\usage{
+stamp_logo_png(
+  path,
+  type = c("wordmark", "mark"),
+  variant = c("light", "dark"),
+  position = c("bottom-right", "bottom-left", "top-right", "top-left"),
+  width_frac = 0.15,
+  margin_frac = 0.02
+)
+}
+\arguments{
+\item{path}{Character. Path to the PNG to stamp. The file is overwritten
+in place at its original pixel dimensions.}
+
+\item{type}{Character. `"wordmark"` (default) or `"mark"`. As in
+[make_logo_grob()].}
+
+\item{variant}{Character. `"light"` (default, dark logo for light
+backgrounds) or `"dark"` (reverse logo for dark backgrounds).}
+
+\item{position}{Character. Corner placement: `"bottom-right"` (default),
+`"bottom-left"`, `"top-right"`, or `"top-left"`.}
+
+\item{width_frac}{Numeric. Logo width as a fraction of the image width
+(default `0.15`). Height follows from the logo's aspect ratio.}
+
+\item{margin_frac}{Numeric. Padding from the edges as a fraction of the
+image width (default `0.02`).}
+}
+\value{
+`path`, invisibly.
+}
+\description{
+The raster analogue of [civilytics_logo()] for outputs that are already
+rendered to a file rather than held as a ggplot/grob — e.g. a `flextable`
+exported to PNG, or any `grDevices::png()` / `ragg::agg_png()` output.
+Resolves the *same* brand asset that [make_logo_grob()] uses, so file-based
+tables stay visually consistent with logo-branded plots, and composites it
+into a corner of the image. Pure base-graphics + grid + png — no new
+package dependencies.
+}
+\examples{
+\dontrun{
+# Brand a table exported to PNG so it matches civilytics_logo()-branded plots
+ragg::agg_png("table.png", width = 8, height = 4, units = "in", res = 200)
+plot(flextable::flextable(head(mtcars)))
+dev.off()
+stamp_logo_png("table.png")                         # wordmark, bottom-right
+stamp_logo_png("table.png", type = "mark", position = "bottom-left")
+}
+}

tests/testthat/test_logo.R

@@ -0,0 +1,30 @@
+test_that("stamp_logo_png preserves image dimensions and returns the path invisibly", {
+  p <- tempfile(fileext = ".png")
+  on.exit(unlink(p), add = TRUE)
+  grDevices::png(p, width = 600, height = 240); plot(1:5); grDevices::dev.off()
+  in_dim <- dim(png::readPNG(p))[1:2]
+
+  expect_invisible(out <- stamp_logo_png(p))
+  expect_identical(out, p)
+  expect_identical(dim(png::readPNG(p))[1:2], in_dim)  # overwritten at same size
+})
+
+test_that("stamp_logo_png runs for every type/variant/position combination", {
+  p <- tempfile(fileext = ".png")
+  on.exit(unlink(p), add = TRUE)
+  grDevices::png(p, width = 500, height = 200); plot(1:5); grDevices::dev.off()
+
+  for (ty in c("wordmark", "mark")) {
+    for (va in c("light", "dark")) {
+      for (pos in c("bottom-right", "bottom-left", "top-right", "top-left")) {
+        expect_no_error(stamp_logo_png(p, type = ty, variant = va, position = pos))
+      }
+    }
+  }
+})
+
+test_that("stamp_logo_png validates its inputs", {
+  expect_error(stamp_logo_png(tempfile(fileext = ".png")))  # file does not exist
+  # invalid type is rejected by match.arg() before the file is touched
+  expect_error(stamp_logo_png(tempfile(fileext = ".png"), type = "banner"))
+})