@pega/sdk 0.0.13 → 0.0.14

package/templates/react-sdk-reference/.ai-common/skills/template-skills/SimpleTable.md

@@ -18,134 +18,143 @@ Entry-point template for embedded table data in a form or detail view. Routes to
 
 ## Inputs
 
-| Prop                   | Type       | Required | Description                                                                               |
-| ---------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- |
-| `multiRecordDisplayAs` | `string`   | No       | `'fieldGroup'` delegates to FieldGroupTemplate; else table                                |
-| `fieldMetadata`        | `object`   | No       | Field-level metadata including `dataRetrievalType`                                        |
-| `referenceList`        | `string`   | No       | Property path to the reference list                                                       |
-| `displayAs`            | `string`   | No       | For SimpleTableSelectReadonly: `'readonlyMulti'`, `'combobox'`, `'checkboxgroup'` routing |
-| `selectionMode`        | `string`   | No       | `'single'` or `'multi'` (for SimpleTableSelect)                                           |
-| `displayMode`          | `string`   | No       | `'DISPLAY_ONLY'` triggers read-only sub-variant                                           |
-| `readOnly`             | `boolean`  | No       | Alternative read-only flag                                                                |
-| `getPConnect`          | `function` | Yes      | PConnect getter                                                                           |
+| Name                   | Type                 | Description                                                                                     |
+| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
+| `getPConnect`          | accessor             | The PConnect accessor                                                                           |
+| `multiRecordDisplayAs` | `string` (optional)  | `fieldGroup` routes to the repeating-group template; anything else to a table                   |
+| `fieldMetadata`        | `object` (optional)  | Field metadata, including its `type`, its `dataRetrievalType` and its datasource parameters     |
+| `referenceList`        | `string` or `list`   | The router receives the list path; the manually-fed table receives the resolved list of records |
+| `contextClass`         | `string` (optional)  | The records' class; when absent, taken from the list property's field metadata `pageClass`      |
+| `allowActions`         | `object` (optional)  | `allowAdd`, `allowEdit`, `allowDelete`, `allowDragDrop`                                         |
+| `allowTableEdit`       | `boolean` (optional) | When false, hides add and delete and disables reordering                                        |
+| `editMode`             | `string` (optional)  | `modal` or `tableRows`                                                                          |
+| `editModeConfig`       | `object` (optional)  | The add-and-edit targets — see the EmbeddedDataMulti skill                                      |
+| `renderMode`           | `string` (optional)  | `ReadOnly` or `Editable`                                                                        |
+| `uniqueField`          | `string` (optional)  | Property that receives a fresh identifier on every inserted record                              |
+| `targetClassLabel`     | `string` (optional)  | Used in the add caption                                                                         |
+| `displayAs`            | `string` (optional)  | For the read-only selection variant: `readonlyMulti`, `combobox` or `checkboxgroup`             |
+| `selectionMode`        | `string` (optional)  | `single` or `multi`, for the selection variant                                                  |
+| `displayMode`          | `string` (optional)  | A display-only value forces read-only behaviour                                                 |
+| `readOnly`             | `boolean` (optional) | Alternative read-only flag                                                                      |
 
 ## Implementation Structure
 
 ### SimpleTable (router)
 
-**Module Setup:** The component depends on the project's component registry (to resolve `ListView`, `FieldGroupTemplate`, and `SimpleTableManual`) and the project's simple-table helper utilities (`buildMetaForListView` and `getContext`).
+**Module Setup:** The component depends on the project's component registry, which resolves `ListView`, `FieldGroupTemplate` and `SimpleTableManual`, and on the project's simple-table helpers, which build a list-view configuration and read the list path.
 
-**Main Component Logic** — steps in order:
+**Main Component Logic** — in order:
 
-1. Resolve `ListView`, `FieldGroupTemplate`, and `SimpleTableManual` from the project's component registry; receive `getPConnect`, `multiRecordDisplayAs`, `allowTableEdit`, `fieldMetadata`, `displayMode`, and other relevant inputs.
-2. **Route to `fieldGroup`:** when `multiRecordDisplayAs === 'fieldGroup'`, render `FieldGroupTemplate` with all inputs plus `contextClass`.
-3. **Route to a read-only reference list:** when `fieldMetadata?.type === 'Page List'` and `fieldMetadata?.dataRetrievalType === 'refer'`, build `metaForListView` via `buildMetaForListView(...)` and render `ListView` with the list-view inputs plus `bInForm: true` and `displayMode`.
-4. **Route to the editable table:** otherwise, render `SimpleTableManual` with all inputs plus `contextClass`.
+1. **Resolve the class.** When `contextClass` is absent, take the `pageClass` from the field metadata of the list property named by the configuration's `referenceList`.
+2. **Repeating group.** When `multiRecordDisplayAs` is `fieldGroup`, render `FieldGroupTemplate` with every input plus the class, and stop.
+3. **Read-only reference list.** When the field metadata's `type` is `Page List` and its `dataRetrievalType` is `refer`, build a list-view configuration from the field metadata, the raw column descriptors, the label and the parameters; create an accessor for it once, with `PCore.createPConnect(...)`, in the current context and page reference — plus the list path when display-only — and render `ListView` inside a form with that accessor, and stop.
+4. **Allow settings.** When an edit mode is set and allow settings exist — or the configuration allows row editing — hide the add, delete and edit affordances whose allow flag is false, and pass the row-editing flag and the edit flag through. Otherwise, when `allowTableEdit` is false, hide add and delete and disable reordering.
+5. **Editable table.** Render `SimpleTableManual` with every input, the class, and the settings from step 4.
 
-### SimpleTableManual (editable table — ~600+ lines)
+### SimpleTableManual (manually-fed table)
 
-Key structural outline:
-
-- `getReferenceList(pConn)` + `setReferenceList`
-- `buildElementsForTable()` — creates PConnect views per cell
-- `generateRowsData()` — for read-only/modal mode
-- `addRecord()` / `deleteRecord()` / `editRecord()` with modal support
-- Sort/filter/column menu (same pattern as ListView)
-- Render: Table with header sort + body rows + add/delete controls
+The largest of the variants. It reads its rows from the resolved list, its columns from its own raw configuration, and writes every change through the accessor's list actions or the embedded-data modal. Its full contract is under Behavioral Contract. Split the implementation into small pieces — column resolution, row formatting, add, edit, delete, sort and filter — using whatever composition mechanism the target framework offers.
 
 ### SimpleTableSelect (selection wrapper)
 
-Retrieve `ListView` and `PromotedFilters` from the component registry. Build an `additionalTableConfig` incorporating `selectionMode` and `compositeKeys`. When promoted filters are configured, render `<PromotedFilters ... />`; otherwise render `<ListView {...listViewProps} />` directly.
+A router first: when the configuration's `selectionMode` is `multi` and `renderMode` is `ReadOnly`, render `SimpleTableManual` with every input. Otherwise render the selectable table below.
+
+The selectable table receives everything through its **own** configuration, because the reference field creates it with `getPConnect().createComponent` — including the table preset that carries its columns. It never builds, filters or reorders columns. It:
+
+1. Resolves `ListView` and `PromotedFilters` from the registry.
+2. Clears the label when the inherited `showLabel` is false.
+3. Derives the **composite keys** from the field metadata of the selection list: for multi-selection the list's property name, for single selection the relationship context under the current page reference. Every data page parameter whose bound path points back into that property is a composite key, named by its last segment.
+4. In multi-selection, the first time it is displayed and before painting, registers `selectionList` in its state inputs with `setStateProps` and calls `getPConnect().getListActions().initDefaultPageInstructions(selectionList, compositeKeys)`. Without this, checked rows are never saved to the case.
+5. Chooses the preselected values: the read-only context list for multi-selection, the context page for single selection, and none for advanced search.
+6. Renders `ListView` with all of its own inputs plus: the resolved label as the title, `globalSearch` true, `personalization`, `grouping` and `editing` all false, `basicMode` true, the composite keys, the preselected values, the view name, the parameters, the raw `searchFields`, and an item key of `$key`. When promoted filters are configured and switched on, render `PromotedFilters` around the same inputs instead.
 
-### SimpleTableSelectReadonly (link + modal)
+Both table presentations of a reference field arrive here and render identically. Grouping is switched off, and configured filters, sort, row density and column visibility are not supported — ignore them.
 
-Renders a `SemanticLink` per selected item (comma-separated). When the list has more than 5 items, show a "(N Total)" link that opens a modal. The modal renders a `<Dialog>` wrapping a read-only `<SimpleTableManual readOnly ... />`.
+### SimpleTableSelectReadonly (links and a list dialog)
+
+Shows each selected record as a link, separated by commas. When more than five are selected, show the first five followed by a link reading the total count, which opens a dialog holding a read-only `SimpleTableManual` of every selected record.
 
 ## Behavioral Contract
 
 ### SimpleTable — Routing Logic
 
-When `multiRecordDisplayAs === 'fieldGroup'`, render `FieldGroupTemplate`. Otherwise, when `fieldMetadata.dataRetrievalType === 'refer'`, render `ListView` (read-only, `bInForm: true`). Otherwise, render `SimpleTableManual` (the editable table).
+First match wins: `fieldGroup` goes to `FieldGroupTemplate`; a `Page List` field whose data retrieval type is `refer` goes to a read-only `ListView` inside a form; everything else goes to `SimpleTableManual`.
 
-### SimpleTableManual — Full Editable Table
+### SimpleTableManual — Manually-Fed Table
 
-Full editable table with add/delete rows, inline editing, sort, filter, and column customization (~600+ lines).
+A table whose rows are the case's own records, with add, edit, delete, reorder, inline editing, sort and filter.
 
 Key behaviors:
 
-1. **Row data source:** `referenceList` property path via `pConn.getValue(referenceList + '.pxResults')`.
-2. **Add row:** `pConn.getListActions().insert({})`.
-3. **Delete row:** `pConn.getListActions().deleteEntry(index)`.
-4. **Inline field editing:** Each cell renders the field's registered edit component via `buildView(pConn, rowIndex, colFieldName)`.
-5. **Sort:** Client-side sort on loaded data.
-6. **Column customization:** Visibility toggles per column via a settings popover.
-7. **Filter dialog:** Same filter pattern as ListView.
+1. **Row data source:** the resolved `referenceList` input, which is the list of records itself. Register it with `pConn.setReferenceList(...)`. When it is empty and a `dataPageName` is supplied, fetch the rows from that data page instead, using the parameters from `fieldMetadata`.
+2. **Columns:** the children of the first child region in the raw configuration, or of the first preset's first region. An entry whose value is `pyPrimaryFields`, or its namespace-qualified form, is replaced in place by the descriptors of the primary-fields view resolved with `PCore.getMetadataUtils().resolveView(...)`, choosing the resolved view whose class is the table's `contextClass`; then duplicates by bound path are removed. Every descriptor is rendered through the registry by its own type. A descriptor whose configuration sets `hide` is never shown.
+3. **Add row:** when adding and editing happen in a modal and a view or an action is configured, call `getPConnect().getActionsApi().openEmbeddedDataModal(view, pConn, listPath, listLength, PCore.getConstants().RESOURCE_STATUS.CREATE, targetClassLabel, editType, actionId)`. Otherwise insert with `pConn.getListActions().insert(payload, listLength)`, where the payload carries the table's class as `classID` and, when `uniqueField` is set, a fresh identifier under that property.
+4. **Edit row in a modal:** call `openEmbeddedDataModal` with the edit view when a separate one is configured, otherwise the add view, the row index, `RESOURCE_STATUS.UPDATE`, the class label, the edit type, and the edit action — the separate one when configured, otherwise the add action.
+5. **Delete row:** `pConn.getListActions().deleteEntry(index)`. A row may be deleted only when deletion is shown and the raw `allowRowDelete` is absent or true, or — when it is an expression-marked string — when `PCore.getExpressionEngine().evaluate(expression, row)` returns true for that row.
+6. **Page instructions:** before first painting, call `getPConnect().getListActions().initDefaultPageInstructions(...)` with the list path — plus the column names, excluding attachments, in the modal flow, or plus `uniqueField` otherwise.
+7. **Inline field editing:** each cell renders the field's registered edit component for that row.
+8. **Read-only cells:** each value is formatted by its descriptor's type, with a checkbox shown through its true and false labels.
+9. **Sort and filter:** client-side, from the column menu, on loaded data.
+10. **Add caption:** `Add` followed by the class label when one is available, otherwise `Add`, both localized.
+11. **Containment:** the table scrolls horizontally inside its own container, never widening the form around it.
 
 ### SimpleTableSelect — Selection Mode
 
 Wraps `ListView` with additional selection configuration:
 
-- Passes `additionalTableConfig` with `selectionMode: 'single'` or `'multi'`.
-- On selection: calls `pConn.getListActions().setSelectedRow(selectedData)`.
-- Used when `DataReference` routes to table-based selection.
+- Passes `selectionMode` of `single` or `multi`, the composite keys and the preselected values.
+- Selection is written by `ListView` through `getPConnect().getListActions().setSelectedRows(...)` and `clearSelectedRows()` — see the ListView skill. There is no `setSelectedRow` call.
+- Used when a reference field routes to table-based selection.
 
-### SimpleTableSelectReadonly — Read-Only with Modal
+### SimpleTableSelectReadonly — Read-Only with a List Dialog
 
-1. Renders a link/chip showing the current selection count.
-2. On click: opens a `<Dialog>` containing a `<SimpleTableManual>` in read-only mode.
-3. Inputs: same as `SimpleTableManual` but all fields locked (no add/delete/edit).
+1. Shows the selected records as links, as described above.
+2. The total-count link opens a dialog containing `SimpleTableManual` in read-only mode.
+3. Inside the dialog every field is locked: no add, delete or edit.
 
 ## Visual Specifications
 
 ### SimpleTableManual
 
-| Element         | Description                                            |
-| --------------- | ------------------------------------------------------ |
-| Toolbar         | Column settings button, filter button, optional search |
-| Table           | Full-width, alternating row colors                     |
-| Add row         | `"+ Add row"` button below the table                   |
-| Delete row      | Trash icon per row (rightmost column)                  |
-| Column settings | Popover with checkboxes for visibility toggles         |
-
-**CSS-only implementation notes:**
+| Element    | Description                                                          |
+| ---------- | -------------------------------------------------------------------- |
+| Table      | Full width of its container, inside its own horizontal scroll region |
+| Header     | Column labels, with a menu for sorting and filtering                 |
+| Add        | An add action below the table, captioned as described above          |
+| Row delete | A delete action at the end of each row that may be deleted           |
+| Row edit   | An edit action per row when editing happens in a modal               |
 
-- Table: `width: 100%; border-collapse: collapse`.
-- Add row button: `margin-top: 0.5rem; text-align: left`.
-- Delete cell: `width: 40px; text-align: center`.
-- Read-only mode: hide add/delete controls; cells show plain text.
+In read-only mode, hide the add, delete and edit actions, and show each cell as formatted text. Keep the delete column narrow and centred, and align the add action with the table's start edge.
 
 ### SimpleTableSelectReadonly
 
-| Element     | Description                                        |
-| ----------- | -------------------------------------------------- |
-| Trigger     | Link or chip showing selection count               |
-| Modal       | Full-screen or large dialog with SimpleTableManual |
-| Modal close | `X` button in modal header                         |
+| Element      | Description                                         |
+| ------------ | --------------------------------------------------- |
+| Trigger      | The selected records as links, then the total count |
+| Dialog       | A large dialog holding the read-only table          |
+| Dialog close | A close control in the dialog header                |
 
 ## Edge Cases & Special Logic
 
-- `multiRecordDisplayAs === 'fieldGroup'` — completely bypasses table; delegates to `FieldGroupTemplate`.
-- `dataRetrievalType === 'refer'` — data comes from a reference list, not a full data page; use `ListView` in read-only mode.
-- `SimpleTableManual` with 600+ lines — break into sub-hooks if re-implementing.
-- Row keys must be unique — use composite keys from `compositeKeys` config if available.
-- Column customization state is local — not persisted across navigation.
+- The repeating-group route bypasses the table entirely.
+- A `refer` page list gets its rows from a data page, not from the case, so it goes to a read-only `ListView`.
+- Row identity must be unique: use the composite keys when they are supplied.
+- Sort and filter choices are the user's own and are not persisted across navigation.
 
 ## Dependencies
 
-- `FieldGroupTemplate` (for `multiRecordDisplayAs === 'fieldGroup'` routing)
-- `ListView` (for `dataRetrievalType === 'refer'` routing)
-- `buildView` from the project's field-group utility helpers (for inline cell rendering in SimpleTableManual)
-- The design system's table, dialog, popover, icon button, button, and checkbox components.
+- `FieldGroupTemplate`, for the repeating-group route.
+- `ListView`, for the `refer` route and for selection.
+- The project's helper that builds one field view per row for inline editing.
+- The platform APIs named in this skill: the accessor's list actions and actions interface, `PCore.createPConnect`, `PCore.getMetadataUtils().resolveView`, and `PCore.getExpressionEngine().evaluate`.
+- The design system's table, dialog, menu, icon action, button and checkbox, or native equivalents.
 
 ## Design System Mapping
 
-**UI control type:** Embedded data table with routing to field group, read-only list, or fully editable table.
-
-When implementing in a specific design system, map the following:
+**UI control type:** Embedded data table that routes to a repeating group, a read-only list, or an editable table.
 
-- **SimpleTableManual** → use the DS's table component with add/delete row controls and inline editing
-- **SimpleTableSelect** → use `ListView` with selection mode enabled, optionally with promoted filters
-- **SimpleTableSelectReadonly** → render selected values as chips/links that open a modal with full list view
-- Always check `multiRecordDisplayAs === 'fieldGroup'` first — this bypasses the table entirely
-- `SimpleTableManual` add/delete row controls must be hidden when `readOnly === true` or `displayMode === 'DISPLAY_ONLY'`
-- `SimpleTableSelect` uses the same `ListView` but adds selection callbacks
+- **SimpleTableManual** → the design system's table, with add, edit and delete actions and inline editing
+- **SimpleTableSelect** → `ListView` with a selection mode, optionally inside promoted filters
+- **SimpleTableSelectReadonly** → links for the selected records, opening a dialog with the full list
+- Check the repeating-group route first — it bypasses the table entirely
+- Hide the add, edit and delete actions whenever the table is read-only or the surrounding view is display-only