@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,119 @@
+# 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, input contract, 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` input.
+
+## Pega Metadata
+
+- **Pega Name:** `Decimal`
+- **Type / Subtype:** `Field` / `Decimal`
+- **Registration key:** `Decimal` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name                  | 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 |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. Nearly identical to Currency but with configurable precision and conditional prefix/suffix.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`), the project's event-commit utility, the project's currency utility helpers (for decimal/separator/symbol lookup), and the project's formatting helpers (for display-mode value formatting). It also uses a numeric-format masking library that handles locale-aware decimal/thousands display within a text input. Define the input contract as an extension of the project's field input contract, adding optional `currencyISOCode`, `decimalPrecision`, `showGroupSeparators`, and `formatter` 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`, `helperText`, `displayMode`, `hideLabel`, `currencyISOCode` (default `'USD'`), `decimalPrecision`, `showGroupSeparators`, `testId`, `placeholder`, `formatter`.
+3. **Local state** — `values` initialized from `value.toString()`.
+4. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+5. **Currency/decimal symbols** — derive the decimal indicator, digit group separator, and currency symbol via the project's currency utility helpers using `currencyISOCode`, and obtain the currency formatting options object.
+6. **Sync from store** — a lifecycle effect watching `value` updates `values` (as a string) whenever it changes.
+7. **Read-only flag** — build a read-only configuration, set to mark the input read-only only when `readOnly` is true.
+8. **Formatted value** — computed eagerly, before the display-mode check: if `formatter === 'Currency'`, compute the formatted value using the project's formatting helper with format key `'currency'` and the currency options; otherwise compute using the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key with the same currency options.
+9. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the formatted value, the latter with a stacked variant.
+10. **Test ID and event handlers** — build a test-id attribute from `testId`; the blur handler commits via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`; the value-change handler updates `values` with the raw numeric string from the masking library's callback.
+11. **Render** — a numeric-format input configured with: value-is-numeric-string flag, full width, current `values`, an outlined style when editable or flat/borderless style when read-only, prefix set to the currency symbol only when read-only AND `formatter === 'Currency'` (otherwise empty), suffix set to `'%'` only when read-only AND `formatter === 'Percentage'` (otherwise empty), decimal separator set to the locale-derived decimal indicator, thousands separator set to the locale-derived group separator only when `showGroupSeparators` is truthy (otherwise empty string), decimal scale set to `undefined` when read-only AND `formatter === 'Currency'` (otherwise `decimalPrecision`), the value-change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, small size, and the read-only/test-id attributes applied to the underlying input element.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** A lifecycle effect watching `value` updates `values` (converted to string).
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+4. **Separators:** Derive the decimal indicator and digit group separator from the project's currency utility helpers using `currencyISOCode`. Apply the thousands separator only when `showGroupSeparators` is truthy (otherwise pass an empty string).
+5. **Formatted value (computed eagerly):** When `formatter === 'Currency'`, compute the formatted value using the project's formatting helper with format key `'currency'` and the currency options; otherwise compute using the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key with the same options.
+6. **Prefix/Suffix (read-only only):**
+   - Prefix: the currency symbol when read-only AND `formatter === 'Currency'`, otherwise empty.
+   - Suffix: `'%'` when read-only AND `formatter === 'Percentage'`, otherwise empty.
+7. **Decimal scale:** `undefined` when read-only AND `formatter === 'Currency'` (let the formatter decide), otherwise `decimalPrecision`.
+8. **On value change:** Update `values` with the raw numeric string from the masking library's callback.
+9. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`.
+10. **Read-only:** Set the read-only attribute on the underlying input. Switch to a flat/borderless visual style. Omit the blur handler.
+11. **Render ordering:** state → read-only flag → formatted value → display modes → test-id + handlers → main render.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the formatted value.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+
+The formatted value is computed before the display-mode check:
+
+- `formatter === 'Currency'` → currency-formatted string.
+- Otherwise → decimal-formatted string using the component's type name as the format key.
+
+## Read-Only Rendering
+
+Keep the numeric-format input with the read-only attribute set. Apply prefix (currency symbol) or suffix (`%`) based on `formatter`. Use a flat/borderless visual style.
+
+## Visual Specifications
+
+| Property            | Standard (editable)                  | Read-only                                            |
+| ------------------- | ------------------------------------ | ---------------------------------------------------- |
+| Width               | 100%                                 | 100%                                                 |
+| Size                | Small                                | Small                                                |
+| Variant             | Outlined                             | Flat/borderless                                      |
+| 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 the `placeholder` input         | —                                                    |
+
+## Edge Cases & Special Logic
+
+- In read-only Currency mode, decimal scale is set to `undefined` (let the formatter decide), not `decimalPrecision`.
+- `thousandSeparator` defaults to empty string (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
+
+- A numeric-format masking library (for locale-aware decimal/thousands display within a text input).
+- The project's currency utility helpers — for decimal indicator, digit group separator, and currency symbol lookup.
+- The project's currency options helper — for formatting options based on ISO code.
+- The project's formatting helpers — specifically the named `format` export (not a method on the default export). Use it as a standalone function, not as a property of the default-exported object.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+
+## Design System Mapping
+
+**UI control type:** Decimal / numeric formatted input.
+
+When implementing in a specific design system, map the following:
+
+- **Numeric format input** → use a numeric masking library compatible with the project's framework, or implement custom input masking
+- **Decimal/thousands separators** → derive from the currency utility helpers based on the ISO code
+- **Read-only prefix/suffix** → conditionally display the currency symbol or `%` sign
+- **Error state** → the DS's error/danger visual state
+- **Flat/borderless style** → the DS's read-only/standard input variant

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

@@ -0,0 +1,136 @@
+# 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, input contract, 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 the project's component map)
+
+## Inputs (component-specific)
+
+| 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) |
+| `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                             |
+
+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 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` 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 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.
+   - 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: 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`:** 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 the read-only attribute on the select element. Flat/borderless style. Change handler removed.
+
+## Visual Specifications
+
+| Property           | Standard (editable)                  | Read-only       |
+| ------------------ | ------------------------------------ | --------------- |
+| Width              | 100%                                 | 100%            |
+| Size               | Small                                | Small           |
+| 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                       | —               |
+
+**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
+
+- 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
+- Display mode check must resolve the key→value mapping before localizing and rendering.
+
+## Dependencies
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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

@@ -0,0 +1,99 @@
+# 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, 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 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 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 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`:** 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`, 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 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 `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.
+- The blur handler is only attached when the field is not read-only.
+
+## Dependencies
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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)

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

@@ -0,0 +1,88 @@
+# 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, input contract, 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 the project's component map)
+
+## Inputs (component-specific)
+
+| Input          | Type                    | Description                                       |
+| -------------- | ----------------------- | ------------------------------------------------- |
+| `children`     | array of child elements | 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 the project's field input contract.
+
+## Implementation Structure
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldGroup`). Define the input contract as the project's field input contract extended with `children` (array of child elements), `heading: string`, `showHeading: boolean`, `instructions?: string`, `collapsible: boolean`, and `type: string`.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldGroup` via the project's component registry.
+2. **Receive inputs** — `children`, `heading`, `showHeading`, `instructions`, `collapsible`, `displayMode`, `type`.
+3. **Derived flag** — `isReadOnly = displayMode === 'DISPLAY_ONLY'`.
+4. **Memoized content grid** (dependencies: `children`, `type`, `isReadOnly`) — build a grid container (spacing 2) where each child is wrapped in a full-width grid item, preserving each child's key.
+5. **Null guard** — if `!children`, return `null`.
+6. **Return `FieldGroup` wrapper** — pass `name` as `heading` only when `showHeading` is true (otherwise `undefined`), plus `collapsible` and `instructions`, wrapping the memoized content grid.
+
+## 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 a memoized computation (dependencies: `children`, `type`, `isReadOnly`):
+   - Each child gets a full-width grid item (100% column width in a 12-column grid system or equivalent).
+   - Children are mapped with their unique key 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 the project's component registry with key `'FieldGroup'`. Receives `name`, `collapsible`, and `instructions` inputs.
+
+## Display Mode Rendering
+
+`displayMode` is not explicitly handled — it's passed through as an input 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: a grid container with spacing 2, where each child occupies a full-width grid item.
+
+**Visual-only styling notes:** The children grid uses a single-column layout with a consistent gap between items.
+
+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
+
+- **Memoized computation dependencies:** `children`, `type`, `isReadOnly` — the grid re-renders only when these change, not on every parent render.
+- Children must have stable keys for reconciliation.
+- `instructions` may be undefined — `FieldGroup` should handle this gracefully.
+
+## Dependencies
+
+- The project's component registry to resolve `FieldGroup` — the design system extension providing the collapsible container.
+- A grid layout mechanism for arranging children in a single-column layout with consistent spacing.
+
+## Design System Mapping
+
+**UI control type:** Collapsible field group container with heading.
+
+When implementing in a specific design system, map the following: a grid container component with consistent spacing (gap of 2 units) where each child occupies a full-width row, and a collapsible section/panel component for the outer `FieldGroup` wrapper. The collapsible panel should support an optional title, collapse/expand toggle, and an instructions area. Native HTML equivalents include `<fieldset>` or `<details>/<summary>` for collapsibility.

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

@@ -0,0 +1,102 @@
+# Skill: Integer
+
+Integer-only text input that filters out decimal separators, binds to a Pega case property.
+
+> **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 restricted to integer values. Actively filters out decimal (`.`) and thousands separator (`,`) characters as the user types, mimicking Pega's native integer field behavior. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Integer`
+- **Type / Subtype:** `Field` / `Integer`
+- **Registration key:** `Integer` (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. The key differentiator from TextInput is the character filtering in the change handler.
+
+**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 it 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).
+8. **Test ID** — build a test-id attribute from `testId`.
+9. **Change handler with character filtering** — read the attempted value from the change event, check whether its last character is a disallowed character (`.` or `,`), and if so strip that last character before updating the DOM value; then update local `inputValue` with the (possibly trimmed) value. This mimics Pega's native integer field behavior of blocking decimal/thousands separators as the user types.
+10. **Blur handler** — commit to store via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+11. **Render** — a text input configured with: input type `text` (explicitly NOT `number`, to retain full control over character filtering), full width, outlined style, small size, 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'`, and HTML input attributes `inputMode: 'numeric'` and `pattern: '[0-9]*'` merged with the test-id attribute to hint numeric keyboards on mobile while still filtering as plain text.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching `value` updates `inputValue`.
+3. **On change (character filtering):** Before updating local state, inspect the last character typed:
+   - If the last character is `.` or `,`, strip it from the value (slice off the last character).
+   - Then update local state with the sanitized value.
+   - This "eating" of separator characters replicates Pega's native integer field behavior.
+4. **Input mode:** Set `inputMode='numeric'` and `pattern='[0-9]*'` on the input element for mobile keyboards.
+5. **Input type:** Use `type='text'` (NOT `type='number'`) — this avoids browser-specific number input quirks.
+6. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+7. **Read-only:** Delegate to `TextInput`, passing all inputs through.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value`.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`, passing all inputs through.
+
+## Visual Specifications
+
+Identical to `TextInput` visually:
+
+| Property      | Value                                        |
+| ------------- | -------------------------------------------- |
+| Width         | 100%                                         |
+| Size          | Small (~40px height)                         |
+| Variant       | Outlined                                     |
+| Border        | 1px solid                                    |
+| Border radius | 4px                                          |
+| Error state   | Red border + red helper text                 |
+| Input mode    | `numeric` (shows numeric keyboard on mobile) |
+| Pattern       | `[0-9]*`                                     |
+
+## Edge Cases & Special Logic
+
+- **Character filtering is inline** — do NOT use `type='number'` as it introduces inconsistent behavior across browsers (e.g., accepts `e`, `+`, `-` by default).
+- The disallowed characters array is `['.', ',']` — both decimal point and thousands separator are rejected.
+- Strip only the LAST character if it is disallowed — do not strip from anywhere else in the string (user may paste a valid integer that is then validated by blur).
+- The blur handler is omitted when `readOnly`.
+
+## Dependencies
+
+- 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.
+
+## Design System Mapping
+
+**UI control type:** Numeric text input (integer-only).
+
+When implementing in a specific design system, map the following:
+
+- **Text input** → use the DS's text input with `type='text'`, `inputMode='numeric'`, `pattern='[0-9]*'`
+- **Character filtering** → implement in the change handler (strip `.` and `,` from the last character)
+- **Read-only mode** → delegate to the `TextInput` component
+- **Error state** → the DS's error/danger visual state