Create a dragmapr state object — d

A dragmapr_state stores the mutable, editorial layout of a draggable map separately from the source geometry and from display options. It is the shared composition contract handed between layout producers (such as explodemap::as_dragmapr_state()), the interactive editor, and static renderers.

Usage

d_state(
  level = "region",
  region_col = NULL,
  label_id_col = NULL,
  region_offsets = NULL,
  label_offsets = NULL,
  expanded_groups = character(),
  view = NULL,
  version = 0L,
  crs = NULL,
  geometry_id = NULL,
  selected_feature = NULL,
  styles = NULL,
  binding = NULL,
  schema_version = "1.2.0",
  package_version = as.character(utils::packageVersion("dragmapr"))
)

Arguments

level: Character label for the active geography level.
region_col: Source-geometry column used to join region_offsets$region back to features. Defaults to level for old/simple states, but should be set explicitly for saved projects and package handoffs.
label_id_col: Source or label-table column identifying draggable labels.
region_offsets: Data frame with region, dx_m, and dy_m.
label_offsets: Data frame with label_id, region, dx_m, and dy_m.
expanded_groups: Character vector of expanded parent groups.
view: Optional list describing the client view, such as scale and translation.
version: Integer state revision.
crs: Optional coordinate reference system the metre offsets are expressed in. Accepts anything sf::st_crs() understands (an EPSG code, a PROJ/WKT string, or a crs object). Stored as an EPSG integer when available, otherwise as a WKT string, so it round-trips through JSON. Because dx_m/dy_m are only meaningful in a projected CRS, recording it here makes a saved state safe to reapply in a later session.
geometry_id: Optional single string identifying the geometry this state was composed against (provenance / binding tag). Lets a downstream consumer detect when a state is being applied to a different dataset than it was authored for.
selected_feature: Optional single string naming the feature currently selected in a dashboard or editor. Carried so a composition can be restored with focus intact.
styles: Optional keyed feature-style table created by d_styles(). Styles are editorial overrides, not thematic classification rules.
binding: Optional list of binding metadata. When supplied, binding$region_col and binding$label_id_col are used as defaults for the corresponding top-level arguments.
schema_version: State schema version. Stored with JSON snapshots so future migrations can read older projects.
package_version: Package version that created the state.

Value

An object of class "dragmapr_state".

Details

The state is deliberately geometry-free: it carries deltas, not absolute geometry, and is bound to features at apply time via a join key. That key is recorded in region_col, while level remains the human geography level label. For durable round-trips prefer a stable code (e.g. a FIPS/ISO id) over a display name, and record which geometry the state was composed against with geometry_id.