@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,273 @@
+# Skill: AppShell
+
+Top-level application shell template. Renders the outer portal/WSS portal frame: navigation bar, alert banners, operator avatar, portal logo, and case types. Provides NavContext to child components.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> **NavBar requires `pConn` prop.** Without it, `pConn.resolveConfigProps()` throws `TypeError: Cannot read properties of undefined`. ALWAYS pass `pConn={pConn}` where `const pConn = getPConnect()`.
+>
+> This component has **mandatory side effects** (portal logo loading, case type fetching from data page, WSS vs standard portal detection). Do NOT collapse to a single-line return statement.
+>
+> **Minimum Viable Implementation must include:**
+>
+> 1. `const pConn = getPConnect()` — and pass `pConn` to NavBar
+> 2. WSS vs standard portal detection (`portalTemplate === 'wss'`)
+> 3. `NavContext.Provider` wrapping the standard portal layout
+> 4. NavBar receiving: `getPConnect`, `pConn`, `appName`, `pages`, `caseTypes`
+> 5. AlertBanner rendering messages from `httpMessages` + `pageMessages`
+>
+> **Post-Generation Checklist:**
+>
+> - [ ] `pConn` passed to NavBar
+> - [ ] `NavContext.Provider` wrapping standard portal
+> - [ ] WSS vs standard portal detection
+> - [ ] AlertBanner with combined messages
+> - [ ] Operator info from `PCore.getEnvironmentInfo()`
+
+---
+
+## Component Purpose
+
+The outermost container for the Pega SDK React app. Determines whether the app is running in WSS portal or standard portal mode, renders the appropriate navigation bar, handles HTTP and page-level alert messages, loads the portal logo asynchronously, and passes navigation links and case types to the nav bar.
+
+## Pega Metadata
+
+- **Registration key:** `AppShell` (in `component-map.ts`)
+- **Category:** Page template — application shell
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop          | Type        | Required | Description                                                  |
+| ------------- | ----------- | -------- | ------------------------------------------------------------ |
+| `pages`       | `array`     | Yes      | Array of portal page objects `{ name, pyLabel, linkUrl }`    |
+| `caseTypes`   | `array`     | No       | Fallback case types (overridden by data page fetch if empty) |
+| `portalName`  | `string`    | Yes      | Portal identifier — determines WSS vs standard rendering     |
+| `displayName` | `string`    | No       | Operator display name for avatar                             |
+| `getPConnect` | `function`  | Yes      | PConnect getter                                              |
+| `children`    | `ReactNode` | Yes      | Main content area                                            |
+
+## Component Skeleton
+
+```typescript
+import { type PropsWithChildren, useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+import { Utils } from '../../helpers/utils';
+import { NavContext } from '../../helpers/reactContextHelpers';
+import './AppShell.css';
+
+interface AppShellProps extends PConnProps {
+  showAppName: boolean;
+  pages: { pxPageViewIcon: string; pyClassName: string; pyLabel: string; pyRuleName: string; pyURLContent: string }[];
+  caseTypes?: object[];
+  portalTemplate: string;
+  portalName: string;
+  portalLogo: string;
+  navDisplayOptions: { alignment: string; position: string };
+  httpMessages: string[];
+  pageMessages: string[];
+}
+
+export default function AppShell(props: PropsWithChildren<AppShellProps>) {
+  // 1. Registry lookups
+  const NavBar = getComponentFromRegistry('NavBar');
+  const WssNavBar = getComponentFromRegistry('WssNavBar');
+  const AlertBanner = getComponentFromRegistry('AlertBanner');
+
+  // 2. Destructure props
+  const {
+    pages = [], caseTypes = [], showAppName, children = [],
+    getPConnect, httpMessages = [], pageMessages = [],
+    portalTemplate, portalName, portalLogo, navDisplayOptions,
+  } = props;
+
+  // 3. State + PConnect setup
+  const [open, setOpen] = useState(true);
+  const pConn = getPConnect();
+  const envInfo = PCore.getEnvironmentInfo();
+  const userName = envInfo.getOperatorName() || '';
+  const currentUserInitials = Utils.getInitials(userName);
+  const appNameToDisplay = showAppName ? envInfo.getApplicationLabel() : '';
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const [iconURL, setIconURL] = useState('');
+
+  // 4. Messages/banners
+  const messages = [...httpMessages, ...pageMessages];
+  const hasBanner = messages.length > 0;
+
+  // 5. useEffect: load portal logo async
+  // 6. useEffect: fetch case types from data page
+  // 7. useEffect: set pyPortalTemplate for WSS
+
+  // 8. Build nav links from pages
+  const links = pages.map(page => ({
+    text: localizedVal(page.pyLabel, '', ''),
+    onClick: () => !page.pyURLContent
+      ? pConn.getActionsApi().showPage(page.pyRuleName, page.pyClassName)
+      : window.open(page.pyURLContent, '_blank'),
+  }));
+
+  // 9. Render: WSS portal vs standard portal
+  if (portalTemplate === 'wss') {
+    return (
+      <div id="AppShell">
+        <WssNavBar portalName={portalName} imageSrc={iconURL} navLinks={links}
+          operator={{ name: userName, currentUserInitials }} navDisplayOptions={navDisplayOptions} />
+        <div>{hasBanner && <AlertBanner messages={messages} />}{children}</div>
+      </div>
+    );
+  }
+  return (
+    <NavContext.Provider value={{ open, setOpen }}>
+      <div id="AppShell" style={{ display: 'flex' }}>
+        <NavBar getPConnect={getPConnect} pConn={pConn}
+          appName={appNameToDisplay} pages={pages} caseTypes={caseTypes} />
+        <div>{hasBanner && <AlertBanner messages={messages} />}{children}</div>
+      </div>
+    </NavContext.Provider>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Portal Type Detection
+
+- Check `portalName` (or metadata flag) against WSS portal identifier.
+- WSS portal → render `<WssNavBar>` component.
+- Standard portal → render `<NavBar>` component.
+
+### Alert Banners
+
+1. Subscribe to `getPConnect()` for `httpMessages` and `pageMessages` updates.
+2. If either array is non-empty, render `<AlertBanner>` DSE component above the main content.
+3. `AlertBanner` receives the combined message array and a dismiss handler.
+
+### Portal Logo
+
+1. On mount, call `PCore.getAssetLoader().getSvcImageUrl(logoAssetName)` asynchronously.
+2. Store the resolved URL in `portalLogoUrl` state.
+3. Pass `portalLogoUrl` to the nav bar as the `logo` prop.
+
+### Operator Avatar
+
+- Read `displayName` from `getPConnect().getValue('.pyUserName')` or the `displayName` prop.
+- Render operator avatar (initials) in the nav bar via the `operatorInfo` prop.
+
+### Case Types
+
+> ⚠️ **DO NOT hardcode `'D_pyPortalTypeList'`** — this data page does not exist in most environments and will 404.
+
+The correct pattern reads the data page name dynamically from the environment:
+
+```typescript
+useEffect(() => {
+  // @ts-expect-error - environmentInfoObject may not be in typedefs
+  const caseTypesDP = PCore.getEnvironmentInfo().environmentInfoObject?.pxApplication?.pyCaseTypesAvailableToCreateDP;
+  if (caseTypesDP) {
+    const portalID = pConn.getValue('.pyOwner', '');
+    PCore.getDataPageUtils()
+      .getPageDataAsync(caseTypesDP, pConn.getContextName(), { PortalName: portalID })
+      .then((response) => {
+        if (response?.pyCaseTypesAvailableToCreate) {
+          pConn.replaceState('.pyCaseTypesAvailableToCreate', response.pyCaseTypesAvailableToCreate, {
+            skipDirtyValidation: true,
+          });
+        }
+      })
+      .catch(() => undefined);
+  }
+}, []);
+```
+
+Key points:
+
+1. Data page name comes from `environmentInfoObject.pxApplication.pyCaseTypesAvailableToCreateDP` (dynamic)
+2. Context is `pConn.getContextName()` (NOT `'root'`)
+3. Parameter `{ PortalName: portalID }` is required
+4. Result is stored via `pConn.replaceState('.pyCaseTypesAvailableToCreate', ...)` — this populates PConnect state for other consumers
+
+> ⚠️ **NavBar reads `caseTypes` from its PROP, not from PConnect state.** Do NOT shadow the `caseTypes` prop with `useState`. Pass the prop directly to NavBar:
+>
+> ```typescript
+> const { caseTypes = [] } = props;  // direct from props, NO useState
+> <NavBar caseTypes={caseTypes} />   // pass the prop through
+> ```
+>
+> If you use `useState(caseTypes)`, NavBar will receive an empty array because the React state is never updated by `replaceState`.
+
+### NavContext
+
+- Wrap children in `<NavContext.Provider value={{ open, setOpen }}>`.
+
+### Render Structure
+
+```
+<NavContext.Provider value={{ open, setOpen }}>
+  <div id="AppShell" style={{ display: 'flex' }}>
+    <NavBar caseTypes={caseTypes} ... />
+    <main style={{ flexGrow: 1, height: '100vh', overflow: 'auto', margin: '0 1rem' }}>
+      <AlertBanner (if messages) />
+      {children}
+    </main>
+  </div>
+</NavContext.Provider>
+```
+
+> ⚠️ The `<main>` element MUST have:
+>
+> - `flexGrow: 1` — fill remaining viewport width beside NavBar
+> - `height: 100vh` — full viewport height
+> - `overflow: auto` — scroll when content exceeds viewport
+> - `margin: '0 1rem'` — horizontal spacing between NavBar and content (matches reference's `theme.spacing(2)` = 16px)
+
+## Visual Specifications
+
+**CSS-only implementation notes:**
+
+- Shell wrapper: `display: flex; flex-direction: column; height: 100vh`.
+- Nav bar: `flex: 0 0 auto` (fixed height).
+- Alert banner: `flex: 0 0 auto` (shown below nav, pushes content down).
+- Content area: `flex: 1 1 auto; overflow-y: auto`.
+
+## Edge Cases & Special Logic
+
+- Logo loading is async — show fallback (app name or blank) until URL resolves.
+- Case types fetch may fail — catch errors and fall back to the `caseTypes` prop.
+- `httpMessages` are transient (from API errors) — clear them after display or on next navigation.
+- `pageMessages` are persistent until explicitly dismissed.
+- If `pages` is empty, `links` array is empty — nav bar may render without page links.
+
+## Dependencies
+
+- `NavBar` DSE component — standard portal navigation
+- `WssNavBar` template component — WSS portal navigation (see `WssNavBar.md`)
+- `AlertBanner` DSE component — message display
+- `NavContext` from `../../context/nav-context`
+- `PCore.getAssetLoader().getSvcImageUrl()` — logo URL resolution
+- `PCore.getDataPageUtils().getPageDataAsync()` — case types data page
+
+## Design System Mapping
+
+**UI control type:** Application shell layout — fixed nav + scrollable content area.
+
+Listed design systems are examples only.
+
+| Design System      | Nav Bar                  | Alert Banner         | Shell Layout                                  |
+| ------------------ | ------------------------ | -------------------- | --------------------------------------------- |
+| Default (CSS only) | `<header>` + custom nav  | `<div role='alert'>` | CSS flexbox column                            |
+| MUI                | `<AppBar>` + `<Toolbar>` | `<Alert>`            | `<Box display='flex' flexDirection='column'>` |
+| Ant Design         | `<Layout.Header>`        | `<Alert>`            | `<Layout>`                                    |
+| Chakra UI          | `<Box as='header'>`      | `<Alert>`            | `<Flex direction='column'>`                   |
+| Shadcn/ui          | Custom header            | `<Alert>`            | Tailwind `flex flex-col h-screen`             |
+
+When implementing in a specific design system:
+
+- WSS vs portal detection must remain — the nav bar component differs for each
+- Logo URL must be loaded asynchronously from `PCore.getAssetLoader()`
+- `NavContext.Provider` must wrap children so descendant nav-aware components can access links

package/templates/react-sdk-reference/{.cursor/rules/skills/template-skills/BannerPage.mdrules → .ai-common/skills/template-skills/BannerPage.md}

@@ -1,8 +1,3 @@
----
-description: Template component skill: BannerPage
-alwaysApply: false
----
-
 # Skill: BannerPage
 
 Page template that wraps the `Banner` DSE component, rendering a hero image section with a configurable two-column content area below.
@@ -23,16 +18,55 @@ A thin template wrapper that delegates entirely to the `Banner` DSE component. T
 
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | Yes | At least 2 children — `[0]` → left (`a`) slot, `[1]` → right (`b`) slot |
-| `layout` | `string` | No | Column layout variant for `Banner`: `'two-column'` (default), `'narrow-wide'`, `'wide-narrow'` |
-| `heading` | `string` | No | Hero section heading text. Default `''` |
-| `message` | `string` | No | Hero section message/subtitle. Default `''` |
-| `imageTheme` | `string` | No | Banner image theme (e.g., `'light'`). Default `'light'` |
-| `backgroundImage` | `string` | No | URL of the background image for the hero. Default `''` |
-| `backgroundColor` | `string` | No | Background color for the hero. Default `''` |
-| `tintImage` | `boolean` | No | Whether to tint the background image. Default `false` |
+| Prop              | Type          | Required | Description                                                                                    |
+| ----------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `children`        | `ReactNode[]` | Yes      | At least 2 children — `[0]` → left (`a`) slot, `[1]` → right (`b`) slot                        |
+| `layout`          | `string`      | No       | Column layout variant for `Banner`: `'two-column'` (default), `'narrow-wide'`, `'wide-narrow'` |
+| `heading`         | `string`      | No       | Hero section heading text. Default `''`                                                        |
+| `message`         | `string`      | No       | Hero section message/subtitle. Default `''`                                                    |
+| `imageTheme`      | `string`      | No       | Banner image theme (e.g., `'light'`). Default `'light'`                                        |
+| `backgroundImage` | `string`      | No       | URL of the background image for the hero. Default `''`                                         |
+| `backgroundColor` | `string`      | No       | Background color for the hero. Default `''`                                                    |
+| `tintImage`       | `boolean`     | No       | Whether to tint the background image. Default `false`                                          |
+
+## Component Skeleton
+
+Simplest template — pure pass-through to `Banner` DSE component.
+
+```typescript
+import { Children, type PropsWithChildren, useMemo } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface BannerPageProps extends PConnProps {
+  layout?: string;
+  heading?: string;
+  message?: string;
+  imageTheme?: string;
+  backgroundImage?: string;
+  backgroundColor?: string;
+  tintImage?: boolean;
+}
+
+export default function BannerPage(props: PropsWithChildren<BannerPageProps>) {
+  const Banner = getComponentFromRegistry('Banner');
+  const {
+    children, layout = 'two-column', heading = '', message = '',
+    imageTheme = 'light', backgroundImage = '', backgroundColor = '', tintImage = false,
+  } = props;
+
+  const childArray = useMemo(() => Children.toArray(children), [children]);
+
+  return (
+    <Banner
+      variant={layout}
+      a={childArray[0]}
+      b={childArray[1]}
+      banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}
+    />
+  );
+}
+```
 
 ## Behavioral Contract
 
@@ -50,10 +84,12 @@ A thin template wrapper that delegates entirely to the `Banner` DSE component. T
 This component has no independent visual output — all visual behavior is defined by the `Banner` DSE component. See [`design-system-extension-skills/Banner.md`](../design-system-extension-skills/Banner.md) for full visual specs.
 
 Key visual behaviors inherited from `Banner`:
+
 - Hero: full-width background image section, height `19rem`, centered title and message overlay
 - Content area: two-column grid below the hero, column widths driven by `variant`/`layout`
 
 **CSS-only implementation notes:**
+
 - This template creates no CSS of its own — implement it as a pure pass-through to `Banner`.
 - The `layout` prop maps directly to `Banner`'s `variant` prop.
 - `heading` → `Banner.banner.title`, `message` → `Banner.banner.message`.
@@ -75,14 +111,15 @@ Key visual behaviors inherited from `Banner`:
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
+| Design System      | Recommended Component                                                |
+| ------------------ | -------------------------------------------------------------------- |
 | Default (CSS only) | Pass-through to `Banner` — implement Banner's CSS hero + grid layout |
-| MUI | Pass-through to `Banner` (MUI-based) |
-| Ant Design | Pass-through to `Banner` (Ant-based) |
-| Chakra UI | Pass-through to `Banner` (Chakra-based) |
-| Shadcn/ui | Pass-through to `Banner` (Shadcn-based) |
+| MUI                | Pass-through to `Banner` (MUI-based)                                 |
+| Ant Design         | Pass-through to `Banner` (Ant-based)                                 |
+| Chakra UI          | Pass-through to `Banner` (Chakra-based)                              |
+| Shadcn/ui          | Pass-through to `Banner` (Shadcn-based)                              |
 
 When implementing in a specific design system:
+
 - `BannerPage` is always a thin wrapper — implement `Banner` first, then `BannerPage` simply delegates to it
 - Prop mapping: `layout` → `variant`, `heading` → `banner.title`, `message` → `banner.message`, `backgroundImage` → `banner.backgroundImage`

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

@@ -0,0 +1,185 @@
+# Skill: CaseSummary
+
+Case summary template. Renders a summary panel with primary and secondary case fields, derived from either props or child region extraction.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — Children extraction is MANDATORY**
+>
+> The `arPrimaryFields` and `arSecondaryFields` props are almost always EMPTY at runtime. The Pega engine passes field data as **React children** (regions named "primary fields" and "secondary fields"), not as pre-computed array props.
+>
+> You MUST include the children-extraction block:
+>
+> ```typescript
+> if (arPrimaryFields.length === 0 && arSecondaryFields.length === 0) {
+>   for (const child of childArr) {
+>     const childPConn = child.props.getPConnect();
+>     const childPConnData = childPConn.resolveConfigProps(childPConn.getRawMetadata());
+>     if (childPConnData.name.toLowerCase() === 'primary fields') {
+>       arPrimaryFields = childPConnData.children;
+>     } else if (childPConnData.name.toLowerCase() === 'secondary fields') {
+>       arSecondaryFields = childPConnData.children;
+>     }
+>   }
+> }
+> ```
+>
+> Without this, the summary will render completely empty.
+
+## Component Purpose
+
+Displays a case's key summary data in a structured summary panel. Primary fields are shown prominently; secondary fields are shown with labels. Data is sourced either directly from props or by extracting child regions. All field values are localized before display.
+
+## Pega Metadata
+
+- **Registration key:** `CaseSummary` (in `component-map.ts`)
+- **Category:** Page template — summary
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop                | Type          | Required | Description                                             |
+| ------------------- | ------------- | -------- | ------------------------------------------------------- |
+| `children`          | `ReactNode[]` | No       | Region children when fields come from PConnect metadata |
+| `arPrimaryFields`   | `array`       | No       | Array of primary field objects (direct prop)            |
+| `arSecondaryFields` | `array`       | No       | Array of secondary field objects (direct prop)          |
+| `getPConnect`       | `function`    | Yes      | PConnect getter                                         |
+
+## Component Skeleton
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface CaseSummaryProps extends PConnProps {
+  arPrimaryFields: any[];
+  arSecondaryFields: any[];
+}
+
+export default function CaseSummary(props: PropsWithChildren<CaseSummaryProps>) {
+  const CaseSummaryFields = getComponentFromRegistry('CaseSummaryFields');
+  const { children } = props;
+  let { arPrimaryFields = [], arSecondaryFields = [] } = props;
+
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const localeCategory = 'ModalContainer';
+
+  // 1. Helper: create component from metadata and return { value: createdComponent }
+  function prepareComponentInCaseSummary(pConnectMeta, getPConnect) { /* ... */ }
+
+  // 2. Helper: convert children to summary data array
+  function prepareCaseSummaryData(summaryFieldChildren) { /* ... */ }
+
+  // 3. If direct props empty, extract from children regions
+  if (arPrimaryFields.length === 0 && arSecondaryFields.length === 0) {
+    for (const child of children as ReactElement[]) {
+      const childPConn = (child as ReactElement).props.getPConnect();
+      const childPConnData = childPConn.resolveConfigProps(childPConn.getRawMetadata());
+      if (childPConnData.name.toLowerCase() === 'primary fields') {
+        arPrimaryFields = childPConnData.children;
+        arPrimaryFields.forEach(field => {
+          if (field.config?.value && typeof field.config?.value === 'string')
+            field.config.value = localizedVal(field.config.value, localeCategory);
+        });
+      } else if (childPConnData.name.toLowerCase() === 'secondary fields') {
+        const secondarySummaryFields = prepareCaseSummaryData(childPConn);
+        arSecondaryFields = childPConnData.children;
+        arSecondaryFields.forEach((field, index) => {
+          field.config.displayLabel = secondarySummaryFields[index]?.value?.props?.label;
+        });
+      }
+    }
+  }
+
+  // 4. Render
+  return (
+    <div id="CaseSummary">
+      <CaseSummaryFields theFields={arPrimaryFields} />
+      <CaseSummaryFields theFields={arSecondaryFields} />
+    </div>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Field Sourcing
+
+Two modes — prefer direct props if provided:
+
+**Mode A — Direct props:**
+
+- `arPrimaryFields` and `arSecondaryFields` are passed directly.
+- Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` to localize values.
+
+**Mode B — Child extraction:**
+
+- Extract primary and secondary regions from `children` by type/name matching.
+- Primary region: first region child (or `type === 'Region' && name === 'Primary'`).
+- Secondary region: second region child (or `type === 'Region' && name === 'Secondary'`).
+- Build field arrays from the extracted region children metadata.
+- Then call `prepareCaseSummaryData(...)` as in Mode A.
+
+### `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)`
+
+Helper that:
+
+1. Iterates each field in both arrays.
+2. Localizes the field value via `PCore.getLocaleUtils().getLocaleValue(value, classID, value)`.
+3. Returns `{ arPrimaryFields: localizedPrimary, arSecondaryFields: localizedSecondary }`.
+
+### Render
+
+Delegates entirely to `<CaseSummaryFields>` DSE component, passing:
+
+- `arPrimaryFields` — array of `{ name, value }` objects for primary display
+- `arSecondaryFields` — array of `{ name, value, displayLabel }` objects for secondary display
+
+## Visual Specifications
+
+- `<CaseSummaryFields>` handles all rendering — see the DSE component skill for details.
+- Primary fields: large text, no label.
+- Secondary fields: label + value pairs.
+
+**CSS-only implementation notes (for `CaseSummaryFields` wrapper):**
+
+- Container: `display: flex; flex-direction: column; gap: 8px`.
+- Primary field value: `font-size: 1rem; font-weight: 600`.
+- Secondary field row: `display: flex; gap: 4px; font-size: 0.875rem`.
+- Secondary label: `color: var(--secondary-text-color)`.
+
+## Edge Cases & Special Logic
+
+- If both `arPrimaryFields` prop and children are present, the direct prop takes priority.
+- `prepareCaseSummaryData` — guard against undefined/null field values before passing to `getLocaleValue`.
+- `displayLabel` on secondary fields controls whether the field label is shown alongside the value.
+- If `arSecondaryFields` is empty, the secondary section is not rendered.
+
+## Dependencies
+
+- `prepareCaseSummaryData` from `./utils` (local helper)
+- `CaseSummaryFields` — DSE component registered in the component registry
+- `PCore.getLocaleUtils().getLocaleValue()` — value localization
+
+## Design System Mapping
+
+**UI control type:** Read-only case summary panel with primary and secondary field groups.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Approach                               |
+| ------------------ | -------------------------------------------------- |
+| Default (CSS only) | Flexbox column with CSS-styled field rows          |
+| MUI                | `<Typography>` variants for primary/secondary text |
+| Ant Design         | `<Descriptions>` with `bordered={false}`           |
+| Chakra UI          | `<VStack>` with `<Text>` variants                  |
+| Shadcn/ui          | Custom `<dl>/<dt>/<dd>` or card                    |
+
+When implementing in a specific design system:
+
+- Always localize field values before display — use `PCore.getLocaleUtils().getLocaleValue()`
+- `CaseSummaryFields` is a DSE component — implement it separately and call it from here
+- Primary fields have no labels; secondary fields have labels