@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.claude/skills/widget-skills/SummaryItem.md

@@ -0,0 +1,167 @@
+# 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/.claude/skills/widget-skills/ToDo.md

@@ -0,0 +1,190 @@
+# 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/component-map.mdrules

@@ -0,0 +1,41 @@
+---
+globs: ["**/component-map.ts"]
+alwaysApply: false
+---
+
+# 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/.cursor/rules/dse-component.mdrules

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

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