@pega/sdk 0.0.4 → 0.0.5

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

@@ -0,0 +1,399 @@
+# 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()` helper — extract regions by metadata name, NOT by array index
+> 2. `getComponentFromRegistry('VerticalTabs')` — for tab navigation in the sidebar
+> 3. `getComponentFromRegistry('DeferLoad')` — for lazy-loading tab content
+> 4. `getComponentFromRegistry('CaseViewActionsMenu')` — for case actions
+> 5. `useEffect` for `VerticalTabClick` event listener (add + remove on unmount)
+> 6. `useEffect` for `hasNewAttachments` → publish `CASE_ATTACHMENTS_UPDATED`
+> 7. `displayOnlyFA` check from `useContext(StoreContext)` — renders only todo region in focused action mode
+> 8. `activeVertTab` state for tracking which tab is selected
+> 9. `vertTabInfo` + `deferLoadInfo` arrays built from tabs region children — **`vertTabInfo` MUST be `{ name: string; id: number }[]`, NOT a React element**
+> 10. 3-column grid layout: sidebar (3) + main content (6) + utilities (3)
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `getChildRegionByName()` helper function defined
+> - [ ] All 5 named regions extracted: summary, stages, todo, utilities, tabs
+> - [ ] **Case header card** rendered at top of sidebar with: title (`header` prop), 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
+> - [ ] useEffect for VerticalTabClick event
+> - [ ] useEffect 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` — `export { default } from '../CaseView'`. 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:** `PConnProps`
+
+## Props
+
+| Prop            | Type          | Required | Description                                                    |
+| --------------- | ------------- | -------- | -------------------------------------------------------------- |
+| `children`      | `ReactNode[]` | 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                                                |
+
+## Component Skeleton
+
+```typescript
+import { type PropsWithChildren, type ReactElement, useContext, useEffect, useState } from 'react';
+import { PegaStoreContext as StoreContext, getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+import { Utils } from '../../helpers/utils';
+
+interface CaseViewProps extends PConnProps {
+  icon: string;
+  subheader: string;
+  header: string;
+  showIconInHeader: boolean;
+  caseInfo: any;
+  lastUpdateCaseTime: any;
+}
+
+export default function CaseView(props: PropsWithChildren<CaseViewProps>) {
+  // 1. Registry lookups
+  const CaseViewActionsMenu = getComponentFromRegistry('CaseViewActionsMenu');
+  const VerticalTabs = getComponentFromRegistry('VerticalTabs');
+  const DeferLoad = getComponentFromRegistry('DeferLoad');
+
+  // 2. Destructure props
+  const {
+    getPConnect, icon = '', header, subheader, children = [],
+    caseInfo: { availableActions = [], availableProcesses = [],
+      hasNewAttachments, caseTypeID = '', caseTypeName = '', caseTypeIcon },
+  } = props;
+  const { lastUpdateCaseTime = getPConnect().getValue('caseInfo.lastUpdateTime') } = props;
+  const currentCaseID = props.caseInfo.ID;
+  const { displayOnlyFA } = useContext<any>(StoreContext);
+  const thePConn = getPConnect();
+
+  // 3. Extract named regions from children by metadata type+name
+  //    IMPORTANT: children may be a single element or array — normalize first
+  const childArr = Array.isArray(children) ? children : [children].filter(Boolean);
+  function getChildRegionByName(inName: string): any {
+    for (const child of childArr as ReactElement[]) {
+      const meta = (child as any)?.props?.getPConnect?.()?.getRawMetadata?.();
+      if (meta?.type?.toLowerCase() === 'region' && meta?.name?.toLowerCase() === inName)
+        return child;
+    }
+    return null;
+  }
+  const theSummaryRegion = getChildRegionByName('summary');
+  const theStagesRegion = getChildRegionByName('stages');
+  const theTodoRegion = getChildRegionByName('todo');
+  const theUtilitiesRegion = getChildRegionByName('utilities');
+  const theTabsRegion = getChildRegionByName('tabs');
+
+  // 4. Build tab info + deferred load info from tabs region children
+  //    ⚠️ CRITICAL: vertTabInfo MUST be an array of { name, id } objects.
+  //    DO NOT pass the React element (theTabsRegion) directly to <VerticalTabs tabconfig={...}>.
+  //    VerticalTabs calls tabconfig.map() — passing a React element causes:
+  //    "TypeError: tabconfig.map is not a function"
+  //
+  //    ⚠️ CRITICAL: vertTabInfo and deferLoadInfo MUST be TWO SEPARATE arrays.
+  //    - vertTabInfo stores { name: LABEL, id } — the DISPLAY LABEL for VerticalTabs UI
+  //    - deferLoadInfo stores { config } — the FULL CONFIG object including config.name
+  //    - DeferLoad's `name` prop MUST use deferLoadInfo[activeTab].config.name
+  //      (the VIEW RULE NAME, e.g., "pyDetailsTabContent")
+  //    - DO NOT pass the display label (e.g., "Details") to DeferLoad — it causes:
+  //      "View not found for the given parameter ID" (404 on /views/Details/refresh)
+  //    - config.label = "Details" (display) ≠ config.name = "pyDetailsTabContent" (view rule)
+  //    DO NOT collapse these into a single array. They serve different purposes.
+  const vertTabInfo: { name: string; id: number }[] = [];
+  const deferLoadInfo: any[] = [];
+  const tabChildren = theTabsRegion?.props?.getPConnect?.().getChildren?.() ?? [];
+  tabChildren.forEach((tabComp, index) => {
+    const config = tabComp.getPConnect?.().getConfigProps?.() ?? tabComp.getPConnect?.().getRawMetadata?.()?.config ?? {};
+    let label = config.label || '';
+    if (!label && config.inheritedProps) config.inheritedProps.forEach(ip => { if (ip.prop === 'label') label = ip.value; });
+    if (config.visibility === undefined || config.visibility === true) {
+      vertTabInfo.push({ name: label || `Tab ${index + 1}`, id: index });
+      deferLoadInfo.push({ type: 'DeferLoad', config });
+    }
+  });
+
+  const [activeVertTab, setActiveVertTab] = useState(0);
+  // editAction is data-driven — comes from the availableActions array in the network response.
+  // The ID 'pyUpdateCaseDetails' is a common Pega convention but may differ per case type.
+  // If this action exists, render a shortcut button in the header; label is localized.
+  const editAction = availableActions.find(a => a.ID === 'pyUpdateCaseDetails');
+
+  // 5. useEffect: VerticalTabClick event listener (DOM event, not PubSub)
+  useEffect(() => {
+    const handler = (event) => { const idx = parseInt(event?.detail?.additionalData?.itemClicked ?? event, 10); if (!isNaN(idx)) setActiveVertTab(idx); };
+    document.addEventListener('VerticalTabClick', handler);
+    return () => document.removeEventListener('VerticalTabClick', handler);
+  }, []);
+  // 6. useEffect: publish CASE_ATTACHMENTS_UPDATED on hasNewAttachments
+  useEffect(() => { if (hasNewAttachments) PCore.getPubSubUtils().publish((PCore.getEvents().getCaseEvent()).CASE_ATTACHMENTS_UPDATED_FROM_CASEVIEW, true); }, [hasNewAttachments]);
+
+  // 7. Edit action click handler
+  function _editClick() {
+    const actionsAPI = thePConn.getActionsApi();
+    actionsAPI.openLocalAction(editAction.ID, {
+      ...editAction, containerName: 'modal', type: 'express',
+    });
+  }
+
+  // 8. Render
+  //    ⚠️ CRITICAL — USE THE PROJECT'S DESIGN SYSTEM for buttons and header card.
+  //    Check `package.json` for the installed DS and use its button component (ghost/text variant).
+  //    NEVER use plain HTML <button> — always use the DS button.
+  //    Localize labels: PCore.getLocaleUtils().getLocaleValue('Edit', 'CaseView')
+  //
+  //    Examples of known design systems (check package.json for actual installed DS):
+  //    | DS | Action Button | Header Background |
+  //    |---|---|---|
+  //    | @carbon/react | <Button kind="ghost" size="sm"> | use $blue-10 token or #e3f2fd |
+  //    | @mui/material | <Button variant="text"> | theme.palette.info.light |
+  //    | antd | <Button type="link"> | token blue-1 |
+  //    | CSS-only | <button> with styled class | #e3f2fd |
+  if (displayOnlyFA) {
+    return <div>{theTodoRegion}</div>;
+  }
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  return (
+    <div className='psdk-case-view'>
+      <aside>
+        <div hidden id='current-caseID'>{currentCaseID}</div>
+        {/* Case header card — themed background, DS buttons, localized labels */}
+        <div className='psdk-case-view-header'>
+          <div className='psdk-case-view-header-content'>
+            <h2 className='psdk-case-view-header-title'>{header}</h2>
+            {subheader && <span className='psdk-case-view-header-id'>{subheader}</span>}
+          </div>
+          <div className='psdk-case-view-header-actions'>
+            {/* Action buttons are DATA-DRIVEN from availableActions (network response).
+                The edit shortcut uses a known Pega action ID but could be any action.
+                Labels MUST be localized — never hardcode button text. */}
+            {editAction && (
+              <DSButton variant='ghost' onClick={_editClick}>{localizedVal('Edit', 'CaseView')}</DSButton>
+            )}
+            {/* CaseViewActionsMenu renders ALL available actions + processes as dropdown items */}
+            {CaseViewActionsMenu && (
+              <CaseViewActionsMenu
+                getPConnect={getPConnect}
+                availableActions={availableActions}
+                availableProcesses={availableProcesses}
+                caseTypeID={caseTypeID}
+                caseTypeName={caseTypeName}
+              />
+            )}
+          </div>
+        </div>
+        {theSummaryRegion}
+        {vertTabInfo.length > 1 && <VerticalTabs tabconfig={vertTabInfo} />}
+      </aside>
+      <main>
+        {/* ⚠️ STAGES MUST be in the CENTER column, above ToDo — NOT in the sidebar */}
+        {theStagesRegion}
+        {theTodoRegion}
+        {deferLoadInfo.length > 0 && deferLoadInfo[activeVertTab] && <DeferLoad getPConnect={getPConnect}
+          name={deferLoadInfo[activeVertTab].config.name} isTab
+          lastUpdateCaseTime={lastUpdateCaseTime} />}
+      </main>
+      <aside>{theUtilitiesRegion}</aside>
+    </div>
+  );
+}
+```
+
+> **Note:** `ObjectPage` is a re-export: `export { default } from '../CaseView'`. Register both keys to the same component.
+
+## Behavioral Contract
+
+### Region Extraction
+
+Use `getRawMetadata()` to access `children` with `type` and `name` metadata. Extract by:
+
+- **Summary region:** `type === 'Region' && name === 'Summary'`
+- **Stages region:** `type === 'Region' && name === 'Stages'`
+- **ToDo region:** `type === 'Region' && name === 'ToDo'`
+- **Utilities region:** `type === 'Region' && name === 'Utilities'`
+- **Tabs region:** `type === 'Region' && name === 'Tabs'`
+
+Render each region as a React child element using `createElement(PConnectComponent, { ...regionConfig })`.
+
+### Tabs Region — Deferred Load
+
+- From the Tabs region children, build `vertTabInfo` (vertical tab definitions) and `deferLoadInfo` (deferred loading metadata).
+- Pass both to `<DeferLoad>` component which handles lazy rendering of tab content.
+- The tabs list comes from `theTabsRegionChildren` (the children of the Tabs region).
+
+### 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.
+
+```
+[Col xs:3 — Sidebar]     [Col xs:6 — Main]         [Col xs:3 — Utilities]
+ Case Header Card         Stages                    Utilities region
+ (title + ID)             ToDo / Assignment
+ (Edit + Actions btns)    DeferLoad tab content
+ Summary region
+ VerticalTabs
+```
+
+| Column | xs  | Contents                                                    |
+| ------ | --- | ----------------------------------------------------------- |
+| Left   | 3   | Case header card, Summary, VerticalTabs                     |
+| Center | 6   | **Stages**, ToDo/assignment, DeferLoad (active tab content) |
+| Right  | 3   | 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 `CaseView.css`):**
+
+```css
+.psdk-case-view {
+  display: grid;
+  grid-template-columns: minmax(0, 3fr) minmax(0, 6fr) minmax(0, 3fr);
+  gap: 1rem;
+  width: 100%;
+}
+.psdk-case-view aside,
+.psdk-case-view main {
+  min-width: 0;
+}
+@media (max-width: 672px) {
+  .psdk-case-view {
+    grid-template-columns: 1fr;
+  }
+}
+.psdk-case-view-header {
+  background-color: #e3f2fd;
+  border-radius: 4px;
+  padding: 1rem;
+  margin-bottom: 1rem;
+}
+.psdk-case-view-header-content {
+  margin-bottom: 0.5rem;
+}
+.psdk-case-view-header-title {
+  margin: 0;
+  font-size: 1.25rem;
+  font-weight: 500;
+  color: #1565c0;
+}
+.psdk-case-view-header-id {
+  font-size: 0.875rem;
+  color: #555;
+}
+.psdk-case-view-header-actions {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}
+.psdk-case-view-edit-btn {
+  background: none;
+  border: none;
+  color: #1976d2;
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+  text-transform: uppercase;
+  padding: 0.25rem 0.5rem;
+}
+.psdk-case-view-edit-btn:hover {
+  background-color: 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 from `@pega/sdk-react` — deferred tab content loading
+- `PCore.getPubSubUtils()` — pub/sub for attachment updates
+- `PConnectComponent` from `@pega/sdk-react`
+- `CASE_ATTACHMENTS_UPDATED` constant from `@pega/sdk-core` (or local constants)
+
+## Sub-Variants
+
+### ObjectPage
+
+`ObjectPage` is registered as:
+
+```tsx
+// packages/sdk-react/src/components/template/ObjectPage/index.tsx
+export { default } from '../CaseView';
+```
+
+- No separate implementation needed.
+- In `component-map.ts`, 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.
+
+Listed design systems are examples only.
+
+| Design System      | Grid                                                  | Sidebar   | Deferred Tabs                   |
+| ------------------ | ----------------------------------------------------- | --------- | ------------------------------- |
+| Default (CSS only) | CSS Grid 25/50/25                                     | `<aside>` | Intersection Observer lazy load |
+| MUI                | `<Grid container>` with `<Grid size={{ xs: 3/6/3 }}>` | `<Box>`   | MUI `<Tabs>` + DeferLoad        |
+| Ant Design         | `<Row><Col span={6/12/6}>`                            | `<Sider>` | `<Tabs>` lazy                   |
+| Chakra UI          | `<Grid templateColumns='1fr 2fr 1fr'>`                | `<Box>`   | Custom lazy tabs                |
+| Shadcn/ui          | Tailwind `grid grid-cols-[1fr_2fr_1fr]`               | `<aside>` | Custom                          |
+
+When implementing in a specific 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,282 @@
+# 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 Snackbar toast on process action error.
+
+## Pega Metadata
+
+- **Registration key:** `CaseViewActionsMenu` (in `component-map.ts`)
+- **Category:** Page template — action menu
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop             | Type       | Required | Description                                    |
+| ---------------- | ---------- | -------- | ---------------------------------------------- |
+| `localActions`   | `array`    | No       | Array of `{ ID, name }` local action objects   |
+| `processActions` | `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                                |
+
+## Component Skeleton
+
+> ⚠️ **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 `<ul>/<li>` list with CSS.
+>
+> Examples of known design systems (check `package.json` for actual installed DS):
+>
+> | DS                 | Trigger Button                    | Menu Items                             |
+> | ------------------ | --------------------------------- | -------------------------------------- |
+> | `@carbon/react`    | `<Button kind="ghost" size="sm">` | `<ul>/<li>` with CSS or `OverflowMenu` |
+> | `@mui/material`    | `<Button variant="text">`         | `<Menu>` + `<MenuItem>`                |
+> | `antd`             | `<Button type="link">`            | `<Dropdown>` + `<Menu>`                |
+> | `@chakra-ui/react` | `<Button variant="ghost">`        | `<Menu>` + `<MenuItem>`                |
+> | None / CSS-only    | `<button>` with styled class      | `<ul>/<li>` with CSS                   |
+>
+> ❌ **NEVER** use unstyled HTML `<button>` elements when a DS is installed.
+>
+> The dropdown MUST include click-outside-to-close behavior via a `useRef` + `mousedown` listener.
+
+```typescript
+import { useState, useRef, useEffect } from 'react';
+import type { PConnProps } from '@pega/sdk-react';
+// Import your DS button here — e.g.:
+// import { Button } from '@carbon/react';
+// import { Button } from '@mui/material';
+import './CaseViewActionsMenu.css';
+
+interface CaseViewActionsMenuProps extends PConnProps {
+  availableActions?: any[];
+  availableProcesses?: any[];
+  caseTypeID?: string;
+  caseTypeName?: string;
+}
+
+export default function CaseViewActionsMenu(props: CaseViewActionsMenuProps) {
+  const { getPConnect, availableActions = [], availableProcesses = [], caseTypeID = '', caseTypeName = '' } = props;
+  const thePConn = getPConnect();
+  const [open, setOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // Click-outside-to-close — MANDATORY
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    }
+    if (open) document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, [open]);
+
+  // Local action click — openLocalAction with modal container
+  function handleActionClick(action: any) {
+    (thePConn.getActionsApi() as any).openLocalAction(action.ID, {
+      ...action, containerName: 'modal', type: 'express',
+    });
+    setOpen(false);
+  }
+
+  // Process action click — openProcessAction
+  function handleProcessClick(process: any) {
+    (thePConn.getActionsApi() as any).openProcessAction(process.ID, { ...process });
+    setOpen(false);
+  }
+
+  const hasItems = availableActions.length > 0 || availableProcesses.length > 0;
+  if (!hasItems) return null;
+
+  return (
+    <div className='psdk-actions-menu' ref={menuRef}>
+      {/* Use the installed DS button component (ghost/text variant) — NOT plain <button> */}
+      <DSButton
+        variant='ghost'
+        size='sm'
+        onClick={() => setOpen(!open)}
+        aria-haspopup='true'
+        aria-expanded={open}
+      >
+        Actions&hellip;
+      </DSButton>
+      {open && (
+        <ul className='psdk-actions-menu-dropdown' role='menu'>
+          {availableActions.map((action: any) => (
+            <li className='psdk-actions-menu-item' role='menuitem'
+              key={action.ID} onClick={() => handleActionClick(action)}
+              onKeyDown={(e) => { if (e.key === 'Enter') handleActionClick(action); }}
+              tabIndex={0}>{action.name}</li>
+          ))}
+          {availableActions.length > 0 && availableProcesses.length > 0 && (
+            <li className='psdk-actions-menu-divider' role='separator' />
+          )}
+          {availableProcesses.map((process: any) => (
+            <li className='psdk-actions-menu-item' role='menuitem'
+              key={process.ID} onClick={() => handleProcessClick(process)}
+              onKeyDown={(e) => { if (e.key === 'Enter') handleProcessClick(process); }}
+              tabIndex={0}>{process.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Required CSS file (`CaseViewActionsMenu.css`)
+
+The following CSS MUST be created alongside the component:
+
+```css
+.psdk-actions-menu {
+  position: relative;
+  display: inline-block;
+}
+/* No trigger button CSS needed — the DS button component handles its own styling */
+.psdk-actions-menu-dropdown {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 1000;
+  min-width: 160px;
+  background: #fff;
+  border-radius: 4px;
+  box-shadow:
+    0 2px 8px rgba(0, 0, 0, 0.15),
+    0 1px 3px rgba(0, 0, 0, 0.1);
+  padding: 0.25rem 0;
+  margin: 0;
+  list-style: none;
+}
+.psdk-actions-menu-item {
+  padding: 0.5rem 1rem;
+  font-size: 0.875rem;
+  color: #161616;
+  cursor: pointer;
+}
+.psdk-actions-menu-item:hover {
+  background-color: #e5e5e5;
+}
+.psdk-actions-menu-item:focus-visible {
+  outline: 2px solid #0f62fe;
+  outline-offset: -2px;
+}
+.psdk-actions-menu-divider {
+  border-top: 1px solid #e0e0e0;
+  margin: 0.25rem 0;
+}
+```
+
+## Behavioral Contract
+
+### Button Label
+
+- Localized via `PCore.getLocaleUtils().getLocaleValue('Actions', 'CaseView', 'Actions')`.
+- 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, { caseID: getPConnect().getCaseInfo().getID() })`.
+2. **Process actions** — each item triggers `getPConnect().getActionsApi().openProcessAction(action.ID, { ... })`.
+
+If both groups exist, render a divider between them.
+
+### Localized Action Labels
+
+For localized case type context:
+
+```
+localeKey = `${caseTypeID}!CASE!${caseTypeName.toUpperCase()}`
+```
+
+Action name localization: `PCore.getLocaleUtils().getLocaleValue(action.name, localeKey, action.name)`.
+
+### Process Action Error Handling
+
+1. On process action click, wrap in `try/catch`.
+2. On error: show Snackbar toast with the error message.
+3. Snackbar auto-hides after 3000ms.
+
+### Menu State
+
+- `open` boolean state controls menu visibility.
+- A `useRef<HTMLDivElement>` wraps the entire menu container.
+- On `open === true`, add a `mousedown` document listener to detect clicks outside the `ref` and close.
+- Remove the listener on cleanup or when `open` becomes false.
+- **DO NOT** use `anchorEl` pattern unless the design system provides a `Menu` component (like MUI). 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`.
+
+### Snackbar Toast
+
+| Property  | Value                         |
+| --------- | ----------------------------- |
+| Position  | Bottom-center or bottom-right |
+| Auto-hide | 3000ms                        |
+| Severity  | Error (red)                   |
+
+## Edge Cases & Special Logic
+
+- If both `localActions` and `processActions` are empty, the "Actions" button may be hidden or disabled.
+- `caseTypeName.toUpperCase()` — guard against `undefined`/`null` values.
+- Process action errors may include HTML — sanitize before displaying in the Snackbar message.
+- Menu should close on any item click (both local and process).
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — label localization
+- `PConnectComponent` from `@pega/sdk-react`
+- MUI: `<Button>`, `<Menu>`, `<MenuItem>`, `<Divider>`, `<Snackbar>`
+
+## Design System Mapping
+
+**UI control type:** Dropdown action menu with button trigger and toast error notification.
+
+Listed design systems are examples only.
+
+| Design System      | Button                                 | Menu                 | Toast                         |
+| ------------------ | -------------------------------------- | -------------------- | ----------------------------- |
+| Default (CSS only) | `<button>` + custom dropdown           | `<ul>/<li>` with CSS | Custom toast overlay          |
+| MUI                | `<Button>` + `<Menu>/<MenuItem>`       | MUI Menu             | `<Snackbar>/<Alert>`          |
+| Ant Design         | `<Dropdown menu={{ items }}>`          | Ant Dropdown         | `message.error()`             |
+| Chakra UI          | `<Menu>/<MenuButton>/<MenuList>`       | Chakra Menu          | `useToast()`                  |
+| Shadcn/ui          | `<DropdownMenu>/<DropdownMenuTrigger>` | Shadcn DropdownMenu  | `<Toaster>` + `toast.error()` |
+
+When implementing in a specific 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