@pega/sdk 0.0.4 → 0.0.5

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

@@ -28,6 +28,73 @@ All other props come from `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+The foundational field component — simplest pattern. All text-like fields (Email, URL, Integer, Phone) follow this structure with minor variations.
+
+```typescript
+import { useState, useEffect } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TextInputProps extends PConnFieldProps {
+  fieldMetadata?: any;
+}
+
+export default function TextInput(props: TextInputProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, fieldMetadata,
+    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;
+  const maxLength = fieldMetadata?.maxLength;
+
+  // 4. State + readOnly prop
+  const [inputValue, setInputValue] = useState('');
+  let readOnlyProp = {};
+
+  // 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 prop
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Test ID + 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 — single-line text input
+  //    Key props:
+  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
+  return <TextFieldWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `value` prop (`''` default).

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

@@ -24,6 +24,73 @@ No props beyond `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+No local state for time value — derived directly from `props.value` on each render.
+
+```typescript
+import dayjs from 'dayjs';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TimeProps extends PConnFieldProps {}
+
+export default function Time(props: TimeProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const TextInput = getComponentFromRegistry('TextInput');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, helperText, displayMode,
+    hideLabel, testId,
+  } = props;
+  const helperTextToDisplay = validatemessage || helperText;
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 3. 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" />;
+  }
+
+  // 4. Read-only return
+  if (readOnly) return <TextInput {...props} />;
+
+  // 5. Test ID
+  const testProps: any = { 'data-test-id': testId };
+
+  // 6. handleChange — commit on change (not blur)
+  const handleChange = (date) => {
+    const theValue = date && date.isValid() ? date.format('HH:mm:ss') : null;
+    handleEvent(actions, 'changeNblur', propName, theValue);
+  };
+
+  // 7. Parse time value from HH:mm:ss string
+  let timeValue: any = null;
+  if (value && Object.keys(value).length) {
+    const timeArray = value.split(':').map(itm => Number(itm));
+    timeValue = dayjs().hour(timeArray[0]).minute(timeArray[1]);
+  }
+
+  // 8. Main render — time picker
+  //    Key props:
+  //    - disabled, label, value: timeValue
+  //    - minutesStep: 5, format: 'hh:mm a'
+  //    - onChange: handleChange
+  //    - textField slot: variant 'outlined', placeholder 'hh:mm am',
+  //      required, error: status === 'error', helperText: helperTextToDisplay,
+  //      size: 'small', InputProps: { ...testProps }
+  return <TimePickerWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Value format stored/committed:** `HH:mm:ss` (24-hour, e.g., `'14:30:00'`).

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

@@ -26,6 +26,65 @@ import type { PConnFieldProps } from '@pega/sdk-react';
 
 > **Important naming note:** Export the component as `URLComponent` (not `URL`) to avoid conflicts with the browser's built-in `URL` global. Register it in `component-map.ts` as `URL: URLComponent`.
 
+## Component Skeleton
+
+Nearly identical to TextInput — only difference is `type='url'`.
+
+```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 URLComponentProps extends PConnFieldProps {}
+
+export default function URLComponent(props: URLComponentProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const TextInput = getComponentFromRegistry('TextInput');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+  const helperTextToDisplay = validatemessage || helperText;
+  const [inputValue, setInputValue] = useState('');
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 3. useEffect: sync — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 4. 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" />;
+  }
+
+  // 5. Read-only return
+  if (readOnly) return <TextInput {...props} />;
+
+  // 6. Handlers
+  const testProps: any = { 'data-test-id': testId };
+  const handleChange = (event) => { setInputValue(event?.target?.value); };
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 7. Main render — URL input (type='url')
+  //    Key props: same as TextInput but type: 'url'
+  //    - fullWidth, variant: 'outlined', size: 'small'
+  //    - value: inputValue, onChange, onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { inputProps: { ...testProps } } }
+  return <TextFieldWidget type="url" ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).

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

@@ -43,6 +43,96 @@ import type { PConnProps } from '@pega/sdk-react';
 | `variant`             | `string` (optional)  | `'inline'` | Layout variant                                                   |
 | `onChange`            | `any` (optional)     | —          | Change handler (passed through to child)                         |
 
+## Component Skeleton
+
+Orchestrator component — renders either AutoComplete, Dropdown, formatted text, or FieldValueList based on mode. Uses `memo` with custom comparison.
+
+```typescript
+import { memo, useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+import { getUserId, isUserNameAvailable } from './UserReferenceUtils';
+
+const DROPDOWN_LIST = 'Drop-down list';
+const SEARCH_BOX = 'Search box';
+
+interface UserReferenceProps extends PConnProps {
+  displayAs?: string;
+  displayMode?: string;
+  label?: string;
+  value?: any;
+  testId?: string;
+  placeholder?: string;
+  helperText?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  validatemessage?: string;
+  showAsFormattedText?: boolean;
+  additionalProps?: object;
+  hideLabel?: boolean;
+  variant?: string;
+  onChange?: any;
+}
+
+const UserReference = (props: UserReferenceProps) => {
+  // 1. Registry lookups
+  const AutoComplete = getComponentFromRegistry('AutoComplete');
+  const Dropdown = getComponentFromRegistry('Dropdown');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props (all with defaults)
+  const {
+    label = '',
+    displayAs = '',
+    displayMode = '',
+    getPConnect,
+    value = '',
+    testId = '',
+    helperText = '',
+    validatemessage = '',
+    placeholder = '',
+    showAsFormattedText = false,
+    additionalProps = {},
+    hideLabel = false,
+    readOnly = false,
+    required = false,
+    disabled = false,
+    onChange,
+  } = props;
+
+  // 3. State
+  const [dropDownDataSource, setDropDownDataSource] = useState([]);
+  const [userName, setUserName] = useState('');
+
+  // 4. Derived
+  const OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP();
+  const userId = getUserId(value);
+
+  // 5. useEffect — deps: [displayAs, readOnly, showAsFormattedText, value]
+  //    Case 1: userId && readOnly && showAsFormattedText → resolve userName
+  //    Case 2: displayAs === DROPDOWN_LIST → fetch user list via REST
+
+  // 6. Rendering decision tree
+  //    displayMode DISPLAY_ONLY → FieldValueList(userName || '')
+  //    displayMode STACKED → FieldValueList(userName || '', variant='stacked')
+  //    readOnly && showAsFormattedText && userId → label + userName text
+  //    displayAs SEARCH_BOX → <AutoComplete datasource={OPERATORS_DP} listType='datapage' ...>
+  //    displayAs DROPDOWN_LIST → <Dropdown datasource={dropDownDataSource} listType='associated' ...>
+  return userReferenceComponent;
+};
+
+// 7. Memo with custom comparison
+const comparisonFn = (prevProps, nextProps) =>
+  getUserId(prevProps.value) === getUserId(nextProps.value) &&
+  prevProps.validatemessage === nextProps.validatemessage &&
+  prevProps.required === nextProps.required &&
+  prevProps.disabled === nextProps.disabled &&
+  prevProps.readOnly === nextProps.readOnly;
+
+export default memo(UserReference, comparisonFn);
+```
+
 ## Behavioral Contract
 
 ### User ID extraction

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

@@ -31,7 +31,7 @@ src/components/template/TwoColumn/
 Template components extend `PConnProps`:
 
 ```typescript
-import type { PConnProps } from '../../../types/PConnProps';
+import type { PConnProps } from '@pega/sdk-react';
 
 interface PConnProps {
   getPConnect: () => typeof PConnect;
@@ -65,36 +65,33 @@ export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
   const { children, templateCol = '1fr 1fr' } = props;
   const childrenToRender = children as ReactElement[];
 
-  // Parse templateCol into column width ratios
-  // Strip unit suffixes, split on whitespace, convert to numbers
-  const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
-  const totalCols = colArray.reduce((v, itm) => itm + v, 0);
-  // colArray[0] / totalCols = left column fraction
-  // colArray[1] / totalCols = right column fraction
-
-  // [DS GRID] — render two children in a responsive grid using the computed ratios
-  // On mobile (narrow viewport): both columns should stack to full width
-  // On desktop: apply the computed left/right ratio
+  // templateCol maps directly to CSS grid-template-columns — no conversion needed
+  // Use plain CSS grid with width: 100% to guarantee the layout fills its parent
+  // On mobile: use a media query or @container query to stack columns
   return (
-    <YourDesignSystemGrid>
-      <YourDesignSystemColumn ratio={colArray[0] / totalCols}>
+    <div style={{ display: 'grid', gridTemplateColumns: templateCol, gap: '0.5rem', width: '100%' }}>
+      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
         {childrenToRender[0]}
-      </YourDesignSystemColumn>
-      <YourDesignSystemColumn ratio={colArray[1] / totalCols}>
+      </div>
+      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
         {childrenToRender[1]}
-      </YourDesignSystemColumn>
-    </YourDesignSystemGrid>
+      </div>
+    </div>
   );
 }
 ```
 
+> ⚠️ **Do NOT use DS-specific grid components** (e.g., Carbon `<Grid>`, Ant Design `<Row>/<Col>`) for layout templates. Many DS grids have built-in `max-width` constraints that prevent the layout from filling its parent container. Use plain CSS grid with `grid-template-columns: templateCol` — this works with every design system and guarantees full-width rendering.
+
 ---
 
 ## Design System Adaptation (Layout Templates Only)
 
 > Form templates and page templates use the PConnect bridge pattern and do **not** use any design system primitives. This section applies only to layout templates: TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants.
+>
+> **Use plain CSS grid** (`display: grid; grid-template-columns; width: 100%`) for all layout templates. The `templateCol` prop value (e.g., `'1fr 1fr'`, `'2fr 1fr'`) maps directly to `grid-template-columns`. Do NOT use DS grid components — they may have max-width constraints.
 
-**1. Check the component-specific skill file** — `.github/skills/template-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
 
 **2. If the chosen design system is not listed** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
 
@@ -119,59 +116,82 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 Used for: DefaultForm, HierarchicalForm
 
+> ⚠️ **CRITICAL:** Form templates MUST use the `connectToState` HOC pattern. Without it, form fields will not render because they won't be subscribed to the Redux store for visibility and prop updates.
+
 ```typescript
 import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
+import { PConnectComponent } from '@pega/sdk-react';
 import connectToState from '../../helpers/state-utils';
-import type { PConnProps } from '../../../types/PConnProps';
+import { getKeyForMappedField, mapStateToProps } from './utils';
+import type { PConnProps } from '@pega/sdk-react';
 
 interface DefaultFormProps extends PConnProps {
   NumCols: string;
   instructions: string;
 }
 
+// MANDATORY: connectToState HOC wraps each field in Redux store subscription
+const Child = connectToState(mapStateToProps)((props) => {
+  const { key, visibility, ...rest } = props;
+  return createElement(PConnectComponent, { ...rest, key, visibility });
+});
+
 export default function DefaultForm(props: DefaultFormProps) {
   const { getPConnect, NumCols = '1' } = props;
 
-  // Get children from the first region
+  // Unwrap region children (first child is a region → get ITS children)
   const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
 
-  // Wrap each child in a PConnect component
-  const dfChildren = arChildren?.map((kid, i) => (
-    createElement(createPConnectComponent(), { ...kid, key: `child-${i}` })
+  // Each child MUST be wrapped in the connectToState HOC
+  const dfChildren = arChildren?.map((kid) => (
+    <Child key={getKeyForMappedField(kid)} {...kid} />
   ));
 
   return <div className={`form-${NumCols}-col`}>{dfChildren}</div>;
 }
 ```
 
+> ❌ **INCORRECT pattern** (will cause fields to not render):
+>
+> ```typescript
+> // DO NOT USE — fields won't be subscribed to store
+> arChildren.map((kid, i) => createElement(PConnectComponent, { ...kid, key: i }));
+> ```
+
 ### Page Template (renders regions from PConnect children)
 
-Used for: CaseView, DefaultPage, ObjectPage
+Used for: CaseView, DefaultPage, ObjectPage, AppShell, Confirmation
+
+> ⚠️ **CRITICAL:** Page templates are NOT simple wrappers. They contain PCore API calls, useEffect hooks, state management, and complex prop drilling to infrastructure components. NEVER simplify a Page template to a single return statement. Always follow the component-specific skill file skeleton faithfully.
+>
+> After generating a Page template, compare your output against the skill file skeleton. Every `useState`, `useEffect`, `getComponentFromRegistry`, `PCore.*` call, helper function, and utility import from the skeleton MUST appear in your generated output. If your output is significantly shorter than the skeleton, you have over-simplified.
+>
+> ⚠️ **COMMON ERROR — `tabconfig` must be an array, NOT a React element:**
+> The `VerticalTabs` infrastructure component expects `tabconfig` to be `{ name: string; id: number }[]`. You MUST build this array by iterating the tab region's PConnect children (extracting `label` from each child's config props). NEVER pass the raw React region element to `<VerticalTabs tabconfig={...}>` — it causes `TypeError: tabconfig.map is not a function`.
 
 ```typescript
-import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-import type { PConnProps } from '../../../types/PConnProps';
+import { type PropsWithChildren, type ReactElement, useEffect, useState } from 'react';
+import { getComponentFromRegistry, PConnectComponent } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
 
-interface CaseViewProps extends PConnProps {
-  header?: string;
-  subheader?: string;
-}
+export default function CaseView(props: PropsWithChildren<CaseViewProps>) {
+  // 1. Get infrastructure components from registry
+  const VerticalTabs = getComponentFromRegistry('VerticalTabs');
+  const DeferLoad = getComponentFromRegistry('DeferLoad');
 
-export default function CaseView(props: CaseViewProps) {
-  const { getPConnect, header } = props;
+  // 2. Destructure ALL props from the skill file skeleton
+  const { getPConnect, children, header, ... } = props;
   const pConn = getPConnect();
-  const children = pConn.getChildren();
 
-  return (
-    <div>
-      <h2>{header}</h2>
-      {children.map((child, index) => (
-        createElement(createPConnectComponent(), { ...child, key: `region-${index}` })
-      ))}
-    </div>
-  );
+  // 3. Include ALL state, effects, and handlers from the skill file
+  const [activeTab, setActiveTab] = useState(0);
+  useEffect(() => { /* event listeners, pub/sub */ }, []);
+
+  // 4. Extract named regions (NOT by index — use metadata name)
+  function getChildRegionByName(name: string) { ... }
+
+  // 5. Render with full layout structure from skill file
+  return ( /* full layout */ );
 }
 ```
 
@@ -193,39 +213,50 @@ const childrenToRender = children as ReactElement[];
 
 ```typescript
 import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
+import { PConnectComponent } from '@pega/sdk-react';
 
 // Get child PConnect objects
 const children = getPConnect().getChildren();
 
 // Render each child through the PConnect bridge
-children.map((child, i) => createElement(createPConnectComponent(), { ...child, key: `child-${i}` }));
+children.map((child, i) => createElement(PConnectComponent, { ...child, key: `child-${i}` }));
 ```
 
-### 3. State-connected children (DefaultForm pattern)
+### 3. State-connected children (REQUIRED for Form templates)
+
+> ⚠️ This is the ONLY correct pattern for Form templates (DefaultForm, HierarchicalForm). Using pattern #2 above for form fields will result in fields not rendering.
 
 ```typescript
+import { createElement } from 'react';
+import { PConnectComponent } from '@pega/sdk-react';
 import connectToState from '../../helpers/state-utils';
-import createPConnectComponent from '../../helpers/react_pconnect';
+import { getKeyForMappedField, mapStateToProps } from './utils';
 
 // connectToState HOC subscribes to Redux store for visibility/props
 const Child = connectToState(mapStateToProps)((props) => {
   const { key, visibility, ...rest } = props;
-  return createElement(createPConnectComponent(), { ...rest, key, visibility });
+  return createElement(PConnectComponent, { ...rest, key, visibility });
 });
+
+// Usage inside component:
+const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
+const dfChildren = arChildren?.map((kid) => (
+  <Child key={getKeyForMappedField(kid)} {...kid} />
+));
 ```
 
 ---
 
 ## Helper Utilities
 
-### `createPConnectComponent` (from `../../helpers/react_pconnect`)
+### `PConnectComponent` (from `@pega/sdk-react`)
 
-Factory that returns the PConnect bridge component. Used to render child PConnect objects:
+The PConnect bridge component. Used to render child PConnect objects:
 
 ```typescript
-import createPConnectComponent from '../../helpers/react_pconnect';
-createElement(createPConnectComponent(), childPConnectProps);
+import { createElement } from 'react';
+import { PConnectComponent } from '@pega/sdk-react';
+createElement(PConnectComponent, { ...childPConnectProps, key });
 ```
 
 ### `connectToState` (from `../../helpers/state-utils`)

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

@@ -24,6 +24,83 @@ Renders a multi-section advanced search form where search fields are organized i
 | `parameters`   | `object`   | No       | Parameters passed to the data page |
 | `getPConnect`  | `function` | Yes      | PConnect getter                    |
 
+## Component Skeleton
+
+```typescript
+import { useContext, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import DataReferenceAdvancedSearchContext from '../DataReference/DataReferenceAdvancedSearchContext';
+import { getFirstChildConfig } from '../DataReference/utils';
+
+export default function AdvancedSearch(props) {
+  const { getPConnect, targetObjectClass, localeReference } = props;
+  const SearchGroups = getComponentFromRegistry('SearchGroups');
+
+  // 1. Context — shared config from DataReference parent
+  const {
+    dataReferenceConfigToChild, isCreateNewReferenceEnabled,
+    disableStartingFieldsForReference, pyID, searchSelectCacheKey,
+  } = useContext(DataReferenceAdvancedSearchContext) as any;
+
+  // 2. Selection state check
+  const { selectionMode, value: singleSelectFieldValue, readonlyContextList: multiSelectField } =
+    dataReferenceConfigToChild;
+  const { MULTI } = PCore.getConstants().LIST_SELECTION_MODE;
+  const isSelectionExist = selectionMode === MULTI
+    ? getPConnect().getValue(multiSelectField)?.length || false
+    : getPConnect().getValue(singleSelectFieldValue) || false;
+  const [showRecords, setShowRecords] = useState(isSelectionExist);
+
+  // 3. Metadata + field deduplication
+  const pConn = getPConnect();
+  const rawViewMetadata = pConn.getRawMetadata();
+  const searchFieldsSet = new Set();
+  const searchFields: any = [];
+  rawViewMetadata.config.searchGroups.forEach((group) => {
+    group.children.forEach((child) => {
+      if (!searchFieldsSet.has(child.config.value) && !child.config.validator) {
+        searchFields.push(child);
+        searchFieldsSet.add(child.config.value);
+      }
+    });
+  });
+
+  // 4. Create editable field component from first child
+  const firstChildPConnect = getPConnect().getChildren()[0].getPConnect;
+  const [firstChildMeta] = rawViewMetadata.children;
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const cache = PCore.getNavigationUtils().getComponentCache(searchSelectCacheKey) ?? {};
+
+  const editableFieldComp = firstChildPConnect().createComponent({
+    type: firstChildMeta.type,
+    config: {
+      ...getFirstChildConfig({ firstChildMeta, getPConnect, rawViewMetadata,
+        contextClass: targetObjectClass, dataReferenceConfigToChild,
+        isCreateNewReferenceEnabled, disableStartingFieldsForReference, pyID }),
+      searchFields, showRecords,
+      label: localizedVal('Search results', 'DataReference'),
+      searchSelectCacheKey, cache,
+    },
+  });
+
+  // 5. Derive editable field path
+  const { selectionList, dataRelationshipContext } =
+    editableFieldComp.props.getPConnect().getConfigProps();
+  const editableField = selectionMode === MULTI
+    ? selectionList.substring(1) : dataRelationshipContext;
+
+  // 6. Render: SearchGroups + editableFieldComp
+  return (
+    <>
+      <SearchGroups getPConnect={getPConnect} editableField={editableField}
+        localeReference={localeReference} setShowRecords={setShowRecords}
+        searchSelectCacheKey={searchSelectCacheKey} cache={cache} />
+      {editableFieldComp}
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### Search Groups from Metadata