@pega/sdk 0.0.2 → 0.0.4

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

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

@@ -0,0 +1,110 @@
+# 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,206 @@
+# 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,103 @@
+# 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