@pega/sdk 0.0.1

package/templates/react-sdk-reference/.github/skills/run-and-verify.md

@@ -0,0 +1,68 @@
+# Skill: Run and Verify
+
+Build the application, run the dev server, and verify changes work correctly.
+
+---
+
+## Build Verification
+
+### If inside the pega-sdk monorepo:
+
+```bash
+# Full build (all packages + samples)
+cd /path/to/pega-sdk
+npm run build
+
+# Force rebuild sdk-react (if you modified it)
+npx nx run sdk-react:build --skip-nx-cache
+```
+
+### If standalone repo:
+
+```bash
+npm run build
+```
+
+### What to check:
+- Zero TypeScript errors
+- Zero build warnings related to missing imports
+- Output bundle is generated
+
+---
+
+## Dev Server
+
+```bash
+npm run dev
+# Opens on http://localhost:3500
+```
+
+### What to verify:
+1. App loads without console errors
+2. "Create Case" button appears after auth
+3. Clicking "Create Case" renders the form
+4. Field inputs accept keyboard input
+5. Tabbing between fields triggers blur (values persist)
+6. Validation errors appear when required fields are empty
+7. Form submission works (assignment completes)
+
+---
+
+## Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "X is not registered" console error | Component missing from `component-map.ts` | Add the import + map entry |
+| Field value doesn't persist after blur | `handleEvent` not called on blur | Add `onBlur` handler calling `handleEvent(actions, 'changeNblur', propName, value)` |
+| Read-only view shows nothing | Missing `displayMode` handling | Add the `DISPLAY_ONLY` / `STACKED_LARGE_VAL` checks |
+| TypeScript error on `getPConnect` | Wrong props interface | Extend `PConnFieldProps` or `PConnProps` from `@pega/sdk-react` |
+| Build fails on CSS import | Missing CSS loader config | Ensure Vite config handles `.css` imports |
+| "Cannot read property of undefined" on theme | Design system provider missing | Wrap app in the design system's ThemeProvider/Provider |
+
+---
+
+## Quick Lint Check
+
+```bash
+npx tsc --noEmit   # TypeScript only, no output
+```

package/templates/react-sdk-reference/.github/skills/swap-design-system.md

@@ -0,0 +1,105 @@
+# Skill: Swap Design System
+
+Replace the entire MUI design system in this application with a customer-specified design system. This is a large-scale refactor that touches all component categories.
+
+---
+
+## Prerequisites
+
+- Customer has chosen a target design system (e.g., Chakra UI, Radix/Shadcn, Ant Design, Mantine, etc.)
+- The target package is available on npm
+
+---
+
+## Procedure
+
+### Phase 1: Setup
+
+1. Install the target design system package(s)
+2. Install any required peer dependencies (e.g., emotion for Chakra, tailwind for Shadcn)
+3. Set up the design system's provider/theme in `src/MashupApp.tsx` (replace MUI's ThemeProvider)
+
+### Phase 2: Replace FieldValueList First
+
+`src/components/designSystemExtension/FieldValueList/` is used by EVERY field component for display modes. Replace this first so field replacements work immediately.
+
+Required props interface:
+
+```typescript
+interface FieldValueListProps {
+  name?: string;
+  value?: string;
+  variant?: 'stacked' | 'inline';
+}
+```
+
+### Phase 3: Replace Field Components
+
+For each field in `src/components/field/`:
+
+1. Replace MUI input with target design system equivalent
+2. Keep: `getPConnect()`, `handleEvent(actions, 'changeNblur', propName, value)` on blur
+3. Keep: `displayMode` handling (returns FieldValueList)
+4. Keep: validation display (`validatemessage` when `status === 'error'`)
+5. Keep: `data-test-id={testId}`
+
+### Phase 4: Replace Template Components
+
+For each template in `src/components/template/`:
+
+1. Replace MUI Grid/Box/Tabs with target layout primitives
+2. Keep: children rendering logic (either React children or PConnect children)
+3. Keep: `templateCol` parsing for column ratios
+
+### Phase 5: Replace Widget Components
+
+For each widget in `src/components/widget/`:
+
+1. Replace MUI Card/List/Table/Button with target equivalents
+2. Keep: ALL `PCore.*` API calls (data fetching, attachments, pub/sub)
+3. Keep: Loading and error state handling
+
+### Phase 6: Replace DSE Components
+
+For each DSE in `src/components/designSystemExtension/`:
+
+1. Replace MUI Alert/Typography/Chip with target equivalents
+2. Keep: Same prop interfaces (other components depend on these)
+
+### Phase 7: Replace Infra Components
+
+For each infra component in `src/components/infra/`:
+
+1. Replace MUI AppBar/Stepper/Tabs with target equivalents
+2. Keep: SDK integration logic
+
+### Phase 8: Clean Up
+
+1. Remove all `@mui/*` packages from `package.json`
+2. Remove MUI-specific theme configuration
+3. Run `npm run build` — fix any TypeScript errors
+4. Run `npm run dev` — verify components render
+
+---
+
+## Critical Invariants (NEVER change these)
+
+- `src/components/helpers/event-utils.ts` — event handler utility
+- `src/components/component-map.ts` structure (only change imports)
+- `...sdkComponents` spread in the component map
+- `@pega/sdk-react` imports
+- `getPConnect()` prop extraction pattern
+- `handleEvent(actions, 'changeNblur', propName, value)` calls
+- `PCore.*` API calls in widgets
+
+---
+
+## Verification
+
+After completing all phases:
+
+1. `npm run build` — must pass with zero errors
+2. `npm run dev` — app should load, create case, render form
+3. Field inputs should accept values and persist on blur
+4. Read-only views should show FieldValueList
+5. Validation messages should appear on error

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

@@ -0,0 +1,285 @@
+# 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).
+
+---
+
+## 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)
+```
+
+Some templates have nested sub-templates:
+
+```
+src/components/template/TwoColumn/
+├── TwoColumn/TwoColumn.tsx
+├── TwoColumnPage/TwoColumnPage.tsx
+└── TwoColumnTab/TwoColumnTab.tsx
+```
+
+---
+
+## Props Interface
+
+Template components extend `PConnProps`:
+
+```typescript
+import type { PConnProps } from '../../../types/PConnProps';
+
+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.
+
+---
+
+## Implementation Patterns
+
+### Layout Template (renders React children in grid)
+
+Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import Grid, { type GridSize } from '@mui/material/Grid';
+import type { PConnProps } from '../../../types/PConnProps';
+
+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[];
+
+  // Parse templateCol to calculate grid sizes
+  const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
+  const totalCols = colArray.reduce((v, itm) => itm + v, 0);
+  const ratio = 12 / totalCols;
+  const aSize = (ratio * colArray[0]) as GridSize;
+  const bSize = (ratio * colArray[1]) as GridSize;
+
+  return (
+    <Grid container spacing={1}>
+      <Grid size={{ xs: 12, md: aSize }}>{childrenToRender[0]}</Grid>
+      <Grid size={{ xs: 12, md: bSize }}>{childrenToRender[1]}</Grid>
+    </Grid>
+  );
+}
+```
+
+### Form Template (renders children via PConnect bridge)
+
+Used for: DefaultForm, HierarchicalForm
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+import connectToState from '../../helpers/state-utils';
+import type { PConnProps } from '../../../types/PConnProps';
+
+interface DefaultFormProps extends PConnProps {
+  NumCols: string;
+  instructions: string;
+}
+
+export default function DefaultForm(props: DefaultFormProps) {
+  const { getPConnect, NumCols = '1' } = props;
+
+  // Get children from the first region
+  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}` })
+  ));
+
+  return <div className={`form-${NumCols}-col`}>{dfChildren}</div>;
+}
+```
+
+### Page Template (renders regions from PConnect children)
+
+Used for: CaseView, DefaultPage, ObjectPage
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+import type { PConnProps } from '../../../types/PConnProps';
+
+interface CaseViewProps extends PConnProps {
+  header?: string;
+  subheader?: string;
+}
+
+export default function CaseView(props: CaseViewProps) {
+  const { getPConnect, 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>
+  );
+}
+```
+
+---
+
+## Rendering Children
+
+Templates use two patterns to render child components:
+
+### 1. React children (layout templates)
+
+```typescript
+// TwoColumn, OneColumn, etc. receive children as React props
+const { children } = props;
+const childrenToRender = children as ReactElement[];
+```
+
+### 2. PConnect children (form/page templates)
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+
+// 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}` }),
+);
+```
+
+### 3. State-connected children (DefaultForm pattern)
+
+```typescript
+import connectToState from '../../helpers/state-utils';
+import createPConnectComponent from '../../helpers/react_pconnect';
+
+// 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 });
+});
+```
+
+---
+
+## Helper Utilities
+
+### `createPConnectComponent` (from `../../helpers/react_pconnect`)
+
+Factory that returns the PConnect bridge component. Used to render child PConnect objects:
+
+```typescript
+import createPConnectComponent from '../../helpers/react_pconnect';
+createElement(createPConnectComponent(), childPConnectProps);
+```
+
+### `connectToState` (from `../../helpers/state-utils`)
+
+HOC that connects a component to the Redux store for visibility and dynamic props:
+
+```typescript
+import connectToState from '../../helpers/state-utils';
+const ConnectedChild = connectToState(mapStateToProps)(ChildComponent);
+```
+
+### `getInstructions` (from `../../helpers/template-utils`)
+
+Extracts instruction text for forms:
+
+```typescript
+import { getInstructions } from '../../helpers/template-utils';
+const instructions = getInstructions(getPConnect(), props.instructions);
+```
+
+---
+
+## 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';
+
+{
+  TwoColumn,
+  TwoColumnPage,
+  TwoColumnTab,
+}
+```
+
+---
+
+## Existing Template Components
+
+| Component                                       | Type       | Description                          |
+| ----------------------------------------------- | ---------- | ------------------------------------ |
+| AdvancedSearch                                  | Page       | Advanced search with filters         |
+| AppShell                                        | Page       | Top-level app layout with nav        |
+| BannerPage                                      | Page       | Page with banner section             |
+| CaseSummary                                     | Page       | Case summary header                  |
+| CaseView                                        | Page       | Main case view with regions          |
+| CaseViewActionsMenu                             | Widget     | Case action dropdown menu            |
+| Confirmation                                    | Page       | Case completion confirmation         |
+| DataReference                                   | Form       | Embedded data reference lookup       |
+| DefaultForm                                     | Form       | Standard form layout (1/2/3 columns) |
+| DefaultPage                                     | Page       | Default page structure               |
+| Details / DetailsTwoColumn / DetailsThreeColumn | Layout     | Details region layouts               |
+| FieldGroupTemplate                              | Form       | Repeating field group                |
+| HierarchicalForm                                | Form       | Multi-step hierarchical form         |
+| InlineDashboard                                 | Page       | Inline dashboard container           |
+| ListPage                                        | Page       | List/table page                      |
+| ListView                                        | Page       | Data table with filtering/sorting    |
+| MultiReferenceReadOnly                          | Display    | Read-only multi-reference display    |
+| NarrowWide / WideNarrow                         | Layout     | Asymmetric two-column layouts        |
+| ObjectPage                                      | Page       | Object detail page                   |
+| OneColumn                                       | Layout     | Single-column layout                 |
+| PromotedFilters                                 | Widget     | Filter bar for lists                 |
+| SimpleTable                                     | Table      | Editable/read-only data tables       |
+| SingleReferenceReadOnly                         | Display    | Read-only single reference           |
+| SubTabs                                         | Navigation | Tab container                        |
+| TwoColumn                                       | Layout     | Two-column layout                    |
+| WssNavBar                                       | Navigation | WSS navigation bar                   |
+
+---
+
+## Key Conventions
+
+1. **Default export** — `export default function TemplateName`.
+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.

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

@@ -0,0 +1,144 @@
+# 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 |
+
+## 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)`