MapVX Website Component

A modern, framework-agnostic web component built with Angular 20 that provides an interactive map and location discovery interface.

🚀 Features

- ✅ Compatible with any framework (React, Vue, Vanilla JS, etc.)
- ✅ Self-contained and isolated (Shadow DOM)
- ✅ Optimized bundle without hashing for production
- ✅ Angular 20 with modern architecture (standalone components)
- 🔑 Requires API Key: The component needs a valid API key to function

📦 Installation

$3

``bash
npm install @mapvx/website-component
`

After installation, you can reference the files in your application:

JavaScript/TypeScript:

`javascript
// Import the main component file
import '@mapvx/website-component/dist/browser/main.js'
// Import the styles
import '@mapvx/website-component/dist/browser/styles.css'
`

HTML:

`html



`

Webpack/Vite/Bundler:

`javascript
// In your main entry file
import '@mapvx/website-component/dist/browser/main.js'
import '@mapvx/website-component/dist/browser/styles.css'
`

Framework-specific examples:

React:

`jsx
// In your main App.jsx or index.jsx
import '@mapvx/website-component/dist/browser/main.js'

function App() {
return
}
`

`css
/ In your main CSS file (e.g., index.css, App.css) /
@import '@mapvx/website-component/dist/browser/styles.css';
`

Vue:

`javascript
// In your main.js
import '@mapvx/website-component/dist/browser/main.js'
`

`css
/ In your main CSS file (e.g., style.css, main.css) /
@import '@mapvx/website-component/dist/browser/styles.css';
`

Angular:

#### Method 1: HTML Script Tags

Configure assets in angular.json and use script tags in index.html:

`json
{
"assets": [
{
"glob": "*/",
"input": "public"
},
{
"glob": "*/",
"input": "src/assets",
"output": "assets"
},
{
"glob": "*/",
"input": "node_modules/@mapvx/website-component/dist/browser",
"output": "website-component"
}
]
}
`

Then reference the files in your index.html:

`html





`

Why this configuration is needed:

- Angular doesn't serve files from node_modules by default in development
- Without proper asset configuration, you'll get SyntaxError: Unexpected token '<' errors
- This ensures files are served as static assets with proper caching headers

#### Method 2: TypeScript Imports

Alternatively, you can import the files in your application:

`typescript
// In your main.ts - Import the JavaScript
import '@mapvx/website-component/dist/browser/main.js'
`

`scss
/ In your styles.scss - Import the styles (Modern Sass) /
@use '@mapvx/website-component/dist/browser/styles.css';

/ Alternative for older Sass versions or CSS files /
@import '@mapvx/website-component/dist/browser/styles.css';
`

Important: Choose ONE method only:

- ✅ Method 1: HTML script tags + assets configuration
- ✅ Method 2: TypeScript imports + SCSS imports
- ❌ Don't use both: This can cause duplicate loading and conflicts

$3

For Server-Side Rendering (SSR) applications that need to preload initial data on the server:

`bash
npm install @mapvx/website-component-helpers
`

$3

`html


rel="stylesheet"
href="https://unpkg.com/@mapvx/website-component@latest/dist/browser/styles.css"
/>
`

🎯 Usage

$3

`html


`

$3

`html

api-key="your-api-key-here"
institution-id="optional-institution-id"
initial-data='{"custom": "data"}'
default-to-map="true"
show-category-filters="false"
show-city-filter="true"
inherit-font-family="false"
>

`

$3

#### React

`jsx
function App() {
return (
api-key="your-api-key-here"
default-to-map="true"
show-category-filters="false"
/>
)
}
`

#### Vue

`vue

`

#### Angular

`typescript
// In your component
@Component({
template:
[attr.api-key]="apiKey"
[attr.default-to-map]="defaultToMap"
[attr.show-category-filters]="showFilters"
/>
,
})
export class MyComponent {
apiKey = 'your-api-key-here'
defaultToMap = true
showFilters = false
}
`

📋 Input Properties

The web component accepts the following input properties to customize its behavior:

| Property | Type | Required | Default | Description |
| ----------------------- | --------- | ---------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| api-key | string | ✅ Yes | - | Valid API key to initialize the SDK |
| institution-id | string | ✅ Yes | - | Institution ID for specific data filtering and search |
| initial-data | string | ❌ No | - | JSON string with initial data (use prepareInitialData from @mapvx/website-component-helpers) |
| default-to-map | boolean | ❌ No | false | If true, shows map view by default |
| show-category-filters | boolean | ❌ No | true | If true, shows category filters |
| show-city-filter | boolean | ❌ No | true | If true, shows city filter |
| inherit-font-family | boolean | ❌ No | false | If true, inherits font family from parent |
| hide-deals | boolean | ❌ No | false | If true, hides deals and promotional content |
| card-width | number | ❌ No | 237 (desktop), 170 (mobile) | Custom card width in pixels for grid view. Affects card size and number of cards per row |
| rows-per-page | number | ❌ No | 2 | Maximum number of rows per page (1-10). Shows fewer rows if not enough cards to fill all rows |

$3

#### Required Properties Only

`html

`

#### With Optional Configuration

`html
api-key="your-api-key-here"
institution-id="institution-123"
default-to-map="true"
show-category-filters="false"
show-city-filter="true"
hide-deals="true"
card-width="300"
>

`

#### Custom Card Width

`html







`

#### Custom Rows Per Page

`html





api-key="your-api-key-here"
institution-id="institution-123"
card-width="250"
rows-per-page="4"
>

`

📤 Output Events

The web component emits custom events that you can listen to for user interactions:

| Event Name | Type | Description |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| cardSelected | string | ⚠️ Deprecated: Use userAction with type show-place instead. Emitted when a location card is selected. Contains the card ID. |
| userAction | UserAction | Emitted when a user performs an action (filter selection, search, place navigation, etc.). Contains action type and associated data. |

$3

#### Vanilla JavaScript

`javascript
// Wait for the web component to be registered
function setupUserActionListener() {
const element = document.querySelector('mapvx-website')
if (element) {
element.addEventListener('userAction', (event) => {
if (event instanceof CustomEvent && event.detail.type === 'show-place') {
const placeId = event.detail.data.placeId
console.log('Place shown:', placeId)
// Handle place display
}
})
} else {
// Retry if element is not yet available
setTimeout(setupUserActionListener, 100)
}
}

// Check if web component is already registered
if (customElements.get('mapvx-website')) {
setupUserActionListener()
} else {
// Wait for registration
const checkInterval = setInterval(() => {
if (customElements.get('mapvx-website')) {
setupUserActionListener()
clearInterval(checkInterval)
}
}, 100)
}
`

#### Update Browser URL with history.pushState

You can react to user actions to change the browser URL without a full page reload, which is especially useful in SSR apps looking to keep client-side navigation in sync with the selected place.

`html

`

#### React

`jsx
import { useEffect, useRef } from 'react'

function App() {
const webComponentRef = useRef(null)

useEffect(() => {
const element = webComponentRef.current
if (!element) return

const handleUserAction = (event) => {
if (event instanceof CustomEvent && event.detail.type === 'show-place') {
const placeId = event.detail.data.placeId
console.log('Place shown:', placeId)
// Handle place display
}
}

element.addEventListener('userAction', handleUserAction)

return () => {
element.removeEventListener('userAction', handleUserAction)
}
}, [])

return
}
`

#### Vue

`vue



`

#### Angular

`typescript
import { Component, ElementRef, OnDestroy, ViewChild, AfterViewInit } from '@angular/core'

@Component({
selector: 'app-mapvx',
template: ,
})
export class MapvxComponent implements AfterViewInit, OnDestroy {
@ViewChild('webComponent', { static: false }) webComponentRef!: ElementRef

apiKey = 'your-api-key-here'
private userActionListener?: (event: Event) => void

ngAfterViewInit() {
this.setupUserActionListener()
}

private setupUserActionListener() {
const element = this.webComponentRef?.nativeElement
if (!element) {
// Retry if element is not yet available
setTimeout(() => this.setupUserActionListener(), 100)
return
}

this.userActionListener = (event: Event) => {
if (event instanceof CustomEvent) {
const action = event.detail as { type: string; data: any }
if (action.type === 'show-place') {
const placeId = action.data.placeId
console.log('Place shown:', placeId)
// Handle place display
}
}
}

element.addEventListener('userAction', this.userActionListener)
}

ngOnDestroy() {
const element = this.webComponentRef?.nativeElement
if (element && this.userActionListener) {
element.removeEventListener('userAction', this.userActionListener)
}
}
}
`

$3

The userAction event provides detailed information about user interactions within the component. The event detail contains an object with type and data properties.

#### UserAction Types

| Type | Description | Data Structure |
| -------------------- | ------------------------------------------ | --------------------------------------- | ------------ |
| select-filter | Emitted when a filter is selected | { filter: string } |
| show-place | Emitted when a place is displayed | { placeId: string, alias: string | undefined } |
| select-destination | Emitted when a destination is selected | { destinationId: string, alias: string | undefined } |
| search | Emitted when a search is performed | { searchTerm: string } |
| return-to-home | Emitted when user returns to the home view | { filter: string } |

#### UserAction Usage Examples

#### Vanilla JavaScript

`javascript
// Wait for the web component to be registered
function setupUserActionListener() {
const element = document.querySelector('mapvx-website')
if (element) {
element.addEventListener('userAction', (event) => {
if (event instanceof CustomEvent) {
const action = event.detail
console.log('User action:', action.type, action.data)

// Handle different action types
switch (action.type) {
case 'select-filter':
console.log('Filter selected:', action.data.filter)
break
case 'show-place':
console.log('Place shown:', action.data.placeId)
break
case 'select-destination':
console.log('Destination selected:', action.data.destinationId)
break
case 'search':
console.log('Search performed:', action.data.searchTerm)
break
case 'return-to-home':
console.log('Returned to home with filter:', action.data.filter)
break
}
}
})
} else {
// Retry if element is not yet available
setTimeout(setupUserActionListener, 100)
}
}

// Check if web component is already registered
if (customElements.get('mapvx-website')) {
setupUserActionListener()
} else {
// Wait for registration
const checkInterval = setInterval(() => {
if (customElements.get('mapvx-website')) {
setupUserActionListener()
clearInterval(checkInterval)
}
}, 100)
}
`

#### React

`jsx
import { useEffect, useRef } from 'react'

function App() {
const webComponentRef = useRef(null)

useEffect(() => {
const element = webComponentRef.current
if (!element) return

const handleUserAction = (event) => {
if (event instanceof CustomEvent) {
const action = event.detail
console.log('User action:', action.type, action.data)

// Handle different action types
switch (action.type) {
case 'select-filter':
// Handle filter selection
break
case 'show-place':
// Handle place display
break
case 'search':
// Handle search
break
// ... other cases
}
}
}

element.addEventListener('userAction', handleUserAction)

return () => {
element.removeEventListener('userAction', handleUserAction)
}
}, [])

return
}
`

#### Vue

`vue



`

#### Angular

`typescript
import { Component, ElementRef, OnDestroy, ViewChild, AfterViewInit } from '@angular/core'

@Component({
selector: 'app-mapvx',
template: ,
})
export class MapvxComponent implements AfterViewInit, OnDestroy {
@ViewChild('webComponent', { static: false }) webComponentRef!: ElementRef

apiKey = 'your-api-key-here'
private userActionListener?: (event: Event) => void

ngAfterViewInit() {
this.setupUserActionListener()
}

private setupUserActionListener() {
const element = this.webComponentRef?.nativeElement
if (!element) {
// Retry if element is not yet available
setTimeout(() => this.setupUserActionListener(), 100)
return
}

this.userActionListener = (event: Event) => {
if (event instanceof CustomEvent) {
const action = event.detail as { type: string; data: any }
console.log('User action:', action.type, action.data)

// Handle different action types
switch (action.type) {
case 'select-filter':
// Handle filter selection
break
case 'show-place':
// Handle place display
break
case 'search':
// Handle search
break
// ... other cases
}
}
}

element.addEventListener('userAction', this.userActionListener)
}

ngOnDestroy() {
const element = this.webComponentRef?.nativeElement
if (element && this.userActionListener) {
element.removeEventListener('userAction', this.userActionListener)
}
}
}
`

🔧 Server-Side Rendering (SSR) Support

For applications using Server-Side Rendering (SSR) where you need to preload initial data on the server before sending it to the browser:

$3

`bash
npm install @mapvx/website-component-helpers
`

$3

#### Next.js (App Router)

1. Install dependencies:

`bash
npm install @mapvx/website-component @mapvx/website-component-helpers
`

2. Copy the bundle script to your package.json:

`json
{
"scripts": {
"copy-bundle": "node copy-bundle.mjs"
}
}
`

3. Create copy-bundle.mjs in your project root:

`javascript
#!/usr/bin/env node

import { existsSync, mkdirSync, copyFileSync } from 'fs'
import { join } from 'path'

const sourcePath = 'node_modules/@mapvx/website-component/dist/browser/main.js'
const targetDir = 'public/mapvx-website'
const targetPath = join(targetDir, 'bundle.js')

if (!existsSync(sourcePath)) {
console.error(❌ Source file not found: ${sourcePath})
process.exit(1)
}

if (!existsSync(targetDir)) {
mkdirSync(targetDir, { recursive: true })
}

copyFileSync(sourcePath, targetPath)
console.log(✅ Bundle copied successfully!)
`

4. Create your page component:

`typescript
// app/page.tsx
import { prepareInitialData } from '@mapvx/website-component-helpers';
import '@mapvx/website-component/dist/browser/styles.css';
import Script from 'next/script';

export default async function HomePage() {
const initialData = await prepareInitialData(process.env.NEXT_PUBLIC_MAPVX_API_KEY || '');

return (