@pega/sdk 0.0.1 → 0.0.3

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

@@ -0,0 +1,107 @@
+# Skill: CaseHistory
+
+Case history widget. Fetches and displays the full audit trail for the current case in a table with Date, Description, and Performer columns.
+
+> **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 table of case events sourced from the `D_pyWorkHistory` data page. Shows when each event happened (`pyUpdatedDateTime`), what happened (`pyMessageKey`), and who performed it (`pyPerformer`). Uses `fast-deep-equal` to skip unnecessary re-renders when data has not changed.
+
+## Pega Metadata
+
+- **Registration key:** `CaseHistory` (in `component-map.ts`)
+- **Category:** Widget — case data display
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `getPConnect` | `function` | Yes | PConnect getter — used to resolve case ID and context |
+
+No additional custom props. All data is fetched internally.
+
+## Behavioral Contract
+
+### Data Fetch
+
+On mount, fetch history from the `D_pyWorkHistory` data page:
+
+```
+PCore.getDataApiUtils().getData(
+  'D_pyWorkHistory',
+  { pyCaseInsKey: caseKey },
+  context
+)
+```
+
+- `caseKey` = `pConn.getCaseInfo().getKey()` (the fully-qualified case key).
+- `context` = `pConn.getContextName()`.
+- Store result in `historyData` state array.
+- On error or empty response, `historyData` stays as `[]`.
+
+### Re-render Optimization
+
+Use `fast-deep-equal/react` to compare new `historyData` with previous value — only call `setHistoryData` if the data has actually changed. This prevents unnecessary re-renders caused by reference inequality.
+
+### Data Transformation
+
+For each history row, map:
+- **Date column:** Format `pyUpdatedDateTime` using the SDK date formatter (e.g., `formatDateTime(row.pyUpdatedDateTime)`) or display as-is.
+- **Description column:** `row.pyMessageKey` — the localized event description string.
+- **Performer column:** `row.pyPerformer` — the operator who performed the action.
+- Missing values: display `"---"` for any undefined/null field.
+
+## Visual Specifications
+
+### Table Layout
+
+| Column | Field | Width |
+|--------|-------|-------|
+| Date | `pyUpdatedDateTime` (formatted) | ~25% |
+| Description | `pyMessageKey` | ~50% |
+| Performer | `pyPerformer` | ~25% |
+
+**CSS-only implementation notes:**
+- Table container: `width: 100%; overflow-x: auto`.
+- Table: `border-collapse: collapse; width: 100%`.
+- Header cells: `background: var(--table-header-bg); font-weight: 600; padding: 8px 12px; border-bottom: 2px solid var(--divider-color)`.
+- Body cells: `padding: 8px 12px; border-bottom: 1px solid var(--divider-color)`.
+- Missing value placeholder `"---"`: `color: var(--secondary-text-color)`.
+- No pagination in the reference implementation — all rows shown.
+
+## Edge Cases & Special Logic
+
+- `D_pyWorkHistory` may return an empty array for cases with no history events — render an empty table body (or an empty-state message like `"No history available"`).
+- `pyUpdatedDateTime` format varies — always run it through the SDK date formatter before display.
+- `pyMessageKey` may be a locale key — resolve it via `PCore.getLocaleUtils().getLocaleValue()` if a localized string is required.
+- The widget has no pagination — for cases with very long history, the table may become very tall. Consider adding pagination if needed.
+
+## Dependencies
+
+- `PCore.getDataApiUtils().getData()` — fetches `D_pyWorkHistory` data page
+- `fast-deep-equal/react` — prevents unnecessary re-renders
+- `PCore.getConstants().CASE_INFO.CASE_INFO_ID` — resolves case ID constant
+- MUI: `<Table>`, `<TableBody>`, `<TableCell>`, `<TableContainer>`, `<TableHead>`, `<TableRow>`
+
+## Design System Mapping
+
+**UI control type:** Read-only case audit table with 3 columns.
+
+Listed design systems are examples only.
+
+| Design System | Table |
+|---|---|
+| Default (CSS only) | `<table>/<thead>/<tbody>/<tr>/<td>` |
+| MUI | `<TableContainer>` + `<Table>` + `<TableHead>/<TableBody>/<TableRow>/<TableCell>` |
+| Ant Design | `<Table dataSource={historyData} columns={...}>` |
+| Chakra UI | `<Table>` + `<Thead>/<Tbody>/<Tr>/<Th>/<Td>` |
+| Shadcn/ui | `<Table>` + `<TableHeader>/<TableBody>/<TableRow>/<TableHead>/<TableCell>` |
+
+When implementing in a specific design system:
+- `fast-deep-equal` comparison is a performance optimization — include it to avoid redundant renders on re-subscription
+- Data page name `D_pyWorkHistory` is fixed — do not make it configurable
+- Missing field fallback `"---"` should be consistent across all three columns

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

@@ -0,0 +1,200 @@
+# Skill: FileUtility
+
+File and URL management utility widget. Displays case attachments and links, supports upload/download/delete, and provides modals for adding new files or URLs. Also covers `ActionButtonsForFileUtil` sub-component.
+
+> **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
+
+The primary attachments management panel in the case utilities column. Shows up to 3 attachments/links in the main view with a "View all" option that opens a modal with the full list. Users can upload files, attach URLs, download, and delete items. Attachment state is kept fresh via debounced pub-sub subscriptions.
+
+## Pega Metadata
+
+- **Registration key:** `FileUtility` (in `component-map.ts`)
+- **Category:** Widget — file management
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `caseId` | `string` | No | Optional case ID override. If absent, resolved from `pConn.getCaseInfo().getID()` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Attachment Fetch
+
+On mount and on attachment change events:
+```
+PCore.getAttachmentUtils().getCaseAttachments(caseKey, context)
+```
+Returns array of attachment/link objects. Store in `attachments` state.
+
+Debounced auto-refresh: on `CASE_ATTACHMENTS_UPDATED` pub-sub event, wait 1000ms (debounced) then re-fetch. This prevents rapid re-fetches when multiple files are uploaded simultaneously.
+
+### Main View — Top 3 Display
+
+Show only the first 3 items from `attachments`. If `attachments.length > 3`, show a `"View all (N)"` button that opens the full-list modal.
+
+### SummaryList Integration
+
+Map each attachment/link to a `SummaryItem`-compatible object:
+```typescript
+{
+  id: attachment.ID,
+  visual: { icon: getFileIcon(attachment.mimeType) },
+  primary: {
+    type: attachment.category === 'FILE' ? 'FILE' : 'URL',
+    name: attachment.name,
+    click: () => handleDownloadOrOpen(attachment)
+  },
+  secondary: { text: attachment.createdBy + ' · ' + formatDate(attachment.createTime) }
+  actions: [
+    { id: 'delete', text: 'Delete', icon: 'trash', onClick: () => handleDelete(attachment.ID) }
+  ]
+}
+```
+
+Pass to `<SummaryList arItems$={summaryItems} />`.
+
+### File Upload
+
+1. User clicks "Add file" from the `<Menu>`.
+2. Opens an add-file modal (dialog).
+3. User selects a file via `<input type='file'>`.
+4. On confirm: call `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, onError, context)`.
+5. On success: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [newAttachment], context)`.
+6. Refresh attachment list.
+
+### URL Attachment
+
+1. User clicks "Add link" from the `<Menu>`.
+2. Opens add-link modal with two fields: `Title` (required) and `URL` (required).
+3. The "Attach" button is enabled only when both `title` and `url` are non-empty.
+4. On confirm: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [{ name: title, url, category: 'URL' }], context)`.
+5. Refresh attachment list.
+
+### Download / Open
+
+- **FILE type:** Call `PCore.getAttachmentUtils().downloadAttachment(attachmentID, context)` then trigger browser download via `downloadjs`.
+- **URL type:** Open `attachment.url` in a new browser tab (`window.open(url, '_blank')`).
+
+### Delete
+
+Call `PCore.getAttachmentUtils().deleteAttachment(attachmentID, context)`. Refresh attachment list after success.
+
+### Actions Menu
+
+Render a `<MoreVertIcon>` `<IconButton>` that opens a `<Menu>` with:
+- `"Add file"` — opens add-file modal
+- `"Add link"` — opens add-link modal
+
+## Visual Specifications
+
+### Main Card
+
+| Element | Description |
+|---------|-------------|
+| Card header | `"Attachments"` (or localized) + count badge |
+| Actions icon | `<MoreVertIcon>` button top-right |
+| Attachment rows | Up to 3 `SummaryItem` cards |
+| "View all" button | Text button, shown when > 3 attachments |
+
+### "View all" Modal
+
+| Element | Description |
+|---------|-------------|
+| Modal header | `"All attachments (N)"` |
+| Attachment rows | All items in `SummaryList` |
+| Close button | `X` in modal header |
+
+### Add File Modal
+
+| Element | Description |
+|---------|-------------|
+| File picker | `<input type='file'>` |
+| Progress bar | Per-file upload progress |
+| Action buttons | `ActionButtonsForFileUtil` (Cancel + Attach) |
+
+### Add Link Modal
+
+| Element | Description |
+|---------|-------------|
+| Title field | `<TextField label='Title'>` — required |
+| URL field | `<TextField label='URL'>` — required |
+| Attach button | Enabled only when both fields are filled |
+| Action buttons | `ActionButtonsForFileUtil` (Cancel + Attach) |
+
+**CSS-only implementation notes:**
+- Main card: standard card styles.
+- Modal: `position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: white; border-radius: 8px; box-shadow: 0 4px 24px rgba(0,0,0,0.2); min-width: 480px; padding: 1.5rem`.
+- "View all" button: text style, `color: var(--app-primary-color); cursor: pointer`.
+- Progress bar: `height: 4px; background: var(--app-primary-color); transition: width 0.3s`.
+
+## Sub-Component: ActionButtonsForFileUtil
+
+**Registration key:** `ActionButtonsForFileUtil`
+
+A simple button row component used inside the FileUtility modals to render Cancel + primary action buttons.
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `arMainButtons` | `any[]` | Yes | Primary button definitions `[{ actionID, name }]` |
+| `arSecondaryButtons` | `any[]` | Yes | Secondary (cancel) button definitions `[{ actionID, name }]` |
+| `primaryAction` | `function` | Yes | Callback invoked when the primary button is clicked |
+| `secondaryAction` | `function` | Yes | Callback invoked when the secondary/cancel button is clicked |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+### Layout
+
+```
+[Secondary buttons (left)]   [Primary buttons (right)]
+      Cancel                        Attach
+```
+
+- Secondary buttons: outlined/text style.
+- Primary buttons: contained/filled style with theme primary color.
+- Render using `arSecondaryButtons.map(...)` and `arMainButtons.map(...)`.
+
+## Edge Cases & Special Logic
+
+- **Debounce (1000ms):** Prevents excessive re-fetches when multiple attachment events fire in quick succession.
+- **Add link "Attach" button disabled state:** Title and URL validation must happen on every keystroke — use controlled inputs with `!title || !url` to derive disabled state.
+- **`linkAttachmentsToCase`:** After upload, the file must be explicitly linked to the case. Uploading alone does not associate the file with the case.
+- **Pub-sub cleanup:** Unsubscribe from `CASE_ATTACHMENTS_UPDATED` on unmount to prevent stale callbacks.
+- **Error display:** Use `PCore.getMessageManager()` or inline error state in the modal — do not silently fail on upload/link errors.
+
+## Dependencies
+
+- `PCore.getAttachmentUtils()` — getCaseAttachments, uploadAttachment, downloadAttachment, deleteAttachment, linkAttachmentsToCase
+- `PCore.getMessagingServiceManager()` — subscribe to attachment change events
+- `PCore.getConstants()` — case info ID, summary refresh timing
+- `getComponentFromRegistry('SummaryList')` — renders the attachment item list
+- `getComponentFromRegistry('ActionButtonsForFileUtil')` — renders modal action buttons
+- `downloadjs` — browser file download trigger
+- MUI: `<Card>`, `<CardHeader>`, `<CardContent>`, `<IconButton>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<TextField>`, `<Dialog>`, `<CircularProgress>`
+- MUI Icons: `<MoreVertIcon>`
+
+## Design System Mapping
+
+**UI control type:** File management widget — attachment list with upload/download/delete and add modals.
+
+Listed design systems are examples only.
+
+| Design System | Card | Action Menu | Modal | Progress |
+|---|---|---|---|---|
+| Default (CSS only) | `<div>` card | `<button>` + custom dropdown | `<dialog>` | CSS progress bar |
+| MUI | `<Card>` | `<IconButton>` + `<Menu>/<MenuItem>` | `<Dialog>` | `<CircularProgress>` or `<LinearProgress>` |
+| Ant Design | `<Card>` | `<Dropdown menu={{ items }}>` | `<Modal>` | `<Progress>` |
+| Chakra UI | `<Card>` | `<Menu>/<MenuButton>/<MenuList>` | `<Modal>` | `<Progress>` |
+| Shadcn/ui | `<Card>` | `<DropdownMenu>` | `<Dialog>` | Custom progress bar |
+
+When implementing in a specific design system:
+- Debounced refresh (1000ms) after pub-sub attachment events is required — prevents excessive API calls
+- `linkAttachmentsToCase` must be called after upload — uploading alone does not attach to the case
+- `ActionButtonsForFileUtil` receives button definition arrays — render them generically from `arMainButtons`/`arSecondaryButtons`

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

@@ -0,0 +1,99 @@
+# Skill: Followers
+
+Followers widget. Displays the list of users following the current case. Currently a stub/placeholder in the reference implementation — renders an "unsupported" message.
+
+> **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
+
+Intended to display the list of operators following a case, allowing users to follow/unfollow a case and see who else is following it. The reference implementation is a **stub** — it renders a `"Followers - unsupported"` message inside a card. A full implementation would fetch follower data from the Pega data layer and provide follow/unfollow actions.
+
+## Pega Metadata
+
+- **Registration key:** `Followers` (in `component-map.ts`)
+- **Category:** Widget — social / collaboration
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+No additional custom props in the current stub implementation. A full implementation would likely include:
+- `datasource` — data page name for follower list
+- `headerText` — widget title (e.g., `"Followers"`)
+
+## Behavioral Contract
+
+### Current (Stub) Implementation
+
+1. Render a `<Card>` with title `"Followers"`.
+2. Show `"Followers - unsupported"` body text.
+3. No data fetching, no actions.
+
+### Expected Full Implementation
+
+1. **Fetch followers:** Call `PCore.getDataPageUtils().getDataAsync('D_pyCaseFollowers', context, { caseKey })` on mount.
+2. **Display follower list:** Render each follower's avatar (initials) and display name.
+3. **Follow/unfollow toggle:** Button to follow or unfollow the current case:
+   - Follow: `PCore.getRestClient().invokeCustomRestApi('/api/v1/cases/{caseID}/followers', { method: 'POST', ... })`.
+   - Unfollow: same endpoint with `DELETE` method.
+4. **Real-time update:** Subscribe to follower change events via pub-sub if available.
+
+## Visual Specifications
+
+### Stub Rendering
+
+| Element | Value |
+|---------|-------|
+| Card title | `"Followers"` |
+| Card body | `"Followers - unsupported"` plain text |
+
+### Expected Full Rendering
+
+| Element | Description |
+|---------|-------------|
+| Card header | `"Followers"` + count badge |
+| Follower avatars | Row of avatar initials circles |
+| Follow button | Toggle button `"Follow"` / `"Unfollow"` |
+
+**CSS-only implementation notes (stub):**
+- Card: standard card layout — `border-radius: 4px; box-shadow: 0 1px 4px rgba(0,0,0,0.12); padding: 1rem`.
+- Unsupported message: `color: var(--secondary-text-color); font-size: 0.875rem`.
+
+**CSS-only implementation notes (full):**
+- Avatar row: `display: flex; flex-wrap: wrap; gap: 4px`.
+- Avatar circle: `width: 32px; height: 32px; border-radius: 50%; background: var(--avatar-bg); display: flex; align-items: center; justify-content: center; font-size: 0.75rem; font-weight: 600`.
+
+## Edge Cases & Special Logic
+
+- If the stub message `"Followers - unsupported"` is shown in production, it means this widget has not been fully implemented yet — that is expected behavior.
+- When implementing: guard against empty follower arrays — show a `"No followers yet"` state.
+- Follow/unfollow toggle must reflect the current user's follow status — fetch this as part of the initial data load.
+
+## Dependencies
+
+- MUI: `<Card>`, `<CardContent>`, `<CardHeader>`, `<Typography>` (current stub)
+- Future full implementation would add: `<Avatar>`, `<Button>`, `<Badge>`, pub-sub subscriptions
+
+## Design System Mapping
+
+**UI control type:** Social widget — follower list with follow/unfollow action.
+
+Listed design systems are examples only.
+
+| Design System | Card | Avatar | Toggle Button |
+|---|---|---|---|
+| Default (CSS only) | `<div>` with border | CSS circle with initials | `<button>` |
+| MUI | `<Card>` + `<Avatar>` | `<Avatar>` | `<Button>` variant toggle |
+| Ant Design | `<Card>` | `<Avatar>` | `<Button>` |
+| Chakra UI | `<Card>` | `<Avatar>` | `<Button>` |
+| Shadcn/ui | `<Card>` | Custom avatar | `<Button>` |
+
+When implementing in a specific design system:
+- The current stub only needs a card with a message — implement the full behavior once the Pega backend supports it
+- Follow/unfollow must be scoped to the current case (`caseKey` from `pConn.getCaseInfo().getKey()`)
+- Follower count badge in the card header improves scannability

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

@@ -0,0 +1,114 @@
+# 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`