@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/.github/skills/template-skills/AppShell.md

@@ -1,124 +0,0 @@
-# Skill: AppShell
-
-Top-level application shell template. Renders the outer portal/WSS portal frame: navigation bar, alert banners, operator avatar, portal logo, and case types. Provides NavContext to child components.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-The outermost container for the Pega SDK React app. Determines whether the app is running in WSS portal or standard portal mode, renders the appropriate navigation bar, handles HTTP and page-level alert messages, loads the portal logo asynchronously, and passes navigation links and case types to the nav bar.
-
-## Pega Metadata
-
-- **Registration key:** `AppShell` (in `component-map.ts`)
-- **Category:** Page template — application shell
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop          | Type        | Required | Description                                                  |
-| ------------- | ----------- | -------- | ------------------------------------------------------------ |
-| `pages`       | `array`     | Yes      | Array of portal page objects `{ name, pyLabel, linkUrl }`    |
-| `caseTypes`   | `array`     | No       | Fallback case types (overridden by data page fetch if empty) |
-| `portalName`  | `string`    | Yes      | Portal identifier — determines WSS vs standard rendering     |
-| `displayName` | `string`    | No       | Operator display name for avatar                             |
-| `getPConnect` | `function`  | Yes      | PConnect getter                                              |
-| `children`    | `ReactNode` | Yes      | Main content area                                            |
-
-## Behavioral Contract
-
-### Portal Type Detection
-
-- Check `portalName` (or metadata flag) against WSS portal identifier.
-- WSS portal → render `<WssNavBar>` component.
-- Standard portal → render `<NavBar>` component.
-
-### Alert Banners
-
-1. Subscribe to `getPConnect()` for `httpMessages` and `pageMessages` updates.
-2. If either array is non-empty, render `<AlertBanner>` DSE component above the main content.
-3. `AlertBanner` receives the combined message array and a dismiss handler.
-
-### Portal Logo
-
-1. On mount, call `PCore.getAssetLoader().getSvcImageUrl(logoAssetName)` asynchronously.
-2. Store the resolved URL in `portalLogoUrl` state.
-3. Pass `portalLogoUrl` to the nav bar as the `logo` prop.
-
-### Operator Avatar
-
-- Read `displayName` from `getPConnect().getValue('.pyUserName')` or the `displayName` prop.
-- Render operator avatar (initials) in the nav bar via the `operatorInfo` prop.
-
-### Case Types
-
-1. On mount, fetch case types via `PCore.getDataPageUtils().getPageDataAsync('D_pyPortalTypeList', 'root', {})`.
-2. Store result in `caseTypes` state (overrides the prop default).
-3. Pass `caseTypes` to the nav bar.
-
-### NavContext
-
-- Wrap children in `<NavContext.Provider value={{ links, caseTypes }}>`.
-- `links` is derived from `pages` prop: `pages.map(p => ({ label: p.pyLabel, url: p.linkUrl, id: p.name }))`.
-
-### Render Structure
-
-```
-<div className="psdk-app-shell">
-  <NavBar | WssNavBar (with logo, caseTypes, operatorInfo, links) />
-  <AlertBanner (if messages) />
-  <main className="psdk-app-shell-content">
-    <NavContext.Provider>
-      {children}
-    </NavContext.Provider>
-  </main>
-</div>
-```
-
-## Visual Specifications
-
-**CSS-only implementation notes:**
-
-- Shell wrapper: `display: flex; flex-direction: column; height: 100vh`.
-- Nav bar: `flex: 0 0 auto` (fixed height).
-- Alert banner: `flex: 0 0 auto` (shown below nav, pushes content down).
-- Content area: `flex: 1 1 auto; overflow-y: auto`.
-
-## Edge Cases & Special Logic
-
-- Logo loading is async — show fallback (app name or blank) until URL resolves.
-- Case types fetch may fail — catch errors and fall back to the `caseTypes` prop.
-- `httpMessages` are transient (from API errors) — clear them after display or on next navigation.
-- `pageMessages` are persistent until explicitly dismissed.
-- If `pages` is empty, `links` array is empty — nav bar may render without page links.
-
-## Dependencies
-
-- `NavBar` DSE component — standard portal navigation
-- `WssNavBar` template component — WSS portal navigation (see `WssNavBar.md`)
-- `AlertBanner` DSE component — message display
-- `NavContext` from `../../context/nav-context`
-- `PCore.getAssetLoader().getSvcImageUrl()` — logo URL resolution
-- `PCore.getDataPageUtils().getPageDataAsync()` — case types data page
-
-## Design System Mapping
-
-**UI control type:** Application shell layout — fixed nav + scrollable content area.
-
-Listed design systems are examples only.
-
-| Design System      | Nav Bar                  | Alert Banner         | Shell Layout                                  |
-| ------------------ | ------------------------ | -------------------- | --------------------------------------------- |
-| Default (CSS only) | `<header>` + custom nav  | `<div role='alert'>` | CSS flexbox column                            |
-| MUI                | `<AppBar>` + `<Toolbar>` | `<Alert>`            | `<Box display='flex' flexDirection='column'>` |
-| Ant Design         | `<Layout.Header>`        | `<Alert>`            | `<Layout>`                                    |
-| Chakra UI          | `<Box as='header'>`      | `<Alert>`            | `<Flex direction='column'>`                   |
-| Shadcn/ui          | Custom header            | `<Alert>`            | Tailwind `flex flex-col h-screen`             |
-
-When implementing in a specific design system:
-
-- WSS vs portal detection must remain — the nav bar component differs for each
-- Logo URL must be loaded asynchronously from `PCore.getAssetLoader()`
-- `NavContext.Provider` must wrap children so descendant nav-aware components can access links

package/templates/react-sdk-reference/.github/skills/template-skills/BannerPage.md

@@ -1,86 +0,0 @@
-# Skill: BannerPage
-
-Page template that wraps the `Banner` DSE component, rendering a hero image section with a configurable two-column content area below.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-A thin template wrapper that delegates entirely to the `Banner` DSE component. Translates page-template props (heading, message, layout, backgroundImage) into `Banner`'s props and passes the first two React children as the `a` (left) and `b` (right) content slot.
-
-## Pega Metadata
-
-- **Registration key:** `BannerPage` (in `component-map.ts`)
-- **Category:** Page template
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop              | Type          | Required | Description                                                                                    |
-| ----------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `children`        | `ReactNode[]` | Yes      | At least 2 children — `[0]` → left (`a`) slot, `[1]` → right (`b`) slot                        |
-| `layout`          | `string`      | No       | Column layout variant for `Banner`: `'two-column'` (default), `'narrow-wide'`, `'wide-narrow'` |
-| `heading`         | `string`      | No       | Hero section heading text. Default `''`                                                        |
-| `message`         | `string`      | No       | Hero section message/subtitle. Default `''`                                                    |
-| `imageTheme`      | `string`      | No       | Banner image theme (e.g., `'light'`). Default `'light'`                                        |
-| `backgroundImage` | `string`      | No       | URL of the background image for the hero. Default `''`                                         |
-| `backgroundColor` | `string`      | No       | Background color for the hero. Default `''`                                                    |
-| `tintImage`       | `boolean`     | No       | Whether to tint the background image. Default `false`                                          |
-
-## Behavioral Contract
-
-1. Retrieve `Banner` from the component registry via `getComponentFromRegistry('Banner')`.
-2. Convert `children` to an array using `Children.toArray(children)` (memoized).
-3. Render `<Banner>` with the following props:
-   - `variant={layout}` — controls column widths below the hero
-   - `a={childArray[0]}` — left/first column content
-   - `b={childArray[1]}` — right/second column content
-   - `banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}`
-4. No additional wrapper or layout — this component IS a single `<Banner>` render.
-
-## Visual Specifications
-
-This component has no independent visual output — all visual behavior is defined by the `Banner` DSE component. See [`design-system-extension-skills/Banner.md`](../design-system-extension-skills/Banner.md) for full visual specs.
-
-Key visual behaviors inherited from `Banner`:
-
-- Hero: full-width background image section, height `19rem`, centered title and message overlay
-- Content area: two-column grid below the hero, column widths driven by `variant`/`layout`
-
-**CSS-only implementation notes:**
-
-- This template creates no CSS of its own — implement it as a pure pass-through to `Banner`.
-- The `layout` prop maps directly to `Banner`'s `variant` prop.
-- `heading` → `Banner.banner.title`, `message` → `Banner.banner.message`.
-
-## Edge Cases & Special Logic
-
-- Children are memoized: `useMemo(() => Children.toArray(children), [children])` — only recomputed when `children` changes.
-- If only one child is provided, `childArray[1]` will be `undefined` — `Banner` receives `b={undefined}` and should render an empty second column.
-- `BannerPage` does NOT call `getPConnect()` itself for layout — children are React children (passed by the Pega rendering engine).
-
-## Dependencies
-
-- `getComponentFromRegistry('Banner')` from `@pega/sdk-react` — all rendering delegated to `Banner`
-- `Children.toArray` from React — for child array normalization
-
-## Design System Mapping
-
-**UI control type:** Full-width banner hero page with configurable two-column content area.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                |
-| ------------------ | -------------------------------------------------------------------- |
-| Default (CSS only) | Pass-through to `Banner` — implement Banner's CSS hero + grid layout |
-| MUI                | Pass-through to `Banner` (MUI-based)                                 |
-| Ant Design         | Pass-through to `Banner` (Ant-based)                                 |
-| Chakra UI          | Pass-through to `Banner` (Chakra-based)                              |
-| Shadcn/ui          | Pass-through to `Banner` (Shadcn-based)                              |
-
-When implementing in a specific design system:
-
-- `BannerPage` is always a thin wrapper — implement `Banner` first, then `BannerPage` simply delegates to it
-- Prop mapping: `layout` → `variant`, `heading` → `banner.title`, `message` → `banner.message`, `backgroundImage` → `banner.backgroundImage`

package/templates/react-sdk-reference/.github/skills/template-skills/CaseView.md

@@ -1,137 +0,0 @@
-# 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/.github/skills/template-skills/CaseViewActionsMenu.md

@@ -1,131 +0,0 @@
-# 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/.github/skills/template-skills/DataReference.md

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