@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,11 +14,11 @@ Renders a typeahead input that shows a dropdown of matching options as the user
 
 - **Pega Name:** `AutoComplete`
 - **Type / Subtype:** `Field` / `Picklist`
-- **Registration key:** `AutoComplete` (in `component-map.ts`)
+- **Registration key:** `AutoComplete` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop                 | Type                 | Description                                                    |
+| Name                 | Type                 | Description                                                    |
 | -------------------- | -------------------- | -------------------------------------------------------------- |
 | `listType`           | `string`             | `'associated'` or `'datapage'`                                 |
 | `datasource`         | `any`                | Datasource (array for associated, string name for datapage)    |
@@ -27,168 +27,57 @@ Renders a typeahead input that shows a dropdown of matching options as the user
 | `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 ... />;
-}
-```
+| `additionalProps`    | `object` (optional)  | Extra inputs passed through to the autocomplete                |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure when implementing. Replace the autocomplete widget with the equivalent from your chosen design system.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`), the project's event-commit utility, a deep-equality utility (for datasource change detection), the project's utility helpers (for associated option list loading), and the project's data-page utility (for async data page fetching). Define an option type with `key: string` and `value: string`. Declare the top-level helper functions `preProcessColumns`, `getDisplayFieldsMetaData`, and `flattenParameters` (described in the Helper Functions section below). Define the input contract as an extension of the project's field input contract, adding `displayMode`, `deferDatasource`, `datasourceMetadata`, `status`, `onRecordChange`, `additionalProps`, `listType`, `parameters`, `datasource`, and `columns` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `TextInput` and `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `placeholder`, `value` (default `''`), `validatemessage`, `readOnly`, `testId`, `displayMode`, `deferDatasource`, `datasourceMetadata`, `status`, `helperText`, `hideLabel`, `onRecordChange`.
+3. **PConnect setup** — obtain the PConnect instance, context name via `pConn.getContextName()`, actions API, and bound property name.
+4. **Inputs that may be reassigned** — receive `listType`, `parameters`, `datasource` (default `[]`), and `columns` (default `[]`) as reassignable since they get overridden by deferred datasource transformation.
+5. **Local state** — `inputValue` (default `''`), `options` (array of option objects, default `[]`), and `theDatasource` (default `null`).
+6. **Derived values** — a local (non-state) `selectedValue` variable initialized to `''`, and `helperTextToDisplay = validatemessage || helperText`.
+7. **Render-time datasource comparison (not in a lifecycle effect)** — if deep-equal comparison of incoming `datasource` vs cached `theDatasource` is false, update `theDatasource`.
+8. **Deferred datasource transformation** — reassigns the reassignable variables; see Behavioral Contract item 5.
+9. **Column preprocessing** — apply `preProcessColumns(columns)`.
+10. **Lifecycle effect: load associated options** — watching `theDatasource`; see Behavioral Contract item 7.
+11. **Lifecycle effect: load datapage options** — on mount only, guarded to skip when `displayMode` is set or `listType === 'associated'`; see Behavioral Contract item 8.
+12. **Display mode returns** (must come before the main render) — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with `value` set to the raw stored `value` (the key, not the resolved label).
+13. **Resolve `selectedValue` from options** — see Behavioral Contract item 9.
+14. **Event handlers** — the selection change handler and input change handler; see Behavioral Contract items 10 and 11.
+15. **Read-only return** — when `readOnly` is true, resolve the display label by finding the `options` entry whose `key` matches `value` and taking its `value` field, then render `TextInput` with all inputs passed through plus that resolved label as the `value` override.
+16. **Main editable render** — use the DS's autocomplete/combobox widget, passing `options`, a label-resolution function, `value` (`selectedValue`), `inputValue`, selection change handler, input change handler, `label`, `placeholder`, `required`, an error state, `helperTextToDisplay`, and `testId`.
 
 ## 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`.
+1. **Options state:** Maintain `options` as an array of `{key: string, value: string}` objects.
+2. **Input value state:** Maintain `inputValue` (string) — the typed text in the input box. `selectedValue` is a **local variable** (not state) recalculated on every render from `options` and `value`.
+3. **Helper text:** Compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Datasource change detection:** During render (not in an effect), use deep equality to compare incoming `datasource` with cached `theDatasource`. If different, update `theDatasource` to trigger the associated-list lifecycle effect.
 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`.
+   - `listType`, `parameters`, `datasource`, `columns` must be declared as **reassignable** because this block overrides them.
+   - Set `listType = 'datapage'`, `datasource` to the metadata's 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
-   ```
+   - Strip the `@P` prefix from property paths.
+   - Build `columns` as a two-entry array: the first entry marks the key column, the second marks the display column.
+6. **Column preprocessing:** Apply `preProcessColumns(columns)` — strips leading `.` from each column's `value` field.
+7. **Loading options (`associated`):** Lifecycle effect watching `theDatasource` — load options via the project's utility helper and update `options` state.
+8. **Loading options (`datapage`):** Mount-only lifecycle effect (skipped when `displayMode` is set OR `listType === 'associated'`) — call the project's data-page utility, map results using `getDisplayFieldsMetaData(columns)` to extract `key` and `value` per row, and update `options` state.
+9. **Selected value resolution:** On render, find `selectedValue` by locating the option whose `key` matches `value` (the stored key); if found, `selectedValue` is that option's display text, otherwise it falls back to the raw `value`.
 10. **On selection change:**
-
-- `val = newValue ? newValue.key : ''`
-- Commit via `handleEvent(actionsApi, 'changeNblur', propName, val)`.
-- If `onRecordChange`, call it with the event.
-
+    - Extract the key from the selected option (or empty string if cleared).
+    - Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the key.
+    - If `onRecordChange` is provided, 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} />`.
+12. **Read-only:** Resolve the option label (`options.find(opt => opt.key === value)?.value`), delegate to `TextInput` with the resolved label as the `value` override.
 
 ## Helper Functions
 
@@ -196,55 +85,26 @@ These are **top-level pure functions** defined outside the component (design-sys
 
 ### `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;
-});
-```
+Returns a new array where each column object's `.value` has a leading `.` stripped (values not starting with `.` are left unchanged).
 
 ### `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;
-```
+Extracts key, primary display, and secondary display field names from column config: filter the column list to entries with `display === 'true'` (the display columns) and separately to entries with `key === 'true'` (the key column). Initialize a result object with `key: ''`, `primary: ''`, `secondary: []`. Set the key to the first key column's `value` if one exists, otherwise default to `'auto'`. For each display column, if it is marked `primary === 'true'` assign its `value` to primary, otherwise push its `value` onto secondary. Return the result.
 
 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;
-```
+Converts Pega's nested parameter format to a flat key-value map: for each key in the `params` object, read its `name` and `value` fields and assign `flat[name] = value`. Return the resulting flat map.
 
 ## 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' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw stored `value` (key string).
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Resolve the display label from options and delegate: `return <TextInput {...props} value={theValAsString} />`.
+Resolve the display label from options and delegate to `TextInput` with the resolved label as the `value` override.
 
 ## Visual Specifications
 
@@ -257,42 +117,41 @@ Resolve the display label from options and delegate: `return <TextInput {...prop
 | 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                                     |
+| Placeholder    | From the `placeholder` input                                |
 
 **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).
+- The label-resolution function returns the option's display text (the `value` field).
+- Option equality comparison uses the option's display text.
 
 ## 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`.
+- `context` is obtained from `pConn.getContextName()` and passed to the data-page utility.
 - **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.
+- A deep-equality utility — for datasource change detection.
+- The project's utility helpers — for associated list option loading.
+- The project's data-page utility — for async datapage fetch.
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- A typeahead/autocomplete UI widget from the design system.
 
 ## Design System Mapping
 
 **UI control type:** Combobox / typeahead autocomplete input.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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                 |
+- **Autocomplete** → use the DS's combobox/autocomplete component with option filtering
+- **Option format** → `{key, value}` where `key` is stored and `value` is displayed
+- **Read-only mode** → resolve the display label and delegate to `TextInput`
+- **Error state** → the DS's error/danger visual state
+- **Combobox behavior** → controlled `value` (selected option) + controlled `inputValue` (typed text)