@burdenoff/microfe-movethewheels 2026.1101.1 → 2026.1101.2

package/src/movethewheels/utils/driverNavigation.ts

@@ -0,0 +1,103 @@
+/**
+ * Turn-by-turn navigation hand-off for the driver day view (BOFF-3991).
+ *
+ * The driver app does not embed its own routing engine: it hands the stop
+ * (or the remaining stops, in sequence) to the device's maps app through the
+ * universal Google Maps URL scheme, which opens the native Google Maps / Apple
+ * Maps-compatible handler on Android and iOS and a browser tab on desktop.
+ */
+import type { Address } from '../types';
+import { formatAddress } from './formatters';
+
+const MAPS_DIRECTIONS_BASE = 'https://www.google.com/maps/dir/?api=1';
+
+/**
+ * Google's universal URL accepts at most 9 intermediate waypoints (plus the
+ * destination). Longer days are handed off in chunks: the driver restarts
+ * navigation from the next remaining stop once these are done.
+ */
+export const MAX_NAVIGATION_WAYPOINTS = 9;
+
+/** The best destination string for an address: coordinates when present, else the formatted address. */
+export function navigationDestination(address: Partial<Address> | null | undefined): string | null {
+  if (!address) return null;
+  if (
+    typeof address.latitude === 'number' &&
+    typeof address.longitude === 'number' &&
+    Number.isFinite(address.latitude) &&
+    Number.isFinite(address.longitude)
+  ) {
+    return `${address.latitude},${address.longitude}`;
+  }
+  const formatted = formatAddress(address).trim();
+  return formatted.length > 0 ? formatted : null;
+}
+
+/** Directions from the device's current position to one stop. */
+export function stopNavigationUrl(address: Partial<Address> | null | undefined): string | null {
+  const destination = navigationDestination(address);
+  if (!destination) return null;
+  const params = new URLSearchParams({ destination, travelmode: 'driving' });
+  return `${MAPS_DIRECTIONS_BASE}&${params.toString()}`;
+}
+
+/**
+ * Directions through the remaining stops in sequence: the last stop in the
+ * chunk is the destination, the ones before it are waypoints. Stops without a
+ * usable address are skipped. Returns null when no stop is navigable.
+ */
+export function routeNavigationUrl(
+  addresses: Array<Partial<Address> | null | undefined>
+): string | null {
+  const destinations = addresses
+    .map((address) => navigationDestination(address))
+    .filter((value): value is string => value !== null)
+    .slice(0, MAX_NAVIGATION_WAYPOINTS + 1);
+  if (destinations.length === 0) return null;
+  const destination = destinations[destinations.length - 1];
+  const waypoints = destinations.slice(0, -1);
+  const params = new URLSearchParams({ destination, travelmode: 'driving' });
+  if (waypoints.length > 0) params.set('waypoints', waypoints.join('|'));
+  return `${MAPS_DIRECTIONS_BASE}&${params.toString()}`;
+}
+
+/** A `tel:` link for a phone number, keeping only dialable characters. */
+export function phoneHref(phone: string | null | undefined): string | null {
+  if (!phone) return null;
+  const dialable = phone.replace(/[^\d+]/g, '');
+  return dialable.length >= 3 ? `tel:${dialable}` : null;
+}
+
+/** The device-local calendar date as YYYY-MM-DD (what `myDeliveryDay` expects). */
+export function localDateString(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/** Shift a YYYY-MM-DD date by whole days, staying in local calendar terms. */
+export function shiftLocalDate(date: string, days: number): string {
+  const [year, month, day] = date.split('-').map(Number);
+  return localDateString(new Date(year, month - 1, day + days));
+}
+
+/** The `Date#getTimezoneOffset()` value for local midnight of a YYYY-MM-DD date (DST-correct). */
+export function timezoneOffsetFor(date: string): number {
+  const [year, month, day] = date.split('-').map(Number);
+  return new Date(year, month - 1, day).getTimezoneOffset();
+}
+
+/**
+ * The device's IANA time zone (e.g. `Asia/Kolkata`), so the server can build
+ * the day window from real local midnights, including on DST transition
+ * days. Null when the runtime cannot report one; the fixed offset is then used.
+ */
+export function deviceTimeZone(): string | null {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof zone === 'string' && zone.length > 0 ? zone : null;
+  } catch {
+    return null;
+  }
+}