@netloc8/react 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @netloc8/react
+
+React bindings for the NetLoc8 geolocation SDK. Provides a context Provider,
+`useGeo()` hook, and `<GeoGate>` component for conditional rendering by
+location.
+
+> **Tip:** If you're using Next.js, install [`@netloc8/nextjs`](../nextjs/)
+> instead — it re-exports everything from this package and adds server-side
+> proxy and data helpers.
+
+## Install
+
+```bash
+bun add @netloc8/react
+```
+
+**Peer dependencies:** `react >= 19`
+
+## Usage
+
+### Provider with publishable key (SPA)
+
+Wrap your app with `<NetLoc8Provider>` and pass a publishable key. The
+provider will call the NetLoc8 API on mount to fetch geo data, then
+reconcile the browser timezone automatically.
+
+```tsx
+import { NetLoc8Provider, useGeo } from '@netloc8/react';
+
+function App() {
+    return (
+        <NetLoc8Provider publishableKey="pk_...">
+            <LocationBanner />
+        </NetLoc8Provider>
+    );
+}
+
+function LocationBanner() {
+    const geo = useGeo();
+    return <p>Timezone: {geo.timezone}</p>;
+}
+```
+
+### Conditional rendering with GeoGate
+
+```tsx
+import { GeoGate } from '@netloc8/react';
+
+<GeoGate eu={true}>
+    <CookieConsentBanner />
+</GeoGate>
+
+<GeoGate country={['US', 'CA']} not fallback={<p>Not available in your region</p>}>
+    <SpecialOffer />
+</GeoGate>
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `NetLoc8Provider` | Context provider — pass `publishableKey` (SPA) or `initialGeo` (SSR) |
+| `useGeo()` | Hook to read the current `Geo` object |
+| `GeoGate` | Conditionally render children based on location |
+| `GeoContext` | Raw React context (for advanced use) |
+
+## License
+
+[Elastic License 2.0 (ELv2)](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,75 @@
+
+import { Context, ReactNode } from "react";
+import { Geo } from "@netloc8/netloc8-js";
+
+//#region src/provider.d.ts
+interface NetLoc8ProviderProps {
+  initialGeo?: Geo;
+  publishableKey?: string;
+  apiUrl?: string;
+  children: ReactNode;
+}
+/**
+* Provider component that makes geolocation data available to all child
+* components via the useGeo() hook.
+*
+* Two usage modes:
+*
+* 1. **Server proxy (Next.js):** Pass `initialGeo` from the server. The
+*    provider only reconciles the browser timezone on mount.
+*
+* 2. **Client-side SPA:** Pass `publishableKey` (a `pk_` key). The provider
+*    fetches geo data from the API on mount via GET /api/v1/ip/me, then
+*    reconciles the browser timezone.
+*/
+declare function NetLoc8Provider({
+  initialGeo,
+  publishableKey,
+  apiUrl,
+  children
+}: NetLoc8ProviderProps): ReactNode;
+//#endregion
+//#region src/hook.d.ts
+/**
+* Hook to access geolocation data in client components.
+* Must be used inside a <NetLoc8Provider>.
+*
+* @throws {Error} if called outside a NetLoc8Provider.
+*/
+declare function useGeo(): Geo;
+//#endregion
+//#region src/gate.d.ts
+interface GeoGateProps {
+  country?: string | string[];
+  region?: string | string[];
+  city?: string | string[];
+  eu?: boolean;
+  not?: boolean;
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+/**
+* Conditionally render children based on the user's geolocation.
+*
+* Multiple values can be passed as an array for OR matching within a field.
+* When multiple fields are specified, ALL must match (AND logic).
+*/
+declare function GeoGate({
+  country,
+  region,
+  city,
+  eu,
+  not,
+  fallback,
+  children
+}: GeoGateProps): ReactNode;
+//#endregion
+//#region src/context.d.ts
+/**
+* Internal sentinel — `null` means no provider is present.
+* The public default is cast to `Geo` so consumers see the correct type.
+*/
+declare const GeoContext: Context<Geo>;
+//#endregion
+export { GeoContext, GeoGate, NetLoc8Provider, useGeo };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provider.tsx","../src/hook.ts","../src/gate.tsx","../src/context.tsx"],"mappings":";;;;;UAWU,oBAAA;EACN,UAAA,GAAa,GAAA;EACb,cAAA;EACA,MAAA;EACA,QAAA,EAAU,SAAA;AAAA;;;;;;;;;AAsCd;;;;;iBAAgB,eAAA,CAAA;EAAkB,UAAA;EAAY,cAAA;EAAgB,MAAA;EAAQ;AAAA,GAAY,oBAAA,GAAuB,SAAA;;;;;;AA9ChF;;;iBCKT,MAAA,CAAA,GAAU,GAAA;;;UCPhB,YAAA;EACN,OAAA;EACA,MAAA;EACA,IAAA;EACA,EAAA;EACA,GAAA;EACA,QAAA,GAAW,SAAA;EACX,QAAA,EAAU,SAAA;AAAA;;;;;;;iBASE,OAAA,CAAA;EACZ,OAAA;EACA,MAAA;EACA,IAAA;EACA,EAAA;EACA,GAAA;EACA,QAAA;EACA;AAAA,GACD,YAAA,GAAe,SAAA;;;;;AFtBO;;cGEZ,UAAA,EAAY,OAAA,CAAQ,GAAA"}

package/dist/index.mjs

@@ -0,0 +1,122 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState } from "react";
+import { COOKIE_NAME, COOKIE_OPTIONS, fetchMyGeo, normalizeApiResponse, serializeCookie } from "@netloc8/netloc8-js";
+//#region src/context.tsx
+/**
+* Internal sentinel — `null` means no provider is present.
+* The public default is cast to `Geo` so consumers see the correct type.
+*/
+const GeoContext = createContext(null);
+//#endregion
+//#region src/provider.tsx
+/**
+* Write the geo cookie using the shared COOKIE_OPTIONS constants.
+*/
+function writeGeoCookie(geo) {
+	const parts = [`${COOKIE_NAME}=${serializeCookie(geo)}`, `path=${COOKIE_OPTIONS.path}`];
+	if (COOKIE_OPTIONS.secure && globalThis.location?.protocol === "https:") parts.push("secure");
+	if (COOKIE_OPTIONS.sameSite) parts.push(`samesite=${COOKIE_OPTIONS.sameSite}`);
+	if (COOKIE_OPTIONS.maxAge !== void 0) parts.push(`max-age=${COOKIE_OPTIONS.maxAge}`);
+	document.cookie = parts.join("; ");
+}
+/**
+* Provider component that makes geolocation data available to all child
+* components via the useGeo() hook.
+*
+* Two usage modes:
+*
+* 1. **Server proxy (Next.js):** Pass `initialGeo` from the server. The
+*    provider only reconciles the browser timezone on mount.
+*
+* 2. **Client-side SPA:** Pass `publishableKey` (a `pk_` key). The provider
+*    fetches geo data from the API on mount via GET /api/v1/ip/me, then
+*    reconciles the browser timezone.
+*/
+function NetLoc8Provider({ initialGeo, publishableKey, apiUrl, children }) {
+	const [geo, setGeo] = useState(initialGeo ?? {});
+	useEffect(() => {
+		let cancelled = false;
+		async function init() {
+			let currentGeo = initialGeo ?? {};
+			if (publishableKey && !initialGeo) {
+				const raw = await fetchMyGeo({
+					apiKey: publishableKey,
+					apiUrl,
+					clientId: `@netloc8/react/0.1.0`
+				});
+				if (cancelled) return;
+				if (raw) {
+					currentGeo = normalizeApiResponse(raw);
+					setGeo(currentGeo);
+					writeGeoCookie(currentGeo);
+				}
+			}
+			const browserTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+			if (browserTz !== currentGeo.timezone || currentGeo.timezoneFromClient !== true) {
+				if (!cancelled) setGeo((prevGeo) => {
+					const updatedGeo = {
+						...prevGeo,
+						timezone: browserTz,
+						timezoneFromClient: true
+					};
+					writeGeoCookie(updatedGeo);
+					return updatedGeo;
+				});
+			}
+		}
+		init();
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	return /* @__PURE__ */ jsx(GeoContext.Provider, {
+		value: geo,
+		children
+	});
+}
+//#endregion
+//#region src/hook.ts
+/**
+* Hook to access geolocation data in client components.
+* Must be used inside a <NetLoc8Provider>.
+*
+* @throws {Error} if called outside a NetLoc8Provider.
+*/
+function useGeo() {
+	const geo = useContext(GeoContext);
+	if (geo === null) throw new Error("useGeo() must be used inside a <NetLoc8Provider>.");
+	return geo;
+}
+//#endregion
+//#region src/gate.tsx
+/**
+* Conditionally render children based on the user's geolocation.
+*
+* Multiple values can be passed as an array for OR matching within a field.
+* When multiple fields are specified, ALL must match (AND logic).
+*/
+function GeoGate({ country, region, city, eu, not = false, fallback = null, children }) {
+	const geo = useGeo();
+	const checks = [];
+	if (eu !== void 0) checks.push(geo.isEU === eu);
+	if (country !== void 0) {
+		const countries = Array.isArray(country) ? country : [country];
+		checks.push(geo.country !== void 0 && countries.includes(geo.country));
+	}
+	if (region !== void 0) {
+		const regions = Array.isArray(region) ? region : [region];
+		checks.push(geo.region !== void 0 && regions.includes(geo.region));
+	}
+	if (city !== void 0) {
+		const cities = Array.isArray(city) ? city : [city];
+		checks.push(geo.city !== void 0 && cities.includes(geo.city));
+	}
+	let matches = checks.length === 0 || checks.every(Boolean);
+	if (not) matches = !matches;
+	return matches ? children : fallback;
+}
+//#endregion
+export { GeoContext, GeoGate, NetLoc8Provider, useGeo };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/context.tsx","../src/provider.tsx","../src/hook.ts","../src/gate.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type Context } from 'react';\nimport type { Geo } from '@netloc8/netloc8-js';\n\n/**\n * Internal sentinel — `null` means no provider is present.\n * The public default is cast to `Geo` so consumers see the correct type.\n */\nexport const GeoContext: Context<Geo> = createContext<Geo>(null as unknown as Geo);\n","declare const __PKG_NAME__: string;\ndeclare const __PKG_VERSION__: string;\n\n'use client';\n\nimport { useState, useEffect } from 'react';\nimport type { ReactNode } from 'react';\nimport type { Geo } from '@netloc8/netloc8-js';\nimport { COOKIE_NAME, COOKIE_OPTIONS, serializeCookie, fetchMyGeo, normalizeApiResponse } from '@netloc8/netloc8-js';\nimport { GeoContext } from './context';\n\ninterface NetLoc8ProviderProps {\n    initialGeo?: Geo;\n    publishableKey?: string;\n    apiUrl?: string;\n    children: ReactNode;\n}\n\n/**\n * Write the geo cookie using the shared COOKIE_OPTIONS constants.\n */\nfunction writeGeoCookie(geo: Geo): void {\n    const value = serializeCookie(geo);\n    const parts = [`${COOKIE_NAME}=${value}`, `path=${COOKIE_OPTIONS.path}`];\n\n    if (COOKIE_OPTIONS.secure && globalThis.location?.protocol === 'https:') {\n        parts.push('secure');\n    }\n\n    if (COOKIE_OPTIONS.sameSite) {\n        parts.push(`samesite=${COOKIE_OPTIONS.sameSite}`);\n    }\n\n    if (COOKIE_OPTIONS.maxAge !== undefined) {\n        parts.push(`max-age=${COOKIE_OPTIONS.maxAge}`);\n    }\n\n    document.cookie = parts.join('; ');\n}\n\n/**\n * Provider component that makes geolocation data available to all child\n * components via the useGeo() hook.\n *\n * Two usage modes:\n *\n * 1. **Server proxy (Next.js):** Pass `initialGeo` from the server. The\n *    provider only reconciles the browser timezone on mount.\n *\n * 2. **Client-side SPA:** Pass `publishableKey` (a `pk_` key). The provider\n *    fetches geo data from the API on mount via GET /api/v1/ip/me, then\n *    reconciles the browser timezone.\n */\nexport function NetLoc8Provider({ initialGeo, publishableKey, apiUrl, children }: NetLoc8ProviderProps): ReactNode {\n    const [geo, setGeo] = useState<Geo>(initialGeo ?? {});\n\n    useEffect(() => {\n        let cancelled = false;\n\n        async function init() {\n            let currentGeo: Geo = initialGeo ?? {};\n\n            // Client-side fetch when publishableKey is provided and no server data\n            if (publishableKey && !initialGeo) {\n                const raw = await fetchMyGeo({ apiKey: publishableKey, apiUrl, clientId: typeof __PKG_NAME__ !== 'undefined' ? `${__PKG_NAME__}/${__PKG_VERSION__}` : undefined });\n\n                if (cancelled) {\n                    return;\n                }\n\n                if (raw) {\n                    currentGeo = normalizeApiResponse(raw);\n                    setGeo(currentGeo);\n                    writeGeoCookie(currentGeo);\n                }\n            }\n\n            // Timezone reconciliation — runs in both modes\n            const browserTz = Intl.DateTimeFormat().resolvedOptions().timeZone;\n\n            if (browserTz !== currentGeo.timezone || currentGeo.timezoneFromClient !== true) {\n                if (!cancelled) {\n                    setGeo((prevGeo: Geo) => {\n                        const updatedGeo: Geo = {\n                            ...prevGeo,\n                            timezone: browserTz,\n                            timezoneFromClient: true,\n                        };\n\n                        writeGeoCookie(updatedGeo);\n                        return updatedGeo;\n                    });\n                }\n            }\n        }\n\n        init();\n\n        return () => {\n            cancelled = true;\n        };\n    }, []); // Only run once on mount\n\n    return (\n        <GeoContext.Provider value={geo}>\n            {children}\n        </GeoContext.Provider>\n    );\n}\n","'use client';\n\nimport { useContext } from 'react';\nimport { GeoContext } from './context';\nimport type { Geo } from '@netloc8/netloc8-js';\n\n/**\n * Hook to access geolocation data in client components.\n * Must be used inside a <NetLoc8Provider>.\n *\n * @throws {Error} if called outside a NetLoc8Provider.\n */\nexport function useGeo(): Geo {\n    const geo = useContext(GeoContext);\n\n    if (geo === null) {\n        throw new Error('useGeo() must be used inside a <NetLoc8Provider>.');\n    }\n\n    return geo;\n}\n","'use client';\n\nimport type { ReactNode } from 'react';\nimport { useGeo } from './hook';\n\ninterface GeoGateProps {\n    country?: string | string[];\n    region?: string | string[];\n    city?: string | string[];\n    eu?: boolean;\n    not?: boolean;\n    fallback?: ReactNode;\n    children: ReactNode;\n}\n\n/**\n * Conditionally render children based on the user's geolocation.\n *\n * Multiple values can be passed as an array for OR matching within a field.\n * When multiple fields are specified, ALL must match (AND logic).\n */\nexport function GeoGate({\n    country,\n    region,\n    city,\n    eu,\n    not = false,\n    fallback = null,\n    children,\n}: GeoGateProps): ReactNode {\n    const geo = useGeo();\n\n    const checks: boolean[] = [];\n\n    if (eu !== undefined) {\n        checks.push(geo.isEU === eu);\n    }\n\n    if (country !== undefined) {\n        const countries = Array.isArray(country) ? country : [country];\n        checks.push(geo.country !== undefined && countries.includes(geo.country));\n    }\n\n    if (region !== undefined) {\n        const regions = Array.isArray(region) ? region : [region];\n        checks.push(geo.region !== undefined && regions.includes(geo.region));\n    }\n\n    if (city !== undefined) {\n        const cities = Array.isArray(city) ? city : [city];\n        checks.push(geo.city !== undefined && cities.includes(geo.city));\n    }\n\n    // If no props specified, matches everything\n    let matches = checks.length === 0 || checks.every(Boolean);\n\n    if (not) {\n        matches = !matches;\n    }\n\n    return matches ? children : fallback;\n}\n"],"mappings":";;;;;;;;;AASA,MAAa,aAA2B,cAAmB,KAAuB;;;;;;ACYlF,SAAS,eAAe,KAAgB;CAEpC,MAAM,QAAQ,CAAC,GAAG,YAAY,GADhB,gBAAgB,IAAI,IACQ,QAAQ,eAAe,OAAO;AAExE,KAAI,eAAe,UAAU,WAAW,UAAU,aAAa,SAC3D,OAAM,KAAK,SAAS;AAGxB,KAAI,eAAe,SACf,OAAM,KAAK,YAAY,eAAe,WAAW;AAGrD,KAAI,eAAe,WAAW,KAAA,EAC1B,OAAM,KAAK,WAAW,eAAe,SAAS;AAGlD,UAAS,SAAS,MAAM,KAAK,KAAK;;;;;;;;;;;;;;;AAgBtC,SAAgB,gBAAgB,EAAE,YAAY,gBAAgB,QAAQ,YAA6C;CAC/G,MAAM,CAAC,KAAK,UAAU,SAAc,cAAc,EAAE,CAAC;AAErD,iBAAgB;EACZ,IAAI,YAAY;EAEhB,eAAe,OAAO;GAClB,IAAI,aAAkB,cAAc,EAAE;AAGtC,OAAI,kBAAkB,CAAC,YAAY;IAC/B,MAAM,MAAM,MAAM,WAAW;KAAE,QAAQ;KAAgB;KAAQ,UAAgD;KAAkD,CAAC;AAElK,QAAI,UACA;AAGJ,QAAI,KAAK;AACL,kBAAa,qBAAqB,IAAI;AACtC,YAAO,WAAW;AAClB,oBAAe,WAAW;;;GAKlC,MAAM,YAAY,KAAK,gBAAgB,CAAC,iBAAiB,CAAC;AAE1D,OAAI,cAAc,WAAW,YAAY,WAAW,uBAAuB;QACnE,CAAC,UACD,SAAQ,YAAiB;KACrB,MAAM,aAAkB;MACpB,GAAG;MACH,UAAU;MACV,oBAAoB;MACvB;AAED,oBAAe,WAAW;AAC1B,YAAO;MACT;;;AAKd,QAAM;AAEN,eAAa;AACT,eAAY;;IAEjB,EAAE,CAAC;AAEN,QACI,oBAAC,WAAW,UAAZ;EAAqB,OAAO;EACvB;EACiB,CAAA;;;;;;;;;;AC9F9B,SAAgB,SAAc;CAC1B,MAAM,MAAM,WAAW,WAAW;AAElC,KAAI,QAAQ,KACR,OAAM,IAAI,MAAM,oDAAoD;AAGxE,QAAO;;;;;;;;;;ACEX,SAAgB,QAAQ,EACpB,SACA,QACA,MACA,IACA,MAAM,OACN,WAAW,MACX,YACwB;CACxB,MAAM,MAAM,QAAQ;CAEpB,MAAM,SAAoB,EAAE;AAE5B,KAAI,OAAO,KAAA,EACP,QAAO,KAAK,IAAI,SAAS,GAAG;AAGhC,KAAI,YAAY,KAAA,GAAW;EACvB,MAAM,YAAY,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;AAC9D,SAAO,KAAK,IAAI,YAAY,KAAA,KAAa,UAAU,SAAS,IAAI,QAAQ,CAAC;;AAG7E,KAAI,WAAW,KAAA,GAAW;EACtB,MAAM,UAAU,MAAM,QAAQ,OAAO,GAAG,SAAS,CAAC,OAAO;AACzD,SAAO,KAAK,IAAI,WAAW,KAAA,KAAa,QAAQ,SAAS,IAAI,OAAO,CAAC;;AAGzE,KAAI,SAAS,KAAA,GAAW;EACpB,MAAM,SAAS,MAAM,QAAQ,KAAK,GAAG,OAAO,CAAC,KAAK;AAClD,SAAO,KAAK,IAAI,SAAS,KAAA,KAAa,OAAO,SAAS,IAAI,KAAK,CAAC;;CAIpE,IAAI,UAAU,OAAO,WAAW,KAAK,OAAO,MAAM,QAAQ;AAE1D,KAAI,IACA,WAAU,CAAC;AAGf,QAAO,UAAU,WAAW"}

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "@netloc8/react",
+    "version": "0.1.0",
+    "type": "module",
+    "license": "Elastic-2.0",
+    "exports": {
+        ".": {
+            "bun": "./src/index.ts",
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.mts"
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "tsdown",
+        "clean": "rm -rf dist",
+        "test": "bun test src/"
+    },
+    "peerDependencies": {
+        "react": ">=19.0.0"
+    },
+    "dependencies": {
+        "@netloc8/netloc8-js": "0.1.0"
+    }
+}