@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/field-skills/AutoComplete.mdrules

@@ -0,0 +1,117 @@
+---
+description: Field component skill: AutoComplete
+alwaysApply: false
+---
+
+# Skill: AutoComplete
+
+Typeahead / autocomplete search field that fetches options from a data page or associated list, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a typeahead input that shows a dropdown of matching options as the user types. Options are loaded from a Pega data page or associated list. The stored value is always the **key** of the selected option, while the displayed text is the resolved **value** (label). Delegates read-only to `TextInput` with the resolved label.
+
+## Pega Metadata
+
+- **Pega Name:** `AutoComplete`
+- **Type / Subtype:** `Field` / `Picklist`
+- **Registration key:** `AutoComplete` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `listType` | `string` | `'associated'` or `'datapage'` |
+| `datasource` | `any` | Datasource (array for associated, string name for datapage) |
+| `columns` | `any[]` | Column config for extracting key/value from datasource records |
+| `parameters` | `any` (optional) | Query parameters for data page calls |
+| `deferDatasource` | `boolean` (optional) | If true, transform `datasourceMetadata` into datapage config |
+| `datasourceMetadata` | `any` (optional) | Metadata for deferred datasource |
+| `onRecordChange` | `any` (optional) | Callback fired on selection change |
+| `additionalProps` | `object` (optional) | Extra props passed through to the autocomplete |
+
+## Behavioral Contract
+
+1. **Options state:** Maintain `options` as `Array<{key: string, value: string}>`.
+2. **Input value state:** Maintain `inputValue` (string) — the typed text in the input box. Separate from `selectedValue` (the displayed label of the selected item).
+3. **Datasource change detection:** Use `isDeepEqual` to compare incoming `datasource` with cached `theDatasource`. If different, update `theDatasource` to trigger `useEffect`.
+4. **Deferred datasource transformation:** Same pattern as Dropdown — if `deferDatasource && datasourceMetadata?.datasource?.name`:
+   - Set `listType = 'datapage'`, `datasource = datasourceName`
+   - Flatten `parameters`
+   - Build `columns` from `propertyForDisplayText` / `propertyForValue`
+5. **Column preprocessing:** Strip leading `.` from column `value` fields.
+6. **Loading options (`associated`):** In `useEffect` watching `theDatasource`, call `Utils.getOptionList(props, pConn.getDataObject(''))`.
+7. **Loading options (`datapage`):** In mount-time `useEffect` (when NOT in display mode), call `getDataPage(datasource, parameters, context)`. Map results using `getDisplayFieldsMetaData(columns)`.
+8. **Selected value resolution:** On render, find `selectedValue` by matching `value` (stored key) against `options`:
+   ```
+   index = options.findIndex(el => el.key === value)
+   selectedValue = index > -1 ? options[index].value : value
+   ```
+9. **On selection change:**
+   - `val = newValue ? newValue.key : ''`
+   - Commit via `handleEvent(actionsApi, 'changeNblur', propName, val)`.
+   - If `onRecordChange`, call it with the event.
+10. **On input change:** Update `inputValue` state (typed text, does NOT commit to store).
+11. **Read-only:** Resolve the option label (`options.find(opt => opt.key === value)?.value`), delegate to `TextInput` with resolved label: `return <TextInput {...props} value={theValAsString} />`.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw stored value (key string).
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Resolve the display label from options and delegate: `return <TextInput {...props} value={theValAsString} />`.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant | Outlined |
+| Dropdown popup | Opens below input, shows filtered options |
+| Input | Combobox pattern — types to filter, click arrow to open all |
+| Error state | Red border + red helper text |
+| Label | Floating label |
+| Placeholder | From `placeholder` prop |
+
+**Autocomplete behavior:**
+- The controlled `value` is the selected option object (or `selectedValue` string).
+- The controlled `inputValue` is the typed text.
+- `getOptionLabel` returns `option.value` (the display label).
+- `isOptionEqualToValue` returns `option.value` (used for selection matching).
+
+## Edge Cases & Special Logic
+
+- `inputValue || selectedValue` — the input displays `inputValue` when typing, `selectedValue` when a selection has been made and nothing is typed.
+- When `value` is a key that does not yet exist in `options` (e.g., options still loading), display `value` directly as `selectedValue`.
+- Options array uses `{key, value}` — `key` = stored value, `value` = display label.
+- `context` is obtained from `pConn.getContextName()` and passed to `getDataPage`.
+
+## Dependencies
+
+- `isDeepEqual` from `fast-deep-equal/react`.
+- `Utils.getOptionList()` from `../../helpers/utils`.
+- `getDataPage()` from `../../helpers/data_page`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- Typeahead/autocomplete UI widget.
+
+## Design System Mapping
+
+**UI control type:** Combobox / typeahead autocomplete input.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input>` + custom dropdown list with filtering |
+| MUI | `<Autocomplete>` with `renderInput` using `<TextField>` |
+| Ant Design | `<AutoComplete>` or `<Select showSearch>` |
+| Chakra UI | `<Combobox>` (Downshift) or third-party |

package/templates/react-sdk-reference/.cursor/rules/skills/field-skills/CancelAlert.mdrules

@@ -0,0 +1,208 @@
+---
+description: Field component skill: CancelAlert
+alwaysApply: false
+---
+
+# Skill: CancelAlert
+
+Cancel confirmation dialog that offers the user a choice between going back or discarding/deleting the current case/action.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a full-screen modal overlay with a confirmation dialog. Presents two actions: "Go back" (continue working) and "Discard" (cancel/delete). Handles different cancellation scenarios: standard case creation stage, local action, bulk action, data object, and reverse coexistence. Shows a snackbar notification on delete failure.
+
+## Pega Metadata
+
+- **Pega Name:** `CancelAlert`
+- **Type / Subtype:** Internal modal/alert
+- **Registration key:** `CancelAlert` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `heading` | `string` | Modal dialog heading text |
+| `content` | `string` | Modal dialog body/description text |
+| `itemKey` | `string` | The container item ID for the case being cancelled (aliased as `containerItemID`) |
+| `hideDelete` | `boolean` | Whether to hide/disable the delete option |
+| `isDataObject` | `boolean` | Whether this is cancelling a data object (not a work item) |
+| `skipReleaseLockRequest` | `any` | Whether to skip lock release when removing container item |
+| `dismiss` | `Function` | Callback to close/dismiss this dialog (called with `true` to indicate confirmed dismiss) |
+
+## Behavioral Contract
+
+### Setup
+
+```typescript
+const actionsAPI = getPConnect().getActionsApi()
+const containerManagerAPI = getPConnect().getContainerManager()
+const isLocalAction = getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION)
+const isBulkAction = getPConnect()?.options?.isBulkAction
+const isReverseCoexistence = PCore.getCoexistenceManager().getBroadcastUtils().isReverseCoexistenceCaseLoaded()
+```
+
+### State
+
+- `buttonsState`: tracks disabled state per button: `{ saveAndClose: false, delete: false }`
+- `showSnackbar`: boolean — whether to show the failure snackbar
+- `snackbarMessage`: string — error message text
+
+### "Go back" button (`leftButton`)
+
+Always calls `dismiss()` (no argument = don't confirm). If `isReverseCoexistence`:
+```
+broadCastUtils.setCallBackFunction(null)
+broadCastUtils.setIsDirtyDialogActive(false)
+```
+
+### "Discard" button (`rightButton`) — `cancelHandler()`
+
+Decision tree (evaluated in order):
+
+1. **Reverse coexistence:**
+   ```
+   dismiss(true)
+   PCore.getPubSubUtils().publish(REVERSE_COEXISTENCE_EVENTS.HANDLE_DISCARD)
+   ```
+
+2. **Standard case in create stage** (`!isDataObject && !isLocalAction && !isBulkAction`):
+   - Disable delete button
+   - Call `actionsAPI.deleteCaseInCreateStage(containerItemID, hideDelete)`
+   - `.then()`: publish `EVENT_CANCEL`
+   - `.catch()`: show snackbar with `'Delete failed.'`
+   - `.finally()`: re-enable delete button, call `dismiss(true)`
+
+3. **Local action** (`isLocalAction`):
+   ```
+   dismiss(true)
+   actionsAPI.cancelAssignment(containerItemID, false)
+   ```
+
+4. **Bulk action** (`isBulkAction`):
+   ```
+   dismiss(true)
+   actionsAPI.cancelBulkAction(containerItemID)
+   ```
+
+5. **Data object or other** (default):
+   ```
+   dismiss(true)
+   containerManagerAPI.removeContainerItem({ containerItemID, skipReleaseLockRequest })
+   ```
+
+### Snackbar dismissal
+
+`handleSnackbarClose`: if `reason === 'clickaway'`, return (do not close). Otherwise `setShowSnackbar(false)`.
+
+### Localization
+
+All visible text is localized via `PCore.getLocaleUtils().getLocaleValue(key, 'ModalContainer')`:
+- `'Go back'`
+- `'Discard'`
+- `heading` prop value
+- `content` prop value
+- `'Delete failed.'`
+
+## Visual Specifications
+
+Derived from `CancelAlert.css`:
+
+### Full-screen overlay (`.cancel-alert-background`)
+```css
+.cancel-alert-background {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  height: 100%;
+  width: 100%;
+  background-color: var(--modal-background-color);
+  position: fixed;
+  z-index: 9999;
+  top: 0;
+  left: 0;
+}
+```
+
+### Dialog box (`.cancel-alert-top`)
+```css
+.cancel-alert-top {
+  display: table;
+  margin: auto;
+  min-width: 550px;
+  background-color: var(--modal-top-color);
+  border: 1px solid var(--modal-border-color);
+  border-radius: 10px;
+  padding: 20px;
+  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color);
+}
+```
+
+### Content layout
+
+```
+.cancel-alert-top
+  <h3>{heading}</h3>
+  <div>
+    <p>{content}</p>
+  </div>
+  <div class="action-controls">
+    Grid container spacing=4, justifyContent='space-between'
+      Grid → leftButton ("Go back", secondary/outlined)
+      Grid → rightButton ("Discard", primary/contained, can be disabled)
+```
+
+### Button styles
+
+| Button | Style | Color |
+|--------|-------|-------|
+| Go back | Contained | Secondary |
+| Discard | Contained | Primary |
+
+### Snackbar
+
+- `autoHideDuration: 3000ms`
+- Shows `snackbarMessage` (e.g., `'Delete failed.'`)
+- Close icon button to dismiss manually
+
+**CSS variables used:**
+- `--modal-background-color`: semi-transparent overlay (e.g., `rgba(0,0,0,0.5)`)
+- `--modal-top-color`: dialog background (e.g., white or app background)
+- `--modal-border-color`: dialog border
+- `--modal-box-shadow-color`: dialog shadow color
+
+**CSS companion file required:** Import `./CancelAlert.css`.
+
+## Edge Cases & Special Logic
+
+- **`buttonsState`** tracks loading state to prevent double-clicks during async delete.
+- `dismiss(true)` vs `dismiss()`: passing `true` signals confirmed cancellation; no arg means the user chose to continue.
+- `isBulkAction` is accessed via `getPConnect()?.options?.isBulkAction` — a private property, marked with `@ts-ignore`.
+- All action handling is async — the UI must show loading/disabled state during `deleteCaseInCreateStage`.
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — for text localization.
+- `PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION`, `PUB_SUB_EVENTS.EVENT_CANCEL`, etc.
+- `PCore.getPubSubUtils().publish()` — for pub/sub events.
+- `PCore.getCoexistenceManager().getBroadcastUtils()` — for reverse coexistence handling.
+- Button, Grid, IconButton, Snackbar components.
+- Close icon.
+- `./CancelAlert.css` — must be imported.
+
+## Design System Mapping
+
+**UI control type:** Full-screen modal confirmation dialog.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<div class="cancel-alert-background">` + `<div class="cancel-alert-top">` + CSS from above |
+| MUI | `<Button>`, `<Grid>`, `<Snackbar>`, `<IconButton>`, fixed overlay `<div>` |
+| Ant Design | `<Modal>` or custom overlay |
+| Chakra UI | `<Modal>` or `<AlertDialog>` |

package/templates/react-sdk-reference/.cursor/rules/skills/field-skills/Checkbox.mdrules

@@ -0,0 +1,163 @@
+---
+description: Field component skill: Checkbox
+alwaysApply: false
+---
+
+# Skill: Checkbox
+
+Checkbox field supporting single boolean toggle, multi-selection mode, and optional card-style variant.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders one or more checkboxes. Supports three usage modes: (1) a single boolean checkbox, (2) a multi-select list of checkboxes bound to a reference list, and (3) a card-style selectable grid. Display mode shows the true/false label rather than the raw boolean.
+
+## Pega Metadata
+
+- **Pega Name:** `Checkbox`
+- **Type / Subtype:** `Field` / `Boolean`
+- **Registration key:** `Checkbox` (mapped to `CheckboxComponent` import in `component-map.ts`)
+
+## Props (component-specific)
+
+> Note: `Checkbox` uses `Omit<PConnFieldProps, 'value'>` with its own `value?: boolean`. Import type as:
+> ```typescript
+> import type { PConnFieldProps } from '@pega/sdk-react';
+> ```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `boolean` (optional) | Checked state for single-mode checkbox |
+| `caption` | `string` (optional) | Label shown next to the single checkbox (not the group label) |
+| `trueLabel` | `string` (optional) | Display text when `value` is `true` (used in display modes) |
+| `falseLabel` | `string` (optional) | Display text when `value` is `false` (used in display modes) |
+| `selectionMode` | `string` (optional) | `'multi'` — enables multi-selection mode from a datasource list |
+| `datasource` | `any` (optional) | Options source for multi/card modes |
+| `selectionKey` | `string` (optional) | The property path used as the key in selection list |
+| `selectionList` | `any` (optional) | Property path for the reference list (multi mode) |
+| `primaryField` | `string` | Primary display field for multi/card mode |
+| `readonlyContextList` | `any` | Array of currently selected items (for multi/card read-only display) |
+| `referenceList` | `string` | Reference list property path |
+| `variant` | `string` (optional) | `'card'` — renders options as selectable card grid |
+| `hideFieldLabels` | `boolean` | Hide field labels inside card variant |
+| `additionalProps` | `any` | Extra props passed to card or checkbox |
+| `imagePosition` | `string` | Card image position |
+| `imageSize` | `string` | Card image size |
+| `showImageDescription` | `string` | Whether to show image description |
+| `renderMode` | `string` | `'ReadOnly'` — sets read-only mode alongside `readOnly` prop |
+| `image` | `string` | Image field path for card variant |
+
+## Behavioral Contract
+
+### Common
+
+1. **Read-only determination:** `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`.
+2. **Local state:** Maintain `checked` (boolean) from `value` prop. `useEffect` watching `value` → `setChecked(value)`.
+3. **Reference list init:** On mount (`useEffect` watching `pConn`), if `referenceList.length > 0 && !readOnlyMode`, call `pConn.setReferenceList(selectionList)` and `updateNewInstuctions(pConn, selectionList)`.
+
+### Variant: Single checkbox (default)
+
+Render a single checkbox with:
+- `checked={checked}`
+- `onChange={!readOnly ? handleChange : undefined}`
+- `onBlur={!readOnly ? handleBlur : undefined}`
+- Label = `caption` (next to checkbox)
+- Group label = `label` (above, hidden if `hideLabel`)
+- **On change:** `handleEvent(actionsApi, 'changeNblur', propName, event.target.checked)` — passes boolean.
+- **On blur:** `pConn.getValidationApi().validate(event.target.checked)`.
+
+### Variant: Multi-select (`selectionMode === 'multi'`)
+
+Render a list of checkboxes from `datasource.source`:
+- Each option: `key` from `selectionKey` extraction, `text`/`value` as label.
+- `checked` per option: `selectedvalues.some(data => data[dataField] === element.key)` where `dataField = selectionKey.split('.')[1]`.
+- **On change per checkbox:**
+  - If checked: `insertInstruction(pConn, selectionList, selectionKey, primaryField, { id, primary })`.
+  - If unchecked: `deleteInstruction(pConn, selectionList, selectionKey, { id, primary })`.
+  - `pConn.clearErrorMessages({ property: selectionList, category: '', context: '' })`.
+- Layout: vertical column (`display: flex, flexDirection: column`).
+
+### Variant: Card (`variant === 'card'`)
+
+Render a heading (`<h4>`) + CSS Grid + `SelectableCard` component:
+- Grid: `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, `gridAutoRows: '1fr'`, `gap: '0.5rem'`.
+- `SelectableCard` props:
+  - `type='checkbox'`
+  - `dataSource={datasource}`
+  - `readOnlyList={selectedvalues}` (for read-only display)
+  - `readOnly={renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly}`
+  - `recordKey={selectionKey?.split('.').pop()}`
+  - `cardLabel={primaryField.split('.').pop()}`
+  - `image` config from `imagePosition`, `imageSize`, `showImageDescription`, `image` props
+  - `showNoValue={(readOnlyMode) && selectedvalues.length === 0}`
+  - `onChange`: calls `handleCheckboxChange` on each item
+  - `onBlur`: `pConn.getValidationApi().validate(selectedvalues, selectionList)`
+
+## Display Mode Rendering
+
+Display mode uses `caption` (not `label`) and shows true/false label:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} variant='stacked' />`
+
+## Read-Only Rendering
+
+Single mode: Set `readOnly` on checkbox element; disable `onChange`/`onBlur`.
+Multi/Card mode: `readOnlyMode` flag prevents `insertInstruction`/`deleteInstruction`; cards show `readOnlyList`.
+
+## Visual Specifications
+
+### Standard / Multi-select
+
+| Property | Value |
+|----------|-------|
+| Checkbox size | Default (24px) |
+| Label placement | End (right of checkbox) |
+| Group label | `<legend>` above group, hidden if `hideLabel` |
+| Layout | Single: single row. Multi: vertical column |
+| Helper text | Below group |
+| Error state | Red text/border on helper |
+| Disabled/readOnly | Greyed out, pointer-events none |
+
+**CSS-only:**
+```css
+.checkbox-group { display: flex; flex-direction: column; gap: 4px; }
+.checkbox-label { display: flex; align-items: center; gap: 8px; cursor: pointer; }
+input[type="checkbox"]:disabled { opacity: 0.38; }
+```
+
+### Card Variant
+
+| Property | Value |
+|----------|-------|
+| Layout | CSS Grid `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, row height equal (`1fr`), gap `0.5rem` |
+| Heading | `<h4>` with `marginTop: 0, marginBottom: 0` |
+
+## Edge Cases & Special Logic
+
+- **`handleCheckboxChange`** (card mode): Finds the selected item from `datasource.source` by matching `item[recordKey] === e.target.id`, then calls `insertInstruction`/`deleteInstruction`.
+- `updateNewInstuctions` is called on mount to sync reference list state.
+- `clearErrorMessages` is called after every multi-select change.
+- For card read-only: use `readOnlyList` prop populated from `selectedvalues`.
+
+## Dependencies
+
+- `insertInstruction`, `deleteInstruction`, `updateNewInstuctions` from `../../helpers/instructions-utils` — for multi-selection reference list management.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `getComponentFromRegistry('SelectableCard')` for card variant.
+
+## Design System Mapping
+
+**UI control type:** Single or multi-select checkbox (boolean or list).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="checkbox">` with `<label>` |
+| MUI | `<Checkbox>` in `<FormControlLabel>`, `<FormGroup>` |
+| Ant Design | `<Checkbox>` / `<Checkbox.Group>` |
+| Chakra UI | `<Checkbox>` / `<CheckboxGroup>` |

package/templates/react-sdk-reference/.cursor/rules/skills/field-skills/Currency.mdrules

@@ -0,0 +1,111 @@
+---
+description: Field component skill: Currency
+alwaysApply: false
+---
+
+# Skill: Currency
+
+Currency input field with locale-aware symbol, decimal separator, and thousands separator. Supports ISO currency codes.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a numeric input formatted as a currency value. Displays the correct currency symbol, decimal separator, and thousands separator for the given ISO currency code. Uses a numeric formatting library to handle locale-aware input. Shows formatted read-only values in display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `Currency`
+- **Type / Subtype:** `Field` / `Decimal-Currency`
+- **Registration key:** `Currency` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`, `'GBP'`) |
+| `allowDecimals` | `boolean` | — | Whether to allow decimal input. If `false`, `decimalScale=0`. If `true`, fixed 2 decimal places shown. |
+
+All other props from `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Currency symbols:** Derive the currency symbol, decimal indicator, and digit group separator from the `currencyISOCode` using locale-aware lookup:
+   - Call locale-aware currency formatter for the ISO code to determine: `theCurrencySymbol`, `theDecimalIndicator`, `theDigitGroupSeparator`.
+   - Default: `$`, `.`, `,` (USD/en-US).
+4. **Numeric format config:**
+   - `prefix`: the currency symbol
+   - `decimalSeparator`: `theDecimalIndicator`
+   - `thousandSeparator`: `theDigitGroupSeparator`
+   - `decimalScale`: `allowDecimals !== false ? 2 : 0`
+   - `fixedDecimalScale`: `allowDecimals` — forces exactly 2 decimal places when `true`
+   - `valueIsNumericString`: `true`
+5. **On value change:** Update local `values` state with the raw numeric string (from the numeric format library's callback).
+6. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, values)`.
+7. **Read-only:** Set `readOnly: true` on the input. Visual style switches to flat/borderless. The formatted display value (from `format()` helper) is shown rather than raw numeric.
+
+## Display Mode Rendering
+
+Format the value before display using a currency formatter with `currencyISOCode`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />` where `formattedValue = format(value, 'currency', currencyOptions)`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+The `formattedValue` uses the locale and currency from `currencyISOCode` to produce a localized string (e.g., `$1,234.56`).
+
+## Read-Only Rendering
+
+Keep the numeric format input but set `readOnly: true` on the input element. Switch the visual variant to flat/borderless. The `onBlur` handler is omitted (`onBlur={!readOnly ? currOnBlur : undefined}`).
+
+## Visual Specifications
+
+| Property | Standard (editable) | Read-only |
+|----------|---------------------|-----------|
+| Width | 100% | 100% |
+| Size | Small | Small |
+| Variant | Outlined | Standard (flat) |
+| Prefix | Currency symbol (e.g., `$`) | Currency symbol |
+| Alignment | Left-aligned text | Left-aligned |
+| Decimal places | 2 (when `allowDecimals`) | 2 |
+| Error state | Red border + red helper text | — |
+| Placeholder | From `placeholder` prop | — |
+
+## Edge Cases & Special Logic
+
+- **EUR uses `nl-NL` locale:** When `currencyISOCode === 'EUR'`, use NL locale for symbol/separator lookup.
+- **Fallback:** If `currencyISOCode` lookup fails, fall back to USD (`$`, `.`, `,`).
+- **`allowDecimals` vs `fixedDecimalScale`:** `fixedDecimalScale` is only applied when `allowDecimals` is explicitly `true`. It forces `decimalScale=2` and shows trailing zeros.
+- The input stores the raw numeric string (e.g., `'1234.56'`) in state and in the Pega store — not the formatted display string.
+- `data-test-id` is passed via `inputProps` on the inner input element.
+
+## Dependencies
+
+- A numeric formatting library (e.g., `react-number-format`'s `NumericFormat`) — handles locale-aware separators, prefix, and decimal scale.
+- `format()` from `../../helpers/formatters` — for display mode value formatting.
+- `getCurrencyCharacters(currencyISOCode)` — returns `{ theCurrencySymbol, theDecimalIndicator, theDigitGroupSeparator }`.
+- `getCurrencyOptions(currencyISOCode)` — returns `{ locale, style: 'currency', currency }` for the `format()` call.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+**For CSS-only / design-system-agnostic implementations:**
+- The numeric format library handles the input masking. Use any numeric format library that supports prefix, decimal separator, and thousands separator configuration.
+- Alternatively, implement manually: on change, strip non-numeric chars, insert separators, prepend symbol.
+
+## Design System Mapping
+
+**UI control type:** Currency / numeric formatted input with prefix symbol.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` + custom numeric formatting logic |
+| MUI | `NumericFormat` (from `react-number-format`) with `customInput={TextField}` |
+| Ant Design | `<InputNumber prefix="$" precision={2} />` |
+| Chakra UI | `<NumberInput>` + custom formatting |