@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.ai-common/skills/widget-skills/AppAnnouncement.md

@@ -0,0 +1,121 @@
+# Skill: AppAnnouncement
+
+Card-based announcement widget. Displays a system-wide or application announcement with an optional bullet list of items and a "See what's new" external link button.
+
+> **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 an announcement card with a heading, description text, optional bullet list of items sourced from a `datasource` prop, and an optional external link button. Styled with a left accent border to visually distinguish it from other cards.
+
+## Pega Metadata
+
+- **Registration key:** `AppAnnouncement` (in `component-map.ts`)
+- **Category:** Widget — informational display
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop           | Type       | Required | Description                                                            |
+| -------------- | ---------- | -------- | ---------------------------------------------------------------------- |
+| `header`       | `string`   | No       | Announcement card title                                                |
+| `description`  | `string`   | No       | Announcement body text                                                 |
+| `datasource`   | `object`   | No       | Data source object — `datasource.source` is an array of item objects   |
+| `whatsnewlink` | `string`   | No       | URL for the "See what's new" button; if absent, button is not rendered |
+| `getPConnect`  | `function` | Yes      | PConnect getter                                                        |
+
+## Component Skeleton
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface AppAnnouncementProps extends PConnProps {
+  header?: string;
+  description?: string;
+  datasource?: any;
+  whatsnewlink?: string;
+}
+
+export default function AppAnnouncement(props: AppAnnouncementProps) {
+  const { header = '', description = '', datasource = [], whatsnewlink = '' } = props;
+
+  // 1. Extract item names from datasource
+  const details = datasource?.source?.map(item => item.name) || [];
+
+  // 2. Render: Card with left accent border + vertical margin for sibling spacing
+  //    ⚠️ margin '0.5rem 0' is REQUIRED — without it the card has no top spacing
+  return (
+    <Card style={{ borderLeft: '6px solid var(--app-primary-light-color)', margin: '0.5rem 0' }}>
+      <CardHeader><h6>{header}</h6></CardHeader>
+      <CardContent>
+        <p>{description}</p>
+        {details.map((itm, idx) => <p key={idx}>- {itm}</p>)}
+      </CardContent>
+      {whatsnewlink && (
+        <CardActions>
+          <Button onClick={() => window.open(whatsnewlink, '_blank')}>See what's new</Button>
+        </CardActions>
+      )}
+    </Card>
+  );
+}
+```
+
+## Behavioral Contract
+
+1. **Item list extraction:** If `datasource` is provided and `datasource.source` is a non-empty array, extract item names and render them as a bullet list. Each array item is expected to have a `name` property.
+2. **Button:** If `whatsnewlink` is non-empty, render a button labeled `"See what's new"` (or localized equivalent). On click, open the URL in a new browser tab (`window.open(whatsnewlink, '_blank')`).
+3. **Description:** Render the `description` string as plain text below the header.
+4. **No data fetching:** This widget is purely prop-driven — it does not call any PCore data APIs.
+
+## Visual Specifications
+
+### Card Layout
+
+| Element                 | Position                                |
+| ----------------------- | --------------------------------------- |
+| Left accent border      | 6px solid, primary light color          |
+| Card header             | `header` prop as title                  |
+| Card content            | Description text + optional bullet list |
+| "See what's new" button | Below description / bullet list         |
+
+**CSS-only implementation notes:**
+
+- Card: `border-left: 6px solid var(--app-primary-light-color); border-radius: 4px; box-shadow: 0 1px 4px rgba(0,0,0,0.12); margin: 0.5rem 0` — the vertical margin ensures consistent spacing with sibling widgets (e.g., Pulse).
+- Card header: `padding: 12px 16px; font-weight: 600`.
+- Card content: `padding: 0 16px 16px`.
+- Bullet list: `padding-left: 1.5rem; margin: 0.5rem 0`.
+- "See what's new" button: `margin-top: 0.75rem; text-transform: none`.
+
+## Edge Cases & Special Logic
+
+- `datasource` may be `undefined` or `datasource.source` may be an empty array — in both cases, render no bullet list (not even an empty `<ul>`).
+- `whatsnewlink` may be an empty string — treat the same as absent (no button rendered).
+- `header` and `description` may both be absent — render the card with empty/placeholder content without crashing.
+- Item objects in `datasource.source` are expected to have `name` — guard against items where `name` is `undefined`.
+
+## Dependencies
+
+- MUI: `<Card>`, `<CardHeader>`, `<CardContent>`, `<Typography>`, `<Button>`
+
+## Design System Mapping
+
+**UI control type:** Announcement / informational card with bullet list and external link.
+
+Listed design systems are examples only.
+
+| Design System      | Card                                        | Bullet List                   | Button                     |
+| ------------------ | ------------------------------------------- | ----------------------------- | -------------------------- |
+| Default (CSS only) | `<div>` with left border + box-shadow       | `<ul>/<li>`                   | `<button>` opening new tab |
+| MUI                | `<Card>` + `<CardHeader>` + `<CardContent>` | `<List>/<ListItem>` or `<ul>` | `<Button>`                 |
+| Ant Design         | `<Card>` with `title` prop                  | `<ul>/<li>`                   | `<Button>`                 |
+| Chakra UI          | `<Card>` + `<CardHeader>` + `<CardBody>`    | `<UnorderedList>/<ListItem>`  | `<Button>`                 |
+| Shadcn/ui          | `<Card>` + `<CardHeader>` + `<CardContent>` | `<ul>/<li>`                   | `<Button>`                 |
+
+When implementing in a specific design system:
+
+- Left accent border is a key visual identifier — implement it via CSS or the design system's border utilities
+- "See what's new" must open in a new tab (`target='_blank'` + `rel='noopener noreferrer'`)
+- The widget is entirely prop-driven — no data fetching needed

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

@@ -0,0 +1,209 @@
+# 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                                                              |
+
+## Component Skeleton
+
+This is a complex form-field widget (~400 lines). Key structural outline:
+
+```typescript
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { validateMaxSize } from '../../helpers/attachmentShared';
+import { clearFieldErrorMessages, deleteAttachments, getIconFromFileType, insertAttachments,
+  useDeepMemo, useFileDownload, validateFileExtension } from './AttachmentUtils';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import './Attachment.css';
+
+interface AttachmentProps extends Omit<PConnFieldProps, 'value'> {
+  value: any; allowMultiple: boolean | string; extensions: string;
+  editMode: string; isTableFormatter: boolean;
+}
+
+export default function Attachment(props: AttachmentProps) {
+  const { value, getPConnect, label, validatemessage, extensions, displayMode, helperText, editMode, isTableFormatter } = props;
+  let { required, disabled, allowMultiple } = props;
+  // Coerce string booleans
+  [required, disabled, allowMultiple] = [required, disabled, allowMultiple].map(
+    p => p === true || (typeof p === 'string' && p === 'true')
+  );
+  const pConn = getPConnect();
+  const actionSequencer = useMemo(() => PCore.getActionsSequencer(), []);
+  const contextName = pConn.getContextName();
+
+  // 1. Normalize attachment data (old vs new format)
+  const { attachments, isOldAttachment } = PCore.getAttachmentUtils().prepareAttachmentData(value);
+  // 2. Set reference list
+  let valueRef = (pConn.getStateProps() as any).value;
+  pConn.setReferenceList(`.${valueRef}`);
+
+  // 3. State: files array, error tracking, upload toggle
+  const [files, setFiles] = useState(attachments);
+  const [toggleUploadBegin, setToggleUploadBegin] = useState(false);
+
+  // 4. deleteFile — removes from state, calls deleteAttachments, deregisters sequencer
+  // 5. onFileAdded — validates extension + size, adds to files, sets toggleUploadBegin
+  // 6. uploadFiles — registerBlockingAction, uploadAttachment per file, insertAttachments on success
+  // 7. useEffect: trigger uploadFiles when toggleUploadBegin changes
+  // 8. useEffect: subscribe to ASSIGNMENT_SUBMISSION for state override
+
+  // 9. Render: label + upload button + validation message + file list with progress/delete
+  return (
+    <div className="file-upload-container">
+      <label>{label}</label>
+      {/* Upload button (hidden input + styled button) */}
+      {/* Validation/helper text */}
+      {/* File list: icon + name + meta + progress + delete button */}
+    </div>
+  );
+}
+```
+
+> **Key patterns:** Action sequencer blocking (`registerBlockingAction`/`deRegisterBlockingAction`), `prepareAttachmentData` normalization, per-file progress tracking, `insertAttachments`/`deleteAttachments` helpers for Redux state.
+
+## 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 → .ai-common/skills/widget-skills/CaseHistory.md}

@@ -1,8 +1,3 @@
----
-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.
@@ -23,9 +18,72 @@ Renders a table of case events sourced from the `D_pyWorkHistory` data page. Sho
 
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `getPConnect` | `function` | Yes | PConnect getter — used to resolve case ID and context |
+| Prop          | Type       | Required | Description                                           |
+| ------------- | ---------- | -------- | ----------------------------------------------------- |
+| `getPConnect` | `function` | Yes      | PConnect getter — used to resolve case ID and context |
+
+## Component Skeleton
+
+```typescript
+import { useEffect, useRef, useState } from 'react';
+import isDeepEqual from 'fast-deep-equal/react';
+import { Utils } from '../../helpers/utils';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface CaseHistoryProps extends PConnProps {}
+
+export default function CaseHistory(props: CaseHistoryProps) {
+  const { getPConnect } = props;
+  const thePConn = getPConnect();
+  const rowData = useRef([]);
+  const [waitingForData, setWaitingForData] = useState(true);
+
+  const caseID = thePConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '');
+  const context = thePConn.getContextName();
+
+  const displayedColumns = [
+    { label: thePConn.getLocalizedValue('Date', '', ''), type: 'DateTime', fieldName: 'pxTimeCreated' },
+    { label: thePConn.getLocalizedValue('Description', '', ''), type: 'TextInput', fieldName: 'pyMessageKey' },
+    { label: thePConn.getLocalizedValue('Performed by', '', ''), type: 'TextInput', fieldName: 'pyPerformer' },
+  ];
+
+  // 1. Fetch D_pyWorkHistory on mount
+  useEffect(() => {
+    let active = true;
+    PCore.getDataApiUtils().getData('D_pyWorkHistory',
+      { dataViewParameters: [{ CaseInstanceKey: caseID }] }, context
+    ).then((historyJSON: any) => {
+      if (active) {
+        computeRowData(historyJSON.data.data);
+        setWaitingForData(false);
+      }
+    });
+    return () => { active = false; };
+  }, []);
+
+  // 2. computeRowData — format dates, use isDeepEqual to prevent unnecessary updates
+  function computeRowData(rows) {
+    const theRowData = rows.map(row => displayedColumns.map(col =>
+      col.type === 'DateTime' ? Utils.generateDateTime(row[col.fieldName], 'DateTime-Short') : row[col.fieldName]
+    ));
+    if (!isDeepEqual(theRowData, rowData.current)) rowData.current = theRowData;
+  }
+
+  // 3. Render: Table with 3 columns, '---' for missing values
+  return (
+    <TableContainer>
+      <Table>
+        <TableHead><TableRow>{displayedColumns.map(col => <TableCell key={col.fieldName}>{col.label}</TableCell>)}</TableRow></TableHead>
+        <TableBody>
+          {rowData.current.map((row, i) => (
+            <TableRow key={i}>{row.map((cell, j) => <TableCell key={j}>{cell || '---'}</TableCell>)}</TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+}
+```
 
 No additional custom props. All data is fetched internally.
 
@@ -55,6 +113,7 @@ Use `fast-deep-equal/react` to compare new `historyData` with previous value —
 ### 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.
@@ -64,13 +123,14 @@ For each history row, map:
 
 ### Table Layout
 
-| Column | Field | Width |
-|--------|-------|-------|
-| Date | `pyUpdatedDateTime` (formatted) | ~25% |
-| Description | `pyMessageKey` | ~50% |
-| Performer | `pyPerformer` | ~25% |
+| 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)`.
@@ -98,15 +158,16 @@ For each history row, map:
 
 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>` |
+| 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