@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/.claude/skills/template-skills/ListPage.md

@@ -1,70 +0,0 @@
-# Skill: ListPage
-
-List page template. Thin wrapper that renders `ListView` in standalone page mode (`bInForm: false`).
-
-> **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 full-page list view by forwarding all props to `ListView` with `bInForm: false`. There is no additional logic — this component exists solely to provide a registration key that signals "this is a page, not an inline table."
-
-> See `ListView.md` for full documentation of all capabilities.
-
-## Pega Metadata
-
-- **Registration key:** `ListPage` (in `component-map.ts`)
-- **Category:** Page template — list page
-- **Extends:** `PConnProps`
-
-## Props
-
-All props are forwarded to `ListView`. Key props:
-
-| Prop           | Type       | Required | Description                    |
-| -------------- | ---------- | -------- | ------------------------------ |
-| `dataPageName` | `string`   | Yes      | Data page to load records from |
-| `columns`      | `array`    | No       | Column definitions             |
-| `isSearchable` | `boolean`  | No       | Whether global search is shown |
-| `payload`      | `object`   | No       | Query payload                  |
-| `getPConnect`  | `function` | Yes      | PConnect getter                |
-
-## Behavioral Contract
-
-```tsx
-<ListView {...props} bInForm={false} />
-```
-
-That is the complete implementation. `bInForm: false` ensures ListView renders with full page chrome (outer padding, page-level toolbar layout).
-
-## Visual Specifications
-
-Identical to `ListView` with `bInForm: false`:
-
-- Full outer padding applied.
-- Toolbar occupies full width.
-- Table stretches to fill page width.
-
-See `ListView.md` for all visual details.
-
-## Edge Cases & Special Logic
-
-None beyond `ListView`. The only constraint is that `bInForm` is always `false` for `ListPage`.
-
-## Dependencies
-
-- `ListView` — the primary list template component
-
-## Design System Mapping
-
-**UI control type:** Full-page data list — pass-through to `ListView` with page-mode flag.
-
-Listed design systems are examples only.
-
-Implement identically to `ListView` — `ListPage` adds no new UI. The distinction is purely in the `bInForm` prop which controls spacing/chrome.
-
-When implementing in a specific design system:
-
-- `bInForm: false` signals that the list should have page-level layout (more padding, full-width toolbar)
-- No additional logic beyond `ListView` is required

package/templates/react-sdk-reference/.claude/skills/template-skills/ListView.md

@@ -1,142 +0,0 @@
-# Skill: ListView
-
-Full-featured list view template. Renders a data table with sorting, pagination, global search, single/multi selection, column menu, and filter dialog.
-
-> **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 data table component. Renders a sortable, paginated, filterable, and selectable table from a PConnect data source. Supports both standalone page use (`bInForm: false`) and embedded form use (`bInForm: true`). Columns are configurable, and the table supports row-level selection with callback.
-
-## Pega Metadata
-
-- **Registration key:** `ListView` (in `component-map.ts`)
-- **Category:** Data display template
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop                    | Type       | Required | Description                                                                   |
-| ----------------------- | ---------- | -------- | ----------------------------------------------------------------------------- |
-| `bInForm`               | `boolean`  | No       | Whether rendered inside a form (affects toolbar and padding). Default `false` |
-| `selectionMode`         | `string`   | No       | `'single'` (radio) or `'multi'` (checkbox) or absent (no selection)           |
-| `dataPageName`          | `string`   | No       | Name of data page to fetch records from                                       |
-| `referenceList`         | `array`    | No       | In-memory data array (used when data is already available)                    |
-| `compositeKeys`         | `object`   | No       | Key fields for unique row identification                                      |
-| `columns`               | `array`    | No       | Column definition objects `{ fieldName, label, sortable, filterable }`        |
-| `additionalTableConfig` | `object`   | No       | Extra config merged with column/sort/filter settings                          |
-| `isSearchable`          | `boolean`  | No       | Whether global search input is shown                                          |
-| `payload`               | `object`   | No       | Query payload for data page requests                                          |
-| `getPConnect`           | `function` | Yes      | PConnect getter                                                               |
-
-## Behavioral Contract
-
-### Initialization
-
-`useInit(getPConnect, columns, dataPageName, payload)` hook:
-
-1. Calls `initializeColumns(getPConnect, columns)` to build `configFields`.
-2. Calls `buildFieldsForTable(configFields)` to produce display column definitions.
-3. Calls `getConfigFields(configFields)` for sort/filter metadata.
-4. Fetches initial data via `PCore.getDataApiUtils().getDataAsync(dataPageName, payload)`.
-5. Returns `{ tableDataRows, configFields, totalCount }`.
-
-### Sorting
-
-- `<TableSortLabel>` in each sortable column header.
-- On click: call `PCore.getDataApiUtils().getDataAsync(dataPageName, { ...payload, sortBy, sortOrder })`.
-- `sortBy` = column field name, `sortOrder` = `'ASC'` or `'DESC'`.
-
-### Pagination
-
-- `<TablePagination>` component below the table.
-- `rowsPerPageOptions`: `[5, 10, 25]`.
-- On page/rows change: re-fetch with `startIndex` and `maxResults` params.
-
-### Global Search
-
-- Shown when `isSearchable === true`.
-- `<TextField>` input above the table (toolbar area).
-- On submit/debounce: re-fetch with `searchText` param.
-
-### Selection
-
-| `selectionMode` | Control per row | Callback                     |
-| --------------- | --------------- | ---------------------------- |
-| `'single'`      | `<Radio>`       | `onRowSelect(rowData)`       |
-| `'multi'`       | `<Checkbox>`    | `onRowsSelect(selectedRows)` |
-| absent          | None            | None                         |
-
-- Select-all checkbox in the header for multi-selection.
-- Selected rows highlighted with `selected` row class.
-
-### Column Menu
-
-- `<MoreVertIcon>` button in each column header.
-- Opens `<Menu>` with options: Show/Hide column, Pin column.
-- Column visibility stored in local state `columnVisibility`.
-
-### Filter Dialog
-
-- Filter icon in toolbar or column header.
-- Opens `<Dialog>` with filter form fields for each filterable column.
-- On apply: re-fetch with filter params.
-- `filterData(filters, configFields)` formats filter objects for the API.
-
-### Snackbar Toast
-
-- Shown on fetch errors or action feedback.
-- Auto-hides after 3000ms.
-
-## Visual Specifications
-
-| Element        | Description                                              |
-| -------------- | -------------------------------------------------------- |
-| Toolbar        | Search input + filter button + (optional) action buttons |
-| Table head     | Sticky header with sort labels and column menu           |
-| Table body     | Striped rows, hover state, selected state                |
-| Pagination bar | Below table, page size selector + page nav               |
-
-**CSS-only implementation notes:**
-
-- Table container: `overflow-x: auto`.
-- Header row: `background: var(--table-header-bg); font-weight: 600`.
-- Selected row: `background: var(--selection-highlight-bg)`.
-- Hover row: `background: var(--hover-bg)`.
-- Sticky header: `position: sticky; top: 0; z-index: 1`.
-
-## Edge Cases & Special Logic
-
-- `bInForm: true` — remove outer padding, hide some toolbar elements.
-- Empty result set — show empty state message `"No records found"`.
-- `compositeKeys` — used for unique row key generation when no single ID field exists.
-- Column visibility changes are local state only — not persisted by default.
-- Large datasets — pagination is mandatory; do not load all rows at once.
-
-## Dependencies
-
-- `useInit`, `filterData`, `buildFieldsForTable`, `getConfigFields`, `initializeColumns` from `./utils`
-- `PCore.getDataApiUtils().getDataAsync()` — data fetching
-- MUI: `<Table>`, `<TableHead>`, `<TableBody>`, `<TableRow>`, `<TableCell>`, `<TableSortLabel>`, `<TablePagination>`, `<Checkbox>`, `<Radio>`, `<Dialog>`, `<TextField>`, `<Menu>`, `<MenuItem>`, `<Snackbar>`
-
-## Design System Mapping
-
-**UI control type:** Full-featured data table with sorting, pagination, search, selection, and filtering.
-
-Listed design systems are examples only.
-
-| Design System      | Table                      | Pagination                 | Dialog             |
-| ------------------ | -------------------------- | -------------------------- | ------------------ |
-| Default (CSS only) | `<table>/<thead>/<tbody>`  | Custom pagination controls | `<dialog>` element |
-| MUI                | `<Table>` + sub-components | `<TablePagination>`        | `<Dialog>`         |
-| Ant Design         | `<Table>`                  | Built-in pagination prop   | `<Modal>`          |
-| Chakra UI          | `<Table>`                  | Custom or `react-table`    | `<Modal>`          |
-| Shadcn/ui          | `<Table>` + TanStack Table | Custom pagination          | `<Dialog>`         |
-
-When implementing in a specific design system:
-
-- `bInForm` prop affects layout — tighten spacing and remove outer chrome when `true`
-- Sorting, pagination, and search all trigger data re-fetches — do not filter client-side for server-paged data
-- Selection mode (`single`/`multi`) requires different controls and callbacks

package/templates/react-sdk-reference/.claude/skills/template-skills/MultiReferenceReadOnly.md

@@ -1,82 +0,0 @@
-# Skill: MultiReferenceReadOnly
-
-Multi-reference read-only template. Routes to `SimpleTableSelectReadonly` or `SimpleTable` based on `displayAs` for read-only rendering of multi-value reference fields.
-
-> **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 multi-value reference field in read-only mode. Routing is based on the `displayAs` prop: certain display variants use `SimpleTableSelectReadonly` (link + modal), while others use `SimpleTable` directly.
-
-## Pega Metadata
-
-- **Registration key:** `MultiReferenceReadOnly` (in `component-map.ts`)
-- **Category:** Display template — read-only multi-reference
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop                  | Type       | Required | Description                                              |
-| --------------------- | ---------- | -------- | -------------------------------------------------------- |
-| `displayAs`           | `string`   | Yes      | UI variant that was used in edit mode                    |
-| `referenceList`       | `string`   | No       | Property path to the reference list                      |
-| `readonlyContextList` | `array`    | No       | Fallback data array when `referenceList` is not resolved |
-| `fieldMetadata`       | `object`   | No       | Field-level metadata                                     |
-| `getPConnect`         | `function` | Yes      | PConnect getter                                          |
-
-## Behavioral Contract
-
-### Routing by `displayAs`
-
-```
-if displayAs in ['readonlyMulti', 'combobox', 'checkboxgroup']:
-  → render SimpleTableSelectReadonly
-else:
-  → render SimpleTable (with readOnly=true / displayMode='DISPLAY_ONLY')
-```
-
-### Reference List Fallback
-
-- Primary: `pConn.getValue(referenceList + '.pxResults')`.
-- Fallback: use `readonlyContextList` directly if the above is undefined/empty.
-
-## Visual Specifications
-
-- `SimpleTableSelectReadonly` variant: link/chip showing selection count + modal dialog.
-- `SimpleTable` variant: flat read-only table of values.
-
-See `SimpleTable.md` and `ListView.md` for detailed visual specs.
-
-**CSS-only notes:**
-
-- Fallback to `readonlyContextList` renders identically to the resolved reference list.
-- No edit controls in either variant.
-
-## Edge Cases & Special Logic
-
-- `readonlyContextList` is the fallback — always use it when `pConn.getValue(referenceList)` returns nothing.
-- `displayAs` check uses an inclusion array: `['readonlyMulti', 'combobox', 'checkboxgroup']` — extend this list if new multi-select display variants are added.
-- The component is only reached in `DISPLAY_ONLY`/`readOnly` mode — never needs to handle edit states.
-
-## Dependencies
-
-- `SimpleTableSelectReadonly` (see `SimpleTable.md`)
-- `SimpleTable` (see `SimpleTable.md`)
-
-## Design System Mapping
-
-**UI control type:** Read-only multi-value reference display — routes to modal table or flat table.
-
-Listed design systems are examples only.
-
-| `displayAs`                                  | Routing                     | DS Implementation    |
-| -------------------------------------------- | --------------------------- | -------------------- |
-| `readonlyMulti`, `combobox`, `checkboxgroup` | `SimpleTableSelectReadonly` | Link/chip + modal    |
-| All others                                   | `SimpleTable`               | Flat read-only table |
-
-When implementing in a specific design system:
-
-- The `displayAs` routing list must match the edit-mode variants defined in `DataReference.md`
-- `readonlyContextList` fallback is critical — reference list data may not be available on initial render

package/templates/react-sdk-reference/.claude/skills/template-skills/OneColumn.md

@@ -1,114 +0,0 @@
-# Skill: OneColumn
-
-Single-column layout template that stacks all children in a full-width column.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-Renders all children stacked vertically in a single full-width column. Three closely related sub-variants:
-
-- **`OneColumn`** — core layout with internal grid and column style
-- **`OneColumnPage`** — thin wrapper that delegates to `OneColumn` via the component registry
-- **`OneColumnTab`** — minimal pass-through wrapper for tab context (`<div id='OneColumnTab'>`)
-
-## Pega Metadata
-
-| Variant       | Registration Key |
-| ------------- | ---------------- |
-| OneColumn     | `OneColumn`      |
-| OneColumnPage | `OneColumnPage`  |
-| OneColumnTab  | `OneColumnTab`   |
-
-All extend `PConnProps`. Children are received as React `children`.
-
-## Props
-
-| Prop       | Type          | Required | Description                                         |
-| ---------- | ------------- | -------- | --------------------------------------------------- |
-| `children` | `ReactNode[]` | Yes      | One or more children to render in the single column |
-
-## Sub-Variants
-
-### OneColumnPage
-
-Thin pass-through wrapper. Retrieves `OneColumn` from the component registry and renders with all props forwarded:
-
-```typescript
-const OneColumn = getComponentFromRegistry('OneColumn');
-return <OneColumn {...props} />;
-```
-
-### OneColumnTab
-
-Minimal wrapper — renders children in a plain `<div>` with `id='OneColumnTab'`:
-
-```typescript
-return <div id='OneColumnTab'>{children}</div>;
-```
-
-No grid or column styles applied. Used purely as a slot container inside tab panels.
-
-## Behavioral Contract
-
-1. Render a Grid container with `spacing={2}`.
-2. Render a single inner Grid at `size={{ xs: 12 }}` with `colStyles` applied.
-3. Map over all `children` and render each child.
-4. `OneColumnPage` delegates all rendering to `OneColumn` from the registry.
-5. `OneColumnTab` renders children in a plain `<div>` — no Grid, no styles.
-
-## Visual Specifications
-
-Derived from `OneColumn.tsx` makeStyles:
-
-### Column Style
-
-| Property      | Value                                 |
-| ------------- | ------------------------------------- |
-| Display       | grid                                  |
-| Gap           | 1rem                                  |
-| Align content | baseline (children stack top-aligned) |
-
-### Grid Spacing
-
-| Property          | Value      |
-| ----------------- | ---------- |
-| Container spacing | 2 (≈ 16px) |
-
-**CSS-only implementation notes:**
-
-- Column: `display: grid; gap: 1rem; align-content: baseline; width: 100%`.
-- Outer container: `display: grid; grid-template-columns: 1fr; gap: 16px`.
-- `OneColumnTab`: just `<div>` with no special styling.
-
-## Edge Cases & Special Logic
-
-- `OneColumn` maps over all children (not just first/second) — supports any number of children.
-- `OneColumnPage` uses the registry — if an override exists for `OneColumn`, it will be used.
-- `OneColumnTab` does NOT apply the `colStyles` grid — it is intentionally simpler.
-
-## Dependencies
-
-- `OneColumnPage`: `getComponentFromRegistry` from `@pega/sdk-react`
-- `OneColumn` / `OneColumnTab`: no special dependencies
-
-## Design System Mapping
-
-**UI control type:** Single full-width column layout.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                    |
-| ------------------ | -------------------------------------------------------- |
-| Default (CSS only) | `<div style="display:grid;gap:1rem;">` wrapping children |
-| MUI                | `<Grid container spacing={2}><Grid size={{ xs: 12 }}>`   |
-| Ant Design         | `<Row><Col span={24}>`                                   |
-| Chakra UI          | `<Stack spacing={4}>` or `<Grid templateColumns='1fr'>`  |
-| Shadcn/ui          | Tailwind `flex flex-col gap-4`                           |
-
-When implementing in a specific design system:
-
-- All children render in a single column, top-aligned
-- `OneColumnTab` variant is a minimal `<div>` container with no layout styling

package/templates/react-sdk-reference/.claude/skills/template-skills/SimpleTable.md

@@ -1,131 +0,0 @@
-# Skill: SimpleTable
-
-Simple table template. Routes to FieldGroupTemplate, ListView (read-only), or the manual editable table based on configuration. Also covers `SimpleTableManual`, `SimpleTableSelect`, and `SimpleTableSelectReadonly` sub-variants.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-Entry-point template for embedded table data in a form or detail view. Routes to the appropriate sub-component based on `multiRecordDisplayAs`, `fieldMetadata.dataRetrievalType`, and `readOnly`/`displayMode` flags. Sub-variants handle selection, read-only display, and full manual editing.
-
-## Pega Metadata
-
-- **Registration keys:** `SimpleTable`, `SimpleTableManual`, `SimpleTableSelect`, `SimpleTableSelectReadonly` (all in `component-map.ts`)
-- **Category:** Data display / Form template — embedded table
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop                   | Type       | Required | Description                                                                               |
-| ---------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- |
-| `multiRecordDisplayAs` | `string`   | No       | `'fieldGroup'` delegates to FieldGroupTemplate; else table                                |
-| `fieldMetadata`        | `object`   | No       | Field-level metadata including `dataRetrievalType`                                        |
-| `referenceList`        | `string`   | No       | Property path to the reference list                                                       |
-| `displayAs`            | `string`   | No       | For SimpleTableSelectReadonly: `'readonlyMulti'`, `'combobox'`, `'checkboxgroup'` routing |
-| `selectionMode`        | `string`   | No       | `'single'` or `'multi'` (for SimpleTableSelect)                                           |
-| `displayMode`          | `string`   | No       | `'DISPLAY_ONLY'` triggers read-only sub-variant                                           |
-| `readOnly`             | `boolean`  | No       | Alternative read-only flag                                                                |
-| `getPConnect`          | `function` | Yes      | PConnect getter                                                                           |
-
-## Behavioral Contract
-
-### SimpleTable — Routing Logic
-
-```
-if multiRecordDisplayAs === 'fieldGroup':
-  → render FieldGroupTemplate
-else if fieldMetadata.dataRetrievalType === 'refer':
-  → render ListView (read-only, bInForm: true)
-else:
-  → render SimpleTableManual (editable table)
-```
-
-### SimpleTableManual — Full Editable Table
-
-Full MUI table with add/delete rows, inline editing, sort, filter, and column customization (~600+ lines).
-
-Key behaviors:
-
-1. **Row data source:** `referenceList` property path via `pConn.getValue(referenceList + '.pxResults')`.
-2. **Add row:** `pConn.getListActions().insert({})`.
-3. **Delete row:** `pConn.getListActions().deleteEntry(index)`.
-4. **Inline field editing:** Each cell renders the field's registered edit component via `buildView(pConn, rowIndex, colFieldName)`.
-5. **Sort:** Client-side sort on loaded data.
-6. **Column customization:** Visibility toggles per column via a settings popover.
-7. **Filter dialog:** Same filter pattern as ListView.
-
-### SimpleTableSelect — Selection Mode
-
-Wraps `ListView` with additional selection configuration:
-
-- Passes `additionalTableConfig` with `selectionMode: 'single'` or `'multi'`.
-- On selection: calls `pConn.getListActions().setSelectedRow(selectedData)`.
-- Used when `DataReference` routes to table-based selection.
-
-### SimpleTableSelectReadonly — Read-Only with Modal
-
-1. Renders a link/chip showing the current selection count.
-2. On click: opens a `<Dialog>` containing a `<SimpleTableManual>` in read-only mode.
-3. Props: same as `SimpleTableManual` but all fields locked (no add/delete/edit).
-
-## Visual Specifications
-
-### SimpleTableManual
-
-| Element         | Description                                            |
-| --------------- | ------------------------------------------------------ |
-| Toolbar         | Column settings button, filter button, optional search |
-| Table           | Full-width, alternating row colors                     |
-| Add row         | `"+ Add row"` button below the table                   |
-| Delete row      | Trash icon per row (rightmost column)                  |
-| Column settings | Popover with checkboxes for visibility toggles         |
-
-**CSS-only implementation notes:**
-
-- Table: `width: 100%; border-collapse: collapse`.
-- Add row button: `margin-top: 0.5rem; text-align: left`.
-- Delete cell: `width: 40px; text-align: center`.
-- Read-only mode: hide add/delete controls; cells show plain text.
-
-### SimpleTableSelectReadonly
-
-| Element     | Description                                        |
-| ----------- | -------------------------------------------------- |
-| Trigger     | Link or chip showing selection count               |
-| Modal       | Full-screen or large dialog with SimpleTableManual |
-| Modal close | `X` button in modal header                         |
-
-## Edge Cases & Special Logic
-
-- `multiRecordDisplayAs === 'fieldGroup'` — completely bypasses table; delegates to `FieldGroupTemplate`.
-- `dataRetrievalType === 'refer'` — data comes from a reference list, not a full data page; use `ListView` in read-only mode.
-- `SimpleTableManual` with 600+ lines — break into sub-hooks if re-implementing.
-- Row keys must be unique — use composite keys from `compositeKeys` config if available.
-- Column customization state is local — not persisted across navigation.
-
-## Dependencies
-
-- `FieldGroupTemplate` (for `multiRecordDisplayAs === 'fieldGroup'` routing)
-- `ListView` (for `dataRetrievalType === 'refer'` routing)
-- `buildView` from `../../helpers/field-group-utils` (for inline cell rendering in SimpleTableManual)
-- MUI: `<Table>`, `<Dialog>`, `<Popover>`, `<IconButton>`, `<Button>`, `<Checkbox>`
-
-## Design System Mapping
-
-**UI control type:** Embedded data table with routing to field group, read-only list, or fully editable table.
-
-Listed design systems are examples only.
-
-| Sub-variant               | Default (CSS only)            | MUI                  |
-| ------------------------- | ----------------------------- | -------------------- |
-| SimpleTableManual         | `<table>` + custom controls   | MUI `<Table>`        |
-| SimpleTableSelect         | Custom table + radio/checkbox | `<ListView>` wrapper |
-| SimpleTableSelectReadonly | Link + `<dialog>`             | Chip + `<Dialog>`    |
-
-When implementing in a specific design system:
-
-- Always check `multiRecordDisplayAs === 'fieldGroup'` first — this bypasses the table entirely
-- `SimpleTableManual` add/delete row controls must be hidden when `readOnly === true` or `displayMode === 'DISPLAY_ONLY'`
-- `SimpleTableSelect` uses the same `ListView` but adds selection callbacks

package/templates/react-sdk-reference/.claude/skills/template-skills/SingleReferenceReadOnly.md

@@ -1,108 +0,0 @@
-# Skill: SingleReferenceReadOnly
-
-Single reference read-only template. Renders a read-only reference field as a semantic link for editable field types, or as a plain label otherwise.
-
-> **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 single data reference field in read-only mode. For fields that were displayed as editable selection controls (autocomplete, table select, dropdown), renders a `SemanticLink` component so the reference value is clickable/navigable. For other display types, renders a plain read-only label.
-
-## Pega Metadata
-
-- **Registration key:** `SingleReferenceReadOnly` (in `component-map.ts`)
-- **Category:** Display template — read-only reference
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop              | Type       | Required | Description                                               |
-| ----------------- | ---------- | -------- | --------------------------------------------------------- |
-| `label`           | `string`   | Yes      | Field label                                               |
-| `displayAs`       | `string`   | Yes      | The edit-mode display type this field was configured with |
-| `value`           | `string`   | No       | Current field value (display text)                        |
-| `caseClass`       | `string`   | No       | Class identifier for the referenced case                  |
-| `text`            | `string`   | No       | Display text for the semantic link                        |
-| `caseID`          | `string`   | No       | Case ID for the semantic link                             |
-| `contextPage`     | `string`   | No       | Context page identifier                                   |
-| `resourceParams`  | `object`   | No       | Parameters for the referenced resource                    |
-| `resourcePayload` | `object`   | No       | Payload for resource navigation                           |
-| `getPConnect`     | `function` | Yes      | PConnect getter                                           |
-
-## Behavioral Contract
-
-### Editable Component Check
-
-```
-editableComponents = ['AutoComplete', 'SimpleTableSelect', 'Dropdown']
-```
-
-If `displayAs` is in `editableComponents`:
-
-1. Build config with: `caseClass`, `text`, `caseID`, `contextPage`, `resourceParams`, `resourcePayload`.
-2. Create: `createComponent({ type: 'SemanticLink', config: { ...builtConfig } })`.
-3. Render the created `SemanticLink` component.
-
-Else:
-
-- Render a plain read-only display using `<FormControl variant='standard'>` + `<FormLabel>` + value text.
-
-### Layout
-
-For both variants, wrap with:
-
-```tsx
-<FormControl variant="standard" sx={{ flexDirection: 'row' }}>
-  <FormLabel sx={{ marginRight: '2rem' }}>{label}</FormLabel>
-  {semanLinkOrValue}
-</FormControl>
-```
-
-## Visual Specifications
-
-| Variant         | Layout                                |
-| --------------- | ------------------------------------- |
-| SemanticLink    | Label (left) + clickable link (right) |
-| Plain read-only | Label (left) + plain text (right)     |
-
-**CSS-only implementation notes:**
-
-- Wrapper: `display: flex; flex-direction: row; align-items: baseline; gap: 1rem`.
-- Label: `font-size: 0.875rem; color: var(--secondary-text-color); min-width: 120px`.
-- Semantic link: `color: var(--link-color); text-decoration: underline; cursor: pointer`.
-- Plain value: `font-size: 0.875rem; color: var(--primary-text-color)`.
-
-## Edge Cases & Special Logic
-
-- `displayAs` check is case-sensitive — values are `'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'` (exact match).
-- `createComponent` returns a PConnect config — render via `createElement(PConnectComponent, { ...createdConfig })`.
-- If `text` is empty/undefined, the semantic link shows the `caseID` as fallback text.
-- `SemanticLink` navigation requires `caseClass` and `caseID` — if either is missing, fall back to plain read-only display.
-
-## Dependencies
-
-- `PConnectComponent` from `@pega/sdk-react` — for rendering the `SemanticLink`
-- `getPConnect().createComponent()` — creates the SemanticLink component config
-- MUI: `<FormControl>`, `<FormLabel>`
-
-## Design System Mapping
-
-**UI control type:** Read-only reference field — semantic link for navigable references, plain label otherwise.
-
-Listed design systems are examples only.
-
-| Design System      | Semantic Link                                 | Plain Read-Only     |
-| ------------------ | --------------------------------------------- | ------------------- |
-| Default (CSS only) | `<a>` with case navigation                    | `<span>`            |
-| MUI                | `SemanticLink` rendered via `createComponent` | `<Typography>`      |
-| Ant Design         | `<Typography.Link>`                           | `<Typography.Text>` |
-| Chakra UI          | `<Link>`                                      | `<Text>`            |
-| Shadcn/ui          | Custom link                                   | `<span>`            |
-
-When implementing in a specific design system:
-
-- The `editableComponents` list (`'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'`) controls semantic link vs plain display
-- `SemanticLink` must be rendered via `createComponent` — do not implement the link logic directly in this component
-- Horizontal label + value layout (row direction) is required