@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/{.github → .ai-common}/skills/template-skills/WssNavBar.md

@@ -12,13 +12,13 @@ Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive:
 
 ## Pega Metadata
 
-- **Registration key:** `WssNavBar` (in `component-map.ts`)
+- **Registration key:** `WssNavBar` (in the project's component map)
 - **Category:** Navigation template — WSS portal
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop                | Type       | Required | Description                                           |
+| Input               | Type       | Required | Description                                           |
 | ------------------- | ---------- | -------- | ----------------------------------------------------- |
 | `links`             | `array`    | Yes      | Array of `{ label, url, id }` navigation link objects |
 | `navDisplayOptions` | `object`   | No       | `{ alignment: 'left'                                  | 'right' | 'center', position: 'inline' | 'below' }` |
@@ -26,14 +26,26 @@ Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive:
 | `operatorInfo`      | `object`   | No       | `{ displayName: string }` — for avatar initials       |
 | `getPConnect`       | `function` | Yes      | PConnect getter                                       |
 
+## Implementation Structure
+
+**Module Setup:** Use the project's base component interface for typing. Import the `logout` function from the SDK auth manager (`@pega/auth/lib/sdk-auth-manager`). Include a companion styles file for layout. Register the component under its key in the project's component map.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `appInfo`, `navLinks`, `operator`, and `navDisplayOptions`; further destructure `alignment` and `position` from `navDisplayOptions`.
+2. Declare local state for menu anchoring: one for the mobile hamburger menu, one for the user/avatar menu (both initialized to `null`). Bind `localizedVal` to `PCore.getLocaleUtils().getLocaleValue`.
+3. Build a reusable `navLinksContent` element — a container hidden on mobile and shown as a flex row on desktop (justified per `alignment`), containing one button per nav link that invokes the link's `onClick`.
+4. Render an app bar with static position, containing a toolbar with, in order: the app logo/name button (invoking `appInfo.onClick`, showing `appInfo.imageSrc` and `appInfo.appName`); a hamburger icon button shown only on mobile that opens the mobile menu; a mobile dropdown menu (anchored to the hamburger state, open when set, closing by resetting to `null`) listing each nav link as a menu item; the `navLinksContent` block rendered inline when `position === 'inline'`; and an avatar showing `operator.currentUserInitials` that opens a user menu containing a "Log off" menu item (localized via `localizedVal('Log off', 'AppShell')`) wired to the imported `logout` function.
+5. When `position === 'below'`, render the `navLinksContent` block again below the toolbar, still inside the app bar.
+
 ## Behavioral Contract
 
 ### Responsive Layout
 
-- **Mobile (xs breakpoint):** Hamburger menu button (`<MenuIcon>`) shown; nav links hidden.
-  - On click: opens a `<Drawer>` or dropdown menu with nav links.
-  - CSS: `display: { xs: 'flex', md: 'none' }` on hamburger; `display: { xs: 'none', md: 'flex' }` on nav links.
-- **Desktop (md+ breakpoint):** Nav links shown inline; hamburger hidden.
+- **Mobile (narrow viewport):** Hamburger menu button shown; nav links hidden.
+  - On click: opens a dropdown or drawer with nav links.
+  - CSS approach: hide nav links at narrow breakpoint, show hamburger; reverse at wide breakpoint.
+- **Desktop (wide viewport):** Nav links shown inline; hamburger hidden.
 
 ### Navigation Position
 
@@ -47,7 +59,7 @@ From `navDisplayOptions.position`:
 From `navDisplayOptions.alignment`:
 
 - `'left'` — links flush left.
-- `'right'` — links pushed to the right (flex with `ml: 'auto'`).
+- `'right'` — links pushed to the right (e.g., flex with auto-margin on left side).
 - `'center'` — links centered.
 
 ### Operator Avatar
@@ -55,7 +67,7 @@ From `navDisplayOptions.alignment`:
 - Extract initials from `operatorInfo.displayName`:
   - Split by space, take first letter of first and last word.
   - E.g. `"John Smith"` → `"JS"`.
-- Render as `<Avatar>{initials}</Avatar>`.
+- Render as a circular avatar element with initials text.
 - Clicking avatar opens a menu with a Logout option.
 
 ### Logout
@@ -65,27 +77,7 @@ From `navDisplayOptions.alignment`:
 
 ### Render Structure
 
-```
-<AppBar position='static'>
-  <Toolbar>
-    {/* Logo */}
-    {portalLogoUrl && <img src={portalLogoUrl} alt='logo' />}
-
-    {/* Hamburger (mobile) */}
-    <IconButton sx={{ display: { xs: 'flex', md: 'none' } }} onClick={openMobileMenu}>
-      <MenuIcon />
-    </IconButton>
-
-    {/* Nav links (desktop) */}
-    <Box sx={{ display: { xs: 'none', md: 'flex' }, ...alignmentStyles }}>
-      {links.map(link => <Button key={link.id} href={link.url}>{link.label}</Button>)}
-    </Box>
-
-    {/* Operator avatar */}
-    <Avatar onClick={openUserMenu}>{initials}</Avatar>
-  </Toolbar>
-</AppBar>
-```
+An app bar (static position) containing a toolbar with, in order: the portal logo image (when `portalLogoUrl` is set); a hamburger icon button hidden on desktop that opens the mobile menu; a nav-links container hidden on mobile / shown on desktop applying the alignment styles, with one button per link (using `link.url` as the href and `link.label` as the text); and an avatar showing the operator initials that opens the user menu.
 
 ## Visual Specifications
 
@@ -110,29 +102,18 @@ From `navDisplayOptions.alignment`:
 - `portalLogoUrl` is async — show fallback text until resolved.
 - `operatorInfo.displayName` may be undefined — guard and show a default avatar (single letter or icon).
 - `navDisplayOptions` may be absent — default to `{ alignment: 'left', position: 'inline' }`.
-- Mobile drawer state must be managed separately from the user menu state.
+- Mobile menu state must be managed separately from the user menu state.
 
 ## Dependencies
 
 - `logout` from `@pega/auth/lib/sdk-auth-manager` — logout handler
-- MUI: `<AppBar>`, `<Toolbar>`, `<IconButton>`, `<Avatar>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<Box>`
-- MUI Icons: `<MenuIcon>`
+- The project's design system components for app bar, toolbar, icon button, avatar, menu, and button elements
 
 ## Design System Mapping
 
 **UI control type:** Responsive application navigation bar with avatar and logout.
 
-Listed design systems are examples only.
-
-| Design System      | App Bar                  | Avatar                 | Mobile Menu              |
-| ------------------ | ------------------------ | ---------------------- | ------------------------ |
-| Default (CSS only) | `<header>` + CSS         | `<div class='avatar'>` | CSS hamburger + dropdown |
-| MUI                | `<AppBar>` + `<Toolbar>` | `<Avatar>`             | `<Drawer>` or `<Menu>`   |
-| Ant Design         | `<Layout.Header>`        | `<Avatar>`             | `<Drawer>`               |
-| Chakra UI          | `<Box as='header'>`      | `<Avatar>`             | `<Drawer>`               |
-| Shadcn/ui          | Custom `<header>`        | Custom initials avatar | `<Sheet>` (drawer)       |
-
-When implementing in a specific design system:
+When implementing, choose the design system's app bar, avatar, and mobile menu (drawer or dropdown) components that match the project's chosen library. All design systems must preserve:
 
 - `logout` from `@pega/auth/lib/sdk-auth-manager` is mandatory — always call the SDK logout, not a custom one
 - Responsive breakpoints for hamburger/nav visibility must be implemented

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

@@ -0,0 +1,124 @@
+# Skill: Widget Components
+
+Create or replace widget components in the project. Widgets are self-contained UI blocks that fetch their own data from Pega APIs (data pages, case info) and render interactive features (ToDo lists, attachments, case history, etc.).
+
+---
+
+## Architecture Overview
+
+Each widget lives in its own folder under the project's widget components directory, named after the component. The folder typically contains: the component implementation file; optionally a re-export module; optionally a companion stylesheet; optionally a widget-specific utilities module; optionally a types definition module; and optionally a metadata file.
+
+---
+
+## Input Contract
+
+Widget components extend the project's **base component interface** (which provides `getPConnect`). A typical widget input contract adds widget-specific inputs provided by the platform, such as `datasource`, `headerText`, and `context`.
+
+Some widgets extend the project's **field input contract** when they behave like form fields (e.g., Attachment): the Attachment input contract overrides `value` to be `any` (an attachment list rather than a string), and adds `allowMultiple` and `extensions`.
+
+---
+
+## Implementation Pattern
+
+### Data-Fetching Widget
+
+Widgets typically fetch data from Pega data pages on mount. This pattern is design-system agnostic. The design-system render section must be replaced with your design system's presentation primitives (card, list, table, etc.) — see "Design System Adaptation" below.
+
+**Module Setup:** The component depends on local state management and a lifecycle effect for data fetching, plus the design system's presentation components (card, list, etc.). Define the input contract as an extension of the project's base component interface with `datasource` and `headerText` fields.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect`, `datasource`, and `headerText` (default `'My Widget'`) from inputs; call `getPConnect()` into `pConn`. Declare `data` local state (array, default empty) and `loading` local state (boolean, default `true`).
+2. **Fetch data from a Pega data page on mount** — this block is always the same regardless of design system. In a lifecycle effect that runs once on initialization: resolve `context` via `pConn.getContextName()`; call `PCore.getDataPageUtils().getDataAsync(datasource?.source, context, {}, { pageNumber: 1, pageSize: 10 }, { select: [{ field: 'pyID' }, { field: 'pyLabel' }] }, { invalidateCache: true })` — where `datasource?.source` is the data page name (e.g. `'D_WorkList'`); on success, set `data` to `response?.data` when it is an array (otherwise an empty array) and set `loading` to `false`; on failure, just set `loading` to `false`.
+3. **Loading state** — while `loading` is true, render a simple loading placeholder (replace with the design system's loading indicator if available).
+4. **Design-system render** — once loaded, render the design system's card/list primitives: a card with a header showing `headerText`, and inside the card content, a list where each `data` item (keyed by index) renders `item.pyLabel`. See "Design System Adaptation" below for guidance on choosing the actual DS components.
+
+---
+
+## Design System Adaptation
+
+The PCore data-fetching logic (all `PCore.*` calls) is always identical regardless of design system. Only the design-system render section changes.
+
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` contains a **Design System Mapping** section where available. Use it as a starting point.
+
+**2. If the chosen design system is not covered** — use the component purpose description to identify the appropriate DS primitives (card, list, table, button, badge, etc.).
+
+**3. Discover the API from installed packages** — confirm component names and inputs from the design system's type declaration files before writing the render markup.
+
+**4. Common widget UI primitive mapping:**
+
+| Widget pattern       | Typical DS equivalent                           |
+| -------------------- | ----------------------------------------------- |
+| Container with title | Card + header/title, or Panel, Box              |
+| Item list            | List, or Table rows                             |
+| Loading indicator    | Spinner, Skeleton, Loading                      |
+| Action button        | Button with click handler                       |
+| Status badge         | Badge, Tag, Chip                                |
+| Empty state          | DS empty/placeholder component or plain element |
+
+**5. Icons** — if the DS has a companion icon package, check its exports before using any icon name. Never guess icon names.
+
+---
+
+### Action Widget (opens assignments/cases)
+
+Define `openAssignment(assignment)`: resolve `classname` and `ID` from `assignment`; resolve `context` via `getPConnect().getContextName()`; build `options = { containerName: 'primary', channelName: '' }`; then call `PCore.getMashupApi().openAssignment(ID, classname, options)`. Define `createCase(caseType)` to call `PCore.getMashupApi().createCase(caseType, PCore.getConstants().APP.APP)`.
+
+---
+
+## Common Pega APIs Used in Widgets
+
+### Data Pages
+
+Fetch list data via `PCore.getDataPageUtils().getDataAsync(dataPageName, context, params, paging, query, options)`. Get a single-record page via `PCore.getDataPageUtils().getPageDataAsync(dataPageName, context, params)`.
+
+### Case Info
+
+Call `getPConnect()` into `pConn`, then read `pConn.getCaseInfo().getKey()` for the case key, `pConn.getCaseInfo().getID()` for the case ID, and `pConn.getCaseInfo().getName()` for the case name.
+
+### Attachments
+
+Use `PCore.getAttachmentUtils().prepareAttachmentData(value)` to prepare attachment data, `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, errorHandler, context)` to upload, and `PCore.getAttachmentUtils().downloadAttachment(attachmentID, context)` to download.
+
+### Actions
+
+Resolve `actionsApi` via `pConn.getActionsApi()`, then use `actionsApi.updateFieldValue(propName, value)` to update a field's value, `actionsApi.triggerFieldChange(propName, value)` to trigger a field change event, and `actionsApi.openLocalAction(actionName, options)` to open a local action.
+
+### Container Management
+
+Resolve `containerManager` via `pConn.getContainerManager()`, then call `containerManager.addContainerItem({ semanticURL, key, flowName, caseViewMode, resourceType, data })` to add a container item.
+
+---
+
+## Registration
+
+Register widgets in the project's component map: import the widget's default export from its folder under the widget components directory, then add it to the object returned by the project's component registration function. The key must match the Pega component name.
+
+---
+
+## Existing Widget Components
+
+| Component       | Description                 | Key APIs                                                            |
+| --------------- | --------------------------- | ------------------------------------------------------------------- |
+| AppAnnouncement | System-wide announcements   | `PCore.getMessagingServiceUtils()`                                  |
+| Attachment      | File upload/download        | `PCore.getAttachmentUtils()`                                        |
+| CaseHistory     | Case audit trail            | `PCore.getDataPageUtils()`                                          |
+| FileUtility     | File management utility     | `PCore.getAttachmentUtils()`                                        |
+| Followers       | Case followers list         | `PCore.getDataPageUtils()`                                          |
+| QuickCreate     | Quick case creation buttons | `PCore.getMashupApi().createCase()`                                 |
+| SummaryItem     | Single summary card         | Inputs from parent                                                  |
+| SummaryList     | List of summary cards       | Inputs from parent                                                  |
+| ToDo            | Assignment worklist         | `PCore.getDataPageUtils()`, `PCore.getMashupApi().openAssignment()` |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component is exported as the module's default export.
+2. **Self-contained data** — Widgets fetch their own data (don't rely on parent passing data down).
+3. **Loading states** — Always handle loading/error states when fetching data.
+4. **PCore globals** — Access `PCore` directly (declared globally by the Pega runtime type definitions).
+5. **Localization** — Use `pConn.getLocalizationService()` for translated strings when available.
+6. **Context** — Use `pConn.getContextName()` as the context parameter for data page calls.
+7. **Card layout** — Widgets typically render inside the design system's card component with a header and content area.
+8. **Action handling** — Use `PCore.getMashupApi()` for case/assignment operations, `actionsApi` for field updates.

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

@@ -0,0 +1,94 @@
+# 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, inputs 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` input, and an optional external link button. Styled with a left accent border to visually distinguish it from other cards.
+
+## Pega Metadata
+
+- **Registration key:** `AppAnnouncement` (registered in the project's component map)
+- **Category:** Widget — informational display
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input          | 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                                                        |
+
+## Implementation Structure
+
+**Module Setup:** The component's inputs interface extends the project's base component interface with optional `header` (string), `description` (string), `datasource` (any), and `whatsnewlink` (string).
+
+**Main Component Logic** — steps in order:
+
+1. Receive `header`, `description`, `datasource`, and `whatsnewlink` from inputs, each defaulting to an empty string (`datasource` defaulting to an empty array).
+2. Extract item names from `datasource`: map `datasource?.source` to an array of each item's `name` property, defaulting to an empty array when `datasource.source` is absent.
+3. Render a card with a left accent border (6px solid, using the primary light color token) and vertical margin (`0.5rem 0` top/bottom) so the card has proper spacing from sibling elements — this margin is required, without it the card has no top spacing. Inside, render a card header containing the `header` text as a heading, followed by a card content block containing the `description` paragraph and one paragraph per extracted item name (prefixed with a dash). When `whatsnewlink` is non-empty, render a card actions block with a button labeled "See what's new" that opens `whatsnewlink` in a new browser tab on click.
+
+## 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 input-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` input 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.
+- `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
+
+- The design system's card component (with header, content, and actions regions)
+- The design system's typography component
+- The design system's button component
+
+## Design System Mapping
+
+**UI control type:** Announcement / informational card with bullet list and external link.
+
+When implementing in a specific design system, map the following:
+
+- **Card container:** A card component with distinct header, content, and footer/actions regions. Apply a 6px solid left accent border using the primary light color token — this is the key visual identifier.
+- **Card header:** Renders the `header` text as a heading-level element (typically h6 weight).
+- **Card content:** Contains the `description` as body text, followed by the optional bullet list (one item per line, prefixed with a dash or rendered as a standard unordered list).
+- **Card actions / footer:** Contains the "See what's new" button. This button must open the URL in a new tab with appropriate security attributes.
+- **Button:** A primary-colored text or outlined button with no text transformation (no uppercase).
+
+Implementation notes:
+
+- 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 with `rel='noopener noreferrer'`
+- The widget is entirely input-driven — no data fetching needed

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

@@ -0,0 +1,163 @@
+# 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, inputs 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` (registered in the project's component map)
+- **Category:** Widget — form field (file input)
+- **Extends:** the project's base component interface (with `value` typed as `any` instead of the standard string value)
+
+## Inputs
+
+| Input              | 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 base interface) | 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                                                              |
+
+## Implementation Structure
+
+This is a complex form-field widget (~400 lines). Key structural outline:
+
+**Module Setup:** The component requires local state, lifecycle effects, cached callbacks, memoized computations, and instance references. It depends on `validateMaxSize` from the project's attachment helpers, as well as `clearFieldErrorMessages`, `deleteAttachments`, `getIconFromFileType`, `insertAttachments`, a deep-memo utility, a file-download utility, and `validateFileExtension` from the component's own utility module. The component's inputs interface extends the project's base component interface (with `value` as `any`) plus `allowMultiple` (boolean or string), `extensions` (string), `editMode` (string), and `isTableFormatter` (boolean).
+
+**Main Component Logic** — steps in order:
+
+1. Receive `value`, `getPConnect`, `label`, `validatemessage`, `extensions`, `displayMode`, `helperText`, `editMode`, and `isTableFormatter` from inputs; also receive `required`, `disabled`, and `allowMultiple` as mutable locals. Coerce each of `required`, `disabled`, and `allowMultiple` to a real boolean (true when the value is literally `true` or the string `'true'`), since these may arrive as string booleans.
+2. Call `getPConnect()` into `pConn`; store `actionSequencer = PCore.getActionsSequencer()` via a memoized computation (no dependencies); resolve `contextName = pConn.getContextName()`.
+3. **Normalize attachment data** (old vs. new format): call `PCore.getAttachmentUtils().prepareAttachmentData(value)` to get `{ attachments, isOldAttachment }`.
+4. **Set the reference list**: read `valueRef` from `(pConn.getStateProps() as any).value`, then call `pConn.setReferenceList('.' + valueRef)`.
+5. Declare local state: `files` (array, initialized from `attachments`) and `toggleUploadBegin` (boolean, default `false`).
+6. Define `deleteFile`: removes the file from local state, calls `deleteAttachments`, and deregisters it from the action sequencer.
+7. Define `onFileAdded`: validates the file's extension and size, adds it to `files`, and sets `toggleUploadBegin`.
+8. Define `uploadFiles`: registers a blocking action via the sequencer, uploads each file via `uploadAttachment`, and calls `insertAttachments` on success.
+9. In a lifecycle effect keyed on `toggleUploadBegin`, trigger `uploadFiles` when it changes.
+10. In another lifecycle effect, subscribe to the `ASSIGNMENT_SUBMISSION` event for state override (block submission while uploads are pending).
+11. **Render**: a container element with the field `label`, an upload button (hidden native file input plus a styled button), validation/helper text, and the file list — each row showing an icon, name, metadata, upload progress, and a delete button.
+
+> **Key patterns:** Action sequencer blocking (`registerBlockingAction`/`deRegisterBlockingAction`), `prepareAttachmentData` normalization, per-file progress tracking, `insertAttachments`/`deleteAttachments` helpers for state management.
+
+## Behavioral Contract
+
+### Attachment Format Detection
+
+Pega has two attachment data formats — detect which one is in use:
+
+**Old format (annotation-based):** `value` is an object shaped like `{ pxResults: [...], pyAttachCount: N }`.
+
+**New standard format:** `value` is an array of attachment objects, each shaped like `{ ID, name, mimeType, category, ... }`.
+
+Call `PCore.getAttachmentUtils().prepareAttachmentData(value)` to normalize both formats into a unified `FileObject[]` array.
+
+### File Validation
+
+On file selection (via a file-picker control):
+
+1. **Extension check:** Compare selected file's extension against the `extensions` input (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 local 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 of `fileId → number` in local state.
+- `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
+
+- The project's attachment utility module — `validateExtension`, `validateSize`, `getFileTypeIcon`, `buildDownloadURL`, error handling helpers
+- The project's attachment type definitions — `FileObject`, `AttachmentLinks`, `PageInstructionOptions`
+- `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
+- A file-download utility — browser file download trigger
+
+## Design System Mapping
+
+**UI control type:** File upload form field with progress tracking, validation, and attachment list.
+
+When implementing in a specific design system, map the following:
+
+- **File input / drop zone:** A clickable upload area (optionally supporting drag-and-drop) backed by a hidden native file input. The design system's file-picker or upload component can replace the custom drop zone, but the hidden native input pattern works universally.
+- **Progress indicator:** A linear progress bar (determinate, 0–100) shown per-file during upload. Use the design system's linear progress component or a CSS-based bar.
+- **File list:** A vertical list of uploaded file rows. Each row contains: a file-type icon, the file name, file size metadata, the progress indicator (during upload), and a delete action button. Use the design system's list component or simple styled rows.
+- **Error text:** Validation or upload error messages displayed below the control in an error color.
+- **Helper text:** Secondary descriptive text below the control.
+
+Implementation notes:
+
+- 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/.ai-common/skills/widget-skills/CaseHistory.md

@@ -0,0 +1,90 @@
+# 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, the base component 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 (`pxTimeCreated`), what happened (`pyMessageKey`), and who performed it (`pyPerformer`). Uses a deep-equality utility to skip unnecessary re-renders when data has not changed.
+
+## Pega Metadata
+
+- **Registration key:** `CaseHistory` (in the project's component map)
+- **Category:** Widget — case data display
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input         | Type       | Required | Description                                           |
+| ------------- | ---------- | -------- | ----------------------------------------------------- |
+| `getPConnect` | `function` | Yes      | PConnect getter — used to resolve case ID and context |
+
+## Implementation Structure
+
+**Module Setup:** Requires local state, an instance reference, and a lifecycle effect. Also needs a deep-equality utility and the project's SDK utility helpers for date formatting. The component interface extends the project's base component interface (no additional custom inputs).
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect` from inputs; call it once into `thePConn`. Declare a `rowData` instance reference (initialized to an empty array) and a `waitingForData` local state boolean (default `true`).
+2. Resolve `caseID` via `thePConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '')` and `context` via `thePConn.getContextName()`.
+3. Build a `displayedColumns` array of three column descriptors, each with a localized `label` (via `thePConn.getLocalizedValue`), a `type`, and a `fieldName`: Date (`'DateTime'`, `pxTimeCreated`), Description (`'TextInput'`, `pyMessageKey`), and Performed by (`'TextInput'`, `pyPerformer`).
+4. **Fetch `D_pyWorkHistory` on mount** — in a lifecycle effect that runs once on initialization, using a guard flag to prevent post-teardown state updates: call `PCore.getDataApiUtils().getData('D_pyWorkHistory', { dataViewParameters: [{ CaseInstanceKey: caseID }] }, context)`; on resolution, when still active, call `computeRowData` with `historyJSON.data.data` and set `waitingForData` to `false`. In the teardown callback, set the guard flag to `false` so the state setter is never called after the component is destroyed.
+5. Define `computeRowData(rows)`: map each row to an array of cell values, one per `displayedColumns` entry — formatting `DateTime`-type columns through the SDK utility helper `generateDateTime(row[col.fieldName], 'DateTime-Short')` and passing other column values through as-is. Compare the resulting `theRowData` against the current `rowData` instance reference using the deep-equality utility, and only update the instance reference when the data has actually changed (this avoids unnecessary re-renders).
+6. **Render** a table with three columns and `'---'` as the placeholder for missing or falsy cell values. The header row renders one cell per `displayedColumns` entry (using its `label`). The body renders one row per entry in the `rowData` instance reference, with one cell per value (falling back to `'---'` when the value is falsy).
+
+No additional custom inputs. All data is fetched internally.
+
+## Behavioral Contract
+
+### Data Fetch
+
+On mount, fetch history from the `D_pyWorkHistory` data page by calling `PCore.getDataApiUtils().getData('D_pyWorkHistory', { dataViewParameters: [{ CaseInstanceKey: caseID }] }, context)`.
+
+- `caseID` = `thePConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '')`.
+- `context` = `thePConn.getContextName()`.
+- Store result in a `rowData` instance reference.
+- On error or empty response, `rowData` stays as `[]`.
+
+### Re-render Optimization
+
+Use a deep-equality utility to compare new row data with the previous value — only update the stored data if it has actually changed. This prevents unnecessary re-renders caused by reference inequality.
+
+### Data Transformation
+
+For each history row, map:
+
+- **Date column:** Format `pxTimeCreated` using the SDK date formatting utility (e.g., `generateDateTime(row.pxTimeCreated, 'DateTime-Short')`).
+- **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         | `pxTimeCreated` (formatted) | ~25%  |
+| Description  | `pyMessageKey`              | ~50%  |
+| Performed by | `pyPerformer`               | ~25%  |
+
+The table header cells should have a distinct background color, bold text, and 1px solid borders. Body cells should have 1px solid borders in a silver/neutral tone. Missing-value placeholders (`"---"`) should be visually subdued. Use the design system's table component for consistent styling. No pagination in the reference implementation — all rows are 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"`).
+- `pxTimeCreated` format varies — always run it through the SDK date formatting utility 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.
+- The lifecycle effect teardown callback sets a guard flag to prevent calling state setters after component destruction, avoiding framework warnings about unmounted state updates.
+
+## Dependencies
+
+- `PCore.getDataApiUtils().getData()` — fetches `D_pyWorkHistory` data page
+- A deep-equality utility — prevents unnecessary re-renders by comparing row data before updating
+- `PCore.getConstants().CASE_INFO.CASE_INFO_ID` — resolves case ID constant
+- The project's SDK utility helpers — for date formatting (`generateDateTime`)
+- The design system's table component (container, header, body, row, and cell elements)