@mapvx/website-component 0.8.0 → 0.9.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,206 @@ 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` | Emitted when a location card is selected. Contains the card ID. |
+
+### Output Usage Examples
+
+#### Vanilla JavaScript
+
+```javascript
+// Wait for the web component to be registered
+function setupCardSelectedListener() {
+  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
+      }
+    })
+  } else {
+    // Retry if element is not yet available
+    setTimeout(setupCardSelectedListener, 100)
+  }
+}
+
+// Check if web component is already registered
+if (customElements.get('mapvx-website')) {
+  setupCardSelectedListener()
+} else {
+  // Wait for registration
+  const checkInterval = setInterval(() => {
+    if (customElements.get('mapvx-website')) {
+      setupCardSelectedListener()
+      clearInterval(checkInterval)
+    }
+  }, 100)
+}
+```
+
+#### 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
+
+```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 handleCardSelected = (event) => {
+      if (event instanceof CustomEvent) {
+        const cardId = event.detail
+        // Update URL using history.pushState
+        history.pushState(
+          { page: 'profile', id: cardId },
+          '',
+          `${location.pathname}?tenant=${cardId}`,
+        )
+      }
+    }
+
+    element.addEventListener('cardSelected', handleCardSelected)
+  }
+
+  // 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 handleCardSelected = (event) => {
+      if (event instanceof CustomEvent) {
+        const cardId = event.detail
+        console.log('Card selected:', cardId)
+        // Handle card selection
+      }
+    }
+
+    element.addEventListener('cardSelected', handleCardSelected)
+
+    return () => {
+      element.removeEventListener('cardSelected', handleCardSelected)
+    }
+  }, [])
+
+  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 handleCardSelected = (event) => {
+  if (event instanceof CustomEvent) {
+    const cardId = event.detail
+    console.log('Card selected:', cardId)
+    // Handle card selection
+  }
+}
+
+onMounted(() => {
+  if (webComponent.value) {
+    webComponent.value.addEventListener('cardSelected', handleCardSelected)
+  }
+})
+
+onUnmounted(() => {
+  if (webComponent.value) {
+    webComponent.value.removeEventListener('cardSelected', handleCardSelected)
+  }
+})
+</script>
+```
+
+#### Angular
+
+```typescript
+import { Component, ElementRef, OnInit, 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 cardSelectedListener?: (event: Event) => void
+
+  ngAfterViewInit() {
+    this.setupCardSelectedListener()
+  }
+
+  private setupCardSelectedListener() {
+    const element = this.webComponentRef?.nativeElement
+    if (!element) {
+      // Retry if element is not yet available
+      setTimeout(() => this.setupCardSelectedListener(), 100)
+      return
+    }
+
+    this.cardSelectedListener = (event: Event) => {
+      if (event instanceof CustomEvent) {
+        const cardId = event.detail as string
+        console.log('Card selected:', cardId)
+        // Handle card selection
+      }
+    }
+
+    element.addEventListener('cardSelected', this.cardSelectedListener)
+  }
+
+  ngOnDestroy() {
+    const element = this.webComponentRef?.nativeElement
+    if (element && this.cardSelectedListener) {
+      element.removeEventListener('cardSelected', this.cardSelectedListener)
+    }
+  }
+}
+```
+
 ## 🔧 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: