# Quick Start with VizModules

## See the modules

Start with the hosted gallery to explore what each module can do: https://j-andrews7-VizModules.share.connect.posit.cloud/

You can also run the same gallery locally from this package:

    library(shiny)
    shiny::runApp(system.file("apps/module-gallery", package = "VizModules"))

## Drop a module into your app

All modules follow the same pattern: `*InputsUI()` for controls, `*OutputUI()` for the plot, and `*Server()` for the logic. Here is a minimal `scatterPlot` example:

    library(VizModules)

    ui <- fluidPage(
        sidebarLayout(
            sidebarPanel(
                dittoViz_scatterPlotInputsUI("cars",
                    mtcars,
                    defaults = list(
                        x.by = "wt",
                        y.by = "mpg",
                        color.by = "cyl"
                    )
                )
            ),
            mainPanel(dittoViz_scatterPlotOutputUI("cars"))
        )
    )

    server <- function(input, output, session) {
        dittoViz_scatterPlotServer("cars", data = reactive(mtcars))
    }

    shinyApp(ui, server)

## Set defaults and hide controls

- Defaults: Pass a named list to the `defaults` argument of `*InputsUI()` to pre-fill inputs. Names match the underlying plot function arguments (e.g., `defaults = list(fill.color = "steelblue")`).
- Hide inputs: Use `hide.inputs` in the server call to remove controls while still initializing their values. This is useful when your app sets certain parameters itself.
- Hide tabs: Use `hide.tabs` to remove whole groups of controls (e.g., `"Plotly"` or `"Legend"` in `scatterPlot`).

    dittoViz_scatterPlotServer(
        "cars",
        data = reactive(mtcars),
        hide.inputs = c("split.by", "rows.use"),
        hide.tabs = c("Plotly")
    )

Hidden inputs and tabs still feed their values into the plot, so the module stays fully configured while exposing only what your users need.

## App factory with `createModuleApp()`

To enable simple, consistent testing of any module, we provide an app factory function that returns a full standalone app with data import, a filterable data table, and dataset switching for any module - `createModuleApp()`:

    library(VizModules)

    app <- createModuleApp(
        inputs_ui_fn = plotthis_BarPlotInputsUI,
        output_ui_fn = plotthis_BarPlotOutputUI,
        server_fn    = plotthis_BarPlotServer,
        data_list    = list("cars" = mtcars),
        title        = "My Bar Plot"
    )
    if (interactive()) runApp(app)

All built-in `*App()` convenience functions (e.g. `plotthis_BarPlotApp()`, `linePlotApp()`) are thin wrappers around `createModuleApp()` with sensible default data. You can also pass custom wrapper module functions to `createModuleApp()` for rapid prototyping.

## Export Summary Data:

We provide `collect_source_data()` to assemble a compact record of the plotted data, stats, UI inputs, and the rendered plot, and `create_source_download_handler()` to turn that record into a downloadable `.zip`. `collect_source_data()` requires a reactive plotly plot; the output summary can be optionally enriched by both a stats reactive and a UI inputs reactive. `create_source_download_handler()` also accepts a named list of summaries (one per plot), which is how the Panel Builder bundles every plot on its canvas into a single download.

    if (interactive()) {
        library(shiny)
        library(plotly)

        ui <- fluidPage(
            plotlyOutput("plot"),
            downloadButton("download_summary", "Download Summary")
        )

        server <- function(input, output, session) {
            # A reactive plotly plot
            plot_reactive <- reactive({
                plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
            })

            # Optional: a reactive returning a stats data.frame
            stats_reactive <- reactive({
                data.frame(
                    metric = c("mean_mpg", "sd_mpg"),
                    value  = c(mean(mtcars$mpg), sd(mtcars$mpg))
                )
            })

            # Optional: capture all UI inputs as a named list
            AllInputs <- reactive({
                reactiveValuesToList(input)
            })

            output$plot <- renderPlotly(plot_reactive())

            # Assemble the summary, then wire up the download handler.
            plot_summary_reactive <- reactive({
                collect_source_data(
                    plot_reactive   = plot_reactive,
                    stats_reactive  = stats_reactive,
                    inputs_reactive = AllInputs()
                )
            })

            output$download_summary <- create_source_download_handler(
                data_list     = plot_summary_reactive,
                filename_base = "my_plot_summary"
            )
        }

        shinyApp(ui, server)
    }

## Which plot parameters are exposed?

Modules wrap plotting functions from dittoViz, plotthis, and native plotting functions. To see which arguments are available in a module:

1. Open the module input help page, e.g., `?dittoViz_scatterPlotInputsUI` or `?plotthis_AreaPlotInputsUI`. The Details section notes which arguments from the underlying plot function are wired through and any that are intentionally omitted.
2. Cross-reference the base plot documentation (`?dittoViz::scatterPlot`, `?plotthis::AreaPlot`, etc.). Input names in `defaults` line up with those function arguments when they are supported.

If an argument is listed as missing or non-functional in the module docs, it has been intentionally hidden because it does not round-trip well in the interactive Plotly output.