@tvsgroup/appointment-form 0.1.1

package/README.md

@@ -0,0 +1,121 @@
+# @tvsgroup/appointment-form
+
+Multi-step appointment booking form for TVS Engineering, shipped as the `<tvs-appointment-form>` web component (Vue 3 inside a shadow root) with an optional typed Vue wrapper. Consumable three ways:
+
+1. **Web component** from any framework or plain HTML (Astro, WordPress, …)
+2. **Vue wrapper component** (`AppointmentForm`) for Vue apps / Astro with `@astrojs/vue`
+3. **Standalone bundle** (`dist/appointment-form.es.js`) served from S3 — the legacy embed, unchanged
+
+## Installation
+
+```sh
+npm install @tvsgroup/appointment-form
+```
+
+Vue 3 is a peer dependency (npm ≥7 installs it automatically). All other runtime dependencies (Pinia, intl-tel-input, js-datepicker, …) are bundled.
+
+## Attributes / Props
+
+| Custom-element attribute | Vue wrapper prop | Type (wrapper) | Default | Description |
+|---|---|---|---|---|
+| `lang` | `lang` | `string` | `'nl'` | UI language (`nl` or `en`) |
+| `aws_url` | `awsUrl` | `string` | — (required) | Base URL of the appointment API |
+| `vacation_mode` | `vacationMode` | `boolean` | `false` | Holiday closure: disables queue/direct lanes, shows closure banner. Attribute form accepts `"true"` / `"1"` / `"yes"` / bare attribute |
+| `vacation_start` | `vacationStart` | `string` | `''` | First closed day, ISO `YYYY-MM-DD` |
+| `vacation_end` | `vacationEnd` | `string` | `''` | Last closed day, ISO `YYYY-MM-DD` |
+| `vacation_reopen` | `vacationReopen` | `string` | `''` | First day back at work, ISO `YYYY-MM-DD` |
+
+## Usage
+
+### Astro — web component (no framework integration needed)
+
+```astro
+---
+// src/pages/afspraak.astro
+---
+<tvs-appointment-form
+  lang="nl"
+  aws_url="https://<api-id>.execute-api.us-east-1.amazonaws.com"
+></tvs-appointment-form>
+
+<script>
+  import '@tvsgroup/appointment-form/register';
+</script>
+```
+
+The `/register` import defines the element on the client (idempotent, SSR-safe).
+
+### Astro + `@astrojs/vue` — Vue wrapper
+
+```astro
+---
+import { AppointmentForm } from '@tvsgroup/appointment-form';
+---
+<AppointmentForm
+  client:only="vue"
+  lang="nl"
+  awsUrl="https://<api-id>.execute-api.us-east-1.amazonaws.com"
+  vacationMode={false}
+/>
+```
+
+`client:only="vue"` is recommended — the form is fully interactive and gains nothing from SSR.
+
+### Plain HTML (standalone S3 bundle — legacy embed)
+
+```html
+<script type="module" src="https://<bucket>/appointment-form.es.js"></script>
+
+<tvs-appointment-form
+  lang="nl"
+  aws_url="https://<api-id>.execute-api.us-east-1.amazonaws.com"
+></tvs-appointment-form>
+```
+
+### Host-page notes
+
+- **Multiple instances supported.** Each `<tvs-appointment-form>` element gets its own Pinia instance (installed per element via `configureApp`), so several forms on one page keep fully independent state.
+- **Fonts**: the component inherits the host page's font stack; the TVS look expects [Inter](https://fonts.google.com/specimen/Inter) to be loaded by the host.
+- **Styles** are encapsulated in a shadow root — the host page's CSS (and Tailwind config) won't clash with the form's.
+- **Runtime network**: the phone input loads the intl-tel-input utils script from jsDelivr and does a geo-IP lookup (ipapi.co) for the default country flag.
+
+## Package layout
+
+| Entry | File | Vue |
+|---|---|---|
+| `@tvsgroup/appointment-form` | `dist/index.js` — `AppointmentForm`, `register()`, `TAG_NAME`, types | external (peer) |
+| `@tvsgroup/appointment-form/register` | `dist/register.js` — side-effect: defines the element | external (peer) |
+| standalone | `dist/appointment-form.es.js` — self-contained, self-registering | bundled |
+
+## Development
+
+```sh
+npm install
+npm run dev          # dev harness (src/main.ts + App.vue)
+npm run build        # standalone bundle + npm library (dist/)
+npm run test:unit    # vitest
+npm run e2e:dry      # Playwright suite in dry-run mode
+npm run type-check
+```
+
+Deployment of the standalone bundle to S3 is handled by `.github/workflows/deploy-*.yml` + `s3-sync.sh`. Publishing to a registry is not wired up yet; `npm run build` runs automatically via `prepublishOnly`.
+
+## Known Issues / Pending Fixes
+
+These items are tracked here so the team has a single source of truth for outstanding tech debt. Update this list as items are resolved or new issues are discovered.
+
+### Cross-repo: Lambda `createAppointment` (`tvs-cloud-services/services/rest/src/createAppointment.ts`)
+
+1. **`loanCar` contract mismatch (worked around in this repo).** The Lambda types `loanCar` as `string` (scalar) and forwards it directly to Frappe's scalar fields `loan_car` and `custom_loan_car`. This webcomponent originally sent `loanCar` as `string[]` (multiselect), which caused Frappe to throw `frappe.exceptions.ValidationError: Waar voor Loan car kan geen lijst worden` (HTTP 417).
+   - **Current workaround**: `buildSubmitPayload` in `src/stores/appointmentForm.ts` serializes the array to a CSV string before fetch.
+   - **Proper fix**: keep `loanCar: string[]` end-to-end and let the Lambda do the join. The transformation belongs in the anti-corruption layer (Lambda), not the UI.
+
+2. **Bug at `createAppointment.ts:152` (latent).** In the PUT branch (when a project already exists), the field assignment is `custom_is_loan_car: data.loanCar` — it should be `data.needsLoanCar` (boolean). Today it never fires because the flow always goes through POST, but it will break the moment a customer updates an existing appointment.
+
+### Internal: this repo
+
+3. **Duplicate `LOAN_CAR_LABELS` mapping.** The map `golf6 → "GOLF 6 DSG"`, `up → "VW UP!"`, `caddy → "VW CADDY"` lives in **two** places:
+   - `src/stores/appointmentForm.ts` — used by `buildSubmitPayload` for the wire payload.
+   - `src/views/steps/ConfirmView.vue` — used by `formatLoanCars` for the confirmation summary shown to the customer.
+
+   If a label changes in only one place, the customer will see one value on Confirm but a different one will land in ERPNext. Candidate to dedupe into a shared util / constants module.

package/dist/AppointmentForm.d.ts

@@ -0,0 +1,78 @@
+export interface AppointmentFormProps {
+    /** UI language, e.g. "nl" or "en". Defaults to "nl". */
+    lang?: string;
+    /** Base URL of the appointment API (required). */
+    awsUrl: string;
+    /** Holiday closure switch. Defaults to false. */
+    vacationMode?: boolean;
+    /** First closed day (ISO `YYYY-MM-DD`). */
+    vacationStart?: string;
+    /** Last closed day (ISO `YYYY-MM-DD`). */
+    vacationEnd?: string;
+    /** First day back at work (ISO `YYYY-MM-DD`). */
+    vacationReopen?: string;
+}
+/**
+ * Vue wrapper around the <tvs-appointment-form> custom element with typed,
+ * camelCase props. Rendered via a render function so consumers don't need
+ * `isCustomElement` compiler configuration.
+ */
+export declare const AppointmentForm: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    lang: {
+        type: StringConstructor;
+        default: string;
+    };
+    awsUrl: {
+        type: StringConstructor;
+        required: true;
+    };
+    vacationMode: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    vacationStart: {
+        type: StringConstructor;
+        default: string;
+    };
+    vacationEnd: {
+        type: StringConstructor;
+        default: string;
+    };
+    vacationReopen: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    lang: {
+        type: StringConstructor;
+        default: string;
+    };
+    awsUrl: {
+        type: StringConstructor;
+        required: true;
+    };
+    vacationMode: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    vacationStart: {
+        type: StringConstructor;
+        default: string;
+    };
+    vacationEnd: {
+        type: StringConstructor;
+        default: string;
+    };
+    vacationReopen: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    lang: string;
+    vacationMode: boolean;
+    vacationStart: string;
+    vacationEnd: string;
+    vacationReopen: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;