@pega/sdk 0.0.3 → 0.0.5

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

@@ -1,8 +1,3 @@
----
-description: template-components
-alwaysApply: false
----
-
 # 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).
@@ -36,7 +31,7 @@ src/components/template/TwoColumn/
 Template components extend `PConnProps`:
 
 ```typescript
-import type { PConnProps } from '../../../types/PConnProps';
+import type { PConnProps } from '@pega/sdk-react';
 
 interface PConnProps {
   getPConnect: () => typeof PConnect;
@@ -70,40 +65,38 @@ export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
   const { children, templateCol = '1fr 1fr' } = props;
   const childrenToRender = children as ReactElement[];
 
-  // Parse templateCol into column width ratios
-  // Strip unit suffixes, split on whitespace, convert to numbers
-  const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
-  const totalCols = colArray.reduce((v, itm) => itm + v, 0);
-  // colArray[0] / totalCols = left column fraction
-  // colArray[1] / totalCols = right column fraction
-
-  // [DS GRID] — render two children in a responsive grid using the computed ratios
-  // On mobile (narrow viewport): both columns should stack to full width
-  // On desktop: apply the computed left/right ratio
+  // 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 (
-    <YourDesignSystemGrid>
-      <YourDesignSystemColumn ratio={colArray[0] / totalCols}>
+    <div style={{ display: 'grid', gridTemplateColumns: templateCol, gap: '0.5rem', width: '100%' }}>
+      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
         {childrenToRender[0]}
-      </YourDesignSystemColumn>
-      <YourDesignSystemColumn ratio={colArray[1] / totalCols}>
+      </div>
+      <div style={{ display: 'grid', gap: '1rem', alignContent: 'baseline' }}>
         {childrenToRender[1]}
-      </YourDesignSystemColumn>
-    </YourDesignSystemGrid>
+      </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.
+
 ---
 
 ## Design System Adaptation (Layout Templates Only)
 
 > 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.
 
-**1. Check the component-specific skill file** — `.cursor/rules/skills/template-skills/<ComponentName>.mdrules` 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** table 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).
 
 **3. Discover the API from installed packages** — confirm layout component names and props from `.d.ts` before writing JSX:
+
 ```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>
@@ -111,11 +104,11 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 **4. Column ratio mapping** — the `templateCol` prop (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
 
-| `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` |
+| `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.
 
@@ -123,59 +116,82 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 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 createPConnectComponent from '../../helpers/react_pconnect';
+import { PConnectComponent } from '@pega/sdk-react';
 import connectToState from '../../helpers/state-utils';
-import type { PConnProps } from '../../../types/PConnProps';
+import { getKeyForMappedField, mapStateToProps } from './utils';
+import type { PConnProps } from '@pega/sdk-react';
 
 interface DefaultFormProps extends PConnProps {
   NumCols: string;
   instructions: string;
 }
 
+// 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 });
+});
+
 export default function DefaultForm(props: DefaultFormProps) {
   const { getPConnect, NumCols = '1' } = props;
 
-  // Get children from the first region
+  // Unwrap region children (first child is a region → get ITS children)
   const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
 
-  // Wrap each child in a PConnect component
-  const dfChildren = arChildren?.map((kid, i) => (
-    createElement(createPConnectComponent(), { ...kid, key: `child-${i}` })
+  // Each child MUST be wrapped in the connectToState HOC
+  const dfChildren = arChildren?.map((kid) => (
+    <Child key={getKeyForMappedField(kid)} {...kid} />
   ));
 
   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 }));
+> ```
+
 ### Page Template (renders regions from PConnect children)
 
-Used for: CaseView, DefaultPage, ObjectPage
+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.
+>
+> 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.
+>
+> ⚠️ **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 { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-import type { PConnProps } from '../../../types/PConnProps';
+import { type PropsWithChildren, type ReactElement, useEffect, useState } from 'react';
+import { getComponentFromRegistry, PConnectComponent } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
 
-interface CaseViewProps extends PConnProps {
-  header?: string;
-  subheader?: string;
-}
+export default function CaseView(props: PropsWithChildren<CaseViewProps>) {
+  // 1. Get infrastructure components from registry
+  const VerticalTabs = getComponentFromRegistry('VerticalTabs');
+  const DeferLoad = getComponentFromRegistry('DeferLoad');
 
-export default function CaseView(props: CaseViewProps) {
-  const { getPConnect, header } = props;
+  // 2. Destructure ALL props from the skill file skeleton
+  const { getPConnect, children, header, ... } = props;
   const pConn = getPConnect();
-  const children = pConn.getChildren();
 
-  return (
-    <div>
-      <h2>{header}</h2>
-      {children.map((child, index) => (
-        createElement(createPConnectComponent(), { ...child, key: `region-${index}` })
-      ))}
-    </div>
-  );
+  // 3. Include ALL state, effects, and handlers from the skill file
+  const [activeTab, setActiveTab] = useState(0);
+  useEffect(() => { /* event listeners, pub/sub */ }, []);
+
+  // 4. Extract named regions (NOT by index — use metadata name)
+  function getChildRegionByName(name: string) { ... }
+
+  // 5. Render with full layout structure from skill file
+  return ( /* full layout */ );
 }
 ```
 
@@ -197,41 +213,50 @@ const childrenToRender = children as ReactElement[];
 
 ```typescript
 import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
+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(createPConnectComponent(), { ...child, key: `child-${i}` }),
-);
+children.map((child, i) => createElement(PConnectComponent, { ...child, key: `child-${i}` }));
 ```
 
-### 3. State-connected children (DefaultForm pattern)
+### 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 createPConnectComponent from '../../helpers/react_pconnect';
+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(createPConnectComponent(), { ...rest, key, visibility });
+  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} />
+));
 ```
 
 ---
 
 ## Helper Utilities
 
-### `createPConnectComponent` (from `../../helpers/react_pconnect`)
+### `PConnectComponent` (from `@pega/sdk-react`)
 
-Factory that returns the PConnect bridge component. Used to render child PConnect objects:
+The PConnect bridge component. Used to render child PConnect objects:
 
 ```typescript
-import createPConnectComponent from '../../helpers/react_pconnect';
-createElement(createPConnectComponent(), childPConnectProps);
+import { createElement } from 'react';
+import { PConnectComponent } from '@pega/sdk-react';
+createElement(PConnectComponent, { ...childPConnectProps, key });
 ```
 
 ### `connectToState` (from `../../helpers/state-utils`)

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

@@ -0,0 +1,227 @@
+# Skill: AdvancedSearch
+
+Advanced search template. Renders grouped search field sections with deduplication, delegating each section to a `SearchGroups` sub-component. Also covers the `SearchGroups` sub-component.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a multi-section advanced search form where search fields are organized into groups. Deduplicates search fields by value across groups. Each group is rendered by the `SearchGroups` sub-component. Shares search configuration via a React context (`DataReferenceAdvancedSearchContext`).
+
+## Pega Metadata
+
+- **Registration key:** `AdvancedSearch` (in `component-map.ts`)
+- **Category:** Search / Filter template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop           | Type       | Required | Description                        |
+| -------------- | ---------- | -------- | ---------------------------------- |
+| `dataPageName` | `string`   | Yes      | Data page for search results       |
+| `parameters`   | `object`   | No       | Parameters passed to the data page |
+| `getPConnect`  | `function` | Yes      | PConnect getter                    |
+
+## Component Skeleton
+
+```typescript
+import { useContext, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import DataReferenceAdvancedSearchContext from '../DataReference/DataReferenceAdvancedSearchContext';
+import { getFirstChildConfig } from '../DataReference/utils';
+
+export default function AdvancedSearch(props) {
+  const { getPConnect, targetObjectClass, localeReference } = props;
+  const SearchGroups = getComponentFromRegistry('SearchGroups');
+
+  // 1. Context — shared config from DataReference parent
+  const {
+    dataReferenceConfigToChild, isCreateNewReferenceEnabled,
+    disableStartingFieldsForReference, pyID, searchSelectCacheKey,
+  } = useContext(DataReferenceAdvancedSearchContext) as any;
+
+  // 2. Selection state check
+  const { selectionMode, value: singleSelectFieldValue, readonlyContextList: multiSelectField } =
+    dataReferenceConfigToChild;
+  const { MULTI } = PCore.getConstants().LIST_SELECTION_MODE;
+  const isSelectionExist = selectionMode === MULTI
+    ? getPConnect().getValue(multiSelectField)?.length || false
+    : getPConnect().getValue(singleSelectFieldValue) || false;
+  const [showRecords, setShowRecords] = useState(isSelectionExist);
+
+  // 3. Metadata + field deduplication
+  const pConn = getPConnect();
+  const rawViewMetadata = pConn.getRawMetadata();
+  const searchFieldsSet = new Set();
+  const searchFields: any = [];
+  rawViewMetadata.config.searchGroups.forEach((group) => {
+    group.children.forEach((child) => {
+      if (!searchFieldsSet.has(child.config.value) && !child.config.validator) {
+        searchFields.push(child);
+        searchFieldsSet.add(child.config.value);
+      }
+    });
+  });
+
+  // 4. Create editable field component from first child
+  const firstChildPConnect = getPConnect().getChildren()[0].getPConnect;
+  const [firstChildMeta] = rawViewMetadata.children;
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const cache = PCore.getNavigationUtils().getComponentCache(searchSelectCacheKey) ?? {};
+
+  const editableFieldComp = firstChildPConnect().createComponent({
+    type: firstChildMeta.type,
+    config: {
+      ...getFirstChildConfig({ firstChildMeta, getPConnect, rawViewMetadata,
+        contextClass: targetObjectClass, dataReferenceConfigToChild,
+        isCreateNewReferenceEnabled, disableStartingFieldsForReference, pyID }),
+      searchFields, showRecords,
+      label: localizedVal('Search results', 'DataReference'),
+      searchSelectCacheKey, cache,
+    },
+  });
+
+  // 5. Derive editable field path
+  const { selectionList, dataRelationshipContext } =
+    editableFieldComp.props.getPConnect().getConfigProps();
+  const editableField = selectionMode === MULTI
+    ? selectionList.substring(1) : dataRelationshipContext;
+
+  // 6. Render: SearchGroups + editableFieldComp
+  return (
+    <>
+      <SearchGroups getPConnect={getPConnect} editableField={editableField}
+        localeReference={localeReference} setShowRecords={setShowRecords}
+        searchSelectCacheKey={searchSelectCacheKey} cache={cache} />
+      {editableFieldComp}
+    </>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Search Groups from Metadata
+
+1. `rawViewMetadata = getPConnect().getRawMetadata()`.
+2. `searchGroups = rawViewMetadata.config.searchGroups` — array of group config objects.
+3. Each group has a `label` and a `fields` array.
+
+### Field Deduplication
+
+- Track seen field values in a `Set`.
+- For each field across all groups: if `field.value` already in Set, skip it.
+- Else add `field.value` to Set and include the field.
+- Deduplication is applied per-group in order — earlier groups take precedence.
+
+### Context (`DataReferenceAdvancedSearchContext`)
+
+Provides shared config to `SearchGroups`:
+
+```tsx
+<DataReferenceAdvancedSearchContext.Provider value={{ dataPageName, parameters, getPConnect }}>
+  {searchGroups.map((group) => (
+    <SearchGroups key={group.label} group={group} />
+  ))}
+</DataReferenceAdvancedSearchContext.Provider>
+```
+
+### Render Structure
+
+```
+<div className="psdk-advanced-search">
+  {searchGroups.map(group => (
+    <SearchGroups group={group} key={group.label} />
+  ))}
+</div>
+```
+
+---
+
+## Sub-Component: SearchGroups
+
+Renders a single search group section: a heading + a list of editable search fields.
+
+### Props
+
+| Prop    | Type     | Description                        |
+| ------- | -------- | ---------------------------------- |
+| `group` | `object` | `{ label: string, fields: array }` |
+
+### Behavioral Contract
+
+For each field in `group.fields`:
+
+1. Get `firstChildPConnect = getPConnect().getChildren()[0]`.
+2. Create an editable field component: `firstChildPConnect.createComponent({ type: field.type, config: { ...field.config } })`.
+3. Render the created component alongside a `<SearchGroups>` label row.
+
+### Render Structure
+
+```
+<div className="psdk-search-group">
+  <h4>{group.label}</h4>
+  {group.fields.map((field, i) => (
+    <div key={i} className="psdk-search-group-field">
+      {createdFieldComponent[i]}
+    </div>
+  ))}
+</div>
+```
+
+## Visual Specifications
+
+### AdvancedSearch Container
+
+| Element         | Description                             |
+| --------------- | --------------------------------------- |
+| Outer container | Vertical stack of search group sections |
+
+### SearchGroups Section
+
+| Element       | Description                           |
+| ------------- | ------------------------------------- |
+| Group heading | `<h4>` with group label               |
+| Field rows    | Each field rendered as a form control |
+
+**CSS-only implementation notes:**
+
+- Outer container: `display: flex; flex-direction: column; gap: 1.5rem`.
+- Group section: `display: flex; flex-direction: column; gap: 0.75rem`.
+- Group heading: `font-size: 1rem; font-weight: 600; margin-bottom: 0.25rem`.
+- Field row: `display: grid; grid-template-columns: 200px 1fr; align-items: center; gap: 0.5rem`.
+
+## Edge Cases & Special Logic
+
+- `rawViewMetadata.config.searchGroups` may be undefined if the view has no search groups — default to `[]`.
+- Field deduplication is by `field.value` (the property path), not by label.
+- `firstChildPConnect.createComponent` — must use the correct field type from `field.type`; the created component is a live PConnect view.
+- Context is required by `SearchGroups` — always wrap `SearchGroups` with the context provider.
+
+## Dependencies
+
+- `DataReferenceAdvancedSearchContext` — shared context (defined in `./context` or inline)
+- `PConnectComponent` from `@pega/sdk-react` — renders created field components
+- `getRawMetadata()` — for search group config extraction
+
+## Design System Mapping
+
+**UI control type:** Multi-section advanced search form with grouped field rows.
+
+Listed design systems are examples only.
+
+| Design System      | Group Heading                  | Field Layout                   |
+| ------------------ | ------------------------------ | ------------------------------ |
+| Default (CSS only) | `<h4>`                         | CSS grid 2-col (label + input) |
+| MUI                | `<Typography variant='h6'>`    | `<Grid container>`             |
+| Ant Design         | `<Typography.Title level={5}>` | `<Form.Item>`                  |
+| Chakra UI          | `<Heading size='sm'>`          | `<FormControl>` rows           |
+| Shadcn/ui          | `<h4>` or `<Label>`            | Tailwind grid                  |
+
+When implementing in a specific design system:
+
+- `DataReferenceAdvancedSearchContext` must be provided — `SearchGroups` consumes it via `useContext`
+- Field deduplication by `field.value` must happen before rendering
+- `createComponent` creates live editable fields — render via `createElement(PConnectComponent, fieldConfig)`