@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/template-skills/CaseSummary.md

@@ -0,0 +1,129 @@
+# Skill: CaseSummary
+
+Case summary template. Renders a summary panel with primary and secondary case fields, derived from either inputs or child region extraction.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — Children-based field resolution is MANDATORY**
+>
+> The `arPrimaryFields` and `arSecondaryFields` inputs are almost always EMPTY at runtime. The Pega engine passes field data as region children, not as pre-computed array inputs.
+>
+> You MUST include children-based field extraction: when both `arPrimaryFields` and `arSecondaryFields` are empty, iterate the `children` and for each child, access its PConnect instance via the child element's **passed properties** (the `getPConnect` function is available on the child's properties, not directly on the child element itself). Then call `resolveConfigProps(getRawMetadata())` on that PConnect instance to resolve `@P` property references and `@L` label references into actual values. Check the resolved `name` (case-insensitive) to identify "primary fields" and "secondary fields" regions, and assign their resolved `children` arrays.
+>
+> **Key:** Access `getPConnect` from the child element's **passed properties** (NOT directly on the child). Children passed to page templates are rendered elements — `getPConnect` is available on their properties, not as a top-level method.
+>
+> **DO NOT** use `filterSummaryFields()`, `getSDKCaseUtils()`, or any other shortcut API to obtain summary fields. These APIs return raw unresolved metadata containing `@L` and `@P` tokens that will render as literal text. Only the children-based extraction with `resolveConfigProps(getRawMetadata())` resolves these tokens into actual values.
+>
+> Without this extraction, the summary will render completely empty or show unresolved `@P`/`@L` references.
+
+## Component Purpose
+
+Displays a case's key summary data in a structured summary panel. Primary fields are shown prominently; secondary fields are shown with labels. Data is sourced either directly from inputs or by extracting child regions. All field values are localized before display.
+
+## Pega Metadata
+
+- **Registration key:** `CaseSummary` (in the project's component map)
+- **Category:** Page template — summary
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input               | Type               | Required | Description                                             |
+| ------------------- | ------------------ | -------- | ------------------------------------------------------- |
+| `children`          | renderable content | No       | Region children when fields come from PConnect metadata |
+| `arPrimaryFields`   | `array`            | No       | Array of primary field objects (direct input)           |
+| `arSecondaryFields` | `array`            | No       | Array of secondary field objects (direct input)         |
+| `getPConnect`       | `function`         | Yes      | PConnect getter                                         |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the project's base component interface for typing. Obtain the project's component registry for resolving child components at runtime.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `CaseSummaryFields` from the project's component registry.
+2. Receive inputs: extract `children`, and `arPrimaryFields`/`arSecondaryFields` (both defaulting to empty arrays) as mutable bindings.
+3. Set up localization: `localizedVal = PCore.getLocaleUtils().getLocaleValue` and `localeCategory = 'ModalContainer'`.
+4. Define a helper `prepareComponentInCaseSummary(pConnectMeta, getPConnect)` that creates a component from metadata and returns `{ value: createdComponent }`.
+5. Define a helper `prepareCaseSummaryData(summaryFieldChildren)` that converts children into a summary data array.
+6. If both `arPrimaryFields` and `arSecondaryFields` are empty, iterate the `children`: for each child element, access its PConnect instance via the child's **passed properties** (the `getPConnect` function lives on the element's properties, not directly on the element). Call `resolveConfigProps(getRawMetadata())` on that PConnect instance — this resolves `@P` property references and `@L` label references into actual values. Check the resolved object's `name` (case-insensitive): when it equals `'primary fields'`, assign its `children` array to `arPrimaryFields` and localize each field's string `config.value`; when it equals `'secondary fields'`, assign its `children` array to `arSecondaryFields` and localize each field's string `config.value`.
+7. Render a container element with id `CaseSummary` containing two `CaseSummaryFields` instances — one with `theFields` set to `arPrimaryFields`, the other with `theFields` set to `arSecondaryFields`.
+
+## Behavioral Contract
+
+### Field Sourcing
+
+Two modes — prefer direct inputs if provided:
+
+**Mode A — Direct inputs:**
+
+- `arPrimaryFields` and `arSecondaryFields` are passed directly.
+- Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` to localize values.
+
+**Mode B — Children-based extraction:**
+
+- Iterate the `children` content-projected elements.
+- For each child, access its PConnect via the child element's **passed properties** (NOT directly on the child element).
+- Call `resolveConfigProps(getRawMetadata())` on the PConnect instance — this resolves `@P` property references and `@L` label references into actual runtime values.
+- Check the resolved `name` (case-insensitive) to identify "primary fields" and "secondary fields" regions.
+- Assign the resolved region's `children` array to the appropriate field list.
+- Localize each field's string `config.value` via `PCore.getLocaleUtils().getLocaleValue(value, localeCategory)`.
+
+### `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)`
+
+Helper that:
+
+1. Iterates each field in both arrays.
+2. Localizes the field value via `PCore.getLocaleUtils().getLocaleValue(value, classID, value)`.
+3. Returns `{ arPrimaryFields: localizedPrimary, arSecondaryFields: localizedSecondary }`.
+
+### Render
+
+Delegates entirely to `CaseSummaryFields` (a DSE component resolved from the project's component registry), passing:
+
+- `arPrimaryFields` — array of `{ name, value }` objects for primary display
+- `arSecondaryFields` — array of `{ name, value, displayLabel }` objects for secondary display
+
+## Visual Specifications
+
+- `CaseSummaryFields` handles all rendering — see the DSE component skill for details.
+- Primary fields: large text, no label.
+- Secondary fields: label + value pairs.
+
+**CSS-only implementation notes (for `CaseSummaryFields` wrapper):**
+
+- Container: `display: flex; flex-direction: column; gap: 8px`.
+- Primary field value: `font-size: 1rem; font-weight: 600`.
+- Secondary field row: `display: flex; gap: 4px; font-size: 0.875rem`.
+- Secondary label: `color: var(--secondary-text-color)`.
+
+## Edge Cases & Special Logic
+
+- If both `arPrimaryFields` input and children are present, the direct input takes priority.
+- `prepareCaseSummaryData` — guard against undefined/null field values before passing to `getLocaleValue`.
+- `displayLabel` on secondary fields controls whether the field label is shown alongside the value.
+- If `arSecondaryFields` is empty, the secondary section is not rendered.
+
+## Dependencies
+
+- `prepareCaseSummaryData` — local helper within this component
+- `CaseSummaryFields` — DSE component resolved from the project's component registry
+- `PCore.getLocaleUtils().getLocaleValue()` — value localization
+
+## Design System Mapping
+
+**UI control type:** Read-only case summary panel with primary and secondary field groups.
+
+When implementing in a specific design system, map the following:
+
+- **Primary fields:** Use a prominent text element (e.g., a heading or bold typography variant) to display values without labels.
+- **Secondary fields:** Use label + value pairs in a description-list style layout (e.g., a vertical list of term/definition pairs, or a compact grid of label-value rows).
+- **Container:** A vertical stack or flexbox column with consistent spacing between field groups.
+
+Regardless of design system:
+
+- Always localize field values before display — use `PCore.getLocaleUtils().getLocaleValue()`
+- `CaseSummaryFields` is a DSE component — implement it separately and call it from here
+- Primary fields have no labels; secondary fields have labels

package/templates/react-sdk-reference/.ai-common/skills/template-skills/CaseView.md

@@ -0,0 +1,196 @@
+# Skill: CaseView
+
+Case view template. Renders the full case workspace: summary sidebar, stages, to-do region, main content tabs, and utilities column. Also covers `ObjectPage` (which is a re-export of `CaseView`).
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> This is the most complex Page template (~260 lines in the reference). It MUST NOT be collapsed into a single-line return. The following are MANDATORY in the generated output:
+>
+> 1. `getChildRegionByName` from `PCore.getSDKUtils().getSDKCaseUtils()` — extract regions by metadata name, NOT by array index, NOT by a custom helper calling `child.getPConnect()`
+> 2. Resolve `VerticalTabs` from the project's component registry — for tab navigation in the sidebar
+> 3. Resolve `DeferLoad` from the project's component registry — for lazy-loading tab content
+> 4. Resolve `CaseViewActionsMenu` from the project's component registry — for case actions
+> 5. Lifecycle effect for `VerticalTabClick` event listener (add + remove on teardown)
+> 6. Lifecycle effect for `hasNewAttachments` → publish `CASE_ATTACHMENTS_UPDATED`
+> 7. `displayOnlyFA` check from the application store context — renders only todo region in focused action mode
+> 8. `activeVertTab` local state for tracking which tab is selected
+> 9. `vertTabInfo` + `deferLoadInfo` obtained from `extractTabsInfo(theTabsRegion)` SDK utility — **`vertTabInfo` MUST be `{ name: string; id: number }[]`, NOT a renderable element**
+> 10. 3-column grid layout: sidebar (3) + main content (6) + utilities (3)
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `getChildRegionByName` and `extractTabsInfo` obtained from `PCore.getSDKUtils().getSDKCaseUtils()`
+> - [ ] All 5 named regions extracted: summary, stages, todo, utilities, tabs
+> - [ ] Regions rendered DIRECTLY in the template — NOT passed through the PConnect bridge component
+> - [ ] **Case header card** rendered at top of sidebar with: title (`header` input), subheader (case ID), action buttons from `availableActions`, CaseViewActionsMenu
+> - [ ] Action buttons rendered **dynamically from `caseInfo.availableActions`** — labels localized via `PCore.getLocaleUtils().getLocaleValue()`
+> - [ ] VerticalTabs component rendered with tab config array
+> - [ ] DeferLoad component rendered with `name={deferLoadInfo[activeTab].config.name}` — **NOT the display label**
+> - [ ] **`vertTabInfo` and `deferLoadInfo` are SEPARATE arrays** — never merged into one
+> - [ ] CaseViewActionsMenu rendered **inside the case header card** (NOT standalone)
+> - [ ] displayOnlyFA check returning only todo region
+> - [ ] Lifecycle effect for VerticalTabClick event
+> - [ ] Lifecycle effect for hasNewAttachments pub/sub
+> - [ ] **Stages region in CENTER column** (main), NOT in sidebar
+
+---
+
+## Component Purpose
+
+The primary case workspace template. Extracts named regions from PConnect children by metadata type and name, arranges them in a 3-column responsive grid (3/6/3), handles deferred tab loading, and supports a `displayOnlyFA` mode that shows only the to-do region. Edit actions are triggered via the utilities column.
+
+> **Note:** `ObjectPage` is a direct re-export of `CaseView` — the ObjectPage module simply re-exports CaseView's default export. Do not create a separate `ObjectPage` component; register both keys pointing to the same implementation.
+
+## Pega Metadata
+
+- **Registration key:** `CaseView` and `ObjectPage` (both point to the same component)
+- **Category:** Page template — case workspace
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input                | Type               | Required | Description                                                                                                         |
+| -------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `children`           | renderable content | Yes      | Named region children (summary, stages, todo, utilities, tabs)                                                      |
+| `displayOnlyFA`      | `boolean`          | No       | If true, renders only the to-do region (focused action mode)                                                        |
+| `getPConnect`        | `function`         | Yes      | PConnect getter                                                                                                     |
+| `icon`               | `string`           | No       | Icon identifier for case type                                                                                       |
+| `subheader`          | `string`           | No       | Case ID displayed below the header                                                                                  |
+| `header`             | `string`           | Yes      | Case name/title                                                                                                     |
+| `showIconInHeader`   | `boolean`          | No       | Whether to show the case type icon in the header card                                                               |
+| `caseInfo`           | `object`           | Yes      | Case metadata (availableActions, availableProcesses, hasNewAttachments, caseTypeID, caseTypeName, caseTypeIcon, ID) |
+| `lastUpdateCaseTime` | `any`              | No       | Last case update timestamp; defaults to `getPConnect().getValue('caseInfo.lastUpdateTime')`                         |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the project's base component interface for typing. Obtain the project's component registry for resolving child components at runtime. Obtain the application store context for reading `displayOnlyFA`. Obtain a static-content URL utility for resolving icon paths.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `CaseViewActionsMenu`, `VerticalTabs`, and `DeferLoad` from the project's component registry.
+2. Receive inputs: extract `getPConnect`, `icon` (default `''`), `header`, `subheader`, `children` (default `[]`), and the nested `caseInfo` fields `availableActions` (default `[]`), `availableProcesses` (default `[]`), `hasNewAttachments`, `caseTypeID` (default `''`), `caseTypeName` (default `''`), and `caseTypeIcon`. Default `lastUpdateCaseTime` to `getPConnect().getValue('caseInfo.lastUpdateTime')` when not supplied. Read `currentCaseID` from `caseInfo.ID`; read `displayOnlyFA` from the application store context; call `getPConnect()` once into `thePConn`.
+3. **Extract named regions using SDK utilities:** Obtain `getChildRegionByName`, `extractTabsInfo`, and `openCaseEditAction` from `PCore.getSDKUtils().getSDKCaseUtils()`. Normalize `children` into an array (`childArr`). Use `getChildRegionByName(childArr, 'summary')` etc. to extract `theSummaryRegion`, `theStagesRegion`, `theTodoRegion`, `theUtilitiesRegion`, and `theTabsRegion`. **Do NOT implement a custom `getChildRegionByName` helper** — the SDK utility handles the internal child format correctly (children passed to page templates are rendered elements that do not expose `.getPConnect()` as a direct method).
+4. **Build tab info using SDK utility:** Call `extractTabsInfo(theTabsRegion)` to get `{ vertTabInfo, deferLoadInfo }`. Destructure with defaults: `const { vertTabInfo = [], deferLoadInfo = [] } = extractTabsInfo(theTabsRegion) ?? {}`. `vertTabInfo` is a plain array of `{ name: string; id: number }` objects (display labels for `VerticalTabs`). `deferLoadInfo` is a separate array of `{ type: 'DeferLoad', config }` objects (the full config for each tab). `DeferLoad`'s `name` input must always come from `deferLoadInfo[activeTab].config.name` (e.g., `"pyDetailsTabContent"`) — never the display label. **Do NOT manually iterate tab children to build these arrays** — the SDK utility handles the extraction correctly.
+5. Declare local state `activeVertTab` (number, default `0`). Determine `editAction` by finding the entry in `availableActions` whose `ID === 'pyUpdateCaseDetails'` — this action is data-driven from the network response; the ID is a common Pega convention but may differ per case type, and its label must always be localized rather than hardcoded.
+6. **`VerticalTabClick` listener:** in a lifecycle effect that runs once on initialization, add a `document` listener for the custom `VerticalTabClick` DOM event (not PubSub) that parses `event?.detail?.additionalData?.itemClicked` (or the event itself) as an integer and updates `activeVertTab` when valid; remove the listener on teardown. Track a mounted flag to avoid updating local state after teardown.
+7. **Attachment updates:** in a lifecycle effect keyed on `hasNewAttachments`, when it's true, publish `PCore.getPubSubUtils().publish(PCore.getEvents().getCaseEvent().CASE_ATTACHMENTS_UPDATED_FROM_CASEVIEW, true)`.
+8. Define `_editClick()`: call `openCaseEditAction(thePConn, editAction)` — this SDK utility handles the local action invocation correctly.
+9. **Render:** when `displayOnlyFA` is true, render only a wrapping container holding `theTodoRegion` directly (NOT through the PConnect bridge component) and stop there. Otherwise, bind `localizedVal = PCore.getLocaleUtils().getLocaleValue` and render a `psdk-case-view` container with three sections. **Regions returned by `getChildRegionByName` are rendered directly in the template** — do NOT pass them through the PConnect bridge component because they are already renderable elements:
+   - **Sidebar (column width 3/12):** a hidden element holding `currentCaseID`; a case header card (`psdk-case-view-header`) with a themed background, containing the title (`header`) and subheader/case-ID (`subheader`, when present) in a `psdk-case-view-header-content` block, followed by a `psdk-case-view-header-actions` block holding: an Edit button (rendered with the project's installed design system button component, NOT a plain button element, labeled via `localizedVal('Edit', 'CaseView')`, shown only when `editAction` exists, wired to `_editClick`); and the `CaseViewActionsMenu` (passed `getPConnect`, `availableActions`, `availableProcesses`, `caseTypeID`, `caseTypeName`) rendered inside this header card, not standalone. After the header card, render `theSummaryRegion`, then `VerticalTabs` (with `tabconfig` set to `vertTabInfo`) when there's more than one tab.
+   - **Main (column width 6/12):** `theStagesRegion` MUST appear here in the center column (never in the sidebar), followed by `theTodoRegion`, followed by `DeferLoad` (passed `getPConnect`, `name` set to `deferLoadInfo[activeVertTab].config.name`, `isTab`, `lastUpdateCaseTime`) when `deferLoadInfo` has an entry for the active tab.
+   - **Utilities (column width 3/12):** `theUtilitiesRegion`.
+
+   For the Edit button and header card styling, use the project's installed design system: e.g. a ghost/small button for a Carbon-based system, a text-variant button for a Material-based system, a link-type button for an Ant-based system, or a styled plain button when CSS-only; the header background should use a matching light accent token or color for each.
+
+> **Note:** `ObjectPage` is a re-export: its module simply re-exports CaseView's default export. Register both keys to the same component.
+
+## Behavioral Contract
+
+### Region Extraction
+
+> ⚠️ **CRITICAL:** Use `PCore.getSDKUtils().getSDKCaseUtils().getChildRegionByName(childArr, name)` to extract regions. Do NOT implement a custom helper that calls `child.getPConnect()` — children passed to page templates are rendered elements and do not expose `getPConnect` as a direct method. The SDK utility handles the internal format correctly.
+
+Extract the following named regions:
+
+- **Summary region:** `getChildRegionByName(childArr, 'summary')`
+- **Stages region:** `getChildRegionByName(childArr, 'stages')`
+- **ToDo region:** `getChildRegionByName(childArr, 'todo')`
+- **Utilities region:** `getChildRegionByName(childArr, 'utilities')`
+- **Tabs region:** `getChildRegionByName(childArr, 'tabs')`
+
+Render each extracted region directly in the template — they are already renderable elements.
+
+### Tabs Region — Deferred Load
+
+- Call `extractTabsInfo(theTabsRegion)` from `PCore.getSDKUtils().getSDKCaseUtils()` to build `vertTabInfo` (vertical tab definitions) and `deferLoadInfo` (deferred loading metadata).
+- Do NOT manually iterate tab children — the SDK utility handles this correctly.
+- Pass `vertTabInfo` to `VerticalTabs` component as its `tabconfig` prop.
+- Pass `deferLoadInfo[activeVertTab].config.name` to `DeferLoad` as its `name` prop.
+
+### displayOnlyFA Mode
+
+If `displayOnlyFA === true`:
+
+- Render only the ToDo region, centered.
+- Skip summary, stages, tabs, utilities rendering.
+
+### Attachments Subscription
+
+- Subscribe to `PCore.getPubSubUtils().subscribe(CASE_ATTACHMENTS_UPDATED, handleAttachmentUpdate, 'CaseView')`.
+- Track `hasNewAttachments` boolean state — passed to utilities region.
+- Unsubscribe on unmount.
+
+### Edit Action
+
+- The utilities region may include an edit action button.
+- On click: call `getPConnect().getActionsApi().openLocalAction(editActionId, { ... })`.
+
+## Visual Specifications
+
+### 3-Column Grid Layout
+
+> ⚠️ **CRITICAL LAYOUT RULE:** Stages MUST be in the CENTER column, NOT the sidebar.
+> The sidebar contains: case header card → summary → vertical tabs.
+> The center contains: stages → todo → deferred tab content.
+
+Three columns share the row: a 3/12-width sidebar column holding the case header card (title + ID), the Edit and Actions buttons, the summary region, and the vertical tabs; a 6/12-width main column holding the stages region, the to-do/assignment region, and the deferred tab content; and a 3/12-width utilities column holding the utilities region (attachments, etc.).
+
+| Column | Width | Contents                                                    |
+| ------ | ----- | ----------------------------------------------------------- |
+| Left   | 3/12  | Case header card, Summary, VerticalTabs                     |
+| Center | 6/12  | **Stages**, ToDo/assignment, DeferLoad (active tab content) |
+| Right  | 3/12  | Utilities region (attachments, etc.)                        |
+
+**CSS-only implementation notes:**
+
+- Outer grid: `display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 6fr) minmax(0, 3fr); gap: 1rem; width: 100%`.
+- Left column: `display: flex; flex-direction: column; gap: 0.5rem`.
+- Center column: `overflow: hidden`.
+- Responsive: on mobile (`max-width: 672px`), stack to single column.
+
+**Case header card CSS (MUST be included in companion styles):** the `.psdk-case-view` container is a CSS grid with columns `minmax(0, 3fr) minmax(0, 6fr) minmax(0, 3fr)`, a `1rem` gap, and full width; its direct children get `min-width: 0`; at `max-width: 672px` it collapses to a single column. The `.psdk-case-view-header` card has a light blue background (`#e3f2fd`), `4px` border radius, `1rem` padding, and `1rem` bottom margin; `.psdk-case-view-header-content` has `0.5rem` bottom margin; `.psdk-case-view-header-title` has no margin, `1.25rem` font size, medium weight, and a blue accent color (`#1565c0`); `.psdk-case-view-header-id` is smaller (`0.875rem`) and gray (`#555`); `.psdk-case-view-header-actions` is a flex row with `0.5rem` gap and centered items; `.psdk-case-view-edit-btn` is an unstyled, borderless, uppercase text button in blue (`#1976d2`, `0.875rem`, medium weight) with a subtle hover background (`rgba(25, 118, 210, 0.04)`).
+
+## Edge Cases & Special Logic
+
+- `displayOnlyFA === true` — completely different render tree (only ToDo), no grid layout.
+- Missing regions — guard each region before rendering; a region may not exist for all case types.
+- `DeferLoad` handles progressive loading — do not eagerly render all tab content.
+- `hasNewAttachments` is passed down to the utilities region — it affects attachment icon badge display.
+
+## Dependencies
+
+- `DeferLoad` component — resolved from the project's component registry; handles deferred tab content loading
+- `PCore.getPubSubUtils()` — pub/sub for attachment updates
+- The project's PConnect bridge utility — for rendering region children
+- `CASE_ATTACHMENTS_UPDATED` constant from PCore events API
+
+## Sub-Variants
+
+### ObjectPage
+
+`ObjectPage` is registered as a direct re-export module whose default export simply re-exports `CaseView`'s default export.
+
+- No separate implementation needed.
+- In the project's component map, register `ObjectPage` key pointing to the same component as `CaseView`.
+
+## Design System Mapping
+
+**UI control type:** Full case workspace layout — 3-column grid with sidebar, main content, and utilities.
+
+When implementing in a specific design system, map the following:
+
+- **Grid layout:** Use the design system's grid component with a 3/6/3 column ratio. For CSS-only, use CSS Grid with `grid-template-columns: minmax(0, 3fr) minmax(0, 6fr) minmax(0, 3fr)`.
+- **Sidebar container:** Use the design system's card or panel component to wrap the case header, summary, and vertical tabs.
+- **Deferred tabs:** Use the design system's tab component for the vertical tab list, paired with the DeferLoad component for lazy content rendering. The VerticalTabs component handles its own rendering — just pass `tabconfig` as the array of `{ name, id }` objects.
+- **Case header card:** A card with a light accent background, containing the case title, case ID, and action buttons.
+- **Action buttons:** Use the design system's button component (text/ghost variant for Edit, menu component for CaseViewActionsMenu).
+
+Regardless of design system:
+
+- `displayOnlyFA` must completely bypass the grid — render only ToDo region
+- Region extraction by metadata name is required — do not assume positional ordering
+- Deferred loading is mandatory for performance — tab content must not all load at once

package/templates/react-sdk-reference/.ai-common/skills/template-skills/CaseViewActionsMenu.md

@@ -0,0 +1,157 @@
+# Skill: CaseViewActionsMenu
+
+Case actions dropdown menu. Renders an "Actions" button that opens a menu of local actions and process actions for the current case.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a button that opens a dropdown menu containing all available case actions. Distinguishes between local actions (UI flow) and process actions (server-side), invoking the appropriate API for each. Shows a toast notification on process action error.
+
+## Pega Metadata
+
+- **Registration key:** `CaseViewActionsMenu` (in the project's component map)
+- **Category:** Page template — action menu
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Name                 | Type       | Required | Description                                    |
+| -------------------- | ---------- | -------- | ---------------------------------------------- |
+| `availableActions`   | `array`    | No       | Array of `{ ID, name }` local action objects   |
+| `availableProcesses` | `array`    | No       | Array of `{ ID, name }` process action objects |
+| `caseTypeID`         | `string`   | Yes      | Case type identifier for label localization    |
+| `caseTypeName`       | `string`   | Yes      | Case type display name for label localization  |
+| `getPConnect`        | `function` | Yes      | PConnect getter                                |
+
+## Implementation Structure
+
+> ⚠️ **CRITICAL — USE THE PROJECT'S DESIGN SYSTEM for the trigger button and menu items.**
+>
+> Check `package.json` for the installed design system. Use its button component (ghost/text variant) for the "Actions…" trigger. Use its menu/dropdown if available, otherwise use a positioned list with CSS.
+>
+> When implementing in a specific design system, map the following: the trigger button should use a text or ghost variant button from the installed library; the menu should use the library's dropdown/menu component if available; the toast notification should use the library's snackbar or toast primitive. When no design system is installed, use plain styled elements with a positioned list dropdown.
+>
+> ❌ **NEVER** use unstyled HTML elements when a design system is installed.
+>
+> The dropdown MUST include click-outside-to-close behavior via an instance reference on the container plus a `mousedown` document listener.
+
+**Module Setup:** The component needs local state (for menu open/closed and toast visibility), an instance reference (for click-outside detection), a lifecycle effect (for registering/cleaning up the outside-click listener), the project's base component interface, the installed design system's button component, and companion styles.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `getPConnect`, `availableActions` (default `[]`), `availableProcesses` (default `[]`), `caseTypeID` (default `''`), and `caseTypeName` (default `''`); call `getPConnect()` once into `thePConn`. Declare local state `open` (boolean, default `false`) and an instance reference for the menu container element.
+2. **Click-outside-to-close (mandatory):** in a lifecycle effect keyed on `open`, register a `mousedown` document listener while `open` is true that closes the menu when the click target falls outside the container reference; clean up the listener on unmount or when `open` changes.
+3. Define `handleActionClick(action)`: call `thePConn.getActionsApi().openLocalAction(action.ID, { ...action, containerName: 'modal', type: 'express' })`, then close the menu.
+4. Define `handleProcessClick(process)`: call `thePConn.getActionsApi().openProcessAction(process.ID, { ...process })` as a promise; on rejection show a toast with `"${process.name} Submit failed!"`; then close the menu.
+5. Compute `hasItems = availableActions.length > 0 || availableProcesses.length > 0`; render nothing when there are no items.
+6. Render a `psdk-actions-menu` container (attached to the instance reference) containing: the installed design system's button (ghost/text variant) labeled "Actions…", with `aria-haspopup="true"`, `aria-expanded` bound to `open`, and an `onClick` that toggles `open`; and, when `open` is true, a `psdk-actions-menu-dropdown` list (`role="menu"`) listing each `availableActions` entry as a `psdk-actions-menu-item` item (`role="menuitem"`, keyed by `action.ID`, showing the localized `action.name`, wired to `handleActionClick` on click and Enter keydown, with `tabIndex={0}`), followed by a `psdk-actions-menu-divider` separator when both action groups are non-empty, followed by each `availableProcesses` entry rendered the same way but wired to `handleProcessClick`.
+
+### Required companion styles (`CaseViewActionsMenu.css`)
+
+Create this file alongside the component with the following rules: `.psdk-actions-menu` is `position: relative; display: inline-block` (no trigger-button CSS needed since the DS button handles its own styling); `.psdk-actions-menu-dropdown` is absolutely positioned below the trigger (`top: 100%; left: 0`), with `z-index: 1000`, `min-width: 160px`, white background, `4px` border radius, a two-layer drop shadow, `0.25rem 0` padding, no margin, and no list bullets; `.psdk-actions-menu-item` has `0.5rem 1rem` padding, `0.875rem` font size, dark text color, and a pointer cursor, with a light-gray hover background and a visible focus outline (`2px solid`, `-2px` offset) on `:focus-visible`; `.psdk-actions-menu-divider` is a thin top border with `0.25rem 0` margin.
+
+## Behavioral Contract
+
+### Button Label
+
+- Localized via `PCore.getLocaleUtils().getLocaleValue('Actions...', 'CaseView')`.
+- Rendered as an outlined/secondary button with a dropdown indicator icon.
+
+### Menu Items
+
+The menu combines:
+
+1. **Local actions** — each item triggers `getPConnect().getActionsApi().openLocalAction(action.ID, { ...action, containerName: 'modal', type: 'express' })`.
+2. **Process actions** — each item triggers `getPConnect().getActionsApi().openProcessAction(process.ID, { ...process })`.
+
+If both groups exist, render a divider between them.
+
+### Localized Action Labels
+
+For localized case type context, build a `localeKey` string as `${caseTypeID}!CASE!${caseTypeName}`.toUpperCase().
+
+Action name localization: `PCore.getLocaleUtils().getLocaleValue(action.name, '', localeKey)`.
+
+### Process Action Error Handling
+
+1. On process action click, invoke the API as a promise.
+2. On rejection: show a toast notification with `"${process.name} Submit failed!"`.
+3. Toast auto-hides after 3000ms.
+4. Toast should include a close/dismiss button.
+
+### Menu State
+
+- `open` boolean local state controls menu visibility.
+- An instance reference wraps the entire menu container.
+- On `open === true`, add a `mousedown` document listener to detect clicks outside the container reference and close.
+- Remove the listener on cleanup or when `open` becomes false.
+- **DO NOT** use an anchor-element pattern unless the design system provides a dedicated menu component. For CSS-only, use the `open` boolean + absolute positioning.
+
+## Visual Specifications
+
+### Button
+
+| Property | Value                           |
+| -------- | ------------------------------- |
+| Label    | Localized `"Actions..."`        |
+| Variant  | Outlined or secondary           |
+| Icon     | Dropdown chevron or expand_more |
+
+### Menu
+
+| Property    | Value                                   |
+| ----------- | --------------------------------------- |
+| Position    | Anchored below the button               |
+| Divider     | Between local and process action groups |
+| Item height | Standard menu item height               |
+
+**CSS-only implementation notes:**
+
+- Button: `padding: 6px 12px; border: 1px solid var(--app-primary-color); border-radius: 4px; cursor: pointer`.
+- Dropdown menu: `position: absolute; background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.2); border-radius: 4px; min-width: 160px; z-index: 1000`.
+- Menu item: `padding: 8px 16px; cursor: pointer`. Hover: `background: var(--hover-bg)`.
+- Divider: `border-top: 1px solid var(--divider-color); margin: 4px 0`.
+
+### Toast Notification
+
+| Property  | Value                         |
+| --------- | ----------------------------- |
+| Position  | Bottom-center or bottom-right |
+| Auto-hide | 3000ms                        |
+| Severity  | Error (red)                   |
+| Dismiss   | Close button                  |
+
+## Edge Cases & Special Logic
+
+- If both `availableActions` and `availableProcesses` are empty, render nothing (return null).
+- `caseTypeName.toUpperCase()` — guard against `undefined`/`null` values.
+- Process action errors may include HTML — sanitize before displaying in the toast message.
+- Menu should close on any item click (both local and process).
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — label localization
+- `getPConnect().getActionsApi()` — local action and process action invocation
+- The project's base component interface
+- The installed design system's button, menu, and toast components (check `package.json`)
+
+## Design System Mapping
+
+**UI control type:** Dropdown action menu with button trigger and toast error notification.
+
+When implementing in a specific design system, map the following:
+
+- **Trigger button:** Use the design system's text or ghost-variant button. The button label is the localized "Actions..." string. It must support `aria-haspopup` and `aria-expanded` attributes.
+- **Menu/Dropdown:** Use the design system's menu or dropdown primitive if available. If none exists, use a positioned list with CSS and manual open/close logic. Items must support click handlers and keyboard activation (Enter key).
+- **Divider:** Use the design system's divider or separator between the local actions group and the process actions group.
+- **Toast notification:** Use the design system's snackbar or toast component to surface process action errors. Must auto-hide after 3000ms and include a dismiss/close button.
+- **Click-outside-to-close:** If the design system's menu handles this natively, rely on that. Otherwise implement manually with an instance reference and a document `mousedown` listener.
+
+Key constraints regardless of design system:
+
+- Local vs process action distinction must be preserved — they call different APIs
+- Localized labels via `localeKey = ${caseTypeID}!CASE!${caseTypeName}`.toUpperCase()
+- Process action errors must be surfaced via a dismissible toast

package/templates/react-sdk-reference/.ai-common/skills/template-skills/Confirmation.md

@@ -0,0 +1,149 @@
+# Skill: Confirmation
+
+Case confirmation template. Renders the post-submission confirmation view with a Done button, optionally showing ToDo assignments that remain after the case is submitted.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> The close event MUST use `PCore.getContainerUtils()` to get the proper container info for the pub/sub payload. Without this, the confirmation view won't close properly and the case won't transition correctly.
+>
+> **Mandatory implementation details:**
+>
+> 1. `PCore.getContainerUtils().getActiveContainerItemName(getPConnect().getTarget())` — gets active container item
+> 2. `PCore.getContainerUtils().getContainerItemData(target, activeItemID)` — gets root info for close event
+> 3. `PCore.getPubSubUtils().publish(CONSTS.PUB_SUB_EVENTS.CASE_EVENTS.CLOSE_CONFIRM_VIEW, rootInfo)` — proper close event with payload
+> 4. Look up the `'Details'` component from the project's component registry — for rendering case details in confirmation
+> 5. `getToDoAssignments(getPConnect())` — from `PCore.getSDKUtils().getSDKContainerUtils()`
+> 6. Check `showDetails` before rendering Details component
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `PCore.getContainerUtils()` used for close event (NOT a simple toggle of local state)
+> - [ ] `rootInfo` passed to `CLOSE_CONFIRM_VIEW` pub/sub event
+> - [ ] Details component rendered when `showDetails` is true
+> - [ ] ToDo component rendered with `getToDoAssignments` when `showTasks` is true
+> - [ ] Two render states: confirmation view (with Done button) and post-close (just ToDo if any)
+
+---
+
+## Component Purpose
+
+Displayed after a case or assignment is submitted. Shows the confirmation view (with `Details` region) and a Done button. If outstanding ToDo assignments remain after the user clicks Done, they are displayed. When the user truly finishes, publishes `CLOSE_CONFIRM_VIEW` to close the container.
+
+## Pega Metadata
+
+- **Registration key:** `Confirmation` (in the project's component map)
+- **Category:** Page template — confirmation
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input         | Type               | Required | Description                                                                   |
+| ------------- | ------------------ | -------- | ----------------------------------------------------------------------------- |
+| `children`    | child element list | Yes      | Region children: `[0]` = ToDo region, `[1]` = Details region (when available) |
+| `getPConnect` | function           | Yes      | PConnect getter                                                               |
+| `datasource`  | object             | No       | Shape `{ source: any }` — what's-next data source                             |
+| `label`       | string             | No       | Confirmation heading text                                                     |
+| `showLabel`   | boolean            | No       | Whether to render the heading label                                           |
+| `showTasks`   | boolean            | No       | Whether to render outstanding ToDo assignments                                |
+
+## Implementation Structure
+
+**Module Setup:** This component needs the project's base component interface for typing, the project's component registry for retrieving `ToDo` and `Details` dynamically, and a local state primitive for tracking the confirm-view toggle. Define a companion styles block with padding and margin (1 spacing unit on all sides) applied to the card wrapper.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `ToDo` from the project's component registry using the key `'Todo'` (note the capitalization — not `'ToDo'`), and `Details` similarly using `'Details'`.
+2. Set `CONSTS = PCore.getConstants()`; declare local state `showConfirmView` initialized to `true`; receive inputs `showTasks`, `getPConnect`, `showLabel`, and `label`.
+3. Get the active container and root info: `activeContainerItemID = PCore.getContainerUtils().getActiveContainerItemName(getPConnect().getTarget() || '')`, then `rootInfo = PCore.getContainerUtils().getContainerItemData(getPConnect().getTarget(), activeContainerItemID)`.
+4. Get pending ToDo assignments: destructure `getToDoAssignments` from `PCore.getSDKUtils().getSDKContainerUtils()`, then call `toDoList = getToDoAssignments(getPConnect())`.
+5. Define the Done-button handler `onConfirmViewClose`: set `showConfirmView` to `false`, then publish `PCore.getPubSubUtils().publish(PCore.getConstants().PUB_SUB_EVENTS.CASE_EVENTS.CLOSE_CONFIRM_VIEW, rootInfo)`.
+6. Compute `showDetails` by checking whether the first child's nested PConnect has children: `children?.[0]` → get its `getPConnect()` → call `getChildren()` → check `length > 0`.
+7. **Render — confirm view:** if `showConfirmView` is true, render a card container (with companion styles) containing: a heading with the label (when `showLabel` is true); the Details component (with `showLabel` set to false) when `showDetails` is true; the ToDo component (with `datasource: { source: toDoList }`, `getPConnect`, `type: CONSTS.TODO`, `headerText: "Open Tasks"`, `isConfirm: true`) when `showTasks` is true and `toDoList` is non-empty; and a primary Done button aligned to the end, wired to `onConfirmViewClose`.
+8. **Render — post-close:** otherwise, if `toDoList` is non-empty, render a card container containing just the ToDo component (same inputs as above but `headerText: "Tasks"`); if `toDoList` is empty, render nothing.
+
+## Behavioral Contract
+
+### State
+
+- `showConfirmView`: boolean local state, initially `true`.
+- `toDoAssignments`: array from `getToDoAssignments(getPConnect())` — pending assignments.
+
+### Done Button Click
+
+1. Set `showConfirmView` local state to `false`.
+2. Publish `PCore.getPubSubUtils().publish(PCore.getConstants().PUB_SUB_EVENTS.CASE_EVENTS.CLOSE_CONFIRM_VIEW, rootInfo)`.
+3. The `rootInfo` payload is derived from `PCore.getContainerUtils().getContainerItemData(target, activeContainerItemID)` — this is mandatory for correct container closure.
+
+### Show Details
+
+- `showDetails`: true when the first child region's PConnect has children (i.e., there is content to display in the Details area).
+
+### Render: Confirm View (showConfirmView is true)
+
+1. Confirmation heading label (when `showLabel` is true).
+2. If `showDetails`: render the Details component retrieved from the project's component registry with `showLabel` set to false, passing the current component's inputs.
+3. If `showTasks` and `toDoList` is non-empty: render the ToDo component with `datasource: { source: toDoList }`, `type: CONSTS.TODO`, `headerText: "Open Tasks"`, `isConfirm: true`.
+4. Done button (primary action) — triggers `onConfirmViewClose`.
+
+### Render: Post-Close View (showConfirmView is false)
+
+- If `toDoList` is non-empty: render a card with the ToDo component (`headerText: "Tasks"`, same core inputs).
+- If `toDoList` is empty: render nothing.
+
+## Visual Specifications
+
+### Confirm View
+
+| Element             | Description                                   |
+| ------------------- | --------------------------------------------- |
+| Confirmation header | Heading text (label) when showLabel is true   |
+| Details section     | Optional — rendered below confirmation header |
+| Done button         | Primary button, aligned to end of the form    |
+
+**CSS-only implementation notes:**
+
+- Card wrapper: padding and margin of 1 spacing unit on all sides.
+- Done button container: `display: flex; justify-content: flex-end`.
+- Confirmation heading: rendered as a level-2 heading element.
+
+### ToDo View
+
+- Full-width ToDo region rendered in place of confirmation inside a card wrapper.
+- No additional wrapping — render the region directly.
+
+## Edge Cases & Special Logic
+
+- `getToDoAssignments(getPConnect())` — returns empty array if no assignments remain; when empty in post-close state, renders nothing.
+- The first child region may not have Details content — always check `showDetails` before rendering the Details component.
+- `CLOSE_CONFIRM_VIEW` is a PubSub constant — ensure it matches the consuming container's subscription key.
+- The confirmation view should not be navigable backward — Done is the only exit.
+- The ToDo registry key is `'Todo'` (capital T, lowercase odo) — this is the ConstellationJS Engine convention.
+
+## Dependencies
+
+- The project's component registry — for retrieving `'Todo'` and `'Details'` components dynamically at runtime
+- `PCore.getSDKUtils().getSDKContainerUtils().getToDoAssignments` — for retrieving pending assignments
+- `PCore.getPubSubUtils().publish()` — for the CLOSE_CONFIRM_VIEW event
+- `PCore.getContainerUtils()` — for container item management (active item name + container item data)
+- `PCore.getConstants()` — for PubSub event keys and TODO type constant
+
+## Design System Mapping
+
+**UI control type:** Post-submission confirmation page with done action and optional todo view.
+
+When implementing in a specific design system, map the following:
+
+- **Card wrapper:** Use the design system's card or surface container component with standard padding/margin.
+- **Done button:** Use the design system's primary action button component.
+- **Heading:** Use a level-2 heading or the design system's title typography component.
+- **Layout:** A vertical flex column layout containing heading, optional details, optional todo list, and the done button at the end.
+
+Implementation constraints regardless of design system:
+
+- Done button must trigger `onConfirmViewClose` which both toggles local state and publishes the `CLOSE_CONFIRM_VIEW` event with `rootInfo`
+- `showDetails` check must guard Details component rendering
+- ToDo component receives `isConfirm: true` to signal it is rendered within a confirmation context