@pega/sdk 0.0.5 → 0.0.7

package/templates/react-sdk-reference/.ai-common/skills/field-skills/CancelAlert.md

@@ -2,7 +2,7 @@
 
 Cancel confirmation dialog that offers the user a choice between going back or discarding/deleting the current case/action.
 
-> **Note:** This component extends `PConnFieldProps` for registry compatibility but does **not** use standard field patterns (no `displayMode`, no `handleEvent`, no value binding). It is an internal modal dialog.
+> **Note:** This component extends the project's field input contract for registry compatibility but does **not** use standard field patterns (no `displayMode`, no event-commit utility, no value binding). It is an internal modal dialog.
 
 ---
 
@@ -14,9 +14,9 @@ Renders a full-screen modal overlay with a confirmation dialog. Presents two act
 
 - **Pega Name:** `CancelAlert`
 - **Type / Subtype:** Internal modal/alert
-- **Registration key:** `CancelAlert` (in `component-map.ts`)
+- **Registration key:** `CancelAlert` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
 | Prop                     | Type       | Description                                                                              |
 | ------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
@@ -28,135 +28,39 @@ Renders a full-screen modal overlay with a confirmation dialog. Presents two act
 | `skipReleaseLockRequest` | `any`      | Whether to skip lock release when removing container item                                |
 | `dismiss`                | `Function` | Callback to close/dismiss this dialog (called with `true` to indicate confirmed dismiss) |
 
-## Component Skeleton
+All other inputs come from the project's field input contract (for registry compatibility only).
+
+## Implementation Structure
 
 Follow this exact structure when implementing. Replace modal/button/snackbar components with equivalents from your chosen design system.
 
-```typescript
-import { useState } from 'react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-import './CancelAlert.css';
-
-// ── Props interface ──────────────────────────────────────────
-interface CancelAlertProps extends PConnFieldProps {
-  heading: string;
-  content: string;
-  itemKey: string;
-  hideDelete: boolean;
-  isDataObject: boolean;
-  skipReleaseLockRequest: any;
-  dismiss: Function;
-}
-
-// ── Component ────────────────────────────────────────────────
-export default function CancelAlert(props: CancelAlertProps) {
-  // 1. Destructure props (note: itemKey aliased to containerItemID)
-  const {
-    heading, content, getPConnect,
-    itemKey: containerItemID,
-    hideDelete, isDataObject, skipReleaseLockRequest, dismiss,
-  } = props;
-
-  // 2. PConnect APIs
-  const actionsAPI = getPConnect().getActionsApi();
-  const containerManagerAPI = getPConnect().getContainerManager();
-  const isLocalAction = getPConnect().getValue(
-    PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION
-  );
-  // @ts-ignore - Property 'options' is private
-  const isBulkAction = getPConnect()?.options?.isBulkAction;
-
-  // 3. Localization setup
-  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-  const localeCategory = 'ModalContainer';
-
-  // 4. Coexistence setup
-  const broadCastUtils: any = PCore.getCoexistenceManager().getBroadcastUtils();
-  const isReverseCoexistence = broadCastUtils.isReverseCoexistenceCaseLoaded();
-
-  // 5. Button ID constants
-  const btnIds = {
-    SAVE_AND_CLOSE: 'saveAndClose',
-    CONTINUE_WORKING: 'continueWorking',
-    DELETE: 'delete',
-  };
-
-  // 6. State
-  const [buttonsState, setButtonsState] = useState({
-    [btnIds.SAVE_AND_CLOSE]: false,
-    [btnIds.DELETE]: false,
-  });
-  const [showSnackbar, setShowSnackbar] = useState(false);
-  const [snackbarMessage, setSnackbarMessage] = useState('');
-
-  // 7. Button enable/disable helpers
-  function disableButton(id) {
-    setButtonsState(prev => ({ ...prev, [id]: true }));
-  }
-  function enableButton(id) {
-    setButtonsState(prev => ({ ...prev, [id]: false }));
-  }
-
-  // 8. cancelHandler — see Behavioral Contract "Discard" section
-  function cancelHandler() { /* decision tree */ }
-
-  // 9. handleSnackbarClose — see Behavioral Contract
-  function handleSnackbarClose(event, reason?) {
-    if (reason === 'clickaway') return;
-    setShowSnackbar(false);
-  }
-
-  // 10. Build leftButton ("Go back") and rightButton ("Discard") JSX
-  //     leftButton: onClick → dismiss(), plus reverse coexistence cleanup
-  //     rightButton: onClick → cancelHandler(), disabled={buttonsState[btnIds.DELETE]}
-  //     All button text wrapped in localizedVal(text, localeCategory)
-
-  // 11. Return: overlay div + dialog box + snackbar
-  //     See Visual Specifications for layout and CSS classes
-  return (
-    <>
-      <div className="cancel-alert-background">
-        <div className="cancel-alert-top">
-          <h3>{localizedVal(heading, localeCategory)}</h3>
-          <div><p>{localizedVal(content, localeCategory)}</p></div>
-          <div className="action-controls">
-            {/* Two buttons: Go back (secondary) | Discard (primary) */}
-          </div>
-        </div>
-      </div>
-      {/* Snackbar: open={showSnackbar}, autoHideDuration=3000, message={snackbarMessage} */}
-    </>
-  );
-}
-```
+**Module Setup:** The component depends on a companion stylesheet for dialog/overlay styling. Define the input contract as an extension of the project's field input contract (for registry compatibility), adding `heading`, `content`, `itemKey`, `hideDelete`, `isDataObject`, `skipReleaseLockRequest`, and `dismiss` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** (note: `itemKey` is aliased to `containerItemID`) — `heading`, `content`, `getPConnect`, `itemKey` as `containerItemID`, `hideDelete`, `isDataObject`, `skipReleaseLockRequest`, `dismiss`.
+2. **PConnect APIs** — `actionsAPI` via `getPConnect().getActionsApi()`; `containerManagerAPI` via `getPConnect().getContainerManager()`; `isLocalAction` via `getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION)`; `isBulkAction` via `getPConnect()?.options?.isBulkAction` (a private property, may require suppressing type checks).
+3. **Localization setup** — `localizedVal` bound to `PCore.getLocaleUtils().getLocaleValue`; `localeCategory = 'ModalContainer'`.
+4. **Coexistence setup** — `broadCastUtils` via `PCore.getCoexistenceManager().getBroadcastUtils()`; `isReverseCoexistence` via `broadCastUtils.isReverseCoexistenceCaseLoaded()`.
+5. **Button ID constants** — an object `btnIds` with `SAVE_AND_CLOSE: 'saveAndClose'`, `CONTINUE_WORKING: 'continueWorking'`, `DELETE: 'delete'`.
+6. **Local state** — `buttonsState` initialized to `{ [btnIds.SAVE_AND_CLOSE]: false, [btnIds.DELETE]: false }`; `showSnackbar` initialized to `false`; `snackbarMessage` initialized to `''`.
+7. **Button enable/disable helpers** — `disableButton(id)` sets `buttonsState[id]` to `true` (via functional state update); `enableButton(id)` sets it to `false`.
+8. **`cancelHandler()`** — the "Discard" decision tree; see the Behavioral Contract "Discard" section.
+9. **`handleSnackbarClose(event, reason?)`** — returns without closing when `reason === 'clickaway'`, otherwise sets `showSnackbar` to `false`.
+10. **Build the "Go back" (`leftButton`) and "Discard" (`rightButton`) elements** — `leftButton`'s `onClick` calls `dismiss()` plus reverse-coexistence cleanup; `rightButton`'s `onClick` calls `cancelHandler()` and is disabled when `buttonsState[btnIds.DELETE]` is true. All button text is wrapped in `localizedVal(text, localeCategory)`.
+11. **Return** — a full-screen overlay `<div>` containing a dialog box `<div>` with a heading (`localizedVal(heading, localeCategory)`), body text (`localizedVal(content, localeCategory)`), and an action-controls row holding the two buttons ("Go back" as secondary, "Discard" as primary); alongside the dialog, a snackbar with `open={showSnackbar}`, `autoHideDuration={3000}`, and `message={snackbarMessage}`. See the Visual Specifications section for layout and CSS classes.
 
 ## Behavioral Contract
 
 ### Setup
 
-```typescript
-// PConnect APIs
-const actionsAPI = getPConnect().getActionsApi();
-const containerManagerAPI = getPConnect().getContainerManager();
-const isLocalAction = getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION);
-// @ts-ignore - Property 'options' is private and only accessible within class 'C11nEnv'
-const isBulkAction = getPConnect()?.options?.isBulkAction;
-
-// Localization
-const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-const localeCategory = 'ModalContainer';
-
-// Coexistence (store broadCastUtils — reused in Go back handler)
-const broadCastUtils: any = PCore.getCoexistenceManager().getBroadcastUtils();
-const isReverseCoexistence = broadCastUtils.isReverseCoexistenceCaseLoaded();
-
-// Button IDs (used as keys in buttonsState)
-const btnIds = {
-  SAVE_AND_CLOSE: 'saveAndClose',
-  CONTINUE_WORKING: 'continueWorking',
-  DELETE: 'delete',
-};
-```
+`actionsAPI` is `getPConnect().getActionsApi()`; `containerManagerAPI` is `getPConnect().getContainerManager()`; `isLocalAction` is `getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION)`; `isBulkAction` is read from the private `getPConnect()?.options?.isBulkAction` (may require suppressing type checks since the property is private).
+
+Localization: `localizedVal` is bound to `PCore.getLocaleUtils().getLocaleValue`; `localeCategory` is `'ModalContainer'`.
+
+Coexistence: `broadCastUtils` is `PCore.getCoexistenceManager().getBroadcastUtils()` (stored for reuse in the Go back handler); `isReverseCoexistence` is `broadCastUtils.isReverseCoexistenceCaseLoaded()`.
+
+Button IDs (used as keys in `buttonsState`): `btnIds = { SAVE_AND_CLOSE: 'saveAndClose', CONTINUE_WORKING: 'continueWorking', DELETE: 'delete' }`.
 
 ### State
 
@@ -166,34 +70,17 @@ const btnIds = {
 
 ### Helper Functions
 
-```typescript
-function disableButton(id) {
-  setButtonsState((prev) => ({ ...prev, [id]: true }));
-}
-function enableButton(id) {
-  setButtonsState((prev) => ({ ...prev, [id]: false }));
-}
-```
+`disableButton(id)` sets `buttonsState[id]` to `true` via a functional state update (spreading the previous state). `enableButton(id)` sets it to `false` the same way.
 
 ### "Go back" button (`leftButton`)
 
-Always calls `dismiss()` (no argument = don't confirm). If `isReverseCoexistence`:
-
-```
-broadCastUtils.setCallBackFunction(null)
-broadCastUtils.setIsDirtyDialogActive(false)
-```
+Always calls `dismiss()` (no argument = don't confirm). If `isReverseCoexistence`, additionally call `broadCastUtils.setCallBackFunction(null)` and `broadCastUtils.setIsDirtyDialogActive(false)`.
 
 ### "Discard" button (`rightButton`) — `cancelHandler()`
 
 Decision tree (evaluated in order):
 
-1. **Reverse coexistence:**
-
-   ```
-   dismiss(true)
-   PCore.getPubSubUtils().publish(REVERSE_COEXISTENCE_EVENTS.HANDLE_DISCARD)
-   ```
+1. **Reverse coexistence:** call `dismiss(true)`, then publish `PCore.getPubSubUtils().publish(REVERSE_COEXISTENCE_EVENTS.HANDLE_DISCARD)`.
 
 2. **Standard case in create stage** (`!isDataObject && !isLocalAction && !isBulkAction`):
    - Disable delete button
@@ -202,25 +89,11 @@ Decision tree (evaluated in order):
    - `.catch()`: show snackbar with `'Delete failed.'`
    - `.finally()`: re-enable delete button, call `dismiss(true)`
 
-3. **Local action** (`isLocalAction`):
-
-   ```
-   dismiss(true)
-   actionsAPI.cancelAssignment(containerItemID, false)
-   ```
-
-4. **Bulk action** (`isBulkAction`):
+3. **Local action** (`isLocalAction`): call `dismiss(true)`, then `actionsAPI.cancelAssignment(containerItemID, false)`.
 
-   ```
-   dismiss(true)
-   actionsAPI.cancelBulkAction(containerItemID)
-   ```
+4. **Bulk action** (`isBulkAction`): call `dismiss(true)`, then `actionsAPI.cancelBulkAction(containerItemID)`.
 
-5. **Data object or other** (default):
-   ```
-   dismiss(true)
-   containerManagerAPI.removeContainerItem({ containerItemID, skipReleaseLockRequest })
-   ```
+5. **Data object or other** (default): call `dismiss(true)`, then `containerManagerAPI.removeContainerItem({ containerItemID, skipReleaseLockRequest })`.
 
 ### Snackbar dismissal
 
@@ -242,50 +115,15 @@ Derived from `CancelAlert.css`:
 
 ### Full-screen overlay (`.cancel-alert-background`)
 
-```css
-.cancel-alert-background {
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  align-items: center;
-  height: 100%;
-  width: 100%;
-  background-color: var(--modal-background-color);
-  position: fixed;
-  z-index: 9999;
-  top: 0;
-  left: 0;
-}
-```
+**Visual-only styling notes:** A fixed, full-viewport overlay (`position: fixed`, top/left `0`, `100%` height and width) with a high z-index (`9999`), using a semi-transparent modal background color, laid out as a centered flex column (both horizontally and vertically).
 
 ### Dialog box (`.cancel-alert-top`)
 
-```css
-.cancel-alert-top {
-  display: table;
-  margin: auto;
-  min-width: 550px;
-  background-color: var(--modal-top-color);
-  border: 1px solid var(--modal-border-color);
-  border-radius: 10px;
-  padding: 20px;
-  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color);
-}
-```
+**Visual-only styling notes:** A centered table-display box with a minimum width of 550px, a themed dialog background color, a 1px themed border, 10px border radius, 20px padding, and a themed drop shadow.
 
 ### Content layout
 
-```
-.cancel-alert-top
-  <h3>{heading}</h3>
-  <div>
-    <p>{content}</p>
-  </div>
-  <div class="action-controls">
-    Grid container spacing=4, justifyContent='space-between'
-      Grid → leftButton ("Go back", secondary/outlined)
-      Grid → rightButton ("Discard", primary/contained, can be disabled)
-```
+Inside the `.cancel-alert-top` dialog box: a heading (`<h3>`) showing `heading`, a body paragraph showing `content`, and an `action-controls` row laid out as a grid container (spacing 4, `justifyContent='space-between'`) containing two grid items — the left one holding `leftButton` ("Go back", secondary/outlined) and the right one holding `rightButton` ("Discard", primary/contained, can be disabled).
 
 ### Button styles
 
@@ -322,19 +160,19 @@ Derived from `CancelAlert.css`:
 - `PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION`, `PUB_SUB_EVENTS.EVENT_CANCEL`, etc.
 - `PCore.getPubSubUtils().publish()` — for pub/sub events.
 - `PCore.getCoexistenceManager().getBroadcastUtils()` — for reverse coexistence handling.
-- Button, Grid, IconButton, Snackbar components.
-- Close icon.
-- `./CancelAlert.css` — must be imported.
+- The DS's button, grid/layout, icon button, and snackbar/toast components.
+- A close icon.
+- A companion stylesheet for dialog/overlay styling.
 
 ## Design System Mapping
 
 **UI control type:** Full-screen modal confirmation dialog.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                                                       |
-| ------------------ | ------------------------------------------------------------------------------------------- |
-| Default (CSS only) | `<div class="cancel-alert-background">` + `<div class="cancel-alert-top">` + CSS from above |
-| MUI                | `<Button>`, `<Grid>`, `<Snackbar>`, `<IconButton>`, fixed overlay `<div>`                   |
-| Ant Design         | `<Modal>` or custom overlay                                                                 |
-| Chakra UI          | `<Modal>` or `<AlertDialog>`                                                                |
+- **Overlay** → use the DS's modal overlay or a fixed full-viewport container with semi-transparent background
+- **Dialog box** → a centered card/container with heading, body text, and action buttons
+- **"Go back" button** → secondary/outlined style button
+- **"Discard" button** → primary/contained style button (disableable during async operations)
+- **Snackbar/toast** → the DS's notification/toast component with auto-hide (3s) and manual close
+- **Grid layout** → space the two buttons apart using the DS's layout utility