@mapvx/website-component 0.8.1 → 0.10.0

package/README.md

@@ -253,7 +253,7 @@ The web component accepts the following input properties to customize its behavi
 #### Required Properties Only
 
 ```html
-<mapvx-website api-key="your-api-key-here"></mapvx-website>
+<mapvx-website api-key="your-api-key-here" institution-id="institution-123"></mapvx-website>
 ```
 
 #### With Optional Configuration
@@ -270,6 +270,462 @@ The web component accepts the following input properties to customize its behavi
 </mapvx-website>
 ```
 
+## 📤 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. |
+
+### Output 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 && 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
+<script>
+  // Wait for the web component to be registered
+  function setupUrlUpdater() {
+    const element = document.querySelector('mapvx-website')
+    if (!element) {
+      setTimeout(setupUrlUpdater, 100)
+      return
+    }
+
+    const handleUserAction = (event) => {
+      if (event instanceof CustomEvent) {
+        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 } = action.data
+            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('userAction', handleUserAction)
+  }
+
+  // Check if web component is already registered
+  if (customElements.get('mapvx-website')) {
+    setupUrlUpdater()
+  } else {
+    // Wait for registration
+    const waitForRegistration = setInterval(() => {
+      if (customElements.get('mapvx-website')) {
+        clearInterval(waitForRegistration)
+        setupUrlUpdater()
+      }
+    }, 100)
+  }
+</script>
+```
+
+#### 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 <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 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)
+    }
+  }
+}
+```
+
+### 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 }`       |
+| `select-destination` | Emitted when a destination is selected     | `{ destinationId: string }` |
+| `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 <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) {
+    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('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 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: