@pega/sdk 0.0.4 → 0.0.5

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

@@ -29,6 +29,111 @@ Renders a single-select dropdown (select box). Options are loaded from a Pega da
 | `fieldMetadata`      | `any` (optional)     | Field metadata for localization context                             |
 | `onRecordChange`     | `any` (optional)     | Callback fired after a selection change                             |
 
+## Component Skeleton
+
+Follow this exact structure. Same helper functions as AutoComplete (`flattenParameters`, `preProcessColumns`, `getDisplayFieldsMetaData`).
+
+```typescript
+import { useEffect, useState } from 'react';
+import isDeepEqual from 'fast-deep-equal/react';
+import Utils from '../../helpers/utils';
+import { getDataPage } from '../../helpers/data_page';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface IOption { key: string; value: string; }
+
+// ── Helper functions (top-level) ─────────────────────────────
+// flattenParameters, preProcessColumns, getDisplayFieldsMetaData
+// → same implementations as AutoComplete (see that skill file)
+
+interface DropdownProps extends PConnFieldProps {
+  datasource?: any[];
+  onRecordChange?: any;
+  fieldMetadata?: any;
+  listType: string;
+  deferDatasource?: boolean;
+  datasourceMetadata?: any;
+  parameters?: any;
+  columns: any[];
+}
+
+export default function Dropdown(props: DropdownProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, helperText,
+    displayMode, deferDatasource, datasourceMetadata,
+    hideLabel, onRecordChange, fieldMetadata,
+  } = props;
+  let { placeholder = '' } = props;
+  const context = getPConnect().getContextName();
+  let { listType, parameters, datasource = [], columns = [] } = props;
+  placeholder = placeholder || 'Select...';
+
+  // 3. State
+  const [options, setOptions] = useState<IOption[]>([]);
+  const [theDatasource, setDatasource] = useState<any[] | null>(null);
+
+  // 4. PConnect setup
+  const helperTextToDisplay = validatemessage || helperText;
+  const thePConn = getPConnect();
+  const actionsApi = thePConn.getActionsApi();
+  const propName = (thePConn.getStateProps() as any).value;
+  const className = thePConn.getCaseInfo().getClassName();
+  const refName = propName?.slice(propName.lastIndexOf('.') + 1);
+
+  // 5. Render-time datasource comparison (NOT in useEffect)
+  if (!isDeepEqual(datasource, theDatasource)) {
+    setDatasource(datasource);
+  }
+
+  // 6. Deferred datasource transformation (same as AutoComplete)
+  //    → reassigns listType, datasource, parameters, columns
+
+  // 7. Column preprocessing
+  columns = preProcessColumns(columns);
+
+  // 8. useEffect: associated options — deps: [theDatasource]
+  //    → prepend placeholder option, call Utils.getOptionList
+
+  // 9. useEffect: datapage options — deps: []
+  //    Guard: listType !== 'associated' && typeof datasource === 'string'
+
+  // 10. Localization metadata derivation
+  //     → metaData, displayName, localeContext, localeClass, localeName, localePath
+
+  // 11. Display mode — resolve key→value, localize, return FieldValueList
+  if (displayMode) {
+    const resolvedValue = options.find(opt => opt.key === value)?.value || value;
+    const localizedValue = thePConn.getLocalizedValue(resolvedValue, localePath,
+      thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName));
+    // return <FieldValueList ... value={localizedValue} />
+  }
+
+  // 12. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 13. Test ID + handleChange
+  const testProps: any = { 'data-test-id': testId };
+  const handleChange = (evt) => {
+    const selectedValue = evt.target.value === placeholder ? '' : evt.target.value;
+    handleEvent(actionsApi, 'changeNblur', propName, selectedValue);
+    if (onRecordChange) onRecordChange(evt);
+  };
+
+  // 14. Main render — return null if options empty, otherwise select
+  //     value: value === '' && !readOnly ? placeholder : value
+  //     Options rendered with localized labels via thePConn.getLocalizedValue()
+  return options.length === 0 ? null : <SelectWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Options state:** Maintain `options` as `Array<{key: string, value: string}>`. Initially empty — render nothing (`return null`) until options are populated (avoids design system warnings about undefined options).
@@ -47,7 +152,28 @@ Renders a single-select dropdown (select box). Options are loaded from a Pega da
    - Commit via `handleEvent(actionsApi, 'changeNblur', propName, selectedValue)`.
    - Fire `onRecordChange(evt)` if provided.
 9. **Read-only:** Set `readOnly: true` on the select input. Flat/borderless style. Change handler omitted.
-10. **Localization:** Option labels and display values are localized via `pConn.getLocalizedValue(label, localePath, localeRuleName)`.
+10. **Localization metadata:** Derived from `fieldMetadata`:
+    ```
+    const metaData = Array.isArray(fieldMetadata)
+      ? fieldMetadata.filter(f => f?.classID === className)[0]
+      : fieldMetadata;
+    let displayName = metaData?.datasource?.propertyForDisplayText;
+    displayName = displayName?.slice(displayName.lastIndexOf('.') + 1);
+    const localeContext = metaData?.datasource?.tableType === 'DataPage' ? 'datapage' : 'associated';
+    const localeClass = localeContext === 'datapage' ? '@baseclass' : className;
+    const localeName = localeContext === 'datapage' ? metaData?.datasource?.name : refName;
+    const localePath = localeContext === 'datapage' ? displayName : localeName;
+    ```
+    Where `className = thePConn.getCaseInfo().getClassName()` and `refName = propName?.slice(propName.lastIndexOf('.') + 1)`.
+11. **Display mode rendering:** Uses a `displayFn` that resolves key→value from options, then localizes:
+    ```
+    const resolvedValue = options.find(opt => opt.key === value)?.value || value;
+    return <FieldValueList value={thePConn.getLocalizedValue(resolvedValue, localePath,
+      thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))} />;
+    ```
+12. **Select value when empty:** `value={value === '' && !readOnly ? placeholder : value}` — shows placeholder as selected when value is empty.
+13. **Return null until options load:** `return options.length === 0 ? null : <Select ... />` — prevents rendering empty select.
+14. **Option labels localized:** Each `<MenuItem>` label is wrapped in `thePConn.getLocalizedValue(option.value, localePath, localeRuleName)`.
 
 ## Display Mode Rendering
 

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

@@ -24,6 +24,74 @@ No props beyond `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+Follow this exact structure. Replace the mail icon and TextField with equivalents from your chosen design system.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import handleEvent from '../../helpers/event-utils';
+
+interface EmailProps extends PConnFieldProps {}
+
+export default function Email(props: EmailProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState('');
+
+  // 5. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only return (delegates entirely to TextInput — no mail icon)
+  if (readOnly) {
+    return <TextInput {...props} />;
+  }
+
+  // 8. Test ID + event handlers
+  const testProps: any = { 'data-test-id': testId };
+  function handleChange(event) { setInputValue(event?.target?.value); }
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 9. Main render — email input with leading mail icon
+  //    Key props:
+  //    - fullWidth, variant: 'outlined', size: 'small'
+  //    - type: 'email'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - startAdornment: mail/envelope icon
+  //    - inputProps: { ...testProps }
+  return <EmailInput ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).

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

@@ -29,6 +29,57 @@ A layout/structural component (not a form input). Wraps a set of child field com
 
 `displayMode` is also consumed from `PConnFieldProps`.
 
+## Component Skeleton
+
+```typescript
+import { type ReactElement, useMemo } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface GroupProps extends PConnFieldProps {
+  children: ReactElement[];
+  heading: string;
+  showHeading: boolean;
+  instructions?: string;
+  collapsible: boolean;
+  type: string;
+}
+
+export default function Group(props: GroupProps) {
+  // 1. Registry lookup
+  const FieldGroup = getComponentFromRegistry('FieldGroup');
+
+  // 2. Destructure props
+  const { children, heading, showHeading, instructions, collapsible, displayMode, type } = props;
+
+  // 3. Derived flag
+  const isReadOnly = displayMode === 'DISPLAY_ONLY';
+
+  // 4. Memoized content grid — deps: [children, type, isReadOnly]
+  const content = useMemo(() => (
+    <GridContainer spacing={2}>
+      {children?.map(child => (
+        <GridItem fullWidth key={child.key}>{child}</GridItem>
+      ))}
+    </GridContainer>
+  ), [children, type, isReadOnly]);
+
+  // 5. Null guard
+  if (!children) return null;
+
+  // 6. Return FieldGroup wrapper
+  return (
+    <FieldGroup
+      name={showHeading ? heading : undefined}
+      collapsible={collapsible}
+      instructions={instructions}
+    >
+      {content}
+    </FieldGroup>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **No state, no event handling** — purely structural/layout.

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

@@ -24,6 +24,87 @@ No props beyond `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+Follow this exact structure. The key differentiator from TextInput is the character filtering in `onChange`.
+
+```typescript
+import { useEffect, useState } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface IntegerProps extends PConnFieldProps {}
+
+export default function Integer(props: IntegerProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState('');
+
+  // 5. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only return
+  if (readOnly) {
+    return <TextInput {...props} />;
+  }
+
+  // 8. Test ID
+  const testProps: any = { 'data-test-id': testId };
+
+  // 9. onChange with character filtering
+  function intOnChange(event) {
+    const disallowedChars = ['.', ','];
+    const theAttemptedValue = event.target.value;
+    const lastChar = theAttemptedValue.slice(-1);
+    if (disallowedChars.includes(lastChar)) {
+      event.target.value = theAttemptedValue.slice(0, -1);
+    }
+    setInputValue(event.target.value);
+  }
+
+  // 10. onBlur — commit to store
+  function handleBlur() {
+    handleEvent(actions, 'changeNblur', propName, inputValue);
+  }
+
+  // 11. Main render — text input (type='text', NOT 'number')
+  //     Key props:
+  //     - fullWidth, variant: 'outlined', size: 'small'
+  //     - type: 'text' (NOT 'number')
+  //     - value: inputValue, onChange: intOnChange
+  //     - onBlur: !readOnly ? handleBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error'
+  //     - htmlInput: { inputMode: 'numeric', pattern: '[0-9]*', ...testProps }
+  return <TextFieldWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).

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

@@ -25,6 +25,111 @@ Renders a text input that integrates with Google Maps Places API for address/loc
 | `showMap`         | `boolean` (optional) | —       | Show the interactive map in editable mode                                |
 | `showMapReadOnly` | `boolean` (optional) | —       | Show the map in read-only mode                                           |
 
+## Component Skeleton
+
+Follow this exact structure. This component is complex — integrates Google Maps API for places autocomplete, geolocation, and optional map display.
+
+```typescript
+import { useEffect, useState, useCallback, useRef } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import handleEvent from '../../helpers/event-utils';
+import './Location.css';
+
+interface LocationProps extends PConnFieldProps {
+  coordinates?: string;
+  onlyCoordinates?: boolean;
+  showMap?: boolean;
+  showMapReadOnly?: boolean;
+}
+
+const mapContainerStyle = { width: '100%', height: '300px', marginTop: '0px' };
+const defaultCenter = { lat: 18.5204, lng: 73.8567 };
+const disabledMapOptions = {
+  gestureHandling: 'none', keyboardShortcuts: false,
+  disableDefaultUI: true, clickableIcons: false,
+};
+
+export default function Location(props: LocationProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required = false, disabled = false, value = '',
+    validatemessage, status, readOnly = false, testId, displayMode,
+    hideLabel = false, placeholder, helperText,
+    coordinates = '', onlyCoordinates = false, showMap, showMapReadOnly,
+  } = props;
+
+  // 3. PConnect setup — note TWO property names
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const coordPropName = (pConn.getStateProps() as any).coordinates;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState<string>(value ?? '');
+  const [mapCenter, setMapCenter] = useState(defaultCenter);
+  const [markerPosition, setMarkerPosition] = useState<{lat:number,lng:number} | null>(null);
+
+  // 5. Refs
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const autocompleteRef = useRef<google.maps.places.Autocomplete | null>(null);
+
+  // 6. Load Google Maps API
+  const { isLoaded } = useLoadScript({
+    googleMapsApiKey: pConn.getGoogleMapsAPIKey?.() || '',
+    libraries: ['places', 'geocoding'],
+  });
+
+  // 7. Error flag
+  const hasError = status === 'error' && !!validatemessage && !disabled;
+
+  // 8. useEffect: sync value + coordinates — deps: [value, coordinates, onlyCoordinates]
+  //    → see Behavioral Contract #3
+
+  // 9. handleChange (manual text input) — useCallback
+  //    Commits immediately, clears coordinates if input emptied
+
+  // 10. handlePlaceChanged — useCallback
+  //     Reads place from autocompleteRef, extracts lat/lng,
+  //     stores address or coordinates based on onlyCoordinates flag
+
+  // 11. useEffect: init Places Autocomplete — deps: [isLoaded, handlePlaceChanged]
+  //     Guard: isLoaded && inputRef.current && !autocompleteRef.current
+
+  // 12. handleGetCurrentLocation — useCallback
+  //     Uses navigator.geolocation.getCurrentPosition
+  //     If onlyCoordinates: store coords directly
+  //     Else: reverse geocode via google.maps.Geocoder
+
+  // 13. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 14. Map element (shared between readOnly and editable)
+  //     opacity: disabled ? 0.7 : 1, options: disabled ? disabledMapOptions : undefined
+
+  // 15. Read-only return
+  if (readOnly) {
+    return <div><TextInput {...props} />{isLoaded && showMapReadOnly && map}</div>;
+  }
+
+  // 16. Main render
+  //     - Error alert ABOVE input if hasError
+  //     - Guard: only render TextField when isLoaded
+  //     - TextField with inputRef, endAdornment location icon button
+  //     - Map below if isLoaded && showMap
+  return <div>...</div>;
+}
+```
+
 ## Behavioral Contract
 
 1. **APIs required:**

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

@@ -44,6 +44,76 @@ 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                                               |
 
+## 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`)

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

@@ -33,6 +33,80 @@ 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                          |
 
+## 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
 
 ### Setup