@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/CaseSummary.mdrules

@@ -0,0 +1,105 @@
+---
+description: Template component skill: CaseSummary
+alwaysApply: false
+---
+
+# Skill: CaseSummary
+
+Case summary template. Renders a summary panel with primary and secondary case fields, derived from either props or child region extraction.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Displays a case's key summary data in a structured summary panel. Primary fields are shown prominently; secondary fields are shown with labels. Data is sourced either directly from props or by extracting child regions. All field values are localized before display.
+
+## Pega Metadata
+
+- **Registration key:** `CaseSummary` (in `component-map.ts`)
+- **Category:** Page template — summary
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | No | Region children when fields come from PConnect metadata |
+| `arPrimaryFields` | `array` | No | Array of primary field objects (direct prop) |
+| `arSecondaryFields` | `array` | No | Array of secondary field objects (direct prop) |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Field Sourcing
+
+Two modes — prefer direct props if provided:
+
+**Mode A — Direct props:**
+- `arPrimaryFields` and `arSecondaryFields` are passed directly.
+- Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` to localize values.
+
+**Mode B — Child extraction:**
+- Extract primary and secondary regions from `children` by type/name matching.
+- Primary region: first region child (or `type === 'Region' && name === 'Primary'`).
+- Secondary region: second region child (or `type === 'Region' && name === 'Secondary'`).
+- Build field arrays from the extracted region children metadata.
+- Then call `prepareCaseSummaryData(...)` as in Mode A.
+
+### `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)`
+
+Helper that:
+1. Iterates each field in both arrays.
+2. Localizes the field value via `PCore.getLocaleUtils().getLocaleValue(value, classID, value)`.
+3. Returns `{ arPrimaryFields: localizedPrimary, arSecondaryFields: localizedSecondary }`.
+
+### Render
+
+Delegates entirely to `<CaseSummaryFields>` DSE component, passing:
+- `arPrimaryFields` — array of `{ name, value }` objects for primary display
+- `arSecondaryFields` — array of `{ name, value, displayLabel }` objects for secondary display
+
+## Visual Specifications
+
+- `<CaseSummaryFields>` handles all rendering — see the DSE component skill for details.
+- Primary fields: large text, no label.
+- Secondary fields: label + value pairs.
+
+**CSS-only implementation notes (for `CaseSummaryFields` wrapper):**
+- Container: `display: flex; flex-direction: column; gap: 8px`.
+- Primary field value: `font-size: 1rem; font-weight: 600`.
+- Secondary field row: `display: flex; gap: 4px; font-size: 0.875rem`.
+- Secondary label: `color: var(--secondary-text-color)`.
+
+## Edge Cases & Special Logic
+
+- If both `arPrimaryFields` prop and children are present, the direct prop takes priority.
+- `prepareCaseSummaryData` — guard against undefined/null field values before passing to `getLocaleValue`.
+- `displayLabel` on secondary fields controls whether the field label is shown alongside the value.
+- If `arSecondaryFields` is empty, the secondary section is not rendered.
+
+## Dependencies
+
+- `prepareCaseSummaryData` from `./utils` (local helper)
+- `CaseSummaryFields` — DSE component registered in the component registry
+- `PCore.getLocaleUtils().getLocaleValue()` — value localization
+
+## Design System Mapping
+
+**UI control type:** Read-only case summary panel with primary and secondary field groups.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Approach |
+|---|---|
+| Default (CSS only) | Flexbox column with CSS-styled field rows |
+| MUI | `<Typography>` variants for primary/secondary text |
+| Ant Design | `<Descriptions>` with `bordered={false}` |
+| Chakra UI | `<VStack>` with `<Text>` variants |
+| Shadcn/ui | Custom `<dl>/<dt>/<dd>` or card |
+
+When implementing in a specific design system:
+- Always localize field values before display — use `PCore.getLocaleUtils().getLocaleValue()`
+- `CaseSummaryFields` is a DSE component — implement it separately and call it from here
+- Primary fields have no labels; secondary fields have labels

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/CaseView.mdrules

@@ -0,0 +1,136 @@
+---
+description: Template component skill: CaseView
+alwaysApply: false
+---
+
+# Skill: CaseView
+
+Case view template. Renders the full case workspace: summary sidebar, stages, to-do region, main content tabs, and utilities column. Also covers `ObjectPage` (which is a re-export of `CaseView`).
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+The primary case workspace template. Extracts named regions from PConnect children by metadata type and name, arranges them in a 3-column responsive grid (3/6/3), handles deferred tab loading, and supports a `displayOnlyFA` mode that shows only the to-do region. Edit actions are triggered via the utilities column.
+
+> **Note:** `ObjectPage` is a direct re-export of `CaseView` — `export { default } from '../CaseView'`. Do not create a separate `ObjectPage` component; register both keys pointing to the same implementation.
+
+## Pega Metadata
+
+- **Registration key:** `CaseView` and `ObjectPage` (both point to the same component)
+- **Category:** Page template — case workspace
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Named region children (summary, stages, todo, utilities, tabs) |
+| `displayOnlyFA` | `boolean` | No | If true, renders only the to-do region (focused action mode) |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Region Extraction
+
+Use `getRawMetadata()` to access `children` with `type` and `name` metadata. Extract by:
+- **Summary region:** `type === 'Region' && name === 'Summary'`
+- **Stages region:** `type === 'Region' && name === 'Stages'`
+- **ToDo region:** `type === 'Region' && name === 'ToDo'`
+- **Utilities region:** `type === 'Region' && name === 'Utilities'`
+- **Tabs region:** `type === 'Region' && name === 'Tabs'`
+
+Render each region as a React child element using `createElement(PConnectComponent, { ...regionConfig })`.
+
+### Tabs Region — Deferred Load
+
+- From the Tabs region children, build `vertTabInfo` (vertical tab definitions) and `deferLoadInfo` (deferred loading metadata).
+- Pass both to `<DeferLoad>` component which handles lazy rendering of tab content.
+- The tabs list comes from `theTabsRegionChildren` (the children of the Tabs region).
+
+### displayOnlyFA Mode
+
+If `displayOnlyFA === true`:
+- Render only the ToDo region, centered.
+- Skip summary, stages, tabs, utilities rendering.
+
+### Attachments Subscription
+
+- Subscribe to `PCore.getPubSubUtils().subscribe(CASE_ATTACHMENTS_UPDATED, handleAttachmentUpdate, 'CaseView')`.
+- Track `hasNewAttachments` boolean state — passed to utilities region.
+- Unsubscribe on unmount.
+
+### Edit Action
+
+- The utilities region may include an edit action button.
+- On click: call `getPConnect().getActionsApi().openLocalAction(editActionId, { ... })`.
+
+## Visual Specifications
+
+### 3-Column Grid Layout
+
+```
+[Col xs:3]  [Col xs:6]  [Col xs:3]
+ Summary     Main tabs   Utilities
+ Stages      (Deferred)
+ ToDo
+```
+
+| Column | xs | Contents |
+|--------|----|----------|
+| Left | 3 | Summary, Stages, ToDo regions |
+| Center | 6 | Tabs region (deferred content) |
+| Right | 3 | Utilities region |
+
+**CSS-only implementation notes:**
+- Outer grid: `display: grid; grid-template-columns: 25% 50% 25%; gap: 1rem`.
+- Left column: `display: flex; flex-direction: column; gap: 0.5rem`.
+- Center column: `overflow: hidden`.
+- Responsive: on mobile, stack to single column.
+
+## Edge Cases & Special Logic
+
+- `displayOnlyFA === true` — completely different render tree (only ToDo), no grid layout.
+- Missing regions — guard each region before rendering; a region may not exist for all case types.
+- `DeferLoad` handles progressive loading — do not eagerly render all tab content.
+- `hasNewAttachments` is passed down to the utilities region — it affects attachment icon badge display.
+
+## Dependencies
+
+- `DeferLoad` component from `@pega/sdk-react` — deferred tab content loading
+- `PCore.getPubSubUtils()` — pub/sub for attachment updates
+- `PConnectComponent` from `@pega/sdk-react`
+- `CASE_ATTACHMENTS_UPDATED` constant from `@pega/sdk-core` (or local constants)
+
+## Sub-Variants
+
+### ObjectPage
+
+`ObjectPage` is registered as:
+```tsx
+// packages/sdk-react/src/components/template/ObjectPage/index.tsx
+export { default } from '../CaseView';
+```
+- No separate implementation needed.
+- In `component-map.ts`, register `ObjectPage` key pointing to the same component as `CaseView`.
+
+## Design System Mapping
+
+**UI control type:** Full case workspace layout — 3-column grid with sidebar, main content, and utilities.
+
+Listed design systems are examples only.
+
+| Design System | Grid | Sidebar | Deferred Tabs |
+|---|---|---|---|
+| Default (CSS only) | CSS Grid 25/50/25 | `<aside>` | Intersection Observer lazy load |
+| MUI | `<Grid container>` with `<Grid size={{ xs: 3/6/3 }}>` | `<Box>` | MUI `<Tabs>` + DeferLoad |
+| Ant Design | `<Row><Col span={6/12/6}>` | `<Sider>` | `<Tabs>` lazy |
+| Chakra UI | `<Grid templateColumns='1fr 2fr 1fr'>` | `<Box>` | Custom lazy tabs |
+| Shadcn/ui | Tailwind `grid grid-cols-[1fr_2fr_1fr]` | `<aside>` | Custom |
+
+When implementing in a specific design system:
+- `displayOnlyFA` must completely bypass the grid — render only ToDo region
+- Region extraction by metadata name is required — do not assume positional ordering
+- Deferred loading is mandatory for performance — tab content must not all load at once

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/CaseViewActionsMenu.mdrules

@@ -0,0 +1,131 @@
+---
+description: Template component skill: CaseViewActionsMenu
+alwaysApply: false
+---
+
+# Skill: CaseViewActionsMenu
+
+Case actions dropdown menu. Renders an "Actions" button that opens a menu of local actions and process actions for the current case.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a button that opens a dropdown menu containing all available case actions. Distinguishes between local actions (UI flow) and process actions (server-side), invoking the appropriate API for each. Shows a Snackbar toast on process action error.
+
+## Pega Metadata
+
+- **Registration key:** `CaseViewActionsMenu` (in `component-map.ts`)
+- **Category:** Page template — action menu
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `localActions` | `array` | No | Array of `{ ID, name }` local action objects |
+| `processActions` | `array` | No | Array of `{ ID, name }` process action objects |
+| `caseTypeID` | `string` | Yes | Case type identifier for label localization |
+| `caseTypeName` | `string` | Yes | Case type display name for label localization |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Button Label
+
+- Localized via `PCore.getLocaleUtils().getLocaleValue('Actions', 'CaseView', 'Actions')`.
+- Rendered as an outlined/secondary button with a dropdown indicator icon.
+
+### Menu Items
+
+The menu combines:
+1. **Local actions** — each item triggers `getPConnect().getActionsApi().openLocalAction(action.ID, { caseID: getPConnect().getCaseInfo().getID() })`.
+2. **Process actions** — each item triggers `getPConnect().getActionsApi().openProcessAction(action.ID, { ... })`.
+
+If both groups exist, render a divider between them.
+
+### Localized Action Labels
+
+For localized case type context:
+```
+localeKey = `${caseTypeID}!CASE!${caseTypeName.toUpperCase()}`
+```
+Action name localization: `PCore.getLocaleUtils().getLocaleValue(action.name, localeKey, action.name)`.
+
+### Process Action Error Handling
+
+1. On process action click, wrap in `try/catch`.
+2. On error: show Snackbar toast with the error message.
+3. Snackbar auto-hides after 3000ms.
+
+### Menu State
+
+- `anchorEl` state controls menu open/close.
+- Open: `setAnchorEl(event.currentTarget)`.
+- Close: `setAnchorEl(null)`.
+
+## Visual Specifications
+
+### Button
+
+| Property | Value |
+|----------|-------|
+| Label | Localized `"Actions"` |
+| Variant | Outlined or secondary |
+| Icon | Dropdown chevron or expand_more |
+
+### Menu
+
+| Property | Value |
+|----------|-------|
+| Position | Anchored below the button |
+| Divider | Between local and process action groups |
+| Item height | Standard menu item height |
+
+**CSS-only implementation notes:**
+- Button: `padding: 6px 12px; border: 1px solid var(--app-primary-color); border-radius: 4px; cursor: pointer`.
+- Dropdown menu: `position: absolute; background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.2); border-radius: 4px; min-width: 160px; z-index: 1000`.
+- Menu item: `padding: 8px 16px; cursor: pointer`. Hover: `background: var(--hover-bg)`.
+- Divider: `border-top: 1px solid var(--divider-color); margin: 4px 0`.
+
+### Snackbar Toast
+
+| Property | Value |
+|----------|-------|
+| Position | Bottom-center or bottom-right |
+| Auto-hide | 3000ms |
+| Severity | Error (red) |
+
+## Edge Cases & Special Logic
+
+- If both `localActions` and `processActions` are empty, the "Actions" button may be hidden or disabled.
+- `caseTypeName.toUpperCase()` — guard against `undefined`/`null` values.
+- Process action errors may include HTML — sanitize before displaying in the Snackbar message.
+- Menu should close on any item click (both local and process).
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — label localization
+- `PConnectComponent` from `@pega/sdk-react`
+- MUI: `<Button>`, `<Menu>`, `<MenuItem>`, `<Divider>`, `<Snackbar>`
+
+## Design System Mapping
+
+**UI control type:** Dropdown action menu with button trigger and toast error notification.
+
+Listed design systems are examples only.
+
+| Design System | Button | Menu | Toast |
+|---|---|---|---|
+| Default (CSS only) | `<button>` + custom dropdown | `<ul>/<li>` with CSS | Custom toast overlay |
+| MUI | `<Button>` + `<Menu>/<MenuItem>` | MUI Menu | `<Snackbar>/<Alert>` |
+| Ant Design | `<Dropdown menu={{ items }}>` | Ant Dropdown | `message.error()` |
+| Chakra UI | `<Menu>/<MenuButton>/<MenuList>` | Chakra Menu | `useToast()` |
+| Shadcn/ui | `<DropdownMenu>/<DropdownMenuTrigger>` | Shadcn DropdownMenu | `<Toaster>` + `toast.error()` |
+
+When implementing in a specific design system:
+- Local vs process action distinction must be preserved — they call different APIs
+- Localized labels via `localeKey = ${caseTypeID}!CASE!${caseTypeName.toUpperCase()}`
+- Process action errors must be surfaced via a dismissible toast

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/Confirmation.mdrules

@@ -0,0 +1,112 @@
+---
+description: Template component skill: Confirmation
+alwaysApply: false
+---
+
+# Skill: Confirmation
+
+Case confirmation template. Renders the post-submission confirmation view with a Done button, optionally showing ToDo assignments that remain after the case is submitted.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Displayed after a case or assignment is submitted. Shows the confirmation view (with `Details` region) and a Done button. If outstanding ToDo assignments remain after the user clicks Done, they are displayed. When the user truly finishes, publishes `CLOSE_CONFIRM_VIEW` to close the container.
+
+## Pega Metadata
+
+- **Registration key:** `Confirmation` (in `component-map.ts`)
+- **Category:** Page template — confirmation
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Region children: `[0]` = ToDo region, `[1]` = Details region (when available) |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### State
+
+- `showConfirmView`: boolean, initially `true`.
+- `toDoAssignments`: array from `getToDoAssignments(getPConnect())` — pending assignments.
+
+### Done Button Click
+
+1. Call `getPConnect().getContainerManager().closeContainerItem(getPConnect().getContainerName())`.
+2. OR call `PCore.getContainerUtils().getActiveContainerItemName(getPConnect().getContainerName())`.
+3. Check remaining `toDoAssignments`.
+4. If assignments remain: `setShowConfirmView(false)` — show ToDo view instead.
+5. If no assignments remain: publish `PCore.getPubSubUtils().publish(CLOSE_CONFIRM_VIEW, {})`.
+
+### Show Details
+
+- `showDetails`: `children.length > 1` — true when a Details region is present.
+
+### Render: Confirm View (`showConfirmView === true`)
+
+1. Confirmation message header (localized `"Your submission is confirmed"` or equivalent).
+2. If `showDetails`: render `children[1]` (Details region) using `createElement(PConnectComponent, ...)`.
+3. Done button (`localized "Done"`) — triggers done click handler above.
+
+### Render: ToDo View (`showConfirmView === false`)
+
+- Render `children[0]` (ToDo region) using `createElement(PConnectComponent, ...)`.
+
+## Visual Specifications
+
+### Confirm View
+
+| Element | Description |
+|---------|-------------|
+| Confirmation header | Success icon + heading text |
+| Details section | Optional — rendered below confirmation header |
+| Done button | Primary button, bottom of the form |
+
+**CSS-only implementation notes:**
+- Confirm view: `display: flex; flex-direction: column; align-items: center; gap: 1.5rem; padding: 2rem`.
+- Success icon: large checkmark or success indicator, centered.
+- Confirmation heading: `font-size: 1.5rem; font-weight: 600; text-align: center`.
+- Done button: `align-self: flex-end` or centered.
+
+### ToDo View
+
+- Full-width ToDo region rendered in place of confirmation.
+- No additional wrapping — render the region directly.
+
+## Edge Cases & Special Logic
+
+- `getToDoAssignments(getPConnect())` — returns empty array if no assignments remain; triggers close publish immediately.
+- `children[1]` may not exist — always check `showDetails` before rendering.
+- `CLOSE_CONFIRM_VIEW` is a PubSub constant — ensure it matches the consuming container's subscription key.
+- The confirmation view should not be navigable backward — Done is the only exit.
+
+## Dependencies
+
+- `getToDoAssignments` from `../../helpers/case-utils` (or equivalent)
+- `PCore.getPubSubUtils().publish()` — for CLOSE_CONFIRM_VIEW event
+- `PCore.getContainerUtils()` — for container item management
+- `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Post-submission confirmation page with done action and optional todo view.
+
+Listed design systems are examples only.
+
+| Design System | Success Indicator | Done Button | Layout |
+|---|---|---|---|
+| Default (CSS only) | CSS checkmark SVG | `<button class='primary'>` | Centered flexbox column |
+| MUI | `<CheckCircleIcon>` | `<Button variant='contained'>` | `<Box display='flex' flexDirection='column'>` |
+| Ant Design | `<Result status='success'>` | `<Button type='primary'>` | Ant Result component |
+| Chakra UI | `<CheckCircleIcon>` + `<Text>` | `<Button colorScheme='blue'>` | `<VStack>` |
+| Shadcn/ui | Custom icon + `<h2>` | `<Button>` | Tailwind centered div |
+
+When implementing in a specific design system:
+- Done button must check remaining `toDoAssignments` before deciding whether to show ToDo view or close
+- `CLOSE_CONFIRM_VIEW` publish must happen only after confirming no assignments remain
+- `showDetails` check must guard `children[1]` access

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/DataReference.mdrules

@@ -0,0 +1,125 @@
+---
+description: Template component skill: DataReference
+alwaysApply: false
+---
+
+# Skill: DataReference
+
+Data reference template. Routes to field, table, or search renderers based on `selectionMode` and `displayAs` props. Handles deferred data source loading, dropdown options, and multi-select variants.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a data reference field that can be displayed as a dropdown, autocomplete, checkbox group, radiobutton group, or a card-selection layout. In read-only mode, delegates to `SingleReferenceReadOnly` (single selection) or `MultiReferenceReadOnly` (multi-selection). Supports deferred/parameterized data sources.
+
+## Pega Metadata
+
+- **Registration key:** `DataReference` (in `component-map.ts`)
+- **Category:** Form template — data selection
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Field label |
+| `displayAs` | `string` | Yes | UI variant: `'dropdown'`, `'autocomplete'`, `'checkbox'`, `'radiobutton'`, `'listview'`, `'searchbox'` |
+| `selectionMode` | `string` | Yes | `'single'` or `'multi'` |
+| `displayMode` | `string` | No | `'DISPLAY_ONLY'` for read-only rendering |
+| `readOnly` | `boolean` | No | Alternative read-only flag |
+| `ruleClass` | `string` | Yes | Data page class reference |
+| `dataRelationship` | `string` | No | Relationship type |
+| `isDDSourceDeferred` | `boolean` | No | Whether data source is loaded asynchronously |
+| `parameters` | `object` | No | Parameters passed to the data page for deferred sources |
+| `allowSearch` | `boolean` | No | Show search input inside dropdown/autocomplete |
+| `searchIcon` | `boolean` | No | Show search icon in the field |
+| `numCols` | `string` | No | Column count for checkbox/radiobutton layouts: `'1'`, `'2'`, `'3'` |
+| `listType` | `string` | No | `'associated'` or `'datapage'` |
+| `fieldMetadata` | `object` | No | Extra field-level metadata |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Read-Only Routing
+
+If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
+- `selectionMode === 'single'` → render `<SingleReferenceReadOnly />`.
+- `selectionMode === 'multi'` → render `<MultiReferenceReadOnly />`.
+- Both receive all relevant props plus `getPConnect`.
+
+### Edit Routing (by `displayAs`)
+
+| `displayAs` | Rendered component |
+|-------------|--------------------|
+| `'dropdown'` | Registered `Dropdown` field component |
+| `'autocomplete'` | Registered `AutoComplete` field component |
+| `'checkbox'` | Registered `CheckboxGroup` with `numCols` |
+| `'radiobutton'` | Registered `RadioButtons` with `numCols` |
+| `'listview'` | Inline `ListView` sub-component |
+| `'searchbox'` | Inline `SearchForm` sub-component |
+| Default | `Dropdown` |
+
+### Deferred Data Source (`isDDSourceDeferred === true`)
+
+1. On mount, call `PCore.getDataApiUtils().getData(dataSourceName, parameters)`.
+2. Store result in `dropDownDataSource` state.
+3. Pass `dropDownDataSource` to the rendered field component as `datasource`.
+
+### Localized Placeholder
+
+- Generate a localized "Please select..." option via `localizedPlaceholderOption` using `PCore.getLocaleUtils().getLocaleValue(...)`.
+- Prepend this option to `dropDownDataSource` for dropdown/autocomplete variants.
+
+### SearchForm Sub-Component
+
+When `displayAs === 'searchbox'`, renders an inline `<SearchForm>` sub-component that:
+1. Shows a text input with search icon.
+2. On submit: calls `getPConnect().getListActions().search(searchText)`.
+3. Renders the search results list below the input using `buildView`.
+
+## Visual Specifications
+
+**CSS-only implementation notes:**
+- Wrapper: `display: flex; flex-direction: column; gap: 4px`.
+- Label: `font-size: 0.875rem; font-weight: 500; margin-bottom: 4px`.
+- Dropdown/Autocomplete: standard select input, full-width.
+- Checkbox/Radio group: grid layout matching `numCols`.
+- SearchForm: `display: flex; gap: 8px` (input + search button).
+
+## Edge Cases & Special Logic
+
+- `isDDSourceDeferred` — data is not available synchronously; show a loading indicator until `dropDownDataSource` resolves.
+- `parameters` may contain property references — resolve them via `pConn.getValue(paramRef)` before passing to `getData`.
+- `listType === 'associated'` — use `pConn.getFieldMetadata().options` directly instead of fetching from data page.
+- Card variant (`displayAs === 'listview'`) — may include image props (`image`, `imagePlaceholder`) from `getComponentConfig()`.
+- Multi-select with `displayAs === 'checkbox'` — values stored as comma-separated string in the property.
+
+## Dependencies
+
+- `SingleReferenceReadOnly` (registered DSE or template component)
+- `MultiReferenceReadOnly` (registered template component)
+- Field components from registry: `Dropdown`, `AutoComplete`, `CheckboxGroup`, `RadioButtons`
+- `PCore.getDataApiUtils().getData()` — for deferred data source fetch
+- `PCore.getLocaleUtils().getLocaleValue()` — for localized placeholder
+
+## Design System Mapping
+
+**UI control type:** Polymorphic data selection field — dropdown, autocomplete, checkbox, radiobutton, or search variants.
+
+Listed design systems are examples only.
+
+| Design System | Dropdown | Autocomplete | Checkbox Group | Radio Group |
+|---|---|---|---|---|
+| Default (CSS only) | `<select>` | Custom combobox | `<input type='checkbox'>` list | `<input type='radio'>` list |
+| MUI | `<Select>/<MenuItem>` | `<Autocomplete>` | `<FormGroup><Checkbox>` | `<RadioGroup><Radio>` |
+| Ant Design | `<Select>` | `<AutoComplete>` | `<Checkbox.Group>` | `<Radio.Group>` |
+| Chakra UI | `<Select>` | Custom | `<CheckboxGroup>` | `<RadioGroup>` |
+| Shadcn/ui | `<Select>` + combobox | `<Combobox>` | custom | `<RadioGroup>` |
+
+When implementing in a specific design system:
+- Always check `displayMode`/`readOnly` first and route to read-only components before rendering editable variants
+- Deferred loading must be handled — show skeleton/spinner until data is ready
+- `numCols` applies to checkbox and radiobutton layouts only