introduce decorators for tm_g_forest_tte (#1264)

Part of insightsengineering/teal#1371

<details><summary> Working Example </summary>

```r
devtools::load_all("../teal.reporter")
devtools::load_all("../teal")
devtools::load_all(".")
library(nestcolor)
library(dplyr)

caption_decorator <- function(annotation = "I am a good decorator", var_to_decorate = "plot") {
  teal_transform_module(
    label = "Annotation",
    ui = function(id) shiny::textInput(shiny::NS(id, "annotation"), "Annotation", value = annotation),
    server = make_teal_transform_server(
      substitute({
        var_to_decorate <- cowplot::add_sub(var_to_decorate, annotation)
      }, env = list(var_to_decorate = as.name(var_to_decorate)))
    )
  )
}

data <- teal_data()
data <- within(data, {
  ADSL <- tmc_ex_adsl
  ADTTE <- tmc_ex_adtte
  ADSL$RACE <- droplevels(ADSL$RACE) %>% with_label("Race")
})
join_keys(data) <- default_cdisc_join_keys[names(data)]

ADSL <- data[["ADSL"]]
ADTTE <- data[["ADTTE"]]

arm_ref_comp <- list(
  ARM = list(
    ref = "B: Placebo",
    comp = c("A: Drug X", "C: Combination")
  ),
  ARMCD = list(
    ref = "ARM B",
    comp = c("ARM A", "ARM C")
  )
)

app <- init(
  data = data,
  modules = modules(
    tm_g_forest_tte(
      label = "Forest Survival",
      dataname = "ADTTE",
      arm_var = choices_selected(
        variable_choices(ADSL, c("ARM", "ARMCD")),
        "ARMCD"
      ),
      arm_ref_comp = arm_ref_comp,
      paramcd = choices_selected(
        value_choices(ADTTE, "PARAMCD", "PARAM"),
        "OS"
      ),
      subgroup_var = choices_selected(
        variable_choices(ADSL, names(ADSL)),
        c("BMRKR2", "SEX")
      ),
      strata_var = choices_selected(
        variable_choices(ADSL, c("STRATA1", "STRATA2")),
        "STRATA2"
      ),
      decorators = list(caption_decorator())
    )
  )
)
shinyApp(app$ui, app$server)


```

</details>

R/tm_g_forest_tte.R

@@ -210,7 +210,7 @@ template_forest_tte <- function(dataname = "ANL",
     plot_list,
     substitute(
       expr = {
-        p <- cowplot::plot_grid(
+        plot <- cowplot::plot_grid(
           f[["table"]] + ggplot2::labs(title = ggplot2_args_title, subtitle = ggplot2_args_subtitle),
           f[["plot"]] + ggplot2::labs(caption = ggplot2_args_caption),
           align = "h",
@@ -243,6 +243,14 @@ template_forest_tte <- function(dataname = "ANL",
 #'
 #' @inherit module_arguments return seealso
 #'
+#' @section Decorating `tm_g_forest_tte`:
+#'
+#' This module generates the following objects, which can be modified in place using decorators:
+#' - `plot` (`ggplot2`)
+#'
+#' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-modules-output", package = "teal")` or the [`teal_transform_module()`] documentation.
+#'
 #' @examplesShinylive
 #' library(teal.modules.clinical)
 #' interactive <- function() TRUE
@@ -339,7 +347,8 @@ tm_g_forest_tte <- function(label,
                             font_size = c(15L, 1L, 30L),
                             pre_output = NULL,
                             post_output = NULL,
-                            ggplot2_args = teal.widgets::ggplot2_args()) {
+                            ggplot2_args = teal.widgets::ggplot2_args(),
+                            decorators = NULL) {
   message("Initializing tm_g_forest_tte")
   checkmate::assert_string(label)
   checkmate::assert_string(dataname)
@@ -367,6 +376,8 @@ tm_g_forest_tte <- function(label,
   checkmate::assert_class(pre_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
+  decorators <- normalize_decorators(decorators)
+  assert_decorators(decorators, null.ok = TRUE, "plot")
 
   args <- as.list(environment())
 
@@ -395,7 +406,8 @@ tm_g_forest_tte <- function(label,
         riskdiff = riskdiff,
         plot_height = plot_height,
         plot_width = plot_width,
-        ggplot2_args = ggplot2_args
+        ggplot2_args = ggplot2_args,
+        decorators = decorators
       )
     ),
     datanames = teal.transform::get_extract_datanames(data_extract_list)
@@ -468,6 +480,7 @@ ui_g_forest_tte <- function(id, ...) {
         data_extract_spec = a$strata_var,
         is_single_dataset = is_single_dataset_value
       ),
+      ui_decorate_teal_data(ns("decorator"), decorators = select_decorators(a$decorators, "plot")),
       teal.widgets::panel_group(
         teal.widgets::panel_item(
           "Additional plot settings",
@@ -528,7 +541,8 @@ srv_g_forest_tte <- function(id,
                              riskdiff,
                              plot_height,
                              plot_width,
-                             ggplot2_args) {
+                             ggplot2_args,
+                             decorators) {
   with_reporter <- !missing(reporter) && inherits(reporter, "Reporter")
   with_filter <- !missing(filter_panel_api) && inherits(filter_panel_api, "FilterPanelAPI")
   checkmate::assert_class(data, "reactive")
@@ -691,7 +705,13 @@ srv_g_forest_tte <- function(id,
     })
 
     # Outputs to render.
-    plot_r <- reactive(all_q()[["p"]])
+    decorated_all_q <- srv_decorate_teal_data(
+      id = "decorator",
+      data = all_q,
+      decorators = select_decorators(decorators, "plot"),
+      expr = print(plot)
+    )
+    plot_r <- reactive(decorated_all_q()[["plot"]])
 
     pws <- teal.widgets::plot_with_settings_srv(
       id = "myplot",
@@ -702,7 +722,7 @@ srv_g_forest_tte <- function(id,
 
     teal.widgets::verbatim_popup_srv(
       id = "rcode",
-      verbatim_content = reactive(teal.code::get_code(all_q())),
+      verbatim_content = reactive(teal.code::get_code(req(decorated_all_q()))),
       title = "R Code for the Current Time-to-Event Forest Plot"
     )
 
@@ -721,7 +741,7 @@ srv_g_forest_tte <- function(id,
           card$append_text("Comment", "header3")
           card$append_text(comment)
         }
-        card$append_src(teal.code::get_code(all_q()))
+        card$append_src(teal.code::get_code(req(decorated_all_q())))
         card
       }
       teal.reporter::simple_reporter_srv("simple_reporter", reporter = reporter, card_fun = card_fun)