@madebylars.com/mbl-fleetmap 1.0.0

package/README.md

@@ -0,0 +1,301 @@
+# mbl-fleetmap
+
+[![npm version][npm-version-src]][npm-version-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+A Nuxt 4 module that wraps Leaflet with a transport-specific composable API — driver markers, live position updates, route display, and pickup/dropoff pins. No API key required (OpenStreetMap tiles).
+
+---
+
+## Installation
+
+```bash
+npm install @madebylars.com/mbl-fleetmap
+```
+
+Register the module in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@madebylars.com/mbl-fleetmap'],
+
+  mblFleetMap: {
+    defaultCenter: [59.913, 10.752],  // [lat, lng] — Oslo
+    defaultZoom: 13,
+    // tileUrl and attribution default to OpenStreetMap — no changes needed
+  },
+})
+```
+
+That's it. The component and all composables are auto-imported.
+
+---
+
+## Configuration options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tileUrl` | `string` | OpenStreetMap URL | Tile server URL template |
+| `attribution` | `string` | `© OpenStreetMap contributors` | Map attribution text |
+| `defaultZoom` | `number` | `13` | Initial zoom level |
+| `defaultCenter` | `[number, number]` | `[51.505, -0.09]` | Initial `[lat, lng]` |
+| `clusterMarkers` | `boolean` | `true` | Cluster driver markers when zoomed out |
+
+---
+
+## Quick start
+
+### 1. Add the map to a page
+
+```vue
+<template>
+  <div class="map-container">
+    <MblFleetMap
+      map-id="fleet"
+      @ready="onMapReady"
+      @click="onMapClick"
+    />
+  </div>
+</template>
+
+<style scoped>
+.map-container {
+  height: 100vh;
+  width: 100%;
+}
+</style>
+```
+
+The component is renderless — it fills whatever container you give it. Apply height via CSS; without a defined height Leaflet has nothing to render into.
+
+### 2. Add drivers and routes on ready
+
+```vue
+<script setup lang="ts">
+const { addDriver, updateDriver } = useDriverMarkers('fleet')
+const { setPickup, setDropoff }   = useJobPins('fleet')
+const { drawRoute }               = useFleetRoute('fleet')
+
+function onMapReady() {
+  // Add a driver marker (green circle with initials)
+  addDriver({
+    driverId: 'd1',
+    name:     'Alice Smith',
+    lat:      59.913,
+    lng:      10.752,
+    status:   'active',   // 'active' | 'idle' | 'offline'
+    jobId:    'job1',
+  })
+
+  // Pickup (green pin) and dropoff (red pin)
+  setPickup( 'job1', 59.920, 10.740, 'Oslo S')
+  setDropoff('job1', 59.905, 10.765, 'Grønland')
+
+  // Straight-line route (replace with OSRM/GraphHopper waypoints for real routing)
+  drawRoute('job1', [
+    [59.920, 10.740],
+    [59.913, 10.752],
+    [59.905, 10.765],
+  ])
+}
+
+function onMapClick({ lat, lng }: { lat: number; lng: number }) {
+  console.log('clicked', lat, lng)
+}
+</script>
+```
+
+---
+
+## Composables
+
+All composables take a `mapId` string that matches the `map-id` prop on `<MblFleetMap>`. You can have multiple independent maps on one page by using different IDs.
+
+### `useFleetMap(mapId)`
+
+Access the raw Leaflet instance and control the viewport.
+
+```ts
+const {
+  map,       // ComputedRef<L.Map | null>  — null until 'ready' fires
+  isReady,   // ComputedRef<boolean>
+  setCenter, // (lat, lng, zoom?) => void
+  fitBounds, // (bounds: L.LatLngBounds) => void
+} = useFleetMap('fleet')
+```
+
+### `useDriverMarkers(mapId)`
+
+Manage driver markers. Each marker is a coloured circle with the driver's initials (CSS only, no images).
+
+| Status | Colour |
+|---|---|
+| `active` | Green `#16a34a` |
+| `idle` | Amber `#d97706` |
+| `offline` | Grey `#6b7280` |
+
+```ts
+const {
+  drivers,       // Ref<Map<string, DriverMarker>>
+  addDriver,     // (driver: DriverMarker) => void
+  updateDriver,  // (driverId, [lat, lng]) => void  — animates smoothly over 500 ms
+  removeDriver,  // (driverId) => void
+  clearDrivers,  // () => void
+} = useDriverMarkers('fleet')
+```
+
+**Live position updates** — call `updateDriver` as often as you receive GPS ticks. The marker slides to its new position over 500 ms using a CSS transform transition.
+
+```ts
+// e.g. fed by a WebSocket or polling composable
+watch(livePosition, pos => {
+  updateDriver('d1', [pos.lat, pos.lng])
+})
+```
+
+### `useJobPins(mapId)`
+
+Pickup (green teardrop) and dropoff (red teardrop) pins with hover tooltips. CSS only, no images.
+
+```ts
+const {
+  setPickup,  // (jobId, lat, lng, label?) => void
+  setDropoff, // (jobId, lat, lng, label?) => void
+  clearJob,   // (jobId) => void
+  clearAll,   // () => void
+} = useJobPins('fleet')
+```
+
+### `useFleetRoute(mapId)`
+
+Draw a polyline between waypoints (solid blue, weight 4).
+
+> **Note:** The module draws straight lines between the waypoints you provide. Hook up OSRM, GraphHopper, or any routing API in your own code and pass the snapped waypoints here.
+
+```ts
+const {
+  routes,      // Ref<Map<string, L.Polyline>>
+  drawRoute,   // (jobId, waypoints: [lat, lng][]) => void
+  clearRoute,  // (jobId) => void
+  clearAll,    // () => void
+} = useFleetRoute('fleet')
+```
+
+### `useMapEvents(mapId)`
+
+Subscribe to map and marker events. Call `offAll()` when the component that registered the listeners unmounts.
+
+```ts
+const { onDriverClick, onMapClick, onDriverHover, offAll } = useMapEvents('fleet')
+
+onDriverClick(driver => {
+  // driver is the full DriverMarker object at the time of the click
+  openDriverPanel(driver.driverId)
+})
+
+onDriverHover(driver => {
+  // driver is null when the cursor leaves a marker
+  hoveredDriver.value = driver
+})
+
+onMapClick((lat, lng) => {
+  console.log('map click', lat, lng)
+})
+
+onUnmounted(offAll)
+```
+
+---
+
+## Multiple maps on one page
+
+Use a different `mapId` for each `<MblFleetMap>` instance. Every composable scopes its state to the ID you pass, so they never interfere.
+
+```vue
+<!-- Dispatcher full-screen map -->
+<MblFleetMap map-id="dispatch" @ready="setupDispatch" />
+
+<!-- Small order-detail inset -->
+<MblFleetMap map-id="order-detail" @ready="setupOrderDetail" />
+```
+
+```ts
+const { addDriver }  = useDriverMarkers('dispatch')
+const { setDropoff } = useJobPins('order-detail')
+```
+
+---
+
+## TypeScript types
+
+All types are exported from the package root:
+
+```ts
+import type {
+  DriverMarker,
+  JobPin,
+  RouteOptions,
+  MarkerStatus,
+  LatLng,
+} from '@madebylars.com/mbl-fleetmap'
+```
+
+```ts
+interface DriverMarker {
+  driverId: string
+  name:     string
+  lat:      number
+  lng:      number
+  status:   'active' | 'idle' | 'offline'
+  jobId?:   string
+}
+```
+
+---
+
+## SSR
+
+Leaflet requires the browser DOM and cannot run server-side. The module handles this automatically:
+
+- The plugin is registered as `mode: 'client'` — it never runs during SSR.
+- `<MblFleetMap>` is registered as `mode: 'client'` — it is not rendered on the server.
+- Composable methods are no-ops when called before the client plugin has initialised (which should never happen in normal use, since `ready` only fires client-side).
+
+No `<ClientOnly>` wrapper or `process.client` guards are needed in your own code.
+
+---
+
+## Integration with mbl-transport
+
+Replace all `mbl-mapman` references:
+
+| View | Composables |
+|---|---|
+| Dispatcher fleet | `useDriverMarkers('fleet')` fed by `useFleet()` from mbl-order · `useMapEvents('fleet').onDriverClick()` opens driver panel |
+| Driver job navigation | `useJobPins` + `useFleetRoute` + `useDriverMarkers` with a single self-position marker |
+| Customer order detail | Single driver marker + dropoff pin, read-only (no click handlers) |
+
+---
+
+## Contributing
+
+```bash
+npm install          # install dependencies
+npm run dev:prepare  # generate type stubs
+npm run dev          # start playground at localhost:3000
+npm run lint
+npm run test
+```
+
+---
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/@madebylars.com/mbl-fleetmap/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/@madebylars.com/mbl-fleetmap
+
+[license-src]: https://img.shields.io/npm/l/@madebylars.com/mbl-fleetmap.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/@madebylars.com/mbl-fleetmap
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,18 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    tileUrl: string;
+    attribution: string;
+    defaultZoom: number;
+    defaultCenter: [number, number];
+    clusterMarkers: boolean;
+}
+declare module 'nuxt/schema' {
+    interface PublicRuntimeConfig {
+        mblFleetMap: ModuleOptions;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "mbl-fleetmap",
+  "configKey": "mblFleetMap",
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,32 @@
+import { defineNuxtModule, createResolver, addPlugin, addComponent, addImportsDir } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "mbl-fleetmap",
+    configKey: "mblFleetMap"
+  },
+  defaults: {
+    tileUrl: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
+    attribution: "\xA9 OpenStreetMap contributors",
+    defaultZoom: 13,
+    defaultCenter: [51.505, -0.09],
+    clusterMarkers: true
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.css.push("leaflet/dist/leaflet.css");
+    nuxt.options.runtimeConfig.public.mblFleetMap = options;
+    addPlugin({
+      src: resolver.resolve("./runtime/plugin"),
+      mode: "client"
+    });
+    addComponent({
+      name: "MblFleetMap",
+      filePath: resolver.resolve("./runtime/components/MblFleetMap.vue"),
+      mode: "client"
+    });
+    addImportsDir(resolver.resolve("./runtime/composables"));
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/components/MblFleetMap.d.vue.ts

@@ -0,0 +1,20 @@
+type __VLS_Props = {
+    mapId: string;
+    center?: [number, number];
+    zoom?: number;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: () => any;
+    click: (args_0: {
+        lat: number;
+        lng: number;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReady?: (() => any) | undefined;
+    onClick?: ((args_0: {
+        lat: number;
+        lng: number;
+    }) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/MblFleetMap.vue

@@ -0,0 +1,41 @@
+<script setup>
+import { onMounted, onUnmounted, ref } from "vue";
+import { useRuntimeConfig } from "#app";
+import { registerMap, getMap, removeMap, getLeaflet } from "../utils/registry";
+import { emitMapClick } from "../utils/events";
+const props = defineProps({
+  mapId: { type: String, required: true },
+  center: { type: Array, required: false },
+  zoom: { type: Number, required: false }
+});
+const emit = defineEmits(["ready", "click"]);
+const containerEl = ref(null);
+onMounted(() => {
+  const L = getLeaflet();
+  if (!L || !containerEl.value) return;
+  const config = useRuntimeConfig().public.mblFleetMap;
+  const map = L.map(containerEl.value, {
+    center: props.center ?? config.defaultCenter,
+    zoom: props.zoom ?? config.defaultZoom
+  });
+  L.tileLayer(config.tileUrl, {
+    attribution: config.attribution
+  }).addTo(map);
+  map.on("click", (e) => {
+    const payload = { lat: e.latlng.lat, lng: e.latlng.lng };
+    emitMapClick(props.mapId, payload);
+    emit("click", payload);
+  });
+  registerMap(props.mapId, map);
+  emit("ready");
+});
+onUnmounted(() => {
+  const map = getMap(props.mapId);
+  if (map) map.remove();
+  removeMap(props.mapId);
+});
+</script>
+
+<template>
+  <div ref="containerEl" />
+</template>

package/dist/runtime/components/MblFleetMap.vue.d.ts

@@ -0,0 +1,20 @@
+type __VLS_Props = {
+    mapId: string;
+    center?: [number, number];
+    zoom?: number;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: () => any;
+    click: (args_0: {
+        lat: number;
+        lng: number;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReady?: (() => any) | undefined;
+    onClick?: ((args_0: {
+        lat: number;
+        lng: number;
+    }) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/composables/useDriverMarkers.d.ts

@@ -0,0 +1,22 @@
+import type { DriverMarker, LatLng } from '../../types.js';
+export declare function useDriverMarkers(mapId: string): {
+    addDriver: (driver: DriverMarker) => void;
+    updateDriver: (driverId: string, position: LatLng) => void;
+    removeDriver: (driverId: string) => void;
+    clearDrivers: () => void;
+    drivers: import("vue").Ref<Map<string, {
+        driverId: string;
+        name: string;
+        lat: number;
+        lng: number;
+        status: "active" | "idle" | "offline";
+        jobId?: string | undefined;
+    }> & Omit<Map<string, DriverMarker>, keyof Map<any, any>>, Map<string, DriverMarker> | (Map<string, {
+        driverId: string;
+        name: string;
+        lat: number;
+        lng: number;
+        status: "active" | "idle" | "offline";
+        jobId?: string | undefined;
+    }> & Omit<Map<string, DriverMarker>, keyof Map<any, any>>)>;
+};

package/dist/runtime/composables/useDriverMarkers.js

@@ -0,0 +1,72 @@
+import { ref } from "vue";
+import { getMap, getLeaflet } from "../utils/registry.js";
+import { emitDriverClick, emitDriverHover } from "../utils/events.js";
+const STATUS_COLORS = {
+  active: "#16a34a",
+  idle: "#d97706",
+  offline: "#6b7280"
+};
+function initials(name) {
+  return name.split(" ").slice(0, 2).map((n) => n[0] ?? "").join("").toUpperCase();
+}
+function createDriverIcon(L, driver) {
+  const color = STATUS_COLORS[driver.status];
+  const label = initials(driver.name);
+  return L.divIcon({
+    className: "",
+    html: `<div style="
+      width:36px;height:36px;border-radius:50%;
+      background:${color};color:#fff;
+      display:flex;align-items:center;justify-content:center;
+      font-size:13px;font-weight:600;font-family:sans-serif;
+      box-shadow:0 2px 4px rgba(0,0,0,.3);
+      cursor:pointer;
+    ">${label}</div>`,
+    iconSize: [36, 36],
+    iconAnchor: [18, 18]
+  });
+}
+export function useDriverMarkers(mapId) {
+  const drivers = ref(/* @__PURE__ */ new Map());
+  const markerInstances = /* @__PURE__ */ new Map();
+  const addDriver = (driver) => {
+    const L = getLeaflet();
+    const map = getMap(mapId);
+    if (!L || !map) return;
+    const icon = createDriverIcon(L, driver);
+    const marker = L.marker([driver.lat, driver.lng], { icon }).addTo(map);
+    const el = marker.getElement();
+    if (el) el.style.transition = "transform 500ms ease-out";
+    marker.on("click", () => {
+      const current = drivers.value.get(driver.driverId);
+      if (current) emitDriverClick(mapId, current);
+    });
+    marker.on("mouseover", () => {
+      const current = drivers.value.get(driver.driverId);
+      if (current) emitDriverHover(mapId, current);
+    });
+    marker.on("mouseout", () => emitDriverHover(mapId, null));
+    markerInstances.set(driver.driverId, marker);
+    drivers.value.set(driver.driverId, driver);
+  };
+  const updateDriver = (driverId, position) => {
+    const marker = markerInstances.get(driverId);
+    if (!marker) return;
+    marker.setLatLng(position);
+    const existing = drivers.value.get(driverId);
+    if (existing) {
+      drivers.value.set(driverId, { ...existing, lat: position[0], lng: position[1] });
+    }
+  };
+  const removeDriver = (driverId) => {
+    markerInstances.get(driverId)?.remove();
+    markerInstances.delete(driverId);
+    drivers.value.delete(driverId);
+  };
+  const clearDrivers = () => {
+    markerInstances.forEach((m) => m.remove());
+    markerInstances.clear();
+    drivers.value.clear();
+  };
+  return { addDriver, updateDriver, removeDriver, clearDrivers, drivers };
+}

package/dist/runtime/composables/useFleetMap.d.ts

@@ -0,0 +1,7 @@
+import type L from 'leaflet';
+export declare function useFleetMap(mapId: string): {
+    map: import("vue").ComputedRef<L.Map | null>;
+    setCenter: (lat: number, lng: number, zoom?: number) => void;
+    fitBounds: (bounds: L.LatLngBounds) => void;
+    isReady: import("vue").ComputedRef<boolean>;
+};

package/dist/runtime/composables/useFleetMap.js

@@ -0,0 +1,16 @@
+import { computed } from "vue";
+import { getMap } from "../utils/registry.js";
+export function useFleetMap(mapId) {
+  const map = computed(() => getMap(mapId));
+  const isReady = computed(() => getMap(mapId) !== null);
+  const setCenter = (lat, lng, zoom) => {
+    const m = getMap(mapId);
+    if (!m) return;
+    if (zoom !== void 0) m.setView([lat, lng], zoom);
+    else m.panTo([lat, lng]);
+  };
+  const fitBounds = (bounds) => {
+    getMap(mapId)?.fitBounds(bounds);
+  };
+  return { map, setCenter, fitBounds, isReady };
+}