@pega/sdk 0.0.13 → 0.0.14

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

@@ -18,84 +18,102 @@ Renders a typeahead input that shows a dropdown of matching options as the user
 
 ## Inputs (component-specific)
 
-| Name                 | 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 inputs passed through to the autocomplete                |
+| Name                                 | 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 inputs passed through to the autocomplete                                                                                     |
+| `allowCreatingRecords`               | `boolean` (optional)            | Data-reference mode — show a "Create new" action at the foot of the option list. Default `false`                                    |
+| `createNewRecord`                    | `function` (optional)           | Data-reference mode — starts creation of a new referenced record. Supplied by the reference field only when the user may create one |
+| `onCreateNew`                        | `function` (optional)           | Replaces the whole create-new flow when supplied                                                                                    |
+| `createNewLabel`                     | `string` (optional)             | Caption of the create-new action. Default `Create new`                                                                              |
+| `contextClass`                       | `string` (optional)             | Data-reference mode — the class of the referenced record                                                                            |
+| `referenceType`                      | `string` (optional)             | Data-reference mode — `Data` or `Case`, compared case-insensitively                                                                 |
+| `showFieldMessage` + `messageConfig` | `boolean` + `object` (optional) | Field input warning: when shown and not read-only, `messageConfig.content` replaces the helper text                                 |
+
+Two further keys are read from the component's **own raw configuration**, `getPConnect().getRawMetadata().config`, never from resolved inputs, because resolution would replace their property paths with values: `columnsFormatter`, a list of component descriptors shown as each option's secondary line, and `groupsFields`, a list of descriptors whose first entry groups the options. The reference field supplies both when it creates this component; otherwise both are absent.
+
+**Data-reference mode** is simply this component created by the reference field with `deferDatasource` true and a `datasourceMetadata`. Nothing else switches it on, and every step below applies in both modes.
 
 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`.
+Replace the autocomplete control with the equivalent from your chosen design system.
+
+**Module Setup:** The component depends on the project's component registry, which resolves `TextInput` and `FieldValueList`; a deep-equality utility, for detecting a changed datasource; the project's helper for building an associated option list; and the platform APIs named in this skill. Define the input contract as an extension of the project's field input contract, adding every input in the table above together with `displayMode` and `status`. An option carries a key, which is stored, and a label, which is shown; in data-reference mode it also carries a list of rendered secondary entries, a list of raw secondary strings, and an optional group.
+
+**Main Component Logic** — in order:
+
+1. **Registry lookups.** Resolve `TextInput` and `FieldValueList`.
+2. **Receive inputs,** each defaulted as documented; `value` defaults to empty text.
+3. **Accessor set-up.** Obtain the accessor from `getPConnect()`, its context name from `getContextName()`, its actions interface from `getActionsApi()`, and the bound property name from the `value` entry of `getStateProps()`.
+4. **Working copies.** Take working copies of `listType`, `parameters`, `datasource` (default: an empty list) and `columns` (default: an empty list). The deferred-datasource step replaces them.
+5. **Component state.** Keep three values that survive re-rendering: the typed text, initially empty; the option list, initially empty; and the last datasource seen, initially none.
+6. **Derived values.** The helper text to show is the validation message when there is one; otherwise the field input warning's content when the warning is shown and the field is not read-only; otherwise `helperText`. The selected label is recomputed on every render — see Behavioral Contract item 10 — and is never stored.
+7. **Detect a changed datasource** while rendering, not in a reaction that runs after rendering: when the incoming datasource differs by deep comparison from the last one seen, remember it. That is what reloads an associated list.
+8. **Transform a deferred datasource** — Behavioral Contract item 5.
+9. **Add secondary and group columns, then normalise every column** — items 6 and 7.
+10. **Load associated options** whenever the remembered datasource changes — item 8.
+11. **Load data-page options** once, when the component is first displayed — item 9.
+12. **Display modes,** before anything else is drawn — see Display Mode Rendering.
+13. **Resolve the selected label** — item 10.
+14. **Define the handlers** for selection, typing and create-new — items 11 and 12, and Create New.
+15. **Read-only** — see Read-Only Rendering.
+16. **Editable render** — the design system's combobox, given the options, a way to read an option's label, the selected label, the typed text, the two handlers, the filtering and option layout described under Visual Specifications, the create-new footer, grouping when present, `label`, `placeholder`, `required`, the error state, the helper text, and `testId`.
 
 ## Behavioral Contract
 
-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 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.
-   - 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:**
-    - 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 the resolved label as the `value` override.
-
-## 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 (values not starting with `.` are left unchanged).
-
-### `getDisplayFieldsMetaData(columnList)`
-
-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: for each key in the `params` object, read its `name` and `value` fields and assign `flat[name] = value`. Return the resulting flat map.
+1. **Options.** Each option pairs a key, which is what gets stored, with a label, which is what the user sees.
+2. **Typed text versus selection.** The typed text is component state and changes as the user types, without committing anything. The selected label is recomputed on every render from the options and the stored value.
+3. **Helper text** — as described in Main Component Logic step 6.
+4. **Datasource change detection** happens during rendering, by deep comparison, and is what triggers the associated-list reload.
+5. **Deferred datasource transformation.** Applies only when `deferDatasource` is true and `datasourceMetadata` names a datasource. Then, on the working copies:
+   - The list type becomes `datapage`, and the datasource becomes the metadata's datasource name.
+   - Set `parameters` from the metadata's `parameters`, accepting **both** shapes it arrives in. When every entry is an object carrying a `name` and a `value`, flatten it into a map from each name to its value. Otherwise it is already a flat map from parameter name to value — use it as it is. Flattening a flat map loses every parameter and leaves a parameterised data page with nothing.
+   - Take the display and value properties from the metadata's `propertyForDisplayText` and `propertyForValue`, stripping a leading property-reference marker from each.
+   - Build `columns`. When the incoming `columns` already hold a column marked as the key — which is what the reference field sends — keep every incoming column, so that its hidden composite-key columns and their set-property targets survive. Otherwise build a two-entry list: a key column for the value property whose set-property target is `Associated property`, and a display column for the display property that is primary and usable for search.
+6. **Secondary and group columns:** For each `columnsFormatter` descriptor carrying a value, add a displayed, searchable, secondary column named by that value with its marker and leading separator removed. For each `groupsFields` descriptor, add a hidden, non-searchable column for its property unless one is already present, so the data page returns it.
+7. **Column normalisation:** Remove a leading separator from every column's value.
+8. **Associated options:** When the list type is `associated`, build the options with the project's associated-list helper from the current data, and rebuild them whenever the remembered datasource changes.
+9. **Data-page options:** Loaded once, when the component is first displayed, and skipped when `displayMode` is set or the list type is `associated`. Call `PCore.getDataApiUtils().getData(dataPageName, payload, contextName)`, where the payload carries the parameters under `dataViewParameters` and is omitted when there are none. The rows are at the response's `data.data`. Build one option per row, as follows.
+   - **Key:** the row's value for the key column, falling back to its `pyGUID`.
+   - **Label:** the row's value for the primary column, as text. This is what the input shows and what filtering matches first.
+   - **Secondary entries:** when `columnsFormatter` is present, one entry per descriptor, rendered from the row. For each descriptor, create a temporary accessor with `PCore.createPConnect(...)`, giving it the descriptor as its metadata with its configuration extended by a display-only display mode, the current context name and the `inline-compact` variant, and the row as its custom context. Resolve that accessor's configuration and render the registry component named by the descriptor's own `type`, in display-only mode, with the resolved configuration. This is how an amount appears as `$777.33` and a label as `Amount:`. If creation or rendering fails, fall back to the row's raw value. When `hideFieldLabels` is true, show values without their labels. Without `columnsFormatter`, the secondary entries are the row's values for the other displayed columns.
+   - **Raw secondary text:** the row's raw values for those same descriptors, kept for filtering.
+   - **Group:** when `groupsFields` is present, the row's value for the first group property. Sort the options by group so that each group is contiguous.
+10. **Selected label:** On every render, find the option whose key equals the stored value. The selected label is that option's label, or the stored value itself when no option matches.
+11. **On selection change:**
+    - Extract the key from the selected option (or empty string if cleared, clearing the typed text as well).
+    - Write it with `getPConnect().getActionsApi().updateFieldValue(propertyName, key)`, then trigger the change with `triggerFieldChange(propertyName, key)` on the same actions interface.
+    - For every other column carrying a set-property target, write the chosen row's value for that column into the target: update the target's value with this field as its associated property, then trigger the change on the target.
+    - Once the triggered change settles, call `onRecordChange` — if provided — with the event extended by the key as its `id`.
+12. **On typing:** Update the typed text only. Nothing is committed to the case.
+13. **Read-only:** Find the option whose key equals the stored value, and delegate to `TextInput` with that option's label as its value.
+
+### Create New
+
+Show the create-new action when `allowCreatingRecords` is true: a divider and then a full-width action at the foot of the option popup, captioned `createNewLabel`, which must not close the popup or steal focus before its own activation runs. On activation:
+
+1. If `onCreateNew` is supplied, call it and stop.
+2. Otherwise start creation: call `createNewRecord` when supplied. Without it, open `showDataObjectCreateView(contextClass)` for a data reference, or call `createWork(contextClass, ...)` with the case view closed after creation for a case reference, both on the actions interface.
+3. Once creation has started, re-fetch the options, and subscribe — keyed by the class — to the data-object-created event for a data reference, or the create-stage-done case event for a case reference, both read from `PCore.getConstants().PUB_SUB_EVENTS`.
+4. When the event arrives for this class: clear the contexted data cache with `PCore.getDataApi().clearContextedCache(contextName)`; find the new record — for data, the response data carried by the event; for a case, by re-fetching the options and matching the created identifier; write every set-property column from it, the key going to this field; call `onRecordChange` with the new key as its `id`; re-fetch the options; and unsubscribe.
+
+## Helper Logic
+
+Three small pieces of logic, independent of any design system. Keep each separate from the component so it can be reasoned about on its own.
+
+**Column normalisation.** Produce a new column list in which each column's value has its leading separator removed. Values without one are left unchanged.
+
+**Display-field extraction.** From a column list, find the key column — the first whose key flag is the string `true` — and the displayed columns — those whose display flag is the string `true`. The key property is the key column's value, or `auto` when there is no key column. Among the displayed columns, the one whose primary flag is the string `true` gives the primary property, and each of the others adds a secondary property, in order. The result is one key property, one primary property, and an ordered list of secondary properties.
+
+**Parameter flattening.** When parameters arrive as entries that each carry a `name` and a `value`, produce a map from each name to its value. A map that is already flat is returned unchanged.
 
 ## Display Mode Rendering
 
@@ -108,41 +126,40 @@ Resolve the display label from options and delegate to `TextInput` with the reso
 
 ## 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 the `placeholder` input                                |
+| Property    | Value                                                                  |
+| ----------- | ---------------------------------------------------------------------- |
+| Width       | The full width of its container                                        |
+| Size        | The design system's compact field size                                 |
+| Popup       | Opens below the input and lists the filtered options                   |
+| Input       | Combobox pattern — typing filters; the open control shows every option |
+| Error state | The design system's error treatment on the border and the helper text  |
+| Label       | The design system's standard field label                               |
+| 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.
-- The label-resolution function returns the option's display text (the `value` field).
-- Option equality comparison uses the option's display text.
+- The input shows the typed text while the user is typing, and the selected label otherwise.
+- An option's label is read from its label entry, and two options are the same option when their labels match.
+- Filtering matches the typed text against the option's label joined with all of its raw secondary text.
+- Each option shows its label on the first line and, when present, its secondary entries on a wrapped second line, separated by a middle dot.
+- Grouped options appear under their group's heading.
+- The create-new action, when shown, sits below the options behind a divider.
 
 ## 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 the data-page utility.
-- **Render ordering matters:** display mode checks → `selectedValue` resolution → define event handlers → readOnly check → main editable render. Do not reorder.
+- The input shows the typed text while the user is typing, and the selected label once a selection has been made and nothing is typed.
+- When the stored value is a key not yet among the options — for instance while they are still loading — show the stored value itself.
+- The key is stored; the label is shown.
+- The data page is always queried in the current context, taken from the accessor's context name.
+- **Order matters:** display modes, then the selected label, then the handlers, then read-only, then the editable render. Do not reorder.
 
 ## Dependencies
 
-- 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.
+- A deep-equality utility, for datasource change detection.
+- The project's associated-list helper.
+- The platform APIs named in this skill: `PCore.getDataApiUtils().getData`, `PCore.createPConnect`, the accessor's actions interface, and the publish/subscribe utilities.
+- The project's component registry, resolving `TextInput` for read-only rendering, `FieldValueList` for display modes, and the type of every secondary descriptor.
+- A combobox control from the design system, or one built to the pattern described under Design System Mapping.
 
 ## Design System Mapping
 
@@ -150,8 +167,23 @@ Resolve the display label from options and delegate to `TextInput` with the reso
 
 When implementing in a specific design system, map the following:
 
-- **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)
+- **Autocomplete** → the design system's combobox or autocomplete, with option filtering
+- **Option format** → the option's key is stored and its label is displayed
+- **Read-only mode** → resolve the label and delegate to `TextInput`
+- **Error state** → the design system's error or danger treatment
+- **Combobox behavior** → this component controls both the selected option and the typed text
+- **Rich options** → the design system's option slot, so each option can hold a label line and a secondary line
+- **Create new** → a footer slot inside the option popup
+
+**When the design system has no combobox,** build one to the accessible combobox pattern: a text input that owns a popup list box, opens on click and on the arrow keys, moves the active option with the arrow keys, selects with Enter, closes with Escape, and reports the expanded state and the active option to assistive technology. **Never use a native data-list element.** It cannot show a secondary line or a footer action, does not open reliably on click, and merges options that share a label.
+
+## Generation Self-Check
+
+- Options load from `PCore.getDataApiUtils().getData(...)` and their rows are read from `data.data`.
+- Every option has a non-empty label taken from the primary column; none is built from a resolved property value.
+- `columnsFormatter` and `groupsFields` are read from the raw configuration, and secondary entries are rendered by each descriptor's own type in display-only mode.
+- Parameters reach the data page whichever shape they arrived in.
+- Incoming key and composite-key columns survive the deferred-datasource transformation, and selection writes every set-property target.
+- Selection updates the value, triggers the field change, and only then calls `onRecordChange` with the key as `id`.
+- The create-new action appears only when `allowCreatingRecords` is true, and a created record becomes the selection.
+- No native data-list element is used.