#' 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 (`shiny`) input variable accessible with `input$tz` which is a (`character`)

#'  string containing the timezone of the browser/client.

#'

#' @keywords internal

#'

get_client_timezone <- function(ns) {

  )

}

#' Resolve the expected bootstrap theme

#' @noRd

#' @keywords internal

get_teal_bs_theme <- function() {

  } else {

  }

}

#' Return parentnames along with datanames.

#' @noRd

#' @keywords internal

include_parent_datanames <- function(dataname, 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 `datanames(x)`

#' @return A `FilteredData` object.

#' @keywords internal

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

  )

  # Piggy-back pre-processing code for datasets of interest so that filtering code can be appended 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

#'

#' This function ensures specified `datanames` in modules match those in the data object,

#' returning error messages or `TRUE` for successful validation.

#'

#' @param modules (`teal_modules`) 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_modules_datanames <- function(modules, datanames) {

    # check teal_modules against datanames

    } else {

        )

      }

    }

  }

  } else {

  }

}

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

  }

}

#' Create filterable data for modules

#'

#' Converts input data to a `FilteredData` object(s) to allow filtering before passing data to individual modules.

#'

#' @param data (`teal_data`)

#' @param modules (`teal_modules`) object

#' @param filters (`teal_slices`) object

#' @param filtered_data_singleton A result of `teal_data_to_filtered_data` applied to `data`.

#' @param progress (`Progress`) object from `shiny`, optional.

#'  The progress bar will be filled during the (possibly recursive) call.

#' @return Returns list of same shape as `modules`, containing `FilteredData` at every leaf.

#' If module specific, each leaf contains different instance, otherwise every leaf contains `filtered_data_singleton`.

#' @keywords internal

modules_datasets <- function(data,

                             modules,

                             filters,

                             filtered_data_singleton = teal_data_to_filtered_data(data),

                             progress = NULL) {

      )

    }

    # subset global filters

    })

  }

      )

    }

    # 1. get datanames

        )

      } else {

        )

      }

    # 2. subset filters (global + dedicated)

      })

    })

    # 2a. subset include/exclude varnames

    # 3. instantiate FilteredData

    # 4. set state

    # 5. return

    )

  }

}

# Returns nested list of same shape as `modules` with `value` at every leaf.

modules_structure <- function(modules, value = TRUE) {

  } else {

    )

  }

}

#' Wrapper on `teal.data::datanames`

#'

#' Special function used in internals of `teal` to return names of datasets even if `datanames`

#' has not been set.

#' @param data (`teal_data`)

#' @return `character`

#' @keywords internal

teal_data_datanames <- function(data) {

  } 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) {

  }

}

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

}

# FilteredData ------

#' Drive a `teal` application

#'

#' Extension of the `shinytest2::AppDriver` class with methods for

#' driving a teal application for performing interactions for `shinytest2` tests.

#'

#' @keywords internal

#'

TealAppDriver <- R6::R6Class( # nolint: object_name.

  "TealAppDriver",

  inherit = shinytest2::AppDriver,

  # public methods ----

  public = list(

    #' @description

    #' Initialize a `TealAppDriver` object for testing a `teal` application.

    #'

    #' @param data,modules,filter,title,header,footer arguments passed to `init`

    #' @param timeout (`numeric`) Default number of milliseconds for any timeout or

    #' timeout_ parameter in the `TealAppDriver` class.

    #' Defaults to 20s.

    #'

    #' See [`shinytest2::AppDriver`] `new` method for more details on how to change it

    #' via options or environment variables.

    #' @param load_timeout (`numeric`) How long to wait for the app to load, in ms.

    #' This includes the time to start R. Defaults to 100s.

    #'

    #' See [`shinytest2::AppDriver`] `new` method for more details on how to change it

    #' via options or environment variables

    #' @param ... Additional arguments to be passed to `shinytest2::AppDriver$new`

    #'

    #'

    #' @return  Object of class `TealAppDriver`

    initialize = function(data,

                          modules,

                          filter = teal_slices(),

                          title = build_app_title(),

                          header = tags$p(),

                          footer = tags$p(),

                          timeout = rlang::missing_arg(),

                          load_timeout = rlang::missing_arg(),

                          ...) {

      )

      # Default timeout is hardcoded to 4s in shinytest2:::resolve_timeout

      # It must be set as parameter to the AppDriver

          ...

        )

      )

      # Check for minimum version of Chrome that supports the tests

      #  - Element.checkVisibility was added on 105

          "",

        ),

      )

      )

        )

      )

      # end od check

    },

    #' @description

    #' Append parent [`shinytest2::AppDriver`] `click` method with a call to `waif_for_idle()` method.

    #' @param ... arguments passed to parent [`shinytest2::AppDriver`] `click()` method.

    click = function(...) {

    },

    #' @description

    #' Check if the app has shiny errors. This checks for global shiny errors.

    #' Note that any shiny errors dependent on shiny server render will only be captured after the teal module tab

    #' is visited because shiny will not trigger server computations when the tab is invisible.

    #' So, navigate to the module tab you want to test before calling this function.

    #' Although, this catches errors hidden in the other module tabs if they are already rendered.

    expect_no_shiny_error = function() {

      )

    },

    #' @description

    #' Check if the app has no validation errors. This checks for global shiny validation errors.

    expect_no_validation_error = function() {

      )

    },

    #' @description

    #' Check if the app has validation errors. This checks for global shiny validation errors.

    expect_validation_error = function() {

      )

    },

    #' @description

    #' Set the input in the `teal` app.

    #'

    #' @param input_id (character) The shiny input id with it's complete name space.

    #' @param value The value to set the input to.

    #' @param ... Additional arguments to be passed to `shinytest2::AppDriver$set_inputs`

    #'

    #' @return The `TealAppDriver` object invisibly.

    set_input = function(input_id, value, ...) {

      )

    },

    #' @description

    #' Navigate the teal tabs in the `teal` app.

    #'

    #' @param tabs (character) Labels of tabs to navigate to. The order of the tabs is important,

    #' and it should start with the most parent level tab.

    #' Note: In case the teal tab group has duplicate names, the first tab will be selected,

    #' If you wish to select the second tab with the same name, use the suffix "_1".

    #' If you wish to select the third tab with the same name, use the suffix "_2" and so on.

    #'

    #' @return The `TealAppDriver` object invisibly.

    navigate_teal_tab = function(tabs) {

        )

      }

    },

    #' @description

    #' Get the active shiny name space for different components of the teal app.

    #'

    #' @return (`list`) The list of active shiny name space of the teal components.

    active_ns = function() {

      }

    },

    #' @description

    #' Get the active shiny name space for interacting with the module content.

    #'

    #' @return (`string`) The active shiny name space of the component.

    active_module_ns = function() {

      }

    },

    #' @description

    #' Get the active shiny name space bound with a custom `element` name.

    #'

    #' @param element `character(1)` custom element name.

    #'

    #' @return (`string`) The active shiny name space of the component bound with the input `element`.

    active_module_element = function(element) {

    },

    #' @description

    #' Get the text of the active shiny name space bound with a custom `element` name.

    #'

    #' @param element `character(1)` the text of the custom element name.

    #'

    #' @return (`string`) The text of the active shiny name space of the component bound with the input `element`.

    active_module_element_text = function(element) {

    },

    #' @description

    #' Get the active shiny name space for interacting with the filter panel.

    #'

    #' @return (`string`) The active shiny name space of the component.

    active_filters_ns = function() {

      }

    },

    #' @description

    #' Get the input from the module in the `teal` app.

    #' This function will only access inputs from the name space of the current active teal module.

    #'

    #' @param input_id (character) The shiny input id to get the value from.

    #'

    #' @return The value of the shiny input.

    get_active_module_input = function(input_id) {

    },

    #' @description

    #' Get the output from the module in the `teal` app.

    #' This function will only access outputs from the name space of the current active teal module.

    #'

    #' @param output_id (character) The shiny output id to get the value from.

    #'

    #' @return The value of the shiny output.

    get_active_module_output = function(output_id) {

    },

    #' @description

    #' Get the output from the module's `teal.widgets::table_with_settings` or `DT::DTOutput` in the `teal` app.

    #' This function will only access outputs from the name space of the current active teal module.

    #'

    #' @param table_id (`character(1)`) The id of the table in the active teal module's name space.

    #' @param which (integer) If there is more than one table, which should be extracted.

    #' By default it will look for  a table that is built using `teal.widgets::table_with_settings`.

    #'

    #' @return The data.frame with table contents.

    get_active_module_table_output = function(table_id, which = 1) {

      } else {

      }

    },

    #' @description

    #' Get the output from the module's `teal.widgets::plot_with_settings` in the `teal` app.

    #' This function will only access plots from the name space of the current active teal module.

    #'

    #' @param plot_id (`character(1)`) The id of the plot in the active teal module's name space.

    #'

    #' @return The `src` attribute as `character(1)` vector.

    get_active_module_plot_output = function(plot_id) {

      )

    },

    #' @description

    #' Set the input in the module in the `teal` app.

    #' This function will only set inputs in the name space of the current active teal module.

    #'

    #' @param input_id (character) The shiny input id to get the value from.

    #' @param value The value to set the input to.

    #' @param ... Additional arguments to be passed to `shinytest2::AppDriver$set_inputs`

    #'

    #' @return The `TealAppDriver` object invisibly.

    set_active_module_input = function(input_id, value, ...) {

        ...

      )

    },

    #' @description

    #' Get the active datasets that can be accessed via the filter panel of the current active teal module.

    get_active_filter_vars = function() {

      )

        )

      )

    },

    #' @description

    #' Test if `DOM` elements are visible on the page with a JavaScript call.

    #' @param selector (`character(1)`) `CSS` selector to check visibility.

    #' A `CSS` id will return only one element if the UI is well formed.

    #' @param content_visibility_auto,opacity_property,visibility_property (`logical(1)`) See more information

    #' on <https://developer.mozilla.org/en-US/docs/Web/API/Element/checkVisibility>.

    #'

    #' @return Logical vector with all occurrences of the selector.

    is_visible = function(selector,

                          content_visibility_auto = FALSE,

                          opacity_property = FALSE,

                          visibility_property = FALSE) {

      )

            # Extra parameters

          )

        )

      )

    },

    #' @description

    #' Get the active filter variables from a dataset in the `teal` app.

    #'

    #' @param dataset_name (character) The name of the dataset to get the filter variables from.

    #' If `NULL`, the filter variables for all the datasets will be returned in a list.

    get_active_data_filters = function(dataset_name = NULL) {

            )

          ) %>%

          )

        }

      )

      }

    },

    #' @description

    #' Add a new variable from the dataset to be filtered.

    #'

    #' @param dataset_name (character) The name of the dataset to add the filter variable to.

    #' @param var_name (character) The name of the variable to add to the filter panel.

    #' @param ... Additional arguments to be passed to `shinytest2::AppDriver$set_inputs`

    #'

    #' @return The `TealAppDriver` object invisibly.

    add_filter_var = function(dataset_name, var_name, ...) {

        ),

        ...

      )

    },

    #' @description

    #' Remove an active filter variable of a dataset from the active filter variables panel.

    #'

    #' @param dataset_name (character) The name of the dataset to remove the filter variable from.

    #' If `NULL`, all the filter variables will be removed.

    #' @param var_name (character) The name of the variable to remove from the filter panel.

    #' If `NULL`, all the filter variables of the dataset will be removed.

    #'

    #' @return The `TealAppDriver` object invisibly.

    remove_filter_var = function(dataset_name = NULL, var_name = NULL) {

        )

        )

      } else {

        )

      }

      )

    },

    #' @description

    #' Set the active filter values for a variable of a dataset in the active filter variable panel.

    #'

    #' @param dataset_name (character) The name of the dataset to set the filter value for.

    #' @param var_name (character) The name of the variable to set the filter value for.

    #' @param input The value to set the filter to.

    #' @param ... Additional arguments to be passed to `shinytest2::AppDriver$set_inputs`

    #'

    #' @return The `TealAppDriver` object invisibly.

    set_active_filter_selection = function(dataset_name,

                                           var_name,

                                           input,

                                           ...) {

      )

      # Find the type of filter (based on filter panel)

            },

          )

        )

      ]

      # Generate correct namespace

      )

          )

        )

          )

        }

          ...

        )

      } else {

      }

    },

    #' @description

    #' Extract `html` attribute (found by a `selector`).

    #'

    #' @param selector (`character(1)`) specifying the selector to be used to get the content of a specific node.

    #' @param attribute (`character(1)`) name of an attribute to retrieve from a node specified by `selector`.

    #'

    #' @return The `character` vector.

    get_attr = function(selector, attribute) {

    },

    #' @description

    #' Wrapper around `get_html` that passes the output directly to `rvest::read_html`.

    #'

    #' @param selector `(character(1))` passed to `get_html`.

    #'

    #' @return An XML document.

    get_html_rvest = function(selector) {

    },

    #' Wrapper around `get_url()` method that opens the app in the browser.

    #'

    #' @return Nothing. Opens the underlying teal app in the browser.

    open_url = function() {

    },

    #' @description

    #' Waits until a specified input, output, or export value.

    #' This function serves as a wrapper around the `wait_for_value` method,

    #' providing a more flexible interface for waiting on different types of values within the active module namespace.

    #' @param input,output,export A name of an input, output, or export value.

    #' Only one of these parameters may be used.

    #' @param ... Must be empty. Allows for parameter expansion.

    #' Parameter with additional value to passed in `wait_for_value`.

    wait_for_active_module_value = function(input = rlang::missing_arg(),

                                            output = rlang::missing_arg(),

                                            export = rlang::missing_arg(),

                                            ...) {

        ...

      )

    }

  ),

  # private members ----

  private = list(

    # private attributes ----

    data = NULL,

    modules = NULL,

    filter = teal_slices(),

    ns = list(

      module = character(0),

      filter_panel = character(0)

    ),

    # private methods ----

    set_active_ns = function() {

        )

      }) %>%

          }

        }

      }

      } else {

      }

    },

    # @description

    # Get the active filter values from the active filter selection of dataset from the filter panel.

    #

    # @param dataset_name (character) The name of the dataset to get the filter values from.

    # @param var_name (character) The name of the variable to get the filter values from.

    #

    # @return The value of the active filter selection.

    get_active_filter_selection = function(dataset_name, var_name) {

      )

      # Find the type of filter (categorical or range)

        }

      }

    },

    # @description

    # Check if the page is stable without any `DOM` updates in the body of the app.

    # This is achieved by blocing the R process by sleeping until the page is unchanged till the `stability_period`.

    # @param stability_period (`numeric(1)`) The time in milliseconds to wait till the page to be stable.

    # @param check_interval (`numeric(1)`) The time in milliseconds to check for changes in the page.

    # The stability check is reset when a change is detected in the page after sleeping for check_interval.

    wait_for_page_stability = function(stability_period = 2000, check_interval = 200) {

        }

      }

    }

  )

)

#' 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 [`wunder_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_wunder_bar

#'

#' @return Invisible `NULL`.

#'

#' @aliases bookmark bookmark_manager bookmark_manager_module

#'

#' @name module_bookmark_manager

#' @keywords internal

#'

bookmark_manager_ui <- function(id) {

}

#' @rdname module_bookmark_manager

#' @keywords internal

#'

bookmark_manager_srv <- function(id, modules) {

      # option alone doesn't activate bookmarking - we need to set shinyOptions

    }

    ))

    # Render bookmark warnings count

              )

            }

          )

        )

      }

    })

    # 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

    })

  })

}

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

  }

}

#' Compare bookmarks.

#'

#' Test if two bookmarks store identical state.

#'

#' `input` environments are compared one variable at a time and if not identical,

#' values in both bookmarks are reported. States of `datatable`s are stripped

#' of the `time` element before comparing because the time stamp is always different.

#' The contents themselves are not printed as they are large and the contents are not informative.

#' Elements present in one bookmark and absent in the other are also reported.

#' Differences are printed as messages.

#'

#' `values` environments are compared with `all.equal`.

#'

#' @section How to use:

#' Open an application, change relevant inputs (typically, all of them), and create a bookmark.

#' Then open that bookmark and immediately create a bookmark of that.

#' If restoring bookmarks occurred properly, the two bookmarks should store the same state.

#'

#'

#' @param book1,book2 bookmark directories stored in `shiny_bookmarks/`;

#'                    default to the two most recently modified directories

#'

#' @return

#' Invisible `NULL` if bookmarks are identical or if there are no bookmarks to test.

#' `FALSE` if inconsistencies are detected.

#'

#' @keywords internal

#'

bookmarks_identical <- function(book1, book2) {

  }

    }

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

  }

}

#' 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 [`wunder_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.

#' @param mapping_matrix (`reactive`) that contains a `data.frame` representation

#'                       of the mapping of filter state ids (rows) to modules labels (columns);

#'                       all columns are `logical` vectors.

#' @param datasets non-nested (named `list`) of `FilteredData` objects.

#'

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

#'

#' @name module_snapshot_manager

#' @aliases snapshot snapshot_manager snapshot_manager_module

#'

#' @author Aleksander Chlebowski

#'

#' @rdname module_snapshot_manager

#' @keywords internal

#'

snapshot_manager_ui <- function(id) {

    ),

  )

}

#' @rdname module_snapshot_manager

#' @keywords internal

#'

snapshot_manager_srv <- function(id, slices_global, mapping_matrix, datasets) {

    # Set up bookmarking callbacks ----

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

    ))

    # Add current filter state to bookmark.

    # This is done on the app session because the value is restored in `module_teal`

    # and we don't want to have to use this module's name space there.

    })

    # Add snapshot history to bookmark.

    })

    # Track global filter states ----

      # Restore directly from bookmarked state, if applicable.

    })

    # Snapshot current application state ----

    # Name snaphsot.