#' Evaluate expression on `teal_data_module`

#'

#' @details

#' `within` is a convenience function for evaluating inline code inside the environment of a `teal_data_module`.

#' It accepts only inline expressions (both simple and compound) and allows for injecting values into `expr` through

#' the `...` argument: as `name:value` pairs are passed to `...`, `name` in `expr` will be replaced with `value.`

#'

#' @param data (`teal_data_module`) object

#' @param expr (`expression`) to evaluate. Must be inline code. See [within()]

#' @param ... See `Details`.

#'

#' @return

#' `within` returns a `teal_data_module` object with a delayed evaluation of `expr` when the module is run.

#'

#' @examples

#' within(tdm, dataset1 <- subset(dataset1, Species == "virginica"))

#'

#' # use additional parameter for expression value substitution.

#' valid_species <- "versicolor"

#' within(tdm, dataset1 <- subset(dataset1, Species %in% species), species = valid_species)

#' @include teal_data_module.R

#' @name within

#' @rdname teal_data_module

#'

#' @export

#'

within.teal_data_module <- function(data, expr, ...) {

  # Add braces for consistency.

  }

  # Inject extra values into expressions.

}

#' `teal` main module

#'

#' @description

#' Module to create a `teal` app as a Shiny Module.

#'

#' @details

#' This module can be used instead of [init()] in custom Shiny applications. Unlike [init()], it doesn't

#' automatically include [`module_session_info`].

#'

#' Module is responsible for creating the main `shiny` app layout and initializing all the necessary

#' components. This module establishes reactive connection between the input `data` and every other

#' component in the app. Reactive change of the `data` passed as an argument, reloads the app and

#' possibly keeps all input settings the same so the user can continue where one left off.

#'

#' ## data flow in `teal` application

#'

#' This module supports multiple data inputs but eventually, they are all converted to `reactive`

#' returning `teal_data` in this module. On this `reactive teal_data` object several actions are

#' performed:

#' - data loading in [`module_init_data`]

#' - data filtering in [`module_filter_data`]

#' - data transformation in [`module_transform_data`]

#'

#' ## Fallback on failure

#'

#' `teal` is designed in such way that app will never crash if the error is introduced in any

#' custom `shiny` module provided by app developer (e.g. [teal_data_module()], [teal_transform_module()]).

#' If any module returns a failing object, the app will halt the evaluation and display a warning message.

#' App user should always have a chance to fix the improper input and continue without restarting the session.

#'

#' @rdname module_teal

#' @name module_teal

#'

#' @inheritParams init

#' @param id (`character(1)`) `shiny` module instance id.

#' @param data (`teal_data`, `teal_data_module`, or `reactive` returning `teal_data`)

#' The data which application will depend on.

#' @param modules (`teal_modules`)

#'   `teal_modules` object. These are the specific output modules which

#'   will be displayed in the `teal` application. See [modules()] and [module()] for

#'   more details.

#'

#' @return `NULL` invisibly

NULL

#' @rdname module_teal

#' @export

ui_teal <- function(id, modules) {

  # show busy icon when `shiny` session is busy computing stuff

  # based on https://stackoverflow.com/questions/17325521/r-shiny-display-loading-message-while-function-is-running/22475216#22475216 # nolint: line_length.

    )

  )

          },

          },

          },

          }

        )

      )

    }),

  )

  )

}

#' @rdname module_teal

#' @export

srv_teal <- function(id, data, modules, filter = teal_slices(), reporter = teal.reporter::Reporter$new()) {

    }

    })

    # set timezone in shiny app

    # timezone is set in the early beginning so it will be available also

    # for `DDL` and all shiny modules

      }

    )

    )

        )

      }

    })

      } else {

      }

    })

        )

      )

        {

                ),

              )

            )

          )

          } else {

          }

        }

      )

        # when once = TRUE we pull data once and then remove data button and a modal

        })

      }

    } else {

      # when no teal_data_module then we want to display messages above tabsetPanel (because there is no data-tab)

      )

    }

    # Wait for UI to be rendered before showing/hiding reporter UI elements

    # See: https://github.com/rstudio/shiny/issues/3348

      {

          }

        } else {

        }

      }

    )

      })

    }

    )

  })

}

#' App state management.

#'

#' @description

#' `r lifecycle::badge("experimental")`

#'

#' Capture and restore the global (app) input state.

#'

#' @details

#' This module introduces bookmarks into `teal` apps: the `shiny` bookmarking mechanism becomes enabled

#' and server-side bookmarks can be created.

#'

#' The bookmark manager presents a button with the bookmark icon and is placed in the tab-bar.

#' When clicked, the button creates a bookmark and opens a modal which displays the bookmark URL.

#'

#' `teal` does not guarantee that all modules (`teal_module` objects) are bookmarkable.

#' Those that are, have a `teal_bookmarkable` attribute set to `TRUE`. If any modules are not bookmarkable,

#' the bookmark manager modal displays a warning and the bookmark button displays a flag.

#' In order to communicate that a external module is bookmarkable, the module developer

#' should set the `teal_bookmarkable` attribute to `TRUE`.

#'

#' @section Server logic:

#' A bookmark is a URL that contains the app address with a `/?_state_id_=<bookmark_dir>` suffix.

#' `<bookmark_dir>` is a directory created on the server, where the state of the application is saved.

#' Accessing the bookmark URL opens a new session of the app that starts in the previously saved state.

#'

#' @section Note:

#' To enable bookmarking use either:

#' - `shiny` app by using `shinyApp(..., enableBookmarking = "server")` (not supported in `shinytest2`)

#' - set `options(shiny.bookmarkStore = "server")` before running the app

#'

#'

#' @inheritParams module_teal

#'

#' @return Invisible `NULL`.

#'

#' @aliases bookmark bookmark_manager bookmark_manager_module

#'

#' @name module_bookmark_manager

#' @rdname module_bookmark_manager

#'

#' @keywords internal

#'

NULL

#' @rdname module_bookmark_manager

ui_bookmark_panel <- function(id, modules) {

    )

  }

}

#' @rdname module_bookmark_manager

srv_bookmark_panel <- function(id, modules) {

    # Set up bookmarking callbacks ----

    # Register bookmark exclusions: do_bookmark button to avoid re-bookmarking

    # This bookmark can only be used on the app session.

        )

        )

      } else {

          ),

                } else {

                }

              }

            )

              ),

            )

          }

        )

      }

          )

        )

      )

    })

    # manually trigger bookmarking because of the problems reported on windows with bookmarkButton in teal

    })

  })

}

#' @rdname module_bookmark_manager

get_bookmarking_option <- function() {

  }

}

#' @rdname module_bookmark_manager

need_bookmarking <- function(modules) {

  ))

}

# utilities ----

#' Restore value from bookmark.

#'

#' Get value from bookmark or return default.

#'

#' Bookmarks can store not only inputs but also arbitrary values.

#' These values are stored by `onBookmark` callbacks and restored by `onBookmarked` callbacks,

#' and they are placed in the `values` environment in the `session$restoreContext` field.

#' Using `teal_data_module` makes it impossible to run the callbacks

#' because the app becomes ready before modules execute and callbacks are registered.

#' In those cases the stored values can still be recovered from the `session` object directly.

#'

#' Note that variable names in the `values` environment are prefixed with module name space names,

#' therefore, when using this function in modules, `value` must be run through the name space function.

#'

#' @param value (`character(1)`) name of value to restore

#' @param default fallback value

#'

#' @return

#' In an application restored from a server-side bookmark,

#' the variable specified by `value` from the `values` environment.

#' Otherwise `default`.

#'

#' @keywords internal

#'

restoreValue <- function(value, default) { # nolint: object_name.

  } else {

  }

}

# Replacement for [base::rapply] which doesn't handle NULL values - skips the evaluation

# of the function and returns NULL for given element.

rapply2 <- function(x, f) {

  } else {

  }

}

#' The default favicon for the teal app.

#' @keywords internal

.teal_favicon <- "https://raw.githubusercontent.com/insightsengineering/hex-stickers/main/PNG/teal.png"

#' Get client timezone

#'

#' User timezone in the browser may be different to the one on the server.

#' This script can be run to register a `shiny` input which contains information about the timezone in the browser.

#'

#' @param ns (`function`) namespace function passed from the `session` object in the `shiny` server.

#'  For `shiny` modules this will allow for proper name spacing of the registered input.

#'

#' @return `NULL`, invisibly.

#'

#' @keywords internal

#'

get_client_timezone <- function(ns) {

  )

}

#' Resolve the expected bootstrap theme

#' @noRd

#' @keywords internal

get_teal_bs_theme <- function() {

  }

    )

  }

}

#' Return parentnames along with datanames.

#' @noRd

#' @keywords internal

.include_parent_datanames <- function(datanames, join_keys) {

    }

  }

}

#' Create a `FilteredData`

#'

#' Create a `FilteredData` object from a `teal_data` object.

#'

#' @param x (`teal_data`) object

#' @param datanames (`character`) vector of data set names to include; must be subset of `names(x)`

#' @return A `FilteredData` object.

#' @keywords internal

teal_data_to_filtered_data <- function(x, datanames = names(x)) {

  # Otherwise, FilteredData will be created in the modules' scope later

  )

}

#' Template function for `TealReportCard` creation and customization

#'

#' This function generates a report card with a title,

#' an optional description, and the option to append the filter state list.

#'

#' @param title (`character(1)`) title of the card (unless overwritten by label)

#' @param label (`character(1)`) label provided by the user when adding the card

#' @param description (`character(1)`) optional, additional description

#' @param with_filter (`logical(1)`) flag indicating to add filter state

#' @param filter_panel_api (`FilterPanelAPI`) object with API that allows the generation

#' of the filter state in the report

#'

#' @return (`TealReportCard`) populated with a title, description and filter state.

#'

#' @export

report_card_template <- function(title, label, description = NULL, with_filter, filter_panel_api) {

}

#' Check `datanames` in modules

#'

#' These functions check if specified `datanames` in modules match those in the data object,

#' returning error messages or `TRUE` for successful validation. Two functions return error message

#' in different forms:

#' - `check_modules_datanames` returns `character(1)` for basic assertion usage

#' - `check_modules_datanames_html` returns `shiny.tag.list` to display it in the app.

#'

#' @param modules (`teal_modules`) object

#' @param datanames (`character`) names of datasets available in the `data` object

#'

#' @return `TRUE` if validation passes, otherwise `character(1)` or `shiny.tag.list`

#' @keywords internal

check_modules_datanames <- function(modules, datanames) {

  } else {

  }

}

#' @rdname check_modules_datanames

check_reserved_datanames <- function(datanames) {

  }

    )

  )

}

#' @rdname check_modules_datanames

check_modules_datanames_html <- function(modules, datanames) {

    } else {

    }

  }

              )

            )

          ),

                )

              )

            )

          } else {

          },

        )

      }

    )

  )

}

#' Recursively checks modules and returns list for every datanames mismatch between module and data

#' @noRd

check_modules_datanames_recursive <- function(modules, datanames) { # nolint: object_name_length

    )

  } else {

      ))

    }

  }

}

#' Convert character vector to html code separated with commas and "and"

#' @noRd

to_html_code_list <- function(x) {

        }

      )

    })

  )

}

#' Check `datanames` in filters

#'

#' This function checks whether `datanames` in filters correspond to those in `data`,

#' returning character vector with error messages or `TRUE` if all checks pass.

#'

#' @param filters (`teal_slices`) object

#' @param datanames (`character`) names of datasets available in the `data` object

#'

#' @return A `character(1)` containing error message or TRUE if validation passes.

#' @keywords internal

check_filter_datanames <- function(filters, datanames) {

  # check teal_slices against datanames

        )

      }

    }

  ))

  } else {

  }

}

#' Function for validating the title parameter of `teal::init`

#'

#' Checks if the input of the title from `teal::init` will create a valid title and favicon tag.

#' @param shiny_tag (`shiny.tag`) Object to validate for a valid title.

#' @keywords internal

validate_app_title_tag <- function(shiny_tag) {

  )

}

#' Build app title with favicon

#'

#' A helper function to create the browser title along with a logo.

#'

#' @param title (`character`) The browser title for the `teal` app.

#' @param favicon (`character`) The path for the icon for the title.

#' The image/icon path can be remote or the static path accessible by `shiny`, like the `www/`

#'

#' @return A `shiny.tag` containing the element that adds the title and logo to the `shiny` app.

#' @export

build_app_title <- function(

  title = "teal app",

  favicon = "https://raw.githubusercontent.com/insightsengineering/hex-stickers/main/PNG/nest.png"

) {

  )

    )

  )

}

#' Application ID

#'

#' Creates App ID used to match filter snapshots to application.

#'

#' Calculate app ID that will be used to stamp filter state snapshots.

#' App ID is a hash of the app's data and modules.

#' See "transferring snapshots" section in ?snapshot.

#'

#' @param data (`teal_data` or `teal_data_module`) as accepted by `init`

#' @param modules (`teal_modules`) object as accepted by `init`

#'

#' @return A single character string.

#'

#' @keywords internal

create_app_id <- function(data, modules) {

  }

  # Suppress warnings of type: `package:MultiAssayExperiment' may not be available when loading`

  # This is because the package namespace may be part of the `data` object

}

#' Go through list and extract bodies of encountered functions as string, recursively.

#' @keywords internal

#' @noRd

defunction <- function(x) {

  } else {

  }

}

#' Get unique labels

#'

#' Get unique labels for the modules to avoid namespace conflicts.

#'

#' @param labels (`character`) vector of labels

#'

#' @return (`character`) vector of unique labels

#'

#' @keywords internal

get_unique_labels <- function(labels) {

}

#' @keywords internal

#' @noRd

#' Convert character list to human readable html with commas and "and"

#' @noRd

paste_datanames_character <- function(x,

                                      tags = list(span = shiny::tags$span, code = shiny::tags$code),

                                      tagList = shiny::tagList) { # nolint: object_name.

        }

      )

    })

  )

}

#' Build datanames error string for error message

#'

#' tags and tagList are overwritten in arguments allowing to create strings for

#' logging purposes

#' @noRd

build_datanames_error_message <- function(label = NULL,

                                          datanames,

                                          extra_datanames,

                                          tags = list(span = shiny::tags$span, code = shiny::tags$code),

                                          tagList = shiny::tagList) { # nolint: object_name.

      )

    ),

          )

        )

      )

    } else {

    }

  )

}

#' Smart `rbind`

#'

#' Combine `data.frame` objects which have different columns

#'

#' @param ... (`data.frame`)

#' @keywords internal

.smart_rbind <- function(...) {

    }

  )

}

#' Pluralize a word depending on the size of the input

#'

#' @param x (`object`) to check length for plural.

#' @param singular (`character`) singular form of the word.

#' @param plural (optional `character`) plural form of the word. If not given an "s"

#' is added to the singular form.

#'

#' @return A `character` that correctly represents the size of the `x` argument.

#' @keywords internal

pluralize <- function(x, singular, plural = NULL) {

  } else {

    } else {

    }

  }

}

#' @keywords internal

.dropdown_button <- function(id = NULL, label, icon) {

    )

  )

}

#' @keywords internal

.expand_button <- function(id, label, icon) {

    ),

    )

  )

}

#' @keywords internal

.primary_button <- function(id, label, icon = NULL) {

    },

  )

}

setOldClass("teal_module")

setOldClass("teal_modules")

#' Create `teal_module` and `teal_modules` objects

#'

#' @description

#' Create a nested tab structure to embed modules in a `teal` application.

#'

#' @details

#' `module()` creates an instance of a `teal_module` that can be placed in a `teal` application.

#' `modules()` shapes the structure of a the application by organizing `teal_module` within the navigation panel.

#' It wraps `teal_module` and `teal_modules` objects in a `teal_modules` object,

#' which results in a nested structure corresponding to the nested tabs in the final application.

#'

#' Note that for `modules()` `label` comes after `...`, so it must be passed as a named argument,

#' otherwise it will be captured by `...`.

#'

#' The labels `"global_filters"` and `"Report previewer"` are reserved

#' because they are used by the `mapping` argument of [teal_slices()]

#' and the report previewer module [reporter_previewer_module()], respectively.

#'

#' # Restricting datasets used by `teal_module`:

#'

#' The `datanames` argument controls which datasets are used by the module's server. These datasets,

#' passed via server's `data` argument, are the only ones shown in the module's tab.

#'

#' When `datanames` is set to `"all"`, all datasets in the data object are treated as relevant.

#' However, this may include unnecessary datasets, such as:

#' -	Proxy variables for column modifications

#' -	Temporary datasets used to create final ones

#' -	Connection objects

#'

#' Datasets which name is prefixed in `teal_data` by the dot (`.`) are not displayed in the `teal` application.

#' Please see the _"Hidden datasets"_ section in `vignette("including-data-in-teal-applications").

#'

#' # `datanames` with `transformators`

#' When transformators are specified, their `datanames` are added to the module's `datanames`, which

#' changes the behavior as follows:

#' - If `module(datanames)` is `NULL` and the `transformators` have defined `datanames`, the sidebar

#'   will appear showing the `transformators`' datasets, instead of being hidden.

#' - If `module(datanames)` is set to specific values and any `transformator` has `datanames = "all"`,

#'   the module may receive extra datasets that could be unnecessary

#'

#' @param label (`character(1)`) Label shown in the navigation item for the module or module group.

#'   For `modules()` defaults to `"root"`. See `Details`.

#' @param server (`function`) `shiny` module with following arguments:

#'  - `id` - `teal` will set proper `shiny` namespace for this module (see [shiny::moduleServer()]).

#'  - `input`, `output`, `session` - (optional; not recommended) When provided, then [shiny::callModule()]

#'    will be used to call a module. From `shiny` 1.5.0, the recommended way is to use

#'    [shiny::moduleServer()] instead which doesn't require these arguments.

#'  - `data` (optional) If the server function includes a `data` argument, it will receive a reactive

#'     expression containing the `teal_data` object.

#'  - `datasets` (optional) When provided, the module will be called with `FilteredData` object as the

#'    value of this argument. (See [`teal.slice::FilteredData`]).

#'  - `reporter` (optional) When provided, the module will be called with `Reporter` object as the value

#'    of this argument. (See [`teal.reporter::Reporter`]).

#'  - `filter_panel_api` (optional) When provided, the module will be called with `FilterPanelAPI` object

#'    as the value of this argument. (See [`teal.slice::FilterPanelAPI`]).

#'  - `...` (optional) When provided, `server_args` elements will be passed to the module named argument

#'    or to the `...`.

#' @param ui (`function`) `shiny` UI module function with following arguments:

#'  - `id` - `teal` will set proper `shiny` namespace for this module.

#'  - `...` (optional) When provided, `ui_args` elements will be passed to the module named argument

#'    or to the `...`.

#' @param filters (`character`) Deprecated. Use `datanames` instead.

#' @param datanames (`character`) Names of the datasets relevant to the item.

#' There are 2 reserved values that have specific behaviors:

#' - The keyword `"all"` includes all datasets available in the data passed to the teal application.

#' - `NULL` hides the sidebar panel completely.

#' - If `transformators` are specified, their `datanames` are automatically added to this `datanames`

#'   argument.

#' @param server_args (named `list`) with additional arguments passed on to the server function.

#' @param ui_args (named `list`) with additional arguments passed on to the UI function.

#' @param x (`teal_module` or `teal_modules`) Object to format/print.

#' @param transformators (`list` of `teal_transform_module`) that will be applied to transform module's data input.

#' To learn more check `vignette("transform-input-data", package = "teal")`.

#'

#' @param ...

#' - For `modules()`: (`teal_module` or `teal_modules`) Objects to wrap into a tab.

#' - For `format()` and `print()`: Arguments passed to other methods.

#'

#' @return

#' `module()` returns an object of class `teal_module`.

#'

#' `modules()` returns an object of class `teal_modules`.

#'

#' @name teal_modules

#' @aliases teal_module

#'

#' @examplesShinylive

#' library(teal)

#' interactive <- function() TRUE

#' {{ next_example }}

#' @examples

#' library(shiny)

#'

#' module_1 <- module(

#'   label = "a module",

#'   server = function(id, data) {

#'     moduleServer(

#'       id,

#'       module = function(input, output, session) {

#'         output$data <- renderDataTable(data()[["iris"]])

#'       }

#'     )

#'   },

#'   ui = function(id) {

#'     ns <- NS(id)

#'     tagList(dataTableOutput(ns("data")))

#'   },

#'   datanames = "all"

#' )

#'

#' module_2 <- module(

#'   label = "another module",

#'   server = function(id) {

#'     moduleServer(

#'       id,

#'       module = function(input, output, session) {

#'         output$text <- renderText("Another Module")

#'       }

#'     )

#'   },

#'   ui = function(id) {

#'     ns <- NS(id)

#'     tagList(textOutput(ns("text")))

#'   },

#'   datanames = NULL

#' )

#'

#' modules <- modules(

#'   label = "modules",

#'   modules(

#'     label = "nested modules",

#'     module_1

#'   ),

#'   module_2

#' )

#'

#' app <- init(

#'   data = teal_data(iris = iris),

#'   modules = modules

#' )

#'

#' if (interactive()) {

#'   shinyApp(app$ui, app$server)

#' }

#' @rdname teal_modules

#' @export

#'

module <- function(label = "module",

                   server = function(id, data, ...) moduleServer(id, function(input, output, session) NULL),

                   ui = function(id, ...) tags$p(paste0("This module has no UI (id: ", id, " )")),

                   filters,

                   datanames = "all",

                   server_args = NULL,

                   ui_args = NULL,

                   transformators = list()) {

  # argument checking (independent)

  ## `label`

    )

  }

    )

  }

  ## server

  )) {

    )

  }

    )

  }

  ## UI

    )

  }

    )

  }

  ## `filters`

  }

  ## `datanames` (also including deprecated `filters`)

  # please note a race condition between datanames set when filters is not missing and data arg in server function

  }

  ## `server_args`

    )

  }

  ## `ui_args`

    )

  }

  ## `transformators`

  }

  } else {

  }

    ),

  )

}

#' @rdname teal_modules

#' @export

#'

modules <- function(..., label = character(0)) {

    )

  }

      ),

    )

  )

}

# printing methods ----

#' Extract decorator labels from a decorator structure

#'

#' Recursively extracts labels from decorators, handling both single decorators

#' and nested list structures.

#'

#' @param dec Decorator object or list of decorators

#' @return Character vector of decorator labels, or `character(0L)` if none found

#' @keywords internal

extract_decorator_labels <- function(dec) {

    } else {

    }

  } else {

  }

}

#' Format decorators in a tree structure

#'

#' Formats decorators showing global decorators and object-specific decorators

#' in a tree structure. Returns a list with 'global' and 'objects' components.

#'

#' @param decorators List of decorators (can be mixed: global and named lists)

#' @return List with 'global' (character vector) and 'objects' (named list) components

#' @keywords internal

format_decorators_tree <- function(decorators) {

  }

    } else {

      }

    }

  }

}

#' Render labels as tree leaf nodes

#'

#' Takes a character vector of labels and renders them as tree leaves

#' with proper `|-` / `L-` connectors.

#'

#' @param labels (`character`) Labels to render as leaf nodes

#' @param prefix (`character(1)`) Prefix for each line (indentation and pipe characters)

#' @return (`character(1)`) Formatted string with tree connectors

#' @keywords internal

format_tree_leaves <- function(labels, prefix) {

  }

}

#' Render decorator entries as tree nodes