@pega/sdk 0.0.1

package/templates/react-sdk-reference/.github/copilot-instructions.md

@@ -0,0 +1,185 @@
+# Copilot Instructions — React SDK Reference
+
+You are assisting developers in a React reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (MUI, Chakra, Radix, Shadcn, Ant Design, or any other).
+
+---
+
+## 1. Repository Purpose
+
+This is a **reference implementation** — not a framework. The UI components (fields, templates, widgets) are intentionally simple MUI-based implementations meant to be swapped out. The SDK wiring (bootstrap, PConnect bridge, component registry) is reusable infrastructure that should NOT be modified.
+
+---
+
+## 2. What Is Replaceable vs. Infrastructure
+
+### Replaceable (customer modifies these)
+
+| Directory                               | Purpose                                                     |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `src/components/field/`                 | Form field components (TextInput, Dropdown, Date, etc.)     |
+| `src/components/template/`              | Layout templates (OneColumn, TwoColumn, Details, etc.)      |
+| `src/components/widget/`                | Data widgets (ToDo, Attachment, CaseHistory, etc.)          |
+| `src/components/designSystemExtension/` | Extended UI (AlertBanner, FieldGroup, RichTextEditor, etc.) |
+
+### Infrastructure (do NOT modify unless you know what you're doing)
+
+| File/Directory                          | Purpose                                                   |
+| --------------------------------------- | --------------------------------------------------------- |
+| `src/MashupApp.tsx`                     | Auth + bootstrap + root rendering                         |
+| `src/components/component-map.ts`       | Registry wiring (only add/remove entries)                 |
+| `src/components/infra/`                 | Infrastructure components (ActionButtons, Stages, NavBar) |
+| `src/components/helpers/event-utils.ts` | PConnect event handler utility                            |
+| `@pega/sdk-react`                       | SDK bridge — never modify                                 |
+
+---
+
+## 3. Component Architecture
+
+### The PConnect Bridge
+
+Every component receives `getPConnect` as a prop. This is the bridge to the Pega platform:
+
+```typescript
+const pConn = getPConnect();
+const actions = pConn.getActionsApi(); // For field updates
+const propName = (pConn.getStateProps() as any).value; // Property path
+```
+
+### Event Handling Pattern
+
+All field components use this pattern for two-way binding:
+
+```typescript
+import handleEvent from '../../helpers/event-utils';
+
+// On change (local state only):
+function handleChange(event) {
+  setInputValue(event.target.value);
+}
+
+// On blur (push to platform):
+function handleBlur() {
+  handleEvent(actions, 'changeNblur', propName, inputValue);
+}
+```
+
+### Display Mode Handling
+
+Field components must handle `displayMode` prop:
+
+- `undefined` → render editable input
+- `'DISPLAY_ONLY'` → render read-only value via `FieldValueList`
+- `'STACKED_LARGE_VAL'` → render stacked read-only via `FieldValueList` with `variant='stacked'`
+
+### Component Registry
+
+Components are registered by name in `src/components/component-map.ts`:
+
+```typescript
+import { sdkComponents } from '@pega/sdk-react';
+
+function getSampleComponentMap() {
+  return {
+    ...sdkComponents, // Infrastructure (View, Region, FlowContainer, etc.)
+    TextInput, // Your field components
+    Dropdown,
+    // ...
+  };
+}
+```
+
+To add a new component: add the import + add to the map object.
+To replace a component: change the import to point to your new implementation.
+
+---
+
+## 4. Props Interfaces
+
+### Field Components (`PConnFieldProps`)
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface PConnFieldProps {
+  getPConnect: () => typeof PConnect;
+  label: string;
+  required: boolean;
+  disabled: boolean;
+  value?: string;
+  validatemessage: string;
+  status?: string; // 'error' | 'warning' | undefined
+  onChange: any;
+  onBlur?: any;
+  readOnly: boolean;
+  testId: string;
+  helperText: string;
+  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL'
+  hideLabel: boolean;
+  placeholder?: string;
+}
+```
+
+### Template/Widget Components (`PConnProps`)
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect;
+}
+```
+
+---
+
+## 5. Rules for Replacing Components
+
+1. **Keep the same default export name** — the component-map references it.
+2. **Keep `getPConnect` wiring intact** — extract props, call `handleEvent` on blur.
+3. **Handle `displayMode`** — return `FieldValueList` for read-only modes.
+4. **Handle validation** — show `validatemessage` when `status === 'error'`.
+5. **Preserve `data-test-id`** — pass `testId` to the root interactive element.
+6. **Use `getComponentFromRegistry`** to render sub-components (e.g., `FieldValueList`) — don't hardcode imports for components that might also be replaced.
+
+---
+
+## 6. Build & Dev Commands
+
+```bash
+# From monorepo root (if developing locally with source packages):
+npm run build              # Build all packages + samples
+npm run dev:react          # Build + dev server
+
+# From this directory (standalone):
+npm run dev                # Vite dev server (port 3500)
+npm run build              # Production build
+```
+
+---
+
+## 7. Key Imports
+
+```typescript
+// From SDK (never modify these)
+import {
+  PConnectComponent,
+  PegaStoreContext,
+  registerComponentCreator,
+  getComponentFromRegistry,
+  sdkComponents,
+} from '@pega/sdk-react';
+import type { PConnProps, PConnFieldProps } from '@pega/sdk-react';
+
+// Event utility (preserve this)
+import handleEvent from '../../helpers/event-utils';
+```
+
+---
+
+## 8. Do NOT
+
+- Modify `MashupApp.tsx` bootstrap flow when replacing design system components.
+- Import from `@pega/sdk-react/src/...` — use the package entry point only.
+- Hardcode component references — use `getComponentFromRegistry('Name')` for components that may be overridden.
+- Remove the `...sdkComponents` spread from `component-map.ts`.
+- Use `any` without justification — prefer `unknown` and narrow.
+- Add `@ts-ignore` — use `@ts-expect-error` with explanation if truly needed.

package/templates/react-sdk-reference/.github/instructions/component-map.instructions.md

@@ -0,0 +1,40 @@
+---
+applyTo: "**/component-map.ts"
+---
+
+# Component Map Rules
+
+The component map (`src/components/component-map.ts`) is the registry that maps Pega component names to React implementations.
+
+## Structure
+
+```typescript
+import { sdkComponents } from '@pega/sdk-react';
+
+function getSampleComponentMap() {
+  return {
+    ...sdkComponents,   // NEVER remove this — provides infrastructure
+    // Your components below:
+    TextInput,
+    Dropdown,
+    // ...
+  };
+}
+```
+
+## Rules
+
+1. **NEVER remove `...sdkComponents`** — it provides View, Region, Reference, RootContainer, FlowContainer, ViewContainer, Assignment, AssignmentCard, ErrorBoundary, MultiStep, CaseSummary, and their aliases.
+
+2. **Map keys must match Pega component names exactly** — these are resolved at runtime by the platform. The key is what Pega sends; the value is your React component.
+
+3. **To replace a component**: change its import path to your new implementation. Do NOT rename the key.
+
+4. **To add a new component**: add the import + add a new key-value entry.
+
+5. **Key naming exceptions** (where key differs from variable name):
+   - `Date: DateField` (Date is reserved in JS)
+   - `URL: URLComponent` (URL is a global)
+   - `Todo: ToDo` (casing difference)
+
+6. **Keep the `registerSampleComponents` function** — it registers all entries into the `ComponentRegistry` instance used by the PConnect bridge.

package/templates/react-sdk-reference/.github/instructions/dse-component.instructions.md

@@ -0,0 +1,77 @@
+---
+applyTo: "src/components/designSystemExtension/**/*.tsx"
+---
+
+# Design System Extension Component Rules
+
+When creating or modifying DSE components, follow these rules:
+
+## What Are DSE Components?
+
+Design System Extension components are display-focused presentational components. They sit between pure UI and data-fetching widgets. Some receive `getPConnect`, others receive only display props.
+
+## Patterns
+
+### Pattern A: With PConnect (data-aware display)
+
+Used for: FieldValueList, CaseSummaryFields, DetailsFields
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface FieldValueListProps extends PConnProps {
+  name?: string;
+  value?: string;
+  variant?: 'stacked' | 'inline';
+}
+
+export default function FieldValueList(props: FieldValueListProps) {
+  const { name, value, variant = 'inline' } = props;
+  // Render a label-value pair
+}
+```
+
+### Pattern B: Without PConnect (pure presentation)
+
+Used for: AlertBanner, Banner, Operator
+
+```typescript
+interface AlertBannerProps {
+  variant: 'urgent' | 'warning' | 'info' | 'success';
+  heading?: string;
+  messages: Array<string | { label?: string; description?: string }>;
+  onClose?: () => void;
+}
+
+export default function AlertBanner(props: AlertBannerProps) {
+  // Render an alert/notification banner
+}
+```
+
+### Pattern C: Rich editor (extends PConnFieldProps)
+
+Used for: RichTextEditor
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface RichTextEditorProps extends PConnFieldProps {
+  content?: string;
+}
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- DSE components are the **most commonly referenced by other components** via `getComponentFromRegistry('FieldValueList')` — every field uses FieldValueList for display modes
+- Keep the same export name (default export) and prop interface shape
+- If you replace FieldValueList, ensure it accepts `name`, `value`, and optional `variant` props
+- AlertBanner must handle the `messages` array format (both strings and `{label, description}` objects)
+- Do NOT drop visual styles when removing `makeStyles` — always map them to an equivalent

package/templates/react-sdk-reference/.github/instructions/field-component.instructions.md

@@ -0,0 +1,73 @@
+---
+applyTo: "src/components/field/**/*.tsx"
+---
+
+# Field Component Rules
+
+When creating or modifying field components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnFieldProps } from '@pega/sdk-react';
+   ```
+
+2. **Define a props interface extending `PConnFieldProps`**:
+   ```typescript
+   interface MyFieldProps extends PConnFieldProps {
+     // additional props specific to this field
+   }
+   ```
+
+3. **Export as default function component**:
+   ```typescript
+   export default function MyField(props: MyFieldProps) { ... }
+   ```
+
+## Required Behaviors
+
+1. **Extract standard props**: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
+
+2. **Get PConnect APIs**:
+   ```typescript
+   const pConn = getPConnect();
+   const actions = pConn.getActionsApi();
+   const propName = (pConn.getStateProps() as any).value;
+   ```
+
+3. **Handle displayMode** (MUST be before the main return):
+   ```typescript
+   if (displayMode === 'DISPLAY_ONLY') {
+     return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+   }
+   if (displayMode === 'STACKED_LARGE_VAL') {
+     return <FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />;
+   }
+   ```
+
+4. **Use local state + blur pattern**:
+   - `onChange` → update local state only
+   - `onBlur` → call `handleEvent(actions, 'changeNblur', propName, localValue)`
+
+5. **Show validation**: Display `validatemessage` and apply error styling when `status === 'error'`
+
+6. **Pass test ID**: Set `data-test-id={testId}` on the interactive element
+
+7. **Use `getComponentFromRegistry('FieldValueList')`** — never hardcode FieldValueList import
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, {{designSystem}} component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Do NOT
+
+- Skip `displayMode` handling — it breaks read-only views
+- Call `handleEvent` on every keystroke — only on blur
+- Hardcode component imports for components that exist in the registry
+- Remove the `handleEvent` import from `../../helpers/event-utils`
+- Drop visual styles when removing `makeStyles` — always map them to an equivalent

package/templates/react-sdk-reference/.github/instructions/template-component.instructions.md

@@ -0,0 +1,94 @@
+---
+applyTo: "src/components/template/**/*.tsx"
+---
+
+# Template Component Rules
+
+When creating or modifying template/layout components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnProps } from '@pega/sdk-react';
+   ```
+
+2. **Export as default function component**:
+   ```typescript
+   export default function MyTemplate(props: MyTemplateProps) { ... }
+   ```
+
+## Template Categories
+
+### Layout Templates (TwoColumn, OneColumn, NarrowWide, WideNarrow)
+
+Receive React `children` directly:
+
+```typescript
+import type { PropsWithChildren, ReactElement } from '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[];
+  // Render childrenToRender[0], childrenToRender[1], etc. in grid columns
+}
+```
+
+### Form/View Templates (DefaultForm, Details, CaseView)
+
+Render children via `getPConnect().getChildren()`:
+
+```typescript
+export default function DefaultForm(props: DefaultFormProps) {
+  const { getPConnect } = props;
+  const pConn = getPConnect();
+  const children = pConn.getChildren() as any[];
+
+  return (
+    <div>
+      {children.map((child, i) => (
+        <PConnectComponent key={i} getPConnect={() => child.getPConnect()} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Page Templates (OneColumnPage, TwoColumnPage)
+
+Wrap a layout with page-level chrome (title, actions):
+
+```typescript
+export default function OneColumnPage(props: PageProps) {
+  const { getPConnect, children } = props;
+  const pConn = getPConnect();
+  const title = pConn.getDataObject('')?.caseInfo?.name;
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      {children}
+    </div>
+  );
+}
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's layout props, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Use `PConnectComponent` from `@pega/sdk-react` to render PConnect children
+- Grid proportions come from `templateCol` prop — parse it to calculate column ratios
+- Templates must not call `handleEvent` or interact with field state
+- Templates are layout-only — they arrange, not edit
+- Do NOT drop column gap, padding, or alignment styles when removing MUI `Grid` — replicate them in the replacement layout

package/templates/react-sdk-reference/.github/instructions/widget-component.instructions.md

@@ -0,0 +1,89 @@
+---
+applyTo: "src/components/widget/**/*.tsx"
+---
+
+# Widget Component Rules
+
+When creating or modifying widget components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnProps } from '@pega/sdk-react';
+   // or PConnFieldProps if the widget behaves like a field (e.g., Attachment)
+   ```
+
+2. **Export as default function component**:
+   ```typescript
+   export default function MyWidget(props: MyWidgetProps) { ... }
+   ```
+
+## Widget Patterns
+
+### Data-Fetching Widget (ToDo, CaseHistory, Followers)
+
+Fetches data from Pega data pages on mount:
+
+```typescript
+export default function MyWidget(props: MyWidgetProps) {
+  const { getPConnect, datasource, headerText } = props;
+  const pConn = getPConnect();
+  const [data, setData] = useState<any[]>([]);
+
+  useEffect(() => {
+    const context = pConn.getContextName();
+    PCore.getDataPageUtils()
+      .getDataAsync(datasource?.source, context, {})
+      .then((response: any) => {
+        setData(response.data || []);
+      });
+  }, []);
+
+  return (
+    <Card>
+      <CardHeader title={headerText} />
+      <CardContent>{/* render data */}</CardContent>
+    </Card>
+  );
+}
+```
+
+### Action Widget (ToDo)
+
+Triggers case actions:
+
+```typescript
+// Get assignments and trigger actions
+import { getToDoAssignments } from '@pega/sdk-react';
+
+const assignments = getToDoAssignments(getPConnect);
+// Each assignment has: onClick callback, urgency, name, etc.
+```
+
+### File Widget (Attachment, FileUtility)
+
+Handles file upload/download via PCore attachment APIs:
+
+```typescript
+PCore.getAttachmentUtils().uploadAttachment(file, onUploadProgress, errorHandler, context);
+PCore.getAttachmentUtils().downloadAttachment(attachmentId, context);
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Widgets are self-contained — they manage their own data fetching
+- Use `PCore.getDataPageUtils()` for data page access
+- Use `PCore.getAttachmentUtils()` for file operations
+- Always handle loading and error states
+- Widgets may use `PCore.getPubSubUtils()` to subscribe to events
+- Clean up subscriptions in `useEffect` return function
+- Do NOT drop card padding, list item spacing, or avatar sizing when removing MUI components — replicate them in the replacement

package/templates/react-sdk-reference/.github/prompts/add-component.prompt.md

@@ -0,0 +1,21 @@
+---
+agent: agent
+description: Add a new component type to the registry
+---
+
+Add a new component called `{{componentName}}` of type **{{componentType}}** (field | template | widget | designSystemExtension).
+
+## Steps:
+
+1. Create the component directory: `src/components/{{componentType}}/{{componentName}}/`
+2. Create `{{componentName}}.tsx` with the appropriate pattern:
+   - **field**: Extend `PConnFieldProps`, use `handleEvent`, handle `displayMode`
+   - **template**: Extend `PConnProps`, render children via grid/layout
+   - **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
+   - **designSystemExtension**: Pure display props or extend `PConnProps`
+3. Create `index.tsx` with: `export { default } from './{{componentName}}';`
+4. Register in `src/components/component-map.ts`:
+   - Add import at top
+   - Add entry in the appropriate section of `getSampleComponentMap()`
+
+Ensure the build passes after adding the component.