@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,190 @@
+# Skill: Field Components
+
+Create or replace field components (form inputs) in the project. Field components render individual form controls that bind to Pega case properties.
+
+---
+
+## Architecture Overview
+
+Each field component lives in its own folder under the project's field components directory, named after the component. The folder contains:
+
+| File                         | Purpose                                                         |
+| ---------------------------- | --------------------------------------------------------------- |
+| Component implementation     | The component's logic and markup                                |
+| Re-export module             | Re-exports the component as the folder's default export         |
+| Metadata (`config-ext.json`) | Registration metadata (name, label, description, type, subtype) |
+
+Components are registered in the project's component map and resolved at runtime via the project's component registry.
+
+---
+
+## Input Contract
+
+All field components extend the project's **field input contract**. The field input contract itself extends a **base component interface**, which provides a single `getPConnect` accessor function (returns the PConnect API object).
+
+The field input contract defines these fields:
+
+| Field             | Type                | Description                                            |
+| ----------------- | ------------------- | ------------------------------------------------------ |
+| `label`           | `string`            | Field label text                                       |
+| `required`        | `boolean`           | Whether the field is required                          |
+| `disabled`        | `boolean`           | Whether the field is disabled                          |
+| `value`           | `string` (optional) | Current field value from the store                     |
+| `validatemessage` | `string`            | Validation error message                               |
+| `status`          | `string` (optional) | `'error'` \| `'warning'` \| undefined                  |
+| `onChange`        | `any`               | Change handler (wired by platform)                     |
+| `onBlur`          | `any` (optional)    | Blur handler (wired by platform)                       |
+| `readOnly`        | `boolean`           | Whether the field is read-only                         |
+| `testId`          | `string`            | Test identifier for automation                         |
+| `helperText`      | `string`            | Helper/hint text below the field                       |
+| `displayMode`     | `string` (optional) | `'DISPLAY_ONLY'` \| `'STACKED_LARGE_VAL'` \| undefined |
+| `hideLabel`       | `boolean`           | Whether to hide the label                              |
+| `placeholder`     | `string` (optional) | Placeholder text                                       |
+
+Extend the field input contract for component-specific additional inputs (e.g., a component that needs `fieldMetadata` and `maxLength` would extend the field input contract with those two additional optional fields).
+
+---
+
+## Implementation Pattern
+
+### Abstract Field Component Pattern
+
+This pattern is design-system agnostic. It defines the **behavioral skeleton** every field component must follow. The final render step must be adapted to your design system's input primitive — see the "Design System Adaptation" section below for guidance.
+
+**Module Setup:** The component depends on the project's event-commit utility (for committing value changes to the Pega store) and the project's component registry (for resolving the display-mode renderer). Define the input contract as an extension of the project's field input contract with any component-specific additional inputs. Export the component as the module's default export.
+
+**Main Component Logic** — the component follows these steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry to get the display-mode renderer.
+2. **Receive inputs** — extract `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`, plus any component-specific inputs.
+3. **PConnect setup** — call `getPConnect()` to get `pConn`; get `actions` via `pConn.getActionsApi()`; get `propName` via `(pConn.getStateProps() as any).value`; compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Track input value locally** — maintain local state initialized to `value`. Do NOT commit to the store on every keystroke.
+5. **Sync local state from the store** — use a lifecycle effect watching `value` to update the local state whenever the store value changes.
+6. **Display mode short-circuits** — these must be checked before any interactive rendering:
+   - If `displayMode === 'DISPLAY_ONLY'`: return `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value`.
+   - If `displayMode === 'STACKED_LARGE_VAL'`: return the same but with a stacked layout variant.
+7. **Event handlers:**
+   - The change handler — updates local state only (no store commit).
+   - The blur handler — invokes the project's event-commit utility with event type `'changeNblur'`, the property name, and the local value to commit to the Pega store.
+8. **Render** — render the design system's input primitive with these inputs wired: `value` (local state), the change handler, the blur handler (only when not read-only), `disabled`, `readOnly`, `required`, `placeholder`, `label`, `helperText` (the computed display text), an error/invalid flag driven by `status === 'error'`, and a test-id attribute driven by `testId`.
+
+---
+
+## Design System Adaptation
+
+When implementing the render section with a specific design system:
+
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** section that describes how to map the component's behavior to a DS primitive. Use it as a starting point.
+
+**2. If the chosen design system is not covered** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
+
+**3. Discover the API from installed packages** — before writing the render markup, confirm all input names from the design system's type declarations. Never rely on training-knowledge of a DS API. Search the design system package's type declaration files for the target component name, then read the exported input interface to confirm exact input names and types.
+
+**4. Input mapping conventions** — adapt these Pega/SDK inputs to whatever the DS component calls them:
+
+| Pega/SDK input                    | Meaning                       | Typical DS equivalent                               |
+| --------------------------------- | ----------------------------- | --------------------------------------------------- |
+| `status === 'error'`              | Validation error state        | `error`, `status="error"`, `invalid`, `isInvalid`   |
+| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra`        |
+| `readOnly`                        | Non-editable, still visible   | `readOnly`, `isReadOnly`, `variant="borderless"`    |
+| `testId`                          | Automation selector           | A test-id attribute on the underlying input element |
+| `required`                        | Required field marker         | `required`, `isRequired`                            |
+| `hideLabel`                       | Suppress label display        | Pass empty string `''` as label                     |
+
+**5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., a form-item or form-control component), use it rather than composing them manually.
+
+---
+
+## Event Handling
+
+> ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM FIELD UTILITIES**
+>
+> If the project has a field-utilities module that exports utility functions AND types (e.g., field input types, commit helpers, value getters, context helpers, option-list helpers), import everything you need in a **single import statement**. NEVER add a separate type-only import for a symbol that is already imported from the same module — doing so causes a duplicate identifier error.
+>
+> **Before writing imports:** Check what the field-utilities module exports. If it exports a type, you can import it alongside value exports in one statement.
+
+Use the project's event-commit utility to commit values to the Pega store. Obtain the two references it needs: `actions` via `pConn.getActionsApi()` and `propName` via `(pConn.getStateProps() as any).value`. Then invoke the utility with one of three event types:
+
+- `'change'` — update store only.
+- `'blur'` — trigger validation only.
+- `'changeNblur'` — update and validate (most common).
+
+**Pattern:** Track local state, update on user input, then call the event-commit utility on blur to commit.
+
+---
+
+## Display Modes
+
+Every field component MUST handle these `displayMode` values:
+
+| Mode                  | Behavior                                                            |
+| --------------------- | ------------------------------------------------------------------- |
+| `undefined` / `null`  | Render editable form control                                        |
+| `'DISPLAY_ONLY'`      | Render read-only via `FieldValueList` (inline layout)               |
+| `'STACKED_LARGE_VAL'` | Render read-only via `FieldValueList` with a stacked layout variant |
+
+Resolve the `FieldValueList` component via the project's component registry.
+
+---
+
+## Resolving Other Components
+
+Use the project's component registry to resolve components by name at runtime — for example, resolving `'FieldValueList'` or `'TextInput'` returns the currently-registered component for that name (including any override).
+
+This is used when:
+
+- Rendering display modes (FieldValueList)
+- Delegating to another field component (e.g., Date delegates to TextInput for readOnly)
+
+---
+
+## Registration
+
+After creating a component, register it in the project's component map: import the component's default export from its folder under the field components directory, then add it to the object returned by the project's component registration function. The key used must match the Pega component name exactly.
+
+---
+
+## Existing Field Components
+
+| Component       | Pega Name       | Description                       |
+| --------------- | --------------- | --------------------------------- |
+| AutoComplete    | AutoComplete    | Typeahead search field            |
+| CancelAlert     | CancelAlert     | Cancel confirmation dialog        |
+| Checkbox        | Checkbox        | Single checkbox with label        |
+| Currency        | Currency        | Currency input with formatting    |
+| Date            | Date            | Date picker                       |
+| DateTime        | DateTime        | Date + time picker                |
+| Decimal         | Decimal         | Decimal number input              |
+| Dropdown        | Dropdown        | Select/dropdown with options      |
+| Email           | Email           | Email input with icon             |
+| Group           | Group           | Field group container             |
+| Integer         | Integer         | Integer-only input                |
+| Location        | Location        | Google Maps location picker       |
+| Multiselect     | Multiselect     | Multi-select dropdown             |
+| ObjectReference | ObjectReference | Reference to another object       |
+| Percentage      | Percentage      | Percentage input                  |
+| Phone           | Phone           | Phone input with country selector |
+| RadioButtons    | RadioButtons    | Radio button group                |
+| RichText        | RichText        | Rich text editor                  |
+| ScalarList      | ScalarList      | List of scalar values             |
+| SelectableCard  | SelectableCard  | Card-style selection              |
+| SemanticLink    | SemanticLink    | Clickable link to another case    |
+| TextArea        | TextArea        | Multi-line text input             |
+| TextContent     | TextContent     | Static text display               |
+| TextInput       | TextInput       | Single-line text input            |
+| Time            | Time            | Time picker                       |
+| URL             | URL             | URL input with validation         |
+| UserReference   | UserReference   | User picker                       |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component is exported as the module's default export.
+2. **Re-export module** — A re-export file in the folder exports the component as the folder's default.
+3. **Local state** — Track input value locally, sync from the `value` input via a lifecycle effect.
+4. **Commit on blur** — Use the project's event-commit utility with event type `'changeNblur'` on blur, not on every keystroke.
+5. **Error display** — Show `validatemessage` or `helperText` below the field; apply an error visual state when `status === 'error'`.
+6. **Read-only** — Set the read-only attribute on the input element or render a display-only component.
+7. **Test IDs** — Pass a test-id attribute driven by `testId` to the underlying input element.
+8. **No PCore imports** — Access PCore globals directly (they're declared globally by the Pega runtime type definitions).

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

@@ -0,0 +1,157 @@
+# Skill: AutoComplete
+
+Typeahead / autocomplete search field that fetches options from a data page or associated list, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a typeahead input that shows a dropdown of matching options as the user types. Options are loaded from a Pega data page or associated list. The stored value is always the **key** of the selected option, while the displayed text is the resolved **value** (label). Delegates read-only to `TextInput` with the resolved label.
+
+## Pega Metadata
+
+- **Pega Name:** `AutoComplete`
+- **Type / Subtype:** `Field` / `Picklist`
+- **Registration key:** `AutoComplete` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name                 | Type                 | Description                                                    |
+| -------------------- | -------------------- | -------------------------------------------------------------- |
+| `listType`           | `string`             | `'associated'` or `'datapage'`                                 |
+| `datasource`         | `any`                | Datasource (array for associated, string name for datapage)    |
+| `columns`            | `any[]`              | Column config for extracting key/value from datasource records |
+| `parameters`         | `any` (optional)     | Query parameters for data page calls                           |
+| `deferDatasource`    | `boolean` (optional) | If true, transform `datasourceMetadata` into datapage config   |
+| `datasourceMetadata` | `any` (optional)     | Metadata for deferred datasource                               |
+| `onRecordChange`     | `any` (optional)     | Callback fired on selection change                             |
+| `additionalProps`    | `object` (optional)  | Extra inputs passed through to the autocomplete                |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure when implementing. Replace the autocomplete widget with the equivalent from your chosen design system.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`), the project's event-commit utility, a deep-equality utility (for datasource change detection), the project's utility helpers (for associated option list loading), and the project's data-page utility (for async data page fetching). Define an option type with `key: string` and `value: string`. Declare the top-level helper functions `preProcessColumns`, `getDisplayFieldsMetaData`, and `flattenParameters` (described in the Helper Functions section below). Define the input contract as an extension of the project's field input contract, adding `displayMode`, `deferDatasource`, `datasourceMetadata`, `status`, `onRecordChange`, `additionalProps`, `listType`, `parameters`, `datasource`, and `columns` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `TextInput` and `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `placeholder`, `value` (default `''`), `validatemessage`, `readOnly`, `testId`, `displayMode`, `deferDatasource`, `datasourceMetadata`, `status`, `helperText`, `hideLabel`, `onRecordChange`.
+3. **PConnect setup** — obtain the PConnect instance, context name via `pConn.getContextName()`, actions API, and bound property name.
+4. **Inputs that may be reassigned** — receive `listType`, `parameters`, `datasource` (default `[]`), and `columns` (default `[]`) as reassignable since they get overridden by deferred datasource transformation.
+5. **Local state** — `inputValue` (default `''`), `options` (array of option objects, default `[]`), and `theDatasource` (default `null`).
+6. **Derived values** — a local (non-state) `selectedValue` variable initialized to `''`, and `helperTextToDisplay = validatemessage || helperText`.
+7. **Render-time datasource comparison (not in a lifecycle effect)** — if deep-equal comparison of incoming `datasource` vs cached `theDatasource` is false, update `theDatasource`.
+8. **Deferred datasource transformation** — reassigns the reassignable variables; see Behavioral Contract item 5.
+9. **Column preprocessing** — apply `preProcessColumns(columns)`.
+10. **Lifecycle effect: load associated options** — watching `theDatasource`; see Behavioral Contract item 7.
+11. **Lifecycle effect: load datapage options** — on mount only, guarded to skip when `displayMode` is set or `listType === 'associated'`; see Behavioral Contract item 8.
+12. **Display mode returns** (must come before the main render) — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with `value` set to the raw stored `value` (the key, not the resolved label).
+13. **Resolve `selectedValue` from options** — see Behavioral Contract item 9.
+14. **Event handlers** — the selection change handler and input change handler; see Behavioral Contract items 10 and 11.
+15. **Read-only return** — when `readOnly` is true, resolve the display label by finding the `options` entry whose `key` matches `value` and taking its `value` field, then render `TextInput` with all inputs passed through plus that resolved label as the `value` override.
+16. **Main editable render** — use the DS's autocomplete/combobox widget, passing `options`, a label-resolution function, `value` (`selectedValue`), `inputValue`, selection change handler, input change handler, `label`, `placeholder`, `required`, an error state, `helperTextToDisplay`, and `testId`.
+
+## Behavioral Contract
+
+1. **Options state:** Maintain `options` as an array of `{key: string, value: string}` objects.
+2. **Input value state:** Maintain `inputValue` (string) — the typed text in the input box. `selectedValue` is a **local variable** (not state) recalculated on every render from `options` and `value`.
+3. **Helper text:** Compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Datasource change detection:** During render (not in an effect), use deep equality to compare incoming `datasource` with cached `theDatasource`. If different, update `theDatasource` to trigger the associated-list lifecycle effect.
+5. **Deferred datasource transformation:** If `deferDatasource && datasourceMetadata?.datasource?.name`:
+   - `listType`, `parameters`, `datasource`, `columns` must be declared as **reassignable** because this block overrides them.
+   - Set `listType = 'datapage'`, `datasource` to the metadata's datasource name.
+   - Flatten `parameters` using `flattenParameters()` (see Helper Functions).
+   - Strip the `@P` prefix from property paths.
+   - Build `columns` as a two-entry array: the first entry marks the key column, the second marks the display column.
+6. **Column preprocessing:** Apply `preProcessColumns(columns)` — strips leading `.` from each column's `value` field.
+7. **Loading options (`associated`):** Lifecycle effect watching `theDatasource` — load options via the project's utility helper and update `options` state.
+8. **Loading options (`datapage`):** Mount-only lifecycle effect (skipped when `displayMode` is set OR `listType === 'associated'`) — call the project's data-page utility, map results using `getDisplayFieldsMetaData(columns)` to extract `key` and `value` per row, and update `options` state.
+9. **Selected value resolution:** On render, find `selectedValue` by locating the option whose `key` matches `value` (the stored key); if found, `selectedValue` is that option's display text, otherwise it falls back to the raw `value`.
+10. **On selection change:**
+    - Extract the key from the selected option (or empty string if cleared).
+    - Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the key.
+    - If `onRecordChange` is provided, call it with the event.
+11. **On input change:** Update `inputValue` state (typed text, does NOT commit to store).
+12. **Read-only:** Resolve the option label (`options.find(opt => opt.key === value)?.value`), delegate to `TextInput` with the resolved label as the `value` override.
+
+## Helper Functions
+
+These are **top-level pure functions** defined outside the component (design-system independent).
+
+### `preProcessColumns(columnList)`
+
+Returns a new array where each column object's `.value` has a leading `.` stripped (values not starting with `.` are left unchanged).
+
+### `getDisplayFieldsMetaData(columnList)`
+
+Extracts key, primary display, and secondary display field names from column config: filter the column list to entries with `display === 'true'` (the display columns) and separately to entries with `key === 'true'` (the key column). Initialize a result object with `key: ''`, `primary: ''`, `secondary: []`. Set the key to the first key column's `value` if one exists, otherwise default to `'auto'`. For each display column, if it is marked `primary === 'true'` assign its `value` to primary, otherwise push its `value` onto secondary. Return the result.
+
+Return type: `{ key: string, primary: string, secondary: string[] }`.
+
+### `flattenParameters(params)`
+
+Converts Pega's nested parameter format to a flat key-value map: for each key in the `params` object, read its `name` and `value` fields and assign `flat[name] = value`. Return the resulting flat map.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw stored `value` (key string).
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+
+## Read-Only Rendering
+
+Resolve the display label from options and delegate to `TextInput` with the resolved label as the `value` override.
+
+## Visual Specifications
+
+| Property       | Value                                                       |
+| -------------- | ----------------------------------------------------------- |
+| Width          | 100%                                                        |
+| Size           | Small                                                       |
+| Variant        | Outlined                                                    |
+| Dropdown popup | Opens below input, shows filtered options                   |
+| Input          | Combobox pattern — types to filter, click arrow to open all |
+| Error state    | Red border + red helper text                                |
+| Label          | Floating label                                              |
+| Placeholder    | From the `placeholder` input                                |
+
+**Autocomplete behavior:**
+
+- The controlled `value` is the selected option object (or `selectedValue` string).
+- The controlled `inputValue` is the typed text.
+- The label-resolution function returns the option's display text (the `value` field).
+- Option equality comparison uses the option's display text.
+
+## Edge Cases & Special Logic
+
+- `inputValue || selectedValue` — the input displays `inputValue` when typing, `selectedValue` when a selection has been made and nothing is typed.
+- When `value` is a key that does not yet exist in `options` (e.g., options still loading), display `value` directly as `selectedValue`.
+- Options array uses `{key, value}` — `key` = stored value, `value` = display label.
+- `context` is obtained from `pConn.getContextName()` and passed to the data-page utility.
+- **Render ordering matters:** display mode checks → `selectedValue` resolution → define event handlers → readOnly check → main editable render. Do not reorder.
+
+## Dependencies
+
+- A deep-equality utility — for datasource change detection.
+- The project's utility helpers — for associated list option loading.
+- The project's data-page utility — for async datapage fetch.
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- A typeahead/autocomplete UI widget from the design system.
+
+## Design System Mapping
+
+**UI control type:** Combobox / typeahead autocomplete input.
+
+When implementing in a specific design system, map the following:
+
+- **Autocomplete** → use the DS's combobox/autocomplete component with option filtering
+- **Option format** → `{key, value}` where `key` is stored and `value` is displayed
+- **Read-only mode** → resolve the display label and delegate to `TextInput`
+- **Error state** → the DS's error/danger visual state
+- **Combobox behavior** → controlled `value` (selected option) + controlled `inputValue` (typed text)

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

@@ -0,0 +1,178 @@
+# Skill: CancelAlert
+
+Cancel confirmation dialog that offers the user a choice between going back or discarding/deleting the current case/action.
+
+> **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.
+
+---
+
+## Component Purpose
+
+Renders a full-screen modal overlay with a confirmation dialog. Presents two actions: "Go back" (continue working) and "Discard" (cancel/delete). Handles different cancellation scenarios: standard case creation stage, local action, bulk action, data object, and reverse coexistence. Shows a snackbar notification on delete failure.
+
+## Pega Metadata
+
+- **Pega Name:** `CancelAlert`
+- **Type / Subtype:** Internal modal/alert
+- **Registration key:** `CancelAlert` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Prop                     | Type       | Description                                                                              |
+| ------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
+| `heading`                | `string`   | Modal dialog heading text                                                                |
+| `content`                | `string`   | Modal dialog body/description text                                                       |
+| `itemKey`                | `string`   | The container item ID for the case being cancelled (aliased as `containerItemID`)        |
+| `hideDelete`             | `boolean`  | Whether to hide/disable the delete option                                                |
+| `isDataObject`           | `boolean`  | Whether this is cancelling a data object (not a work item)                               |
+| `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) |
+
+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.
+
+**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
+
+`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
+
+- `buttonsState`: tracks disabled state per button: `{ [btnIds.SAVE_AND_CLOSE]: false, [btnIds.DELETE]: false }`
+- `showSnackbar`: boolean — whether to show the failure snackbar
+- `snackbarMessage`: string — error message text
+
+### Helper Functions
+
+`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`, additionally call `broadCastUtils.setCallBackFunction(null)` and `broadCastUtils.setIsDirtyDialogActive(false)`.
+
+### "Discard" button (`rightButton`) — `cancelHandler()`
+
+Decision tree (evaluated in order):
+
+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
+   - Call `actionsAPI.deleteCaseInCreateStage(containerItemID, hideDelete)`
+   - `.then()`: publish `EVENT_CANCEL`
+   - `.catch()`: show snackbar with `'Delete failed.'`
+   - `.finally()`: re-enable delete button, call `dismiss(true)`
+
+3. **Local action** (`isLocalAction`): call `dismiss(true)`, then `actionsAPI.cancelAssignment(containerItemID, false)`.
+
+4. **Bulk action** (`isBulkAction`): call `dismiss(true)`, then `actionsAPI.cancelBulkAction(containerItemID)`.
+
+5. **Data object or other** (default): call `dismiss(true)`, then `containerManagerAPI.removeContainerItem({ containerItemID, skipReleaseLockRequest })`.
+
+### Snackbar dismissal
+
+`handleSnackbarClose`: if `reason === 'clickaway'`, return (do not close). Otherwise `setShowSnackbar(false)`.
+
+### Localization
+
+All visible text is localized via `PCore.getLocaleUtils().getLocaleValue(key, 'ModalContainer')`:
+
+- `'Go back'`
+- `'Discard'`
+- `heading` prop value
+- `content` prop value
+- `'Delete failed.'`
+
+## Visual Specifications
+
+Derived from `CancelAlert.css`:
+
+### Full-screen overlay (`.cancel-alert-background`)
+
+**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`)
+
+**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
+
+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
+
+| Button  | Style     | Color     |
+| ------- | --------- | --------- |
+| Go back | Contained | Secondary |
+| Discard | Contained | Primary   |
+
+### Snackbar
+
+- `autoHideDuration: 3000ms`
+- Shows `snackbarMessage` (e.g., `'Delete failed.'`)
+- Close icon button to dismiss manually
+
+**CSS variables used:**
+
+- `--modal-background-color`: semi-transparent overlay (e.g., `rgba(0,0,0,0.5)`)
+- `--modal-top-color`: dialog background (e.g., white or app background)
+- `--modal-border-color`: dialog border
+- `--modal-box-shadow-color`: dialog shadow color
+
+**CSS companion file required:** Import `./CancelAlert.css`.
+
+## Edge Cases & Special Logic
+
+- **`buttonsState`** tracks loading state to prevent double-clicks during async delete.
+- `dismiss(true)` vs `dismiss()`: passing `true` signals confirmed cancellation; no arg means the user chose to continue.
+- `isBulkAction` is accessed via `getPConnect()?.options?.isBulkAction` — a private property, marked with `@ts-ignore`.
+- All action handling is async — the UI must show loading/disabled state during `deleteCaseInCreateStage`.
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — for text localization.
+- `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.
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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