@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/CaseSummaryFields.md

@@ -2,7 +2,7 @@
 
 Display-only grid of typed field values for a case summary header. Renders a 2-column grid of read-only fields, each formatted according to its type (text, date, currency, phone, email, checkbox, status, operator, etc.).
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,70 +13,52 @@ Renders a responsive 2-column read-only grid of field values for a case summary
 ## Pega Metadata
 
 - **Pega Name:** `CaseSummaryFields`
-- **Registration key:** `CaseSummaryFields` (in `component-map.ts`)
-- **Does NOT use `getPConnect` directly** — receives pre-processed `theFields` array as a prop
+- **Registration key:** `CaseSummaryFields` (in the project's component map)
+- **Does NOT use `getPConnect` directly** — receives pre-processed `theFields` array as an input
 
-## Props
+## Component Inputs
 
-| Prop         | Type                                           | Required | Description                                                               |
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name         | Type                                           | Required | Description                                                               |
 | ------------ | ---------------------------------------------- | -------- | ------------------------------------------------------------------------- |
 | `theFields`  | `Array<{ type: string; config: FieldConfig }>` | Yes      | Array of typed field descriptors to render                                |
 | `status`     | `string`                                       | No       | The case status value, injected at position 1 if `showStatus` is true     |
 | `showStatus` | `boolean`                                      | No       | If `true`, splices a status field entry at position 1 in the fields array |
 
-## Component Skeleton
-
-```typescript
-import { useState, useEffect } from 'react';
-import isDeepEqual from 'fast-deep-equal/react';
-import { getDateFormatInfo } from '../../helpers/date-format-utils';
-import { getCurrencyOptions } from '../../field/Currency/currency-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import { format } from '../../helpers/formatters';
-import './CaseSummaryFields.css';
-
-interface CaseSummaryFieldsProps {
-  status?: string;
-  showStatus?: boolean;
-  theFields: any[];
-}
-
-export default function CaseSummaryFields(props: CaseSummaryFieldsProps) {
-  const Operator = getComponentFromRegistry('Operator');
-  const { status, showStatus, theFields } = props;
-  const [theFieldsToRender, setFieldsToRender] = useState([]);
-  const [theFieldsAsGridItems, setFieldsAsGridItems] = useState<any[]>([]);
-
-  // 1. getFieldValue(field) — type-based rendering switch
-  //    See Behavioral Contract #4 for the full type switch
-
-  // 2. useEffect: recompute grid items when theFieldsToRender changes
-  useEffect(() => {
-    const items = theFieldsToRender?.map(field => {
-      if (field.config.visibility === undefined || field.config.visibility === true)
-        return <GridItem xs={6} key={field.config.label}>{getFieldValue(field)}</GridItem>;
-      return null;
-    });
-    setFieldsAsGridItems(items);
-  }, [theFieldsToRender]);
-
-  // 3. Status injection (mutates theFields)
-  const theFieldsModifiable = theFields;
-  if (showStatus && theFields?.[1]?.type !== 'status') {
-    const oStatus = { type: 'status', config: { value: status, label: 'Status' } };
-    if (theFieldsModifiable.length < 2) theFieldsModifiable.push(oStatus);
-    else theFieldsModifiable.splice(1, 0, oStatus);
-  }
-
-  // 4. Deep equality check before state update (prevents infinite re-render)
-  if (!isDeepEqual(theFieldsToRender, theFieldsModifiable)) {
-    setFieldsToRender(theFieldsModifiable);
-  }
-
-  // 5. Render: 2-column grid
-  return <GridContainer className="psdk-case-summary-fields">{theFieldsAsGridItems}</GridContainer>;
-}
-```
+## Implementation Structure
+
+### Module Setup
+
+The component imports the following dependencies:
+
+- A state management mechanism (local state for the fields array and rendered grid items)
+- A lifecycle effect to recompute grid items when the fields array changes
+- A deep-equality utility (for comparing field arrays before updates)
+- `getDateFormatInfo` from the project's date-format utilities for locale date format strings
+- `getCurrencyOptions` from the project's currency utilities for currency formatting
+- The `Operator` component retrieved from the project's component registry at runtime
+- `format` from the project's formatting helpers for value formatting (phone, email, date, currency, etc.)
+- Companion styles (for status field and grid styling) co-located following the project's styling convention
+
+The component is named `CaseSummaryFields` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+The component performs these steps in order:
+
+1. **Resolve Operator** — retrieve the `Operator` component from the project's component registry (allows runtime override).
+2. **Receive inputs** — extract `status`, `showStatus`, and `theFields`.
+3. **Declare state** — two state variables:
+   - `theFieldsToRender` (array) — the final fields array after status injection.
+   - `theFieldsAsGridItems` (array) — the rendered grid item elements.
+4. **Define `getFieldValue(field)` helper** — a type-based rendering switch (see Behavioral Contract #4 for the full type-to-rendering table).
+5. **Lifecycle effect on `theFieldsToRender`** — when `theFieldsToRender` changes, recompute `theFieldsAsGridItems` by mapping each field:
+   - Skip fields where `config.visibility` exists and is `false`.
+   - For visible fields, render a grid cell (6 of 12 columns) keyed by `field.config.label`, containing `getFieldValue(field)`.
+6. **Status injection** — if `showStatus` is `true` AND `theFields[1].type !== 'status'`, inject a status entry at position 1 (an object with `type: 'status'` and `config` containing `value` from the `status` input and `label` set to `'Status'`). If the array has fewer than 2 items, append at the end instead.
+7. **Deep equality guard** — only update `theFieldsToRender` with the new array if it is NOT deep-equal to the current `theFieldsToRender` (prevents infinite re-render/change-detection loops).
+8. **Render** — return a grid container with class `psdk-case-summary-fields` containing `theFieldsAsGridItems` (a 2-column layout).
 
 ### FieldConfig shape (within each item in `theFields`)
 
@@ -94,19 +76,13 @@ export default function CaseSummaryFields(props: CaseSummaryFieldsProps) {
 
 ### 1. Status Field Injection
 
-Before rendering, if `showStatus` is `true` AND `theFields[1].type !== 'status'`, inject a status entry at position 1:
-
-```
-{ type: 'status', config: { value: status, label: 'Status' } }
-```
-
-If the fields array has fewer than 2 items, append the status entry at the end.
+Before rendering, if `showStatus` is `true` AND `theFields[1].type !== 'status'`, inject a status entry at position 1 — an object with `type` set to `'status'` and `config` containing `value` (from the `status` input) and `label` set to `'Status'`. If the fields array has fewer than 2 items, append the status entry at the end.
 
 ### 2. State Management with Deep Equality
 
 - Store the final fields array in `theFieldsToRender` state.
-- Only update `theFieldsToRender` if the new value is not deep-equal to the current value (use `fast-deep-equal/react`).
-- When `theFieldsToRender` changes, recompute `theFieldsAsGridItems` (via `useEffect`).
+- Only update `theFieldsToRender` if the new value is not deep-equal to the current value (use a deep-equality utility).
+- When `theFieldsToRender` changes, recompute `theFieldsAsGridItems` (via a lifecycle effect).
 
 ### 3. Field Visibility
 
@@ -116,34 +92,34 @@ Skip any field where `config.visibility` exists and is `false`.
 
 When `field.config.value` is `null` or `''` (empty):
 
-- For `caseoperator`: render `<Operator {...field.config} />`.
-- For all other types: render a read-only TextField with value `'---'` and the field label.
+- For `caseoperator`: render the `Operator` component with `field.config` spread as inputs.
+- For all other types: render a read-only text display element with value `'---'` and the field label.
 
 When `field.config.value` is non-empty, switch on `field.type.toLowerCase()`:
 
-| Type                                          | Rendering                                                                                           |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `textinput`, `decimal`, `integer`, `dropdown` | Read-only TextField (standard, no underline) with `value`                                           |
-| `checkbox`                                    | Label: `label \|\| caption`; Value: `value ? trueLabel : falseLabel`; read-only TextField           |
-| `status`                                      | Read-only TextField with class `psdk-csf-status-style` (uppercase, small, bold)                     |
-| `phone`                                       | `<a href={'tel:' + value}>` wrapping a read-only TextField with pointer cursor                      |
-| `email`                                       | `<a href={'mailto:' + format(value, 'email')}>` wrapping a read-only TextField with pointer cursor  |
-| `date`                                        | Read-only TextField with `format(value, 'date', { format: dateFormatStringLong })`                  |
-| `datetime`                                    | Read-only TextField with `format(value, 'datetime', { format: dateFormatStringLong + ' hh:mm a' })` |
-| `currency`                                    | Read-only TextField with `format(value, 'currency', getCurrencyOptions(currencyISOCode))`           |
-| `boolean`, `userreference`                    | Read-only TextField with `format(value, type)`                                                      |
-| `caseoperator`                                | `<Operator {...field.config} />`                                                                    |
-| default (unknown)                             | `<span>{type} {value}</span>`                                                                       |
-
-All TextFields use: `variant='standard'`, `slotProps.input.readOnly = true`, `slotProps.input.disableUnderline = true`.
+| Type                                          | Rendering                                                                                              |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `textinput`, `decimal`, `integer`, `dropdown` | Read-only text display (no underline) with `value` and `label`                                         |
+| `checkbox`                                    | Label: `label \|\| caption`; Value: `value ? trueLabel : falseLabel`; read-only text display           |
+| `status`                                      | Read-only text display with class `psdk-csf-status-style` (uppercase, small, bold)                     |
+| `phone`                                       | `<a href={'tel:' + value}>` wrapping a read-only text display with pointer cursor                      |
+| `email`                                       | `<a href={'mailto:' + format(value, 'email')}>` wrapping a read-only text display with pointer cursor  |
+| `date`                                        | Read-only text display with `format(value, 'date', { format: dateFormatStringLong })`                  |
+| `datetime`                                    | Read-only text display with `format(value, 'datetime', { format: dateFormatStringLong + ' hh:mm a' })` |
+| `currency`                                    | Read-only text display with `format(value, 'currency', getCurrencyOptions(currencyISOCode))`           |
+| `boolean`, `userreference`                    | Read-only text display with `format(value, type)`                                                      |
+| `caseoperator`                                | Render the `Operator` component with `field.config` as inputs                                          |
+| default (unknown)                             | `<span>{type} {value}</span>`                                                                          |
+
+All read-only text display elements use: no underline/border, read-only state, with the field label shown above the value.
 
 ### 5. Grid Layout
 
-Render each visible field in `Grid size={{ xs: 6 }}` (2-column layout) inside a container `Grid` with class `psdk-case-summary-fields`.
+Render each visible field in a grid cell (6 of 12 columns — 2-column layout) inside a grid container with class `psdk-case-summary-fields`.
 
 ## Visual Specifications
 
-Derived from `CaseSummaryFields.css`:
+Derived from the component's companion styles:
 
 ### Status Field
 
@@ -173,41 +149,32 @@ Derived from `CaseSummaryFields.css`:
 
 ## Edge Cases & Special Logic
 
-- Use `fast-deep-equal/react` deep equality before updating `theFieldsToRender` to prevent infinite re-render loops.
+- Use deep equality before updating `theFieldsToRender` to prevent infinite re-render loops.
 - Status splicing mutates `theFields` directly — ensure the original array reference is used (not a copy) when checking `theFields[1].type`.
 - Date format comes from `getDateFormatInfo().dateFormatStringLong` — defaults to locale format.
 - Currency options come from `getCurrencyOptions(field.config?.currencyISOCode)`.
-- The `Operator` component is retrieved via `getComponentFromRegistry('Operator')` — not imported directly. This allows runtime component override.
+- The `Operator` component is retrieved from the project's component registry — not imported directly. This allows runtime component override.
 - If `theFields` is null or undefined, initialize to empty to avoid crashes.
 
 ## Dependencies
 
-- `getComponentFromRegistry` from `@pega/sdk-react` — to retrieve the `Operator` component at runtime
-- `isDeepEqual` from `fast-deep-equal/react` — for state change detection
-- `getDateFormatInfo` from `../../helpers/date-format-utils` — for locale date format string
-- `getCurrencyOptions` from `../../field/Currency/currency-utils` — for currency formatting options
-- `format` from `../../helpers/formatters` — for formatting phone, email, date, datetime, currency, boolean, userreference values
+- The project's component registry — to retrieve the `Operator` component at runtime
+- A deep-equality utility — for state change detection
+- The project's date-format utility — for locale date format string
+- The project's currency utility — for currency formatting options
+- The project's formatting helper — for formatting phone, email, date, datetime, currency, boolean, userreference values
 - `Operator` component (resolved via registry) — for `caseoperator` type rendering
 
 ## Design System Mapping
 
 **UI control type:** 2-column grid of read-only labeled field values.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                                                        |
-| ------------------ | ------------------------------------------------------------------------------------------------------------ |
-| Default (CSS only) | CSS Grid 2-column layout with label/value pairs                                                              |
-| MUI                | `<Grid container>` with `<Grid size={{ xs: 6 }}>` cells; `<TextField variant='standard' readOnly>` per field |
-| Ant Design         | `<Descriptions layout='vertical' column={2}>` with typed item renderers                                      |
-| Chakra UI          | `<SimpleGrid columns={2}>` with `<FormControl>` label/value pairs                                            |
-| Shadcn/ui          | 2-column grid with `<Label>` / `<p>` pairs                                                                   |
-
 When implementing in a specific design system, map the following:
 
-- Read-only TextField (standard, no underline) → design system's read-only text display
-- Phone field → `<a href='tel:...'>` wrapper around the display
-- Email field → `<a href='mailto:...'>` wrapper around the display
-- Status field → uppercase badge/chip or styled text
-- `caseoperator` type → delegate to the `Operator` component
-- Missing/empty value → always display `'---'`
+- **Grid layout** → use the DS's grid system to create a 2-column responsive layout (each cell occupies 6 of 12 columns)
+- **Read-only text display** (label above value, no underline) → use the DS's form field in read-only/display mode, or a simple label/value pair with appropriate typography
+- **Phone field** → wrap in an `<a href='tel:...'>` link with pointer cursor
+- **Email field** → wrap in an `<a href='mailto:...'>` link with pointer cursor
+- **Status field** → uppercase badge/chip or styled text (font-size: 0.75rem, bold, uppercase)
+- **`caseoperator` type** → delegate to the `Operator` component from the registry
+- **Missing/empty value** → always display `'---'`

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/DetailsFields.md

@@ -1,81 +1,73 @@
 # Skill: DetailsFields
 
-Read-only field display component that receives an array of PConnect-aware field objects and renders each as a label/value pair. Delegates value rendering to `PConnectComponent` in DISPLAY_ONLY mode.
+Read-only field display component that receives an array of PConnect-aware field objects and renders each as a label/value pair. Delegates value rendering to the PConnect bridge component in DISPLAY_ONLY mode.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
 ## Component Purpose
 
-Renders a vertical list of read-only field name/value pairs for a details/summary panel. Each field is a PConnect-aware object. The component extracts type, label, and view config from each field's PConnect, forces the view into `readOnly + DISPLAY_ONLY` mode, and delegates rendering to `PConnectComponent`.
+Renders a vertical list of read-only field name/value pairs for a details/summary panel. Each field is a PConnect-aware object. The component extracts type, label, and view config from each field's PConnect, forces the view into `readOnly + DISPLAY_ONLY` mode, and delegates rendering to the PConnect bridge component.
 
 Supports three item layouts:
 
 - **Reference type:** Renders the value directly (no label/value grid wrapper).
-- **React element value:** Renders value in a single full-width cell (no label).
+- **Rendered component value:** Renders value in a single full-width cell (no label).
 - **Label + value pair:** Renders label in a 6-col cell and value in a 6-col cell.
 
 ## Pega Metadata
 
 - **Pega Name:** `DetailsFields`
-- **Registration key:** `DetailsFields` (in `component-map.ts`)
+- **Registration key:** `DetailsFields` (in the project's component map)
 - **Does NOT use `getPConnect` on the component itself** — iterates `fields[]` each of which has `.getPConnect()`
 
-## Props
+## Component Inputs
 
-| Prop     | Type    | Required | Description                                                                   |
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name     | Type    | Required | Description                                                                   |
 | -------- | ------- | -------- | ----------------------------------------------------------------------------- |
 | `fields` | `any[]` | Yes      | Array of PConnect-aware field objects. Each must have `.getPConnect()` method |
 
-## Component Skeleton
-
-```typescript
-import { createElement, isValidElement } from 'react';
-import { PConnectComponent } from '@pega/sdk-react';
-import { format } from '../../helpers/formatters';
-
-interface DetailsFieldsProps { fields: any[]; }
-
-export default function DetailsFields(props: DetailsFieldsProps) {
-  const { fields = [] } = props;
-  const fieldComponents: any[] = [];
-
-  // 1. Build field components array
-  fields?.forEach((field, index) => {
-    const thePConn = field.getPConnect();
-    const theCompType = thePConn.getComponentName().toLowerCase();
-    const { label } = thePConn.getConfigProps();
-    const configObj = thePConn.getReferencedView();
-    configObj.config.readOnly = true;
-    configObj.config.displayMode = 'DISPLAY_ONLY';
-    if (theCompType === 'reference') configObj.config.label = thePConn.getInheritedProps()?.label;
-    fieldComponents.push({
-      type: theCompType, label,
-      value: createElement(PConnectComponent, thePConn.getReferencedViewPConnect()),
-    });
-  });
-
-  // 2. Render grid items per field
-  return (
-    <>
-      {fieldComponents.map((field, index) => {
-        if (field.type === 'reference') return field.value;
-        if (isValidElement(field.value)) {
-          return <GridRow key={index}><GridItem xs={12}>{field.value}</GridItem></GridRow>;
-        }
-        const formattedValue = field.type === 'date' ? format(field.value, 'date') : field.value;
-        return (
-          <GridRow key={index} style={{ padding: '4px 0' }}>
-            <GridItem xs={6}><Label>{field.label}</Label></GridItem>
-            <GridItem xs={6}><Value>{formattedValue || '---'}</Value></GridItem>
-          </GridRow>
-        );
-      })}
-    </>
-  );
-}
-```
+## Implementation Structure
+
+### Module Setup
+
+The component imports the following dependencies:
+
+- A utility to check if a value is a rendered component element (to distinguish rendered child components from plain string/primitive values)
+- The project's PConnect bridge component — renders PConnect-configured children
+- `format` from the project's formatting helpers — for date value formatting
+
+The component is named `DetailsFields` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+The component receives `fields` (defaults to `[]`) as input, then performs two phases:
+
+**Phase 1: Build field components array**
+
+Iterate over `fields` using `forEach`. For each field:
+
+1. Call `field.getPConnect()` to obtain the PConnect instance (`thePConn`).
+2. Get `theCompType = thePConn.getComponentName().toLowerCase()`.
+3. Get `label` from `thePConn.getConfigProps()`.
+4. Get the referenced view config: `configObj = thePConn.getReferencedView()`.
+5. Force display-only mode: set `configObj.config.readOnly = true` and `configObj.config.displayMode = 'DISPLAY_ONLY'`.
+6. For `reference` type components: override the label with `thePConn.getInheritedProps()?.label`.
+7. Render the value by invoking the PConnect bridge component with `thePConn.getReferencedViewPConnect()` as its configuration.
+8. Push an object with `{ type, label, value }` into the field components array.
+
+**Phase 2: Render grid items**
+
+Return a fragment containing the mapped field components. For each field, choose the layout:
+
+- **`type === 'reference'`** — render `field.value` directly with no grid wrapper.
+- **Value is a rendered element/component** — render a grid row with a single 12-column cell containing `field.value` (full width, no label).
+- **Default (primitive/string value)** — render a grid row (with `padding: 4px 0`) containing:
+  - A 6-column label cell with body-small text, secondary text color, `fontWeight: 400`.
+  - A 6-column value cell with body-small text, primary text color. Format the value using `format(value, 'date')` if `type === 'date'`, otherwise use value as-is. If the formatted value is `undefined` or empty string, display `'---'`.
 
 ## Behavioral Contract
 
@@ -89,24 +81,24 @@ For each field in `fields`:
 4. Call `configObj = thePConn.getReferencedView()` — get the referenced view config object.
 5. Set `configObj.config.readOnly = true` and `configObj.config.displayMode = 'DISPLAY_ONLY'` — forces display-only rendering.
 6. For `reference` type: override label with `thePConn.getInheritedProps().label`.
-7. Render the value using `createElement(PConnectComponent, thePConn.getReferencedViewPConnect())`.
-8. Push `{ type: theCompType, label, value: <React.Fragment key={index}>{renderedValue}</React.Fragment> }` into the field components array.
+7. Render the value using the PConnect bridge component with `thePConn.getReferencedViewPConnect()` as its configuration.
+8. Push `{ type: theCompType, label, value: renderedElement }` into the field components array.
 
 ### 2. Item Layout (per field component)
 
 Choose the layout based on the field:
 
-| Condition                        | Layout                                                 |
-| -------------------------------- | ------------------------------------------------------ |
-| `type === 'reference'`           | Render `field.value` directly with no wrapper          |
-| `isValidElement(field.value)`    | Single 12-col cell containing `field.value` (no label) |
-| Default (string/primitive value) | 6-col label cell + 6-col value cell                    |
+| Condition                             | Layout                                                 |
+| ------------------------------------- | ------------------------------------------------------ |
+| `type === 'reference'`                | Render `field.value` directly with no wrapper          |
+| Value is a rendered element/component | Single 12-col cell containing `field.value` (no label) |
+| Default (string/primitive value)      | 6-col label cell + 6-col value cell                    |
 
 ### 3. Label/Value Grid Row
 
-- **Row wrapper:** `<Grid container spacing={1} style={{ padding: '4px 0px' }}>`
-- **Label cell:** `<Grid size={{ xs: 6 }}>` containing `<Typography variant='body2' component='span' className='fieldLabel'>{field.label}</Typography>`
-- **Value cell:** `<Grid size={{ xs: 6 }}>` containing `<Typography variant='body2' component='span' className='fieldValue'>{formattedValue}</Typography>`
+- **Row wrapper:** a grid container with spacing and `padding: 4px 0`
+- **Label cell:** 6 of 12 columns containing a body-small text element with secondary text color, `fontWeight: 400`, displaying `field.label`
+- **Value cell:** 6 of 12 columns containing a body-small text element with primary text color, displaying the formatted value
 
 ### 4. Value Formatting
 
@@ -114,30 +106,30 @@ Choose the layout based on the field:
 - For all others: use value as-is.
 - If formatted value is `undefined` or `''`, display `'---'` instead.
 
-### 5. React element detection
+### 5. Rendered element detection
 
-Use `isValidElement(field.value)` — if true, render full-width (12 cols) without label.
+Use the framework's equivalent of checking if a value is a rendered/component element — if true, render full-width (12 cols) without label.
 
 ## Visual Specifications
 
-Derived from `DetailsFields.tsx` makeStyles:
+Derived from the component's companion styles:
 
 ### Label
 
-| Property    | Value                          |
-| ----------- | ------------------------------ |
-| Display     | block                          |
-| Font weight | 400                            |
-| Color       | `theme.palette.text.secondary` |
-| Typography  | `body2` (≈ 0.875rem / 14px)    |
+| Property    | Value                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------- |
+| Display     | block                                                                                 |
+| Font weight | 400                                                                                   |
+| Color       | secondary text color (e.g. `theme.palette.text.secondary` or `var(--text-secondary)`) |
+| Typography  | body-small (≈ 0.875rem / 14px)                                                        |
 
 ### Value
 
-| Property    | Value                        |
-| ----------- | ---------------------------- |
-| Font weight | 400                          |
-| Color       | `theme.palette.text.primary` |
-| Typography  | `body2` (≈ 0.875rem / 14px)  |
+| Property    | Value                                                                           |
+| ----------- | ------------------------------------------------------------------------------- |
+| Font weight | 400                                                                             |
+| Color       | primary text color (e.g. `theme.palette.text.primary` or `var(--text-primary)`) |
+| Typography  | body-small (≈ 0.875rem / 14px)                                                  |
 
 ### Row Padding
 
@@ -150,48 +142,39 @@ Derived from `DetailsFields.tsx` makeStyles:
 - Each row: `display: grid; grid-template-columns: 1fr 1fr; padding: 4px 0; gap: 8px`.
 - Label: `font-size: 0.875rem; font-weight: 400; color: var(--text-secondary); display: block`.
 - Value: `font-size: 0.875rem; font-weight: 400; color: var(--text-primary)`.
-- For a React element value (full-width): render in a single column spanning full width.
+- For a rendered element value (full-width): render in a single column spanning full width.
 - For a reference type: render the component directly with no wrapping grid.
 
 ## Edge Cases & Special Logic
 
 - `fields` defaults to `[]` — guard against null/undefined.
 - Reference fields bypass the label/value layout entirely — their rendered output fills the full row.
-- React element values (e.g., from child components) are detected with `isValidElement` and rendered full-width without a label cell.
+- Rendered element values (e.g., from child components) are detected using the framework's element-check utility and rendered full-width without a label cell.
 - The `configObj` mutation (`readOnly = true`, `displayMode = 'DISPLAY_ONLY'`) happens on the object returned by `getReferencedView()` — this is intentional side-effectful configuration.
 - `format(value, 'date')` is only called for `date` type — all other types pass through raw.
 
 ## Dependencies
 
-- `createElement`, `isValidElement` from `react`
-- `PConnectComponent` from `@pega/sdk-react` — used to render each field in DISPLAY_ONLY mode
-- `format` from `../../helpers/formatters` — for date formatting
+- The project's PConnect bridge component — used to render each field in DISPLAY_ONLY mode
+- The project's formatting helper — for date formatting
+- A utility to detect rendered elements (framework equivalent of checking if a value is a component/element)
 - Each `field` in `fields[]` must support `.getPConnect()` returning a PConnect object with:
   - `.getComponentName()` → string
   - `.getConfigProps()` → `{ label: string }`
   - `.getReferencedView()` → mutable config object
-  - `.getReferencedViewPConnect()` → props object for `PConnectComponent`
+  - `.getReferencedViewPConnect()` → configuration for the PConnect bridge component
   - `.getInheritedProps()` → `{ label?: string }` (for reference type)
 
 ## Design System Mapping
 
 **UI control type:** Vertical list of read-only label/value field pairs with PConnect delegation.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                         |
-| ------------------ | ----------------------------------------------------------------------------- |
-| Default (CSS only) | CSS grid 2-column rows per field pair                                         |
-| MUI                | `<Grid container spacing={1}>` per row with `<Typography>` label and value    |
-| Ant Design         | `<Descriptions layout='horizontal' column={1}>` with PConnect-rendered values |
-| Chakra UI          | `<Grid templateColumns='1fr 1fr'>` rows with `<Text>` label/value             |
-| Shadcn/ui          | `<div class='grid grid-cols-2'>` rows                                         |
-
 When implementing in a specific design system, map the following:
 
-- Label → secondary muted text, `body2` size
-- Value → primary text, `body2` size
-- Row padding → `4px 0` vertical spacing between pairs
-- Full-width value (React element) → single column spanning full width
-- Reference type → render the child component without any label wrapper
-- Empty value → display `'---'`
+- **Grid rows** → use the DS's grid system with 2 columns (6/12 + 6/12) per label/value pair
+- **Label** → secondary/muted text, body-small size (~0.875rem), `fontWeight: 400`
+- **Value** → primary text, body-small size (~0.875rem), `fontWeight: 400`
+- **Row padding** → `4px 0` vertical spacing between pairs
+- **Full-width value (rendered element)** → single column spanning full width, no label
+- **Reference type** → render the child component without any label wrapper
+- **Empty value** → display `'---'`