@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/DetailsFields.mdrules

@@ -0,0 +1,149 @@
+---
+description: DSE component skill: DetailsFields
+alwaysApply: false
+---
+
+# Skill: DetailsFields
+
+Read-only field display component that receives an array of PConnect-aware field objects and renders each as a label/value pair. Delegates value rendering to `PConnectComponent` in DISPLAY_ONLY mode.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a vertical list of read-only field name/value pairs for a details/summary panel. Each field is a PConnect-aware object. The component extracts type, label, and view config from each field's PConnect, forces the view into `readOnly + DISPLAY_ONLY` mode, and delegates rendering to `PConnectComponent`.
+
+Supports three item layouts:
+- **Reference type:** Renders the value directly (no label/value grid wrapper).
+- **React element value:** Renders value in a single full-width cell (no label).
+- **Label + value pair:** Renders label in a 6-col cell and value in a 6-col cell.
+
+## Pega Metadata
+
+- **Pega Name:** `DetailsFields`
+- **Registration key:** `DetailsFields` (in `component-map.ts`)
+- **Does NOT use `getPConnect` on the component itself** — iterates `fields[]` each of which has `.getPConnect()`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `fields` | `any[]` | Yes | Array of PConnect-aware field objects. Each must have `.getPConnect()` method |
+
+## Behavioral Contract
+
+### 1. Field Iteration and PConnect Setup
+
+For each field in `fields`:
+1. Call `field.getPConnect()` to get `thePConn`.
+2. Get `theCompType = thePConn.getComponentName().toLowerCase()`.
+3. Get `label = thePConn.getConfigProps().label`.
+4. Call `configObj = thePConn.getReferencedView()` — get the referenced view config object.
+5. Set `configObj.config.readOnly = true` and `configObj.config.displayMode = 'DISPLAY_ONLY'` — forces display-only rendering.
+6. For `reference` type: override label with `thePConn.getInheritedProps().label`.
+7. Render the value using `createElement(PConnectComponent, thePConn.getReferencedViewPConnect())`.
+8. Push `{ type: theCompType, label, value: <React.Fragment key={index}>{renderedValue}</React.Fragment> }` into the field components array.
+
+### 2. Item Layout (per field component)
+
+Choose the layout based on the field:
+
+| Condition | Layout |
+|-----------|--------|
+| `type === 'reference'` | Render `field.value` directly with no wrapper |
+| `isValidElement(field.value)` | Single 12-col cell containing `field.value` (no label) |
+| Default (string/primitive value) | 6-col label cell + 6-col value cell |
+
+### 3. Label/Value Grid Row
+
+- **Row wrapper:** `<Grid container spacing={1} style={{ padding: '4px 0px' }}>`
+- **Label cell:** `<Grid size={{ xs: 6 }}>` containing `<Typography variant='body2' component='span' className='fieldLabel'>{field.label}</Typography>`
+- **Value cell:** `<Grid size={{ xs: 6 }}>` containing `<Typography variant='body2' component='span' className='fieldValue'>{formattedValue}</Typography>`
+
+### 4. Value Formatting
+
+- For `date` type: call `format(value, 'date')` before display.
+- For all others: use value as-is.
+- If formatted value is `undefined` or `''`, display `'---'` instead.
+
+### 5. React element detection
+
+Use `isValidElement(field.value)` — if true, render full-width (12 cols) without label.
+
+## Visual Specifications
+
+Derived from `DetailsFields.tsx` makeStyles:
+
+### Label
+
+| Property | Value |
+|----------|-------|
+| Display | block |
+| Font weight | 400 |
+| Color | `theme.palette.text.secondary` |
+| Typography | `body2` (≈ 0.875rem / 14px) |
+
+### Value
+
+| Property | Value |
+|----------|-------|
+| Font weight | 400 |
+| Color | `theme.palette.text.primary` |
+| Typography | `body2` (≈ 0.875rem / 14px) |
+
+### Row Padding
+
+| Property | Value |
+|----------|-------|
+| Row style | `padding: 4px 0px` |
+
+**CSS-only implementation notes:**
+- Each row: `display: grid; grid-template-columns: 1fr 1fr; padding: 4px 0; gap: 8px`.
+- Label: `font-size: 0.875rem; font-weight: 400; color: var(--text-secondary); display: block`.
+- Value: `font-size: 0.875rem; font-weight: 400; color: var(--text-primary)`.
+- For a React element value (full-width): render in a single column spanning full width.
+- For a reference type: render the component directly with no wrapping grid.
+
+## Edge Cases & Special Logic
+
+- `fields` defaults to `[]` — guard against null/undefined.
+- Reference fields bypass the label/value layout entirely — their rendered output fills the full row.
+- React element values (e.g., from child components) are detected with `isValidElement` and rendered full-width without a label cell.
+- The `configObj` mutation (`readOnly = true`, `displayMode = 'DISPLAY_ONLY'`) happens on the object returned by `getReferencedView()` — this is intentional side-effectful configuration.
+- `format(value, 'date')` is only called for `date` type — all other types pass through raw.
+
+## Dependencies
+
+- `createElement`, `isValidElement` from `react`
+- `PConnectComponent` from `@pega/sdk-react` — used to render each field in DISPLAY_ONLY mode
+- `format` from `../../helpers/formatters` — for date formatting
+- Each `field` in `fields[]` must support `.getPConnect()` returning a PConnect object with:
+  - `.getComponentName()` → string
+  - `.getConfigProps()` → `{ label: string }`
+  - `.getReferencedView()` → mutable config object
+  - `.getReferencedViewPConnect()` → props object for `PConnectComponent`
+  - `.getInheritedProps()` → `{ label?: string }` (for reference type)
+
+## Design System Mapping
+
+**UI control type:** Vertical list of read-only label/value field pairs with PConnect delegation.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS grid 2-column rows per field pair |
+| MUI | `<Grid container spacing={1}>` per row with `<Typography>` label and value |
+| Ant Design | `<Descriptions layout='horizontal' column={1}>` with PConnect-rendered values |
+| Chakra UI | `<Grid templateColumns='1fr 1fr'>` rows with `<Text>` label/value |
+| Shadcn/ui | `<div class='grid grid-cols-2'>` rows |
+
+When implementing in a specific design system, map the following:
+- Label → secondary muted text, `body2` size
+- Value → primary text, `body2` size
+- Row padding → `4px 0` vertical spacing between pairs
+- Full-width value (React element) → single column spanning full width
+- Reference type → render the child component without any label wrapper
+- Empty value → display `'---'`

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/FieldGroup.mdrules

@@ -0,0 +1,136 @@
+---
+description: DSE component skill: FieldGroup
+alwaysApply: false
+---
+
+# Skill: FieldGroup
+
+Collapsible or static container that groups related fields under an optional section header and instructions text.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a labeled section that wraps one or more field components. Supports optional:
+- **Section name** — rendered as a bold header above the fields.
+- **Collapsible behavior** — the name header becomes a toggle that shows/hides the fields.
+- **Instructions text** — rendered as HTML below the header and above the fields.
+
+Children are rendered inside a full-width inner container.
+
+## Pega Metadata
+
+- **Pega Name:** `FieldGroup`
+- **Registration key:** `FieldGroup` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives children via `PropsWithChildren`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode` | No | Field components to render inside the group |
+| `name` | `string` | No | Section heading displayed above the fields |
+| `collapsible` | `boolean` | No | If `true`, the header acts as a collapse/expand toggle. Default `false` |
+| `instructions` | `string` | No | HTML string of instruction text shown between header and fields |
+
+## Behavioral Contract
+
+1. **State:** Maintain a `collapsed` boolean in local state, initialized to `false` (expanded).
+2. **Name rendering:**
+   - If `name` is not provided, render no header.
+   - If `name` is provided and `collapsible` is `false`, render `<b>{name}</b>`.
+   - If `name` is provided and `collapsible` is `true`, wrap in a clickable `<span>` with:
+     - `id='field-group-header'`
+     - A directional arrow icon: **right arrow** when `collapsed === true`, **down arrow** when `collapsed === false`.
+     - The bold name text beside the arrow.
+     - Clicking the span toggles `collapsed`.
+3. **Instructions:** If `instructions` is provided AND is not the string `'none'`, render it with `dangerouslySetInnerHTML={{ __html: instructions }}`.
+4. **Children:** Render children inside a full-width div. If `collapsed` is `true`, do NOT render children (or instructions).
+5. **Header cursor:** When `collapsible` is `true`, the header span uses `cursor: pointer`. When `collapsible` is `false`, cursor is `auto`.
+6. **Layout:** All content is wrapped in a `Grid container` with `spacing={4}` and `justifyContent='space-between'`. The name row and children are inside a single inner `Grid` at full width.
+
+## Visual Specifications
+
+Derived from `FieldGroup.tsx` makeStyles:
+
+### Outer Container
+
+| Property | Value |
+|----------|-------|
+| Spacing | 4 units (≈ 32px in MUI default) |
+
+### Component Root Margins
+
+| Property | Value |
+|----------|-------|
+| Margin right | `theme.spacing(1)` (≈ 8px) |
+| Margin left | `theme.spacing(1)` |
+| Margin top | `theme.spacing(1)` |
+| Margin bottom | `theme.spacing(1)` |
+
+### Field Margin (name row)
+
+| Property | Value |
+|----------|-------|
+| Padding top | `theme.spacing(1)` |
+| Padding bottom | `theme.spacing(1)` |
+| Margin top | `theme.spacing(1)` |
+
+### Header Row (collapsible)
+
+| Property | Value |
+|----------|-------|
+| Display | flex |
+| Align items | center |
+| Gap | 5px |
+| Cursor | `pointer` (collapsible) or `auto` (non-collapsible) |
+
+### Instructions
+
+| Property | Value |
+|----------|-------|
+| Padding | `5px 0` |
+
+**CSS-only implementation notes:**
+- Outer wrapper: `margin: 8px`.
+- Name row: `padding: 8px 0; margin-top: 8px`.
+- Collapsible header: `display: flex; align-items: center; gap: 5px; cursor: pointer; user-select: none`.
+- Non-collapsible name: plain `<b>` with no wrapper.
+- Instructions: `padding: 5px 0`.
+- Arrow icons: use Unicode or inline SVG — collapsed → `▶` / `›`, expanded → `▼` / `⌄`.
+- Children wrapper: `width: 100%`.
+- When collapsed, use `display: none` or conditional rendering to hide children.
+
+## Edge Cases & Special Logic
+
+- If `collapsible` is `false` (default), the `collapsed` state is never changed — clicking the name does nothing.
+- `instructions` equal to the string `'none'` must NOT be rendered (skip entirely).
+- `instructions` is rendered as raw HTML — ensure the content is trusted (server-side).
+- If `name` is absent, render no header row, but still render instructions (if any) and children.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- Arrow icons: `KeyboardArrowRightIcon` / `KeyboardArrowDownIcon` from `@mui/icons-material` (MUI only) — use equivalent icons or Unicode characters in non-MUI implementations
+
+## Design System Mapping
+
+**UI control type:** Collapsible section container with label, instructions, and children.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<div>` with toggled `display: none` on children, `<b>` header |
+| MUI | Grid container with `KeyboardArrowRight/Down` icons for collapse toggle |
+| Ant Design | `<Collapse>` or `<Card>` with collapsible panels |
+| Chakra UI | `<Accordion>` or manual `<Box>` with toggle state |
+| Shadcn/ui | `<Collapsible>` + `<CollapsibleTrigger>` + `<CollapsibleContent>` |
+
+When implementing in a specific design system, map the following:
+- `collapsed` toggle → design system's collapse/expand state or controlled component
+- Arrow direction → visual indicator of expand/collapse state (chevron or arrow icon)
+- `instructions` HTML → design system's `dangerouslySetInnerHTML` or rich content slot
+- Full-width children → ensure children container spans the full group width

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/FieldGroupList.mdrules

@@ -0,0 +1,116 @@
+---
+description: DSE component skill: FieldGroupList
+alwaysApply: false
+---
+
+# Skill: FieldGroupList
+
+Repeating list of named field groups, each with its own children. Supports per-item delete and a global "+Add" link at the bottom.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a vertical list of field group items. Each item has a bold name header, optional delete button (top-right), and rendered children (the group's fields). An optional "+Add" link appears at the bottom when adding is allowed. A horizontal divider separates items when `onAdd` is provided.
+
+## Pega Metadata
+
+- **Pega Name:** `FieldGroupList`
+- **Registration key:** `FieldGroupList` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `items` | `Array<{ name: string; id: string; children: ReactNode }>` | Yes | List of field group items to render |
+| `onDelete` | `(id: string) => void` | No | Called with the item's `id` when the delete button is clicked. If not provided, no delete button is shown |
+| `onAdd` | `() => void` | No | Called when the "+Add" link is clicked. If not provided, no add link or dividers are shown |
+
+## Behavioral Contract
+
+1. Render a `Grid container` with `spacing={4}` and `justifyContent='space-between'` as the outer wrapper.
+2. Inside, render a full-width inner Grid with `spacing={1}`.
+3. For **each item** in `props.items`:
+   - Render a full-width `Grid` keyed by `item.name`.
+   - Render `<b>{item.name}</b>` as the item header.
+   - If `onDelete` is provided, render a delete button:
+     - Floated right.
+     - `type='button'`, `id={'delete-row-' + item.id}`, `aria-label='Delete Row'`.
+     - Button class: `psdk-utility-button`.
+     - On click: call `onDelete(item.id)`.
+     - Button contains an `<img>` with the trash icon loaded via `Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl())`.
+     - Image class: `psdk-utility-card-action-svg-icon`.
+   - Render `{item.children}`.
+   - Render `<br />`.
+   - If `onAdd` is provided: render `<Divider />`, then `<br />`.
+4. After all items, if `onAdd` is provided, render a `<Link>` (or `<a>`) with text `'+Add'`, `cursor: pointer`, and `onClick={onAdd}`.
+
+## Visual Specifications
+
+Derived from `FieldGroupList.tsx`:
+
+### Outer Layout
+
+| Property | Value |
+|----------|-------|
+| Grid container spacing | 4 (≈ 32px) |
+
+### Delete Button
+
+| Property | Value |
+|----------|-------|
+| Float | right |
+| Style class | `psdk-utility-button` |
+| Icon source | `Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl())` |
+
+### "+Add" Link
+
+| Property | Value |
+|----------|-------|
+| Cursor | pointer |
+| Underline | hover |
+| Text | `'+Add'` |
+
+**CSS-only implementation notes:**
+- Outer wrapper: `display: flex; flex-direction: column; gap: 32px`.
+- Item wrapper: `display: flex; flex-direction: column; gap: 8px; width: 100%`.
+- Item header row: `display: flex; justify-content: space-between; align-items: center`.
+- Delete button: `float: right` (or use flexbox `justify-content: space-between` on the header row instead).
+- Delete icon: `width: 20px; height: 20px` SVG image of a trash/delete icon.
+- Divider: `border-top: 1px solid var(--divider-color); margin: 8px 0`.
+- "+Add" link: `cursor: pointer; text-decoration: underline; color: var(--app-primary-color)`.
+
+## Edge Cases & Special Logic
+
+- If `items` is empty, render only the "+Add" link (if `onAdd` is provided).
+- If neither `onDelete` nor `onAdd` is provided, the list is read-only (no interactive elements).
+- The trash icon is loaded dynamically via `Utils.getImageSrc` — if this utility is unavailable, fall back to a standard `🗑` character or an SVG trash icon.
+- The delete button must use `type='button'` to prevent form submission.
+
+## Dependencies
+
+- `Utils` from `../../helpers/utils` — for `getImageSrc` and `getSDKStaticConentUrl` (used only for the trash icon)
+- No Pega SDK `getPConnect` imports required
+
+## Design System Mapping
+
+**UI control type:** Repeating list of named groups with optional delete and add actions.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Flex column layout with `<hr>` divider and `<button>` delete |
+| MUI | `<Grid container>` items with `<Divider>` and `<Link>` for "+Add" |
+| Ant Design | `<List>` items with `<Divider>` and `<Button type='link'>` for "+Add" |
+| Chakra UI | `<VStack>` with `<Divider>` and `<Button variant='link'>` |
+| Shadcn/ui | `<div>` flex column with `<Separator>` and a link button |
+
+When implementing in a specific design system, map the following:
+- Delete button → icon button or `danger` variant button placed at the item top-right
+- Divider between items → `<Divider>` / `<hr>` (only when `onAdd` is present)
+- "+Add" link → a text link / `Button variant='link'` that calls `onAdd`
+- Trash icon → design system's delete icon or an SVG

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/FieldValueList.mdrules

@@ -0,0 +1,120 @@
+---
+description: DSE component skill: FieldValueList
+alwaysApply: false
+---
+
+# Skill: FieldValueList
+
+Single field-value pair display component. Renders a label and value in either an inline (side-by-side) or stacked layout. Also used as a display mode renderer by field components (e.g., `TextInput`, `Dropdown`, etc.).
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a single name/value pair in a compact read-only layout. Supports two layout variants:
+- **Inline:** Label and value are side by side (label 4/12 cols, value 8/12 cols).
+- **Stacked:** Label is on top, value is larger below (both 12/12 cols).
+
+When no name is provided, only the value is rendered at full width. Used directly as a display widget and delegated to by field components for their `DISPLAY_ONLY` and `STACKED_LARGE_VAL` display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `FieldValueList`
+- **Registration key:** `FieldValueList` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | No | Field label. If omitted, only the value is rendered |
+| `value` | `any` | Yes | Field value to display |
+| `variant` | `string` | No | Layout: `'inline'` (default) or `'stacked'` |
+| `isHtml` | `boolean` | No | If `true`, render value as raw HTML (default `false`) |
+
+## Behavioral Contract
+
+1. **Empty value fallback:** If `value` is `undefined` or an empty string (`''`), display `'---'` instead.
+2. **No-name case:** If `name` is not provided, render only the value at full width (12 columns) regardless of `variant`.
+3. **Inline variant** (default — `variant !== 'stacked'`):
+   - Label column: 4 of 12 columns.
+   - Value column: 8 of 12 columns (or 12 if no name).
+   - Label: secondary text color, `body2` typography, `fontWeight: 400`.
+   - Value: primary text color, `body2` typography.
+4. **Stacked variant** (`variant === 'stacked'`):
+   - Label column: 12 of 12, `paddingBottom: 0` (label sits tight above value).
+   - Value column: 12 of 12, `paddingTop: 0` (value sits tight below label).
+   - Label: secondary text color, `body2` typography, `fontWeight: 400`.
+   - Value: primary text color, **`h6` typography** (larger / more prominent than inline).
+5. **HTML rendering:** If `isHtml` is `true`, wrap value in a `<div dangerouslySetInnerHTML={{ __html: formattedValue }}>`. The formatted value (with `'---'` fallback) is passed to `__html`.
+6. **Layout wrapper:** Render everything inside a container row with space-between justification and consistent spacing.
+
+## Visual Specifications
+
+Derived from `FieldValueList.tsx` makeStyles:
+
+### Label
+
+| Property | Value |
+|----------|-------|
+| Font weight | 400 |
+| Color | `theme.palette.text.secondary` (muted/secondary text) |
+| Typography | `body2` (≈ 0.875rem / 14px) |
+
+### Value
+
+| Property | Value |
+|----------|-------|
+| Color | `theme.palette.text.primary` (default text) |
+| Typography (inline) | `body2` (≈ 0.875rem / 14px) |
+| Typography (stacked) | `h6` (≈ 1.25rem / 20px, weight 500) |
+
+### Padding Adjustments (stacked only)
+
+| Property | Value |
+|----------|-------|
+| Label bottom padding | `0 !important` |
+| Value top padding | `0 !important` |
+
+**CSS-only implementation notes:**
+- Root row: `display: flex; justify-content: space-between; align-items: baseline; gap: 1rem`.
+- **Inline label:** `flex: 0 0 33%; font-weight: 400; font-size: 0.875rem; color: var(--text-secondary)`.
+- **Inline value:** `flex: 1; font-size: 0.875rem; color: var(--text-primary)`.
+- **Stacked:** `display: flex; flex-direction: column; gap: 0`.
+- **Stacked label:** `font-weight: 400; font-size: 0.875rem; color: var(--text-secondary); margin-bottom: 0`.
+- **Stacked value:** `font-size: 1.25rem; font-weight: 500; color: var(--text-primary); margin-top: 0`.
+
+## Edge Cases & Special Logic
+
+- `value` can be any type (string, number, boolean, React element). Render it as-is unless it's empty/undefined.
+- When `isHtml` is `true`, set the raw HTML from the formatted value — do NOT sanitize (the caller is responsible). Ensure value is a string before passing to `dangerouslySetInnerHTML`.
+- When `variant` is `'stacked'` and `name` is absent, render value at 12 cols with `h6` typography.
+- When `variant` is `'inline'` and `name` is absent, render value at 12 cols with `body2` typography.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Read-only field label/value display pair.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<div class='field-value-inline'>` or `<div class='field-value-stacked'>` with CSS |
+| MUI | `<Grid container>` with `<Typography>` for label and value |
+| Ant Design | `<Descriptions>` item, or `<Typography.Text type='secondary'>` + `<Typography.Text>` |
+| Chakra UI | `<Stack direction='row'>` (inline) or `<Stack spacing={0}>` (stacked) |
+| Shadcn/ui | Custom label/value pair with Tailwind flex utilities |
+
+When implementing in a specific design system, map the following:
+- Label → secondary/muted text style
+- Value inline → same size as label
+- Value stacked → larger typography (h6 equivalent)
+- Empty value → always display `'---'` (never show blank)
+- `isHtml={true}` → design system's `dangerouslySetInnerHTML` or `innerHTML` equivalent

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/Operator.mdrules

@@ -0,0 +1,154 @@
+---
+description: DSE component skill: Operator
+alwaysApply: false
+---
+
+# Skill: Operator
+
+Read-only display of a Pega case operator (creator or updater). Shows the operator's name and relative timestamp. On click, fetches full operator details from Pega and displays them in a popover.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a clickable read-only field displaying a case operator's name and the relative time of their action (created/updated). Clicking the field triggers an async fetch of the operator's profile details (position, organization, reports-to, telephone, email) and shows them in a popover panel.
+
+## Pega Metadata
+
+- **Pega Name:** `Operator`
+- **Registration key:** `Operator` (in `component-map.ts`)
+- **Extends `PConnProps`** — but does NOT call `getPConnect()`. Props are all passed directly.
+
+## Props
+
+The component interface extends `PConnProps` but all rendering data is passed as explicit props:
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | The field label used to identify which operator to display. Must be `'create operator'` or `'update operator'` (case-insensitive). |
+| `displayLabel` | `any` | No | Alternative label (used if `label` doesn't match). Also compared case-insensitively. |
+| `createDateTime` | `string` | Yes | ISO datetime string of when the case was created |
+| `createLabel` | `string` | Yes | Display label for the create operator field |
+| `createOperator` | `{ userName: string; userId: string }` | Yes | Creator's name and ID |
+| `updateDateTime` | `string` | Yes | ISO datetime string of last update |
+| `updateLabel` | `string` | Yes | Display label for the update operator field |
+| `updateOperator` | `{ userName: string; userId: string }` | Yes | Updater's name and ID |
+
+## Behavioral Contract
+
+### 1. Operator Selection
+
+Determine which operator to display based on `label.toLowerCase()` or `displayLabel?.toLowerCase()`:
+- If either is `'create operator'`:
+  - `caseOpLabel = createLabel`
+  - `caseOpName = createOperator.userName`
+  - `caseOpId = createOperator.userId`
+  - `caseTime = createDateTime`
+- If either is `'update operator'`:
+  - `caseOpLabel = updateLabel`
+  - `caseOpName = updateOperator.userName`
+  - `caseOpId = updateOperator.userId`
+  - `caseTime = updateDateTime`
+- Otherwise: `caseOpLabel = '---'`, `caseOpName = '---'`, `caseOpId = ''`, `caseTime = ''`.
+
+### 2. Main Display
+
+Render a read-only TextField (standard variant, no underline, pointer cursor) with:
+- `defaultValue={caseOpName}`
+- `label={caseOpLabel}`
+- `onClick={showOperatorDetails}`
+- `readOnly: true`, `disableUnderline: true`, `cursor: 'pointer'`
+
+Below the TextField, render the relative time: `Utils.generateDateTime(caseTime, 'DateTime-Since')`.
+
+### 3. Popover on Click (`showOperatorDetails`)
+
+When the TextField is clicked:
+1. Call `PCore.getUserApi().getOperatorDetails(caseOpId)` — returns a Promise.
+2. Use `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` to localize field labels.
+3. On resolution, build a fields array with these entries (using `'---'` as fallback for missing values):
+   - Position (`pyPosition`)
+   - Organization (`pyOrganization`)
+   - Reports to (`pyReportToUserName`)
+   - Telephone (`pyTelephone`) — rendered as `<a href={'tel:' + value}>{value}</a>`
+   - Email address (`pyEmailAddress`) — rendered as `<a href={'mailto:' + value}>{value}</a>`
+4. If `res.data.pyOperatorInfo.pyUserName` is empty, use all `'---'` fallbacks.
+5. Set `popoverFields` state with the resolved fields.
+6. Set `popoverAnchorEl` to the clicked element to open the popover.
+
+### 4. Popover Layout
+
+The popover renders when `popoverAnchorEl` is set:
+- Anchor origin: `{ vertical: 'bottom', horizontal: 'center' }`
+- Transform origin: `{ vertical: 'top', horizontal: 'center' }`
+- Max width: `45ch`
+- Content: A `Grid container` with:
+  - `Typography h6` showing `caseOpName` at full width.
+  - One row per field: 6-col `Typography caption` (label) + 6-col `Typography subtitle2` (value).
+
+Closing the popover sets `popoverAnchorEl` to `null`.
+
+## Visual Specifications
+
+Derived from `Operator.tsx` makeStyles:
+
+### Root Container
+
+| Property | Value |
+|----------|-------|
+| Padding | `theme.spacing(1)` (≈ 8px) |
+| Margin | `theme.spacing(1)` |
+
+### Popover Container
+
+| Property | Value |
+|----------|-------|
+| Padding | `theme.spacing(1)` |
+| Margin | `theme.spacing(1)` |
+| Max width | 45ch |
+
+**CSS-only implementation notes:**
+- Main display: read-only text field with label above, value below, pointer cursor on the value element.
+- Time display: secondary muted text below the operator name (e.g., `font-size: 0.75rem; color: var(--text-secondary)`).
+- Popover: `position: absolute; background: var(--bg-paper); border: 1px solid var(--divider); border-radius: 4px; padding: 8px; max-width: 45ch; box-shadow: 0 4px 12px rgba(0,0,0,0.15)`.
+- Operator name in popover: `font-size: 1.25rem; font-weight: 500; margin-bottom: 8px`.
+- Detail rows: `display: grid; grid-template-columns: 1fr 1fr; gap: 4px; align-items: baseline`.
+- Detail label: `font-size: 0.75rem; color: var(--text-secondary)`.
+- Detail value: `font-size: 0.875rem; font-weight: 500`.
+- Close popover on outside click (use `onClose` / blur handler).
+
+## Edge Cases & Special Logic
+
+- If `caseOpId` is empty (label not recognized), do NOT call `getOperatorDetails` — the fetch would fail.
+- If the API response has no `pyOperatorInfo.pyUserName`, fall back to all `'---'` for field values (still open the popover).
+- `Utils.generateDateTime(caseTime, 'DateTime-Since')` handles empty `caseTime` gracefully.
+- State: `popoverFields` starts as empty array `[]`. Check `popoverFields.length === 0` and return `undefined` from `getPopoverGrid()` to render nothing before data loads.
+
+## Dependencies
+
+- `Utils` from `../../helpers/utils` — `Utils.generateDateTime` for relative time display
+- `PCore.getUserApi().getOperatorDetails(userId)` — global Pega runtime API for operator details
+- `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` — for localized field labels in the popover
+
+## Design System Mapping
+
+**UI control type:** Clickable read-only field with async popover detail panel.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<div>` with click handler, custom CSS popover/tooltip panel |
+| MUI | Read-only `<TextField>` + `<Popover>` with `<Grid>` detail rows |
+| Ant Design | `<Input readOnly>` + `<Popover>` with `<Descriptions>` |
+| Chakra UI | `<Input isReadOnly>` + `<Popover>` with custom content |
+| Shadcn/ui | `<Input readOnly>` + `<Popover>` + `<PopoverContent>` |
+
+When implementing in a specific design system, map the following:
+- `onClick` on read-only input → trigger async fetch + open popover
+- `PCore.getUserApi().getOperatorDetails()` → call this before showing the popover
+- Popover anchor → position relative to the clicked element
+- `Utils.generateDateTime(caseTime, 'DateTime-Since')` → relative time display (e.g., "2 hours ago")
+- Telephone/email in popover → clickable `<a href='tel:...'>` and `<a href='mailto:...'>` links