feat: refactor maplibre for reactive signals and Via-native API

- Export Signal type (signal → Signal) so subpackages can reference it - Expose viewport signals as public fields (CenterLng, CenterLat, Zoom, Bearing, Pitch) for .Text() display and .Bind() usage - Add signal-backed marker positions (LngSignal/LatSignal) with data-effect reactivity for server push and dragend writeback - Add event system (MapEvent, OnClick, OnLayerClick, OnMouseMove, OnContextMenu) using hidden inputs + action triggers - Add Source interface replacing type-switch, with RawSource escape hatch - Add CameraOptions for FlyTo/EaseTo/JumpTo/FitBounds/Stop - Add Control interface with NavigationControl, ScaleControl, GeolocateControl, FullscreenControl - Expand Options with interaction toggles, MaxBounds, and Extra map - Add effectspike example to validate data-effect with server-pushed signals - Update maplibre example to showcase all new features
2026-02-20 05:11:22 -10:00
parent 47dcab8fea
commit 7eb86999b2
12 changed files with 724 additions and 146 deletions
--- a/maplibre/js.go
+++ b/maplibre/js.go
@@ -36,8 +36,9 @@ func initScript(m *Map) string {
 		jsonStr(m.id),
 	))

+	// Build constructor options object
 	b.WriteString(fmt.Sprintf(
-		`var map=new maplibregl.Map({container:%s,style:%s,center:[%s,%s],zoom:%s`,
+		`var opts={container:%s,style:%s,center:[%s,%s],zoom:%s`,
 		jsonStr("_vmap_"+m.id),
 		jsonStr(m.opts.Style),
 		formatFloat(m.opts.Center.Lng),
@@ -56,14 +57,49 @@ func initScript(m *Map) string {
 	if m.opts.MaxZoom != 0 {
 		b.WriteString(fmt.Sprintf(`,maxZoom:%s`, formatFloat(m.opts.MaxZoom)))
 	}
-	b.WriteString(`});`)

+	// Interaction toggles
+	writeBoolOpt := func(name string, val *bool) {
+		if val != nil {
+			if *val {
+				b.WriteString(fmt.Sprintf(`,%s:true`, name))
+			} else {
+				b.WriteString(fmt.Sprintf(`,%s:false`, name))
+			}
+		}
+	}
+	writeBoolOpt("scrollZoom", m.opts.ScrollZoom)
+	writeBoolOpt("boxZoom", m.opts.BoxZoom)
+	writeBoolOpt("dragRotate", m.opts.DragRotate)
+	writeBoolOpt("dragPan", m.opts.DragPan)
+	writeBoolOpt("keyboard", m.opts.Keyboard)
+	writeBoolOpt("doubleClickZoom", m.opts.DoubleClickZoom)
+	writeBoolOpt("touchZoomRotate", m.opts.TouchZoomRotate)
+	writeBoolOpt("touchPitch", m.opts.TouchPitch)
+	writeBoolOpt("renderWorldCopies", m.opts.RenderWorldCopies)
+
+	if m.opts.MaxBounds != nil {
+		b.WriteString(fmt.Sprintf(`,maxBounds:[[%s,%s],[%s,%s]]`,
+			formatFloat(m.opts.MaxBounds.SW.Lng), formatFloat(m.opts.MaxBounds.SW.Lat),
+			formatFloat(m.opts.MaxBounds.NE.Lng), formatFloat(m.opts.MaxBounds.NE.Lat)))
+	}
+
+	b.WriteString(`};`)
+
+	// Merge Extra options
+	if len(m.opts.Extra) > 0 {
+		extra, _ := json.Marshal(m.opts.Extra)
+		b.WriteString(fmt.Sprintf(`Object.assign(opts,%s);`, string(extra)))
+	}
+
+	b.WriteString(`var map=new maplibregl.Map(opts);`)
 	b.WriteString(`if(!window.__via_maps)window.__via_maps={};`)
 	b.WriteString(fmt.Sprintf(`window.__via_maps[%s]=map;`, jsonStr(m.id)))
-	b.WriteString(`map._via_markers={};map._via_popups={};`)
+	b.WriteString(`map._via_markers={};map._via_popups={};map._via_controls={};`)

-	// Pre-render sources, layers, markers, popups run on 'load'
-	if len(m.sources) > 0 || len(m.layers) > 0 || len(m.markers) > 0 || len(m.popups) > 0 {
+	// Pre-render sources, layers, markers, popups, controls run on 'load'
+	hasLoad := len(m.sources) > 0 || len(m.layers) > 0 || len(m.markers) > 0 || len(m.popups) > 0 || len(m.controls) > 0
+	if hasLoad {
 		b.WriteString(`map.on('load',function(){`)
 		for _, src := range m.sources {
 			b.WriteString(fmt.Sprintf(`map.addSource(%s,%s);`, jsonStr(src.id), src.js))
@@ -76,14 +112,22 @@ func initScript(m *Map) string {
 			}
 		}
 		for _, me := range m.markers {
-			b.WriteString(markerBodyJS(me.id, me.marker))
+			b.WriteString(markerBodyJS(m.id, me.id, me.marker))
 		}
 		for _, pe := range m.popups {
 			b.WriteString(popupBodyJS(pe.id, pe.popup))
 		}
+		for _, ce := range m.controls {
+			b.WriteString(controlBodyJS(ce.id, ce.ctrl))
+		}
 		b.WriteString(`});`)
 	}

+	// Event listeners
+	for _, ev := range m.events {
+		b.WriteString(eventListenerJS(m.id, ev))
+	}
+
 	// Sync viewport signals on moveend via hidden inputs
 	b.WriteString(fmt.Sprintf(`map.on('moveend',function(){`+
 		`var c=map.getCenter();`+
@@ -100,11 +144,11 @@ func initScript(m *Map) string {
 		`});`+
 		`});`,
 		jsonStr("_vwrap_"+m.id),
-		jsonStr(m.centerLng.ID()),
-		jsonStr(m.centerLat.ID()),
-		jsonStr(m.zoom.ID()),
-		jsonStr(m.bearing.ID()),
-		jsonStr(m.pitch.ID()),
+		jsonStr(m.CenterLng.ID()),
+		jsonStr(m.CenterLat.ID()),
+		jsonStr(m.Zoom.ID()),
+		jsonStr(m.Bearing.ID()),
+		jsonStr(m.Pitch.ID()),
 	))

 	// ResizeObserver for auto-resize
@@ -132,8 +176,7 @@ func initScript(m *Map) string {
 }

 // markerBodyJS generates JS to add a marker, assuming `map` is in scope.
-// Used inside the init script's load callback.
-func markerBodyJS(markerID string, mk Marker) string {
+func markerBodyJS(mapID, markerID string, mk Marker) string {
 	var b strings.Builder
 	opts := "{"
 	if mk.Color != "" {
@@ -143,16 +186,61 @@ func markerBodyJS(markerID string, mk Marker) string {
 		opts += `draggable:true,`
 	}
 	opts += "}"
-	b.WriteString(fmt.Sprintf(`var mk=new maplibregl.Marker(%s).setLngLat([%s,%s]);`,
-		opts, formatFloat(mk.LngLat.Lng), formatFloat(mk.LngLat.Lat)))
+
+	// Determine initial position
+	if mk.LngSignal != nil && mk.LatSignal != nil {
+		b.WriteString(fmt.Sprintf(`var mk=new maplibregl.Marker(%s).setLngLat([%s,%s]);`,
+			opts, mk.LngSignal.String(), mk.LatSignal.String()))
+	} else {
+		b.WriteString(fmt.Sprintf(`var mk=new maplibregl.Marker(%s).setLngLat([%s,%s]);`,
+			opts, formatFloat(mk.LngLat.Lng), formatFloat(mk.LngLat.Lat)))
+	}
+
 	if mk.Popup != nil {
 		b.WriteString(popupConstructorJS(*mk.Popup, "pk"))
 		b.WriteString(`mk.setPopup(pk);`)
 	}
 	b.WriteString(fmt.Sprintf(`mk.addTo(map);map._via_markers[%s]=mk;`, jsonStr(markerID)))
+
+	// Dragend → signal writeback
+	if mk.Draggable && mk.LngSignal != nil && mk.LatSignal != nil {
+		b.WriteString(dragendHandlerJS(mapID, markerID, mk))
+	}
+
 	return b.String()
 }

+// dragendHandlerJS generates JS that writes marker position back to signal hidden inputs on dragend.
+func dragendHandlerJS(mapID, markerID string, mk Marker) string {
+	return fmt.Sprintf(
+		`mk.on('dragend',function(){`+
+			`var pos=mk.getLngLat();`+
+			`var el=document.getElementById(%[1]s);if(!el)return;`+
+			`var inputs=el.querySelectorAll('input[data-bind]');`+
+			`inputs.forEach(function(inp){`+
+			`var sig=inp.getAttribute('data-bind');`+
+			`if(sig===%[2]s){inp.value=pos.lng;inp.dispatchEvent(new Event('input',{bubbles:true}))}`+
+			`if(sig===%[3]s){inp.value=pos.lat;inp.dispatchEvent(new Event('input',{bubbles:true}))}`+
+			`});`+
+			`});`,
+		jsonStr("_vwrap_"+mapID),
+		jsonStr(mk.LngSignal.ID()),
+		jsonStr(mk.LatSignal.ID()),
+	)
+}
+
+// markerEffectExpr generates a data-effect expression that moves a signal-backed marker
+// when its signals change.
+func markerEffectExpr(mapID, markerID string, mk Marker) string {
+	return fmt.Sprintf(
+		`var m=window.__via_maps&&window.__via_maps[%s];`+
+			`if(m&&m._via_markers[%s]){`+
+			`m._via_markers[%s].setLngLat([$%s,$%s])}`,
+		jsonStr(mapID), jsonStr(markerID), jsonStr(markerID),
+		mk.LngSignal.ID(), mk.LatSignal.ID(),
+	)
+}
+
 // addMarkerJS generates a self-contained IIFE to add a marker post-render.
 func addMarkerJS(mapID, markerID string, mk Marker) string {
 	var b strings.Builder
@@ -163,7 +251,7 @@ func addMarkerJS(mapID, markerID string, mk Marker) string {
 	b.WriteString(fmt.Sprintf(
 		`if(map._via_markers[%[1]s]){map._via_markers[%[1]s].remove();delete map._via_markers[%[1]s];}`,
 		jsonStr(markerID)))
-	b.WriteString(markerBodyJS(markerID, mk))
+	b.WriteString(markerBodyJS(mapID, markerID, mk))
 	b.WriteString(`})()`)
 	return b.String()
 }
@@ -221,6 +309,106 @@ func popupConstructorJS(p Popup, varName string) string {
 		varName, opts, jsonStr(p.Content))
 }

+// --- Control JS ---
+
+// controlBodyJS generates JS to add a control, assuming `map` is in scope.
+func controlBodyJS(controlID string, ctrl Control) string {
+	return fmt.Sprintf(
+		`var ctrl=%s;map.addControl(ctrl,%s);map._via_controls[%s]=ctrl;`,
+		ctrl.controlJS(), jsonStr(ctrl.controlPosition()), jsonStr(controlID))
+}
+
+// addControlJS generates a self-contained IIFE to add a control post-render.
+func addControlJS(mapID, controlID string, ctrl Control) string {
+	return fmt.Sprintf(
+		`(function(){var map=window.__via_maps&&window.__via_maps[%[1]s];if(!map)return;`+
+			`if(map._via_controls[%[2]s]){map.removeControl(map._via_controls[%[2]s]);delete map._via_controls[%[2]s];}`+
+			`var ctrl=%[3]s;map.addControl(ctrl,%[4]s);map._via_controls[%[2]s]=ctrl;`+
+			`})()`,
+		jsonStr(mapID), jsonStr(controlID), ctrl.controlJS(), jsonStr(ctrl.controlPosition()))
+}
+
+// removeControlJS generates JS to remove a control. Expects `m` in scope.
+func removeControlJS(controlID string) string {
+	return fmt.Sprintf(
+		`if(m._via_controls[%[1]s]){m.removeControl(m._via_controls[%[1]s]);delete m._via_controls[%[1]s];}`,
+		jsonStr(controlID))
+}
+
+// --- Event JS ---
+
+// eventListenerJS generates JS to register a map event listener that writes
+// event data to a hidden signal input.
+func eventListenerJS(mapID string, ev eventEntry) string {
+	var handler string
+	if ev.layerID != "" {
+		handler = fmt.Sprintf(
+			`map.on(%[1]s,%[2]s,function(e){`+
+				`var d={lngLat:{Lng:e.lngLat.lng,Lat:e.lngLat.lat},point:[e.point.x,e.point.y],layerID:%[2]s};`+
+				`if(e.features)d.features=e.features.map(function(f){return JSON.parse(JSON.stringify(f))});`+
+				`var el=document.getElementById(%[3]s);if(!el)return;`+
+				`var inp=el.querySelector('input[data-bind=%[4]s]');`+
+				`if(inp){inp.value=JSON.stringify(d);inp.dispatchEvent(new Event('input',{bubbles:true}))}`+
+				`});`,
+			jsonStr(ev.event), jsonStr(ev.layerID),
+			jsonStr("_vwrap_"+mapID), jsonStr(ev.signal.ID()),
+		)
+	} else {
+		handler = fmt.Sprintf(
+			`map.on(%[1]s,function(e){`+
+				`var d={lngLat:{Lng:e.lngLat.lng,Lat:e.lngLat.lat},point:[e.point.x,e.point.y]};`+
+				`var el=document.getElementById(%[2]s);if(!el)return;`+
+				`var inp=el.querySelector('input[data-bind=%[3]s]');`+
+				`if(inp){inp.value=JSON.stringify(d);inp.dispatchEvent(new Event('input',{bubbles:true}))}`+
+				`});`,
+			jsonStr(ev.event),
+			jsonStr("_vwrap_"+mapID), jsonStr(ev.signal.ID()),
+		)
+	}
+	return handler
+}
+
+// --- Camera options JS ---
+
+// cameraOptionsJS converts CameraOptions to a JS object literal string.
+func cameraOptionsJS(opts CameraOptions) string {
+	obj := map[string]any{}
+	if opts.Center != nil {
+		obj["center"] = []float64{opts.Center.Lng, opts.Center.Lat}
+	}
+	if opts.Zoom != nil {
+		obj["zoom"] = *opts.Zoom
+	}
+	if opts.Bearing != nil {
+		obj["bearing"] = *opts.Bearing
+	}
+	if opts.Pitch != nil {
+		obj["pitch"] = *opts.Pitch
+	}
+	if opts.Duration != nil {
+		obj["duration"] = *opts.Duration
+	}
+	if opts.Speed != nil {
+		obj["speed"] = *opts.Speed
+	}
+	if opts.Curve != nil {
+		obj["curve"] = *opts.Curve
+	}
+	if opts.Padding != nil {
+		obj["padding"] = map[string]int{
+			"top":    opts.Padding.Top,
+			"bottom": opts.Padding.Bottom,
+			"left":   opts.Padding.Left,
+			"right":  opts.Padding.Right,
+		}
+	}
+	if opts.Animate != nil {
+		obj["animate"] = *opts.Animate
+	}
+	b, _ := json.Marshal(obj)
+	return string(b)
+}
+
 func formatFloat(f float64) string {
 	return fmt.Sprintf("%g", f)
 }
--- a/maplibre/maplibre.go
+++ b/maplibre/maplibre.go
@@ -8,6 +8,7 @@ import (
 	"crypto/rand"
 	_ "embed"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"strconv"
@@ -38,29 +39,25 @@ func Plugin(v *via.V) {
 	)
 }

-// viaSignal is the interface satisfied by via's *signal type.
-type viaSignal interface {
-	ID() string
-	String() string
-	SetValue(any)
-	Bind() h.H
-}
-
 // Map represents a MapLibre GL map instance bound to a Via context.
 type Map struct {
+	// Viewport signals — readable with .Text(), .String(), etc.
+	CenterLng *via.Signal
+	CenterLat *via.Signal
+	Zoom      *via.Signal
+	Bearing   *via.Signal
+	Pitch     *via.Signal
+
 	id   string
 	ctx  *via.Context
 	opts Options

-	// Viewport signals for browser → server sync
-	centerLng, centerLat viaSignal
-	zoom, bearing, pitch viaSignal
-
-	// Pre-render accumulation
-	sources []sourceEntry
-	layers  []Layer
-	markers []markerEntry
-	popups  []popupEntry
+	sources  []sourceEntry
+	layers   []Layer
+	markers  []markerEntry
+	popups   []popupEntry
+	events   []eventEntry
+	controls []controlEntry

 	rendered bool
 }
@@ -81,11 +78,11 @@ func New(c *via.Context, opts Options) *Map {
 		opts: opts,
 	}

-	m.centerLng = c.Signal(opts.Center.Lng)
-	m.centerLat = c.Signal(opts.Center.Lat)
-	m.zoom = c.Signal(opts.Zoom)
-	m.bearing = c.Signal(opts.Bearing)
-	m.pitch = c.Signal(opts.Pitch)
+	m.CenterLng = c.Signal(opts.Center.Lng)
+	m.CenterLat = c.Signal(opts.Center.Lat)
+	m.Zoom = c.Signal(opts.Zoom)
+	m.Bearing = c.Signal(opts.Bearing)
+	m.Pitch = c.Signal(opts.Pitch)

 	return m
 }
@@ -93,10 +90,14 @@ func New(c *via.Context, opts Options) *Map {
 // Element returns the h.H DOM tree for the map. Call this once inside your View function.
 // After Element() is called, subsequent source/layer/marker/popup operations
 // use ExecScript instead of accumulating for the init script.
-func (m *Map) Element() h.H {
+//
+// Extra children are appended inside the wrapper div (useful for event inputs
+// and data-effect binding elements).
+func (m *Map) Element(extra ...h.H) h.H {
 	m.rendered = true

-	return h.Div(h.ID("_vwrap_"+m.id),
+	children := []h.H{
+		h.ID("_vwrap_" + m.id),
 		// Map container — morph-ignored so MapLibre's DOM isn't destroyed on Sync()
 		h.Div(
 			h.ID("_vmap_"+m.id),
@@ -104,14 +105,36 @@ func (m *Map) Element() h.H {
 			h.Attr("style", fmt.Sprintf("width:%s;height:%s", m.opts.Width, m.opts.Height)),
 		),
 		// Hidden inputs for viewport signal binding (outside morph-ignored zone)
-		h.Input(h.Type("hidden"), m.centerLng.Bind()),
-		h.Input(h.Type("hidden"), m.centerLat.Bind()),
-		h.Input(h.Type("hidden"), m.zoom.Bind()),
-		h.Input(h.Type("hidden"), m.bearing.Bind()),
-		h.Input(h.Type("hidden"), m.pitch.Bind()),
-		// Init script
-		h.Script(h.Raw(initScript(m))),
-	)
+		h.Input(h.Type("hidden"), m.CenterLng.Bind()),
+		h.Input(h.Type("hidden"), m.CenterLat.Bind()),
+		h.Input(h.Type("hidden"), m.Zoom.Bind()),
+		h.Input(h.Type("hidden"), m.Bearing.Bind()),
+		h.Input(h.Type("hidden"), m.Pitch.Bind()),
+	}
+
+	// data-effect elements for signal-backed markers
+	for _, me := range m.markers {
+		if me.marker.LngSignal != nil && me.marker.LatSignal != nil {
+			children = append(children, h.Div(
+				h.Attr("style", "display:none"),
+				h.DataEffect(markerEffectExpr(m.id, me.id, me.marker)),
+			))
+		}
+	}
+
+	// Event listener binding elements
+	for _, ev := range m.events {
+		children = append(children,
+			h.Input(h.Type("hidden"), ev.signal.Bind()),
+		)
+	}
+
+	children = append(children, extra...)
+
+	// Init script last
+	children = append(children, h.Script(h.Raw(initScript(m))))
+
+	return h.Div(children...)
 }

 // --- Viewport readers (signal → Go) ---
@@ -119,32 +142,43 @@ func (m *Map) Element() h.H {
 // Center returns the current map center from synced signals.
 func (m *Map) Center() LngLat {
 	return LngLat{
-		Lng: parseFloat(m.centerLng.String()),
-		Lat: parseFloat(m.centerLat.String()),
+		Lng: parseFloat(m.CenterLng.String()),
+		Lat: parseFloat(m.CenterLat.String()),
 	}
 }

-// Zoom returns the current map zoom level from the synced signal.
-func (m *Map) Zoom() float64 {
-	return parseFloat(m.zoom.String())
+// --- Camera methods ---
+
+// FlyTo animates the map to the target camera state.
+func (m *Map) FlyTo(opts CameraOptions) {
+	m.exec(fmt.Sprintf(`m.flyTo(%s);`, cameraOptionsJS(opts)))
 }

-// Bearing returns the current map bearing from the synced signal.
-func (m *Map) Bearing() float64 {
-	return parseFloat(m.bearing.String())
+// EaseTo eases the map to the target camera state.
+func (m *Map) EaseTo(opts CameraOptions) {
+	m.exec(fmt.Sprintf(`m.easeTo(%s);`, cameraOptionsJS(opts)))
 }

-// Pitch returns the current map pitch from the synced signal.
-func (m *Map) Pitch() float64 {
-	return parseFloat(m.pitch.String())
+// JumpTo jumps the map to the target camera state without animation.
+func (m *Map) JumpTo(opts CameraOptions) {
+	m.exec(fmt.Sprintf(`m.jumpTo(%s);`, cameraOptionsJS(opts)))
 }

-// --- Viewport setters (Go → browser) ---
+// FitBounds fits the map to the given bounds with optional camera options.
+func (m *Map) FitBounds(bounds LngLatBounds, opts ...CameraOptions) {
+	boundsJS := fmt.Sprintf("[[%s,%s],[%s,%s]]",
+		formatFloat(bounds.SW.Lng), formatFloat(bounds.SW.Lat),
+		formatFloat(bounds.NE.Lng), formatFloat(bounds.NE.Lat))
+	if len(opts) > 0 {
+		m.exec(fmt.Sprintf(`m.fitBounds(%s,%s);`, boundsJS, cameraOptionsJS(opts[0])))
+	} else {
+		m.exec(fmt.Sprintf(`m.fitBounds(%s);`, boundsJS))
+	}
+}

-// FlyTo animates the map to the given center and zoom.
-func (m *Map) FlyTo(center LngLat, zoom float64) {
-	m.exec(fmt.Sprintf(`m.flyTo({center:[%s,%s],zoom:%s});`,
-		formatFloat(center.Lng), formatFloat(center.Lat), formatFloat(zoom)))
+// Stop aborts any in-progress camera animation.
+func (m *Map) Stop() {
+	m.exec(`m.stop();`)
 }

 // SetCenter sets the map center without animation.
@@ -175,10 +209,9 @@ func (m *Map) SetStyle(url string) {

 // --- Source methods ---

-// AddSource adds a source to the map. src should be a GeoJSONSource,
-// VectorSource, RasterSource, or any JSON-marshalable value.
-func (m *Map) AddSource(id string, src any) {
-	js := sourceJSON(src)
+// AddSource adds a source to the map.
+func (m *Map) AddSource(id string, src Source) {
+	js := src.sourceJS()
 	if !m.rendered {
 		m.sources = append(m.sources, sourceEntry{id: id, js: js})
 		return
@@ -187,7 +220,6 @@ func (m *Map) AddSource(id string, src any) {
 }

 // RemoveSource removes a source from the map.
-// Before render, it removes a previously accumulated source. After render, it issues an ExecScript.
 func (m *Map) RemoveSource(id string) {
 	if !m.rendered {
 		for i, s := range m.sources {
@@ -222,7 +254,6 @@ func (m *Map) AddLayer(layer Layer) {
 }

 // RemoveLayer removes a layer from the map.
-// Before render, it removes a previously accumulated layer. After render, it issues an ExecScript.
 func (m *Map) RemoveLayer(id string) {
 	if !m.rendered {
 		for i, l := range m.layers {
@@ -261,7 +292,6 @@ func (m *Map) AddMarker(id string, marker Marker) {
 }

 // RemoveMarker removes a marker from the map.
-// Before render, it removes a previously accumulated marker. After render, it issues an ExecScript.
 func (m *Map) RemoveMarker(id string) {
 	if !m.rendered {
 		for i, me := range m.markers {
@@ -288,7 +318,6 @@ func (m *Map) ShowPopup(id string, popup Popup) {
 }

 // ClosePopup closes a standalone popup on the map.
-// Before render, it removes a previously accumulated popup. After render, it issues an ExecScript.
 func (m *Map) ClosePopup(id string) {
 	if !m.rendered {
 		for i, pe := range m.popups {
@@ -302,6 +331,64 @@ func (m *Map) ClosePopup(id string) {
 	m.exec(closePopupJS(id))
 }

+// --- Control methods ---
+
+// AddControl adds a control to the map.
+func (m *Map) AddControl(id string, ctrl Control) {
+	if !m.rendered {
+		m.controls = append(m.controls, controlEntry{id: id, ctrl: ctrl})
+		return
+	}
+	m.exec(addControlJS(m.id, id, ctrl))
+}
+
+// RemoveControl removes a control from the map.
+func (m *Map) RemoveControl(id string) {
+	if !m.rendered {
+		for i, ce := range m.controls {
+			if ce.id == id {
+				m.controls = append(m.controls[:i], m.controls[i+1:]...)
+				return
+			}
+		}
+		return
+	}
+	m.exec(removeControlJS(id))
+}
+
+// --- Event methods ---
+
+// OnClick returns a MapEvent that fires on map click.
+func (m *Map) OnClick() *MapEvent {
+	return m.on("click", "")
+}
+
+// OnLayerClick returns a MapEvent that fires on click of a specific layer.
+func (m *Map) OnLayerClick(layerID string) *MapEvent {
+	return m.on("click", layerID)
+}
+
+// OnMouseMove returns a MapEvent that fires on map mouse movement.
+func (m *Map) OnMouseMove() *MapEvent {
+	return m.on("mousemove", "")
+}
+
+// OnContextMenu returns a MapEvent that fires on right-click.
+func (m *Map) OnContextMenu() *MapEvent {
+	return m.on("contextmenu", "")
+}
+
+func (m *Map) on(event, layerID string) *MapEvent {
+	sig := m.ctx.Signal("")
+	ev := &MapEvent{signal: sig}
+	m.events = append(m.events, eventEntry{
+		event:   event,
+		layerID: layerID,
+		signal:  sig,
+	})
+	return ev
+}
+
 // --- Escape hatch ---

 // Exec runs arbitrary JS with the map available as `m`.
@@ -314,6 +401,30 @@ func (m *Map) exec(body string) {
 	m.ctx.ExecScript(guard(m.id, body))
 }

+// --- MapEvent ---
+
+// MapEvent wraps a signal that receives map event data as JSON.
+type MapEvent struct {
+	signal *via.Signal
+}
+
+// Bind returns the data-bind attribute for this event's signal.
+func (e *MapEvent) Bind() h.H { return e.signal.Bind() }
+
+// Data parses the event signal's JSON value into EventData.
+func (e *MapEvent) Data() EventData {
+	var d EventData
+	json.Unmarshal([]byte(e.signal.String()), &d)
+	return d
+}
+
+// Input creates a hidden input wired to this event's signal.
+// Pass action triggers (e.g. handleClick.OnInput()) as attrs.
+func (e *MapEvent) Input(attrs ...h.H) h.H {
+	all := append([]h.H{h.Type("hidden"), e.Bind()}, attrs...)
+	return h.Input(all...)
+}
+
 func parseFloat(s string) float64 {
 	f, _ := strconv.ParseFloat(s, 64)
 	return f
--- a/maplibre/types.go
+++ b/maplibre/types.go
@@ -1,6 +1,10 @@
 package maplibre

-import "encoding/json"
+import (
+	"encoding/json"
+
+	"github.com/ryanhamamura/via"
+)

 // LngLat represents a geographic coordinate.
 type LngLat struct {
@@ -8,6 +12,20 @@ type LngLat struct {
 	Lat float64
 }

+// LngLatBounds represents a rectangular geographic area.
+type LngLatBounds struct {
+	SW LngLat
+	NE LngLat
+}
+
+// Padding represents padding in pixels on each side of the map viewport.
+type Padding struct {
+	Top    int
+	Bottom int
+	Left   int
+	Right  int
+}
+
 // Options configures the initial map state.
 type Options struct {
 	// Style is the map style URL (required).
@@ -23,6 +41,30 @@ type Options struct {
 	// CSS dimensions for the map container. Defaults: "100%", "400px".
 	Width  string
 	Height string
+
+	// Interaction toggles (nil = MapLibre default)
+	ScrollZoom        *bool
+	BoxZoom           *bool
+	DragRotate        *bool
+	DragPan           *bool
+	Keyboard          *bool
+	DoubleClickZoom   *bool
+	TouchZoomRotate   *bool
+	TouchPitch        *bool
+	RenderWorldCopies *bool
+
+	MaxBounds *LngLatBounds
+
+	// Extra is merged last into the MapLibre constructor options object,
+	// allowing pass-through of any option not covered above.
+	Extra map[string]any
+}
+
+// --- Source interface ---
+
+// Source is implemented by map data sources (GeoJSON, vector, raster, etc.).
+type Source interface {
+	sourceJS() string
 }

 // GeoJSONSource provides inline GeoJSON data to MapLibre.
@@ -31,7 +73,7 @@ type GeoJSONSource struct {
 	Data any
 }

-func (s GeoJSONSource) toJS() string {
+func (s GeoJSONSource) sourceJS() string {
 	data, _ := json.Marshal(s.Data)
 	return `{"type":"geojson","data":` + string(data) + `}`
 }
@@ -42,7 +84,7 @@ type VectorSource struct {
 	Tiles []string
 }

-func (s VectorSource) toJS() string {
+func (s VectorSource) sourceJS() string {
 	obj := map[string]any{"type": "vector"}
 	if s.URL != "" {
 		obj["url"] = s.URL
@@ -61,7 +103,7 @@ type RasterSource struct {
 	TileSize int
 }

-func (s RasterSource) toJS() string {
+func (s RasterSource) sourceJS() string {
 	obj := map[string]any{"type": "raster"}
 	if s.URL != "" {
 		obj["url"] = s.URL
@@ -76,21 +118,135 @@ func (s RasterSource) toJS() string {
 	return string(b)
 }

-// sourceJSON converts a source value to its JS object literal string.
-func sourceJSON(src any) string {
-	switch s := src.(type) {
-	case GeoJSONSource:
-		return s.toJS()
-	case VectorSource:
-		return s.toJS()
-	case RasterSource:
-		return s.toJS()
-	default:
-		b, _ := json.Marshal(src)
-		return string(b)
-	}
+// RawSource is an escape hatch that passes an arbitrary JSON-marshalable
+// value directly as a MapLibre source definition.
+type RawSource struct {
+	Value any
 }

+func (s RawSource) sourceJS() string {
+	b, _ := json.Marshal(s.Value)
+	return string(b)
+}
+
+// --- Control interface ---
+
+// Control is implemented by map controls (navigation, scale, etc.).
+type Control interface {
+	controlJS() string
+	controlPosition() string
+}
+
+// NavigationControl adds zoom and rotation buttons.
+type NavigationControl struct {
+	Position       string // "top-right" (default), "top-left", "bottom-right", "bottom-left"
+	ShowCompass    *bool
+	ShowZoom       *bool
+	VisualizeRoll  *bool
+	VisualizePitch *bool
+}
+
+func (c NavigationControl) controlJS() string {
+	opts := map[string]any{}
+	if c.ShowCompass != nil {
+		opts["showCompass"] = *c.ShowCompass
+	}
+	if c.ShowZoom != nil {
+		opts["showZoom"] = *c.ShowZoom
+	}
+	if c.VisualizeRoll != nil {
+		opts["visualizeRoll"] = *c.VisualizeRoll
+	}
+	if c.VisualizePitch != nil {
+		opts["visualizePitch"] = *c.VisualizePitch
+	}
+	b, _ := json.Marshal(opts)
+	return "new maplibregl.NavigationControl(" + string(b) + ")"
+}
+
+func (c NavigationControl) controlPosition() string {
+	if c.Position == "" {
+		return "top-right"
+	}
+	return c.Position
+}
+
+// ScaleControl displays a scale bar.
+type ScaleControl struct {
+	Position string // default "bottom-left"
+	MaxWidth int
+	Unit     string // "metric", "imperial", "nautical"
+}
+
+func (c ScaleControl) controlJS() string {
+	opts := map[string]any{}
+	if c.MaxWidth > 0 {
+		opts["maxWidth"] = c.MaxWidth
+	}
+	if c.Unit != "" {
+		opts["unit"] = c.Unit
+	}
+	b, _ := json.Marshal(opts)
+	return "new maplibregl.ScaleControl(" + string(b) + ")"
+}
+
+func (c ScaleControl) controlPosition() string {
+	if c.Position == "" {
+		return "bottom-left"
+	}
+	return c.Position
+}
+
+// GeolocateControl adds a button to track the user's location.
+type GeolocateControl struct {
+	Position string // default "top-right"
+}
+
+func (c GeolocateControl) controlJS() string {
+	return "new maplibregl.GeolocateControl()"
+}
+
+func (c GeolocateControl) controlPosition() string {
+	if c.Position == "" {
+		return "top-right"
+	}
+	return c.Position
+}
+
+// FullscreenControl adds a fullscreen toggle button.
+type FullscreenControl struct {
+	Position string // default "top-right"
+}
+
+func (c FullscreenControl) controlJS() string {
+	return "new maplibregl.FullscreenControl()"
+}
+
+func (c FullscreenControl) controlPosition() string {
+	if c.Position == "" {
+		return "top-right"
+	}
+	return c.Position
+}
+
+// --- Camera options ---
+
+// CameraOptions configures animated camera movements (FlyTo, EaseTo, JumpTo).
+// Nil pointer fields are omitted from the JS call.
+type CameraOptions struct {
+	Center   *LngLat
+	Zoom     *float64
+	Bearing  *float64
+	Pitch    *float64
+	Duration *int     // milliseconds
+	Speed    *float64 // FlyTo only
+	Curve    *float64 // FlyTo only
+	Padding  *Padding
+	Animate  *bool
+}
+
+// --- Layer ---
+
 // Layer describes a MapLibre style layer.
 type Layer struct {
 	ID          string
@@ -137,12 +293,20 @@ func (l Layer) toJS() string {
 	return string(b)
 }

+// --- Marker ---
+
 // Marker describes a map marker.
 type Marker struct {
-	LngLat    LngLat
+	LngLat    LngLat // static position (used when signals are nil)
 	Color     string
 	Draggable bool
 	Popup     *Popup
+
+	// Signal-backed position. When set, signals drive marker position reactively.
+	// Initial position is read from the signal values. LngLat is ignored when signals are set.
+	// If Draggable is true, drag updates write back to these signals.
+	LngSignal *via.Signal
+	LatSignal *via.Signal
 }

 // Popup describes a map popup.
@@ -156,20 +320,40 @@ type Popup struct {
 	MaxWidth        string
 }

-// sourceEntry pairs a source ID with its JS representation for pre-render accumulation.
+// --- Event data ---
+
+// EventData contains data from a map event (click, mousemove, etc.).
+type EventData struct {
+	LngLat   LngLat            `json:"lngLat"`
+	Point    [2]float64        `json:"point"`
+	Features []json.RawMessage `json:"features,omitempty"`
+	LayerID  string            `json:"layerID,omitempty"`
+}
+
+// --- Internal accumulation entries ---
+
 type sourceEntry struct {
 	id string
 	js string
 }

-// markerEntry pairs a marker ID with its definition for pre-render accumulation.
 type markerEntry struct {
 	id     string
 	marker Marker
 }

-// popupEntry pairs a popup ID with its definition for pre-render accumulation.
 type popupEntry struct {
 	id    string
 	popup Popup
 }
+
+type eventEntry struct {
+	event   string
+	layerID string
+	signal  *via.Signal
+}
+
+type controlEntry struct {
+	id   string
+	ctrl Control
+}