@pega/sdk 0.0.2 → 0.0.3

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

@@ -0,0 +1,92 @@
+---
+description: Field component skill: Integer
+alwaysApply: false
+---
+
+# 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, props interface, 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 `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 (character filtering):** Before updating local state, inspect the last character typed:
+   - If the last character is `.` or `,`, strip it from the value: `event.target.value = theAttemptedValue.slice(0, -1)`.
+   - 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 `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+7. **Read-only:** Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## 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).
+- `onBlur` is omitted when `readOnly`.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils`
+- `getComponentFromRegistry('TextInput')` — for read-only delegation
+- `getComponentFromRegistry('FieldValueList')` — for display modes
+
+## Design System Mapping
+
+**UI control type:** Numeric text input (integer-only) — use `<input type="text" inputmode="numeric" pattern="[0-9]*">`.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text" inputMode="numeric" pattern="[0-9]*">` |
+| MUI | `<TextField type='text' slotProps={{ htmlInput: { inputMode: 'numeric', pattern: '[0-9]*' } }} />` |
+| Ant Design | `<InputNumber precision={0} />` or `<Input />` with custom `onChange` filter |
+| Chakra UI | `<NumberInput allowMouseWheel={false} />` or plain `<Input>` with filter |

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

@@ -0,0 +1,141 @@
+---
+description: Field component skill: Location
+alwaysApply: false
+---
+
+# Skill: Location
+
+Location input with Google Maps Places autocomplete, interactive map display, and optional geolocation (current location).
+
+> **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 text input that integrates with Google Maps Places API for address/location autocomplete. Optionally shows an interactive map with a marker. Supports an `onlyCoordinates` mode that stores `"lat, lng"` instead of address text. Includes a "get current location" button using the browser geolocation API.
+
+## Pega Metadata
+
+- **Pega Name:** `Location`
+- **Type / Subtype:** `Field` / `Text-Location`
+- **Registration key:** `Location` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `coordinates` | `string` (optional) | `''` | Comma-separated lat/lng string (e.g., `'18.5204, 73.8567'`) |
+| `onlyCoordinates` | `boolean` (optional) | `false` | If `true`, store and display lat/lng coordinates instead of address text |
+| `showMap` | `boolean` (optional) | — | Show the interactive map in editable mode |
+| `showMapReadOnly` | `boolean` (optional) | — | Show the map in read-only mode |
+
+## Behavioral Contract
+
+1. **APIs required:**
+   - Google Maps JavaScript API with `places` and `geocoding` libraries
+   - API key obtained from `pConn.getGoogleMapsAPIKey?.() || ''`
+2. **Local state:**
+   - `inputValue` (string): shown in the text input
+   - `mapCenter` (`{lat, lng}`): default `{ lat: 18.5204, lng: 73.8567 }` (Pune, India)
+   - `markerPosition` (`{lat, lng} | null`)
+3. **Value sync:** `useEffect` watching `value`, `coordinates`, `onlyCoordinates`:
+   - If `onlyCoordinates && coordinates`: `setInputValue(coordinates)`
+   - Else: `setInputValue(value ?? '')`
+   - If `coordinates` exists: parse `lat, lng`, update `mapCenter` and `markerPosition`
+4. **Places Autocomplete (init):** `useEffect` watching `isLoaded` — once Maps API loads and `inputRef.current` is set, attach `new google.maps.places.Autocomplete(inputRef.current)` and add `place_changed` listener.
+5. **On place changed:**
+   - Get `place.geometry.location` → extract `lat`, `lng`
+   - If `onlyCoordinates`: `inputValue = "${lat}, ${lng}"`, commit this as the value AND update `coordinates` property
+   - Else: `inputValue = place.formatted_address`, commit address as value, update `coordinates` property separately: `actions.updateFieldValue(coordPropName, coordinateString)`
+   - Update `mapCenter` and `markerPosition`
+6. **On text change (manual):**
+   - Update `inputValue` and commit immediately via `handleEvent(actions, 'changeNblur', propName, newValue)`
+   - If input cleared and `coordPropName` exists: `actions.updateFieldValue(coordPropName, '')`; `setMarkerPosition(null)`
+7. **Get current location button:**
+   - Use `navigator.geolocation.getCurrentPosition()`
+   - If `onlyCoordinates`: store `"lat, lng"` as value and coordinates
+   - Else: reverse-geocode using `google.maps.Geocoder`, store address as value, `"lat, lng"` as coordinates
+8. **Coordinate property name:** `coordPropName = (pConn.getStateProps() as any).coordinates` — separate from the main `propName`
+9. **Error display:** If `status === 'error' && !!validatemessage && !disabled`, show an error alert ABOVE the input.
+10. **Read-only:** Delegate text to `TextInput`, optionally show map if `showMapReadOnly`.
+
+### Map configuration (disabled state)
+
+When `disabled`, map options disable all interactions:
+- `gestureHandling: 'none'`, `keyboardShortcuts: false`, `disableDefaultUI: true`, `clickableIcons: false`
+- Map opacity: `0.7` when disabled
+
+### CSS for Google Maps autocomplete dropdown z-index:
+```css
+/* Location.css */
+.pac-container { z-index: 2147483647; }
+```
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw address/coordinates string.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+```
+<div>
+  <TextInput {...props} />
+  {isLoaded && showMapReadOnly && <GoogleMap ... />}
+</div>
+```
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Input variant | Default (outlined, from `TextField`) |
+| Trailing icon | Location pin icon button (for current location) |
+| Error alert | Alert banner ABOVE the input field when `hasError` |
+| Map container | `width: 100%`, `height: 300px`, `marginTop: 0px` |
+| Map render | Only shown when `isLoaded && (showMap || showMapReadOnly)` |
+| Disabled map opacity | `0.7` |
+
+**CSS companion file required:** `Location.css` with:
+```css
+.pac-container { z-index: 2147483647; }
+```
+This ensures the Google Maps autocomplete dropdown appears above modal/dialog overlays.
+
+**CSS-only implementation notes:**
+- Location pin button: `<button>` with `position: absolute; right: 8px; top: 50%; transform: translateY(-50%);`
+
+## Edge Cases & Special Logic
+
+- **`isLoaded` guard:** Only render the `TextField` and map after Google Maps API is fully loaded.
+- **`onlyCoordinates` mode:** The stored `value` is `"lat, lng"` format; coordinates and address are the same.
+- **Dual property:** The component writes to TWO properties — `propName` (address or coordinates) and `coordPropName` (coordinates). `coordPropName` may be undefined if the Pega config doesn't include a coordinates property.
+- **Autocomplete ref lifecycle:** `autocompleteRef` is only initialized once (when `!autocompleteRef.current`). The `handlePlaceChanged` callback must be stable (`useCallback` with deps).
+- **Map default center:** Pune, India — `{ lat: 18.5204, lng: 73.8567 }`.
+- Google Maps Geocoder is only called in non-`onlyCoordinates` geolocation mode for reverse geocoding.
+
+## Dependencies
+
+- Google Maps JavaScript API (loaded dynamically via `@react-google-maps/api` or equivalent loader).
+- `@react-google-maps/api` — `GoogleMap`, `Marker`, `useLoadScript`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- A location pin icon.
+
+**CSS companion:** `Location.css` — must be imported to fix autocomplete z-index.
+
+## Design System Mapping
+
+**UI control type:** Text input with location autocomplete dropdown + optional map.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` + Google Maps Autocomplete API + Google Map embed |
+| MUI | `<TextField>` + `InputAdornment` for icon + `@react-google-maps/api` |
+| Ant Design | `<Input suffix={<LocationIcon />}>` + Google Maps |
+| Chakra UI | `<InputGroup>` + `<InputRightElement>` + Google Maps |

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

@@ -0,0 +1,169 @@
+---
+description: Field component skill: Multiselect
+alwaysApply: false
+---
+
+# Skill: Multiselect
+
+Multi-select autocomplete field supporting flat lists, grouped/hierarchical data, reference list binding, and debounced search.
+
+> **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 multi-value typeahead input where users can search and select multiple items. Supports flat datasources, grouped/hierarchical data, reference lists (embedded page lists), and debounced async search. Manages selection state and commits changes via reference list instructions.
+
+## Pega Metadata
+
+- **Pega Name:** `Multiselect`
+- **Type / Subtype:** `Field` / `Picklist-Multi`
+- **Registration key:** `Multiselect` (in `component-map.ts`)
+
+> **Note:** `Multiselect` does NOT extend `PConnFieldProps` — it uses raw `props` (no typed interface in the reference implementation). Define props as needed for your implementation.
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `getPConnect` | `function` | — | PConnect accessor |
+| `label` | `string` | — | Field label |
+| `placeholder` | `string` | — | Input placeholder |
+| `referenceList` | `any[]` | — | Currently selected items from embedded page list |
+| `selectionKey` | `string` | — | Property path used as the selection key |
+| `primaryField` | `string` | — | Property path for the primary display field |
+| `initialCaseClass` | `string` | — | Case class for context in search |
+| `selectionList` | `string` | — | Property path of the reference list |
+| `datasource` | `any[]` | `[]` | Flat data source |
+| `columns` | `any[]` | `[{}]` | Column config for key/value extraction |
+| `listType` | `string` | `''` | `'associated'`, `'datapage'`, `'promptList'`, `'localList'` |
+| `isGroupData` | `boolean` | `false` | Whether to use grouped/hierarchical data |
+| `groupDataSource` | `any[]` | `[]` | Data source for grouped display |
+| `groupColumnsConfig` | `any[]` | `[{}]` | Column config for group display |
+| `referenceType` | `string` | — | `'Case'` or `'Data'` |
+| `secondaryFields` | `any` | — | Additional secondary display fields |
+| `showSecondaryInSearchOnly` | `boolean` | `false` | Show secondary fields only during search |
+| `parameters` | `object` | `{}` | Data page query parameters |
+| `matchPosition` | `string` | `'contains'` | Search match position (`'contains'`, `'startsWith'`) |
+| `maxResultsDisplay` | `string` | — | Max results to display (`'100'` default) |
+| `value` | `any` | — | Current value |
+
+## Behavioral Contract
+
+### Reference List Mode (when `referenceList.length > 0`)
+
+When `referenceList` has items, override datasource and columns:
+- `datasource = referenceList`
+- Build `columns`: primary display field, key field, secondary columns (from `secondaryFields` or default to `selectionKey`)
+- If `referenceType === 'Case'`: append secondary columns
+
+### Data Config
+
+Build a `dataConfig` object (memoized with deep comparison) containing:
+- `dataSource`, `groupDataSource`, `isGroupData`, `showSecondaryInSearchOnly`, `parameters`, `matchPosition`, `listType`, `maxResultsDisplay`
+- `columns`: preprocessed (strip leading `.` from value fields)
+- `groupColumnsConfig`: preprocessed
+
+### Items Tree
+
+- `displayFieldMeta`: derived from `columns` when `listType !== 'associated'`
+- `groupsDisplayFieldMeta`: derived from `groupColumnsConfig` when `listType !== 'associated'`
+- `itemsTree` state: for `isGroupData` mode, initialized from `getGroupDataForItemsTree(groupDataSource, groupsDisplayFieldMeta, showSecondaryInSearchOnly)`; otherwise `[]`
+
+### Data API Initialization
+
+In `useEffect` watching `dataConfig` (non-associated lists):
+```
+PCore.getDataApi().init(dataConfig, contextName).then(dataObj => {
+  dataApiObj.current = dataObj
+  if (!isGroupData) {
+    getCaseListBasedOnParamsDebounced.current(inputValue ?? '', '', [...selectedItems], [...itemsTree])
+  }
+})
+```
+
+### Search
+
+`getCaseListBasedOnParams(searchText, group, selectedRows, currentItemsTree, isTriggeredFromSearch)`:
+1. If `referenceList.length > 0`: get currently selected rows from `listActions.getSelectedRows(true)`, map to `{id, primary}` format, update `selectedItems` state.
+2. Build `initalItemsTree`: use fresh data if `isTriggeredFromSearch || !currentItemsTree`, else current.
+3. Call `doSearch(...)` to get filtered results.
+4. `setItemsTree(results)`.
+
+**Debounce:** 500ms debounce on `getCaseListBasedOnParams` via `getCaseListBasedOnParamsDebounced` ref.
+
+### Mount Effects
+
+- `useEffect([pConn])`: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
+- `useEffect([])`: set up debounced search ref.
+
+### Selection Changes (`handleChange`)
+
+When selection changes (user adds/removes item):
+1. Mark all currently selected items as `selected: true`.
+2. Determine if this was an add or remove.
+3. Update `itemsTree` selections in-place.
+4. `setSelectedItems(updatedItems)`, `setItemsTree(itemsTree)`.
+5. Reset `inputValue` to `''`.
+6. If `referenceList`: call `setSelectedItemsForReferenceList(clickedItem[0])`.
+
+`setSelectedItemsForReferenceList`: calls `insertInstruction` (if `selected: true`) or `deleteInstruction` (if `selected: false`) and clears error messages.
+
+### Search Input
+
+`onSearchHandler`: updates `inputValue` state and calls debounced search with `isTriggeredFromSearch=true`.
+
+## Display Mode Rendering
+
+No explicit `displayMode` handling in the reference implementation — Multiselect is rendered directly by parent components when display mode is needed. If `displayMode` support is needed, implement similar to Dropdown.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant | Outlined |
+| Multiple values | Tags/chips shown inside the input box |
+| Dropdown | Shows filtered options with checkboxes |
+| Close on select | Off (`disableCloseOnSelect`) — user can select multiple before closing |
+| Option label | `option.primary` field |
+| Placeholder | From `placeholder` prop |
+| Error state | Red border + red helper text |
+
+**CSS-only notes:**
+```css
+.multiselect-tags { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px; border: 1px solid rgba(0,0,0,0.23); border-radius: 4px; }
+.multiselect-tag { background: rgba(0,0,0,0.08); border-radius: 16px; padding: 2px 8px; font-size: 0.8125rem; display: flex; align-items: center; gap: 4px; }
+.multiselect-tag-delete { cursor: pointer; font-size: 0.75rem; }
+```
+
+## Edge Cases & Special Logic
+
+- **`dataConfig` deep memoization:** Use custom deep-equal hook (`useDeepMemo`) to avoid re-initializing data API on every render.
+- `itemsTreeBaseData` is fixed at render time — used as the base for each fresh search.
+- When `isGroupData=false`: debounced search fires after data API init.
+- When `isGroupData=true`: groups are pre-populated from `groupDataSource`.
+- The `selected` flag on items in `itemsTree` tracks selection state in the dropdown.
+
+## Dependencies
+
+- `doSearch`, `getDisplayFieldsMetaData`, `useDeepMemo`, `preProcessColumns`, `getGroupDataForItemsTree` from `./utils` (local utils file).
+- `insertInstruction`, `deleteInstruction` from `../../helpers/instructions-utils`.
+- `debounce` from `throttle-debounce` library (or any debounce utility).
+- `PCore.getDataApi()` — for data initialization.
+- Multi-select autocomplete UI widget.
+
+## Design System Mapping
+
+**UI control type:** Multi-select combobox with tags/chips and searchable dropdown.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Custom tag input + filterable dropdown list |
+| MUI | `<Autocomplete multiple disableCloseOnSelect>` |
+| Ant Design | `<Select mode="multiple" showSearch>` |
+| Chakra UI | Third-party multi-select (e.g., Chakra React Select) |

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

@@ -0,0 +1,169 @@
+---
+description: Field component skill: ObjectReference
+alwaysApply: false
+---
+
+# Skill: ObjectReference
+
+Composite field that dynamically renders a child component (Dropdown, AutoComplete, or SemanticLink) for referencing another Pega case or data object. Supports editable-in-review mode with direct case update.
+
+> **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
+
+Does NOT render a UI control directly. Instead, it reads the raw metadata to determine which child component type to render (`Dropdown`, `AutoComplete`, or `SemanticLink`), constructs that child component via `getPConnect().createComponent(...)`, and renders it inside a grid container. Also handles editable-in-review mode where the user can change a reference field while viewing a case.
+
+## Pega Metadata
+
+- **Pega Name:** `ObjectReference`
+- **Type / Subtype:** `Field` / `Reference`
+- **Registration key:** `ObjectReference` (in `component-map.ts`)
+
+## Props (component-specific)
+
+> Uses `Omit<PConnFieldProps, 'value'>` — no direct `value` prop.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `getPConnect` | `any` | — | PConnect accessor |
+| `displayMode` | `any` | — | Display mode |
+| `allowAndPersistChangesInReviewMode` | `any` | `false` | Whether the reference can be edited while in review/display mode |
+| `targetObjectType` | `any` | — | `'case'` or `'data'` — determines `referenceType` |
+| `mode` | `string` | `''` | `'single'` or `'multi'` (SELECTION_MODE) |
+| `parameters` | `object` | — | Data page query parameters |
+| `hideLabel` | `boolean` | `false` | Whether to hide label |
+| `inline` | `boolean` | `false` | Whether to render inline |
+| `showPromotedFilters` | `boolean` | `false` | Show promoted filters in child |
+| `additionalFields` | `any` | — | Additional fields for read-only display |
+
+## Behavioral Contract
+
+### Setup
+
+1. `referenceType = targetObjectType === 'case' ? 'Case' : 'Data'`
+2. `rawViewMetadata = pConn.getRawMetadata()` — the raw component metadata from Pega config
+3. `refFieldMetadata = pConn.getFieldMetadata(rawViewMetadata?.config?.value?.split('.', 2)[1])`
+4. `propsToUse = { ...pConn.getInheritedProps(), ...props }` — merged inherited + local props
+5. `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`
+6. `canBeChangedInReviewMode = editableInReview && ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType)`
+
+### Subsection: Read-only variants (display mode, non-editable)
+
+**If `componentType === 'SemanticLink'` and `!canBeChangedInReviewMode`:**
+Build a SemanticLink config from rawViewMetadata and call `getPConnect().createComponent({ type: 'SemanticLink', config: {...} })`. Config includes:
+- `displayField` → `primaryField` and `text`
+- `value` → `caseID`
+- `resourceParams: { workID: value }`, `resourcePayload: { caseClassName: caseClass }`
+- `displayMode`, `referenceType`, `hideLabel`, `dataRelationshipContext`
+
+**If `isDisplayModeEnabled && !canBeChangedInReviewMode` (other types):**
+Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, passing:
+- `label`, `type`, `displayAs='readonly'`, `displayMode`, `referenceType`, `hideLabel`, `dataRelationshipContext`, `additionalFields`
+
+### Subsection: Editable variants (including editable-in-review)
+
+**If NOT in a read-only case:**
+
+1. **Set datasource:** Call `generateColumns(rawViewMetadata.config, pConn, referenceType)` to populate column config.
+   - Set `rawViewMetadata.config.deferDatasource = true`
+   - Set `rawViewMetadata.config.listType = 'datapage'`
+   - Set default placeholder `'@L Select...'` for Dropdown/AutoComplete if missing
+
+2. **Pass-through configs:**
+   - `rawViewMetadata.config.showPromotedFilters = showPromotedFilters`
+   - If `!canBeChangedInReviewMode`: set `rawViewMetadata.config.displayMode = displayMode`
+
+3. **Build fieldMetaData:**
+   ```
+   fieldMetaData = { datasourceMetadata: { datasource: { parameters: {} } } }
+   ```
+   - Set `propertyForDisplayText` from `datasource.fields.text` (strip `@P ` prefix)
+   - Set `propertyForValue` from `datasource.fields.value` (strip `@P ` prefix)
+   - Set `name` from `referenceList`
+   - If `rawViewMetadata.config.parameters`: assign `parameters` prop
+
+4. **Create child component:**
+   ```
+   getPConnect().createComponent({
+     type,  // 'Dropdown' or 'AutoComplete'
+     config: {
+       ...rawViewMetadata.config,
+       descriptors: mode === SELECTION_MODE.SINGLE ? refFieldMetadata?.descriptors : null,
+       datasourceMetadata: fieldMetaData.datasourceMetadata,
+       required, visibility, disabled, label, parameters, readOnly: false,
+       localeReference, referenceType (for single mode only),
+       contextClass: targetObjectClass,
+       primaryField: displayField,
+       dataRelationshipContext,
+       hideLabel, onRecordChange, inline
+     }
+   })
+   ```
+
+### `onRecordChange` handler
+
+Called when user selects a new value in editable/editable-in-review mode:
+1. Build `refreshOptions = { autoDetectRefresh: true, propertyName: rawViewMetadata.config?.value }`
+2. If `!canBeChangedInReviewMode || !pConn.getValue('__currentPageTabViewName')`: call `getPConnect().getActionsApi().refreshCaseView(caseKey, viewName, pgRef, refreshOptions)`.
+3. Extract `propValue = event?.id || event?.target?.value`.
+4. For multi mode (`SimpleTableSelect`): `propName = getPropertyName(rawViewMetadata.config.selectionList)`, else `propName = getPropertyName(rawViewMetadata.config.value)`.
+5. If `propValue && canBeChangedInReviewMode && isDisplayModeEnabled`:
+   - Get edit lock via `PCore.getCaseUtils().getCaseEditLock(caseKey, '')`
+   - Build commit data from page reference path
+   - Call `PCore.getCaseUtils().updateCaseEditFieldsData(...)` to persist the change
+   - Update container's last update time and etag
+
+### Memoization
+
+`recreatedFirstChild` is memoized with `useMemo` — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+
+## Display Mode Rendering
+
+Display mode is passed through to the child component — the child (Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly) handles its own display mode rendering.
+
+## Visual Specifications
+
+ObjectReference itself renders a minimal grid container:
+```
+<Grid container>
+  <Grid>{recreatedFirstChild}</Grid>
+</Grid>
+```
+
+The visual appearance is entirely determined by the child component being rendered. No additional styling is applied by `ObjectReference` itself.
+
+**CSS-only implementation:**
+```css
+.object-reference-container { display: grid; width: 100%; }
+```
+
+## Edge Cases & Special Logic
+
+- **`generateColumns`**: a utility from `./utils` that populates `rawViewMetadata.config` with proper column definitions for the child Dropdown/AutoComplete.
+- **`getDataRelationshipContextFromKey`**: extracts the relationship context from a field key (also from `./utils`).
+- `rawViewMetadata.config` is mutated in place before being passed to `createComponent` — this is intentional but means the component re-creates the child on relevant prop changes.
+- For `SemanticLink` type, the child is created via `createComponent`, not rendered as a direct React element.
+- `SELECTION_MODE.SINGLE` and `SELECTION_MODE.MULTI` constants from `./utils`.
+
+## Dependencies
+
+- `SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey` from `./utils` (local).
+- `getComponentFromRegistry('SingleReferenceReadOnly')` — for display-only non-SemanticLink.
+- `PCore.getCaseUtils()`, `PCore.getAnnotationUtils()`, `PCore.getContainerUtils()` — for editable-in-review updates.
+- `useMemo` from React.
+- No `handleEvent` — selection handling is done by the child component via `onRecordChange`.
+
+## Design System Mapping
+
+**UI control type:** Composite wrapper — renders Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly. No dedicated UI control.
+
+Listed design systems are examples only.
+
+| Scenario | Rendered Child |
+|----------|----------------|
+| `componentType='Dropdown'` (editable) | `Dropdown` component |
+| `componentType='AutoComplete'` (editable) | `AutoComplete` component |
+| `componentType='SemanticLink'` | `SemanticLink` component |
+| `displayMode='DISPLAY_ONLY'` (non-editable-in-review) | `SingleReferenceReadonly` component |

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

@@ -0,0 +1,97 @@
+---
+description: Field component skill: Percentage
+alwaysApply: false
+---
+
+# Skill: Percentage
+
+Percentage numeric input with a `%` suffix and locale-aware decimal/thousands separators.
+
+> **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 for percentage values. Always appends a `%` suffix in the input. Supports configurable decimal precision and optional thousands separator. Shows a formatted percentage string in display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `Percentage`
+- **Type / Subtype:** `Field` / `Decimal-Percentage`
+- **Registration key:** `Percentage` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO code used for locale-aware decimal/thousands separator lookup only (not for currency symbol) |
+| `showGroupSeparators` | `string` (optional) | — | Whether to show thousands separators (passed as string, truthy check applies) |
+| `decimalPrecision` | `number` (optional) | — | Number of decimal places |
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Separators:** Derive `decimalSeparator` and `thousandSeparator` from locale lookup using `currencyISOCode` (same as Currency/Decimal). Apply `thousandSeparator` only when `showGroupSeparators` is truthy.
+4. **Suffix:** Always append `%` suffix to the numeric input.
+5. **Decimal scale:** Use `decimalPrecision` prop.
+6. **No prefix:** Unlike Currency, no prefix symbol.
+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. Flat/borderless style. `onBlur` omitted.
+
+## Display Mode Rendering
+
+Format the value using the percentage formatter before display:
+- `formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), currencyOptions)`
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Keep numeric format input with `readOnly: true` and `%` suffix still visible. Flat/borderless style.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant editable | Outlined |
+| Variant read-only | Standard (flat) |
+| Suffix | `%` (always shown after the value) |
+| Thousands separator | Only when `showGroupSeparators` is truthy |
+| Decimal scale | `decimalPrecision` |
+| Placeholder | From `placeholder` prop |
+| Error state | Red border + red helper text |
+
+**CSS-only notes:** Achieve the `%` suffix by wrapping the input in a relative container and absolutely positioning a `%` label at the right side, or using an input with a `::after` pseudo-element technique.
+
+## Edge Cases & Special Logic
+
+- `showGroupSeparators` is typed as `string` (not `boolean`) in the reference implementation — apply truthy check.
+- `currencyISOCode` is only used for separator lookup (decimal/thousands), NOT for a currency symbol.
+- The stored value is always a raw numeric string (e.g., `'45.5'`), not `'45.5%'`.
+
+## Dependencies
+
+- Numeric formatting library (e.g., `react-number-format`'s `NumericFormat`).
+- `getCurrencyCharacters(currencyISOCode)` — for `theDecimalIndicator`, `theDigitGroupSeparator`.
+- `getCurrencyOptions(currencyISOCode)` — for `format()` call.
+- `format()` from `../../helpers/formatters`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Percentage numeric input with `%` suffix.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` + custom masking + `%` suffix span |
+| MUI | `NumericFormat` with `suffix='%'` and `customInput={TextField}` |
+| Ant Design | `<InputNumber suffix="%" precision={decimalPrecision} />` |
+| Chakra UI | `<NumberInput>` + `<InputRightAddon>%</InputRightAddon>` |