@pega/sdk 0.0.5 → 0.0.7

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

@@ -1,87 +1,44 @@
 # Skill: Template Components
 
-Create or replace template components (layouts and page structures) in the react-sdk-reference application. Template components arrange child components into visual layouts (columns, tabs, forms, pages).
+Create or replace template components (layouts and page structures) in the project. Template components arrange child components into visual layouts (columns, tabs, forms, pages).
 
 ---
 
 ## Architecture Overview
 
-```
-src/components/template/<ComponentName>/
-├── <ComponentName>.tsx      # Component implementation
-├── index.tsx                # Re-export (if present)
-├── <ComponentName>.css      # Styles (CSS file, optional)
-├── utils.ts                 # Template-specific utilities (optional)
-└── config-ext.json          # Metadata (optional)
-```
+Each template component lives under the project's template components directory in its own folder, named after the component. The folder typically contains: the component implementation file; an optional re-export module; an optional companion stylesheet; an optional utilities module for template-specific helpers; and an optional metadata file.
 
-Some templates have nested sub-templates:
-
-```
-src/components/template/TwoColumn/
-├── TwoColumn/TwoColumn.tsx
-├── TwoColumnPage/TwoColumnPage.tsx
-└── TwoColumnTab/TwoColumnTab.tsx
-```
+Some templates have nested sub-templates instead of a flat structure. For example, `TwoColumn` organizes its three variants as separate sub-folders, each containing its own implementation file.
 
 ---
 
-## Props Interface
-
-Template components extend `PConnProps`:
+## Input Contract
 
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
+Template components extend the project's **base component interface**, which declares a single required member, `getPConnect` — a function returning the `PConnect` instance for the component.
 
-interface PConnProps {
-  getPConnect: () => typeof PConnect;
-}
-```
-
-Templates typically receive children through `getPConnect().getChildren()` rather than React `children` prop, though layout templates (TwoColumn, OneColumn) receive React children directly.
+Templates typically receive children through `getPConnect().getChildren()` rather than via the framework's content projection mechanism, though layout templates (TwoColumn, OneColumn) receive children via content projection directly.
 
 ---
 
 ## Implementation Patterns
 
-### Layout Template (renders React children in grid)
+### Layout Template (renders children in grid)
 
 Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
 
-This pattern is design-system agnostic. The `// [DS GRID]` section must be replaced with your design system's grid or flex layout primitive — see the "Design System Adaptation" section below.
-
-```typescript
-import type { PropsWithChildren, ReactElement } from 'react';
-// Import your design system layout primitive here:
-// e.g. import { Grid } from 'antd';
-// e.g. import { SimpleGrid } from '@chakra-ui/react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface TwoColumnProps extends PConnProps {
-  templateCol?: string; // e.g. '1fr 1fr', '2fr 1fr'
-}
-
-export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
-  const { children, templateCol = '1fr 1fr' } = props;
-  const childrenToRender = children as ReactElement[];
-
-  // templateCol maps directly to CSS grid-template-columns — no conversion needed
-  // Use plain CSS grid with width: 100% to guarantee the layout fills its parent
-  // On mobile: use a media query or @container query to stack columns
-  return (
-    <div style={{ display: 'grid', gridTemplateColumns: templateCol, gap: '0.5rem', width: '100%' }}>
-      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
-        {childrenToRender[0]}
-      </div>
-      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
-        {childrenToRender[1]}
-      </div>
-    </div>
-  );
-}
-```
-
-> ⚠️ **Do NOT use DS-specific grid components** (e.g., Carbon `<Grid>`, Ant Design `<Row>/<Col>`) for layout templates. Many DS grids have built-in `max-width` constraints that prevent the layout from filling its parent container. Use plain CSS grid with `grid-template-columns: templateCol` — this works with every design system and guarantees full-width rendering.
+This pattern is design-system agnostic — the grid/flex section must be replaced with your design system's grid or flex layout primitive; see the "Design System Adaptation" section below.
+
+**Module Setup:** Define the input contract as an extension of the project's base component interface, adding an optional `templateCol` string (e.g. `'1fr 1fr'`, `'2fr 1fr'`) representing the CSS grid column template. The component accepts children via the framework's content projection mechanism.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `children` and `templateCol` (defaulting to `'1fr 1fr'`) from inputs; treat `children` as an array of child elements.
+2. `templateCol` maps directly to CSS `grid-template-columns` — no conversion needed.
+3. Render an outer container with `display: grid`, `gridTemplateColumns: templateCol`, a `gap`, and `width: 100%` so the layout always fills its parent.
+4. Inside, render two inner wrapper elements — one per column — each with `display: grid`, a `gap`, and `alignContent: baseline`; the first wraps `children[0]`, the second wraps `children[1]`.
+5. On mobile, use a media query or container query to stack the columns into a single column.
+
+> ⚠️ **Do NOT use DS-specific grid components** for layout templates. Many DS grids have built-in `max-width` constraints that prevent the layout from filling its parent container. Use plain CSS grid with `grid-template-columns: templateCol` — this works with every design system and guarantees full-width rendering.
 
 ---
 
@@ -89,223 +46,112 @@ export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
 
 > Form templates and page templates use the PConnect bridge pattern and do **not** use any design system primitives. This section applies only to layout templates: TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants.
 >
-> **Use plain CSS grid** (`display: grid; grid-template-columns; width: 100%`) for all layout templates. The `templateCol` prop value (e.g., `'1fr 1fr'`, `'2fr 1fr'`) maps directly to `grid-template-columns`. Do NOT use DS grid components — they may have max-width constraints.
+> **Use plain CSS grid** (`display: grid; grid-template-columns; width: 100%`) for all layout templates. The `templateCol` input value (e.g., `'1fr 1fr'`, `'2fr 1fr'`) maps directly to `grid-template-columns`. Do NOT use DS grid components — they may have max-width constraints.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>.md` contains a **Design System Mapping** section where available. Use it as a starting point.
 
-**2. If the chosen design system is not listed** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
+**2. If the chosen design system is not covered** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
 
-**3. Discover the API from installed packages** — confirm layout component names and props from `.d.ts` before writing JSX:
+**3. Discover the API from installed packages** — before writing the component's markup, confirm the layout component names and inputs by searching the installed design-system package's type declaration files for grid/column/flex primitives, then inspecting the exported input interface.
 
-```bash
-find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Grid\|Columns\|Flex" | head -5
-grep -A 30 "interface.*Props" <path-to-file>
-```
+**4. Column ratio mapping** — the `templateCol` input (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
 
-**4. Column ratio mapping** — the `templateCol` prop (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
+| `templateCol` | Fraction  | 12-col grid | CSS `grid-template-columns` |
+| ------------- | --------- | ----------- | --------------------------- |
+| `'1fr 1fr'`   | 50% / 50% | 6 / 6       | `1fr 1fr`                   |
+| `'2fr 1fr'`   | 67% / 33% | 8 / 4       | `2fr 1fr`                   |
+| `'1fr 2fr'`   | 33% / 67% | 4 / 8       | `1fr 2fr`                   |
 
-| `templateCol` | Fraction  | MUI 12-col | CSS `grid-template-columns` |
-| ------------- | --------- | ---------- | --------------------------- |
-| `'1fr 1fr'`   | 50% / 50% | 6 / 6      | `1fr 1fr`                   |
-| `'2fr 1fr'`   | 67% / 33% | 8 / 4      | `2fr 1fr`                   |
-| `'1fr 2fr'`   | 33% / 67% | 4 / 8      | `1fr 2fr`                   |
-
-**5. Responsive behavior** — on mobile, both columns must stack to full width. Use your DS's responsive breakpoint props or a CSS media query.
+**5. Responsive behavior** — on mobile, both columns must stack to full width. Use your DS's responsive breakpoint mechanism or a CSS media query.
 
 ### Form Template (renders children via PConnect bridge)
 
 Used for: DefaultForm, HierarchicalForm
 
-> ⚠️ **CRITICAL:** Form templates MUST use the `connectToState` HOC pattern. Without it, form fields will not render because they won't be subscribed to the Redux store for visibility and prop updates.
-
-```typescript
-import { createElement } from 'react';
-import { PConnectComponent } from '@pega/sdk-react';
-import connectToState from '../../helpers/state-utils';
-import { getKeyForMappedField, mapStateToProps } from './utils';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface DefaultFormProps extends PConnProps {
-  NumCols: string;
-  instructions: string;
-}
+> ⚠️ **CRITICAL:** Form templates MUST use the project's state-connection wrapper pattern. Without it, form fields will not render because they won't be subscribed to the application store for visibility and input updates.
 
-// MANDATORY: connectToState HOC wraps each field in Redux store subscription
-const Child = connectToState(mapStateToProps)((props) => {
-  const { key, visibility, ...rest } = props;
-  return createElement(PConnectComponent, { ...rest, key, visibility });
-});
+**Module Setup:** The component depends on the framework's element-creation utility, the project's PConnect bridge utility, the project's state-connection wrapper (from the project's state utilities), and `getKeyForMappedField` / `mapStateToInputs` from the companion utilities module. Define the input contract as an extension of the project's base component interface with `NumCols: string` and `instructions: string`.
 
-export default function DefaultForm(props: DefaultFormProps) {
-  const { getPConnect, NumCols = '1' } = props;
+Outside the main component logic, define a `Child` wrapper using the project's state-connection wrapper invoked with `mapStateToInputs`. This is MANDATORY — it subscribes each field to the application store. Inside `Child`, receive `key`, `visibility`, and the remaining inputs, then render the project's PConnect bridge utility with those values.
 
-  // Unwrap region children (first child is a region → get ITS children)
-  const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
+**Main Component Logic** — steps in order:
 
-  // Each child MUST be wrapped in the connectToState HOC
-  const dfChildren = arChildren?.map((kid) => (
-    <Child key={getKeyForMappedField(kid)} {...kid} />
-  ));
+1. Receive `getPConnect` and `NumCols` (defaulting to `'1'`) from inputs.
+2. Unwrap the region children: the first child returned by `getPConnect().getChildren()` is a region, so call `.getPConnect().getChildren()` on it to get the actual field children.
+3. Map each child through the `Child` wrapper defined above — every child MUST be rendered via the `Child` wrapper with `key` set to `getKeyForMappedField(kid)` and all field data spread, never directly through the PConnect bridge utility alone.
+4. Return a container element with a class name derived from `NumCols` (e.g. `form-${NumCols}-col`) containing the mapped children.
 
-  return <div className={`form-${NumCols}-col`}>{dfChildren}</div>;
-}
-```
-
-> ❌ **INCORRECT pattern** (will cause fields to not render):
->
-> ```typescript
-> // DO NOT USE — fields won't be subscribed to store
-> arChildren.map((kid, i) => createElement(PConnectComponent, { ...kid, key: i }));
-> ```
+> ❌ **INCORRECT pattern** (will cause fields to not render): mapping children directly through the PConnect bridge utility, bypassing the state-connection wrapper entirely. This causes fields to never subscribe to the application store, so they silently fail to render or update.
 
 ### Page Template (renders regions from PConnect children)
 
 Used for: CaseView, DefaultPage, ObjectPage, AppShell, Confirmation
 
-> ⚠️ **CRITICAL:** Page templates are NOT simple wrappers. They contain PCore API calls, useEffect hooks, state management, and complex prop drilling to infrastructure components. NEVER simplify a Page template to a single return statement. Always follow the component-specific skill file skeleton faithfully.
+> ⚠️ **CRITICAL:** Page templates are NOT simple wrappers. They contain PCore API calls, lifecycle effects, state management, and complex input drilling to infrastructure components. NEVER simplify a Page template to a single return statement. Always follow the component-specific skill file's Implementation Structure faithfully.
 >
-> After generating a Page template, compare your output against the skill file skeleton. Every `useState`, `useEffect`, `getComponentFromRegistry`, `PCore.*` call, helper function, and utility import from the skeleton MUST appear in your generated output. If your output is significantly shorter than the skeleton, you have over-simplified.
+> After generating a Page template, compare your output against the skill file's Implementation Structure. Every piece of state, every effect, every registry lookup, every PCore API call, helper function, and utility dependency described there MUST appear in your generated output. If your output is significantly shorter than what's described, you have over-simplified.
 >
-> ⚠️ **COMMON ERROR — `tabconfig` must be an array, NOT a React element:**
-> The `VerticalTabs` infrastructure component expects `tabconfig` to be `{ name: string; id: number }[]`. You MUST build this array by iterating the tab region's PConnect children (extracting `label` from each child's config props). NEVER pass the raw React region element to `<VerticalTabs tabconfig={...}>` — it causes `TypeError: tabconfig.map is not a function`.
-
-```typescript
-import { type PropsWithChildren, type ReactElement, useEffect, useState } from 'react';
-import { getComponentFromRegistry, PConnectComponent } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-
-export default function CaseView(props: PropsWithChildren<CaseViewProps>) {
-  // 1. Get infrastructure components from registry
-  const VerticalTabs = getComponentFromRegistry('VerticalTabs');
-  const DeferLoad = getComponentFromRegistry('DeferLoad');
-
-  // 2. Destructure ALL props from the skill file skeleton
-  const { getPConnect, children, header, ... } = props;
-  const pConn = getPConnect();
+> ⚠️ **COMMON ERROR — `tabconfig` must be an array, NOT a rendered element:**
+> The `VerticalTabs` infrastructure component expects `tabconfig` to be an array of `{ name: string; id: number }` objects. You MUST use the `extractTabsInfo` SDK utility to build this array. NEVER pass a raw rendered region element to `VerticalTabs` — it causes `TypeError: tabconfig.map is not a function`.
+>
+> ⚠️ **CRITICAL — Do NOT call `child.getPConnect()` on framework-rendered children:**
+> Children passed to page templates via the framework's content projection mechanism are **rendered elements** — they do NOT expose `getPConnect` as a direct method. Calling `child.getPConnect()` on them causes `TypeError: child.getPConnect is not a function`. For named region extraction, use `PCore.getSDKUtils().getSDKCaseUtils().getChildRegionByName(childArr, name)`. For tab info, use `PCore.getSDKUtils().getSDKCaseUtils().extractTabsInfo(tabsRegion)`. For field extraction in CaseSummary, use `PCore.getSDKUtils().getSDKCaseUtils().filterSummaryFields(getPConnect)`. If you need PConnect metadata access by index (e.g., SelfServiceCaseView), use `getPConnect().getChildren()` which returns PConnect child envs that DO have `getPConnect` methods. Render extracted regions directly in the template — do NOT pass them through the PConnect bridge component.
 
-  // 3. Include ALL state, effects, and handlers from the skill file
-  const [activeTab, setActiveTab] = useState(0);
-  useEffect(() => { /* event listeners, pub/sub */ }, []);
+**Module Setup:** The component depends on the project's component registry (to resolve infrastructure components like `VerticalTabs` and `DeferLoad`), SDK utilities from `PCore.getSDKUtils()`, local state management, and lifecycle effects. Define the input contract as an extension of the project's base component interface.
 
-  // 4. Extract named regions (NOT by index — use metadata name)
-  function getChildRegionByName(name: string) { ... }
+**Main Component Logic** — general shape for any Page template:
 
-  // 5. Render with full layout structure from skill file
-  return ( /* full layout */ );
-}
-```
+1. Look up infrastructure components from the project's component registry, e.g. `VerticalTabs` and `DeferLoad`.
+2. Receive ALL inputs described in the component-specific skill file (e.g. `getPConnect`, `children`, `header`, etc.), then call `getPConnect()` once and reuse the result.
+3. Declare ALL state, effects, and handlers described in the skill file — for example local state for active tab tracking, and lifecycle effects for event listeners or pub/sub subscriptions.
+4. Use SDK utilities from `PCore.getSDKUtils().getSDKCaseUtils()` for region extraction (e.g., `getChildRegionByName`, `extractTabsInfo`, `filterSummaryFields`). For positional child access needing metadata, use `getPConnect().getChildren()` (PConnect child envs). **NEVER implement custom region extraction that calls `child.getPConnect()` on framework-rendered children.**
+5. Render the full layout structure described in the skill file. Render extracted regions directly in the template — they are already renderable elements.
 
 ---
 
 ## Rendering Children
 
-Templates use two patterns to render child components:
+Templates use three patterns to render child components:
 
-### 1. React children (layout templates)
+### 1. Children via content projection (layout templates)
 
-```typescript
-// TwoColumn, OneColumn, etc. receive children as React props
-const { children } = props;
-const childrenToRender = children as ReactElement[];
-```
+TwoColumn, OneColumn, and similar layout templates receive children via the framework's content projection mechanism. Receive `children` from inputs and treat it as an array of child elements before indexing into it.
 
 ### 2. PConnect children (form/page templates)
 
-```typescript
-import { createElement } from 'react';
-import { PConnectComponent } from '@pega/sdk-react';
-
-// Get child PConnect objects
-const children = getPConnect().getChildren();
-
-// Render each child through the PConnect bridge
-children.map((child, i) => createElement(PConnectComponent, { ...child, key: `child-${i}` }));
-```
+Get the child PConnect objects via `getPConnect().getChildren()`, then render each one through the project's PConnect bridge utility, passing the child's configuration object and a unique key for each child.
 
 ### 3. State-connected children (REQUIRED for Form templates)
 
 > ⚠️ This is the ONLY correct pattern for Form templates (DefaultForm, HierarchicalForm). Using pattern #2 above for form fields will result in fields not rendering.
 
-```typescript
-import { createElement } from 'react';
-import { PConnectComponent } from '@pega/sdk-react';
-import connectToState from '../../helpers/state-utils';
-import { getKeyForMappedField, mapStateToProps } from './utils';
-
-// connectToState HOC subscribes to Redux store for visibility/props
-const Child = connectToState(mapStateToProps)((props) => {
-  const { key, visibility, ...rest } = props;
-  return createElement(PConnectComponent, { ...rest, key, visibility });
-});
-
-// Usage inside component:
-const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
-const dfChildren = arChildren?.map((kid) => (
-  <Child key={getKeyForMappedField(kid)} {...kid} />
-));
-```
+The component depends on the project's PConnect bridge utility, the project's state-connection wrapper (from the project's state utilities), and `getKeyForMappedField` / `mapStateToInputs` from the companion utilities module. Define a `Child` wrapper using the state-connection wrapper invoked with `mapStateToInputs` — this subscribes each field to the application store for visibility and dynamic input updates. Inside the wrapped component, receive `key`, `visibility`, and the remaining inputs, then render the PConnect bridge utility with those values.
+
+To use it: unwrap the first region's children via `getPConnect().getChildren()[0].getPConnect().getChildren()`, then map each child through the `Child` wrapper with `key` set to `getKeyForMappedField(kid)` and all field data spread.
 
 ---
 
 ## Helper Utilities
 
-### `PConnectComponent` (from `@pega/sdk-react`)
-
-The PConnect bridge component. Used to render child PConnect objects:
+### PConnect bridge utility
 
-```typescript
-import { createElement } from 'react';
-import { PConnectComponent } from '@pega/sdk-react';
-createElement(PConnectComponent, { ...childPConnectProps, key });
-```
+The project's PConnect bridge component, used to render child PConnect objects. Use the framework's element-creation mechanism to create an instance of the bridge component for each child, passing the child's PConnect configuration and a unique key.
 
-### `connectToState` (from `../../helpers/state-utils`)
+### State-connection wrapper
 
-HOC that connects a component to the Redux store for visibility and dynamic props:
+A higher-order utility that connects a component to the application store for visibility and dynamic input updates. Apply it with a state-mapping function to produce a store-connected version of the child component. Located in the project's state utilities module.
 
-```typescript
-import connectToState from '../../helpers/state-utils';
-const ConnectedChild = connectToState(mapStateToProps)(ChildComponent);
-```
+### Instructions helper
 
-### `getInstructions` (from `../../helpers/template-utils`)
-
-Extracts instruction text for forms:
-
-```typescript
-import { getInstructions } from '../../helpers/template-utils';
-const instructions = getInstructions(getPConnect(), props.instructions);
-```
+Extracts instruction text for forms. Located in the project's template utilities module. Call it with `getPConnect()` and the component's `instructions` input to obtain the resolved instruction HTML string.
 
 ---
 
 ## Registration
 
-Register templates in `src/components/component-map.ts`:
-
-```typescript
-import MyTemplate from './template/MyTemplate';
-
-// In getSampleComponentMap():
-{
-  ...sdkComponents,
-  MyTemplate,  // Key must match Pega component name
-}
-```
-
-For nested templates (e.g., TwoColumn/TwoColumnPage/TwoColumnTab), register each separately:
-
-```typescript
-import TwoColumn from './template/TwoColumn/TwoColumn/TwoColumn';
-import TwoColumnPage from './template/TwoColumn/TwoColumnPage';
-import TwoColumnTab from './template/TwoColumn/TwoColumnTab';
+Register templates in the project's component map by importing the template's default export from its folder under the template components directory and adding it to the object returned by the project's component registration function, using a key that matches the Pega component name.
 
-{
-  TwoColumn,
-  TwoColumnPage,
-  TwoColumnTab,
-}
-```
+For nested templates (e.g., TwoColumn/TwoColumnPage/TwoColumnTab), import each sub-variant from its own nested path and register all variants as separate keys in the component map.
 
 ---
 
@@ -344,9 +190,9 @@ import TwoColumnTab from './template/TwoColumn/TwoColumnTab';
 
 ## Key Conventions
 
-1. **Default export** — `export default function TemplateName`.
+1. **Default export** — Each component is exported as the module's default export.
 2. **Children from PConnect** — Use `getPConnect().getChildren()` to access child regions.
-3. **createElement pattern** — Use `createElement(createPConnectComponent(), childProps)` to render PConnect children.
-4. **CSS files** — Template-specific styles go in `<TemplateName>.css` alongside the component.
-5. **Responsive** — Use MUI Grid with `xs: 12` for mobile and `md: <size>` for desktop breakpoints.
-6. **templateCol** — Layout templates often receive a `templateCol` prop (e.g., `"1fr 1fr"`, `"2fr 1fr"`) to control column ratios.
+3. **PConnect bridge pattern** — Use the project's PConnect bridge utility to render PConnect children.
+4. **CSS files** — Template-specific styles go in a companion stylesheet alongside the component.
+5. **Responsive** — Use CSS grid with full-width on mobile and computed column widths on desktop breakpoints.
+6. **templateCol** — Layout templates often receive a `templateCol` input (e.g., `"1fr 1fr"`, `"2fr 1fr"`) to control column ratios.