@chaosity/location-client 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -4,4 +4,9 @@ export * from '@aws/amazon-location-utilities-datatypes';
 export { GeoPlaces } from './adapters/GeoPlaces';
 export { createTransformRequest } from './maps/createTransformRequest';
 export { transformRequest } from './maps/Utils';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+export type { MapStyleOptions } from './maps/mapStyle';
+export { applyMapLanguage } from './maps/mapLanguage';
+export { setPoiVisibility, setAllPoiVisibility, POI_CATEGORIES } from './maps/mapPoi';
+export type { PoiCategory } from './maps/mapPoi';
 export type { ClientConfig } from './types';

package/dist/index.js

@@ -9,4 +9,7 @@ export { GeoPlaces } from './adapters/GeoPlaces';
 // Maps utilities
 export { createTransformRequest } from './maps/createTransformRequest';
 export { transformRequest } from './maps/Utils';
+export { buildMapStyleUrl, fetchMapStyle } from './maps/mapStyle';
+export { applyMapLanguage } from './maps/mapLanguage';
+export { setPoiVisibility, setAllPoiVisibility, POI_CATEGORIES } from './maps/mapPoi';
 // Server-only utilities are available via '@chaosity/location-client/server'

package/dist/maps/mapLanguage.d.ts

@@ -0,0 +1,19 @@
+import type { Map } from 'maplibre-gl';
+/**
+ * Apply a preferred display language to all symbol layers on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
+ * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
+ * on every symbol layer to prefer the requested language, falling back to English then the
+ * default name if the preferred language is unavailable for a feature.
+ *
+ * Based on the approach documented at:
+ * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ *
+ * @param map - MapLibre Map instance
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
+ *
+ * @example
+ * map.once('style.load', () => applyMapLanguage(map, 'fr'))
+ */
+export declare function applyMapLanguage(map: Map, language: string): void;

package/dist/maps/mapLanguage.js

@@ -0,0 +1,35 @@
+/**
+ * Apply a preferred display language to all symbol layers on a MapLibre map.
+ *
+ * AWS GeoMaps vector tiles include language-specific name properties in `name:${lang}` format
+ * (e.g. `name:en`, `name:fr`, `name:ja`). This function updates the `text-field` expression
+ * on every symbol layer to prefer the requested language, falling back to English then the
+ * default name if the preferred language is unavailable for a feature.
+ *
+ * Based on the approach documented at:
+ * https://docs.aws.amazon.com/location/latest/developerguide/how-to-set-preferred-language-map.html
+ *
+ * @param map - MapLibre Map instance
+ * @param language - ISO 639-1 language code (e.g. 'en', 'fr', 'de', 'ja', 'zh', 'ar')
+ *
+ * @example
+ * map.once('style.load', () => applyMapLanguage(map, 'fr'))
+ */
+export function applyMapLanguage(map, language) {
+    try {
+        const expression = language === 'en'
+            ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
+            : ['coalesce', ['get', `name:${language}`], ['get', 'name:en'], ['get', 'name']];
+        map.getStyle().layers.forEach(layer => {
+            if (layer.type === 'symbol') {
+                const textField = map.getLayoutProperty(layer.id, 'text-field');
+                if (textField !== undefined && textField !== null) {
+                    map.setLayoutProperty(layer.id, 'text-field', expression);
+                }
+            }
+        });
+    }
+    catch {
+        // Style may not be fully loaded — call after 'style.load' event
+    }
+}

package/dist/maps/mapPoi.d.ts

@@ -0,0 +1,44 @@
+import type { Map } from 'maplibre-gl';
+/**
+ * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
+ * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ */
+export declare const POI_CATEGORIES: {
+    readonly food_drink: readonly ["poi_100_food_drink"];
+    readonly entertainment: readonly ["poi_200_going_out_entertainment"];
+    readonly sights: readonly ["poi_300_sights_museums"];
+    readonly transit: readonly ["poi_400_transit"];
+    readonly accommodations: readonly ["poi_500_accommodations"];
+    readonly leisure: readonly ["poi_550_leisure_outdoor"];
+    readonly shopping: readonly ["poi_600_shopping"];
+    readonly business: readonly ["poi_700_business_services"];
+    readonly facilities: readonly ["poi_800_facilities"];
+    readonly areas: readonly ["poi_900_areas_buildings"];
+    readonly parks: readonly ["poi_landuse_park", "poi_landuse_public_complex"];
+};
+export type PoiCategory = keyof typeof POI_CATEGORIES;
+/**
+ * Set the visibility of one or more POI categories on the map.
+ *
+ * @param map - MapLibre Map instance
+ * @param category - POI category key or array of keys
+ * @param visible - Whether to show (true) or hide (false) the category
+ *
+ * @example
+ * // Hide transit and shopping POIs
+ * setPoiVisibility(map, ['transit', 'shopping'], false)
+ *
+ * // Show all food & drink POIs
+ * setPoiVisibility(map, 'food_drink', true)
+ */
+export declare function setPoiVisibility(map: Map, category: PoiCategory | PoiCategory[], visible: boolean): void;
+/**
+ * Show or hide all POI layers at once.
+ *
+ * @param map - MapLibre Map instance
+ * @param visible - Whether to show or hide all POIs
+ *
+ * @example
+ * setAllPoiVisibility(map, false) // hide everything
+ */
+export declare function setAllPoiVisibility(map: Map, visible: boolean): void;

package/dist/maps/mapPoi.js

@@ -0,0 +1,59 @@
+/**
+ * Mapping of POI category names to their MapLibre layer IDs in AWS GeoMaps tiles.
+ * Layer IDs are stable across Standard, Monochrome, and Hybrid map styles.
+ */
+export const POI_CATEGORIES = {
+    food_drink: ['poi_100_food_drink'],
+    entertainment: ['poi_200_going_out_entertainment'],
+    sights: ['poi_300_sights_museums'],
+    transit: ['poi_400_transit'],
+    accommodations: ['poi_500_accommodations'],
+    leisure: ['poi_550_leisure_outdoor'],
+    shopping: ['poi_600_shopping'],
+    business: ['poi_700_business_services'],
+    facilities: ['poi_800_facilities'],
+    areas: ['poi_900_areas_buildings'],
+    parks: ['poi_landuse_park', 'poi_landuse_public_complex'],
+};
+/**
+ * Set the visibility of one or more POI categories on the map.
+ *
+ * @param map - MapLibre Map instance
+ * @param category - POI category key or array of keys
+ * @param visible - Whether to show (true) or hide (false) the category
+ *
+ * @example
+ * // Hide transit and shopping POIs
+ * setPoiVisibility(map, ['transit', 'shopping'], false)
+ *
+ * // Show all food & drink POIs
+ * setPoiVisibility(map, 'food_drink', true)
+ */
+export function setPoiVisibility(map, category, visible) {
+    const categories = Array.isArray(category) ? category : [category];
+    const visibility = visible ? 'visible' : 'none';
+    for (const cat of categories) {
+        for (const layerId of POI_CATEGORIES[cat]) {
+            try {
+                if (map.getLayer(layerId)) {
+                    map.setLayoutProperty(layerId, 'visibility', visibility);
+                }
+            }
+            catch {
+                // Layer may not exist in the current map style
+            }
+        }
+    }
+}
+/**
+ * Show or hide all POI layers at once.
+ *
+ * @param map - MapLibre Map instance
+ * @param visible - Whether to show or hide all POIs
+ *
+ * @example
+ * setAllPoiVisibility(map, false) // hide everything
+ */
+export function setAllPoiVisibility(map, visible) {
+    setPoiVisibility(map, Object.keys(POI_CATEGORIES), visible);
+}

package/dist/maps/mapStyle.d.ts

@@ -0,0 +1,58 @@
+import type { StyleSpecification } from 'maplibre-gl';
+/**
+ * Options for building an AWS Location Service map style URL.
+ * All parameters map directly to query parameters supported by the style descriptor endpoint.
+ */
+export interface MapStyleOptions {
+    /** Color scheme for the map (default: Light). Not applicable to Satellite/Hybrid styles. */
+    colorScheme?: 'Light' | 'Dark';
+    /** ISO 3166-1 alpha-3 country code for political boundary perspective (e.g. 'IND', 'TUR'). */
+    politicalView?: string;
+    /** Terrain overlay type. */
+    terrain?: 'Hillshade' | 'Terrain3D';
+    /** Enable 3D building extrusions. */
+    buildings?: 'Buildings3D';
+    /** Elevation contour line density. */
+    contourDensity?: 'Low' | 'Medium' | 'High';
+    /** Enable real-time traffic flow visualization. */
+    traffic?: 'All';
+    /** Travel mode overlays for routing-specific features. */
+    travelModes?: Array<'Truck' | 'Transit'>;
+}
+/**
+ * Build a map style descriptor URL for the Location Service API.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param options - Optional style parameters
+ * @returns Full style descriptor URL
+ *
+ * @example
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * map.setStyle(url)
+ */
+export declare function buildMapStyleUrl(apiUrl: string, mapStyle: string, options?: MapStyleOptions): string;
+/**
+ * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
+ *
+ * Language is applied directly to the descriptor's layer definitions before MapLibre ever
+ * processes them, eliminating the visual flash that occurs when modifying layers post-load.
+ * All other style parameters (terrain, traffic, etc.) are passed as query parameters.
+ *
+ * The returned style object can be passed directly to `new maplibregl.Map({ style })` or
+ * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
+ * for authentication — this only pre-processes the descriptor itself.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param getToken - Callback returning the current auth token
+ * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @returns Modified MapLibre StyleSpecification object
+ *
+ * @example
+ * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
+ * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
+ */
+export declare function fetchMapStyle(apiUrl: string, mapStyle: string, getToken: () => string | undefined, options?: MapStyleOptions & {
+    language?: string;
+}): Promise<StyleSpecification>;

package/dist/maps/mapStyle.js

@@ -0,0 +1,88 @@
+/**
+ * Build a map style descriptor URL for the Location Service API.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param options - Optional style parameters
+ * @returns Full style descriptor URL
+ *
+ * @example
+ * const url = buildMapStyleUrl(API_URL, 'Standard', { colorScheme: 'Dark', terrain: 'Hillshade' })
+ * map.setStyle(url)
+ */
+export function buildMapStyleUrl(apiUrl, mapStyle, options = {}) {
+    const params = new URLSearchParams();
+    if (options.colorScheme)
+        params.set('color-scheme', options.colorScheme);
+    if (options.politicalView)
+        params.set('political-view', options.politicalView);
+    if (options.terrain)
+        params.set('terrain', options.terrain);
+    if (options.buildings)
+        params.set('buildings', options.buildings);
+    if (options.contourDensity)
+        params.set('contour-density', options.contourDensity);
+    if (options.traffic)
+        params.set('traffic', options.traffic);
+    if (options.travelModes?.length)
+        params.set('travel-modes', options.travelModes.join(','));
+    const qs = params.toString();
+    return `${apiUrl}/maps/${mapStyle}/descriptor${qs ? `?${qs}` : ''}`;
+}
+/**
+ * Fetch the map style descriptor with authentication and apply descriptor-level modifications.
+ *
+ * Language is applied directly to the descriptor's layer definitions before MapLibre ever
+ * processes them, eliminating the visual flash that occurs when modifying layers post-load.
+ * All other style parameters (terrain, traffic, etc.) are passed as query parameters.
+ *
+ * The returned style object can be passed directly to `new maplibregl.Map({ style })` or
+ * `map.setStyle()`. Tile, glyph, and sprite requests still go through `transformRequest`
+ * for authentication — this only pre-processes the descriptor itself.
+ *
+ * @param apiUrl - Base URL of the Location Service API
+ * @param mapStyle - Map style name (e.g. 'Standard', 'Monochrome', 'Satellite', 'Hybrid')
+ * @param getToken - Callback returning the current auth token
+ * @param options - Style options; `language` is applied to the descriptor, all others become URL params
+ * @returns Modified MapLibre StyleSpecification object
+ *
+ * @example
+ * const style = await fetchMapStyle(API_URL, 'Standard', getToken, { colorScheme: 'Dark', language: 'fr' })
+ * const map = new maplibregl.Map({ style, transformRequest: createTransformRequest(API_URL, getToken) })
+ */
+export async function fetchMapStyle(apiUrl, mapStyle, getToken, options = {}) {
+    const { language, ...styleOptions } = options;
+    const url = buildMapStyleUrl(apiUrl, mapStyle, styleOptions);
+    const token = getToken();
+    const response = await fetch(url, {
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Accept': 'application/json',
+        }
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch map style: ${response.status} ${response.statusText}`);
+    }
+    const style = await response.json();
+    if (language) {
+        applyLanguageToDescriptor(style, language);
+    }
+    return style;
+}
+/**
+ * Apply a preferred language to all symbol layers within a style descriptor object.
+ * Mutates the style in place — call before passing to MapLibre.
+ */
+function applyLanguageToDescriptor(style, language) {
+    const expression = language === 'en'
+        ? ['coalesce', ['get', 'name:en'], ['get', 'name']]
+        : ['coalesce', ['get', `name:${language}`], ['get', 'name:en'], ['get', 'name']];
+    for (const layer of style.layers) {
+        if (layer.type === 'symbol') {
+            const layout = layer.layout;
+            if (layout?.['text-field'] !== undefined) {
+                layout['text-field'] = expression;
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Client library for Chaosity Location Service with AWS Location Service compatibility",
   "type": "module",
   "main": "dist/index.js",