@mappedin/mappedin-js 5.45.1 → 5.47.0

package/lib/esm/get-venue/index.d.ts

@@ -30,7 +30,7 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue' {
         */
     export function setFetchFn(fetchFn: any): void;
     /** Classes */
-    export { MappedinCollectionType, MappedinNavigatable, MappedinNode, MappedinLocation, MappedinPolygon, MappedinCategory, MappedinDirections, MappedinDestinationSet, MappedinVortex, MappedinVenue, MappedinRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinCoordinate, MappedinMapGroup, Mappedin, } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    export { MappedinCollectionType, MappedinNavigatable, MappedinNode, MappedinLocation, MappedinPolygon, MappedinCategory, MappedinDirections, MappedinDestinationSet, MappedinVortex, MappedinVenue, MappedinRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinCoordinate, MappedinMapGroup, findPreferredLanguage, Mappedin, } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
     /**
         * @internal
         * @hidden
@@ -226,6 +226,11 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.types' {
             noAuth?: boolean;
             perspective?: string;
             language?: string;
+            /**
+                * Fallback to navigator language if the language is not available
+                * @default true
+                */
+            fallbackToNavigatorLanguages?: boolean;
             headers?: {
                     [key in string]: string;
             };
@@ -292,18 +297,18 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.types' {
 declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin' {
     import { Navigator } from '@mappedin/mappedin-js/lib/esm/get-venue/--/navigator';
     import type { TAllGetVenueOptions, TGetVenueOptions, TGetVenueOptionsInternal } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.types';
-    import type { MappedinNode, MappedinPolygon, MappedinLocation, MappedinCategory, MappedinVortex, MappedinVenue, MappedinTheme, MappedinRankings, MappedinLocationRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinMapGroup, GET_VENUE_PAYLOAD } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
-    import { TAccessors, GET_VENUE_EVENT } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
-    import { IAnalytics } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.CustomerAnalytics';
-    import { ParsedMVF } from '@mappedin/mvf';
-    import { ParsedMVFv1 } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.MVF.types';
+    import type { MappedinNode, MappedinPolygon, MappedinLocation, MappedinCategory, MappedinVortex, MappedinVenue, MappedinTheme, MappedinRankings, MappedinLocationRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinMapGroup, GET_VENUE_PAYLOAD, TAccessors } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    import { GET_VENUE_EVENT } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    import type { IAnalytics } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.CustomerAnalytics';
+    import type { ParsedMVF } from '@mappedin/mvf';
+    import type { ParsedMVFv1 } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.MVF.types';
     import { PubSub } from '@mappedin/mappedin-js/lib/esm/get-venue/pub-sub.typed';
     export const defaultOptions: TGetVenueOptionsInternal<TGetVenueOptions>;
     export class Mappedin extends PubSub<GET_VENUE_PAYLOAD, GET_VENUE_EVENT> {
             #private;
             perspective: any;
             things: any;
-            options: any;
+            options: TGetVenueOptionsInternal<TAllGetVenueOptions> & Pick<TGetVenueOptions, 'language' | 'fallbackToNavigatorLanguages'>;
             updatedAt?: string;
             categories: MappedinCategory[];
             locations: MappedinLocation[];
@@ -545,6 +550,25 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin' {
                 */
             toString: (includeOptions?: boolean) => string;
     }
+    /**
+        * Finds the ideal language for the venue based on the following priority:
+        * 1. User specified language (if it exists in venue languages)
+        * 2. Browser navigator languages (if fallback is enabled)
+        * 3. Venue's default language
+        *
+        * @param venue - The MappedinVenue object containing available languages
+        * @param options - Configuration options
+        * @param options.language - Preferred language code to use
+        * @param options.fallbackToNavigatorLanguages - Whether to use browser's language settings as fallback (defaults to true)
+        * @returns An object containing the selected language code and name, or undefined if no language is found
+        */
+    export function findPreferredLanguage(venue: MappedinVenue, options: {
+            language?: string;
+            fallbackToNavigatorLanguages?: boolean;
+    }): {
+            code: string;
+            name: string;
+    } | undefined;
 }
 
 declare module '@mappedin/mappedin-js/lib/esm/get-venue/default-things' {
@@ -629,7 +653,7 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/internal' {
             code: string;
         };
     };
-    export { Mappedin } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin';
+    export { Mappedin, findPreferredLanguage } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin';
 }
 
 declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.CustomerAnalytics' {
@@ -949,6 +973,51 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/MappedinLocation' {
                 */
             get parent(): MappedinLocation | undefined;
             set parent(parent: MappedinLocation | undefined);
+            /**
+                * Specific instances of this location with different properties.
+                * Typically, there will be at least one node or polygon defined,
+                * plus one or more other properties that are different from the parent.
+                * The remaining properties will be the same as the parent.
+                * For example, suppose there is a location like this:
+                *
+                * ```json
+                * {
+                *   "id": "location-id-1",
+                *   "name": "Location 1",
+                *   "nodes": ["node-1", "node-2"],
+                *   "polygons": ["polygon-1", "polygon-2"],
+                *   "externalId": "externalId-1",
+                *   "description": "Description 1",
+                * }
+                * ```
+                *
+                * (Note that for clarity, we have put strings in for nodes and polygons, but in practice they would be objects.)
+                *
+                * Then suppose it had an `instances` array that contained an object that looked like this:
+                *
+                * ```json
+                * {
+                *   "id": "instance-id-1",
+                *   "name": "Location 1 - A",
+                *   "nodes": ["node-1"],
+                *   "polygons": ["polygon-1"],
+                *   "externalId": "externalId-1-A",
+                *   "description": "Description 1",
+                * }
+                * ```
+                * This says "Location 1" is the parent location, and "Location 1 - A" is an instance of it. The instance has a different name, and a different external ID, and it only applies to node `node-1` and polygon `polygon-1`.
+                * The ID will always be different, but other properties (like the description) are the same as the parent.
+                *
+                * Example use cases:
+                * - A Mall may have a location with two nodes and one polygon. It may then have an instance with one of the nodes, and operating hours
+                * that are different from the parent. This indicates that this instance is an entrance for the location that is accessible at different times, perhaps for an interior mall entrance, when the main location (and other, exterior entrance) is open later than the rest of the mall.
+                * - An airport may have a location with several polygons and nodes, and an instance for each node (and corresponding polygon, if any) with a different siblingGroup. The location in the sibling group may be the airport terminal, or airside vs landside.
+                * This would allow an application to show the location once in a search result, but offer UX to select the instance that is in the right terminal.
+                *
+                * Note: Instances are actual EnterpriseLocations. This means they have all the properties of a normal EnterpriseLocation, including an `instances` property, that will always be undefined. They also do NOT have a parent property, or any other explicit reference to the parent location. These instances are
+                * only referenced from their parent location, and will not show up in other places in the map data. However, they should otherwise behave like normal EnterpriseLocations, being targetable for things like navigation and focus.
+                */
+            get instances(): MappedinLocation[];
             /**
                 * Categories related to this location.
                 *
@@ -1252,11 +1321,7 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.OfflineSearch'
             /**
                 * Search for a term
                 */
-            search(
-            /**
-                * Search term
-                */
-            term: string): Promise<TMappedinOfflineSearchResult[]>;
+            search(term: string): Promise<TMappedinOfflineSearchResult[]>;
             /**
                 * Export search index to JSON for storage/caching - this would avoid having to re-index
                 * on page reload
@@ -1521,7 +1586,7 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/' {
         */
     export function setFetchFn(fetchFn: any): void;
     /** Classes */
-    export { MappedinCollectionType, MappedinNavigatable, MappedinNode, MappedinLocation, MappedinPolygon, MappedinCategory, MappedinDirections, MappedinDestinationSet, MappedinVortex, MappedinVenue, MappedinRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinCoordinate, MappedinMapGroup, Mappedin, } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    export { MappedinCollectionType, MappedinNavigatable, MappedinNode, MappedinLocation, MappedinPolygon, MappedinCategory, MappedinDirections, MappedinDestinationSet, MappedinVortex, MappedinVenue, MappedinRankings, MappedinEvent, MappedinLocationState, MappedinMap, MappedinCoordinate, MappedinMapGroup, findPreferredLanguage, Mappedin, } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
     /**
         * @internal
         * @hidden
@@ -2029,9 +2094,9 @@ declare module '@mappedin/mappedin-js/lib/esm/get-venue/MappedinNavigatable' {
 }
 
 declare module '@mappedin/mappedin-js/lib/esm/get-venue/MappedinNode' {
-    import type { MappedinPolygon, MappedinLocation, Mappedin } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    import type { MappedinPolygon, MappedinLocation, Mappedin, MappedinDirections, MappedinMap, TDirectionToOptions } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
     import type { TOpeningHours } from '@mappedin/mappedin-js/lib/esm/get-venue/Mappedin.API.types';
-    import { MappedinNavigatable, MappedinDirections, MappedinDestinationSet, MappedinMap, TDirectionToOptions } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
+    import { MappedinNavigatable, MappedinDestinationSet } from '@mappedin/mappedin-js/lib/esm/get-venue/internal';
     /**
         * A {@link MappedinNode} represents a position, anchored to a specific {@link MappedinMap}.
         *