platformcommons-web-lib 1.0.0

package/documentation/form-builder.md

@@ -0,0 +1,597 @@
+# Form Builder Module
+
+The `FormBuilderModule` provides a set of components designed to allow developers and business users to create, select, and configure dynamic forms. It works closely with the `SmartFormModule`, using its schema format as both input and output.
+
+The Form Builder typically follows a two-step process:
+
+1. **Field Selection** (`lib-field-selection`): Choosing which fields and sections from a "master" or "template" schema should be active in the final form.
+2. **Field Configuration** (`lib-field-configurator`): Fine-tuning the properties of the selected fields, such as labels, validation rules, and layout (colSpan).
+
+A third optional step is **Form Preview** — rendering the final configured schema using `<lib-smart-form [readOnly]="true">` so the user can see what the form will look like without being able to edit values.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [1. Field Selection (`lib-field-selection`)](#1-field-selection-lib-field-selection)
+- [2. Field Configurator (`lib-field-configurator`)](#2-field-configurator-lib-field-configurator)
+- [3. Smart Form Preview (`lib-smart-form` in readOnly mode)](#3-smart-form-preview-lib-smart-form-in-readonly-mode)
+- [4. End-to-End Workflow](#4-end-to-end-workflow)
+- [5. Advanced Customization](#5-advanced-customization)
+- [6. Field Type Support](#6-field-type-support)
+- [7. Developer vs. Business-User Mode (recommended patterns)](#7-developer-vs-business-user-mode-recommended-patterns)
+
+---
+
+## Installation
+
+Import `FormBuilderModule` and `SmartFormModule` in your Angular module:
+
+```typescript
+import { FormBuilderModule, SmartFormModule } from 'commons-shared-web-ui';
+
+@NgModule({
+  imports: [
+    FormBuilderModule,
+    SmartFormModule,
+  ]
+})
+export class YourModule {}
+```
+
+---
+
+## 1. Field Selection (`lib-field-selection`)
+
+### Overview
+
+Renders a hierarchical tree of **groups → sections → fields**. Each item has a toggle that controls whether it appears in the output schema.
+
+**Key Features:**
+- **Cascading Toggles**: Disabling a group or section automatically disables all of its nested children.
+- **Locked Fields**: Fields with `readonly: true` in the schema show a padlock icon and cannot be deselected.
+- **Option-Type Toggle Hiding**: DROPDOWN, RADIO, and other option-driven fields can be marked as non-toggleable via `[hideToggleForOptionTypes]="true"`.
+
+### API Reference
+
+| Input / Output | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `[schema]` | `FormSchema` | — | **Required.** The master schema containing all possible fields. |
+| `(schemaChange)` | `EventEmitter<FormSchema>` | — | Emitted whenever a toggle changes. Returns the updated schema with `isEnabled` / `visible` flags updated. |
+| `[hideToggleForOptionTypes]` | `boolean` | `false` | When `true`, hides the enable/disable checkbox for option-driven field types (DROPDOWN, MULTI_SELECT, RADIO, AUTOCOMPLETE, CHECKBOX, MULTI_CHECKBOX, CHIP). A pre-configured badge indicator is shown instead. |
+
+### Basic Usage
+
+```html
+<lib-field-selection
+  [schema]="masterSchema"
+  (schemaChange)="onSelectionChange($event)">
+</lib-field-selection>
+```
+
+```typescript
+onSelectionChange(updated: FormSchema) {
+  this.activeSchema = updated;
+}
+```
+
+### Business-User Mode — Hiding Toggle for Option Types
+
+When a form schema contains dropdown fields (e.g., Gender, Country, Department) whose `optionConfig` is **pre-filled by the developer**, the business user should not be able to toggle those fields on/off — they should always be included.
+
+Set `[hideToggleForOptionTypes]="true"` to suppress the checkbox for DROPDOWN, RADIO, MULTI_SELECT, AUTOCOMPLETE, CHECKBOX, MULTI_CHECKBOX, and CHIP fields:
+
+```html
+<!-- Business-user configurator: hide toggle for pre-configured dropdowns -->
+<lib-field-selection
+  [schema]="masterSchema"
+  [hideToggleForOptionTypes]="true"
+  (schemaChange)="onSelectionChange($event)">
+</lib-field-selection>
+```
+
+#### What it looks like
+
+| Field Type | `hideToggleForOptionTypes="false"` (default) | `hideToggleForOptionTypes="true"` |
+| :--- | :--- | :--- |
+| `TEXT_INPUT` | ✅ Checkbox shown | ✅ Checkbox shown |
+| `DROPDOWN` | ✅ Checkbox shown | 🔒 Clock icon shown — no toggle |
+| `RADIO` | ✅ Checkbox shown | 🔒 Clock icon shown — no toggle |
+| `AUTOCOMPLETE` | ✅ Checkbox shown | 🔒 Clock icon shown — no toggle |
+
+> **Note**: Fields with `readonly: true` in the schema are always locked (padlock icon), regardless of this setting.
+
+### Full Example Component
+
+```typescript
+import { Component } from '@angular/core';
+import { FormSchema } from 'commons-shared-web-ui';
+
+@Component({
+  selector: 'app-form-selector',
+  template: `
+    <div class="selection-container">
+      <h3>Configure Form Fields</h3>
+
+      <!-- For business users: hide toggle on pre-filled option types -->
+      <lib-field-selection
+        [schema]="masterSchema"
+        [hideToggleForOptionTypes]="isBusinessUserMode"
+        (schemaChange)="onSelectionChange($event)">
+      </lib-field-selection>
+    </div>
+  `
+})
+export class SelectionExampleComponent {
+  // Developer sets this true for business-user-facing configurators
+  isBusinessUserMode = true;
+
+  masterSchema: FormSchema = {
+    entityType: 'REGISTRATION',
+    label: 'Master Registration Form',
+    formType: 'SECTION',
+    sectionConfig: {
+      children: [
+        {
+          type: 'GROUP',
+          label: 'Personal Info',
+          name: 'personal',
+          sectionConfig: {
+            children: [
+              { name: 'firstName', type: 'TEXT_INPUT', label: 'First Name' },
+              { name: 'lastName',  type: 'TEXT_INPUT', label: 'Last Name'  },
+              {
+                // Gender: developer pre-fills optionConfig → business user
+                // should not toggle this on/off, just keep it always shown
+                name: 'gender',
+                type: 'DROPDOWN',
+                label: 'Gender',
+                optionConfig: {
+                  optionList: [
+                    { label: 'Male',   code: 'M' },
+                    { label: 'Female', code: 'F' },
+                    { label: 'Other',  code: 'O' },
+                  ]
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  };
+
+  onSelectionChange(updated: FormSchema): void {
+    console.log('Schema updated:', updated);
+    this.masterSchema = updated;
+  }
+}
+```
+
+---
+
+## 2. Field Configurator (`lib-field-configurator`)
+
+### Overview
+
+A split-view tool for editing field details:
+- **Left Panel**: Tree view showing all fields from the schema.
+- **Right Panel**: A dynamically generated `SmartForm` for the currently selected field's configuration.
+
+**Key Features:**
+- **Field-Type Specific UI**: Selecting a `TEXT_INPUT` shows length and pattern constraints; a `DROPDOWN` shows API URL and static list settings.
+- **Type Switching**: Change a field type (e.g., from `shortText` to `email`) while preserving common metadata.
+- **Immutability**: Emits a fresh schema copy on every configuration change.
+- **`showOptionConfig`**: Hide the `optionConfig` section (API URL, data path, etc.) from business users.
+
+### API Reference
+
+| Input / Output | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `[schema]` | `FormSchema` | — | **Required.** The schema to be configured. |
+| `(schemaChange)` | `EventEmitter<FormSchema>` | — | Emitted whenever any field property is changed and "Apply" is clicked. |
+| `[showOptionConfig]` | `boolean` | `true` | When `false`, all `optionConfig.*` settings (API URL, data/label/value paths, etc.) are hidden from the configuration panel. |
+
+### Basic Usage
+
+```html
+<lib-field-configurator
+  [schema]="selectedSchema"
+  (schemaChange)="onConfigApplied($event)">
+</lib-field-configurator>
+```
+
+### Hiding optionConfig for Business Users
+
+When a DROPDOWN or RADIO field's `optionConfig` (e.g., `apiUrl`, `dataPath`, `labelPath`) is pre-filled by a developer in the master schema, a business user configuring the form should never see — or be able to break — those API URL settings.
+
+Set `[showOptionConfig]="false"` to strip the entire option configuration panel from the configurator:
+
+```html
+<!-- Developer mode (default): full optionConfig is visible -->
+<lib-field-configurator
+  [schema]="schema"
+  [showOptionConfig]="true"
+  (schemaChange)="onConfigApplied($event)">
+</lib-field-configurator>
+
+<!-- Business-user mode: optionConfig API fields are hidden -->
+<lib-field-configurator
+  [schema]="schema"
+  [showOptionConfig]="false"
+  (schemaChange)="onConfigApplied($event)">
+</lib-field-configurator>
+```
+
+#### What `showOptionConfig="false"` removes
+
+The following fields are hidden from the dropdown/radio/autocomplete/chip/multiSelect configuration panels:
+
+| Hidden Field | Config Key |
+| :--- | :--- |
+| Options API URL | `optionConfig.apiUrl` |
+| Data Path | `optionConfig.dataPath` |
+| Label Path | `optionConfig.labelPath` |
+| Value Path | `optionConfig.valuePath` |
+| Sort By | `optionConfig.sortBy` |
+| Response Path | `optionConfig.responsePath` |
+| Options Layout | `optionConfig.layout` |
+
+> The static **Options List (JSON)** (`optionConfig.optionList`) is **also** part of `optionConfig` and will be hidden when `showOptionConfig="false"`. If you want to allow editing the static list but not the API URL, use the `BUILDER_FIELD_TYPE_SCHEMA_MAP` token to provide a custom schema.
+
+### Full Example Component
+
+```typescript
+import { Component } from '@angular/core';
+import { FormSchema } from 'commons-shared-web-ui';
+
+@Component({
+  selector: 'app-form-configurator',
+  template: `
+    <div class="configurator-layout">
+      <lib-field-configurator
+        [schema]="configuredSchema"
+        [showOptionConfig]="isDeveloperMode"
+        (schemaChange)="onConfigApplied($event)">
+      </lib-field-configurator>
+    </div>
+  `
+})
+export class ConfiguratorComponent {
+  // false = business user, true = developer
+  isDeveloperMode = false;
+
+  configuredSchema: FormSchema = { /* ... schema from selection step ... */ };
+
+  onConfigApplied(newSchema: FormSchema): void {
+    this.configuredSchema = newSchema;
+    // Persist to backend or state management
+  }
+}
+```
+
+---
+
+## 3. Smart Form Preview (`lib-smart-form` in readOnly mode)
+
+### Overview
+
+Once the business user finishes configuring the form, you can show them a **read-only preview** of exactly how the form will look to end users. The `lib-smart-form` component now accepts a `[readOnly]` input for this purpose.
+
+### `readOnly` Input — `lib-smart-form`
+
+| Input | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `[readOnly]` | `boolean` | `false` | When `true`, all form controls are disabled (rendered as non-editable) and the action bar (submit/apply buttons) is completely hidden. |
+
+### Usage
+
+```html
+<!-- Normal (editable) mode — end user fills the form -->
+<lib-smart-form
+  [formJson]="formJson">
+</lib-smart-form>
+
+<!-- Read-only preview mode — shows the form structure without allowing input -->
+<lib-smart-form
+  [formJson]="formJson"
+  [readOnly]="true">
+</lib-smart-form>
+```
+
+### Preview within a Form Builder wizard
+
+```typescript
+import { Component } from '@angular/core';
+import { FormSchema } from 'commons-shared-web-ui';
+
+@Component({
+  selector: 'app-form-wizard',
+  template: `
+    <div class="wizard-steps">
+
+      <!-- Step 1: Field Selection -->
+      <ng-container *ngIf="currentStep === 'select'">
+        <lib-field-selection
+          [schema]="masterSchema"
+          [hideToggleForOptionTypes]="true"
+          (schemaChange)="activeSchema = $event">
+        </lib-field-selection>
+        <button (click)="currentStep = 'configure'">Next →</button>
+      </ng-container>
+
+      <!-- Step 2: Field Configuration -->
+      <ng-container *ngIf="currentStep === 'configure'">
+        <lib-field-configurator
+          [schema]="activeSchema"
+          [showOptionConfig]="false"
+          (schemaChange)="activeSchema = $event">
+        </lib-field-configurator>
+        <button (click)="currentStep = 'select'">← Back</button>
+        <button (click)="currentStep = 'preview'">Preview →</button>
+      </ng-container>
+
+      <!-- Step 3: Read-Only Preview -->
+      <ng-container *ngIf="currentStep === 'preview'">
+        <div class="preview-banner">
+          👁 Preview — This is how users will see the form
+        </div>
+        <lib-smart-form
+          [formJson]="previewFormJson"
+          [readOnly]="true">
+        </lib-smart-form>
+        <button (click)="currentStep = 'configure'">← Back</button>
+        <button (click)="onSave()">Save Form</button>
+      </ng-container>
+
+    </div>
+  `
+})
+export class FormWizardComponent {
+  currentStep: 'select' | 'configure' | 'preview' = 'select';
+
+  masterSchema: FormSchema = { /* developer-authored master schema */ };
+  activeSchema: FormSchema = this.masterSchema;
+
+  get previewFormJson(): string {
+    return JSON.stringify(this.activeSchema);
+  }
+
+  onSave(): void {
+    // Persist activeSchema to backend
+    console.log('Saving schema:', this.activeSchema);
+  }
+}
+```
+
+---
+
+## 4. End-to-End Workflow
+
+The recommended three-phase workflow for a **business-user-facing smart form configurator**:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  DEVELOPER: Authors master JSON schema with all fields,             │
+│  including pre-filled optionConfig for dropdowns/radios             │
+│  e.g. { name: 'gender', type: 'DROPDOWN',                          │
+│          optionConfig: { optionList: [...] } }                      │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│  PHASE 1 — Field Selection (lib-field-selection)                     │
+│                                                                      │
+│  Business user selects which fields appear in the live form.         │
+│  ✅ Text/number/date fields: show enable/disable toggle              │
+│  🔒 Dropdown/Radio fields: toggle hidden (hideToggleForOptionTypes)  │
+└──────────────────────────────────────────────────────────────────────┘
+                              │ schemaChange ↓
+                              ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│  PHASE 2 — Field Configuration (lib-field-configurator)              │
+│                                                                      │
+│  Business user sets label, placeholder, required flag, colSpan, etc. │
+│  API URL / option paths hidden (showOptionConfig="false")            │
+│  Cannot accidentally break pre-configured dropdown sources           │
+└──────────────────────────────────────────────────────────────────────┘
+                              │ schemaChange ↓
+                              ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│  PHASE 3 — Read-Only Preview (lib-smart-form [readOnly]="true")      │
+│                                                                      │
+│  Business user sees exactly how the form looks to end users.         │
+│  All controls are disabled. Action bar (Submit button) is hidden.    │
+└──────────────────────────────────────────────────────────────────────┘
+                              │ onSave()
+                              ▼
+                        Persist to backend
+```
+
+### Minimal Three-Phase Example
+
+```html
+<!-- Phase 1: Select fields -->
+<lib-field-selection
+  [schema]="masterSchema"
+  [hideToggleForOptionTypes]="true"
+  (schemaChange)="activeSchema = $event">
+</lib-field-selection>
+
+<!-- Phase 2: Configure field details (no optionConfig editing) -->
+<lib-field-configurator
+  [schema]="activeSchema"
+  [showOptionConfig]="false"
+  (schemaChange)="activeSchema = $event">
+</lib-field-configurator>
+
+<!-- Phase 3: Preview in read-only mode -->
+<lib-smart-form
+  [formJson]="activeSchemaJson"
+  [readOnly]="true">
+</lib-smart-form>
+```
+
+```typescript
+get activeSchemaJson(): string {
+  return JSON.stringify(this.activeSchema);
+}
+```
+
+---
+
+## 5. Advanced Customization
+
+### The `BUILDER_FIELD_TYPE_SCHEMA_MAP` Token
+
+You can override or extend the default configuration forms for specific field types by providing the `BUILDER_FIELD_TYPE_SCHEMA_MAP` token. This lets you control *exactly* which settings are editable per field type.
+
+**Use case:** Show only `label` and `required` in the configurator for all text fields — hide everything else.
+
+```typescript
+import { BUILDER_FIELD_TYPE_SCHEMA_MAP } from 'commons-shared-web-ui';
+
+const restrictedSchemaMap = {
+  shortText: {
+    entityType: 'FIELD_CONFIG',
+    label: 'Field Configuration',
+    formType: 'SECTION',
+    sectionConfig: {
+      children: [
+        { name: 'label',    type: 'TEXT_INPUT', label: 'Field Label', required: true, colSpan: 12 },
+        { name: 'required', type: 'SWITCH',     label: 'Required',    colSpan: 6 },
+      ]
+    },
+    actionBarConfig: {
+      buttons: [{
+        id: 'apply', label: 'Apply Changes', variant: 'primary',
+        alignment: 'right', action: { kind: 'emit' }
+      }]
+    }
+  },
+  // ... other types
+};
+
+@NgModule({
+  providers: [
+    {
+      provide: BUILDER_FIELD_TYPE_SCHEMA_MAP,
+      useValue: restrictedSchemaMap
+    }
+  ]
+})
+export class MyFormBuilderModule {}
+```
+
+> **Tip:** You only need to override the types you want to customize. Other types will continue to use the built-in defaults.
+
+### Combining `showOptionConfig` with `BUILDER_FIELD_TYPE_SCHEMA_MAP`
+
+If you want to **allow editing the static option list but hide the API URL** for dropdowns, provide a custom map entry for `dropdown`:
+
+```typescript
+const customDropdownSchema = {
+  dropdown: {
+    formType: 'SECTION',
+    sectionConfig: {
+      children: [
+        // Basic Settings
+        { name: 'label',    type: 'TEXT_INPUT', label: 'Label', colSpan: 12 },
+        { name: 'required', type: 'SWITCH',     label: 'Required', colSpan: 6 },
+        // Allow editing static list only — no apiUrl
+        {
+          type: 'GROUP', label: 'Dropdown Options',
+          sectionConfig: {
+            children: [
+              {
+                name: 'optionConfig.optionList',
+                type: 'TEXT_INPUT', subType: 'LONG',
+                label: 'Static Options (JSON)',
+                placeholder: '[{"label": "Yes", "code": "Y"}]',
+                colSpan: 12
+              }
+            ]
+          }
+        }
+      ]
+    },
+    actionBarConfig: {
+      buttons: [{ id: 'apply', label: 'Apply', variant: 'primary',
+                  alignment: 'right', action: { kind: 'emit' } }]
+    }
+  }
+};
+
+// Then in providers:
+{ provide: BUILDER_FIELD_TYPE_SCHEMA_MAP, useValue: customDropdownSchema }
+```
+
+In this case, use `[showOptionConfig]="true"` (default) since the custom map already contains only what you want to expose.
+
+---
+
+## 6. Field Type Support
+
+The Form Builder supports configuring all core SmartForm types:
+
+| Category | Types |
+| :--- | :--- |
+| **Text Inputs** | Short Text, Long Text, Email, Phone, Password |
+| **Numbers** | Integer, Decimal |
+| **Choice Fields** | Dropdown, Multi-Select, Radio, Checkbox, Multi-Checkbox, Chips, Autocomplete |
+| **Date / Time** | Date, Time, DateTime |
+| **Advanced** | Rich Text, File Upload, Rating (Stars), Location, Formula (Generated) |
+| **Structural** | Group, Section |
+
+---
+
+## 7. Developer vs. Business-User Mode (recommended patterns)
+
+The form builder supports two distinct usage personas. Use the inputs below consistently across your app:
+
+### Developer Mode (authoring the master schema)
+
+The developer configures everything — including API URLs for dropdowns.
+
+```html
+<lib-field-selection
+  [schema]="masterSchema"
+  [hideToggleForOptionTypes]="false">   <!-- show all toggles -->
+</lib-field-selection>
+
+<lib-field-configurator
+  [schema]="activeSchema"
+  [showOptionConfig]="true">            <!-- show optionConfig (API URL etc.) -->
+</lib-field-configurator>
+```
+
+### Business-User Mode (configuring a form instance)
+
+The business user only sees field-level settings (label, placeholder, required). Option API configuration is invisible and cannot be accidentally broken.
+
+```html
+<lib-field-selection
+  [schema]="masterSchema"
+  [hideToggleForOptionTypes]="true">    <!-- hide toggle for DROPDOWN, RADIO etc. -->
+</lib-field-selection>
+
+<lib-field-configurator
+  [schema]="activeSchema"
+  [showOptionConfig]="false">           <!-- hide optionConfig API fields -->
+</lib-field-configurator>
+
+<!-- Preview the form before saving -->
+<lib-smart-form
+  [formJson]="previewJson"
+  [readOnly]="true">                    <!-- read-only preview — no Submit button -->
+</lib-smart-form>
+```
+
+### Summary Table
+
+| Feature | Input | Developer | Business User |
+| :--- | :--- | :---: | :---: |
+| Show toggle for DROPDOWN in field-selection | `[hideToggleForOptionTypes]` | `false` | `true` |
+| Show optionConfig (API URL, paths) in configurator | `[showOptionConfig]` | `true` | `false` |
+| Make the SmartForm preview read-only | `[readOnly]` | `false` | `true` |