@mapvx/website-component 0.9.0 → 0.11.0

package/README.md

@@ -274,9 +274,10 @@ The web component accepts the following input properties to customize its behavi
 
 The web component emits custom events that you can listen to for user interactions:
 
-| Event Name     | Type     | Description                                                     |
-| -------------- | -------- | --------------------------------------------------------------- |
-| `cardSelected` | `string` | Emitted when a location card is selected. Contains the card ID. |
+| 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. |
 
 ### Output Usage Examples
 
@@ -284,30 +285,30 @@ The web component emits custom events that you can listen to for user interactio
 
 ```javascript
 // Wait for the web component to be registered
-function setupCardSelectedListener() {
+function setupUserActionListener() {
   const element = document.querySelector('mapvx-website')
   if (element) {
-    element.addEventListener('cardSelected', (event) => {
-      if (event instanceof CustomEvent) {
-        const cardId = event.detail
-        console.log('Card selected:', cardId)
-        // Handle card selection
+    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(setupCardSelectedListener, 100)
+    setTimeout(setupUserActionListener, 100)
   }
 }
 
 // Check if web component is already registered
 if (customElements.get('mapvx-website')) {
-  setupCardSelectedListener()
+  setupUserActionListener()
 } else {
   // Wait for registration
   const checkInterval = setInterval(() => {
     if (customElements.get('mapvx-website')) {
-      setupCardSelectedListener()
+      setupUserActionListener()
       clearInterval(checkInterval)
     }
   }, 100)
@@ -316,7 +317,7 @@ if (customElements.get('mapvx-website')) {
 
 #### Update Browser URL with `history.pushState`
 
-You can also react to the `cardSelected` event 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. Add this script to your HTML page after the web component:s
+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
 <script>
@@ -328,19 +329,60 @@ You can also react to the `cardSelected` event to change the browser URL without
       return
     }
 
-    const handleCardSelected = (event) => {
+    const handleUserAction = (event) => {
       if (event instanceof CustomEvent) {
-        const cardId = event.detail
-        // Update URL using history.pushState
-        history.pushState(
-          { page: 'profile', id: cardId },
-          '',
-          `${location.pathname}?tenant=${cardId}`,
-        )
+        const action = event.detail
+        switch (action.type) {
+          case 'return-to-home':
+          case 'select-filter': {
+            const { filter } = action.data
+            history.pushState(
+              { page: 'home', filter },
+              '',
+              `${location.pathname}?tab=${encodeURIComponent(filter)}`,
+            )
+            break
+          }
+          case 'show-place': {
+            const { placeId, alias } = action.data
+            if (alias) {
+              history.pushState(
+                { page: 'profile', id: alias },
+                '',
+                `${location.pathname}?tenant=${alias}`,
+              )
+            } else {
+              history.pushState(
+                { page: 'profile', id: placeId },
+                '',
+                `${location.pathname}?tenant=${placeId}`,
+              )
+            }
+            break
+          }
+          case 'search': {
+            const { searchTerm } = action.data
+            history.pushState(
+              { page: 'search', term: searchTerm },
+              '',
+              `${location.pathname}?search=${encodeURIComponent(searchTerm)}`,
+            )
+            break
+          }
+          case 'select-destination': {
+            const { destinationId } = action.data
+            history.pushState(
+              { page: 'route', id: destinationId },
+              '',
+              `${location.pathname}?destination=${destinationId}`,
+            )
+            break
+          }
+        }
       }
     }
 
-    element.addEventListener('cardSelected', handleCardSelected)
+    element.addEventListener('userAction', handleUserAction)
   }
 
   // Check if web component is already registered
@@ -370,18 +412,214 @@ function App() {
     const element = webComponentRef.current
     if (!element) return
 
-    const handleCardSelected = (event) => {
+    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 <mapvx-website ref={webComponentRef} api-key="your-api-key-here" />
+}
+```
+
+#### Vue
+
+```vue
+<template>
+  <mapvx-website ref="webComponent" api-key="your-api-key-here" />
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const webComponent = ref(null)
+
+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
+  }
+}
+
+onMounted(() => {
+  if (webComponent.value) {
+    webComponent.value.addEventListener('userAction', handleUserAction)
+  }
+})
+
+onUnmounted(() => {
+  if (webComponent.value) {
+    webComponent.value.removeEventListener('userAction', handleUserAction)
+  }
+})
+</script>
+```
+
+#### Angular
+
+```typescript
+import { Component, ElementRef, OnDestroy, ViewChild, AfterViewInit } from '@angular/core'
+
+@Component({
+  selector: 'app-mapvx',
+  template: ` <mapvx-website #webComponent [attr.api-key]="apiKey" /> `,
+})
+export class MapvxComponent implements AfterViewInit, OnDestroy {
+  @ViewChild('webComponent', { static: false }) webComponentRef!: ElementRef<HTMLElement>
+
+  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 cardId = event.detail
-        console.log('Card selected:', cardId)
-        // Handle card selection
+        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('cardSelected', handleCardSelected)
+    element.addEventListener('userAction', this.userActionListener)
+  }
+
+  ngOnDestroy() {
+    const element = this.webComponentRef?.nativeElement
+    if (element && this.userActionListener) {
+      element.removeEventListener('userAction', this.userActionListener)
+    }
+  }
+}
+```
+
+### User Action Event
+
+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('cardSelected', handleCardSelected)
+      element.removeEventListener('userAction', handleUserAction)
     }
   }, [])
 
@@ -401,23 +639,36 @@ import { ref, onMounted, onUnmounted } from 'vue'
 
 const webComponent = ref(null)
 
-const handleCardSelected = (event) => {
+const handleUserAction = (event) => {
   if (event instanceof CustomEvent) {
-    const cardId = event.detail
-    console.log('Card selected:', cardId)
-    // Handle card selection
+    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
+    }
   }
 }
 
 onMounted(() => {
   if (webComponent.value) {
-    webComponent.value.addEventListener('cardSelected', handleCardSelected)
+    webComponent.value.addEventListener('userAction', handleUserAction)
   }
 })
 
 onUnmounted(() => {
   if (webComponent.value) {
-    webComponent.value.removeEventListener('cardSelected', handleCardSelected)
+    webComponent.value.removeEventListener('userAction', handleUserAction)
   }
 })
 </script>
@@ -426,7 +677,7 @@ onUnmounted(() => {
 #### Angular
 
 ```typescript
-import { Component, ElementRef, OnInit, OnDestroy, ViewChild, AfterViewInit } from '@angular/core'
+import { Component, ElementRef, OnDestroy, ViewChild, AfterViewInit } from '@angular/core'
 
 @Component({
   selector: 'app-mapvx',
@@ -436,35 +687,48 @@ export class MapvxComponent implements AfterViewInit, OnDestroy {
   @ViewChild('webComponent', { static: false }) webComponentRef!: ElementRef<HTMLElement>
 
   apiKey = 'your-api-key-here'
-  private cardSelectedListener?: (event: Event) => void
+  private userActionListener?: (event: Event) => void
 
   ngAfterViewInit() {
-    this.setupCardSelectedListener()
+    this.setupUserActionListener()
   }
 
-  private setupCardSelectedListener() {
+  private setupUserActionListener() {
     const element = this.webComponentRef?.nativeElement
     if (!element) {
       // Retry if element is not yet available
-      setTimeout(() => this.setupCardSelectedListener(), 100)
+      setTimeout(() => this.setupUserActionListener(), 100)
       return
     }
 
-    this.cardSelectedListener = (event: Event) => {
+    this.userActionListener = (event: Event) => {
       if (event instanceof CustomEvent) {
-        const cardId = event.detail as string
-        console.log('Card selected:', cardId)
-        // Handle card selection
+        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('cardSelected', this.cardSelectedListener)
+    element.addEventListener('userAction', this.userActionListener)
   }
 
   ngOnDestroy() {
     const element = this.webComponentRef?.nativeElement
-    if (element && this.cardSelectedListener) {
-      element.removeEventListener('cardSelected', this.cardSelectedListener)
+    if (element && this.userActionListener) {
+      element.removeEventListener('userAction', this.userActionListener)
     }
   }
 }