@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.github/skills/field-skills/TextArea.md

@@ -1,96 +0,0 @@
-# Skill: TextArea
-
-Multi-line text input field that binds to a Pega case property.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Renders an editable multi-line text area. Used for long-form text input such as descriptions, notes, or comments. Similar to `TextInput` but allows multiple lines with configurable min/max rows.
-
-## Pega Metadata
-
-- **Pega Name:** `TextArea`
-- **Type / Subtype:** `Field` / `Text` (multi-line)
-- **Registration key:** `TextArea` (in `component-map.ts`)
-
-## Props (component-specific)
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the textarea |
-
-All other props come from `PConnFieldProps`. Import type as:
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-## Behavioral Contract
-
-1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.
-2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` 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 calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Read-only:** Set `readOnly` attribute on the textarea; use visually borderless ("standard") variant. Omit `onBlur` handler: `onBlur={!readOnly ? handleBlur : undefined}`.
-6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the textarea's `maxLength` attribute.
-7. **Row sizing:** Fixed at `minRows={5}` and `maxRows={5}` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
-
-## Display Mode Rendering
-
-- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
-- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
-- Both modes short-circuit before interactive rendering.
-
-## Read-Only Rendering
-
-Set `readOnly` on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The `minRows`/`maxRows` constraint is still applied in read-only.
-
-## Visual Specifications
-
-Derived from the reference component's MUI props:
-
-| Property | Standard (editable) | Read-only |
-|----------|---------------------|-----------|
-| Width | 100% | 100% |
-| Min rows | 5 | 5 |
-| Max rows | 5 (scrollable beyond) | 5 |
-| Border | 1px solid (outlined) | None (standard/flat) |
-| Border radius | 4px | — |
-| Label | Floating label | Floating label |
-| Helper text | Below textarea | Below textarea |
-| Error state | Red border + red helper text | — |
-| Resize | Vertical resize handle (browser default) | Same |
-| Font size | 0.875rem | 0.875rem |
-| Padding | 8px 14px | — |
-
-**CSS-only implementation notes:**
-- `textarea { min-height: calc(5 * 1.4375em + 16px); max-height: calc(5 * 1.4375em + 16px); overflow-y: auto; resize: vertical; }`
-- Error: `border-color: #d32f2f`
-- Read-only: `border: none; background: transparent;`
-
-## Edge Cases & Special Logic
-
-- Unlike `TextInput`, do NOT delegate to `TextInput` in read-only mode — render the textarea directly with `readOnly` set, so the multi-line appearance is preserved.
-- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
-
-## Dependencies
-
-- `handleEvent` from `../../helpers/event-utils`
-- `getComponentFromRegistry('FieldValueList')` for display modes
-- No third-party UI libraries required
-
-## Design System Mapping
-
-**UI control type:** Multi-line text input (`<textarea>`).
-
-Listed design systems are examples only.
-
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | `<textarea rows="5">` with floating label |
-| MUI | `<TextField multiline minRows={5} maxRows={5} />` |
-| Ant Design | `<Input.TextArea rows={5} />` |
-| Chakra UI | `<Textarea />` |
-| Shadcn/ui | `<Textarea />` |

package/templates/react-sdk-reference/.github/skills/field-skills/TextContent.md

@@ -1,101 +0,0 @@
-# Skill: TextContent
-
-Static text display component that renders formatted text content (paragraph or heading). Non-interactive — no form binding.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Displays static, read-only text content. Used to embed headings or descriptive paragraph text within forms or views. Not an input field — does NOT bind to a case property value and does NOT use `PConnFieldProps`. It renders purely based on static configuration props.
-
-## Pega Metadata
-
-- **Pega Name:** `TextContent`
-- **Type / Subtype:** `Field` / `Text`
-- **Registration key:** `TextContent` (in `component-map.ts`)
-
-## Props (component-specific)
-
-Extends `PConnProps` (NOT `PConnFieldProps` — there is no form value binding):
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-
-interface TextContentProps extends PConnProps {
-  content: string;
-  displayAs: 'Paragraph' | 'Heading 1' | 'Heading 2' | 'Heading 3' | 'Heading 4';
-}
-```
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `content` | `string` | The text string to render |
-| `displayAs` | `'Paragraph' \| 'Heading 1' \| 'Heading 2' \| 'Heading 3' \| 'Heading 4'` | How to render the text — maps to typography level |
-
-## Behavioral Contract
-
-1. **No state, no effects** — purely presentational. Render `content` using the appropriate typography element for `displayAs`.
-2. **Mapping:** 
-   - `'Paragraph'` → `<p>` / body text
-   - `'Heading 1'` → `<h1>`
-   - `'Heading 2'` → `<h2>`
-   - `'Heading 3'` → `<h3>`
-   - `'Heading 4'` → `<h4>`
-3. **Fallthrough:** Log an error for unrecognized `displayAs` values and render nothing (or a default fallback).
-
-## Display Mode Rendering
-
-Not applicable — this component is display-only by nature. It does not accept a `displayMode` prop.
-
-## Read-Only Rendering
-
-Always read-only — there is no editable state.
-
-## Visual Specifications
-
-Derived from standard HTML typography:
-
-| `displayAs` | Element | Font size | Font weight |
-|-------------|---------|-----------|-------------|
-| `Paragraph` | `<p>` / `body1` | 1rem (16px) | 400 |
-| `Heading 1` | `<h1>` | 2.5rem | 300 |
-| `Heading 2` | `<h2>` | 2rem | 300 |
-| `Heading 3` | `<h3>` | 1.75rem | 400 |
-| `Heading 4` | `<h4>` | 1.5rem | 400 |
-
-Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element.
-
-**CSS-only implementation notes:**
-```css
-.text-content-h1 { font-size: 2.5rem; font-weight: 300; }
-.text-content-h2 { font-size: 2rem; font-weight: 300; }
-.text-content-h3 { font-size: 1.75rem; font-weight: 400; }
-.text-content-h4 { font-size: 1.5rem; font-weight: 400; }
-.text-content-body { font-size: 1rem; font-weight: 400; }
-```
-
-## Edge Cases & Special Logic
-
-- Unrecognized `displayAs` values should trigger a `console.error` and fall back to body text.
-- No `handleEvent`, no store interaction, no `useEffect`.
-
-## Dependencies
-
-- No event utilities needed
-- No `FieldValueList` needed
-- Only a typography rendering element
-
-## Design System Mapping
-
-**UI control type:** Static typography / text block.
-
-Listed design systems are examples only.
-
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | Native `<h1>`–`<h4>` or `<p>` |
-| MUI | `<Typography variant='h1' \| 'h2' \| 'h3' \| 'h4' \| 'body1'>` |
-| Ant Design | `<Typography.Title level={1-4}>` or `<Typography.Text>` |
-| Chakra UI | `<Heading as='h1'-'h4'>` or `<Text>` |

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

@@ -1,104 +0,0 @@
-# Skill: TextInput
-
-Single-line text input field that binds to a Pega case property.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, 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 `component-map.ts`)
-
-## Props (component-specific)
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the input |
-
-All other props come from `PConnFieldProps`. Import type as:
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-## Behavioral Contract
-
-1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `value` prop (`''` default).
-2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` 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 calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Read-only:** Render input with `readOnly` attribute set; use a visually borderless ("standard") variant. Do NOT skip the blur handler when readOnly — simply omit it (`onBlur={!readOnly ? handleBlur : undefined}`).
-6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the underlying input's `maxLength` attribute.
-7. **testId:** Pass as `data-test-id` attribute on the underlying `<input>` element.
-
-## Display Mode Rendering
-
-- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />` — display raw string value, no formatting.
-- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
-- Both modes use `value` prop directly (not local state).
-- Both modes short-circuit before any interactive rendering.
-
-## Read-Only Rendering
-
-Set the `readOnly` attribute on the underlying input element. Use a visually flat/borderless style (no border box). The editable `outlined` variant switches to a `standard` (no outline) variant when read-only.
-
-## Visual Specifications
-
-Derived from the reference component's MUI props and styles:
-
-| Property | Standard (editable) | Read-only |
-|----------|---------------------|-----------|
-| Width | 100% of container | 100% of container |
-| Height / size | Small (`height ~40px`) | Small |
-| Border | 1px solid (outlined) | None (standard variant) |
-| 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 `value` prop is `undefined`, default to `''` to keep the input controlled.
-- If `readOnly` is true, the `onBlur` 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
-
-- `handleEvent` from `../../helpers/event-utils` — for committing value to store.
-- `getComponentFromRegistry('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 (`<input type="text">`).
-
-Listed design systems are examples only.
-
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | `<input type="text">` with floating label pattern |
-| MUI | `<TextField variant='outlined' size='small' fullWidth />` |
-| Ant Design | `<Input />` |
-| Chakra UI | `<Input />` |
-| Shadcn/ui | `<Input />` |
-
-When implementing in a specific design system, map the following behaviors:
-- `error={status === 'error'}` → error/danger variant
-- `helperText` → helper/description slot below the input
-- `label` → field label (floating or static depending on design system)
-- `disabled` → disabled prop
-- `required` → required/asterisk indicator

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

@@ -1,88 +0,0 @@
-# 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, props interface, 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 `minutesStep={5}` for the picker. Delegates read-only rendering to `TextInput`.
-
-## Pega Metadata
-
-- **Pega Name:** `Time`
-- **Type / Subtype:** `Field` / `Time`
-- **Registration key:** `Time` (in `component-map.ts`)
-
-## Props (component-specific)
-
-No props beyond `PConnFieldProps`. Import type as:
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-## 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. Use the date library: `dayjs().hour(hours).minute(minutes)`.
-3. **Local state:** No explicit local state for the time value — the picker's controlled `value` is derived from `props.value` directly on each render.
-4. **On change:**
-   - If date is valid: `theValue = date.format('HH:mm:ss')`, else `theValue = null`.
-   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, theValue)`.
-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`: `return <TextInput {...props} />`.
-
-## Display Mode Rendering
-
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw time string, no extra formatting.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
-
-## Read-Only Rendering
-
-Delegate to `TextInput`: `return <TextInput {...props} />`.
-
-## 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 `Object.keys(value).length === 0`, set `timeValue = null` — do NOT try to parse an empty object.
-- **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 `date.isValid()` is false (user clears the time), commit `null`.
-
-## Dependencies
-
-- Date manipulation library (e.g., `dayjs`) — for time parsing and `format('HH:mm:ss')`.
-- Time picker UI component (e.g., `@mui/x-date-pickers/TimePicker`).
-- `handleEvent` from `../../helpers/event-utils`.
-- `getComponentFromRegistry('TextInput')` for read-only.
-- `getComponentFromRegistry('FieldValueList')` for display modes.
-
-## Design System Mapping
-
-**UI control type:** Time picker (clock popup or input with am/pm selector).
-
-Listed design systems are examples only.
-
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | `<input type="time">` (24h, no am/pm) |
-| MUI | `<TimePicker minutesStep={5} format='hh:mm a' />` |
-| Ant Design | `<TimePicker format="hh:mm a" minuteStep={5} />` |
-| Chakra UI | Third-party time picker |

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

@@ -1,85 +0,0 @@
-# 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, props interface, 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` (mapped to `URLComponent` in `component-map.ts` — the component export is named `URLComponent` to avoid conflicts with the global `URL` API)
-
-## Props (component-specific)
-
-No props beyond `PConnFieldProps`. Import type as:
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-> **Important naming note:** Export the component as `URLComponent` (not `URL`) to avoid conflicts with the browser's built-in `URL` global. Register it in `component-map.ts` as `URL: URLComponent`.
-
-## Behavioral Contract
-
-1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).
-2. **Sync from store:** `useEffect` watching `value` → `setInputValue(value)`.
-3. **On change:** Update local state only.
-4. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Input type:** Use `type='url'` for browser-native URL format hint/validation.
-6. **Read-only:** Delegate entirely to `TextInput`: `return <TextInput {...props} />`.
-
-## Display Mode Rendering
-
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw URL string.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
-
-## Read-Only Rendering
-
-Delegate to `TextInput`: `return <TextInput {...props} />`.
-
-## 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 `type='url'`.
-
-## Edge Cases & Special Logic
-
-- The component is named `URLComponent` internally to avoid shadowing the global `URL` constructor. Register under the key `URL` in the component map.
-- `type='url'` triggers browser tooltip/validation but Pega validation is the authoritative source.
-- `onBlur` is only wired when `!readOnly`.
-
-## Dependencies
-
-- `handleEvent` from `../../helpers/event-utils`
-- `getComponentFromRegistry('TextInput')` — for read-only delegation
-- `getComponentFromRegistry('FieldValueList')` — for display modes
-
-## Design System Mapping
-
-**UI control type:** Single-line URL text input.
-
-Listed design systems are examples only.
-
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | `<input type="url">` |
-| MUI | `<TextField type='url' />` |
-| Ant Design | `<Input type="url" />` |
-| Chakra UI | `<Input type="url" />` |

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

@@ -1,180 +0,0 @@
-# Skill: UserReference
-
-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.
-
----
-
-## 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.
-
-## Pega Metadata
-
-- **Pega Name:** `UserReference`
-- **Type / Subtype:** `Field` / `Text-UserReference`
-- **Registration key:** `UserReference` (in `component-map.ts`)
-
-## Props (component-specific)
-
-> Extends `PConnProps` (NOT `PConnFieldProps` — field-specific props are defined manually):
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-```
-
-| 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 props forwarded to the child component |
-| `hideLabel` | `boolean` (optional) | `false` | |
-| `variant` | `string` (optional) | `'inline'` | Layout variant |
-| `onChange` | `any` (optional) | — | Change handler (passed through to child) |
-
-## 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).
-
-### State
-
-- `dropDownDataSource` (array): populated when `displayAs === 'Drop-down list'`
-- `userName` (string): resolved display name for formatted text mode
-
-### Mount effect: `useEffect([displayAs, readOnly, showAsFormattedText, value])`
-
-**Case 1: `userId && readOnly && showAsFormattedText`**
-- If `isUserNameAvailable(value)`: `setUserName(value.userName)` — username already in value object
-- Else: call `PCore.getUserApi().getOperatorDetails(userId)` and extract `pyUserName` from response
-
-**Case 2: `displayAs === 'Drop-down list'`**
-- 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.
-
-### 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
-```
-
-### 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' }
-]
-```
-Props: `datasource={OPERATORS_DP}`, `listType='datapage'`, `value={userId}`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
-
-### Subsection: Dropdown mode (`displayAs === 'Drop-down list'`)
-
-Render `Dropdown` with:
-- `datasource={dropDownDataSource}` (fetched user list)
-- `listType='associated'`
-- `value={userId}`
-- Plus same field props 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>
-```
-
-### 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)`
-
-## Display Mode Rendering
-
-Uses resolved `userName` (not raw `value`):
-- **`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.
-
-## Visual Specifications
-
-The visual appearance is determined by the child component rendered:
-- **Search box**: Same as `AutoComplete` — combobox input with outlined border, floating label
-- **Dropdown**: Same as `Dropdown` — select field with outlined border, floating label
-- **Formatted text read-only**:
-
-| Property | Value |
-|----------|-------|
-| Label | Caption-size text (small, secondary color) above the name |
-| 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; }
-```
-
-## 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.
-
-## 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.
-- `PCore.getUserApi().getOperatorDetails()` — for async user name resolution.
-- `PCore.getRestClient().invokeRestApi('getListData', ...)` — for dropdown data source.
-- `PCore.getEnvironmentInfo().getDefaultOperatorDP()` — for operators data page name.
-
-## Design System Mapping
-
-**UI control type:** User picker — delegates to AutoComplete or Dropdown for the actual input.
-
-Listed design systems are examples only.
-
-| Mode | Underlying control |
-|------|--------------------|
-| Search box | AutoComplete (combobox/typeahead) |
-| Drop-down list | Dropdown (select) |
-| Formatted text read-only | Label + text display |
-| Display mode | FieldValueList |