@trackany-device/components 1.0.0

package/src/lib/map-styles.ts

@@ -0,0 +1,351 @@
+/**
+ * Custom Google Maps styles.
+ *
+ * Themes mirror Google's "style selector" reference set
+ * (https://developers.google.com/maps/documentation/javascript/examples/style-selector):
+ *
+ *  - default  → Google's stock styling (no overrides)
+ *  - silver   → desaturated greys, our standard light theme
+ *  - night    → dark navy with warm-brown accents, our standard dark theme
+ *  - retro    → cream / beige / orange roads with green parks
+ *  - hiding   → tiny overlay that hides business POIs + transit icons
+ *
+ * `hiding` is intended to be merged on top of one of the other themes
+ * rather than used by itself.
+ *
+ * We use inline style arrays so the theme can flip instantly at runtime
+ * (e.g. when the user toggles light/dark) without round-tripping the
+ * Google Cloud Console for a cloud-styled map ID.
+ */
+
+type Style = google.maps.MapTypeStyle;
+
+export type MapStyleName = 'default' | 'silver' | 'night' | 'retro' | 'hiding';
+
+export const MAP_STYLES: Record<MapStyleName, Style[]> = {
+    default: [],
+
+    silver: [
+        { elementType: 'geometry', stylers: [{ color: '#f5f5f5' }] },
+        { elementType: 'labels.icon', stylers: [{ visibility: 'off' }] },
+        { elementType: 'labels.text.fill', stylers: [{ color: '#616161' }] },
+        { elementType: 'labels.text.stroke', stylers: [{ color: '#f5f5f5' }] },
+        {
+            featureType: 'administrative.land_parcel',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#bdbdbd' }],
+        },
+        {
+            featureType: 'poi',
+            elementType: 'geometry',
+            stylers: [{ color: '#eeeeee' }],
+        },
+        {
+            featureType: 'poi',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#757575' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'geometry',
+            stylers: [{ color: '#e5e5e5' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#9e9e9e' }],
+        },
+        {
+            featureType: 'road',
+            elementType: 'geometry',
+            stylers: [{ color: '#ffffff' }],
+        },
+        {
+            featureType: 'road.arterial',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#757575' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'geometry',
+            stylers: [{ color: '#dadada' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#616161' }],
+        },
+        {
+            featureType: 'road.local',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#9e9e9e' }],
+        },
+        {
+            featureType: 'transit.line',
+            elementType: 'geometry',
+            stylers: [{ color: '#e5e5e5' }],
+        },
+        {
+            featureType: 'transit.station',
+            elementType: 'geometry',
+            stylers: [{ color: '#eeeeee' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'geometry',
+            stylers: [{ color: '#c9c9c9' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#9e9e9e' }],
+        },
+    ],
+
+    night: [
+        { elementType: 'geometry', stylers: [{ color: '#242f3e' }] },
+        { elementType: 'labels.text.stroke', stylers: [{ color: '#242f3e' }] },
+        { elementType: 'labels.text.fill', stylers: [{ color: '#746855' }] },
+        {
+            featureType: 'administrative.locality',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#d59563' }],
+        },
+        {
+            featureType: 'poi',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#d59563' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'geometry',
+            stylers: [{ color: '#263c3f' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#6b9a76' }],
+        },
+        {
+            featureType: 'road',
+            elementType: 'geometry',
+            stylers: [{ color: '#38414e' }],
+        },
+        {
+            featureType: 'road',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#212a37' }],
+        },
+        {
+            featureType: 'road',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#9ca5b3' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'geometry',
+            stylers: [{ color: '#746855' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#1f2835' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#f3d19c' }],
+        },
+        {
+            featureType: 'transit',
+            elementType: 'geometry',
+            stylers: [{ color: '#2f3948' }],
+        },
+        {
+            featureType: 'transit.station',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#d59563' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'geometry',
+            stylers: [{ color: '#17263c' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#515c6d' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'labels.text.stroke',
+            stylers: [{ color: '#17263c' }],
+        },
+    ],
+
+    retro: [
+        { elementType: 'geometry', stylers: [{ color: '#ebe3cd' }] },
+        { elementType: 'labels.text.fill', stylers: [{ color: '#523735' }] },
+        { elementType: 'labels.text.stroke', stylers: [{ color: '#f5f1e6' }] },
+        {
+            featureType: 'administrative',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#c9b2a6' }],
+        },
+        {
+            featureType: 'administrative.land_parcel',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#dcd2be' }],
+        },
+        {
+            featureType: 'administrative.land_parcel',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#ae9e90' }],
+        },
+        {
+            featureType: 'landscape.natural',
+            elementType: 'geometry',
+            stylers: [{ color: '#dfd2ae' }],
+        },
+        {
+            featureType: 'poi',
+            elementType: 'geometry',
+            stylers: [{ color: '#dfd2ae' }],
+        },
+        {
+            featureType: 'poi',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#93817c' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'geometry.fill',
+            stylers: [{ color: '#a5b076' }],
+        },
+        {
+            featureType: 'poi.park',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#447530' }],
+        },
+        {
+            featureType: 'road',
+            elementType: 'geometry',
+            stylers: [{ color: '#f5f1e6' }],
+        },
+        {
+            featureType: 'road.arterial',
+            elementType: 'geometry',
+            stylers: [{ color: '#fdfcf8' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'geometry',
+            stylers: [{ color: '#f8c967' }],
+        },
+        {
+            featureType: 'road.highway',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#e9bc62' }],
+        },
+        {
+            featureType: 'road.highway.controlled_access',
+            elementType: 'geometry',
+            stylers: [{ color: '#e98d58' }],
+        },
+        {
+            featureType: 'road.highway.controlled_access',
+            elementType: 'geometry.stroke',
+            stylers: [{ color: '#db8555' }],
+        },
+        {
+            featureType: 'road.local',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#806b63' }],
+        },
+        {
+            featureType: 'transit.line',
+            elementType: 'geometry',
+            stylers: [{ color: '#dfd2ae' }],
+        },
+        {
+            featureType: 'transit.line',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#8f7d77' }],
+        },
+        {
+            featureType: 'transit.line',
+            elementType: 'labels.text.stroke',
+            stylers: [{ color: '#ebe3cd' }],
+        },
+        {
+            featureType: 'transit.station',
+            elementType: 'geometry',
+            stylers: [{ color: '#dfd2ae' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'geometry.fill',
+            stylers: [{ color: '#b9d3c2' }],
+        },
+        {
+            featureType: 'water',
+            elementType: 'labels.text.fill',
+            stylers: [{ color: '#92998d' }],
+        },
+    ],
+
+    hiding: [
+        {
+            featureType: 'poi.business',
+            stylers: [{ visibility: 'off' }],
+        },
+        {
+            featureType: 'transit',
+            elementType: 'labels.icon',
+            stylers: [{ visibility: 'off' }],
+        },
+    ],
+};
+
+/** Returns the style array for a named theme, or an empty array if unknown. */
+export function mapStyleByName(name: MapStyleName): Style[] {
+    return MAP_STYLES[name] ?? [];
+}
+
+/**
+ * Picks the right style array for the current `<html class="dark">` state.
+ * Dark mode → night, light mode → retro.
+ */
+export function mapStyleForAppearance(isDark: boolean): Style[] {
+    return isDark ? MAP_STYLES.night : MAP_STYLES.retro;
+}
+
+/**
+ * Subscribes to dark-mode changes by watching the `dark` class on the
+ * root `<html>` element. Returns an unsubscribe function. The callback
+ * receives the current `isDark` value.
+ */
+export function watchDarkMode(callback: (isDark: boolean) => void): () => void {
+    if (typeof document === 'undefined') {
+        return () => {};
+    }
+
+    const observer = new MutationObserver(() => {
+        callback(document.documentElement.classList.contains('dark'));
+    });
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['class'],
+    });
+
+    return () => observer.disconnect();
+}
+
+/** Reads the current `dark` class on the root `<html>` element. */
+export function isDarkMode(): boolean {
+    if (typeof document === 'undefined') {
+        return false;
+    }
+
+    return document.documentElement.classList.contains('dark');
+}

package/src/lib/utils.ts

@@ -0,0 +1,11 @@
+import type { PlatformLinkProps } from '../platform/types';
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+}
+
+export function toUrl(url: NonNullable<PlatformLinkProps['href']>): string {
+    return url;
+}

package/src/platform/adapters/default.tsx

@@ -0,0 +1,156 @@
+'use client';
+
+import { useCallback, useRef, useState } from 'react';
+import type {
+    FormSubmitOptions,
+    NavigateOptions,
+    PlatformAdapter,
+    PlatformForm,
+    PlatformLinkProps,
+} from '../types';
+
+// ─── Link ────────────────────────────────────────────────────────────────────
+
+function DefaultLink({ href, children, preserveScroll: _ps, replace: _r, ...props }: PlatformLinkProps) {
+    return <a href={href} {...props}>{children}</a>;
+}
+
+// ─── navigate ────────────────────────────────────────────────────────────────
+
+function defaultNavigate(href: string, options?: NavigateOptions) {
+    if (typeof window === 'undefined') return;
+    if (options?.replace) {
+        window.location.replace(href);
+    } else {
+        window.location.href = href;
+    }
+}
+
+// ─── useCurrentUrl ───────────────────────────────────────────────────────────
+
+function useDefaultCurrentUrl() {
+    if (typeof window === 'undefined') return '';
+    return window.location.pathname + window.location.search;
+}
+
+// ─── usePageProps ─────────────────────────────────────────────────────────────
+
+function useDefaultPageProps<T extends Record<string, unknown>>(): T {
+    return {} as T;
+}
+
+// ─── useForm ─────────────────────────────────────────────────────────────────
+
+function useFetchForm<T extends Record<string, unknown>>(initialData: T): PlatformForm<T> {
+    const [data, setDataState] = useState<T>(initialData);
+    const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
+    const [processing, setProcessing] = useState(false);
+    const [wasSuccessful, setWasSuccessful] = useState(false);
+    const [recentlySuccessful, setRecentlySuccessful] = useState(false);
+    const recentTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    const initialRef = useRef(initialData);
+
+    const setData: PlatformForm<T>['setData'] = useCallback((fieldOrValues: keyof T | Partial<T>, value?: unknown) => {
+        if (typeof fieldOrValues === 'string') {
+            setDataState((prev) => ({ ...prev, [fieldOrValues]: value }));
+        } else {
+            setDataState((prev) => ({ ...prev, ...(fieldOrValues as Partial<T>) }));
+        }
+    }, []);
+
+    const reset = useCallback((...fields: (keyof T)[]) => {
+        if (fields.length === 0) {
+            setDataState(initialRef.current);
+        } else {
+            setDataState((prev) => {
+                const next = { ...prev };
+                fields.forEach((f) => { next[f] = initialRef.current[f]; });
+                return next;
+            });
+        }
+        setErrors({});
+    }, []);
+
+    const clearErrors = useCallback((...fields: (keyof T)[]) => {
+        if (fields.length === 0) {
+            setErrors({});
+        } else {
+            setErrors((prev) => {
+                const next = { ...prev };
+                fields.forEach((f) => { delete next[f]; });
+                return next;
+            });
+        }
+    }, []);
+
+    const setError = useCallback((field: keyof T, message: string) => {
+        setErrors((prev) => ({ ...prev, [field]: message }));
+    }, []);
+
+    async function submit(method: string, url: string, options?: FormSubmitOptions<T>) {
+        setProcessing(true);
+        setWasSuccessful(false);
+        setErrors({});
+        try {
+            const res = await fetch(url, {
+                method: method.toUpperCase(),
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    'X-Requested-With': 'XMLHttpRequest',
+                },
+                body: JSON.stringify(data),
+            });
+
+            const json = await res.json().catch(() => ({}));
+
+            if (!res.ok) {
+                const serverErrors = (json?.errors ?? {}) as Partial<Record<keyof T, string>>;
+                setErrors(serverErrors);
+                options?.onError?.(serverErrors);
+            } else {
+                setWasSuccessful(true);
+                setRecentlySuccessful(true);
+                if (recentTimer.current) clearTimeout(recentTimer.current);
+                recentTimer.current = setTimeout(() => setRecentlySuccessful(false), 2000);
+                options?.onSuccess?.(json);
+            }
+        } catch {
+            const networkError = { _network: 'Network error. Please try again.' } as Partial<Record<keyof T, string>>;
+            setErrors(networkError);
+            options?.onError?.(networkError);
+        } finally {
+            setProcessing(false);
+            options?.onFinish?.();
+        }
+    }
+
+    return {
+        data,
+        setData,
+        errors,
+        processing,
+        wasSuccessful,
+        recentlySuccessful,
+        isDirty: JSON.stringify(data) !== JSON.stringify(initialRef.current),
+        post:   (url, opts) => submit('POST',   url, opts),
+        put:    (url, opts) => submit('PUT',    url, opts),
+        patch:  (url, opts) => submit('PATCH',  url, opts),
+        delete: (url, opts) => submit('DELETE', url, opts),
+        reset,
+        clearErrors,
+        setError,
+    };
+}
+
+// ─── Adapter ─────────────────────────────────────────────────────────────────
+
+export const defaultAdapter: PlatformAdapter = {
+    Link: DefaultLink,
+    navigate: defaultNavigate,
+    useCurrentUrl: useDefaultCurrentUrl,
+    usePageProps: useDefaultPageProps,
+    useForm: useFetchForm,
+    Head: null,
+};

package/src/platform/adapters/inertia.tsx

@@ -0,0 +1,88 @@
+/**
+ * Inertia.js Platform Adapter Factory
+ *
+ * Call this ONCE in the consuming app's entry point (app.tsx / bootstrap.tsx)
+ * and pass the result to <PlatformProvider adapter={...}>.
+ *
+ * The factory accepts Inertia's primitives so packages/node never imports
+ * @inertiajs/react directly — zero coupling.
+ *
+ * Usage (core/ or login/ resources/js/app.tsx):
+ *
+ *   import { Link, usePage, useForm, Head, router } from '@inertiajs/react';
+ *   import { createInertiaAdapter, PlatformProvider } from '@trackany-device/components';
+ *
+ *   const adapter = createInertiaAdapter({ Link, usePage, useForm, Head, router });
+ *
+ *   createInertiaApp({
+ *     resolve: ...,
+ *     setup({ el, App, props }) {
+ *       createRoot(el).render(
+ *         <PlatformProvider adapter={adapter}><App {...props} /></PlatformProvider>
+ *       );
+ *     },
+ *   });
+ */
+
+import type { ComponentType } from 'react';
+import type { PlatformAdapter, PlatformLinkProps, PlatformForm, FormSubmitOptions, NavigateOptions } from '../types';
+
+type InertiaLink = ComponentType<PlatformLinkProps>;
+
+interface InertiaRouter {
+    visit: (url: string, options?: { replace?: boolean; preserveScroll?: boolean; preserveState?: boolean }) => void;
+}
+
+interface InertiaPageObject {
+    props: Record<string, unknown>;
+    url: string;
+}
+
+interface InertiaDeps {
+    /** Inertia's <Link> component */
+    Link: InertiaLink;
+    /** Inertia's usePage hook */
+    usePage: () => InertiaPageObject;
+    /** Inertia's useForm hook */
+    useForm: <T extends Record<string, unknown>>(initialData: T) => PlatformForm<T>;
+    /** Inertia's <Head> component (optional — pass null if not needed) */
+    Head: ComponentType<{ title?: string }> | null;
+    /** Inertia's router instance */
+    router: InertiaRouter;
+}
+
+export function createInertiaAdapter({
+    Link,
+    usePage,
+    useForm,
+    Head,
+    router,
+}: InertiaDeps): PlatformAdapter {
+    return {
+        Link,
+
+        navigate(href: string, options?: NavigateOptions) {
+            router.visit(href, {
+                replace: options?.replace,
+                preserveScroll: options?.preserveScroll,
+                preserveState: options?.preserveState,
+            });
+        },
+
+        useCurrentUrl() {
+            return usePage().url;
+        },
+
+        usePageProps<T extends Record<string, unknown>>(): T {
+            return usePage().props as T;
+        },
+
+        useForm<T extends Record<string, unknown>>(initialData: T): PlatformForm<T> {
+            return useForm<T>(initialData);
+        },
+
+        Head: Head
+            ? (({ title, description: _d }) => <Head title={title} />) as ComponentType<{ title?: string; description?: string }>
+            : null,
+    };
+}

package/src/platform/adapters/nextjs.ts

@@ -0,0 +1,86 @@
+/**
+ * Next.js Platform Adapter Factory
+ *
+ * Call this ONCE in the consuming app's root layout and pass the result
+ * to <PlatformProvider adapter={...}>.
+ *
+ * The factory accepts Next.js primitives so packages/node never imports
+ * next/link or next/navigation directly — zero coupling.
+ *
+ * Usage (web/ app/layout.tsx):
+ *
+ *   'use client';
+ *   import Link from 'next/link';
+ *   import { useRouter, usePathname } from 'next/navigation';
+ *   import { createNextjsAdapter, PlatformProvider } from '@trackany-device/components';
+ *
+ *   export default function ClientProviders({ children, pageProps }) {
+ *     const adapter = createNextjsAdapter({ Link, useRouter, usePathname, pageProps });
+ *     return <PlatformProvider adapter={adapter}>{children}</PlatformProvider>;
+ *   }
+ *
+ * Note: usePageProps() in the Next.js adapter reads from `pageProps` passed
+ * to the factory, NOT from a server context. For shared data (auth, nav_links
+ * etc.) fetch them server-side and pass them in as pageProps.
+ */
+
+import { useRef } from 'react';
+import type { ComponentType } from 'react';
+import type { PlatformAdapter, PlatformLinkProps, PlatformForm, NavigateOptions } from '../types';
+import { defaultAdapter } from './default';
+
+interface NextjsRouter {
+    push:    (href: string) => void;
+    replace: (href: string) => void;
+}
+
+interface NextjsDeps {
+    /** next/link's <Link> component */
+    Link: ComponentType<PlatformLinkProps>;
+    /** next/navigation's useRouter hook */
+    useRouter: () => NextjsRouter;
+    /** next/navigation's usePathname hook */
+    usePathname: () => string;
+    /**
+     * Shared page props (auth, nav_links, etc.) — equivalent to Inertia's
+     * shared props. Pass them from the server component down via props.
+     */
+    pageProps?: Record<string, unknown>;
+}
+
+export function createNextjsAdapter({
+    Link,
+    useRouter,
+    usePathname,
+    pageProps = {},
+}: NextjsDeps): PlatformAdapter {
+    const frozenProps = pageProps;
+
+    return {
+        Link,
+
+        navigate(href: string, options?: NavigateOptions) {
+            const router = useRouter();
+            if (options?.replace) {
+                router.replace(href);
+            } else {
+                router.push(href);
+            }
+        },
+
+        useCurrentUrl() {
+            return usePathname();
+        },
+
+        usePageProps<T extends Record<string, unknown>>(): T {
+            return frozenProps as T;
+        },
+
+        // useForm uses the default fetch-based implementation — same interface as Inertia.
+        useForm: defaultAdapter.useForm,
+
+        // Next.js manages document head via the `metadata` export on server components,
+        // not via a client component. PlatformHead renders nothing here.
+        Head: null,
+    };
+}