@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,51 @@
+// The reactive half of vehicleFilter.ts — state, and the three renderings kept in step with it.
+//
+// No map. A filter is not a map concern: the same value drives a GL layer, a table, a KPI row and a
+// link, and a composable that took an instance would have forced the surfaces without one to reach
+// past it to the pure functions.
+import { computed, ref, type Ref } from 'vue';
+import {
+  activeAxisCount,
+  decodeVehicleFilter,
+  encodeVehicleFilter,
+  isEmptyVehicleFilter,
+  toggleVehicleFilter,
+  vehicleFilterExpression,
+  vehicleFilterMatch,
+  type VehicleFilter,
+  type VehicleFilterListAxis,
+  type VehicleFilterProps,
+} from './vehicleFilter';
+
+export function useVehicleFilter(initial: VehicleFilter = {}, props: VehicleFilterProps = {}) {
+  const filter = ref<VehicleFilter>({ ...initial }) as Ref<VehicleFilter>;
+
+  return {
+    /** the value itself — writable, so a form can `v-model` into it */
+    filter,
+    /** for `layer.filter`. `['literal', true]` while nothing is constrained */
+    expression: computed(() => vehicleFilterExpression(filter.value, props)),
+    /** for the list and the counts. Call it in a template as `match(vehicle)` */
+    match: computed(() => vehicleFilterMatch(filter.value)),
+    /** how many axes bite — the number beside a Clear button */
+    active: computed(() => activeAxisCount(filter.value)),
+    isEmpty: computed(() => isEmptyVehicleFilter(filter.value)),
+    /** for the link. Empty string while nothing is constrained, so the URL key can be dropped */
+    query: computed(() => encodeVehicleFilter(filter.value)),
+    /** add or remove one value on a list axis — what a chip row calls */
+    toggle<K extends VehicleFilterListAxis>(axis: K, value: NonNullable<VehicleFilter[K]>[number]) {
+      filter.value = toggleVehicleFilter(filter.value, axis, value);
+    },
+    /** replace wholesale. A new object, so a caller cannot keep a handle on the internal one */
+    set(next: VehicleFilter) {
+      filter.value = { ...next };
+    },
+    clear() {
+      filter.value = {};
+    },
+    /** restore from a link. Unknown values are dropped, so an older link still opens */
+    apply(query: string | null | undefined) {
+      filter.value = decodeVehicleFilter(query);
+    },
+  };
+}

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

@@ -0,0 +1,124 @@
+// The list beside the map — what is on screen, as rows.
+//
+// It reads a source the surface already owns rather than adding one. That is the difference from
+// `useMarkerSource`, which owns its source because it exists to place DOM markers; the mass tier has
+// no DOM markers at all, and still needs a list.
+//
+// ★ `querySourceFeatures`, NOT `queryRenderedFeatures`. The rendered query omits symbols dropped by
+// the collision index, so a list built from it silently loses the bikes whose marks lost a label
+// fight — and the reader sees a list that disagrees with the map for no visible reason. The source
+// query answers "what is here", which is the question a list is asking.
+import { computed, onScopeDispose, shallowRef, watch, type ShallowRef } from 'vue';
+import type { Map } from 'mapbox-gl';
+import { collectVisible, type CollectOptions, type ViewBox, type VisibleFeature } from './visibleFeatures';
+
+export interface VisibleFeaturesOptions extends CollectOptions {
+  /** the source id — the one a `useMapOverlay` spec declared */
+  source: string;
+  sourceLayer?: string;
+  /**
+   * A style-spec filter, evaluated by GL itself.
+   *
+   * ★ Hand it `useVehicleFilter().expression` — the same value the layer carries — and the list
+   * cannot disagree with the map, because the same engine decided both.
+   */
+  filter?: unknown[];
+  /** `idle` re-reads once motion settles (cheap); `move` tracks every frame */
+  refresh?: 'idle' | 'move';
+}
+
+const EMPTY = { items: [] as VisibleFeature[], count: 0, capped: false };
+
+export function useVisibleFeatures(map: ShallowRef<Map | null>, options: () => VisibleFeaturesOptions) {
+  const result = shallowRef(EMPTY);
+  let attached: Map | null = null;
+  let listening: 'idle' | 'move' = 'idle';
+
+  function read() {
+    const m = map.value;
+    if (!m) return;
+    const o = options();
+    // A source the surface has not added yet is not an error — an overlay spec applies a tick later,
+    // and `sourcedata` will bring us back the moment it does.
+    if (!m.getSource(o.source)) {
+      result.value = EMPTY;
+      return;
+    }
+    const bounds = m.getBounds();
+    if (!bounds) return;
+    const box: ViewBox = {
+      west: bounds.getWest(),
+      south: bounds.getSouth(),
+      east: bounds.getEast(),
+      north: bounds.getNorth(),
+    };
+    const features = m.querySourceFeatures(o.source, {
+      ...(o.sourceLayer ? { sourceLayer: o.sourceLayer } : {}),
+      ...(o.filter ? { filter: o.filter } : {}),
+    } as never) as unknown as GeoJSON.Feature[];
+    result.value = collectVisible(features, box, o);
+  }
+
+  function attach(m: Map) {
+    if (attached) return;
+    attached = m;
+    listening = options().refresh === 'move' ? 'move' : 'idle';
+    m.on(listening, read);
+    // Tiles arrive after the camera settles, so the first `idle` can see a fraction of the source.
+    // `sourcedata` is what turns a partial answer into the whole one.
+    m.on('sourcedata', read);
+    read();
+  }
+
+  // ★ A pending `once` is a listener that has not fired YET, not one that is gone. A panel closed
+  // while the style is still loading disposes with nothing attached, and then `style.load` runs the
+  // orphaned `start`, which attaches `idle` and `sourcedata` handlers to a map that outlives it —
+  // for good. Ten open-and-close cycles leave ten readers re-querying the source on every tick.
+  let disposed = false;
+  let pending: Map | null = null;
+
+  function start() {
+    if (disposed) return;
+    const m = map.value;
+    if (!m || attached) return;
+    if (m.isStyleLoaded()) {
+      attach(m);
+      return;
+    }
+    pending = m;
+    m.once('styledata', start);
+    m.once('idle', start);
+  }
+
+  watch(map, start, { immediate: true });
+
+  // A filter change moves nothing and loads nothing, so no map event fires — and the list would go on
+  // showing what the layer has already stopped drawing. Stringified because the expression is rebuilt
+  // into a new array on every filter edit.
+  watch(
+    () => JSON.stringify(options().filter ?? null),
+    () => read(),
+  );
+
+  onScopeDispose(() => {
+    disposed = true;
+    // The guard above is the belt; this is the braces. `once` handlers come off by identity like any
+    // other, so a scope that never got as far as attaching still leaves the map clean.
+    pending?.off('styledata', start);
+    pending?.off('idle', start);
+    const m = attached;
+    if (!m) return;
+    m.off(listening, read);
+    m.off('sourcedata', read);
+  });
+
+  return {
+    /** the rows, capped. Keyed by `key`, which survives a tile seam and a re-read */
+    features: computed(() => result.value.items),
+    /** how many are in view — the number BEFORE the cap, which is the one a reader wants */
+    count: computed(() => result.value.count),
+    /** whether the list is short of `count`, so a surface can say "500 of 1,284" */
+    capped: computed(() => result.value.capped),
+    refresh: read,
+  };
+}