[ddsjoberg]

What changes are proposed in this pull request?

• Updates to tbl_ard_hierarchical(): (tbl_hierarchical() enhancements #2021)
  • Added the overall_row argument to include an overall summary row at the top of the table, using results from cards::ard_stack_hierarchical(over_variables = TRUE) or cards::ard_stack_hierarchical_count(over_variables = TRUE).
  • The structure of the cards input is now checked against the variables, by, include, and statistic arguments, and an informative error is returned when they do not match. Previously, some mismatches silently returned an incomplete table.
  • The default variable labels are now taken from the label attributes saved in the ARD (e.g. cards::ard_stack_hierarchical(attributes = TRUE)), and the label argument now accepts formula-list-selector syntax, as documented.

Notes for the reviewer

• These are the remaining unchecked items in tbl_hierarchical() enhancements #2021. The open question in that issue (should the hierarchical ARD functions optionally include the data frame attributes?) is already handled in cards 0.9.0 via attributes = TRUE. The gtsummary side, using those attributes as the default labels, is done here.
• Before this change, overall rows in the ARD were silently dropped because overall_row = FALSE was hard-coded in the bridge call. A label for the overall row could also never be applied, because the code looked up an "overall" name instead of "..ard_hierarchical_overall..".
• Example of a silent failure that is now an error: with the default include = everything(), an ARD built with include = AETERM returned a table missing every SOC row.
• Structure check: each hierarchy variable's results must be grouped by exactly c(by, <preceding hierarchy variables>), in order. The non-standard ard_tabulate() ARD in the existing tests passes this check.
• New tests confirm that overall_row = TRUE output is identical to tbl_hierarchical() and tbl_hierarchical_count(). Each new error message is covered by a snapshot.
• Not a hot path, so no perf prefix.

If there is an GitHub issue associated with this pull request, please provide link.

closes #2021

---

Reviewer Checklist (if item does not apply, mark is as complete)

• If a bug was fixed, a unit test was added.
• Code coverage is suitable for any new functions/features: devtools::test_coverage()
• spelling::spell_check_package() runs with no spelling errors in documentation
• All GitHub Action workflows pass with a ✅
• Update NEWS.md with the changes from this pull request under the heading "# gtsummary (development version)". If there is an issue associated with the pull request, reference it in parentheses at the end update (see NEWS.md for examples).

When the branch is ready to be merged into master:

• Approve Pull Request
• Merge the PR. Please use "Squash and merge".

🤖 Generated with Claude Code