@pega/sdk 0.0.4 → 0.0.6

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

@@ -1,243 +0,0 @@
-# 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.
-
----
-
-## 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 `.github/prompts/add-component.prompt.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 `.github/prompts/generate-field-components.prompt.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 `.github/prompts/generate-template-components.prompt.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 `.github/prompts/generate-widget-components.prompt.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 `.github/prompts/generate-dse-components.prompt.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 `.github/prompts/generate-all-components.prompt.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
-> 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/.github/instructions/component-map.instructions.md

@@ -1,40 +0,0 @@
----
-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

@@ -1,77 +0,0 @@
----
-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

@@ -1,77 +0,0 @@
----
-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

@@ -1,95 +0,0 @@
----
-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

@@ -1,90 +0,0 @@
----
-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