@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.github/skills/field-skills/RadioButtons.md

@@ -1,167 +0,0 @@
-# Skill: RadioButtons
-
-Radio button group field with optional card-style variant and localized option labels.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Renders a group of radio buttons for single-selection from a list of options. Supports standard radio button layout (inline or stacked) and a card-style visual variant. Option labels are localized. Commits value immediately on selection.
-
-## Pega Metadata
-
-- **Pega Name:** `RadioButtons`
-- **Type / Subtype:** `Field` / `Picklist-Radio`
-- **Registration key:** `RadioButtons` (in `component-map.ts`)
-
-## Props (component-specific)
-
-| Prop                   | Type                 | Description                                                                     |
-| ---------------------- | -------------------- | ------------------------------------------------------------------------------- |
-| `inline`               | `boolean`            | If `true`, render radio buttons in a horizontal row; if `false`, vertical stack |
-| `fieldMetadata`        | `any` (optional)     | For localization context (tableType, datasource name, display text property)    |
-| `variant`              | `string` (optional)  | `'card'` — renders options as selectable cards instead of radio buttons         |
-| `hideFieldLabels`      | `boolean` (optional) | Hide field labels inside card variant                                           |
-| `additionalProps`      | `any` (optional)     | Extra props passed to `SelectableCard` in card variant                          |
-| `imagePosition`        | `string` (optional)  | Card image position: `'inline-start'`, `'inline-end'`, or block                 |
-| `imageSize`            | `string` (optional)  | Card image size                                                                 |
-| `showImageDescription` | `boolean` (optional) | Whether to show image description in cards                                      |
-| `datasource`           | `any` (optional)     | Datasource for card variant                                                     |
-
-## Behavioral Contract
-
-1. **Local state:** Maintain `theSelectedButton` (string). Initialize from `value` prop. `useEffect` watching `value` → `setSelectedButton(value)`.
-2. **Options:** Load options from `Utils.getOptionList(theConfigProps, pConn.getDataObject(''))` — returns `Array<{key: string, value: string}>`.
-3. **On change:** Commit via `handleEvent(actionsApi, 'changeNblur', propName, event.target.value)`.
-4. **On blur:** Validate via `pConn.getValidationApi().validate(event.target.value, '')`. Second arg is empty string (optional parameter).
-5. **Inline layout:** Use `row={inline}` on the radio group — horizontal when `inline=true`.
-6. **Read-only:** Disable radio inputs (set `disabled` to `readOnly` value) — do NOT use a separate read-only component.
-7. **Localization:** Option labels are localized via `pConn.getLocalizedValue(option.value, localePath, localeRuleName)`.
-8. **Localization keys derivation:**
-   - Strip `@P ` prefix and leading `.` from `configProperty` (from `pConn.getRawMetadata()`).
-   - `localeContext`: `'datapage'` if `fieldMetadata.datasource.tableType === 'DataPage'`, else `'associated'`.
-   - `localeClass`: `'@baseclass'` for datapage, else `className`.
-   - `localeName`: datapage name or property name.
-   - `localePath`: display text property or localeName.
-
-### Variant: Standard (default)
-
-Render a radio group with `FormControl > FormLabel > RadioGroup > FormControlLabel (Radio)` pattern:
-
-- `FormLabel`: the `label` prop
-- `RadioGroup`: `value={theSelectedButton}`, `onChange={handleChange}`, `onBlur`, `row={inline}`
-- Each `FormControlLabel`: `value={option.key}`, `label={localizedLabel}`, `control={<Radio color='primary' disabled={readOnly} />}`
-- Wrap in `FormHelperText` for `helperTextToDisplay`
-- `error={status === 'error'}` on `FormControl`
-
-### Variant: Card (`variant === 'card'`)
-
-Render a heading (`<h4>`) with the `label`, then delegate to `SelectableCard` component:
-
-```
-<div>
-  <h4 style={{ marginTop: 0, marginBottom: 0 }}>{label}</h4>
-  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(min(200px, 100%), 1fr))', gap: '1rem' }}>
-    <SelectableCard
-      type='radio'
-      dataSource={datasource}
-      recordKey={stateProps.value?.split('.').pop()}
-      cardLabel={stateProps.primaryField?.split('.').pop()}
-      radioBtnValue={value}
-      onChange={handleChange}
-      image={{ imagePosition, imageSize, showImageDescription, imageField, imageDescription }}
-      setIsRadioCardSelected={displayMode !== 'DISPLAY_ONLY' ? setSelectedButton : undefined}
-      hideFieldLabels={hideFieldLabels}
-      additionalProps={additionalProps}
-      getPConnect={getPConnect}
-    />
-  </div>
-</div>
-```
-
-- `imageField`: `stateProps.image?.split('.').pop()`
-- `imageDescription`: `stateProps.imageDescription?.split('.').pop()`
-
-## Display Mode Rendering
-
-Both modes render the localized display label of the selected option:
-
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedValue} />`
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedValue} variant='stacked' />`
-
-Where `localizedValue = pConn.getLocalizedValue(value, localePath, localeRuleName)`.
-
-## Visual Specifications
-
-### Standard Variant
-
-| Property            | Value                                                                |
-| ------------------- | -------------------------------------------------------------------- |
-| Layout              | Vertical stack (or horizontal row when `inline=true`)                |
-| Radio indicator     | Circle button with filled inner circle when selected                 |
-| Label               | Label text to the right of the radio button (`labelPlacement='end'`) |
-| Group label         | `<legend>` / `<FormLabel>` above the group                           |
-| Error state         | Group border or text in red                                          |
-| Helper text         | Below the group                                                      |
-| Disabled (readOnly) | Greyed-out radio buttons, not-allowed cursor                         |
-
-**CSS-only notes:**
-
-```css
-.radio-group {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-}
-.radio-group.inline {
-  flex-direction: row;
-  flex-wrap: wrap;
-  gap: 8px;
-}
-.radio-label {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  cursor: pointer;
-}
-input[type='radio']:disabled {
-  opacity: 0.38;
-  cursor: default;
-}
-```
-
-### Card Variant
-
-| Property | Value                                                                   |
-| -------- | ----------------------------------------------------------------------- |
-| Layout   | CSS Grid: `repeat(auto-fit, minmax(min(200px, 100%), 1fr))`, gap `1rem` |
-| Card     | Elevated card with click handler that activates the radio               |
-| Heading  | `<h4>` with `marginTop: 0, marginBottom: 0` above grid                  |
-
-## Edge Cases & Special Logic
-
-- `theOptions` is loaded synchronously from `Utils.getOptionList()` on every render — no async fetching.
-- `theSelectedButton` tracks the selected key locally and syncs from `value` prop via `useEffect`.
-- Card variant uses `setIsRadioCardSelected` callback to inform parent when a radio card is selected.
-
-## Dependencies
-
-- `Utils.getOptionList()` from `../../helpers/utils`.
-- `handleEvent` from `../../helpers/event-utils`.
-- `getComponentFromRegistry('FieldValueList')` for display modes.
-- `getComponentFromRegistry('SelectableCard')` for card variant.
-
-## Design System Mapping
-
-**UI control type:** Radio button group (single selection).
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                        |
-| ------------------ | ------------------------------------------------------------ |
-| Default (CSS only) | `<input type="radio">` with `<label>` per option             |
-| MUI                | `<RadioGroup>` with `<FormControlLabel control={<Radio />}>` |
-| Ant Design         | `<Radio.Group>` with `<Radio>` options                       |
-| Chakra UI          | `<RadioGroup>` with `<Radio>` items                          |

package/templates/react-sdk-reference/.github/skills/field-skills/RichText.md

@@ -1,149 +0,0 @@
-# Skill: RichText
-
-Rich text editor field with HTML content support, binds to a Pega case property.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Renders a rich text (WYSIWYG) editor for HTML content. Uses a registry-resolved `RichTextEditor` component. Handles both read-only and editable states. Commits HTML content on blur by reading from the editor's internal ref.
-
-## Pega Metadata
-
-- **Pega Name:** `RichText`
-- **Type / Subtype:** `Field` / `Text-RichText`
-- **Registration key:** `RichText` (in `component-map.ts`)
-
-## Props (component-specific)
-
-| Prop              | Type                | Description                                   |
-| ----------------- | ------------------- | --------------------------------------------- |
-| `additionalProps` | `object` (optional) | Extra props forwarded to the `RichTextEditor` |
-
-## Behavioral Contract
-
-1. **Editor ref:** Maintain an `editorRef` (via `useRef`) — the editor exposes its content via `editorRef.current.getContent({ format: 'html' })`.
-2. **No local state** — unlike text inputs, value is NOT tracked in local state. The editor manages its own internal content via `defaultValue`.
-3. **Props coercion:** `readOnly`, `required`, `disabled` must be coerced to booleans:
-   ```typescript
-   [readOnly, required, disabled] = [readOnly, required, disabled].map(
-     (prop) => prop === true || (typeof prop === 'string' && prop === 'true'),
-   );
-   ```
-4. **Editable mode:**
-   - Track `status` for error state.
-   - **On change:** If `status === 'error'`, clear error messages via:
-     ```
-     pConn.clearErrorMessages({ property, category: '', context: '' })
-     ```
-   - **On blur:** Read HTML from editor ref and commit:
-     ```
-     const editorValue = editorRef.current.getContent({ format: 'html' })
-     handleEvent(actionsApi, 'changeNblur', property, editorValue)
-     ```
-5. **Read-only mode:** Render `RichTextEditor` with `readOnly` prop only — no `onChange`/`onBlur`.
-6. **`RichTextEditor` component:** Resolved via `getComponentFromRegistry('RichTextEditor')`. This is a design-system extension component that wraps the actual WYSIWYG library (e.g., TinyMCE).
-
-### Editable RichTextEditor props
-
-```
-label, labelHidden={hideLabel}, info={helperTextToDisplay}, defaultValue={value},
-placeholder, disabled, required, testId, ref={editorRef},
-error={status === 'error'}, onBlur={handleBlur}, onChange={handleChange}
-```
-
-### Read-only RichTextEditor props
-
-```
-label, labelHidden={hideLabel}, defaultValue={value}, testId, info={helperTextToDisplay},
-ref={editorRef}, readOnly
-```
-
-## Display Mode Rendering
-
-Display modes pass `isHtml={true}` to render HTML content safely:
-
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml />`
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml variant='stacked' />`
-
-## Read-Only Rendering
-
-Render `RichTextEditor` with `readOnly` prop. Uses same `editorRef`.
-
-## Visual Specifications
-
-The visual appearance of the rich text editor depends on the underlying `RichTextEditor` implementation. The reference implementation uses TinyMCE theming via CSS variables:
-
-```css
-/* RichText.css — must be imported */
-.tox .tox-toolbar {
-  background-color: var(--app-background-color) !important;
-}
-.tox .tox-toolbar__primary {
-  background-color: var(--app-background-color) !important;
-}
-.tox .tox-toolbar__button {
-  color: var(--app-text-color) !important;
-}
-.tox .tox-toolbar__button--enabled {
-  background: var(--app-primary-color) !important;
-  color: #fff !important;
-}
-.tox .tox-dialog {
-  background-color: var(--modal-top-color) !important;
-  color: var(--app-text-color) !important;
-  border: 1px solid var(--modal-border-color) !important;
-  padding: 20px !important;
-  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color) !important;
-}
-.tox .tox-dialog__header {
-  background-color: var(--modal-top-color) !important;
-  color: var(--app-text-color) !important;
-  font-weight: 500;
-  border-bottom: 1px solid var(--modal-border-color);
-}
-```
-
-**Note:** Import `./RichText.css` in the component file. The CSS variables (`--app-background-color`, `--app-text-color`, etc.) are set by the application theme.
-
-When implementing with a different design system:
-
-- Custom CSS for toolbar theming may be needed
-- The editor container should be full-width
-- Minimum height: ~200px for a usable editing area
-
-## Edge Cases & Special Logic
-
-- **Props coercion to boolean:** Pega may pass these props as strings (`'true'`/`'false'`) — always coerce.
-- **On blur, NOT on change:** Content is committed to the store only on blur (when user leaves the editor), not on every keystroke.
-- **Error clearing:** When `status === 'error'`, the `onChange` handler clears the error message from Pega so it doesn't persist after the user starts editing.
-- **`editorRef.current.getContent`:** This is specific to the TinyMCE API. For other rich text libraries, use the equivalent method to get HTML content.
-- **`FieldValueList` with `isHtml`:** The display mode renders HTML — ensure XSS protection in the `FieldValueList` component (use `dangerouslySetInnerHTML` only with sanitization, or a trusted HTML renderer).
-
-## Dependencies
-
-- `getComponentFromRegistry('RichTextEditor')` — the actual editor widget (e.g., TinyMCE wrapper).
-- `getComponentFromRegistry('FieldValueList')` for display modes.
-- `handleEvent` from `../../helpers/event-utils`.
-- `./RichText.css` — must be imported for TinyMCE toolbar theming.
-- `useRef` from React.
-
-**For other rich text editors:**
-
-- Any WYSIWYG editor that exposes `ref.current.getContent()` or equivalent.
-- Examples: Quill, Draft.js, Slate.js, CKEditor.
-
-## Design System Mapping
-
-**UI control type:** WYSIWYG rich text editor (HTML content).
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                             |
-| ------------------ | ------------------------------------------------- |
-| Default (CSS only) | `contenteditable` div + custom toolbar OR TinyMCE |
-| MUI                | `RichTextEditor` custom extension (TinyMCE)       |
-| Ant Design         | Quill or TinyMCE with Ant styling                 |
-| Chakra UI          | Quill or TipTap with Chakra styling               |

package/templates/react-sdk-reference/.github/skills/field-skills/ScalarList.md

@@ -1,134 +0,0 @@
-# Skill: ScalarList
-
-Read-only display component that renders a list of scalar values by creating a child component for each item.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Renders a list of scalar (primitive) values by dynamically creating a child component of a specified type for each item. Used for read-only display of list-type properties. Not an editable input.
-
-## Pega Metadata
-
-- **Pega Name:** `ScalarList`
-- **Type / Subtype:** `Field` / `ScalarList`
-- **Registration key:** `ScalarList` (in `component-map.ts`)
-
-## Props (component-specific)
-
-> ScalarList uses `PConnProps` (NOT `PConnFieldProps`) because its `value` is an array, not a string:
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-```
-
-| Prop             | Type      | Description                                                                  |
-| ---------------- | --------- | ---------------------------------------------------------------------------- |
-| `value`          | `any[]`   | Array of scalar values to display                                            |
-| `componentType`  | `string`  | The Pega component type to use for each item (e.g., `'TextInput'`, `'Date'`) |
-| `label`          | `string`  | Field label                                                                  |
-| `displayMode`    | `string`  | Display mode                                                                 |
-| `hideLabel`      | `boolean` | Whether to hide the label                                                    |
-| `displayInModal` | `boolean` | Whether this is displayed in a modal context                                 |
-
-All remaining props (`...restProps`) are forwarded to each child component.
-
-## Behavioral Contract
-
-1. **No state, no event handling** — purely display/read-only.
-2. **Item rendering:** Map each value in `scalarValues` to a component via `getPConnect().createComponent(...)`:
-   ```typescript
-   const items = scalarValues?.map((scalarValue) =>
-     getPConnect().createComponent(
-       {
-         type: componentType,
-         config: {
-           value: scalarValue,
-           displayMode: 'DISPLAY_ONLY',
-           label,
-           ...restProps,
-           readOnly: 'true',
-         },
-       },
-       '', // 2nd arg: empty string
-       '', // 3rd arg: empty string
-       {}, // 4th arg: empty object
-     ),
-   );
-   ```
-3. **`CommaSeparatedList` sub-component:** A local component that renders items as `<span>` elements inside a `<ul>` with no list styling:
-   ```html
-   <ul style="padding: 0; margin: 0;">
-     <span>item1</span>
-     <span>item2</span>
-     ...
-   </ul>
-   ```
-
-## Display Mode Rendering
-
-**`STACKED_LARGE_VAL` or `DISPLAY_ONLY`:**
-
-```html
-<div>
-  <CommaSeparatedList items="{items}" />
-</div>
-```
-
-No `FieldValueList` wrapper in these modes — the items are rendered directly.
-
-**Default (no display mode):**
-
-```
-<FieldValueList name={hideLabel ? '' : label} value={<CommaSeparatedList items={items} />} variant='stacked' />
-```
-
-## Visual Specifications
-
-| Property     | Value                                                             |
-| ------------ | ----------------------------------------------------------------- |
-| List style   | No bullets, no padding, no margin on `<ul>`                       |
-| Item display | Each item rendered as `<span>` (inline)                           |
-| Separator    | Items are adjacent spans (no comma separator despite the name)    |
-| Layout       | Vertical stack when wrapped in `FieldValueList variant='stacked'` |
-
-**CSS-only notes:**
-
-```css
-.scalar-list {
-  list-style: none;
-  padding: 0;
-  margin: 0;
-}
-.scalar-list-item {
-  display: inline;
-}
-```
-
-## Edge Cases & Special Logic
-
-- `scalarValues` may be `undefined` — the `?.map()` safely returns `undefined`; ensure null-check before rendering.
-- Each child component is created with `displayMode: 'DISPLAY_ONLY'` and `readOnly: 'true'` (as string) — the read-only is passed as a string, not boolean.
-- `restProps` includes all remaining props from the parent beyond the destructured ones — these are forwarded to each child component config.
-- `createComponent` takes 4 args — 2nd, 3rd, 4th are empty string/object as the typedef marks them optional.
-
-## Dependencies
-
-- `getComponentFromRegistry('FieldValueList')` for default display.
-- `getPConnect().createComponent()` — for creating each child component.
-- No `handleEvent` — read-only component.
-
-## Design System Mapping
-
-**UI control type:** Read-only list of scalar values.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                      |
-| ------------------ | ---------------------------------------------------------- |
-| Default (CSS only) | `<ul>` with `<span>` items                                 |
-| MUI                | `<List>` with `<ListItem>` or just `<Typography>` per item |
-| Ant Design         | `<List>` items or `<Space>` with `<Tag>`                   |
-| Chakra UI          | `<List>` or `<HStack>` with `<Tag>`                        |

package/templates/react-sdk-reference/.github/skills/field-skills/SelectableCard.md

@@ -1,231 +0,0 @@
-# Skill: SelectableCard
-
-Card-style radio or checkbox selection grid with optional image support.
-
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
-
----
-
-## Component Purpose
-
-Renders a grid of selectable cards. Each card contains a radio button or checkbox (depending on `type`), a label, optional image, and optional additional fields. Cards are clickable — clicking anywhere on the card triggers the input. Used by `RadioButtons` (variant='card') and `Checkbox` (variant='card').
-
-## Pega Metadata
-
-- **Pega Name:** `SelectableCard`
-- **Type / Subtype:** Internal design system extension
-- **Registration key:** `SelectableCard` (in `component-map.ts`)
-
-> This component does NOT have a `config-ext.json` and does NOT extend `PConnFieldProps` — it's a design system component used internally by `RadioButtons` and `Checkbox`.
-
-## Props
-
-| Prop                     | Type                    | Default | Description                                                                        |
-| ------------------------ | ----------------------- | ------- | ---------------------------------------------------------------------------------- |
-| `getPConnect`            | `function`              | —       | PConnect accessor                                                                  |
-| `type`                   | `'radio' \| 'checkbox'` | —       | Selection type                                                                     |
-| `image`                  | `object`                | —       | `{ imagePosition, imageSize, showImageDescription, imageField, imageDescription }` |
-| `dataSource`             | `any`                   | —       | Source of card data (in editable mode)                                             |
-| `recordKey`              | `string`                | `''`    | The key field name in each record (e.g., `'pyID'`)                                 |
-| `className`              | `string`                | —       | CSS class for the card                                                             |
-| `cardLabel`              | `string`                | —       | The field name to use as card title                                                |
-| `hideFieldLabels`        | `boolean`               | `false` | Hide field labels inside cards                                                     |
-| `readOnly`               | `boolean`               | —       | Read-only mode                                                                     |
-| `disabled`               | `boolean`               | —       | Disabled state                                                                     |
-| `readOnlyList`           | `any[]`                 | `[]`    | Selected items for read-only display                                               |
-| `displayMode`            | `string`                | —       | Display mode string                                                                |
-| `radioBtnValue`          | `any`                   | —       | Currently selected value (radio mode)                                              |
-| `onChange`               | `function`              | —       | Change handler                                                                     |
-| `onBlur`                 | `function`              | —       | Blur handler                                                                       |
-| `onClick`                | `function`              | —       | Click handler                                                                      |
-| `onKeyDown`              | `function`              | —       | KeyDown handler                                                                    |
-| `additionalProps`        | `any`                   | —       | Spread onto the radio/checkbox input                                               |
-| `testId`                 | `string`                | —       | Test identifier                                                                    |
-| `setIsRadioCardSelected` | `function`              | —       | Callback to inform parent whether radio selection matched                          |
-| `showNoValue`            | `boolean`               | `false` | When true (read-only + no selected items), render "No Value" text                  |
-
-## Behavioral Contract
-
-### Data source selection
-
-```
-cardDataSource = (readOnly || displayMode === 'DISPLAY_ONLY')
-  ? readOnlyList || []
-  : dataSource?.source
-```
-
-### "No Value" guard
-
-If `showNoValue`: render a plain text element showing `'No Value'` and return early.
-
-### Card click handler
-
-Cards should be clickable anywhere (not just on the checkbox/radio):
-
-```typescript
-const handleCardClick = (event) => {
-  if (disabled || readOnly) return;
-  if (event.target.closest('label, input')) return; // native click already handled
-  const input = event.currentTarget.querySelector('input[type="radio"], input[type="checkbox"]');
-  if (input) input.click();
-};
-```
-
-### Subsection: Display mode (`displayMode === 'DISPLAY_ONLY'`)
-
-Render a **simple read-only card** (no radio/checkbox) with:
-
-- Optional image (`<img>`)
-- Card title: `item[cardLabel]`
-- Additional resolved fields (from `resolveReferenceFields`)
-- `style: { display: 'flex' }`
-
-```html
-<Card style="display: flex">
-  {image && <img src="..." alt="..." style="width: 100px" />}
-  <CardContent>
-    <body1>{item[cardLabel]}</body1>
-    {fields.map(field => <body2>{field.value}</body2>)}
-  </CardContent>
-</Card>
-```
-
-### Subsection: Editable mode (radio or checkbox)
-
-Render a **selectable card** with click handler, containing the appropriate input:
-
-```html
-<div style="paddingTop: 15px">
-  <Card style="cursor: pointer, height: 100%, flexDirection: column"
-        onClick={handleCardClick}>
-    <CardContent style={imageLayoutStyle}>
-      <!-- Image section (40% width for inline positions) -->
-      {image && <img full-width, aspect-ratio 16/9, contain>}
-      <!-- Content section (60% width for inline positions) -->
-      {type === 'radio'
-        ? <FormControlLabel control={<Radio value={item[recordKey]} checked={radioBtnValue === item[recordKey]} onChange={onChange} ... />} label={item[cardLabel]}>
-        : <FormControlLabel control={<Checkbox id={item[recordKey]} checked={readOnlyList.some(d => d[recordKey] === item[recordKey])} onChange={onChange} ... />} label={item[cardLabel]}>
-      }
-      {fields.map(field => <div style={fieldLayoutStyle}>{field.name && <div>{field.name}</div>}<div>{field.value}</div></div>)}
-    </CardContent>
-  </Card>
-</div>
-```
-
-### Image layout (inline positions)
-
-| `imagePosition`  | CardContent style                           | Image section width | Content section width |
-| ---------------- | ------------------------------------------- | ------------------- | --------------------- |
-| `'inline-start'` | `display: flex`                             | 40%                 | 60%                   |
-| `'inline-end'`   | `display: flex, flexDirection: row-reverse` | 40%                 | 60%                   |
-| block (default)  | default                                     | full width          | full width            |
-
-### Image element
-
-```css
-img {
-  width: 100%;
-  background-color: transparent;
-  aspect-ratio: 16 / 9;
-  max-height: 100%;
-  height: 100%;
-  object-fit: contain;
-  max-width: 100%;
-}
-```
-
-### Field display layout
-
-Each additional field in editable mode:
-
-```css
-.card-field {
-  font-size: 0.875rem;
-  display: grid; /* only if type !== 'TextArea' */
-  grid-template-columns: 1fr 1fr;
-  margin: 5px;
-}
-```
-
-### Radio tracking
-
-After iterating cards, if `type === 'radio'` and `setIsRadioCardSelected`:
-
-```
-if (radioBtnValue === item[recordKey]) radioItemSelected = true
-// After loop:
-setIsRadioCardSelected(radioItemSelected)
-```
-
-## Display Mode Rendering
-
-`displayMode === 'DISPLAY_ONLY'`: renders simple read-only cards (no radio/checkbox inputs). Uses `readOnlyList` as the data source.
-
-## Visual Specifications
-
-| Property             | Editable card                                    | Display-only card |
-| -------------------- | ------------------------------------------------ | ----------------- |
-| Cursor               | `pointer` (unless disabled/readOnly → `default`) | Default           |
-| Height               | `100%` (fills grid row)                          | Auto              |
-| Layout               | Column flex                                      | Row flex          |
-| Padding top          | 15px wrapper                                     | —                 |
-| Image (display-only) | 100px fixed width                                | 100px fixed width |
-| Card border          | Default (design-system card elevation)           | Default           |
-| Disabled             | `cursor: default`                                | —                 |
-
-**CSS-only card implementation:**
-
-```css
-.selectable-card {
-  border: 1px solid rgba(0, 0, 0, 0.12);
-  border-radius: 4px;
-  padding: 16px;
-  cursor: pointer;
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  margin-top: 15px;
-  transition: border-color 0.2s;
-}
-.selectable-card:hover {
-  border-color: #1976d2;
-}
-.selectable-card.disabled {
-  cursor: default;
-  opacity: 0.7;
-}
-.selectable-card.readonly {
-  cursor: default;
-}
-.selectable-card-label {
-  font-size: 1rem;
-  font-weight: 400;
-}
-```
-
-## Edge Cases & Special Logic
-
-- **`resolveReferenceFields(item, hideFieldLabels, recordKey, pConn)`** — local utility that resolves additional display fields from an item record.
-- Checkbox `id={item[recordKey]}` — required for the card click handler to find and click the input by ID.
-- `getPConnect` prop on Checkbox (MUI): passed through to support `@pega/sdk-react` checkbox augmentation (non-standard MUI prop).
-- `imageDescriptionKey = showImageDescription ? imageDescription : undefined` — only show alt text when `showImageDescription` is true.
-
-## Dependencies
-
-- `resolveReferenceFields` from `./utils` (local utility).
-- Radio/Checkbox + FormControlLabel components.
-- Card/CardContent components.
-- Typography/text component.
-
-## Design System Mapping
-
-**UI control type:** Selectable card grid (radio or multi-select).
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                      |
-| ------------------ | -------------------------------------------------------------------------- |
-| Default (CSS only) | Custom `<div>` cards with `<input type="radio/checkbox">` inside           |
-| MUI                | `<Card>` + `<CardContent>` + `<FormControlLabel>` + `<Radio>`/`<Checkbox>` |
-| Ant Design         | Custom cards with `<Radio>`/`<Checkbox>`                                   |
-| Chakra UI          | `<Box>` as card + `<Radio>`/`<Checkbox>`                                   |