@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/WssQuickCreate.md

@@ -0,0 +1,168 @@
+# Skill: WssQuickCreate
+
+Quick-launch action grid that displays a heading and a set of labeled buttons, each optionally with an icon, for creating WSS cases.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a titled section of clickable action cards arranged in a responsive CSS grid. Each card contains an optional icon image and a label. Used in workspace/portal contexts to provide quick access to case creation actions.
+
+## Pega Metadata
+
+- **Pega Name:** `WssQuickCreate`
+- **Registration key:** `WssQuickCreate` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop      | Type                                                           | Required | Description                                                                  |
+| --------- | -------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `heading` | `string`                                                       | Yes      | Section title rendered as an `<h1>`                                          |
+| `actions` | `Array<{ label: string; onClick: () => void; icon?: string }>` | No       | List of action items; each has a label, click handler, and optional icon URL |
+
+## Component Skeleton
+
+```typescript
+import './WssQuickCreate.css';
+
+interface WssQuickCreateProps {
+  heading: string;
+  actions?: Array<{ label: string; onClick: () => void; icon?: string }>;
+}
+
+export default function WssQuickCreate({ heading, actions }: WssQuickCreateProps) {
+  return (
+    <>
+      <h1 id="quick-links-heading" className="quick-links-heading">{heading}</h1>
+      <ul id="quick-links" className="quick-link-ul-list">
+        {actions?.map((action, index) => (
+          <li key={index} className="quickLinkList">
+            <button type="button" className="quick-link-button" onClick={action.onClick}>
+              <span className="quick-link-button-span">
+                {action.icon && <img className="quick-link-icon" src={action.icon} />}
+                <span>{action.label}</span>
+              </span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+## Behavioral Contract
+
+1. Render the `heading` in an `<h1>` element with `id='quick-links-heading'` and class `quick-links-heading`.
+2. Render a `<ul>` with `id='quick-links'` and class `quick-link-ul-list`.
+3. If `actions` is provided, iterate and render one `<li>` per action.
+4. Each `<li>` has the `quickLinkList` style class (styled card with border, rounded corners, and background color).
+5. Inside each `<li>`, render a `<button>` with class `quick-link-button` and the action's `onClick` handler.
+6. Button content is a `<span class='quick-link-button-span'>` (column flex layout) containing:
+   - If `action.icon` is provided: `<img class='quick-link-icon' src={action.icon} />`
+   - `<span>{action.label}</span>`
+7. If `actions` is not provided or is empty, render only the heading with an empty list.
+
+## Visual Specifications
+
+Derived from `WssQuickCreate.css` and component makeStyles:
+
+### Section Heading
+
+| Property   | Value  |
+| ---------- | ------ |
+| Tag        | `<h1>` |
+| Margin top | 8px    |
+
+### Action List
+
+| Property              | Value                                                                 |
+| --------------------- | --------------------------------------------------------------------- |
+| List style            | none                                                                  |
+| Padding               | 0                                                                     |
+| Display               | grid                                                                  |
+| Grid template columns | `repeat(auto-fit, minmax(min(20ch, 100%), 1fr))` (responsive columns) |
+| Gap                   | 1rem                                                                  |
+
+### Action Card (`<li>`)
+
+| Property                | Value                                |
+| ----------------------- | ------------------------------------ |
+| Background (light mode) | `var(--link-button-color)`           |
+| Background (dark mode)  | `var(--app-background-color)`        |
+| Text color              | `var(--app-text-color)`              |
+| Border radius           | 16px                                 |
+| Border                  | `1px solid var(--app-primary-color)` |
+
+### Action Button
+
+| Property       | Value                       |
+| -------------- | --------------------------- |
+| Text transform | capitalize                  |
+| Font size      | 16px                        |
+| Color          | `var(--app-text-color)`     |
+| Height         | 10rem                       |
+| Width          | 100%                        |
+| Background     | transparent (inherits card) |
+
+### Button Inner Span
+
+| Property       | Value  |
+| -------------- | ------ |
+| Display        | flex   |
+| Flex direction | column |
+| Align items    | center |
+| Gap            | 0.5rem |
+
+### Icon
+
+| Property    | Value   |
+| ----------- | ------- |
+| Flex shrink | 0       |
+| Object fit  | contain |
+| Width       | 3rem    |
+| Height      | 3rem    |
+
+**CSS-only implementation notes:**
+
+- Action list: `list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fit, minmax(min(20ch, 100%), 1fr)); gap: 1rem`.
+- Action card: `background: var(--link-button-color); border-radius: 16px; border: 1px solid var(--app-primary-color); color: var(--app-text-color)`.
+- Button: `width: 100%; height: 10rem; background: transparent; border: none; cursor: pointer; text-transform: capitalize; font-size: 16px; color: inherit`.
+- Button content: `display: flex; flex-direction: column; align-items: center; gap: 0.5rem`.
+- Icon: `width: 3rem; height: 3rem; object-fit: contain; flex-shrink: 0`.
+
+## Edge Cases & Special Logic
+
+- If `actions` is `undefined` or empty, render the heading and empty `<ul>` without errors.
+- If `action.icon` is `undefined` or an empty string, render only the label span (no `<img>` element).
+- Labels are displayed as-is (no truncation); the grid layout handles responsive sizing naturally.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+- Icon images are passed as URLs (strings) via `action.icon` — no internal icon system used
+
+## Design System Mapping
+
+**UI control type:** Responsive grid of action cards / quick-launch buttons.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                   |
+| ------------------ | ----------------------------------------------------------------------- |
+| Default (CSS only) | CSS grid `<ul>` + `<button>` cards with flex icon/label layout          |
+| MUI                | `<Button>` inside Grid items; use `makeStyles` or `sx` for card styling |
+| Ant Design         | `<List>` with `<Card>` items or `<Button>` blocks inside a CSS grid     |
+| Chakra UI          | `<SimpleGrid>` with `<Button>` children; `flexDir='column'`             |
+| Shadcn/ui          | Grid of custom `<Button variant='outline'>` cards                       |
+
+When implementing in a specific design system, map the following:
+
+- Card border/background → design system's card or outlined button variant
+- Button `onClick` → standard click handler prop
+- Icon + label stacked layout → `flexDirection: 'column'` button content
+- Responsive grid → design system's grid or `SimpleGrid` equivalent

package/templates/react-sdk-reference/{.cursor/rules/skills/design-system-extension.mdrules → .ai-common/skills/design-system-extension.md}

@@ -1,8 +1,3 @@
----
-description: design-system-extension
-alwaysApply: false
----
-
 # Skill: Design System Extension (DSE) Components
 
 Create or replace Design System Extension components in the react-sdk-reference application. DSE components are display-focused presentational components that render structured data without direct PConnect binding. Some receive `getPConnect`, others receive only display props.
@@ -206,6 +201,7 @@ DSE components use one of three approaches depending on the component and design
 ### Design System Style Props (use if your DS provides them)
 
 If the chosen design system provides built-in spacing, typography, or layout props, prefer them over plain CSS:
+
 - Use the DS's layout wrapper (e.g., `<Stack>`, `<Flex>`, `<HStack>`) instead of manual flex CSS
 - Use DS typography components (e.g., `<Text>`, `<Heading>`) instead of raw `<span>`/`<div>`
 - Use DS CSS custom properties or tokens for spacing — never hardcode `px` values
@@ -217,19 +213,20 @@ If the chosen design system provides built-in spacing, typography, or layout pro
 
 DSE components fall into three patterns with different DS dependencies:
 
-| Pattern | Examples | DS needed? |
-|---|---|---|
-| **B — Pure display** (no PConnect) | AlertBanner, Banner, Operator, WssQuickCreate | Yes — DS provides alert/card/avatar primitives |
-| **A — PConnect display** | CaseSummaryFields, DetailsFields, FieldValueList | Minimal — CSS-based layout; DS typography optional |
-| **C — Complex display** (PConnect bridge) | FieldGroup, FieldGroupList, Pulse | No — PConnect bridge is DS-agnostic; semantic HTML |
+| Pattern                                   | Examples                                         | DS needed?                                         |
+| ----------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| **B — Pure display** (no PConnect)        | AlertBanner, Banner, Operator, WssQuickCreate    | Yes — DS provides alert/card/avatar primitives     |
+| **A — PConnect display**                  | CaseSummaryFields, DetailsFields, FieldValueList | Minimal — CSS-based layout; DS typography optional |
+| **C — Complex display** (PConnect bridge) | FieldGroup, FieldGroupList, Pulse                | No — PConnect bridge is DS-agnostic; semantic HTML |
 
 The component-specific skill file specifies which pattern applies.
 
-**1. Check the component-specific skill file** — `.cursor/rules/skills/design-system-extension-skills/<ComponentName>.mdrules` contains a **Design System Mapping** table where available.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` contains a **Design System Mapping** table where available.
 
 **2. If the chosen design system is not listed** — use the component purpose and pattern category above to pick the closest DS primitive.
 
 **3. Discover the API from installed packages** — confirm component names and props from `.d.ts` before writing JSX:
+
 ```bash
 find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Alert\|Badge\|Avatar" | head -5
 grep -A 30 "interface.*Props" <path-to-file>
@@ -237,12 +234,12 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 **4. Variant mapping** — always map Pega's variant names to your DS equivalent before passing to DS components:
 
-| Pega variant | Meaning | Typical DS equivalent |
-|---|---|---|
-| `urgent` | Critical / error | `error`, `danger`, `critical` |
-| `warning` | Warning | `warning` |
-| `info` | Informational | `info` |
-| `success` | Success | `success` |
+| Pega variant | Meaning          | Typical DS equivalent         |
+| ------------ | ---------------- | ----------------------------- |
+| `urgent`     | Critical / error | `error`, `danger`, `critical` |
+| `warning`    | Warning          | `warning`                     |
+| `info`       | Informational    | `info`                        |
+| `success`    | Success          | `success`                     |
 
 ---
 

package/templates/react-sdk-reference/{.cursor/rules/skills/field-components.mdrules → .ai-common/skills/field-components.md}

@@ -1,8 +1,3 @@
----
-description: field-components
-alwaysApply: false
----
-
 # 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.
@@ -158,11 +153,12 @@ export default function MyField(props: MyFieldProps) {
 
 When filling in the `// [DS RENDER]` section with a specific design system:
 
-**1. Check the component-specific skill file** — `.cursor/rules/skills/field-skills/<ComponentName>.mdrules` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
 
 **2. If the chosen design system is not in the mapping table** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
 
 **3. Discover the API from installed packages** — before writing any render JSX, confirm all prop names from `.d.ts` files. Never rely on training-knowledge of a DS API:
+
 ```bash
 find node_modules/<ds-package> -name "ComponentName.d.ts" | head -3
 grep -A 40 "interface.*Props" <path-to-file>
@@ -170,14 +166,14 @@ grep -A 40 "interface.*Props" <path-to-file>
 
 **4. Prop mapping conventions** — adapt these Pega/SDK props to whatever your DS component calls them:
 
-| Pega/SDK prop | Meaning | Typical DS equivalent |
-|---|---|---|
-| `status === 'error'` | Validation error state | `error`, `status="error"`, `invalid`, `isInvalid` |
-| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra` |
-| `readOnly` | Non-editable, still visible | `readOnly`, `isReadOnly`, `variant="borderless"` |
-| `testId` | Automation selector | `data-test-id` on the underlying `<input>` element |
-| `required` | Required field marker | `required`, `isRequired` |
-| `hideLabel` | Suppress label display | Pass empty string `''` as label |
+| Pega/SDK prop                     | Meaning                       | Typical DS equivalent                              |
+| --------------------------------- | ----------------------------- | -------------------------------------------------- |
+| `status === 'error'`              | Validation error state        | `error`, `status="error"`, `invalid`, `isInvalid`  |
+| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra`       |
+| `readOnly`                        | Non-editable, still visible   | `readOnly`, `isReadOnly`, `variant="borderless"`   |
+| `testId`                          | Automation selector           | `data-test-id` on the underlying `<input>` element |
+| `required`                        | Required field marker         | `required`, `isRequired`                           |
+| `hideLabel`                       | Suppress label display        | Pass empty string `''` as label                    |
 
 **5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., `<Form.Item>` in Ant Design, `<FormControl>` in Chakra UI), use it rather than composing them manually.
 
@@ -185,6 +181,23 @@ grep -A 40 "interface.*Props" <path-to-file>
 
 ## Event Handling
 
+> ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM `field-utils`**
+>
+> If the project has a `field-utils.ts` or `field-utils.tsx` file that exports utility functions AND types (e.g., `DynamicFieldProps`, `commitField`, `FieldValue`, `getFieldContext`, `useFieldValue`, `helperText`, `getOptions`), import everything you need in a **single import statement**.
+>
+> ```typescript
+> // ✅ CORRECT — one import for both types and functions
+> import { commitField, DynamicFieldProps, FieldValue, getFieldContext, helperText } from '../field-utils';
+>
+> // ❌ WRONG — duplicate identifier error!
+> import type { DynamicFieldProps } from '../field-utils';
+> import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';
+> ```
+>
+> TypeScript allows mixing type and value exports in a single import. NEVER add a separate `import type` line for a symbol that is already imported in another import from the same module.
+>
+> **Before writing imports:** Check what `field-utils` exports. If it exports `DynamicFieldProps` as a `type`, you can import it alongside value exports in one statement.
+
 Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
 
 ```typescript

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                 |