npm package: @qssolutions/ssas-registration-form
Description: Self-Service Assessment Registration Form Library
Author: QSSolutions
Latest version: 1.0.9

# SSAS Registration Form Library

Reusable registration form library for SSAS scenarios, with:

- React component usage (`SSASRegistrationForm`)
- Framework-agnostic Web Component usage (`<ssas-registration-form>`)
- Configurable theme, language, and feature flags
- Built-in API integration for partner lookup, localization, and registration

## Installation

```bash
npm install @qssolutions/ssas-registration-form
```

> **Peer dependencies** — `react` and `react-dom` must be installed in your project:
> ```bash
> npm install react react-dom
> ```

## Quick start (React)

> **Only `partnerGuid` is required.** All other options are optional — if omitted, the form will automatically use partner's default configuration from the Self-service Assessment home page.

```tsx
import React from 'react';
import { SSASRegistrationForm, type FormLibraryConfig } from '@qssolutions/ssas-registration-form';

const config: FormLibraryConfig = {
  partnerGuid: 'your-partner-guid', // Contact QSSolutions to obtain your Guid
  theme: {
    primaryColor: '#00BAE4',
    backgroundColor: '#FCFCFF',
  },
  languageCode: 'en',
  onSuccess: (email) => {
    console.log('Registration successful for', email);
  },
  onError: (error) => {
    console.error('Registration failed:', error);
  },
};

export default function App() {
  return <SSASRegistrationForm config={config} />;
}
```

## Quick start (Web Component)

Use the browser bundle directly — no React installation needed.

> **Only `partnerGuid` is required.** All other options are optional — if omitted, the form will automatically use partner's default configuration from the Self-service Assessment home page.

```html
<script src="https://unpkg.com/@qssolutions/ssas-registration-form/dist/web-component.min.js"></script>
<ssas-registration-form id="registrationForm"></ssas-registration-form>
<script>
  const form = document.getElementById('registrationForm');
  form.config = {
    partnerGuid: 'your-partner-guid', // Contact QSSolutions to obtain your Guid
    languageCode: 'en',
    theme: {
      primaryColor: '#00BAE4',
      backgroundColor: '#FCFCFF',
    },
    onSuccess: (email) => console.log('Success:', email),
    onError: (error) => console.error('Error:', error),
  };

  form.addEventListener('ssas-form-ready', (event) => {
    console.log('Form ready', event.detail);
  });
</script>
```

## Quick start (Angular)

The Web Component bundle includes React internally — no extra dependencies needed.

> **Only `partnerGuid` is required.** All other options are optional — if omitted, the form will automatically use partner's default configuration from the Self-service Assessment home page.

```ts
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}
```

```html
<!-- index.html -->
<script src="https://unpkg.com/@qssolutions/ssas-registration-form/dist/web-component.min.js"></script>
```

```html
<!-- registration.component.html -->
<ssas-registration-form #form></ssas-registration-form>
```

```ts
// registration.component.ts
import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';

@Component({ selector: 'app-registration', templateUrl: './registration.component.html' })
export class RegistrationComponent implements AfterViewInit {
  @ViewChild('form') formEl!: ElementRef;

  ngAfterViewInit() {
    this.formEl.nativeElement.config = {
      partnerGuid: 'your-partner-guid', // Contact QSSolutions to obtain your Guid
      languageCode: 'en',
      onSuccess: (email: string) => console.log('Success:', email),
      onError: (error: string) => console.error('Error:', error),
    };
  }
}
```

## Quick start (Vue)

> **Only `partnerGuid` is required.** All other options are optional — if omitted, the form will automatically use partner's default configuration from the Self-service Assessment home page.

```html
<!-- index.html -->
<script src="https://unpkg.com/@qssolutions/ssas-registration-form/dist/web-component.min.js"></script>
```

```vue
<!-- RegistrationForm.vue -->
<template>
  <ssas-registration-form ref="form" />
</template>

<script setup>
import { onMounted, ref } from 'vue'

const form = ref(null)

onMounted(() => {
  form.value.config = {
    partnerGuid: 'your-partner-guid', // Contact QSSolutions to obtain your Guid
    languageCode: 'en',
    onSuccess: (email) => console.log('Success:', email),
    onError: (error) => console.error('Error:', error),
  }
})
</script>
```

> **Vue note** — add `vue: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('ssas-') } }` to your `vite.config.ts` to suppress unknown element warnings.

## Framework comparison

| | React | Angular / Vue | Vanilla JS |
|---|---|---|---|
| **Install** | `npm install @qssolutions/ssas-registration-form` | CDN script tag | CDN script tag |
| **React required** | Yes (peer dep) | No — bundled in IIFE | No — bundled in IIFE |
| **Entry point** | `dist/index.esm.js` | `dist/web-component.min.js` | `dist/web-component.min.js` |
| **Usage** | `<SSASRegistrationForm config={...} />` | `<ssas-registration-form>` + `.config = {...}` | `<ssas-registration-form>` + `.config = {...}` |

## Configuration

Full `FormLibraryConfig` reference:

```ts
type SupportedLanguage =
  | 'en' | 'fr' | 'de' | 'it' | 'ja' | 'ko' | 'pt' | 'es' | 'nl'
  | 'ar' | 'he' | 'pt-br' | 'tr' | 'id' | 'th' | 'vi' | 'pl';

interface FormLibraryConfig {
  // ── Required ────────────────────────────────────────────────────────────────

  // Unique partner identifier (GUID) used for lookup and domain resolution.
  // Contact QSSolutions to obtain your Guid.
  partnerGuid: string;

  // ── Language ────────────────────────────────────────────────────────────────

  // Override the form language. Falls back to the partner's configured language,
  // then to 'en' if neither is set.
  languageCode?: SupportedLanguage;

  // ── Theme ───────────────────────────────────────────────────────────────────

  theme?: {
    // Accent color used for buttons and interactive elements
    // Default: resolved from partner's ColorWidget setting, falling back to #00BAE4
    primaryColor?: string;

    // Page background color
    // Default: #FCFCFF
    backgroundColor?: string;

    fonts?: {
      // Default: 'Proxima Nova, sans-serif'
      family?: string;
      sizes?: {
        heading?: number;     // Default: 36
        subheading?: number;  // Default: 18
        body?: number;        // Default: 16
      };
    };
  };

  // ── Layout overrides ────────────────────────────────────────────────────────

  // Inline style overrides applied on top of the default FluentUI class styles.
  // topWrapper  — the outer centering/padding container
  // formWrapper — the white card that wraps the form fields
  customStyles?: {
    topWrapper?: React.CSSProperties;
    formWrapper?: React.CSSProperties;
  };

  // ── Callbacks ───────────────────────────────────────────────────────────────

  // Custom async email validation (receives AbortSignal for debounce cancellation)
  onValidateEmail?: (email: string, signal?: AbortSignal) => Promise<boolean>;

  // Called with the registered email on successful submission
  onSuccess?: (email: string) => void;

  // Called with a human-readable error message on failure
  onError?: (error: string) => void;

}
```

### Defaults

| Option | Default |
|---|---|
| `languageCode` | `'en'` (or partner language if set) |
| `theme.backgroundColor` | `'#FCFCFF'` |
| `theme.primaryColor` | Partner's ColorWidget value → `'#00BAE4'` |
| `theme.fonts.family` | `'Proxima Nova, sans-serif'` |
| `theme.fonts.sizes.heading` | `36` |
| `theme.fonts.sizes.subheading` | `18` |
| `theme.fonts.sizes.body` | `16` |

### Custom layout styles

`customStyles` lets you override the two main layout containers with plain CSS properties. These are applied as inline `style` attributes on top of the default class styles:

```ts
customStyles: {
  // outer container — controls padding/alignment around the form card
  topWrapper: { padding: '20px 10%' },

  // the white form card — controls border, radius, width, etc.
  formWrapper: { borderRadius: 0, border: 'none', minWidth: 'unset' },
}
```

## Runtime flow

1. Fetch partner record by `partnerGuid`
2. Resolve partner domain → build service base URL (`https://{partner.domain}`)
3. In parallel: fetch countries, org sizes, industries, localization
4. Render form

**Language resolution order:** `config.languageCode` → `partner.languageCode` → `'en'`

**Primary color resolution order:** `config.theme.primaryColor` → partner ColorWidget setting → `#00BAE4`

## Callbacks

| Callback | Signature | Description |
|---|---|---|
| `onSuccess` | `(email: string) => void` | Fired after successful registration |
| `onError` | `(error: string) => void` | Fired on API or validation error |
| `onValidateEmail` | `(email, signal?) => Promise<boolean>` | Custom async email check |

## Web Component events

| Event | Description |
|---|---|
| `ssas-form-ready` | Fired after the React component mounts inside the custom element |

## Build outputs

Generated in `dist/`:

| File | Format | Description |
|---|---|---|
| `index.js` | CJS | Node / CommonJS consumers |
| `index.esm.js` | ESM | Vite / Webpack 5 / modern bundlers |
| `index.d.ts` | — | TypeScript declarations |
| `web-component.js` | IIFE | Browser bundle (unminified) |
| `web-component.min.js` | IIFE | Browser bundle (minified, CDN) |

## Public exports

```ts
// Components
export { SSASRegistrationForm } from '...'
export { SSASFormElement } from '...'         // web component class

// Config & types
export type { FormLibraryConfig, SupportedLanguage }
export type { IUser, IPartnerModel, IPartnerSetting, IColorWidget,
              ICountry, IOrgSize, IIndustry, ApiResponse }
export { FormModel, FormType }

// Data & utilities
export { FormDataModels }                     // static dropdown option sets
export { ApiService }
export { useFormConfig }

// Style helpers
export { createFormStyles, textFieldStyles, choiceGroupStyles,
         dropdownStyles, comboboxStyles, checkboxStyles }
```

## License

MIT