@elliemae/loan-field-renderers 26.2.2

package/dist/cjs/ARCHITECTURE.md

@@ -0,0 +1,434 @@
+# Loan Field Renderers — Technical Documentation
+
+---
+
+## 1. Purpose
+
+**Loan Field Renderers** is a metadata-driven smart control system that renders loan form fields as UI components. Instead of every page manually wiring up data fetching, formatting, validation, locking, accessibility, and persistence for each field, this system encapsulates all of that behind a single declarative `<FieldRenderer>` component.
+
+A consuming page only needs to specify:
+
+- **`fieldId`** — the loan field identifier (e.g., `"FR0104"`)
+- **`rendererType`** — the desired UI control (e.g., `"text"`, `"number"`, `"dropdown"`)
+
+The system then automatically:
+
+- Fetches field metadata (format, options, read-only, lock, maxLength, description) from SSF
+- Fetches and formats the current field value for display
+- Applies the correct input mask (Phone, SSN, number, date, zip)
+- Validates user input on blur using configurable rules
+- Parses display values back to raw data and persists to the loan object
+- Manages lock/unlock, disabled, and read-only states
+- Provides Go-To-Field navigation highlighting
+- Builds ARIA accessibility attributes from field descriptions
+- Subscribes to loan change events for live refresh
+
+---
+
+## 2. Architecture & Layers
+
+The system follows a **layered architecture** with clear separation of concerns. Each layer has a single responsibility and communicates downward through well-defined interfaces.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     CONSUMER / PAGE LAYER                     │
+│  <FieldRenderer fieldId="FR0104" rendererType="number" />    │
+└──────────────────────────────────┬───────────────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    ENTRY POINT LAYER                          │
+│  FieldRenderer.tsx → RendererFactory.create(rendererType)    │
+└──────────────────────────────────┬───────────────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    RENDERER LAYER (renderer/)                 │
+│                                                              │
+│  ┌─────────────────────┐  ┌────────────────────────────────┐ │
+│  │  Specific Renderers │  │  Base Infrastructure           │ │
+│  │  ─────────────────  │  │  ──────────────────            │ │
+│  │  TextRenderer       │  │  Renderer<T> (abstract base)   │ │
+│  │  NumberRenderer     │  │  RendererValidator             │ │
+│  │  DateRenderer       │  │  Hooks (Mixin-composed)        │ │
+│  │  DropdownRenderer   │  │    ├ FieldMeta                 │ │
+│  │  ZipCodeRenderer    │  │    ├ FieldValue                │ │
+│  │  CheckboxRenderer   │  │    ├ FieldValidation           │ │
+│  │  ToggleRenderer     │  │    ├ FieldDisabled             │ │
+│  │  RadioRenderer      │  │    ├ FieldLocked               │ │
+│  │  RadioGroupRenderer │  │    ├ FieldSubscribers          │ │
+│  │  LargeTextRenderer  │  │    ├ FieldGoTo                 │ │
+│  │  AddonRenderer      │  │    └ FieldDescription          │ │
+│  └─────────────────────┘  └────────────────────────────────┘ │
+└──────────────────────────────────┬───────────────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│                  BUSINESS LOGIC LAYER (bll/)                  │
+│                                                              │
+│  BLL (Singleton Façade)                                      │
+│  ├── Formatter Factory → SSN / Phone / Number / Date / Zip  │
+│  │                        Boolean / Text / Dropdown / Regex  │
+│  ├── Validator Factory → Required / Email / Date / Zip /     │
+│  │                        MaxChar                            │
+│  ├── SSF Service (Mixin-composed)                            │
+│  │    ├ Loan    → field values, metadata, lock, collections  │
+│  │    └ LoConnect → host operations, readonly, GTF, state DD │
+│  └── Core → Logging, Exceptions, Utilities                   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Layer Breakdown
+
+| Layer           | Location                     | Responsibility                                                                                                                                                                           |
+| --------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Entry Point** | `renderer/FieldRenderer.tsx` | Single public component. Delegates to `RendererFactory` based on `rendererType`.                                                                                                         |
+| **Renderer**    | `renderer/`                  | UI rendering, event handling, ViewModel initialization. Each renderer extends the abstract `Renderer<T>` base class.                                                                     |
+| **Hooks**       | `renderer/base/hooks/`       | Composable state management classes mixed into a single `Hooks` class. Each hook handles one concern (metadata, value, validation, disabled, locked, subscribers, go-to, accessibility). |
+| **BLL**         | `bll/`                       | Business logic. Formatter and Validator factories, SSF data access, Core utilities. Acts as the single gateway between the renderer layer and external services.                         |
+| **SSF**         | `bll/ssf/`                   | Loan data operations. `Loan` mixin handles field CRUD; `LoConnect` mixin handles host-level operations (readonly status, Go-To-Field, state dropdown).                                   |
+| **Core**        | `core/`                      | Cross-cutting concerns: structured logging and exception utilities.                                                                                                                      |
+
+### Key Design Patterns
+
+| Pattern                 | Where Used                                                | Why                                                                                                                                                             |
+| ----------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Factory**             | `RendererFactory`, `FormatterFactory`, `ValidatorFactory` | Dynamic creation of renderers, formatters, and validators based on runtime type/acronym. Enables open-closed extensibility.                                     |
+| **Abstract Base Class** | `Renderer<T>`                                             | Shared initialization (`initVM`), formatting/parsing, validation, BR wrapper, and prop sanitization across all renderers.                                       |
+| **Mixin Composition**   | `Hooks`, `SSF`                                            | Avoids deep class hierarchies. Each concern is a self-contained class mixed into a combined class using `@decorators.class.Mixins`.                             |
+| **Singleton**           | `BLL`, `SSF`, `FormatterFactory`, `Core`                  | Shared instances across renderers for consistent state and performance.                                                                                         |
+| **Strategy**            | Formatters, Validators                                    | Each formatter/validator encapsulates a specific algorithm (e.g., `NumberFormatter` vs. `PhoneFormatter`). The factory selects the correct strategy at runtime. |
+| **ViewModel**           | `ViewModelT`                                              | Encapsulates all reactive state a renderer needs, decoupling UI rendering from state management.                                                                |
+
+---
+
+## 3. High-Level Design
+
+### Component Hierarchy
+
+```
+FieldRenderer (public API)
+  └─ RendererFactory.create(type)
+       └─ [SpecificRenderer].render()        ← e.g., TextRenderer
+            ├─ BRWrapper (Business Rules)     ← wraps the field for BR integration
+            │    └─ subscribes to loan change + loanUpdated events
+            ├─ AddonRenderer                  ← lock button + right addon slot
+            └─ DS Component                   ← e.g., DSInputText, DSCombobox
+                 ├─ value ← formatted via Formatter
+                 ├─ onChange → local state update + optional callback
+                 ├─ onBlur → format → validate → parse → persist to SSF
+                 ├─ disabled ← computed from metadata (readonly, locked)
+                 └─ ARIA props ← built from field description
+```
+
+### ViewModel (`ViewModelT`)
+
+Every renderer initializes a shared ViewModel through `initVM(props)`. The ViewModel contains:
+
+| Property           | Type                        | Source                                                                       |
+| ------------------ | --------------------------- | ---------------------------------------------------------------------------- |
+| `fieldMetadata`    | `FieldMetadataT`            | Fetched from SSF via `FieldMeta` hook                                        |
+| `fieldValue`       | `unknown`                   | Fetched from SSF, formatted for display                                      |
+| `setFieldValue`    | state setter                | React `useState`                                                             |
+| `isLockedState`    | `boolean`                   | SSF lock status via `FieldLocked` hook                                       |
+| `isFieldDisabled`  | `boolean`                   | Computed: `isReadonlyLoan OR (isLockField AND !isLockedState) OR isReadOnly` |
+| `isSearchedField`  | `boolean`                   | Go-To-Field highlight via `FieldGoTo` hook                                   |
+| `validationResult` | `IValidationResult \| null` | Set on blur after running validators                                         |
+| `ariaDescProps`    | `AriaDescT`                 | Built from label + field description via `FieldDescription` hook             |
+
+### Initialization Sequence (inside `useFieldInit`)
+
+```
+1. Parallel fetch via Promise.all:
+   ├─ getMetadata(fieldId)       → field format, options, readonly, lock, maxLength
+   ├─ isLoanReadonly()           → loan-level readonly status
+   ├─ getFieldLockStatus(fieldId)→ field-level lock status
+   ├─ getFieldValue(fieldId)     → raw field value from loan object
+   └─ isGoToField(fieldId)       → whether this is the Go-To-Field target
+
+2. Post-fetch processing:
+   ├─ Format raw value using FormatterFactory → display value
+   ├─ Resolve lock state from metadata.isLockField + SSF lock status
+   ├─ Set readonly state
+   ├─ Set Go-To-Field highlight state
+   └─ Build ARIA description props from label + metadata.description
+```
+
+---
+
+## 4. Sequence Diagrams
+
+### 4.1 Mount Flow — Field Appears on Screen
+
+```mermaid
+sequenceDiagram
+    participant Page as Page (Consumer)
+    participant FR as FieldRenderer
+    participant Factory as RendererFactory
+    participant TR as TextRenderer
+    participant Hooks as Hooks (Mixins)
+    participant BLL as BLL
+    participant SSF as SSF
+
+    Page->>FR: <FieldRenderer fieldId="FR0104" rendererType="text" />
+    FR->>Factory: create("text")
+    Factory-->>FR: TextRenderer.render() → FC
+
+    FR->>TR: render(props)
+    TR->>Hooks: initVM(props)
+
+    rect rgb(235, 245, 255)
+        Note over Hooks,SSF: Parallel fetch via Promise.all
+        Hooks->>SSF: getMetadata(fieldId)
+        Hooks->>SSF: getFieldValue(fieldId)
+        Hooks->>SSF: getLockStatus(fieldId)
+        Hooks->>SSF: isLoanReadonly()
+        Hooks->>SSF: isGoToField(fieldId)
+        SSF-->>Hooks: metadata, value, lock, readonly, goTo
+    end
+
+    Hooks->>BLL: formatValue(rawValue, fieldFormat)
+    BLL-->>Hooks: displayValue
+
+    Hooks->>Hooks: compute isFieldDisabled
+    Hooks->>Hooks: build ARIA props
+
+    Hooks-->>TR: ViewModel (value, metadata, disabled, locked, validation, aria)
+
+    TR->>TR: render BRWrapper → AddonRenderer → DSInputText
+    TR-->>Page: Rendered field on screen
+```
+
+### 4.2 onChange Flow — User Types
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TR as TextRenderer
+    participant VM as ViewModel (state)
+    participant Page as Page (Consumer)
+
+    User->>TR: keystroke
+    TR->>TR: clear GoToField highlight
+    TR->>VM: setFieldValue(typedValue)
+    VM-->>TR: UI re-renders with new value
+
+    opt onChange callback provided
+        TR->>Page: onChange(fieldId, parsedValue)
+    end
+```
+
+### 4.3 onBlur Flow — User Leaves Field
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TR as TextRenderer
+    participant BLL as BLL
+    participant Hooks as Hooks
+    participant SSF as SSF
+    participant Page as Page (Consumer)
+
+    User->>TR: blur (leaves field)
+
+    TR->>BLL: getFormattedValue(rawInput)
+    BLL-->>TR: formattedValue
+
+    TR->>Hooks: runValidationsOnValue(formattedValue, rules)
+
+    alt Validation fails
+        Hooks-->>TR: { isValid: false, message }
+        TR->>TR: setValidationResult → show error
+        Note over TR: STOP — do not save
+    else Validation passes
+        Hooks-->>TR: { isValid: true }
+        TR->>BLL: getParsedValue(formattedValue)
+        BLL-->>TR: parsedValue (raw for storage)
+
+        opt autoFieldSet = true (default)
+            TR->>SSF: setFieldValue(fieldId, parsedValue)
+        end
+
+        opt onBlur callback provided
+            TR->>Page: onBlur(fieldId, parsedValue)
+        end
+    end
+```
+
+### 4.4 External Change Flow — Live Sync
+
+```mermaid
+sequenceDiagram
+    participant BR as Business Rule / Other Field
+    participant SSF as SSF
+    participant BRW as BRWrapper
+    participant TR as TextRenderer
+    participant BLL as BLL
+    participant VM as ViewModel (state)
+
+    BR->>SSF: modifies loan data
+
+    alt Specific field changed
+        SSF-)BRW: loan.change event (fieldId, oldVal, newVal)
+        Note over BRW: only reacts if fieldId matches & oldVal ≠ newVal
+    else Bulk loan update
+        SSF-)BRW: loan.loanUpdated event
+    end
+
+    BRW->>TR: refreshFieldFromLoan()
+    TR->>SSF: getFieldValue(fieldId)
+    SSF-->>TR: raw value
+    TR->>BLL: formatValue(rawValue, fieldFormat)
+    BLL-->>TR: displayValue
+    TR->>VM: setFieldValue(displayValue)
+    VM-->>TR: UI re-renders with updated value
+```
+
+### Key Lifecycle Events
+
+| Event                  | What Happens                                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Mount**              | `useFieldInit` fires → parallel SSF fetches → ViewModel populated → UI renders                            |
+| **onChange**           | Local state updated immediately → optional `props.onChange` callback fired                                |
+| **onBlur**             | Format → Validate → (if invalid, show error & stop) → Parse → Persist to SSF → `props.onBlur` callback    |
+| **Loan Change Event**  | BRWrapper detects `change` event for this `fieldId` → re-fetches value from SSF → re-formats → updates UI |
+| **Loan Updated Event** | BRWrapper detects `loanUpdated` → re-fetches and refreshes all field data                                 |
+| **Lock Toggle**        | `callCalcForLock()` on SSF → toggle `isLockedState` → recompute `isFieldDisabled`                         |
+
+---
+
+## 5. Smart Control Capabilities via Field Metadata
+
+Field metadata (`FieldMetadataT`) is fetched once per field from SSF and drives virtually all behavior. Below is each metadata property and what the smart controls do with it.
+
+### 5.1 Format-Driven Rendering (`fieldFormat`)
+
+The `fieldFormat` acronym (e.g., `"D2"`, `"SS"`, `"ST"`, `"P"`) determines:
+
+| Acronym                 | Format              | Formatter Used      | Behavior                                      |
+| ----------------------- | ------------------- | ------------------- | --------------------------------------------- |
+| `SS`                    | SSN                 | `SsnFormatter`      | Masks as `***-**-1234`, parses to raw digits  |
+| `P`                     | Phone               | `PhoneFormatter`    | Formats as `(123) 456-7890`, parses to digits |
+| `I`                     | Integer             | `NumberFormatter`   | No decimal, thousands separator               |
+| `D2`–`D6`               | Decimal (2-6)       | `NumberFormatter`   | Fixed decimal places, thousands separator     |
+| `T`                     | Date                | `DateFormatter`     | Formats to `MM/DD/YYYY` or custom format      |
+| `TD`                    | DateTime            | `DateFormatter`     | Date + time formatting                        |
+| `Y`                     | Yes/No              | `BooleanFormatter`  | Converts `"Y"`/`"N"` ↔ `true`/`false`         |
+| `S`                     | String              | `TextFormatter`     | Pass-through                                  |
+| `ST`                    | State               | `DropdownFormatter` | Auto-fetches state dropdown list from SSF     |
+| `Z`                     | Zip Code            | `ZipFormatter`      | 5 or 9-digit zip formatting                   |
+| `RS`, `RI`, `RD2`–`RD6` | Read-Ahead variants | Same as base        | Used for collection/RA fields                 |
+
+The `FormatterFactory` maps acronyms to formatter instances. Each formatter implements `IFormatter<T, U>` with `format()` and `parse()` methods, enabling bidirectional conversion between display values and raw loan data.
+
+### 5.2 Renderer–Format Compatibility Validation
+
+`RendererValidator` ensures the `rendererType` is compatible with the `fieldFormat`:
+
+- **number** renderer requires numeric formats (`DECIMAL_*`, `INTEGER`)
+- **checkbox** renderer requires boolean formats (`YN`, `BOOLEAN`)
+- **date** renderer requires date formats (`DATE`, `DATETIME`)
+- **text/email** renderers accept anything except numeric, boolean, and date formats
+
+A mismatch throws an error with a diagnostic log, preventing subtle bugs from incorrect configuration.
+
+### 5.3 Dropdown Options (`fieldOptions`)
+
+- If the metadata includes `fieldOptions`, they are mapped to `{ dsId, type, label, value }` objects for the `DSCombobox` component.
+- **Special case**: When `fieldFormat === "ST"` (State), the system auto-fetches the state dropdown list from SSF via `getStateDropDownList()` and memoizes the result.
+- Consumers can also pass custom `options` via props for non-metadata-driven dropdowns.
+
+### 5.4 Lock/Unlock Field (`isLockField`)
+
+When `isLockField` is `true` in metadata:
+
+- The `AddonRenderer` displays a lock/unlock button next to the field
+- Lock status is fetched from SSF via `getLockStatus(fieldId)`
+- Toggling calls `SSF.callCalcForLock(fieldId, isLockedState)` which triggers a server-side calculation
+- **Locked fields are disabled**: `isFieldDisabled = isLockField && !isLockedState`
+
+### 5.5 Read-Only State (`isReadOnly`)
+
+Two levels of read-only are checked:
+
+- **Field-level**: `metadata.isReadOnly` — this specific field is read-only
+- **Loan-level**: `SSF.isReadOnlyLoan()` — the entire loan is in read-only mode
+
+The combined disabled state is: `isReadonlyLoan || (isLockField && !isLockedState) || isReadOnly`
+
+### 5.6 Max Length Enforcement (`maxLength`)
+
+- For **text** fields: applied directly as the HTML `maxLength` attribute
+- For **number** fields: adjusted to account for prefix, suffix, thousands separators, and decimal points. The system calculates `totalMaxLength = integerPartLength + prefixLength + decimalSeparator + decimalPlaces + suffixLength`
+
+### 5.7 Accessibility (`description`)
+
+The `description` field from metadata is used to build ARIA attributes:
+
+- If the field has a visible `label` → `aria-description` is set to the metadata description
+- If the field has no label → `aria-label` is set to the metadata description
+- This ensures screen readers always have meaningful context for every field
+
+### 5.8 Contract Path & Collection Support (`contractPath`)
+
+- Each field maps to a canonical loan contract path (e.g., `"Loan.LoanAmount"`)
+- For **collection fields**, the contract path contains a `[%]` placeholder (e.g., `"Loan.Borrowers[%].FirstName"`) which is resolved to the actual row index at runtime via `SSF.getCollectionRowIndex()`
+
+### 5.9 Nullable Fields (`isNullable`)
+
+The `isNullable` flag from metadata indicates whether a field can hold `null`/empty values. This is used in conjunction with validation rules (e.g., the `required` validator checks this).
+
+### 5.10 Validation Rules
+
+Validation is consumer-configured via `validationRules` prop but integrates with metadata:
+
+| Validator  | Trigger                                       | Behavior                            |
+| ---------- | --------------------------------------------- | ----------------------------------- |
+| `required` | Blur                                          | Fails if value is empty/null        |
+| `email`    | Blur (auto-added for `rendererType: "email"`) | Regex-based email validation        |
+| `date`     | Blur                                          | Validates date format and range     |
+| `zip`      | Blur                                          | Validates 5 or 9-digit zip format   |
+| `maxChar`  | Blur                                          | Checks against `options.charsLimit` |
+
+Validators run sequentially; the first failure stops execution and displays the error message via `validationMessage` and `hasError` props on the BR wrapper.
+
+### 5.11 Go-To-Field Highlighting
+
+The system integrates with the host application's "Go-To-Field" (GTF) navigation:
+
+- On mount, checks if this field is the GTF target via `SSF.getGTFSelectedFormDetails()`
+- If matched, sets `isSearchedField = true` → applies `withHighlight` styling on the BR wrapper
+- On user interaction (`onChange`), the highlight is cleared
+
+### 5.12 Prop Sanitization
+
+The `sanitize()` method on the base `Renderer` class filters out "controlled props" from the `extra` prop bag. This prevents consumers from accidentally overriding internally-managed props like `onChange`, `onBlur`, `value`, etc. The controlled props per renderer type are defined in `RENDERER_CONTROLLED_PROPS`.
+
+### 5.13 Live Loan Synchronization
+
+Every rendered field subscribes to two SSF events through the `BRWrapper`:
+
+- **`loan.change`** — fired when a specific field changes; if the changed field ID matches, re-fetches and re-formats the value
+- **`loan.loanUpdated`** — fired on bulk loan updates; re-fetches all field data
+
+This ensures fields stay in sync when business rules, calculations, or other UI interactions modify loan data externally.
+
+### 5.14 Auto Field Set (`autoFieldSet`)
+
+The `autoFieldSet` flag (default `true`) controls whether the renderer automatically persists the parsed value to SSF on blur. When set to `false`, the renderer only updates local state and calls the `onBlur` callback, letting the consumer handle persistence manually.
+
+---
+
+## Summary
+
+| Aspect                 | Implementation                                                |
+| ---------------------- | ------------------------------------------------------------- |
+| **Entry Point**        | `<FieldRenderer fieldId={...} rendererType={...} />`          |
+| **Renderer Selection** | Factory pattern → 12 renderer types                           |
+| **State Management**   | ViewModel pattern with React hooks composed via Mixins        |
+| **Data Access**        | SSF abstraction layer (Loan + LoConnect mixins)               |
+| **Formatting**         | Bidirectional format/parse via strategy-based formatters      |
+| **Validation**         | Pluggable validator chain via factory                         |
+| **Accessibility**      | ARIA attributes auto-generated from metadata                  |
+| **Synchronization**    | Event-driven via SSF `change` and `loanUpdated` subscriptions |
+| **Extensibility**      | Add new renderer → extend `Renderer<T>`, register in factory  |

package/dist/cjs/OVERVIEW.md

@@ -0,0 +1,229 @@
+# Loan Field Renderers — Overview
+
+## What Is It?
+
+A **metadata-driven smart control system** that renders loan form fields. Instead of each page manually handling data fetching, formatting, validation, locking, and persistence — a single component does it all.
+
+**Before (without smart controls):**
+Each page manually wires up SSF calls, formatting logic, validation, lock handling, accessibility, and event subscriptions for every field.
+
+**After (with smart controls):**
+
+```jsx
+<FieldRenderer fieldId="FR0104" rendererType="number" />
+```
+
+One line. The system handles everything else automatically.
+
+---
+
+## What Does It Do Automatically?
+
+| Capability        | Description                                                                      |
+| ----------------- | -------------------------------------------------------------------------------- |
+| **Data Fetch**    | Fetches field metadata + current value from SSF on mount                         |
+| **Formatting**    | Applies the correct display format (currency, phone, SSN, date, zip)             |
+| **Input Masking** | Enforces input patterns (phone mask, SSN mask, number mask)                      |
+| **Validation**    | Runs configurable validation rules on blur (required, email, date, zip, maxChar) |
+| **Persistence**   | Parses display value back to raw data and saves to loan on blur                  |
+| **Lock/Unlock**   | Shows lock button, manages lock state, disables field when locked                |
+| **Read-Only**     | Respects both field-level and loan-level read-only states                        |
+| **Live Sync**     | Subscribes to loan events — auto-refreshes when data changes externally          |
+| **Accessibility** | Builds ARIA attributes from field description metadata                           |
+| **Go-To-Field**   | Highlights the field when navigated to via Go-To-Field                           |
+
+---
+
+## Supported Renderer Types
+
+| Type         | UI Component        | Use Case                                                  |
+| ------------ | ------------------- | --------------------------------------------------------- |
+| `text`       | Text input          | Names, addresses, general text (supports Phone/SSN masks) |
+| `number`     | Masked number input | Amounts, rates, percentages                               |
+| `date`       | Date picker         | Dates with configurable format                            |
+| `dropdown`   | Combobox            | Picklists, state selection                                |
+| `zipcode`    | Autocomplete input  | Zip codes with geo-lookup                                 |
+| `checkbox`   | Checkbox            | Yes/No boolean fields                                     |
+| `toggle`     | Toggle switch       | On/Off boolean fields                                     |
+| `radio`      | Single radio button | One option in a group                                     |
+| `radiogroup` | Radio button group  | Multiple exclusive options                                |
+| `largetext`  | Textarea            | Comments, large text with char counter                    |
+| `button`     | Button              | Action triggers                                           |
+| `email`      | Text input          | Email with built-in email validation                      |
+
+---
+
+## How It Works — 3 Phases
+
+### Phase 1: Mount — "Set Up the Field"
+
+```
+  Consumer passes fieldId + rendererType
+           │
+           ▼
+  RendererFactory picks the right renderer
+           │
+           ▼
+  Parallel SSF calls (all at once):
+  ┌─────────────────────────────────┐
+  │  • Field metadata (format,      │
+  │    options, readonly, lock,     │
+  │    maxLength, description)      │
+  │  • Current field value          │
+  │  • Lock status                  │
+  │  • Loan readonly status         │
+  │  • Go-To-Field status           │
+  └─────────────────────────────────┘
+           │
+           ▼
+  Build ViewModel → Render UI
+```
+
+### Phase 2: User Interaction — "Handle Input"
+
+```
+  User types → onChange
+  ┌────────────────────────────┐
+  │  Update local display value │
+  │  Fire optional callback     │
+  └────────────────────────────┘
+
+  User leaves field → onBlur
+  ┌────────────────────────────┐
+  │  1. Format the value        │
+  │  2. Validate                │
+  │     └─ Invalid? Show error, │
+  │        stop here            │
+  │  3. Parse to raw value      │
+  │  4. Save to loan via SSF    │
+  │  5. Fire optional callback  │
+  └────────────────────────────┘
+```
+
+### Phase 3: External Changes — "Stay in Sync"
+
+```
+  Business rule or another field changes loan data
+           │
+           ▼
+  SSF fires "change" or "loanUpdated" event
+           │
+           ▼
+  Field re-fetches its value from SSF
+           │
+           ▼
+  Re-formats and updates display automatically
+```
+
+---
+
+## Architecture — 3 Layers
+
+```
+┌───────────────────────────────────────────┐
+│          RENDERER LAYER                    │
+│  UI components, event handling, ViewModel  │
+│  12 specific renderers + shared base class │
+├───────────────────────────────────────────┤
+│          BUSINESS LOGIC LAYER              │
+│  Formatters (10 types) — format ↔ parse    │
+│  Validators (5 types) — validate on blur   │
+│  SSF Service — loan data access & events   │
+├───────────────────────────────────────────┤
+│          DATA ACCESS LAYER (SSF)           │
+│  Field metadata, values, lock status       │
+│  Loan readonly, Go-To-Field, state list    │
+│  Event subscriptions (change, loanUpdated) │
+└───────────────────────────────────────────┘
+```
+
+**Key design decisions:**
+
+- **Factory Pattern** — Renderers, formatters, and validators are created dynamically by type
+- **Mixin Composition** — Hooks and SSF combine focused classes instead of deep inheritance
+- **ViewModel Pattern** — All reactive state lives in one object, decoupled from UI
+
+---
+
+## How Metadata Drives Everything
+
+When a field is loaded, its metadata from SSF determines behavior automatically:
+
+```
+  fieldFormat: "D2"  →  NumberFormatter with 2 decimal places
+  fieldFormat: "SS"  →  SSN mask (***-**-1234)
+  fieldFormat: "ST"  →  Auto-fetch state dropdown list
+  fieldFormat: "P"   →  Phone mask ((123) 456-7890)
+
+  isLockField: true  →  Show lock button, disable when locked
+  isReadOnly: true   →  Disable the field
+  isReadonlyLoan     →  Loan-level check — if loan is disabled, all fields disable
+  maxLength: 50      →  Enforce character limit
+  description: "..." →  Set ARIA label/description
+  fieldOptions: [...] → Populate dropdown choices
+```
+
+No conditional logic needed in consuming pages — the metadata configures the control.
+
+---
+
+## Consumer API — Quick Reference
+
+### Basic Usage
+
+```jsx
+// Simple text field
+<FieldRenderer fieldId="FR0001" rendererType="text" label="First Name" />
+
+// Number with label
+<FieldRenderer fieldId="FR0104" rendererType="number" label="Loan Amount" />
+
+// Dropdown
+<FieldRenderer fieldId="FR0200" rendererType="dropdown" label="State" />
+
+// Date
+<FieldRenderer fieldId="FR0300" rendererType="date" label="Closing Date" />
+```
+
+### With Optional Props
+
+```jsx
+<FieldRenderer
+  fieldId="FR0104"
+  rendererType="number"
+  label="Loan Amount"
+  onBlur={(fieldId, value) => console.log('saved', value)}
+  onChange={(fieldId, value) => console.log('changed', value)}
+  validationRules={[{ type: 'required', message: 'Amount is required' }]}
+  autoFieldSet={true} // auto-persist on blur (default: true)
+  isDisable={false} // consumer-controlled disable
+  forceRefresh={refreshFlag} // trigger re-fetch from SSF
+/>
+```
+
+### Common Props
+
+| Prop              | Type        | Purpose                                           |
+| ----------------- | ----------- | ------------------------------------------------- |
+| `fieldId`         | `string`    | **(Required)** SSF field identifier               |
+| `rendererType`    | `string`    | **(Required)** Which UI control to render         |
+| `label`           | `string`    | Field label text                                  |
+| `onBlur`          | `function`  | Callback after value is validated and parsed      |
+| `onChange`        | `function`  | Callback on every value change                    |
+| `validationRules` | `array`     | Custom validation rules                           |
+| `autoFieldSet`    | `boolean`   | Auto-save to SSF on blur (default: `true`)        |
+| `isDisable`       | `boolean`   | Consumer-controlled disable override              |
+| `forceRefresh`    | `boolean`   | Toggle to force re-fetch from SSF                 |
+| `extra`           | `object`    | Pass-through props to the underlying DS component |
+| `rightAddon`      | `ReactNode` | Custom content to the right of the input          |
+
+---
+
+## Adding a New Renderer (Extensibility)
+
+1. Create `NewRenderer.tsx` extending `Renderer<T>`
+2. Define props type in `renderer/types.ts`
+3. Register in `renderer/factory/index.ts`
+4. Add controlled props to `bll/constants.ts` (if applicable)
+
+The factory pattern means zero changes to existing renderers or the `FieldRenderer` entry point.