@trackany-device/components 1.0.0

package/src/lib/datetime.ts

@@ -0,0 +1,188 @@
+import { usePlatformPageProps } from '../platform/context';
+/**
+ * Datetime utilities for rendering server-UTC timestamps in the user's local
+ * timezone. The server emits ISO-8601 with a 'Z' suffix (see Carbon serialiser
+ * configured in AppServiceProvider). All helpers in this module accept either
+ * an ISO string or a Date / null and return display strings.
+ *
+ * Display timezone resolution order:
+ *   1. explicit `timezone` argument
+ *   2. usePage().props.user_timezone (Inertia shared prop) — resolved via useUserTimezone()
+ *   3. Intl.DateTimeFormat().resolvedOptions().timeZone (browser default)
+ *   4. 'UTC' as final fallback
+ *
+ * NOTE: useUserTimezone() and reportBrowserTimezone() import from @inertiajs/react
+ * which must be available in the consuming app.
+ */
+
+
+type IsoOrDate = string | Date | null | undefined;
+
+const isoCache = new Map<string, Date>();
+
+function toDate(value: IsoOrDate): Date | null {
+    if (value === null || value === undefined) {
+        return null;
+    }
+
+    if (value instanceof Date) {
+        return isNaN(value.getTime()) ? null : value;
+    }
+
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const cached = isoCache.get(value);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const d = new Date(value);
+
+    if (isNaN(d.getTime())) {
+        return null;
+    }
+
+    isoCache.set(value, d);
+
+    return d;
+}
+
+export function browserTimezone(): string {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    } catch {
+        return 'UTC';
+    }
+}
+
+let _sharedTimezone: string | null = null;
+
+export function setSharedTimezone(tz: string | null): void {
+    _sharedTimezone = tz;
+}
+
+export function resolveTimezone(explicit?: string | null): string {
+    if (explicit) {
+        return explicit;
+    }
+
+    if (_sharedTimezone) {
+        return _sharedTimezone;
+    }
+
+    return browserTimezone();
+}
+
+const DEFAULT_OPTIONS: Intl.DateTimeFormatOptions = {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+};
+
+export function formatLocalDateTime(
+    value: IsoOrDate,
+    options: Intl.DateTimeFormatOptions = DEFAULT_OPTIONS,
+    timezone?: string,
+): string {
+    const d = toDate(value);
+
+    if (d === null) {
+        return '';
+    }
+
+    return new Intl.DateTimeFormat(undefined, {
+        ...options,
+        timeZone: resolveTimezone(timezone),
+    }).format(d);
+}
+
+export function formatLocalDate(value: IsoOrDate, timezone?: string): string {
+    return formatLocalDateTime(
+        value,
+        { year: 'numeric', month: 'short', day: 'numeric' },
+        timezone,
+    );
+}
+
+export function formatLocalTime(value: IsoOrDate, timezone?: string): string {
+    return formatLocalDateTime(
+        value,
+        {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12: false,
+        },
+        timezone,
+    );
+}
+
+export function formatRelative(value: IsoOrDate): string {
+    const d = toDate(value);
+
+    if (d === null) {
+        return '';
+    }
+
+    const diffMs = Date.now() - d.getTime();
+    const sec = Math.round(diffMs / 1000);
+
+    if (Math.abs(sec) < 45) {
+        return 'just now';
+    }
+
+    const min = Math.round(sec / 60);
+
+    if (Math.abs(min) < 60) {
+        return `${min}m ago`;
+    }
+
+    const hr = Math.round(min / 60);
+
+    if (Math.abs(hr) < 24) {
+        return `${hr}h ago`;
+    }
+
+    const days = Math.round(hr / 24);
+
+    if (Math.abs(days) < 30) {
+        return `${days}d ago`;
+    }
+
+    return formatLocalDate(d);
+}
+
+/**
+ * Returns the user's timezone resolved from Inertia shared props.
+ * Use inside React components; outside components prefer resolveTimezone().
+ */
+export function useUserTimezone(): string {
+    const { user_timezone } = usePlatformPageProps<{ user_timezone?: string | null }>();
+    return resolveTimezone(user_timezone);
+}
+
+/**
+ * Send the browser's resolved timezone to the server so unauthenticated
+ * users (and the X-Browser-Timezone fallback in HandleInertiaRequests) get
+ * a sensible default. Idempotent — safe to call on every page load.
+ */
+interface TimezoneRouter { on: (e: string, cb: (event: unknown) => void) => () => void; }
+
+export function reportBrowserTimezone(router?: TimezoneRouter): void {
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    const tz = browserTimezone();
+    if (!router) return;
+    router.on('before', (event: unknown) => {
+        const xhr = (event as { detail: { visit?: { headers?: Record<string, string> } } }).detail.visit?.headers ?? {};
+        (xhr as Record<string, string>)['X-Browser-Timezone'] = tz;
+    });
+}

package/src/lib/google-maps-loader.ts

@@ -0,0 +1,99 @@
+import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
+
+/**
+ * Shared Google Maps JS API loader. All map-rendering surfaces
+ * (`/map`, `/playback`, `/incidents/{id}`, `/beats/create+edit`,
+ * `LocationPlayback`, hero `kind:map` section bg) call `loadGoogleMaps()`
+ * which returns the same memoised `Promise<typeof google.maps>`.
+ *
+ * Uses the v2 functional API (`setOptions` + `importLibrary`) — the
+ * legacy `Loader` class is deprecated. setOptions is idempotent and
+ * importLibrary triggers the actual script injection on first call.
+ *
+ * SECURITY: the API key ships in the JS bundle. Restrict it in the
+ * Google Cloud Console by HTTP referrer to the platform's central +
+ * tenant subdomains so a leaked key can't be abused.
+ *
+ * COST: every page-view that mounts a map fires one Google Maps map
+ * load (billable at ~$7 per 1,000 loads under the Dynamic Maps SKU).
+ * Pages that mount a map should gate on `hasGoogleMapsKey()` so dev /
+ * test / CI environments without a key render an empty placeholder
+ * instead of triggering loader errors.
+ *
+ * NOTE: Reads from import.meta.env.VITE_GOOGLE_MAPS_API_KEY and
+ * import.meta.env.VITE_GOOGLE_MAPS_LIBRARIES — configure these env
+ * vars in the consuming app's Vite config.
+ */
+
+// import.meta.env is only available in Vite bundles (not Next.js/webpack).
+// Read lazily so module evaluation doesn't throw in non-Vite environments.
+function getEnv(key: string): string {
+    try {
+        return (import.meta as unknown as { env?: Record<string, string> }).env?.[key] ?? '';
+    } catch {
+        return '';
+    }
+}
+
+const KEY: string = getEnv('VITE_GOOGLE_MAPS_API_KEY');
+const EXTRA_LIBS: string = getEnv('VITE_GOOGLE_MAPS_LIBRARIES');
+
+// Libraries we always load:
+//   - places   → Autocomplete for beat editor address search
+//   - drawing  → DrawingManager + editable Polygon for beat polygon edits
+const BASE_LIBRARIES = ['places', 'drawing'];
+
+let initialised = false;
+let loaderPromise: Promise<typeof google.maps> | null = null;
+
+/**
+ * Returns true when a Google Maps API key is configured. Pages should
+ * gate map rendering on this to avoid loader errors in test / CI / dev
+ * environments without a key.
+ */
+export function hasGoogleMapsKey(): boolean {
+    return KEY.length > 0;
+}
+
+/**
+ * Lazy-load the Google Maps JS API. Memoised — every caller after the
+ * first await gets the cached resolution.
+ *
+ * Throws if no key is configured; callers should check `hasGoogleMapsKey()`
+ * first and render a fallback when it's false.
+ */
+export function loadGoogleMaps(): Promise<typeof google.maps> {
+    if (!KEY) {
+        return Promise.reject(
+            new Error(
+                'VITE_GOOGLE_MAPS_API_KEY is not set. Maps will not load.',
+            ),
+        );
+    }
+
+    if (loaderPromise) {
+        return loaderPromise;
+    }
+
+    if (!initialised) {
+        const extra = EXTRA_LIBS.split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const libraries = Array.from(new Set([...BASE_LIBRARIES, ...extra]));
+
+        setOptions({
+            key: KEY,
+            v: 'weekly',
+            libraries,
+        });
+        initialised = true;
+    }
+
+    // importLibrary('maps') triggers the script injection on first call.
+    // We don't need the returned namespace itself — once 'maps' has loaded,
+    // every google.maps.* member is on the global `google` object, so we
+    // return that for callers to destructure as they wish.
+    loaderPromise = importLibrary('maps').then(() => google.maps);
+
+    return loaderPromise;
+}

package/src/lib/location.ts

@@ -0,0 +1,127 @@
+'use client';
+
+/**
+ * Browser geolocation consent helper.
+ *
+ * Returns a hook that requests the user's coordinates on demand. Coords are
+ * cached in component state and forwarded as `X-Browser-Latitude` /
+ * `X-Browser-Longitude` headers on every Inertia visit. The hook is a soft
+ * prompt — login/register still work when the user denies permission, but
+ * the form payload omits the coords and the server stores null.
+ *
+ * attachLocationToInertiaVisits(router) accepts Inertia's router from the
+ * consuming app and is a no-op when omitted (Storybook / Next.js).
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+
+interface LocationRouter {
+    on: (event: string, callback: (e: unknown) => void) => () => void;
+}
+
+export type Coords = {
+    latitude: number;
+    longitude: number;
+};
+
+export type ConsentStatus =
+    | 'idle'
+    | 'prompting'
+    | 'granted'
+    | 'denied'
+    | 'unavailable';
+
+let _cached: Coords | null = null;
+
+export function cachedCoords(): Coords | null {
+    return _cached;
+}
+
+export function setCachedCoords(coords: Coords | null): void {
+    _cached = coords;
+}
+
+export function useLocationConsent(): {
+    coords: Coords | null;
+    status: ConsentStatus;
+    request: () => Promise<Coords | null>;
+} {
+    const [coords, setCoords] = useState<Coords | null>(_cached);
+    const [status, setStatus] = useState<ConsentStatus>(
+        _cached ? 'granted' : 'idle',
+    );
+
+    const request = useCallback((): Promise<Coords | null> => {
+        if (typeof window === 'undefined' || !navigator.geolocation) {
+            setStatus('unavailable');
+
+            return Promise.resolve(null);
+        }
+
+        setStatus('prompting');
+
+        return new Promise<Coords | null>((resolve) => {
+            navigator.geolocation.getCurrentPosition(
+                (position) => {
+                    const next: Coords = {
+                        latitude: position.coords.latitude,
+                        longitude: position.coords.longitude,
+                    };
+                    _cached = next;
+                    setCoords(next);
+                    setStatus('granted');
+                    resolve(next);
+                },
+                () => {
+                    setStatus('denied');
+                    resolve(null);
+                },
+                {
+                    enableHighAccuracy: false,
+                    maximumAge: 60_000,
+                    timeout: 8_000,
+                },
+            );
+        });
+    }, []);
+
+    return { coords, status, request };
+}
+
+/**
+ * Wire cached coordinates onto every outgoing Inertia visit as request
+ * headers. Idempotent — safe to call once at app bootstrap.
+ */
+export function attachLocationToInertiaVisits(router?: LocationRouter): void {
+    if (typeof window === 'undefined' || !router) {
+        return;
+    }
+
+    router.on('before', (event: unknown) => {
+        if (!_cached) {
+            return;
+        }
+
+        const headers = (event as { detail: { visit?: { headers?: Record<string, string> } } }).detail.visit?.headers ?? {};
+        (headers as Record<string, string>)['X-Browser-Latitude'] = String(
+            _cached.latitude,
+        );
+        (headers as Record<string, string>)['X-Browser-Longitude'] = String(
+            _cached.longitude,
+        );
+    });
+}
+
+/** Convenience: re-request location on mount, swallowing failures. */
+export function useEagerLocationConsent(): ConsentStatus {
+    const { status, request } = useLocationConsent();
+
+    useEffect(() => {
+        if (status === 'idle') {
+            void request();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    return status;
+}

package/src/lib/lucide-icon-map.ts

@@ -0,0 +1,132 @@
+import {
+    Activity,
+    AlertTriangle,
+    ArrowDown,
+    ArrowLeft,
+    ArrowRight,
+    ArrowUp,
+    Battery,
+    Bell,
+    BookOpen,
+    Building2,
+    Calendar,
+    Check,
+    CheckCircle,
+    ChevronDown,
+    ChevronRight,
+    Cloud,
+    Code,
+    Cpu,
+    Database,
+    Download,
+    Droplets,
+    ExternalLink,
+    Factory,
+    Globe,
+    GraduationCap,
+    HardHat,
+    Headphones,
+    Heart,
+    Image as ImageIcon,
+    Landmark,
+    Leaf,
+    Mail,
+    MapPin,
+    Newspaper,
+    Package,
+    Phone,
+    Plane,
+    Play,
+    Radio,
+    RefreshCw,
+    Rocket,
+    Search,
+    Shield,
+    Ship,
+    ShoppingBag,
+    ShoppingCart,
+    Sparkles,
+    Star,
+    Stethoscope,
+    Thermometer,
+    Tractor,
+    Truck,
+    Users,
+    Wheat,
+    Zap,
+} from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+
+/**
+ * String → LucideIcon lookup for CMS content (icons stored as PascalCase
+ * lucide-react export names in section JSON). Keep this list aligned with
+ * the icon options in Filament resource Selects (icon_name fields).
+ *
+ * To add a new icon: import it above, add it to the map below, and add
+ * it to the matching Filament Select options array.
+ */
+export const LUCIDE_ICON_MAP: Record<string, LucideIcon> = {
+    Activity,
+    AlertTriangle,
+    ArrowDown,
+    ArrowLeft,
+    ArrowRight,
+    ArrowUp,
+    Battery,
+    Bell,
+    BookOpen,
+    Building2,
+    Calendar,
+    Check,
+    CheckCircle,
+    ChevronDown,
+    ChevronRight,
+    Cloud,
+    Code,
+    Cpu,
+    Database,
+    Download,
+    Droplets,
+    ExternalLink,
+    Factory,
+    Globe,
+    GraduationCap,
+    HardHat,
+    Headphones,
+    Heart,
+    Image: ImageIcon,
+    Landmark,
+    Leaf,
+    Mail,
+    MapPin,
+    Newspaper,
+    Package,
+    Phone,
+    Plane,
+    Play,
+    Radio,
+    RefreshCw,
+    Rocket,
+    Search,
+    Shield,
+    Ship,
+    ShoppingBag,
+    ShoppingCart,
+    Sparkles,
+    Star,
+    Stethoscope,
+    Thermometer,
+    Tractor,
+    Truck,
+    Users,
+    Wheat,
+    Zap,
+};
+
+export function lucideIcon(name?: string | null): LucideIcon | null {
+    if (!name) {
+        return null;
+    }
+
+    return LUCIDE_ICON_MAP[name] ?? null;
+}

package/src/lib/map-markers.ts

@@ -0,0 +1,124 @@
+import arrowBlue   from '../assets/map/arrows/map-arrow-blue.png';
+import arrowGreen  from '../assets/map/arrows/map-arrow-green.png';
+import arrowPurple from '../assets/map/arrows/map-arrow-purple.png';
+import arrowRed    from '../assets/map/arrows/map-arrow-red.png';
+
+import flagBlue   from '../assets/map/flags/flag-blue.png';
+import flagGreen  from '../assets/map/flags/flag-green.png';
+import flagRed    from '../assets/map/flags/flag-red.png';
+import flagYellow from '../assets/map/flags/flag-yellow.png';
+
+// ─── Network quality ──────────────────────────────────────────────────────────
+
+/**
+ * Four-tier signal classification.
+ * Input is a 0–100 percentage (normalise before calling if the device
+ * sends a raw dBm or 0–4 bar value).
+ *
+ * | Tier       | Range  | Colour  |
+ * |------------|--------|---------|
+ * | none/low   | 0–25   | red     |
+ * | above-low  | 26–50  | purple  |
+ * | average    | 51–75  | blue    |
+ * | good       | 76–100 | green   |
+ */
+export type NetworkTier = 'none' | 'low' | 'above-low' | 'average' | 'good';
+export type MarkerColor = 'red' | 'purple' | 'blue' | 'green';
+
+export function networkTier(signal: number | null | undefined): NetworkTier {
+    if (signal == null || signal <= 0) return 'none';
+    if (signal <= 25) return 'low';
+    if (signal <= 50) return 'above-low';
+    if (signal <= 75) return 'average';
+    return 'good';
+}
+
+/** Maps any signal strength (0–100) to its marker colour. */
+export function markerColor(signal: number | null | undefined): MarkerColor {
+    const tier = networkTier(signal);
+    if (tier === 'none' || tier === 'low') return 'red';
+    if (tier === 'above-low') return 'purple';
+    if (tier === 'average') return 'blue';
+    return 'green';
+}
+
+// ─── Arrow markers (device has a known heading) ───────────────────────────────
+
+/** Arrow images keyed by colour. All images point north (up = 0°). */
+export const ARROW_URLS: Record<MarkerColor, string> = {
+    red:    arrowRed,
+    purple: arrowPurple,
+    blue:   arrowBlue,
+    green:  arrowGreen,
+};
+
+/**
+ * CSS `transform` string for a north-pointing arrow image.
+ * Returns an empty string when heading is unknown (renders the image unrotated,
+ * but in practice callers should show a pin instead — see `useArrow`).
+ *
+ * @param heading - Degrees clockwise from north (0–360).
+ */
+export function arrowRotation(heading: number | null | undefined): string {
+    if (heading == null) return '';
+    return `rotate(${(heading % 360 + 360) % 360}deg)`;
+}
+
+/**
+ * Whether to show an arrow (has heading) or a static pin (no heading).
+ * Call this before deciding which marker type to render.
+ */
+export function useArrow(heading: number | null | undefined): boolean {
+    return heading != null;
+}
+
+/**
+ * Returns the arrow image URL for a device, given its network signal.
+ * Only call this when `useArrow(device.heading)` is true.
+ */
+export function deviceArrowUrl(signal: number | null | undefined): string {
+    return ARROW_URLS[markerColor(signal)];
+}
+
+// ─── Pin colours (device has no heading) ─────────────────────────────────────
+
+/**
+ * Hex fill colours for the static pin marker (rendered as a DOM element,
+ * no separate image needed).
+ */
+export const PIN_COLORS: Record<MarkerColor, string> = {
+    red:    '#ef4444',
+    purple: '#a855f7',
+    blue:   '#3b82f6',
+    green:  '#22c55e',
+};
+
+/** Returns the hex pin colour for a device, given its network signal. */
+export function devicePinColor(signal: number | null | undefined): string {
+    return PIN_COLORS[markerColor(signal)];
+}
+
+// ─── Incident flags ───────────────────────────────────────────────────────────
+
+/**
+ * Incident flags mark the location where an incident was last opened.
+ * Colour reflects the incident's priority/severity.
+ */
+export type IncidentSeverity = 'critical' | 'high' | 'medium' | 'low';
+
+export const FLAG_URLS: Record<IncidentSeverity, string> = {
+    critical: flagRed,
+    high:     flagYellow,
+    medium:   flagBlue,
+    low:      flagGreen,
+};
+
+/** Returns the flag image URL for an incident. */
+export function incidentFlagUrl(severity: IncidentSeverity): string {
+    return FLAG_URLS[severity];
+}
+
+// ─── Named re-exports ─────────────────────────────────────────────────────────
+
+export const arrows = { red: arrowRed, purple: arrowPurple, blue: arrowBlue, green: arrowGreen };
+export const flags  = { red: flagRed, yellow: flagYellow, blue: flagBlue, green: flagGreen };