@pega/sdk 0.0.4 → 0.0.5

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

@@ -1,105 +0,0 @@
----
-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

@@ -1,136 +0,0 @@
----
-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

@@ -1,131 +0,0 @@
----
-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

@@ -1,112 +0,0 @@
----
-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

@@ -1,125 +0,0 @@
----
-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