feat(flextable): add reusable Civilytics flextable branding helpers

Generalize the flextable brand styling and "export to PNG + stamp logo" pattern repeated across Civilytics projects into two small functions: - style_flextable_civilytics(): applies only the visual brand (header fill/color, body font/size, zebra striping guarded for <2 rows, borders, footer styling, fixed layout) to an already-structured flextable. Every value is an overridable parameter; zebra toggles striping. Structure (labels, headers, widths, alignment, footer text) stays with the caller. - save_branded_flextable_png(): exports a styled flextable to PNG via ragg::agg_png() sized to the table plus extra_height headroom, then optionally stamps the logo via stamp_logo_png() (... forwarded). flextable, officer, and ragg are added to Suggests (not Imports) to keep the base install light; both functions reference them fully qualified and guard with requireNamespace() + an install hint. Real round-trip tests cover styling, 1-row idempotence, PNG export, and extra_height.
2026-06-22 16:53:37 -04:00
parent 5fc8155965
commit 4f51a49903
6 changed files with 424 additions and 1 deletions
@@ -0,0 +1,89 @@
+test_that("style_flextable_civilytics returns a styled flextable", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+
+  ft <- flextable::flextable(head(mtcars, 4))
+  ft <- flextable::add_footer_lines(ft, "Source: mtcars")
+  styled <- style_flextable_civilytics(ft)
+
+  expect_s3_class(styled, "flextable")
+  # Fixed layout is the documented end-state of the styling.
+  expect_identical(styled$properties$layout, "fixed")
+})
+
+test_that("style_flextable_civilytics is idempotent on a 1-row table (no zebra error)", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+
+  ft <- flextable::flextable(head(mtcars, 1))
+  expect_no_error(once <- style_flextable_civilytics(ft))
+  # Re-styling an already-styled table must not error either.
+  expect_no_error(twice <- style_flextable_civilytics(once))
+  expect_s3_class(twice, "flextable")
+})
+
+test_that("zebra = FALSE still returns a valid flextable", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+
+  ft <- flextable::flextable(head(mtcars, 6))
+  expect_s3_class(style_flextable_civilytics(ft, zebra = FALSE), "flextable")
+})
+
+test_that("save_branded_flextable_png writes a PNG with plausible dimensions", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+  skip_if_not_installed("ragg")
+  skip_if_not_installed("png")
+
+  ft <- flextable::flextable(head(mtcars, 4))
+  ft <- flextable::add_footer_lines(ft, "Source: mtcars")
+  ft <- style_flextable_civilytics(ft)
+
+  path <- tempfile(fileext = ".png")
+  on.exit(unlink(path), add = TRUE)
+
+  out <- save_branded_flextable_png(ft, path)
+
+  expect_identical(out, path)
+  expect_true(file.exists(path))
+
+  dims <- dim(png::readPNG(path))
+  # height x width x channels — a real table is at least a few hundred px each.
+  expect_gt(dims[1], 50)
+  expect_gt(dims[2], 50)
+})
+
+test_that("save_branded_flextable_png with logo = FALSE skips stamping but still writes", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+  skip_if_not_installed("ragg")
+  skip_if_not_installed("png")
+
+  ft <- style_flextable_civilytics(flextable::flextable(head(mtcars, 3)))
+
+  path <- tempfile(fileext = ".png")
+  on.exit(unlink(path), add = TRUE)
+
+  save_branded_flextable_png(ft, path, logo = FALSE)
+  expect_true(file.exists(path))
+  expect_gt(file.info(path)$size, 0)
+})
+
+test_that("extra_height increases the exported PNG height", {
+  skip_if_not_installed("flextable")
+  skip_if_not_installed("officer")
+  skip_if_not_installed("ragg")
+  skip_if_not_installed("png")
+
+  ft <- style_flextable_civilytics(flextable::flextable(head(mtcars, 4)))
+
+  path_small <- tempfile(fileext = ".png")
+  path_big <- tempfile(fileext = ".png")
+  on.exit(unlink(c(path_small, path_big)), add = TRUE)
+
+  save_branded_flextable_png(ft, path_small, logo = FALSE, extra_height = 0)
+  save_branded_flextable_png(ft, path_big, logo = FALSE, extra_height = 2)
+
+  expect_gt(dim(png::readPNG(path_big))[1], dim(png::readPNG(path_small))[1])
+})