@pega/sdk 0.0.4 → 0.0.5

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

@@ -0,0 +1,298 @@
+# 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                 |
+
+## Component Skeleton
+
+Follow this exact structure when implementing. Replace `<AutocompleteWidget>` with the equivalent from your chosen design system.
+
+```typescript
+import { useEffect, useState } from 'react';
+import isDeepEqual from 'fast-deep-equal/react';
+
+import Utils from '../../helpers/utils';
+import { getDataPage } from '../../helpers/data_page';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+// ── Option type ──────────────────────────────────────────────
+interface IOption {
+  key: string;
+  value: string;
+}
+
+// ── Helper functions (top-level, outside component) ──────────
+// preProcessColumns   → see Helper Functions section
+// getDisplayFieldsMetaData → see Helper Functions section
+// flattenParameters   → see Helper Functions section
+
+// ── Props interface ──────────────────────────────────────────
+interface AutoCompleteProps extends PConnFieldProps {
+  displayMode?: string;
+  deferDatasource?: boolean;
+  datasourceMetadata?: any;
+  status?: string;
+  onRecordChange?: any;
+  additionalProps?: object;
+  listType: string;
+  parameters?: any;
+  datasource: any;
+  columns: any[];
+}
+
+// ── Component ────────────────────────────────────────────────
+export default function AutoComplete(props: AutoCompleteProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, placeholder, value = '',
+    validatemessage, readOnly, testId, displayMode,
+    deferDatasource, datasourceMetadata, status,
+    helperText, hideLabel, onRecordChange,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const context = pConn.getContextName();
+  const actionsApi = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 4. Props that may be reassigned (use let)
+  let { listType, parameters, datasource = [], columns = [] } = props;
+
+  // 5. State
+  const [inputValue, setInputValue] = useState('');
+  const [options, setOptions] = useState<IOption[]>([]);
+  const [theDatasource, setDatasource] = useState(null);
+
+  // 6. Derived values
+  let selectedValue: any = '';
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 7. Render-time datasource comparison (NOT in useEffect)
+  if (!isDeepEqual(datasource, theDatasource)) {
+    setDatasource(datasource);
+  }
+
+  // 8. Deferred datasource transformation (reassigns let vars)
+  //    → see Behavioral Contract #5
+
+  // 9. Column preprocessing
+  columns = preProcessColumns(columns);
+
+  // 10. useEffect: load associated options — deps: [theDatasource]
+  //     → see Behavioral Contract #7
+
+  // 11. useEffect: load datapage options — deps: [] (mount only)
+  //     Guard: skip if displayMode is set OR listType === 'associated'
+  //     → see Behavioral Contract #8
+
+  // 12. Display mode returns (MUST come before main render)
+  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" />;
+  }
+
+  // 13. Resolve selectedValue from options
+  //     → see Behavioral Contract #9
+
+  // 14. Event handlers: handleChange, handleInputValue
+  //     → see Behavioral Contract #10, #11
+
+  // 15. Read-only return
+  if (readOnly) {
+    const theValAsString = options?.find(opt => opt.key === value)?.value;
+    return <TextInput {...props} value={theValAsString} />;
+  }
+
+  // 16. Main editable render — use your design system's autocomplete widget
+  //     Pass: options, getOptionLabel, value, inputValue, onChange, onInputChange,
+  //     label, placeholder, required, error state, helperTextToDisplay, testId
+  return <AutocompleteWidget ... />;
+}
+```
+
+## 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. `selectedValue` is a **local variable** (not React state) recalculated on every render from `options` and `value`.
+3. **Helper text:** Compute `helperTextToDisplay = validatemessage || helperText` — use this wherever helper/error text is rendered.
+4. **Datasource change detection:** During render (not in an effect), use `isDeepEqual` to compare incoming `datasource` with cached `theDatasource`. If different, call `setDatasource(datasource)` to trigger the associated-list `useEffect`.
+5. **Deferred datasource transformation:** If `deferDatasource && datasourceMetadata?.datasource?.name`:
+   - `listType`, `parameters`, `datasource`, `columns` must be declared with **`let`** (not `const`) because this block reassigns them.
+   - Set `listType = 'datapage'`, `datasource = datasourceMetadata.datasource.name`.
+   - Flatten `parameters` using `flattenParameters()` (see Helper Functions).
+   - Strip the `@P` prefix from property paths: `propertyForDisplayText.startsWith('@P') ? propertyForDisplayText.substring(3) : propertyForDisplayText` (same for `propertyForValue`).
+   - Build `columns` as:
+     ```
+     [
+       { key: 'true', setProperty: 'Associated property', value: valueProp },
+       { display: 'true', primary: 'true', useForSearch: true, value: displayProp }
+     ]
+     ```
+6. **Column preprocessing:** Apply `preProcessColumns(columns)` (see Helper Functions) — strips leading `.` from each column's `value` field.
+7. **Loading options (`associated`):** `useEffect` with dependency array **`[theDatasource]`** — call `Utils.getOptionList(props, pConn.getDataObject(''))` and `setOptions(result)`.
+8. **Loading options (`datapage`):** `useEffect` with dependency array **`[]`** (mount only, skipped when `displayMode` is set OR `listType === 'associated'`) — call `getDataPage(datasource, parameters, context)`. Map results:
+   ```
+   const displayColumn = getDisplayFieldsMetaData(columns);
+   results.forEach(element => {
+     optionsData.push({
+       key: element[displayColumn.key] || element.pyGUID,
+       value: element[displayColumn.primary]?.toString()
+     });
+   });
+   setOptions(optionsData);
+   ```
+9. **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
+   ```
+10. **On selection change:**
+
+- `val = newValue ? newValue.key : ''`
+- Commit via `handleEvent(actionsApi, 'changeNblur', propName, val)`.
+- If `onRecordChange`, call it with the event.
+
+11. **On input change:** Update `inputValue` state (typed text, does NOT commit to store).
+12. **Read-only:** Resolve the option label (`options.find(opt => opt.key === value)?.value`), delegate to `TextInput` with resolved label: `return <TextInput {...props} value={theValAsString} />`.
+
+## Helper Functions
+
+These are **top-level pure functions** defined outside the component (design-system independent).
+
+### `preProcessColumns(columnList)`
+
+Returns a new array where each column object's `.value` has a leading `.` stripped:
+
+```
+columnList.map(col => {
+  const temp = { ...col };
+  temp.value = col.value?.startsWith('.') ? col.value.substring(1) : col.value;
+  return temp;
+});
+```
+
+### `getDisplayFieldsMetaData(columnList)`
+
+Extracts key, primary display, and secondary display field names from column config:
+
+```
+const displayColumns = columnList.filter(col => col.display === 'true');
+const keyCol = columnList.filter(col => col.key === 'true');
+const metaData = { key: '', primary: '', secondary: [] };
+metaData.key = keyCol.length > 0 ? keyCol[0].value : 'auto';
+for (const dc of displayColumns) {
+  if (dc.primary === 'true') metaData.primary = dc.value;
+  else metaData.secondary.push(dc.value);
+}
+return metaData;
+```
+
+Return type: `{ key: string, primary: string, secondary: string[] }`.
+
+### `flattenParameters(params)`
+
+Converts Pega's nested parameter format to a flat key-value map:
+
+```
+const flat = {};
+Object.keys(params).forEach(key => {
+  const { name, value } = params[key];
+  flat[name] = value;
+});
+return flat;
+```
+
+## 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`.
+- **Render ordering matters:** display mode checks → `selectedValue` resolution → define event handlers → readOnly check → main editable render. Do not reorder.
+
+## 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/{.claude → .ai-common}/skills/field-skills/CancelAlert.md

@@ -2,7 +2,7 @@
 
 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.
+> **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.
 
 ---
 
@@ -28,24 +28,153 @@ Renders a full-screen modal overlay with a confirmation dialog. Presents two act
 | `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;
-const isReverseCoexistence = PCore.getCoexistenceManager().getBroadcastUtils().isReverseCoexistenceCaseLoaded();
+
+// 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: `{ saveAndClose: false, delete: false }`
+- `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`: