@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/FMapGeolocate.vue

@@ -0,0 +1,208 @@
+<script setup lang="ts">
+// "Where am I" — Mapbox's behaviour, Forest's chrome.
+//
+//   <FMapGeolocate :map="map" />
+//
+// ★ WRAPPED, NOT REBUILT, and this is the one control where that is the right call. Zoom is two methods
+// and a compass is a bearing, but geolocation is a permission flow, a `watchPosition` subscription with
+// its own error taxonomy, an accuracy ring that has to track the position's own confidence, a heading
+// cone, and two tracking modes (active-lock, and the background mode a map enters once the user pans
+// away). Rebuilding that is a liability with no upside; what was wrong with the stock control was never
+// its behaviour.
+//
+// What IS wrong with it is placement: Mapbox mounts controls into its own corner containers, which are
+// not the HUD's areas — so a stock control cannot sit in a rail, cannot take the canvas-chrome surface
+// with the rest of the chrome, and cannot step aside for an open <FSidePanel> (the HUD insets its areas
+// from the strip the panel publishes; Mapbox's corners never hear about it). So the control is added for
+// its behaviour and its own button is hidden; ours drives it and reports back.
+//
+// ★ The user dot, its accuracy ring and the heading cone are still Mapbox's, drawn on the map itself
+// rather than in the control container — they survive hiding the button, which is the whole trick.
+import { computed, onBeforeUnmount, ref, shallowRef, watch } from 'vue';
+import mapboxgl from 'mapbox-gl';
+import FCanvasControl from '../canvas/FCanvasControl.vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** The live map, from <FMap @ready>. */
+    map?: mapboxgl.Map | null;
+    /** Keep following the user after the first fix, which is what a rider-facing surface wants. */
+    track?: boolean;
+    /** The heading cone. Needs `track`, and a device that reports heading. */
+    heading?: boolean;
+    /** High accuracy costs battery; on by default because a bay 30m away is the wrong bay. */
+    highAccuracy?: boolean;
+  }>(),
+  { map: null, track: true, heading: true, highAccuracy: true },
+);
+
+const emit = defineEmits<{
+  geolocate: [position: GeolocationPosition];
+  error: [error: GeolocationPositionError];
+}>();
+
+const control = shallowRef<mapboxgl.GeolocateControl | null>(null);
+
+/**
+ * ★ THREE STATES, because that is what the underlying control has — and collapsing them lost the one a
+ * rider is in most of the time. Mapbox documents them as:
+ *
+ *   active   the camera follows the user; the dot stays centred.
+ *   passive  the DOT still updates, the camera does not. Entered the moment the user pans away.
+ *   disabled geolocation unavailable, or the permission refused.
+ *
+ * This used to render active and "off", so panning made the control look exactly as it had before the
+ * user ever located themselves — while their position was still live on the map. Passive is a real
+ * state and it now looks like one: located, not followed, and one click from following again.
+ */
+export type GeolocateState = 'idle' | 'active' | 'passive' | 'disabled';
+
+const following = ref(false);
+const located = ref(false);
+const unavailable = ref(false);
+
+const state = computed<GeolocateState>(() =>
+  unavailable.value ? 'disabled' : following.value ? 'active' : located.value ? 'passive' : 'idle',
+);
+
+const onGeolocate = (e: unknown) => {
+  located.value = true;
+  emit('geolocate', e as GeolocationPosition);
+};
+const onStart = () => (following.value = true);
+// Not "stop": the dot lives on. Only the camera let go.
+const onEnd = () => (following.value = false);
+const onError = (e: unknown) => {
+  following.value = false;
+  located.value = false;
+  // PERMISSION_DENIED is terminal for the session: the browser will not re-prompt, so a control that
+  // stays enabled invites a click that can only fail.
+  const err = e as GeolocationPositionError;
+  if (err?.code === 1) unavailable.value = true;
+  emit('error', err);
+};
+
+watch(
+  () => props.map,
+  (m, _old, onCleanup) => {
+    if (!m) return;
+
+    // No geolocation at all — an insecure origin, or a browser without it. Say so by disabling rather
+    // than by failing on click.
+    if (typeof navigator === 'undefined' || !navigator.geolocation) {
+      unavailable.value = true;
+      return;
+    }
+
+    // ★ ASK THE PERMISSIONS API UP FRONT, which is what the stock control does — and not asking showed:
+    // on an origin the user had already refused, Mapbox's own (hidden) button was disabled and labelled
+    // "Location not available" while ours sat there offering a click that could only fail. Reacting to
+    // the error alone means the control looks available until someone proves it is not.
+    //
+    // Watched, not read once: a permission granted or revoked in site settings has to reach the button
+    // without a reload.
+    void navigator.permissions
+      ?.query({ name: 'geolocation' as PermissionName })
+      .then((status) => {
+        const read = () => (unavailable.value = status.state === 'denied');
+        read();
+        status.addEventListener('change', read);
+        onCleanup(() => status.removeEventListener('change', read));
+      })
+      // Safari has refused `permissions.query` for geolocation historically: no answer is not a denial,
+      // so the control stays available and the error path remains the backstop.
+      .catch(() => {});
+
+    const ctrl = new mapboxgl.GeolocateControl({
+      positionOptions: { enableHighAccuracy: props.highAccuracy },
+      trackUserLocation: props.track,
+      showUserHeading: props.heading && props.track,
+      showAccuracyCircle: true,
+      // ★ The control's OWN button, suppressed the supported way. This used to be `display: none` on
+      // its `_container` — a private field, and a hack that would break the day Mapbox renamed it.
+      // The option exists for exactly this pattern: no button, `trigger()` called from ours, and the
+      // map-side layers (dot, ring, heading cone) unaffected because they are drawn on the map rather
+      // than in the control.
+      showButton: false,
+    });
+    m.addControl(ctrl);
+    control.value = ctrl;
+
+    ctrl.on('geolocate', onGeolocate);
+    ctrl.on('trackuserlocationstart', onStart);
+    ctrl.on('trackuserlocationend', onEnd);
+    ctrl.on('error', onError);
+
+    onCleanup(() => {
+      ctrl.off('geolocate', onGeolocate);
+      ctrl.off('trackuserlocationstart', onStart);
+      ctrl.off('trackuserlocationend', onEnd);
+      ctrl.off('error', onError);
+      if (m.hasControl(ctrl)) m.removeControl(ctrl);
+      control.value = null;
+      following.value = false;
+      located.value = false;
+    });
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => {
+  const m = props.map;
+  const ctrl = control.value;
+  if (m && ctrl && m.hasControl(ctrl)) m.removeControl(ctrl);
+});
+
+// `trigger()` is the control's own entry point, so the permission prompt, the fix and the tracking
+// transitions all run exactly as they do for the stock button.
+//
+// ★ `following` is BOUND with v-model, so the click marks the button pressed before any fix arrives, and
+// the control's own events then correct it — `trackuserlocationend` when the user pans away, `error`
+// when the permission is refused. Optimistic on purpose: a geolocation fix can take seconds, and a
+// button that looks inert until it lands reads as a button that did not take the press.
+const locate = () => control.value?.trigger();
+
+// Passive earns the FILLED icon without the pressed cut: the position is known and on screen, but the
+// camera is the user's again. Idle is the outline. The difference has to be visible at a glance, or
+// "am I still being followed?" costs a pan to answer.
+//
+// ★ And `disabled` takes the SLASHED glyph. A crossed-out icon means "this cannot happen" in every set,
+// which is wrong for a resting control and exactly right for a refused permission — the one state where
+// the control genuinely cannot act. Dimming alone left it looking like a button someone had simply not
+// pressed yet.
+const icon = computed(() => {
+  switch (state.value) {
+    case 'disabled':
+      return 'i-lucide-locate-off';
+    case 'idle':
+      return 'i-lucide-locate';
+    default:
+      return 'i-lucide-locate-fixed';
+  }
+});
+
+const label = computed(() => {
+  switch (state.value) {
+    case 'disabled':
+      return 'Location unavailable';
+    case 'active':
+      return 'Stop following your location';
+    case 'passive':
+      return 'Follow your location again';
+    default:
+      return 'Show your location';
+  }
+});
+
+defineExpose({ state });
+</script>
+
+<template>
+  <FCanvasControl
+    :icon="icon"
+    :label="label"
+    :disabled="!map || unavailable"
+    v-model:pressed="following"
+    @click="locate()"
+  />
+</template>

package/packages/ui/src/map/FMapLayers.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+// The switch for what the map is painting — the legend's interactive twin.
+//
+//   <FMapLayers v-model="hidden" :sections="[{ label: 'Zones', items: zoneLegendItems('operations') }]" />
+//
+// ★ IT TAKES THE LEGEND'S OWN ROWS. A legend row says what a colour means; a layers row says the same
+// thing and adds "and you can turn it off". Two lists with two vocabularies over one map would be drift
+// with nothing to recommend it, so MapLegendItem is the contract for both and the swatch is drawn by
+// one shared function.
+//
+// ★ IT CARRIES NO SURFACE AND DOES NOT POSITION ITSELF, for the reasons <FMapLegend> gives: over a
+// basemap a bare list is unreadable, <FCanvasCard> is that panel already, and the same rows have to be
+// able to sit in a side panel or a settings sheet where a card would be an intrusion. A rail trigger
+// needs no new primitive either — <FCanvasControl v-model:pressed> opens an <FCanvasCard>.
+//
+// ★ IT TAKES NO MAP. The model feeds `visible:` in the surface's own OverlaySpec, and useMapOverlay
+// applies it. Calling setLayoutProperty from here would work until the next apply — a spec change, a
+// colour-mode flip, a new style — and then be reverted, with the switch still reporting the state it
+// asked for. Given the map it could also enumerate layers the audience filter had already removed from
+// the legend, and offer them; taking rows makes that impossible rather than merely unlikely.
+//
+// ★ AUDIENCE IS NOT A SWITCH. Rows come from the same builder the legend uses — zoneLegendItems(audience)
+// — which has already dropped what that audience must not see. Visibility is the reader's; existence is
+// the audience's, and it is settled upstream in the source and the geometry.
+import { legendSwatchStyle } from './mapLegend';
+import { sectionState, toggleKey, toggleSection, type MapLayerSection } from './mapLayers';
+
+/** The keys NOT painted. `[]` is the map as the surface authored it — see mapLayers.ts. */
+const hidden = defineModel<string[]>({ default: () => [] });
+
+withDefaults(
+  defineProps<{
+    /** Groups of rows. One section without a label is a flat list, and needs no second API. */
+    sections?: MapLayerSection[];
+  }>(),
+  { sections: () => [] },
+);
+</script>
+
+<template>
+  <div class="flex flex-col gap-4">
+    <div v-for="(section, i) in sections" :key="section.label ?? i" class="flex flex-col gap-2">
+      <!-- A labelled section gets the all/none header; an unlabelled one is a bare list, because
+           there is nothing to name the toggle after. `some` renders indeterminate and reveals on
+           press — the direction that cannot empty a map by accident. -->
+      <UCheckbox
+        v-if="section.label"
+        :model-value="
+          sectionState(section.items, hidden) === 'some' ? 'indeterminate' : sectionState(section.items, hidden) === 'all'
+        "
+        :label="section.label"
+        :ui="{ label: 'type-caption font-bold text-default' }"
+        @update:model-value="hidden = toggleSection(section.items, hidden)"
+      />
+
+      <ul role="list" class="flex flex-col gap-1.5" :class="section.label ? 'ps-6' : ''">
+        <li v-for="item in section.items" :key="item.key">
+          <USwitch
+            :model-value="!hidden.includes(item.key)"
+            @update:model-value="hidden = toggleKey(item.key, hidden)"
+          >
+            <template #label>
+              <span class="flex items-center gap-2">
+                <!-- The swatch is drawn the way the layer is drawn, by the legend's own function: a
+                     reader checks either list by looking from it to the map and matching. -->
+                <span class="size-3 shrink-0 rounded-[2px] border" :style="legendSwatchStyle(item)" aria-hidden="true" />
+                <span class="type-caption text-default">{{ item.label }}</span>
+              </span>
+            </template>
+          </USwitch>
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>

package/packages/ui/src/map/FMapLegend.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+// The key to what a map is painting.
+//
+//   <FCanvasCard><FMapLegend :items="zoneLegendItems('operations')" /></FCanvasCard>
+//
+// ★ IT CARRIES NO SURFACE. Over a basemap a bare list is unreadable, so a legend on a map needs a
+// panel — and <FCanvasCard> is that panel, with the translucent fill, the radius and the pointer
+// opt-in already settled. Owning a second one here would mean maintaining two. Bare also lets the
+// same rows sit in a side panel or a table, where a card would be an intrusion.
+//
+// ★ THE SWATCH IS DRAWN THE WAY THE LAYER IS DRAWN. A reader checks a legend by looking from the key
+// to the map, and that only works if a zone painted as a bare dashed outline appears here as a bare
+// dashed outline. See MapLegendItem — `swatch` and `dash` exist for exactly this, and are the reason
+// this takes items rather than a list of colours and strings.
+//
+// ★ IT KNOWS NOTHING ABOUT ZONES. `zoneLegendItems()` in zone.ts builds the rows, including the
+// audience rule that keeps the exclusion zone off a rider's map. Anything else with a paint vocabulary
+// can build its own.
+// ★ The swatch's style lives in mapLegend.ts, not here: <FMapLayers> draws the same row with a switch
+// on it, and two copies of the wash would drift exactly where it costs most — a bounded zone shown as
+// a filled one in the list a reader is using to decide what to turn off.
+import { legendSwatchStyle, type MapLegendItem } from './mapLegend';
+
+withDefaults(
+  defineProps<{
+    items: MapLegendItem[];
+    /** `vertical` stacks the rows for a corner card; `horizontal` wraps them for the hub band. */
+    orientation?: 'vertical' | 'horizontal';
+  }>(),
+  { orientation: 'vertical' },
+);
+</script>
+
+<template>
+  <ul
+    role="list"
+    class="flex"
+    :class="orientation === 'horizontal' ? 'flex-wrap items-center gap-x-4 gap-y-2' : 'flex-col gap-1.5'"
+  >
+    <li v-for="item in items" :key="item.key" class="flex items-center gap-2">
+      <span class="size-3 shrink-0 rounded-[2px] border" :style="legendSwatchStyle(item)" aria-hidden="true" />
+      <span class="type-caption text-default">{{ item.label }}</span>
+    </li>
+  </ul>
+</template>

package/packages/ui/src/map/FMapPopup.vue

@@ -0,0 +1,129 @@
+<script setup lang="ts">
+// FMapPopup — a Mapbox popup whose contents are a Vue slot, so a callout can hold real components
+// (a badge, a button) instead of an HTML string built by hand. Put it in <FMarker>'s `popup` slot and
+// it binds to that marker's click; give it `lng-lat` and `v-model:open` to place one anywhere on the
+// map. It must be the `popup` slot, not the default one — that slot replaces the pin itself.
+//
+// The chrome itself — surface, radius, tip, close button — is tokened in styles/map.css, which FMap
+// imports. A popup is still Mapbox chrome: keep it to a line or two and put anything richer in app
+// UI beside the map.
+import { inject, onBeforeUnmount, ref, shallowRef, watch } from 'vue';
+import mapboxgl from 'mapbox-gl';
+import { FOREST_MAP, FOREST_MARKER } from './mapContext';
+import { useLazyHost } from './useMap';
+
+type Anchor =
+  | 'center' | 'top' | 'bottom' | 'left' | 'right'
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+const props = withDefaults(
+  defineProps<{
+    /** standalone placement. Omit inside <FMarker>, which supplies the position */
+    lngLat?: [number, number];
+    /** standalone open state — pair with v-model:open. Ignored when bound to a marker */
+    open?: boolean;
+    offset?: number | [number, number];
+    closeButton?: boolean;
+    anchor?: Anchor;
+    /** CSS max-width mapbox applies to the popup box */
+    maxWidth?: string;
+  }>(),
+  {
+    lngLat: undefined,
+    open: false,
+    offset: 18,
+    closeButton: false,
+    anchor: undefined,
+    maxWidth: '260px',
+  },
+);
+
+const emit = defineEmits<{ 'update:open': [value: boolean] }>();
+
+const map = inject(FOREST_MAP, null);
+const marker = inject(FOREST_MARKER, null);
+
+// Slot content lives in this element; mapbox mounts it as the popup body. Created on demand rather
+// than during setup, which may run on a server.
+const { host, ensure } = useLazyHost();
+const popup = shallowRef<mapboxgl.Popup | null>(null);
+
+// Focus, the whole contract: a popup is a callout that just appeared somewhere on a canvas, so a
+// keyboard user has to be able to reach it, dismiss it, and land back where they were. The body takes
+// focus on open, Escape closes, and whatever was focused before (usually the marker button) gets it
+// back — which is also why the popup must not be focused when it opens for no reason.
+const body = ref<HTMLElement | null>(null);
+let returnFocusTo: HTMLElement | null = null;
+
+function onKeydown(event: KeyboardEvent) {
+  if (event.key !== 'Escape') return;
+  event.stopPropagation();
+  popup.value?.remove();
+}
+
+function build() {
+  if (popup.value) return popup.value;
+  const p = new mapboxgl.Popup({
+    offset: props.offset,
+    closeButton: props.closeButton,
+    maxWidth: props.maxWidth,
+    ...(props.anchor ? { anchor: props.anchor } : {}),
+  }).setDOMContent(ensure());
+  // Mapbox closes a popup on its own (close button, click-away, marker toggle) — mirror that back so
+  // a bound `open` never drifts from what is on screen.
+  p.on('close', () => {
+    emit('update:open', false);
+    // Only take focus back if it is still inside the popup that just went away; a click elsewhere has
+    // already moved it somewhere the user chose, and yanking it back would be worse than doing nothing.
+    const active = document.activeElement;
+    if (returnFocusTo && (!active || active === document.body || body.value?.contains(active))) {
+      returnFocusTo.focus();
+    }
+    returnFocusTo = null;
+  });
+  p.on('open', () => {
+    emit('update:open', true);
+    const active = document.activeElement;
+    returnFocusTo = active instanceof HTMLElement && active !== document.body ? active : null;
+    body.value?.focus();
+  });
+  popup.value = p;
+  return p;
+}
+
+// Bound to a marker: mapbox toggles it on marker click, and tracks the marker's position for us.
+if (marker) {
+  watch(marker, (mk) => mk?.setPopup(build()), { immediate: true });
+}
+
+// Standalone: `open` + `lng-lat` drive it.
+if (!marker && map) {
+  const sync = () => {
+    const m = map.value;
+    if (!m || !props.lngLat) return;
+    const p = build().setLngLat(props.lngLat);
+    if (props.open) p.addTo(m);
+    else p.remove();
+  };
+  watch([map, () => props.open, () => props.lngLat], sync, { immediate: true, deep: true });
+}
+
+onBeforeUnmount(() => popup.value?.remove());
+</script>
+
+<template>
+  <Teleport v-if="host" :to="host">
+    <!-- tabindex="-1" so the body can be focused programmatically without joining the tab order;
+         Escape is handled here rather than on the document, so it never steals the key from a dialog
+         or a command palette above the map. -->
+    <div
+      ref="body"
+      tabindex="-1"
+      role="dialog"
+      class="type-body font-sans focus:outline-none"
+      @keydown="onKeydown"
+    >
+      <slot />
+    </div>
+  </Teleport>
+</template>

package/packages/ui/src/map/FMapRamp.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+// The key to a QUANTITY on the map — the ordered counterpart to <FMapLegend>.
+//
+//   <FCanvasCard><FMapRamp :legend="densityLegend({ domain, unit: 'rides', res: 8 })" /></FCanvasCard>
+//
+// ★ IT IS A SEPARATE COMPONENT BECAUSE A RAMP IS NOT A LIST. `MapLegendItem` describes an unordered
+// category by how it is DRAWN — filled or bounded, solid or dashed — and its rows are separated
+// because the categories are unrelated to each other. A ramp is one continuous claim cut into
+// buckets: the rows are in an order that means something, the swatches carry no fill/line
+// distinction, and the numbers between them are the content. Forcing that through the categorical
+// legend would mean spending its swatch vocabulary on something it does not describe.
+//
+// ★ THE SWATCHES ABUT. A gap between two swatches says "these are different things"; a density ramp
+// says the opposite, and the reader has to see it as one bar to read it as an order.
+//
+// ★ AND IT STATES ITS UNIT. A shaded map with no unit is the most confidently wrong object in data
+// visualisation: the reader takes the darkest cell as "a lot" without ever learning a lot of what, at
+// what size, or whether the top of the ramp is the maximum. `unit`, `cellM` and `clamped` are all
+// carried by the legend model rather than left to a caption someone might not write.
+import type { RampLegend } from './density';
+
+withDefaults(
+  defineProps<{
+    legend: RampLegend;
+    /** `horizontal` is the bar; `vertical` stacks the buckets for a narrow rail. */
+    orientation?: 'horizontal' | 'vertical';
+  }>(),
+  { orientation: 'horizontal' },
+);
+</script>
+
+<template>
+  <div class="flex flex-col gap-1.5">
+    <p v-if="legend.unit" class="type-caption text-muted">{{ legend.unit }}</p>
+
+    <!-- Horizontal: one bar, labels under the buckets they belong to. -->
+    <ul v-if="orientation === 'horizontal'" role="list" class="flex items-stretch">
+      <li v-for="stop in legend.stops" :key="stop.key" class="flex min-w-0 flex-1 flex-col gap-1">
+        <span
+          class="h-3 w-full first:rounded-l-[2px] last:rounded-r-[2px]"
+          :style="{ backgroundColor: `var(${stop.colour})` }"
+          aria-hidden="true"
+        />
+        <span class="type-caption truncate text-muted">{{ stop.label }}</span>
+      </li>
+    </ul>
+
+    <!-- Vertical: rows, for a rail too narrow for a bar to carry its own labels. -->
+    <ul v-else role="list" class="flex flex-col">
+      <li v-for="stop in legend.stops" :key="stop.key" class="flex items-center gap-2">
+        <span
+          class="size-3 shrink-0 first:rounded-t-[2px] last:rounded-b-[2px]"
+          :style="{ backgroundColor: `var(${stop.colour})` }"
+          aria-hidden="true"
+        />
+        <span class="type-caption text-default">{{ stop.label }}</span>
+      </li>
+    </ul>
+
+    <!-- ★ The footnote is not optional decoration. The cell size is what makes a count comparable
+         between two cells, and the clamp is the difference between "the top of the ramp" and "the
+         largest reading" — a ramp that hides its clamp overstates the quiet parts of the map. -->
+    <p v-if="legend.cellM || legend.clamped" class="type-caption text-dimmed">
+      <span v-if="legend.cellM">cell ≈ {{ legend.cellM }} m across</span>
+      <span v-if="legend.cellM && legend.clamped"> · </span>
+      <span v-if="legend.clamped">{{ legend.clamped }} above the top of the ramp</span>
+    </p>
+  </div>
+</template>

package/packages/ui/src/map/FMapRegion.vue

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+// The shape a region gesture is drawing, painted over the canvas.
+//
+//   const region = useRegionSelect(map, select, () => ({ layers: ['bikes'] }))
+//   <FMapRegion :path="region.path.value" :shape="'lasso'" />
+//
+// ★ IT DRAWS, IT DOES NOT LISTEN. Every pointer event belongs to useRegionSelect, which owns the
+// gesture and needs the map to disable panning at exactly the right moment. An overlay that captured
+// its own events would either fight that or need the same modifier logic a second time.
+//
+// ★ SCREEN SPACE, so it never reprojects. The path is already canvas px — the same coordinates the
+// gesture was captured in and the same ones the hit test runs in — so the drawn shape and the caught
+// features cannot disagree. An overlay that stored lng/lat would visibly lag a pan by one frame.
+import { computed } from 'vue';
+import { circleFromPath, type RegionShape, type ScreenPoint } from './regionSelect';
+
+const props = withDefaults(
+  defineProps<{
+    /** the live path from useRegionSelect, in canvas px. Empty draws nothing */
+    path: readonly ScreenPoint[];
+    shape?: RegionShape;
+  }>(),
+  { shape: 'lasso' },
+);
+
+const ring = computed(() => circleFromPath(props.path));
+
+const points = computed(() => props.path.map(([x, y]) => `${x},${y}`).join(' '));
+
+/** A box is its two corners; normalised so dragging up or left still yields a positive rect. */
+const rect = computed(() => {
+  const [a, b] = [props.path[0], props.path[props.path.length - 1]];
+  if (!a || !b) return null;
+  return { x: Math.min(a[0], b[0]), y: Math.min(a[1], b[1]), w: Math.abs(b[0] - a[0]), h: Math.abs(b[1] - a[1]) };
+});
+</script>
+
+<template>
+  <!-- pointer-events-none throughout: the gesture is captured on the map's own canvas container, and
+       an overlay that swallowed events would break the drag it exists to visualise. -->
+  <svg
+    v-if="path.length > 1"
+    class="pointer-events-none absolute inset-0 z-10 h-full w-full overflow-visible"
+    aria-hidden="true"
+  >
+    <rect
+      v-if="shape === 'box' && rect"
+      :x="rect.x"
+      :y="rect.y"
+      :width="rect.w"
+      :height="rect.h"
+      class="fill-primary/10 stroke-primary"
+      stroke-width="1.5"
+      stroke-dasharray="4 3"
+    />
+    <!-- Centre-out, matching the gesture: the press is the centre and the pointer is on the rim. -->
+    <circle
+      v-else-if="shape === 'circle' && ring"
+      :cx="ring.centre[0]"
+      :cy="ring.centre[1]"
+      :r="ring.radius"
+      class="fill-primary/10 stroke-primary"
+      stroke-width="1.5"
+      stroke-dasharray="4 3"
+    />
+    <!-- The lasso is drawn as a polygon rather than a polyline: the shape it will TEST against is
+         closed, so showing it open would promise a different catch than the one it makes. -->
+    <polygon
+      v-else-if="shape === 'lasso'"
+      :points="points"
+      class="fill-primary/10 stroke-primary"
+      stroke-width="1.5"
+      stroke-linejoin="round"
+      stroke-dasharray="4 3"
+    />
+  </svg>
+</template>