Migrate to {lt}

[jdblischak]

Need to migrate from {gt} to {lt} to be consistent with our other packages

xref: keaven/gsDesign#297, keaven/gsDesign#282, Merck/gsDesign2#629

[yihui]

simtrial#371 — Convert gt to lt

Mirror what was done in gsDesign2 PR #629 (merged 70d450e6) and gsDesign PR #282.
Goal: replace the heavy gt dependency with the lightweight lt package.
Deprecate as_gt() gently (keep it returning a gt_tbl for one release), add an
lt() S3 method, and convert all vignettes.

Reference implementations to copy patterns from:

• ../gsDesign2/R/lt.R (lt S3 method + re-export block)
• ../gsDesign2/R/as_gt.R (softened deprecation + assert_gt_installed())

Ground rules

• Run tests only via the project's usual runner; do not invent commands.
• Never drop existing code comments.
• simtrial uses Roxygen: list(markdown = TRUE) (unlike gsDesign), so roxygen
  markdown [lt()], **gt** etc. are fine — same as gsDesign2.
• After any roxygen run, do NOT let it bump RoxygenNote/Config/roxygen2/version
  unintentionally; keep whatever main is on (currently RoxygenNote: 7.3.3).

Tasks

1. DESCRIPTION

• Add lt to Imports (simtrial currently has no Imports table entry for
  table rendering; gt is only in Suggests). Use the lt version gsDesign2
  settled on — check ../gsDesign2/DESCRIPTION (lt in Imports) and match or
  exceed it.
• Keep gt in Suggests (still needed by the deprecated as_gt() and any
  vignette not yet converted). Keep alphabetical order.

2. Add lt() S3 method — new file R/lt.R

• Add the re-export block (so lt() dispatches after loading only simtrial):
  r #' @importFrom lt lt #' @export lt::lt
  with the same explanatory comment used in ../gsDesign2/R/lt.R.
• Port as_gt.simtrial_gs_wlr (in R/as_gt.R) to lt.simtrial_gs_wlr:
  - gt::gt() → lt::lt()
  - gt::cols_label(a = "A", ...) → lt::lt_label(a = "A", ...)
  - gt::cols_move(columns = c(...), after = analysis) → lt::lt_move(columns = c(...), after = "analysis")
  - gt::tab_header(title=, subtitle=) → lt::lt_header(title=, subtitle=)
  - gt::tab_spanner(label=, columns = gt::ends_with("_time")) →
  lt::lt_spanner(label=, columns=<...>). lt has no tidyselect;
  columns accepts character names, integer positions, or a one-sided
  formula, and spanned columns must be contiguous. Replace each
  gt::ends_with("_x") by explicitly enumerating the matching column names
  (e.g. compute them with grep("_time$", names(x), value = TRUE)), or by a
  formula. Verify columns are contiguous.
  - Keep the two-branch logic (compare_with_design == "no" vs design compare)
  and the design_type == "two-sided" extra spanner.
• roxygen: document as @name lt-methods / @rdname lt-methods, port the
  long @examples (change the final simtrial::as_gt() calls to lt()),
  @exportS3Method lt::lt. Match the doc style of ../gsDesign2/R/lt.R.

3. Soften as_gt() deprecation — edit R/as_gt.R

• Generic: emit .Deprecated("lt", package = "simtrial", msg = "...use lt() instead.")
  then UseMethod("as_gt", x).
• Keep the gt-based as_gt.simtrial_gs_wlr body (still returns gt_tbl), but
  add an assert_gt_installed() guard at the top (copy the helper from
  ../gsDesign2/R/as_gt.R, s/gsDesign2/simtrial/).
• Update roxygen: note deprecation, @seealso [lt()], [lt-methods], mention it
  still returns a gt_tbl for one release and requires gt installed.
• Leave the as_gt.fixed_design / as_gt.gs_design S3-redirection shims as-is
  (they forward to gsDesign2). Consider adding matching lt.fixed_design /
  lt.gs_design shims only if lt() on those objects fails when simtrial is
  loaded after gsDesign2 — test first, add only if needed.

4. Convert vignettes (7 files) gt → lt

Replace library(gt) with library(lt); convert calls. Drop library(lt) only
in files that end up calling only the re-exported lt() and no bare lt_*()
helpers (mirrors the gsDesign2 review feedback).
Mapping: gt()→lt(), fmt_number(columns=, decimals=)→lt_format(columns=, decimals=)
(columns must be strings/positions/formula — no bare names, no tidyselect),
tab_header()→lt_header(), tab_spanner()→lt_spanner(),
cols_label()→lt_label(), cols_move()→lt_move().

• vignettes/maxcombo.Rmd (gt + fmt_number)
• vignettes/routines.Rmd (gt + fmt_number)
• vignettes/sim_fixed_design_simple.Rmd (gt + tab_header + fmt_number)
• vignettes/sim_fixed_design_custom.Rmd (gt + tab_header)
• vignettes/sim_gs_design_simple.Rmd (gt + tab_header + fmt_number)
• vignettes/rmst.Rmd (gt)
• vignettes/discrepancy-between-simtrial-and-survival.Rmd (library(gt); table
  calls are commented out — just swap the library line)
• fmt_number(columns = c(4,5,7)) style (integer positions) is fine in
  lt_format. fmt_number(columns = c("a","b")) also fine. Verify each renders.

5. NAMESPACE / man

• Regenerate with roxygen. Expect: export(lt), importFrom(lt,lt),
  S3method(lt::lt,simtrial_gs_wlr), and existing S3method(as_gt,*) kept.
• Confirm man/as_gt.Rd + new man/lt-methods.Rd + man/reexports.Rd generated.

6. pkgdown

• _pkgdown.yml: add lt.simtrial_gs_wlr (and/or lt-methods) next to the
  existing as_gt.simtrial_gs_wlr reference entry (line ~62).

7. NEWS

• Add a "Major changes" entry: gt replaced by lt, lt() recommended,
  lt() generic re-exported, as_gt() deprecated but kept one release
  returning gt_tbl, gt now suggested. Reference Migrate to {lt} #371.

8. Verify

• R CMD INSTALL to a temp lib, then smoke-test: after library(simtrial)
  alone (no library(lt)), a simtrial_gs_wlr summary |> lt() returns an
  lt_tbl; as_gt() warns once and returns a gt_tbl.
• Build vignettes (or knit each) to confirm no gt calls remain and CSS renders.
• Run the package test suite.
• Grep for leftovers: grep -rn "gt::\|library(gt)\|as_gt(" R/ vignettes/
  should only show the intentionally-kept deprecated as_gt() internals.

9. Follow-up

• After merge, file an issue (like gsDesign2#663) to fully remove gt and
  as_gt() in a future release.