@pega/sdk 0.0.13 → 0.0.15

package/templates/react-sdk-reference/.ai-common/skills/field-skills/UserReference.md

@@ -1,6 +1,6 @@
 # Skill: UserReference
 
-User picker field that renders as either a search box (AutoComplete) or a dropdown, populated from the Pega operators data page.
+User picker field that binds to a Pega case property, backed by a data page of operators.
 
 > **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
@@ -8,7 +8,7 @@ User picker field that renders as either a search box (AutoComplete) or a dropdo
 
 ## Component Purpose
 
-Renders a user selection field. Can display as a typeahead search box or a dropdown list of Pega users. Resolves user IDs to display names for read-only and display modes. Optimized with shallow comparison to avoid unnecessary re-renders.
+Renders a user selection field. With the current field-configuration UI it is always set up as a searchable typeahead picker backed by a data page of operators (or another selected data page). Resolves the raw stored identifier to a human-readable display name for read-only and display presentations. Skips redundant re-rendering when unrelated inputs change.
 
 ## Pega Metadata
 
@@ -16,114 +16,178 @@ Renders a user selection field. Can display as a typeahead search box or a dropd
 - **Type / Subtype:** `Field` / `Text-UserReference`
 - **Registration key:** `UserReference` (in the project's component map)
 
+### Configuration Settings → Config Keys
+
+The Configure Field dialog for this field type exposes the following controls, and each one emits the config key(s) listed below into the view metadata. Every value below arrives at the component already resolved by the runtime — see Annotation Prefixes and Condition Encoding for what "resolved" means.
+
+| Configuration control            | Emitted config key(s)                  | Value shape and notes                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Display As                       | `displayAs`                            | Always `"Search box"` with the current configuration UI — the control is permanently disabled there. Treat this as a fixed fact about the field type, not a real choice.                                                                                                                                                                                                                                                                                                   |
+| Label                            | `labelOption` + `label`                | `labelOption` is `"default"` when the field's own name is kept (emitted as plain text) or `"custom"` when custom text is supplied (emitted with the localization marker). Always render the resolved `label` value; never branch rendering on `labelOption`.                                                                                                                                                                                                               |
+| Edit mode                        | `readOnly`                             | Absent (Auto), `true` (Read-only), an expression-marked string (Read-only on a Custom Condition), or a When-Rule-marked string (Read-only via a When Rule). See Condition Encoding.                                                                                                                                                                                                                                                                                        |
+| Data page                        | `referenceList`                        | The rule name of the selected data page — not the friendly label shown in the picker. This is fully configurable; never assume a fixed data page.                                                                                                                                                                                                                                                                                                                          |
+| Parameters                       | `parameters`                           | A flat object whose keys are the parameter names defined by the selected data page's own rule (the set of names differs per data page) and whose values may be a plain literal, a property reference, or an environment reference (see Annotation Prefixes). Present only when at least one parameter has a value; a parameter that is configured but left empty is emitted as an empty string and must be treated as not provided.                                        |
+| Placeholder                      | `placeholder`                          | The built-in default prompt is emitted as plain text; a custom placeholder is emitted with the localization marker.                                                                                                                                                                                                                                                                                                                                                        |
+| Helper text                      | `helperText`                           | Emitted with the localization marker when configured; absent otherwise.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Show field input warning         | `showFieldMessage` + `messageConfig`   | Enabling the checkbox emits `showFieldMessage: true` plus a `messageConfig` object with a `content` field (the localization-marked warning text, including any literal quote characters that were typed into it) and its own nested `visibility` field controlling when the warning itself should appear, encoded exactly like the top-level Condition Encoding. This nested `visibility` governs only the warning message, not the field itself — do not confuse the two. |
+| Show as formatted text           | `showAsFormattedText`                  | Boolean; only meaningful when the field is read-only (see Behavioral Contract).                                                                                                                                                                                                                                                                                                                                                                                            |
+| Required / Disabled / Visibility | `required` / `disabled` / `visibility` | Each encoded per Condition Encoding below. Visibility's extra choices (shown as "if not blank" or "if not zero") are convenience options in the configuration UI that compile down to the same expression encoding, evaluated against the field's own bound value — they introduce no new value shape.                                                                                                                                                                     |
+| Test ID                          | `testId`                               | A plain, non-localized string.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+
+### Annotation Prefixes
+
+The runtime resolves every one of the following markers before the component ever receives its inputs. The component must consume the already-resolved value and must never itself parse, strip, or evaluate these markers:
+
+- a **localization** marker on user-facing text (labels, placeholders, helper text, warning messages)
+- a **property reference** marker on values sourced from another field on the case
+- an **environment reference** marker on values sourced from application/operator environment information — this is the encoding actually used when a parameter's source is set to reference an operator attribute; despite that wording in the configuration UI, the resolved marker is an environment reference, not an operator-scoped one, so do not assume otherwise
+- an **expression** marker on values computed from a custom condition
+- a **When Rule** marker on values that reference a named decision rule
+- a **user reference** marker on the field's own bound value, identifying it as a reference to an operator
+
+Whenever a configuration picker displays a friendly label (a rule's description, a case field's display name, a data page's description), the underlying configuration stores the rule or property NAME instead of that label. Never assume one can be reconstructed from the other — treat both as opaque, independently-sourced strings.
+
+### Condition Encoding
+
+State this rule once and apply it everywhere it is relevant: `readOnly`, `required`, `disabled`, `visibility`, and the nested field-warning `visibility` can each arrive in one of six shapes — absent, the boolean `true`, the boolean `false`, an empty string, an expression-marked string, or a When-Rule-marked string. All six are already resolved to a plain boolean by the time the component receives the input. Consequences for a generated component:
+
+- Treat every one of these inputs as a plain boolean type. Never inspect its raw string form, and never treat a non-empty string as automatically true (doing so would make an expression- or rule-based setting permanently active).
+- Treat an absent value as equivalent to that setting's documented default, and treat an explicitly-set default value (for example an explicit `false`) exactly the same as an absent key. Never use key presence alone as a signal that a setting was deliberately changed.
+- Treat an empty string the same way. It means the setting was never given a value, not that it was set to something falsy — so it must resolve to the setting's default rather than being read as a present-but-empty value.
+
+### Generation Rules
+
+Guardrails that a generated component must follow to correctly honor every combination of settings:
+
+1. Use the data page named in `referenceList` as the source of selectable options; fall back to `PCore.getEnvironmentInfo().getDefaultOperatorDP()` only when `referenceList` is absent.
+2. Forward the `parameters` object to the datasource lookup unchanged, which means using `PCore.getDataApiUtils().getData(dataPageName, payload, context)` rather than a call that accepts no parameter payload. Never assume a fixed set of parameter names, and never send an empty-string parameter value as though it were provided.
+3. Apply mode precedence: while the field is read-only, ignore any configured `required`, `disabled`, `placeholder`, or field-warning settings even if those keys are still present in the metadata — they are stale leftovers from when the field was last editable, not active settings.
+4. Ensure the resolved `disabled` state genuinely prevents interaction with the rendered control, rather than simply being accepted as an unused input.
+5. Implement the field-warning contract as its own pair: only show a warning when `showFieldMessage` is true, and when it is, display the resolved `messageConfig` content, gated by the resolved `messageConfig` visibility — which is independent of the field's own visibility and must not be conflated with it.
+6. Never implement custom show/hide logic driven by the `visibility` setting. A field whose visibility resolves to false is not rendered at all by the surrounding runtime, so the component does not need to and should not handle that case itself.
+7. Resolve and display the user's name — not just the raw identifier — on every read-only and display-only rendering path, not only the one gated by "show as formatted text"; otherwise some read-only presentations will show an empty value instead of the user's name.
+8. Do not assume the fields used to search and display results are operator-specific. `pyUserName` and `pyUserIdentifier` are only guaranteed to exist when the configured data page is the operator list; a different data page requires resolving different fields generically rather than hardcoding these operator-specific property names.
+9. Treat the typeahead/search presentation as the only reachable rendering path for this field type. Do not build, wire, or rely on a separate dropdown-list rendering path, since the current configuration UI cannot produce the setting that would select it.
+10. Confirm this component's registry dependencies actually exist before relying on them. This component renders nothing of its own — it resolves a search/typeahead component and a value-display component out of the component registry — so if either is missing from the registry, this component silently renders nothing. See Registry Dependency Prerequisite below; generate and register any missing dependency before finishing this component.
+
 ## Inputs (component-specific)
 
 > Extends the project's base component interface (NOT the field input contract — field-specific inputs are defined manually).
 
-| Prop                  | Type                 | Default    | Description                                                      |
-| --------------------- | -------------------- | ---------- | ---------------------------------------------------------------- |
-| `displayAs`           | `string` (optional)  | `''`       | `'Drop-down list'` or `'Search box'` — determines the input type |
-| `displayMode`         | `string` (optional)  | `''`       | `'DISPLAY_ONLY'` or `'STACKED_LARGE_VAL'`                        |
-| `label`               | `string` (optional)  | `''`       | Field label                                                      |
-| `value`               | `any` (optional)     | `''`       | Raw value from Pega store (may be a user object or string ID)    |
-| `testId`              | `string` (optional)  | `''`       | Test identifier                                                  |
-| `placeholder`         | `string` (optional)  | `''`       | Placeholder text                                                 |
-| `helperText`          | `string` (optional)  | `''`       | Helper text                                                      |
-| `disabled`            | `boolean` (optional) | `false`    |                                                                  |
-| `readOnly`            | `boolean` (optional) | `false`    |                                                                  |
-| `required`            | `boolean` (optional) | `false`    |                                                                  |
-| `validatemessage`     | `string` (optional)  | `''`       | Validation error message                                         |
-| `showAsFormattedText` | `boolean` (optional) | `false`    | When `true` in read-only mode, show formatted user name text     |
-| `additionalProps`     | `object` (optional)  | `{}`       | Extra inputs forwarded to the child component                    |
-| `hideLabel`           | `boolean` (optional) | `false`    |                                                                  |
-| `variant`             | `string` (optional)  | `'inline'` | Layout variant                                                   |
-| `onChange`            | `any` (optional)     | —          | Change handler (passed through to child)                         |
+| Input                 | Type                 | Default     | Description                                                                                                                      |
+| --------------------- | -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `displayAs`           | `string` (optional)  | `''`        | Always arrives as `'Search box'`; informational only, do not branch rendering on it                                              |
+| `displayMode`         | `string` (optional)  | `''`        | `'DISPLAY_ONLY'` or `'STACKED_LARGE_VAL'`                                                                                        |
+| `label`               | `string` (optional)  | `''`        | Field label, already resolved (any localization marker already removed by the runtime)                                           |
+| `value`               | `any` (optional)     | `''`        | Raw value from Pega store (may be a user object or string ID)                                                                    |
+| `status`              | `string` (optional)  | —           | `'error'` or `'warning'` — drives validation-state styling                                                                       |
+| `testId`              | `string` (optional)  | `''`        | Test identifier                                                                                                                  |
+| `placeholder`         | `string` (optional)  | `''`        | Placeholder text, already resolved                                                                                               |
+| `helperText`          | `string` (optional)  | `''`        | Helper text, already resolved                                                                                                    |
+| `disabled`            | `boolean` (optional) | `false`     |                                                                                                                                  |
+| `readOnly`            | `boolean` (optional) | `false`     | Already-resolved boolean regardless of whether it was set to Always, a Custom Condition, or a When Rule                          |
+| `required`            | `boolean` (optional) | `false`     | Already-resolved boolean                                                                                                         |
+| `validatemessage`     | `string` (optional)  | `''`        | Validation error message; takes precedence over `helperText` when both are present                                               |
+| `showAsFormattedText` | `boolean` (optional) | `false`     | Meaningful only when `readOnly` is `true` — see Behavioral Contract                                                              |
+| `referenceList`       | `string` (optional)  | —           | The configured data page name; source of options for the picker                                                                  |
+| `parameters`          | `object` (optional)  | —           | Flat name-to-value map of data-page parameters; names and required-ness are defined by the selected data page, not by this field |
+| `showFieldMessage`    | `boolean` (optional) | `false`     | Enables the field-warning contract                                                                                               |
+| `messageConfig`       | `object` (optional)  | —           | Field-warning content and its own independent visibility                                                                         |
+| `labelOption`         | `string` (optional)  | `'default'` | `'default'` or `'custom'`; informational only — always render the resolved `label`                                               |
+| `visibility`          | `boolean` (optional) | `true`      | Already-resolved boolean; the component is typically never rendered at all when this is `false`                                  |
+| `additionalProps`     | `object` (optional)  | `{}`        | Extra inputs forwarded to the child component                                                                                    |
+| `hideLabel`           | `boolean` (optional) | `false`     |                                                                                                                                  |
+| `variant`             | `string` (optional)  | `'inline'`  | Layout variant                                                                                                                   |
+| `onChange`            | `any` (optional)     | —           | Change handler (passed through to child)                                                                                         |
 
 ## Implementation Structure
 
-Orchestrator component — renders either AutoComplete, Dropdown, formatted text, or FieldValueList based on mode. Wrapped in a memoization wrapper with a custom comparison function.
+Orchestrator component — it renders no input control itself, but instead delegates to a registered search/typeahead component, a registered formatted-text/value-display component, or an inline label-plus-name block, depending on mode. It also skips redundant re-rendering when its inputs have not meaningfully changed.
+
+### Registry Dependency Prerequisite
+
+> **Check this before writing the component.** Because this component only orchestrates other components, it cannot work unless its dependencies are already generated and registered.
+
+The components it resolves from the registry — the search/typeahead component (registry key `AutoComplete`), the value-display component (registry key `FieldValueList`), and, only if the legacy path is retained, the dropdown/select component (registry key `Dropdown`) — are **not** guaranteed to exist. Tooling that discovers components by walking a case's view metadata will not find them, because they never appear as fields in that metadata; they are internal building blocks that only this component (and others like it) reach for at runtime. So a discovery-driven generation pass can produce `UserReference` while silently omitting everything it depends on.
+
+The failure this causes is quiet: the registry lookup returns nothing, and the field renders as blank with no error. Do not assume a missing dependency will announce itself.
 
-**Module Setup:** The component depends on the project's component registry (to resolve `AutoComplete`, `Dropdown`, and `FieldValueList`) and local utility helpers (`getUserId` and `isUserNameAvailable`). It also uses `PCore.getUserApi()`, `PCore.getRestClient()`, and `PCore.getEnvironmentInfo()` for user data resolution. Define two constants: `DROPDOWN_LIST = 'Drop-down list'` and `SEARCH_BOX = 'Search box'`. Define the input contract as an extension of the project's base component interface with all the optional fields listed in the inputs table above.
+Before finishing this component:
 
-**Main Component Logic** (defined as an arrow function, not a plain function declaration) — steps in order:
+1. Check whether each required registry key is already registered in the project's component map, or was generated earlier in the current session.
+2. For any key that is missing, generate that component from its own skill file and register it under its expected key.
+3. Only then wire this component to resolve them.
 
-1. **Registry lookups** — resolve `AutoComplete`, `Dropdown`, and `FieldValueList` via the project's component registry.
-2. **Receive inputs (all with defaults)** — `label` (default `''`), `displayAs` (default `''`), `displayMode` (default `''`), `getPConnect`, `value` (default `''`), `testId` (default `''`), `helperText` (default `''`), `validatemessage` (default `''`), `placeholder` (default `''`), `showAsFormattedText` (default `false`), `additionalProps` (default `{}`), `hideLabel` (default `false`), `readOnly` (default `false`), `required` (default `false`), `disabled` (default `false`), `onChange`.
-3. **Local state** — `dropDownDataSource` (array, default `[]`) and `userName` (string, default `''`).
-4. **Derived values** — `OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP()` (the default operators data page name) and `userId = getUserId(value)`.
-5. **Mount/update effect** — a lifecycle effect with dependencies `[displayAs, readOnly, showAsFormattedText, value]`, handling two cases (see Behavioral Contract below for the exact branching logic): resolving the display username when in read-only formatted-text mode, or fetching the dropdown data source when `displayAs === 'Drop-down list'`.
-6. **Rendering decision tree** (see Behavioral Contract below for the exact order): `DISPLAY_ONLY` returns `FieldValueList(userName || '')`; `STACKED_LARGE_VAL` returns the stacked variant; read-only formatted text mode returns a label + username text block; `'Search box'` mode renders `AutoComplete`; `'Drop-down list'` mode renders `Dropdown`.
+Apply the same check to any component that is itself an orchestrator — a missing leaf dependency several levels down produces the same blank render.
 
-**Export:** wrap the component in a memoization wrapper with a custom comparison function (see "Re-render optimization" below).
+**Module Setup:** The component depends on the project's component registry (to resolve the registered search/typeahead component and the registered value-display component) and on local utility helpers for extracting a user identifier from the value and for checking whether a display name is already present on the value. It also depends on three Pega Platform APIs, all reached through the global `PCore` object and detailed in the Pega Platform APIs section below: `PCore.getEnvironmentInfo().getDefaultOperatorDP()`, `PCore.getUserApi().getOperatorDetails(userId)`, and `PCore.getDataApiUtils().getData(dataPageName, payload, context)`. Recognize that `displayAs` can in principle carry either of its two known values, but only one of them (the search/typeahead value) is reachable through the current configuration UI — see Generation Rules. Define the input contract as an extension of the project's base component interface with every optional field listed in the Inputs table above, including the previously-unused `referenceList`, `parameters`, `showFieldMessage`, and `messageConfig`.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve the registered search/typeahead component and the registered value-display component via the project's component registry. See Registry Dependency Prerequisite above — these must already be generated and registered, or the field renders blank.
+2. **Receive inputs (all with defaults)** — every input listed in the Inputs table, each defaulted as documented there.
+3. **Local state** — a resolved-display-name value (initially empty) and, only for the legacy dropdown-list path, a fetched options list (initially empty).
+4. **Derived values** — resolve which data page to query: the configured `referenceList` when present, otherwise the value returned by `PCore.getEnvironmentInfo().getDefaultOperatorDP()`; and resolve the user identifier from the raw `value` using the identifier-extraction helper.
+5. **Asynchronous resolution step** — work that runs once when the component is first displayed, and again whenever the resolved identifier, read-only state, formatted-text flag, or value changes. It resolves the display name needed for every read-only and display presentation (see Behavioral Contract), and — unlike a naïve implementation — also resolves the field-warning message and its visibility when the field warning is enabled. Use whatever mechanism the target framework provides for running side effects in response to changed inputs.
+6. **Rendering decision tree** (see Behavioral Contract below for the exact order): a display-only mode renders the value-display component with the resolved name; a stacked display mode renders its stacked variant; read-only with formatted text renders the inline label-plus-name block; otherwise render the search/typeahead component, passing through the resolved datasource and parameters.
+
+**Expose the component** with the re-render-skipping behavior described under "Re-render optimization" below applied to it, using whatever change-detection mechanism the target framework provides.
 
 ## Behavioral Contract
 
 ### User ID extraction
 
-`getUserId(value)` — utility that extracts the user identifier from the value (which may be a plain string or a user object with an ID property).
+An identifier-extraction helper reads the user identifier out of the value, which may be a plain string or a user object carrying an identifier property.
 
 ### State
 
-- `dropDownDataSource` (array): populated when `displayAs === 'Drop-down list'`
-- `userName` (string): resolved display name for formatted text mode
+- A fetched options list, populated only on the legacy, no-longer-configurable dropdown-list path.
+- A resolved display name, used by every read-only and display presentation.
 
-### Mount effect: lifecycle effect watching `[displayAs, readOnly, showAsFormattedText, value]`
+### Asynchronous resolution
 
-**Case 1: `userId && readOnly && showAsFormattedText`**
+This work runs once when the component is first displayed, and again whenever the resolved identifier, read-only state, formatted-text flag, or value changes. It handles two situations:
 
-- If `isUserNameAvailable(value)`: `setUserName(value.userName)` — username already in value object
-- Else: call `PCore.getUserApi().getOperatorDetails(userId)` and extract `pyUserName` from response
+**Resolving the display name** — needed whenever the field is being shown in a read-only or display presentation (not only when "show as formatted text" is checked; see Generation Rules). If the value already carries a display name, use it directly. Otherwise, call `PCore.getUserApi().getOperatorDetails(userId)` with the resolved identifier and read the display name from `pyUserName` inside the `pyOperatorInfo` object on the resolved response's `data` property.
 
-**Case 2: `displayAs === 'Drop-down list'`**
+**Resolving the field-warning content** — when the field warning is enabled, resolve its message text and its own independent visibility so they are ready before the warning needs to be shown.
 
-- Call `PCore.getRestClient().invokeRestApi('getListData', { queryPayload: { dataViewName: OPERATORS_DP } })`
-- Map results to `{key: pyUserIdentifier, value: pyUserName}` array
-- `setDropDownDataSource(mapped)`
-
-`OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP()` — the default operators data page name.
+The legacy dropdown-list path (no longer producible through configuration) additionally fetches a full list of users by calling `PCore.getRestClient().invokeRestApi('getListData', { queryPayload: { dataViewName } })` and maps each row from the resolved response's nested `data.data` array into an option keyed by `pyUserIdentifier` with `pyUserName` as its display value.
 
 ### Rendering decision tree
 
-Evaluated in this order: if `displayMode === 'DISPLAY_ONLY'`, render `FieldValueList(userName || '')`; else if `displayMode === 'STACKED_LARGE_VAL'`, render the stacked `FieldValueList` variant; else if `readOnly && showAsFormattedText && userId`, render the formatted text block; else if `displayAs === 'Search box'`, render the `AutoComplete` component; else if `displayAs === 'Drop-down list'`, render the `Dropdown` component.
-
-### Subsection: Search box mode (`displayAs === 'Search box'`)
+Evaluated in this order: a display-only mode renders the value-display component with the resolved display name; a stacked display mode renders that same component's stacked variant; being read-only with "show as formatted text" enabled and an identifier present renders the inline label-plus-name block; otherwise render the search/typeahead component using the resolved datasource, resolved parameters, and resolved identifier.
 
-Render `AutoComplete` with hardcoded columns for operator search: a primary column on `pyUserName` (displayed, used for search, marked primary), and a secondary key column on `pyUserIdentifier` (displayed, used for search, marked secondary, with `setProperty: 'Associated property'` and `key: 'true'`).
+### Subsection: Search/typeahead presentation
 
-Inputs: `datasource` set to `OPERATORS_DP`, `listType='datapage'`, `value` set to `userId`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
+This is the only presentation the current configuration UI can produce. Render the registered search/typeahead component using the datasource resolved in step 4 (the configured `referenceList`, or `PCore.getEnvironmentInfo().getDefaultOperatorDP()` as a fallback) and the parameters resolved from the `parameters` setting. Configure the search/select columns generically rather than assuming operator-specific field names: when the datasource is known to be the operator list, a display column and a paired identifier column — `pyUserName` and `pyUserIdentifier` respectively — are appropriate; for any other configured data page, resolve equivalent display and identifier columns from that data page's own shape instead of assuming these operator-specific names apply.
 
-### Subsection: Dropdown mode (`displayAs === 'Drop-down list'`)
+Also pass through: label, placeholder, read-only state, disabled state, required state, helper text, validation message, hide-label flag, change handler, additional inputs, and test id.
 
-Render `Dropdown` with:
+### Subsection: Legacy dropdown-list presentation (no longer producible through configuration)
 
-- `datasource={dropDownDataSource}` (fetched user list)
-- `listType='associated'`
-- `value={userId}`
-- Plus same field inputs as above
+A dropdown-style presentation exists in the reference implementation for backward compatibility with views built before the current configuration UI, but the control that would select it is now permanently fixed to the search/typeahead value. Do not implement this as a co-equal alternative path when generating a new component; treat the search/typeahead presentation as the sole target, and only preserve a dropdown fallback if there is a concrete need to support pre-existing views that still carry the legacy value.
 
-### Subsection: Formatted text read-only (`readOnly && showAsFormattedText && userId`)
+### Subsection: Formatted text read-only presentation
 
-Render a small wrapper containing a caption-style text element showing `label`, followed by a body-style text element showing `userName`.
+Render a small block containing a caption-style text element showing the label, followed by a body-style text element showing the resolved display name.
 
 ### Re-render optimization
 
-Export with a memoization wrapper using a custom comparison function that returns `true` (skip re-render) only when all of the following are equal between previous and next inputs: `getUserId(value)` (resolved on both sides), `validatemessage`, `required`, `disabled`, and `readOnly`.
+The component should re-render only when something it actually displays has changed. Skip the re-render only when every one of the following is unchanged between the previous and next inputs: the resolved user identifier, the validation message, the required state, the disabled state, the read-only state, and — to correct a gap in the original approach — the displayed text inputs as well (label, placeholder, helper text, and test id), so that configured text changes always repaint. Express this with whatever change-detection mechanism the target framework offers; the comparison list above is the contract, not the mechanism.
 
 ## Display Mode Rendering
 
-Uses resolved `userName` (not raw `value`):
+Both display-only and stacked-display modes render through the registered value-display component, passing the resolved display name (not the raw value), so the same identifier-to-name resolution used for formatted-text mode is reused here too. For the stacked mode, additionally request the value-display component's stacked layout.
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={userName || ''} />`
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={userName || ''} variant='stacked' />`
-
-`userName` may still be empty string while the async `getOperatorDetails` call resolves — this is expected.
+The value-display component shows a placeholder dash sequence when given an empty or undefined value, rather than rendering nothing — so the resolved display name must genuinely be available before this render happens. Resolve the display name whenever the field is in a display-only or stacked-display mode, not only when it is read-only and showing formatted text; otherwise these presentations will show the placeholder dash sequence instead of the user's name.
 
 ## Visual Specifications
 
-The visual appearance is determined by the child component rendered:
+The visual appearance is determined by which presentation is active:
 
-- **Search box**: Same as `AutoComplete` — combobox input with outlined border, floating label
-- **Dropdown**: Same as `Dropdown` — select field with outlined border, floating label
+- **Search/typeahead presentation**: combobox input with outlined border, floating label — matching the project's shared typeahead/search component
+- **Legacy dropdown-list presentation**: select field with outlined border, floating label — matching the project's shared dropdown/select component
 - **Formatted text read-only**:
 
 | Property | Value                                                     |
@@ -136,31 +200,65 @@ The visual appearance is determined by the child component rendered:
 
 ## Edge Cases & Special Logic
 
-- **`getUserId`**: handles both plain string values and object values with an ID property.
-- **`isUserNameAvailable`**: checks whether the value object already contains a `userName` property (avoiding unnecessary API call).
-- **Async name resolution**: when `userName` is not available in the value object, a REST call is made. The component renders empty initially and updates when the call completes.
-- **Drop-down source**: Users are fetched via REST API (`getListData`), not via a data page config — this is different from `AutoComplete`/`Dropdown` field patterns.
-- **`onChange` prop** is passed through to the child component unchanged — it's the platform-wired handler.
+- **Identifier extraction**: handles both plain string values and object values with an identifier property.
+- **Display-name availability check**: checks whether the value object already contains a display-name property, avoiding an unnecessary lookup call.
+- **Async name resolution**: when the display name is not already available on the value object, a `PCore.getUserApi().getOperatorDetails(userId)` call is made. The resolved name starts empty and updates once the Promise resolves; any presentation that depends on it should tolerate this brief empty state rather than treating it as an error.
+- **Stale configuration keys**: keys such as `required`, `disabled`, `placeholder`, `showFieldMessage`, or `messageConfig` may still be present in the metadata even after the field has become read-only, because the configuration UI does not necessarily clear a setting's value when its control becomes hidden. Apply the mode-precedence rule from Generation Rules rather than trusting key presence.
+- **Empty parameter values**: a data-page parameter that is configured but left blank is emitted as an empty string rather than omitted entirely; treat it as not provided rather than forwarding it as a real value.
+- **Non-operator data pages**: `pyUserName` and `pyUserIdentifier` are only guaranteed to exist when the configured data page is the operator list. A different configured data page may expose different fields, and those need to be resolved from that data page's own shape rather than assumed.
+- **Field warning independence**: the field-warning contract (`showFieldMessage` / `messageConfig`) is a separate notification channel from validation messaging (`validatemessage`) and helper text (`helperText`); implement it as its own affordance rather than folding it into either of those.
+- **Legacy dropdown-list data source**: when the legacy path is retained, its options come from `PCore.getRestClient().invokeRestApi('getListData', ...)`, which accepts no parameter payload, rather than the parameter-aware `PCore.getDataApiUtils().getData(...)` used by the search/typeahead presentation — keep this distinction if both paths are ever supported side by side.
+- **Missing registry dependencies**: a registry lookup that finds nothing causes a silent blank render, not an error. This is the most likely failure mode when this component is generated by a pass that discovered components from case view metadata, since its dependencies never appear in that metadata. See Registry Dependency Prerequisite.
+- **`onChange` input** is passed through to the child component unchanged — it's the platform-wired handler.
 
 ## Dependencies
 
-- A memoization wrapper from the framework.
-- Local utility helpers: `getUserId`, `isUserNameAvailable`.
-- The project's component registry, resolving `AutoComplete` — for search box mode.
-- The project's component registry, resolving `Dropdown` — for dropdown mode.
-- The project's component registry, resolving `FieldValueList` — for display modes.
-- `PCore.getUserApi().getOperatorDetails()` — for async user name resolution.
-- `PCore.getRestClient().invokeRestApi('getListData', ...)` — for dropdown data source.
-- `PCore.getEnvironmentInfo().getDefaultOperatorDP()` — for operators data page name.
+> Every registry dependency below must be generated and registered before this component can render — see Registry Dependency Prerequisite.
+
+- The target framework's change-detection mechanism for skipping redundant re-renders.
+- Local utility helpers for identifier extraction and display-name availability checking.
+- The project's component registry, resolving the shared search/typeahead component (key `AutoComplete`) — for the search/typeahead presentation.
+- The project's component registry, resolving the shared dropdown/select component (key `Dropdown`) — for the legacy dropdown-list presentation, if retained.
+- The project's component registry, resolving the shared value-display component (key `FieldValueList`) — for display-only and stacked-display presentations.
+- The Pega Platform APIs listed in the next section.
+
+## Pega Platform APIs
+
+All of these are reached through the global `PCore` object, which the SDK runtime installs on the window before any component renders. Never import them from a package — read them off `PCore` at the point of use. Each entry below gives the call, what it returns, and how this component uses it.
+
+**`PCore.getEnvironmentInfo().getDefaultOperatorDP()`**
+
+- Returns: a string — the rule name of the application's default operator data page (a `D_`-prefixed data page listing operators).
+- Synchronous; safe to call during render.
+- Used as the fallback datasource for the picker when the `referenceList` config key is absent. When `referenceList` is present, use that value instead and do not call this.
+
+**`PCore.getUserApi().getOperatorDetails(userId)`**
+
+- Parameter: `userId` — the operator identifier string extracted from the field's `value`.
+- Returns: a Promise resolving to a response object whose `data` property contains a `pyOperatorInfo` object; the operator's display name is the `pyUserName` property inside it.
+- Used to resolve a raw operator identifier into a human-readable name for every read-only and display presentation. Guard the read — `data`, `pyOperatorInfo`, and `pyUserName` may each be missing — and only set the resolved name when all three are present.
+
+**`PCore.getDataApiUtils().getData(dataPageName, payload, context)`**
+
+- Parameters: `dataPageName` — the resolved datasource rule name; `payload` — an object carrying the data page's parameters, built from the `parameters` config key; `context` — the current context name, obtained from `getPConnect().getContextName()`.
+- Returns: a Promise resolving to a response object whose rows are at the nested `data.data` array.
+- Used to fetch selectable options when the picker needs its own list, and it is the correct call for honoring the `parameters` config key, because it accepts a parameter payload.
+
+**`PCore.getRestClient().invokeRestApi('getListData', { queryPayload: { dataViewName } })`** — legacy only
+
+- Parameters: the literal API name `'getListData'` and an options object containing a `queryPayload` whose `dataViewName` is the data page rule name.
+- Returns: a Promise resolving to a response object whose rows are at the nested `data.data` array.
+- Used only by the legacy dropdown-list path. Prefer `PCore.getDataApiUtils().getData(...)` for anything new, since this call takes no parameter payload and therefore cannot honor the `parameters` config key.
 
 ## Design System Mapping
 
-**UI control type:** User picker — delegates to AutoComplete or Dropdown for the actual input.
+**UI control type:** User picker — delegates to a shared search/typeahead or dropdown/select component for the actual input.
 
 When implementing in a specific design system, map the following:
 
-- **Search box mode** → render the `AutoComplete` component with operator columns
-- **Dropdown mode** → render the `Dropdown` component with the fetched operator list
+- **Search/typeahead presentation** → render the shared search/typeahead component, sourced from the configured data page (with the default operator data page as fallback) and the configured parameters, with generically-resolved search/display fields
+- **Legacy dropdown-list presentation** → render the shared dropdown/select component with a fetched option list, retained only for backward compatibility and no longer producible through configuration
 - **Formatted text read-only** → render a label + text display (caption + body text)
-- **Display mode** → render `FieldValueList` with the resolved username
-- **Memoization** → wrap the component with a custom comparison to avoid unnecessary re-renders
+- **Display-only / stacked-display presentation** → render the shared value-display component with the resolved display name
+- **Field warning** → map to a secondary/alternate messaging affordance, independent of the error/helper-text region
+- **Re-render skipping** → apply the framework's change-detection mechanism using the comparison list above, which must include the displayed-text inputs so configured text changes are never missed

package/templates/react-sdk-reference/.ai-common/skills/infra-components.md

@@ -108,7 +108,7 @@ When an infrastructure component renders another Pega component, resolve it thro
 
 The runtime contract — inputs, callback signatures, derivation logic, and localization — is identical regardless of design system. Only the rendered markup changes.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/infra-skills/<ComponentName>.md` contains a **Design System Mapping** section. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/infra-skills/<ComponentName>{{SKILL_EXT}}` contains a **Design System Mapping** section. Use it as a starting point.
 
 **2. If the chosen design system is not covered** — use the component purpose description to identify the appropriate primitives (button, stepper, breadcrumb, divider, list).
 
@@ -129,6 +129,18 @@ The runtime contract — inputs, callback signatures, derivation logic, and loca
 
 ---
 
+## Visual Preservation
+
+When replacing an existing implementation, the replacement must look the same as the original:
+
+1. **Read the component's companion style file first** (for example a `.css` file in its folder). Note every class's visual intent — spacing, sizing, colours, and layout.
+2. Reproduce that intent through the new design system's inputs or variants, inline styles, or by keeping the style import — whichever gives the closest match.
+3. Never silently drop legacy styling utility classes — map each one to an equivalent style.
+
+In the embedded flow there is no original to preserve: the customer's look, recorded in the Design Profile, decides instead.
+
+---
+
 ## Registration
 
 Register infrastructure overrides in the project's component map under the component's Pega name. Because the SDK's own components are contributed as a spread of built-in entries, **an override must appear after that spread** — an entry listed before it is replaced by the SDK's version and the override silently does nothing.