% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paintr-input-spec.R
\name{ptr_id_table}
\alias{ptr_id_table}
\title{Enumerate every Shiny id a ggpaintr formula produces}
\usage{
ptr_id_table(formula, id = NULL)
}
\arguments{
\item{formula}{A single ggpaintr formula string (the same input you
would pass to \code{ptr_app()} / \code{ptr_server()}).}

\item{id}{Optional outer namespace — the same string you pass to
\code{ptr_server(formula, id = ...)}. When supplied, rows whose \code{scope}
is \code{"instance"} come back with that namespace prefixed
(\verb{<id>-<raw>}); \code{"global"} rows stay bare. When \code{NULL}, every row
shows its bare id.}
}
\value{
A \code{data.frame} with one row per Shiny id and ten columns:
\itemize{
\item \code{id} — the Shiny id (prefixed when \verb{id=} is given and
\code{scope == "instance"}).
\item \code{kind} — \code{"input_widget"} or \code{"output_slot"}.
\item \code{role} — semantic role: \code{"placeholder"}, \code{"source_companion"},
\code{"layer_checkbox"}, \code{"layer_subtab"}, \code{"layer_content"},
\code{"stage_enabled"}, \code{"ptr_plot"}, \code{"ptr_error"}, \code{"ptr_code"},
\code{"ptr_code_mode"}, \code{"ptr_update_plot"}.
\item \code{scope} — \code{"instance"} (namespaced via \code{shiny::NS(id)}) or
\code{"global"} (un-namespaced; only used by cross-formula shared-panel
keys in a \code{ptr_shared()} setup — see Single-formula section).
\item \code{include_in_ui} — \code{TRUE} when the row is something the user
\emph{places} in their custom UI; \code{FALSE} when the server populates
it inside a sleeve (\verb{<id>_ui}) and the user must not place it
manually. The two \code{FALSE} cases are the inner placeholder widget
and \code{ppUpload}'s file-name companion.
\item \code{layer} — layer name (\code{"ggplot"}, \code{"geom_point"}, …) or \code{NA}.
\item \code{keyword} — placeholder keyword (\code{"ppVar"}/\code{"ppText"}/…) or \code{NA}.
\item \code{param} — argument or aesthetic name (\code{"x"}, \code{"color"}, \code{"data"},
…) or \code{NA}.
\item \code{parent_call} — immediate enclosing call (\code{"aes"}, \code{"head"}, or
the layer itself when the placeholder is a direct layer arg) or
\code{NA}.
\item \code{shared} — shared key (\code{"xcol"}, …) or \code{NA}.
}
}
\description{
Walks the typed AST of a single formula and returns one row per Shiny
id ever rendered by \code{\link[=ptr_ui]{ptr_ui()}} / \code{\link[=ptr_server]{ptr_server()}} for that formula:
placeholder sleeves, inner widgets, source companions, layer-level
controls (checkbox, subtab, content container), pipeline stage
toggles, plus the static infrastructure ids (\code{ptr_plot}, \code{ptr_error},
\code{ptr_code}, \code{ptr_code_mode}, \code{ptr_update_plot}).
}
\details{
Advanced (L3) users call this to build their own UI by hand and still
get the server's bindings to match. The default-layout L2 path does
not need it; \code{ptr_ui()} emits these ids internally.
}
\section{Stability under formula edits}{

Adding a layer at the end keeps existing ids stable. Reordering
arguments inside \code{aes()} or a pipeline shifts positional paths and
therefore changes ids; renaming a placeholder keyword or its
\verb{shared=} annotation also changes ids.
}

\section{Single-formula}{

\code{ptr_id_table()} accepts a single formula. In multi-instance
(\verb{ptr_shared(formulas = list(…))}) layouts the partition rule
decides whether \verb{shared_<key>} lives in an instance's inline section
or the cross-formula panel. The \code{scope} column reflects the
single-formula interpretation (\code{"instance"}); when embedding into a
shared-panel context those rows are bare (\code{"global"}) and you should
override accordingly.
}

\examples{
ptr_id_table("ggplot(ppUpload, aes(x = ppVar, y = ppVar)) + geom_point(color = ppText)")
ptr_id_table("ggplot(ppUpload, aes(x = ppVar))", id = "myplot")
}
