Adding a New Module

1. @section Plot parameters not implemented or with altered functionality:

List all parameters from the base plot function that are not exposed via UI inputs, with explanations:

#' @section Plot parameters not implemented or with altered functionality:
#' The following [plotthis::AreaPlot()] parameters are not available via UI inputs:
#' \itemize{
#'   \item \code{xlab} - X-axis label (plotly allows interactive editing)
#'   \item \code{ylab} - Y-axis label (plotly allows interactive editing)
#'   \item \code{title} - Plot title (plotly allows interactive editing)
#'   \item \code{subtitle} - Plot subtitle (not supported in plotly)
#'   \item \code{legend.position} - Legend positioning (plotly allows interactive repositioning)
#'   \item \code{split_by} - Split variable (returns a patchwork object, not supported in plotly)
#'   \item \code{palette} - Managed internally via the palette selection UI
#' }

2. @section Plot parameters and defaults:

Document all parameters that are exposed, listing their UI label and default value:

#' @section Plot parameters and defaults:
#' The following [plotthis::AreaPlot()] parameters can be accessed via UI inputs and/or the \code{defaults} argument:
#' \itemize{
#'   \item \code{x} - X-axis variable (UI: "X values", default: 2nd categorical variable)
#'   \item \code{y} - Y-axis variable (UI: "Y values", default: 2nd numeric variable)
#'   \item \code{group_by} - Grouping variable (UI: "Group by", default: 3rd categorical variable or "")
#'   \item \code{facet_by} - Faceting variable (UI: "Facet by", default: "")
#'   \item \code{theme} - ggplot2 theme (UI: "Theme", default: "theme_this")
#'   \item \code{alpha} - Area fill transparency (UI: "Alpha", default: 1)
#' }

3. @section Plot parameters implementing new functionality:

Document all module-specific parameters (plotly controls, reference lines, etc.):

#' The following parameters implementing new functionality or controlling plotly-specific features are also available:
#' \itemize{
#'   \item \code{axis.font.size} - Axis title font size (UI: "Axis font size", default: 18)
#'   \item \code{axis.showline} - Show axis border lines (UI: "Show axis lines", default: TRUE)
#'   \item \code{axis.tickfont.size} - Size of tick labels (UI: "Tick label size", default: 12)
#'   \item \code{hline.intercepts} - Y-coordinates for horizontal reference lines (UI: "Y-intercepts", default: "")
#'   \item \code{hline.colors} - Colors for horizontal lines, comma-separated (UI: "Colors", default: "#000000")
#'   \item \code{hline.linetypes} - Line types for horizontal lines, comma-separated (UI: "Line types", default: "dashed")
#'   \item \code{vline.intercepts} - X-coordinates for vertical reference lines (UI: "X-intercepts", default: "")
#'   \item \code{abline.slopes} - Slopes for diagonal reference lines (UI: "Slopes", default: "")
#' }

Note: Reference line parameters (hline.*, vline.*, abline.*) accept comma-separated values to control each line individually.

Inputs Rebuilt by renderUI()

Freezing does not cover an input your module rebuilds with renderUI(), such as a [multiColorPicker()] whose groups follow the data. A freeze pauses only the readers that run after it in that flush, and at startup the plot output runs first. The freeze lands too late to pause anything, and the value the freshly built input reports then rebuilds the plot for a mapping it was already drawing.

In short, this results in the plot being re-rendered one or more times in a way that can be annoying, particularly for large data sets.

Give the plot a server-side value to read instead, so the client’s echo is compared against what is already in use rather than against NULL. For a colour picker, setup_group_colors() does this for you — it resolves the mapping as soon as the group set is known and holds it in a reactiveVal(), which only invalidates on a real change:

• Create the store beside your group-levels reactive:

  palette_store <- setup_group_colors(
      input, "palette.colours", palette_groups,
      default_palette_values, defaults, params
  )

• Seed it inside the picker’s renderUI(), with the same colours the input itself is built from, so the mapping is right even when the render was deferred (a picker on a hidden tab is suspended until that tab is opened):

  initial_colors <- isolate(resolve_palette(
      groups, input$palette.colours, default_palette_values,
      .default_group_colors(defaults, "palette.colours")
  ))
  palette_store(initial_colors)

• Read the store in the plot reactive, in place of the raw input:

  palette_values <- isolate_fn(palette_store())   # not isolate_fn(input$palette.colours)

The same shape works for any renderUI()-rebuilt input: resolve the value on the server, hold it in a reactiveVal(), and have the plot read that.

Axis Limits

Limits behave the same way, and for the same reason: the module derives them on the server, pushes them into the y.min/y.max controls, and the echo of that push rebuilds the plot. setup_axis_range() is the store for them.

• Create the store, then seed it beside every update*Input() that sets the limits — the y-data observer and the Reset button:

  y_range_store <- setup_axis_range(input, session, params = params)
  
  observeEvent(input$y.data, {
      y_range <- .calculate_range(df = data(), data_col_y = input$y.data,
                                  axis_scale_factor = .y_axis_scale_factor)
      if (!is.null(y_range)) {
          y_range_store(list(min = y_range$min, max = y_range$max))
          updateNumericInput(session, "y.min", value = y_range$min)
          updateNumericInput(session, "y.max", value = y_range$max)
      }
  })

• Read isolate_fn(y_range_store()) in the plot reactive, in place of isolate_fn(input$y.min) and isolate_fn(input$y.max).

If your module draws significance brackets, pass headroom as well. The brackets are stacked above the data, so the limits have to clear them or they are drawn clipped; stat_bracket_y_max() works out how high they will reach, and the store raises the maximum to meet it and updates the control to match. It only ever raises, so a larger limit the user chose is left alone:

y_range_store <- setup_axis_range(
    input, session, params = params,
    headroom = function() {
        if (!isTRUE(input$stats.enabled)) {
            return(NULL)
        }
        .stat_bracket_headroom(
            df = data(), x = input$x.data, y = input$y.data,
            group.by = .blank_to_null(input$group.by),
            facet.by = .blank_to_null(input$facet.by),
            per.facet = isTRUE(input$stat.per.facet),
            input = input
        )
    }
)

Pass the resolved limits on to apply_stat_annotations() too, as y.min and y.max. It has the last word on the drawn range, and knowing what you asked for is what lets it leave a large maximum alone rather than shrinking the axis onto the brackets.

Server

• Near the top of your moduleServer() body, create a unique plotly event source for this module instance and the edit store:

  # Unique source so each module instance captures only its own events.
  plot_source <- session$ns("myplot")
  edit_store <- setup_manual_edits(input, session, plot_source)

• In your renderPlotly(), pass the freshly built figure through finalize_manual_edits() immediately before returning it:

  output$myPlot <- renderPlotly({
      req(input$x, input$y)
      fig <- generate_myPlot()  # your function that builds the plotly figure
      finalize_manual_edits(fig, plot_source, edit_store, session)
  })

Pretty simple.

setup_manual_edits() registers the observers that capture plotly_relayout events (legend, annotation, and axis-title drags) plus the JavaScript-forwarded colorbar drag; finalize_manual_edits() tags the figure with the event source, restores any captured edits, records the figure for stable annotation keying, and re-attaches the colorbar listener.

Edits are matched to annotations by a content-derived key, so they survive even when annotations are added, removed, or reordered between rebuilds (e.g. when statistical brackets or reference labels appear).

Key helpers (all in R/plot_helpers.R)

Both functions are exported, so the same two-step pattern works from a custom module in your own package. The supporting internals (.capture_manual_edits(), .reapply_manual_edits(), .add_colorbar_listener()) are not exported and shouldn’t need to be used directly (though you can always access them via VizModules::: if really necessary.

See any module server (e.g. dittoViz_scatterPlotServer) for a complete example.

UI

• Add a "Stats" tab to the module’s tabsetPanel containing .uniform_stats_inputs_ui(ns, defaults).

Server

• Create a reactiveVal to store the last computed stats table: last_stats_df <- reactiveVal(NULL).
• When input$stats.enabled is TRUE in the plot rendering block, call compute_pairwise_stats() to run tests, then create_stat_annotations() to build bracket shapes/annotations, then apply_stat_annotations() to append them to the plotly figure.
• Store the result: last_stats_df(stats_df).
• Add an observeEvent to update stat.pairs choices when the x or grouping column changes, using generate_pair_strings(), selecting .default_stat_pairs(defaults, pairs) so a stat.pairs default is honoured.
• Call .reset_stats_inputs(session, defaults, pairs) in the reset observer, with the pairs currently on offer.

Key helpers (all in R/stat_helper.R)

See the plotthis_BoxPlotServer, dittoViz_yPlotServer, or dittoViz_freqPlotServer implementations for complete integration examples.

Input Labels

• Capitalize the first word of every input label: "Group By", not "group by".
• Be concise — prefer short, scannable labels over long descriptions. Move detail into a tipify tooltip instead.
• Avoid redundant words. "Color" is better than "Select a Color".
• Match plotthis/dittoViz parameter names loosely, so users can cross-reference the upstream docs. E.g., label the group_by input "Group By".

Select Inputs

Use viz_select_input() rather than shiny::selectInput() or shiny::selectizeInput(), and update_viz_select() in place of their update*() counterparts. It takes the same inputId/label/choices/selected/multiple arguments, but renders a virtualised dropdown, so an input backed by a column with tens of thousands of distinct values stays usable. A search box appears automatically once there are more than ten choices.

An empty-string choice still means “no selection”; it is displayed as (none) so users can see and pick it.

viz_select_input(ns("group.by"), "Group By",
    choices = cat.choices,
    selected = get_default(defaults, "group.by", "", function(x) x %in% cat.choices)
)

Tooltips with tipify

Wrap any non-obvious input in shinyBS::tipify() to show a tooltip on hover. This keeps labels concise while still informing the user.

Apply tipify when:

• The input’s purpose is not immediately clear from its label alone.
• The input accepts a specific format that users might not guess (e.g., comma-separated values, index positions for categorical axes).
• The input has a non-trivial effect on the plot (e.g., stat correction methods, bracket inset).

Standard pattern — always use placement = "top" and options = list(container = "body") so tooltips render correctly inside sidebar panels:

tipify(
    textInput(ns("hline.intercepts"), "Y-intercepts",
        placeholder = "e.g. 2, -2",
        value = get_default(defaults, "hline.intercepts", "")
    ),
    paste(
        "For categorical or factor axes, enter the index (position) of the",
        "category rather than its name."
    ),
    placement = "top", options = list(container = "body")
)

Inputs that are self-explanatory from their label (e.g., "Plot Title", "X-axis Variable") do not need a tooltip.

Reuse Uniform Input Helpers

In time, these helpers will be further formalized and exported, but they can be used with the VizModules::: prefix in the meantime.

Before writing custom inputs, check whether a uniform helper already covers your needs:

Each UI helper has a matching reset_*_inputs() function to call from the module’s observeEvent(input$reset, ...) block.

Modules that draw individual points can adopt uniform_annotation_inputs_ui() to let users highlight and label points by the values of a chosen column. The server side needs the chosen column carried in the plot’s hover text (that is where the values are read back from), then .apply_highlight_styling() to restyle matching markers and .create_highlight_annotations()/.create_selected_annotations() to build the labels. Set require.markers = TRUE when other scatter traces are drawn from the same data (box or violin outlines, say) so only the point markers are matched. Append the resulting annotations to fig$x$layout$annotations rather than replacing them, or facet strip labels and statistical brackets will be lost.

Pass ns and a defaults list to each helper. Use the include.* arguments to opt in to optional groups (e.g., include.fit.lines = TRUE for scatter plots, include.rotate = TRUE for bar plots).

Using the uniform helpers ensures that shared inputs behave identically across every module and that future changes to those helpers propagate automatically.

Imports: @importFrom Over ::

• Always use @importFrom pkg fun in the roxygen header of any file that calls an external function, then call the function directly (fun()) in the body.
• Avoid pkg::fun() calls in module code.

The only exception is a one-off call in an @examples block or vignette where the full qualified name aids readability.

Additional Conventions

• Use 4-space indentation and keep lines to 120 characters max (enforced by .lintr).
• Avoid sapply() — use vapply() or lapply() with explicit types instead.
• Do not edit NAMESPACE manually; always regenerate with devtools::document().

Only ever style classes this package created

Anchor every selector on a package-owned prefix — .multi-color-picker, .mc-, .mdi-, .vizmodules-, .viz-, .pb-. Never write a bare rule against a class that belongs to Bootstrap, Shiny, selectize, DT or any other library:

/* WRONG — restyles every dropdown, well and tab strip in the host app */
.selectize-dropdown .option { padding: 0 !important; }
.well .btn { padding: 4px 10px; }
.nav-tabs { flex-wrap: wrap; }

/* RIGHT — reaches only markup this package rendered */
.mc-palette-dropdown .option { padding: 0 !important; }
.pb-app .well .btn { padding: 4px 10px; }
.vizmodules-input-tabs > .nav-tabs { flex-wrap: wrap; }

The trap is that these rules look scoped. .well .btn reads like “the buttons in my well” — but .well is what shiny::sidebarPanel() renders, so it is every sidebar on the page. If a selector’s leftmost class is not one you invented, it is not scoped.

tests/testthat/test-ui_utils.R enforces this: it parses every selector in every bundled and inline stylesheet and fails on anything not anchored to a package prefix. Add your widget’s prefix there if you introduce one.

A dropdown or popover parented to <body> needs its own marker class

Anything that escapes its container to avoid clipping — selectize’s dropdownParent: "body", a tooltip, a popper — can no longer be reached by a .my-widget .thing selector, which is exactly why the leaking rules were written unscoped in the first place. Give the escaped element a class of its own instead:

$(select).selectize({
  dropdownParent: "body",
  // Selectize replaces its default dropdownClass wholesale, so its own class
  // has to be restated alongside ours.
  dropdownClass: "selectize-dropdown mc-palette-dropdown",
  ...
});

Check that the rule matches what you think it does

.selectize-dropdown .option never matched the colour picker’s own options at all — its custom render.option emits .mc-palette-option, and selectize does not add .option to that. The rule’s only effect was on other people’s dropdowns: a selector that misses everything you own and hits everything you don’t. Open the widget, inspect the element, and confirm the class you are targeting is actually on it.

Keep layout out of inline styles

An inline style= attribute can only be overridden with !important, which makes a host app fight your widget rather than theme it. Put layout in a stylesheet and pass only the values that vary per instance, as CSS custom properties:

# organize_inputs() emits just the column count; the rest lives in vizModules.css
div(
    class = "vizmodules-input-grid",
    style = paste0("--viz-input-columns: ", columns, ";"),
    lapply(cells, function(x) div(class = "vizmodules-input-cell", x))
)

Do not assume anything about the parent

The control grid used Bootstrap’s negative-margin row idiom (margin-left: -15px on the row, matching padding on each cell), which assumes a parent with at least that much horizontal padding to absorb it. Dropped into a bslib::sidebar() with less, the grid overhung on both sides and the sidebar grew a horizontal scrollbar. Use gap instead — it needs nothing from the parent.

Give flex children min-width: 0 as well. Without it a long select or label refuses to shrink below its intrinsic width and pushes the container wider — the same overflow by a different route.

Shipping a stylesheet

Put it in inst/src/, serve it through an htmlDependency(), and attach it to the UI that needs it rather than to the app as a whole:

.viz_modules_dependency <- function() {
    htmlDependency(
        name = "viz-modules",
        version = as.character(utils::packageVersion("VizModules")),
        src = "src", package = "VizModules",
        stylesheet = "vizModules.css"
    )
}

Attaching it with htmltools::attachDependencies(ui, dep, append = TRUE) means the styles travel with the markup — including through a runtime insertUI(), which the Figure Builder relies on when it injects a panel’s controls.

Verifying containment

Automated checks catch an unscoped selector, but not whether your rule actually changed anything. To see the real effect, load the widget beside a stock selectInput(), sidebarPanel() and DT::datatable(), then disable just your stylesheet in the browser and re-measure:

document.querySelectorAll('link[rel=stylesheet]').forEach(function (l) {
  if (l.href.indexOf('yourFile.css') !== -1) { l.disabled = true; }
});

If a computed style on the host’s own controls changes, your CSS is leaking. If nothing in your widget changes, your rule was never matching in the first place.

safe_eval_filter(expr_text, data)

Use when a module evaluates a user-typed filter expression directly to produce a logical vector for row subsetting. The expression is parsed, its AST is walked to ensure only allowed operations are present (comparisons, logical operators, column references, and literals), and then it is evaluated in a restricted environment containing only the data frame’s columns.

# In a module server — filtering rows by a textInput:
rows.use = safe_eval_filter(isolate_fn(input$rows.use), data())

Returns a logical vector (same length as nrow(data)), or NULL if the input is empty, unparseable, or contains disallowed operations.

validate_expression(expr_text, col_names)

Use when a module passes a user-typed expression string through to a downstream plotting function that will evaluate it internally (e.g., plotthis::BoxPlot(highlight = ...)). The string is validated but not executed.

# In a module server — passing a highlight expression to plotthis:
highlight <- validate_expression(isolate_fn(input$highlight), names(data()))

Returns the original string if safe, or NULL.

safe_resolve_adj_fxn(fn_name)

Use when a module resolves a function name from a dropdown or text input into an actual function reference (e.g., for x.adj.fxn, y.adj.fxn). Only function names in the allowed list ("log2", "log", "log10", "neg_log10", "log1p", "as.factor", "abs", "sqrt") are accepted.

# In a module server — resolving an adjustment function:
x.adj.fxn = safe_resolve_adj_fxn(isolate_fn(input$x.adj.fxn))

Returns the function, or NULL if the name is empty or not in the allowed list.

What counts as “allowed”?

safe_eval_filter() and validate_expression() share one whitelist of safe AST nodes:

• Comparisons: <, >, <=, >=, ==, !=
• Logical operators: &, &&, |, ||, !, xor()
• Utilities: %in%, c(), is.na(), is.null()
• Arithmetic: -, +, *, /, :, %%, abs(), round()
• Strings and patterns: grepl(), startsWith(), endsWith(), substr(), nchar(), toupper(), tolower(), trimws()
• Grouping: ()
• Column names from the data
• Literals: numbers, strings, TRUE, FALSE, NA, NULL, Inf, NaN

Anything outside this list (including function calls like system(), file.remove(), library(), etc.) is rejected and a warning is issued. So is a namespaced or extracted call such as base::log(x), which would otherwise slip past a name-based check.

The expression must also be a single statement: anything after a ; or a newline is rejected rather than silently ignored.

safe_resolve_adj_fxn() is the exception — it does not walk an AST at all. It matches the whole input against its own short list of numeric transforms (log2, log, log10, neg_log10, log1p, as.factor, abs, sqrt) and resolves it with match.fun().

Model formulas (.safe_build_model(), behind the custom fit lines) reuse the same walker with a formula-specific vocabulary: ~, +, -, *, /, ^, (, :, I(), and the transforms log(), log2(), log10(), sqrt(), exp(), poly().