Detect too-wide content and add overflow_action to downgrade to a warning

[billdenney]

Summary

Closes #30. Adds a single user-facing knob overflow_action = c("error", "warn") (default "error") on export_tfl_page(), forwarded automatically to export_tfl() via @inheritDotParams. Three width-overflow detection sites share the knob:

• Page-level grob check — non-ggplot, non-character, non-tfl_table_grob content (gt/rtables/gridExtra/raw user grobs) is measured against the content viewport. Previously silent.
• tfl_table per-column / group-aware check — for each data column j, signals when grp_w + widths_in[j] > content_width_in (group columns repeat on every column-paginated page, so a data col that doesn't fit alongside the row headers is unrenderable). Previously silent.
• tfl_table total-width check — existing allow_col_split = FALSE abort, now downgrade-able.

Every overflow message ends with the literal hint Set `overflow_action = "warn"` to convert this error to a warning and still produce output for diagnosis. Centralized in a private .overflow_signal() helper so the hint stays consistent across all three sites.

Why error by default

Issue #30 explicitly asks for an error that's convertible to a warning. Silent overflow was the bug — defaulting to "error" surfaces it; "warn" is the diagnostic escape hatch (PDF still produced, overflow visibly clipped by grid). No "silent" third level: that would re-open the bug.

sub_tfl ordering

The per-column check lives in compute_col_widths(), reached from .tfl_table_to_pagelist_default() after .strip_sub_tfl_cols() runs. So a tfl_table whose original group_vars would overflow only because one is later stripped by sub_tfl is correctly accepted. New regression test in test-sub_tfl.R locks the ordering in.

Implementation notes

• compute_col_widths() second pass (the cw_adj recompute for col_cont_msg layout) passes validate_overflow = FALSE to avoid re-emitting the same warning twice.
• Page-level check skips tfl_table_grob since compute_col_widths() already validated more precisely.
• export_tfl()'s @param ... switched to @inheritDotParams export_tfl_page so future top-level args propagate without manual doc edits. Verified with devtools::document(): overflow_action shows up in export_tfl.Rd automatically.

Decision log

Full rationale in design/DECISIONS.md as D-39, with companion entries in DESIGN.md, ARCHITECTURE.md, TESTING.md, and a troubleshooting section in vignettes/v04-troubleshooting.Rmd.

Test plan

• devtools::document() regenerates NAMESPACE and Rd files cleanly
• devtools::test() — 991/991 pass, WARN = 1 (pre-existing ggplot2 R-version mismatch in test-draw.R:6, unrelated)
• devtools::check() — clean for everything I touched (R code OK, Rd OK, examples OK, tests OK). The only check failure is a pre-existing gt::as_gtable()/vctrs bug in vignettes/v05-gt_tables.Rmd, confirmed identical on main.
• New tests in test-layout.R (7), test-export_tfl_page.R (5), test-tfl_table.R (9), test-sub_tfl.R (1)
• Every abort/warning message asserted to contain the overflow_action = "warn" hint

🤖 Generated with Claude Code