@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.ai-common/skills/field-skills/CancelAlert.md

@@ -0,0 +1,340 @@
+# Skill: CancelAlert
+
+Cancel confirmation dialog that offers the user a choice between going back or discarding/deleting the current case/action.
+
+> **Note:** This component extends `PConnFieldProps` for registry compatibility but does **not** use standard field patterns (no `displayMode`, no `handleEvent`, no value binding). It is an internal modal dialog.
+
+---
+
+## Component Purpose
+
+Renders a full-screen modal overlay with a confirmation dialog. Presents two actions: "Go back" (continue working) and "Discard" (cancel/delete). Handles different cancellation scenarios: standard case creation stage, local action, bulk action, data object, and reverse coexistence. Shows a snackbar notification on delete failure.
+
+## Pega Metadata
+
+- **Pega Name:** `CancelAlert`
+- **Type / Subtype:** Internal modal/alert
+- **Registration key:** `CancelAlert` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop                     | Type       | Description                                                                              |
+| ------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
+| `heading`                | `string`   | Modal dialog heading text                                                                |
+| `content`                | `string`   | Modal dialog body/description text                                                       |
+| `itemKey`                | `string`   | The container item ID for the case being cancelled (aliased as `containerItemID`)        |
+| `hideDelete`             | `boolean`  | Whether to hide/disable the delete option                                                |
+| `isDataObject`           | `boolean`  | Whether this is cancelling a data object (not a work item)                               |
+| `skipReleaseLockRequest` | `any`      | Whether to skip lock release when removing container item                                |
+| `dismiss`                | `Function` | Callback to close/dismiss this dialog (called with `true` to indicate confirmed dismiss) |
+
+## Component Skeleton
+
+Follow this exact structure when implementing. Replace modal/button/snackbar components with equivalents from your chosen design system.
+
+```typescript
+import { useState } from 'react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import './CancelAlert.css';
+
+// ── Props interface ──────────────────────────────────────────
+interface CancelAlertProps extends PConnFieldProps {
+  heading: string;
+  content: string;
+  itemKey: string;
+  hideDelete: boolean;
+  isDataObject: boolean;
+  skipReleaseLockRequest: any;
+  dismiss: Function;
+}
+
+// ── Component ────────────────────────────────────────────────
+export default function CancelAlert(props: CancelAlertProps) {
+  // 1. Destructure props (note: itemKey aliased to containerItemID)
+  const {
+    heading, content, getPConnect,
+    itemKey: containerItemID,
+    hideDelete, isDataObject, skipReleaseLockRequest, dismiss,
+  } = props;
+
+  // 2. PConnect APIs
+  const actionsAPI = getPConnect().getActionsApi();
+  const containerManagerAPI = getPConnect().getContainerManager();
+  const isLocalAction = getPConnect().getValue(
+    PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION
+  );
+  // @ts-ignore - Property 'options' is private
+  const isBulkAction = getPConnect()?.options?.isBulkAction;
+
+  // 3. Localization setup
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const localeCategory = 'ModalContainer';
+
+  // 4. Coexistence setup
+  const broadCastUtils: any = PCore.getCoexistenceManager().getBroadcastUtils();
+  const isReverseCoexistence = broadCastUtils.isReverseCoexistenceCaseLoaded();
+
+  // 5. Button ID constants
+  const btnIds = {
+    SAVE_AND_CLOSE: 'saveAndClose',
+    CONTINUE_WORKING: 'continueWorking',
+    DELETE: 'delete',
+  };
+
+  // 6. State
+  const [buttonsState, setButtonsState] = useState({
+    [btnIds.SAVE_AND_CLOSE]: false,
+    [btnIds.DELETE]: false,
+  });
+  const [showSnackbar, setShowSnackbar] = useState(false);
+  const [snackbarMessage, setSnackbarMessage] = useState('');
+
+  // 7. Button enable/disable helpers
+  function disableButton(id) {
+    setButtonsState(prev => ({ ...prev, [id]: true }));
+  }
+  function enableButton(id) {
+    setButtonsState(prev => ({ ...prev, [id]: false }));
+  }
+
+  // 8. cancelHandler — see Behavioral Contract "Discard" section
+  function cancelHandler() { /* decision tree */ }
+
+  // 9. handleSnackbarClose — see Behavioral Contract
+  function handleSnackbarClose(event, reason?) {
+    if (reason === 'clickaway') return;
+    setShowSnackbar(false);
+  }
+
+  // 10. Build leftButton ("Go back") and rightButton ("Discard") JSX
+  //     leftButton: onClick → dismiss(), plus reverse coexistence cleanup
+  //     rightButton: onClick → cancelHandler(), disabled={buttonsState[btnIds.DELETE]}
+  //     All button text wrapped in localizedVal(text, localeCategory)
+
+  // 11. Return: overlay div + dialog box + snackbar
+  //     See Visual Specifications for layout and CSS classes
+  return (
+    <>
+      <div className="cancel-alert-background">
+        <div className="cancel-alert-top">
+          <h3>{localizedVal(heading, localeCategory)}</h3>
+          <div><p>{localizedVal(content, localeCategory)}</p></div>
+          <div className="action-controls">
+            {/* Two buttons: Go back (secondary) | Discard (primary) */}
+          </div>
+        </div>
+      </div>
+      {/* Snackbar: open={showSnackbar}, autoHideDuration=3000, message={snackbarMessage} */}
+    </>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Setup
+
+```typescript
+// PConnect APIs
+const actionsAPI = getPConnect().getActionsApi();
+const containerManagerAPI = getPConnect().getContainerManager();
+const isLocalAction = getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION);
+// @ts-ignore - Property 'options' is private and only accessible within class 'C11nEnv'
+const isBulkAction = getPConnect()?.options?.isBulkAction;
+
+// Localization
+const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+const localeCategory = 'ModalContainer';
+
+// Coexistence (store broadCastUtils — reused in Go back handler)
+const broadCastUtils: any = PCore.getCoexistenceManager().getBroadcastUtils();
+const isReverseCoexistence = broadCastUtils.isReverseCoexistenceCaseLoaded();
+
+// Button IDs (used as keys in buttonsState)
+const btnIds = {
+  SAVE_AND_CLOSE: 'saveAndClose',
+  CONTINUE_WORKING: 'continueWorking',
+  DELETE: 'delete',
+};
+```
+
+### State
+
+- `buttonsState`: tracks disabled state per button: `{ [btnIds.SAVE_AND_CLOSE]: false, [btnIds.DELETE]: false }`
+- `showSnackbar`: boolean — whether to show the failure snackbar
+- `snackbarMessage`: string — error message text
+
+### Helper Functions
+
+```typescript
+function disableButton(id) {
+  setButtonsState((prev) => ({ ...prev, [id]: true }));
+}
+function enableButton(id) {
+  setButtonsState((prev) => ({ ...prev, [id]: false }));
+}
+```
+
+### "Go back" button (`leftButton`)
+
+Always calls `dismiss()` (no argument = don't confirm). If `isReverseCoexistence`:
+
+```
+broadCastUtils.setCallBackFunction(null)
+broadCastUtils.setIsDirtyDialogActive(false)
+```
+
+### "Discard" button (`rightButton`) — `cancelHandler()`
+
+Decision tree (evaluated in order):
+
+1. **Reverse coexistence:**
+
+   ```
+   dismiss(true)
+   PCore.getPubSubUtils().publish(REVERSE_COEXISTENCE_EVENTS.HANDLE_DISCARD)
+   ```
+
+2. **Standard case in create stage** (`!isDataObject && !isLocalAction && !isBulkAction`):
+   - Disable delete button
+   - Call `actionsAPI.deleteCaseInCreateStage(containerItemID, hideDelete)`
+   - `.then()`: publish `EVENT_CANCEL`
+   - `.catch()`: show snackbar with `'Delete failed.'`
+   - `.finally()`: re-enable delete button, call `dismiss(true)`
+
+3. **Local action** (`isLocalAction`):
+
+   ```
+   dismiss(true)
+   actionsAPI.cancelAssignment(containerItemID, false)
+   ```
+
+4. **Bulk action** (`isBulkAction`):
+
+   ```
+   dismiss(true)
+   actionsAPI.cancelBulkAction(containerItemID)
+   ```
+
+5. **Data object or other** (default):
+   ```
+   dismiss(true)
+   containerManagerAPI.removeContainerItem({ containerItemID, skipReleaseLockRequest })
+   ```
+
+### Snackbar dismissal
+
+`handleSnackbarClose`: if `reason === 'clickaway'`, return (do not close). Otherwise `setShowSnackbar(false)`.
+
+### Localization
+
+All visible text is localized via `PCore.getLocaleUtils().getLocaleValue(key, 'ModalContainer')`:
+
+- `'Go back'`
+- `'Discard'`
+- `heading` prop value
+- `content` prop value
+- `'Delete failed.'`
+
+## Visual Specifications
+
+Derived from `CancelAlert.css`:
+
+### Full-screen overlay (`.cancel-alert-background`)
+
+```css
+.cancel-alert-background {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  height: 100%;
+  width: 100%;
+  background-color: var(--modal-background-color);
+  position: fixed;
+  z-index: 9999;
+  top: 0;
+  left: 0;
+}
+```
+
+### Dialog box (`.cancel-alert-top`)
+
+```css
+.cancel-alert-top {
+  display: table;
+  margin: auto;
+  min-width: 550px;
+  background-color: var(--modal-top-color);
+  border: 1px solid var(--modal-border-color);
+  border-radius: 10px;
+  padding: 20px;
+  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color);
+}
+```
+
+### Content layout
+
+```
+.cancel-alert-top
+  <h3>{heading}</h3>
+  <div>
+    <p>{content}</p>
+  </div>
+  <div class="action-controls">
+    Grid container spacing=4, justifyContent='space-between'
+      Grid → leftButton ("Go back", secondary/outlined)
+      Grid → rightButton ("Discard", primary/contained, can be disabled)
+```
+
+### Button styles
+
+| Button  | Style     | Color     |
+| ------- | --------- | --------- |
+| Go back | Contained | Secondary |
+| Discard | Contained | Primary   |
+
+### Snackbar
+
+- `autoHideDuration: 3000ms`
+- Shows `snackbarMessage` (e.g., `'Delete failed.'`)
+- Close icon button to dismiss manually
+
+**CSS variables used:**
+
+- `--modal-background-color`: semi-transparent overlay (e.g., `rgba(0,0,0,0.5)`)
+- `--modal-top-color`: dialog background (e.g., white or app background)
+- `--modal-border-color`: dialog border
+- `--modal-box-shadow-color`: dialog shadow color
+
+**CSS companion file required:** Import `./CancelAlert.css`.
+
+## Edge Cases & Special Logic
+
+- **`buttonsState`** tracks loading state to prevent double-clicks during async delete.
+- `dismiss(true)` vs `dismiss()`: passing `true` signals confirmed cancellation; no arg means the user chose to continue.
+- `isBulkAction` is accessed via `getPConnect()?.options?.isBulkAction` — a private property, marked with `@ts-ignore`.
+- All action handling is async — the UI must show loading/disabled state during `deleteCaseInCreateStage`.
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue()` — for text localization.
+- `PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION`, `PUB_SUB_EVENTS.EVENT_CANCEL`, etc.
+- `PCore.getPubSubUtils().publish()` — for pub/sub events.
+- `PCore.getCoexistenceManager().getBroadcastUtils()` — for reverse coexistence handling.
+- Button, Grid, IconButton, Snackbar components.
+- Close icon.
+- `./CancelAlert.css` — must be imported.
+
+## Design System Mapping
+
+**UI control type:** Full-screen modal confirmation dialog.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| Default (CSS only) | `<div class="cancel-alert-background">` + `<div class="cancel-alert-top">` + CSS from above |
+| MUI                | `<Button>`, `<Grid>`, `<Snackbar>`, `<IconButton>`, fixed overlay `<div>`                   |
+| Ant Design         | `<Modal>` or custom overlay                                                                 |
+| Chakra UI          | `<Modal>` or `<AlertDialog>`                                                                |

package/templates/react-sdk-reference/.ai-common/skills/field-skills/Checkbox.md

@@ -0,0 +1,358 @@
+# Skill: Checkbox
+
+Checkbox field supporting single boolean toggle, multi-selection mode, and optional card-style variant.
+
+> **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 one or more checkboxes. Supports three usage modes: (1) a single boolean checkbox, (2) a multi-select list of checkboxes bound to a reference list, and (3) a card-style selectable grid. Display mode shows the true/false label rather than the raw boolean.
+
+## Pega Metadata
+
+- **Pega Name:** `Checkbox`
+- **Type / Subtype:** `Field` / `Boolean`
+- **Registration key:** `Checkbox` (mapped to `CheckboxComponent` import in `component-map.ts`)
+
+## Props (component-specific)
+
+> Note: `Checkbox` uses `Omit<PConnFieldProps, 'value'>` with its own `value?: boolean`. Import type as:
+>
+> ```typescript
+> import type { PConnFieldProps } from '@pega/sdk-react';
+> ```
+
+| Prop                   | Type                 | Description                                                          |
+| ---------------------- | -------------------- | -------------------------------------------------------------------- |
+| `value`                | `boolean` (optional) | Checked state for single-mode checkbox                               |
+| `caption`              | `string` (optional)  | Label shown next to the single checkbox (not the group label)        |
+| `trueLabel`            | `string` (optional)  | Display text when `value` is `true` (used in display modes)          |
+| `falseLabel`           | `string` (optional)  | Display text when `value` is `false` (used in display modes)         |
+| `selectionMode`        | `string` (optional)  | `'multi'` — enables multi-selection mode from a datasource list      |
+| `datasource`           | `any` (optional)     | Options source for multi/card modes                                  |
+| `selectionKey`         | `string` (optional)  | The property path used as the key in selection list                  |
+| `selectionList`        | `any` (optional)     | Property path for the reference list (multi mode)                    |
+| `primaryField`         | `string`             | Primary display field for multi/card mode                            |
+| `readonlyContextList`  | `any`                | Array of currently selected items (for multi/card read-only display) |
+| `referenceList`        | `string`             | Reference list property path                                         |
+| `variant`              | `string` (optional)  | `'card'` — renders options as selectable card grid                   |
+| `hideFieldLabels`      | `boolean`            | Hide field labels inside card variant                                |
+| `additionalProps`      | `any`                | Extra props passed to card or checkbox                               |
+| `imagePosition`        | `string`             | Card image position                                                  |
+| `imageSize`            | `string`             | Card image size                                                      |
+| `showImageDescription` | `string`             | Whether to show image description                                    |
+| `renderMode`           | `string`             | `'ReadOnly'` — sets read-only mode alongside `readOnly` prop         |
+| `image`                | `string`             | Image field path for card variant                                    |
+
+## Component Skeleton
+
+Follow this exact structure. The export name is **`CheckboxComponent`** (not `Checkbox`) to avoid collision with the design system's Checkbox widget.
+
+```typescript
+import { useState, useEffect } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import {
+  insertInstruction,
+  deleteInstruction,
+  updateNewInstuctions,
+} from '../../helpers/instructions-utils';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+// ── Props interface ──────────────────────────────────────────
+// Note: Omit 'value' from PConnFieldProps — Checkbox uses boolean, not string
+interface CheckboxProps extends Omit<PConnFieldProps, 'value'> {
+  value?: boolean;
+  caption?: string;
+  trueLabel?: string;
+  falseLabel?: string;
+  selectionMode?: string;
+  datasource?: any;
+  selectionKey?: string;
+  selectionList?: any;
+  primaryField: string;
+  readonlyContextList: any;
+  referenceList: string;
+  variant?: string;
+  hideFieldLabels: boolean;
+  additionalProps: any;
+  imagePosition: string;
+  imageSize: string;
+  showImageDescription: string;
+  renderMode: string;
+  image: string;
+}
+
+// ── Styles (design-system agnostic) ──────────────────────────
+// .checkbox-column  → display: flex, flexDirection: column
+// .selectable-card-grid → display: grid, gridTemplateColumns: repeat(auto-fit, minmax(min(100%, 40ch), 1fr)),
+//                          gridAutoRows: 1fr, gap: 0.5rem
+
+// ── Component ────────────────────────────────────────────────
+export default function CheckboxComponent(props: CheckboxProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const SelectableCard = getComponentFromRegistry('SelectableCard');
+
+  // 2. Destructure props — note alias: readonlyContextList → selectedvalues
+  const {
+    getPConnect, label, caption, value, readOnly, testId,
+    required, disabled, status, helperText, validatemessage,
+    displayMode, hideLabel, trueLabel, falseLabel,
+    selectionMode, datasource, selectionKey, selectionList,
+    primaryField, referenceList,
+    readonlyContextList: selectedvalues,
+    variant, hideFieldLabels, additionalProps,
+    imagePosition, imageSize, showImageDescription, renderMode, image,
+  } = props;
+
+  // 3. Derived flags
+  const readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. PConnect setup
+  const thePConn = getPConnect();
+  const actionsApi = thePConn.getActionsApi();
+  const propName = (thePConn.getStateProps() as any).value;
+
+  // 5. State
+  const [checked, setChecked] = useState<any>(false);
+
+  // 6. useEffect: sync checked state from value prop — deps: [value]
+  useEffect(() => { setChecked(value); }, [value]);
+
+  // 7. useEffect: init reference list on mount — deps: [thePConn]
+  //    Guard: referenceList?.length > 0 && !readOnlyMode
+  //    Calls: thePConn.setReferenceList(selectionList)
+  //           updateNewInstuctions(thePConn, selectionList)
+
+  // 8. Display mode returns (uses caption, not label!)
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} variant="stacked" />;
+  }
+
+  // 9. Event handlers — see Behavioral Contract for each variant
+
+  // 10. Branch: card variant (variant === 'card')
+  //     → see Behavioral Contract "Card" section
+  //     Return early with heading + grid + SelectableCard
+
+  // 11. Branch: multi-select (selectionMode === 'multi')
+  //     → see Behavioral Contract "Multi-select" section
+  //     Build list of checkbox controls from datasource.source
+
+  // 12. Branch: single checkbox (default)
+  //     → see Behavioral Contract "Single checkbox" section
+  //     Single FormControlLabel with checked={checked}
+
+  // 13. Main return: wrapper with group label + checkbox(es) + helper text
+  //     Error state: status === 'error'
+  //     Group label: {label}, hidden if hideLabel
+  //     Helper text: helperTextToDisplay
+  return (
+    <FormWrapper required={required} error={status === 'error'}>
+      {!hideLabel && <GroupLabel>{label}</GroupLabel>}
+      <CheckboxGroup>{/* theCheckbox from step 11 or 12 */}</CheckboxGroup>
+      <HelperText>{helperTextToDisplay}</HelperText>
+    </FormWrapper>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Common
+
+1. **Read-only determination:** `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`.
+2. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+3. **Local state:** Maintain `checked` (boolean) initialized to `false`. `useEffect` watching `[value]` → `setChecked(value)`.
+4. **Reference list init:** `useEffect` watching `[thePConn]` — if `referenceList?.length > 0 && !readOnlyMode`, call `thePConn.setReferenceList(selectionList)` and `updateNewInstuctions(thePConn, selectionList)`.
+5. **`handleCheckboxChange(event, item)`** — shared by card and internally:
+   ```
+   if (event.target.checked) {
+     insertInstruction(thePConn, selectionList, selectionKey, primaryField, item);
+   } else {
+     deleteInstruction(thePConn, selectionList, selectionKey, item);
+   }
+   thePConn.clearErrorMessages({ property: selectionList });
+   ```
+
+### Variant: Single checkbox (default)
+
+Render a single checkbox with:
+
+- `checked={checked}`
+- `onChange={!readOnly ? handleChange : undefined}`
+- `onBlur={!readOnly ? handleBlur : undefined}`
+- Label = `caption` (next to checkbox)
+- Group label = `label` (above, hidden if `hideLabel`)
+- **On change:** `handleEvent(actionsApi, 'changeNblur', propName, event.target.checked)` — passes boolean.
+- **On blur:** `pConn.getValidationApi().validate(event.target.checked)`.
+
+### Variant: Multi-select (`selectionMode === 'multi'`)
+
+Render a list of checkboxes from `datasource.source`:
+
+- Extract `dataField`: `selectionKey?.split?.('.')[1]`.
+- For each `element` in `datasource.source`:
+  - `checked`: `selectedvalues?.some?.(data => data[dataField] === element.key)`
+  - Label: `element.text ?? element.value`
+  - **On change:** `handleChangeMultiMode(event, element)`:
+    ```
+    if (event.target.checked) {
+      insertInstruction(thePConn, selectionList, selectionKey, primaryField, {
+        id: element.key,
+        primary: element.text ?? element.value,
+      });
+    } else {
+      deleteInstruction(thePConn, selectionList, selectionKey, {
+        id: element.key,
+        primary: element.text ?? element.value,
+      });
+    }
+    thePConn.clearErrorMessages({ property: selectionList, category: '', context: '' });
+    ```
+  - **On blur:** `thePConn.getValidationApi().validate(selectedvalues, selectionList)`
+  - `data-testid`: `${testId}:${element.value}`
+- Layout: vertical column (`display: flex, flexDirection: column`).
+
+### Variant: Card (`variant === 'card'`)
+
+Return early (before multi/single logic) with heading + CSS Grid + `SelectableCard`:
+
+- Build `commonProps`:
+  ```
+  const actions = thePConn.getActionsApi();
+  const commonProps = {
+    ...additionalProps,
+    className: 'standard',
+    disabled,
+    readOnly,
+    onClick: (actions as any).onClick,
+  };
+  ```
+- Grid: `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, `gridAutoRows: '1fr'`, `gap: '0.5rem'`.
+- `SelectableCard` props:
+  - `{...commonProps}`, `testId`, `displayMode`, `getPConnect`
+  - `type='checkbox'`
+  - `dataSource={datasource}`
+  - `readOnly={renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly}`
+  - `recordKey={selectionKey?.split('.').pop()}`
+  - `cardLabel={primaryField.split('.').pop()}`
+  - `readOnlyList={selectedvalues}`
+  - `hideFieldLabels={hideFieldLabels}`
+  - `showNoValue={(readOnlyMode) && selectedvalues.length === 0}`
+  - `image` config object:
+    ```
+    image={{
+      imagePosition,
+      imageSize,
+      showImageDescription,
+      imageField: image?.split('.').pop(),
+      imageDescription: (thePConn?.getRawMetadata()?.config as any)
+        .imageDescription?.split('.').pop(),
+    }}
+    ```
+  - `onChange`: stop propagation, find item from `datasource.source` by matching `item[recordKey] === e.target.id`, call `handleCheckboxChange`:
+    ```
+    onChange={(e) => {
+      e.stopPropagation();
+      const recordKey = selectionKey?.split('.').pop();
+      const selectedItem = datasource?.source?.find(
+        item => item[recordKey] === e.target.id
+      ) ?? {};
+      handleCheckboxChange(e, {
+        id: selectedItem[recordKey],
+        primary: selectedItem[recordKey],
+      });
+    }}
+    ```
+  - `onBlur`: `() => thePConn.getValidationApi().validate(selectedvalues, selectionList)`
+
+## Display Mode Rendering
+
+Display mode uses `caption` (not `label`) and shows true/false label:
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} variant='stacked' />`
+
+## Read-Only Rendering
+
+Single mode: Set `readOnly` on checkbox element; disable `onChange`/`onBlur`.
+Multi/Card mode: `readOnlyMode` flag prevents `insertInstruction`/`deleteInstruction`; cards show `readOnlyList`.
+
+## Visual Specifications
+
+### Standard / Multi-select
+
+| Property          | Value                                         |
+| ----------------- | --------------------------------------------- |
+| Checkbox size     | Default (24px)                                |
+| Label placement   | End (right of checkbox)                       |
+| Group label       | `<legend>` above group, hidden if `hideLabel` |
+| Layout            | Single: single row. Multi: vertical column    |
+| Helper text       | Below group                                   |
+| Error state       | Red text/border on helper                     |
+| Disabled/readOnly | Greyed out, pointer-events none               |
+
+**CSS-only:**
+
+```css
+.checkbox-group {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.checkbox-label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+input[type='checkbox']:disabled {
+  opacity: 0.38;
+}
+```
+
+### Card Variant
+
+| Property | Value                                                                                             |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| Layout   | CSS Grid `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, row height equal (`1fr`), gap `0.5rem` |
+| Heading  | `<h4>` with `marginTop: 0, marginBottom: 0`                                                       |
+
+## Edge Cases & Special Logic
+
+- **Export name is `CheckboxComponent`** (not `Checkbox`) to avoid collision with the design system's checkbox widget import.
+- **Display mode uses `caption`** (not `label`) for the field name. This is unique to Checkbox.
+- **`readonlyContextList`** is destructured with alias `selectedvalues` — use `selectedvalues` everywhere in the component body.
+- **`handleCheckboxChange`** (card mode): Calls `e.stopPropagation()` before processing. Finds the selected item from `datasource.source` by matching `item[recordKey] === e.target.id`.
+- `updateNewInstuctions` is called on mount to sync reference list state.
+- `clearErrorMessages` is called after every multi-select change.
+- Card variant returns early (before multi/single branch logic).
+- Multi-select `onBlur` validates with both `selectedvalues` and `selectionList` as arguments.
+
+## Dependencies
+
+- `insertInstruction`, `deleteInstruction`, `updateNewInstuctions` from `../../helpers/instructions-utils` — for multi-selection reference list management.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `getComponentFromRegistry('SelectableCard')` for card variant.
+
+## Design System Mapping
+
+**UI control type:** Single or multi-select checkbox (boolean or list).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                               |
+| ------------------ | --------------------------------------------------- |
+| Default (CSS only) | `<input type="checkbox">` with `<label>`            |
+| MUI                | `<Checkbox>` in `<FormControlLabel>`, `<FormGroup>` |
+| Ant Design         | `<Checkbox>` / `<Checkbox.Group>`                   |
+| Chakra UI          | `<Checkbox>` / `<CheckboxGroup>`                    |