@pega/sdk 0.0.2 → 0.0.3

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

@@ -0,0 +1,151 @@
+---
+description: Widget component skill: Attachment
+alwaysApply: false
+---
+
+# Skill: Attachment
+
+File upload/download widget for case attachments. Behaves like a form field — binds to a case attachment property, supports multiple files, validates extensions and size, tracks upload progress, and blocks form submission during active uploads.
+
+> **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 file attachment control within a Pega form. Users can upload one or multiple files, download existing attachments, and delete attachments. The widget validates file extensions and enforces a maximum size from environment config. Upload progress is shown per-file. Form submission is blocked while uploads are in progress via the action sequencer.
+
+## Pega Metadata
+
+- **Registration key:** `Attachment` (in `component-map.ts`)
+- **Category:** Widget — form field (file input)
+- **Extends:** `Omit<PConnFieldProps, 'value'>` (uses `value: any` instead of the standard string value)
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `value` | `any` | Yes | Attachment list or single attachment object (from Pega property) |
+| `allowMultiple` | `boolean \| string` | No | Whether multiple files can be attached. Default `false` |
+| `extensions` | `string` | No | Comma-separated list of allowed file extensions (e.g., `".pdf,.doc,.jpg"`) |
+| `editMode` | `string` | No | `"tableRows"` for inline table edit mode (special multi-attachment handling) |
+| `isTableFormatter` | `boolean` | No | Whether this widget is used inside a table formatter |
+| `label` | `string` | Yes (from PConnFieldProps) | Field label |
+| `required` | `boolean` | No | Whether a file is required |
+| `disabled` | `boolean` | No | Whether the control is disabled |
+| `displayMode` | `string` | No | `"DISPLAY_ONLY"` for read-only rendering |
+| `validatemessage` | `string` | No | Validation error message to display |
+| `helperText` | `string` | No | Helper text shown below the control |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Attachment Format Detection
+
+Pega has two attachment data formats — detect which one is in use:
+
+**Old format (annotation-based):**
+```typescript
+value = { pxResults: [...], pyAttachCount: N }
+```
+
+**New standard format:**
+```typescript
+value = [{ ID, name, mimeType, category, ... }]  // array
+```
+
+Call `PCore.getAttachmentUtils().prepareAttachmentData(value)` to normalize both formats into a unified `FileObject[]` array.
+
+### File Validation
+
+On file selection (via `<input type='file'>`):
+1. **Extension check:** Compare selected file's extension against `extensions` prop (split by comma). If not allowed, add an error to the file and do not upload.
+2. **Size check:** Compare file size against `PCore.getEnvironmentInfo().getMaxAttachmentSize()` (in bytes). If too large, add a size error.
+3. Valid files proceed to upload.
+
+### Upload Flow
+
+1. Call `PCore.getActionsSequencer().addAction('attachment_upload_' + fileId)` — blocks form submission.
+2. Call `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, onError, context)`.
+3. On progress: update per-file `progress` value (0–100) in state.
+4. On success: add the returned attachment metadata to the local file list; update the Pega property via `pConn.setReferenceList(newAttachmentList)`.
+5. Call `PCore.getActionsSequencer().removeAction('attachment_upload_' + fileId)` — unblocks form submission.
+6. On error: set file error state; call `PCore.getMessageManager().addMessages([errorMessage])`.
+
+### Download
+
+Call `PCore.getAttachmentUtils().downloadAttachment(attachmentID, context)` — triggers browser file download.
+
+### Delete
+
+Remove the attachment from the local list and update `pConn.setReferenceList(updatedList)`. Do not call a separate delete API in the reference implementation — deletion is committed on form save.
+
+### Pub-Sub: Assignment Submission
+
+Subscribe to `PCore.getPubSubUtils().subscribe(BEFORE_ASSIGNMENT_SUBMIT, handleBeforeSubmit, 'Attachment')`. In `handleBeforeSubmit`, validate that no uploads are still in progress.
+
+### Read-Only Mode (`displayMode === 'DISPLAY_ONLY'`)
+
+Render a list of existing attachments as download links. No upload controls shown.
+
+### Inline Table Edit Mode (`editMode === 'tableRows'`)
+
+Compressed display for use inside a table cell. Show attachment count and a small upload button. Clicking opens a minimal upload dialog.
+
+## Visual Specifications
+
+| Element | Description |
+|---------|-------------|
+| Label | Standard field label above the control |
+| Drop zone / Upload button | Clickable area to select files; optionally supports drag-and-drop |
+| File list | Each uploaded file: icon + name + size + progress bar (during upload) + delete button |
+| Error state | Red error text below the control for invalid files or upload failures |
+| Helper text | Secondary text below the control |
+
+**CSS-only implementation notes:**
+- Drop zone: `border: 2px dashed var(--border-color); border-radius: 4px; padding: 1rem; text-align: center; cursor: pointer`.
+- Drop zone hover: `border-color: var(--app-primary-color); background: var(--hover-bg)`.
+- File row: `display: flex; align-items: center; gap: 0.5rem; padding: 4px 0`.
+- Progress bar: `height: 4px; background: var(--app-primary-color); border-radius: 2px; transition: width 0.2s`.
+- Error text: `color: var(--error-color); font-size: 0.75rem; margin-top: 4px`.
+- Delete button: `color: var(--error-color)`.
+
+## Edge Cases & Special Logic
+
+- `allowMultiple` may be a string `"true"` / `"false"` or a boolean — always coerce: `allowMultiple === true || allowMultiple === 'true'`.
+- Upload progress: track per-file progress in a `Map<fileId, number>` state object.
+- `isTableFormatter`: when `true`, hide the label and reduce padding for compact table display.
+- Concurrent uploads: multiple files may upload simultaneously — the sequencer action must be keyed per-file.
+- Max size: call `PCore.getEnvironmentInfo().getMaxAttachmentSize()` at validation time (not at mount) — size config may be dynamic.
+- `extensions` may be empty string — if empty, allow all file types.
+
+## Dependencies
+
+- `AttachmentUtils.ts` — `validateExtension`, `validateSize`, `getFileTypeIcon`, `buildDownloadURL`, error handling helpers
+- `Attachment.types.ts` — `FileObject`, `AttachmentLinks`, `PageInstructionOptions` type definitions
+- `PCore.getAttachmentUtils()` — upload, download, prepareAttachmentData
+- `PCore.getActionsSequencer()` — block/unblock form submission during upload
+- `PCore.getEnvironmentInfo()` — max attachment size
+- `PCore.getMessageManager()` — error message display
+- `PCore.getPubSubUtils()` — before-submit subscription
+- `downloadjs` library — browser file download trigger
+
+## Design System Mapping
+
+**UI control type:** File upload form field with progress tracking, validation, and attachment list.
+
+Listed design systems are examples only.
+
+| Design System | File Input | Progress | File List |
+|---|---|---|---|
+| Default (CSS only) | `<input type='file'>` + custom styled drop zone | `<progress>` element or CSS bar | `<ul>/<li>` rows |
+| MUI | Custom styled `<Box>` drop zone + hidden `<input>` | `<LinearProgress>` | `<List>/<ListItem>` |
+| Ant Design | `<Upload dragger>` | `<Progress>` | Built-in upload file list |
+| Chakra UI | Custom `<Box>` with `useDropzone` | `<Progress>` | `<VStack>` rows |
+| Shadcn/ui | Custom drop zone | Custom CSS progress bar | `<ul>/<li>` rows |
+
+When implementing in a specific design system:
+- Action sequencer blocking (`addAction`/`removeAction`) is mandatory — do not skip it; form submission must be blocked during uploads
+- Detect and normalize both old and new attachment formats via `prepareAttachmentData`
+- `allowMultiple` coercion (string vs boolean) is required
+- Extension and size validation must happen client-side before calling the upload API

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

@@ -0,0 +1,112 @@
+---
+description: Widget component skill: CaseHistory
+alwaysApply: false
+---
+
+# 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/.cursor/rules/skills/widget-skills/FileUtility.mdrules

@@ -0,0 +1,205 @@
+---
+description: Widget component skill: FileUtility
+alwaysApply: false
+---
+
+# 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/.cursor/rules/skills/widget-skills/Followers.mdrules

@@ -0,0 +1,104 @@
+---
+description: Widget component skill: Followers
+alwaysApply: false
+---
+
+# 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