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

package/src/ai/catalog/best-practices/genai-assistant-integration-patterns.md

@@ -0,0 +1,49 @@
+---
+title: GenAI Assistant Integration Patterns
+description: Conversation lifecycle, state rehydration, streaming, feedback, and safety-gate patterns for building custom components on top of GenAIAssistantUtils and GenAIUtils.
+---
+
+# GenAI Assistant Integration Patterns
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+`GenAIAssistantUtils` and `GenAIUtils` (see [pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md) and [pcore-case-collaboration-genai.md](../references/pcore-case-collaboration-genai.md)) let a custom component start and continue a conversation with a GenAI Assistant or Agent, and rewrite text. This guide covers the integration patterns specific to these APIs — for content-safety concerns (prompt injection, sanitizing model output), see [Security Considerations](./security-considerations.md); for the general async-state and mocking patterns, see [Testing](./testing-pconnect-components.md#testing-genai-assistant-conversations) and [Error Handling & Resiliency](./error-handling-and-resiliency.md).
+
+## Gate on `isGenAIEnabled()` Before Rendering Any GenAI Affordance
+
+Not every environment has GenAI enabled. Check `PCore.getEnvironmentInfo().isGenAIEnabled()` before rendering a GenAI-dependent button, panel, or suggestion — and treat "disabled" as an expected, silent state (simply don't render the affordance), not an error condition to surface to the user:
+
+```typescript
+const genAIEnabled = PCore.getEnvironmentInfo().isGenAIEnabled();
+
+if (!genAIEnabled) return null; // no GenAI affordance in this environment — not an error
+```
+
+## Rehydrate Conversation History Instead of Trusting Local State Alone
+
+`createConversation`/`createConversationForAgent` start a conversation that's tracked server-side; `getMessages`/`getMessagesForAgent` and the paginated `getConversations`/`getConversationsForAgent` retrieve what's already there. Local component state built up as the user sends/receives messages in the current session is a convenient cache, but it is not the source of truth — on mount (or when reopening a previously started conversation), call `getMessages(assistantID, conversationID, context)` to rehydrate rather than assuming a fresh component instance starts with no history (see [Troubleshooting: a GenAI Assistant conversation's history is empty after a page reload](./troubleshooting-common-pitfalls.md#a-genai-assistant-conversations-history-is-empty-after-a-page-reload)).
+
+## Render Incrementally When `enableStreaming` Is Used
+
+`sendMessage` supports an `enableStreaming` option for a more responsive, incremental reply rather than waiting for the full response. If a component uses streaming, render the partial response as it arrives (with its own visible "in progress" indicator distinct from a fully-loaded message) rather than buffering the whole thing client-side and only rendering once — buffering defeats the purpose of requesting streaming in the first place and leaves the user staring at nothing for longer than necessary.
+
+## Handle `GenAIUtils.rewriteText`'s Discriminated Result Explicitly
+
+`rewriteText({ originalText, rewriteAction })` resolves an object shaped as either `{ success: true, rewrittenText }` or a failure shape — it does not reject on a model-side failure the way a network error would. Check `result.success` explicitly and handle both branches (see [Testing: testing GenAI Assistant conversations](./testing-pconnect-components.md#testing-genai-assistant-conversations)); a component that only reads `result.rewrittenText` without checking `success` first will render `undefined` on failure instead of a clear fallback message.
+
+## Use the Like/Unlike Feedback Loop, Don't Build a Parallel One
+
+`likeAgentMessage`/`unLikeAgentMessage(agentID, conversationID, messageID, context, feedbackText?)` are the documented mechanism for capturing a user's reaction to an Agent's message, including optional free-text feedback on removal of a like. Route thumbs-up/thumbs-down UI through these calls rather than inventing a separate feedback-collection mechanism — this keeps feedback attached to the same conversation/message record the platform already tracks, rather than living in a disconnected system nobody correlates back to the conversation.
+
+## Treat a Long-Running Conversation Call Like Any Other Async Operation
+
+Nothing about `sendMessage`/`sendMessageForAgent` exempts it from the general patterns elsewhere in this folder: it's a `Promise` that can reject (see [Error Handling & Resiliency](./error-handling-and-resiliency.md)), a user can trigger a new message before a previous one resolves (consider whether to disable the input or track/cancel the stale one, per [Performance & Efficiency: cancel requests that are no longer needed](./performance-and-efficiency.md#cancel-requests-that-are-no-longer-needed)), and its pending/success/error states need the same live-region treatment as any other async UI (see [Accessibility for Async, API-Driven Components](./accessibility-for-async-components.md)).
+
+## Checklist
+
+- Check `PCore.getEnvironmentInfo().isGenAIEnabled()` before rendering any GenAI-dependent UI; treat "disabled" as a silent no-render, not an error.
+- Rehydrate conversation history via `getMessages`/`getConversations` on mount rather than relying only on in-session local state.
+- Render streamed responses incrementally, not buffered until fully complete, when `enableStreaming` is used.
+- Explicitly branch on `rewriteText`'s `success` field rather than assuming the happy-path shape.
+- Route message feedback through `likeAgentMessage`/`unLikeAgentMessage` instead of a separate, disconnected mechanism.
+- Apply the same async-state, cancellation, and accessibility patterns used elsewhere in these guides to conversation calls — they aren't a special case.

package/src/ai/catalog/best-practices/performance-and-efficiency.md

@@ -0,0 +1,109 @@
+---
+title: Performance & Efficiency
+description: Debouncing, buffering, caching/invalidation, request cancellation, and subscription hygiene patterns for components that call PCore/PConnect APIs.
+---
+
+# Performance & Efficiency
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+Most PCore/PConnect calls cross a network boundary, and several return values the framework already caches for you. The patterns below keep a custom component from doing unnecessary work — its own or the server's.
+
+## Debounce or Buffer User-Triggered Calls
+
+A field wired directly to `onChange` → REST/data-page call fires once per keystroke, which wastes network round trips and can make results arrive out of order (see [Troubleshooting: an older async response overwrites a newer one](./troubleshooting-common-pitfalls.md#an-older-async-response-overwrites-a-newer-one-a-fast-typed-search-shows-results-for-an-earlier-query)). Two documented options:
+
+```typescript
+// Option 1: a debounced Observable — react only after input goes quiet.
+const debouncedSubject = PCore.getAsynchronousUtils().getDebouncedSubject(250);
+const subscription = debouncedSubject.subscribe((value) => runSearch(value));
+// ...on each keystroke: debouncedSubject.next(currentValue);
+```
+
+```typescript
+// Option 2: buffered/batched fetches built into a live DataApi instance (typeahead-style fields).
+const dataApiInstance = await PCore.getDataApi().init(dataConfig, contextName);
+dataApiInstance.registerForBufferedCall({ waitTime: 50 });
+const results = await dataApiInstance.fetchData(searchTerm);
+```
+
+See [pcore-misc-details.md](../references/pcore-misc-details.md) and [pcore-rest-data-details.md](../references/pcore-rest-data-details.md) for full signatures.
+
+## Cache Data Pages, But Invalidate Deliberately
+
+Data page reads (`DataPageUtils.getDataAsync`/`getPageDataAsync`, `DataApi.init`) are cached by the framework — calling them again with the same parameters typically reuses the cached result instead of re-fetching. That's a performance win, but it means a stale read is a common bug after a write:
+
+- After a save/update that should be reflected on next read, call `DataPageUtils.markDataInstanceDirty(dataPageName, parameters)` or re-fetch with `{ invalidateCache: true }`.
+- When a `DataApi` instance is scoped to a context that's going away (e.g. a container item closing), call `DataApi.clearContextedCache(context)` so the next open of that context doesn't reuse a stale cached instance.
+- For small, component-local values (not full data page results), `NavigationUtils.getComponentCache`/`setComponentCache`/`resetComponentCache` (see [pcore-misc-details.md](../references/pcore-misc-details.md)) offer a lighter-weight, shorter-lived cache than a data page round trip.
+
+Caching is only a net win if invalidation is deliberate — don't cache a value and then forget which write paths should invalidate it.
+
+## Cancel Requests That Are No Longer Needed
+
+If a component can trigger a new request before a previous one resolves (a search box, a fast-changing filter, an unmounting component), cancel the stale request instead of letting it complete and race the newer one:
+
+```typescript
+const { invokeRestApi, getCancelTokenSource, isRequestCanceled } = PCore.getRestClient();
+const cancelTokenSource = getCancelTokenSource();
+
+invokeRestApi(routeKey, { ...payload, cancelTokenSource }).catch((error) => {
+  if (isRequestCanceled(error)) return; // expected — a newer request superseded this one
+  handleRealError(error);
+});
+
+// When a newer request starts, or the component unmounts:
+cancelTokenSource.cancel();
+```
+
+This isn't only about correctness (see [Error Handling & Resiliency: distinguish cancellation from failure](./error-handling-and-resiliency.md#distinguish-cancellation-from-failure)) — it also frees the response payload the server would otherwise still compute and send for a result nobody will use.
+
+## Avoid Redundant Subscriptions
+
+If multiple sibling components need the same data page or the same pub/sub event, prefer a single subscription owned by a shared ancestor/context over each sibling independently calling `subscribeToDataPageUpdates`/`PubSubUtils.subscribe`. Duplicate subscriptions mean duplicate network/server work for identical data, and duplicate cleanup surface area for the same bug class described in the troubleshooting guide's [subscription cleanup entry](./troubleshooting-common-pitfalls.md#subscription-callback-keeps-firing-after-the-component-unmounts).
+
+## Minimize Store Reads in the Render Path
+
+`StateUtils.getSharedState`/`ContextTreeManager.getFieldsList` (see [pcore-store-context-details.md](../references/pcore-store-context-details.md)) can return large structures. Read only the narrow piece of state a component actually renders, rather than pulling a broad object and destructuring it afterward — a narrower read makes it easier to reason about what a re-render actually depends on, and avoids re-rendering on changes to sibling state the component never displays.
+
+## Batch Related List Operations
+
+When applying the same change to many rows of a repeating structure, prefer `ListActions`' batch-capable operations (see [pconnect-list-actions.md](../references/pconnect-list-actions.md)) over looping and calling a single-row update once per row — a loop of individual calls multiplies both client-side dispatches and, depending on the operation, server round trips.
+
+## Parallelize Independent Calls Instead of Awaiting Them One at a Time
+
+If a component needs the results of two or more calls that don't depend on each other's output (for example, a data page lookup and a separate `AnalyticsUtils` call), issue them together with `Promise.all` rather than `await`-ing each in sequence. Sequential awaits of independent calls create an artificial waterfall — the total wait time becomes the sum of both round trips instead of the slower of the two:
+
+```typescript
+// Avoid: the second call doesn't start until the first one finishes, for no reason.
+const lookupResult = await PCore.getDataPageUtils().getDataAsync(dataPage, contextName);
+const insightIDs = await PCore.getAnalyticsUtils().getInsightIDs();
+
+// Prefer: both requests are in flight at the same time.
+const [lookupResult, insightIDs] = await Promise.all([
+  PCore.getDataPageUtils().getDataAsync(dataPage, contextName),
+  PCore.getAnalyticsUtils().getInsightIDs()
+]);
+```
+
+Only sequence calls when the second genuinely depends on the first's resolved value (for example, using a fetched record's ID as a parameter to the next call).
+
+## Virtualize Long Repeating Structures
+
+Rendering every row of a large repeating structure or list view at once means the browser builds and lays out DOM nodes for rows the user can't currently see. For lists that can grow into the hundreds of rows, render only the visible window (plus a small overscan buffer) instead of the full data set — check whether the presentation component already used for the list (in `cosmos-core`/`dx-components`) has built-in virtualization support before building a custom windowing solution.
+
+## Lazy-Load Assets That Aren't Needed on Initial Render
+
+`AssetLoader.loadAssets(assets, options)`/`getSvcImage(key)`/`getSvcImageUrl(key)` (see [pcore-misc-details.md](../references/pcore-misc-details.md)) fetch assets on demand rather than requiring them to be bundled/loaded upfront. Prefer loading an image, icon set, or other optional asset only when the view that displays it actually renders (or becomes visible), instead of loading every asset a component might ever need at mount time — this matters most for content behind a tab, an accordion panel, or a modal that many users never open.
+
+## Checklist
+
+- Debounce or buffer any call wired to a fast-firing user input (typing, dragging, rapid toggles).
+- After a write that affects a cached data page, invalidate it deliberately (`markDataInstanceDirty`/`invalidateCache`) rather than assuming the next read will be fresh.
+- Cancel a request that a newer one has superseded, and check `isRequestCanceled` before treating its rejection as a real error.
+- Share one subscription across siblings that need the same data instead of each subscribing independently.
+- Read only the state slice a component renders, not a broad object it partially uses.
+- Batch repeating-row operations instead of looping a single-row call.
+- Run independent calls with `Promise.all` instead of awaiting them one after another.
+- Virtualize (render only the visible window of) large repeating structures instead of every row at once.
+- Lazy-load optional assets (`AssetLoader`) when the view that needs them renders, not unconditionally at mount.

package/src/ai/catalog/best-practices/security-considerations.md

@@ -0,0 +1,93 @@
+---
+title: Security Considerations
+description: OWASP-aligned guidance for safely rendering, uploading, linking, authenticating, and logging data obtained through PCore/PConnect APIs.
+---
+
+# Security Considerations
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+The APIs cataloged in these skills return content that can originate from other users, an AI model, or the current URL — none of it should be treated as trusted by default. The items below call out where that matters, organized roughly by OWASP Top 10 category.
+
+| OWASP category                                | Where it applies here                                                             |
+| --------------------------------------------- | --------------------------------------------------------------------------------- |
+| A01: Broken Access Control                    | Client-side checks as a security boundary; trusting client-computed permissions   |
+| A03: Injection (incl. XSS)                    | Rendering feed/comment/GenAI content; prompt injection into GenAI Assistant calls |
+| A05: Security Misconfiguration                | Manually managing auth headers/tokens instead of using the provided REST client   |
+| A08: Software and Data Integrity Failures     | Trusting uploaded/downloaded attachment content without a type check              |
+| A09: Security Logging and Monitoring Failures | Logging raw error payloads or field values that may contain PII/tokens            |
+
+## Sanitize Free-Text Content Before Rendering It as HTML
+
+Case feed posts/comments (`FeedUtils`), correspondence, and GenAI Assistant replies (`GenAIAssistantUtils.sendMessage`/`sendMessageForAgent`) are free text written by another user or generated by a model — not markup you authored. **NEVER** render this content with `dangerouslySetInnerHTML`/`innerHTML` without first sanitizing it through a library such as `dompurify`. Treat an AI-generated response exactly like user-generated content for this purpose: a model can be prompted (directly or indirectly, via injected content it summarizes) into emitting markup or script, and it is not a trusted source of pre-sanitized HTML.
+
+```typescript
+import DOMPurify from 'dompurify';
+
+const safeHtml = DOMPurify.sanitize(feedPost.message);
+```
+
+If the content is only ever rendered as plain text (no formatting needed), render it as text content instead of HTML and skip the sanitization step entirely — that's a stronger guarantee than sanitizing and still using an HTML sink.
+
+## Treat Feed Content Forwarded Into a GenAI Prompt as Untrusted Input Too
+
+If a component builds a GenAI Assistant message (`sendMessage`/`sendMessageForAgent`) that incorporates case feed text, attachment names, or other user-authored content, remember that content can itself contain text crafted to influence the model ("prompt injection") — for example, embedded instructions telling the assistant to ignore prior context. Don't concatenate raw user content directly into a system-level instruction string; keep user-authored content clearly delimited as data being discussed, not as instructions to the assistant, and don't let a model's response alone gate a subsequent privileged action (like a submit or delete) without the normal validation/confirmation flow.
+
+## Client-Side Checks Are UX, Never the Security Boundary
+
+Hiding a button, disabling an action, or skipping a client-side field because a role/permission check failed is a UX affordance, not access control. The server (case type stage, access control rules) is the actual authority — never assume that because a component doesn't render a "Delete" button, the corresponding `ActionsApi.deleteWork` call is unreachable, and never treat a client-computed permission flag (from cached state, a prior response, or a stale subscription) as authoritative for anything higher-stakes than what to render. Fail closed: if a permission/config value that gates a sensitive action hasn't loaded yet or failed to load, treat it as "not permitted" rather than defaulting to showing the action.
+
+## Only Build Deep Links From a Trusted `routeKey`
+
+When constructing a shareable link with `SemanticUrlUtils.getResolvedSemanticURL(routeKey, payload, params, locale?)` (see [deep-link-semantic-url](../pconnect-navigation-locale-genai/cookbooks/deep-link-semantic-url.md)), source `routeKey` from `PCore.getSemanticUrlUtils().getActions()` — never from a raw query string, hash fragment, or other user-controllable input. Passing an attacker-influenced value as a route key risks resolving to an unintended destination (an open-redirect-style issue) rather than the case/view you meant to link to.
+
+## Treat Client-Side Upload Checks as UX Only, Not a Security Control
+
+`AttachmentUtils.uploadAttachment` performs server-side size/type rejection — that is the authoritative check. A client-side file-type or size pre-check (to show a fast error before the network round trip) is fine for UX, but never rely on it as the actual security boundary: always still handle the rejection from `uploadAttachment` itself, and never assume a file "passed" validation just because the client-side check didn't flag it.
+
+## Don't Trust Downloaded Attachment Content Either
+
+`AttachmentUtils.downloadAttachment`/`streamDownloadAttachment` return binary content another user uploaded. If a component renders that content inline (previewing an SVG, HTML, or text file, for example) rather than triggering a normal file download, apply the same rule as feed content: an SVG can carry an embedded `<script>`, and an HTML file can carry arbitrary markup. Prefer the browser's native download/save behavior for attachment content, and if inline preview is genuinely required, sanitize it first and never render it as same-origin HTML without isolation (for example, a sandboxed `<iframe>`).
+
+## Let the Provided REST Client Own Authentication
+
+`RestClient` (see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)) already attaches the operator's authenticated session/auth headers to `invokeRestApi`/`invokeCustomRestApi` calls, and exposes `getHeaderProcessor()` for the supported way to add custom headers. Never manually read, store, or forward an auth token from component code (e.g. into `localStorage`, a query string, or a custom header built by hand) — that both duplicates a security-relevant responsibility the platform already owns and creates a new place a token can leak (browser storage is readable by any script on the page, and tokens in URLs end up in server access logs and browser history).
+
+## Don't Leak Sensitive Details Through Error Handling
+
+When a `Promise`-returning PCore/PConnect method rejects, `ErrorHandler`/`FormUtils` (see [pcore-misc-details.md](../references/pcore-misc-details.md)) let you show a message to the user and/or log the failure. Show the user a clear, actionable, generic message via `ErrorHandler.setGenericFailedMessage`/the component's own error state — never the raw rejection object, a stack trace, or an internal error code that could reveal implementation details. If you log the error for diagnostics, make sure the logged payload doesn't include field values that could contain PII or auth tokens; log identifiers (case ID, context name) instead of full field state.
+
+## Unsubscribe When a Component Loses Access, Not Just to Avoid Leaks
+
+`PubSubUtils.subscribe`/`MessagingServiceManager.subscribe` keep delivering events to a callback until you unsubscribe. Beyond the memory-leak concern already covered in the [data-page-subscription-cleanup](../pconnect-data-subscriptions/cookbooks/data-page-subscription-cleanup.md) and [pubsub-cleanup](../pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md) recipes, unsubscribing promptly on unmount also matters from a least-privilege standpoint — a component that has navigated away from a case shouldn't keep receiving that case's pushed updates in memory for longer than it's displayed.
+
+## Treat User-Supplied Values as Untrusted Before Passing Them as API Parameters
+
+Search boxes, list filters, and other user-editable inputs sometimes feed directly into a data page or REST call parameter (`DataApiUtils`, `RestClient` — see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)). The server enforces access control on the resulting request, but still validate/constrain the shape of user input client-side before sending it (for example, an expected numeric ID field should not accept arbitrary text, and an expected enum value should be checked against an allow-list rather than passed through) — this reduces malformed-request noise and avoids accidentally surfacing another record's error details in a client-visible error message.
+
+## Practice Data Minimization When Forwarding Content to a GenAI Model
+
+`GenAIAssistantUtils.sendMessage`/`sendMessageForAgent` and `GenAIUtils.rewriteText` (see [pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md)) send whatever text you pass to a model, which may be hosted by a third party outside the case's normal data boundary. Don't forward more of the case than the task actually needs — for example, summarizing one field's free text doesn't require serializing the entire case payload into the prompt. Passing an entire case (including fields the current user shouldn't be exfiltrating verbatim into a model's context, such as another party's contact details embedded in an unrelated field) is a data-minimization problem independent of whether the model itself is trustworthy.
+
+## Don't Assume a Case/Assignment ID From a URL Is Valid for the Current User
+
+A deep link, browser history entry, or bookmarked route can carry a case ID, assignment handle, or `routeKey` that the current user is no longer (or was never) authorized to open. The server-side access check on the resulting request is the real control, but the component should treat "the ID resolved to a permission/not-found error" as an expected, handled outcome — not a bug — and show a clear "you don't have access to this" or "not found" state rather than a raw error, a blank screen, or (worse) a partially-rendered view built from a previous, unrelated case still held in memory.
+
+## Be Deliberate About What `EnvironmentInfo` Details You Surface
+
+`PCore.getEnvironmentInfo()` (see [pcore-environment-info-details.md](../references/pcore-environment-info-details.md)) exposes details about the running application/environment. Avoid logging or otherwise surfacing its full contents in a way that ends up in client-visible debug output, error reports, or telemetry sent to a third party — prefer reading and forwarding only the specific field a feature needs (e.g. the current locale) over passing the whole object along.
+
+## Checklist
+
+- Sanitize (or render as plain text) any feed post, comment, or GenAI Assistant reply before putting it in an HTML sink.
+- Never let raw user-authored content become part of a GenAI system instruction — keep it clearly framed as data, not instructions.
+- Never treat a hidden/disabled UI element, or a client-cached permission flag, as the actual access-control boundary — fail closed on unknown/unloaded permission state.
+- Source deep-link `routeKey` values from `getActions()`, never from user-controllable URL input.
+- Treat client-side upload/download type checks as UX only; the server's validation is authoritative, and previewed attachment content needs the same sanitization as any other untrusted HTML.
+- Never hand-manage auth tokens/headers — use `RestClient`'s built-in mechanisms.
+- Show users a generic, actionable error message; log identifiers, not raw field values or tokens.
+- Unsubscribe on unmount/navigation-away, not only to avoid leaks but to stop receiving updates a component no longer has a reason to see.
+- Validate/allow-list user-supplied values before they become REST or data page parameters.
+- Forward only the case content a GenAI call actually needs — don't serialize an entire case into a prompt when one field would do.
+- Handle a permission/not-found error from a URL-sourced case or assignment ID as an expected outcome, with a clear message — not a raw error or a stale view left over from a previous case.
+- Read only the specific `EnvironmentInfo` field a feature needs rather than logging or forwarding the whole object.

package/src/ai/catalog/best-practices/testing-pconnect-components.md

@@ -0,0 +1,245 @@
+---
+title: Testing Components That Use PCore/PConnect
+description: How to mock PCore and PConnect in Jest + React Testing Library tests, covering type safety, the four API-driven UI states, cancellation, debouncing, and cleanup — without over-mocking or coupling tests to internal implementation.
+---
+
+# Testing Components That Use PCore/PConnect
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+A component that calls `PCore.*` or `pConn.*` needs those calls mocked in a unit test — `PCore` and `PConnect` are runtime globals provided by the Constellation shell, never available in a plain Jest environment. This guide covers how to mock them correctly, and how to test the behaviors that are specific to API-driven components (loading/error states, cancellation, debouncing, cleanup).
+
+## Only Mock What the Component Actually Uses
+
+Do not create a large, all-purpose mock of `PCore` or `pConn` shared across every test. Mock only the methods the component under test actually calls, scoped to that test file:
+
+```typescript
+beforeEach(() => {
+  globalThis.PCore = {
+    getEnvironmentInfo: () => ({ getLocale: () => 'en-US' }),
+    getAttachmentUtils: () => ({ uploadAttachment: jest.fn() })
+    // Add more only as the component grows to call more of PCore.
+  } as unknown as typeof PCore;
+});
+```
+
+**NEVER** add `PCore`/`pConn` mocks to a shared `setupTests.ts` or `setupGlobals.ts` file. A shared global mock hides which methods a given component actually depends on, and one test's mock shape silently leaks into unrelated tests. Each test file owns its own mock.
+
+## Mocking `pConn` (PConnect)
+
+`pConn` is normally obtained via a `getPConnect` prop. Mock the prop function to return an object literal with only the methods the component calls:
+
+```typescript
+const mockPConnect = {
+  getValue: jest.fn().mockReturnValue(''),
+  getActionsApi: jest.fn().mockReturnValue({
+    updateFieldValue: jest.fn()
+  })
+};
+
+render(<MyComponent getPConnect={() => mockPConnect} />);
+```
+
+For a method the component calls conditionally (`pConn.someMethod?.()`), still provide it in the mock when the test exercises that branch — an optional-chained call that resolves to `undefined` will silently skip the branch instead of failing, which can mask a broken test.
+
+## Keep Mocks Type-Safe, Not `any`
+
+A mock typed as `any` compiles no matter how far it drifts from the real API — it will happily accept a call with the wrong argument count or a typo'd method name. Cast the mock object to the real type instead of typing it as `any`, so a genuine signature mismatch is caught at compile time rather than discovered at runtime:
+
+```typescript
+const mockPConnect: Partial<PConnect> = {
+  getValue: jest.fn().mockReturnValue('')
+};
+
+render(<MyComponent getPConnect={() => mockPConnect as PConnect} />);
+```
+
+This is also why a full, shared, all-purpose mock is a trap even when it's convenient: a giant object that "implements everything" tends to get typed as `any`/`unknown` to avoid maintenance overhead, which silently defeats this safety net. Small, per-test, precisely typed mocks keep the type checker useful.
+
+## Test the Four States of an API-Driven Component
+
+Any component whose rendered output depends on a `Promise`-returning `PCore`/`pConn` call has (at least) four distinct states worth a test each — it's easy to only cover the success path and ship the other three unverified:
+
+| State   | What to assert                                                                                           |
+| ------- | -------------------------------------------------------------------------------------------------------- |
+| Loading | A loading indicator/skeleton is shown while the promise is still pending.                                |
+| Success | The resolved data renders correctly, and the loading indicator is gone.                                  |
+| Empty   | A resolved-but-empty result (e.g. `[]` or `null`) renders an empty state, not a blank screen or a crash. |
+| Error   | A rejected promise renders a visible error state — never a silently blank component.                     |
+
+```typescript
+it('renders an empty state when the data page returns no rows', async () => {
+  const getListDataView = jest.fn().mockResolvedValue({ data: [] });
+  globalThis.PCore = { getDataApiUtils: () => ({ getListDataView }) } as unknown as typeof PCore;
+
+  render(<MyListComponent getPConnect={() => mockPConnect} />);
+
+  expect(await screen.findByText(/no results/i)).toBeInTheDocument();
+});
+```
+
+## Testing Promise-Returning Methods
+
+Most PCore/PConnect methods that hit the network return a `Promise`. Mock both the success and rejection path, and assert on the resulting UI state rather than on the mock call itself:
+
+```typescript
+it('shows an error state when the upload fails', async () => {
+  const uploadAttachment = jest.fn().mockRejectedValue(new Error('upload failed'));
+  globalThis.PCore = { getAttachmentUtils: () => ({ uploadAttachment }) } as unknown as typeof PCore;
+
+  render(<AttachmentUploader />);
+  await userEvent.upload(screen.getByLabelText(/choose file/i), someFile);
+
+  expect(await screen.findByRole('alert')).toHaveTextContent(/upload failed/i);
+});
+```
+
+## Testing Cancellation-Aware Requests
+
+If a component uses `RestClient.getCancelTokenSource()`/`isRequestCanceled()` (see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)) to abort an in-flight request — for example, when a search term changes before the previous search resolved — test that a canceled request's resolution is ignored rather than shown as an error:
+
+```typescript
+it('ignores a canceled request instead of showing an error', async () => {
+  const cancel = jest.fn();
+  const invokeRestApi = jest.fn().mockRejectedValue(new Error('canceled'));
+  globalThis.PCore = {
+    getRestClient: () => ({
+      getCancelTokenSource: () => ({ token: {}, cancel }),
+      invokeRestApi,
+      isRequestCanceled: () => true
+    })
+  } as unknown as typeof PCore;
+
+  const { rerender } = render(<SearchField getPConnect={() => mockPConnect} query="a" />);
+  rerender(<SearchField getPConnect={() => mockPConnect} query="ab" />);
+
+  expect(cancel).toHaveBeenCalled();
+  expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+});
+```
+
+## Testing Debounced or Buffered Input
+
+If a component uses `AsynchronousUtils.getDebouncedSubject(delay)` or `DataApi.registerForBufferedCall({ waitTime })` (see [pcore-misc-details.md](../references/pcore-misc-details.md) and [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)) to avoid firing a request on every keystroke, use fake timers to assert the call is debounced rather than fired once per keystroke:
+
+```typescript
+it('fires one lookup after typing stops, not one per keystroke', async () => {
+  jest.useFakeTimers();
+  const fetchData = jest.fn().mockResolvedValue([]);
+  // ...render, then simulate rapid input...
+  jest.advanceTimersByTime(300);
+
+  expect(fetchData).toHaveBeenCalledTimes(1);
+  jest.useRealTimers();
+});
+```
+
+## Testing Subscribe/Unsubscribe Cleanup
+
+Any component that subscribes to a data page, `PubSubUtils`, or `MessagingServiceManager` should have its unmount behavior tested — a missed unsubscribe is a real bug (see [Troubleshooting: subscription keeps firing after unmount](./troubleshooting-common-pitfalls.md#subscription-callback-keeps-firing-after-the-component-unmounts)), and it is straightforward to verify:
+
+```typescript
+it('unsubscribes on unmount', () => {
+  const subscribe = jest.fn().mockReturnValue('sub-1'); // MessagingServiceManager.subscribe returns the subscription id
+  const unsubscribe = jest.fn();
+  globalThis.PCore = { getMessagingServiceManager: () => ({ subscribe, unsubscribe }) } as unknown as typeof PCore;
+
+  const { unmount } = render(<MyComponent getPConnect={() => mockPConnect} />);
+  unmount();
+
+  expect(unsubscribe).toHaveBeenCalledWith('sub-1');
+});
+```
+
+`PubSubUtils.subscribe` returns nothing: it unsubscribes by event type and subscriber name, so assert `unsubscribe` was called with `(eventType, name)` instead.
+
+## Avoid Testing Implementation Details
+
+Assert on what the user would see or experience (rendered text, roles, an emitted callback prop), not on private internals. A test that asserts "component calls `getValue` exactly once" is brittle — it breaks on a harmless refactor (e.g. reading the value once and memoizing it vs. reading it twice) without the actual behavior changing. The one legitimate exception is cleanup/lifecycle behavior (unsubscribe, cancel) where the call itself **is** the behavior under test — there, asserting the mock was called is correct, not an implementation-detail test.
+
+## Guard Against Mock/Reality Drift
+
+A mock that always resolves happily gives false confidence once the real method's signature or behavior changes upstream. Periodically re-check a component's mocks against the method's actual documented signature in `references/` — an outdated mock (missing a newly required parameter, or resolving a shape the real method no longer returns) can keep a test green long after the component itself is broken against the real API.
+
+## Prefer `findBy`/`waitFor` Over Manual Timers for Async Assertions
+
+Once a mock resolves a `Promise`, the resulting state update is asynchronous — asserting on it immediately (before the microtask queue flushes) is a common source of flaky tests. Use RTL's `findBy*` queries (which internally retry until timeout) or `waitFor` instead of an arbitrary `setTimeout`/manual `await Promise.resolve()` chain:
+
+```typescript
+// Avoid: a magic delay that's either too short (flaky) or too long (slow suite).
+await new Promise((resolve) => setTimeout(resolve, 100));
+expect(screen.getByText(/loaded/i)).toBeInTheDocument();
+
+// Prefer: retries automatically until the assertion passes or times out.
+expect(await screen.findByText(/loaded/i)).toBeInTheDocument();
+```
+
+The one exception is a debounced/buffered call under fake timers (see above) — there, `jest.advanceTimersByTime` is the correct, deterministic way to advance past the delay, not a substitute for `findBy`/`waitFor` on the resulting UI update.
+
+## Testing Locale-Dependent Rendering
+
+If a component reads `pConn.getLocalizationService().getLocalizedText(...)`/`getLocalizedMessage(...)` (see [pcore-environment-info-details.md](../references/pcore-environment-info-details.md)) or calls `PCore.switchLocale(locale)`, mock the localization service to return a distinguishable value per key rather than echoing the key back unchanged — an identity mock (`getLocalizedText: (key) => key`) can hide a bug where the component accidentally renders the raw key instead of the resolved value in production:
+
+```typescript
+const mockPConnect = {
+  getLocalizationService: () => ({
+    getLocalizedText: (key: string) => `[localized]${key}`
+  })
+};
+```
+
+If the component also needs to react to a locale switch (see [Troubleshooting: locale switched but labels didn't update](./troubleshooting-common-pitfalls.md#locale-switched-but-already-rendered-labels-didnt-update)), add a test that re-invokes the localization mock after simulating the switch and asserts the rendered text actually changed — not just that the switch function was called.
+
+## Testing GenAI Assistant Conversations
+
+`GenAIAssistantUtils.sendMessage`/`sendMessageForAgent` (see [pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md)) resolve a `Promise`, and `GenAIUtils.rewriteText` resolves a discriminated union (`{ success: true, rewrittenText }` or `{ success: false, ... }`). Test both branches of the union explicitly — a mock that only ever resolves the success shape hides a missing/incorrect handler for the failure shape:
+
+```typescript
+it('shows a fallback message when text rewriting reports failure', async () => {
+  const rewriteText = jest.fn().mockResolvedValue({ success: false, message: 'unavailable' });
+  globalThis.PCore = {
+    getEnvironmentInfo: () => ({ isGenAIEnabled: () => true }),
+    getGenAIUtils: () => ({ rewriteText })
+  } as unknown as typeof PCore;
+
+  render(<RewriteButton getPConnect={() => mockPConnect} />);
+  await userEvent.click(screen.getByRole('button', { name: /rewrite/i }));
+
+  expect(await screen.findByText(/unavailable/i)).toBeInTheDocument();
+});
+```
+
+Also test the gate itself: when `isEnvironmentInfo().isGenAIEnabled()` returns `false`, assert the component doesn't render the GenAI-dependent affordance at all, rather than rendering it and letting the call fail.
+
+## Build Small, Local Test Data Factories Instead of One Shared Fixture
+
+A single large shared fixture object (for example, one exported `mockCaseData` used across many test files) tends to accumulate fields for whichever test needed them first, and every later test either depends on unrelated fields it doesn't understand or has to override several to get a clean state. Prefer a small factory function local to (or near) the test file that returns a minimal valid object, with overrides for the specific field a test cares about:
+
+```typescript
+const buildCaseInfo = (overrides: Partial<CaseInfo> = {}): CaseInfo => ({
+  ID: 'WORK-1',
+  caseTypeName: 'Case',
+  status: 'Open',
+  ...overrides
+});
+
+it('shows a resolved badge when the case is closed', () => {
+  render(<CaseStatusBadge caseInfo={buildCaseInfo({ status: 'Resolved' })} />);
+  expect(screen.getByText(/resolved/i)).toBeInTheDocument();
+});
+```
+
+## Checklist
+
+- Mock only the methods the component under test calls — no shared, all-purpose global mock.
+- Type mocks against the real interface (`Partial<PConnect>`/`typeof PCore`) instead of `any`, so drift is caught at compile time.
+- Cover all four states for any API-driven view: loading, success, empty, and error.
+- If the component cancels stale requests, test that a canceled/superseded response doesn't produce a visible error.
+- If the component debounces/buffers input, use fake timers to assert a single call, not one per keystroke.
+- If the component subscribes to anything, add a test asserting the unsubscribe function is called on unmount.
+- Assert on rendered output (`screen.getByRole`/`getByText`) rather than on internal state or an incidental mock call.
+- Never make a real network call from a unit test — every `PCore`/`pConn` method the component touches must be mocked.
+- Use `findBy*`/`waitFor` for async assertions instead of arbitrary `setTimeout` delays.
+- Mock localization with a distinguishable value per key, not an identity echo, so a raw-key rendering bug can't hide.
+- For a GenAI-gated affordance, test both the enabled/disabled gate and the success/failure branches of any discriminated-union result.
+- Prefer small, local test-data factory functions over one large shared fixture that accumulates unrelated fields.