@pega/custom-dx-components 26.1.11 → 26.1.12-alpha-0.1

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.

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

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