@pega/sdk 0.0.5 → 0.0.7

package/templates/react-sdk-reference/.ai-common/skills/template-skills/DynamicTabs.md

@@ -12,83 +12,30 @@ Unlike `SubTabs` or `DetailsSubTabs` where tabs are defined statically in metada
 
 ## Pega Metadata
 
-- **Registration key:** `DynamicTabs` (in `component-map.ts`)
+- **Registration key:** `DynamicTabs` (in the project's component map)
 - **Category:** Navigation template — data-driven
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop            | Type       | Required | Description                                               |
+| Input           | Type       | Required | Description                                               |
 | --------------- | ---------- | -------- | --------------------------------------------------------- |
 | `referenceList` | `string`   | Yes      | Property path to the reference list (e.g. `'.pxResults'`) |
 | `getPConnect`   | `function` | Yes      | PConnect getter                                           |
 
-## Component Skeleton
-
-```typescript
-import React, { Children, useMemo, useState } from 'react';
-import { buildView } from '../../../helpers/field-group-utils';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface DynamicTabsProps extends PConnProps {
-  showLabel: boolean;
-  label: string;
-  referenceList?: any[];
-}
-
-export default function DynamicTabs(props: DynamicTabsProps) {
-  const { referenceList, showLabel, label, getPConnect } = props;
-  const pConnect = getPConnect();
-  const propsToUse = { label, showLabel, ...pConnect.getInheritedProps() };
-
-  // 1. Resolve tab label property from annotation
-  const { tablabel } = pConnect.getComponentConfig();
-  const tablabelProp = PCore.getAnnotationUtils().getPropertyName(tablabel);
-
-  // 2. Get reference list data
-  const referenceListData: any = pConnect.getValue(`${referenceList}.pxResults`, '');
-
-  // 3. Memoized tab views — set display-only mode, build views
-  const memoisedTabViews = useMemo(() => {
-    pConnect.setInheritedProp('displayMode', 'DISPLAY_ONLY');
-    pConnect.setInheritedProp('readOnly', true);
-    return referenceListData && Children.toArray(
-      referenceListData.map((item, index) => (
-        <React.Fragment key={item[tablabelProp]}>
-          {buildView(pConnect, index, '')}
-        </React.Fragment>
-      ))
-    );
-  }, [referenceListData]);
-
-  // 4. Tab state
-  const [panelShown, changePanel] = useState(0);
-  const handleTabClick = (e, id) => changePanel(parseInt(id, 10));
-
-  // 5. Build tab items from reference list data
-  const tabItems = referenceListData?.map((item, i) => ({
-    name: item[tablabelProp] || PCore.getLocaleUtils().getLocaleValue('No label specified in config', 'Generic'),
-    id: i,
-  })) || [];
-
-  // 6. Render: optional heading + TabContext + scrollable Tabs + TabPanels
-  return (
-    <>
-      {propsToUse.label && <h3>{propsToUse.label}</h3>}
-      <TabContext value={panelShown.toString()}>
-        <TabBar onChange={handleTabClick} value={panelShown} variant="scrollable" scrollButtons="auto">
-          {tabItems.map(tab => <Tab key={tab.id} label={tab.name} value={tab.id} />)}
-        </TabBar>
-        {tabItems.map(tab => (
-          <TabPanel key={tab.id} value={tab.id.toString()} tabIndex={+tab.id}>
-            {memoisedTabViews?.[tab.id] || 'No content exists'}
-          </TabPanel>
-        ))}
-      </TabContext>
-    </>
-  );
-}
-```
+## Implementation Structure
+
+**Module Setup:** This component requires the `buildView` helper (from the project's field-group utilities) and the project's base component interface. Define a component input contract extending the base component interface with `showLabel: boolean`, `label: string`, and optional `referenceList?: any[]`.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `referenceList`, `showLabel`, `label`, and `getPConnect`; call `getPConnect()` once into `pConnect`; merge inherited inputs into `inputsToUse = { label, showLabel, ...pConnect.getInheritedProps() }`.
+2. **Resolve tab label property:** read `tablabel` from `pConnect.getComponentConfig()`, then resolve it to a raw property path via `PCore.getAnnotationUtils().getPropertyName(tablabel)` into `tablabelProp`.
+3. **Get reference list data:** `referenceListData = pConnect.getValue(referenceList + '.pxResults', '')`.
+4. **Memoized tab views** (recomputed only when `referenceListData` changes): force display-only mode via `pConnect.setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `pConnect.setInheritedProp('readOnly', true)`; then, if `referenceListData` is present, map each row to a keyed fragment (keyed by `item[tablabelProp]`) wrapping `buildView(pConnect, index, '')`, and normalize the result to an array.
+5. Declare local state `panelShown` (number, default `0`) with a click handler that parses the clicked tab's id as an integer and updates the state.
+6. **Build tab items:** map `referenceListData` to `{ name, id }` objects, where `name` is `item[tablabelProp]` or, if missing, the localized fallback `PCore.getLocaleUtils().getLocaleValue('No label specified in config', 'Generic')`, and `id` is the row index; default to an empty array when there's no data.
+7. Render: an optional heading element (shown when `inputsToUse.label` is set); a tab context (value = `panelShown` as a string) wrapping a scrollable tab bar with auto scroll buttons (one tab item per `tabItems` entry, labeled `tab.name`, valued `tab.id`) and one tab panel per `tabItems` entry (keyed and valued by `tab.id`, `tabIndex` set to the numeric id) showing `memoisedTabViews?.[tab.id]` or a "No content exists" fallback.
 
 ## Behavioral Contract
 
@@ -101,32 +48,22 @@ export default function DynamicTabs(props: DynamicTabsProps) {
 
 ### Reference List Data
 
-```
-referenceListData = pConnect.getValue(referenceList + '.pxResults')
-```
-
-Returns an array of row objects.
+`referenceListData` is obtained via `pConnect.getValue(referenceList + '.pxResults')` and returns an array of row objects.
 
 ### Tab Views
 
-For each row index `i`:
-
-```
-tabView = buildView(pConnect, i, '')
-```
-
-Memoized — recalculate only when `referenceListData` changes.
+For each row index `i`, the tab view is `buildView(pConnect, i, '')`. Memoized computation — recalculate only when `referenceListData` changes.
 
 ### State
 
-- `currentPanel`: index of active tab (number, default `0`).
-- `changePanel(index)`: `setCurrentPanel(index)`.
+- `currentPanel`: index of active tab (number, default `0`) — managed as local state.
+- `changePanel(index)`: updates the local state to the new index.
 
 ### Render
 
-- `<TabContext value={currentPanel.toString()}>`.
-- `<Tabs onChange={changePanel}>` — one `<Tab label={tabLabel[i]} value={i.toString()}>` per row.
-- `<TabPanel value={i.toString()}>` containing `tabView[i]`.
+- A tab context wrapper with value = `currentPanel` as a string.
+- A scrollable tab bar — one tab item per row, labeled with the resolved tab label and valued with the row index as a string.
+- One tab panel per row containing `tabView[i]`.
 
 ## Visual Specifications
 
@@ -140,34 +77,27 @@ Identical tab bar appearance to `SubTabs`.
 ## Edge Cases & Special Logic
 
 - `referenceListData` may be undefined on first render — default to empty array, render no tabs.
-- `tablabel` may be a reference annotation like `@[FIELD/.pyLabel]` — `getPropertyName` resolves it to the raw field path.
-- `buildView` is memoized on `referenceListData` — if the list changes, tab views must be regenerated.
-- `changePanel` receives the raw index (number) but `TabContext` value is a string — always `toString()` the index.
+- `tablabel` may be a reference annotation like `@[FIELD/.pyLabel]` — `PCore.getAnnotationUtils().getPropertyName()` resolves it to the raw field path.
+- `buildView` is wrapped in a memoized computation keyed on `referenceListData` — if the list changes, tab views must be regenerated.
+- `changePanel` receives the raw index (number) but the tab context value is a string — always convert the index to a string.
 - Empty reference list — show a "No items" empty state instead of an empty tab bar.
 
 ## Dependencies
 
-- `buildView` from `../../helpers/field-group-utils`
+- `buildView` from the project's field-group utilities — generates the content view for each tab
 - `PCore.getAnnotationUtils().getPropertyName()` — resolves annotation to property path
-- `TabContext`, `TabPanel` from `@mui/lab`
-- `Tab`, `Tabs` from `@mui/material`
+- `PCore.getLocaleUtils().getLocaleValue()` — provides localized fallback label
+- A tab component from your chosen design system — for rendering the tab bar and panels
 
 ## Design System Mapping
 
 **UI control type:** Data-driven tab navigation — tab count and labels from a reference list.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                            |
-| ------------------ | ------------------------------------------------ |
-| Default (CSS only) | Custom tab bar, dynamically generated from array |
-| MUI                | `<TabContext>` + `<Tabs>` + `<TabPanel>`         |
-| Ant Design         | `<Tabs items={dynamicItems}>`                    |
-| Chakra UI          | `<Tabs>` with dynamic `<TabList>/<TabPanels>`    |
-| Shadcn/ui          | `<Tabs>` with mapped triggers and content        |
-
-When implementing in a specific design system:
+When implementing in a specific design system, map the following:
 
+- A tab context/container that tracks the active panel by string value
+- A scrollable tab bar with auto scroll buttons, rendering one tab per data row
+- A tab panel container that shows the content for the active tab
 - `tablabelProp` resolution via `PCore.getAnnotationUtils().getPropertyName()` is required — do not hardcode the label field
 - `buildView(pConnect, rowIndex, '')` generates the content for each tab — the empty string third arg means no specific child config lookup
 - Tab count is entirely data-driven — handle 0, 1, and many tab cases

package/templates/react-sdk-reference/.ai-common/skills/template-skills/FieldGroupTemplate.md

@@ -10,41 +10,40 @@ Repeating field group template. Renders a list of field group rows from a refere
 >
 > This template manages a repeating list of field groups with add/delete actions. It MUST NOT be reduced to a simple delegation to `FieldGroup` or `FieldGroupList`. The following are MANDATORY:
 >
-> 1. `getReferenceList(pConn)` from `../../helpers/field-group-utils` — resolves the reference list path
-> 2. `buildView(pConn, index, lookForChildInConfig)` from `../../helpers/field-group-utils` — builds each row's view
+> 1. `getReferenceList(pConn)` from the project's field-group utility helpers — resolves the reference list path
+> 2. `buildView(pConn, index, lookForChildInConfig)` from the project's field-group utility helpers — builds each row's view
 > 3. `pConn.setReferenceList(resolvedList)` — sets the reference list on PConnect
 > 4. `pConn.getListActions().initDefaultPageInstructions(resolvedList)` — initializes list instructions
-> 5. `useLayoutEffect` for list initialization (not useEffect)
+> 5. A synchronous layout effect for list initialization (must run before paint, not a standard lifecycle effect)
 > 6. Add/delete record handlers using `pConn.getListActions().insert()` and `.deleteEntry()`
-> 7. `useMemo` for `MemoisedChildren` built from `referenceList.map(...)` + `buildView`
+> 7. A memoized computation for `MemoisedChildren` built from referenceList iteration plus `buildView`
 > 8. `allowActions` handling (allowAdd, allowDelete)
 > 9. `isReadonlyMode` check switching between FieldGroupList (edit) and FieldGroup (read-only)
 >
 > **Minimum Implementation Checklist:**
 >
-> - [ ] `getReferenceList` and `buildView` imported from `../../helpers/field-group-utils`
+> - [ ] `getReferenceList` and `buildView` sourced from the project's field-group utility helpers
 > - [ ] `pConn.getListActions()` used for insert/delete
-> - [ ] `useLayoutEffect` for `initDefaultPageInstructions`
+> - [ ] Synchronous layout effect for `initDefaultPageInstructions`
 > - [ ] `addRecord` and `deleteFieldGroupItem` handlers
-> - [ ] Edit mode → `<FieldGroupList items={...} onAdd={...} onDelete={...} />`
-> - [ ] Read-only mode → `<FieldGroup>` with `buildView` children
-> - [ ] `allowActions` / `allowTableEdit` props respected
+> - [ ] Edit mode renders a FieldGroupList with items, onAdd, and onDelete
+> - [ ] Read-only mode renders FieldGroup instances with `buildView` children
+> - [ ] `allowActions` / `allowTableEdit` inputs respected
 
 ---
 
 ## Component Purpose
 
-Renders a repeating list of field group rows sourced from a PConnect reference list. In edit mode, rows can be added and deleted via list actions. In read-only mode (DISPLAY_ONLY), delegates to a read-only `FieldGroup` renderer. Each row is built via `buildView`.
+Renders a repeating list of field group rows sourced from a PConnect reference list. In edit mode, rows can be added and deleted via list actions. In read-only mode (DISPLAY_ONLY), delegates to a read-only FieldGroup renderer. Each row is built via `buildView`.
 
 ## Pega Metadata
 
-- **Registration key:** `FieldGroupTemplate` (in `component-map.ts`)
+- **Registration key:** `FieldGroupTemplate` (in the project's component map)
 - **Category:** Form template — repeating
-- **Extends:** `PConnProps`
 
-## Props
+## Inputs
 
-| Prop             | Type       | Required | Description                                                      |
+| Input            | Type       | Required | Description                                                      |
 | ---------------- | ---------- | -------- | ---------------------------------------------------------------- |
 | `label`          | `string`   | Yes      | Section heading                                                  |
 | `showLabel`      | `boolean`  | No       | Whether to show the heading. Default `true`                      |
@@ -54,98 +53,21 @@ Renders a repeating list of field group rows sourced from a PConnect reference l
 | `readOnly`       | `boolean`  | No       | Alternative read-only flag                                       |
 | `getPConnect`    | `function` | Yes      | PConnect getter                                                  |
 
-## Component Skeleton
-
-```typescript
-import { useLayoutEffect, useMemo } from 'react';
-import { getReferenceList, buildView } from '../../helpers/field-group-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface FieldGroupTemplateProps extends PConnProps {
-  referenceList?: any[];
-  contextClass: string;
-  renderMode?: string;
-  heading?: string;
-  lookForChildInConfig?: boolean;
-  displayMode?: string;
-  fieldHeader?: string;
-  allowTableEdit: boolean;
-  allowActions?: any;
-}
-
-export default function FieldGroupTemplate(props: FieldGroupTemplateProps) {
-  const FieldGroup = getComponentFromRegistry('FieldGroup');
-  const FieldGroupList = getComponentFromRegistry('FieldGroupList');
-
-  const {
-    referenceList = [], renderMode, contextClass, getPConnect,
-    lookForChildInConfig, heading = '', displayMode, fieldHeader,
-    allowActions, allowTableEdit: allowAddEdit,
-  } = props;
-  const pConn = getPConnect();
-  const resolvedList = getReferenceList(pConn);
-  pConn.setReferenceList(resolvedList);
-  const pageReference = `${pConn.getPageReference()}${resolvedList}`;
-  const isReadonlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY';
-  const HEADING = heading ?? 'Row';
-
-  // 1. Resolve allowAdd/allowDelete from allowActions or allowTableEdit
-  const hasAllowActions = Object.keys(allowActions ?? {}).length > 0;
-  const { allowAdd: actionAdd, allowDelete: actionDelete } = allowActions ?? {};
-  const allowAdd = hasAllowActions ? (actionAdd ?? true) : (allowAddEdit ?? true);
-  const allowDelete = hasAllowActions ? (actionDelete ?? true) : (allowAddEdit ?? true);
-
-  // 2. Init page instructions on mount (edit mode only)
-  useLayoutEffect(() => {
-    if (!isReadonlyMode) {
-      pConn.getListActions().initDefaultPageInstructions(resolvedList);
-    }
-  }, [referenceList?.length]);
-
-  // 3. Dynamic header per row
-  const getDynamicHeaderProp = (item, index) => {
-    if (fieldHeader === 'propertyRef' && heading && item[heading.substring(1)])
-      return item[heading.substring(1)];
-    return `Row ${index + 1}`;
-  };
-
-  // 4. Add/delete handlers
-  const addRecord = () => {
-    if (PCore.getPCoreVersion()?.includes('8.7'))
-      pConn.getListActions().insert({ classID: contextClass }, referenceList.length, pageReference);
-    else pConn.getListActions().insert({}, referenceList.length);
-  };
-  const deleteRecord = (index) => {
-    if (PCore.getPCoreVersion()?.includes('8.7'))
-      pConn.getListActions().deleteEntry(index, pageReference);
-    else pConn.getListActions().deleteEntry(index);
-  };
-
-  // 5. Edit mode: auto-add first row if empty, render FieldGroupList
-  if (!isReadonlyMode) {
-    if (referenceList.length === 0 && allowAdd) addRecord();
-    const items = useMemo(() => referenceList.map((item, index) => ({
-      id: index,
-      name: fieldHeader === 'propertyRef' ? getDynamicHeaderProp(item, index) : `${HEADING} ${index + 1}`,
-      children: buildView(pConn, index, lookForChildInConfig),
-    })), [referenceList?.length]);
-    return <FieldGroupList items={items}
-      onAdd={allowAdd ? addRecord : undefined}
-      onDelete={allowDelete ? deleteRecord : undefined} />;
-  }
-
-  // 6. Read-only mode: FieldGroup per row
-  pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY');
-  const readOnlyList = useMemo(() => referenceList.map((item, index) => (
-    <FieldGroup key={item[heading] || `field-group-row-${index}`}
-      name={fieldHeader === 'propertyRef' ? getDynamicHeaderProp(item, index) : `${HEADING} ${index + 1}`}>
-      {buildView(pConn, index, lookForChildInConfig)}
-    </FieldGroup>
-  )), []);
-  return <div>{readOnlyList}</div>;
-}
-```
+Additional inputs accepted: `referenceList` (array, defaults to empty), `contextClass` (string, required), `renderMode` (string, optional), `heading` (string, defaults to empty), `lookForChildInConfig` (boolean, optional), `allowActions` (object, optional).
+
+## Main Component Logic
+
+Steps in order:
+
+1. Retrieve FieldGroup and FieldGroupList from the project's component registry.
+2. Receive inputs: `referenceList` (default empty array), `renderMode`, `contextClass`, `getPConnect`, `lookForChildInConfig`, `heading` (default empty string), `displayMode`, `fieldHeader`, `allowActions`, and `allowTableEdit` (alias `allowAddEdit`).
+3. Call `getPConnect()` into `pConn`. Resolve the reference list path via `getReferenceList(pConn)` into `resolvedList` and register it via `pConn.setReferenceList(resolvedList)`. Build `pageReference` by concatenating `pConn.getPageReference()` with `resolvedList`. Determine `isReadonlyMode` when `renderMode === 'ReadOnly'` or `displayMode === 'DISPLAY_ONLY'`. Default `HEADING` to `heading` or `'Row'`.
+4. **Resolve add/delete permissions:** check whether `allowActions` has any keys (`hasAllowActions`). Destructure `allowAdd`/`allowDelete` from it as `actionAdd`/`actionDelete`. Compute final `allowAdd`/`allowDelete` flags — when `hasAllowActions` is true, use `actionAdd ?? true` / `actionDelete ?? true`; otherwise fall back to `allowAddEdit ?? true` for both.
+5. **Init page instructions on mount** (edit mode only): inside a synchronous layout effect (must run before paint) keyed on `referenceList` length, when not in read-only mode, call `pConn.getListActions().initDefaultPageInstructions(resolvedList)`. This MUST be a synchronous layout effect, not a standard lifecycle effect, to avoid visual flicker during list initialization.
+6. Define `getDynamicHeaderProp(item, index)`: if `fieldHeader === 'propertyRef'` and `heading` resolves a value on `item` (via `item[heading.substring(1)]`), return that value; otherwise return a default label like "Row N".
+7. Define `addRecord`: if `PCore.getPCoreVersion()` includes `'8.7'`, call `pConn.getListActions().insert({ classID: contextClass }, referenceList.length, pageReference)`; otherwise call `pConn.getListActions().insert({}, referenceList.length)`. Define `deleteRecord(index)` similarly, calling `pConn.getListActions().deleteEntry(index, pageReference)` on 8.7 or `pConn.getListActions().deleteEntry(index)` otherwise.
+8. **Edit mode:** if not read-only, auto-add a first row when `referenceList` is empty and `allowAdd` is true. Produce a memoized computation (keyed on `referenceList` length) by mapping `referenceList` to objects of shape `{ id: index, name: <dynamic or default heading>, children: buildView(pConn, index, lookForChildInConfig) }`. Render FieldGroupList with `items`, `onAdd` (when `allowAdd` is true), and `onDelete` (when `allowDelete` is true).
+9. **Read-only mode:** force `pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY')`. Produce a memoized computation (run once) by mapping `referenceList` to one FieldGroup per row (keyed by `item[heading]` or a fallback row key, named via the dynamic/default heading) containing `buildView(pConn, index, lookForChildInConfig)`. Render the list inside a wrapping container.
 
 ## Behavioral Contract
 
@@ -153,21 +75,19 @@ export default function FieldGroupTemplate(props: FieldGroupTemplateProps) {
 
 If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
 
-1. Set `setInheritedProp('DISPLAY_ONLY', true)` on the pConn.
-2. Render `<FieldGroup>` — the DSE component that shows data in a read-only layout.
+1. Call `pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY')`.
+2. Render a FieldGroup (from the component registry) per row — the design system component that shows data in a read-only layout.
 
 ### Edit Mode
 
-1. **Get reference list:** `resolvedList = getReferenceList(pConn)` — extracts the array of row data objects.
-2. **Set reference list:** `pConn.setReferenceList(resolvedList)` — ensures the pConn has the resolved list.
-3. **Build row views:** For each row index `i`, call `buildView(pConn, i, true)` to get the PConnect view for that row.
-4. **Render `<FieldGroupList>`** — the DSE component for edit mode, receiving:
-   - `resolvedList` for row count
-   - Row views as children
-   - `onAdd`: calls `pConn.getListActions().insert({})`
-   - `onDelete(index)`: calls `pConn.getListActions().deleteEntry(index)`
-   - `fieldHeader`: evaluated property ref for dynamic row heading
-   - `allowActions`: from `allowTableEdit` prop (controls visibility of add/delete buttons)
+1. **Get reference list:** `resolvedList = getReferenceList(pConn)` — extracts the reference list path string.
+2. **Set reference list:** `pConn.setReferenceList(resolvedList)` — ensures the pConn has the resolved list registered.
+3. **Build row views:** For each row index `i`, call `buildView(pConn, i, lookForChildInConfig)` to get the PConnect view for that row.
+4. **Render FieldGroupList** — the design system component for edit mode, receiving:
+   - Memoized items array for row content
+   - `onAdd`: calls `pConn.getListActions().insert(...)` with version-appropriate arguments
+   - `onDelete(index)`: calls `pConn.getListActions().deleteEntry(...)` with version-appropriate arguments
+   - Row headings: dynamic (from `fieldHeader` property ref) or default ("Row N")
 
 ### `allowActions` Override
 
@@ -182,50 +102,29 @@ If the field group is inside a read-only context (parent has set `readOnly` or `
   - Dynamic heading from `fieldHeader` property value (e.g. `"Active"`, `"Pending"`).
   - Row fields in a grid layout.
   - Delete button (trash icon) per row.
-- Add row button at the bottom (e.g. `"+ Add row"`).
+- Add row button at the bottom (e.g. "+ Add row").
 
 ### Read-Only Mode
 
 - Section heading at top (if `showLabel`).
 - Flat list of rows — no add/delete controls.
 
-**CSS-only implementation notes:**
-
-- Row section: `border: 1px solid var(--border-color); border-radius: 4px; padding: 1rem; margin-bottom: 0.5rem`.
-- Add button: text button, below the last row.
-- Delete button: icon button, top-right of each row section.
+Use companion styles to achieve row cards with a border, border-radius, padding, and bottom margin. The add button appears as a text-style button below the last row. The delete button appears as an icon button at the top-right of each row section.
 
 ## Edge Cases & Special Logic
 
 - `getReferenceList(pConn)` returns `undefined` if the reference list is not yet loaded — guard and render empty list.
 - `buildView(pConn, index, true)` — third argument `lookForChildInConfig=true` — required for embedded field groups.
 - Row index must be passed to `deleteEntry` as a number (not string).
-- `fieldHeader` is a property ref like `'.pyStatusWork'` — evaluate it per-row via `pConn.getValue(fieldHeader, index)` to get the display label for each row heading.
-- `FieldGroupList` and `FieldGroup` are DSE (design system extension) components registered in the component registry.
+- `fieldHeader` is a property ref like `'.pyStatusWork'` — evaluate it per-row via `item[heading.substring(1)]` to get the display label for each row heading.
+- FieldGroupList and FieldGroup are design system extension components registered in the project's component registry.
 
 ## Dependencies
 
-- `getReferenceList`, `buildView` from `../../helpers/field-group-utils`
-- `getComponentFromRegistry('FieldGroupList')` — edit mode renderer
-- `getComponentFromRegistry('FieldGroup')` — read-only renderer
-- `PConnectComponent` from `@pega/sdk-react` — used inside `buildView`
+- `getReferenceList`, `buildView` from the project's field-group utility helpers
+- The project's component registry to retrieve FieldGroupList (edit mode) and FieldGroup (read-only mode)
+- The project's base component interface for rendering child PConnect views inside `buildView`
 
 ## Design System Mapping
 
-**UI control type:** Repeating list of grouped form sections with add/delete row management.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                              |
-| ------------------ | ------------------------------------------------------------------ |
-| Default (CSS only) | Custom row card list with add/delete buttons                       |
-| MUI                | `<Paper>` per row + `<IconButton>` for delete + `<Button>` for add |
-| Ant Design         | `<Form.List>` with `<Card>` per row                                |
-| Chakra UI          | Custom repeating section with `<Box>` rows                         |
-| Shadcn/ui          | Custom list with `<Card>` per row + `<Button variant='ghost'>`     |
-
-When implementing in a specific design system:
-
-- The add/delete controls must be hidden when `allowActions` is false
-- Row heading is dynamic — evaluate `fieldHeader` property ref per row
-- `buildView` generates child PConnect views — render them inside each row section
+Use repeating row cards for the edit mode layout. Each row should be a bordered card containing the fields generated by `buildView`. Provide an add button (text style) below the last row and a delete button (icon style) at the top-right of each row card. The design system's grouping or card primitive is the natural fit for each row. In read-only mode, use a simpler flat list of labelled groups without action controls. Hide add/delete controls when `allowActions` is false. The row heading is dynamic — evaluate the `fieldHeader` property ref per row.