ngx-iso-form-enterprise 1.0.0-beta

package/README.md

@@ -0,0 +1,391 @@
+<div align="center">
+  <a href="https://github.com/pixelbyaj/ngx-iso-form">
+    <img src="https://raw.githubusercontent.com/pixelbyaj/ngx-form/main/anguar_logo.svg?sanitize=true" alt="Angular Logo" />
+  </a>
+  <br />
+  <h1>XSD - JSON Powered / Dynamic ISO 20022 Forms in Angular v20</h1>
+  
+  ![npm](https://img.shields.io/npm/v/ngx-iso-form)
+  ![NPM](https://img.shields.io/npm/l/ngx-iso-form)
+  [![Downloads](https://img.shields.io/npm/dt/ngx-iso-form.svg)](https://npmjs.org/package/ngx-iso-form)
+  [![Downloads](https://img.shields.io/npm/dm/ngx-iso-form.svg)](https://npmjs.org/package/ngx-iso-form)
+</div>
+
+---
+
+# NgxIsoForm
+
+NgxIsoForm is a  Enterprise version of library for dynamically generating Angular Reactive Forms using JSON derived from XSD. It is primarily designed for ISO 20022 forms.
+
+## Features
+
+- 🔥 Automatic form generation
+- 📝 Extendable with custom field types
+- ⚡️ Supports ISO 20022 schemas:
+  - XSD to JSON Schema conversion using XSDService NuGet
+  - Validation support: required, pattern, minlength, maxlength
+  - Translation support for labels, errors, and date formats
+- 💪 Built on [Angular Reactive Forms](https://angular.dev/guide/forms/reactive-forms)
+
+## [Live Demo](https://swiftmx.co/#/ngx-iso-form-demo?json=pacs.009.001.10)
+
+## [StackBlitz Demo](https://stackblitz.com/edit/ngx-iso-form)
+
+## **NOTE**
+
+The library does not directly execute XSD. Users must convert XSD to JSON using the [xsd-json-converter](https://www.npmjs.com/package/xsd-json-converter) npm package or the [.NET ISO20022.XSD](https://www.nuget.org/packages/iSO20022.XSD) NuGet package.
+
+
+## How to Use
+
+### Add Angular Material v20
+
+```bash
+ng add @angular/material@20
+```
+
+### Install the Library
+
+```bash
+npm install ngx-iso-form
+```
+
+### Import Module and SCSS
+
+```typescript
+import { NgxIsoFormModule } from 'ngx-iso-form';
+import { HttpClient, provideHttpClient } from '@angular/common/http';
+
+// register license key
+const licenseKey = 'eyJleHBpcn......wI=';
+IsoLicenseManager.registerLicense(licenseKey);
+
+initLicense();
+@NgModule({
+  imports: [
+    NgxIsoFormModule,
+    TranslateModule.forRoot({
+      defaultLanguage: 'en',
+      loader: {
+        provide: TranslateLoader,
+        useFactory: HttpLoaderFactory,
+        deps: [HttpClient]
+      }
+    })
+  ],
+  providers: [provideHttpClient()]
+})
+export function HttpLoaderFactory(http: HttpClient) {
+  return new TranslateHttpLoader(http, '/i18n/', '.json');
+}
+```
+
+Add the style file to `angular.json`:
+
+```json
+"styles": [
+  "node_modules/ngx-iso-form/lib/styles/index.scss"
+]
+```
+
+### Usage
+
+#### New Option: `excludes`
+
+```html
+<ngx-iso-form #isoForm [schema]="schema" [form]="form" [excludes]="excludes"></ngx-iso-form>
+```
+
+**Note:** `excludes` (optional) accepts a `string[]` to exclude specific IDs from the form, allowing customization for business requirements.
+
+### Public APIs
+
+- `FormReadyEvent`: Event once form get ready.
+- `FormApi`: public api.
+
+```typescript
+export class FormReadyEvent {
+  api: FormApi;
+}
+
+export interface FormApi {
+  invalid: boolean;
+  setXmlForm: (model: any) => void;
+  setJsonForm: (model: any) => void;
+  getForm: () => any;
+  getNamespace: () => string;
+}
+```
+
+### Component Example
+
+```typescript
+export class AppComponent implements OnInit {
+  formApi: FormApi;
+  schema: SchemaElement;
+  excludes: string[] = [];
+
+  constructor(private httpClient: HttpClient,private license: IsoLicenseService) {}
+
+  ngOnInit() {
+    //validate license
+    this.license.validate().then(() => {
+      this.httpClient.get("path/to/schema.json").subscribe((data) => {
+        this.schema = data as SchemaElement;
+      });
+     }):
+  }
+
+  setWithJsonModel() {
+    this.httpClient.get("path/to/model.json").subscribe((model) => {
+      this.formApi.setJsonForm(model);
+    });
+  }
+
+  // New Support of XML Message as a model
+  setWithXmlMessage() {
+    this.httpClient.get("path/to/message.xml").subscribe((xmlMessage) => {
+      this.formApi.setXmlForm(model);
+    });
+  }
+
+  onFormReadyEvent(data: FormReadyEvent) {
+    this.formApi = data.api; //FormApi
+  }
+}
+```
+
+### Supported JSON Schema
+
+```typescript
+export interface SchemaElement {
+  id: string;
+  name: string;
+  dataType: string;
+  minOccurs: string;
+  maxOccurs: string;
+  minLength: string;
+  maxLength: string;
+  pattern: string;
+  fractionDigits: string;
+  totalDigits: string;
+  minInclusive: string;
+  maxInclusive: string;
+  values: string[];
+  isCurrency: boolean;
+  xpath: string;
+  expanded: boolean;
+  elements: SchemaElement[];
+  isUETR: boolean;
+  defaultValue?: string;
+}
+```
+
+### Translation Support
+
+Translation is supported for the `name` and `id` properties of `SchemaElement`. Declare translation rules under the `iso` object.
+
+```json
+{
+  "iso": {
+    "BkToCstmrStmt": {
+      "label": "Bank To Customer Statement"
+    },
+    "GrpHdr": {
+      "label": "Group Header"
+    },
+    "Document_BkToCstmrStmt_GrpHdr_CreDtTm": {
+      "label": "Create Datetime",
+      "general": {
+        "format": "YYYY-MM-DDThh:mm:ss.sss+/-"
+      },
+      "error": {
+        "required": "This field is required"
+      }
+    }
+  }
+}
+```
+
+### Sample XML Model
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09">
+  <CstmrCdtTrfInitn>
+    <GrpHdr>
+      <MsgId>123456</MsgId>
+      <CreDtTm>2025-03-27T10:00:00</CreDtTm>
+      <NbOfTxs>1</NbOfTxs>
+      <CtrlSum>1000.00</CtrlSum>
+      <InitgPty>
+        <Nm>Sender Company</Nm>
+      </InitgPty>
+    </GrpHdr>
+    <PmtInf>
+      <PmtInfId>PAY001</PmtInfId>
+      <PmtMtd>TRF</PmtMtd>
+      <BtchBookg>false</BtchBookg>
+      <Dbtr>
+        <Nm>John Doe</Nm>
+      </Dbtr>
+      <DbtrAcct>
+        <Id>
+          <IBAN>DE89370400440532013000</IBAN>
+        </Id>
+      </DbtrAcct>
+      <DbtrAgt>
+        <FinInstnId>
+          <BICFI>DEUTDEFFXXX</BICFI>
+        </FinInstnId>
+      </DbtrAgt>
+      <CdtTrfTxInf>
+        <PmtId>
+          <EndToEndId>TX123</EndToEndId>
+        </PmtId>
+        <Amt>
+          <InstdAmt Ccy="EUR">1000.00</InstdAmt>
+        </Amt>
+        <Cdtr>
+          <Nm>Jane Smith</Nm>
+        </Cdtr>
+        <CdtrAcct>
+          <Id>
+            <IBAN>FR7630006000011234567890189</IBAN>
+          </Id>
+        </CdtrAcct>
+        <CdtrAgt>
+          <FinInstnId>
+            <BICFI>BNPAFRPPXXX</BICFI>
+          </FinInstnId>
+        </CdtrAgt>
+      </CdtTrfTxInf>
+    </PmtInf>
+  </CstmrCdtTrfInitn>
+</Document>
+```
+
+### Output JSON Example (pain.001.001.12)
+
+```json
+{
+  "Document": {
+    "CstmrCdtTrfInitn": {
+      "GrpHdr": {
+        "MsgId": "123456",
+        "CreDtTm": "2025-03-27T10:00:00",
+        "NbOfTxs": "1",
+        "CtrlSum": "1000",
+        "InitgPty": {
+          "Nm": "Sender Company",
+          "CtryOfRes": "US"
+        }
+      },
+      "PmtInf": [
+        {
+          "PmtInfId": "PAY001",
+          "PmtMtd": "TRF",
+          "BtchBookg": "false",
+          "Dbtr": {
+            "Nm": "John Doe"
+          },
+          "DbtrAcct": {
+            "Nm": "DE89370400440532013000"
+          },
+          "DbtrAgt": {
+            "FinInstnId": {
+              "BICFI": "DEUTDEFFXXX"
+            }
+          },
+          "CdtTrfTxInf": [
+            {
+              "PmtId": {
+                "EndToEndId": "TX123"
+              },
+              "Amt": {
+                "InstdAmt": {
+                  "Ccy": "USD",
+                  "Amt": "1000"
+                }
+              },
+              "CdtrAgt": {
+                "FinInstnId": {
+                  "BICFI": "BNPAFRPPXXX"
+                }
+              },
+              "Cdtr": {
+                "Nm": "Jane Smith"
+              },
+              "CdtrAcct": {
+                "Id": {
+                  "IBAN": "FR7630006000011234567890189"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## Convert XSD to JSON
+
+### Global Installation (CLI)
+
+```bash
+npm install -g xsd-json-converter
+```
+
+### Local Installation (Script)
+
+```bash
+npm install xsd-json-converter
+```
+
+### CLI Usage
+
+```bash
+xjc <source-path> <output-path>
+```
+
+#### Example
+
+##### Linux
+
+```bash
+xjc /mnt/c/source/xsd/camt.053.001.10.xsd /mnt/c/source/xsd/camt.053.json
+```
+
+##### Windows
+
+```bash
+xjc C:/source/xsd/camt.053.001.10.xsd C:/source/xsd/camt.053.json
+```
+
+### Script Usage
+
+#### JavaScript
+
+```javascript
+const xsd = require("xsd-json-converter").default;
+
+xsd
+  .convert("./camt.053.001.10.xsd")
+  .then((output) => console.log(output))
+  .catch((error) => console.error(error));
+```
+
+#### TypeScript
+
+```typescript
+import xsd from "xsd-json-converter";
+
+xsd
+  .convert("./camt.053.001.10.xsd")
+  .then((output) => console.log(output))
+  .catch((error) => console.error(error));
+```
+
+**Note:** For scripts, install the package locally.