@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,11 +14,11 @@ Renders a single-select dropdown (select box). Options are loaded from a Pega da
 
 - **Pega Name:** `Dropdown`
 - **Type / Subtype:** `Field` / `Picklist`
-- **Registration key:** `Dropdown` (in `component-map.ts`)
+- **Registration key:** `Dropdown` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop                 | Type                 | Description                                                         |
+| Name                 | 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) |
@@ -29,168 +29,67 @@ Renders a single-select dropdown (select box). Options are loaded from a Pega da
 | `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 ... />;
-}
-```
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. Same helper functions as AutoComplete (`flattenParameters`, `preProcessColumns`, `getDisplayFieldsMetaData`) — see that skill file for their exact behavior.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`), the project's event-commit utility, a deep-equality utility (for datasource change detection), the project's utility helpers (for associated option list loading), and the project's data-page utility (for async data page fetching). Define an option type with `key: string` and `value: string`. Declare the same top-level helper functions used by AutoComplete (`flattenParameters`, `preProcessColumns`, `getDisplayFieldsMetaData`). Define the input contract as an extension of the project's field input contract, adding `datasource`, `onRecordChange`, `fieldMetadata`, `listType`, `deferDatasource`, `datasourceMetadata`, `parameters`, and `columns` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `deferDatasource`, `datasourceMetadata`, `hideLabel`, `onRecordChange`, `fieldMetadata`; separately receive `placeholder` (default `''`) as a reassignable variable since it may be overridden; also grab `context` via `getPConnect().getContextName()`, and `listType`, `parameters`, `datasource` (default `[]`), `columns` (default `[]`) as reassignable since they may be overridden. Default `placeholder` to `'Select...'` when empty.
+3. **Local state** — `options` (array of option objects, default `[]`) and `theDatasource` (default `null`).
+4. **PConnect setup** — `helperTextToDisplay = validatemessage || helperText`; obtain the PConnect instance, actions API, bound property name; derive `className` via `thePConn.getCaseInfo().getClassName()`; derive `refName` by taking the substring of the property name after its last `.`.
+5. **Render-time datasource comparison (not in a lifecycle effect)** — if deep-equal comparison of incoming `datasource` vs cached `theDatasource` is false, update `theDatasource` directly during render to trigger the associated-list effect.
+6. **Deferred datasource transformation** (same as AutoComplete) — reassigns `listType`, `datasource`, `parameters`, and `columns` when deferred.
+7. **Column preprocessing** — apply `preProcessColumns(columns)`.
+8. **Lifecycle effect: associated options** — watching `theDatasource`: prepend a placeholder option, then load options via the project's utility helper.
+9. **Lifecycle effect: datapage options** — on mount only, guarded to skip when `listType === 'associated'`.
+10. **Localization metadata derivation** — compute `metaData`, `displayName`, `localeContext`, `localeClass`, `localeName`, `localePath` (see Behavioral Contract item 10 for the exact derivation).
+11. **Display mode** — when `displayMode` is set: resolve the display value by matching `value` against the `key` of an entry in `options` (falling back to the raw `value` if no match), localize it via `thePConn.getLocalizedValue(resolvedValue, localePath, thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))`, and return `FieldValueList` with that localized value.
+12. **Read-only flag** — build a read-only configuration, set to mark the input read-only only when `readOnly` is true.
+13. **Test ID and change handler** — build a test-id attribute from `testId`; the change handler treats a selection equal to the placeholder as an empty string, commits via the project's event-commit utility with event type `'changeNblur'`, the property name, and the selected value, and invokes `onRecordChange` when provided.
+14. **Render** — return `null` when `options` is empty (avoids rendering with no options); otherwise render the select widget with `value` set to the placeholder when `value === '' && !readOnly`, and options rendered with localized labels via `thePConn.getLocalizedValue()`.
 
 ## 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`.
+1. **Options state:** Maintain `options` as an array of `{key: string, value: string}` objects. Initially empty — render nothing (`return null`) until options are populated (avoids design system warnings about undefined options).
+2. **Datasource detection:** Use deep equality to compare incoming `datasource` input with cached `theDatasource` state. If different, update `theDatasource` to trigger a lifecycle effect.
 3. **Deferred datasource transformation:** If `deferDatasource && datasourceMetadata?.datasource?.name`:
    - Override `listType = 'datapage'`
-   - Set `datasource = datasourceMetadata.datasource.name` (string page name)
+   - Set `datasource` to the metadata's 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.
+5. **Loading options for `associated` listType:** In a lifecycle effect watching `theDatasource`, load options via the project's utility helper. Prepend a placeholder option `{key: placeholder, value: localizedPlaceholder}`.
+6. **Loading options for `datapage` listType:** In a mount-time lifecycle effect, call the project's data-page utility. 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)`.
+   - If selected value equals `placeholder`, treat as empty string.
+   - Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the selected value.
+   - Fire `onRecordChange` if provided.
+9. **Read-only:** Set the read-only attribute on the select input. Flat/borderless style. Change handler omitted.
+10. **Localization metadata:** Derived from `fieldMetadata`: if `fieldMetadata` is an array, filter to the entry whose `classID` matches `className` and take the first match, otherwise use `fieldMetadata` directly, to get `metaData`. `displayName` is `metaData?.datasource?.propertyForDisplayText`, trimmed to the substring after its last `.`. `localeContext` is `'datapage'` when `metaData?.datasource?.tableType === 'DataPage'`, else `'associated'`. `localeClass` is `'@baseclass'` for datapage context, else `className`. `localeName` is `metaData?.datasource?.name` for datapage context, else `refName`. `localePath` is `displayName` for datapage context, else `localeName`. Where `className = thePConn.getCaseInfo().getClassName()` and `refName` is the substring of the property name after its last `.`.
+11. **Display mode rendering:** Resolve the display value by matching `value` (the stored key) against `options` to find the corresponding `value` field (falling back to the raw `value` if no match), then localize it via `thePConn.getLocalizedValue(resolvedValue, localePath, thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))` and render it inside `FieldValueList`.
+12. **Select value when empty:** Show the placeholder as selected when `value` is empty and the field is not read-only.
+13. **Return null until options load:** Prevents rendering an empty select.
+14. **Option labels localized:** Each option's 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
-```
+Display modes use the **resolved display value** (the `value` string matching the selected `key`), NOT the raw stored key: found by matching `value` against each option's `key` field and taking its `value` field (falling back to the raw `value` if no match found).
 
 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' />`
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the localized display value.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Set `readOnly: true` on the select element. Flat/borderless variant. Change handler removed.
+Set the read-only attribute on the select element. Flat/borderless style. Change handler removed.
 
 ## Visual Specifications
 
@@ -198,36 +97,13 @@ Set `readOnly: true` on the select element. Flat/borderless variant. Change hand
 | ------------------ | ------------------------------------ | --------------- |
 | Width              | 100%                                 | 100%            |
 | Size               | Small                                | Small           |
-| Variant            | Outlined                             | Standard (flat) |
+| Variant            | Outlined                             | Flat/borderless |
 | 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;
-}
-```
+**Visual-only styling notes:** The select element spans full width at a fixed ~40px height, with a 1px solid outlined border and 4px border radius. On focus, the border switches to an accent color (no default browser outline). In an error state, the border switches to red. When read-only, the border is removed, the background becomes transparent, and pointer interaction is disabled.
 
 ## Edge Cases & Special Logic
 
@@ -236,25 +112,25 @@ select[readonly] {
   - `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)`.
+- Display mode check must resolve the key→value mapping before localizing and rendering.
 
 ## 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.
+- A deep-equality utility — for datasource change detection.
+- The project's utility helpers — for associated list option loading.
+- The project's data-page utility — for async datapage fetch.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
 **UI control type:** Single-select dropdown / select box.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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>`                                      |
+- **Select/dropdown** → use the DS's select component with option items
+- **Placeholder option** → prepend as the first option for associated lists
+- **Option labels** → localize via `pConn.getLocalizedValue()` before display
+- **Read-only mode** → flat/borderless style with read-only attribute
+- **Error state** → the DS's error/danger visual state
+- **Return null until loaded** → do not render an empty select

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

@@ -2,176 +2,98 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, 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.
+Renders a single-line text input of type `email` with a leading mail icon adornment. Provides browser-native email validation via the `email` input type. 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 ... />;
-}
-```
+- **Registration key:** `Email` (in the project's component map)
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. Replace the mail icon and text field with equivalents from your chosen design system.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as the project's field input contract with no additional fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `TextInput` and `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Local state** — `inputValue` initialized to `''`.
+5. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever `value` changes.
+6. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+7. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation; no mail icon in read-only mode).
+8. **Test ID and event handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's input value; the blur handler commits the value via the project's event-commit utility, passing the actions API, event type `'changeNblur'`, the property name, and `inputValue`.
+9. **Render** — an email input with a leading mail icon, configured with: full width, an outlined style, small size, input type `email`, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, a start-adornment slot containing a mail/envelope icon, and the test-id attribute applied to the underlying input element.
 
 ## 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.
+1. **Local state:** Maintain `inputValue` (string). Initialize from the `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching `value` updates `inputValue`.
+3. **On change:** Update local state only (set `inputValue` from the event's input value).
+4. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Input type:** Use an `email`-typed input for browser-native email format validation.
+6. **Read-only:** Delegate entirely to the `TextInput` component, passing all inputs through. 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' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw email string, no formatting.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Delegate to `TextInput`: `return <TextInput {...props} />`. This means the mail icon adornment is NOT shown in read-only mode.
+Delegate to `TextInput`, passing all inputs through. 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;
-}
-```
+Derived from the reference component's styling:
+
+| Property      | Value                                         |
+| ------------- | --------------------------------------------- |
+| Width         | 100%                                          |
+| Size          | Small (~40px height)                          |
+| Variant       | Outlined                                      |
+| Leading icon  | Mail/envelope icon (start-adornment position) |
+| 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 the `placeholder` input (`''` default)   |
+
+**Visual-only styling notes:** The wrapper element is a flex container spanning the full input width, with a 1px solid outlined border (`rgba(0, 0, 0, 0.23)`) and 4px border radius. Left padding is increased (36px) to make room for the icon. The icon itself is absolutely positioned near the left edge (10px), colored with a muted text tone (`rgba(0, 0, 0, 0.54)`), and marked non-interactive (`pointer-events: none`) so clicks pass through to the input. In the error state, the wrapper border color switches to red (`#d32f2f`).
 
 ## Edge Cases & Special Logic
 
-- The `type='email'` attribute triggers browser-native validation — this is intentional and supplements Pega's server-side validation.
+- The `email` input type 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`.
+- The blur handler is only attached when the field is not read-only.
 
 ## 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)
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `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.
+When implementing in a specific design system, map the following:
 
-| 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>` |
+- **Email input** → use the DS's text input with input type set to `email`
+- **Leading mail icon** → use the DS's input adornment/prefix slot, or an absolutely-positioned icon if the DS has no adornment slot
+- **Read-only mode** → delegate to the `TextInput` component (no icon shown)