@pega/sdk 0.0.2 → 0.0.4

package/templates/react-sdk-reference/AGENTS.md

@@ -1,59 +1,246 @@
-# Agents
+# AGENTS — React SDK Reference
 
-AI assistant guide for React SDK Reference application.
+> Claude Code instructions for the Pega React SDK reference application.
+> Skill files and workflow prompts are in `.claude/skills/` and `.claude/prompts/`. Read them when asked to generate or replace components.
 
-For complete rules, see [`.github/copilot-instructions.md`](.github/copilot-instructions.md).
+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).
 
 ---
 
-## Purpose
+## 1. Repository Purpose
 
-This is a **reference app** for Pega Infinity SDK. Customers clone it and replace the MUI-based sample components with their own design system. The SDK wiring (`@pega/sdk-react`, bootstrap, PConnect bridge) is infrastructure — only the UI layer is meant to be customized.
+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.
 
 ---
 
-## Replaceable Component Directories
+## 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
 ```
-src/components/
-├── field/                  ← Form inputs (TextInput, Dropdown, Date, etc.)
-├── template/               ← Layouts (OneColumn, TwoColumn, Details, etc.)
-├── widget/                 ← Data widgets (ToDo, Attachment, CaseHistory, etc.)
-└── designSystemExtension/  ← Extended UI (AlertBanner, FieldGroup, etc.)
+
+### 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);
+}
 ```
 
-## Do Not Modify
+### 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;
+}
 ```
-src/MashupApp.tsx            ← Bootstrap/auth flow
-src/components/component-map.ts  ← Only add/remove entries, don't restructure
-src/components/infra/        ← SDK infrastructure
-src/components/helpers/      ← Shared utilities (event-utils, formatters)
+
+### Template/Widget Components (`PConnProps`)
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect;
+}
 ```
 
 ---
 
-## Quick Commands
+## 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
-npm run dev       # Vite dev server (port 3500)
-npm run build     # Production build
+# 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';
 ```
 
 ---
 
-## Key Pattern
+## 8. Do NOT
 
-Every replaceable component receives `getPConnect()` prop → extracts field state → renders UI → calls `handleEvent(actions, 'changeNblur', propName, value)` on blur to push changes back to Pega.
+- 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.
 
 ---
 
-## Reference
+## 9. Component Generation Workflow — Single Component
+
+When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
+read the full contents of `.claude/prompts/add-component.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> For generating **multiple field components** at once, see Section 10.
+
+---
+
+## 10. Batch Field Component Generation
+
+When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
+read the full contents of `.claude/prompts/generate-field-components.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 11. Batch Template Component Generation
+
+When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
+read the full contents of `.claude/prompts/generate-template-components.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 12. Batch Widget Component Generation
+
+When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
+read the full contents of `.claude/prompts/generate-widget-components.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 13. Batch Design System Extension Component Generation
+
+When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
+read the full contents of `.claude/prompts/generate-dse-components.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 14. Generate All Components (Multi-Type)
+
+When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
+read the full contents of `.claude/prompts/generate-all-components.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
 
-| Topic | File |
-|-------|------|
-| Full instructions | `.github/copilot-instructions.md` |
-| Field component skill | `.github/skills/field-components.md` |
-| Template component skill | `.github/skills/template-components.md` |
-| Widget component skill | `.github/skills/widget-components.md` |
-| DSE component skill | `.github/skills/design-system-extension.md` |
+> Use this section when the request spans more than one component type. For a single type, use Sections 10–13.

package/templates/react-sdk-reference/index.html

@@ -27,10 +27,7 @@
   </head>
   <body>
     <div id="outlet" style="width: 100%"></div>
-    <script
-      src="node_modules/@pega/constellationjs/dist/constellation-core-web.js"
-      type="text/javascript"
-    ></script>
+    <script src="node_modules/@pega/constellationjs/dist/constellation-core-web.js" type="text/javascript"></script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

package/templates/react-sdk-reference/package.json

@@ -11,43 +11,43 @@
   "dependencies": {
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.1",
-    "@mui/icons-material": "^9.0.0",
-    "@mui/lab": "^9.0.0-beta.3",
-    "@mui/material": "^9.0.0",
+    "@mui/icons-material": "^9.2.0",
+    "@mui/lab": "^9.0.0-beta.6",
+    "@mui/material": "^9.2.0",
     "@mui/styles": "^6.5.0",
-    "@mui/x-date-pickers": "^9.2.0",
+    "@mui/x-date-pickers": "^9.9.0",
     "@pega/auth": "file:pega-auth-0.2.42.tgz",
-    "@pega/constellationjs": "file:pega-constellationjs-0.26.2.tgz",
+    "@pega/constellationjs": "file:pega-constellationjs-0.26.3-local.tgz",
     "@pega/sdk-react": "file:pega-sdk-react-0.1.0.tgz",
     "@pega/sdk-types": "file:pega-sdk-types-0.1.0.tgz",
     "@react-google-maps/api": "^2.20.8",
     "@tinymce/tinymce-react": "^6.3.0",
     "clsx": "^2.1.1",
-    "dayjs": "^1.11.20",
+    "dayjs": "^1.11.21",
     "downloadjs": "^1.4.7",
     "fast-deep-equal": "^3.1.3",
     "lodash.clonedeep": "^4.5.0",
     "mui-tel-input": "^11.0.0",
-    "react": "^18.3.1",
+    "react": "^19.2.7",
     "react-datepicker": "^9.1.0",
-    "react-dom": "^18.3.1",
+    "react-dom": "^19.2.7",
     "react-number-format": "^5.4.5",
     "react-redux": "^9.3.0",
-    "react-router-dom": "^7.6.1",
+    "react-router-dom": "^7.18.1",
     "throttle-debounce": "^5.0.2"
   },
   "devDependencies": {
     "@pega/pcore-pconnect-typedefs": "^4.1.0",
     "@types/downloadjs": "^1.4.6",
     "@types/lodash.clonedeep": "^4.5.9",
-    "@types/react": "^18.3.18",
-    "@types/react-datepicker": "^6.2.0",
-    "@types/react-dom": "^18.3.5",
+    "@types/react": "^19.2.17",
+    "@types/react-datepicker": "^7.0.0",
+    "@types/react-dom": "^19.2.3",
     "@types/react-redux": "^7.1.34",
     "@types/throttle-debounce": "^5.0.2",
-    "@vitejs/plugin-react": "^4.3.4",
-    "typescript": "~5.8.2",
-    "vite": "^6.3.5",
-    "vite-plugin-static-copy": "^2.3.0"
+    "@vitejs/plugin-react": "^6.0.3",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.4",
+    "vite-plugin-static-copy": "^4.1.1"
   }
 }

package/templates/react-sdk-reference/sdk-config.json

@@ -3,7 +3,7 @@
     "infinityRestServerUrl": "https://lab-16027-us-east-1.internal.pegalabs.io/prweb",
     "appAlias": "MediaCo",
     "sdkContentServerUrl": "",
-    "appPortal": "MediaCoSelfService",
+    "appPortal": "",
     "appMashupCaseType": "DIXL-MediaCo-Work-NewService",
     "excludePortals": [
       "pxExpress",

package/templates/react-sdk-reference/src/AppSelector.tsx

@@ -5,12 +5,12 @@ import { PortalApp } from './PortalApp';
 function AppSelector() {
   return (
     <Routes>
-      <Route path='/portal' element={<PortalApp />} />
-      <Route path='/portal.html' element={<PortalApp />} />
-      <Route path='/embedded' element={<MashupApp />} />
-      <Route path='/embedded.html' element={<MashupApp />} />
-      <Route path='/' element={<MashupApp />} />
-      <Route path='*' element={<MashupApp />} />
+      <Route path="/portal" element={<PortalApp />} />
+      <Route path="/portal.html" element={<PortalApp />} />
+      <Route path="/embedded" element={<MashupApp />} />
+      <Route path="/embedded.html" element={<MashupApp />} />
+      <Route path="/" element={<MashupApp />} />
+      <Route path="*" element={<MashupApp />} />
     </Routes>
   );
 }

package/templates/react-sdk-reference/src/FallbackComponent.tsx

@@ -18,9 +18,7 @@ function FallbackComponent({
   const displayProps = Object.fromEntries(
     Object.entries(props).filter(
       ([k]) =>
-        !['getPConnect', 'pConnect', 'fallback', 'componentRegistry'].includes(
-          k,
-        ) && typeof props[k] !== 'function',
+        !['getPConnect', 'pConnect', 'fallback', 'componentRegistry'].includes(k) && typeof props[k] !== 'function',
     ),
   );
 
@@ -28,9 +26,7 @@ function FallbackComponent({
     <div style={styles.fallback.container}>
       <div style={styles.fallback.label}>{componentName ?? 'Unknown'}</div>
       {Object.keys(displayProps).length > 0 && (
-        <pre style={styles.fallback.props}>
-          {JSON.stringify(displayProps, null, 2)}
-        </pre>
+        <pre style={styles.fallback.props}>{JSON.stringify(displayProps, null, 2)}</pre>
       )}
       {children && <div style={styles.fallback.children}>{children}</div>}
     </div>