@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,112 @@
+# Skill: TextInput
+
+Single-line text input field that binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a single-line editable text field. It is the simplest and most foundational field component — used directly for free-text string properties and also delegated to by other components (e.g., `Email`, `URL`, `Date` in read-only mode).
+
+## Pega Metadata
+
+- **Pega Name:** `TextInput`
+- **Type / Subtype:** `Field` / `Text`
+- **Registration key:** `TextInput` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name            | Type             | Description                                             |
+| --------------- | ---------------- | ------------------------------------------------------- |
+| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the input |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+The foundational field component — simplest pattern. All text-like fields (Email, URL, Integer, Phone) follow this structure with minor variations.
+
+**Module Setup:** The component depends on the project's event-commit utility (for committing value changes to the store) and the project's component registry (to resolve the `FieldValueList` display component). Define the input contract as an extension of the project's field input contract, adding an optional `fieldMetadata` field.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `fieldMetadata`, `helperText`, `displayMode`, `hideLabel`, `placeholder`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`, and `maxLength = fieldMetadata?.maxLength`.
+4. **Local state and read-only flag** — `inputValue` initialized to `''`; declare a read-only configuration object (populated conditionally later).
+5. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever `value` changes.
+6. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+7. **Read-only flag** — set the read-only configuration to mark the input read-only only when `readOnly` is true.
+8. **Test ID and handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's input value; the blur handler commits the value via the project's event-commit utility, passing the actions API, event type `'changeNblur'`, the property name, and `inputValue`.
+9. **Render** — a single-line text input configured with: full width, a visually outlined style when editable and a flat/borderless style when read-only, small size, current `inputValue`, the change handler wired to update local state, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and `maxLength` plus the read-only/test-id attributes applied to the underlying input element.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to the `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching the `value` input updates `inputValue` whenever `value` changes.
+3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
+4. **On blur:** Commit to store by invoking the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Read-only:** Render input with a read-only attribute set; use a visually borderless ("standard") style. Do NOT skip the blur handler unconditionally — only omit it when the field is read-only.
+6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the underlying input's `maxLength` attribute.
+7. **testId:** Pass as a test-identifier attribute on the underlying input element.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render the `FieldValueList` display component with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — display raw string value, no formatting.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+- Both modes use the `value` input directly (not local state).
+- Both modes short-circuit before any interactive rendering.
+
+## Read-Only Rendering
+
+Set a read-only attribute on the underlying input element. Use a visually flat/borderless style (no border box). The editable outlined style switches to a flat (no outline) style when read-only.
+
+## Visual Specifications
+
+Derived from the reference component's styling:
+
+| Property        | Standard (editable)                              | Read-only         |
+| --------------- | ------------------------------------------------ | ----------------- |
+| Width           | 100% of container                                | 100% of container |
+| Height / size   | Small (`height ~40px`)                           | Small             |
+| Border          | 1px solid (outlined)                             | None (flat style) |
+| Border radius   | 4px                                              | —                 |
+| Label           | Floating label (above input when focused/filled) | Floating label    |
+| Helper text     | Shown below input                                | Shown below input |
+| Error state     | Red border + red helper text                     | —                 |
+| Disabled        | Reduced opacity (~0.38), not-allowed cursor      | —                 |
+| Padding (input) | 8px 14px                                         | —                 |
+| Font size       | 0.875rem (14px)                                  | 0.875rem          |
+
+**CSS-only implementation notes:**
+
+- Floating label: use `<label>` positioned absolutely, translate upward on `:focus-within` or when input has value.
+- Error state: add `.error` class → border-color: `#d32f2f`; helper text color: `#d32f2f`.
+- Outlined box shadow on focus: `0 0 0 2px rgba(25, 118, 210, 0.2)`.
+
+## Edge Cases & Special Logic
+
+- If the `value` input is `undefined`, default to `''` to keep the input controlled.
+- If `readOnly` is true, the blur handler must be omitted — do not commit on blur for read-only.
+- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
+
+## Dependencies
+
+- The project's event-commit utility — for committing value to store.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- No third-party UI libraries required beyond a basic text input element.
+
+## Design System Mapping
+
+**UI control type:** Single-line text input.
+
+When implementing in a specific design system, map the following:
+
+- **Text input** → use the DS's basic text input component
+- **`status === 'error'`** → the DS's error/danger visual state
+- **`helperText`** → the DS's helper/description text slot below the input
+- **`label`** → the DS's field label (floating or static depending on the design system)
+- **`disabled`** → the DS's disabled state
+- **`required`** → the DS's required/asterisk indicator

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

@@ -0,0 +1,102 @@
+# Skill: Time
+
+Time picker field with 5-minute step increments, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a time-only picker. Stores time as `HH:mm:ss` string. Displays time in 12-hour (`hh:mm a`) format. Uses 5-minute step increments for the picker. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Time`
+- **Type / Subtype:** `Field` / `Time`
+- **Registration key:** `Time` (in the project's component map)
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+No local state for the time value — it is derived directly from the `value` input on each render.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `TextInput`), the project's event-commit utility, and a date/time manipulation library (for parsing and formatting time values). Define the input contract as the project's field input contract with no additional fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `TextInput` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `helperText`, `displayMode`, `hideLabel`, `testId`. Compute `helperTextToDisplay = validatemessage || helperText`, and set up the PConnect instance, actions API, and bound property name.
+3. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+4. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+5. **Test ID** — build a test-id attribute from `testId`.
+6. **Change handler — commit on change, not blur** — given a selected time object: if it is valid, format it to `'HH:mm:ss'`; otherwise use `null`. Immediately commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted value — there is no separate blur-triggered commit for this field.
+7. **Parse time value from the `HH:mm:ss` string** — when `value` is present and non-empty, split it on `:` into numeric parts and construct a time object with the parsed hours and minutes to get the picker's controlled time value; otherwise the time value is `null`.
+8. **Render** — a time picker configured with: `disabled`, `label`, current time value, minutes step of `5`, display format `'hh:mm a'`, the change handler, and a nested text-field slot configured with an outlined style, placeholder `'hh:mm am'`, `required`, an error state when `status === 'error'`, `helperText: helperTextToDisplay`, small size, and the test-id attribute applied to the input element.
+
+## Behavioral Contract
+
+1. **Value format stored/committed:** `HH:mm:ss` (24-hour, e.g., `'14:30:00'`).
+2. **Value parsed for display:** Split the `HH:mm:ss` string into `[hours, minutes, seconds]` and construct a time object using the date library.
+3. **Local state:** No explicit local state for the time value — the picker's controlled value is derived from the `value` input directly on each render.
+4. **On change:**
+   - If the time object is valid: format to `'HH:mm:ss'`, else use `null`.
+   - Commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted value.
+5. **Display format:** `'hh:mm a'` (12-hour with am/pm) in the picker UI.
+6. **Placeholder:** `'hh:mm am'`.
+7. **Minutes step:** 5 minutes.
+8. **Read-only:** Delegate to `TextInput`, passing all inputs through.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw time string, no extra formatting.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`, passing all inputs through.
+
+## Visual Specifications
+
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| Width        | Auto (time picker natural width) |
+| Size         | Small                            |
+| Variant      | Outlined                         |
+| Format       | `hh:mm a` (12-hour)              |
+| Placeholder  | `hh:mm am`                       |
+| Minutes step | 5                                |
+| Error state  | Red border + red helper text     |
+
+**Note on known issue:** Keyboard input in the minute field may jump to the am/pm field after one digit — same as DateTime, this is a known date picker library quirk.
+
+## Edge Cases & Special Logic
+
+- **Null/empty value:** When `value` is empty or has no content, set the time value to `null` — do NOT try to parse an empty value.
+- **Value parsing:** Split by `:` and convert each part to a number before constructing the time object.
+- **Commits on change** (picker selection), not on blur.
+- If the time object is invalid (user clears the time), commit `null`.
+
+## Dependencies
+
+- A date/time manipulation library — for time parsing and formatting to `'HH:mm:ss'`.
+- A time picker UI component (for the clock popup or time selection UI).
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+
+## Design System Mapping
+
+**UI control type:** Time picker (clock popup or input with am/pm selector).
+
+When implementing in a specific design system, map the following:
+
+- **Time picker** → use the DS's time picker component or a compatible third-party picker
+- **Display format** → `'hh:mm a'` (12-hour with am/pm)
+- **Minutes step** → configure the time picker to snap to 5-minute increments
+- **Stored format** → `'HH:mm:ss'` (24-hour, committed to the Pega store)
+- **Read-only mode** → delegate to the `TextInput` component
+- **Commit behavior** → commit on valid selection (not on blur)

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

@@ -0,0 +1,96 @@
+# Skill: URL
+
+URL input field with browser-native URL validation, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a single-line text input of type `url`. Provides browser-native URL format validation. Delegates read-only rendering to the `TextInput` component.
+
+## Pega Metadata
+
+- **Pega Name:** `URL`
+- **Type / Subtype:** `Field` / `Text-URL`
+- **Registration key:** `URL` (in the project's component map)
+
+> **Important naming note:** The component's export name should avoid conflicts with the platform's built-in `URL` global (e.g., use `URLComponent` as the export name). Register it under the key `URL` in the project's component map.
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Nearly identical to TextInput — only difference is the `url` input type.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `TextInput`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as the project's field input contract with no additional fields. Export the component with a name that avoids conflicts with the platform's built-in `URL` global.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `TextInput` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Compute `helperTextToDisplay = validatemessage || helperText`, initialize `inputValue` local state to `''`, and set up the PConnect instance, actions API, and bound property name.
+3. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+4. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+5. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+6. **Handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's input value; the blur handler commits the value via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+7. **Render** — same configuration as TextInput but with a `url` input type: full width, an outlined style, small size, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and the test-id attribute applied to the underlying input element.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` (string). Initialize from the `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching `value` updates `inputValue`.
+3. **On change:** Update local state only.
+4. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Input type:** Use a `url`-typed input for browser-native URL format hint/validation.
+6. **Read-only:** Delegate entirely to the `TextInput` component, passing all inputs through.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw URL string.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`, passing all inputs through.
+
+## Visual Specifications
+
+Identical to `TextInput` visually — no additional adornments.
+
+| Property      | Value                        |
+| ------------- | ---------------------------- |
+| Width         | 100%                         |
+| Size          | Small (~40px height)         |
+| Variant       | Outlined                     |
+| Border        | 1px solid outlined           |
+| Border radius | 4px                          |
+| Error state   | Red border + red helper text |
+| Helper text   | Below input                  |
+
+No special icon or adornment — the only difference from `TextInput` is the `url` input type.
+
+## Edge Cases & Special Logic
+
+- The component's export name should avoid shadowing the platform's global `URL` constructor. Register under the key `URL` in the project's component map.
+- The `url` input type triggers browser tooltip/validation but Pega validation is the authoritative source.
+- The blur handler is only wired when the field is not read-only.
+
+## Dependencies
+
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+
+## Design System Mapping
+
+**UI control type:** Single-line URL text input.
+
+When implementing in a specific design system, map the following:
+
+- **URL input** → use the DS's text input with input type set to `url`
+- **Read-only mode** → delegate to the `TextInput` component
+- **Error state** → the DS's error/danger visual state
+- **Helper text** → the DS's helper/description text slot below the input

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/field-skills/UserReference.md

@@ -2,7 +2,7 @@
 
 User picker field that renders as either a search box (AutoComplete) or a dropdown, populated from the Pega operators data page.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,15 +14,11 @@ Renders a user selection field. Can display as a typeahead search box or a dropd
 
 - **Pega Name:** `UserReference`
 - **Type / Subtype:** `Field` / `Text-UserReference`
-- **Registration key:** `UserReference` (in `component-map.ts`)
+- **Registration key:** `UserReference` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-> Extends `PConnProps` (NOT `PConnFieldProps` — field-specific props are defined manually):
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-```
+> Extends the project's base component interface (NOT the field input contract — field-specific inputs are defined manually).
 
 | Prop                  | Type                 | Default    | Description                                                      |
 | --------------------- | -------------------- | ---------- | ---------------------------------------------------------------- |
@@ -38,11 +34,28 @@ import type { PConnProps } from '@pega/sdk-react';
 | `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 props forwarded to the child component                     |
+| `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.
+
+**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.
+
+**Main Component Logic** (defined as an arrow function, not a plain function declaration) — steps in order:
+
+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`.
+
+**Export:** wrap the component in a memoization wrapper with a custom comparison function (see "Re-render optimization" below).
+
 ## Behavioral Contract
 
 ### User ID extraction
@@ -54,7 +67,7 @@ import type { PConnProps } from '@pega/sdk-react';
 - `dropDownDataSource` (array): populated when `displayAs === 'Drop-down list'`
 - `userName` (string): resolved display name for formatted text mode
 
-### Mount effect: `useEffect([displayAs, readOnly, showAsFormattedText, value])`
+### Mount effect: lifecycle effect watching `[displayAs, readOnly, showAsFormattedText, value]`
 
 **Case 1: `userId && readOnly && showAsFormattedText`**
 
@@ -71,33 +84,13 @@ import type { PConnProps } from '@pega/sdk-react';
 
 ### Rendering decision tree
 
-```
-if displayMode === 'DISPLAY_ONLY' → FieldValueList(userName || '')
-if displayMode === 'STACKED_LARGE_VAL' → FieldValueList(userName || '', variant='stacked')
-if readOnly && showAsFormattedText && userId → formatted text label+body
-else if displayAs === 'Search box' → AutoComplete component
-else if displayAs === 'Drop-down list' → Dropdown component
-```
+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'`)
 
-Render `AutoComplete` with hardcoded columns for operator search:
-
-```typescript
-columns = [
-  { value: 'pyUserName', display: 'true', useForSearch: true, primary: 'true' },
-  {
-    value: 'pyUserIdentifier',
-    setProperty: 'Associated property',
-    key: 'true',
-    display: 'true',
-    secondary: 'true',
-    useForSearch: 'true',
-  },
-];
-```
+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'`).
 
-Props: `datasource={OPERATORS_DP}`, `listType='datapage'`, `value={userId}`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
+Inputs: `datasource` set to `OPERATORS_DP`, `listType='datapage'`, `value` set to `userId`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
 
 ### Subsection: Dropdown mode (`displayAs === 'Drop-down list'`)
 
@@ -106,33 +99,15 @@ Render `Dropdown` with:
 - `datasource={dropDownDataSource}` (fetched user list)
 - `listType='associated'`
 - `value={userId}`
-- Plus same field props as above
+- Plus same field inputs as above
 
 ### Subsection: Formatted text read-only (`readOnly && showAsFormattedText && userId`)
 
-Render a label + name display:
-
-```html
-<div>
-  <caption-text>{label}</caption-text>
-  <body-text>{userName}</body-text>
-</div>
-```
+Render a small wrapper containing a caption-style text element showing `label`, followed by a body-style text element showing `userName`.
 
 ### Re-render optimization
 
-Export with `memo` using custom comparison `comparisonFn`:
-
-```typescript
-const comparisonFn = (prevProps, nextProps) =>
-  getUserId(prevProps.value) === getUserId(nextProps.value) &&
-  prevProps.validatemessage === nextProps.validatemessage &&
-  prevProps.required === nextProps.required &&
-  prevProps.disabled === nextProps.disabled &&
-  prevProps.readOnly === nextProps.readOnly;
-```
-
-`export default memo(UserReference, comparisonFn)`
+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`.
 
 ## Display Mode Rendering
 
@@ -157,18 +132,7 @@ The visual appearance is determined by the child component rendered:
 | Name     | Body text (normal size)                                   |
 | Spacing  | Standard form field spacing                               |
 
-**CSS-only for formatted text:**
-
-```css
-.user-reference-label {
-  font-size: 0.75rem;
-  color: rgba(0, 0, 0, 0.6);
-  margin-bottom: 4px;
-}
-.user-reference-name {
-  font-size: 1rem;
-}
-```
+**Visual-only styling notes for formatted text:** The label is rendered in caption-size text (0.75rem) with a muted secondary color and a small bottom margin (4px) separating it from the name. The name is rendered in standard body text size (1rem).
 
 ## Edge Cases & Special Logic
 
@@ -180,11 +144,11 @@ The visual appearance is determined by the child component rendered:
 
 ## Dependencies
 
-- `memo` from React.
-- `getUserId`, `isUserNameAvailable` from `./UserReferenceUtils` (local utility).
-- `getComponentFromRegistry('AutoComplete')` — for search box mode.
-- `getComponentFromRegistry('Dropdown')` — for dropdown mode.
-- `getComponentFromRegistry('FieldValueList')` — for display modes.
+- 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.
@@ -193,11 +157,10 @@ The visual appearance is determined by the child component rendered:
 
 **UI control type:** User picker — delegates to AutoComplete or Dropdown for the actual input.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Mode                     | Underlying control                |
-| ------------------------ | --------------------------------- |
-| Search box               | AutoComplete (combobox/typeahead) |
-| Drop-down list           | Dropdown (select)                 |
-| Formatted text read-only | Label + text display              |
-| Display mode             | FieldValueList                    |
+- **Search box mode** → render the `AutoComplete` component with operator columns
+- **Dropdown mode** → render the `Dropdown` component with the fetched operator list
+- **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