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

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/publish-and-subscribe-events.md

@@ -0,0 +1,40 @@
+---
+title: Publish a custom application-wide event for other components to react to
+keywords: [event bus, publish, custom event, cross-component communication, broadcast]
+primary_methods: [PubSubUtils.publish, PubSubUtils.subscribeOnce]
+related: [pubsub-cleanup]
+---
+
+# Recipe: Publish a custom application-wide event for other components to react to
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component completes an action (for example, "review submitted") that several unrelated components elsewhere in the page need to react to, without wiring them together directly through props or a shared parent.
+
+## Solution
+
+Uses `PCore.getPubSubUtils()` (see [pcore-messaging-details.md](../../references/pcore-messaging-details.md)). This is the publisher side of the pattern documented from the subscriber side in [Publish/subscribe between unrelated components, with cleanup](./pubsub-cleanup.md).
+
+```typescript
+const CUSTOM_EVENT = 'my-app:review-submitted';
+
+// Publisher — fires after the action completes.
+function onReviewSubmitted(caseID) {
+  PCore.getPubSubUtils().publish(CUSTOM_EVENT, { caseID });
+}
+
+// A subscriber that only needs to react the next time this happens, not every time.
+PCore.getPubSubUtils().subscribeOnce(CUSTOM_EVENT, ({ caseID }) => refreshSummaryPanel(caseID), 'summary-panel-once');
+```
+
+## Discussion
+
+**SHOULD** namespace custom event names (for example, `my-app:review-submitted`) rather than a bare string like `reviewSubmitted` — `PubSubUtils` is a single, application-wide bus shared by every component, and an unnamespaced string can collide with another component's event.
+
+**MUST** use `subscribeOnce` (not `subscribe` followed by a manual `unsubscribe` inside the handler) when a listener genuinely only needs to fire one time — it self-removes after the first invocation, which is easy to get wrong by hand.
+
+## Related recipes
+
+- [Publish/subscribe between unrelated components, with cleanup](./pubsub-cleanup.md)

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md

@@ -0,0 +1,38 @@
+---
+title: Publish/subscribe between unrelated components, with cleanup
+keywords: [event bus, publish, subscribe, cross-component communication, orphaned handler]
+primary_methods: [PubSubUtils.subscribe, PubSubUtils.unsubscribe, Events.getCaseEvent]
+related: [data-page-subscription-cleanup, cascading-dependent-fields]
+---
+
+# Recipe: Publish/subscribe between unrelated components, with cleanup
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+Two components that don't share a parent/child relationship need to communicate through an application-wide event, without leaving a stale handler registered after either unmounts.
+
+## Solution
+
+Uses `PCore.getPubSubUtils()` (see [pcore-messaging-details.md](../../references/pcore-messaging-details.md)).
+
+```typescript
+useEffect(() => {
+  const { subscribe, unsubscribe } = PCore.getPubSubUtils();
+  const handlerName = 'my-widget-stage-listener';
+
+  subscribe(PCore.getEvents().getCaseEvent().CREATE_STAGE_DONE, onStageCreated, handlerName);
+
+  return () => unsubscribe(PCore.getEvents().getCaseEvent().CREATE_STAGE_DONE, handlerName);
+}, []);
+```
+
+## Discussion
+
+**MUST** use the same `name` for `subscribe`/`unsubscribe`. **NEVER** mismatch them (for example, unsubscribing with a different string) — doing so silently leaves the original handler active.
+
+## Related recipes
+
+- [Subscribe to a data page and clean up on unmount](./data-page-subscription-cleanup.md)
+- [Register cascading/dependent fields and clean them up](../../pconnect-forms-and-fields/cookbooks/cascading-dependent-fields.md)

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/query-paginated-list-data.md

@@ -0,0 +1,44 @@
+---
+title: Query a paginated, filterable list data view
+keywords: [list query, pagination, filter, sort, data view, search results]
+primary_methods: [DataApiUtils.getData, DataApiUtils.getListCount, DataApiUtils.getDataViewMetadata]
+related: [refresh-and-update-data]
+---
+
+# Recipe: Query a paginated, filterable list data view
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A grid/table needs to fetch a page of results from a list data view with filters and sorting applied, show a total record count for the pager, and know which columns are filterable/sortable ahead of rendering filter controls.
+
+## Solution
+
+Uses `PCore.getDataApiUtils()` (see [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md)).
+
+```typescript
+const { getData, getListCount, getDataViewMetadata } = PCore.getDataApiUtils();
+
+// Render filter controls from the data view's own field metadata rather than hardcoding column config.
+const metadata = await getDataViewMetadata('D_CaseSearchResults', context);
+
+const payload = {
+  paging: { pageSize: 20, pageNumber: 1 },
+  sortBy: [{ field: 'pxCreateDateTime', direction: 'DESC' }],
+  filters: [{ field: 'pyStatusWork', operator: 'IN', values: ['Open'] }]
+};
+
+const { data } = await getData('D_CaseSearchResults', payload, context);
+const { data: count } = await getListCount('D_CaseSearchResults', payload, context);
+```
+
+## Discussion
+
+**SHOULD** call `getDataViewMetadata` once (and cache the result) to discover which fields are actually queryable/sortable, rather than assuming every visible column supports server-side filtering — an unsupported filter field is silently ignored by some data views rather than raising an error.
+
+**MUST** pass the identical `payload` (filters and paging) to both `getData` and `getListCount` — a mismatched payload returns a total count that doesn't correspond to the rows actually shown, breaking the pager.
+
+## Related recipes
+
+- [Force-refresh a stale cached data page on demand](./refresh-and-update-data.md)

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/realtime-case-subscription.md

@@ -0,0 +1,46 @@
+---
+title: Subscribe to real-time case updates pushed from the server
+keywords: [WebSocket, server push, real-time update, live case status, messaging service]
+primary_methods:
+  [MessagingServiceManager.subscribe, MessagingServiceManager.unsubscribe, MessagingServiceManager.getCaseSubscription]
+related: [pubsub-cleanup, data-page-subscription-cleanup]
+---
+
+# Recipe: Subscribe to real-time case updates pushed from the server
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to reflect another user's changes to the same case in near-real-time (for example, a live "someone else updated this case" banner), which requires a server-pushed message rather than a purely local, same-tab event.
+
+## Solution
+
+Uses `MessagingServiceManager` (via `PCore.getMessagingServiceManager()`, see [pcore-messaging-details.md](../../references/pcore-messaging-details.md)).
+
+```typescript
+useEffect(() => {
+  const manager = PCore.getMessagingServiceManager();
+
+  // The filter is { matcher, criteria }: 'CASE' with the case ID selects server pushes for that case.
+  // caseID is the case ID string (the same value as pConn.getCaseSummary().caseID; the typedef examples use
+  // 'Approval-Request A-101'). Do not use getCaseSummary().ID: that is the assignment ID.
+  const subscriptionId = manager.subscribe(
+    { matcher: 'CASE', criteria: { caseId: caseID } },
+    (payload: unknown) => showLiveUpdateBanner(payload),
+    pConn.getContextName()
+  );
+
+  // subscribe returns the subscription id (a string), not an unsubscribe function.
+  return () => manager.unsubscribe(subscriptionId);
+}, [caseID]);
+```
+
+## Discussion
+
+`MessagingServiceManager` is a distinct transport from `PubSubUtils`: this `subscribe` reacts to server-pushed WebSocket messages describing changes made in other sessions, while `PubSubUtils.subscribe` (see [Publish/subscribe between unrelated components](./pubsub-cleanup.md)) only reacts to events published locally within the same browser tab. **NEVER** expect `PubSubUtils` to notice another user's edit. **MUST** apply the same unsubscribe-on-unmount discipline here — an orphaned `MessagingServiceManager` subscription keeps a live socket handler registered for a component that no longer exists.
+
+## Related recipes
+
+- [Publish/subscribe between unrelated components, with cleanup](./pubsub-cleanup.md)
+- [Subscribe to a data page and clean up on unmount](./data-page-subscription-cleanup.md)

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/refresh-and-update-data.md

@@ -0,0 +1,41 @@
+---
+title: Force-refresh a stale cached data page on demand
+keywords: [refresh, stale cache, cache invalidation, force reload, refresh button]
+primary_methods: [DataPageUtils.markDataInstanceDirty, DataPageUtils.getDataAsync]
+related: [data-page-subscription-cleanup]
+---
+
+# Recipe: Force-refresh a stale cached data page on demand
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component caches a data page result, but the user clicks an explicit "Refresh" affordance (or the component knows the underlying data changed some other way) and needs the next read to hit the server instead of returning the cached value.
+
+## Solution
+
+Uses `PCore.getDataPageUtils()` (see [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md)).
+
+```typescript
+async function onRefreshClick(dataPageName, parameters, context) {
+  const { markDataInstanceDirty, getDataAsync } = PCore.getDataPageUtils();
+
+  // Marks the cached instance stale; it does NOT itself trigger a re-fetch.
+  markDataInstanceDirty(dataPageName, parameters);
+
+  // The next getDataAsync call — with the same parameters — now goes to the server instead of the cache.
+  const refreshed = await getDataAsync(dataPageName, context, parameters);
+  return refreshed;
+}
+```
+
+## Discussion
+
+**MUST** call `getDataAsync` (or otherwise re-request the page) after `markDataInstanceDirty` — marking a page dirty does not by itself cause any subscriber to re-render with new data; it only changes what the _next_ fetch returns.
+
+**MUST** pass the exact same `parameters` to `markDataInstanceDirty` and the follow-up `getDataAsync` call — the cache key includes parameters, so marking one parameter combination dirty does not invalidate a differently-parameterized cached instance of the same data page.
+
+## Related recipes
+
+- [Subscribe to a data page and clean up on unmount](./data-page-subscription-cleanup.md)

package/src/ai/catalog/pconnect-forms-and-fields/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pconnect-forms-and-fields
+description: "Reference catalog and cookbook for PCore/PConnect APIs governing form and field behavior — FormUtils, CascadeManager, AutosaveUtils, NavigationUtils component state, and ValidationApi — with recipes for full-form validation before submit, cascading/dependent fields, autosave status tracking, persisting a custom widget's UI state across navigation, collecting changed/submittable data for a manual save, discarding changes and resetting a form, and registering a custom cross-field validator. Use when you need the exact signature for these APIs, or the correct order to call them to validate, cascade, or persist form/field state."
+user-invocable: true
+argument-hint: "Use when validating a whole form, wiring cascading/dependent fields, tracking autosave status, or persisting a custom widget's UI state across navigation — for the exact FormUtils/CascadeManager/AutosaveUtils/NavigationUtils signature, or the correct call order."
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Forms & Field Behavior — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for **form and field behavior**: whole-form validation, cascading/dependent fields, autosave tracking, and persisting custom widget UI state. It is one of the PCore/PConnect API skills — see the [skills index](../README.md) for the full method catalog, architecture primer, and the other five skills.
+
+## When to Use This Skill
+
+Load this skill when:
+
+- You need the exact parameters, return type, or purpose of a `FormUtils`, `CascadeManager`, `AutosaveUtils`, or `NavigationUtils` (component state) method.
+- You're disabling/enabling a Submit button based on whole-form validity and dirty state, rather than a single field.
+- You're wiring one field's change to reset or reload a dependent field, or tracking/notifying autosave status.
+- You're persisting a custom component's UI state (for example, a selected tab) across navigation/unmount.
+
+If your task is actually about submitting or deleting the assignment/case itself, see [pconnect-assignment-lifecycle](../pconnect-assignment-lifecycle/SKILL.md) instead.
+
+New to PCore/PConnect? Start with [Architecture at a Glance](../references/architecture-overview.md).
+
+## Key Reference Files
+
+| File                                                                                 | Class(es)                                       | Obtained via                |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------- | --------------------------- |
+| [../references/pcore-misc-details.md](../references/pcore-misc-details.md)           | `FormUtils`, `AutosaveUtils`, `NavigationUtils` | `PCore.get*()`              |
+| [../references/pcore-rest-data-details.md](../references/pcore-rest-data-details.md) | `CascadeManager`                                | `PCore.getCascadeManager()` |
+| [../references/pconnect-validation-api.md](../references/pconnect-validation-api.md) | `ValidationApi`                                 | `pConn.getValidationApi()`  |
+| [../references/pconnect-actions-api.md](../references/pconnect-actions-api.md)       | `ActionsApi`                                    | `pConn.getActionsApi()`     |
+
+See the [full reference index](../README.md) for every other PCore/PConnect method not directly related to this skill's topic.
+
+## Cookbooks
+
+Multi-method, ordering/cleanup recipes for this skill's topic live in [cookbooks/README.md](./cookbooks/README.md): full-form validation before submit, cascading/dependent fields, autosave status tracking, persisting a custom widget's UI state, collecting changed/submittable data for a manual save action, discarding changes and resetting a form, and registering a custom field validator.
+
+Use the reference files above for a single method's signature. Use the cookbook index when you need the **order** multiple methods should be called in to complete a task.
+
+For testing components that call these APIs, security considerations, performance (debouncing cascades/autosave), error-handling strategy for a failed validation/autosave call, accessibly announcing validation/autosave status, or troubleshooting a call that isn't behaving as documented, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/README.md

@@ -0,0 +1,36 @@
+---
+title: Forms & Field Behavior Cookbook — Recipe Index
+description: Multi-method recipes for form/field validation, cascading fields, autosave, and persisted UI state, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Forms & Field Behavior
+
+> Part of the [Forms & Field Behavior skill](../SKILL.md).
+
+Every file in [`../../references/`](../../references/) documents one method at a time. Each file in this folder shows how to **chain multiple documented methods together** to complete one common real-world task. Every recipe only uses methods already cataloged in `references/` — follow the links in each recipe for full signatures. Nothing here invents a new API; every call is a direct composition of already-documented methods.
+
+Each recipe is a single, self-contained file with:
+
+- YAML frontmatter (`keywords`, `primary_methods`, `related`) for structured/metadata search.
+- A **Problem** statement — what you're trying to accomplish, in plain language.
+- A **Solution** — the minimal correct code, linking to the individual reference files for each method used.
+- A **Discussion** — the ordering/cleanup/gotcha pitfall that makes this worth documenting as a recipe instead of assembling from scratch.
+- **Related recipes** — links to recipes that share a pattern (lifecycle, cleanup, error handling, etc.), including recipes in sibling skills.
+
+## Recipe Index
+
+Search by symptom or keyword before assembling a sequence of calls from scratch — there is a good chance the ordering/cleanup pitfalls have already been worked out below.
+
+| Recipe                                                                              | Keywords                                                                    | Primary methods              |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
+| [Full-form validation before submit](./full-form-validation.md)                     | validate all fields, disable submit button, dirty check, unsaved changes    | `FormUtils`, `ActionsApi`    |
+| [Cascading dependent fields](./cascading-dependent-fields.md)                       | dependent dropdown, country/state, cascade, dynamic field reset             | `CascadeManager`             |
+| [Autosave status tracking](./autosave-tracking.md)                                  | autosave, draft, in-progress edits, save indicator                          | `AutosaveUtils`              |
+| [Persist widget UI state](./persist-widget-ui-state.md)                             | persist UI state, remember selected tab, navigation cache, survive remount  | `NavigationUtils`            |
+| [Collect form changes for a manual save](./collect-form-changes-for-manual-save.md) | manual save, save draft, changed fields, submit payload, custom save button | `FormUtils`                  |
+| [Discard changes and reset a form](./discard-changes-and-reset-form.md)             | discard changes, reset form, clear validation errors, cancel edit, revert   | `FormUtils`                  |
+| [Register a custom field validator](./custom-field-validators.md)                   | custom validator, business rule validation, cross-field validation          | `FormUtils`, `ValidationApi` |
+
+Use the individual reference files in [`../../references/`](../../references/) to look up a single method's exact signature. Use a recipe here when you need to know the **order** multiple methods should be called in to complete a task.
+
+As more cookbooks are added, add one file per recipe (not more content to an existing recipe file) and a row here — see any existing recipe file for the expected frontmatter/structure.

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/autosave-tracking.md

@@ -0,0 +1,45 @@
+---
+title: Track autosave status while editing a form
+keywords: [autosave, draft, in-progress edits, save indicator]
+primary_methods:
+  [AutosaveUtils.isAutosaveEnabledForContext, AutosaveUtils.subscribeAutosaveStatus, AutosaveUtils.notifyChange]
+related: [data-page-subscription-cleanup, full-form-validation]
+---
+
+# Recipe: Track autosave status while editing a form
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to show an autosave indicator and tell the autosave engine about in-progress edits, without leaking the status subscription after unmount.
+
+## Solution
+
+Uses `AutosaveUtils` (via `PCore.getAutosaveUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+useEffect(() => {
+  if (!PCore.getAutosaveUtils().isAutosaveEnabledForContext(context)) return undefined;
+
+  const unsubscribe = PCore.getAutosaveUtils().subscribeAutosaveStatus(itemKey, (status) => {
+    setAutosaveStatus(status);
+  });
+
+  return unsubscribe;
+}, [context, itemKey]);
+
+const onFieldChange = (propReference, value) => {
+  // Tell the autosave engine about the edit so it can debounce/save it, separately from field-level state.
+  PCore.getAutosaveUtils().notifyChange(context, propReference, value);
+};
+```
+
+## Discussion
+
+**MUST** check `isAutosaveEnabledForContext` before subscribing. **NEVER** subscribe unconditionally — it wires up a listener that never fires on a context where autosave is off, which is a silent no-op that's easy to mistake for a bug elsewhere.
+
+## Related recipes
+
+- [Subscribe to a data page and clean up on unmount](../../pconnect-data-subscriptions/cookbooks/data-page-subscription-cleanup.md)
+- [Validate an entire form before allowing submit](./full-form-validation.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/cascading-dependent-fields.md

@@ -0,0 +1,51 @@
+---
+title: Register cascading/dependent fields and clean them up
+keywords: [dependent dropdown, country/state, cascade, dynamic field reset]
+primary_methods: [CascadeManager.registerFields, CascadeManager.unRegisterFields]
+related: [data-page-subscription-cleanup, pubsub-cleanup]
+---
+
+# Recipe: Register cascading/dependent fields and clean them up
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+Changing one field (for example, Country) needs to reset or reload a dependent field (for example, State), and the listener must not keep firing after the component unmounts.
+
+## Solution
+
+Uses `PCore.getCascadeManager()` (see [pcore-rest-data-messaging.md](../../references/pcore-rest-data-messaging.md)).
+
+```typescript
+useEffect(() => {
+  const context = pConn.getContextName();
+  const pageReference = pConn.getPageReference();
+  const subscriberId = 'country-state-cascade';
+  // Register the field being WATCHED (the one whose change should trigger the reload), not the dependent field.
+  const watchedProps = ['.Country'];
+
+  const onCountryChanged = () => {
+    pConn.getActionsApi().updateFieldValue('.State', ''); // clear the dependent value
+    reloadStateOptions(); // load the options for the new country
+  };
+
+  PCore.getCascadeManager().registerFields(context, pageReference, watchedProps, onCountryChanged, subscriberId);
+
+  return () => {
+    // Always pair registerFields with unRegisterFields, or the callback keeps firing after unmount.
+    PCore.getCascadeManager().unRegisterFields(context, pageReference, watchedProps, subscriberId);
+  };
+}, []);
+```
+
+The typedef's own example registers field names without a leading dot (`['firstName', 'lastName']`) with an explicit page reference (`'caseInfo.content'`). Use the form your runtime resolves and confirm it in a running app; the call compiles either way.
+
+## Discussion
+
+**MUST** pass the exact same `context`, `pageReference`, `watchedProps`, and `subscriberId` to both `registerFields` and `unRegisterFields`. **NEVER** let them drift apart — a mismatch silently fails the cleanup, and the original callback keeps firing after unmount.
+
+## Related recipes
+
+- [Subscribe to a data page and clean up on unmount](../../pconnect-data-subscriptions/cookbooks/data-page-subscription-cleanup.md)
+- [Publish/subscribe between unrelated components, with cleanup](../../pconnect-data-subscriptions/cookbooks/pubsub-cleanup.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/collect-form-changes-for-manual-save.md

@@ -0,0 +1,45 @@
+---
+title: Collect changed or submittable form data for a manual save action
+keywords: [manual save, save draft, changed fields, submit payload, custom save button]
+primary_methods: [FormUtils.getChanges, FormUtils.getSubmitData]
+related: [autosave-tracking, full-form-validation]
+---
+
+# Recipe: Collect changed or submittable form data for a manual save action
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A custom "Save Draft" button — distinct from both autosave and the final assignment submit — needs to package up either just the fields the user changed, or the full submittable payload, to send to a custom endpoint.
+
+## Solution
+
+Uses `FormUtils` (via `PCore.getFormUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+const { getChanges, getSubmitData } = PCore.getFormUtils();
+
+function onSaveDraftClick(context) {
+  // Only the properties the user actually touched since the last save.
+  const changedFields = getChanges(context);
+  return saveDraftToCustomEndpoint(changedFields);
+}
+
+function onSaveFullSnapshotClick(context) {
+  // The complete submittable payload, as if the form were being submitted now.
+  const fullPayload = getSubmitData(context, { onlyChangedData: false });
+  return saveDraftToCustomEndpoint(fullPayload);
+}
+```
+
+## Discussion
+
+**MUST** choose `getChanges` vs. `getSubmitData({ onlyChangedData: true })` deliberately rather than interchangeably — `getChanges` returns the raw changed-properties list, while `getSubmitData` shapes the data the way an actual submit would, including any fields the form's own submit-time logic would add. Prefer `getSubmitData` when the draft will later be replayed through the same submit path.
+
+**SHOULD** pass `{ includeDisabledFields: false }` (the default) unless the custom save endpoint specifically needs disabled-field values — including them can leak data the user never had a chance to edit or even see.
+
+## Related recipes
+
+- [Track autosave status while editing a form](./autosave-tracking.md)
+- [Validate an entire form before allowing submit](./full-form-validation.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/custom-field-validators.md

@@ -0,0 +1,44 @@
+---
+title: Register a custom validator for business-rule field validation
+keywords: [custom validator, business rule validation, cross-field validation, register validator]
+primary_methods: [FormUtils.setCustomValidator, ValidationApi.validate]
+related: [full-form-validation]
+---
+
+# Recipe: Register a custom validator for business-rule field validation
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A field needs validation logic beyond what's configured on the field itself — for example, a business rule that compares two fields' values — and that logic should run through the same validation pipeline as built-in validators rather than being wired up ad hoc in the component.
+
+## Solution
+
+Uses `FormUtils` and `ValidationApi` (`FormUtils` via `PCore.getFormUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md); `ValidationApi` via `pConn.getValidationApi()`, see [pconnect-validation-api.md](../../references/pconnect-validation-api.md)).
+
+```typescript
+// Register once, near app bootstrap — not per component instance.
+PCore.getFormUtils().setCustomValidator('endDateAfterStartDate', (value, context) => {
+  const startDate = PCore.getStoreValue('.StartDate', 'caseInfo.content', context);
+  return value > startDate ? undefined : 'End date must be after the start date';
+});
+```
+
+```typescript
+// At the field, run validation the same way as any other field.
+const result = pConn.getValidationApi().validate(endDateValue, 'EndDate');
+if (!result.status) {
+  // result.message reflects whichever validator (built-in or custom) failed
+}
+```
+
+## Discussion
+
+**MUST** register a given validator `type` name once — registering the same type name a second time (for example, from another component that also calls `setCustomValidator` with the same string) silently replaces the first registration, the same last-write-wins hazard as `ConfirmDialogService.registerConfirmHandler`.
+
+**SHOULD** keep custom validator functions pure and side-effect-free — they can run on every keystroke depending on the field's validation trigger, so anything beyond a synchronous check (a network call, for example) belongs in `validateEmail`-style pre-submit validation instead, not a custom validator.
+
+## Related recipes
+
+- [Validate an entire form before allowing submit](./full-form-validation.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/discard-changes-and-reset-form.md

@@ -0,0 +1,41 @@
+---
+title: Discard changes and reset a form to its pristine state
+keywords: [discard changes, reset form, clear validation errors, cancel edit, revert]
+primary_methods: [FormUtils.clearChangedProperties, FormUtils.resetComplexObjectDirtyStatus]
+related: [collect-form-changes-for-manual-save, full-form-validation]
+---
+
+# Recipe: Discard changes and reset a form to its pristine state
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A "Discard changes" / "Cancel edit" affordance needs to clear the form's changed-properties tracking and dirty-status flags so the form no longer reports unsaved changes, without a full page reload.
+
+## Solution
+
+Uses `FormUtils` (via `PCore.getFormUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+function onDiscardChangesClick(context) {
+  const { clearChangedProperties, resetComplexObjectDirtyStatus } = PCore.getFormUtils();
+
+  clearChangedProperties(context);
+  resetComplexObjectDirtyStatus(context);
+
+  // Field values themselves are not reset by either call — reload/re-fetch the underlying
+  // page/case data if the visible field values must also revert to their last-saved values.
+}
+```
+
+## Discussion
+
+**MUST NOT** assume `clearChangedProperties`/`resetComplexObjectDirtyStatus` revert field values — they only clear the _tracking_ of what changed and whether a complex object is dirty. If the UI must show the last-saved values again, re-fetch or restore them separately (for example, by re-opening the assignment).
+
+**SHOULD** call both together when fully resetting a form's dirty state — `clearChangedProperties` covers simple properties, while `resetComplexObjectDirtyStatus` covers the dirty flag on nested/complex objects; using only one can leave the other half of the form still reporting as dirty.
+
+## Related recipes
+
+- [Collect changed or submittable form data for a manual save action](./collect-form-changes-for-manual-save.md)
+- [Validate an entire form before allowing submit](./full-form-validation.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/full-form-validation.md

@@ -0,0 +1,38 @@
+---
+title: Validate an entire form before allowing submit
+keywords: [validate all fields, disable submit button, dirty check, unsaved changes]
+primary_methods: [FormUtils.isFormValid, FormUtils.isStateModified, ActionsApi.finishAssignment]
+related: [modal-assignment-submit, multi-step-wizard, autosave-tracking]
+---
+
+# Recipe: Validate an entire form before allowing submit
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A Submit button must stay disabled until every field on the view is valid and the user has actually changed something — not just one field, as in the modal recipe.
+
+## Solution
+
+Uses `PCore.getFormUtils()` (see [pcore-misc-details.md](../../references/pcore-misc-details.md)) together with [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+const canSubmit = PCore.getFormUtils().isFormValid(context) && PCore.getFormUtils().isStateModified(context);
+
+if (canSubmit) {
+  await pConn.getActionsApi().finishAssignment(containerItemID);
+} else {
+  // Keep the Submit button disabled; individual field errors are already shown by the framework.
+}
+```
+
+## Discussion
+
+**MUST** combine `isStateModified` with `isFormValid` — checking validity alone allows submitting an assignment the user never actually changed.
+
+## Related recipes
+
+- [Open an assignment in a modal, edit, validate, submit, and close](../../pconnect-assignment-lifecycle/cookbooks/modal-assignment-submit.md)
+- [Multi-step wizard navigation with per-step save and final submit](../../pconnect-assignment-lifecycle/cookbooks/multi-step-wizard.md)
+- [Track autosave status while editing a form](./autosave-tracking.md)

package/src/ai/catalog/pconnect-forms-and-fields/cookbooks/persist-widget-ui-state.md

@@ -0,0 +1,41 @@
+---
+title: Persist a custom widget's UI state across navigation
+keywords: [persist UI state, remember selected tab, navigation cache, component cache, survive remount]
+primary_methods:
+  [NavigationUtils.getComponentState, NavigationUtils.setComponentState, NavigationUtils.getComponentCache]
+related: [autosave-tracking]
+---
+
+# Recipe: Persist a custom widget's UI state across navigation
+
+> Part of the [Forms & Field Behavior cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A custom component (for example, a tab strip or collapsible panel) needs to remember which sub-view the user had open, surviving a full unmount when the user navigates away and back — plain React state resets on remount.
+
+## Solution
+
+Uses `NavigationUtils` (via `PCore.getNavigationUtils()`, see [pcore-misc-details.md](../../references/pcore-misc-details.md)).
+
+```typescript
+const stateKey = `my-widget-${pConn.getContextName()}`;
+
+const [selectedTab, setSelectedTab] = useState(
+  () => PCore.getNavigationUtils().getComponentState(stateKey) ?? 'overview'
+);
+
+useEffect(() => {
+  PCore.getNavigationUtils().setComponentState(stateKey, selectedTab);
+}, [selectedTab]);
+```
+
+## Discussion
+
+**MUST** scope `stateKey` to the component's own context (`pConn.getContextName()`) rather than a hardcoded literal. **NEVER** use a shared key across multiple instances of the same widget — it collides across instances open in different containers, so one instance's tab selection silently overwrites another's.
+
+`setComponentState` (persisted navigation state) and `setComponentCache` (in-memory cache) are not the same durability tier — reach for `setComponentCache` for cheap, short-lived memoization that's fine to lose, and reserve `setComponentState` for values that genuinely need to survive a full unmount/remount.
+
+## Related recipes
+
+- [Track autosave status while editing a form](./autosave-tracking.md)