@pega/sdk 0.0.5 → 0.0.6

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

@@ -8,76 +8,50 @@ Page template that wraps the `Banner` DSE component, rendering a hero image sect
 
 ## Component Purpose
 
-A thin template wrapper that delegates entirely to the `Banner` DSE component. Translates page-template props (heading, message, layout, backgroundImage) into `Banner`'s props and passes the first two React children as the `a` (left) and `b` (right) content slot.
+A thin template wrapper that delegates entirely to the `Banner` DSE component. Translates page-template inputs (heading, message, layout, backgroundImage) into the Banner component's inputs and passes the first two children as the `a` (left) and `b` (right) content slot.
 
 ## Pega Metadata
 
-- **Registration key:** `BannerPage` (in `component-map.ts`)
+- **Registration key:** `BannerPage` (in the project's component map)
 - **Category:** Page template
-- **Extends:** `PConnProps`
-
-## 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`                                          |
-
-## 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 }}
-    />
-  );
-}
-```
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input             | Type                    | Required | Description                                                                                    |
+| ----------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `children`        | array of child elements | 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`                                          |
+
+## Implementation Structure
+
+Simplest template — pure pass-through to the `Banner` DSE component.
+
+**Module Setup:** This component requires access to the project's component registry (to resolve `Banner` at runtime) and the project's base component interface. Define a component input contract extending the base component interface with optional `layout`, `heading`, `message`, `imageTheme`, `backgroundImage`, `backgroundColor` (all strings), and `tintImage` (boolean).
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `Banner` from the project's component registry (keyed by `'Banner'`).
+2. Receive inputs: `children`, `layout` (default `'two-column'`), `heading` (default `''`), `message` (default `''`), `imageTheme` (default `'light'`), `backgroundImage` (default `''`), `backgroundColor` (default `''`), and `tintImage` (default `false`).
+3. Normalize `children` to an array via a memoized computation keyed on `children`.
+4. Render a single `Banner` element with: `variant={layout}`; `a={childArray[0]}`; `b={childArray[1]}`; and a `banner` input object combining `variant: imageTheme`, `backgroundColor`, `title: heading`, `message`, `backgroundImage`, and `tintImage`.
 
 ## Behavioral Contract
 
-1. Retrieve `Banner` from the component registry via `getComponentFromRegistry('Banner')`.
-2. Convert `children` to an array using `Children.toArray(children)` (memoized).
-3. Render `<Banner>` with the following props:
+1. Retrieve `Banner` from the project's component registry (keyed by `'Banner'`).
+2. Normalize `children` to an array (memoized computation).
+3. Render `Banner` with the following inputs:
    - `variant={layout}` — controls column widths below the hero
    - `a={childArray[0]}` — left/first column content
    - `b={childArray[1]}` — right/second column content
    - `banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}`
-4. No additional wrapper or layout — this component IS a single `<Banner>` render.
+4. No additional wrapper or layout — this component IS a single `Banner` render.
 
 ## Visual Specifications
 
@@ -91,35 +65,26 @@ Key visual behaviors inherited from `Banner`:
 **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.
+- The `layout` input maps directly to `Banner`'s `variant` input.
 - `heading` → `Banner.banner.title`, `message` → `Banner.banner.message`.
 
 ## Edge Cases & Special Logic
 
-- Children are memoized: `useMemo(() => Children.toArray(children), [children])` — only recomputed when `children` changes.
+- Children are normalized to an array via a memoized computation — only recomputed when `children` changes.
 - If only one child is provided, `childArray[1]` will be `undefined` — `Banner` receives `b={undefined}` and should render an empty second column.
-- `BannerPage` does NOT call `getPConnect()` itself for layout — children are React children (passed by the Pega rendering engine).
+- `BannerPage` does NOT call `getPConnect()` itself for layout — children are passed by the Pega rendering engine via content projection.
 
 ## Dependencies
 
-- `getComponentFromRegistry('Banner')` from `@pega/sdk-react` — all rendering delegated to `Banner`
-- `Children.toArray` from React — for child array normalization
+- The project's component registry — to resolve the `Banner` component at runtime
+- A utility to normalize children to an array — for child array normalization
 
 ## Design System Mapping
 
 **UI control type:** Full-width banner hero page with configurable two-column content area.
 
-Listed design systems are examples only.
-
-| 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)                              |
-
-When implementing in a specific design system:
+When implementing in a specific design system, map the following:
 
 - `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`
+- Input mapping: `layout` → `variant`, `heading` → `banner.title`, `message` → `banner.message`, `backgroundImage` → `banner.backgroundImage`
+- The Banner component renders a hero section (full-width background image with title/message overlay) plus a two-column content grid below; use your design system's layout primitives to achieve this

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

@@ -1,127 +1,75 @@
 # Skill: CaseSummary
 
-Case summary template. Renders a summary panel with primary and secondary case fields, derived from either props or child region extraction.
+Case summary template. Renders a summary panel with primary and secondary case fields, derived from either inputs 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**
+> ⚠️ **CRITICAL — Children-based field resolution 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.
+> The `arPrimaryFields` and `arSecondaryFields` inputs are almost always EMPTY at runtime. The Pega engine passes field data as region children, not as pre-computed array inputs.
 >
-> You MUST include the children-extraction block:
+> You MUST include children-based field extraction: when both `arPrimaryFields` and `arSecondaryFields` are empty, iterate the `children` and for each child, access its PConnect instance via the child element's **passed properties** (the `getPConnect` function is available on the child's properties, not directly on the child element itself). Then call `resolveConfigProps(getRawMetadata())` on that PConnect instance to resolve `@P` property references and `@L` label references into actual values. Check the resolved `name` (case-insensitive) to identify "primary fields" and "secondary fields" regions, and assign their resolved `children` arrays.
 >
-> ```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;
->     }
->   }
-> }
-> ```
+> **Key:** Access `getPConnect` from the child element's **passed properties** (NOT directly on the child). Children passed to page templates are rendered elements — `getPConnect` is available on their properties, not as a top-level method.
 >
-> Without this, the summary will render completely empty.
+> **DO NOT** use `filterSummaryFields()`, `getSDKCaseUtils()`, or any other shortcut API to obtain summary fields. These APIs return raw unresolved metadata containing `@L` and `@P` tokens that will render as literal text. Only the children-based extraction with `resolveConfigProps(getRawMetadata())` resolves these tokens into actual values.
+>
+> Without this extraction, the summary will render completely empty or show unresolved `@P`/`@L` references.
 
 ## 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.
+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 inputs or by extracting child regions. All field values are localized before display.
 
 ## Pega Metadata
 
-- **Registration key:** `CaseSummary` (in `component-map.ts`)
+- **Registration key:** `CaseSummary` (in the project's component map)
 - **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>
-  );
-}
-```
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input               | Type               | Required | Description                                             |
+| ------------------- | ------------------ | -------- | ------------------------------------------------------- |
+| `children`          | renderable content | No       | Region children when fields come from PConnect metadata |
+| `arPrimaryFields`   | `array`            | No       | Array of primary field objects (direct input)           |
+| `arSecondaryFields` | `array`            | No       | Array of secondary field objects (direct input)         |
+| `getPConnect`       | `function`         | Yes      | PConnect getter                                         |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the project's base component interface for typing. Obtain the project's component registry for resolving child components at runtime.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `CaseSummaryFields` from the project's component registry.
+2. Receive inputs: extract `children`, and `arPrimaryFields`/`arSecondaryFields` (both defaulting to empty arrays) as mutable bindings.
+3. Set up localization: `localizedVal = PCore.getLocaleUtils().getLocaleValue` and `localeCategory = 'ModalContainer'`.
+4. Define a helper `prepareComponentInCaseSummary(pConnectMeta, getPConnect)` that creates a component from metadata and returns `{ value: createdComponent }`.
+5. Define a helper `prepareCaseSummaryData(summaryFieldChildren)` that converts children into a summary data array.
+6. If both `arPrimaryFields` and `arSecondaryFields` are empty, iterate the `children`: for each child element, access its PConnect instance via the child's **passed properties** (the `getPConnect` function lives on the element's properties, not directly on the element). Call `resolveConfigProps(getRawMetadata())` on that PConnect instance — this resolves `@P` property references and `@L` label references into actual values. Check the resolved object's `name` (case-insensitive): when it equals `'primary fields'`, assign its `children` array to `arPrimaryFields` and localize each field's string `config.value`; when it equals `'secondary fields'`, assign its `children` array to `arSecondaryFields` and localize each field's string `config.value`.
+7. Render a container element with id `CaseSummary` containing two `CaseSummaryFields` instances — one with `theFields` set to `arPrimaryFields`, the other with `theFields` set to `arSecondaryFields`.
 
 ## Behavioral Contract
 
 ### Field Sourcing
 
-Two modes — prefer direct props if provided:
+Two modes — prefer direct inputs if provided:
 
-**Mode A — Direct props:**
+**Mode A — Direct inputs:**
 
 - `arPrimaryFields` and `arSecondaryFields` are passed directly.
 - Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` to localize values.
 
-**Mode B — Child extraction:**
+**Mode B — Children-based 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.
+- Iterate the `children` content-projected elements.
+- For each child, access its PConnect via the child element's **passed properties** (NOT directly on the child element).
+- Call `resolveConfigProps(getRawMetadata())` on the PConnect instance — this resolves `@P` property references and `@L` label references into actual runtime values.
+- Check the resolved `name` (case-insensitive) to identify "primary fields" and "secondary fields" regions.
+- Assign the resolved region's `children` array to the appropriate field list.
+- Localize each field's string `config.value` via `PCore.getLocaleUtils().getLocaleValue(value, localeCategory)`.
 
 ### `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)`
 
@@ -133,14 +81,14 @@ Helper that:
 
 ### Render
 
-Delegates entirely to `<CaseSummaryFields>` DSE component, passing:
+Delegates entirely to `CaseSummaryFields` (a DSE component resolved from the project's component registry), 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.
+- `CaseSummaryFields` handles all rendering — see the DSE component skill for details.
 - Primary fields: large text, no label.
 - Secondary fields: label + value pairs.
 
@@ -153,32 +101,28 @@ Delegates entirely to `<CaseSummaryFields>` DSE component, passing:
 
 ## Edge Cases & Special Logic
 
-- If both `arPrimaryFields` prop and children are present, the direct prop takes priority.
+- If both `arPrimaryFields` input and children are present, the direct input 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
+- `prepareCaseSummaryData` — local helper within this component
+- `CaseSummaryFields` — DSE component resolved from the project's 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.
+When implementing in a specific design system, map the following:
 
-| 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                    |
+- **Primary fields:** Use a prominent text element (e.g., a heading or bold typography variant) to display values without labels.
+- **Secondary fields:** Use label + value pairs in a description-list style layout (e.g., a vertical list of term/definition pairs, or a compact grid of label-value rows).
+- **Container:** A vertical stack or flexbox column with consistent spacing between field groups.
 
-When implementing in a specific design system:
+Regardless of 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