@vergelijkdirect/comparison-forms 2.0.0-rc.8 → 2.0.0

package/README.md

@@ -1,136 +1,172 @@
-# Vergelijkdirect comparison forms
+# @vergelijkdirect/comparison-forms — Vue 3 library (`2.x`)
 
-This project designed to provide single source of true for insurances forms. It supports two mode: standalone and embedded. Standalone designed as SSR application, with its own server and clients sides. Can be implemented due i-frame anywhere. Embedded version using node dependency comparison-forms, that can be downloaded from NPM.
+Headless comparison forms for vergelijkdirect, consumable two ways:
 
-## How to install
+- **Vue 3 hosts** — npm package export `@vergelijkdirect/comparison-forms/vue`
+- **Vue 2.7 / non-Vue hosts** — self-contained Web Component `@vergelijkdirect/comparison-forms/wc`
 
-### Standalone mode
+The library is the whole of `src/`. The legacy Vue 2.7 app it replaced was migrated form by form
+and has since been removed — its `<embedded-comparison-forms>` plugin API does not exist here
+(see the migration table below). If you still need `1.x`, it lives on the **`v1`** branch, in
+maintenance mode: bugfixes and security only, no new forms or features.
 
-1.Insert i-frame tag anywhere in your project, with next data:
+## Install & prerequisites
 
-|   Queryparams   |                                            Meaning                                             |               Example               |
-| :-------------: | :--------------------------------------------------------------------------------------------: | :---------------------------------: |
-|  Page address   |                                  Corresponds to type of form                                   |             /motor-form             |
-|      link       |              Indicate address, where user should be redirected after forms submit              |  &link=verzekeringen/results-page   |     |
-|      title      |                                      Specify forms title                                       | &title=Motorverzekering vergelijken |
-| full-form-width | Specify, should form has 100% width of parent component, or should has strong standard borders |        &full-form-width=true        |
+The ITC client (`@vergelijkdirect/insurance-transmission-client`) is **your** peer dependency:
+the library never creates or exports it for Vue hosts. You install and initialize it yourself,
+once, before mounting any form — the library's forms/flow lazily pull the already-initialized
+services (see `preview/main.ts` for a working bootstrap example).
 
-Example: <iframe src="localhost:3000/motor-form?link=http://google.com"&has-new-design=1&title=Motorverzekering vergelijken&full-form-width=true"></iframe>
+```bash
+npm i @vergelijkdirect/comparison-forms
+```
 
-### Embedded mode
+Load the styles once per page:
 
-1.Install package @vergelijkdirect/comparison-forms (Strongly recommend to use exact version of package)
+```ts
+import '@vergelijkdirect/comparison-forms/vue/styles';
+```
 
+## Usage
+
+### 1. Drop-in (recommended) — the form handles everything
+
+```vue
+<script setup>
+import { ComparisonFormFlow } from '@vergelijkdirect/comparison-forms/vue';
+// ITC must already be initialized (see "Install & prerequisites" above)
+</script>
+
+<template>
+    <ComparisonFormFlow
+        form="bike"
+        link="https://www.vergelijkdirect.com/fietsverzekering/"
+        layout="horizontal"
+        @submitted="(url) => track(url)"
+        @error="showFallbackLead"
+    />
+</template>
 ```
-npm i @vergelijkdirect/comparison-forms --save-exact
+
+Fills the form → creates the comparison via ITC → appends the comparison route (`#/<id>/…`)
+to the base `link` → redirects.
+On failure it emits `error(error, payload)` and does nothing else — the fallback-lead UI is
+yours to wire, with the user's data available in `payload.user`.
+
+### 2. Headless — you own the submit
+
+```vue
+<script setup>
+import {
+    BikeForm,
+    bikePresenter,
+    useComparisonSubmit,
+} from '@vergelijkdirect/comparison-forms/vue';
+
+const { submit, isSubmitting } = useComparisonSubmit({
+    link: 'https://…/fietsverzekering/funnel/',
+    onError: showFallbackLead,
+});
+</script>
+
+<template>
+    <BikeForm @submitted="(data) => submit(bikePresenter(data))" />
+</template>
 ```
 
-2.Ensure, that version of Vue is >2.7.14, and version of Node is 20.6.1
-3.In entry js file (for example vd-partner.ts in partner-front) import comparisonFormsPlugin
+Or skip the flow entirely (result-page edit, custom persistence):
 
+```vue
+<BikeForm :initial-data="savedBike" @submitted="updateMyComparison" />
 ```
-import comparisonFormsPlugin from '@vergelijkdirect/comparison-forms';
-```
-
-4.Make Vue use plugin
 
+`initialData` is read once on mount — remount with `:key` when it arrives async.
+
+### 3. Web Component (Vue 2.7 / plain HTML hosts)
+
+```html
+<script
+    type="module"
+    src=".../comparison-forms/wc"
+></script>
+<link
+    rel="stylesheet"
+    href=".../comparison-forms/wc/styles"
+/>
+
+<vd-comparison-form
+    form="bike"
+    link="https://…/fietsverzekering/funnel/"
+    api-url="https://api.vergelijkdirect.com"
+></vd-comparison-form>
+
+<script>
+    document
+        .querySelector('vd-comparison-form')
+        .addEventListener('error', (e) => console.error(e.detail[0]));
+</script>
 ```
-Vue.use(comparisonFormsPlugin);
+
+The element initializes the shared ITC client from the url attributes — it is its own consumer,
+no host-side setup needed. Events are native `CustomEvent`s (`submitted`, `error`) with the
+emit arguments in `detail` — `error` carries the error in `detail[0]` and, when the failure
+happened on submit, the `ComparisonPayload` in `detail[1]` (client-init failures have no
+payload). `initial-data` accepts either a JSON-string attribute (`initial-data='{"kind":1}'`, for
+plain HTML) or an object set as a DOM property (`el.initialData = {…}`); other complex props are
+DOM properties only.
+
+## Migrating from the 1.x `<embedded-comparison-forms>` events
+
+The 2.x event contract is a deliberate break. How each legacy event maps:
+
+| Legacy (1.x)                                            | When it fired                                                       | 2.x equivalent                                                                                                                                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@change`                                               | result/coverage page — "update, don't create"                       | headless `@submitted` with typed form data; run it through the form's presenter and `payload.user` carries the fields hosts wrote back (`zipCode`, `birthdate`, `houseNumber`, `houseNumberAddition`, `street`, `city`) |
+| `@emit-event` `{ event: 'open-quotation-modal', data }` | comparison create failed → fallback lead                            | `@error` — emits `(error, payload)`; build the fallback lead from `payload.user`. ITC rejects an unknown postcode the same way as a transport failure — check `error instanceof Error` if you need to tell them apart   |
+| `@emit-event` (no arguments)                            | submitted with unchanged data → "close me"                          | none by design — the form always emits `submitted`; the host owns update semantics, so compare the submitted data with what it passed as `initial-data` (e.g. lodash `isEqual`) and skip the update                     |
+| `@redirect-page`                                        | never reached hosts — the 1.x embedded shell consumed it internally | `submitted(url)` fires before the redirect; the `redirect` prop overrides navigation                                                                                                                                    |
+
+## Development
+
+```bash
+npm run dev            # live sandbox (preview/) — demos for every component and form
+npm run test:unit      # vitest run
+npm run typecheck      # vue-tsc --noEmit
+npm run lint           # eslint src tests preview  (lint:fix to autofix)
+npm run format         # prettier --write .        (format:check to verify only)
 ```
 
-5.During creating vue-instance of app, add property:
+Node version is pinned in `.nvmrc` (Node 24) — run `nvm use` (or fnm) before installing. Install
+with `npm ci`, not `npm install`: it installs exactly from the committed `package-lock.json` and
+avoids the npm optional-dependency bug ([npm#4828](https://github.com/npm/cli/issues/4828)) that
+can drop rolldown's native binding and break `vite`. If a machine gets into that state, a clean
+`rm -rf node_modules && npm ci` fixes it.
 
-```
-provide: { 'ITC': Vue.prototype.$transmissionClient },
-```
+`src/environment/environment.ts` is gitignored — create it from the checked-in
+`environment.dev.ts` / `environment.prod.ts` first.
 
-6.For correct work of styles add globally or in correspond component styles import
+### Builds
 
+```bash
+npm run build          # typecheck, then every build below (also runs on prepublishOnly)
+npm run build:lib      # dist/vue      — Vue 3 library, vue external
+npm run build:wc       # dist/wc       — self-contained <vd-comparison-form> (ES; ITC + Vue inlined)
+npm run build:wc-noitc # dist/wc-noitc — same element, UMD, ITC left external (host resolves it)
+npm run build:wc-forms # dist/wc-forms — one CJS element bundle per form (<name>.cjs), ITC external
 ```
-import '@vergelijkdirect/comparison-forms/styles';
-```
 
-7.Use component <embedded-comparison-forms> to render appropriate form. Below indicated props types:
-
-|       Props        | Type/required |                                                                                     Meaning                                                                                     |                                      Example                                       |
-| :----------------: | :-----------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------: |
-|   form-component   |  String/Yes   |                                                                           Corresponds to type of form                                                                           |                                     motor-form                                     |
-|        link        |   String/No   |                                                      Indicate address, where user should be redirected after forms submit                                                       |                          &link=verzekeringen/results-page                          |
-|   has-new-design   |  Boolean/No   |                        Indicate which version of form styles implemented. Missing value or false mean old form, true - new redesign form (non-required)                         |                                        true                                        |
-|      classes       |   String/No   |                                                  Indicate which classes should be implemented for root element (vd-form-card)                                                   |                                    vd-form-flat                                    |
-|  insurance-state   |   Object/No   |                             There should be indicated object with data for insurance. Used to show data in inputs, if user already filled in form.                              |          for motor insurance can be included object motorState from store          |
-|  user-information  |   Object/No   |                                 There should be indicated object with user's data. Used to show data in inputs, if user already filled in form.                                 |                   Usually it's userInformation object from store                   |
-|      base-url      |   String/No   |                                                      Base url should be used only for loans create forms, specify base url                                                      |                                         /                                          |
-|       title        |   String/No   |                                                    Specify title of form (by default has value <insurance name> vergelijken)                                                    |                            Motorverzekering vergelijken                            |
-|     show-title     |  Boolean/No   |                    Boolean, that specify should title, in title prop be showed (Use value false, if there is external modal title, to prevent double titles)                    |                                       false                                        |
-|  form-orientation  |   String/No   |                                           Specify form orientation (Vertical or Horizontal) Should be used only for create loan form                                            |                                      Vertical                                      |
-|   form-location    |   String/No   |                                       String, that indicate, where form is located. Can be before flow, on result, coverages,family page.                                       |      IS_BEFORE_FLOW/IS_ON_RESULT_PAGE/IS_ON_COVERAGES_PAGE/IS_ON_FAMILY_PAGE       |
-| additional-options |   Object/No   |                            Props that contains all special data, for separate form. E.g. qustionnary data for only Risk scanner/business car forms.                             |                              { qa_id: 'some value' }                               |
-|      @change       |  Function/No  | Function, that should be called, when user submit form. Has parameters ({ insuranceState: {...}, userInformation: {...} }), that can be used for furtner actions with this data |               Any function, that should be called after form submit                |
-|   @redirect-page   |  Function/No  |                Function, that should be called, when user submit form, and should be redirected to page, indicated in link props with necessary data in queries.                |               Any function, that should be called after form submit                |
-|  @emit-event-hub   |  Function/No  |                           Function, that should be called, when user want to use external emit event. Has parameters ({ event: String, data: {...}})                            | emit('emit-event-hub', { event: 'call-some-external-event', data: { ...any data }) |
-
-Example
+`build:wc` is the self-contained drop-in used from a plain `<script>` tag. The `wc-noitc` /
+`wc-forms` variants keep `@vergelijkdirect/insurance-transmission-client` external so a host
+bundler (webpack 5) shares its own configured client with the forms.
+
+## Architecture
 
 ```
-            <embedded-comparison-forms
-                v-if="isFormOpen"
-                @change="submitForm"
-                @emit-event="emitEvent"
-                :form-component="'motor-form'"
-                :user-information="userInformation"
-                :insurance-state="motorState"
-                :has-new-design="true"
-                :classes="'w-100 vd-form-card--flat'"
-                :link="'/'"
-                :show-title="false"
-                :form-location="'IS_ON_RESULT_PAGE'"
-                :additional-options="{
-                    some-data-for-some-certain-form: 'some data'
-                }"
-            />
+entries (lib.ts, wc.ts)  →  flow (useComparisonSubmit, ComparisonFormFlow)
+  →  comparisons (registry + one dir per comparison: Form, schema, models, presenter)
+    →  components (fields: address/licensePlate/company  →  ui: Vd* primitives)
+data/itc.ts — the single gateway to the ITC client        interfaces — shared types
 ```
 
-### THE LIST OF AVAILABLE FORMS
-
-- bike-form
-- bike-form-horizontal
-- business-car-form
-- business-car-form-horizontal
-- business-liability-form
-- car-form
-- car-form-horizontal
-- caravan-form
-- caravan-form-horizontal
-- default-form
-- house-form
-- house-form-horizontal
-- legal-assistance-form
-- legal-assistance-form-horizontal
-- liability-form
-- liability-form-horizontal
-- loan-form
-- loan-form-horizontal
-- moped-form
-- moped-form-horizontal
-- motor-form
-- motor-form-horizontal
-- package-form
-- pet-form
-- pet-form-horizontal
-- questionnaire-form
-- risk-scanner-form
-- travel-form
-- travel-form-horizontal
-
-Those names should be used in form-component prop for embedded mode, or for link address for standalone version, and should be exact as in this list. If there is a need to get old horizontal form, formComponent should include: form-type-horizontal-old, or form-type-old-horizontal. E.g. motor-form-horizontal-old.
-
-NOTICE: If there is :link prop, user will be redirected to this address with appropriate queryparams.
-
-### Embedded mode Comparison forms commands
-
-- npm run watch - launch dev mode SSR app
-- npm run serve - launch prod mode SSR app
-- npm run test - launch test mode app
-- npm run build - make build
-- npm run rollup - make rollup of comparison forms
+Forms are headless: they validate (yup via `useValidator`) and emit `submitted` with typed, valid
+data — no API calls, no redirects, no global state inside a form.