@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/useMap.ts

@@ -0,0 +1,150 @@
+// Small seams every map child needs, so none of them re-implement the awkward bits.
+import { inject, onScopeDispose, shallowRef, watch, type ShallowRef } from 'vue';
+import type { LngLatBoundsLike, Map } from 'mapbox-gl';
+import { FOREST_MAP } from './mapContext';
+import { withGap } from './padding';
+
+/**
+ * The map from the enclosing <FMap>. `fn` runs once the Standard style has loaded — which may be
+ * well after mount, because FMap creates the WebGL context lazily. Returns the ref for later use.
+ */
+export function useMapReady(fn?: (map: Map) => void): ShallowRef<Map | null> {
+  const map = inject(FOREST_MAP, null) ?? shallowRef<Map | null>(null);
+  if (fn) {
+    watch(
+      map,
+      (m) => {
+        if (!m) return;
+        if (m.isStyleLoaded()) {
+          fn(m);
+          return;
+        }
+        // `style.load` if it is still ahead of us, `idle` as the backstop: a map handed over inside
+        // someone else's style.load handler can report !isStyleLoaded() while that event has already
+        // fired (the Standard style is an import that settles later), and waiting on it would hang.
+        let done = false;
+        const once = () => {
+          if (done) return;
+          done = true;
+          fn(m);
+        };
+        m.once('style.load', once);
+        m.once('idle', once);
+      },
+      { immediate: true },
+    );
+  }
+  return map;
+}
+
+/**
+ * An element mapbox will own (a marker body, a popup body). Created on demand rather than during
+ * setup: setup can run on a server, where `document` does not exist. Anything that needs the host
+ * only runs once a map exists, and a map only exists in a browser.
+ */
+export function useLazyHost() {
+  const host = shallowRef<HTMLElement | null>(null);
+  const ensure = (): HTMLElement => (host.value ??= document.createElement('div'));
+  return { host, ensure };
+}
+
+/**
+ * The scale a reader has already asked the browser for, as a multiplier on 16px.
+ *
+ * There is no media query for "large text" on the web. What there IS: a browser's default font size is
+ * a real accessibility setting, and it lands on the root element — so `1rem` is 20px for a reader who
+ * set 20px. Every Forest surface is rem-based and grows with it. A map canvas is the one that does not,
+ * because its symbols are drawn by the GPU from a size ramp in CSS pixels.
+ */
+export function readerTextScale(): number {
+  if (typeof document === 'undefined') return 1;
+  const root = parseFloat(getComputedStyle(document.documentElement).fontSize);
+  return Number.isFinite(root) && root > 0 ? root / 16 : 1;
+}
+
+/**
+ * Grow a map's symbols with the reader's own text setting, so the canvas stops being the one surface
+ * that ignores it.
+ *
+ * ⚠ CLAMP IT AT THE LAYER. `setScaleFactor` is a MAP-wide multiplier, and its default range allows
+ *   0.8× — which would push the mark under the floor its size ramp exists to defend. Pair this with
+ *   `icon-size-scale-range: MARKER_SIZE_SCALE_RANGE` on every Forest symbol layer; the clamp lives on
+ *   the layer, not here, because only the layer knows its own artwork's floor.
+ *
+ * ⚠ `setScaleFactor` is EXPERIMENTAL and triggers a re-layout of every symbol layer, so it is called
+ *   only when the value actually changes — not on every resize tick.
+ *
+ * Pass an explicit `factor` to drive it from a surface's own preference control instead of the browser.
+ */
+export function useMapScaleFactor(map: ShallowRef<Map | null>, factor?: () => number) {
+  const applied = shallowRef(1);
+
+  const apply = () => {
+    const m = map.value;
+    // Experimental API: a GL version without it must not take the map down.
+    if (!m || typeof m.setScaleFactor !== 'function') return;
+    const next = factor ? factor() : readerTextScale();
+    if (!Number.isFinite(next) || next === applied.value) return;
+    applied.value = next;
+    m.setScaleFactor(next);
+  };
+
+  // No event fires when a browser's default font size changes, so this re-reads on the things that do
+  // coincide with it — a resize, and the tab coming back to the front.
+  useMapReady(apply);
+  watch(map, apply);
+  if (typeof window !== 'undefined') {
+    window.addEventListener('resize', apply, { passive: true });
+    document.addEventListener('visibilitychange', apply);
+    onScopeDispose(() => {
+      window.removeEventListener('resize', apply);
+      document.removeEventListener('visibilitychange', apply);
+    });
+  }
+
+  /** what was last SET — not necessarily what renders, since the layer range clamps it */
+  return { applied, refresh: apply };
+}
+
+/**
+ * Camera moves with Forest's defaults. Never passes `essential` — that flag opts the move out of
+ * prefers-reduced-motion, and a camera flight is presentation, not content. GL JS then jumps
+ * instantly for anyone who asked for less motion.
+ */
+export function useMapCamera(map: ShallowRef<Map | null>) {
+  return {
+    /** fly to a point — for following an entity */
+    focus(center: [number, number], opts: { zoom?: number; pitch?: number; duration?: number } = {}) {
+      map.value?.flyTo({ center, duration: 2200, ...opts });
+    },
+    /** ease the pitch — depth is opt-in, so this is separate from focus */
+    tilt(pitch: number, opts: { duration?: number } = {}) {
+      map.value?.easeTo({ pitch, duration: 1200, ...opts });
+    },
+    /**
+     * Frame a bounding box, with room for overlay chrome. `padding` is room on top of whatever the
+     * map's own `padding` prop already keeps clear, so a fit lands inside the same box a fly does.
+     *
+     * ★ THAT SUM IS NOT WHAT fitBounds DOES — measured on GL JS 3.24.1, its `padding` REPLACES the
+     * transform padding. `_extendPadding` only falls back to `transform.padding` when the option is
+     * absent, and `_fitInternal` then forwards the option into the flight, which writes it onto the
+     * transform for good. On a map with setPadding({ left: 400 }), fitBounds(b, { padding: 48 })
+     * framed against the whole element and left the padding at 48 on all four sides afterwards, so
+     * the next camera move was wrong too. Hence: read the inset, add to it, and move the camera
+     * directly — flyTo without a `padding` key leaves the transform alone.
+     */
+    fit(bounds: LngLatBoundsLike, opts: { padding?: number; duration?: number } = {}) {
+      const m = map.value;
+      if (!m) return;
+      const gap = opts.padding ?? 48;
+      // Each side is optional on PaddingOptions — a map that has never been given a padding reports
+      // undefined rather than 0, which `withGap` resolves before adding.
+      const camera = m.cameraForBounds(bounds, { padding: withGap(m.getPadding(), gap) });
+      // Nothing fits the box at any zoom. GL JS has already warned; staying put beats jumping.
+      if (!camera) return;
+      // `duration` is read by key presence, so an undefined one would leave flyTo with NaN rather
+      // than its distance-derived default.
+      m.flyTo(opts.duration === undefined ? camera : { ...camera, duration: opts.duration });
+    },
+  };
+}