@pega/sdk 0.0.5 → 0.0.7

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

@@ -2,7 +2,7 @@
 
 Location input with Google Maps Places autocomplete, interactive map display, and optional geolocation (current location).
 
-> **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,121 +14,41 @@ Renders a text input that integrates with Google Maps Places API for address/loc
 
 - **Pega Name:** `Location`
 - **Type / Subtype:** `Field` / `Text-Location`
-- **Registration key:** `Location` (in `component-map.ts`)
+- **Registration key:** `Location` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop              | Type                 | Default | Description                                                              |
+| Input             | Type                 | Default | Description                                                              |
 | ----------------- | -------------------- | ------- | ------------------------------------------------------------------------ |
 | `coordinates`     | `string` (optional)  | `''`    | Comma-separated lat/lng string (e.g., `'18.5204, 73.8567'`)              |
 | `onlyCoordinates` | `boolean` (optional) | `false` | If `true`, store and display lat/lng coordinates instead of address text |
 | `showMap`         | `boolean` (optional) | —       | Show the interactive map in editable mode                                |
 | `showMapReadOnly` | `boolean` (optional) | —       | Show the map in read-only mode                                           |
 
-## Component Skeleton
+## Implementation Structure
 
 Follow this exact structure. This component is complex — integrates Google Maps API for places autocomplete, geolocation, and optional map display.
 
-```typescript
-import { useEffect, useState, useCallback, useRef } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-import handleEvent from '../../helpers/event-utils';
-import './Location.css';
-
-interface LocationProps extends PConnFieldProps {
-  coordinates?: string;
-  onlyCoordinates?: boolean;
-  showMap?: boolean;
-  showMapReadOnly?: boolean;
-}
-
-const mapContainerStyle = { width: '100%', height: '300px', marginTop: '0px' };
-const defaultCenter = { lat: 18.5204, lng: 73.8567 };
-const disabledMapOptions = {
-  gestureHandling: 'none', keyboardShortcuts: false,
-  disableDefaultUI: true, clickableIcons: false,
-};
-
-export default function Location(props: LocationProps) {
-  // 1. Registry lookups
-  const TextInput = getComponentFromRegistry('TextInput');
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required = false, disabled = false, value = '',
-    validatemessage, status, readOnly = false, testId, displayMode,
-    hideLabel = false, placeholder, helperText,
-    coordinates = '', onlyCoordinates = false, showMap, showMapReadOnly,
-  } = props;
-
-  // 3. PConnect setup — note TWO property names
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-  const coordPropName = (pConn.getStateProps() as any).coordinates;
-
-  // 4. State
-  const [inputValue, setInputValue] = useState<string>(value ?? '');
-  const [mapCenter, setMapCenter] = useState(defaultCenter);
-  const [markerPosition, setMarkerPosition] = useState<{lat:number,lng:number} | null>(null);
-
-  // 5. Refs
-  const inputRef = useRef<HTMLInputElement | null>(null);
-  const autocompleteRef = useRef<google.maps.places.Autocomplete | null>(null);
-
-  // 6. Load Google Maps API
-  const { isLoaded } = useLoadScript({
-    googleMapsApiKey: pConn.getGoogleMapsAPIKey?.() || '',
-    libraries: ['places', 'geocoding'],
-  });
-
-  // 7. Error flag
-  const hasError = status === 'error' && !!validatemessage && !disabled;
-
-  // 8. useEffect: sync value + coordinates — deps: [value, coordinates, onlyCoordinates]
-  //    → see Behavioral Contract #3
-
-  // 9. handleChange (manual text input) — useCallback
-  //    Commits immediately, clears coordinates if input emptied
-
-  // 10. handlePlaceChanged — useCallback
-  //     Reads place from autocompleteRef, extracts lat/lng,
-  //     stores address or coordinates based on onlyCoordinates flag
-
-  // 11. useEffect: init Places Autocomplete — deps: [isLoaded, handlePlaceChanged]
-  //     Guard: isLoaded && inputRef.current && !autocompleteRef.current
-
-  // 12. handleGetCurrentLocation — useCallback
-  //     Uses navigator.geolocation.getCurrentPosition
-  //     If onlyCoordinates: store coords directly
-  //     Else: reverse geocode via google.maps.Geocoder
-
-  // 13. Display mode returns
-  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" />;
-  }
-
-  // 14. Map element (shared between readOnly and editable)
-  //     opacity: disabled ? 0.7 : 1, options: disabled ? disabledMapOptions : undefined
-
-  // 15. Read-only return
-  if (readOnly) {
-    return <div><TextInput {...props} />{isLoaded && showMapReadOnly && map}</div>;
-  }
-
-  // 16. Main render
-  //     - Error alert ABOVE input if hasError
-  //     - Guard: only render TextField when isLoaded
-  //     - TextField with inputRef, endAdornment location icon button
-  //     - Map below if isLoaded && showMap
-  return <div>...</div>;
-}
-```
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`), the project's event-commit utility (for committing value changes to the store), and a Google Maps script loader capable of loading the `places` and `geocoding` libraries dynamically. A companion stylesheet is needed to fix the autocomplete dropdown z-index (see CSS section). Define the input contract as the project's field input contract extended with `coordinates?`, `onlyCoordinates?`, `showMap?`, and `showMapReadOnly?`. Define module-level constants: `mapContainerStyle` (`width: '100%'`, `height: '300px'`, `marginTop: '0px'`), `defaultCenter` (`{ lat: 18.5204, lng: 73.8567 }` — Pune, India), and `disabledMapOptions` (`gestureHandling: 'none'`, `keyboardShortcuts: false`, `disableDefaultUI: true`, `clickableIcons: false`).
+
+**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` (default `false`), `disabled` (default `false`), `value` (default `''`), `validatemessage`, `status`, `readOnly` (default `false`), `testId`, `displayMode`, `hideLabel` (default `false`), `placeholder`, `helperText`, `coordinates` (default `''`), `onlyCoordinates` (default `false`), `showMap`, `showMapReadOnly`.
+3. **PConnect setup** (note TWO property names) — `pConn`, `actions`, `propName` for the address/value, and a separate `coordPropName` for the coordinates property.
+4. **Local state** — `inputValue` (initialized from `value`), `mapCenter` (initialized to `defaultCenter`), and `markerPosition` (initialized to `null`).
+5. **Instance references** — `inputRef` for the text input element, `autocompleteRef` for the Google Places Autocomplete instance.
+6. **Load Google Maps API** — use a script-loading mechanism with the API key from `pConn.getGoogleMapsAPIKey?.() || ''` and the `places` and `geocoding` libraries. Track the loaded status via an `isLoaded` flag.
+7. **Error flag** — `hasError = status === 'error' && !!validatemessage && !disabled`.
+8. **Sync lifecycle effect** — watching `value`, `coordinates`, `onlyCoordinates`; see Behavioral Contract item 3.
+9. **`handleChange`** (manual text input, cached callback) — commits immediately, clears coordinates if the input is emptied.
+10. **`handlePlaceChanged`** (cached callback) — reads the selected place from the autocomplete instance reference, extracts `lat`/`lng`, and stores either the address or the coordinates depending on the `onlyCoordinates` flag.
+11. **Init Places Autocomplete** — a lifecycle effect watching `isLoaded` and the place-changed handler, guarded to run only once `isLoaded && inputRef is set && autocompleteRef is not yet set`.
+12. **`handleGetCurrentLocation`** (cached callback) — uses `navigator.geolocation.getCurrentPosition`; when `onlyCoordinates` is set, stores the coordinates directly, otherwise reverse-geocodes via `google.maps.Geocoder`.
+13. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with the raw `value`.
+14. **Map element** (shared between read-only and editable rendering) — opacity reduced to `0.7` when `disabled`, and `disabledMapOptions` applied when `disabled`.
+15. **Read-only return** — render a wrapper containing `TextInput` with all inputs spread, plus the map (once loaded) when `showMapReadOnly` is set.
+16. **Main render** — render an error alert above the input when `hasError`; only render the text field once `isLoaded`; the text field carries the input reference and a trailing location-icon button that triggers `handleGetCurrentLocation`; render the map below when `isLoaded && showMap`.
 
 ## Behavioral Contract
 
@@ -139,19 +59,19 @@ export default function Location(props: LocationProps) {
    - `inputValue` (string): shown in the text input
    - `mapCenter` (`{lat, lng}`): default `{ lat: 18.5204, lng: 73.8567 }` (Pune, India)
    - `markerPosition` (`{lat, lng} | null`)
-3. **Value sync:** `useEffect` watching `value`, `coordinates`, `onlyCoordinates`:
-   - If `onlyCoordinates && coordinates`: `setInputValue(coordinates)`
-   - Else: `setInputValue(value ?? '')`
+3. **Value sync:** A lifecycle effect watching `value`, `coordinates`, `onlyCoordinates`:
+   - If `onlyCoordinates && coordinates`: set `inputValue` to `coordinates`
+   - Else: set `inputValue` to `value ?? ''`
    - If `coordinates` exists: parse `lat, lng`, update `mapCenter` and `markerPosition`
-4. **Places Autocomplete (init):** `useEffect` watching `isLoaded` — once Maps API loads and `inputRef.current` is set, attach `new google.maps.places.Autocomplete(inputRef.current)` and add `place_changed` listener.
+4. **Places Autocomplete (init):** A lifecycle effect watching `isLoaded` — once Maps API loads and the input element reference is set, attach `new google.maps.places.Autocomplete(inputElement)` and add `place_changed` listener.
 5. **On place changed:**
    - Get `place.geometry.location` → extract `lat`, `lng`
-   - If `onlyCoordinates`: `inputValue = "${lat}, ${lng}"`, commit this as the value AND update `coordinates` property
-   - Else: `inputValue = place.formatted_address`, commit address as value, update `coordinates` property separately: `actions.updateFieldValue(coordPropName, coordinateString)`
+   - If `onlyCoordinates`: set `inputValue` to `"lat, lng"` format, commit this as the value AND update the coordinates property
+   - Else: set `inputValue` to `place.formatted_address`, commit address as value, update coordinates property separately via `actions.updateFieldValue(coordPropName, coordinateString)`
    - Update `mapCenter` and `markerPosition`
 6. **On text change (manual):**
-   - Update `inputValue` and commit immediately via `handleEvent(actions, 'changeNblur', propName, newValue)`
-   - If input cleared and `coordPropName` exists: `actions.updateFieldValue(coordPropName, '')`; `setMarkerPosition(null)`
+   - Update `inputValue` and commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the new value
+   - If input cleared and `coordPropName` exists: `actions.updateFieldValue(coordPropName, '')` and clear the marker position
 7. **Get current location button:**
    - Use `navigator.geolocation.getCurrentPosition()`
    - If `onlyCoordinates`: store `"lat, lng"` as value and coordinates
@@ -169,82 +89,54 @@ When `disabled`, map options disable all interactions:
 
 ### CSS for Google Maps autocomplete dropdown z-index:
 
-```css
-/* Location.css */
-.pac-container {
-  z-index: 2147483647;
-}
-```
+A companion stylesheet sets the `.pac-container` (the autocomplete dropdown) to the maximum z-index value, ensuring it appears above modal/dialog overlays.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw address/coordinates string.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to the label (empty string if `hideLabel`) and `value` set to the raw address/coordinates string.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` with the same name/value and a stacked variant.
 
 ## Read-Only Rendering
 
-```
-<div>
-  <TextInput {...props} />
-  {isLoaded && showMapReadOnly && <GoogleMap ... />}
-</div>
-```
+A wrapper containing `TextInput` with all inputs spread, followed by the interactive map (once loaded) when `showMapReadOnly` is set.
 
 ## Visual Specifications
 
-| Property             | Value                                              |
-| -------------------- | -------------------------------------------------- |
-| Width                | 100%                                               |
-| Input variant        | Default (outlined, from `TextField`)               |
-| Trailing icon        | Location pin icon button (for current location)    |
-| Error alert          | Alert banner ABOVE the input field when `hasError` |
-| Map container        | `width: 100%`, `height: 300px`, `marginTop: 0px`   |
-| Map render           | Only shown when `isLoaded && (showMap              |     | showMapReadOnly)` |
-| Disabled map opacity | `0.7`                                              |
+| Property             | Value                                                        |
+| -------------------- | ------------------------------------------------------------ |
+| Width                | 100%                                                         |
+| Input variant        | Default outlined text field                                  |
+| Trailing icon        | Location pin icon button (for current location)              |
+| Error alert          | Alert banner ABOVE the input field when `hasError`           |
+| Map container        | `width: 100%`, `height: 300px`, `marginTop: 0px`             |
+| Map render           | Only shown when `isLoaded && (showMap \|\| showMapReadOnly)` |
+| Disabled map opacity | `0.7`                                                        |
 
-**CSS companion file required:** `Location.css` with:
+**CSS companion file required:** A stylesheet that sets `.pac-container` to the maximum z-index value, ensuring the Google Maps autocomplete dropdown appears above modal/dialog overlays.
 
-```css
-.pac-container {
-  z-index: 2147483647;
-}
-```
-
-This ensures the Google Maps autocomplete dropdown appears above modal/dialog overlays.
-
-**CSS-only implementation notes:**
-
-- Location pin button: `<button>` with `position: absolute; right: 8px; top: 50%; transform: translateY(-50%);`
+**Visual-only styling notes:** The location pin button is positioned at the trailing edge of the input, vertically centered.
 
 ## Edge Cases & Special Logic
 
-- **`isLoaded` guard:** Only render the `TextField` and map after Google Maps API is fully loaded.
+- **`isLoaded` guard:** Only render the text field and map after Google Maps API is fully loaded.
 - **`onlyCoordinates` mode:** The stored `value` is `"lat, lng"` format; coordinates and address are the same.
 - **Dual property:** The component writes to TWO properties — `propName` (address or coordinates) and `coordPropName` (coordinates). `coordPropName` may be undefined if the Pega config doesn't include a coordinates property.
-- **Autocomplete ref lifecycle:** `autocompleteRef` is only initialized once (when `!autocompleteRef.current`). The `handlePlaceChanged` callback must be stable (`useCallback` with deps).
+- **Autocomplete instance reference lifecycle:** The autocomplete instance is only initialized once (when the reference is not yet set). The `handlePlaceChanged` callback must be stable (cached with appropriate dependencies).
 - **Map default center:** Pune, India — `{ lat: 18.5204, lng: 73.8567 }`.
 - Google Maps Geocoder is only called in non-`onlyCoordinates` geolocation mode for reverse geocoding.
 
 ## Dependencies
 
-- Google Maps JavaScript API (loaded dynamically via `@react-google-maps/api` or equivalent loader).
-- `@react-google-maps/api` — `GoogleMap`, `Marker`, `useLoadScript`.
-- `handleEvent` from `../../helpers/event-utils`.
-- `getComponentFromRegistry('TextInput')` for read-only.
-- `getComponentFromRegistry('FieldValueList')` for display modes.
-- A location pin icon.
+- Google Maps JavaScript API (loaded dynamically via a script loader).
+- A Google Maps rendering library providing map display, marker, and script-loading capabilities.
+- The project's event-commit utility for committing field value changes.
+- The project's component registry to resolve `TextInput` (for read-only) and `FieldValueList` (for display modes).
+- A location pin icon from the project's icon set.
 
-**CSS companion:** `Location.css` — must be imported to fix autocomplete z-index.
+**CSS companion:** A stylesheet that fixes the autocomplete dropdown z-index (`.pac-container`).
 
 ## Design System Mapping
 
 **UI control type:** Text input with location autocomplete dropdown + optional map.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                   |
-| ------------------ | ----------------------------------------------------------------------- |
-| Default (CSS only) | `<input type="text">` + Google Maps Autocomplete API + Google Map embed |
-| MUI                | `<TextField>` + `InputAdornment` for icon + `@react-google-maps/api`    |
-| Ant Design         | `<Input suffix={<LocationIcon />}>` + Google Maps                       |
-| Chakra UI          | `<InputGroup>` + `<InputRightElement>` + Google Maps                    |
+When implementing in a specific design system, map the following: a full-width outlined text field with trailing icon adornment (for the current-location button), an alert/banner component for error display above the input, and a Google Maps embed component for the interactive map. The trailing icon should be a location/pin icon wrapped in a clickable button. The autocomplete functionality comes from the Google Maps Places API directly attached to the input element, not from the design system.

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

@@ -2,7 +2,7 @@
 
 Multi-select autocomplete field supporting flat lists, grouped/hierarchical data, reference list binding, and debounced search.
 
-> **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 multi-value typeahead input where users can search and select multiple
 
 - **Pega Name:** `Multiselect`
 - **Type / Subtype:** `Field` / `Picklist-Multi`
-- **Registration key:** `Multiselect` (in `component-map.ts`)
+- **Registration key:** `Multiselect` (in the project's component map)
 
-> **Note:** `Multiselect` does NOT extend `PConnFieldProps` — it uses raw `props` (no typed interface in the reference implementation). Define props as needed for your implementation.
+> **Note:** `Multiselect` does NOT extend the project's field input contract — it defines its own inputs directly.
 
-## Props (component-specific)
+## Inputs (component-specific)
 
 | Prop                        | Type       | Default      | Description                                                 |
 | --------------------------- | ---------- | ------------ | ----------------------------------------------------------- |
@@ -44,75 +44,28 @@ Renders a multi-value typeahead input where users can search and select multiple
 | `maxResultsDisplay`         | `string`   | —            | Max results to display (`'100'` default)                    |
 | `value`                     | `any`      | —            | Current value                                               |
 
-## Component Skeleton
-
-This is a complex component. Note: it does NOT extend `PConnFieldProps` — uses raw `props`.
-
-```typescript
-import { useEffect, useMemo, useRef, useState } from 'react';
-import {
-  doSearch, getDisplayFieldsMetaData, useDeepMemo,
-  preProcessColumns, getGroupDataForItemsTree,
-} from './utils';
-import { insertInstruction, deleteInstruction } from '../../helpers/instructions-utils';
-import { debounce } from 'throttle-debounce';
-
-export default function Multiselect(props) {
-  // 1. Destructure props (use let for datasource/columns — may be reassigned)
-  const {
-    getPConnect, label, placeholder, referenceList, selectionKey,
-    primaryField, initialCaseClass, showSecondaryInSearchOnly = false,
-    listType = '', isGroupData = false, referenceType, secondaryFields,
-    groupDataSource = [], parameters = {}, matchPosition = 'contains',
-    maxResultsDisplay, groupColumnsConfig = [{}], selectionList, value,
-  } = props;
-  let { datasource = [], columns = [{}] } = props;
-
-  // 2. Reference list mode override (if referenceList.length > 0)
-  //    → reassign datasource and columns
-  //    → see Behavioral Contract "Reference List Mode"
-
-  // 3. State
-  const [inputValue, setInputValue] = useState(value);
-  const [selectedItems, setSelectedItems] = useState([]);
-
-  // 4. dataConfig (memoized with deep comparison via useDeepMemo)
-  //    → see Behavioral Contract "Data Config"
-
-  // 5. Display field metadata + items tree
-  //    → displayFieldMeta, groupsDisplayFieldMeta, itemsTreeBaseData, itemsTree state
-
-  // 6. Refs
-  const getCaseListBasedOnParamsDebounced: any = useRef();
-  const dataApiObj: any = useRef();
-  const pConn = getPConnect();
-  const contextName = pConn.getContextName();
-  const listActions = pConn.getListActions();
-
-  // 7. getCaseListBasedOnParams — main search function
-  //    → see Behavioral Contract "Search"
-
-  // 8. useEffect: setReferenceList — deps: [pConn]
-  // 9. useEffect: init debounced ref — deps: []
-  // 10. useEffect: init data API — deps: [dataConfig, ...]
-  //     → PCore.getDataApi().init(dataConfig, contextName)
-
-  // 11. onSearchHandler — updates inputValue, triggers debounced search
-  // 12. setSelectedItemsForReferenceList — insert/delete instruction
-  // 13. handleChange — selection add/remove logic
-  //     → see Behavioral Contract "Selection Changes"
-
-  // 14. Main render — multi-select autocomplete
-  //     Key props:
-  //     - multiple, fullWidth, disableCloseOnSelect
-  //     - options: itemsTree, value: selectedItems
-  //     - getOptionLabel: (option) => option?.primary
-  //     - onChange: handleChange
-  //     - renderInput: TextField with label, placeholder, size='small',
-  //       variant='outlined', onChange=onSearchHandler
-  return <MultiSelectAutocomplete ... />;
-}
-```
+## Implementation Structure
+
+This is a complex component. Note: it does NOT extend the project's field input contract — it defines its own inputs directly.
+
+**Module Setup:** The component depends on local utility helpers (`doSearch`, `getDisplayFieldsMetaData`, a deep-memoization hook, `preProcessColumns`, `getGroupDataForItemsTree`), the project's instruction helpers (`insertInstruction` and `deleteInstruction`), and a debounce utility. It does not use the standard field input contract or the project's event-commit utility — selection commits happen via the instruction helpers.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** (declare `datasource`/`columns` as reassignable since they may be overridden) — `getPConnect`, `label`, `placeholder`, `referenceList`, `selectionKey`, `primaryField`, `initialCaseClass`, `showSecondaryInSearchOnly` (default `false`), `listType` (default `''`), `isGroupData` (default `false`), `referenceType`, `secondaryFields`, `groupDataSource` (default `[]`), `parameters` (default `{}`), `matchPosition` (default `'contains'`), `maxResultsDisplay`, `groupColumnsConfig` (default `[{}]`), `selectionList`, `value`; separately destructure `datasource` (default `[]`) and `columns` (default `[{}]`) with `let`.
+2. **Reference list mode override** — when `referenceList.length > 0`, reassign `datasource` and `columns`; see the Behavioral Contract "Reference List Mode" section.
+3. **Local state** — `inputValue` initialized from `value`, and `selectedItems` initialized to `[]`.
+4. **`dataConfig`** (memoized with deep comparison via a deep-memoization utility) — see the Behavioral Contract "Data Config" section.
+5. **Display field metadata and items tree** — `displayFieldMeta`, `groupsDisplayFieldMeta`, `itemsTreeBaseData`, and an `itemsTree` state value; see the Behavioral Contract "Items Tree" section.
+6. **Instance references** — `getCaseListBasedOnParamsDebounced` and `dataApiObj` as instance references; also `pConn` via `getPConnect()`, `contextName` via `pConn.getContextName()`, and `listActions` via `pConn.getListActions()`.
+7. **`getCaseListBasedOnParams`** — the main search function; see the Behavioral Contract "Search" section.
+8. **Lifecycle effect: set reference list** — watching the PConnect instance.
+9. **Lifecycle effect: init debounced reference** — on mount.
+10. **Lifecycle effect: init data API** — watching `dataConfig` and related dependencies; calls `PCore.getDataApi().init(dataConfig, contextName)`.
+11. **`onSearchHandler`** — updates `inputValue` and triggers the debounced search.
+12. **`setSelectedItemsForReferenceList`** — inserts or deletes an instruction depending on selection state.
+13. **`handleChange`** — selection add/remove logic; see the Behavioral Contract "Selection Changes" section.
+14. **Main render** — a multi-select autocomplete widget with: `multiple`, `fullWidth`, `disableCloseOnSelect` set; `options={itemsTree}`, `value={selectedItems}`; `getOptionLabel` returning `option?.primary`; `onChange={handleChange}`; and a `renderInput` producing a text field with `label`, `placeholder`, `size='small'`, `variant='outlined'`, and `onChange={onSearchHandler}`.
 
 ## Behavioral Contract
 
@@ -140,16 +93,7 @@ Build a `dataConfig` object (memoized with deep comparison) containing:
 
 ### Data API Initialization
 
-In `useEffect` watching `dataConfig` (non-associated lists):
-
-```
-PCore.getDataApi().init(dataConfig, contextName).then(dataObj => {
-  dataApiObj.current = dataObj
-  if (!isGroupData) {
-    getCaseListBasedOnParamsDebounced.current(inputValue ?? '', '', [...selectedItems], [...itemsTree])
-  }
-})
-```
+In a lifecycle effect watching `dataConfig` (non-associated lists), call `PCore.getDataApi().init(dataConfig, contextName)`. When the promise resolves with a data object: store it in the `dataApiObj` instance reference, and when `isGroupData` is false, invoke the debounced search function with the current `inputValue` (or `''`), an empty group, a copy of `selectedItems`, and a copy of `itemsTree`.
 
 ### Search
 
@@ -164,8 +108,8 @@ PCore.getDataApi().init(dataConfig, contextName).then(dataObj => {
 
 ### Mount Effects
 
-- `useEffect([pConn])`: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
-- `useEffect([])`: set up debounced search ref.
+- A lifecycle effect watching the PConnect instance: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
+- A mount lifecycle effect: set up the debounced search reference.
 
 ### Selection Changes (`handleChange`)
 
@@ -202,35 +146,11 @@ No explicit `displayMode` handling in the reference implementation — Multisele
 | Placeholder     | From `placeholder` prop                                                |
 | Error state     | Red border + red helper text                                           |
 
-**CSS-only notes:**
-
-```css
-.multiselect-tags {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px;
-  padding: 4px;
-  border: 1px solid rgba(0, 0, 0, 0.23);
-  border-radius: 4px;
-}
-.multiselect-tag {
-  background: rgba(0, 0, 0, 0.08);
-  border-radius: 16px;
-  padding: 2px 8px;
-  font-size: 0.8125rem;
-  display: flex;
-  align-items: center;
-  gap: 4px;
-}
-.multiselect-tag-delete {
-  cursor: pointer;
-  font-size: 0.75rem;
-}
-```
+**Visual-only styling notes:** Selected values render as wrapping flex tags inside a bordered, rounded input container with a small gap and padding. Each tag has a light grey pill background, rounded corners, small padding, and a small font size, laid out as a flex row with a delete affordance at a slightly smaller font size and a pointer cursor.
 
 ## Edge Cases & Special Logic
 
-- **`dataConfig` deep memoization:** Use custom deep-equal hook (`useDeepMemo`) to avoid re-initializing data API on every render.
+- **`dataConfig` deep memoization:** Use a deep-equality memoization utility to avoid re-initializing data API on every render.
 - `itemsTreeBaseData` is fixed at render time — used as the base for each fresh search.
 - When `isGroupData=false`: debounced search fires after data API init.
 - When `isGroupData=true`: groups are pre-populated from `groupDataSource`.
@@ -238,21 +158,20 @@ No explicit `displayMode` handling in the reference implementation — Multisele
 
 ## Dependencies
 
-- `doSearch`, `getDisplayFieldsMetaData`, `useDeepMemo`, `preProcessColumns`, `getGroupDataForItemsTree` from `./utils` (local utils file).
-- `insertInstruction`, `deleteInstruction` from `../../helpers/instructions-utils`.
-- `debounce` from `throttle-debounce` library (or any debounce utility).
+- Local utility helpers: `doSearch`, `getDisplayFieldsMetaData`, a deep-memoization utility, `preProcessColumns`, `getGroupDataForItemsTree`.
+- The project's instruction helpers (`insertInstruction`, `deleteInstruction`).
+- A debounce utility.
 - `PCore.getDataApi()` — for data initialization.
-- Multi-select autocomplete UI widget.
+- A multi-select autocomplete UI widget from the design system.
 
 ## Design System Mapping
 
 **UI control type:** Multi-select combobox with tags/chips and searchable dropdown.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                |
-| ------------------ | ---------------------------------------------------- |
-| Default (CSS only) | Custom tag input + filterable dropdown list          |
-| MUI                | `<Autocomplete multiple disableCloseOnSelect>`       |
-| Ant Design         | `<Select mode="multiple" showSearch>`                |
-| Chakra UI          | Third-party multi-select (e.g., Chakra React Select) |
+- **Multi-select autocomplete** → use the DS's multi-select combobox with tag/chip display and searchable dropdown
+- **Disable close on select** → the dropdown should stay open after each selection
+- **Option label** → display `option.primary`
+- **Selected items** → render as tags/chips inside the input area
+- **Search input** → wired to the debounced search function