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

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

@@ -0,0 +1,43 @@
+---
+title: Start and continue a GenAI Assistant conversation
+keywords: [chatbot, GenAI, coach, conversation, assistant]
+primary_methods:
+  [GenAIAssistantUtils.createConversation, GenAIAssistantUtils.sendMessage, GenAIAssistantUtils.getMessages]
+related: []
+---
+
+# Recipe: Start and continue a GenAI Assistant conversation
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to start a conversation with a configured GenAI Assistant, send a message, and then retrieve the Assistant's reply.
+
+## Solution
+
+Uses `GenAIAssistantUtils` (via `PCore.getGenAIAssistantUtils()`, see [pcore-analytics-genai-details.md](../../references/pcore-analytics-genai-details.md)).
+
+```typescript
+const { createConversation, sendMessage, getMessages } = PCore.getGenAIAssistantUtils();
+
+// Resolves to a ConversationResponse — the conversation ID is on `data.ID`, not `id`.
+const conversation = await createConversation(contextID, assistantID, context);
+const conversationID = conversation.data.ID;
+await sendMessage(assistantID, conversationID, userMessage, context);
+
+// Re-fetch messages to pick up the Assistant's reply once it's ready.
+// getMessages resolves to an AxiosResponse (not an array); the payload is on `response.data`.
+const response = await getMessages(assistantID, conversationID, context);
+const messages = response.data;
+```
+
+The 5.1.0 typedefs type `response.data` as `any`, so they do not specify the inner shape of the message list — confirm the field names against your server response before relying on them.
+
+## Discussion
+
+**MUST** use `createConversationForAgent`/`sendMessageForAgent`/`getMessagesForAgent` instead when talking to a configured Agent rather than an Assistant — the two conversation types are NOT interchangeable.
+
+## Related recipes
+
+None — see [pcore-analytics-genai-details.md](../../references/pcore-analytics-genai-details.md) for the full `GenAIAssistantUtils` catalog, including the Agent-specific variants.

package/src/ai/catalog/pconnect-navigation-locale-genai/cookbooks/locale-switch-and-relocalize.md

@@ -0,0 +1,38 @@
+---
+title: Switch the active locale and re-resolve already-fetched labels
+keywords: [locale switch, language change, i18n, localization, hot reload, getLocalizedText]
+primary_methods: [PCore.switchLocale, LocalizationService.getLocalizedText]
+related: [pubsub-cleanup]
+---
+
+# Recipe: Switch the active locale and re-resolve already-fetched labels
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A custom language switcher needs to change the operator's active locale at runtime, and any label text the component already resolved and stored in local state must be refreshed — it won't update on its own.
+
+## Solution
+
+Uses `PCore.switchLocale()` (see [pcore-environment-locale-namespace.md](../../references/pcore-environment-locale-namespace.md)) and `LocalizationService.getLocalizedText()` (see [pconnect-case-info-data-info-localization.md](../../references/pconnect-case-info-data-info-localization.md)).
+
+```typescript
+async function onLanguageChange(nextLocale: string) {
+  await PCore.switchLocale(nextLocale);
+
+  // Re-resolve any label already cached in component state — switchLocale
+  // does not retroactively update strings you resolved before it finished.
+  setSubmitLabel(pConn.getLocalizationService().getLocalizedText('Submit'));
+}
+```
+
+## Discussion
+
+**MUST** re-call `getLocalizedText`/`getLocalizedMessage` after `switchLocale` resolves, for any text your component holds in its own state rather than re-reading on every render. `switchLocale` resolves once the new locale bundle finishes loading, but it does NOT push updated values into code that already called `getLocalizedText` earlier and stored the result.
+
+If multiple sibling components (not just the one that triggered the switch) need to react, pair this with an application-wide event (see [Publish/subscribe between unrelated components](../../pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md)) rather than assuming every open component will independently notice the change.
+
+## Related recipes
+
+- [Publish/subscribe between unrelated components, with cleanup](../../pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md)

package/src/ai/catalog/pconnect-navigation-locale-genai/cookbooks/persist-operator-preferences.md

@@ -0,0 +1,40 @@
+---
+title: Store and restore an operator's persistent preferences
+keywords: [user settings, operator preferences, persist settings, remember preference, default view]
+primary_methods: [NavigationUtils.getUserSettings, NavigationUtils.setUserSettings]
+related: [persist-widget-ui-state]
+---
+
+# Recipe: Store and restore an operator's persistent preferences
+
+> Part of the [Navigation, Locale & GenAI cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to remember an operator's choice (a default view, a theme, a column layout) so it's restored the next time that operator logs in — not just across navigation within the current session, which [`NavigationUtils.getComponentState`](../../pconnect-forms-and-fields/cookbooks/persist-widget-ui-state.md) already covers.
+
+## Solution
+
+Uses `NavigationUtils` (via `PCore.getNavigationUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+const SETTINGS_PATH = 'myWidget.defaultView';
+
+const savedView = PCore.getNavigationUtils().getUserSettings(SETTINGS_PATH) ?? 'list';
+
+async function onDefaultViewChange(newView) {
+  // setUserSettings persists to the operator's own profile — the value is a string, so
+  // serialize non-string values before storing them.
+  await PCore.getNavigationUtils().setUserSettings(SETTINGS_PATH, newView);
+}
+```
+
+## Discussion
+
+**MUST** choose `getUserSettings`/`setUserSettings` (persisted to the operator's profile, survives across logins/devices) over `getComponentState`/`setComponentState` (persisted only within the current navigation session) or `getComponentCache`/`setComponentCache` (in-memory only) based on how long the value genuinely needs to live — see [Persist a custom widget's UI state across navigation](../../pconnect-forms-and-fields/cookbooks/persist-widget-ui-state.md) for the session-scoped alternative.
+
+**MUST** serialize non-string values (`JSON.stringify`) before calling `setUserSettings`, and parse them back out after `getUserSettings` — the API only accepts/returns a string value at this layer.
+
+## Related recipes
+
+- [Persist a custom widget's UI state across navigation](../../pconnect-forms-and-fields/cookbooks/persist-widget-ui-state.md)

package/src/ai/catalog/references/architecture-overview.md

@@ -0,0 +1,52 @@
+---
+title: PCore / PConnect Architecture at a Glance
+description: Shared architecture primer for all PCore/PConnect skills — PCore vs PConnect, and the sub-APIs reachable through PConnect.
+---
+
+# PCore / PConnect Architecture at a Glance
+
+> Referenced by every skill in the [skills index](../README.md).
+
+Pega Constellation exposes two global entry points to component code:
+
+- **`PCore`** — A global singleton available anywhere in the app (`window.PCore`). Use it for capabilities that don't require a specific component's context: environment/locale info, REST calls, data pages, pub/sub, constants, and other application-wide utilities. Never construct or import it — it's provided by the runtime.
+- **`PConnect`** — An object representing a _specific component's context_ in the rendered view tree, obtained via `getPConnect()` (passed to every component as a prop) or by creating one dynamically with `PCore.createPConnect(config).getPConnect()`. Use it to read/write the current field's value, dispatch case actions, iterate a component's children, or resolve view-relative configuration. In examples throughout these skills, a `PConnect` instance is referred to as `pConn`.
+
+```typescript
+// PCore: no component context needed
+const locale = PCore.getEnvironmentInfo().getLocale();
+
+// PConnect: needs the current component's context
+const MyComponent = ({ getPConnect }) => {
+  const pConn = getPConnect();
+  const value = pConn.getValue('.FirstName');
+  return null;
+};
+```
+
+## PCore vs PConnect — Quick Decision Guide
+
+| Need                                                               | Use        |
+| ------------------------------------------------------------------ | ---------- |
+| Read environment, locale, time zone                                | `PCore`    |
+| Make a REST call to a Pega API                                     | `PCore`    |
+| Subscribe to an application-wide event                             | `PCore`    |
+| Read or invalidate a data page                                     | `PCore`    |
+| Read a field value within the current component                    | `PConnect` |
+| Dispatch a field change / submit an assignment                     | `PConnect` |
+| Iterate children of a container component                          | `PConnect` |
+| Resolve config annotations against the current component's context | `PConnect` |
+
+## Sub-APIs Reached Through PConnect
+
+Several `pConn.*` methods return a further "sub-API" object with its own methods, rather than a plain value:
+
+| Accessor                         | Returns               | Used for                                                                     |
+| -------------------------------- | --------------------- | ---------------------------------------------------------------------------- |
+| `pConn.getActionsApi()`          | `ActionsApi`          | Case/work lifecycle, navigation, data object CRUD, field updates             |
+| `pConn.getValidationApi()`       | `ValidationApi`       | Field-level validation                                                       |
+| `pConn.getContainerManager()`    | `ContainerManager`    | Managing items within a container region                                     |
+| `pConn.getCaseInfo()`            | `CaseInfo`            | Case-level metadata (ID, class, stages, assignments)                         |
+| `pConn.getDataInfo()`            | `DataInfo`            | Data-object-level context metadata                                           |
+| `pConn.getLocalizationService()` | `LocalizationService` | Resolving localized text                                                     |
+| `pConn.getListActions()`         | `ListActions`         | Insert/update/delete/reorder/select operations on page-list (repeating) data |