@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,198 @@
+# Skill: Decimal
+
+Decimal number input with configurable precision, group separators, and optional currency/percentage display formatting.
+
+> **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 that accepts decimal values. Supports configurable decimal precision, optional thousands separator, and optional formatter override (`'Currency'` or `'Percentage'`). Differs from `Currency` in that it's more generic — it can display values as currency, percentage, or plain decimal based on a `formatter` prop.
+
+## Pega Metadata
+
+- **Pega Name:** `Decimal`
+- **Type / Subtype:** `Field` / `Decimal`
+- **Registration key:** `Decimal` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop                  | Type                 | Default | Description                                                                                  |
+| --------------------- | -------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `currencyISOCode`     | `string` (optional)  | `'USD'` | ISO code for symbol/separator lookup (used when `formatter === 'Currency'`)                  |
+| `decimalPrecision`    | `number` (optional)  | —       | Number of decimal places to show                                                             |
+| `showGroupSeparators` | `boolean` (optional) | —       | Whether to show thousands separators                                                         |
+| `formatter`           | `string` (optional)  | —       | `'Currency'` or `'Percentage'` — changes display mode formatting and read-only prefix/suffix |
+
+## Component Skeleton
+
+Follow this exact structure. Nearly identical to Currency but with configurable precision and conditional prefix/suffix.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getCurrencyCharacters, getCurrencyOptions } from '../Currency/currency-utils';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface DecimalProps extends PConnFieldProps {
+  currencyISOCode?: string;
+  decimalPrecision?: number;
+  showGroupSeparators?: boolean;
+  formatter?: string;
+}
+
+export default function Decimal(props: DecimalProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, helperText, displayMode,
+    hideLabel, currencyISOCode = 'USD', decimalPrecision,
+    showGroupSeparators, testId, placeholder, formatter,
+  } = props;
+
+  // 3. State
+  const [values, setValues] = useState(value.toString());
+
+  // 4. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Currency/decimal symbols
+  const theSymbols = getCurrencyCharacters(currencyISOCode);
+  const theCurrDec = theSymbols.theDecimalIndicator;
+  const theCurrSep = theSymbols.theDigitGroupSeparator;
+  const theCurrSym = theSymbols.theCurrencySymbol;
+  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setValues(value.toString()); }, [value]);
+
+  // 7. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Formatted value (computed eagerly, before display mode check)
+  let formattedValue = '';
+  if (formatter === 'Currency') {
+    formattedValue = format(value, formatter.toLowerCase(), theCurrencyOptions);
+  } else {
+    formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+  }
+
+  // 9. 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" />;
+  }
+
+  // 10. Test ID + event handlers
+  const testProps: any = { 'data-test-id': testId };
+  function decimalOnBlur() { handleEvent(actions, 'changeNblur', propName, values); }
+  const handleChange = (val) => { setValues(val.value); };
+
+  // 11. Main render — numeric format input
+  //     Key props:
+  //     - valueIsNumericString: true, fullWidth: true
+  //     - value: values
+  //     - variant: readOnly ? 'standard' : 'outlined'
+  //     - prefix: readOnly && formatter === 'Currency' ? theCurrSym : ''
+  //     - suffix: readOnly && formatter === 'Percentage' ? '%' : ''
+  //     - decimalSeparator: theCurrDec
+  //     - thousandSeparator: showGroupSeparators ? theCurrSep : ''
+  //     - decimalScale: readOnly && formatter === 'Currency' ? undefined : decimalPrecision
+  //     - onValueChange, onBlur: !readOnly ? decimalOnBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error', size: 'small'
+  //     - slotProps: { input: { ...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. **Separators:** Derive `theCurrDec` and `theCurrSep` from `getCurrencyCharacters(currencyISOCode)`. Apply `thousandSeparator` only when `showGroupSeparators` is truthy (otherwise pass `''`).
+5. **Formatted value (computed eagerly):**
+   ```
+   if (formatter === 'Currency') {
+     formattedValue = format(value, formatter.toLowerCase(), theCurrencyOptions);
+   } else {
+     formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+   }
+   ```
+6. **Prefix/Suffix (read-only only):**
+   - `prefix`: `readOnly && formatter === 'Currency' ? theCurrSym : ''`
+   - `suffix`: `readOnly && formatter === 'Percentage' ? '%' : ''`
+7. **Decimal scale:** `readOnly && formatter === 'Currency' ? undefined : decimalPrecision`.
+8. **On value change:** `setValues(val.value)` — raw numeric string.
+9. **On blur:** `handleEvent(actions, 'changeNblur', propName, values)`.
+10. **Read-only:** Set `readOnly: true` via `readOnlyProp`. Variant switches to `'standard'` (flat). `onBlur` omitted.
+11. **Render ordering:** state → readOnlyProp → formattedValue → display modes → testProps + handlers → main render.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+`formattedValue` is computed before display-mode check:
+
+- `formatter === 'Currency'` → currency-formatted string.
+- Otherwise → decimal-formatted string using `pConn.getComponentName()?.toLowerCase()` as format key.
+
+## Read-Only Rendering
+
+Keep numeric format input with `readOnly: true`. Apply prefix (`$`) or suffix (`%`) based on `formatter`. Flat/borderless visual style.
+
+## Visual Specifications
+
+| Property            | Standard (editable)                  | Read-only                                            |
+| ------------------- | ------------------------------------ | ---------------------------------------------------- |
+| Width               | 100%                                 | 100%                                                 |
+| Size                | Small                                | Small                                                |
+| Variant             | Outlined                             | Standard (flat)                                      |
+| Prefix              | None (unless read-only Currency)     | Currency symbol if `formatter='Currency'`            |
+| Suffix              | None (unless read-only Percentage)   | `%` if `formatter='Percentage'`                      |
+| Thousands separator | Only when `showGroupSeparators=true` | Same                                                 |
+| Decimal scale       | From `decimalPrecision`              | Undefined for Currency, `decimalPrecision` otherwise |
+| Placeholder         | From `placeholder` prop              | —                                                    |
+
+## Edge Cases & Special Logic
+
+- In read-only Currency mode, `decimalScale` is set to `undefined` (let the formatter decide), not `decimalPrecision`.
+- `thousandSeparator` defaults to `''` (disabled) unless `showGroupSeparators` is `true`.
+- `prefix` and `suffix` are only rendered in read-only mode — NOT in editable mode.
+- The stored value is always a raw numeric string, not the formatted display string.
+
+## Dependencies
+
+- Numeric formatting library (e.g., `react-number-format`'s `NumericFormat`).
+- `getCurrencyCharacters(currencyISOCode)` — for `theDecimalIndicator` and `theDigitGroupSeparator`.
+- `getCurrencyOptions(currencyISOCode)` — for `format()` options.
+- `format()` from `../../helpers/formatters`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Decimal / numeric formatted input.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                             |
+| ------------------ | ------------------------------------------------- |
+| Default (CSS only) | `<input type="text">` with custom numeric masking |
+| MUI                | `NumericFormat` with `customInput={TextField}`    |
+| Ant Design         | `<InputNumber precision={decimalPrecision} />`    |
+| Chakra UI          | `<NumberInput>`                                   |

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

@@ -0,0 +1,260 @@
+# Skill: Dropdown
+
+Select/dropdown field with options loaded from a data page, associated list, or deferred datasource. Includes localization of option labels.
+
+> **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 single-select dropdown (select box). Options are loaded from a Pega datasource — either an `associated` list (static key/value pairs) or a `datapage` (async data page fetch). Supports deferred datasource loading and localized option labels. Commits value immediately on selection change.
+
+## Pega Metadata
+
+- **Pega Name:** `Dropdown`
+- **Type / Subtype:** `Field` / `Picklist`
+- **Registration key:** `Dropdown` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop                 | Type                 | Description                                                         |
+| -------------------- | -------------------- | ------------------------------------------------------------------- |
+| `listType`           | `string`             | `'associated'` or `'datapage'` — determines how options are loaded  |
+| `datasource`         | `any[]` (optional)   | The raw 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 from deferred datasource resolution                        |
+| `fieldMetadata`      | `any` (optional)     | Field metadata for localization context                             |
+| `onRecordChange`     | `any` (optional)     | Callback fired after a selection change                             |
+
+## Component Skeleton
+
+Follow this exact structure. Same helper functions as AutoComplete (`flattenParameters`, `preProcessColumns`, `getDisplayFieldsMetaData`).
+
+```typescript
+import { useEffect, useState } from 'react';
+import isDeepEqual from 'fast-deep-equal/react';
+import Utils from '../../helpers/utils';
+import { getDataPage } from '../../helpers/data_page';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface IOption { key: string; value: string; }
+
+// ── Helper functions (top-level) ─────────────────────────────
+// flattenParameters, preProcessColumns, getDisplayFieldsMetaData
+// → same implementations as AutoComplete (see that skill file)
+
+interface DropdownProps extends PConnFieldProps {
+  datasource?: any[];
+  onRecordChange?: any;
+  fieldMetadata?: any;
+  listType: string;
+  deferDatasource?: boolean;
+  datasourceMetadata?: any;
+  parameters?: any;
+  columns: any[];
+}
+
+export default function Dropdown(props: DropdownProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, helperText,
+    displayMode, deferDatasource, datasourceMetadata,
+    hideLabel, onRecordChange, fieldMetadata,
+  } = props;
+  let { placeholder = '' } = props;
+  const context = getPConnect().getContextName();
+  let { listType, parameters, datasource = [], columns = [] } = props;
+  placeholder = placeholder || 'Select...';
+
+  // 3. State
+  const [options, setOptions] = useState<IOption[]>([]);
+  const [theDatasource, setDatasource] = useState<any[] | null>(null);
+
+  // 4. PConnect setup
+  const helperTextToDisplay = validatemessage || helperText;
+  const thePConn = getPConnect();
+  const actionsApi = thePConn.getActionsApi();
+  const propName = (thePConn.getStateProps() as any).value;
+  const className = thePConn.getCaseInfo().getClassName();
+  const refName = propName?.slice(propName.lastIndexOf('.') + 1);
+
+  // 5. Render-time datasource comparison (NOT in useEffect)
+  if (!isDeepEqual(datasource, theDatasource)) {
+    setDatasource(datasource);
+  }
+
+  // 6. Deferred datasource transformation (same as AutoComplete)
+  //    → reassigns listType, datasource, parameters, columns
+
+  // 7. Column preprocessing
+  columns = preProcessColumns(columns);
+
+  // 8. useEffect: associated options — deps: [theDatasource]
+  //    → prepend placeholder option, call Utils.getOptionList
+
+  // 9. useEffect: datapage options — deps: []
+  //    Guard: listType !== 'associated' && typeof datasource === 'string'
+
+  // 10. Localization metadata derivation
+  //     → metaData, displayName, localeContext, localeClass, localeName, localePath
+
+  // 11. Display mode — resolve key→value, localize, return FieldValueList
+  if (displayMode) {
+    const resolvedValue = options.find(opt => opt.key === value)?.value || value;
+    const localizedValue = thePConn.getLocalizedValue(resolvedValue, localePath,
+      thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName));
+    // return <FieldValueList ... value={localizedValue} />
+  }
+
+  // 12. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 13. Test ID + handleChange
+  const testProps: any = { 'data-test-id': testId };
+  const handleChange = (evt) => {
+    const selectedValue = evt.target.value === placeholder ? '' : evt.target.value;
+    handleEvent(actionsApi, 'changeNblur', propName, selectedValue);
+    if (onRecordChange) onRecordChange(evt);
+  };
+
+  // 14. Main render — return null if options empty, otherwise select
+  //     value: value === '' && !readOnly ? placeholder : value
+  //     Options rendered with localized labels via thePConn.getLocalizedValue()
+  return options.length === 0 ? null : <SelectWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Options state:** Maintain `options` as `Array<{key: string, value: string}>`. Initially empty — render nothing (`return null`) until options are populated (avoids design system warnings about undefined options).
+2. **Datasource detection:** Use `isDeepEqual` (deep equality) to compare incoming `datasource` prop with cached `theDatasource` state. If different, update `theDatasource` to trigger a `useEffect`.
+3. **Deferred datasource transformation:** If `deferDatasource && datasourceMetadata?.datasource?.name`:
+   - Override `listType = 'datapage'`
+   - Set `datasource = datasourceMetadata.datasource.name` (string page name)
+   - Flatten `parameters` from `{key: {name, value}}` format to `{name: value}` pairs
+   - Build `columns` from `propertyForDisplayText` and `propertyForValue`
+4. **Column preprocessing:** Strip leading `.` from column `value` fields.
+5. **Loading options for `associated` listType:** In `useEffect` watching `theDatasource`, call `Utils.getOptionList(props, pConn.getDataObject(''))`. Prepend a placeholder option `{key: placeholder, value: localizedPlaceholder}`.
+6. **Loading options for `datapage` listType:** In mount-time `useEffect`, call `getDataPage(datasource, parameters, context)`. Map results using `getDisplayFieldsMetaData(columns)` to extract `key` and `value` per row.
+7. **Placeholder:** Default `'Select...'` if not provided. Prepended as the first option for associated lists.
+8. **On change:**
+   - If selected value equals `placeholder`, treat as empty string: `selectedValue = evt.target.value === placeholder ? '' : evt.target.value`.
+   - Commit via `handleEvent(actionsApi, 'changeNblur', propName, selectedValue)`.
+   - Fire `onRecordChange(evt)` if provided.
+9. **Read-only:** Set `readOnly: true` on the select input. Flat/borderless style. Change handler omitted.
+10. **Localization metadata:** Derived from `fieldMetadata`:
+    ```
+    const metaData = Array.isArray(fieldMetadata)
+      ? fieldMetadata.filter(f => f?.classID === className)[0]
+      : fieldMetadata;
+    let displayName = metaData?.datasource?.propertyForDisplayText;
+    displayName = displayName?.slice(displayName.lastIndexOf('.') + 1);
+    const localeContext = metaData?.datasource?.tableType === 'DataPage' ? 'datapage' : 'associated';
+    const localeClass = localeContext === 'datapage' ? '@baseclass' : className;
+    const localeName = localeContext === 'datapage' ? metaData?.datasource?.name : refName;
+    const localePath = localeContext === 'datapage' ? displayName : localeName;
+    ```
+    Where `className = thePConn.getCaseInfo().getClassName()` and `refName = propName?.slice(propName.lastIndexOf('.') + 1)`.
+11. **Display mode rendering:** Uses a `displayFn` that resolves key→value from options, then localizes:
+    ```
+    const resolvedValue = options.find(opt => opt.key === value)?.value || value;
+    return <FieldValueList value={thePConn.getLocalizedValue(resolvedValue, localePath,
+      thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))} />;
+    ```
+12. **Select value when empty:** `value={value === '' && !readOnly ? placeholder : value}` — shows placeholder as selected when value is empty.
+13. **Return null until options load:** `return options.length === 0 ? null : <Select ... />` — prevents rendering empty select.
+14. **Option labels localized:** Each `<MenuItem>` label is wrapped in `thePConn.getLocalizedValue(option.value, localePath, localeRuleName)`.
+
+## Display Mode Rendering
+
+Display modes use the **resolved display value** (the `value` string matching the selected `key`), NOT the raw stored key:
+
+```
+options.find(option => option.key === value)?.value || value
+```
+
+Both modes pass this resolved value through `pConn.getLocalizedValue()` for localization:
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedDisplayValue} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedDisplayValue} variant='stacked' />`
+
+## Read-Only Rendering
+
+Set `readOnly: true` on the select element. Flat/borderless variant. Change handler removed.
+
+## Visual Specifications
+
+| Property           | Standard (editable)                  | Read-only       |
+| ------------------ | ------------------------------------ | --------------- |
+| Width              | 100%                                 | 100%            |
+| Size               | Small                                | Small           |
+| Variant            | Outlined                             | Standard (flat) |
+| Placeholder option | First option in list (`'Select...'`) | Not shown       |
+| Options            | Rendered as select menu items        | —               |
+| Error state        | Red border + red helper text         | —               |
+| Label              | Floating label                       | —               |
+
+**CSS-only notes:**
+
+```css
+select {
+  width: 100%;
+  height: 40px;
+  border: 1px solid rgba(0, 0, 0, 0.23);
+  border-radius: 4px;
+  padding: 8px 12px;
+  font-size: 0.875rem;
+}
+select:focus {
+  border-color: #1976d2;
+  outline: none;
+}
+select.error {
+  border-color: #d32f2f;
+}
+select[readonly] {
+  border: none;
+  background: transparent;
+  pointer-events: none;
+}
+```
+
+## Edge Cases & Special Logic
+
+- Do NOT render the component until `options.length > 0` — return `null` until options load.
+- **Localization keys:** Build from `fieldMetadata`:
+  - `localeContext`: `'datapage'` if `tableType === 'DataPage'`, else `'associated'`
+  - `localeClass`: `'@baseclass'` for datapage, else the case className
+  - `localeName`, `localePath` derived from datasource name and display text property
+- `displayMode` check must resolve the key→value mapping — it calls `displayFn(displayMode, resolvedValue)`.
+
+## Dependencies
+
+- `isDeepEqual` from `fast-deep-equal/react` — for datasource change detection.
+- `Utils.getOptionList()` from `../../helpers/utils` — for associated list options.
+- `getDataPage()` from `../../helpers/data_page` — for datapage async fetch.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Single-select dropdown / select box.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                           |
+| ------------------ | ----------------------------------------------- |
+| Default (CSS only) | `<select>` with `<option>` elements             |
+| MUI                | `<TextField select>` with `<MenuItem>` children |
+| Ant Design         | `<Select>` with `<Select.Option>`               |
+| Chakra UI          | `<Select>`                                      |

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

@@ -0,0 +1,177 @@
+# Skill: Email
+
+Email input field with a leading mail icon, 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 single-line text input of type `email` with a leading mail icon adornment. Provides browser-native email validation via `type='email'`. Delegates read-only rendering to the `TextInput` component.
+
+## Pega Metadata
+
+- **Pega Name:** `Email`
+- **Type / Subtype:** `Field` / `Text-Email`
+- **Registration key:** `Email` (in `component-map.ts`)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Component Skeleton
+
+Follow this exact structure. Replace the mail icon and TextField with equivalents from your chosen design system.
+
+```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';
+
+interface EmailProps extends PConnFieldProps {}
+
+export default function Email(props: EmailProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState('');
+
+  // 5. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only return (delegates entirely to TextInput — no mail icon)
+  if (readOnly) {
+    return <TextInput {...props} />;
+  }
+
+  // 8. Test ID + event handlers
+  const testProps: any = { 'data-test-id': testId };
+  function handleChange(event) { setInputValue(event?.target?.value); }
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 9. Main render — email input with leading mail icon
+  //    Key props:
+  //    - fullWidth, variant: 'outlined', size: 'small'
+  //    - type: 'email'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - startAdornment: mail/envelope icon
+  //    - inputProps: { ...testProps }
+  return <EmailInput ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).
+2. **Sync from store:** `useEffect` watching `value` → `setInputValue(value)`.
+3. **On change:** Update local state only (`setInputValue(event.target.value)`).
+4. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+5. **Input type:** Use `type='email'` for browser-native email format validation.
+6. **Read-only:** Delegate entirely to `TextInput` component: `return <TextInput {...props} />`. Do NOT render the email-specific UI.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw email string, no formatting.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`. This means the mail icon adornment is NOT shown in read-only mode.
+
+## Visual Specifications
+
+Derived from the reference component's MUI props and styles:
+
+| Property      | Value                                             |
+| ------------- | ------------------------------------------------- |
+| Width         | 100%                                              |
+| Size          | Small (~40px height)                              |
+| Variant       | Outlined                                          |
+| Leading icon  | Mail/envelope icon (`position='start'` adornment) |
+| Icon color    | Inherits text color                               |
+| Border        | 1px solid outlined                                |
+| Border radius | 4px                                               |
+| Error state   | Red border + red helper text                      |
+| Helper text   | Below input                                       |
+| Placeholder   | From `placeholder` prop (`''` default)            |
+
+**CSS-only implementation notes:**
+
+```css
+.email-input-wrapper {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  border: 1px solid rgba(0, 0, 0, 0.23);
+  border-radius: 4px;
+  padding: 8px 14px 8px 36px; /* left padding for icon */
+}
+.email-input-icon {
+  position: absolute;
+  left: 10px;
+  color: rgba(0, 0, 0, 0.54);
+  pointer-events: none;
+}
+.email-input-wrapper.error {
+  border-color: #d32f2f;
+}
+```
+
+## Edge Cases & Special Logic
+
+- The `type='email'` attribute triggers browser-native validation — this is intentional and supplements Pega's server-side validation.
+- In read-only mode, the full delegation to `TextInput` means the component renders without the mail icon adornment.
+- `onBlur` is only attached when `!readOnly`.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils`
+- `getComponentFromRegistry('TextInput')` — for read-only delegation
+- `getComponentFromRegistry('FieldValueList')` — for display modes
+- A mail/envelope icon (e.g., from an icon library or inline SVG)
+
+## Design System Mapping
+
+**UI control type:** Email text input with leading icon adornment.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                                               |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| Default (CSS only) | `<input type="email">` with absolutely-positioned icon                                              |
+| MUI                | `<TextField type='email' InputProps={{ startAdornment: <MailIcon /> }} />`                          |
+| Ant Design         | `<Input type="email" prefix={<MailOutlined />} />`                                                  |
+| Chakra UI          | `<InputGroup><InputLeftElement><EmailIcon /></InputLeftElement><Input type="email" /></InputGroup>` |