# 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/Scale"` 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.

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