@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,154 @@
+<script setup lang="ts">
+// The compass — where north is, how far the view is tilted, and one click back to square.
+//
+//   <FMapCompass :map="map" />
+//
+// ★ IT STAYS, AND DISABLES AT SQUARE. It used to hide itself at north, following Google's mobile
+// behaviour ("the compass will only ever appear when the camera is oriented such that it has a non-zero
+// bearing or non-zero tilt"). Two things make that wrong HERE:
+//
+//   · Google's compass sits alone in a corner. Ours sits in a RAIL, so appearing and disappearing
+//     shifts every control below it — the layout jumps each time someone nudges the map off north.
+//   · Our own zoom pair disables at the zoom limits rather than vanishing. A control that goes inert
+//     when it has nothing to do is the pattern this rail already teaches; a control that evaporates is
+//     the exception.
+//
+// Present-and-inert also makes the capability discoverable: a pointer user who never guesses the
+// modifier-drag can still see that the map has an orientation to reset. `hideWhenSquare` restores the
+// mobile behaviour for a surface where the compass stands alone and shifts nothing.
+//
+// ★ THREE STATES, TWO CONTINUOUS CHANNELS. The glyph is not a binary indicator:
+//
+//     rotateZ(-bearing)  where north is
+//     rotateX(pitch)     how far the view leans away from you
+//
+// The second is Mapbox's own device — its NavigationControl documents `visualizePitch` as "the pitch is
+// visualized by rotating X-axis of compass". So tilt is legible on the compass itself, and FMapTilt is
+// left as what it should be: the way IN to the mode, not a second indicator of it.
+//
+// Fill is the third signal, and the one readable without measuring an angle: outline means square-on,
+// filled means off-axis on either channel.
+//
+// ★ The needle reads the map's OWN bearing and pitch from its `rotate`/`pitch` events rather than
+// mirroring them in state — a second copy drifts during an inertial spin, which is exactly when it is
+// being watched.
+//
+// ★ `navigation-2`, not `navigation`. The needle has to be SYMMETRIC about its vertical axis or its
+// resting position already looks like a heading: `navigation` is a tilted paper plane, so at north it
+// reads as pointing north-east and every rotation carries the glyph's own lean as an offset.
+//
+// The map arrives as a prop for the same reason it does in FMapZoom: <FMap> is a SIBLING, sitting in the
+// HUD's default slot while a rail control sits in a rail, so it is never on the control's ancestor chain.
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import type mapboxgl from 'mapbox-gl';
+import FCanvasControl from '../canvas/FCanvasControl.vue';
+
+const props = withDefaults(
+  defineProps<{
+    map?: mapboxgl.Map | null;
+    /**
+     * Hide it entirely while the view is square, the way a phone map does. Only right where the compass
+     * stands alone — in a rail it takes its siblings with it every time it appears.
+     */
+    hideWhenSquare?: boolean;
+  }>(),
+  { map: null, hideWhenSquare: false },
+);
+
+/** What the view is doing, which is what the glyph and the label both read from. */
+export type CompassState = 'square' | 'rotated' | 'tilted';
+
+const bearing = ref(0);
+const pitch = ref(0);
+
+// Under a degree reads as square to anyone looking, and floating-point camera values rarely land on 0.
+const SQUARE_EPSILON = 1;
+
+const rotated = computed(() => Math.abs(bearing.value) >= SQUARE_EPSILON);
+const tilted = computed(() => pitch.value >= SQUARE_EPSILON);
+const state = computed<CompassState>(() =>
+  tilted.value ? 'tilted' : rotated.value ? 'rotated' : 'square',
+);
+const square = computed(() => state.value === 'square');
+const visible = computed(() => !!props.map && (!props.hideWhenSquare || !square.value));
+
+const sync = () => {
+  const m = props.map;
+  if (!m) return;
+  bearing.value = m.getBearing();
+  pitch.value = m.getPitch();
+};
+
+watch(
+  () => props.map,
+  (m, _old, onCleanup) => {
+    if (!m) return;
+    sync();
+    m.on('rotate', sync);
+    m.on('pitch', sync);
+    onCleanup(() => {
+      m.off('rotate', sync);
+      m.off('pitch', sync);
+    });
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => {
+  props.map?.off('rotate', sync);
+  props.map?.off('pitch', sync);
+});
+
+// ★ easeTo, not jumpTo: the reset is a camera move the operator is watching, and a north-up snap loses
+// the connection between where they were pointing and where they end up. The duration rides the motion
+// tokens like every other travel in the system.
+const reset = () => props.map?.easeTo({ bearing: 0, pitch: 0 });
+
+// ★ The label names the axis that is ACTUALLY off. A fixed "reset to north" once announced a heading of
+// 0 degrees on a map that was merely tilted — a state a sighted user can see and a screen-reader user
+// was being told the opposite of.
+const label = computed(() => {
+  const deg = Math.round((bearing.value + 360) % 360);
+  if (rotated.value && tilted.value) return `Facing ${deg} degrees and tilted — reset the view`;
+  if (rotated.value) return `Facing ${deg} degrees — reset to north`;
+  if (tilted.value) return 'Tilted — reset to flat';
+  return 'Facing north, flat';
+});
+
+// ★ FILL, not a second glyph. `navigation-2`'s path is a closed shape, so `fill-current` turns the same
+// needle solid — the state reads without changing what the icon IS. The obvious alternative,
+// `navigation-2-off`, is the crossed-out variant: in every icon set a slash means DISABLED, and the
+// off-axis state is the one where the control is most alive.
+//
+// ★ And the selector has to reach the PATH, not the <svg>. Lucide puts `fill="none"` on the path itself,
+// and a presentation attribute on an element beats a value INHERITED from its parent — so `fill-current`
+// on the svg is silently inert. Measured: computed fill stayed `none` with the class applied.
+const iconClass = computed(() =>
+  square.value
+    ? ''
+    : '[&_[data-slot=leadingIcon]]:text-primary [&_[data-slot=leadingIcon]_path]:fill-current',
+);
+
+// ★ The pitch lean is DAMPENED. A 60-degree map tilted through a 20px glyph is nearly edge-on and reads
+// as a rendering fault rather than as a state; half the angle keeps the lean legible while staying
+// monotonic with the camera. The needle still says "leaning", which is the whole job.
+const PITCH_VISUAL_RATIO = 0.5;
+</script>
+
+<template>
+  <FCanvasControl
+    v-if="visible"
+    icon="i-lucide-navigation-2"
+    :label="label"
+    :disabled="square"
+    :style="{
+      '--forest-compass-bearing': `${-bearing}deg`,
+      '--forest-compass-pitch': `${pitch * PITCH_VISUAL_RATIO}deg`,
+    }"
+    :class="[
+      '[&_[data-slot=leadingIcon]]:[transform:perspective(120px)_rotateX(var(--forest-compass-pitch))_rotateZ(var(--forest-compass-bearing))]',
+      iconClass,
+    ]"
+    @click="reset"
+  />
+</template>

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

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+// Where the map is, in numbers.
+//
+//   <FMapCoordinates :map="map" />
+//
+// ★ A READOUT, LIKE THE SCALE BAR, and it takes the same corner and the same tile: the chrome surface
+// shared with the controls, and the tighter 8px radius that says a thing is not a control. The two are
+// the only pieces of map chrome that answer a question rather than take an instruction.
+//
+// ★ ON TOUCH THERE IS NO POINTER, so a pointer readout on a phone is a tile that never says anything.
+// `auto` reads the pointer where one exists and the map's centre where it does not — the same shape as
+// <FMap>'s own `lightPreset: 'auto'`: read the environment, and let a surface with a reason pin it.
+//
+// ★ AND IT COPIES. This is the one place a readout earns an affordance. What an operator does with a
+// coordinate is paste it — into a ticket, a message, another tool — and a number that can only be read
+// off the screen is one somebody retypes by hand and gets a digit wrong. The pair is printed the way it
+// is typed: "lat, lng", the opposite of the [lng, lat] the rest of the subsystem speaks.
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import type mapboxgl from 'mapbox-gl';
+import { coordinatePlaces, formatCoordinates, type LngLat } from './coordinates';
+
+const props = withDefaults(
+  defineProps<{
+    /** The live map, from <FMap @ready>. Null until it arrives, which reads as nothing yet. */
+    map?: mapboxgl.Map | null;
+    /** `auto` follows the device: the pointer where there is one, the centre where there is not. */
+    source?: 'auto' | 'pointer' | 'centre';
+    /** Click to copy. Off returns it to a plain, unpressable readout. */
+    copy?: boolean;
+  }>(),
+  { map: null, source: 'auto', copy: true },
+);
+
+// Read once, at setup: a device does not grow a mouse mid-session, and a media query listener here
+// would be machinery for a case that does not arise.
+const coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+const mode = computed(() => (props.source === 'auto' ? (coarse ? 'centre' : 'pointer') : props.source));
+
+const at = ref<LngLat | null>(null);
+const zoom = ref(0);
+const copied = ref(false);
+let clearCopied: ReturnType<typeof setTimeout> | undefined;
+
+const text = computed(() =>
+  at.value ? formatCoordinates(at.value, coordinatePlaces(zoom.value, at.value[1])) : null,
+);
+
+watch(
+  [() => props.map, mode],
+  ([m, which], _old, onCleanup) => {
+    at.value = null;
+    if (!m) return;
+
+    const fromCentre = () => {
+      const c = m.getCenter();
+      at.value = [c.lng, c.lat];
+      zoom.value = m.getZoom();
+    };
+    const fromPointer = (e: mapboxgl.MapMouseEvent) => {
+      at.value = [e.lngLat.lng, e.lngLat.lat];
+      zoom.value = m.getZoom();
+    };
+    // ★ The tile stays, holding a placeholder, rather than unmounting when the pointer leaves the
+    // canvas. A readout that appears and disappears reflows the rail every time a reader reaches for
+    // the sidebar, and a stale coordinate left behind would be worse than an em dash.
+    const clear = () => {
+      at.value = null;
+    };
+
+    if (which === 'centre') {
+      fromCentre();
+      m.on('move', fromCentre);
+      onCleanup(() => m.off('move', fromCentre));
+      return;
+    }
+
+    m.on('mousemove', fromPointer);
+    m.on('mouseout', clear);
+    onCleanup(() => {
+      m.off('mousemove', fromPointer);
+      m.off('mouseout', clear);
+    });
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => clearTimeout(clearCopied));
+
+async function copyPair() {
+  if (!text.value || !navigator.clipboard) return;
+  try {
+    await navigator.clipboard.writeText(text.value);
+  } catch {
+    // Denied permission, an insecure origin, a browser that refuses outside a trusted gesture. The
+    // label simply does not change, which is the honest report — claiming "Copied" over an empty
+    // clipboard is the one outcome worth avoiding.
+    return;
+  }
+  copied.value = true;
+  clearTimeout(clearCopied);
+  clearCopied = setTimeout(() => (copied.value = false), 1200);
+}
+
+// The scale bar's tile, exactly — the two are a pair and must read as one material. Kept as a constant
+// rather than duplicated across the two branches below.
+const TILE =
+  'forest-canvas-chrome pointer-events-auto block rounded-sm px-2 py-1 ring ring-[var(--neutral-300)] ring-inset dark:ring-[var(--neutral-700)]';
+const INK =
+  'text-[0.6875rem] leading-none font-bold tracking-wide tabular-nums text-[var(--neutral-900)] dark:text-[var(--neutral-100)]';
+</script>
+
+<template>
+  <!-- Pressable only when it can copy. The affordance is a fill and a focus ring, never a second
+       radius or a shadow: it is the same tile as the scale bar, with something to do. -->
+  <button
+    v-if="copy"
+    type="button"
+    :class="[
+      TILE,
+      'cursor-pointer transition-[background-color] duration-(--motion-fast) ease-(--motion-ease-out) motion-reduce:transition-none',
+      'hover:[--forest-canvas-chrome-fill:var(--ui-bg)]',
+      'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
+    ]"
+    :disabled="!text"
+    :aria-label="text ? `Copy the coordinate ${text}` : 'No coordinate to copy yet'"
+    @click="copyPair()"
+  >
+    <span :class="INK">{{ copied ? 'Copied' : (text ?? '—') }}</span>
+  </button>
+
+  <div v-else :class="TILE">
+    <span :class="INK">{{ text ?? '—' }}</span>
+  </div>
+</template>

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

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+// The drawing tool switch — one control that opens into the tools, plus what an unfinished shape needs.
+//
+//   <FMapDrawTools
+//     v-model:tool="tool"
+//     :drafting="!!draw.draft.value"
+//     :can-finish="!draw.invalid.value"
+//     :can-undo="draw.canUndo.value"
+//     @finish="draw.finish" @cancel="draw.cancel" @undo="draw.undo"
+//   />
+//
+// ★ THE TRIGGER WEARS THE ACTIVE TOOL, as <FMapTools> does: the question a reader asks passing a map is
+// "what happens if I drag", and a fixed icon would make them open the group to find out.
+//
+// ★ FINISH AND CANCEL ARE CONTROLS, NOT JUST KEYS. Enter and Escape are the fast path and they are not
+// reachable on a phone, so an unfinished ring would be unfinishable there — the same reason region
+// select grew an armed tool instead of a held modifier. They appear only while something is in flight,
+// because a Finish that is always present is a button that usually does nothing.
+//
+// ★ UNDO IS ALWAYS THERE WHILE A TOOL IS ARMED, and disabled when there is nothing to take back. A
+// control that came and went as history filled would move the two beside it every time a vertex landed.
+import { computed } from 'vue';
+import FCanvasControl from '../canvas/FCanvasControl.vue';
+import FCanvasControlGroup from '../canvas/FCanvasControlGroup.vue';
+import FCanvasFlyout from '../canvas/FCanvasFlyout.vue';
+import type { DrawTool } from './draw';
+
+const tool = defineModel<DrawTool>('tool', { default: 'off' });
+
+const props = withDefaults(
+  defineProps<{
+    /** whether a ring is being placed right now — reveals finish and cancel */
+    drafting?: boolean;
+    /** whether the ring in flight can close. A self-crossing one cannot */
+    canFinish?: boolean;
+    canUndo?: boolean;
+    /** The axis the cluster opens along — horizontal for a vertical rail, and the reverse. */
+    orientation?: 'vertical' | 'horizontal';
+    /** Which end the trigger is pinned to, so the cluster opens inward. */
+    side?: 'start' | 'end';
+    /** Drop a tool a surface has no use for. Keep `off` — it is how a reader puts one down. */
+    tools?: DrawTool[];
+  }>(),
+  {
+    drafting: false,
+    canFinish: true,
+    canUndo: false,
+    orientation: 'horizontal',
+    side: 'end',
+    tools: () => ['off', 'polygon', 'rectangle', 'circle', 'edit'],
+  },
+);
+
+const emit = defineEmits<{ finish: []; cancel: []; undo: [] }>();
+
+const ICON: Record<DrawTool, string> = {
+  off: 'i-lucide-hand',
+  polygon: 'i-lucide-pentagon',
+  rectangle: 'i-lucide-square',
+  circle: 'i-lucide-circle',
+  edit: 'i-lucide-spline-pointer',
+};
+
+const LABEL: Record<DrawTool, string> = {
+  off: 'Pan the map',
+  polygon: 'Draw a boundary',
+  rectangle: 'Draw a rectangle',
+  circle: 'Draw a radius',
+  edit: 'Edit a shape',
+};
+
+const items = computed(() =>
+  props.tools.map((t) => ({ value: t, icon: ICON[t], label: LABEL[t], pressed: tool.value === t })),
+);
+
+const armed = computed(() => tool.value !== 'off');
+</script>
+
+<template>
+  <FCanvasControlGroup :orientation="orientation">
+    <FCanvasFlyout
+      :icon="ICON[tool]"
+      :label="LABEL[tool]"
+      :pressed="armed"
+      :items="items"
+      :orientation="orientation"
+      :side="side"
+      close-label="Close the tools"
+      @select="tool = $event as DrawTool"
+    />
+    <FCanvasControl
+      v-if="armed"
+      icon="i-lucide-undo-2"
+      label="Undo"
+      :disabled="!canUndo"
+      @click="emit('undo')"
+    />
+    <template v-if="drafting">
+      <!-- Finish is disabled rather than hidden while the ring cannot close: the reader has asked for a
+           shape that crosses itself, and a control that vanished would leave them with no statement of
+           why nothing happens. The map paints the crossing in the error colour beside it. -->
+      <FCanvasControl
+        icon="i-lucide-check"
+        label="Finish the shape"
+        :disabled="!canFinish"
+        @click="emit('finish')"
+      />
+      <!-- ★ A BIN, NOT A CROSS, and the reason is two controls away. While the flyout is OPEN its
+           trigger becomes a dismiss wearing `i-lucide-x`, so a cross here put two identical glyphs in
+           one rail — one closing a menu, one destroying the ring the reader is drawing. Tick against
+           cross is the tidier pair right up until the cross means two things; the destructive one is
+           the one that has to move, because it is the one with no way back. -->
+      <FCanvasControl icon="i-lucide-trash-2" label="Discard the shape" @click="emit('cancel')" />
+    </template>
+  </FCanvasControlGroup>
+</template>

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

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+// Fullscreen, as canvas chrome.
+//
+//   <FMapFullscreen :map="map" />
+//
+// ★ REBUILT, NOT WRAPPED — the split FMapZoom and FMapScale already draw. Mapbox's FullscreenControl
+// mounts into a corner container inside the map element, which is not one of the HUD's areas: it cannot
+// sit in a rail, cannot take the canvas-chrome surface with the rest of the chrome, and cannot step
+// aside for an open side panel. What is underneath is one method and one event, so nothing is lost.
+//
+// ★ THE HUD GOES FULLSCREEN, NOT THE CANVAS. The chrome is a sibling layer ABOVE the canvas inside the
+// HUD, so fullscreening the map element alone drops the zoom pair, the compass, the scale bar and this
+// button at the exact moment there is the most map to operate. Mapbox's control could not have done
+// this — it has never heard of the HUD — which is the second reason not to wrap it.
+//
+// ★ NO RESIZE CODE, and the absence is deliberate rather than an omission. <FMap> observes its
+// CONTAINER rather than the window, because a sidebar collapsing does not resize the window either.
+// Entering fullscreen is that same case, handled by machinery that already exists.
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import type mapboxgl from 'mapbox-gl';
+import FCanvasControl from '../canvas/FCanvasControl.vue';
+import { fullscreenApi, isFullscreen } from './fullscreen';
+
+const props = withDefaults(
+  defineProps<{
+    /** The live map, from <FMap @ready>. Null until it arrives, which disables the control. */
+    map?: mapboxgl.Map | null;
+    /**
+     * What goes fullscreen. Defaults to the enclosing <FCanvasHud>, and to the map's own container
+     * where there is none — pass an element for a surface that frames the map in something wider,
+     * a split view or a dashboard tile that should travel with it.
+     */
+    target?: HTMLElement | null;
+  }>(),
+  { map: null, target: null },
+);
+
+// Resolved once. In an SSR pass there is no document at all, and `null` is also the honest answer for
+// a browser that has no fullscreen — see fullscreen.ts.
+const api = fullscreenApi(typeof document === 'undefined' ? null : (document as unknown as Record<string, unknown>));
+
+const active = ref(false);
+
+const element = computed<HTMLElement | null>(() => {
+  if (props.target) return props.target;
+  const container = props.map?.getContainer() ?? null;
+  return (container?.closest('[data-forest-canvas]') as HTMLElement | null) ?? container;
+});
+
+// ★ READ FROM THE DOCUMENT, NEVER FROM A CLICK COUNT. Escape leaves fullscreen without touching this
+// button, and so does the browser's own chrome — a control holding a private boolean would sit lit
+// over a document that had already left. Same rule the tilt toggle follows for pitch.
+const sync = () => {
+  active.value = isFullscreen(document as unknown as Record<string, unknown>, element.value);
+};
+
+watch(
+  element,
+  () => sync(),
+  { immediate: true },
+);
+
+if (api) document.addEventListener(api.event, sync);
+onBeforeUnmount(() => api && document.removeEventListener(api.event, sync));
+
+function toggle() {
+  const el = element.value;
+  if (!api || !el) return;
+  const doc = document as unknown as Record<string, () => Promise<void> | void>;
+  const node = el as unknown as Record<string, () => Promise<void> | void>;
+  // Both can reject — a browser may refuse a request that did not come from a gesture it trusts —
+  // and there is nothing useful to do about it: the event never fires, so the button stays unlit and
+  // says so. Swallowed rather than left to surface as an unhandled rejection in the console.
+  void Promise.resolve(active.value ? doc[api.exit]?.() : node[api.request]?.()).catch(() => {});
+}
+</script>
+
+<template>
+  <!-- ★ ABSENT RATHER THAN DISABLED where fullscreen does not exist — Safari on iPhone, or an iframe
+       without `allowfullscreen`. Forest's disabled treatment says "not right now", which would be a
+       lie about a browser that will never allow it, and a control that can never do its one thing is
+       worse than a missing one: it invites a press that fails silently. <FMapCompass> conditions its
+       own presence for the same reason. -->
+  <FCanvasControl
+    v-if="api"
+    :icon="active ? 'i-lucide-minimize' : 'i-lucide-maximize'"
+    :label="active ? 'Leave fullscreen' : 'Fullscreen'"
+    :disabled="!map && !target"
+    :pressed="active"
+    @click="toggle()"
+  />
+</template>