@genesislcap/foundation-forms 14.25.0 → 14.25.1-alpha-3c26bb7.0

package/README.md

@@ -1,15 +1,38 @@
-# Genesis Foundation Forms
+# Foundation Forms
 
 [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
-`foundation-forms` is a library for efficiently building complex forms at scale
-
 ### [API Docs](./docs/api/index.md)
 
-## General usage
+`foundation-forms` is a library for efficiently building complex forms and filters at scale.
+
+Foundation forms is defined by using two schemata:
+
+- `resourceName`/`jsonSchema` defines the underlying data to be shown in the UI (objects, properties, and their types).
+- `uiSchema` defines how this data is rendered as a form, e.g. the order of controls, their visibility, and the layout.
+
+## Forms
+
+### Basic install
+
+To enable this module in your application, follow the steps below.
+
+1. Add `@genesislcap/foundation-forms` as a dependency in your **package.json** file. Whenever you change the dependencies of your project, ensure you run the `$ npm run bootstrap` command again. You can find more information in the [package.json basics](../../../web/basics/package-json-basics/) page.
+
+```javascript
+{
+  ...
+  "dependencies": {
+    "@genesislcap/foundation-forms": "latest"
+  },
+  ...
+}
+```
 
-1. *Register components*
+### General usage
+
+#### 1. Register components
 
 ```ts
 import { Form } from '@genesislcap/foundation-forms';
@@ -18,39 +41,665 @@ Form
 ...
 ```
 
-2. *Add component to the template*
+#### 2. Add component to the template
+
 ```html
 <foundation-form resourceName="EVENT_TRADE_INSERT"></foundation-form>
 ```
 
-This should generate working form based on the JSON schema for that endpoint. 
-DevTools console will output autogenerated UI schema that you can use to configure the form
+This should generate working form based on the `JSON schema` for that endpoint.
+DevTools console will output autogenerated `UI schema` that you can use to configure the form
+
+#### 3. Configure form using UI schema
 
-3. *Configure form using UI schema*
 ```ts
 const sampleUISchema = {
+  type: "VerticalLayout",
+  elements: [
+    {
+      type: "Control",
+      scope: "#/properties/QUANTITY",
+      label: "Quantity",
+    },
+    {
+      type: "Control",
+      scope: "#/properties/SIDE",
+      label: "Side",
+    },
+  ],
+};
+```
+
+```html
+<foundation-form resourceName="EVENT_TRADE_INSERT" :uischema=${() => sampleUISchema}></foundation-form>
+```
+
+#### 4. Configure form using JSON schema (optional)
+
+Alternatively to providing `resourceName` you can hardcode the `JSON schema` on the client.
+
+```ts
+const sampleJsonSchema = {
+  type: 'object',
+  properties: {
+    ISSUER_NAME: {
+      type: 'string',
+      minLength: 3,
+      description: 'kotlin.String',
+    },
+    PRICE: {
+      type: 'number',
+      description: 'kotlin.Double',
+    },
+    MAIN_CONTACT: {
+      type: 'string',
+      pattern: '^[\\+]?[(]?[0-9]{3}[)]?[-\\s\\.]?[0-9]{3}[-\\s\\.]?[0-9]{4,6}$',
+      description: 'kotlin.String',
+    },
+    PASSWORD: {
+      type: 'string',
+      description: 'kotlin.String',
+    },
+  },
+  additionalProperties: false,
+  required: ['ISSUER_NAME', 'MAIN_CONTACT'],
+};
+```
+
+```ts 
+const sampleUiSchema = {
   type: 'VerticalLayout',
   elements: [
     {
       type: 'Control',
-      scope: '#/properties/QUANTITY',
-      label: 'Quantity',
+      label: 'Issuer Name',
+      scope: '#/properties/ISSUER_NAME',
+    },
+    {
+      type: 'Control',
+      label: 'Phone',
+      scope: '#/properties/MAIN_CONTACT',
+    },
+    {
+      type: 'Control',
+      label: 'Price',
+      scope: '#/properties/PRICE',
+    },
+    {
+      type: 'Control',
+      scope: '#/properties/COUNTERPARTY',
+      options: {
+        allOptionsResourceName: 'COUNTERPARTY',
+        valueField: 'COUNTERPARTY_ID',
+        labelField: 'COUNTERPARTY_ID',
+        datasourceConfig: {
+          request: {
+            COUNTERPARTY_ID: 'ACME',
+          },
+        },
+      },
     },
     {
       type: 'Control',
-      scope: '#/properties/SIDE',
-      label: 'Side',
+      label: 'Password',
+      scope: '#/properties/PASSWORD',
+      options: {
+        isPassword: true,
+      },
     },
   ],
 };
+```
+
+```html
+<foundation-form :jsonSchema=${() => sampleJsonSchema} :uischema=${() => sampleUISchema}></foundation-form>
+```
+
+:::info
+Use this when you want to avoid fetching metadata from the server but be aware that it could get out of sync if metadata changes on the server.
+:::
+
+#### 5. Pre-fill forms with data (optional)
+
+Use the `data` attribute, which allows you to pre-fill the form with ready-made information.
 
+```ts
+const sampleData = {
+    ISSUER_NAME: 'Some Issuer',
+    INVIS: 'Invisible value!',
+    USER: 'JohnDoe',
+  };
 ```
+
 ```html
-<foundation-form resourceName="EVENT_TRADE_INSERT" :uischema=${() => sampleUISchema}></foundation-form>
+<foundation-form resourceName="EVENT_TRADE_INSERT" :uischema=${() => sampleUISchema} :data=${() => sampleData}></foundation-form>
+```
+
+## Filters
+
+### Basic install
+
+To enable this module in your application, follow the steps below.
+
+1. Add `@genesislcap/foundation-forms` as a dependency in your **package.json** file. Whenever you change the dependencies of your project, ensure you run the `$ npm run bootstrap` command again. You can find more information in the [package.json basics](../../../web/basics/package-json-basics/) page.
+
+```javascript
+{
+  ...
+  "dependencies": {
+    "@genesislcap/foundation-forms": "latest"
+  },
+  ...
+}
+```
+
+### General usage
+
+#### 1. Register components
+
+```ts
+import { Filters } from '@genesislcap/foundation-forms';
+...
+Filters
+...
 ```
-       
 
+#### 2. Add component to the template
+
+```html
+<foundation-filters resourceName="ALL_TRADES"></foundation-filters>
+```
+
+This should generate working form based on the `JSON schema` for that endpoint.
+DevTools console will output autogenerated `UI schema` that you can use to configure the filters
+
+#### 3. Configure form using UI schema
+
+```ts
+const sampleUISchema = {
+  type: "VerticalLayout",
+  elements: [
+    {
+      type: "Control",
+      scope: "#/properties/QUANTITY",
+      label: "Quantity",
+    },
+    {
+      type: "Control",
+      scope: "#/properties/SIDE",
+      label: "Side",
+    },
+  ],
+};
+```
+
+```html
+<foundation-filters resourceName="ALL_TRADES" :uischema=${() => sampleUISchema}></foundation-filters>
+```
+
+#### 4. Configure form using JSON schema (optional)
+
+Alternatively to providing `resourceName` you can hardcode the `JSON schema` on the client.
+
+```ts
+const sampleJsonSchema = {
+  type: 'object',
+  properties: {
+    INSTRUMENT_ID: {
+      type: 'string',
+      minLength: 3,
+      description: 'kotlin.String',
+    },
+    QUANTITY: {
+      type: 'number',
+      description: 'kotlin.Double',
+    },
+  },
+};
+```
+
+```ts 
+const sampleUiSchema = {
+  type: 'VerticalLayout',
+  elements: [
+    {
+      type: 'Control',
+      label: 'Instrument ID',
+      scope: '#/properties/INSTRUMENT_ID',
+    },
+    {
+      type: 'Control',
+      label: 'Quantity',
+      scope: '#/properties/QUANTITY',
+    },
+  ],
+};
+```
+
+```html
+<foundation-filters :jsonSchema=${() => sampleJsonSchema} :uischema=${() => sampleUISchema}></foundation-filters>
+```
+
+:::info
+Use this when you want to avoid fetching metadata from the server but be aware that it could get out of sync if metadata changes on the server.
+:::
+
+#### 5. An example of synchronizing values with datasource criteria
+
+```html
+  <zero-card>
+    <foundation-filters 
+      resourceName="ALL_USERS"
+      :value=${sync((x) => x.allUsersfilters)}>
+    </foundation-filters>
+  </zero-card>
+  <zero-grid-pro>
+    <grid-pro-genesis-datasource
+      resource-name="ALL_USERS"
+      criteria=${(x) => x.allUsersfilters}
+    ></grid-pro-genesis-datasource>
+  </zero-grid-pro>
+```
+
+
+## Advanced customization
+
+### Default layout renderers and examples
+
+#### 1. Vertical Layout
+
+This is the default layout that is defined if no `uiSchema` is specified. Arranges our control elements vertically.
+
+```ts
+const VerticalUISchema = {
+  type: 'VerticalLayout',
+  elements: [
+    ...
+  ],
+};
+```
+
+#### 2. Vertical Layout - Two columns
+
+Arranges our control elements in 2 columns vertically
+
+```ts
+const VerticalColumnsUISchema = {
+  type: 'LayoutVertical2Columns',
+  elements: [
+    ...
+  ],
+};
+```
+
+#### 3. Horizontal Layout
+
+Arranges our control elements horizontally
+
+```ts
+const horizontalUISchema = {
+  type: 'HorizontalLayout',
+  elements: [
+    ...
+  ],
+};
+```
+
+#### 4. Array Layout
+
+Array Layout allows you to create a dynamic form with the ability to add, for example, multiple users.
+
+It is more complicated when it comes to customization because it needs proper `jsonSchema` and `uiSchema`.
+
+```ts
+const arrayUISchema = {
+  type: "VerticalLayout",
+  elements: [
+    {
+      type: "array",
+      scope: "#/properties/users",
+      options: {
+        childUiSchema: {
+          type: "HorizontalLayout",
+          elements: [
+            {
+              type: "Control",
+              scope: "#/properties/firstname",
+              label: "First Name",
+            },
+            {
+              type: "Control",
+              scope: "#/properties/lastname",
+              label: "Last Name",
+            },
+            {
+              type: "Control",
+              scope: "#/properties/email",
+              label: "Email",
+            },
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+```ts
+const arrayJsonSchema = {
+  type: "object",
+  properties: {
+    users: {
+      type: "array",
+      items: {
+        type: "object",
+        title: "Users",
+        properties: {
+          firstname: {
+            type: "string",
+          },
+          lastname: {
+            type: "string",
+          },
+          email: {
+            type: "string",
+            format: "email",
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+#### 5. Categorization Layout
+
+Categorization layout allows you to create more complex forms that can be divided into appropriate categories, for example: personal information and address - which will be in separate tabs.
+
+```ts
+const categoryUISchema = {
+  type: "Categorization",
+  elements: [
+    {
+      type: "Category",
+      scope: "#/properties/basic",
+      label: "Personal information",
+      options: {
+        childElements: [
+          {
+            type: "HorizontalLayout",
+            elements: [
+              {
+                type: "Control",
+                scope: "#/properties/firstName",
+              },
+              {
+                type: "Control",
+                scope: "#/properties/secondName",
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      type: "Category",
+      label: "Address",
+      scope: "#/properties/address",
+      options: {
+        childElements: [
+          {
+            type: "HorizontalLayout",
+            elements: [
+              {
+                type: "Control",
+                scope: "#/properties/address/properties/street",
+              },
+              {
+                type: "Control",
+                scope: "#/properties/address/properties/streetNumber",
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ],
+};
+```
+
+#### 6. Group Layout
+
+Group layout similarly to categorization layout divides forms, but this time into groups. They are visible on the same tab, but they are separated from each other by their own labels.
+
+```ts
+const groupUISchema = {
+  type: "VerticalLayout",
+  elements: [
+    {
+      type: "Group",
+      label: "Person",
+      scope: "#/properties/person",
+      options: {
+        childElements: [
+          {
+            type: "LayoutVertical2Columns",
+            elements: [
+              {
+                type: "Control",
+                label: "First Name",
+                scope: "#/properties/person/properties/firstName",
+              },
+              {
+                type: "Control",
+                scope: "#/properties/person/properties/lastName",
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      type: "Group",
+      label: "Address",
+      scope: "#/properties/address/",
+      options: {
+        childElements: [
+          {
+            type: "VerticalLayout",
+            elements: [
+              {
+                type: "Control",
+                scope: "#/properties/person/properties/shippingAddress",
+              },
+              {
+                type: "Control",
+                scope: "#/properties/address/properties/street",
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ],
+};
+```
+
+### Default control renderers and examples
+
+Most renderers are defined directly in the `jsonSchema` that comes from the server, but there are also those that we can add via `uiSchema`.
+
+#### 1. String Renderer
+
+The default renderer that will create a `text-field`.
+
+```ts
+const stringJsonSchema = {
+  type: "object",
+  properties: {
+    ISSUER_NAME: {
+      type: "string",
+      minLength: 3,
+      description: "kotlin.String",
+    },
+    USER: {
+      type: "string",
+      description: "kotlin.String",
+    },
+    MAIN_CONTACT: {
+      type: "string",
+      pattern: "^[\\+]?[(]?[0-9]{3}[)]?[-\\s\\.]?[0-9]{3}[-\\s\\.]?[0-9]{4,6}$",
+      description: "kotlin.String",
+    },
+  },
+};
+```
+
+#### 2. Number Renderer
+
+The number renderer that will create a `number-field`.
+
+```ts
+const numberJsonSchema = {
+  type: "object",
+  properties: {
+    PRICE: {
+      type: "number",
+      description: "kotlin.Double",
+    },
+  },
+};
+```
+
+#### 3. Boolean Renderer
+
+The boolean renderer that will create a `checkbox-field`.
+
+```ts
+const booleanJsonSchema = {
+  type: "object",
+  properties: {
+    vegetarian: {
+      type: "boolean",
+    },
+  },
+};
+```
+
+#### 4. Connected Multiselect Renderer
+
+The boolean renderer that will create a `multiselect` component with options from datasource.
+
+```ts
+const connectedMultiselectUISchema = {
+  type: "HorizontalLayout",
+  elements: [
+    {
+      type: 'Control',
+      label: 'Rights',
+      scope: '#/properties/RIGHT_CODES',
+      options: {
+        allOptionsResourceName: 'RIGHT',
+        valueField: 'CODE',
+        labelField: 'CODE',
+      },
+    },
+    {
+      type: 'Control',
+      label: 'Users',
+      scope: '#/properties/USER_NAMES',
+      options: {
+        allOptionsResourceName: 'USER',
+        valueField: 'USER_NAME',
+        labelField: 'USER_NAME',
+      },
+    },
+  ],
+};
+```
+
+#### 5. Connected Select Renderer
+
+The boolean renderer that will create a `select` component with options.
+
+```ts
+const connectedSelectUISchema = {
+  type: "HorizontalLayout",
+  elements: [
+    {
+      type: "Control",
+      scope: "#/properties/COUNTERPARTY_ID",
+      options: {
+        data: CounterpartyOptions,
+        valueField: "value",
+        labelField: "name",
+      },
+      label: "Counterparty",
+    },
+    {
+      type: "Control",
+      scope: "#/properties/INSTRUMENT_ID",
+      options: {
+        data: InstrumentOptions,
+        valueField: "value",
+        labelField: "name",
+      },
+      label: "Instrument",
+    },
+  ],
+};
+```
+
+#### 6. Date Renderer
+
+The date renderer that will create a `date-field`.
+
+```ts
+const dateJsonSchema = {
+  type: "object",
+  properties: {
+    tradeDate: {
+      type: "string",
+      description: "org.joda.time.DateTime",
+    },
+  },
+};
+```
+
+### Specific renderers for filters and examples
+
+#### 1. Filter Date Renderer
+
+The filter date renderer that will create a two `date-fields` with minimum and maximum value.
+
+```ts
+const dateJsonSchema = {
+  type: "object",
+  properties: {
+    tradeDate: {
+      type: "string",
+      description: "org.joda.time.DateTime",
+    },
+  },
+};
+```
+
+#### 2. Filter Number Renderer
+
+The filter number renderer that will create a two `number-fields` with minimum and maximum value.
+
+```ts
+const numberJsonSchema = {
+  type: "object",
+  properties: {
+    PRICE: {
+      type: "number",
+      description: "kotlin.Double",
+    },
+  },
+};
+```
 
 ## License
 
-Note: this project provides front end dependencies and uses licensed components listed in the next section, thus licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.
+Note: this project provides front end dependencies and uses licensed components listed in the next section, thus licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-forms",
   "description": "Genesis Foundation Forms",
-  "version": "14.25.0",
+  "version": "14.25.1-alpha-3c26bb7.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -43,8 +43,8 @@
     "test:unit:watch": "watchlist src test -- npm run test:unit"
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "^14.25.0",
-    "@genesislcap/genx": "^14.25.0",
+    "@genesislcap/foundation-testing": "14.25.1-alpha-3c26bb7.0",
+    "@genesislcap/genx": "14.25.1-alpha-3c26bb7.0",
     "@playwright/test": "^1.18.1",
     "@types/json-schema": "^7.0.11",
     "@types/ua-parser-js": "^0.7.36",
@@ -59,9 +59,9 @@
     "watchlist": "^0.3.1"
   },
   "dependencies": {
-    "@genesislcap/foundation-comms": "^14.25.0",
-    "@genesislcap/foundation-criteria": "^14.25.0",
-    "@genesislcap/foundation-utils": "^14.25.0",
+    "@genesislcap/foundation-comms": "14.25.1-alpha-3c26bb7.0",
+    "@genesislcap/foundation-criteria": "14.25.1-alpha-3c26bb7.0",
+    "@genesislcap/foundation-utils": "14.25.1-alpha-3c26bb7.0",
     "@jsonforms/core": "^3.0.0",
     "@microsoft/fast-components": "^2.21.3",
     "@microsoft/fast-element": "^1.7.0",
@@ -82,5 +82,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "ee636dcc509e1cd2ab564462cb147819e7043154"
+  "gitHead": "b6c823b4ea994c87daea91aee563858162469ebd"
 }