@pega/sdk 0.0.3 → 0.0.5

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

@@ -1,107 +0,0 @@
-# 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/.github/skills/widget-skills/FileUtility.md

@@ -1,200 +0,0 @@
-# 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/.github/skills/widget-skills/Followers.md

@@ -1,99 +0,0 @@
-# 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/.github/skills/widget-skills/QuickCreate.md

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