Off-by-default layer wrapper

ADR-0020 structural keyword that marks a layer as off-by-default in ptr_app(). Inside ptr_app() / ptr_server() the parser sees the wrapper and unwraps it at translate time, stamping the boot-state metadata on the resulting node: ppLayerOff(layer_expr, hide = TRUE) becomes a ptr_layer with default_active = FALSE. The wrapper itself never appears in the typed tree.

Usage

ppLayerOff(layer_expr, hide = TRUE)

Arguments

layer_expr

A ggplot2 layer expression (e.g. geom_point(), facet_wrap(~ cyl)). Evaluated only when hide = FALSE.

hide

A length-1 logical literal (TRUE or FALSE). In ptr_app() formulas this MUST be a literal — the translator aborts on a non-literal so the formula remains the single source of truth for the app's boot state. Defaults to TRUE.

Value

Outside ptr_app(): NULL when hide = TRUE, otherwise the evaluated layer_expr.

Details

Outside ptr_app() it behaves per its R semantics so naked-ggplot scripts still render: ppLayerOff(geom_point(), TRUE) returns NULL (so ggplot(mtcars, aes(x = mpg, y = wt)) + ppLayerOff(geom_point(), TRUE) renders without the hidden layer); ppLayerOff(geom_point(), FALSE) returns the layer.

For the pipeline-stage sibling that exposes a user-toggleable checkbox (ADR-0021), see ppVerbSwitch().

Examples

library(ggplot2)
# Naked-R semantics: hide = TRUE drops the layer to NULL.
p1 <- ggplot(mtcars, aes(x = mpg, y = wt)) +
  ppLayerOff(geom_point(), TRUE)        # equivalent to no geom_point
p2 <- ggplot(mtcars, aes(x = mpg, y = wt)) +
  ppLayerOff(geom_point(), FALSE)       # the layer is added

# Inside ptr_app(), the wrapper becomes a node-level default and a
# boot-state-off checkbox:
if (interactive()) {
  ptr_app(ggplot() + ppLayerOff(geom_point(aes(x = mpg, y = wt)), TRUE))
}