@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/widget-skills/QuickCreate.mdrules

@@ -0,0 +1,119 @@
+---
+description: Widget component skill: QuickCreate
+alwaysApply: false
+---
+
+# Skill: QuickCreate
+
+Quick case creation widget. Renders a set of buttons — one per available case type — allowing users to create cases directly from the widget without navigating to a separate form.
+
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, props interface, data-fetching patterns, and registration conventions common to ALL widget components.
+
+---
+
+## Component Purpose
+
+Provides a shortcut panel for creating new cases. Case types are sourced from the Pega environment info (or a fallback portal config for Launchpad). The list can be filtered by class name. Each button triggers case creation via `pConn.getActionsApi().createWork()`. Rendering is delegated to the `WssQuickCreate` design system extension component.
+
+## Pega Metadata
+
+- **Registration key:** `QuickCreate` (in `component-map.ts`)
+- **Category:** Widget — action / case creation
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `heading` | `string` | Yes | Widget title (e.g., `"Create"`) |
+| `showCaseIcons` | `boolean` | No | Whether to show case type icons alongside labels. Default `false` |
+| `classFilter` | `any[]` | No | Array of class names to filter available case types. Empty array = show all |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Case Types Resolution
+
+1. Read `PCore.getEnvironmentInfo().environmentInfoObject.pyCaseTypeList` — the primary source.
+2. If the list is empty or unavailable (e.g., Launchpad mode), fall back to the app portal config:
+   ```
+   PCore.getConfig().getApplicationName()  // or portal config equivalent
+   ```
+3. Apply `classFilter`: if `classFilter` is non-empty, retain only case types whose class name is included in the array.
+
+### Case Type Object Mapping
+
+For each case type, build:
+```typescript
+{
+  classname: caseType.pyClassName,
+  label: caseType.pyLabel,
+  onClick: () => pConn.getActionsApi().createWork(caseType.pyClassName, {
+    openCaseViewAfterCreate: true,
+    containerName: PCore.getConstants().APP.APP
+  }),
+  icon: showCaseIcons ? getIconURL(caseType.pyClassName) : undefined
+}
+```
+
+### Rendering Delegation
+
+Pass the mapped case type array to `WssQuickCreate` (retrieved via `getComponentFromRegistry('WssQuickCreate')`):
+```tsx
+const WssQuickCreate = getComponentFromRegistry('WssQuickCreate');
+return <WssQuickCreate heading={heading} caseTypes={caseTypeObjects} />;
+```
+
+This component handles all button rendering — `QuickCreate` is purely a data-preparation orchestrator.
+
+## Visual Specifications
+
+Visual rendering is owned by `WssQuickCreate` (a design system extension component). Typical layout:
+
+| Element | Description |
+|---------|-------------|
+| Heading | Widget title at the top |
+| Case type buttons | One button per case type; icon (optional) + label |
+
+**CSS-only implementation notes (if implementing without `WssQuickCreate`):**
+- Container: `display: flex; flex-direction: column; gap: 0.5rem`.
+- Heading: `font-weight: 600; margin-bottom: 0.5rem`.
+- Case type button: `display: flex; align-items: center; gap: 0.5rem; padding: 8px 12px; border: 1px solid var(--border-color); border-radius: 4px; cursor: pointer; background: white`.
+- Icon: `width: 20px; height: 20px; object-fit: contain`.
+
+## Edge Cases & Special Logic
+
+- `classFilter` is an empty array by default — empty array means **no filtering** (show all case types).
+- If `pyCaseTypeList` is empty and the fallback also produces no results, render the widget with a `"No case types available"` message or hide the widget.
+- `showCaseIcons` requires a valid icon URL — `getIconURL(classname)` returns `undefined` if no icon is configured; guard against rendering a broken `<img>`.
+- `createWork` opens the case creation form in the primary container. If the user already has an unsaved case open, behavior depends on container configuration (may replace or open in a new tab).
+
+## Dependencies
+
+- `getComponentFromRegistry('WssQuickCreate')` — design system extension for case type button rendering
+- `pConn.getActionsApi().createWork()` — triggers case creation
+- `PCore.getEnvironmentInfo()` — primary source for available case types
+- `PCore.getConstants().APP.APP` — app context constant
+
+## Design System Mapping
+
+**UI control type:** Quick-action panel with one button per available case type.
+
+Listed design systems are examples only.
+
+Rendering is delegated to `WssQuickCreate` — implement that DSE component for your design system. `QuickCreate` itself has no direct UI output beyond the delegation.
+
+If implementing without `WssQuickCreate`:
+
+| Design System | Button List |
+|---|---|
+| Default (CSS only) | `<button>` list with optional `<img>` icon |
+| MUI | `<List>` + `<ListItemButton>` or `<Button>` stack |
+| Ant Design | `<Space direction='vertical'>` + `<Button>` per case type |
+| Chakra UI | `<VStack>` + `<Button>` per case type |
+| Shadcn/ui | `<div>` stack + `<Button variant='outline'>` |
+
+When implementing in a specific design system:
+- `classFilter` empty array = show ALL case types (not zero) — this is a common gotcha
+- `createWork` must be called with the correct `containerName` constant (`APP.APP`)
+- `showCaseIcons` is optional — only fetch/render icons when this prop is `true`

package/templates/react-sdk-reference/.cursor/rules/skills/widget-skills/SummaryItem.mdrules

@@ -0,0 +1,172 @@
+---
+description: Widget component skill: SummaryItem
+alwaysApply: false
+---
+
+# Skill: SummaryItem
+
+Individual item card for displaying an attachment, file, or link with an icon, name, metadata, and an actions menu. Also covers `SummaryList` — the container that renders multiple `SummaryItem` cards.
+
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, props interface, data-fetching patterns, and registration conventions common to ALL widget components.
+
+---
+
+## Component Purpose
+
+`SummaryItem` renders a single row/card for an attachment or link item. It shows a file-type icon, the item name (as a link for URLs or plain text for files), secondary metadata text, and an action menu. Used by `FileUtility` via the `SummaryList` container.
+
+`SummaryList` is a thin wrapper that maps an array of item objects to individual `SummaryItem` cards, passing down menu icon overrides for all items.
+
+## Pega Metadata
+
+- **Registration keys:**
+  - `SummaryItem` — the individual item card
+  - `SummaryList` — the container/list component
+- **Category:** Widget — display / composition
+- **Extends:** `PConnProps`
+
+---
+
+## SummaryItem
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `arItems$` | `object` | Yes | A single item object (see Item Structure below) |
+| `menuIconOverride$` | `string` | No | If provided, replaces the standard actions menu with a single direct-action icon button |
+| `menuIconOverrideAction$` | `function` | No | Callback invoked when the override icon button is clicked |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+### Item Structure (`arItems$`)
+
+```typescript
+{
+  id: string;
+  visual: {
+    icon: string;        // Icon identifier or URL
+    progress?: number;   // Upload progress 0–100 (optional)
+  };
+  primary: {
+    type: 'FILE' | 'URL';
+    name: string;        // Display name of the item
+    icon: string;        // Icon for the primary element
+    click: () => void;   // Download (FILE) or open in new tab (URL)
+  };
+  secondary: {
+    text: string;        // Metadata text (e.g., "John Smith · 01/15/2025")
+    error?: boolean;     // If true, render text in error/red color
+  };
+  actions: Array<{
+    id: string;
+    text: string;        // Menu item label
+    icon: string;        // Menu item icon identifier
+    onClick: () => void; // Action callback
+  }>;
+}
+```
+
+### Behavioral Contract
+
+1. **Visual area:** Render `visual.icon` (file type icon). If `visual.progress` is defined and between 0–99, overlay a progress indicator.
+2. **Primary element:**
+   - `type === 'FILE'`: render `primary.name` as plain text (clicking calls `primary.click` which triggers download).
+   - `type === 'URL'`: render `primary.name` as a link button that calls `primary.click` (opens URL in new tab).
+3. **Secondary text:** Render `secondary.text` below the primary element. If `secondary.error === true`, render in error/red color.
+4. **Actions:**
+   - **Standard mode (no `menuIconOverride$`):** Render a `<MoreVertIcon>` icon button. On click, open a `<Menu>` with one `<MenuItem>` per `actions` entry.
+   - **Override mode (`menuIconOverride$` provided):** Render a single direct-action icon button using `menuIconOverride$` as the icon. On click, call `menuIconOverrideAction$()`. No menu rendered.
+
+## Visual Specifications
+
+### Item Layout
+
+```
+[File Icon]  [Name (link if URL)]
+             [Secondary metadata text]
+                                    [Actions button (⋮ or override)]
+```
+
+| Element | Description |
+|---------|-------------|
+| File icon | Left side, fixed size (~36px square) |
+| Name | Bold, truncated with ellipsis if too long |
+| Metadata | Smaller, secondary-color text |
+| Actions button | Right side, `<MoreVertIcon>` or override icon |
+
+**CSS-only implementation notes:**
+- Row: `display: flex; align-items: center; gap: 0.75rem; padding: 8px 0`.
+- File icon: `width: 36px; height: 36px; flex-shrink: 0`.
+- Content area: `flex: 1; min-width: 0` (prevents text overflow).
+- Name: `font-size: 0.875rem; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap`.
+- Metadata: `font-size: 0.75rem; color: var(--secondary-text-color)`.
+- Error metadata: `color: var(--error-color)`.
+- Actions button: `flex-shrink: 0; margin-left: auto`.
+- URL name: `color: var(--link-color); cursor: pointer; text-decoration: underline`.
+
+## Edge Cases & Special Logic
+
+- `visual.progress` — show a progress indicator only when `0 <= progress < 100`. When `progress === 100` (complete) or `progress === undefined`, show only the file icon.
+- `secondary.error === true` — the metadata text (e.g., upload error message) must be red, not the normal secondary color.
+- `menuIconOverride$` replaces the menu entirely — do not render `<MoreVertIcon>` when an override is provided.
+- `actions` may be empty — if empty and no override provided, do not render the actions button at all.
+
+---
+
+## SummaryList
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `arItems$` | `any[]` | Yes | Array of item objects (same shape as `SummaryItem`'s `arItems$`) |
+| `menuIconOverride$` | `string` | No | Passed to every `SummaryItem` |
+| `menuIconOverrideAction$` | `any` | No | Passed to every `SummaryItem` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+### Behavioral Contract
+
+```tsx
+const SummaryItemComp = getComponentFromRegistry('SummaryItem');
+
+return (
+  <div>
+    {arItems$.map((item, i) => (
+      <SummaryItemComp
+        key={item.id || i}
+        arItems$={item}
+        menuIconOverride$={menuIconOverride$}
+        menuIconOverrideAction$={menuIconOverrideAction$}
+        getPConnect={getPConnect}
+      />
+    ))}
+  </div>
+);
+```
+
+No state, no data fetching — purely a mapping wrapper.
+
+## Dependencies
+
+- **SummaryItem:** MUI `<IconButton>`, `<Menu>`, `<MenuItem>`, MUI Icons `<MoreVertIcon>`, utils helper for icon path resolution
+- **SummaryList:** `getComponentFromRegistry('SummaryItem')` — resolves the item component dynamically
+
+## Design System Mapping
+
+**UI control type:** File/link item row with icon, name, metadata, and action menu.
+
+Listed design systems are examples only.
+
+| Design System | Row Layout | Action Menu |
+|---|---|---|
+| Default (CSS only) | `<div>` flexbox row | `<button>` + custom dropdown |
+| MUI | `<ListItem>` or `<Box display='flex'>` | `<IconButton>` + `<Menu>/<MenuItem>` |
+| Ant Design | `<List.Item>` | `<Dropdown menu={{ items }}>` |
+| Chakra UI | `<HStack>` | `<Menu>/<MenuButton>/<MenuList>` |
+| Shadcn/ui | `<div>` flexbox | `<DropdownMenu>` |
+
+When implementing in a specific design system:
+- `menuIconOverride$` completely replaces the standard `⋮` menu — check for it before rendering the actions area
+- `type === 'URL'` must render the name as a clickable link (not plain text)
+- `secondary.error` is a boolean — apply error styling to the `secondary.text` when `true`
+- `SummaryList` is purely compositional — no logic beyond mapping items to `SummaryItem`

package/templates/react-sdk-reference/.cursor/rules/skills/widget-skills/ToDo.mdrules

@@ -0,0 +1,195 @@
+---
+description: Widget component skill: ToDo
+alwaysApply: false
+---
+
+# Skill: ToDo
+
+Assignment worklist widget. Displays the current user's pending assignments with expand/collapse, click-to-open, priority indicators, badge counts, responsive layout, and snackbar error notifications.
+
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, props interface, data-fetching patterns, and registration conventions common to ALL widget components.
+
+---
+
+## Component Purpose
+
+Renders a compact to-do / worklist panel showing the user's pending assignments. Shows the top 3 items by default with a "Show more" / "Show less" toggle. Supports two modes: `worklist` (personal workbasket) and `todo` (case-level assignments). Clicking an item opens the assignment. A badge in the card header shows the total count.
+
+## Pega Metadata
+
+- **Registration key:** `Todo` (note: lowercase `o` in the key; file is `ToDo.tsx`)
+- **Category:** Widget — assignment / action
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `datasource` | `any` | No | Array of assignments passed directly (used in `todo` type). If provided, skips the data page fetch |
+| `myWorkList` | `any` | No | Work list config object `{ datapage: string, fields: [...] }` — for `worklist` type |
+| `caseInfoID` | `string` | No | Case ID to filter assignments (used in `todo` type) |
+| `headerText` | `string` | No | Widget title. Default: `"To do"` |
+| `itemKey` | `string` | No | Field key (reserved, currently unused) |
+| `showTodoList` | `boolean` | No | Whether to show the assignment list. Default `true` |
+| `type` | `string` | No | `'worklist'` (personal work) or `'todo'` (case-level). Default `'worklist'` |
+| `context` | `string` | No | Context name for API calls. Falls back to `pConn.getContextName()` |
+| `isConfirm` | `boolean` | No | Confirmation mode — adjusts rendering for post-submit confirmation view |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Data Source Resolution
+
+**`type === 'todo'` (case-level):**
+- Use `datasource` prop directly (array of assignment objects).
+- `caseInfoID` is used to scope the assignments.
+
+**`type === 'worklist'` (personal work):**
+- Fetch from `myWorkList.datapage` (e.g., `D_WorkList`) via:
+  ```
+  PCore.getDataPageUtils().getDataAsync(
+    myWorkList.datapage,
+    context,
+    {},
+    { pageNumber: 1, pageSize: 50 },
+    { select: myWorkList.fields },
+    { invalidateCache: true }
+  )
+  ```
+- Map the response to assignment objects.
+
+### Top 3 + Show More
+
+- `showCount` state: default `3`.
+- Render only `assignments.slice(0, showCount)`.
+- If `assignments.length > 3`:
+  - Show a `"Show more"` button → sets `showCount = assignments.length`.
+  - When expanded: show `"Show less"` button → sets `showCount = 3`.
+
+### Badge Count
+
+- Render a `<Badge badgeContent={assignments.length}>` on the card header or alongside the title.
+- Badge shows the total count of assignments, not the currently-visible count.
+
+### Open Assignment
+
+On item click:
+```typescript
+pConn.getActionsApi().openAssignment(
+  assignment.pxRefObjectKey,   // case key
+  assignment.pxRefObjectClass, // class name
+  {
+    containerName: pConn.getContainerName() || PCore.getConstants().APP.APP,
+    channelName: ''
+  }
+);
+```
+
+### Assignment Item Rendering
+
+For each assignment, show:
+- **Avatar:** Circle with user initials (derived from `pConn.getContextObject?.().pyLabel` or operator name).
+- **Name/title:** `assignment.pyLabel` — the assignment task name.
+- **Status badge (worklist only):** `assignment.pyStatusWork` — colored status pill.
+- **Priority/urgency:** `assignment.pyUrgencyWork` — urgency level indicator.
+- **Child case indicator:** If `assignment.isChild === true`, show an indent or nested indicator.
+- **Arrow icon:** Right-pointing arrow (`<ArrowForwardIosOutlinedIcon>`) indicating clickable.
+
+### Responsive Layout
+
+Use `useMediaQuery(theme.breakpoints.down('sm'))` (MUI) to detect mobile:
+- **Desktop:** Show avatar, name, status, priority, and arrow in a horizontal row.
+- **Mobile:** Stack or truncate elements for narrow display.
+
+### `canPerform` Permission Check
+
+If an assignment has `canPerform === false`, render it as non-clickable (greyed out, no onClick handler).
+
+### Snackbar Error
+
+- On `openAssignment` failure, catch the error and show a `<Snackbar>` with the error message.
+- Auto-hide after 3000ms.
+- `<IconButton>` (`<CloseIcon>`) to manually dismiss.
+
+### Operator Avatar Initials
+
+Extract initials from `PCore.getEnvironmentInfo().getOperatorName()`:
+```typescript
+const initials = operatorName
+  .split(' ')
+  .map(w => w[0])
+  .join('')
+  .substring(0, 2)
+  .toUpperCase();
+```
+
+## Visual Specifications
+
+### Card Layout
+
+| Element | Description |
+|---------|-------------|
+| Card header | `headerText` (default `"To do"`) + badge with count |
+| Assignment rows | Up to `showCount` items |
+| Show more/less button | Below the last visible item |
+
+### Assignment Row
+
+| Element | Desktop | Mobile |
+|---------|---------|--------|
+| Avatar circle | Shown | Shown |
+| Task name | Full text | Truncated |
+| Status badge | Shown | Hidden or small |
+| Priority indicator | Shown | Simplified |
+| Arrow icon | Shown | Shown |
+
+**CSS-only implementation notes:**
+- Card: standard card layout.
+- Assignment row: `display: flex; align-items: center; gap: 0.75rem; padding: 10px 0; cursor: pointer; border-bottom: 1px solid var(--divider-color)`.
+- Avatar: `width: 36px; height: 36px; border-radius: 50%; background: var(--avatar-bg); display: flex; align-items: center; justify-content: center; font-size: 0.875rem; font-weight: 600`.
+- Status badge: `padding: 2px 6px; border-radius: 10px; font-size: 0.75rem; background: var(--status-bg-color)`.
+- Priority: `font-size: 0.75rem; color: var(--secondary-text-color)`.
+- Arrow: `margin-left: auto; color: var(--secondary-text-color)`.
+- Non-clickable (canPerform=false): `opacity: 0.5; cursor: not-allowed`.
+- Show more button: `width: 100%; text-align: center; padding: 8px; color: var(--app-primary-color)`.
+
+## Edge Cases & Special Logic
+
+- `type` defaults to `'worklist'` — handle the fallback gracefully if `type` is undefined.
+- `datasource` prop vs fetch: if `datasource` is provided (non-empty), skip the data page fetch entirely.
+- `myWorkList` may be undefined for `todo` type — do not attempt a fetch if it's missing.
+- `showTodoList === false` — render only the card header (with badge count) and hide the list body.
+- `isConfirm === true` — used in the Confirmation template context; may adjust layout to hide certain elements (e.g., hide status badge, show simpler view).
+- Empty assignments — show a `"No tasks"` or `"You're all caught up!"` empty state message.
+- `canPerform` check: if `false`, disable click and show cursor `not-allowed`. Do not open the assignment.
+- Container name fallback: `pConn.getContainerName() || PCore.getConstants().APP.APP` — always provide a container name to `openAssignment`.
+
+## Dependencies
+
+- `PCore.getDataPageUtils().getDataAsync()` — worklist data page fetch
+- `PCore.getEnvironmentInfo()` — operator name for avatar initials
+- `PCore.getConstants()` — CASE_INFO, WORK_BASKET, TODO, APP constants
+- `PCore.getLocaleUtils()` — assignment label localization
+- `pConn.getActionsApi().openAssignment()` — opens the selected assignment
+- MUI: `<Card>`, `<CardContent>`, `<CardHeader>`, `<Avatar>`, `<Typography>`, `<Badge>`, `<List>`, `<ListItem>`, `<ListItemText>`, `<Button>`, `<Snackbar>`, `<IconButton>`, `useMediaQuery`, `useTheme`
+- MUI Icons: `<CloseIcon>`, `<ArrowForwardIosOutlinedIcon>`
+
+## Design System Mapping
+
+**UI control type:** Assignment worklist widget with expand/collapse, click-to-open, badge count, and error toast.
+
+Listed design systems are examples only.
+
+| Design System | Card | List | Badge | Snackbar |
+|---|---|---|---|---|
+| Default (CSS only) | `<div>` card | `<ul>/<li>` | CSS counter badge | Custom toast overlay |
+| MUI | `<Card>` + `<CardHeader>` | `<List>/<ListItem>` | `<Badge>` | `<Snackbar>/<Alert>` |
+| Ant Design | `<Card>` | `<List>` | `<Badge count={N}>` | `message.error()` |
+| Chakra UI | `<Card>` | `<VStack>` | `<Badge>` | `useToast()` |
+| Shadcn/ui | `<Card>` | `<ul>/<li>` | Custom badge | `<Toaster>` + `toast.error()` |
+
+When implementing in a specific design system:
+- Show top 3 items by default — `showCount` state controls slice; "Show more/less" toggles between 3 and full length
+- `canPerform === false` must make the row non-clickable — check this before calling `openAssignment`
+- `type === 'worklist'` fetches from a data page; `type === 'todo'` uses the `datasource` prop — both paths must be implemented
+- Operator initials for the avatar must be derived from `PCore.getEnvironmentInfo().getOperatorName()`

package/templates/react-sdk-reference/.cursor/rules/template-component.mdrules

@@ -0,0 +1,95 @@
+---
+globs: ["src/components/template/**/*.tsx"]
+alwaysApply: false
+---
+
+# 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/.cursor/rules/widget-component.mdrules

@@ -0,0 +1,90 @@
+---
+globs: ["src/components/widget/**/*.tsx"]
+alwaysApply: false
+---
+
+# 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