widget-web-component 1.2.0-dev → 1.3.0

package/README.md

@@ -2,8 +2,9 @@
 
 ## 📖 Description
 
-This package provides the `<belender-web-component>` as a reusable web component built with Angular and distributed as a standalone package.  
-It can be used in **any frontend framework** (Angular, React, Vue, Lit, plain HTML/JS, etc.) without additional setup.
+This package provides `<belender-web-component>`, a reusable web component built with
+Angular and distributed as a standalone package. It can be used in **any frontend
+framework** (Angular, React, Vue, Lit, plain HTML/JS, etc.) without additional setup.
 
 ---
 
@@ -13,24 +14,33 @@ It can be used in **any frontend framework** (Angular, React, Vue, Lit, plain HT
 npm i widget-web-component
 ```
 
-## Usage
+---
+
+## 🚀 Quick start
 
-```Lit Example:
-import { LitElement, html } from "lit";
-import { initBelenderComponent } from 'widget-web-component'; 
+The component class is generated asynchronously. Call `initBelenderComponent()`, then
+register the custom element with the tag name of your choice.
+
+```js
+import { initBelenderComponent } from 'widget-web-component';
 
-// 1. Ejecutar la función asíncrona para iniciar Angular y obtener la clase.
 initBelenderComponent()
-    .then((BelenderWebComponent) => {
-        
-        // 2. Usar la clase (Function) obtenida para el registro manual.
-        customElements.define('belender-web-component', BelenderWebComponent);
-        
-        console.log("✅ Componente registrado exitosamente.");
-    })
-    .catch(err => {
-        console.error("❌ Fallo el registro del Web Component:", err);
-    });
+  .then((BelenderWebComponent) => {
+    customElements.define('belender-web-component', BelenderWebComponent);
+    console.log('✅ Web Component registered');
+  })
+  .catch((err) => {
+    console.error('❌ Failed to register the Web Component:', err);
+  });
+```
+
+Then render the element and configure it. Inputs can be set as **HTML attributes**
+(kebab-case) or as **JS properties** (camelCase).
+
+### Example (Lit wrapper)
+
+```js
+import { LitElement, html } from 'lit';
 
 export class BelenderWidget extends LitElement {
   connectedCallback() {
@@ -39,29 +49,82 @@ export class BelenderWidget extends LitElement {
   }
 
   loadData() {
-    const widget = this.shadowRoot.getElementById("widget");
+    const widget = this.shadowRoot?.getElementById('widget');
     if (!widget) {
-      setTimeout(() => {
-        this.loadData();
-      }, 100);
+      setTimeout(() => this.loadData(), 100);
       return;
     }
-    widget.isWebComponent = true; <- required
-    widget.editableDates = true; <- true for enable date inputs to edit
-    widget.flowType = "clavepin";
-    widget.userID = "";
-    widget.packageId = "";
-    widget.documentNumber = "";
-    widget.birthDate = "1990/10/10";
-    widget.documentExpirationDate = "2030/1/1";
-
-    this.requestUpdate();
+
+    widget.isWebComponent = true;                 // required
+    widget.apiUrl = 'https://your-belender-api';  // provided by Belender (see API URL)
+    widget.flowType = 'clavepin';
+    widget.urlPath =
+      '/widget/clavepin/0d529b37-f96e-447d-be86-535b650c4a1e/ec05d020-00b6-494b-86ca-2a9b5d8c2605';
   }
 
   render() {
-    return html`
-      <belender-web-component id="widget"></belender-web-component>
-    `;
+    return html`<belender-web-component id="widget"></belender-web-component>`;
   }
 }
-```
+```
+
+### Example (plain HTML)
+
+```html
+<belender-web-component
+  is-web-component="true"
+  api-url="https://your-belender-api"
+  flow-type="clavepin"
+  user-id="0d529b37-f96e-447d-be86-535b650c4a1e"
+  package-id="ec05d020-00b6-494b-86ca-2a9b5d8c2605"
+  request-id="..."
+></belender-web-component>
+```
+
+---
+
+## ⚙️ Inputs / Properties
+
+| Property (JS) | Attribute (HTML) | Type | Description |
+|---|---|---|---|
+| `isWebComponent` | `is-web-component` | boolean | **Required.** Marks the instance as a web component. |
+| `apiUrl` | `api-url` | string | Base URL of a valid Belender environment. See **API URL** below. |
+| `urlPath` | `url-path` | string | Widget route to open, e.g. `/widget/{flow}/{userId}/{packageId}?request_id=...` |
+| `flowType` | `flow-type` | string | Flow to launch (e.g. `clavepin`, `sms`, `videoid`, `clientcertificate`). |
+| `userID` | `user-id` | string | User / funder id. |
+| `requestId` | `request-id` | string | Request id (pre-request or existing request). |
+| `packageId` | `package-id` | string | Document package id. |
+| `editableDates` | `editable-dates` | boolean | Allows editing the date inputs. |
+| `documentNumber` | `document-number` | string | Prefill: DNI / NIE. |
+| `documentExpirationDate` | `document-expiration-date` | string | Prefill: document expiration (`YYYY/MM/DD`). |
+| `documentSupport` | `document-support` | string | Prefill: document support number. |
+| `birthDate` | `birth-date` | string | Prefill: birth date (`YYYY/MM/DD`). |
+| `phone` | `phone` | string | Prefill: phone. |
+| `email` | `email` | string | Prefill: email. |
+
+> Note: the property name is camelCase (`userID` has a capital `ID`); the attribute is
+> always kebab-case (`user-id`).
+
+---
+
+## 🌐 API URL (`apiUrl` / `api-url`)
+
+Sets the base URL the widget uses for all API calls. The only requirement is that it
+points to a **valid Belender environment**. There is no fixed list of allowed URLs:
+different URLs or domains may resolve to the same environment. Belender will tell you
+which URL to use for your target environment.
+
+**Default:** if `apiUrl` is not set, the URL compiled into the bundle is used. It is
+recommended to always set `apiUrl` explicitly with the URL provided by Belender.
+
+**Format validation:** only the URL **format** is validated before use (not the target).
+If the value is rejected, the previous / default URL is kept and a `console.warn` is
+logged. A value is rejected when:
+- the protocol is not `http`/`https`,
+- it is `http` in production (except `localhost` / `127.0.0.1` / `::1`),
+- the URL is malformed.
+
+Query string, hash and trailing slash are stripped from a valid URL.
+
+> ⚠️ Only the URL **format** is validated, not the destination. The widget will only
+> work if `apiUrl` points to a valid Belender environment.