@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,258 @@
+# 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                                               |
+
+## Component Skeleton
+
+This is a complex component. Note: it does NOT extend `PConnFieldProps` — uses raw `props`.
+
+```typescript
+import { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  doSearch, getDisplayFieldsMetaData, useDeepMemo,
+  preProcessColumns, getGroupDataForItemsTree,
+} from './utils';
+import { insertInstruction, deleteInstruction } from '../../helpers/instructions-utils';
+import { debounce } from 'throttle-debounce';
+
+export default function Multiselect(props) {
+  // 1. Destructure props (use let for datasource/columns — may be reassigned)
+  const {
+    getPConnect, label, placeholder, referenceList, selectionKey,
+    primaryField, initialCaseClass, showSecondaryInSearchOnly = false,
+    listType = '', isGroupData = false, referenceType, secondaryFields,
+    groupDataSource = [], parameters = {}, matchPosition = 'contains',
+    maxResultsDisplay, groupColumnsConfig = [{}], selectionList, value,
+  } = props;
+  let { datasource = [], columns = [{}] } = props;
+
+  // 2. Reference list mode override (if referenceList.length > 0)
+  //    → reassign datasource and columns
+  //    → see Behavioral Contract "Reference List Mode"
+
+  // 3. State
+  const [inputValue, setInputValue] = useState(value);
+  const [selectedItems, setSelectedItems] = useState([]);
+
+  // 4. dataConfig (memoized with deep comparison via useDeepMemo)
+  //    → see Behavioral Contract "Data Config"
+
+  // 5. Display field metadata + items tree
+  //    → displayFieldMeta, groupsDisplayFieldMeta, itemsTreeBaseData, itemsTree state
+
+  // 6. Refs
+  const getCaseListBasedOnParamsDebounced: any = useRef();
+  const dataApiObj: any = useRef();
+  const pConn = getPConnect();
+  const contextName = pConn.getContextName();
+  const listActions = pConn.getListActions();
+
+  // 7. getCaseListBasedOnParams — main search function
+  //    → see Behavioral Contract "Search"
+
+  // 8. useEffect: setReferenceList — deps: [pConn]
+  // 9. useEffect: init debounced ref — deps: []
+  // 10. useEffect: init data API — deps: [dataConfig, ...]
+  //     → PCore.getDataApi().init(dataConfig, contextName)
+
+  // 11. onSearchHandler — updates inputValue, triggers debounced search
+  // 12. setSelectedItemsForReferenceList — insert/delete instruction
+  // 13. handleChange — selection add/remove logic
+  //     → see Behavioral Contract "Selection Changes"
+
+  // 14. Main render — multi-select autocomplete
+  //     Key props:
+  //     - multiple, fullWidth, disableCloseOnSelect
+  //     - options: itemsTree, value: selectedItems
+  //     - getOptionLabel: (option) => option?.primary
+  //     - onChange: handleChange
+  //     - renderInput: TextField with label, placeholder, size='small',
+  //       variant='outlined', onChange=onSearchHandler
+  return <MultiSelectAutocomplete ... />;
+}
+```
+
+## 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 → .ai-common/skills/field-skills/ObjectReference.md}

@@ -1,8 +1,3 @@
----
-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.
@@ -25,18 +20,92 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 
 > 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 |
+| 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                          |
+
+## Component Skeleton
+
+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()`.
+
+```typescript
+import { useMemo } from 'react';
+import { SELECTION_MODE, generateColumns, getDataRelationshipContextFromKey } from './utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface ObjectReferenceProps extends Omit<PConnFieldProps, 'value'> {
+  getPConnect: any;
+  displayMode;
+  allowAndPersistChangesInReviewMode: any;
+  targetObjectType: any;
+  mode: string;
+  parameters: object;
+  hideLabel: boolean;
+  inline: boolean;
+  showPromotedFilters: boolean;
+  additionalFields: any;
+}
+
+export default function ObjectReference(props: ObjectReferenceProps) {
+  // 1. Destructure props
+  const {
+    getPConnect, displayMode,
+    allowAndPersistChangesInReviewMode: editableInReview = false,
+    targetObjectType, mode = '', parameters,
+    hideLabel = false, inline = false,
+    showPromotedFilters = false, additionalFields,
+  } = props;
+
+  // 2. Registry lookup
+  const SingleReferenceReadonly = getComponentFromRegistry('SingleReferenceReadOnly');
+
+  // 3. Setup
+  const pConn = getPConnect();
+  const referenceType = targetObjectType === 'case' ? 'Case' : 'Data';
+  const rawViewMetadata = pConn.getRawMetadata();
+  const refFieldMetadata = pConn.getFieldMetadata(
+    rawViewMetadata?.config?.value?.split('.', 2)[1]
+  );
+  const propsToUse = { ...pConn.getInheritedProps(), ...props };
+  const isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY';
+  const canBeChangedInReviewMode = editableInReview &&
+    ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType);
+
+  // 4. onRecordChange handler — see Behavioral Contract
+  const onRecordChange = (event) => { /* ... */ };
+
+  // 5. recreatedFirstChild (useMemo) — the main logic
+  //    Decision tree:
+  //    a) SemanticLink && !canBeChangedInReviewMode → createComponent('SemanticLink', ...)
+  //    b) isDisplayModeEnabled && !canBeChangedInReviewMode → <SingleReferenceReadonly ... />
+  //    c) Editable: generateColumns, set deferDatasource, build fieldMetaData,
+  //       createComponent(type, { config with datasourceMetadata, onRecordChange, ... })
+  const recreatedFirstChild = useMemo(() => { /* ... */ }, [
+    rawViewMetadata.config?.datasource?.source,
+    parameters,
+    propsToUse.required,
+    propsToUse.disabled,
+    getPConnect().getPageReference(),
+  ]);
+
+  // 6. Return — minimal grid wrapper
+  return (
+    <GridContainer>
+      <GridItem>{recreatedFirstChild}</GridItem>
+    </GridContainer>
+  );
+}
+```
 
 ## Behavioral Contract
 
@@ -53,6 +122,7 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 
 **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 }`
@@ -60,6 +130,7 @@ Build a SemanticLink config from rawViewMetadata and call `getPConnect().createC
 
 **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)
@@ -76,6 +147,7 @@ Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, pa
    - If `!canBeChangedInReviewMode`: set `rawViewMetadata.config.displayMode = displayMode`
 
 3. **Build fieldMetaData:**
+
    ```
    fieldMetaData = { datasourceMetadata: { datasource: { parameters: {} } } }
    ```
@@ -105,6 +177,7 @@ Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, pa
 ### `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`.
@@ -126,6 +199,7 @@ 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>
@@ -135,8 +209,12 @@ ObjectReference itself renders a minimal grid container:
 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%; }
+.object-reference-container {
+  display: grid;
+  width: 100%;
+}
 ```
 
 ## Edge Cases & Special Logic
@@ -161,9 +239,9 @@ The visual appearance is entirely determined by the child component being render
 
 Listed design systems are examples only.
 
-| Scenario | Rendered Child |
-|----------|----------------|
-| `componentType='Dropdown'` (editable) | `Dropdown` component |
-| `componentType='AutoComplete'` (editable) | `AutoComplete` component |
-| `componentType='SemanticLink'` | `SemanticLink` component |
+| 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/.ai-common/skills/field-skills/Percentage.md

@@ -0,0 +1,177 @@
+# 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                                                                         |
+
+## Component Skeleton
+
+Follow this exact structure. Nearly identical to Currency but with `suffix='%'` instead of prefix, and no `fixedDecimalScale`.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getCurrencyCharacters, getCurrencyOptions } from '../Currency/currency-utils';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface PercentageProps extends PConnFieldProps {
+  currencyISOCode?: string;
+  showGroupSeparators?: string;
+  decimalPrecision?: number;
+}
+
+export default function Percentage(props: PercentageProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, currencyISOCode = 'USD',
+    testId, helperText, displayMode, hideLabel, placeholder,
+    showGroupSeparators, decimalPrecision,
+  } = props;
+
+  // 3. State
+  const [values, setValues] = useState(value.toString());
+
+  // 4. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Formatted value (computed eagerly, before display mode check)
+  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+  const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setValues(value.toString()); }, [value]);
+
+  // 7. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant="stacked" />;
+  }
+
+  // 9. Test ID + separators (computed AFTER display mode check in actual code)
+  const testProps: any = { 'data-test-id': testId };
+  const theSymbols = getCurrencyCharacters(currencyISOCode);
+  const theCurrDec = theSymbols.theDecimalIndicator;
+  const theCurrSep = theSymbols.theDigitGroupSeparator;
+
+  // 10. Event handlers
+  function PercentageOnBlur() { handleEvent(actions, 'changeNblur', propName, values); }
+  const handleChange = (val) => { setValues(val.value); };
+
+  // 11. Main render — numeric format input with % suffix
+  //     Key props:
+  //     - valueIsNumericString: true, fullWidth: true
+  //     - value: values, suffix: '%'
+  //     - variant: readOnly ? 'standard' : 'outlined'
+  //     - decimalSeparator: theCurrDec
+  //     - thousandSeparator: showGroupSeparators ? theCurrSep : ''
+  //     - decimalScale: decimalPrecision
+  //     - onValueChange, onBlur: !readOnly ? PercentageOnBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error', size: 'small'
+  //     - slotProps: { input: { ...readOnlyProp, inputProps: { ...testProps } } }
+  return <NumericFormatInput ... />;
+}
+```
+
+## 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>`        |