commons-shared-web-ui 0.0.55 → 0.0.56

package/documentation/form-components.md

@@ -1,384 +0,0 @@
-# Form Components
-
-The `FormComponentsModule` provides a set of customizable, theme-aware form components. All components support `ControlValueAccessor` for seamless integration with Angular Reactive and Template-driven forms.
-
-## Module Import
-
-```typescript
-import { FormComponentsModule } from 'commons-shared-web-ui';
-
-@NgModule({
-  imports: [FormComponentsModule]
-})
-export class YourModule {}
-```
-
----
-
-## Input (`lib-input`)
-
-A text input field supporting multiple types (text, number, email, password, tel, url, textarea).
-
-### Selector
-`<lib-input>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `InputConfig` | — | Configuration object for all properties |
-| `labels` | `InputLabels` | — | i18n labels |
-| `type` | `InputType` | `'text'` | Input type: `text`, `number`, `email`, `password`, `tel`, `url`, `textarea` |
-| `label` | `string` | `''` | Field label |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `readonly` | `boolean` | `false` | Read-only state |
-| `maxLength` | `number` | — | Maximum character length |
-| `minLength` | `number` | — | Minimum character length |
-| `min` | `number` | — | Minimum numeric value |
-| `max` | `number` | — | Maximum numeric value |
-| `pattern` | `string` | — | Validation pattern |
-| `errorMessage` | `string` | — | Error message to display |
-| `helperText` | `string` | — | Helper text below the field |
-| `rows` | `number` | — | Rows for textarea type |
-| `prefixIcon` | `string \| IconObject` | — | Icon before input |
-| `suffixIcon` | `string \| IconObject` | — | Icon after input |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `valueChange` | `EventEmitter<any>` | Emitted when value changes |
-| `blur` | `EventEmitter<void>` | Emitted on blur |
-| `focus` | `EventEmitter<void>` | Emitted on focus |
-
-### Usage
-
-```html
-<lib-input
-  [config]="{ type: 'text', label: 'Name', placeholder: 'Enter your name', required: true }"
-  [labels]="{ label: 'Full Name', placeholder: 'Enter name' }"
-  (valueChange)="onNameChange($event)">
-</lib-input>
-```
-
----
-
-## Dropdown (`lib-dropdown`)
-
-A select/dropdown component with single or multi-select, search, virtual scrolling, and keyboard navigation.
-
-### Selector
-`<lib-dropdown>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `DropdownConfig` | — | Configuration object |
-| `labels` | `DropdownLabels` | — | i18n labels |
-| `options` | `DropdownOption[]` | `[]` | Array of selectable options |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `label` | `string` | `''` | Field label |
-| `multiple` | `boolean` | `false` | Enable multi-select |
-| `searchable` | `boolean` | `false` | Enable search filtering |
-| `clearable` | `boolean` | `false` | Show clear button |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-
-### `DropdownOption` Interface
-
-```typescript
-interface DropdownOption {
-  value: any;
-  label: string;
-  disabled?: boolean;
-  icon?: string | { type: 'material' | 'fontawesome' | 'img'; value: string };
-}
-```
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `selectionChange` | `EventEmitter<any>` | Emitted on selection change |
-
-### Usage
-
-```html
-<lib-dropdown
-  [config]="{ options: items, label: 'Country', searchable: true, clearable: true }"
-  [labels]="{ placeholder: 'Select a country', searchPlaceholder: 'Search...' }"
-  (selectionChange)="onCountryChange($event)">
-</lib-dropdown>
-```
-
----
-
-## Checkbox (`lib-checkbox`)
-
-A checkbox component supporting single and group modes.
-
-### Selector
-`<lib-checkbox>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `CheckboxConfig` | — | Configuration object |
-| `labels` | `CheckboxLabels` | — | i18n labels |
-| `label` | `string` | `''` | Checkbox label |
-| `checked` | `boolean` | `false` | Checked state |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `indeterminate` | `boolean` | `false` | Indeterminate state |
-| `options` | `CheckboxOption[]` | `[]` | Group options |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'accent' \| 'warn'` | `'primary'` | Color theme |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `change` | `EventEmitter<boolean>` | Emitted when checked state changes |
-| `groupChange` | `EventEmitter<CheckboxOption[]>` | Emitted when group selection changes |
-
-### Usage
-
-```html
-<!-- Single checkbox -->
-<lib-checkbox
-  [config]="{ label: 'Accept Terms', required: true }"
-  (change)="onAccept($event)">
-</lib-checkbox>
-
-<!-- Checkbox group -->
-<lib-checkbox
-  [config]="{ label: 'Select interests', options: interestOptions }"
-  (groupChange)="onInterestsChange($event)">
-</lib-checkbox>
-```
-
----
-
-## Radio (`lib-radio`)
-
-A radio button group component.
-
-### Selector
-`<lib-radio>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `RadioConfig` | — | Configuration object |
-| `labels` | `RadioLabels` | — | i18n labels |
-| `options` | `RadioOption[]` | `[]` | Radio options |
-| `label` | `string` | `''` | Group label |
-| `value` | `any` | — | Selected value |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'warning' \| 'danger' \| 'success' \| 'accent' \| 'warn' \| string` | `'primary'` | Radio theme color |
-| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
-
-### `RadioOption` Interface
-
-```typescript
-interface RadioOption {
-  value: any;
-  label: string;
-  disabled?: boolean;
-}
-```
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `selectionChange` | `EventEmitter<any>` | Emitted when selection changes |
-
-### Usage
-
-```html
-<lib-radio
-  [config]="{ label: 'Gender', options: genderOptions, layout: 'horizontal' }"
-  [labels]="{ label: 'Select Gender' }"
-  (selectionChange)="onGenderChange($event)">
-</lib-radio>
-```
-
----
-
-## Toggle (`lib-toggle`)
-
-A slide toggle / switch component.
-
-### Selector
-`<lib-toggle>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `ToggleConfig` | — | Configuration object |
-| `labels` | `ToggleLabels` | — | i18n labels |
-| `label` | `string` | `''` | Toggle label |
-| `checked` | `boolean` | `false` | Toggle state |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'warning' \| 'danger' \| 'success' \| string` | `'primary'` | Track checked color |
-| `uncheckedColor` | `string` | — | Unchecked track color |
-| `checkedColor` | `string` | — | Checked track color |
-| `thumbColor` | `string` | — | Thumb color |
-| `toggleWidth` | `string` | — | Toggle width |
-| `toggleHeight` | `string` | — | Toggle height |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `change` | `EventEmitter<boolean>` | Emitted when toggled |
-
-### Usage
-
-```html
-<lib-toggle
-  [config]="{ label: 'Dark Mode', checked: isDarkMode }"
-  (change)="onToggleDarkMode($event)">
-</lib-toggle>
-```
-
----
-
-## Datepicker (`lib-datepicker`)
-
-A date picker component supporting single date and date range selection.
-
-### Selector
-`<lib-datepicker>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `DatePickerConfig` | — | Configuration object |
-| `labels` | `DatepickerLabels` | — | i18n labels |
-| `label` | `string` | `''` | Field label |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `minDate` | `Date` | — | Minimum selectable date |
-| `maxDate` | `Date` | — | Maximum selectable date |
-| `isRange` | `boolean` | `false` | Enable date range mode |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `dateChange` | `EventEmitter<Date>` | Emitted on single date change |
-| `rangeChange` | `EventEmitter<{start: Date, end: Date}>` | Emitted on range change |
-
-### Usage
-
-```html
-<!-- Single date -->
-<lib-datepicker
-  [config]="{ label: 'Start Date', placeholder: 'Pick a date', required: true }"
-  (dateChange)="onDateChange($event)">
-</lib-datepicker>
-
-<!-- Date range -->
-<lib-datepicker
-  [config]="{ label: 'Date Range', isRange: true }"
-  [labels]="{ startDateLabel: 'From', endDateLabel: 'To' }"
-  (rangeChange)="onRangeChange($event)">
-</lib-datepicker>
-```
-
----
-
-## Search (`lib-search`)
-
-A search input with built-in debounce and clear button support.
-
-### Selector
-`<lib-search>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `FilterSearchConfig` | — | Configuration object |
-| `labels` | `SearchLabels` | — | i18n labels |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `label` | `string` | `''` | Field label |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `debounceMs` | `number` | `300` | Debounce time in milliseconds |
-| `clearable` | `boolean` | `true` | Show clear button |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `search` | `EventEmitter<string>` | Emitted on search (debounced) |
-| `clear` | `EventEmitter<void>` | Emitted when search is cleared |
-
-### Usage
-
-```html
-<lib-search
-  [config]="{ placeholder: 'Search users...', debounceTime: 500, clearable: true }"
-  (search)="onSearch($event)"
-  (clear)="onClear()">
-</lib-search>
-```
-
----
-
-## Theming
-
-All form components support theming via CSS variables and SCSS mixins.
-
-### SCSS Mixin Setup
-
-Include the theme mixin in your application's global `styles.scss`:
-
-```scss
-@use 'commons-shared-web-ui/src/lib/modules/form-components/form-components.theme' as forms;
-
-html, body {
-  @include forms.form-components-theme();
-}
-```
-
-### Customizing Theme
-
-Pass a configuration map to override defaults:
-
-```scss
-@include forms.form-components-theme((
-  primary-color: #ff0000,
-  input-border-radius: 8px
-));
-```
-
-### Key CSS Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--cc-input-bg` | `#FEFEFE` | Input background color |
-| `--cc-input-border-radius` | `0.4375rem` | Input border radius |
-| `--cc-input-border-color` | `#BDC1C6` | Input border color |
-| `--cc-input-focus-border-color` | `#1A73E8` | Focus border color |
-| `--cc-dropdown-bg` | `#FEFEFE` | Dropdown background color |
-| `--cc-dropdown-height` | `2.5rem` | Dropdown trigger height |
-| `--cc-checkbox-checked-color` | `#1A73E8` | Checkbox checked color |
-
-### Inline Style Overrides
-
-All components accept style customization properties (`width`, `height`, `borderRadius`, `fontSize`, `backgroundColor`, `borderColor`, etc.) via their respective `config` objects. These are applied as inline styles with `!important` for precedence.

package/documentation/form-field-configuration.md

@@ -1,250 +0,0 @@
-# Form Field Configuration Module
-
-The `FormFieldConfigurationModule` provides a single component, `lib-form-field-configuration`, that lets an **end user** decide — per field and per section — what is **Visible** and what is **Mandatory** in a Smart Form, without touching the underlying schema by hand.
-
-It takes a `FormSchema` (the same schema format used by `SmartFormModule`) as input and produces a **modified copy** of that schema on demand. It is designed to be dropped inside a `cc-confirmation-modal` (a "Configure fields" dialog) on any page that creates/edits an entity such as a Beneficiary or Donor.
-
-> The component only edits two things: **visibility** (`isEnabled` / `visible`) and **mandatory** (`required`). It never changes labels, validation, options, or layout — that is the job of the richer [`lib-field-configurator`](./form-builder.md).
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [How it works](#how-it-works)
-- [API Reference](#api-reference)
-- [Locking fields (non-editable visibility / mandatory)](#locking-fields-non-editable-visibility--mandatory)
-- [Input → Output schema](#input--output-schema)
-- [Behaviour rules](#behaviour-rules)
-- [Translating labels](#translating-labels)
-- [Styling / theming](#styling--theming)
-- [FAQ](#faq)
-
----
-
-## Installation
-
-Import `FormFieldConfigurationModule` (and, typically, `ConfirmationModalModule`) into your Angular module:
-
-```typescript
-import {
-  FormFieldConfigurationModule,
-  ConfirmationModalModule,
-} from 'commons-shared-web-ui';
-
-@NgModule({
-  imports: [
-    FormFieldConfigurationModule,
-    ConfirmationModalModule,
-  ],
-})
-export class BeneficiaryModule {}
-```
-
----
-
-## Quick Start
-
-Put the component inside your "Configure fields" modal and read the result back on confirm using a template reference and `getUpdatedSchema()`.
-
-```html
-<button (click)="openConfigure = true">Configure fields</button>
-
-<cc-confirmation-modal
-  [isOpen]="openConfigure"
-  [config]="{
-    title: 'Configure form fields',
-    subtitle: 'KYC Onboarding Form',
-    confirmButton: { label: 'Save changes', type: 'primary' },
-    size: 'md'
-  }"
-  (confirm)="onSaveFieldConfig()"
-  (cancel)="openConfigure = false"
-  (close)="openConfigure = false"
->
-  <lib-form-field-configuration
-    #fieldConfig
-    [schema]="formSchema"
-    [translate]="translateFn"
-  />
-</cc-confirmation-modal>
-```
-
-```typescript
-import { ViewChild } from '@angular/core';
-import { FormFieldConfigurationComponent, FormSchema } from 'commons-shared-web-ui';
-
-export class BeneficiaryPage {
-  openConfigure = false;
-  formSchema: FormSchema = /* your master schema */;
-
-  @ViewChild('fieldConfig') fieldConfig!: FormFieldConfigurationComponent;
-
-  // Optional: wire your i18n instant() so labels aren't raw keys
-  translateFn = (key: string) => this.translate.instant(key);
-
-  onSaveFieldConfig(): void {
-    const updated = this.fieldConfig.getUpdatedSchema();
-    if (updated) {
-      this.formSchema = updated;      // hand back the modified schema
-      // persist it / feed it to <lib-smart-form>, etc.
-    }
-    this.openConfigure = false;
-  }
-}
-```
-
-The dialog chrome (title, "Cancel" / "Save changes" buttons, scrolling body) is provided by `cc-confirmation-modal`. `lib-form-field-configuration` renders only the legend and the configurable field tree.
-
----
-
-## How it works
-
-1. You pass a `FormSchema` via `[schema]`.
-2. The component **deep-clones** the schema internally, so your object is **never mutated**.
-3. It walks the schema and renders a collapsible tree:
-   - Every `GROUP` / `SUBFIELDS` / section becomes a **section row** (with a visibility toggle and an `x/y visible` count).
-   - Every leaf field (including those wrapped in a `ROW`) becomes a **field row** with a `Mandatory` checkbox and a visibility toggle.
-4. The user toggles visibility / mandatory.
-5. When you call `getUpdatedSchema()`, the current selections are written back onto the clone and a fresh copy is returned.
-
----
-
-## API Reference
-
-| Input / Output / Method | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `[schema]` | `FormSchema` | — | **Required.** The schema to configure. Deep-cloned internally; never mutated. |
-| `[translate]` | `(key: string) => string` | `undefined` | Optional label translator (e.g. ngx-translate `instant`). Applied to section and field labels at render time. |
-| `[showLegend]` | `boolean` | `true` | Show the "👁 Visible / ✻ Mandatory (only if visible)" legend row. |
-| `getUpdatedSchema()` | `() => FormSchema \| null` | — | **Method.** Returns a fresh, modified copy of the schema with the current visibility/mandatory choices applied. Returns `null` if no schema has been loaded. Call it from your modal's confirm handler. |
-
-The component is `OnPush` and self-contained — it does **not** emit a live change event. Read the result on demand via `getUpdatedSchema()`.
-
----
-
-## Locking fields (non-editable visibility / mandatory)
-
-Some fields must always be present — for example, you can't hide **Full Name** on a Beneficiary form. Mark them in the schema with two flags added to `FieldConfig`:
-
-| Flag | Effect in the configurator |
-| :--- | :--- |
-| `lockVisibility: true` | The visibility toggle is replaced by a 🔒 lock icon. The field/section is always visible and cannot be turned off (including via a parent section's cascade). |
-| `lockMandatory: true` | The `Mandatory` checkbox is disabled. Whatever `required` value the schema shipped with is preserved. |
-
-```jsonc
-{
-  "name": "fullName",
-  "label": "BENEFICIARY_MANAGEMENT.BENEFICIARY_MASTER.FIELD.FULL_NAME",
-  "type": "TEXT_INPUT",
-  "required": true,
-  "lockVisibility": true,   // can never be hidden
-  "lockMandatory": true     // required can never be unset
-}
-```
-
-Both flags work on **sections** too (put them on the `GROUP`/`SUBFIELDS` field). `lockVisibility` on a section keeps the whole section visible.
-
-> `lockVisibility` / `lockMandatory` are **configurator-only** flags. They are independent of `readonly`, which controls the input's editable state in the actual rendered Smart Form.
-
----
-
-## Input → Output schema
-
-The component maps its two controls onto standard Smart Form flags, so the output plugs straight back into `<lib-smart-form>`:
-
-| UI control | Written to `FieldConfig` |
-| :--- | :--- |
-| Visibility toggle (field) | `isEnabled`, `visible` (both `true`/`false`) |
-| Visibility toggle (section) | `isEnabled`, `visible`, and `disabled` on the section's field |
-| Mandatory checkbox | `required` |
-
-Smart Form renders a field only when `isEnabled !== false`, so a hidden field (`isEnabled: false`) disappears for end users.
-
-**Example — before:**
-
-```jsonc
-{ "name": "middleName", "label": "...MIDDLE_NAME", "type": "TEXT_INPUT" }
-```
-
-**After the user hides it:**
-
-```jsonc
-{ "name": "middleName", "label": "...MIDDLE_NAME", "type": "TEXT_INPUT",
-  "isEnabled": false, "visible": false, "required": false }
-```
-
----
-
-## Behaviour rules
-
-- **Mandatory only if visible.** When a field is hidden, its `Mandatory` checkbox is disabled and the output `required` is forced to `false`. Re-showing the field leaves it non-mandatory until the user re-checks it.
-- **Section cascade.** Turning a section's visibility off hides every field and sub-section inside it. Turning it back on re-shows every **non-locked** descendant.
-- **Dependent-field cascade.** A field that declares a dependency on another field via `optionConfig.dependencies.parentDataCode` can only be visible while its parent is visible. Hiding the parent **hides the dependent field too, transitively**, and disables the dependent's toggle until the parent is shown again. (Example: `city → state → country`; hiding **Country** hides both **State** and **City**; hiding **State** hides **City**.) Dependents are not force-shown when the parent reappears — the user turns them back on — so the invariant "a dependent is never visible without its parent" always holds. A `lockVisibility` field is never force-hidden this way.
-- **Locks always win.** A locked field/section is never affected by its own toggle or a parent's cascade.
-- **Non-destructive.** The `[schema]` you pass in is deep-cloned; it is never mutated. `getUpdatedSchema()` returns an independent copy and is idempotent (safe to call multiple times).
-- **Structure preserved.** `ROW` wrappers, nested `GROUP`s, `allowMulti` repeaters, `optionConfig`, validation, etc. all pass through untouched — only visibility/mandatory flags change.
-
----
-
-## Translating labels
-
-Schemas usually store i18n **keys** (e.g. `BENEFICIARY_MANAGEMENT.BENEFICIARY_MASTER.FIELD.FULL_NAME`). Pass a `translate` function to render human-readable labels in the tree:
-
-```typescript
-translateFn = (key: string) => this.translate.instant(key);
-```
-
-```html
-<lib-form-field-configuration [schema]="schema" [translate]="translateFn" />
-```
-
-If `translate` is omitted, the raw label (or `name`) is shown. Translation is display-only — the output schema keeps the original keys.
-
----
-
-## Styling / theming
-
-The toggle and checkbox are **self-contained** (drawn in the module's own CSS, not the generic `lib-toggle` / `lib-checkbox`) so they stay compact and aligned in the dense row. Everything ships neutral defaults and is themeable via CSS custom properties — the screenshot's exact colours are **reference only**. Override any of these on a parent element:
-
-| Variable | Purpose | Default |
-| :--- | :--- | :--- |
-| `--ffc-toggle-on-bg` | Visibility toggle when ON | `#2f9e6f` (green) |
-| `--ffc-toggle-off-bg` | Visibility toggle when OFF | `#cbd2d9` |
-| `--ffc-toggle-width` / `--ffc-toggle-height` | Toggle pill size | `38px` / `22px` |
-| `--ffc-check-on-bg` | Mandatory checkbox when checked | `#d97757` |
-| `--ffc-check-border` | Mandatory checkbox border (unchecked) | `#c3c9d0` |
-| `--ffc-section-header-bg` | Section header background | `#f6f7f8` |
-| `--ffc-section-label-color` | Section title colour | `#1f2933` |
-| `--ffc-count-color` | `x/y visible` counter colour | `#7b8794` |
-| `--ffc-field-bg` / `--ffc-field-hover-bg` | Field row background / hover | `#ffffff` / `#f8fafc` |
-| `--ffc-field-label-color` | Field label colour | `#1f2933` |
-| `--ffc-eye-color` / `--ffc-eye-off-color` | Visible / hidden eye icon | `#6b7280` / `#b0b6be` |
-| `--ffc-lock-color` | Lock icon colour | `#9aa2ab` |
-| `--ffc-asterisk-color` | Legend mandatory asterisk | `#d97757` |
-
-Example — recolour the toggle to your brand:
-
-```css
-lib-form-field-configuration {
-  --ffc-toggle-on-bg: #1a73e8;
-  --ffc-check-on-bg: #1a73e8;
-}
-```
-
----
-
-## FAQ
-
-**Does it emit changes live?**
-No. It exposes `getUpdatedSchema()` so you decide when to read the result (typically the modal's `confirm`). This keeps change detection cheap and avoids re-emitting the full schema on every click.
-
-**Can I use it with a STEPPER form?**
-Yes. Stepper `GROUP`s are rendered as top-level sections just like `SECTION` forms.
-
-**What happens to fields I never touch?**
-They keep whatever `isEnabled` / `visible` / `required` they had in the input schema (fields default to visible when those flags are absent).
-
-**How do I mark a field as un-hideable?**
-Add `lockVisibility: true` to it in the schema. Add `lockMandatory: true` to freeze its required state.