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

package/src/ai/catalog/pconnect-lists-and-views/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pconnect-lists-and-views
+description: 'Reference catalog and cookbook for PCore/PConnect APIs governing lists, containers, and view state — ListActions, ContainerManager, ContainerUtils, and PersonalizationUtils — with recipes for editing a repeating row with validation, personalizing and restoring a saved list view, managing non-assignment container item lifecycle, inserting/deleting list rows, reordering list rows, and switching between container items with an unsaved-changes guard. Use when you need the exact signature for these APIs, or the correct order to call them to edit list rows or manage container items.'
+user-invocable: true
+argument-hint: 'Use when editing a repeating row/table, saving or restoring a personalized list view, or adding/closing items in a non-assignment container — for the exact ListActions/ContainerManager/ContainerUtils/PersonalizationUtils signature, or the correct call order.'
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Lists, Containers & Views — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for **lists, containers, and view state**: repeating row edits, saved list view personalization, and non-assignment container item lifecycle. 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 a `ListActions`, `ContainerManager`, `ContainerUtils`, or `PersonalizationUtils` method.
+- You're validating and updating a field within a repeating row/table (not a top-level form).
+- You're letting users save/restore a personalized sort, filter, or column configuration for a list.
+- You're adding a non-assignment view to a multi-item container (for example, a side panel) without losing items already open.
+
+If your task is about submitting an assignment inside a modal container, see [pconnect-assignment-lifecycle](../pconnect-assignment-lifecycle/SKILL.md) instead — that skill covers the single-assignment modal submit flow.
+
+New to PCore/PConnect? Start with [Architecture at a Glance](../references/architecture-overview.md).
+
+## Key Reference Files
+
+| File                                                                                                   | Class(es)                               | Obtained via                      |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------- | --------------------------------- |
+| [../references/pconnect-list-actions.md](../references/pconnect-list-actions.md)                       | `ListActions`                           | `pConn.getListActions()`          |
+| [../references/pconnect-container-manager.md](../references/pconnect-container-manager.md)             | `ContainerManager`                      | `pConn.getContainerManager()`     |
+| [../references/pcore-case-collaboration-details.md](../references/pcore-case-collaboration-details.md) | `ContainerUtils`                        | `PCore.getContainerUtils()`       |
+| [../references/pcore-case-collaboration-genai.md](../references/pcore-case-collaboration-genai.md)     | `PersonalizationUtils` (accessor-level) | `PCore.getPersonalizationUtils()` |
+
+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): editing a repeating row with validation, saved list view personalization, non-assignment container item lifecycle, inserting/deleting list rows, reordering list rows, and switching between container items with an unsaved-changes guard.
+
+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, performance (batching row operations, virtualizing long lists), or troubleshooting a personalization/container issue that isn't behaving as documented, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/README.md

@@ -0,0 +1,35 @@
+---
+title: Lists, Containers & Views Cookbook — Recipe Index
+description: Multi-method recipes for repeating row edits, list view personalization, and container item lifecycle, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Lists, Containers & Views
+
+> Part of the [Lists, Containers & Views 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                      |
+| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------ |
+| [Repeating row edit](./repeating-row-edit.md)                                                    | table row, grid, embedded list, inline edit, field-level validation                 | `ListActions`, `ValidationApi`       |
+| [Saved list view personalization](./view-personalization.md)                                     | saved view, personalization, sort filter preference, remember columns               | `PersonalizationUtils`               |
+| [Container item lifecycle](./container-item-lifecycle.md)                                        | utility container, side panel, non-assignment view, multiple container, dirty check | `ContainerManager`, `ContainerUtils` |
+| [Insert and delete list rows](./insert-delete-list-rows.md)                                      | add row, remove row, insert row, delete row, dynamic list, embedded list            | `ListActions`                        |
+| [Reorder list rows](./reorder-list-rows.md)                                                      | reorder, drag and drop, move row, priority list, sequence                           | `ListActions`                        |
+| [Switch container items with an unsaved-changes guard](./activate-and-switch-container-items.md) | tabs, switch tab, side panel, active item, unsaved changes guard                    | `ContainerManager`, `ContainerUtils` |
+
+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-lists-and-views/cookbooks/activate-and-switch-container-items.md

@@ -0,0 +1,52 @@
+---
+title: Switch between container items with an unsaved-changes guard
+keywords: [tabs, switch tab, side panel, active item, unsaved changes guard, dirty check]
+primary_methods:
+  [
+    ContainerManager.activateContainerItem,
+    ContainerManager.hasContainerItems,
+    ContainerUtils.isContainerDirty,
+    ContainerUtils.getActiveContainerItemName
+  ]
+related: [container-item-lifecycle]
+---
+
+# Recipe: Switch between container items with an unsaved-changes guard
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A container hosts several items at once (for example, tabs or a multi-document side panel), and switching the active item should warn the user first if the currently active item has unsaved changes.
+
+## Solution
+
+Uses [`ContainerManager`](../../references/pconnect-container-manager.md) and `ContainerUtils` (via `PCore.getContainerUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+async function onSwitchTab(targetContainerItemID, targetName) {
+  const containerManager = pConn.getContainerManager();
+  const containerUtils = PCore.getContainerUtils();
+
+  if (!containerManager.hasContainerItems()) return;
+
+  const activeItemName = containerUtils.getActiveContainerItemName(targetName);
+  if (activeItemName && containerUtils.isContainerDirty(activeItemName)) {
+    const confirmed = await confirmSwitchAwayFromUnsavedTab();
+    if (!confirmed) return;
+  }
+
+  await containerManager.activateContainerItem({ containerItemID: targetContainerItemID });
+}
+```
+
+## Discussion
+
+**MUST** check `hasContainerItems` before calling `getActiveContainerItemName`/`isContainerDirty` on a container that may not have any items yet — calling them on an empty container is a common source of an unhelpful "no active item" branch being reached silently instead of being guarded against explicitly.
+
+**SHOULD** reuse the same confirmation pattern as [Show a custom confirmation dialog before a destructive action](../../pconnect-assignment-lifecycle/cookbooks/confirm-before-destructive-action.md) rather than a one-off `window.confirm`, so switching away from unsaved work is visually consistent with other destructive/interrupting confirmations in the app.
+
+## Related recipes
+
+- [Add a non-assignment view to a multi-item container without losing existing items](./container-item-lifecycle.md)
+- [Show a custom confirmation dialog before a destructive action](../../pconnect-assignment-lifecycle/cookbooks/confirm-before-destructive-action.md)

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/container-item-lifecycle.md

@@ -0,0 +1,61 @@
+---
+title: Add a non-assignment view to a multi-item container without losing existing items
+keywords:
+  [
+    utility container,
+    side panel,
+    non-assignment view,
+    multiple container,
+    addContainerItem,
+    dirty check,
+    closeContainerItem
+  ]
+primary_methods:
+  [
+    ContainerManager.initializeContainers,
+    ContainerManager.addContainerItem,
+    ContainerUtils.isContainerInitialized,
+    ContainerUtils.closeContainerItem
+  ]
+related: [modal-assignment-submit, full-form-validation]
+---
+
+# Recipe: Add a non-assignment view to a multi-item container without losing existing items
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A custom shell wants a "multiple" container (for example, a side panel that can hold several open items at once, like a document comparison view) that can add arbitrary views — not just assignments — without wiping out items a user already has open, and that checks for unsaved changes before closing one.
+
+## Solution
+
+Uses [`ContainerManager`](../../references/pconnect-container-manager.md) and `ContainerUtils` (via `PCore.getContainerUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const containerManager = pConn.getContainerManager();
+const containerUtils = PCore.getContainerUtils();
+
+if (!containerUtils.isContainerInitialized(context, containerName)) {
+  await containerManager.initializeContainers({ type: 'multiple', name: containerName });
+}
+
+await containerManager.addContainerItem({ context, semanticURL: '' });
+
+// Later, when the user closes one item:
+async function onCloseItem(containerItemID: string) {
+  if (containerUtils.isContainerDirty(containerItemID) && !(await confirmDiscard())) return;
+  await containerUtils.closeContainerItem(containerItemID, { skipDirtyCheck: true });
+}
+```
+
+## Discussion
+
+**NEVER** call `initializeContainers` unconditionally before every `addContainerItem` — for a `multiple` container, re-initializing resets the items a user already has open. **ALWAYS** guard it with `isContainerInitialized` first.
+
+`closeContainerItem` (on `ContainerUtils`) and `removeContainerItem` (on `ContainerManager`) are not interchangeable: `closeContainerItem` performs the dirty check itself unless you pass `skipDirtyCheck`, which is why this recipe checks `isContainerDirty` up front and then explicitly skips the built-in check to avoid asking the user twice.
+
+## Related recipes
+
+- [Open an assignment in a modal, edit, validate, submit, and close](../../pconnect-assignment-lifecycle/cookbooks/modal-assignment-submit.md)
+- [Full-form validation before submit](../../pconnect-forms-and-fields/cookbooks/full-form-validation.md)

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/insert-delete-list-rows.md

@@ -0,0 +1,40 @@
+---
+title: Insert and delete rows in an embedded list
+keywords: [add row, remove row, insert row, delete row, dynamic list, embedded list]
+primary_methods: [ListActions.insert, ListActions.deleteEntry]
+related: [repeating-row-edit, reorder-list-rows]
+---
+
+# Recipe: Insert and delete rows in an embedded list
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+An embedded/repeating list needs an "Add row" and "Remove row" affordance — inserting a new row at a specific position, or deleting an existing one — distinct from editing a field within an existing row.
+
+## Solution
+
+Uses [`ListActions`](../../references/pconnect-list-actions.md).
+
+```typescript
+function onAddRowClick(newRowDefaults) {
+  // Inserts at index 0 so the newest row appears first; use the list's current length to append instead.
+  pConn.getListActions().insert(newRowDefaults, 0);
+}
+
+function onRemoveRowClick(rowIndex) {
+  pConn.getListActions().deleteEntry(rowIndex);
+}
+```
+
+## Discussion
+
+**MUST** pass a complete-enough `payload` to `insert` so the new row renders without missing required fields — unlike `update`/`updateProperty`, there's no existing row data to fall back on for fields the payload omits.
+
+**SHOULD** re-validate any fields whose validity depends on row count or ordering (for example, "at least one row required") after a `deleteEntry` call — deleting a row can flip a form from valid to invalid without any field-level `validate()` call being triggered on its own.
+
+## Related recipes
+
+- [Edit a repeating row with validation, then save](./repeating-row-edit.md)
+- [Reorder rows in a list](./reorder-list-rows.md)

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/reorder-list-rows.md

@@ -0,0 +1,39 @@
+---
+title: Reorder rows in a list
+keywords: [reorder, drag and drop, move row, priority list, sequence]
+primary_methods: [ListActions.reorder]
+related: [insert-delete-list-rows]
+---
+
+# Recipe: Reorder rows in a list
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A list where row order itself is meaningful (a priority queue, a ranked sequence of steps) needs to support moving a row to a new position, whether via drag-and-drop or explicit "move up"/"move down" controls.
+
+## Solution
+
+Uses [`ListActions`](../../references/pconnect-list-actions.md).
+
+```typescript
+function onDropRow(fromIndex, toIndex) {
+  pConn.getListActions().reorder(fromIndex, toIndex);
+}
+
+function onMoveUpClick(index) {
+  if (index === 0) return;
+  pConn.getListActions().reorder(index, index - 1);
+}
+```
+
+## Discussion
+
+**MUST** compute `fromIndex`/`toIndex` from the list's current in-memory order at the moment of the call, not from a stale index captured earlier in the render — if the list can change between when a drag starts and when it's dropped (for example, another user's real-time update arrives mid-drag), a stale index reorders the wrong row.
+
+**SHOULD** treat `reorder` as void/fire-and-forget for the row data itself, but still re-render from the updated list state rather than optimistically re-ordering local component state independently — `reorder` already updates the underlying store, so a separately-maintained local copy can drift out of sync.
+
+## Related recipes
+
+- [Insert and delete rows in an embedded list](./insert-delete-list-rows.md)

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/repeating-row-edit.md

@@ -0,0 +1,39 @@
+---
+title: Edit a repeating row with validation, then save
+keywords: [table row, grid, embedded list, inline edit, field-level validation]
+primary_methods: [ValidationApi.validate, ListActions.updateProperty]
+related: [bulk-action-submit, full-form-validation]
+---
+
+# Recipe: Edit a repeating row with validation, then save
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A field within a repeating row (table/grid) needs to be validated before the row's underlying data is updated.
+
+## Solution
+
+Uses [`ListActions`](../../references/pconnect-list-actions.md) and [`ValidationApi`](../../references/pconnect-validation-api.md).
+
+```typescript
+const result = pConn.getValidationApi().validate(newExperienceValue, '.Experience');
+
+if (result.status) {
+  pConn.getListActions().updateProperty('.Experience', newExperienceValue);
+} else {
+  // result.message contains the validation error to display on the row.
+}
+```
+
+## Discussion
+
+`validate()` (unlike `validateEmail()`) writes the error directly into application state, so the field itself will show `result.message` without extra wiring.
+
+The 5.1.0 typedefs type `updateProperty`'s `value` as `GenericObject | undefined` (`Record<string, unknown>`), so a primitive value needs a cast to compile — for example `newExperienceValue as unknown as Record<string, unknown>`.
+
+## Related recipes
+
+- [Bulk-submit selected rows from a list](../../pconnect-assignment-lifecycle/cookbooks/bulk-action-submit.md)
+- [Validate an entire form before allowing submit](../../pconnect-forms-and-fields/cookbooks/full-form-validation.md)

package/src/ai/catalog/pconnect-lists-and-views/cookbooks/view-personalization.md

@@ -0,0 +1,60 @@
+---
+title: Let end users save and restore a personalized list view
+keywords: [saved view, personalization, sort filter preference, remember columns, list view]
+primary_methods:
+  [
+    PCore.getPersonalizationUtils,
+    PersonalizationUtils.fetchPersonalizations,
+    PersonalizationUtils.createPersonalization,
+    PersonalizationUtils.updatePersonalization
+  ]
+related: [repeating-row-edit]
+---
+
+# Recipe: Let end users save and restore a personalized list view
+
+> Part of the [Lists, Containers & Views cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A list/table component wants to let users save their current sort/filter/column configuration and reapply it later, without inventing a custom storage mechanism.
+
+## Solution
+
+Uses `PCore.getPersonalizationUtils(listID)` (see [pcore-case-collaboration-genai.md](../../references/pcore-case-collaboration-genai.md)).
+
+```typescript
+const personalizationUtils = PCore.getPersonalizationUtils(listComponentID);
+
+// Resolves to a PersonalizationStore — { allPersonalizations, defaultPersonalization } — or an AxiosResponse wrapping one.
+// allPersonalizations is either RawPersonalization[] (each with name, personalizationID, personalizationState)
+// or a Personalizations map keyed by personalization key.
+const savedViews = await personalizationUtils.fetchPersonalizations();
+
+// Types below are from the typedefs' rules/types.d.ts.
+async function saveCurrentView(
+  personalizationID: string,
+  name: string,
+  personalizationState: PersonalizationState,
+  alreadySaved: boolean // decide this from `savedViews`
+) {
+  const info: CreatePersonalizationInfo = { name, personalizationState, markAsDefault: false };
+  if (alreadySaved) {
+    await personalizationUtils.updatePersonalization(personalizationID, info);
+  } else {
+    await personalizationUtils.createPersonalization(personalizationID, info);
+  }
+}
+```
+
+`createPersonalization` and `updatePersonalization` both take `(personalizationID: string, personalizedState: CreatePersonalizationInfo)`, where `CreatePersonalizationInfo` is `{ name: string; personalizationState: PersonalizationState; markAsDefault: boolean; markAsAppDefault?: boolean }`. The typedefs do not say how a new `personalizationID` is chosen.
+
+## Discussion
+
+**MUST** keep `listComponentID` stable and unique per list instance (limited to 32 characters). **NEVER** reuse the same ID for two different list components on the same view — their saved personalizations will silently overwrite each other.
+
+A falsy `listComponentID` doesn't throw — `getPersonalizationUtils` returns safe no-op stubs instead, so a "Save view" button can appear to work while doing nothing. **ALWAYS** confirm `listComponentID` resolved to a real value before wiring one up.
+
+## Related recipes
+
+- [Repeating row edit](./repeating-row-edit.md)

package/src/ai/catalog/pconnect-navigation-locale-genai/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pconnect-navigation-locale-genai
+description: 'Reference catalog and cookbook for PCore/PConnect APIs governing navigation, localization, and GenAI Assistant integration — SemanticUrlUtils, NavigationUtils, PCore.switchLocale, LocalizationService, and GenAIAssistantUtils — with recipes for building a shareable deep link, switching locale and re-resolving labels, starting a GenAI Assistant conversation, persisting operator preferences, keeping filter/sort state bookmarkable in the URL, and starting an Agent conversation for task automation. Use when you need the exact signature for these APIs, or the correct order to call them for deep linking, localization, or GenAI conversations.'
+user-invocable: true
+argument-hint: 'Use when building a shareable deep link/semantic URL, switching the active locale and re-resolving labels, or starting a GenAI Assistant conversation — for the exact SemanticUrlUtils/PCore.switchLocale/GenAIAssistantUtils signature, or the correct call order.'
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Navigation, Locale & GenAI — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for **navigation, localization, and GenAI Assistant integration**: shareable deep links, locale switching, and GenAI Assistant conversations. 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 a `SemanticUrlUtils`, `NavigationUtils` (URL params), `PCore.switchLocale`, `LocalizationService`, or `GenAIAssistantUtils` method.
+- You're building a shareable/bookmarkable URL to a specific case or assignment, or reading an identifier back out of the current URL.
+- You're switching the operator's active locale at runtime and need to refresh already-resolved label text.
+- You're starting or continuing a conversation with a configured GenAI Assistant or Agent.
+
+If your task is about persisting a custom widget's own UI state (not the URL) across navigation, 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/pcore-messaging-details.md](../references/pcore-messaging-details.md)                                     | `SemanticUrlUtils`                | `PCore.getSemanticUrlUtils()`    |
+| [../references/pcore-misc-details.md](../references/pcore-misc-details.md)                                               | `NavigationUtils`                 | `PCore.getNavigationUtils()`     |
+| [../references/pcore-environment-locale-namespace.md](../references/pcore-environment-locale-namespace.md)               | Locale switching (accessor-level) | `PCore.switchLocale()`           |
+| [../references/pconnect-case-info-data-info-localization.md](../references/pconnect-case-info-data-info-localization.md) | `LocalizationService`             | `pConn.getLocalizationService()` |
+| [../references/pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md)                         | `GenAIAssistantUtils`             | `PCore.getGenAIAssistantUtils()` |
+
+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): building a shareable deep link, switching locale and re-resolving labels, starting a GenAI Assistant conversation, persisting operator preferences, keeping filter/sort state bookmarkable in the URL, and starting an Agent conversation for task automation.
+
+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 (deep links, sanitizing GenAI Assistant responses, prompt injection), performance/resiliency for GenAI calls, dedicated GenAI Assistant conversation-integration patterns, accessible focus management after a locale/navigation change, or troubleshooting a call that isn't behaving as documented, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-navigation-locale-genai/cookbooks/README.md

@@ -0,0 +1,35 @@
+---
+title: Navigation, Locale & GenAI Cookbook — Recipe Index
+description: Multi-method recipes for deep links, locale switching, and GenAI Assistant conversations, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Navigation, Locale & GenAI
+
+> Part of the [Navigation, Locale & GenAI 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                             |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------- |
+| [Deep link to a case or assignment](./deep-link-semantic-url.md)                     | deep link, semantic URL, shareable link, permalink, bookmark, query param   | `SemanticUrlUtils`, `NavigationUtils`       |
+| [Locale switch and re-localize](./locale-switch-and-relocalize.md)                   | locale switch, language change, i18n, localization, hot reload              | `PCore.switchLocale`, `LocalizationService` |
+| [GenAI Assistant conversation](./genai-assistant-conversation.md)                    | chatbot, GenAI, coach, conversation, assistant                              | `GenAIAssistantUtils`                       |
+| [Store and restore operator preferences](./persist-operator-preferences.md)          | user settings, operator preferences, persist settings, remember preference  | `NavigationUtils`                           |
+| [Keep filter/sort state bookmarkable in the URL](./bookmarkable-filter-state.md)     | bookmarkable filters, URL state, query parameters, shareable filtered view  | `NavigationUtils`                           |
+| [Start an Agent conversation for task automation](./agent-conversation-for-tasks.md) | agent, task automation, GenAI agent, agent conversation, like agent message | `GenAIAssistantUtils`                       |
+
+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-navigation-locale-genai/cookbooks/agent-conversation-for-tasks.md

@@ -0,0 +1,54 @@
+---
+title: Start an Agent conversation for task automation
+keywords: [agent, task automation, GenAI agent, agent conversation, like agent message]
+primary_methods:
+  [
+    GenAIAssistantUtils.createConversationForAgent,
+    GenAIAssistantUtils.sendMessageForAgent,
+    GenAIAssistantUtils.getMessagesForAgent,
+    GenAIAssistantUtils.likeAgentMessage
+  ]
+related: [genai-assistant-conversation]
+---
+
+# Recipe: Start an Agent conversation for task automation
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to hand off a task to a configured Agent (for example, "resolve this case" automation) rather than a conversational GenAI Assistant — a distinct API surface from [Start and continue a GenAI Assistant conversation](./genai-assistant-conversation.md).
+
+## Solution
+
+Uses `GenAIAssistantUtils` (via `PCore.getGenAIAssistantUtils()`, see [pcore-analytics-genai-details.md](../../references/pcore-analytics-genai-details.md)).
+
+```typescript
+const { createConversationForAgent, sendMessageForAgent, getMessagesForAgent, likeAgentMessage } =
+  PCore.getGenAIAssistantUtils();
+
+// Resolves to a ConversationResponse — the conversation ID is on `data.ID`, not `id`.
+const conversation = await createConversationForAgent(contextID, agentID, context);
+const conversationID = conversation.data.ID;
+await sendMessageForAgent(agentID, conversationID, taskInstruction, context);
+
+// Re-fetch to pick up the Agent's response/result once it's ready.
+// getMessagesForAgent resolves to an AxiosResponse (not an array); the payload is on `response.data`.
+const response = await getMessagesForAgent(agentID, conversationID, context);
+
+// Feedback uses the Agent-specific like/unlike methods, not the Assistant ones.
+// `messageID` is the ID of the Agent message being rated, read from `response.data`.
+await likeAgentMessage(agentID, conversationID, messageID, context);
+```
+
+The 5.1.0 typedefs type `response.data` as `any`, so they do not specify the shape of the message list (or the field that holds a message ID) — confirm it against your server response.
+
+## Discussion
+
+**MUST NOT** mix Assistant methods (`createConversation`, `sendMessage`, `getMessages`, `likeAgentMessage`'s Assistant counterpart) with Agent methods (`createConversationForAgent`, `sendMessageForAgent`, `getMessagesForAgent`, `likeAgentMessage`) for the same conversation — the two conversation types are tracked separately server-side, and mixing them for one conversation ID (`conversation.data.ID`) produces a conversation that neither API can fully read back.
+
+**SHOULD** gate rendering of any Agent-conversation affordance on `PCore.getEnvironmentInfo().isGenAIEnabled()`, the same gate used for Assistant conversations — see the [GenAI Assistant integration patterns guide](../../best-practices/genai-assistant-integration-patterns.md).
+
+## Related recipes
+
+- [Start and continue a GenAI Assistant conversation](./genai-assistant-conversation.md)

package/src/ai/catalog/pconnect-navigation-locale-genai/cookbooks/bookmarkable-filter-state.md

@@ -0,0 +1,40 @@
+---
+title: Keep filter and sort state bookmarkable in the URL
+keywords: [bookmarkable filters, URL state, query parameters, shareable filtered view, filter persistence]
+primary_methods: [NavigationUtils.getURLParam, NavigationUtils.setURLParam]
+related: [deep-link-semantic-url]
+---
+
+# Recipe: Keep filter and sort state bookmarkable in the URL
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A list/grid's filter and sort selections should be reflected in the URL's query parameters, so a user can bookmark or share the exact filtered view with a colleague — distinct from [building a semantic deep link to a case or assignment](./deep-link-semantic-url.md), which targets a specific record rather than a filter state.
+
+## Solution
+
+Uses `NavigationUtils` (via `PCore.getNavigationUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+const { getURLParam, setURLParam } = PCore.getNavigationUtils();
+
+// On initial render, restore filters from the URL if present.
+const initialStatus = getURLParam('status', true) ?? 'all';
+
+function onFilterChange(newStatus) {
+  setURLParam('status', newStatus, true);
+  applyFilter(newStatus);
+}
+```
+
+## Discussion
+
+**MUST** pass matching `decode`/`encode` flags on the read and write sides — a value written with `encode: true` but read back with `decode: false` (or vice versa) can produce a mismatched or double-encoded value for filter text containing special characters (spaces, `&`, `#`).
+
+**SHOULD** keep this pattern limited to shallow, display-only filter/sort state — for identifying a specific record to reopen, use [Build a shareable deep link to a specific case or assignment](./deep-link-semantic-url.md) and its semantic-URL route keys instead, since those are recognized by Constellation's own router on reload and plain query parameters are not.
+
+## Related recipes
+
+- [Build a shareable deep link to a specific case or assignment](./deep-link-semantic-url.md)

package/src/ai/catalog/pconnect-navigation-locale-genai/cookbooks/deep-link-semantic-url.md

@@ -0,0 +1,39 @@
+---
+title: Build a shareable deep link to a specific case or assignment
+keywords: [deep link, semantic URL, shareable link, permalink, bookmark, query param]
+primary_methods: [SemanticUrlUtils.getResolvedSemanticURL, SemanticUrlUtils.getActions, NavigationUtils.getURLParam]
+related: [multi-step-wizard]
+---
+
+# Recipe: Build a shareable deep link to a specific case or assignment
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A custom component needs to generate a URL a user can copy, bookmark, or share that reopens the exact case/assignment view, and later read that same identifying parameter back out when the app loads from that URL.
+
+## Solution
+
+Uses `SemanticUrlUtils` and `NavigationUtils` (both via `PCore.get*()`, see [pcore-messaging-details.md](../../references/pcore-messaging-details.md) and [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+const { getResolvedSemanticURL, getActions } = PCore.getSemanticUrlUtils();
+
+const shareableUrl = getResolvedSemanticURL(
+  getActions().ACTION_OPENWORKBYHANDLE,
+  { caseClassName: pConn.getCaseInfo().getClassName() },
+  { workID: pConn.getCaseInfo().getID() }
+);
+
+// On load, read the identifier back out of the current URL.
+const workIDFromUrl = PCore.getNavigationUtils().getURLParam('workID', true);
+```
+
+## Discussion
+
+**MUST** source the `routeKey` from `getActions()` rather than hardcoding a string literal. **NEVER** hardcode it — an arbitrary string produces a URL that Constellation's own router won't recognize on reload, so the "deep link" silently fails to reopen the right view when a user later pastes it into a browser. **MUST** use `getActions().ACTION_OPENWORKBYHANDLE` for a case/assignment deep link — `getActions()` does not expose an `OPEN_ASSIGNMENT` key; the supported keys are `ACTION_OPENWORKBYHANDLE`, `ACTION_SHOWDATA`, `ACTION_SHOWVIEW`, `ACTION_GETOBJECT`, `ACTION_SHOWINSIGHT`, and `ACTION_SHOWDASHBOARD`.
+
+## Related recipes
+
+- [Multi-step wizard navigation with per-step save and final submit](../../pconnect-assignment-lifecycle/cookbooks/multi-step-wizard.md)