commons-shared-web-ui 0.0.50 → 0.0.52

package/documentation/form-builder.md

@@ -1,597 +0,0 @@
-# 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` |