@pega/sdk 0.0.1

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

@@ -0,0 +1,262 @@
+# Skill: Field Components
+
+Create or replace field components (form inputs) in the react-sdk-reference application. Field components render individual form controls that bind to Pega case properties.
+
+---
+
+## Architecture Overview
+
+```
+src/components/field/<ComponentName>/
+├── <ComponentName>.tsx      # Component implementation
+├── index.tsx                # Re-export: export { default } from './<ComponentName>'
+└── config-ext.json          # Metadata (name, label, description, type, subtype)
+```
+
+Components are registered in `src/components/component-map.ts` and resolved at runtime via `getComponentFromRegistry` from `@pega/sdk-react`.
+
+---
+
+## Props Interface
+
+All field components extend `PConnFieldProps` from `src/types/PConnProps.d.ts`:
+
+```typescript
+import type { PConnFieldProps } from '../../../types/PConnProps';
+
+interface PConnFieldProps extends PConnProps {
+  label: string; // Field label text
+  required: boolean; // Whether the field is required
+  disabled: boolean; // Whether the field is disabled
+  value?: string; // Current field value from the store
+  validatemessage: string; // Validation error message
+  status?: string; // 'error' | 'warning' | undefined
+  onChange: any; // Change handler (wired by platform)
+  onBlur?: any; // Blur handler (wired by platform)
+  readOnly: boolean; // Whether the field is read-only
+  testId: string; // Test identifier for automation
+  helperText: string; // Helper/hint text below the field
+  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL' | undefined
+  hideLabel: boolean; // Whether to hide the label
+  placeholder?: string; // Placeholder text
+}
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect; // Returns the PConnect API object
+}
+```
+
+Extend `PConnFieldProps` for component-specific additional props:
+
+```typescript
+interface MyFieldProps extends PConnFieldProps {
+  fieldMetadata?: any;
+  maxLength?: number;
+}
+```
+
+---
+
+## Implementation Pattern
+
+### Minimal Field Component Template
+
+```typescript
+import { useState, useEffect } from 'react';
+import { TextField } from '@mui/material';  // or your design system
+
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '../../../types/PConnProps';
+
+interface MyFieldProps extends PConnFieldProps {
+  // Component-specific props
+}
+
+export default function MyField(props: MyFieldProps) {
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  const {
+    getPConnect,
+    label,
+    required,
+    disabled,
+    value = '',
+    validatemessage,
+    status,
+    readOnly,
+    testId,
+    helperText,
+    displayMode,
+    hideLabel,
+    placeholder
+  } = props;
+
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  const [inputValue, setInputValue] = useState(value);
+
+  useEffect(() => {
+    setInputValue(value);
+  }, [value]);
+
+  // --- Display modes (read-only rendering) ---
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />;
+  }
+
+  // --- Event handlers ---
+  function handleChange(event) {
+    setInputValue(event?.target?.value);
+  }
+
+  function handleBlur() {
+    handleEvent(actions, 'changeNblur', propName, inputValue);
+  }
+
+  // --- Render ---
+  return (
+    <TextField
+      fullWidth
+      variant={readOnly ? 'standard' : 'outlined'}
+      helperText={helperTextToDisplay}
+      placeholder={placeholder ?? ''}
+      size='small'
+      required={required}
+      disabled={disabled}
+      onChange={handleChange}
+      onBlur={!readOnly ? handleBlur : undefined}
+      error={status === 'error'}
+      label={label}
+      value={inputValue}
+      slotProps={{
+        input: { readOnly, inputProps: { 'data-test-id': testId } }
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Event Handling
+
+Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
+
+```typescript
+import handleEvent from '../../helpers/event-utils';
+
+// Get references
+const actions = pConn.getActionsApi();
+const propName = (pConn.getStateProps() as any).value;
+
+// Options:
+handleEvent(actions, 'change', propName, value); // Update store only
+handleEvent(actions, 'blur', propName, value); // Trigger validation only
+handleEvent(actions, 'changeNblur', propName, value); // Update + validate (most common)
+```
+
+**Pattern:** Track local state with `useState`, update on user input, then call `handleEvent` on blur to commit.
+
+---
+
+## Display Modes
+
+Every field component MUST handle these `displayMode` values:
+
+| Mode                  | Behavior                                                       |
+| --------------------- | -------------------------------------------------------------- |
+| `undefined` / `null`  | Render editable form control                                   |
+| `'DISPLAY_ONLY'`      | Render read-only via `FieldValueList` (inline layout)          |
+| `'STACKED_LARGE_VAL'` | Render read-only via `FieldValueList` with `variant='stacked'` |
+
+Use `getComponentFromRegistry('FieldValueList')` to get the display component.
+
+---
+
+## Resolving Other Components
+
+Use `getComponentFromRegistry` from `@pega/sdk-react` to resolve components by name:
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+
+const FieldValueList = getComponentFromRegistry('FieldValueList');
+const TextInput = getComponentFromRegistry('TextInput');
+```
+
+This is used when:
+
+- Rendering display modes (FieldValueList)
+- Delegating to another field component (e.g., Date delegates to TextInput for readOnly)
+
+---
+
+## Registration
+
+After creating a component, register it in `src/components/component-map.ts`:
+
+```typescript
+import MyField from './field/MyField';
+
+// In the getSampleComponentMap() return object:
+{
+  ...sdkComponents,
+  // ... other fields ...
+  MyField,      // Key must match the Pega component name exactly
+}
+```
+
+---
+
+## Existing Field Components
+
+| Component       | Pega Name       | Description                                    |
+| --------------- | --------------- | ---------------------------------------------- |
+| AutoComplete    | AutoComplete    | Typeahead search field                         |
+| CancelAlert     | CancelAlert     | Cancel confirmation dialog                     |
+| Checkbox        | Checkbox        | Single checkbox with label                     |
+| Currency        | Currency        | Currency input with formatting                 |
+| Date            | Date            | Date picker (uses @mui/x-date-pickers + dayjs) |
+| DateTime        | DateTime        | Date + time picker                             |
+| Decimal         | Decimal         | Decimal number input                           |
+| Dropdown        | Dropdown        | Select/dropdown with options from data page    |
+| Email           | Email           | Email input with icon                          |
+| Group           | Group           | Field group container                          |
+| Integer         | Integer         | Integer-only input                             |
+| Location        | Location        | Google Maps location picker                    |
+| Multiselect     | Multiselect     | Multi-select dropdown                          |
+| ObjectReference | ObjectReference | Reference to another object                    |
+| Percentage      | Percentage      | Percentage input                               |
+| Phone           | Phone           | Phone input (uses mui-tel-input)               |
+| RadioButtons    | RadioButtons    | Radio button group                             |
+| RichText        | RichText        | Rich text editor (TinyMCE)                     |
+| ScalarList      | ScalarList      | List of scalar values                          |
+| SelectableCard  | SelectableCard  | Card-style selection                           |
+| SemanticLink    | SemanticLink    | Clickable link to another case/object          |
+| TextArea        | TextArea        | Multi-line text input                          |
+| TextContent     | TextContent     | Static text display                            |
+| TextInput       | TextInput       | Single-line text input                         |
+| Time            | Time            | Time picker                                    |
+| URL             | URL             | URL input with validation                      |
+| UserReference   | UserReference   | User picker                                    |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component uses `export default function`.
+2. **index.tsx** — Re-exports: `export { default } from './ComponentName'`.
+3. **Local state** — Track input value locally, sync from `value` prop via `useEffect`.
+4. **Commit on blur** — Use `handleEvent(actions, 'changeNblur', propName, localValue)` on blur, not on every keystroke.
+5. **Error display** — Show `validatemessage` or `helperText` below the field; set `error={status === 'error'}`.
+6. **Read-only** — Set `readOnly` on input props or render a display-only component.
+7. **Test IDs** — Pass `data-test-id={testId}` to the underlying input element.
+8. **No PCore imports** — Access PCore globals directly (they're declared globally by `@pega/pcore-pconnect-typedefs`).

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

@@ -0,0 +1,112 @@
+# Skill: AutoComplete
+
+Typeahead / autocomplete search field that fetches options from a data page or associated list, 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 typeahead input that shows a dropdown of matching options as the user types. Options are loaded from a Pega data page or associated list. The stored value is always the **key** of the selected option, while the displayed text is the resolved **value** (label). Delegates read-only to `TextInput` with the resolved label.
+
+## Pega Metadata
+
+- **Pega Name:** `AutoComplete`
+- **Type / Subtype:** `Field` / `Picklist`
+- **Registration key:** `AutoComplete` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `listType` | `string` | `'associated'` or `'datapage'` |
+| `datasource` | `any` | Datasource (array for associated, string name for datapage) |
+| `columns` | `any[]` | Column config for extracting key/value from datasource records |
+| `parameters` | `any` (optional) | Query parameters for data page calls |
+| `deferDatasource` | `boolean` (optional) | If true, transform `datasourceMetadata` into datapage config |
+| `datasourceMetadata` | `any` (optional) | Metadata for deferred datasource |
+| `onRecordChange` | `any` (optional) | Callback fired on selection change |
+| `additionalProps` | `object` (optional) | Extra props passed through to the autocomplete |
+
+## Behavioral Contract
+
+1. **Options state:** Maintain `options` as `Array<{key: string, value: string}>`.
+2. **Input value state:** Maintain `inputValue` (string) — the typed text in the input box. Separate from `selectedValue` (the displayed label of the selected item).
+3. **Datasource change detection:** Use `isDeepEqual` to compare incoming `datasource` with cached `theDatasource`. If different, update `theDatasource` to trigger `useEffect`.
+4. **Deferred datasource transformation:** Same pattern as Dropdown — if `deferDatasource && datasourceMetadata?.datasource?.name`:
+   - Set `listType = 'datapage'`, `datasource = datasourceName`
+   - Flatten `parameters`
+   - Build `columns` from `propertyForDisplayText` / `propertyForValue`
+5. **Column preprocessing:** Strip leading `.` from column `value` fields.
+6. **Loading options (`associated`):** In `useEffect` watching `theDatasource`, call `Utils.getOptionList(props, pConn.getDataObject(''))`.
+7. **Loading options (`datapage`):** In mount-time `useEffect` (when NOT in display mode), call `getDataPage(datasource, parameters, context)`. Map results using `getDisplayFieldsMetaData(columns)`.
+8. **Selected value resolution:** On render, find `selectedValue` by matching `value` (stored key) against `options`:
+   ```
+   index = options.findIndex(el => el.key === value)
+   selectedValue = index > -1 ? options[index].value : value
+   ```
+9. **On selection change:**
+   - `val = newValue ? newValue.key : ''`
+   - Commit via `handleEvent(actionsApi, 'changeNblur', propName, val)`.
+   - If `onRecordChange`, call it with the event.
+10. **On input change:** Update `inputValue` state (typed text, does NOT commit to store).
+11. **Read-only:** Resolve the option label (`options.find(opt => opt.key === value)?.value`), delegate to `TextInput` with resolved label: `return <TextInput {...props} value={theValAsString} />`.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw stored value (key string).
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Resolve the display label from options and delegate: `return <TextInput {...props} value={theValAsString} />`.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant | Outlined |
+| Dropdown popup | Opens below input, shows filtered options |
+| Input | Combobox pattern — types to filter, click arrow to open all |
+| Error state | Red border + red helper text |
+| Label | Floating label |
+| Placeholder | From `placeholder` prop |
+
+**Autocomplete behavior:**
+- The controlled `value` is the selected option object (or `selectedValue` string).
+- The controlled `inputValue` is the typed text.
+- `getOptionLabel` returns `option.value` (the display label).
+- `isOptionEqualToValue` returns `option.value` (used for selection matching).
+
+## Edge Cases & Special Logic
+
+- `inputValue || selectedValue` — the input displays `inputValue` when typing, `selectedValue` when a selection has been made and nothing is typed.
+- When `value` is a key that does not yet exist in `options` (e.g., options still loading), display `value` directly as `selectedValue`.
+- Options array uses `{key, value}` — `key` = stored value, `value` = display label.
+- `context` is obtained from `pConn.getContextName()` and passed to `getDataPage`.
+
+## Dependencies
+
+- `isDeepEqual` from `fast-deep-equal/react`.
+- `Utils.getOptionList()` from `../../helpers/utils`.
+- `getDataPage()` from `../../helpers/data_page`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- Typeahead/autocomplete UI widget.
+
+## Design System Mapping
+
+**UI control type:** Combobox / typeahead autocomplete input.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input>` + custom dropdown list with filtering |
+| MUI | `<Autocomplete>` with `renderInput` using `<TextField>` |
+| Ant Design | `<AutoComplete>` or `<Select showSearch>` |
+| Chakra UI | `<Combobox>` (Downshift) or third-party |

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

@@ -0,0 +1,203 @@
+# Skill: CancelAlert
+
+Cancel confirmation dialog that offers the user a choice between going back or discarding/deleting the current case/action.
+
+> **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 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) |
+
+## Behavioral Contract
+
+### Setup
+
+```typescript
+const actionsAPI = getPConnect().getActionsApi()
+const containerManagerAPI = getPConnect().getContainerManager()
+const isLocalAction = getPConnect().getValue(PCore.getConstants().CASE_INFO.IS_LOCAL_ACTION)
+const isBulkAction = getPConnect()?.options?.isBulkAction
+const isReverseCoexistence = PCore.getCoexistenceManager().getBroadcastUtils().isReverseCoexistenceCaseLoaded()
+```
+
+### State
+
+- `buttonsState`: tracks disabled state per button: `{ saveAndClose: false, delete: false }`
+- `showSnackbar`: boolean — whether to show the failure snackbar
+- `snackbarMessage`: string — error message text
+
+### "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>` |