@elliemae/loan-field-renderers 26.2.2

package/dist/cjs/utils/dateHelper.js

@@ -0,0 +1,65 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dateHelper_exports = {};
+__export(dateHelper_exports, {
+  calNextBusinessDay: () => calNextBusinessDay,
+  calNextPresumedRecievedDay: () => calNextPresumedRecievedDay,
+  convertToLocalDateTime: () => convertToLocalDateTime,
+  formatDateForBr: () => formatDateForBr,
+  formatISODate: () => formatISODate,
+  isHoliday: () => isHoliday,
+  isSunday: () => isSunday
+});
+module.exports = __toCommonJS(dateHelper_exports);
+var import_moment = __toESM(require("moment"));
+const isSunday = (momentDateObj) => (0, import_moment.default)(momentDateObj).format("dddd") === "Sunday";
+const isHoliday = (momentDateObj, holidays) => holidays.includes((0, import_moment.default)(momentDateObj).format("YYYY-MM-DD"));
+const calNextBusinessDay = (dayCound, momentDateObj, holidays) => {
+  const nextDateObj = momentDateObj.add(dayCound, "d");
+  if (isSunday(nextDateObj) || isHoliday(nextDateObj, holidays)) {
+    calNextBusinessDay(dayCound, nextDateObj, holidays);
+  }
+  return nextDateObj;
+};
+const calNextPresumedRecievedDay = (dayCount, momentDateObj, holidays) => {
+  const nextPresumedRecievedDay = isSunday(momentDateObj) || isHoliday(momentDateObj, holidays) ? calNextBusinessDay(1, momentDateObj, holidays) : momentDateObj;
+  for (let index = 0; index < dayCount; index += 1) {
+    calNextBusinessDay(1, nextPresumedRecievedDay, holidays);
+  }
+  return nextPresumedRecievedDay;
+};
+const formatISODate = (date) => (0, import_moment.default)(date).utc().format("MM/DD/YYYY");
+const formatDateForBr = (date, format) => {
+  if (!date) return date;
+  if (format === "ISO") {
+    return (0, import_moment.default)(date).format("YYYY-MM-DD");
+  }
+  return (0, import_moment.default)(date).format("MM/DD/YYYY");
+};
+const convertToLocalDateTime = (date) => date ? import_moment.default.utc(date).local().format("MM/DD/YYYY [at] hh:mm A") : date;

package/dist/esm/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  |