@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/.ai-common/skills/field-skills/Checkbox.md

@@ -0,0 +1,358 @@
+# 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                                    |
+
+## Component Skeleton
+
+Follow this exact structure. The export name is **`CheckboxComponent`** (not `Checkbox`) to avoid collision with the design system's Checkbox widget.
+
+```typescript
+import { useState, useEffect } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import {
+  insertInstruction,
+  deleteInstruction,
+  updateNewInstuctions,
+} from '../../helpers/instructions-utils';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+// ── Props interface ──────────────────────────────────────────
+// Note: Omit 'value' from PConnFieldProps — Checkbox uses boolean, not string
+interface CheckboxProps extends Omit<PConnFieldProps, 'value'> {
+  value?: boolean;
+  caption?: string;
+  trueLabel?: string;
+  falseLabel?: string;
+  selectionMode?: string;
+  datasource?: any;
+  selectionKey?: string;
+  selectionList?: any;
+  primaryField: string;
+  readonlyContextList: any;
+  referenceList: string;
+  variant?: string;
+  hideFieldLabels: boolean;
+  additionalProps: any;
+  imagePosition: string;
+  imageSize: string;
+  showImageDescription: string;
+  renderMode: string;
+  image: string;
+}
+
+// ── Styles (design-system agnostic) ──────────────────────────
+// .checkbox-column  → display: flex, flexDirection: column
+// .selectable-card-grid → display: grid, gridTemplateColumns: repeat(auto-fit, minmax(min(100%, 40ch), 1fr)),
+//                          gridAutoRows: 1fr, gap: 0.5rem
+
+// ── Component ────────────────────────────────────────────────
+export default function CheckboxComponent(props: CheckboxProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const SelectableCard = getComponentFromRegistry('SelectableCard');
+
+  // 2. Destructure props — note alias: readonlyContextList → selectedvalues
+  const {
+    getPConnect, label, caption, value, readOnly, testId,
+    required, disabled, status, helperText, validatemessage,
+    displayMode, hideLabel, trueLabel, falseLabel,
+    selectionMode, datasource, selectionKey, selectionList,
+    primaryField, referenceList,
+    readonlyContextList: selectedvalues,
+    variant, hideFieldLabels, additionalProps,
+    imagePosition, imageSize, showImageDescription, renderMode, image,
+  } = props;
+
+  // 3. Derived flags
+  const readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. PConnect setup
+  const thePConn = getPConnect();
+  const actionsApi = thePConn.getActionsApi();
+  const propName = (thePConn.getStateProps() as any).value;
+
+  // 5. State
+  const [checked, setChecked] = useState<any>(false);
+
+  // 6. useEffect: sync checked state from value prop — deps: [value]
+  useEffect(() => { setChecked(value); }, [value]);
+
+  // 7. useEffect: init reference list on mount — deps: [thePConn]
+  //    Guard: referenceList?.length > 0 && !readOnlyMode
+  //    Calls: thePConn.setReferenceList(selectionList)
+  //           updateNewInstuctions(thePConn, selectionList)
+
+  // 8. Display mode returns (uses caption, not label!)
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} variant="stacked" />;
+  }
+
+  // 9. Event handlers — see Behavioral Contract for each variant
+
+  // 10. Branch: card variant (variant === 'card')
+  //     → see Behavioral Contract "Card" section
+  //     Return early with heading + grid + SelectableCard
+
+  // 11. Branch: multi-select (selectionMode === 'multi')
+  //     → see Behavioral Contract "Multi-select" section
+  //     Build list of checkbox controls from datasource.source
+
+  // 12. Branch: single checkbox (default)
+  //     → see Behavioral Contract "Single checkbox" section
+  //     Single FormControlLabel with checked={checked}
+
+  // 13. Main return: wrapper with group label + checkbox(es) + helper text
+  //     Error state: status === 'error'
+  //     Group label: {label}, hidden if hideLabel
+  //     Helper text: helperTextToDisplay
+  return (
+    <FormWrapper required={required} error={status === 'error'}>
+      {!hideLabel && <GroupLabel>{label}</GroupLabel>}
+      <CheckboxGroup>{/* theCheckbox from step 11 or 12 */}</CheckboxGroup>
+      <HelperText>{helperTextToDisplay}</HelperText>
+    </FormWrapper>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Common
+
+1. **Read-only determination:** `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`.
+2. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+3. **Local state:** Maintain `checked` (boolean) initialized to `false`. `useEffect` watching `[value]` → `setChecked(value)`.
+4. **Reference list init:** `useEffect` watching `[thePConn]` — if `referenceList?.length > 0 && !readOnlyMode`, call `thePConn.setReferenceList(selectionList)` and `updateNewInstuctions(thePConn, selectionList)`.
+5. **`handleCheckboxChange(event, item)`** — shared by card and internally:
+   ```
+   if (event.target.checked) {
+     insertInstruction(thePConn, selectionList, selectionKey, primaryField, item);
+   } else {
+     deleteInstruction(thePConn, selectionList, selectionKey, item);
+   }
+   thePConn.clearErrorMessages({ property: 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`:
+
+- Extract `dataField`: `selectionKey?.split?.('.')[1]`.
+- For each `element` in `datasource.source`:
+  - `checked`: `selectedvalues?.some?.(data => data[dataField] === element.key)`
+  - Label: `element.text ?? element.value`
+  - **On change:** `handleChangeMultiMode(event, element)`:
+    ```
+    if (event.target.checked) {
+      insertInstruction(thePConn, selectionList, selectionKey, primaryField, {
+        id: element.key,
+        primary: element.text ?? element.value,
+      });
+    } else {
+      deleteInstruction(thePConn, selectionList, selectionKey, {
+        id: element.key,
+        primary: element.text ?? element.value,
+      });
+    }
+    thePConn.clearErrorMessages({ property: selectionList, category: '', context: '' });
+    ```
+  - **On blur:** `thePConn.getValidationApi().validate(selectedvalues, selectionList)`
+  - `data-testid`: `${testId}:${element.value}`
+- Layout: vertical column (`display: flex, flexDirection: column`).
+
+### Variant: Card (`variant === 'card'`)
+
+Return early (before multi/single logic) with heading + CSS Grid + `SelectableCard`:
+
+- Build `commonProps`:
+  ```
+  const actions = thePConn.getActionsApi();
+  const commonProps = {
+    ...additionalProps,
+    className: 'standard',
+    disabled,
+    readOnly,
+    onClick: (actions as any).onClick,
+  };
+  ```
+- Grid: `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, `gridAutoRows: '1fr'`, `gap: '0.5rem'`.
+- `SelectableCard` props:
+  - `{...commonProps}`, `testId`, `displayMode`, `getPConnect`
+  - `type='checkbox'`
+  - `dataSource={datasource}`
+  - `readOnly={renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly}`
+  - `recordKey={selectionKey?.split('.').pop()}`
+  - `cardLabel={primaryField.split('.').pop()}`
+  - `readOnlyList={selectedvalues}`
+  - `hideFieldLabels={hideFieldLabels}`
+  - `showNoValue={(readOnlyMode) && selectedvalues.length === 0}`
+  - `image` config object:
+    ```
+    image={{
+      imagePosition,
+      imageSize,
+      showImageDescription,
+      imageField: image?.split('.').pop(),
+      imageDescription: (thePConn?.getRawMetadata()?.config as any)
+        .imageDescription?.split('.').pop(),
+    }}
+    ```
+  - `onChange`: stop propagation, find item from `datasource.source` by matching `item[recordKey] === e.target.id`, call `handleCheckboxChange`:
+    ```
+    onChange={(e) => {
+      e.stopPropagation();
+      const recordKey = selectionKey?.split('.').pop();
+      const selectedItem = datasource?.source?.find(
+        item => item[recordKey] === e.target.id
+      ) ?? {};
+      handleCheckboxChange(e, {
+        id: selectedItem[recordKey],
+        primary: selectedItem[recordKey],
+      });
+    }}
+    ```
+  - `onBlur`: `() => thePConn.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
+
+- **Export name is `CheckboxComponent`** (not `Checkbox`) to avoid collision with the design system's checkbox widget import.
+- **Display mode uses `caption`** (not `label`) for the field name. This is unique to Checkbox.
+- **`readonlyContextList`** is destructured with alias `selectedvalues` — use `selectedvalues` everywhere in the component body.
+- **`handleCheckboxChange`** (card mode): Calls `e.stopPropagation()` before processing. Finds the selected item from `datasource.source` by matching `item[recordKey] === e.target.id`.
+- `updateNewInstuctions` is called on mount to sync reference list state.
+- `clearErrorMessages` is called after every multi-select change.
+- Card variant returns early (before multi/single branch logic).
+- Multi-select `onBlur` validates with both `selectedvalues` and `selectionList` as arguments.
+
+## 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/.ai-common/skills/field-skills/Currency.md

@@ -0,0 +1,230 @@
+# 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';
+```
+
+## Component Skeleton
+
+Follow this exact structure. Replace `<NumericFormatInput>` and `<TextFieldWidget>` with equivalents from your chosen design system / numeric format library.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { getCurrencyCharacters, getCurrencyOptions } from './currency-utils';
+
+// ── Props interface ──────────────────────────────────────────
+interface CurrencyProps extends PConnFieldProps {
+  currencyISOCode?: string;
+  allowDecimals: boolean;
+}
+
+// ── Component ────────────────────────────────────────────────
+export default function Currency(props: CurrencyProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel,
+    currencyISOCode = 'USD', placeholder, allowDecimals,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 4. Derived values
+  const helperTextToDisplay = validatemessage || helperText;
+  const testProps: any = { 'data-test-id': testId };
+
+  // 5. State
+  const [values, setValues] = useState(value.toString());
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setValues(value.toString()); }, [value]);
+
+  // 7. Currency symbol lookup
+  const theSymbols = getCurrencyCharacters(currencyISOCode);
+  const theCurrSym = theSymbols.theCurrencySymbol;
+  const theCurrDec = theSymbols.theDecimalIndicator;
+  const theCurrSep = theSymbols.theDigitGroupSeparator;
+
+  // 8. Formatted value for display modes (computed eagerly, before display mode check)
+  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+  const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+
+  // 9. Read-only prop object
+  let readOnlyProp = {};
+  if (readOnly) {
+    readOnlyProp = { readOnly: true };
+  }
+
+  // 10. Currency format config object
+  const currencyProp = {
+    prefix: theCurrSym,
+    decimalSeparator: theCurrDec,
+    thousandSeparator: theCurrSep,
+  };
+
+  // 11. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant="stacked" />;
+  }
+
+  // 12. Event handlers
+  function currOnBlur() {
+    handleEvent(actions, 'changeNblur', propName, values);
+  }
+  const handleChange = (val) => { setValues(val.value); };
+
+  // 13. Main render — numeric format input
+  //     Key props to pass to your numeric format component:
+  //     - valueIsNumericString: true
+  //     - value: values
+  //     - ...currencyProp (prefix, decimalSeparator, thousandSeparator)
+  //     - decimalScale: allowDecimals !== false ? 2 : 0
+  //     - fixedDecimalScale: allowDecimals
+  //     - onValueChange: (val) => handleChange(val)
+  //     - onBlur: !readOnly ? currOnBlur : undefined
+  //     - variant: readOnly ? 'standard' : 'outlined'
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error'
+  //     - inputProps: { ...readOnlyProp, inputProps: { ...testProps } }
+  return <NumericFormatInput ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` with deps **`[value]`** → `setValues(value.toString())`.
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+4. **Test ID prop:** Build `testProps = { 'data-test-id': testId }` — passed via `inputProps` on the inner input element.
+5. **Currency symbols:** Derive from `getCurrencyCharacters(currencyISOCode)`:
+   - Returns `{ theCurrencySymbol, theDecimalIndicator, theDigitGroupSeparator }`.
+   - Default (USD): `$`, `.`, `,`.
+6. **Formatted value:** Computed eagerly (before display mode check):
+   ```
+   const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+   const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+   ```
+7. **Read-only prop:** `let readOnlyProp = {}; if (readOnly) readOnlyProp = { readOnly: true };`
+8. **Currency format config:**
+   ```
+   const currencyProp = {
+     prefix: theCurrSym,
+     decimalSeparator: theCurrDec,
+     thousandSeparator: theCurrSep,
+   };
+   ```
+9. **Numeric format props (merged at render):**
+   - `valueIsNumericString: true`
+   - `value: values` (local state string)
+   - `...currencyProp` (spread prefix + separators)
+   - `decimalScale: allowDecimals !== false ? 2 : 0`
+   - `fixedDecimalScale: allowDecimals`
+   - `onValueChange: (val) => setValues(val.value)`
+   - `onBlur: !readOnly ? currOnBlur : undefined`
+   - `variant: readOnly ? 'standard' : 'outlined'`
+   - Input slot/props: `{ ...readOnlyProp, inputProps: { ...testProps } }`
+10. **On value change:** `setValues(val.value)` — raw numeric string from the format library's callback object.
+11. **On blur:** `handleEvent(actions, 'changeNblur', propName, values)` — commits local state to store.
+
+## 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 set directly to `allowDecimals` (boolean). `decimalScale` uses `allowDecimals !== false ? 2 : 0` (note: `!== false` means undefined/missing also gives 2 decimals).
+- The input stores the raw numeric string (e.g., `'1234.56'`) in state and in the Pega store — not the formatted display string.
+- `formattedValue` is computed eagerly (before display mode check) using `pConn.getComponentName()?.toLowerCase()` as the format type — this resolves to `'currency'`.
+- `data-test-id` is passed via nested `slotProps.input.inputProps` (or `InputProps.inputProps` depending on design system) — not on the outer wrapper.
+- `placeholder` defaults to `''` if undefined: `placeholder ?? ''`.
+- Variant switches between `'outlined'` (editable) and `'standard'` (read-only) — this is design-system specific but the visual intent is: bordered input vs flat/borderless.
+
+## 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                                         |