@webpros/tsxuserprofilevue 3.5.2 → 3.5.3

package/USAGE_GUIDE.md

@@ -0,0 +1,659 @@
+# TSXUserProfile Component - Usage Guide
+
+## Overview
+
+TSXUserProfile is a Vue 3 web component for managing user profiles and licenses. It can be embedded in any web application and communicates via events.
+
+## Installation
+
+### NPM
+```bash
+npm install @webpros/tsxuserprofilevue
+```
+
+### CDN
+```html
+<script type="module" crossorigin src="https://unpkg.com/@webpros/tsxuserprofilevue/dist/index.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@webpros/tsxuserprofilevue/dist/tsxUserProfile.css">
+```
+
+## Basic Usage
+
+### HTML
+```html
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  current-language="en"
+  user-data='{"email":"user@example.com","firstName":"John","familyName":"Doe","timezone":"America/New_York"}'
+  token="your-auth-token"
+></tsx-user-profile>
+```
+
+### Vue 3
+```vue
+<script setup>
+import '@webpros/tsxuserprofilevue'
+
+const userData = {
+  email: 'user@example.com',
+  firstName: 'John',
+  familyName: 'Doe',
+  timezone: 'America/New_York',
+  gravatar: 'https://www.gravatar.com/avatar/...',
+  nixstatsId: '12345',
+  threeSixtyId: '67890'
+}
+</script>
+
+<template>
+  <tsx-user-profile
+    base-api-url="https://api.example.com"
+    :user-data="JSON.stringify(userData)"
+    current-language="en"
+    token="your-auth-token"
+  />
+</template>
+```
+
+### React
+```jsx
+import '@webpros/tsxuserprofilevue'
+
+function UserProfile() {
+  const userData = {
+    email: 'user@example.com',
+    firstName: 'John',
+    familyName: 'Doe',
+    timezone: 'America/New_York'
+  }
+
+  return (
+    <tsx-user-profile
+      base-api-url="https://api.example.com"
+      user-data={JSON.stringify(userData)}
+      current-language="en"
+      token="your-auth-token"
+    />
+  )
+}
+```
+
+## Component Props
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `base-api-url` | String | **Required**. Base URL for API calls |
+
+### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `current-language` | String | `'en'` | Language code: `'de'`, `'en'`, `'fr'`, `'es'`, `'it'`, `'ja'`, `'ru'`, `'pt'` |
+| `user-data` | String (JSON) | `'{}'` | User information as JSON string (see User Data Structure) |
+| `view` | String | `'profile'` | View type: `'profile'` or `'license'` |
+| `token` | String | `''` | Authentication token for API requests |
+| `read-only` | Boolean/String | `false` | Makes the component read-only (no editing) |
+| `off-canvas` | Boolean | `false` | Display as off-canvas sidebar instead of inline |
+| `open-canvas` | Boolean | `false` | Initial state of off-canvas (open/closed) |
+| `partner-type` | String | `''` | Partner type: `'standaloneRetail'`, `'standalonePartner'`, `'whitelabel'`, `'platform'`, `'partner'` |
+| `is-license-partner` | Boolean | `false` | Whether user is a license partner |
+| `extra-inactive-fields` | String (JSON) | `'[]'` | Additional fields to hide (JSON array string) |
+| `locale-saving-url` | String | `''` | URL endpoint for saving language preferences |
+| `override-base-api-url` | String | `''` | Override the base API URL for specific requests |
+| `complete-upsell-url` | String | `''` | URL for license upsell/purchase flow |
+
+## User Data Structure
+
+The `user-data` prop accepts a JSON string with the following structure:
+
+```typescript
+interface IProfileUser {
+  // Basic Information
+  email?: string                // User's email address
+  firstName?: string            // User's first name
+  familyName?: string           // User's last name
+  name?: string                 // Full name (alternative to firstName/familyName)
+  nickname?: string             // User's nickname
+  
+  // Avatar
+  gravatar?: string             // Gravatar URL or email hash
+  
+  // System Information
+  timezone?: string | null      // IANA timezone (e.g., 'America/New_York')
+  nixstatsId?: string          // Nixstats user ID
+  threeSixtyId?: string        // 360 Monitoring user ID
+  
+  // Authentication
+  sessionToken?: string         // Session token
+  isOauthUser?: boolean        // Whether user authenticated via OAuth
+  
+  // Permissions
+  isDeletable?: boolean        // Whether account can be deleted
+}
+```
+
+### Example User Data
+
+```javascript
+const userData = {
+  email: 'john.doe@example.com',
+  firstName: 'John',
+  familyName: 'Doe',
+  nickname: 'johnd',
+  gravatar: 'https://www.gravatar.com/avatar/1e45f0572fb68149199a0acb56ccc3dc',
+  timezone: 'Europe/Berlin',
+  nixstatsId: '12345',
+  threeSixtyId: '67890',
+  isOauthUser: false,
+  isDeletable: true
+}
+
+// Pass as JSON string
+<tsx-user-profile user-data={JSON.stringify(userData)} />
+```
+
+### Important Notes
+
+- **All fields are optional**
+- If `timezone` is not provided, the component will use the browser's timezone
+- If `gravatar` is an email, it will be converted to a Gravatar URL automatically
+- If `isDeletable` is `false`, the "Remove Account" option will be hidden
+
+## Inactive Fields Configuration
+
+You can hide specific sections of the profile using the `extra-inactive-fields` prop and automatic hiding based on `partner-type`.
+
+### Available Fields to Hide
+
+- `naming` - Name editing section
+- `ids` - User IDs display (nixstatsId, threeSixtyId)
+- `password` - Password change section
+- `language` - Language selector
+- `timezone` - Timezone selector
+- `consent` - Consent/privacy settings
+- `dnt` - Do Not Track settings
+- `removeAccount` - Account deletion option
+- `comparePlansLink` - Compare plans link (license view)
+
+### Automatic Hiding by Partner Type
+
+Different partner types automatically hide certain fields:
+
+```typescript
+// Partner Type Configurations
+{
+  'standaloneRetail': [],                              // No fields hidden
+  'standalonePartner': ['consent', 'comparePlansLink'],
+  'whitelabel': ['naming', 'password', 'consent'],
+  'platform': ['naming', 'password', 'consent'],
+  'partner': ['consent', 'comparePlansLink']
+}
+```
+
+### Manual Configuration
+
+Use `extra-inactive-fields` to hide additional fields:
+
+```html
+<!-- Hide password and timezone fields -->
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  user-data='{"email":"user@example.com"}'
+  extra-inactive-fields='["password", "timezone"]'
+/>
+```
+
+### Combined Example
+
+```html
+<!-- Partner type hides some fields, extra-inactive-fields adds more -->
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  partner-type="whitelabel"
+  extra-inactive-fields='["language", "ids"]'
+/>
+<!-- This will hide: naming, password, consent (from whitelabel) + language, ids (from extra) -->
+```
+
+## Event Handling
+
+The component uses [MITT](https://github.com/developit/mitt) for event communication. All user interactions emit events that you can listen to.
+
+### Setting Up Event Listeners
+
+```javascript
+// Listen to all TSXUserProfile events
+window.mitt.on('tsxUserProfile', (payload) => {
+  console.log('Event received:', payload)
+
+  switch(payload.action) {
+    case 'updateTimezone':
+      console.log('Timezone changed to:', payload.data)
+      // Save to your backend
+      break
+    case 'updateName':
+      console.log('Name changed:', payload.data)
+      break
+    case 'updatePassword':
+      console.log('Password change requested')
+      break
+    // ... handle other events
+  }
+})
+```
+
+### Available Events
+
+| Event Action | Payload Data | Description |
+|-------------|--------------|-------------|
+| `updateTimezone` | `string` | User changed timezone |
+| `updateName` | `{firstName: string, familyName: string}` | User updated name |
+| `updatePassword` | `{oldPassword: string, newPassword: string}` | Password change request |
+| `updateLanguage` | `string` | Language changed |
+| `deleteAccount` | `{}` | Account deletion requested |
+| `updateConsent` | `boolean` | Consent settings changed |
+| `updateDnt` | `boolean` | Do Not Track setting changed |
+
+### Event Example
+
+```javascript
+// Initialize MITT if not already done
+window.mitt = window.mitt || mitt()
+
+// Listen for timezone changes
+window.mitt.on('tsxUserProfile', (payload) => {
+  if (payload.action === 'updateTimezone') {
+    // Send to your API
+    fetch('/api/user/timezone', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ timezone: payload.data })
+    })
+  }
+})
+```
+
+## Styling and Theming
+
+The component uses CSS custom properties (variables) for theming. Define these in your stylesheet:
+
+```css
+:root {
+  /* Base Colors */
+  --tsxup-brightest: #ffffff;
+  --tsxup-brightest-darker: #e5e7eb;
+  --tsxup-darkest: #111827;
+  --tsxup-darkest-light: #4b5563;
+
+  /* Signal Colors */
+  --tsxup-signal-success: #4CA154;
+  --tsxup-signal-error: #b73737;
+
+  /* Brand Colors */
+  --tsxup-primary: #1E40AF;
+  --tsxup-primary-light: #668bca;
+
+  /* Text */
+  --tsxup-text: var(--tsxup-darkest);
+  --tsxup-text-lighter: var(--tsxup-darkest-light);
+  --tsxup-headline: var(--tsxup-darkest);
+
+  /* Buttons */
+  --tsxUp-button-color: var(--tsxup-brightest);
+  --tsxUp-button-bg: var(--tsxup-primary);
+  --tsxUp-button-color-hover: var(--tsxup-brightest);
+  --tsxUp-button-bg-hover: var(--tsxup-primary-light);
+
+  /* Select Fields */
+  --tsxUp-selectField-border: var(--tsxup-brightest-darker);
+  --tsxUp-selectField-background: var(--tsxup-brightest);
+  --tsxUp-selectField-backgroundHover: var(--tsxup-brightest);
+  --tsxUp-selectField-backgroundDisabled: var(--tsxup-brightest-darker);
+  --tsxUp-selectField-color: var(--tsxup-darkest);
+  --tsxUp-selectField-selectedBackground: var(--tsxup-primary-light);
+  --tsxUp-selectField-selectedColor: var(--tsxup-brightest);
+}
+```
+
+### Dark Mode Example
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    --tsxup-brightest: #1f2937;
+    --tsxup-brightest-darker: #374151;
+    --tsxup-darkest: #f9fafb;
+    --tsxup-darkest-light: #d1d5db;
+    --tsxup-text: var(--tsxup-darkest);
+    --tsxup-headline: var(--tsxup-darkest);
+  }
+}
+```
+
+## Advanced Usage Examples
+
+### Off-Canvas Sidebar Mode
+
+Display the profile as a sliding sidebar panel:
+
+```html
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  user-data='{"email":"user@example.com","firstName":"John"}'
+  off-canvas="true"
+  open-canvas="false"
+  view="profile"
+  token="your-token"
+/>
+```
+
+Control the canvas programmatically:
+
+```javascript
+// Open the canvas
+window.mitt.emit('openCanvas', { view: 'profile' })
+
+// Close the canvas
+window.mitt.emit('closeCanvas')
+
+// Switch to license view
+window.mitt.emit('openCanvas', { view: 'license' })
+```
+
+### License Management View
+
+Display license and subscription information:
+
+```html
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  view="license"
+  read-only="false"
+  complete-upsell-url="https://example.com/upsell"
+  token="your-token"
+/>
+```
+
+### Read-Only Profile
+
+Display user information without editing capabilities:
+
+```html
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  user-data='{"email":"user@example.com","firstName":"John","familyName":"Doe"}'
+  read-only="true"
+  extra-inactive-fields='["password", "removeAccount"]'
+/>
+```
+
+### Multi-Language Support
+
+```html
+<!-- German -->
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  current-language="de"
+  user-data='{"email":"benutzer@beispiel.de"}'
+/>
+
+<!-- French -->
+<tsx-user-profile
+  base-api-url="https://api.example.com"
+  current-language="fr"
+  user-data='{"email":"utilisateur@exemple.fr"}'
+/>
+```
+
+Supported languages: `de`, `en`, `fr`, `es`, `it`, `ja`, `ru`, `pt`
+
+### Complete Integration Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>User Profile</title>
+  <script type="module" src="https://unpkg.com/@webpros/tsxuserprofilevue/dist/index.js"></script>
+  <link rel="stylesheet" href="https://unpkg.com/@webpros/tsxuserprofilevue/dist/tsxUserProfile.css">
+  <style>
+    :root {
+      --tsxup-primary: #0066cc;
+      --tsxup-primary-light: #3399ff;
+    }
+    .profile-container {
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+  </style>
+</head>
+<body>
+  <div class="profile-container">
+    <h1>My Profile</h1>
+    <tsx-user-profile
+      id="userProfile"
+      base-api-url="https://api.example.com"
+      current-language="en"
+      token="your-auth-token"
+    />
+  </div>
+
+  <script type="module">
+    import mitt from 'https://unpkg.com/mitt/dist/mitt.mjs'
+
+    // Initialize MITT
+    window.mitt = window.mitt || mitt()
+
+    // Fetch user data from your API
+    async function loadUserData() {
+      const response = await fetch('https://api.example.com/user/profile', {
+        headers: { 'Authorization': 'Bearer your-auth-token' }
+      })
+      const userData = await response.json()
+
+      // Set user data on component
+      const profile = document.getElementById('userProfile')
+      profile.setAttribute('user-data', JSON.stringify(userData))
+    }
+
+    // Handle events
+    window.mitt.on('tsxUserProfile', async (payload) => {
+      console.log('Event:', payload)
+
+      // Save changes to your API
+      if (payload.action === 'updateTimezone') {
+        await fetch('https://api.example.com/user/timezone', {
+          method: 'POST',
+          headers: {
+            'Authorization': 'Bearer your-auth-token',
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({ timezone: payload.data })
+        })
+      }
+
+      if (payload.action === 'updateName') {
+        await fetch('https://api.example.com/user/name', {
+          method: 'POST',
+          headers: {
+            'Authorization': 'Bearer your-auth-token',
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify(payload.data)
+        })
+      }
+    })
+
+    // Load user data on page load
+    loadUserData()
+  </script>
+</body>
+</html>
+```
+
+## Framework-Specific Integration
+
+### Vue 3 / Nuxt 3
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+import '@webpros/tsxuserprofilevue'
+import mitt from 'mitt'
+
+// Initialize MITT
+if (!window.mitt) {
+  window.mitt = mitt()
+}
+
+const userData = ref({
+  email: 'user@example.com',
+  firstName: 'John',
+  familyName: 'Doe',
+  timezone: 'America/New_York'
+})
+
+onMounted(() => {
+  window.mitt.on('tsxUserProfile', (payload) => {
+    console.log('Profile event:', payload)
+    // Handle events
+  })
+})
+</script>
+
+<template>
+  <div class="profile-wrapper">
+    <tsx-user-profile
+      base-api-url="https://api.example.com"
+      :user-data="JSON.stringify(userData)"
+      current-language="en"
+      token="your-token"
+    />
+  </div>
+</template>
+```
+
+### React / Next.js
+
+```jsx
+import { useEffect, useRef } from 'react'
+import '@webpros/tsxuserprofilevue'
+import mitt from 'mitt'
+
+export default function UserProfile() {
+  const userData = {
+    email: 'user@example.com',
+    firstName: 'John',
+    familyName: 'Doe',
+    timezone: 'America/New_York'
+  }
+
+  useEffect(() => {
+    // Initialize MITT
+    if (!window.mitt) {
+      window.mitt = mitt()
+    }
+
+    // Event listener
+    const handleEvent = (payload) => {
+      console.log('Profile event:', payload)
+      // Handle events
+    }
+
+    window.mitt.on('tsxUserProfile', handleEvent)
+
+    return () => {
+      window.mitt.off('tsxUserProfile', handleEvent)
+    }
+  }, [])
+
+  return (
+    <div className="profile-wrapper">
+      <tsx-user-profile
+        base-api-url="https://api.example.com"
+        user-data={JSON.stringify(userData)}
+        current-language="en"
+        token="your-token"
+      />
+    </div>
+  )
+}
+```
+
+## Troubleshooting
+
+### Component Not Rendering
+
+1. **Check if the script is loaded**: Verify the component script is included
+2. **Check user-data format**: Must be a valid JSON string
+3. **Check base-api-url**: This prop is required
+
+### Events Not Firing
+
+1. **Initialize MITT**: Ensure `window.mitt` is initialized before the component loads
+2. **Check event listener**: Make sure you're listening to `'tsxUserProfile'` events
+
+### Styling Issues
+
+1. **CSS Variables**: Ensure CSS variables are defined in your stylesheet
+2. **CSS Import**: Import the component's CSS file
+3. **Wrapper Styling**: Add custom styling via a wrapper div
+
+### TypeScript Support
+
+```typescript
+// Type definitions for user data
+interface IProfileUser {
+  email?: string
+  firstName?: string
+  familyName?: string
+  name?: string
+  nickname?: string
+  gravatar?: string
+  timezone?: string | null
+  nixstatsId?: string
+  threeSixtyId?: string
+  sessionToken?: string
+  isOauthUser?: boolean
+  isDeletable?: boolean
+}
+
+// Event payload type
+interface TSXUserProfileEvent {
+  action: string
+  data: any
+}
+
+// Usage
+const userData: IProfileUser = {
+  email: 'user@example.com',
+  firstName: 'John',
+  familyName: 'Doe'
+}
+```
+
+## API Requirements
+
+The component expects certain API endpoints to be available at the `base-api-url`:
+
+- `GET /user/profile` - Fetch user profile data
+- `POST /user/timezone` - Update timezone
+- `POST /user/name` - Update name
+- `POST /user/password` - Change password
+- `GET /licenses` - Fetch license information (for license view)
+- `GET /plans` - Fetch available subscription plans
+
+Ensure your backend implements these endpoints or use the event system to handle data persistence.
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit the [GitHub repository](https://github.com/leankoala-gmbh/tsxuserprofilevue).
+