@pega/sdk 0.0.2 → 0.0.3

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

@@ -0,0 +1,104 @@
+---
+description: Field component skill: Date
+alwaysApply: false
+---
+
+# Skill: Date
+
+Date picker field with locale-aware date format string, 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 date picker input. Stores dates as `YYYY-MM-DD` strings. Displays dates according to locale-aware format (e.g., `MM/DD/YYYY` for en-US). Uses a date picker library for the calendar UI. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Date`
+- **Type / Subtype:** `Field` / `Date`
+- **Registration key:** `Date` (mapped to `DateField` import in `component-map.ts` to avoid conflicts with the JS `Date` global)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+> **Important naming note:** The component file exports a function named `Date`. In `component-map.ts`, import it as `DateField` and register it as `Date: DateField`.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `dateValue` as a date object (e.g., a `dayjs` object or `Date` instance), initialized from `value` prop using the date library's parser. Default to `null` if value is empty/falsy.
+2. **Sync from store:** `useEffect` watching `value` → re-parse and `setDateValue(dayjs(value))`.
+3. **Date format:** Get locale-aware format string via `getDateFormatInfo()`:
+   - Returns `dateFormatString` (display format, e.g., `'MM/DD/YYYY'`), `dateFormatStringLC` (lowercase for placeholder, e.g., `'mm/dd/yyyy'`), `dateFormatMask`.
+   - Start from `dateFormatInfoDefault` and override with locale-specific values.
+4. **On change (valid date selected):** 
+   - Validate the date is valid (e.g., `date.isValid()`).
+   - Format to `YYYY-MM-DD` string: `${year}-${(month+1).padStart(2,'0')}-${day.padStart(2,'0')}`.
+   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, formattedDate)`.
+   - Update local `dateValue` state.
+5. **Invalid dates:** If `date.isValid()` is false, do NOT commit — ignore the change.
+6. **Read-only:** Delegate to `TextInput`: `return <TextInput {...props} />`.
+7. **Placeholder:** Use lowercase format string (e.g., `'mm/dd/yyyy'`).
+
+## Display Mode Rendering
+
+Format the value before display using `format(value, 'date', { format: dateFormatInfo.dateFormatString })`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDate} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDate} variant='stacked' />`.
+- Both modes compute `formattedDate` from the raw `props.value` (not local state).
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`. The raw `YYYY-MM-DD` string is displayed as-is (or formatted by `TextInput`'s read-only rendering).
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | Auto (date picker natural width) |
+| Size | Small |
+| Variant | Outlined |
+| Placeholder | Lowercase format string (e.g., `mm/dd/yyyy`) |
+| Calendar popup | Opens below the input |
+| Error state | Red border + red helper text |
+| Required indicator | `*` on label |
+| Format display | Locale-aware (e.g., `MM/DD/YYYY`, `DD/MM/YYYY`) |
+
+**CSS-only notes:** For a CSS-only date input, use `<input type="date">` — note that the display format is browser-controlled. A custom date picker component is needed for locale-aware format strings.
+
+## Edge Cases & Special Logic
+
+- Commit on **change** (when a valid date is selected), not on blur — this differs from text inputs.
+- Always store value as `YYYY-MM-DD` regardless of display format.
+- Invalid/incomplete dates (e.g., partially typed) are ignored — only commit when `isValid()` returns true.
+- Locale format info is derived at render time from `getDateFormatInfo()` — this reads the Pega environment locale.
+
+## Dependencies
+
+- Date manipulation library (e.g., `dayjs`) — for parsing, formatting, validity checking.
+- Date picker UI component (e.g., `@mui/x-date-pickers/DatePicker`) — for calendar popup.
+- `getDateFormatInfo()` from `../../helpers/date-format-utils` — for locale-aware format string.
+- `dateFormatInfoDefault` from same helper — default fallback.
+- `format()` from `../../helpers/formatters` — for display mode formatting.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only delegation.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Date picker with calendar popup.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="date">` (browser native, limited locale control) |
+| MUI | `<DatePicker />` from `@mui/x-date-pickers` with `dayjs` adapter |
+| Ant Design | `<DatePicker format="MM/DD/YYYY" />` |
+| Chakra UI | Third-party date picker or `<input type="date">` |

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

@@ -0,0 +1,108 @@
+---
+description: Field component skill: DateTime
+alwaysApply: false
+---
+
+# Skill: DateTime
+
+Date and time picker with timezone conversion, 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 combined date and time picker. Stores values as ISO 8601 UTC strings. Converts to/from the Pega environment's configured timezone for display. Shows formatted date-time in display modes. Delegates read-only rendering to `TextInput` with a formatted string.
+
+## Pega Metadata
+
+- **Pega Name:** `DateTime`
+- **Type / Subtype:** `Field` / `DateTime`
+- **Registration key:** `DateTime` (in `component-map.ts`)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Behavioral Contract
+
+1. **Timezone:** Read the environment timezone at render time:
+   ```
+   const timezone = PCore.getEnvironmentInfo().getTimeZone()
+   ```
+2. **Local state:** Maintain `dateValue` as a timezone-aware date object. Initialize from `value` prop by converting to the environment timezone using `DateFormatter.convertToTimezone(value, { timezone })`.
+3. **Sync from store:** `useEffect` watching `value` → re-convert and `setDateValue(dayjs(DateFormatter.convertToTimezone(value, { timezone })))`.
+4. **Date/time format:** Get locale-aware format from `getDateFormatInfo()`. Combined format: `${dateFormatString} hh:mm a` (e.g., `'MM/DD/YYYY hh:mm a'`). Placeholder: `${dateFormatStringLC} hh:mm a`.
+5. **Minutes step:** `minutesStep={5}` — time picker snaps to 5-minute increments.
+6. **On change:**
+   - Convert the selected date to timezone-aware ISO string:
+     ```
+     const timeZoneDateTime = dayjs.tz(date.format('YYYY-MM-DDTHH:mm:ss'), timezone)
+     const changeValue = timeZoneDateTime?.isValid() ? timeZoneDateTime.toISOString() : ''
+     ```
+   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, changeValue)`.
+   - Update local `dateValue`.
+7. **Read-only:** Format value as string using `format(value, 'datetime')`, then delegate: `return <TextInput {...props} value={formattedDateTime} />`.
+
+## Display Mode Rendering
+
+Format using `format(value, 'datetime', { format: \`${dateFormatString} hh:mm a\` })`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Format value as `format(props.value, 'datetime')` then pass to `TextInput`:
+```
+return <TextInput {...props} value={formattedDateTime} />
+```
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | Auto |
+| Size | Small |
+| Variant | Outlined |
+| Format | `MM/DD/YYYY hh:mm a` (locale-aware date + 12h time) |
+| Placeholder | Lowercase format, e.g., `mm/dd/yyyy hh:mm a` |
+| Minutes step | 5 minutes |
+| Error state | Red border + red helper text |
+
+**Note on known issue:** Keyboard input in the minute field may jump to the am/pm field after one digit — this is a known quirk of some date-time picker library versions.
+
+## Edge Cases & Special Logic
+
+- All stored values are **UTC ISO 8601 strings** (e.g., `'2024-03-15T14:30:00.000Z'`).
+- **Timezone conversion** is critical: always convert from UTC → environment timezone for display, and from environment timezone → UTC when committing.
+- If `timeZoneDateTime.isValid()` is false, commit an empty string `''`.
+- Commits on **change** (picker selection), not on blur.
+- `dayjs.tz` requires `dayjs-timezone` plugin.
+
+## Dependencies
+
+- Date manipulation library with timezone support (e.g., `dayjs` + `dayjs/plugin/timezone`).
+- `DateFormatter.convertToTimezone(value, { timezone })` from `../../helpers/formatters/Date` — converts stored UTC value to display timezone.
+- `format()` from `../../helpers/formatters` — for display mode formatting.
+- `getDateFormatInfo()` from `../../helpers/date-format-utils` — for locale date format string.
+- Date-time picker UI component (e.g., `@mui/x-date-pickers/DateTimePicker`).
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Combined date and time picker with timezone awareness.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="datetime-local">` (no timezone control) |
+| MUI | `<DateTimePicker />` from `@mui/x-date-pickers` + `dayjs.tz` |
+| Ant Design | `<DatePicker showTime />` |
+| Chakra UI | Third-party datetime picker |

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

@@ -0,0 +1,103 @@
+---
+description: Field component skill: Decimal
+alwaysApply: false
+---
+
+# 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 |
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Separators:** Always derive `decimalSeparator` and `thousandSeparator` from locale lookup using `currencyISOCode`. Apply `thousandSeparator` only when `showGroupSeparators` is `true`.
+4. **Decimal scale:** Use `decimalPrecision` prop for `decimalScale` — except in read-only mode with `formatter === 'Currency'`, where `decimalScale` is `undefined`.
+5. **Prefix/Suffix in read-only:**
+   - If `readOnly && formatter === 'Currency'`: show currency symbol as prefix.
+   - If `readOnly && formatter === 'Percentage'`: show `%` as suffix.
+   - Otherwise: no prefix/suffix.
+6. **Formatted display value:**
+   - If `formatter === 'Currency'`: `formattedValue = format(value, 'currency', currencyOptions)`.
+   - Otherwise: `formattedValue = format(value, 'decimal', currencyOptions)`.
+7. **On value change:** Update local `values` state with the raw numeric string.
+8. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, values)`.
+9. **Read-only:** Set `readOnly: true` on the input. Visual style switches to flat/borderless. `onBlur` omitted.
+
+## 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/.cursor/rules/skills/field-skills/Dropdown.mdrules

@@ -0,0 +1,119 @@
+---
+description: Field component skill: Dropdown
+alwaysApply: false
+---
+
+# 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 |
+
+## 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:** Option labels and display values are localized via `pConn.getLocalizedValue(label, 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/.cursor/rules/skills/field-skills/Email.mdrules

@@ -0,0 +1,112 @@
+---
+description: Field component skill: Email
+alwaysApply: false
+---
+
+# 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';
+```
+
+## 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>` |

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

@@ -0,0 +1,95 @@
+---
+description: Field component skill: Group
+alwaysApply: false
+---
+
+# Skill: Group
+
+Field group container that wraps child fields in a collapsible section with an optional heading and instructions.
+
+> **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
+
+A layout/structural component (not a form input). Wraps a set of child field components in a `FieldGroup` container with an optional heading, collapsibility, and instructions text. Arranges children in a responsive grid. Does not bind to a Pega property directly.
+
+## Pega Metadata
+
+- **Pega Name:** `Group`
+- **Type / Subtype:** `Field` / `Group`
+- **Registration key:** `Group` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactElement[]` | Child field components to render inside the group |
+| `heading` | `string` | The group heading/title |
+| `showHeading` | `boolean` | Whether to display the heading |
+| `instructions` | `string` (optional) | Instructional text shown below the heading |
+| `collapsible` | `boolean` | Whether the group can be collapsed |
+| `type` | `string` | Group type (used for layout context) |
+
+`displayMode` is also consumed from `PConnFieldProps`.
+
+## Behavioral Contract
+
+1. **No state, no event handling** — purely structural/layout.
+2. **`isReadOnly` flag:** `isReadOnly = displayMode === 'DISPLAY_ONLY'` — passed through to grid for layout context.
+3. **Content grid:** Build a responsive grid of children using `useMemo` (memoized based on `children`, `type`, `isReadOnly`):
+   - Each child gets a full-width grid item (`xs: 12` in a 12-column grid, or equivalent `100%` column).
+   - Children are mapped with their `key` prop preserved.
+4. **Null guard:** If `!children`, return `null`.
+5. **Heading:** Pass `showHeading ? heading : undefined` to `FieldGroup` — if `showHeading` is false, heading is `undefined` (not shown).
+6. **FieldGroup:** Resolved via `getComponentFromRegistry('FieldGroup')`. Receives `name`, `collapsible`, and `instructions` props.
+
+## Display Mode Rendering
+
+`displayMode` is not explicitly handled — it's passed through as a prop for context. `FieldGroup` and children handle their own display mode behavior.
+
+## Visual Specifications
+
+The visual appearance is determined by the `FieldGroup` design system extension component. `Group` itself only applies grid layout to children:
+
+```
+Grid container (spacing=2):
+  per child → Grid item (xs: 12, full width)
+```
+
+**CSS-only grid layout:**
+```css
+.field-group-children { display: grid; grid-template-columns: 1fr; gap: 16px; }
+```
+
+The `FieldGroup` component itself provides:
+- Optional heading/title above the children
+- Optional collapse/expand control
+- Optional instructions text
+- Container border/background (design-system-dependent)
+
+## Edge Cases & Special Logic
+
+- **`useMemo` dependencies:** `[children, type, isReadOnly]` — the grid re-renders only when these change, not on every parent render.
+- Children must have stable `key` props for React reconciliation.
+- `instructions` may be undefined — `FieldGroup` should handle this gracefully.
+
+## Dependencies
+
+- `getComponentFromRegistry('FieldGroup')` — design system extension providing the collapsible container.
+- `useMemo` from React.
+- Grid layout component (e.g., MUI `Grid`).
+
+## Design System Mapping
+
+**UI control type:** Collapsible field group container with heading.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<fieldset>` or `<details>/<summary>` for collapsible |
+| MUI | `<Grid container spacing={2}>` with `<Grid size={{ xs: 12 }}>` per child |
+| Ant Design | `<Collapse>` panel or `<Card>` |
+| Chakra UI | `<Box>` or `<Accordion>` |