@mapvx/web-js 1.0.0

package/LICENSE.md

@@ -0,0 +1,19 @@
+# Proprietary License
+
+Copyright (c) 2024-2026 MapVX. All rights reserved.
+
+This software and associated documentation files (the "Software") are the proprietary property of
+MapVX. Unauthorized copying, modification, distribution, or use of this Software, in whole or in
+part, is strictly prohibited without prior written permission from MapVX.
+
+The Software is provided under a commercial license. For licensing inquiries, please contact
+the MapVX team.
+
+## Terms
+
+- You may use this Software only in accordance with the terms of your license agreement with MapVX.
+- You may not distribute, sublicense, or share this Software or its source code without explicit
+  written consent from MapVX.
+- This Software is provided "as is", without warranty of any kind, express or implied.
+
+For more information, visit [mapvx.com](https://mapvx.com) or contact your MapVX representative.

package/README.md

@@ -0,0 +1,257 @@
+# MapVX Web SDK
+
+A framework-agnostic TypeScript SDK for integrating indoor navigation and mapping capabilities into
+web applications. Works with Angular, React, Lit, and vanilla JavaScript.
+
+## Installation
+
+The package is available on the public npm registry. No authentication token is required.
+
+```bash
+npm install @mapvx/web-js
+```
+
+You also need to include MapLibre GL in your HTML:
+
+```html
+<script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
+<link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel="stylesheet" />
+```
+
+### Module Formats
+
+The SDK ships in three formats:
+
+| Format | Entry Point | Use Case |
+| ------ | ----------- | -------- |
+| ESM | `dist/es/index.js` | Modern bundlers (Vite, webpack 5, Rollup) |
+| CJS | `dist/cjs/index.js` | Node.js, legacy bundlers |
+| UMD | `dist/umd/index.js` | `<script>` tags, CDNs |
+
+Bundlers automatically pick the right format via the `exports` field in `package.json`.
+
+## Quick Start
+
+```typescript
+import { initializeSDK } from "@mapvx/web-js"
+
+// Initialize the SDK with your API token
+const sdk = initializeSDK("your-api-token")
+
+// Create a map
+const container = document.getElementById("map-container")
+const map = sdk.createMap(container, {
+  zoom: 18,
+  center: { lat: 40.7128, lng: -74.006 },
+  parentPlaceId: "your-building-id",
+  onMapReady: () => console.log("Map is ready!"),
+})
+```
+
+## Core Features
+
+### Fetching Places
+
+```typescript
+// Get all available places for your API token
+const places = await sdk.getAvailablePlaces()
+
+// Get sub-places within a building
+const subPlaces = await sdk.getSubPlaces("building-id")
+
+// Get details for a specific place
+const place = await sdk.getPlaceDetail("place-id")
+
+// Search for places
+const results = await sdk.getPlacesByInput("coffee", "institution-id", "building-id")
+```
+
+### Navigation Routes
+
+```typescript
+// Get a route between two points
+const route = await sdk.getRoute({
+  parentPlaceId: "building-id",
+  from: { placeId: "origin-place-id" },
+  to: { placeId: "destination-place-id" },
+  mode: "walking",
+})
+
+// Draw a route on the map
+const routeOnMap = await map.addRoute(
+  {
+    parentPlaceId: "building-id",
+    from: { placeId: "origin-place-id" },
+    to: { placeId: "destination-place-id" },
+  },
+  {
+    width: 4,
+    style: { type: "solid", color: "#007AFF" },
+  }
+)
+
+// Animate a route
+await map.startAnimateRoute({
+  parentPlaceId: "building-id",
+  from: { placeId: "origin-place-id" },
+  to: { placeId: "destination-place-id" },
+})
+```
+
+### Markers
+
+```typescript
+// Add a marker
+const markerId = map.addMarker({
+  id: "my-marker",
+  position: { lat: 40.7128, lng: -74.006 },
+  color: "#FF0000",
+})
+
+// Update marker position
+map.updateMarkerPosition("my-marker", { lat: 40.713, lng: -74.007 })
+
+// Remove a marker
+map.removeMarker("my-marker")
+```
+
+### User Location
+
+```typescript
+// Track user location on the map
+map.addUserLocationTracking(true) // true for high accuracy
+
+// Watch user position
+const watchId = sdk.watchUserPosition(
+  (position) => console.log("Position:", position),
+  (error) => console.error("Error:", error)
+)
+
+// Stop watching
+sdk.unWatchUserPosition(watchId)
+```
+
+### Floor Navigation
+
+```typescript
+// Change the displayed floor
+map.updateFloor("floor-2")
+
+// Get current floor
+const currentFloor = map.getCurrentFloor()
+
+// Listen for floor changes
+const mapConfig = {
+  // ...other config
+  onFloorChange: (newFloorId) => console.log("Floor changed to:", newFloorId),
+}
+```
+
+## Configuration Options
+
+### SDK Configuration
+
+```typescript
+const sdk = initializeSDK("your-api-token", {
+  lang: "en", // Language for labels and responses
+  apiUrl: "https://public-api.mapvx.com", // API endpoint (default)
+  cache: {
+    persistent: true, // Enable localStorage persistence
+    maxStorageBytes: 5 * 1024 * 1024, // 5MB cache limit
+    configs: {
+      places: { maxItems: 1000, ttlMs: 60000 },
+    },
+  },
+})
+```
+
+### Map Configuration
+
+```typescript
+const map = sdk.createMap(container, {
+  zoom: 18,
+  center: { lat: 40.7128, lng: -74.006 },
+  parentPlaceId: "building-id",
+
+  // Optional settings
+  minZoom: 15,
+  maxZoom: 22,
+  pitch: 45, // 3D tilt in degrees
+  showCompass: true,
+  showZoom: true,
+  navigationPosition: "top-right",
+  enableHover: true,
+  lang: "en",
+
+  // Tile caching for performance
+  tileCache: {
+    enabled: true,
+    maxTiles: 500,
+    ttlMs: 60 * 60 * 1000, // 1 hour
+    persistToServiceWorker: true,
+    preloadAdjacentZooms: false,
+  },
+
+  // Event callbacks
+  onMapReady: () => {},
+  onZoomEnd: (zoomLevel) => {},
+  onRotate: (degrees) => {},
+  onFloorChange: (floorId) => {},
+  onParentPlaceChange: (placeId) => {},
+})
+```
+
+### Tile Cache Management
+
+The SDK provides built-in tile caching for improved performance:
+
+```typescript
+// Configure tile caching when creating the map
+const map = sdk.createMap(container, {
+  // ...other config
+  tileCache: {
+    enabled: true, // Enable caching (default: true)
+    maxTiles: 400, // Max tiles in memory (default: 400)
+    ttlMs: 30 * 60 * 1000, // Cache TTL in ms (default: 30 minutes)
+    persistToServiceWorker: true, // Enable offline caching (default: true)
+    preloadAdjacentZooms: false, // Preload nearby zoom levels (default: false)
+  },
+})
+
+// Clear the tile cache when needed
+map.clearTileCache()
+```
+
+## API Reference
+
+For complete API documentation, see the [API Reference](./docs/content/API/index.md).
+
+### Main Interfaces
+
+- [`MapVXSDK`](./docs/content/API/Main/MapVXSDK.md) - Main SDK interface
+- [`MapVXMap`](./docs/content/API/Map/MapVXMap.md) - Map instance interface
+- [`MapConfig`](./docs/content/API/Map/MapConfig.md) - Map configuration options
+- [`MVXPlace`](./docs/content/API/Places___Locations/MVXPlace.md) - Place data model
+- [`MVXRoute`](./docs/content/API/Routes/MVXRoute.md) - Route data model
+
+## FAQ
+
+**Q: Navigation controls are missing on map generation, what can I do?**
+
+A: Ensure you have included the MapLibre GL CSS and JS files in your HTML. See the
+[Installation](#installation) section above.
+
+**Q: How do I handle multiple buildings?**
+
+A: Use the `otherPotentialParentPlacesIds` option in your map configuration or the
+`otherParentPlacesIds` parameter when searching for places.
+
+**Q: How do I enable offline map access?**
+
+A: Set `persistToServiceWorker: true` in the `tileCache` configuration. This enables service worker
+caching for offline tile access.
+
+## Support
+
+For support, please contact your MapVX representative or visit
+[MapVX](https://mapvx.com).

package/dist/cjs/assets/icons.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeAnimationDataUrl = exports.createRouteAnimationIconDataUrl = exports.userLocationDataUrl = void 0;
+exports.userLocationDataUrl = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%20aria-hidden%3D%22false%22%20role%3D%22img%22%3E%3Ccircle%20cx%3D%2212%22%20cy%3D%2212%22%20r%3D%226%22%20fill%3D%22var(--icon-fill%2C%20%23007aff)%22%20stroke%3D%22var(--icon-stroke%2C%20%23ffffff)%22%20stroke-width%3D%222%22/%3E%3C/svg%3E";
+/**
+ * Generates a data URL for the route animation icon SVG with customizable appearance.
+ *
+ * @param config - Optional configuration for the icon appearance.
+ * @param config.backgroundColor - The background color of the circle (default: "#0076B6").
+ * @param config.arrowColor - The color of the arrow (default: "#FFFFFF").
+ * @param config.arrowWidth - The stroke width of the arrow path in pixels (default: 0).
+ * @param config.borderWidth - The border width of the circle in pixels (default: 0).
+ * @param config.borderColor - The border color of the circle (default: "#000000").
+ * @param config.blur - The blur radius in pixels to apply to the icon (default: 0).
+ * @returns A data URL string that can be used as the `src` attribute of an `<img>` element.
+ *
+ * @example
+ * ```typescript
+ * // Use default appearance (blue background, white arrow)
+ * const defaultIcon = createRouteAnimationIconDataUrl()
+ *
+ * // Customize colors
+ * const customIcon = createRouteAnimationIconDataUrl({
+ *   backgroundColor: "#FF5733",
+ *   arrowColor: "#000000"
+ * })
+ *
+ * // Add border and blur
+ * const styledIcon = createRouteAnimationIconDataUrl({
+ *   backgroundColor: "#0076B6",
+ *   arrowColor: "#FFFFFF",
+ *   borderWidth: 2,
+ *   borderColor: "#000000",
+ *   blur: 1
+ * })
+ * ```
+ * @group Assets
+ */
+function createRouteAnimationIconDataUrl(config) {
+    var _a, _b, _c, _d, _e, _f;
+    const backgroundColor = (_a = config === null || config === void 0 ? void 0 : config.backgroundColor) !== null && _a !== void 0 ? _a : "#0076B6";
+    const arrowColor = (_b = config === null || config === void 0 ? void 0 : config.arrowColor) !== null && _b !== void 0 ? _b : "#FFFFFF";
+    const arrowWidth = (_c = config === null || config === void 0 ? void 0 : config.arrowWidth) !== null && _c !== void 0 ? _c : 0;
+    const borderWidth = (_d = config === null || config === void 0 ? void 0 : config.borderWidth) !== null && _d !== void 0 ? _d : 0;
+    const borderColor = (_e = config === null || config === void 0 ? void 0 : config.borderColor) !== null && _e !== void 0 ? _e : "#000000";
+    const blur = (_f = config === null || config === void 0 ? void 0 : config.blur) !== null && _f !== void 0 ? _f : 0;
+    // Build circle style with optional border
+    const circleStyle = `fill:${backgroundColor};`;
+    const circleStroke = borderWidth > 0 ? `stroke:${borderColor};stroke-width:${borderWidth};` : "";
+    // Build arrow style with optional stroke
+    const arrowStyle = `fill:${arrowColor};`;
+    const arrowStroke = arrowWidth > 0 ? `stroke:${arrowColor};stroke-width:${arrowWidth};` : "";
+    // Build filter for blur if needed
+    const filterId = blur > 0 ? "blurFilter" : "";
+    const filterDef = blur > 0
+        ? `<defs><filter id="${filterId}"><feGaussianBlur in="SourceGraphic" stdDeviation="${blur}"/></filter></defs>`
+        : "";
+    const filterAttr = blur > 0 ? `filter="url(#${filterId})"` : "";
+    const svg = `<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 40 40" style="enable-background:new 0 0 40 40;" xml:space="preserve">
+${filterDef}
+<g ${filterAttr}>
+	<circle cx="20" cy="20" r="20" style="${circleStyle}${circleStroke}"/>
+	<path style="${arrowStyle}${arrowStroke}" d="M12.4,29.7c-0.2,0.1-0.4,0.1-0.6,0.1c-0.2,0-0.4-0.1-0.5-0.3c-0.2-0.1-0.2-0.3-0.3-0.5c0-0.2,0-0.4,0.1-0.6
+		l8.2-17.8c0.2-0.4,0.5-0.6,0.9-0.6c0.4,0,0.7,0.2,0.9,0.6l7.9,17.9c0.1,0.2,0.1,0.4,0.1,0.6c0,0.2-0.1,0.4-0.3,0.5
+		c-0.1,0.1-0.3,0.2-0.5,0.3c-0.2,0-0.4,0-0.6-0.1L20,26.5L12.4,29.7z M13.9,27l6.1-2.6l6.1,2.7l-6-13.8L13.9,27z"/>
+</g>
+</svg>`;
+    // Encode the SVG as a data URL
+    const encodedSvg = encodeURIComponent(svg);
+    return `data:image/svg+xml,${encodedSvg}`;
+}
+exports.createRouteAnimationIconDataUrl = createRouteAnimationIconDataUrl;
+/**
+ * Default route animation icon data URL with blue background (#0076B6) and white arrow (#FFFFFF).
+ * This constant is maintained for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * const image = new Image(40, 40)
+ * image.src = routeAnimationDataUrl
+ * ```
+ * @group Assets
+ */
+exports.routeAnimationDataUrl = createRouteAnimationIconDataUrl();
+//# sourceMappingURL=icons.js.map

package/dist/cjs/assets/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.js","sourceRoot":"","sources":["../../../src/assets/icons.ts"],"names":[],"mappings":";;;AAAa,QAAA,mBAAmB,GAC9B,mYAAmY,CAAA;AAwCrY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,+BAA+B,CAAC,MAAiC;;IAC/E,MAAM,eAAe,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,eAAe,mCAAI,SAAS,CAAA;IAC5D,MAAM,UAAU,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,UAAU,mCAAI,SAAS,CAAA;IAClD,MAAM,UAAU,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,UAAU,mCAAI,CAAC,CAAA;IAC1C,MAAM,WAAW,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,mCAAI,CAAC,CAAA;IAC5C,MAAM,WAAW,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,mCAAI,SAAS,CAAA;IACpD,MAAM,IAAI,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,CAAC,CAAA;IAE9B,0CAA0C;IAC1C,MAAM,WAAW,GAAG,QAAQ,eAAe,GAAG,CAAA;IAC9C,MAAM,YAAY,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,WAAW,iBAAiB,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAEhG,yCAAyC;IACzC,MAAM,UAAU,GAAG,QAAQ,UAAU,GAAG,CAAA;IACxC,MAAM,WAAW,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,UAAU,iBAAiB,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAE5F,kCAAkC;IAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7C,MAAM,SAAS,GACb,IAAI,GAAG,CAAC;QACN,CAAC,CAAC,qBAAqB,QAAQ,sDAAsD,IAAI,qBAAqB;QAC9G,CAAC,CAAC,EAAE,CAAA;IACR,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAE/D,MAAM,GAAG,GAAG;;;EAGZ,SAAS;KACN,UAAU;yCAC0B,WAAW,GAAG,YAAY;gBACnD,UAAU,GAAG,WAAW;;;;OAIjC,CAAA;IAEL,+BAA+B;IAC/B,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC1C,OAAO,sBAAsB,UAAU,EAAE,CAAA;AAC3C,CAAC;AAvCD,0EAuCC;AAED;;;;;;;;;;GAUG;AACU,QAAA,qBAAqB,GAAG,+BAA+B,EAAE,CAAA"}

package/dist/cjs/assets/route_animation_icon.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 26.5.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 40 40" style="enable-background:new 0 0 40 40;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#0076B6;}
+	.st1{fill:#FFFFFF;}
+</style>
+<g>
+	<circle class="st0" cx="20" cy="20" r="20"/>
+	<path class="st1" d="M12.4,29.7c-0.2,0.1-0.4,0.1-0.6,0.1c-0.2,0-0.4-0.1-0.5-0.3c-0.2-0.1-0.2-0.3-0.3-0.5c0-0.2,0-0.4,0.1-0.6
+		l8.2-17.8c0.2-0.4,0.5-0.6,0.9-0.6c0.4,0,0.7,0.2,0.9,0.6l7.9,17.9c0.1,0.2,0.1,0.4,0.1,0.6c0,0.2-0.1,0.4-0.3,0.5
+		c-0.1,0.1-0.3,0.2-0.5,0.3c-0.2,0-0.4,0-0.6-0.1L20,26.5L12.4,29.7z M13.9,27l6.1-2.6l6.1,2.7l-6-13.8L13.9,27z"/>
+</g>
+</svg>

package/dist/cjs/assets/user-dot-icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" aria-hidden="false" role="img">
+    <circle cx="12" cy="12" r="6" fill="var(--icon-fill, #007aff)" stroke="var(--icon-stroke, #ffffff)" stroke-width="2"/>
+</svg>

package/dist/cjs/config/sdkConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sdkConfig.js.map

package/dist/cjs/config/sdkConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdkConfig.js","sourceRoot":"","sources":["../../../src/config/sdkConfig.ts"],"names":[],"mappings":""}