Editing state: nudge, snap, and undo • dragmapr

A dragmapr_state is an editable composition object: region and label offsets can be adjusted from R as well as in the browser. This vignette covers the small scripted-editing helpers – nudging one offset, snapping a whole layout to a grid, validating a state, and keeping an undo/redo history while you work.

library(dragmapr)

state <- d_state(
  region_offsets = data.frame(
    region = c("A", "B"),
    dx_m = c(1234, -567),
    dy_m = c(89, 42)
  )
)

Nudge one offset

d_nudge() adds a delta on top of the current offset, like dragging a region or label slightly in the browser. It returns an updated state with a bumped version; the input state is unchanged.

nudged <- d_nudge(state, "A", dx_m = 500, dy_m = -100)
nudged$region_offsets
#>   region dx_m dy_m
#> 1      A 1734  -11
#> 2      B -567   42

label_state <- d_state(
  label_offsets = data.frame(
    label_id = "lbl-a", region = "A", dx_m = 10, dy_m = 20
  )
)
d_nudge(label_state, "lbl-a", dx_m = -5, target = "label")$label_offsets
#>   label_id region dx_m dy_m
#> 1    lbl-a  lbl-a    5   20

Snap a layout to a grid

d_snap_offsets() rounds every region and label offset to the nearest multiple of grid, tidying a hand-dragged layout into even increments.

snapped <- d_snap_offsets(state, grid = 1000)
snapped$region_offsets
#>   region  dx_m dy_m
#> 1      A  1000    0
#> 2      B -1000    0

Validate a state

d_validate_state() returns TRUE for a valid state and throws an informative error otherwise, so it works directly in assertions.

d_validate_state(snapped)
#> [1] TRUE

Undo and redo

d_history() creates an undo/redo stack. Push a checkpoint after each meaningful edit; d_undo() steps back and d_redo() steps forward. Pushing a new checkpoint clears the redo stack, like a text editor.

h <- d_history()
d_history_push(h, state)
d_history_push(h, nudged)
d_history_push(h, snapped)

back <- d_undo(h)  # nudged offsets again
back$region_offsets$dx_m
#> [1] 1734 -567

fwd <- d_redo(h)   # snapped offsets again
fwd$region_offsets$dx_m
#> [1]  1000 -1000

# Branching clears the redo stack.
branched <- d_nudge(back, "B", dx_m = 2000)
d_history_push(h, branched)

The history object has reference semantics, so the push/undo/redo calls modify it in place – reassignment is optional.