@pega/sdk 0.0.2 → 0.0.4

package/templates/react-sdk-reference/.claude/skills/component-contracts.md

@@ -0,0 +1,140 @@
+# Skill: Component Contracts Reference
+
+Quick-reference lookup of all registered component names and their prop contracts. Use this when you need to know what props a specific component receives from the Pega platform.
+
+---
+
+## Field Components
+
+All extend `PConnFieldProps` from `@pega/sdk-react`.
+
+| Registry Name     | File                                | Additional Props                   |
+| ----------------- | ----------------------------------- | ---------------------------------- |
+| `TextInput`       | `field/TextInput/TextInput.tsx`     | `fieldMetadata?: any`              |
+| `TextArea`        | `field/TextArea/`                   | `fieldMetadata?: any`              |
+| `Dropdown`        | `field/Dropdown/`                   | `datasource?, listType?`           |
+| `Checkbox`        | `field/Checkbox/`                   | `value: boolean` (not string)      |
+| `RadioButtons`    | `field/RadioButtons/`               | `datasource?, listType?`           |
+| `Date`            | `field/Date/`                       | —                                  |
+| `DateTime`        | `field/DateTime/`                   | —                                  |
+| `Time`            | `field/Time/`                       | —                                  |
+| `Currency`        | `field/Currency/`                   | `currencyISOCode?, formatterType?` |
+| `Decimal`         | `field/Decimal/`                    | `decimalPrecision?`                |
+| `Integer`         | `field/Integer/`                    | —                                  |
+| `Percentage`      | `field/Percentage/`                 | —                                  |
+| `Email`           | `field/Email/Email.tsx`             | —                                  |
+| `Phone`           | `field/Phone/Phone.tsx`             | `datasource?` (country codes)      |
+| `URL`             | `field/URL/`                        | —                                  |
+| `AutoComplete`    | `field/AutoComplete/`               | `datasource?, listType?, columns?` |
+| `Multiselect`     | `field/Multiselect/Multiselect.tsx` | `datasource?, listType?`           |
+| `RichText`        | `field/RichText/`                   | —                                  |
+| `ScalarList`      | `field/ScalarList/`                 | `datasource?`                      |
+| `SelectableCard`  | `field/SelectableCard/`             | `datasource?`                      |
+| `Group`           | `field/Group/`                      | —                                  |
+| `Location`        | `field/Location/`                   | —                                  |
+| `ObjectReference` | `field/ObjectReference/`            | `value: object`                    |
+| `SemanticLink`    | `field/SemanticLink/`               | `text?, displayAs?`                |
+| `UserReference`   | `field/UserReference/`              | `showAsFormattedText?`             |
+| `CancelAlert`     | `field/CancelAlert/`                | —                                  |
+| `TextContent`     | `field/TextContent/`                | `content?`                         |
+
+---
+
+## Template Components
+
+All extend `PConnProps`. Most receive React `children` or use `getPConnect().getChildren()`.
+
+| Registry Name        | File                                   | Key Props                                |
+| -------------------- | -------------------------------------- | ---------------------------------------- |
+| `OneColumn`          | `template/OneColumn/OneColumn.tsx`     | `children`                               |
+| `OneColumnPage`      | `template/OneColumn/OneColumnPage.tsx` | `children`                               |
+| `OneColumnTab`       | `template/OneColumn/OneColumnTab.tsx`  | `children`                               |
+| `TwoColumn`          | `template/TwoColumn/TwoColumn.tsx`     | `children, templateCol?`                 |
+| `TwoColumnPage`      | `template/TwoColumn/TwoColumnPage.tsx` | `children`                               |
+| `TwoColumnTab`       | `template/TwoColumn/TwoColumnTab.tsx`  | `children`                               |
+| `NarrowWide`         | `template/NarrowWide/NarrowWide.tsx`   | `children, templateCol?`                 |
+| `WideNarrow`         | `template/WideNarrow/WideNarrow.tsx`   | `children, templateCol?`                 |
+| `Details`            | `template/Details/Details.tsx`         | `children`                               |
+| `DefaultForm`        | `template/DefaultForm/`                | PConnect children                        |
+| `DefaultPage`        | `template/DefaultPage/`                | PConnect children                        |
+| `CaseView`           | `template/CaseView/`                   | PConnect children, `header?, subheader?` |
+| `CaseSummary`        | `template/CaseSummary/`                | PConnect children                        |
+| `Confirmation`       | `template/Confirmation/`               | `label?`                                 |
+| `SimpleTable`        | `template/SimpleTable/SimpleTable.tsx` | `datasource?, fields?, label?`           |
+| `ListView`           | `template/ListView/`                   | `datasource?, fields?`                   |
+| `SubTabs`            | `template/SubTabs/`                    | PConnect children                        |
+| `AppShell`           | `template/AppShell/AppShell.tsx`       | PConnect children                        |
+| `DataReference`      | `template/DataReference/`              | PConnect children                        |
+| `ListPage`           | `template/ListPage/ListPage.tsx`       | PConnect children                        |
+| `InlineDashboard`    | `template/InlineDashboard/`            | PConnect children                        |
+| `FieldGroupTemplate` | `template/FieldGroupTemplate/`         | PConnect children                        |
+
+---
+
+## Widget Components
+
+All extend `PConnProps`. Fetch their own data.
+
+| Registry Name     | File                                 | Key Props                            |
+| ----------------- | ------------------------------------ | ------------------------------------ |
+| `Todo`            | `widget/ToDo/`                       | `datasource?, headerText?, context?` |
+| `Attachment`      | `widget/Attachment/`                 | `value, allowMultiple?, extensions?` |
+| `CaseHistory`     | `widget/CaseHistory/`                | `datasource?`                        |
+| `FileUtility`     | `widget/FileUtility/FileUtility.tsx` | `datasource?`                        |
+| `Followers`       | `widget/Followers/`                  | —                                    |
+| `AppAnnouncement` | `widget/AppAnnouncement/`            | `datasource?, headerText?`           |
+| `QuickCreate`     | `widget/QuickCreate/`                | —                                    |
+| `SummaryItem`     | `widget/SummaryItem/`                | `label?, value?, actions?`           |
+| `SummaryList`     | `widget/SummaryList/`                | `datasource?`                        |
+
+---
+
+## Design System Extension Components
+
+| Registry Name       | File                                       | Key Props                               |
+| ------------------- | ------------------------------------------ | --------------------------------------- |
+| `FieldValueList`    | `designSystemExtension/FieldValueList/`    | `name?, value?, variant?`               |
+| `AlertBanner`       | `designSystemExtension/AlertBanner/`       | `variant, heading?, messages, onClose?` |
+| `Banner`            | `designSystemExtension/Banner/`            | `variant?, text?`                       |
+| `CaseSummaryFields` | `designSystemExtension/CaseSummaryFields/` | PConnect-based                          |
+| `DetailsFields`     | `designSystemExtension/DetailsFields/`     | PConnect-based                          |
+| `FieldGroup`        | `designSystemExtension/FieldGroup/`        | PConnect-based                          |
+| `FieldGroupList`    | `designSystemExtension/FieldGroupList/`    | PConnect-based                          |
+| `Operator`          | `designSystemExtension/Operator/`          | `label?, name?, id?`                    |
+| `Pulse`             | `designSystemExtension/Pulse/`             | PConnect-based                          |
+| `RichTextEditor`    | `designSystemExtension/RichTextEditor/`    | extends `PConnFieldProps`               |
+| `WssQuickCreate`    | `designSystemExtension/WssQuickCreate/`    | —                                       |
+
+---
+
+## Infrastructure (from `sdkComponents` — do NOT replace)
+
+| Registry Name         | Source            |
+| --------------------- | ----------------- |
+| `RootContainer`       | `@pega/sdk-react` |
+| `ViewContainer`       | `@pega/sdk-react` |
+| `FlowContainer`       | `@pega/sdk-react` |
+| `Reference`           | `@pega/sdk-react` |
+| `View`                | `@pega/sdk-react` |
+| `Region`              | `@pega/sdk-react` |
+| `CaseView` (infra)    | `@pega/sdk-react` |
+| `Assignment`          | `@pega/sdk-react` |
+| `AssignmentCard`      | `@pega/sdk-react` |
+| `ActionButtons`       | `@pega/sdk-react` |
+| `CaseSummary` (infra) | `@pega/sdk-react` |
+| `ErrorBoundary`       | `@pega/sdk-react` |
+| `MultiStep`           | `@pega/sdk-react` |
+
+---
+
+## Infra (sample-local, replaceable but exercise caution)
+
+| Registry Name           | File                                           |
+| ----------------------- | ---------------------------------------------- |
+| `ActionButtons`         | `infra/ActionButtons/`                         |
+| `DeferLoad`             | `infra/DeferLoad/`                             |
+| `NavBar`                | `infra/NavBar/`                                |
+| `Stages`                | `infra/Stages/`                                |
+| `DashboardFilter`       | `infra/DashboardFilter/`                       |
+| `VerticalTabs`          | `infra/VerticalTabs/VerticalTabs.tsx`          |
+| `LeftAlignVerticalTabs` | `infra/VerticalTabs/LeftAlignVerticalTabs.tsx` |

package/templates/react-sdk-reference/.claude/skills/design-system-extension-skills/AlertBanner.md

@@ -0,0 +1,137 @@
+# Skill: AlertBanner
+
+Alert/notification banner that displays one or more messages with a severity variant and an optional dismiss button.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a visually-styled alert box tied to a Pega `variant` value (urgent, warning, success, info). When multiple messages are present, it shows a count badge in the title and lists items in a `<ul>`. A single message is rendered inline. The component optionally shows a close/dismiss button.
+
+## Pega Metadata
+
+- **Pega Name:** `AlertBanner`
+- **Registration key:** `AlertBanner` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop        | Type                                                        | Required | Description                                                   |
+| ----------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------- |
+| `id`        | `string`                                                    | Yes      | DOM id for the root wrapper element                           |
+| `variant`   | `string`                                                    | Yes      | Alert variant: `'urgent'`, `'warning'`, `'success'`, `'info'` |
+| `messages`  | `Array<string \| { label?: string; description?: string }>` | Yes      | One or more messages (string or structured object)            |
+| `onDismiss` | `function` (optional)                                       | No       | Dismiss/close handler; if provided, show a close button       |
+
+## Behavioral Contract
+
+1. **Variant mapping:** Map the Pega `variant` string to a UI severity level and display label:
+   - `'urgent'` → severity `error`, label `'Error'`
+   - `'warning'` → severity `warning`, label `'Warning'`
+   - `'success'` → severity `success`, label `'Success'`
+   - `'info'` → severity `info`, label `'Info'`
+   - Unknown/missing variant → fall back to `info`
+2. **Single message:** Render `renderMessage(messages[0])` inline (no title, no list).
+3. **Multiple messages (`messages.length > 1`):**
+   - Render a title containing the display label (e.g., "Error") plus a circular count badge showing `messages.length`.
+   - Render messages as a `<ul>` with one `<li>` per message.
+4. **`renderMessage(message)` logic:**
+   - If `message` is an object with a truthy `label`, render `<strong>{label}</strong> {description}`.
+   - If `message` is an object without a label, render `description` only.
+   - If `message` is a string with no colon (`:`), render it as plain text.
+   - If `message` is a string containing a colon, bold everything up to and including the colon, then render the rest as plain text.
+5. **Dismiss button:** Only render the close button if `onDismiss` is provided.
+6. **Root wrapper:** Wrap the alert in a `<div id={id}>`.
+
+## Visual Specifications
+
+Derived from `AlertBanner.css` and MUI Alert usage:
+
+### Alert Container
+
+| Property     | Value                                                                            |
+| ------------ | -------------------------------------------------------------------------------- |
+| Variant      | Outlined (border visible)                                                        |
+| Border color | Driven by severity (error → red, warning → orange, success → green, info → blue) |
+
+### Title Row (multiple messages only)
+
+| Property    | Value                                              |
+| ----------- | -------------------------------------------------- |
+| Font weight | 700                                                |
+| Font size   | 1rem                                               |
+| Layout      | `display: flex; align-items: center; gap: 0.25rem` |
+
+### Count Badge
+
+| Property             | Value                                                                |
+| -------------------- | -------------------------------------------------------------------- |
+| Layout               | `display: inline-flex; align-items: center; justify-content: center` |
+| Min width            | 1rem                                                                 |
+| Height               | 1rem                                                                 |
+| Padding              | `0 0.2rem`                                                           |
+| Border radius        | 999px (fully rounded / pill)                                         |
+| Font size            | 0.6rem                                                               |
+| Font weight          | 700                                                                  |
+| `urgent` background  | `var(--app-error-dark-color)`                                        |
+| `warning` background | `var(--app-warning-color-dark)`                                      |
+| `success` background | `var(--stepper-completed-bg-color)`                                  |
+| `info` background    | `var(--link-button-color)`                                           |
+| Badge text color     | `#fff` (all variants)                                                |
+
+### Message List
+
+| Property     | Value   |
+| ------------ | ------- |
+| Margin       | 0       |
+| Padding left | 1.25rem |
+
+**CSS-only implementation notes:**
+
+- Wrap the entire component in a container `<div>` with `role="alert"`.
+- Use CSS custom properties (`--app-error-dark-color`, etc.) for badge colors.
+- For the outlined alert box: `border: 1px solid currentColor; border-radius: 4px; padding: 0.75rem 1rem`.
+- Severity colors (for border and icon): error `#d32f2f`, warning `#ed6c02`, success `#2e7d32`, info `#0288d1`.
+- Badge: `display: inline-flex; align-items: center; justify-content: center; min-width: 1rem; height: 1rem; padding: 0 0.2rem; border-radius: 999px; font-size: 0.6rem; font-weight: 700; color: #fff`.
+- Left accent icon: use an SVG or Unicode symbol matching the severity (⚠, ✓, ℹ, ✕).
+- Close button (if `onDismiss`): absolutely positioned top-right, `background: none; border: none; cursor: pointer; font-size: 1.25rem`.
+- Message list: `margin: 0; padding-left: 1.25rem; list-style: disc`.
+
+## Edge Cases & Special Logic
+
+- If `variant` is not one of the four known values, default to `info` severity.
+- If `messages` is an empty array, render nothing (or render the alert shell with no content).
+- If `message.label` is falsy but `message.description` is set, render description without `<strong>`.
+- If a string message has no colon, render it entirely as plain text (no bold).
+- The colon-split only applies to the **first** colon in the string.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Alert / Notification banner with severity levels.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| Default (CSS only) | `<div role="alert">` with severity border + inline close button                         |
+| MUI                | `<Alert variant='outlined' severity={severity} onClose={onDismiss}><AlertTitle>`        |
+| Ant Design         | `<Alert type={type} message={title} description={…} closable banner />`                 |
+| Chakra UI          | `<Alert status={status}><AlertIcon /><AlertTitle /><AlertDescription /><CloseButton />` |
+| Shadcn/ui          | Custom `<Alert>` with `variant` prop                                                    |
+
+When implementing in a specific design system, map the following:
+
+- `variant='urgent'` → `severity/type/status='error'` or `'danger'`
+- `variant='warning'` → `severity/type/status='warning'`
+- `variant='success'` → `severity/type/status='success'`
+- `variant='info'` → `severity/type/status='info'`
+- `onDismiss` → `onClose` / `closable` / close button prop
+- Multiple messages → render as a list inside the alert description area
+- Badge count → render as a tag/badge chip next to the title

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

@@ -0,0 +1,152 @@
+# 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, props interface, 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 props. Column widths are controlled by the `variant` prop.
+
+## Pega Metadata
+
+- **Pega Name:** `Banner`
+- **Registration key:** `Banner` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop                     | Type        | Required | Description                                                        |
+| ------------------------ | ----------- | -------- | ------------------------------------------------------------------ |
+| `a`                      | `ReactNode` | Yes      | Content for the first (left/narrower) column                       |
+| `b`                      | `ReactNode` | Yes      | Content for the second (right/wider) column                        |
+| `banner`                 | `object`    | Yes      | Banner metadata (see sub-props 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'` |
+
+## 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
+
+```
+two-column:   [A 50%]  [B 50%]
+narrow-wide:  [A 33%]  [B 67%]
+wide-narrow:  [A 67%]  [B 33%]
+```
+
+## Visual Specifications
+
+Derived from `Banner.css`:
+
+### 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` props 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.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                     |
+| ------------------ | ------------------------------------------------------------------------- |
+| Default (CSS only) | CSS Grid for columns, CSS background for hero                             |
+| MUI                | `<Grid container size={12}>` with `<Grid size={{ xs: ... }}>` for columns |
+| Ant Design         | `<Row gutter={8}>` with `<Col span={...}>` for columns                    |
+| Chakra UI          | `<SimpleGrid columns={2}>` or `<Grid templateColumns='...'>`              |
+| Shadcn/ui          | CSS Grid with Tailwind column utilities                                   |
+
+When implementing in a specific design system, map the following:
+
+- `variant` column widths → grid column span values
+- Background image hero → `backgroundImage` inline style with `background-size: cover`
+- Column A (card-like) → design system's Card or `bg` prop with border-radius
+- Column B (plain) → plain container with horizontal padding only

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

@@ -0,0 +1,159 @@
+# 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, props interface, 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 `component-map.ts`)
+- **Does NOT use `getPConnect` directly** — receives pre-processed `theFields` array as a prop
+
+## Props
+
+| Prop         | 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 |
+
+### 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:
+
+```
+{ type: 'status', config: { value: status, label: '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`).
+
+### 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 `<Operator {...field.config} />`.
+- For all other types: render a read-only TextField 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`.
+
+### 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`.
+
+## Visual Specifications
+
+Derived from `CaseSummaryFields.css`:
+
+### 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 `fast-deep-equal/react` 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.
+- 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
+- `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 `'---'`