@visma-swno/customer-onboarding-wizard 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# Customer Onboarding Wizard
+
+A modern Web Component built with Lit for managing customer onboarding workflows.
+
+## Features
+
+- 🚀 Built with Lit and TypeScript
+- 📦 Bundled with Vite
+- ✅ Fully tested with Vitest
+- 🎨 Customizable with CSS variables
+- 🔧 Type-safe with TypeScript strict mode
+- 📱 Responsive and accessible
+
+## Installation
+
+```bash
+npm install @visma-swno/customer-onboarding-wizard
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<vsn-customer-onboarding-wizard 
+  baseUrl="https://api.example.com"
+  taskId="task-12345"
+  customerId="customer-67890"
+  locale="en-GB">
+</vsn-customer-onboarding-wizard>
+```
+
+### With Module Import
+
+```javascript
+import '@visma-swno/customer-onboarding-wizard';
+
+// Or import specific components
+import { CustomerOnboardingWizard } from '@visma-swno/customer-onboarding-wizard';
+```
+
+## Properties
+
+| Property | Type | Default | Required | Description |
+|----------|------|---------|----------|-------------|
+| `baseUrl` | String | `''` | **Yes** | Base URL for API calls (e.g., 'https://api.example.com') |
+| `taskId` | String | `''` | No | Onboarding task ID. Required for saving progress (`save and close`) and completing the wizard; omitting it skips those API calls |
+| `customerId` | String | `''` | **Yes** | Customer ID used to load company information in Step 1 (Company) |
+| `locale` | String | `'en-GB'` | No | Locale for translations (en-GB, en-US, da-DK, fi-FI, nb-NO, nl-NL, sv-SE) |
+| `step` | String | `'welcome'` | No | Initial step to navigate to: `welcome`, `company`, `administrators`, `partner-access`, `complete` |
+| `adminUrl` | String | `''` | No | Absolute `http`/`https` URL to redirect to after task cleanup when the user clicks "Go to Admin" on the completion step. Relative paths and other schemes are ignored and the wizard closes without redirecting. |
+
+## CSS Custom Properties
+
+Customize the appearance using CSS variables:
+
+```css
+vsn-customer-onboarding-wizard {
+  /* Parent application should load font files and set this variable */
+  --font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+### Available CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--font-family` | System fonts fallback | **Required**: Parent application should provide font files and set this variable to avoid duplicate font loading |
+
+### Font Configuration
+
+**Important**: This component does NOT bundle font files. The parent application must:
+
+1. Load font files (e.g., Inter font via `@font-face` or CDN)
+2. Set the `--font-family` CSS variable
+
+```html
+<style>
+  /* Load fonts in parent application */
+  @font-face {
+    font-family: 'Inter';
+    src: url('/fonts/Inter-Regular.woff2') format('woff2');
+    font-weight: 400;
+  }
+  
+  @font-face {
+    font-family: 'Inter';
+    src: url('/fonts/Inter-Medium.woff2') format('woff2');
+    font-weight: 500;
+  }
+  
+  @font-face {
+    font-family: 'Inter';
+    src: url('/fonts/Inter-SemiBold.woff2') format('woff2');
+    font-weight: 600;
+  }
+  
+  /* Set font variable for component */
+  vsn-customer-onboarding-wizard {
+    --font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  }
+</style>
+
+<vsn-customer-onboarding-wizard baseUrl="https://api.example.com"></vsn-customer-onboarding-wizard>
+```
+
+**Font Requirements**:
+- Font weights needed: 400 (Regular), 500 (Medium), 600 (SemiBold)
+- Recommended font: Inter (see `fonts/README.md` for download links)
+
+## Events
+
+The component emits custom events for host application integration:
+
+### `request-token`
+
+**Emitted**: Once during component initialization
+
+**Purpose**: Request OAuth2 access token from host application
+
+**Detail**:
+```typescript
+{
+  callback: (token: string | null) => void
+}
+```
+
+**Usage**:
+```javascript
+document.addEventListener('request-token', async (event) => {
+  const token = sessionStorage.getItem('accessToken');
+  event.detail.callback(token);
+});
+```
+
+### `http-error`
+
+**Emitted**: Only for authentication/authorization errors (401, 403)
+
+**Purpose**: Allow host application to handle auth errors (e.g., refresh token on 401, redirect on 403)
+
+**Note**: All other errors (400, 422, 500, network errors) are **automatically displayed by the component** via an internal error banner. No handling required by host application.
+
+**Detail**:
+```typescript
+{
+  status: number;           // 401 or 403 only
+  statusText: string;       // HTTP status text
+  message: string;          // Error message
+  endpoint: string;         // Failed endpoint
+  method: string;           // HTTP method
+  retry: () => Promise<any>; // Retry callback
+}
+```
+
+**Usage**:
+```javascript
+document.addEventListener('http-error', async (event) => {
+  const { status, retry } = event.detail;
+  
+  if (status === 401) {
+    // Refresh token
+    const newToken = await fetchNewToken();
+    
+    // Update component token
+    document.querySelector('vsn-customer-onboarding-wizard').updateToken(newToken);
+    
+    // Retry failed request
+    await retry();
+  }
+  
+  if (status === 403) {
+    // Handle permission denied
+    window.location.href = '/access-denied';
+  }
+});
+```
+
+### `error-message` (Internal)
+
+**Emitted**: For validation errors, server errors, and network errors
+
+**Purpose**: Component listens to this event internally and displays a translated error banner
+
+**Detail**:
+```typescript
+{
+  status: number;           // HTTP status code or 0 for network errors
+  errorKey: string;         // Translation key (e.g., 'serverError', 'validationError')
+  endpoint: string;         // Failed endpoint
+  method: string;           // HTTP method
+}
+```
+
+**Handled Automatically**: Host application does not need to listen to this event. The component:
+- Displays a red error banner at the top of the wizard
+- Automatically translates error title and message to the user's selected language
+- Supports all 7 languages: da-DK, en-GB, en-US, fi-FI, nb-NO, nl-NL, sv-SE
+- Banner remains visible until the user manually dismisses it by clicking the X button
+- Allows users to report errors to support
+
+## Public Methods
+
+### `updateToken(token: string | null)`
+
+Update the authentication token. Call this method after refreshing the token.
+
+```javascript
+const wizard = document.querySelector('vsn-customer-onboarding-wizard');
+wizard.updateToken('new-access-token');
+```
+
+## Development
+
+See [DEVELOPER-GUIDE.md](./DEVELOPER-GUIDE.md) for development instructions.
+
+## Testing
+
+See [TESTING-SETUP.md](./TESTING-SETUP.md) for testing documentation.
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+
+## License
+
+ISC
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.