@chaosity/location-client-react 0.1.7 → 0.1.9

package/README.md

@@ -1,6 +1,6 @@
 # @chaosity/location-client-react
 
-React bindings for [@chaosity/location-client](https://www.npmjs.com/package/@chaosity/location-client) - AWS Location Service compatible client.
+React bindings for [@chaosity/location-client](https://www.npmjs.com/package/@chaosity/location-client) with automatic token refresh.
 
 ## Installation
 
@@ -10,34 +10,58 @@ npm install @chaosity/location-client-react @chaosity/location-client
 
 ## Quick Start
 
+### 1. Create a Server Action to fetch config
+
+```typescript
+// app/actions/location.ts
+'use server'
+
+import { getClientConfig } from '@chaosity/location-client/server'
+
+export async function getLocationConfig() {
+  // Auto-reads LOCATION_API_URL, LOCATION_CLIENT_ID, LOCATION_CLIENT_SECRET
+  return await getClientConfig()
+}
+```
+
+### 2. Wrap your app with the provider
+
 ```tsx
-import { LocationClientProvider, useLocationClient } from '@chaosity/location-client-react'
-import { SuggestCommand } from '@chaosity/location-client'
+// app/layout.tsx
+'use client'
+
+import { LocationClientProvider } from '@chaosity/location-client-react'
+import { getLocationConfig } from './actions/location'
 
-// 1. Wrap your app with the provider
-function App() {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <LocationClientProvider getConfig={getLocationConfig}>
-      <MapComponent />
+      {children}
     </LocationClientProvider>
   )
 }
+```
+
+### 3. Use the client in any component
+
+```tsx
+import { useLocationClient } from '@chaosity/location-client-react'
+import { SuggestCommand } from '@chaosity/location-client'
+
+function SearchComponent() {
+  const { client, loading, error } = useLocationClient()
 
-// 2. Use the client in any component
-function MapComponent() {
-  const { client, config, loading, error } = useLocationClient()
-  
   const searchPlaces = async (query: string) => {
     if (!client) return
-    
-    const command = new SuggestCommand({
-      QueryText: query,
-      MaxResults: 5
-    })
-    const response = await client.send(command)
+    const response = await client.send(
+      new SuggestCommand({ QueryText: query, MaxResults: 5 })
+    )
     return response.ResultItems
   }
-  
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error}</div>
+
   return <div>...</div>
 }
 ```
@@ -46,128 +70,96 @@ function MapComponent() {
 
 ### LocationClientProvider
 
-Provides the location client to all child components.
+Provides the location client and automatic token refresh to all child components.
 
 ```tsx
-<LocationClientProvider getConfig={getLocationConfig}>
+<LocationClientProvider
+  getConfig={getLocationConfig}
+  refreshBuffer={60}
+>
   {children}
 </LocationClientProvider>
 ```
 
 **Props:**
-- `getConfig` (function, required) - Async function that returns `{ apiUrl: string, token: string }`
-- `children` (ReactNode, required) - Child components
+- `getConfig` — Async function that returns `{ apiUrl: string, token: string, expiresAt?: number }`. Called on init and whenever the token needs refreshing.
+- `refreshBuffer` (optional, default: `60`) — Seconds before token expiry to proactively refresh. Prevents mid-request expiration.
+- `children` — Child components.
 
 ### useLocationClient
 
 Hook to access the location client in any component.
 
 ```tsx
-const { client, config, loading, error } = useLocationClient()
+const { client, getToken, loading, error } = useLocationClient()
 ```
 
 **Returns:**
-- `client` (GeoPlacesClient | null) - The location client instance
-- `config` (ClientConfig | null) - The client configuration (apiUrl, token)
-- `loading` (boolean) - Whether the client is initializing
-- `error` (string | null) - Error message if initialization failed
-
-**Throws:** Error if used outside `LocationClientProvider`
+- `client` (`GeoPlacesClient | null`) — The location client instance. Automatically refreshes the token before each `send()` call if needed.
+- `getToken` (`() => string | undefined`) — Returns the current token. Useful for direct API calls (e.g., map style fetch).
+- `loading` (`boolean`) — Whether the client is initializing.
+- `error` (`string | null`) — Error message if initialization or token refresh failed.
 
-## Usage with Next.js Server Actions
+**Throws:** Error if used outside `LocationClientProvider`.
 
-```tsx
-// app/actions/location.ts (Server-side)
-'use server'
-
-export async function getLocationConfig() {
-  const response = await fetch('https://api.example.com/auth/token', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      grant_type: 'client_credentials',
-      client_id: process.env.LOCATION_CLIENT_ID!,
-      client_secret: process.env.LOCATION_CLIENT_SECRET!
-    })
-  })
-  
-  const data = await response.json()
-  return {
-    apiUrl: 'https://api.example.com',
-    token: data.access_token
-  }
-}
+## Token Refresh
 
-// app/layout.tsx (Client-side)
-'use client'
+The provider automatically handles token lifecycle:
 
-import { LocationClientProvider } from '@chaosity/location-client-react'
-import { getLocationConfig } from './actions/location'
+1. Fetches an initial token via `getConfig` on mount
+2. Before each `client.send()` call, checks if the token is expired or within the `refreshBuffer` window
+3. If expired, calls `getConfig` again to get a fresh token
+4. Concurrent refresh requests are deduplicated — multiple `send()` calls wait for the same refresh
 
-export default function RootLayout({ children }) {
-  return (
-    <LocationClientProvider getConfig={getLocationConfig}>
-      {children}
-    </LocationClientProvider>
-  )
-}
-```
+No manual token management needed. The `client` always uses a valid token.
 
 ## Complete Example with MapLibre
 
 ```tsx
 'use client'
 
+import { useEffect, useRef } from 'react'
 import { useLocationClient } from '@chaosity/location-client-react'
-import { GeoPlaces } from '@chaosity/location-client'
+import { GeoPlaces, createTransformRequest } from '@chaosity/location-client'
 import maplibregl from 'maplibre-gl'
 import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder'
-import { useEffect, useRef } from 'react'
+
+const API_URL = process.env.NEXT_PUBLIC_LOCATION_API_URL!
 
 export default function MapComponent() {
   const mapContainer = useRef<HTMLDivElement>(null)
   const map = useRef<maplibregl.Map | null>(null)
-  const { config, client, loading, error } = useLocationClient()
+  const { client, getToken, loading, error } = useLocationClient()
 
   useEffect(() => {
-    if (!mapContainer.current || map.current || loading || !config || !client) return
+    if (!mapContainer.current || map.current || loading || !client) return
+
+    const token = getToken()
+    if (!token) return
 
-    // Initialize map
     const mapInstance = new maplibregl.Map({
       container: mapContainer.current,
-      style: `${config.apiUrl}/maps/Standard/descriptor`,
+      style: `${API_URL}/maps/Standard/descriptor`,
       center: [-123.12, 49.28],
       zoom: 10,
-      transformRequest: (url) => {
-        if (url.startsWith(config.apiUrl)) {
-          return {
-            url,
-            headers: { 'Authorization': `Bearer ${config.token}` }
-          }
-        }
-        return { url }
-      }
+      transformRequest: createTransformRequest(API_URL, getToken),
     })
 
-    // Add navigation controls
     mapInstance.addControl(new maplibregl.NavigationControl(), 'top-right')
 
-    // Add geocoder
-    const geoPlaces = new GeoPlaces(config.apiUrl, config.token, mapInstance)
+    // GeoPlaces adapter takes the client instance (not raw apiUrl/token)
+    const geoPlaces = new GeoPlaces(client, mapInstance)
     const geocoder = new MaplibreGeocoder(geoPlaces, {
       maplibregl,
       showResultsWhileTyping: true,
-      limit: 30
+      limit: 30,
     })
     mapInstance.addControl(geocoder, 'top-left')
 
-    // Handle result selection
-    geocoder.on('result', async (event) => {
-      const { id, result_type } = event.result
-      if (result_type === 'Place') {
-        const details = await geoPlaces.searchByPlaceId(id)
-        console.log('Place details:', details)
-      }
+    // The geocoder resolves places internally via searchByPlaceId.
+    // The 'result' event fires with the resolved place feature.
+    geocoder.on('result', (event: any) => {
+      console.log('Selected place:', event.result)
     })
 
     map.current = mapInstance
@@ -178,15 +170,10 @@ export default function MapComponent() {
         map.current = null
       }
     }
-  }, [config, client, loading])
-
-  if (error) {
-    return <div>Error: {error}</div>
-  }
+  }, [client, getToken, loading])
 
-  if (loading) {
-    return <div>Loading map...</div>
-  }
+  if (error) return <div>Error: {error}</div>
+  if (loading) return <div>Loading map...</div>
 
   return <div ref={mapContainer} style={{ width: '100%', height: '600px' }} />
 }
@@ -203,14 +190,14 @@ import {
   ReverseGeocodeCommand,
   GetPlaceCommand,
   SearchTextCommand,
-  SearchNearbyCommand
+  SearchNearbyCommand,
 } from '@chaosity/location-client'
 
 function MyComponent() {
   const { client } = useLocationClient()
 
-  const searchPlaces = async () => {
-    const response = await client.send(
+  const search = async () => {
+    const response = await client!.send(
       new SuggestCommand({ QueryText: 'Vancouver', MaxResults: 5 })
     )
     return response.ResultItems
@@ -218,6 +205,14 @@ function MyComponent() {
 }
 ```
 
+## Logging
+
+Enable debug logging with the `DEBUG` environment variable:
+
+```bash
+DEBUG=location-client-react:* npm run dev
+```
+
 ## TypeScript Support
 
 Full TypeScript support with types from AWS SDK:
@@ -226,21 +221,11 @@ Full TypeScript support with types from AWS SDK:
 import type { SuggestCommandOutput } from '@aws-sdk/client-geo-places'
 
 const { client } = useLocationClient()
-
-const response: SuggestCommandOutput = await client.send(
+const response: SuggestCommandOutput = await client!.send(
   new SuggestCommand({ QueryText: 'Vancouver' })
 )
 ```
 
-## Security Best Practices
-
-⚠️ **NEVER expose client credentials in browser code!**
-
-- The `getConfig` function should call a server-side API or Server Action
-- Store `client_id` and `client_secret` in server environment variables only
-- Only the JWT token should be sent to the browser
-- Tokens should be short-lived and refreshed as needed
-
 ## License
 
 MIT

package/dist/hooks/useMapLanguage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal interface describing the MapLibre Map methods used by this hook.
+ * Using a structural type avoids maplibre-gl version conflicts between packages.
+ */
+interface MapLike {
+    isStyleLoaded(): boolean | void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off(event: string, listener: (...args: unknown[]) => void): void;
+}
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+export declare function useMapLanguage(map: MapLike | null, language: string): void;
+export {};

package/dist/hooks/useMapLanguage.js

@@ -0,0 +1,32 @@
+'use client';
+import { useEffect } from 'react';
+import { applyMapLanguage } from '@chaosity/location-client';
+/**
+ * React hook that keeps map label language in sync with the `language` prop.
+ *
+ * Registers a persistent `style.load` listener so language is automatically
+ * reapplied whenever `map.setStyle()` is called (e.g. style or color scheme change).
+ * Also applies immediately if the style is already loaded.
+ *
+ * @param map - MapLibre Map instance, or null while the map is initializing
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja')
+ *
+ * @example
+ * const [mapInstance, setMapInstance] = useState<maplibregl.Map | null>(null)
+ * useMapLanguage(mapInstance, language)
+ */
+export function useMapLanguage(map, language) {
+    useEffect(() => {
+        if (!map)
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const applyFn = () => applyMapLanguage(map, language);
+        if (map.isStyleLoaded()) {
+            applyFn();
+        }
+        map.on('style.load', applyFn);
+        return () => {
+            map.off('style.load', applyFn);
+        };
+    }, [map, language]);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { LocationClientProvider, useLocationClient } from './provider/LocationClientProvider';
 export type { LocationClientProviderProps } from './provider/LocationClientProvider';
+export { useMapLanguage } from './hooks/useMapLanguage';

package/dist/index.js

@@ -1 +1,2 @@
 export { LocationClientProvider, useLocationClient } from './provider/LocationClientProvider';
+export { useMapLanguage } from './hooks/useMapLanguage';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/chaosity-io/location-service-client-react.git"
+    "url": "git+https://github.com/chaosity-io/location-service-client-react.git"
   },
   "homepage": "https://github.com/chaosity-io/location-service-client-react",
   "bugs": {
@@ -34,14 +34,21 @@
     "debug": "^4.4.3"
   },
   "peerDependencies": {
+    "maplibre-gl": "^5.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",
     "@types/debug": "^4.1.12",
     "@types/react": "^19.0.0",
     "happy-dom": "^17.0.0",
+    "maplibre-gl": "^5.0.0",
     "react": "^19.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"