@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,142 @@
+# 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, input contract, 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 the project's component map)
+
+## Inputs (component-specific)
+
+| Input             | 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                                           |
+
+## Implementation Structure
+
+Follow this exact structure. This component is complex — integrates Google Maps API for places autocomplete, geolocation, and optional map display.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`), the project's event-commit utility (for committing value changes to the store), and a Google Maps script loader capable of loading the `places` and `geocoding` libraries dynamically. A companion stylesheet is needed to fix the autocomplete dropdown z-index (see CSS section). Define the input contract as the project's field input contract extended with `coordinates?`, `onlyCoordinates?`, `showMap?`, and `showMapReadOnly?`. Define module-level constants: `mapContainerStyle` (`width: '100%'`, `height: '300px'`, `marginTop: '0px'`), `defaultCenter` (`{ lat: 18.5204, lng: 73.8567 }` — Pune, India), and `disabledMapOptions` (`gestureHandling: 'none'`, `keyboardShortcuts: false`, `disableDefaultUI: true`, `clickableIcons: false`).
+
+**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` (default `false`), `disabled` (default `false`), `value` (default `''`), `validatemessage`, `status`, `readOnly` (default `false`), `testId`, `displayMode`, `hideLabel` (default `false`), `placeholder`, `helperText`, `coordinates` (default `''`), `onlyCoordinates` (default `false`), `showMap`, `showMapReadOnly`.
+3. **PConnect setup** (note TWO property names) — `pConn`, `actions`, `propName` for the address/value, and a separate `coordPropName` for the coordinates property.
+4. **Local state** — `inputValue` (initialized from `value`), `mapCenter` (initialized to `defaultCenter`), and `markerPosition` (initialized to `null`).
+5. **Instance references** — `inputRef` for the text input element, `autocompleteRef` for the Google Places Autocomplete instance.
+6. **Load Google Maps API** — use a script-loading mechanism with the API key from `pConn.getGoogleMapsAPIKey?.() || ''` and the `places` and `geocoding` libraries. Track the loaded status via an `isLoaded` flag.
+7. **Error flag** — `hasError = status === 'error' && !!validatemessage && !disabled`.
+8. **Sync lifecycle effect** — watching `value`, `coordinates`, `onlyCoordinates`; see Behavioral Contract item 3.
+9. **`handleChange`** (manual text input, cached callback) — commits immediately, clears coordinates if the input is emptied.
+10. **`handlePlaceChanged`** (cached callback) — reads the selected place from the autocomplete instance reference, extracts `lat`/`lng`, and stores either the address or the coordinates depending on the `onlyCoordinates` flag.
+11. **Init Places Autocomplete** — a lifecycle effect watching `isLoaded` and the place-changed handler, guarded to run only once `isLoaded && inputRef is set && autocompleteRef is not yet set`.
+12. **`handleGetCurrentLocation`** (cached callback) — uses `navigator.geolocation.getCurrentPosition`; when `onlyCoordinates` is set, stores the coordinates directly, otherwise reverse-geocodes via `google.maps.Geocoder`.
+13. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with the raw `value`.
+14. **Map element** (shared between read-only and editable rendering) — opacity reduced to `0.7` when `disabled`, and `disabledMapOptions` applied when `disabled`.
+15. **Read-only return** — render a wrapper containing `TextInput` with all inputs spread, plus the map (once loaded) when `showMapReadOnly` is set.
+16. **Main render** — render an error alert above the input when `hasError`; only render the text field once `isLoaded`; the text field carries the input reference and a trailing location-icon button that triggers `handleGetCurrentLocation`; render the map below when `isLoaded && showMap`.
+
+## 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:** A lifecycle effect watching `value`, `coordinates`, `onlyCoordinates`:
+   - If `onlyCoordinates && coordinates`: set `inputValue` to `coordinates`
+   - Else: set `inputValue` to `value ?? ''`
+   - If `coordinates` exists: parse `lat, lng`, update `mapCenter` and `markerPosition`
+4. **Places Autocomplete (init):** A lifecycle effect watching `isLoaded` — once Maps API loads and the input element reference is set, attach `new google.maps.places.Autocomplete(inputElement)` and add `place_changed` listener.
+5. **On place changed:**
+   - Get `place.geometry.location` → extract `lat`, `lng`
+   - If `onlyCoordinates`: set `inputValue` to `"lat, lng"` format, commit this as the value AND update the coordinates property
+   - Else: set `inputValue` to `place.formatted_address`, commit address as value, update coordinates property separately via `actions.updateFieldValue(coordPropName, coordinateString)`
+   - Update `mapCenter` and `markerPosition`
+6. **On text change (manual):**
+   - Update `inputValue` and commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the new value
+   - If input cleared and `coordPropName` exists: `actions.updateFieldValue(coordPropName, '')` and clear the marker position
+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:
+
+A companion stylesheet sets the `.pac-container` (the autocomplete dropdown) to the maximum z-index value, ensuring it appears above modal/dialog overlays.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to the label (empty string if `hideLabel`) and `value` set to the raw address/coordinates string.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` with the same name/value and a stacked variant.
+
+## Read-Only Rendering
+
+A wrapper containing `TextInput` with all inputs spread, followed by the interactive map (once loaded) when `showMapReadOnly` is set.
+
+## Visual Specifications
+
+| Property             | Value                                                        |
+| -------------------- | ------------------------------------------------------------ |
+| Width                | 100%                                                         |
+| Input variant        | Default outlined text field                                  |
+| 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:** A stylesheet that sets `.pac-container` to the maximum z-index value, ensuring the Google Maps autocomplete dropdown appears above modal/dialog overlays.
+
+**Visual-only styling notes:** The location pin button is positioned at the trailing edge of the input, vertically centered.
+
+## Edge Cases & Special Logic
+
+- **`isLoaded` guard:** Only render the text field 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 instance reference lifecycle:** The autocomplete instance is only initialized once (when the reference is not yet set). The `handlePlaceChanged` callback must be stable (cached with appropriate dependencies).
+- **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 a script loader).
+- A Google Maps rendering library providing map display, marker, and script-loading capabilities.
+- The project's event-commit utility for committing field value changes.
+- The project's component registry to resolve `TextInput` (for read-only) and `FieldValueList` (for display modes).
+- A location pin icon from the project's icon set.
+
+**CSS companion:** A stylesheet that fixes the autocomplete dropdown z-index (`.pac-container`).
+
+## Design System Mapping
+
+**UI control type:** Text input with location autocomplete dropdown + optional map.
+
+When implementing in a specific design system, map the following: a full-width outlined text field with trailing icon adornment (for the current-location button), an alert/banner component for error display above the input, and a Google Maps embed component for the interactive map. The trailing icon should be a location/pin icon wrapped in a clickable button. The autocomplete functionality comes from the Google Maps Places API directly attached to the input element, not from the design system.

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/field-skills/Multiselect.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,11 +14,11 @@ Renders a multi-value typeahead input where users can search and select multiple
 
 - **Pega Name:** `Multiselect`
 - **Type / Subtype:** `Field` / `Picklist-Multi`
-- **Registration key:** `Multiselect` (in `component-map.ts`)
+- **Registration key:** `Multiselect` (in the project's component map)
 
-> **Note:** `Multiselect` does NOT extend `PConnFieldProps` — it uses raw `props` (no typed interface in the reference implementation). Define props as needed for your implementation.
+> **Note:** `Multiselect` does NOT extend the project's field input contract — it defines its own inputs directly.
 
-## Props (component-specific)
+## Inputs (component-specific)
 
 | Prop                        | Type       | Default      | Description                                                 |
 | --------------------------- | ---------- | ------------ | ----------------------------------------------------------- |
@@ -44,6 +44,29 @@ Renders a multi-value typeahead input where users can search and select multiple
 | `maxResultsDisplay`         | `string`   | —            | Max results to display (`'100'` default)                    |
 | `value`                     | `any`      | —            | Current value                                               |
 
+## Implementation Structure
+
+This is a complex component. Note: it does NOT extend the project's field input contract — it defines its own inputs directly.
+
+**Module Setup:** The component depends on local utility helpers (`doSearch`, `getDisplayFieldsMetaData`, a deep-memoization hook, `preProcessColumns`, `getGroupDataForItemsTree`), the project's instruction helpers (`insertInstruction` and `deleteInstruction`), and a debounce utility. It does not use the standard field input contract or the project's event-commit utility — selection commits happen via the instruction helpers.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** (declare `datasource`/`columns` as reassignable since they may be overridden) — `getPConnect`, `label`, `placeholder`, `referenceList`, `selectionKey`, `primaryField`, `initialCaseClass`, `showSecondaryInSearchOnly` (default `false`), `listType` (default `''`), `isGroupData` (default `false`), `referenceType`, `secondaryFields`, `groupDataSource` (default `[]`), `parameters` (default `{}`), `matchPosition` (default `'contains'`), `maxResultsDisplay`, `groupColumnsConfig` (default `[{}]`), `selectionList`, `value`; separately destructure `datasource` (default `[]`) and `columns` (default `[{}]`) with `let`.
+2. **Reference list mode override** — when `referenceList.length > 0`, reassign `datasource` and `columns`; see the Behavioral Contract "Reference List Mode" section.
+3. **Local state** — `inputValue` initialized from `value`, and `selectedItems` initialized to `[]`.
+4. **`dataConfig`** (memoized with deep comparison via a deep-memoization utility) — see the Behavioral Contract "Data Config" section.
+5. **Display field metadata and items tree** — `displayFieldMeta`, `groupsDisplayFieldMeta`, `itemsTreeBaseData`, and an `itemsTree` state value; see the Behavioral Contract "Items Tree" section.
+6. **Instance references** — `getCaseListBasedOnParamsDebounced` and `dataApiObj` as instance references; also `pConn` via `getPConnect()`, `contextName` via `pConn.getContextName()`, and `listActions` via `pConn.getListActions()`.
+7. **`getCaseListBasedOnParams`** — the main search function; see the Behavioral Contract "Search" section.
+8. **Lifecycle effect: set reference list** — watching the PConnect instance.
+9. **Lifecycle effect: init debounced reference** — on mount.
+10. **Lifecycle effect: init data API** — watching `dataConfig` and related dependencies; calls `PCore.getDataApi().init(dataConfig, contextName)`.
+11. **`onSearchHandler`** — updates `inputValue` and triggers the debounced search.
+12. **`setSelectedItemsForReferenceList`** — inserts or deletes an instruction depending on selection state.
+13. **`handleChange`** — selection add/remove logic; see the Behavioral Contract "Selection Changes" section.
+14. **Main render** — a multi-select autocomplete widget with: `multiple`, `fullWidth`, `disableCloseOnSelect` set; `options={itemsTree}`, `value={selectedItems}`; `getOptionLabel` returning `option?.primary`; `onChange={handleChange}`; and a `renderInput` producing a text field with `label`, `placeholder`, `size='small'`, `variant='outlined'`, and `onChange={onSearchHandler}`.
+
 ## Behavioral Contract
 
 ### Reference List Mode (when `referenceList.length > 0`)
@@ -70,16 +93,7 @@ Build a `dataConfig` object (memoized with deep comparison) containing:
 
 ### 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])
-  }
-})
-```
+In a lifecycle effect watching `dataConfig` (non-associated lists), call `PCore.getDataApi().init(dataConfig, contextName)`. When the promise resolves with a data object: store it in the `dataApiObj` instance reference, and when `isGroupData` is false, invoke the debounced search function with the current `inputValue` (or `''`), an empty group, a copy of `selectedItems`, and a copy of `itemsTree`.
 
 ### Search
 
@@ -94,8 +108,8 @@ PCore.getDataApi().init(dataConfig, contextName).then(dataObj => {
 
 ### Mount Effects
 
-- `useEffect([pConn])`: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
-- `useEffect([])`: set up debounced search ref.
+- A lifecycle effect watching the PConnect instance: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
+- A mount lifecycle effect: set up the debounced search reference.
 
 ### Selection Changes (`handleChange`)
 
@@ -132,35 +146,11 @@ No explicit `displayMode` handling in the reference implementation — Multisele
 | 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;
-}
-```
+**Visual-only styling notes:** Selected values render as wrapping flex tags inside a bordered, rounded input container with a small gap and padding. Each tag has a light grey pill background, rounded corners, small padding, and a small font size, laid out as a flex row with a delete affordance at a slightly smaller font size and a pointer cursor.
 
 ## Edge Cases & Special Logic
 
-- **`dataConfig` deep memoization:** Use custom deep-equal hook (`useDeepMemo`) to avoid re-initializing data API on every render.
+- **`dataConfig` deep memoization:** Use a deep-equality memoization utility 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`.
@@ -168,21 +158,20 @@ No explicit `displayMode` handling in the reference implementation — Multisele
 
 ## 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).
+- Local utility helpers: `doSearch`, `getDisplayFieldsMetaData`, a deep-memoization utility, `preProcessColumns`, `getGroupDataForItemsTree`.
+- The project's instruction helpers (`insertInstruction`, `deleteInstruction`).
+- A debounce utility.
 - `PCore.getDataApi()` — for data initialization.
-- Multi-select autocomplete UI widget.
+- A multi-select autocomplete UI widget from the design system.
 
 ## Design System Mapping
 
 **UI control type:** Multi-select combobox with tags/chips and searchable dropdown.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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) |
+- **Multi-select autocomplete** → use the DS's multi-select combobox with tag/chip display and searchable dropdown
+- **Disable close on select** → the dropdown should stay open after each selection
+- **Option label** → display `option.primary`
+- **Selected items** → render as tags/chips inside the input area
+- **Search input** → wired to the debounced search function

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/field-skills/ObjectReference.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,11 +14,11 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 
 - **Pega Name:** `ObjectReference`
 - **Type / Subtype:** `Field` / `Reference`
-- **Registration key:** `ObjectReference` (in `component-map.ts`)
+- **Registration key:** `ObjectReference` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-> Uses `Omit<PConnFieldProps, 'value'>` — no direct `value` prop.
+> Overrides the field input contract by omitting `value` — no direct `value` input.
 
 | Prop                                 | Type      | Default | Description                                                      |
 | ------------------------------------ | --------- | ------- | ---------------------------------------------------------------- |
@@ -33,6 +33,21 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 | `showPromotedFilters`                | `boolean` | `false` | Show promoted filters in child                                   |
 | `additionalFields`                   | `any`     | —       | Additional fields for read-only display                          |
 
+## Implementation Structure
+
+This is a composite/orchestrator component — it does NOT render its own UI control. It creates a child component (Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly) via `getPConnect().createComponent()`.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `SingleReferenceReadOnly`) and local utility helpers (`SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey`). Define the input contract by overriding the project's field input contract to omit `value`, and adding `getPConnect`, `displayMode`, `allowAndPersistChangesInReviewMode`, `targetObjectType`, `mode`, `parameters`, `hideLabel`, `inline`, `showPromotedFilters`, and `additionalFields`.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** — `getPConnect`, `displayMode`, alias `allowAndPersistChangesInReviewMode` to `editableInReview` (default `false`), `targetObjectType`, `mode` (default `''`), `parameters`, `hideLabel` (default `false`), `inline` (default `false`), `showPromotedFilters` (default `false`), `additionalFields`.
+2. **Registry lookup** — resolve `SingleReferenceReadonly` (registry key `'SingleReferenceReadOnly'`) via the project's component registry.
+3. **Setup** — `pConn`; `referenceType` set to `'Case'` when `targetObjectType === 'case'`, else `'Data'`; `rawViewMetadata` via `pConn.getRawMetadata()`; `refFieldMetadata` via `pConn.getFieldMetadata()` on the second segment of the raw metadata's config value path; `propsToUse` merging `pConn.getInheritedProps()` with the component inputs; `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`; `canBeChangedInReviewMode` true when `editableInReview` is set and the raw metadata's `config.componentType` is `'Autocomplete'` or `'Dropdown'`.
+4. **`onRecordChange` handler** — see the Behavioral Contract section below for its full logic.
+5. **`recreatedFirstChild`** (memoized computation) — the main decision-tree logic: (a) when the component type is `SemanticLink` and not editable-in-review, create a `SemanticLink` child via `createComponent`; (b) when in display mode and not editable-in-review, render `SingleReferenceReadonly`; (c) otherwise (editable), call `generateColumns`, set `deferDatasource`, build `fieldMetaData`, and create the appropriate child (`Dropdown` or `AutoComplete`) via `createComponent` with a config object carrying the datasource metadata, `onRecordChange`, and related inputs. Dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+6. **Return** — a minimal grid wrapper containing `recreatedFirstChild`.
+
 ## Behavioral Contract
 
 ### Setup
@@ -40,7 +55,7 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 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
+4. `propsToUse = { ...pConn.getInheritedProps(), ...componentInputs }` — merged inherited + local inputs
 5. `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`
 6. `canBeChangedInReviewMode = editableInReview && ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType)`
 
@@ -72,33 +87,9 @@ Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, pa
    - `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
-     }
-   })
-   ```
+3. **Build fieldMetaData:** Start from an object shaped as `{ datasourceMetadata: { datasource: { parameters: {} } } }`. Set `propertyForDisplayText` from `datasource.fields.text` (with any leading `@P ` prefix stripped). Set `propertyForValue` from `datasource.fields.value` (with any leading `@P ` prefix stripped). Set `name` from `referenceList`. If `rawViewMetadata.config.parameters` is present, assign it to the `parameters` property.
+
+4. **Create child component:** Call `getPConnect().createComponent()` with `type` set to `'Dropdown'` or `'AutoComplete'`, and a `config` object spreading `rawViewMetadata.config` plus: `descriptors` (from `refFieldMetadata?.descriptors` when `mode === SELECTION_MODE.SINGLE`, otherwise `null`), `datasourceMetadata` (from `fieldMetaData.datasourceMetadata`), `required`, `visibility`, `disabled`, `label`, `parameters`, `readOnly: false`, `localeReference`, `referenceType` (for single mode only), `contextClass` (the target object class), `primaryField` (the display field), `dataRelationshipContext`, `hideLabel`, `onRecordChange`, and `inline`.
 
 ### `onRecordChange` handler
 
@@ -116,7 +107,7 @@ Called when user selects a new value in editable/editable-in-review mode:
 
 ### Memoization
 
-`recreatedFirstChild` is memoized with `useMemo` — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+`recreatedFirstChild` is a memoized computation — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
 
 ## Display Mode Rendering
 
@@ -124,50 +115,35 @@ Display mode is passed through to the child component — the child (Dropdown, A
 
 ## Visual Specifications
 
-ObjectReference itself renders a minimal grid container:
-
-```
-<Grid container>
-  <Grid>{recreatedFirstChild}</Grid>
-</Grid>
-```
+ObjectReference itself renders a minimal grid container: a grid wrapping a single grid item that holds `recreatedFirstChild`.
 
 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%;
-}
-```
+**Visual-only styling notes:** The outer container uses a full-width grid layout with a single column.
 
 ## 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.
+- For `SemanticLink` type, the child is created via `createComponent`, not rendered as a direct 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.
+- Local utility helpers: `SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey`.
+- The project's component registry, resolving `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`.
+- No event-commit utility — 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.
+When implementing in a specific design system, map the following:
 
-| 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 |
+- **Editable Dropdown/AutoComplete** → child created via `getPConnect().createComponent()` with datasource metadata
+- **SemanticLink** → child created via `createComponent` with case reference config
+- **Display-only** → render `SingleReferenceReadonly` from the project's component registry
+- **Editable-in-review** → allow editing with direct case update via `PCore.getCaseUtils()`
+- **Grid wrapper** → use a simple container to hold the `recreatedFirstChild`

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

@@ -0,0 +1,113 @@
+# Skill: Percentage
+
+Percentage numeric input with a `%` suffix and locale-aware decimal/thousands separators.
+
+> **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 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 the project's component map)
+
+## Inputs (component-specific)
+
+| Name                  | 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                                                                         |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Nearly identical to Currency but with a `%` suffix instead of a prefix, and no fixed decimal scale.
+
+**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 lookup), and the project's formatting helpers (for display-mode value formatting). It also uses a numeric-format masking library for locale-aware input display. Define the input contract as an extension of the project's field input contract, adding optional `currencyISOCode`, `showGroupSeparators`, and `decimalPrecision` 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`, `currencyISOCode` (default `'USD'`), `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`, `showGroupSeparators`, `decimalPrecision`.
+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. **Formatted value** — computed eagerly, before the display-mode check: obtain the currency formatting options via the project's currency options helper, then compute the formatted value using the project's formatting helper with the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key and the currency options.
+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. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the formatted value, the latter with a stacked variant.
+9. **Test ID and separators** — computed after the display-mode check: build a test-id attribute from `testId`; derive the decimal indicator and digit group separator via the project's currency utility helpers using `currencyISOCode`.
+10. **Event handlers** — 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`, suffix `'%'`, an outlined style when editable or flat/borderless style when read-only, 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 `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. **Separators:** Derive the decimal separator and thousands separator from locale lookup using `currencyISOCode` (same as Currency/Decimal). Apply the thousands separator only when `showGroupSeparators` is truthy.
+4. **Suffix:** Always append `%` suffix to the numeric input.
+5. **Decimal scale:** Use the `decimalPrecision` input.
+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 the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`.
+9. **Read-only:** Set the read-only attribute on the input. Flat/borderless style. Blur handler omitted.
+
+## Display Mode Rendering
+
+Format the value using the project's formatting helper with the component's type name as the format key before display:
+
+- **`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.
+
+## Read-Only Rendering
+
+Keep the numeric format input with the read-only attribute and `%` suffix still visible. Flat/borderless style.
+
+## Visual Specifications
+
+| Property            | Value                                     |
+| ------------------- | ----------------------------------------- |
+| Width               | 100%                                      |
+| Size                | Small                                     |
+| Variant editable    | Outlined                                  |
+| Variant read-only   | Flat/borderless                           |
+| Suffix              | `%` (always shown after the value)        |
+| Thousands separator | Only when `showGroupSeparators` is truthy |
+| Decimal scale       | `decimalPrecision`                        |
+| Placeholder         | From the `placeholder` input              |
+| 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
+
+- A numeric formatting library — handles locale-aware separators, suffix, and decimal scale.
+- The project's currency utility helpers — for decimal indicator and digit group separator lookup.
+- The project's currency options helper — for formatting options.
+- 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:** Percentage numeric input with `%` suffix.
+
+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
+- **`%` suffix** → use the DS's input suffix/adornment slot, or absolutely position a `%` label
+- **Decimal/thousands separators** → derive from the currency utility helpers based on the ISO code
+- **Read-only** → flat/borderless style with read-only attribute, suffix still visible
+- **Error state** → the DS's error/danger visual state