@mapvx/website-component 0.5.1 → 0.6.0

package/README.md

@@ -52,29 +52,95 @@ import '@mapvx/website-component/dist/browser/styles.css'
 ```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" />
 }
 ```
 
+```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'
-import '@mapvx/website-component/dist/browser/styles.css'
+```
+
+```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
+<!-- Web Component Scripts -->
+<script src="website-component/main.js" defer></script>
+
+<!-- Web Component Styles -->
+<link rel="stylesheet" href="website-component/styles.css" />
+```
+
+**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 angular.json or import in main.ts
+// In your main.ts - Import the JavaScript
 import '@mapvx/website-component/dist/browser/main.js'
-import '@mapvx/website-component/dist/browser/styles.css'
 ```
 
+```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
+
 ### Helper Package (SSR Support)
 
 For Server-Side Rendering (SSR) applications that need to preload initial data on the server:
@@ -180,6 +246,7 @@ The web component accepts the following input properties to customize its behavi
 | `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                                                   |
 
 ### Input Usage Examples
 
@@ -198,6 +265,7 @@ The web component accepts the following input properties to customize its behavi
   default-to-map="true"
   show-category-filters="false"
   show-city-filter="true"
+  hide-deals="true"
 >
 </mapvx-website>
 ```
@@ -216,19 +284,64 @@ npm install @mapvx/website-component-helpers
 
 #### 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() {
-  // Execute on the server
-  const initialData = await prepareInitialData(process.env.MAPVX_API_KEY!);
+  const initialData = await prepareInitialData(process.env.NEXT_PUBLIC_MAPVX_API_KEY || '');
 
   return (
     <div>
-      <h1>My App</h1>
+      <Script src='/mapvx-website/bundle.js' />
       <mapvx-website
-        api-key={process.env.MAPVX_API_KEY}
+        api-key={process.env.NEXT_PUBLIC_MAPVX_API_KEY}
+        institution-id={process.env.NEXT_PUBLIC_MAPVX_INSTITUTION_ID}
         initial-data={initialData}
         default-to-map="true"
       />
@@ -237,36 +350,18 @@ export default async function HomePage() {
 }
 ```
 
-#### Next.js (Pages Router)
+**5. Set environment variables in `.env.local`:**
 
-```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!);
+```bash
+NEXT_PUBLIC_MAPVX_API_KEY=your-api-key-here
+NEXT_PUBLIC_MAPVX_INSTITUTION_ID=your-institution-id
+```
 
-  return {
-    props: {
-      initialData,
-    },
-  };
-};
+**6. Run the copy script before building:**
 
-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>
-  );
-}
+```bash
+npm run copy-bundle
+npm run build
 ```
 
 #### Nuxt.js
@@ -433,6 +528,36 @@ function App() {
 - The web component will automatically pick up these custom colors
 - Use valid CSS color values (hex, rgb, hsl, etc.)
 
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### `SyntaxError: Unexpected token '<'` in Angular
+
+**Problem**: Angular returns HTML instead of JavaScript files from `node_modules`.
+
+**Solution**: Configure assets in `angular.json` as shown in the Angular Configuration section above.
+
+#### Slow Loading (>10 seconds)
+
+**Problem**: Large bundle size or incorrect asset serving.
+
+**Solutions**:
+
+- Use the recommended Angular assets configuration
+- Ensure files are served as static assets, not through routing
+- Check network tab in DevTools for 404 errors
+
+#### Web Component Not Loading
+
+**Problem**: Scripts not loading or component not registering.
+
+**Solutions**:
+
+- Verify file paths are correct
+- Check browser console for errors
+- Ensure `defer` attribute is used for script tags
+
 ## 🏠 Homepage
 
 Visit [MapVX](https://mapvx.com) for more information.