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

      }

    })

  })

}

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

  }

}

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