@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,176 @@
+# Skill: Banner
+
+Promotional/informational banner with a full-width background image hero section and a two-column content layout below it.
+
+> **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 visually rich banner composed of two parts:
+
+1. **Hero section:** Full-width area with a background image, centered title and message text overlaid.
+2. **Content columns:** Two adjustable-width columns below the hero, rendered from the `a` and `b` slot inputs. Column widths are controlled by the `variant` input.
+
+## Pega Metadata
+
+- **Pega Name:** `Banner`
+- **Registration key:** `Banner` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name                     | Type               | Required | Description                                                        |
+| ------------------------ | ------------------ | -------- | ------------------------------------------------------------------ |
+| `a`                      | renderable content | Yes      | Content for the first (left/narrower) column                       |
+| `b`                      | renderable content | Yes      | Content for the second (right/wider) column                        |
+| `banner`                 | `object`           | Yes      | Banner metadata (see sub-fields below)                             |
+| `banner.title`           | `string`           | Yes      | Title text displayed in the hero section                           |
+| `banner.message`         | `string`           | Yes      | Descriptive message text in the hero section                       |
+| `banner.backgroundImage` | `string`           | Yes      | URL of the background image for the hero section                   |
+| `banner.variant`         | `any`              | No       | Unused internally (layout variant comes from top-level `variant`)  |
+| `banner.backgroundColor` | `any`              | No       | Unused internally                                                  |
+| `banner.tintImage`       | `any`              | No       | Unused internally                                                  |
+| `variant`                | `string`           | Yes      | Column layout: `'two-column'`, `'narrow-wide'`, or `'wide-narrow'` |
+
+## Implementation Structure
+
+### Module Setup
+
+The component requires companion styles (for hero section and layout styling) that should be co-located with the component following the project's styling convention. It does NOT import any Pega SDK modules — all data arrives via direct inputs.
+
+The component is named `Banner` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Variant Map (module-level or function-level constant)
+
+Define a lookup object that maps the `variant` string to a pair of column width values (out of 12):
+
+| Variant       | Column A (first) | Column B (second) |
+| ------------- | ---------------- | ----------------- |
+| `two-column`  | 6                | 6                 |
+| `narrow-wide` | 4                | 8                 |
+| `wide-narrow` | 8                | 4                 |
+
+### Component Logic
+
+The component receives `a`, `b`, `banner` (defaults to `{}`), and `variant` as inputs. From `banner`, extract `title`, `message`, and `backgroundImage`. The render tree is:
+
+1. **Outer wrapper** — a `<div>` with `marginBottom: 2rem`.
+2. **Hero section:**
+   - A `<div>` with class `background-image-style` and inline style `backgroundImage: url({backgroundImage})`.
+   - Inside: an overlay `<div>` with classes `background-style content`.
+   - Inside the overlay: `<h1>` with class `title` containing the title text, and `<p>` with class `message` containing the message text.
+3. **Content columns** — below the hero, a 12-column grid container with `spacing={1}` containing two grid items:
+   - **Column A** (first child slot): grid item sized to the first value from the variant map. Styled with `padding: 1rem; background-color: var(--app-form-bg-color); border-radius: 16px; height: fit-content`. Renders `{a}`.
+   - **Column B** (second child slot): grid item sized to the second value from the variant map. Styled with `padding: 0 1rem` (no background). Renders `{b}`.
+
+## Behavioral Contract
+
+1. **Hero section:** Render a `<div>` with class `background-image-style` and the inline style `backgroundImage: url(${backgroundImage})`.
+2. Inside the hero, render an overlay `<div>` with classes `background-style content`.
+3. Inside the overlay, render `<h1 className='title'>{title}</h1>` and `<p className='message'>{message}</p>`.
+4. **Column layout:** Below the hero, render a 12-column grid container with two columns:
+   - Column `a`: sized according to the variant (left/first column).
+   - Column `b`: sized according to the variant (right/second column).
+5. **Variant column widths:**
+   - `'two-column'`: column A = 6/12, column B = 6/12 (equal split).
+   - `'narrow-wide'`: column A = 4/12, column B = 8/12.
+   - `'wide-narrow'`: column A = 8/12, column B = 4/12.
+6. **Column A styles:** `padding: 1rem; background-color: var(--app-form-bg-color); border-radius: 16px; height: fit-content`.
+7. **Column B styles:** `padding: 0rem 1rem` (no background).
+8. **Outer wrapper:** `<div style={{ marginBottom: '2rem' }}>`.
+
+## Layout Variants
+
+| Variant       | Column A | Column B |
+| ------------- | -------- | -------- |
+| `two-column`  | 50% (6)  | 50% (6)  |
+| `narrow-wide` | 33% (4)  | 67% (8)  |
+| `wide-narrow` | 67% (8)  | 33% (4)  |
+
+## Visual Specifications
+
+Derived from the component's companion styles:
+
+### Hero Section
+
+| Property            | Value                            |
+| ------------------- | -------------------------------- |
+| Margin left         | -16px (bleeds to container edge) |
+| Margin right        | -16px                            |
+| Height              | `calc(19rem)`                    |
+| Background size     | cover                            |
+| Background position | center center                    |
+
+### Hero Overlay
+
+| Property         | Value                      |
+| ---------------- | -------------------------- |
+| Background color | transparent                |
+| Color            | `var(--banner-text-color)` |
+| Width            | 100%                       |
+| Height           | 100%                       |
+| Text align       | center                     |
+| Display          | flex                       |
+| Flex direction   | column                     |
+| Justify content  | center                     |
+| Align items      | center                     |
+| Gap              | `calc(0.5rem)`             |
+
+### Hero Title
+
+| Property    | Value    |
+| ----------- | -------- |
+| Margin      | 0        |
+| Font size   | 1.728rem |
+| Font weight | 600      |
+
+### Hero Message
+
+| Property    | Value |
+| ----------- | ----- |
+| Margin      | 0     |
+| Font size   | 1rem  |
+| Font weight | 400   |
+
+### Content Grid
+
+| Property       | Value                  |
+| -------------- | ---------------------- |
+| Padding        | 1rem                   |
+| Column spacing | 1 spacing unit (≈ 8px) |
+
+**CSS-only implementation notes:**
+
+- Hero: `margin: 0 -16px; height: 19rem; background-size: cover; background-position: center; position: relative`.
+- Overlay: `position: absolute; inset: 0; display: flex; flex-direction: column; justify-content: center; align-items: center; gap: 0.5rem; color: var(--banner-text-color); text-align: center`.
+- Content grid below hero: `display: grid; grid-template-columns: <a-cols>fr <b-cols>fr; gap: 8px; padding: 1rem`.
+- Column A: `padding: 1rem; background-color: var(--app-form-bg-color); border-radius: 16px; height: fit-content`.
+- Column B: `padding: 0 1rem`.
+- For responsive behavior, collapse to single column on small viewports.
+
+## Edge Cases & Special Logic
+
+- If `backgroundImage` is an empty string or undefined, the hero section renders without a background image (transparent/color background).
+- If `variant` is not one of the three known values, implement a safe default (e.g., `'two-column'`).
+- The `banner.backgroundColor`, `banner.variant`, and `banner.tintImage` inputs are received but not rendered in the reference implementation.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Full-width banner hero with responsive two-column content area.
+
+When implementing in a specific design system, map the following:
+
+- **Column layout** → use the DS's grid/column system to create two responsive columns. Map the variant column ratios (6/6, 4/8, 8/4 out of 12) to the DS's grid column sizing convention (span values, fractional units, or percentage widths).
+- **Background image hero** → use inline `backgroundImage` style with `background-size: cover; background-position: center`. No DS component is needed for this — it's always a styled `<div>`.
+- **Column A (card-like)** → use the DS's card component or a container with background color and border-radius (if available). Otherwise use a plain `<div>` with the specified styles.
+- **Column B (plain)** → a plain container with horizontal padding only (no background).
+- **Responsive** → on small viewports (mobile), collapse the two columns to a single stacked column.

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

@@ -0,0 +1,180 @@
+# Skill: CaseSummaryFields
+
+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, input contracts, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a responsive 2-column read-only grid of field values for a case summary header area. Each field in the input array is typed (e.g., `textinput`, `date`, `currency`, `caseoperator`), and the component selects the appropriate display renderer per type. Visibility and a special status field injection are also handled.
+
+## Pega Metadata
+
+- **Pega Name:** `CaseSummaryFields`
+- **Registration key:** `CaseSummaryFields` (in the project's component map)
+- **Does NOT use `getPConnect` directly** — receives pre-processed `theFields` array as an input
+
+## Component Inputs
+
+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 |
+
+## 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`)
+
+| Property          | Type                 | Description                               |
+| ----------------- | -------------------- | ----------------------------------------- |
+| `label`           | `string`             | Field label                               |
+| `value`           | `any`                | Field value                               |
+| `visibility`      | `boolean` (optional) | If `false`, the field is hidden           |
+| `caption`         | `string` (optional)  | Alternative label for checkbox fields     |
+| `trueLabel`       | `string` (optional)  | Display text when checkbox value is true  |
+| `falseLabel`      | `string` (optional)  | Display text when checkbox value is false |
+| `currencyISOCode` | `string` (optional)  | ISO currency code for currency fields     |
+
+## Behavioral Contract
+
+### 1. Status Field Injection
+
+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 a deep-equality utility).
+- When `theFieldsToRender` changes, recompute `theFieldsAsGridItems` (via a lifecycle effect).
+
+### 3. Field Visibility
+
+Skip any field where `config.visibility` exists and is `false`.
+
+### 4. Type-Based Rendering (`getFieldValue(field)`)
+
+When `field.config.value` is `null` or `''` (empty):
+
+- 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 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 a grid cell (6 of 12 columns — 2-column layout) inside a grid container with class `psdk-case-summary-fields`.
+
+## Visual Specifications
+
+Derived from the component's companion styles:
+
+### Status Field
+
+| Property       | Value                            |
+| -------------- | -------------------------------- |
+| Display        | inline-block                     |
+| Font size      | 0.75rem                          |
+| Font weight    | bold                             |
+| Line height    | `calc(0.5rem * 2.5)` (≈ 1.25rem) |
+| Height         | `calc(0.5rem * 2.5)` (≈ 1.25rem) |
+| Text transform | uppercase                        |
+
+### Summary Grid Container
+
+| Property | Value                       |
+| -------- | --------------------------- |
+| Padding  | `calc(2 * 0.5rem)` (≈ 1rem) |
+| Row gap  | `calc(2 * 0.5rem)` (≈ 1rem) |
+
+**CSS-only implementation notes:**
+
+- Summary grid: `display: grid; grid-template-columns: 1fr 1fr; padding: 1rem; row-gap: 1rem`.
+- Each field cell: standard read-only text display with label above value.
+- Status text: `font-size: 0.75rem; font-weight: bold; text-transform: uppercase; line-height: 1.25rem`.
+- Phone/email links: `text-decoration: none; color: inherit` on the `<a>` wrapper; use `cursor: pointer` on the inner input.
+- Read-only field pair: label in secondary text color (`font-weight: 400; color: var(--text-secondary); font-size: 0.75rem`), value in primary text color below.
+
+## Edge Cases & Special Logic
+
+- 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 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
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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

@@ -0,0 +1,180 @@
+# 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 the PConnect bridge component in DISPLAY_ONLY mode.
+
+> **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 the PConnect bridge component.
+
+Supports three item layouts:
+
+- **Reference type:** Renders the value directly (no label/value grid wrapper).
+- **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 the project's component map)
+- **Does NOT use `getPConnect` on the component itself** — iterates `fields[]` each of which has `.getPConnect()`
+
+## Component Inputs
+
+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 |
+
+## 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
+
+### 1. Field Iteration and PConnect Setup
+
+For each field in `fields`:
+
+1. Call `field.getPConnect()` to get `thePConn`.
+2. Get `theCompType = thePConn.getComponentName().toLowerCase()`.
+3. Get `label = thePConn.getConfigProps().label`.
+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 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          |
+| 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:** 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
+
+- For `date` type: call `format(value, 'date')` before display.
+- For all others: use value as-is.
+- If formatted value is `undefined` or `''`, display `'---'` instead.
+
+### 5. Rendered element detection
+
+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 the component's companion styles:
+
+### Label
+
+| 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       | primary text color (e.g. `theme.palette.text.primary` or `var(--text-primary)`) |
+| Typography  | body-small (≈ 0.875rem / 14px)                                                  |
+
+### Row Padding
+
+| Property  | Value              |
+| --------- | ------------------ |
+| Row style | `padding: 4px 0px` |
+
+**CSS-only implementation notes:**
+
+- 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 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.
+- 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
+
+- 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()` → 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.
+
+When implementing in a specific design system, map the following:
+
+- **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 `'---'`