@mapvx/website-component 0.5.0

package/LICENSE

@@ -0,0 +1,17 @@
+PRIVATE AND CONFIDENTIAL
+
+Copyright (c) 2025
+
+All rights reserved.
+
+This software and its documentation are private and confidential. 
+No part of this software may be reproduced, distributed, or transmitted in any form or by any means, 
+including photocopying, recording, or other electronic or mechanical methods, without the prior written 
+permission of the copyright holder.
+
+The receipt or possession of the source code and/or related information does not convey or imply any right 
+to use, reproduce, disclose or distribute its contents, or to manufacture, use, or sell anything that it 
+may describe.
+
+Any unauthorized use, reproduction, or distribution of this software or its contents is strictly prohibited 
+and may result in severe civil and criminal penalties. 

package/README.md

@@ -0,0 +1,438 @@
+# 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
+
+### Via NPM
+
+```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
+<!-- Include the component files -->
+<script src="node_modules/@mapvx/website-component/dist/browser/main.js"></script>
+<link rel="stylesheet" href="node_modules/@mapvx/website-component/dist/browser/styles.css" />
+```
+
+**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'
+import '@mapvx/website-component/dist/browser/styles.css'
+
+function App() {
+  return <mapvx-website api-key="your-api-key-here" />
+}
+```
+
+**Vue:**
+
+```javascript
+// In your main.js
+import '@mapvx/website-component/dist/browser/main.js'
+import '@mapvx/website-component/dist/browser/styles.css'
+```
+
+**Angular:**
+
+```typescript
+// In your angular.json or import in main.ts
+import '@mapvx/website-component/dist/browser/main.js'
+import '@mapvx/website-component/dist/browser/styles.css'
+```
+
+### Helper Package (SSR Support)
+
+For Server-Side Rendering (SSR) applications that need to preload initial data on the server:
+
+```bash
+npm install @mapvx/website-component-helpers
+```
+
+### Via CDN (unpkg)
+
+```html
+<!-- Include the component files -->
+<script src="https://unpkg.com/@mapvx/website-component@latest/dist/browser/main.js"></script>
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/@mapvx/website-component@latest/dist/browser/styles.css"
+/>
+```
+
+## 🎯 Usage
+
+### Basic Usage
+
+```html
+<!-- Basic implementation with required API key -->
+<mapvx-website api-key="your-api-key-here"></mapvx-website>
+```
+
+### Advanced Usage with Configuration
+
+```html
+<!-- With all available options -->
+<mapvx-website
+  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"
+>
+</mapvx-website>
+```
+
+### Framework Integration
+
+#### React
+
+```jsx
+function App() {
+  return (
+    <mapvx-website
+      api-key="your-api-key-here"
+      default-to-map="true"
+      show-category-filters="false"
+    />
+  )
+}
+```
+
+#### Vue
+
+```vue
+<template>
+  <mapvx-website
+    api-key="your-api-key-here"
+    :default-to-map="true"
+    :show-category-filters="false"
+  />
+</template>
+```
+
+#### Angular
+
+```typescript
+// In your component
+@Component({
+  template: `
+    <mapvx-website
+      [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                                                      |
+
+### Input Usage Examples
+
+#### Required Properties Only
+
+```html
+<mapvx-website api-key="your-api-key-here"></mapvx-website>
+```
+
+#### With Optional Configuration
+
+```html
+<mapvx-website
+  api-key="your-api-key-here"
+  institution-id="institution-123"
+  default-to-map="true"
+  show-category-filters="false"
+  show-city-filter="true"
+>
+</mapvx-website>
+```
+
+## 🔧 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:
+
+### Installation
+
+```bash
+npm install @mapvx/website-component-helpers
+```
+
+### Server-Side Usage
+
+#### Next.js (App Router)
+
+```typescript
+// app/page.tsx
+import { prepareInitialData } from '@mapvx/website-component-helpers';
+
+export default async function HomePage() {
+  // Execute on the server
+  const initialData = await prepareInitialData(process.env.MAPVX_API_KEY!);
+
+  return (
+    <div>
+      <h1>My App</h1>
+      <mapvx-website
+        api-key={process.env.MAPVX_API_KEY}
+        initial-data={initialData}
+        default-to-map="true"
+      />
+    </div>
+  );
+}
+```
+
+#### Next.js (Pages Router)
+
+```typescript
+// pages/index.tsx
+import { GetServerSideProps } from 'next';
+import { prepareInitialData } from '@mapvx/website-component-helpers';
+
+export const getServerSideProps: GetServerSideProps = async () => {
+  // Execute on the server
+  const initialData = await prepareInitialData(process.env.MAPVX_API_KEY!);
+
+  return {
+    props: {
+      initialData,
+    },
+  };
+};
+
+export default function HomePage({ initialData }: { initialData: string }) {
+  return (
+    <div>
+      <h1>My App</h1>
+      <mapvx-website
+        api-key={process.env.MAPVX_API_KEY}
+        initial-data={initialData}
+        default-to-map="true"
+      />
+    </div>
+  );
+}
+```
+
+#### Nuxt.js
+
+```vue
+<!-- pages/index.vue -->
+<template>
+  <div>
+    <h1>My App</h1>
+    <mapvx-website :api-key="apiKey" :initial-data="initialData" default-to-map="true" />
+  </div>
+</template>
+
+<script setup>
+import { prepareInitialData } from '@mapvx/website-component-helpers'
+
+// Server-side data fetching
+const { data: initialData } = await useAsyncData('mapvx-data', async () => {
+  return await prepareInitialData(process.env.MAPVX_API_KEY)
+})
+
+const apiKey = process.env.MAPVX_API_KEY
+</script>
+```
+
+#### SvelteKit
+
+```typescript
+// src/routes/+page.server.ts
+import { prepareInitialData } from '@mapvx/website-component-helpers'
+import type { PageServerLoad } from './$types'
+
+export const load: PageServerLoad = async () => {
+  // Execute on the server
+  const initialData = await prepareInitialData(process.env.MAPVX_API_KEY!)
+
+  return {
+    initialData,
+  }
+}
+```
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  import type { PageData } from './$types';
+
+  export let data: PageData;
+</script>
+
+<div>
+  <h1>My App</h1>
+  <mapvx-website
+    api-key={process.env.MAPVX_API_KEY}
+    initial-data={data.initialData}
+    default-to-map="true"
+  />
+</div>
+```
+
+### What `prepareInitialData` does
+
+The `prepareInitialData` function is specifically designed for SSR applications:
+
+- **Server-side execution**: Must be called on the server, not in the browser
+- **Data fetching**: Fetches available places and institutions from the API
+- **Performance optimization**: Preloads data on the server to avoid client-side API calls
+- **SEO benefits**: Ensures data is available during server-side rendering
+- **Returns**: JSON string with combined places and institutions data
+
+### Important Notes
+
+⚠️ **SSR Only**: This function should only be used in server-side rendering contexts. For client-side applications, the web component will fetch data automatically when needed.
+
+## 🎨 Customization
+
+### Custom Colors
+
+The web component supports custom color theming through CSS custom properties. You can override the default colors by defining CSS variables in your application's root:
+
+```css
+:root {
+  --mapvx-secondary-orange: #b41500;
+  --mapvx-secondary-blue: #053a96;
+}
+```
+
+#### Example Implementation
+
+**HTML with inline styles:**
+
+```html
+<style>
+  :root {
+    --mapvx-secondary-orange: #ff6b35;
+    --mapvx-secondary-blue: #1e3a8a;
+  }
+</style>
+
+<mapvx-website api-key="your-api-key-here"></mapvx-website>
+```
+
+**CSS file:**
+
+```css
+/* styles.css */
+:root {
+  --mapvx-secondary-orange: #e74c3c;
+  --mapvx-secondary-blue: #3498db;
+}
+```
+
+**Framework-specific examples:**
+
+**React:**
+
+```jsx
+// In your CSS file or styled-components
+:root {
+  --mapvx-secondary-orange: #ff6b35;
+  --mapvx-secondary-blue: #1e3a8a;
+}
+
+function App() {
+  return <mapvx-website api-key="your-api-key-here" />;
+}
+```
+
+**Vue:**
+
+```vue
+<template>
+  <mapvx-website api-key="your-api-key-here" />
+</template>
+
+<style>
+:root {
+  --mapvx-secondary-orange: #ff6b35;
+  --mapvx-secondary-blue: #1e3a8a;
+}
+</style>
+```
+
+**Angular:**
+
+```scss
+// styles.scss
+:root {
+  --mapvx-secondary-orange: #ff6b35;
+  --mapvx-secondary-blue: #1e3a8a;
+}
+```
+
+### Available Color Variables
+
+| Variable                   | Default Value | Description                                |
+| -------------------------- | ------------- | ------------------------------------------ |
+| `--mapvx-secondary-orange` | `#EE5845`     | Secondary orange color used in UI elements |
+| `--mapvx-secondary-blue`   | `#2C57A0`     | Secondary blue color used in UI elements   |
+
+### Notes
+
+- Colors are applied globally when defined in `:root`
+- The web component will automatically pick up these custom colors
+- Use valid CSS color values (hex, rgb, hsl, etc.)
+
+## 🏠 Homepage
+
+Visit [MapVX](https://mapvx.com) for more information.