% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/focusmap.R
\name{focus_map}
\alias{focus_map}
\alias{focusmapOutput}
\alias{renderFocusmap}
\title{Interactive focus-map viewer}
\usage{
focus_map(
  x,
  label_col = NULL,
  id_col = NULL,
  group_col = NULL,
  group_palette = NULL,
  context_col = NULL,
  context_values = "context",
  context_mode = c("fade", "hide", "show"),
  context_fill = "#cfd9df",
  context_opacity = 0.18,
  context_clickable = FALSE,
  focus_preset = c("none", "municipal", "drilldown", "municipal_drilldown"),
  simplify = TRUE,
  fill = "#2d6ea3",
  fill_opacity = 0.58,
  stroke = "#ffffff",
  lift_scale = 1.16,
  focus_padding = 40,
  focus_size = 0.76,
  min_focus_width = 0,
  min_focus_height = 0,
  tiny_feature_threshold = 48,
  tiny_feature_boost = 1,
  max_zoom = NULL,
  origin_context = c("none", "socket", "inset", "both"),
  origin_context_position = c("bottom-left", "bottom-right", "top-left", "top-right"),
  focus_context_opacity = 0.3,
  show_drag_zoom = FALSE,
  font_size = 14,
  show_labels = TRUE,
  show_sidebar = TRUE,
  performance_mode = NULL,
  info_cols = NULL,
  info_labels = NULL,
  info_title = NULL,
  info_position = c("top-right", "top-left", "bottom-right", "bottom-left"),
  info_card_scale = 1,
  area_min = 5000,
  width_min = 95,
  height_min = 28,
  width = "100\%",
  height = "600px",
  elementId = NULL
)

focusmapOutput(outputId, width = "100\%", height = "600px")

renderFocusmap(expr, env = parent.frame(), quoted = FALSE)
}
\arguments{
\item{x}{An \code{sf}, \code{exploded_map}, or
\code{grouped_exploded_map} object.}

\item{label_col}{Character. Column name for polygon labels.
Auto-detected if \code{NULL}.}

\item{id_col}{Optional stable feature ID column for Shiny selection events.
Defaults to row order if \code{NULL}.}

\item{group_col}{Character. Optional column for region/group
colouring. Polygons sharing a group value share a hue.}

\item{group_palette}{Optional named character vector of colours for
\code{group_col} values. Names should match group values; unmatched groups
fall back to the widget palette.}

\item{context_col}{Optional column identifying features that should remain
as geographic context rather than active focus features.}

\item{context_values}{Character vector of values in \code{context_col} that mark
context features. Default \code{"context"}.}

\item{context_mode}{How context features are drawn: \code{"fade"} keeps them
visible but muted, \code{"hide"} makes them invisible, and \code{"show"} draws them
normally.}

\item{context_fill}{Fill colour for context features when
\code{context_mode = "fade"}.}

\item{context_opacity}{Fill opacity for faded context features.}

\item{context_clickable}{Should context features remain clickable? Default
\code{FALSE}.}

\item{focus_preset}{Optional named preset for common interactive workflows.
\code{"municipal"} tunes small-area focus, source cues, drag zoom, and dense
layer performance. \code{"drilldown"} tunes context fading and source cues for
selected-section maps. \code{"municipal_drilldown"} combines both. Explicit
arguments supplied by the user override preset defaults.}

\item{simplify}{Controls geometry simplification for rendering
performance. \code{TRUE} (default) applies a sensible tolerance
(\code{dTolerance = 0.001} in WGS 84 degrees, \eqn{\approx}
100 m). A positive number sets a custom tolerance. \code{FALSE}
disables simplification. Only affects the widget copy — the
original data is never modified.}

\item{fill}{Fill colour (used when \code{group_col} is \code{NULL}).
Default \code{"#2d6ea3"}.}

\item{fill_opacity}{Fill opacity. Default \code{0.58}.}

\item{stroke}{Stroke colour. Default \code{"#ffffff"}.}

\item{lift_scale}{Initial toast lift scale. Default \code{1.16}.
Increase this to make the lifted feature larger.}

\item{focus_padding}{Extra screen-space padding in pixels around the lifted
feature during focus. Increase this if large lifted features feel too
close to the map edge.}

\item{focus_size}{Target fraction of the map viewport the lifted feature
may occupy. Increase this to make selected areas appear larger while
preserving \code{focus_padding}.}

\item{min_focus_width, min_focus_height}{Minimum focused feature width and
height in screen pixels. When a selected feature is very small, the widget
may zoom past the usual density-aware default until the lifted feature
reaches these dimensions. Set to \code{0} to disable either constraint.}

\item{tiny_feature_threshold}{Screen-pixel size below which a selected
feature receives an adaptive lift-scale boost. Set to \code{0} to disable.}

\item{tiny_feature_boost}{Maximum multiplier applied to \code{lift_scale}
for the smallest features. Values below \code{1} are not allowed.}

\item{max_zoom}{Optional maximum camera zoom. If \code{NULL}, a density-aware
default is used.}

\item{origin_context}{How the selected feature's source location should be
shown while focused. The default \code{"none"} keeps focus maps visually
unchanged unless this feature is explicitly enabled. \code{"socket"} keeps
the source outline in the main
map, \code{"inset"} shows a small overview map, \code{"both"} uses both,
and \code{"none"} disables the cue.}

\item{origin_context_position}{Position for the overview inset:
\code{"bottom-left"}, \code{"bottom-right"}, \code{"top-left"}, or
\code{"top-right"}.}

\item{focus_context_opacity}{Fill opacity for non-selected features while a
feature is focused. Lower values make tiny selected areas easier to read.}

\item{show_drag_zoom}{Show a widget-level drag-zoom toggle. When enabled,
users can draw a marquee rectangle to zoom into dense clusters while
ordinary feature clicks continue to focus the map. Shift-drag works as a
shortcut even when the button is hidden.}

\item{font_size}{Label font size in px. Default \code{14}.}

\item{show_labels}{Show labels on lifted shapes? Default \code{TRUE}.}

\item{show_sidebar}{Deprecated and has no effect. Will be removed in a
future version.}

\item{performance_mode}{Logical or \code{NULL}. If \code{NULL}, dense
layers automatically use shorter camera transitions and lighter
in-flight rendering. Set \code{TRUE} to force it or \code{FALSE} to
disable it.}

\item{info_cols}{Optional character vector of columns to show in a
non-blocking focus card when a feature is selected.}

\item{info_labels}{Optional named character vector or list for display
labels in the focus card. Names should match \code{info_cols}.}

\item{info_title}{Optional column to use as the focus card title. Defaults
to \code{label_col}.}

\item{info_position}{Position for the focus card: \code{"top-right"},
\code{"top-left"}, \code{"bottom-right"}, or \code{"bottom-left"}.}

\item{info_card_scale}{Relative size for the focus card. Values above
\code{1} make the card larger; values below \code{1} make it more compact.}

\item{area_min}{Min screen area (px^2) for label visibility.}

\item{width_min}{Min screen width (px) for label visibility.}

\item{height_min}{Min screen height (px) for label visibility.}

\item{width}{Widget width. Default \code{"100\%"}.}

\item{height}{Widget height. Default \code{"600px"}.}

\item{elementId}{Optional element ID.}

\item{outputId}{Shiny output ID.}

\item{expr}{Expression that returns a \code{focus_map()} widget.}

\item{env}{Environment in which to evaluate \code{expr}.}

\item{quoted}{Logical. Is \code{expr} already quoted?}
}
\value{
An \code{htmlwidgets} object.
}
\description{
Renders spatial features as a smooth, interactive SVG map. Click any
polygon to zoom in and lift it from the map with a "toast" effect;
right-click or press Escape to reset. Camera transitions use D3's
optimal zoom interpolation for fluid 60 fps motion with zero server
round-trips.
}
\details{
Accepts raw \code{sf} objects, \code{exploded_map} results from
\code{\link{explode_sf}}, or \code{grouped_exploded_map} results from
\code{\link{explode_grouped}}. For exploded objects, the displaced
(WGS 84) geometry is used automatically.
}
\examples{
\donttest{
poly <- function(xmin, ymin, xmax, ymax) {
  sf::st_polygon(list(rbind(
    c(xmin, ymin), c(xmax, ymin), c(xmax, ymax),
    c(xmin, ymax), c(xmin, ymin)
  )))
}

counties <- sf::st_sf(
  NAME = c("A", "B"),
  region = c("North", "South"),
  geometry = sf::st_sfc(
    poly(-74.2, 40.0, -74.0, 40.2),
    poly(-73.9, 40.0, -73.7, 40.2),
    crs = 4326
  )
)

focus_map(counties, label_col = "NAME", group_col = "region")
}

}
