@vergelijkdirect/comparison-forms 2.0.1 → 2.0.2-rc.0

package/README.md

@@ -29,7 +29,7 @@ import '@vergelijkdirect/comparison-forms/vue/styles';
 
 ## Usage
 
-### 1. Drop-in (recommended) — the form handles everything
+### 1. Drop-in (recommended for VD) — the form handles everything
 
 ```vue
 <script setup>
@@ -130,6 +130,7 @@ The 2.x event contract is a deliberate break. How each legacy event maps:
 
 ```bash
 npm run dev            # live sandbox (preview/) — demos for every component and form
+npm run verify         # lint + format:check + typecheck + test:unit — the one gate
 npm run test:unit      # vitest run
 npm run typecheck      # vue-tsc --noEmit
 npm run lint           # eslint src tests preview  (lint:fix to autofix)
@@ -142,13 +143,16 @@ avoids the npm optional-dependency bug ([npm#4828](https://github.com/npm/cli/is
 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.
 
+Bumping a `@vergelijkdirect/*` package has rules of its own (exact pins, and a second step for
+ITC) — see [DEPENDENCIES.md](DEPENDENCIES.md).
+
 `src/environment/environment.ts` is gitignored — create it from the checked-in
 `environment.dev.ts` / `environment.prod.ts` first.
 
 ### Builds
 
 ```bash
-npm run build          # typecheck, then every build below (also runs on prepublishOnly)
+npm run build          # typecheck, then every build below (prepublishOnly runs verify + this)
 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)
@@ -159,14 +163,50 @@ npm run build:wc-forms # dist/wc-forms — one CJS element bundle per form (<nam
 `wc-forms` variants keep `@vergelijkdirect/insurance-transmission-client` external so a host
 bundler (webpack 5) shares its own configured client with the forms.
 
+### Publishing to npm
+
+Manual — no pipeline publishes. Needs membership of the `@vergelijkdirect` npm org (`npm whoami`)
+and a clean working tree.
+
+```bash
+nvm use
+npm ci
+npm run verify                         # also runs on publish — but fail before the version commit
+
+npm version <patch|minor|major|prerelease>   # bumps + commits; the tag it makes stays local
+npm publish --tag <latest|next|legacy|rc>
+git push
+
+npm view @vergelijkdirect/comparison-forms dist-tags
+```
+
+`--tag` is not optional: a bare `npm publish` writes `latest` even for a prerelease.
+`latest` = stable 2.x, `next` = 2.x RCs, `legacy` = 1.3.x, `rc` = 1.x prereleases.
+
 ## Architecture
 
 ```
-entries (lib.ts, wc.ts)  →  flow (useComparisonSubmit, ComparisonFormFlow)
+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
+
+entries  →  questionnaires  →  components     (one-off track; never through flow/ or comparisons/)
+data/itc.ts — the single gateway to the ITC client
+constants / models / utils / schemas / enums / interfaces — shared leaves, any layer may import
 ```
 
-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.
+Path alias: `@` → `src/`. The rules that matter:
+
+- **Forms are headless.** They validate (yup via `useValidator`) and emit `submitted` with typed,
+  valid data — no API calls, no redirects, no global state. Whoever handles `submitted` decides
+  the scenario.
+- **One component per comparison.** Vertical/horizontal is the `layout` prop, not a second file.
+- **Dependency arrows point down only.** Comparisons never import each other, and never `flow/`.
+- **Only `data/` touches the ITC client** — everyone else goes through the `@/data` barrel.
+- **Barrels export named symbols only.** `export *` is an ESLint error under `src/` (tree shaking).
+- **All CSS comes from `@vergelijkdirect/styles`** (`.vd-*`) — the library writes none of its own.
+
+## Adding a new comparison form
+
+**[CONTRIBUTING.md](CONTRIBUTING.md)** — step by step, from the field list to the definition of
+done, including the seven places a new form must be registered.