#' Filter panel module in teal

#'

#' Creates filter panel module from `teal_data` object and returns `teal_data`. It is build in a way

#' that filter panel changes and anything what happens before (e.g. [`module_init_data`]) is triggering

#' further reactive events only if something has changed and if the module is visible. Thanks to

#' this special implementation all modules' data are recalculated only for those modules which are

#' currently displayed.

#'

#' @return A `eventReactive` containing `teal_data` containing filtered objects and filter code.

#' `eventReactive` triggers only if all conditions are met:

#'  - tab is selected (`is_active`)

#'  - when filters are changed (`get_filter_expr` is different than previous)

#'

#' @inheritParams module_teal_module

#' @param active_datanames (`reactive` returning `character`) this module's data names

#' @name module_filter_data

#' @keywords internal

NULL

#' @rdname module_filter_data

ui_filter_data <- function(id) {

}

#' @rdname module_filter_data

srv_filter_data <- function(id, datasets, active_datanames, data, is_active) {

        # render will be triggered only when FilteredData object changes (not when filters change)

        # technically it means that teal_data_module needs to be refreshed

        }

      })

    })

    })

  })

}

#' @rdname module_filter_data

.make_filtered_teal_data <- function(modules, data, datasets = NULL, datanames) {

    )

  )

}

#' @rdname module_filter_data

.observe_active_filter_changed <- function(datasets, is_active, active_datanames, data) {

    )

    } else {

    }

  })

        } else {

        }

      })

    }

  })

}

#' @rdname module_filter_data

.get_filter_expr <- function(datasets, datanames) {

  } else {

  }

}

#' `teal` main module

#'

#' @description

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

#' Module to create a `teal` app. This module can be called directly instead of [init()] and

#' included in your custom application. Please note that [init()] adds `reporter_previewer_module`

#' automatically, which is not a case when calling `ui/srv_teal` directly.

#'

#' @details

#'

#' 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 module_init_data

#' @inheritParams init

#'

#' @return `NULL` invisibly

NULL

#' @rdname module_teal

#' @export

ui_teal <- function(id,

                    modules,

                    title = build_app_title(),

                    header = tags$p(),

                    footer = tags$p()) {

  )

  )

  )

  } else {

  }

  }

  }

  # 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.

      # CSS defined in `custom.css`

    )

  )

    ),

      ),

    ),

          "

            });

          ",

        )

      )

    ),

      )

    )

  )

}

#' @rdname module_teal

#' @export

srv_teal <- function(id, data, modules, filter = teal_slices()) {

    }

    )

    )

    # `JavaScript` code

    # 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 {

      }

    })

      })

    }

          )

        )

      )

          # when once = TRUE we pull data once and then remove data tab

        })

      }

    } else {

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

      )

    }

    )

  })

}

#' Filter settings for `teal` applications

#'

#' Specify initial filter states and filtering settings for a `teal` app.

#'

#' Produces a `teal_slices` object.

#' The `teal_slice` components will specify filter states that will be active when the app starts.

#' Attributes (created with the named arguments) will configure the way the app applies filters.

#' See argument descriptions for details.

#'

#' @inheritParams teal.slice::teal_slices

#'

#' @param module_specific (`logical(1)`) optional,

#'  - `FALSE` (default) when one filter panel applied to all modules.

#'  All filters will be shared by all modules.

#'  - `TRUE` when filter panel module-specific.

#'  Modules can have different set of filters specified - see `mapping` argument.

#' @param mapping `r lifecycle::badge("experimental")`

#' _This is a new feature. Do kindly share your opinions on

#' [`teal`'s GitHub repository](https://github.com/insightsengineering/teal/)._

#'

#'  (named `list`) specifies which filters will be active in which modules on app start.

#'  Elements should contain character vector of `teal_slice` `id`s (see [`teal.slice::teal_slice`]).

#'  Names of the list should correspond to `teal_module` `label` set in [module()] function.

#'  - `id`s listed under `"global_filters` will be active in all modules.

#'  - If missing, all filters will be applied to all modules.

#'  - If empty list, all filters will be available to all modules but will start inactive.

#'  - If `module_specific` is `FALSE`, only `global_filters` will be active on start.

#' @param app_id (`character(1)`)

#'  For internal use only, do not set manually.

#'  Added by `init` so that a `teal_slices` can be matched to the app in which it was used.

#'  Used for verifying snapshots uploaded from file. See `snapshot`.

#'

#' @param x (`list`) of lists to convert to `teal_slices`

#'

#' @return

#' A `teal_slices` object.

#'

#' @seealso [`teal.slice::teal_slices`], [`teal.slice::teal_slice`], [slices_store()]

#'

#' @examples

#' filter <- teal_slices(

#'   teal_slice(dataname = "iris", varname = "Species", id = "species"),

#'   teal_slice(dataname = "iris", varname = "Sepal.Length", id = "sepal_length"),

#'   teal_slice(

#'     dataname = "iris", id = "long_petals", title = "Long petals", expr = "Petal.Length > 5"

#'   ),

#'   teal_slice(dataname = "mtcars", varname = "mpg", id = "mtcars_mpg"),

#'   mapping = list(

#'     module1 = c("species", "sepal_length"),

#'     module2 = c("mtcars_mpg"),

#'     global_filters = "long_petals"

#'   )

#' )

#'

#' app <- init(

#'   data = teal_data(iris = iris, mtcars = mtcars),

#'   modules = list(

#'     module("module1"),

#'     module("module2")

#'   ),

#'   filter = filter

#' )

#'

#' if (interactive()) {

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

#' }

#'

#' @export

teal_slices <- function(...,

                        exclude_varnames = NULL,

                        include_varnames = NULL,

                        count_type = NULL,

                        allow_add = TRUE,

                        module_specific = FALSE,

                        mapping,

                        app_id = NULL) {

      } else {

      }

    }

    }

      ))

    }

      ...,

    )

  })

}

#' @rdname teal_slices

#' @export

#' @keywords internal

#'

as.teal_slices <- function(x) { # nolint: object_name.

}

#' @rdname teal_slices

#' @export

#' @keywords internal

#'

c.teal_slices <- function(...) {

    )

  )

}

#' Deep copy `teal_slices`

#'

#' it's important to create a new copy of `teal_slices` when

#' starting a new `shiny` session. Otherwise, object will be shared

#' by multiple users as it is created in global environment before

#' `shiny` session starts.

#' @param filter (`teal_slices`)

#' @return `teal_slices`

#' @keywords internal

deep_copy_filter <- function(filter) {

    })

  })

}

#' Data module for `teal` transformations and output customization

#'

#' @description

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

#'

#' `teal_transform_module` provides a `shiny` module that enables data transformations within a `teal` application

#' and allows for customization of outputs generated by modules.

#'

#' # Transforming Module Inputs in `teal`

#'

#' Data transformations occur after data has been filtered in `teal`.

#' The transformed data is then passed to the `server` of [`teal_module()`] and managed by `teal`'s internal processes.

#' The primary advantage of `teal_transform_module` over custom modules is in its error handling, where all warnings and

#' errors are managed by `teal`, allowing developers to focus on transformation logic.

#'

#' For more details, see the vignette: `vignette("data-transform-as-shiny-module", package = "teal")`.

#'

#' # Customizing Module Outputs

#'

#' `teal_transform_module` also allows developers to modify any object created within [`teal.data::teal_data`].

#' This means you can use it to customize not only datasets but also tables, listings, and graphs.

#' Some [`teal_modules`] permit developers to inject custom `shiny` modules to enhance displayed outputs.

#' To manage these `decorators` within your module, use [`ui_transform_teal_data()`] and [`srv_transform_teal_data()`].

#' (For further guidance on managing decorators, refer to `ui_args` and `srv_args` in the vignette documentation.)

#'

#' See the vignette `vignette("decorate-modules-output", package = "teal")` for additional examples.

#'

#' # `server` as a language

#'

#' The `server` function in `teal_transform_module` must return a reactive [`teal.data::teal_data`] object.

#' For simple transformations without complex reactivity, the `server` function might look like this:s

#'

#' ```

#' function(id, data) {

#'   moduleServer(id, function(input, output, session) {

#'     reactive({

#'       within(

#'         data(),

#'         expr = x <- subset(x, col == level),

#'         level = input$level

#'       )

#'     })

#'   })

#' }

#' ```

#'

#' The example above can be simplified using `make_teal_transform_server`, where `level` is automatically matched to the

#' corresponding `input` parameter:

#'

#' ```

#' make_teal_transform_server(expr = expression(x <- subset(x, col == level)))

#' ```

#' @inheritParams teal_data_module

#' @param server (`function(id, data)` or `expression`)

#' A `shiny` module server function that takes `id` and `data` as arguments, where `id` is the module id and `data`

#' is the reactive `teal_data` input. The `server` function must return a reactive expression containing a `teal_data`

#' object. For simplified syntax, use [`make_teal_transform_server()`].

#' @param datanames (`character`)

#' Specifies the names of datasets relevant to the module. Only filters for the specified `datanames` will be displayed

#' in the filter panel. The keyword `"all"` can be used to display filters for all datasets. `datanames` are

#' automatically appended to the [`modules()`] `datanames`.

#'

#'

#' @examples

#' data_transformators <- list(

#'   teal_transform_module(

#'     label = "Static transformator for iris",

#'     datanames = "iris",

#'     server = function(id, data) {

#'       moduleServer(id, function(input, output, session) {

#'         reactive({

#'           within(data(), {

#'             iris <- head(iris, 5)

#'           })

#'         })

#'       })

#'     }

#'   ),

#'   teal_transform_module(

#'     label = "Interactive transformator for iris",

#'     datanames = "iris",

#'     ui = function(id) {

#'       ns <- NS(id)

#'       tags$div(

#'         numericInput(ns("n_cols"), "Show n columns", value = 5, min = 1, max = 5, step = 1)

#'       )

#'     },

#'     server = function(id, data) {

#'       moduleServer(id, function(input, output, session) {

#'         reactive({

#'           within(data(),

#'             {

#'               iris <- iris[, 1:n_cols]

#'             },

#'             n_cols = input$n_cols

#'           )

#'         })

#'       })

#'     }

#'   )

#' )

#'

#' output_decorator <- teal_transform_module(

#'   server = make_teal_transform_server(

#'     expression(

#'       object <- rev(object)

#'     )

#'   )

#' )

#'

#' app <- init(

#'   data = teal_data(iris = iris),

#'   modules = example_module(

#'     transformators = data_transformators,

#'     decorators = list(output_decorator)

#'   )

#' )

#' if (interactive()) {

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

#' }

#'

#' @name teal_transform_module

#'

#' @export

teal_transform_module <- function(ui = NULL,

                                  server = function(id, data) data,

                                  label = "transform module",

                                  datanames = "all") {

          # This warning message partially detects when `eventReactive` is used in `data_module`.

          )

        }

        )

      }

    ),

  )

}

#' Make teal_transform_module's server

#'

#' A factory function to simplify creation of a [`teal_transform_module`]'s server. Specified `expr`

#' is wrapped in a shiny module function and output can be passed to the `server` argument in

#' [teal_transform_module()] call. Such a server function can be linked with ui and values from the

#' inputs can be used in the expression. Object names specified in the expression will be substituted

#' with the value of the respective input (matched by the name) - for example in

#' `expression(graph <- graph + ggtitle(title))` object `title` will be replaced with the value of

#' `input$title`.

#' @param expr (`language`)

#'  An R call which will be evaluated within [`teal.data::teal_data`] environment.

#' @return `function(id, data)` returning `shiny` module

#' @examples

#'

#' trim_iris <- teal_transform_module(

#'   label = "Simplified interactive transformator for iris",

#'   datanames = "iris",

#'   ui = function(id) {

#'     ns <- NS(id)

#'     numericInput(ns("n_rows"), "Subset n rows", value = 6, min = 1, max = 150, step = 1)

#'   },

#'   server = make_teal_transform_server(expression(iris <- head(iris, n_rows)))

#' )

#'

#' app <- init(

#'   data = teal_data(iris = iris),

#'   modules = example_module(transformators = trim_iris)

#' )

#' if (interactive()) {

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

#' }

#'

#' @export

make_teal_transform_server <- function(expr) {

  }

      )

        })

      })

    })

  }

}

#' Extract all `transformators` from `modules`.

#'

#' @param modules `teal_modules` or `teal_module`

#' @return A list of `teal_transform_module` nested in the same way as input `modules`.

#' @keywords internal

extract_transformators <- function(modules) {

  }

}

#' Filter state snapshot management

#'

#' Capture and restore snapshots of the global (app) filter state.

#'

#' This module introduces snapshots: stored descriptions of the filter state of the entire application.

#' Snapshots allow the user to save the current filter state of the application for later use in the session,

#' as well as to save it to file in order to share it with an app developer or other users,

#' who in turn can upload it to their own session.

#'

#' The snapshot manager is accessed with the camera icon in the tabset bar.

#' At the beginning of a session it presents three icons: a camera, an upload, and an circular arrow.

#' Clicking the camera captures a snapshot, clicking the upload adds a snapshot from a file

#' and applies the filter states therein, and clicking the arrow resets initial application state.

#' As snapshots are added, they will show up as rows in a table and each will have a select button and a save button.

#'

#' @section Server logic:

#' Snapshots are basically `teal_slices` objects, however, since each module is served by a separate instance

#' of `FilteredData` and these objects require shared state, `teal_slice` is a `reactiveVal` so `teal_slices`

#' cannot be stored as is. Therefore, `teal_slices` are reversibly converted to a list of lists representation

#' (attributes are maintained).

#'

#' Snapshots are stored in a `reactiveVal` as a named list.

#' The first snapshot is the initial state of the application and the user can add a snapshot whenever they see fit.

#'

#' For every snapshot except the initial one, a piece of UI is generated that contains

#' the snapshot name, a select button to restore that snapshot, and a save button to save it to a file.

#' The initial snapshot is restored by a separate "reset" button.

#' It cannot be saved directly but a user is welcome to capture the initial state as a snapshot and save that.

#'

#' @section Snapshot mechanics:

#' When a snapshot is captured, the user is prompted to name it.

#' Names are displayed as is but since they are used to create button ids,

#' under the hood they are converted to syntactically valid strings.

#' New snapshot names are validated so that their valid versions are unique.

#' Leading and trailing white space is trimmed.

#'

#' The module can read the global state of the application from `slices_global` and `mapping_matrix`.

#' The former provides a list of all existing `teal_slice`s and the latter says which slice is active in which module.

#' Once a name has been accepted, `slices_global` is converted to a list of lists - a snapshot.

#' The snapshot contains the `mapping` attribute of the initial application state

#' (or one that has been restored), which may not reflect the current one,

#' so `mapping_matrix` is transformed to obtain the current mapping, i.e. a list that,

#' when passed to the `mapping` argument of [teal_slices()], would result in the current mapping.

#' This is substituted as the snapshot's `mapping` attribute and the snapshot is added to the snapshot list.

#'

#' To restore app state, a snapshot is retrieved from storage and rebuilt into a `teal_slices` object.

#' Then state of all `FilteredData` objects (provided in `datasets`) is cleared

#' and set anew according to the `mapping` attribute of the snapshot.

#' The snapshot is then set as the current content of `slices_global`.

#'

#' To save a snapshot, the snapshot is retrieved and reassembled just like for restoring,

#' and then saved to file with [slices_store()].

#'

#' When a snapshot is uploaded, it will first be added to storage just like a newly created one,

#' and then used to restore app state much like a snapshot taken from storage.

#' Upon clicking the upload icon the user will be prompted for a file to upload

#' and may choose to name the new snapshot. The name defaults to the name of the file (the extension is dropped)

#' and normal naming rules apply. Loading the file yields a `teal_slices` object,

#' which is disassembled for storage and used directly for restoring app state.

#'

#' @section Transferring snapshots:

#' Snapshots uploaded from disk should only be used in the same application they come from,

#' _i.e._ an application that uses the same data and the same modules.

#' To ensure this is the case, `init` stamps `teal_slices` with an app id that is stored in the `app_id` attribute of

#' a `teal_slices` object. When a snapshot is restored from file, its `app_id` is compared to that

#' of the current app state and only if the match is the snapshot admitted to the session.

#'

#' @section Bookmarks:

#' An `onBookmark` callback creates a snapshot of the current filter state.

#' This is done on the app session, not the module session.

#' (The snapshot will be retrieved by `module_teal` in order to set initial app state in a restored app.)

#' Then that snapshot, and the previous snapshot history are dumped into the `values.rds` file in `<bookmark_dir>`.

#'

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

#' @param slices_global (`reactiveVal`) that contains a `teal_slices` object

#'                      containing all `teal_slice`s existing in the app, both active and inactive.

#'

#' @return `list` containing the snapshot history, where each element is an unlisted `teal_slices` object.

#'

#' @name module_snapshot_manager

#' @rdname module_snapshot_manager

#'

#' @author Aleksander Chlebowski

#' @keywords internal

NULL

#' @rdname module_snapshot_manager

ui_snapshot_manager_panel <- function(id) {

  )

}

#' @rdname module_snapshot_manager

srv_snapshot_manager_panel <- function(id, slices_global) {

        )

      )

    })

  })

}

#' @rdname module_snapshot_manager

ui_snapshot_manager <- function(id) {

    ),

  )

}

#' @rdname module_snapshot_manager

srv_snapshot_manager <- function(id, slices_global) {

    # Set up bookmarking callbacks ----

    # Register bookmark exclusions (all buttons and text fields).

    ))

    # Add snapshot history to bookmark.

    })

    # Track global filter states ----

      # Restore directly from bookmarked state, if applicable.

      )

    })

    # Snapshot current application state ----

    # Name snaphsot.

          ),

        )

      )

    })

    # Store snaphsot.

        )

        )

      } else {

        # Reopen filter manager modal by clicking button in the main application.

      }

    })

    # Upload a snapshot file ----

    # Select file.

          ),

          )

        )

      )

    })

    # Store new snapshot to list and restore filter states.

      }

        )

      } else {

        # Restore snapshot and verify app compatibility.

          )

          )

        } else {

          # Add to snapshot history.

          ### Begin simplified restore procedure. ###

          ### End  simplified restore procedure. ###

        }

      }

    })

    # Apply newly added snapshot.

    # Restore initial state ----

      ### Begin restore procedure. ###

      ### End restore procedure. ###

    })

    # Build snapshot table ----

    # Create UI elements and server logic for the snapshot table.

    # Observers must be tracked to avoid duplication and excess reactivity.

    # Remaining elements are tracked likewise for consistency and a slight speed margin.

        # Observer for restoring snapshot.

            ### Begin restore procedure. ###

            ### End restore procedure. ###

          })

        }

        # Create handler for downloading snapshot.

            },

            }

          )

        }

        # Create a row for the snapshot table.

          )

        }

      })

    })

    # Create table to display list of snapshots and their actions.

        )

      } else {

      }

    })

  })

}

#' Calls all `modules`

#'

#' On the UI side each `teal_modules` is translated to a `tabsetPanel` and each `teal_module` is a

#' `tabPanel`. Both, UI and server are called recursively so that each tab is a separate module and

#' reflect nested structure of `modules` argument.

#'

#' @name module_teal_module

#'

#' @inheritParams module_teal

#'

#' @param data (`reactive` returning `teal_data`)

#'

#' @param slices_global (`reactiveVal` returning `modules_teal_slices`)

#'   see [`module_filter_manager`]

#'

#' @param depth (`integer(1)`)

#'  number which helps to determine depth of the modules nesting.

#'

#' @param datasets (`reactive` returning `FilteredData` or `NULL`)

#'  When `datasets` is passed from the parent module (`srv_teal`) then `dataset` is a singleton

#'  which implies in filter-panel to be "global". When `NULL` then filter-panel is "module-specific".

#'

#' @param data_load_status (`reactive` returning `character`)

#'  Determines action dependent on a data loading status:

#'  - `"ok"` when `teal_data` is returned from the data loading.

#'  - `"teal_data_module failed"` when [teal_data_module()] didn't return  `teal_data`. Disables tabs buttons.

#'  - `"external failed"` when a `reactive` passed to `srv_teal(data)` didn't return `teal_data`. Hides the whole tab

#'    panel.

#'

#' @return

#' output of currently active module.

#' - `srv_teal_module.teal_module` returns `reactiveVal` containing output of the called module.

#' - `srv_teal_module.teal_modules` returns output of module selected by `input$active_tab`.

#'

#' @keywords internal

NULL

#' @rdname module_teal_module

ui_teal_module <- function(id, modules, depth = 0L) {

}

#' @rdname module_teal_module

#' @export

ui_teal_module.default <- function(id, modules, depth = 0L) {

}

#' @rdname module_teal_module

#' @export

ui_teal_module.teal_modules <- function(id, modules, depth = 0L) {

        # by giving an id, we can reactively respond to tab changes

        ),

            }

              )

            )

          }

        )

      )

    )

  )

}

#' @rdname module_teal_module

#' @export

ui_teal_module.teal_module <- function(id, modules, depth = 0L) {

        )

      )

    ),

      ),

    )

  )

          )

        )

      } else {

      }

    )

  )

}

#' @rdname module_teal_module

srv_teal_module <- function(id,

                            data,

                            modules,

                            datasets = NULL,

                            slices_global,

                            reporter = teal.reporter::Reporter$new(),

                            data_load_status = reactive("ok"),

                            is_active = reactive(TRUE)) {

}

#' @rdname module_teal_module

#' @export

srv_teal_module.default <- function(id,

                                    data,

                                    modules,

                                    datasets = NULL,

                                    slices_global,

                                    reporter = teal.reporter::Reporter$new(),

                                    data_load_status = reactive("ok"),

                                    is_active = reactive(TRUE)) {

}

#' @rdname module_teal_module

#' @export

srv_teal_module.teal_modules <- function(id,

                                         data,

                                         modules,

                                         datasets = NULL,

                                         slices_global,

                                         reporter = teal.reporter::Reporter$new(),

                                         data_load_status = reactive("ok"),

                                         is_active = reactive(TRUE)) {

      }

    })

          )

        )

      },

    )

  })

}

#' @rdname module_teal_module

#' @export

srv_teal_module.teal_module <- function(id,

                                        data,

                                        modules,

                                        datasets = NULL,

                                        slices_global,

                                        reporter = teal.reporter::Reporter$new(),

                                        data_load_status = reactive("ok"),

                                        is_active = reactive(TRUE)) {

    })

      })

    }

    # manage module filters on the module level

    # important:

    #   filter_manager_module_srv needs to be called before filter_panel_srv

    #   Because available_teal_slices is used in FilteredData$srv_available_slices (via srv_filter_panel)

    #   and if it is not set, then it won't be available in the srv_filter_panel

      )

      )

      })

        } else {

        }

      })

      })

      )

      # Call modules.

          }

        )

      } else {

        # Report previewer must be initiated on app start for report cards to be included in bookmarks.

        # When previewer is delayed, cards are bookmarked only if previewer has been initiated (visited).

      }

    })

  })

}

# This function calls a module server function.

.call_teal_module <- function(modules, datasets, data, reporter) {

  # collect arguments to run teal_module

  }

  }

  }

  }

  } else {

  }

}

.resolve_module_datanames <- function(data, modules) {

  } else {

    )

  }

}