@pega/custom-dx-components 26.1.11 → 26.1.12-alpha.0.2

package/src/ai/catalog/best-practices/troubleshooting-common-pitfalls.md

@@ -0,0 +1,132 @@
+---
+title: Troubleshooting Common Pitfalls
+description: Symptom-indexed guide to the handful of mistakes that recur across all the PCore/PConnect skills — search by what's going wrong, not by method name.
+---
+
+# Troubleshooting Common Pitfalls
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+The reference files document what each method does; this guide documents what tends to go wrong even when a method is called correctly according to its signature. Search this page by symptom before assuming a method is broken or under-documented.
+
+## Systematic Diagnosis Checklist
+
+Before assuming a documented method is broken, work through this order — most "the API doesn't work" reports turn out to be one of these:
+
+1. **Check the browser console for the actual error.** A `TypeError`, a rejected-promise stack, or a validation warning almost always names the real problem more precisely than the symptom you started with.
+2. **Re-read the exact signature in the relevant `references/` file.** A missing/misordered required parameter is the single most common root cause — verify argument order and required vs. optional parameters before suspecting the method itself.
+3. **Confirm the method exists in the version you're running against.** If it's a recently-documented method, check whether the runtime/mock you're testing against is old enough to not implement it yet (see the entry below on this exact symptom).
+4. **Check subscribe/unsubscribe and async ordering.** A large share of "state is stale" or "still running after unmount" bugs are a missing cleanup or an out-of-order async resolution, not a wrong method call — see the dedicated entries below.
+5. **If it's failing only in a test, check the mock, not the component.** A test mock can drift out of sync with the real method's shape; confirm the failure reproduces against the real API (or a fresh mock built directly from the reference file) before debugging the component itself.
+
+## `TypeError: pConn.someMethod is not a function` (or the same for `PCore.someMethod`)
+
+**Cause:** the method exists in a newer platform version than the one the current mock, test, or runtime is on. This is especially common right after a new `PConnect`/`PCore` method is added — existing Jest mocks of `pConn`/`PCore` across the codebase don't automatically gain new methods.
+
+**Fix:** call new/optional methods with optional chaining, `pConn.someMethod?.()`, rather than assuming every method is always present. Don't remove the optional chaining just because it works locally — other call sites or older mocks may not implement the method yet.
+
+## `MessageManager.clearMessages(...)` runs without error, but the message is still shown
+
+**Cause:** `type` was omitted from the options object. The underlying filter only removes messages whose `type` matches what you passed — omitting it means nothing matches, so nothing is removed, silently.
+
+**Fix:** always pass the `type` that matches the message you're clearing (for example, `'error'`), alongside `category`/`context`, when calling `PCore.getMessageManager().clearMessages(...)` (see [pcore-messaging-details.md](../references/pcore-messaging-details.md)).
+
+## Deleting a case throws, or deletes the wrong thing
+
+**Cause:** `ActionsApi.deleteWork` and `ActionsApi.deleteCaseInCreateStage` are not interchangeable — one is for a case that has already left its create stage (persisted, has a confirmed ID), the other is for a case still being created.
+
+**Fix:** branch on the case's stage before choosing which method to call — see [safe-case-deletion](../pconnect-assignment-lifecycle/cookbooks/safe-case-deletion.md).
+
+## Subscription callback keeps firing after the component unmounts
+
+**Cause:** the unsubscribe/cancel function returned by `subscribe` (data page, `PubSubUtils`, or `MessagingServiceManager`) was never called. This can also surface as a React warning about updating state on an unmounted component.
+
+**Fix:** always store and invoke the returned unsubscribe handle in a cleanup function (e.g. a `useEffect` cleanup) — see [data-page-subscription-cleanup](../pconnect-data-subscriptions/cookbooks/data-page-subscription-cleanup.md), [pubsub-cleanup](../pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md), and [realtime-case-subscription](../pconnect-data-subscriptions/cookbooks/realtime-case-subscription.md).
+
+## Locale switched, but already-rendered labels didn't update
+
+**Cause:** `PCore.switchLocale(locale)` changes the active locale going forward — it does not retroactively re-resolve strings that a component already fetched and stored (e.g. in state) before the switch.
+
+**Fix:** re-call `pConn.getLocalizationService().getLocalizedText(...)`/`getLocalizedMessage(...)` after the locale switch resolves, for any string held in component state — see [locale-switch-and-relocalize](../pconnect-navigation-locale-genai/cookbooks/locale-switch-and-relocalize.md).
+
+## Two users' (or two components') personalization saves overwrite each other
+
+**Cause:** `PersonalizationUtils` saves are keyed by `listComponentID` — if two different components/instances reuse the same ID, their saves collide, last write wins.
+
+**Fix:** make `listComponentID` unique and stable per component instance (max 32 chars) — see [view-personalization](../pconnect-lists-and-views/cookbooks/view-personalization.md).
+
+## A cascading dependent field doesn't refresh after the field it depends on changes
+
+**Cause:** the dependent field's cascade subscription wasn't set up before the source field's change was dispatched, or the subscription's cleanup fired too early.
+
+**Fix:** follow the subscribe-before-trigger ordering in [cascading-dependent-fields](../pconnect-forms-and-fields/cookbooks/cascading-dependent-fields.md).
+
+## `ContainerUtils.closeContainerItem` doesn't behave like `ContainerManager.removeContainerItem`
+
+**Cause:** these two methods are not interchangeable. `closeContainerItem` performs a dirty-state check before closing (part of `ContainerUtils`); `removeContainerItem` (part of `ContainerManager`) removes an item from the container's item list without that check.
+
+**Fix:** use the one that matches your intent — see [container-item-lifecycle](../pconnect-lists-and-views/cookbooks/container-item-lifecycle.md).
+
+## A data page still shows old data right after a save
+
+**Cause:** data page results are cached; saving a record through a different call doesn't automatically invalidate a data page instance that already cached the old result.
+
+**Fix:** call `DataPageUtils.markDataInstanceDirty(dataPageName, parameters)` after the save, or re-fetch with the `{ invalidateCache: true }` option, before reading the data page again — see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md). See also [Performance & Efficiency: cache deliberately](./performance-and-efficiency.md#cache-data-pages-but-invalidate-deliberately).
+
+## A typeahead/search field hammers the server on every keystroke
+
+**Cause:** the field's `fetchData`/REST call is wired directly to the input's `onChange`, with no debouncing or buffering.
+
+**Fix:** debounce with `AsynchronousUtils.getDebouncedSubject(delay)` or configure `DataApi.registerForBufferedCall({ waitTime, maxSize })` before fetching — see [Performance & Efficiency: debounce and buffer](./performance-and-efficiency.md#debounce-or-buffer-user-triggered-calls).
+
+## The UI shows "online" right after the network actually dropped (or vice versa)
+
+**Cause:** the component reads `navigator.onLine` directly or adds its own `window` `online`/`offline` listeners instead of using the platform's own connectivity tracking, and misses an edge case the platform already handles.
+
+**Fix:** use `PCore.getNetworkUtils().isOnline()`/`onStatusChange(callback)` instead — see [pcore-environment-locale-namespace.md](../references/pcore-environment-locale-namespace.md).
+
+## An older async response overwrites a newer one (a fast-typed search shows results for an earlier query)
+
+**Cause:** two overlapping requests were in flight (e.g. triggered by two keystrokes) and the one that started first happened to resolve last, and nothing discarded the stale response.
+
+**Fix:** cancel the superseded request with `RestClient.getCancelTokenSource()`/check `isRequestCanceled(error)` before treating a rejection as a real error, or otherwise tag each request and ignore a resolution that isn't for the latest one — see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md) and [Error Handling & Resiliency: distinguish cancellation from failure](./error-handling-and-resiliency.md#distinguish-cancellation-from-failure).
+
+## The same generic error message shows for every failure, which makes triage hard
+
+**Cause:** `ErrorHandler`'s generic failure message (shown when a component fails to render) hasn't been customized, so every unrelated failure looks identical to the user/tester.
+
+**Fix:** call `PCore.getErrorHandler().setGenericFailedMessage(message)` with a clearer default, and prefer surfacing a specific, component-level error state over relying solely on the generic fallback — see [pcore-misc-details.md](../references/pcore-misc-details.md).
+
+## A field's validation error message won't clear even after the value is fixed
+
+**Cause:** `ValidationApi.validate(value, propertyName?)` (see [pconnect-validation-api.md](../references/pconnect-validation-api.md)) both validates and writes the result to application state — if the corrected value is never re-passed through `validate()` (for example, a fix applied programmatically rather than through the field's own change handler), the stale message stays in state because nothing told it to re-evaluate.
+
+**Fix:** re-run `validate()` with the corrected value through the same path a normal user edit would take, rather than only updating the underlying value and assuming the displayed message updates itself.
+
+## An attachment upload appears stuck and never resolves
+
+**Cause:** `AttachmentUtils.uploadAttachment` (see [pcore-case-collaboration-details.md](../references/pcore-case-collaboration-details.md)) rejected or the resolved promise's status was never checked, and nothing surfaces a stuck/failed state to the user — the UI is left showing a permanent "uploading" indicator instead of an error.
+
+**Fix:** always attach a `.catch`/handle the rejection path for `uploadAttachment` (see [Error Handling & Resiliency: never fail silently](./error-handling-and-resiliency.md#never-fail-silently)), and pair it with a reasonable timeout guard (see [Error Handling & Resiliency: guard against a call that never resolves](./error-handling-and-resiliency.md#guard-against-a-call-that-never-resolves)) so a genuinely hung request doesn't leave the indicator spinning forever.
+
+## A GenAI Assistant conversation's history is empty after a page reload
+
+**Cause:** `GenAIAssistantUtils.createConversation`/`sendMessage` (see [pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md)) manage the conversation server-side, but the component only reads messages from its own local state (populated as the user sends/receives messages in that session) rather than re-fetching the conversation on mount.
+
+**Fix:** on mount, call `getMessages(assistantID, conversationID, context)`/`getConversations(...)` to rehydrate history from the server instead of assuming local state is the source of truth — local state should be treated as a cache of what `getMessages` would return, not the only copy.
+
+## The autosave indicator stays "unsaved" after a successful save
+
+**Cause:** a change was made through a path that doesn't call `AutosaveUtils.notifyChange(context, propReference, value)` (see [pcore-misc-details.md](../references/pcore-misc-details.md)) — for example, a value set directly via a lower-level state update instead of the field's normal change handler — so the autosave engine never learns the edit happened, and its status subscription never transitions out of the stale state.
+
+**Fix:** route every user-facing edit path through the same mechanism a normal field edit uses, so `notifyChange` fires consistently; don't bypass it for "programmatic" updates that are still meant to be autosaved.
+
+## A buffered/typeahead call never fires, even though the user kept typing
+
+**Cause:** `DataApi.registerForBufferedCall({ waitTime, maxSize })` (see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)) batches calls until either `waitTime` elapses with no new input or `maxSize` queued calls are reached — if `waitTime` is set too high relative to how the component's lifecycle unmounts/resets between keystrokes (for example, the component re-creates the `DataApi` instance on every render instead of reusing one), the buffer can be discarded before it ever fires.
+
+**Fix:** create the buffered `DataApi` instance once (not on every render) and confirm `waitTime` is tuned to the input's actual typing cadence — see [Performance & Efficiency: debounce or buffer user-triggered calls](./performance-and-efficiency.md#debounce-or-buffer-user-triggered-calls).
+
+## Still stuck?
+
+If the symptom isn't listed above, first re-check the exact signature in the relevant `references/` file — many "the method doesn't work" reports turn out to be a missed required parameter, not a bug. If the method genuinely isn't documented anywhere in these skills, treat it as unsupported rather than assuming it exists at runtime.

package/src/ai/catalog/pconnect-assignment-lifecycle/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pconnect-assignment-lifecycle
+description: 'Reference catalog and cookbook for PCore/PConnect APIs governing assignment and case submission lifecycle — ActionsApi, ContainerManager, ValidationApi, AttachmentUtils, ErrorHandler, and ConfirmDialogService — with recipes for opening an assignment in a modal, multi-step wizard navigation, bulk action submit, safe case deletion, custom destructive-action confirmation, attachment upload, graceful submit-failure handling, creating a case and jumping to a stage, approving/rejecting a case, and resolving/ignoring a duplicate case. Use when you need the exact signature for these APIs, or the correct order to call them to open, validate, submit, or delete an assignment/case.'
+user-invocable: true
+argument-hint: 'Use when opening, validating, submitting, or deleting an assignment/case, confirming a destructive action, or uploading an attachment — for the exact ActionsApi/ContainerManager/ValidationApi signature, or the correct call order.'
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Assignment & Submission Lifecycle — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for the **assignment and case submission lifecycle**: opening an assignment, validating it, submitting it, deleting a case, confirming a destructive action, and handling attachments. It is one of the PCore/PConnect API skills — see the [skills index](../README.md) for the full method catalog, architecture primer, and the other five skills.
+
+## When to Use This Skill
+
+Load this skill when:
+
+- You need the exact parameters, return type, or purpose of an `ActionsApi`, `ContainerManager`, `ValidationApi`, `AttachmentUtils`, `ErrorHandler`, or `ConfirmDialogService` method.
+- You're opening an assignment in a modal/container, submitting it, or deleting a case, and need the correct call order.
+- You're building a custom confirmation dialog before a destructive action, or handling a failed submit without losing user edits.
+
+If your task is about form/field validation state, cascading fields, or autosave rather than the submit/delete lifecycle itself, see [pconnect-forms-and-fields](../pconnect-forms-and-fields/SKILL.md) instead.
+
+New to PCore/PConnect? Start with [Architecture at a Glance](../references/architecture-overview.md).
+
+## Key Reference Files
+
+| File                                                                                                   | Class(es)                                           | Obtained via                  |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ----------------------------- |
+| [../references/pconnect-actions-api.md](../references/pconnect-actions-api.md)                         | `ActionsApi`                                        | `pConn.getActionsApi()`       |
+| [../references/pconnect-container-manager.md](../references/pconnect-container-manager.md)             | `ContainerManager`                                  | `pConn.getContainerManager()` |
+| [../references/pconnect-validation-api.md](../references/pconnect-validation-api.md)                   | `ValidationApi`                                     | `pConn.getValidationApi()`    |
+| [../references/pcore-case-collaboration-details.md](../references/pcore-case-collaboration-details.md) | `AttachmentUtils`                                   | `PCore.getAttachmentUtils()`  |
+| [../references/pcore-misc-details.md](../references/pcore-misc-details.md)                             | `ErrorHandler`, `FormUtils`, `ConfirmDialogService` | `PCore.get*()`                |
+
+See the [full reference index](../README.md) for every other PCore/PConnect method not directly related to this skill's topic.
+
+## Cookbooks
+
+Multi-method, ordering/cleanup recipes for this skill's topic live in [cookbooks/README.md](./cookbooks/README.md): modal assignment submit, multi-step wizard navigation, bulk action submit, safe case deletion, custom destructive-action confirmation, attachment upload, graceful submit-failure handling, creating a case and jumping to a target stage, approving or rejecting a case, and resolving or ignoring a duplicate case.
+
+Use the reference files above for a single method's signature. Use the cookbook index when you need the **order** multiple methods should be called in to complete a task.
+
+For testing components that call these APIs, security considerations (attachment uploads, destructive-action confirmation), idempotent/resilient retry and cancellation handling for submits, accessible loading/error states during a submit, or troubleshooting a call that isn't behaving as documented, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/README.md

@@ -0,0 +1,39 @@
+---
+title: Assignment & Submission Lifecycle Cookbook — Recipe Index
+description: Multi-method recipes for opening, validating, submitting, and deleting assignments/cases, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Assignment & Submission Lifecycle
+
+> Part of the [Assignment & Submission Lifecycle skill](../SKILL.md).
+
+Every file in [`../../references/`](../../references/) documents one method at a time. Each file in this folder shows how to **chain multiple documented methods together** to complete one common real-world task. Every recipe only uses methods already cataloged in `references/` — follow the links in each recipe for full signatures. Nothing here invents a new API; every call is a direct composition of already-documented methods.
+
+Each recipe is a single, self-contained file with:
+
+- YAML frontmatter (`keywords`, `primary_methods`, `related`) for structured/metadata search.
+- A **Problem** statement — what you're trying to accomplish, in plain language.
+- A **Solution** — the minimal correct code, linking to the individual reference files for each method used.
+- A **Discussion** — the ordering/cleanup/gotcha pitfall that makes this worth documenting as a recipe instead of assembling from scratch.
+- **Related recipes** — links to recipes that share a pattern (lifecycle, cleanup, error handling, etc.), including recipes in sibling skills.
+
+## Recipe Index
+
+Search by symptom or keyword before assembling a sequence of calls from scratch — there is a good chance the ordering/cleanup pitfalls have already been worked out below.
+
+| Recipe                                                                               | Keywords                                                                      | Primary methods                                   |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------- |
+| [Modal assignment submit](./modal-assignment-submit.md)                              | modal, dialog, submit, close, validate before submit, containerItemID         | `ContainerManager`, `ActionsApi`, `ValidationApi` |
+| [Multi-step wizard](./multi-step-wizard.md)                                          | stepper, process flow, next/previous, save between steps, finish on last step | `ActionsApi`                                      |
+| [Bulk action submit](./bulk-action-submit.md)                                        | select all, checkbox, mass update, multiple cases                             | `ListActions`, `ActionsApi`                       |
+| [Graceful submit failure handling](./graceful-submit-failure.md)                     | error handling, failed submit, generic error message, rollback                | `ErrorHandler`, `FormUtils`, `ActionsApi`         |
+| [Custom confirm before a destructive action](./confirm-before-destructive-action.md) | confirm dialog, are you sure, destructive action, custom modal                | `ConfirmDialogService`                            |
+| [Safe case deletion](./safe-case-deletion.md)                                        | delete case, cancel case, remove work object, create stage                    | `ActionsApi`                                      |
+| [Attachment upload](./attachment-upload.md)                                          | file upload, attach, progress, cancel, category                               | `AttachmentUtils`                                 |
+| [Create a case and jump to a target stage](./create-and-stage-new-case.md)           | create case, new case wizard, skip stage, jump to stage                       | `ActionsApi`                                      |
+| [Approve or reject a case](./approval-workflow-decision.md)                          | approval, reject, approve case, sign-off, decision step                       | `ActionsApi`, `ConfirmDialogService`              |
+| [Resolve or ignore a duplicate case](./resolve-or-ignore-duplicate.md)               | duplicate case, duplicate detection, merge case, ignore duplicate             | `ActionsApi`, `RelatedCasesApi`                   |
+
+Use the individual reference files in [`../../references/`](../../references/) to look up a single method's exact signature. Use a recipe here when you need to know the **order** multiple methods should be called in to complete a task.
+
+As more cookbooks are added, add one file per recipe (not more content to an existing recipe file) and a row here — see any existing recipe file for the expected frontmatter/structure.

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/approval-workflow-decision.md

@@ -0,0 +1,47 @@
+---
+title: Approve or reject a case in an approval step
+keywords: [approval, reject, approve case, sign-off, decision step]
+primary_methods: [ActionsApi.approveCase, ActionsApi.rejectCase]
+related: [confirm-before-destructive-action, graceful-submit-failure]
+---
+
+# Recipe: Approve or reject a case in an approval step
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+An approval assignment presents two outcomes — approve or reject — and the reject path should ask for confirmation first since it is harder to walk back than an approval.
+
+## Solution
+
+Uses [`ActionsApi`](../../references/pconnect-actions-api.md) and, for the confirmation step, [`ConfirmDialogService`](../../references/pcore-misc-details.md).
+
+```typescript
+async function approve(containerItemID) {
+  // approveCase both records the decision and finishes the assignment — do not call finishAssignment afterward.
+  await pConn.getActionsApi().approveCase(containerItemID);
+}
+
+async function rejectWithConfirmation(containerItemID) {
+  const confirmed = await PCore.getConfirmDialogService().confirm(
+    'This case will be sent back and cannot be re-approved from this step. Continue?'
+  );
+
+  if (!confirmed) return;
+
+  // rejectCase also finishes the assignment on its own.
+  await pConn.getActionsApi().rejectCase(containerItemID);
+}
+```
+
+## Discussion
+
+**MUST NOT** call `finishAssignment` after `approveCase`/`rejectCase` — both methods already finish the assignment as part of recording the decision; calling `finishAssignment` again submits an already-finished assignment.
+
+**SHOULD** gate the reject path behind an explicit confirmation (see [Custom confirm before a destructive action](./confirm-before-destructive-action.md)) since rejection is typically harder to reverse than approval, but treat this as a UX choice, not a requirement of the API itself — the API applies no such distinction.
+
+## Related recipes
+
+- [Custom confirm before a destructive action](./confirm-before-destructive-action.md)
+- [Graceful submit failure handling](./graceful-submit-failure.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/attachment-upload.md

@@ -0,0 +1,45 @@
+---
+title: Upload a file, attach it to a case, and handle a failed upload
+keywords: [file upload, attach, progress, cancel, category]
+primary_methods:
+  [AttachmentUtils.uploadAttachment, AttachmentUtils.linkAttachmentsToCase, AttachmentUtils.cancelRequest]
+related: [graceful-submit-failure]
+---
+
+# Recipe: Upload a file, attach it to a case, and handle a failed upload
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A file must be uploaded and linked to a case, with the upload and link steps failing independently and needing different recovery.
+
+## Solution
+
+Uses `PCore.getAttachmentUtils()` (see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { uploadAttachment, linkAttachmentsToCase, cancelRequest } = PCore.getAttachmentUtils();
+
+let uploadedFile;
+try {
+  uploadedFile = await uploadAttachment(file, onUploadProgress, onUploadError, context);
+} catch {
+  // The upload itself failed (network error, size/type rejection) — do not attempt to link.
+  return;
+}
+
+try {
+  await linkAttachmentsToCase(caseID, [uploadedFile], 'File', context);
+} catch {
+  // The file uploaded but failed to link — offer a retry for linking only, don't re-upload.
+}
+```
+
+## Discussion
+
+**MUST** call `cancelRequest(fileID)` if the user navigates away or cancels mid-upload, to stop the in-flight request rather than letting it complete and silently discarding the result.
+
+## Related recipes
+
+- [Handle a failed submit gracefully](./graceful-submit-failure.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/bulk-action-submit.md

@@ -0,0 +1,50 @@
+---
+title: Bulk-submit selected rows from a list
+keywords: [select all, checkbox, mass update, multiple cases, modal]
+primary_methods: [ListActions.getSelectedRows, ActionsApi.openBulkAction, ListActions.clearSelectedRows]
+related: [repeating-row-edit]
+---
+
+# Recipe: Bulk-submit selected rows from a list
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A user has selected several rows in a list and needs to submit a bulk action against exactly those rows, then clear the selection.
+
+## Solution
+
+Uses [`ListActions`](../../references/pconnect-list-actions.md) and [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+// The typedefs type the result as a bare `object`; with `withPayload` false it is the array of selected row keys.
+const selectedKeys = (await pConn.getListActions().getSelectedRows(false)) as string[];
+// getCaseSummary() is typed `any`; its documented keys are caseID, ID (assignment ID), caseClass, name, urgency, routedTo.
+// Confirm which keys your runtime returns for the bulk context before relying on these names.
+const { ID: bulkContextID, caseTypeID: bulkContextType } = pConn.getCaseSummary();
+
+await pConn.getActionsApi().openBulkAction(actionID, {
+  selectedList: selectedKeys,
+  containerName: 'modal',
+  bulkContextID,
+  bulkContextType,
+  callbacks: {
+    submit: async () => {
+      await pConn.getListActions().clearSelectedRows();
+    }
+  }
+});
+```
+
+## Discussion
+
+`getSelectedRows(false)` resolves to a `string[]` of selected row keys, not row objects — pass it straight through as `selectedList`.
+
+**NEVER** call `submitBulkAction` directly with the selected keys — `openBulkAction` opens the bulk-action modal and registers `submitBulkAction`/`submitBulkActionAsync` on its own submit button internally, and `submitBulkAction` only accepts a single `containerItemID` string established by the opened bulk-action context.
+
+**MUST** clear the selection inside the `submit` callback, which only fires once the platform confirms the bulk action was submitted.
+
+## Related recipes
+
+- [Edit a repeating row with validation, then save](../../pconnect-lists-and-views/cookbooks/repeating-row-edit.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/confirm-before-destructive-action.md

@@ -0,0 +1,43 @@
+---
+title: Show a custom confirmation dialog before a destructive action
+keywords: [confirm dialog, are you sure, destructive action, custom modal, delete attachment, remove participant]
+primary_methods: [ConfirmDialogService.registerConfirmHandler, ConfirmDialogService.confirm]
+related: [safe-case-deletion, graceful-submit-failure]
+---
+
+# Recipe: Show a custom confirmation dialog before a destructive action
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+An action like deleting an attachment or removing a participant has no built-in confirmation prompt, and the app wants its own styled confirm dialog — not the native browser `confirm()` — shown consistently before that action runs.
+
+## Solution
+
+Uses `ConfirmDialogService` (via `PCore.getConfirmDialogService()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+// Register once, near app bootstrap.
+PCore.getConfirmDialogService().registerConfirmHandler((message) => showCustomConfirmModal(message));
+
+// At the call site of the destructive action:
+async function onRemoveAttachment(attachmentID: string, context: string) {
+  const confirmed = await PCore.getConfirmDialogService().confirm(
+    'This attachment will be permanently removed. Continue?'
+  );
+  if (!confirmed) return;
+  await PCore.getAttachmentUtils().deleteAttachment(attachmentID, context);
+}
+```
+
+## Discussion
+
+`registerConfirmHandler` is global and last-write-wins. **NEVER** register it per-component — registering a second handler elsewhere in the app (for example, from another custom component) silently replaces the first. **ALWAYS** register it once during bootstrap instead.
+
+If no handler is ever registered, `confirm()` falls back to the native browser `confirm()` dialog — a missing registration won't crash the destructive action, but it does surface an inconsistent, unstyled prompt instead of failing loudly.
+
+## Related recipes
+
+- [Delete a case safely (create stage vs. an existing work object)](./safe-case-deletion.md)
+- [Handle a failed submit gracefully](./graceful-submit-failure.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/create-and-stage-new-case.md

@@ -0,0 +1,45 @@
+---
+title: Create a new case and jump directly to a target stage
+keywords: [create case, new case wizard, skip stage, jump to stage, case creation]
+primary_methods: [ActionsApi.createWork, ActionsApi.openStage, ActionsApi.finishAssignment]
+related: [multi-step-wizard, modal-assignment-submit]
+---
+
+# Recipe: Create a new case and jump directly to a target stage
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A "create case" affordance needs to create the case with some starting field values already known (for example, a case created from a picklist selection), then skip straight to a later stage instead of showing the case's default first stage.
+
+## Solution
+
+Uses [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+async function createCaseAtStage(className, startingFields, targetStageID) {
+  await pConn.getActionsApi().createWork(className, {
+    containerName: 'primary',
+    startingFields
+  });
+
+  // Only call openStage if the target stage differs from the case's default starting stage.
+  await pConn.getActionsApi().openStage(targetStageID);
+}
+
+async function finishCurrentStageAssignment(containerItemID) {
+  await pConn.getActionsApi().finishAssignment(containerItemID);
+}
+```
+
+## Discussion
+
+**MUST NOT** assume `createWork` alone lands the user on the desired stage — it always opens the case's configured first assignment. Call `openStage` afterward only when the target stage is known to differ from that default; calling it unconditionally on every creation adds a redundant navigation round trip.
+
+**MUST** treat `openStage` as a navigation call only — it does not submit or skip validation for stages in between. Any stage-entry data still needs to be collected and submitted through its own assignment(s).
+
+## Related recipes
+
+- [Multi-step wizard navigation with per-step save and final submit](./multi-step-wizard.md)
+- [Open an assignment in a modal, edit, validate, submit, and close](./modal-assignment-submit.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/graceful-submit-failure.md

@@ -0,0 +1,39 @@
+---
+title: Handle a failed submit gracefully
+keywords: [error handling, failed submit, generic error message, rollback]
+primary_methods: [ErrorHandler.setGenericFailedMessage, ActionsApi.finishAssignment, FormUtils.getChanges]
+related: [modal-assignment-submit, attachment-upload]
+---
+
+# Recipe: Handle a failed submit gracefully
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A submit call can fail server-side, and the user's in-progress edits must not be lost or silently discarded when that happens.
+
+## Solution
+
+Uses `ErrorHandler` and `FormUtils` (both via `PCore.get*()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)) together with [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+PCore.getErrorHandler().setGenericFailedMessage('We could not save your changes. Please try again.');
+
+try {
+  await pConn.getActionsApi().finishAssignment(containerItemID);
+} catch (error) {
+  // The assignment stays open and dirty — surface the changed fields so the user doesn't lose them.
+  const changedFields = PCore.getFormUtils().getChanges(context);
+  showRetryBanner(changedFields);
+}
+```
+
+## Discussion
+
+**NEVER** remove the container item or navigate away in the `catch` block — the whole point of leaving the assignment open is so the user's in-progress edits (tracked via `getChanges`) are not lost.
+
+## Related recipes
+
+- [Open an assignment in a modal, edit, validate, submit, and close](./modal-assignment-submit.md)
+- [Upload a file, attach it to a case, and handle a failed upload](./attachment-upload.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/modal-assignment-submit.md

@@ -0,0 +1,58 @@
+---
+title: Open an assignment in a modal, edit, validate, submit, and close
+keywords: [modal, dialog, submit, close, validate before submit, containerItemID]
+primary_methods:
+  [
+    ContainerManager.addContainerItem,
+    ActionsApi.openAssignment,
+    ValidationApi.validateEmail,
+    ActionsApi.finishAssignment,
+    ContainerManager.removeContainerItem
+  ]
+related: [full-form-validation, multi-step-wizard, graceful-submit-failure, safe-case-deletion]
+---
+
+# Recipe: Open an assignment in a modal, edit, validate, submit, and close
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+An assignment needs to open in a modal region, let the user edit a field, and only submit (and close the modal) once that field is valid.
+
+## Solution
+
+Uses [`ContainerManager`](../../references/pconnect-container-manager.md), [`ValidationApi`](../../references/pconnect-validation-api.md), and [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+const containerManager = pConn.getContainerManager();
+
+// 1. Add a container item to host the assignment in a modal region. addContainerItem's promise
+// resolves with null, not the container item — pass an explicit ID so it can be reused below.
+const containerItemID = `modalAssignment_${assignmentID}`;
+await containerManager.addContainerItem({ containerItemID, context, semanticURL: '' });
+
+// 2. Load the assignment into that container item.
+await pConn.getActionsApi().openAssignment(assignmentID, className, { containerName: 'modal' });
+
+// 3. Validate a field before allowing submission.
+const emailCheck = pConn.getValidationApi().validateEmail(emailValue);
+if (emailCheck.status === 'failure') {
+  // Surface emailCheck.message next to the field and stop here.
+} else {
+  // 4. Submit and close the modal.
+  await pConn.getActionsApi().finishAssignment(containerItemID);
+  await containerManager.removeContainerItem({ containerItemID });
+}
+```
+
+## Discussion
+
+**MUST:** call `finishAssignment` before `removeContainerItem`. `finishAssignment` submits server-side; NEVER remove the container item first — doing so closes the modal before you know whether the submission succeeded.
+
+## Related recipes
+
+- [Validate an entire form before allowing submit](../../pconnect-forms-and-fields/cookbooks/full-form-validation.md)
+- [Multi-step wizard navigation with per-step save and final submit](./multi-step-wizard.md)
+- [Handle a failed submit gracefully](./graceful-submit-failure.md)
+- [Delete a case safely (create stage vs. an existing work object)](./safe-case-deletion.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/multi-step-wizard.md

@@ -0,0 +1,44 @@
+---
+title: Multi-step wizard navigation with per-step save and final submit
+keywords: [stepper, process flow, next/previous, save between steps, finish on last step]
+primary_methods: [ActionsApi.saveAssignment, ActionsApi.finishAssignment, ActionsApi.navigateToStep]
+related: [modal-assignment-submit, full-form-validation]
+---
+
+# Recipe: Multi-step wizard navigation with per-step save and final submit
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A multi-step process needs to persist each step's data as the user advances, but only actually submit the assignment on the final step.
+
+## Solution
+
+Uses [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+async function goToNextStep(containerItemID, stepID, isLastStep) {
+  // Persist the current step's data before moving on, without submitting the assignment.
+  await pConn.getActionsApi().saveAssignment(containerItemID);
+
+  if (isLastStep) {
+    await pConn.getActionsApi().finishAssignment(containerItemID);
+  } else {
+    await pConn.getActionsApi().navigateToStep(stepID, containerItemID);
+  }
+}
+
+async function goToPreviousStep(containerItemID) {
+  await pConn.getActionsApi().navigateToStep('previous', containerItemID);
+}
+```
+
+## Discussion
+
+**NEVER** call `finishAssignment` on every step — it MUST only be called on the last step; intermediate steps MUST save (`saveAssignment`) without submitting.
+
+## Related recipes
+
+- [Open an assignment in a modal, edit, validate, submit, and close](./modal-assignment-submit.md)
+- [Validate an entire form before allowing submit](../../pconnect-forms-and-fields/cookbooks/full-form-validation.md)