@pega/sdk 0.0.13 → 0.0.14

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

@@ -1,56 +1,51 @@
 # Skill: ListView
 
-Full-featured list view template. Renders a data table with sorting, pagination, global search, single/multi selection, column menu, and filter dialog.
+Data table template. Renders the rows of a data page as a table with configured columns, sorting, paging, search, and single or multiple selection.
 
 > **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
 
 ---
 
-> ⚠️ **CRITICAL — `referenceList` is a STRING, not an array**
+> ⚠️ **CRITICAL — `referenceList` names a data page; it is not a list of rows**
 >
-> The `referenceList` prop is a **data page reference string** (e.g., `".D_pyMyWorkList.pxResults"`) — NOT an array of data rows. You MUST:
->
-> 1. Check `typeof referenceList === 'string'` before using it
-> 2. Call `PCore.getDataApiUtils().getData(referenceList, payload)` to fetch actual row data
-> 3. Initialize row state as empty array
-> 4. NEVER put `referenceList` directly into state or call `.filter()` on it
->
-> Do NOT initialize row state directly from `referenceList` (e.g. as the initial state value) — this crashes later with "rows.filter is not a function" because `referenceList` is a string, not an array. Instead, initialize rows as an empty array and populate them inside a lifecycle effect keyed on `referenceList`: if `referenceList` happens to already be an array, use it directly; otherwise resolve a `dataRef` from `referenceList` (falling back to `dataPageName`) and, when present, call `PCore.getDataApiUtils().getData(dataRef, payload ?? {})`, storing the resolved rows from `response?.data?.data ?? response?.data?.pxResults ?? []` on success, or an empty array on failure.
+> `referenceList` holds the **name of a data page**, such as `D_pyMyWorkList`. It is never the rows themselves. Start with an empty row list, fetch the rows from the data page as described under Data Fetching, and only then populate the table. Treating the name as a list — storing it as the rows, or filtering it — fails as soon as the table first renders.
 
 ---
 
-> ⚠️ **CRITICAL — Column definitions MUST come from PConnect presets metadata**
->
-> The table must render ONLY the columns configured in the Pega view metadata — NOT all fields from the raw data response. Raw responses contain 20+ internal fields (`pzInsKey`, `pxRefObjectClass`, `pyAssignmentStatus`, etc.) that should never be shown.
+> ⚠️ **CRITICAL — Columns come from this table's own presets, in configured order, and nowhere else**
 >
-> **How to extract configured columns:**
+> The table shows exactly the columns configured in the view — no more, no fewer, in the configured order, with the configured labels. It never looks at the data rows to decide what to show.
 >
-> 1. Get column fields from presets: `getPConnect().getComponentConfig().presets[0].children[0].children`
-> 2. Get field definitions (labels, types) from metadata: `PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, false)`
-> 3. Map each preset column to its field definition to build `{id, label, type, displayAsLink}` headers
+> Work out the columns in this order:
 >
-> Do NOT derive columns by taking `Object.keys(rows[0])` and mapping each key to `{ id: key, label: key }` — that shows every raw data key, including internal fields like `pzInsKey` and `pxRefObjectClass`. Instead, extract the configured columns from PConnect presets plus the analytics metadata: read `componentConfig = getPConnect().getComponentConfig()`; read `columnFields = componentConfig.presets[0].children[0].children`; await `metaResponse = PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, false)` and take `fieldDefs = metaResponse?.data?.fields ?? []`; then map each entry in `columnFields` (with its index) to a column definition: strip the annotation prefix from `field.config.value` (format `"@P .pyID"`, take the substring after the first space, then strip a leading `.` if present) to get `fieldId`; read `additionalDetails` from `field.config` (default `{}`) and compute `displayAsLink` as true when `additionalDetails.type === 'DISPLAY_LINK'` or when `field.config.displayAsLink` is set; build `{ id: fieldId, label: fieldDefs[index]?.label ?? field.config.label ?? fieldId, type: field.type, displayAsLink, classID: fieldDefs.find(f => f.name === fieldId)?.classID }`.
+> 1. **Read the configured fields** from this table's own configuration: the children of the first region of the first preset, in the raw configuration returned by `getPConnect().getRawMetadata().config`. The same list is reachable through `getPConnect().getComponentConfig()`. The presets are put there by whoever created this table — a reference field or a list page — through `getPConnect().createComponent`. **If there are no presets, the parent wired the table wrongly.** Render nothing, report the missing presets, and never guess columns.
+> 2. **Fetch the metadata** with `PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, showDynamicFields)`. Its `data` carries `fields`, `classID`, `isQueryable` and `primaryFields`. Also fetch the report columns with `PCore.getAnalyticsUtils().getFieldsForDataSource(referenceList, false, contextName)`, treating a failure as an empty list; each entry names a field in `pyFieldName`.
+> 3. **Expand a primary-fields entry.** A configured entry whose value is `pyPrimaryFields`, or its namespace-qualified form, stands for the data page's primary fields. Replace it, in place, with one descriptor for each name in `primaryFields` that is not already configured, built from the matching metadata field. When there are no primary fields, simply remove the entry.
+> 4. **Build one column definition per configured field**, in order:
+>    - **Name:** the field's value with its marker and following space removed, then its leading separator — `@P .ConfirmationNumber` becomes `ConfirmationNumber`. The name is the row key for the cell.
+>    - **Label:** a field-label marker (`@FL`) is resolved by looking the property up with `PCore.getMetadataUtils().getPropertyMetadata(propertyName, classID)` and taking its label or caption. Localize that with `PCore.getLocaleUtils().getLocaleValue(label, localeKey, bundle)`, where the locale key is the property's defining class — falling back to its class, then the metadata's class — joined to the property name by a separator, and the bundle is `PCore.getLocaleUtils().FIELD_LABELS_BUNDLE_KEY`. A localization marker (`@L `) is removed. Plain text is used as it is. Then localize the header once more with `PCore.getLocaleUtils().getLocaleValue(label, localeReference)`.
+>    - **Type:** the descriptor's own `type`. It decides the cell format and whether the column is numeric.
+>    - **Shown:** the descriptor's `show` flag, default true, and never when the descriptor is marked hidden.
+> 5. **Extra fields are for the query only.** Metadata fields that are not configured but appear in the report columns are added to the query's select list when the data page is queryable, so that dependent data arrives. They are never displayed.
 >
-> **Key points:**
->
-> - `field.config.value` has format `"@P .pyID"` — strip annotation prefix to get field name
-> - `fieldDefs[index].label` provides the localized display label
-> - `displayAsLink` determines if the cell renders as a clickable navigation link
-> - If `presets` is unavailable (fallback), use first ~6 fields from `fieldDefs` — NEVER use raw data keys
+> Never filter configured columns by name or prefix: `px` and `py` properties such as `pxCreateSystemID` are valid, configured columns. Never map a column to a metadata field by position — the metadata's field order has nothing to do with the configured order.
 
 ---
 
-> ⚠️ **CRITICAL — Data fetching differs by `bInForm`**
+> ⚠️ **CRITICAL — Data Fetching depends on whether the table sits inside a form**
+>
+> `bInForm` defaults to true.
 >
-> The data API to call depends on whether the ListView is inside a form or on a standalone page: for page-level use (`bInForm = false`, e.g. a worklist landing page), await `PCore.getDataApiUtils().getData(referenceList, payload ?? {})` and read rows from `result?.data?.data ?? []`; for form-level use (`bInForm = true`, e.g. an embedded list in a case form), resolve `context = getPConnect().getContextName()`, await `PCore.getDataPageUtils().getDataAsync(referenceList, context, parameters, null, query)`, and read rows from `result?.data ?? []`.
+> - **Inside a form** (`bInForm` true — a reference field, an embedded list): call `PCore.getDataPageUtils().getDataAsync(referenceList, contextName, parameters, paging, query)`, with the accessor's context name, the parameters, no paging, and the query described below. The rows are at the response's `data`.
+> - **On a page** (`bInForm` false — a worklist or landing page): call `PCore.getDataApiUtils().getData(referenceList, payload)`, passing the payload input or an empty one. The rows are at the response's `data.data`.
 >
-> Using the wrong API will return empty data or fail silently.
+> When the data page is queryable, the query's select list names every column definition, the extra fields, any fields needed for links, and the composite keys. When it is not, send no query. Calling the wrong API returns nothing and fails silently. On failure, show an empty table.
 
 ---
 
 ## Component Purpose
 
-The primary data table component. Renders a sortable, paginated, filterable, and selectable table from a PConnect data source. Supports both standalone page use (`bInForm: false`) and embedded form use (`bInForm: true`). Columns are configurable, and the table supports row-level selection with callback.
+The project's data table. It shows the rows of one data page with the columns its creator configured, and lets the user sort, page through, search and — when a selection mode is given — select rows. It is used both inside forms, where a reference field or an embedded list creates it, and on pages such as worklists.
 
 ## Pega Metadata
 
@@ -60,175 +55,152 @@ The primary data table component. Renders a sortable, paginated, filterable, and
 
 ## Inputs
 
-| Prop                    | Type       | Required | Description                                                                   |
-| ----------------------- | ---------- | -------- | ----------------------------------------------------------------------------- |
-| `bInForm`               | `boolean`  | No       | Whether rendered inside a form (affects toolbar and padding). Default `false` |
-| `selectionMode`         | `string`   | No       | `'single'` (radio) or `'multi'` (checkbox) or absent (no selection)           |
-| `dataPageName`          | `string`   | No       | Name of data page to fetch records from                                       |
-| `referenceList`         | `array`    | No       | In-memory data array (used when data is already available)                    |
-| `compositeKeys`         | `object`   | No       | Key fields for unique row identification                                      |
-| `columns`               | `array`    | No       | Column definition objects `{ fieldName, label, sortable, filterable }`        |
-| `additionalTableConfig` | `object`   | No       | Extra config merged with column/sort/filter settings                          |
-| `isSearchable`          | `boolean`  | No       | Whether global search input is shown                                          |
-| `payload`               | `object`   | No       | Query payload for data page requests                                          |
-| `getPConnect`           | `function` | Yes      | PConnect getter                                                               |
+Most inputs arrive through this component's own configuration, set by whoever created it with `getPConnect().createComponent`. The column list is never an input — it lives in the presets of that configuration.
+
+| Name                  | Type                 | Default | Description                                                                             |
+| --------------------- | -------------------- | ------- | --------------------------------------------------------------------------------------- |
+| `getPConnect`         | accessor             | —       | The PConnect accessor                                                                   |
+| `referenceList`       | `string`             | —       | The data page name                                                                      |
+| `bInForm`             | `boolean` (optional) | `true`  | Inside a form, or on a page. Chooses the data API and tightens the layout               |
+| `parameters`          | `object` (optional)  | —       | Data page parameters, a flat map from name to value                                     |
+| `payload`             | `object` (optional)  | —       | Request payload for the page-level data API                                             |
+| `selectionMode`       | `string` (optional)  | —       | `single`, `multi`, or absent for no selection                                           |
+| `compositeKeys`       | `list` (optional)    | —       | Property names that together identify a row                                             |
+| `selectedValues`      | `list` (optional)    | —       | Records already selected, used to pre-check rows in multi-selection                     |
+| `readonlyContextList` | `list` (optional)    | —       | Fallback for `selectedValues`                                                           |
+| `value`               | `string` (optional)  | —       | The bound identity in single selection, used to preselect a row                         |
+| `referenceType`       | `string` (optional)  | —       | `Data` or `Case`; decides the default row identity                                      |
+| `globalSearch`        | `boolean` (optional) | —       | Shows the search input above the table                                                  |
+| `title`               | `string` (optional)  | —       | The heading shown above the table                                                       |
+| `localeReference`     | `string` (optional)  | —       | The localization bundle used for column headers                                         |
+| `showDynamicFields`   | `boolean` (optional) | `false` | Passed to the metadata call; also makes every metadata field eligible as an extra field |
+| `viewName`            | `string` (optional)  | —       | Identifies the table for search-and-select events                                       |
+| `displayAs`           | `string` (optional)  | —       | The presentation that created the table; only `advancedSearch` changes behaviour        |
 
 ## Implementation Structure
 
-> ⚠️ **CRITICAL — USE THE PROJECT'S DESIGN SYSTEM FOR TABLE RENDERING**
->
-> This component MUST use the **installed design system's table components** — NOT plain HTML `<table>/<thead>/<tbody>`.
-> Check the project's dependencies for the installed design system and use its table primitives. The table MUST look like a proper data grid with:
->
-> - Column headers with field labels (from PConnect presets metadata)
-> - Paginated rows (not all rows at once)
-> - Clickable link cells for navigation
-> - Search toolbar (when `globalSearch !== false`)
->
-> Do NOT render raw `Object.values(row)` or dump all data keys as columns, and do NOT use plain HTML when a design system is installed.
-
-This is the largest template component. The implementation MUST include these critical sections.
+> ⚠️ **Use the project's design system for the table** when one is installed — its table, pagination, search input, selection controls and links. When none is installed, use the platform's native table elements, applying the containment rules under Visual Specifications. Either way the result is a data grid with column headers, paged rows and, where configured, link cells and a search input.
 
-**Module Setup:** The component depends on local state management, lifecycle effects, and a cached callback. Declare a constant `AssignDashObjects = ['Assign-Worklist', 'Assign-WorkBasket']` (classes whose links should open as assignments rather than plain work items). Define the input contract as an extension of the project's base component interface with optional `bInForm`, `globalSearch`, `referenceList`, `selectionMode`, `referenceType`, `payload`, `parameters`, `compositeKeys`, and `localeReference` fields.
+**Module Setup:** The component depends on the project's component registry and on the platform APIs named in this skill. It holds, across re-renders: the rows, the column definitions, the current page and page size (default 10), the sort column and direction, the search text, and the set of selected row identities.
 
-**Main Component Logic** — steps in order:
+**Main Component Logic** — in order:
 
-1. Receive inputs: `getPConnect`, `bInForm` (default `true`), `globalSearch`, `referenceList`, `payload`, `parameters`, and `localeReference`. Declare local state: `arRows` (array, default `[]`), `arColumns` (array, default `[]`), `page` (default `1`), `pageSize` (default `10`), `searchValue` (default `''`), and `title` (default `''`).
-2. Call `getPConnect()` once into `thePConn`; read `componentConfig = thePConn.getComponentConfig()` and `resolvedConfigProps = thePConn.getConfigProps()`.
-3. **Extract column definitions from PConnect presets** — define a memoized/cached `getHeaderCells(columnFields, fieldDefs)` callback that maps each `columnFields` entry (with its index) to a header descriptor: strip the annotation prefix from `field.config.value` to get `theField` (take the substring after the first space, then strip a leading `.`); find the matching field definition's index in `fieldDefs` via `.findIndex(ele => ele.name === theField)` as `colIndex`; read `additionalDetails` from `field.config` (default `{}`) and compute `displayAsLink` as true when `additionalDetails.type === 'DISPLAY_LINK'` or when `field.config.displayAsLink` is set; return `{ id: theField, type: field.type, displayAsLink, label: fieldDefs[index]?.label ?? field.config.label ?? theField, classID: colIndex > -1 ? fieldDefs[colIndex].classID : undefined, isAssignmentLink: displayAsLink && AssignDashObjects.includes(fieldDefs[colIndex]?.classID) }`.
-4. **Fetch metadata + data** in a lifecycle effect keyed on `[referenceList, bInForm, payload, parameters]`, using an `isActive` flag to guard against updates after unmount:
-   - Await field definitions via `PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, false)`, reading `fieldDefs` from `metaResponse?.data?.fields ?? []`.
-   - Read configured columns from `componentConfig?.presets?.[0]?.children?.[0]?.children ?? []`; when non-empty, build `myColumns` via `getHeaderCells(columnFields, fieldDefs)`, localize each column's `label` through `PCore.getLocaleUtils().getLocaleValue` when `localeReference` is set, and store the result via `setColumns`.
-   - Fetch the row data using the API appropriate to `bInForm` (see the CRITICAL note above): for `!bInForm`, await `PCore.getDataApiUtils().getData(referenceList, payload ?? {})`; for `bInForm`, resolve `context = thePConn.getContextName()` and await `PCore.getDataPageUtils().getDataAsync(referenceList, context, parameters, null, null)`. Extract `tableData` from `dataResult?.data?.data ?? []` (page mode) or `dataResult?.data ?? []` (form mode), and store it via `setRows` (defaulting to `[]` when not an array).
-5. **Link click handling** — define `handleLinkClick(row, column)`: when `column.isAssignmentLink`, destructure `pxRefObjectClass` and `pzInsKey` from `row` and call `thePConn.getActionsApi().openAssignment(pzInsKey, pxRefObjectClass, { containerName: thePConn.getContainerName(), channelName: '' })`; otherwise, resolve `pxRefObjectKey` from `row.pxRefObjectKey ?? row.pzInsKey` and `pxRefObjectClass` from `row.pxRefObjectClass ?? row.pxObjClass`, and when both are present, call `thePConn.getActionsApi().openWorkByHandle(pxRefObjectKey, pxRefObjectClass)`.
-6. Beyond these mandatory sections, a full implementation also needs search, pagination, sort, selection, and rendering logic (see the Behavioral Contract below for each).
-
-> **Note:** The sections above show the MANDATORY patterns. Full implementations will also include sorting, selection, filter dialog, column menus, and PubSub subscriptions for dashboard filters. But the three critical sections above (column extraction, data fetching, link handling) MUST be present for the table to render correctly.
+1. **Receive inputs,** each defaulted as documented.
+2. **Read the configuration.** Take the component configuration from `getComponentConfig()` and the raw configuration from `getRawMetadata().config` on the accessor.
+3. **Derive the row identity** — see Selection.
+4. **Load once, when first displayed:** fetch the metadata and the report columns, build the column definitions as the CRITICAL note on columns describes, then fetch the rows as Data Fetching describes. Store both. Ignore any result that arrives after the component has been removed.
+5. **Reload** when the parameters change, and when a dashboard filter event or a promoted-filter update arrives — see Dashboard Filters.
+6. **Pre-check selected rows** once rows arrive — see Selection.
+7. **Render** the heading, the search input when `globalSearch` is set, the table, and the paging controls — see the Behavioral Contract.
 
 ## Behavioral Contract
 
-### Initialization
-
-The initialization utility (invoked with `getPConnect`, `columns`, `dataPageName`, and `payload`):
-
-1. Calls `initializeColumns(getPConnect, columns)` to build `configFields`.
-2. Calls `buildFieldsForTable(configFields)` to produce display column definitions.
-3. Calls `getConfigFields(configFields)` for sort/filter metadata.
-4. Fetches initial data via `PCore.getDataApiUtils().getDataAsync(dataPageName, payload)`.
-5. Returns `{ tableDataRows, configFields, totalCount }`.
-
 ### Sorting
 
-- `<TableSortLabel>` in each sortable column header.
-- On click: call `PCore.getDataApiUtils().getDataAsync(dataPageName, { ...payload, sortBy, sortOrder })`.
-- `sortBy` = column field name, `sortOrder` = `'ASC'` or `'DESC'`.
+Each column header offers sorting. Activating it sorts the loaded rows by that column — ascending first, and descending when activated again — keeping rows with equal values in their existing order. Sorting never re-fetches.
 
-### Pagination
+### Paging
 
-- `<TablePagination>` component below the table.
-- `rowsPerPageOptions`: `[5, 10, 25]`.
-- On page/rows change: re-fetch with `startIndex` and `maxResults` params.
+The paging control sits below the table, offers 10, 25 and 100 rows per page, and starts at 10. Changing the page size returns to the first page. Paging acts on the loaded rows and never re-fetches.
 
-### Global Search
+### Search
 
-- Shown when `isSearchable === true`.
-- `<TextField>` input above the table (toolbar area).
-- On submit/debounce: re-fetch with `searchText` param.
+Shown when `globalSearch` is set. As the user types, show only the loaded rows in which some displayed column's value, as text, contains the typed text, ignoring case. Hidden and query-only fields are not searched.
 
 ### Selection
 
-| `selectionMode` | Control per row | Callback                     |
-| --------------- | --------------- | ---------------------------- |
-| `'single'`      | `<Radio>`       | `onRowSelect(rowData)`       |
-| `'multi'`       | `<Checkbox>`    | `onRowsSelect(selectedRows)` |
-| absent          | None            | None                         |
+When `selectionMode` is `single`, each row starts with a single-choice control. When it is `multi`, each row starts with a multiple-choice control, and the header carries one that selects or clears every row — shown as partly selected when some rows are. When it is absent, rows have no selection control.
 
-- Select-all checkbox in the header for multi-selection.
-- Selected rows highlighted with `selected` row class.
+**Row identity.** Use the single composite key when exactly one is supplied; otherwise `pyGUID` for a data reference and `pyID` for a case reference.
 
-### Column Menu
+**Writing the selection.** Selection is written through the list actions of `getPConnect().getListActions()`, never by editing rows directly.
 
-- `<MoreVertIcon>` button in each column header.
-- Opens `<Menu>` with options: Show/Hide column, Pin column.
-- Column visibility stored in local state `columnVisibility`.
+- **Single:** call `setSelectedRows` with a one-entry list holding the chosen row's identity — or, with more than one composite key, every composite key's value taken from the fetched row.
+- **Multi, one row toggled:** call `setSelectedRows` with a one-entry list holding the row's identity as above plus a `$selected` flag saying whether it is now checked.
+- **Select all:** clear first with `clearSelectedRows` when some rows were already checked, then call `setSelectedRows` with an entry for every row, each flagged as selected. **Clear all:** `clearSelectedRows`.
+- **Preselection:** rows whose identity appears in the selected values supplied by the parent start checked, for multi-selection; for single selection, the row whose identity equals the bound value starts selected.
 
-### Filter Dialog
+The filter and group settings of a full table are not supported: both table presentations of a reference field render through this one simple table. Ignore any configured filter expression and grouping.
 
-- Filter icon in toolbar or column header.
-- Opens `<Dialog>` with filter form fields for each filterable column.
-- On apply: re-fetch with filter params.
-- `filterData(filters, configFields)` formats filter objects for the API.
+### Column Menu and Filter Dialog — page-level only
 
-### Link Rendering (Navigation)
+On a page (`bInForm` false), each column header also offers a menu whose filter entry opens a dialog. For a text column the dialog offers a comparison — such as contains — and a value; for a date, date-time or time column it offers a date comparison and a date. Applying it filters the loaded rows by every column filter currently set, re-applies the current sort, and marks the column's header as filtered while its value is non-empty. Column filters never re-fetch. Inside a form there is no column menu.
 
-Columns configured with `displayAsLink: true` (or `additionalDetails.type === 'DISPLAY_LINK'`) render as clickable links that navigate to assignments or work items.
+These are the user's own interactive filters. Configured filters and grouping are a separate matter, and are not supported — see Selection.
 
-**Detection logic:**
+### Dashboard Filters
 
-A column is a link when `column.displayAsLink` is true. It's specifically an assignment link when its `classID` is one of the worklist/workbasket classes in `AssignDashObjects = ['Assign-Worklist', 'Assign-WorkBasket']` (i.e. `AssignDashObjects.includes(column.classID)`).
+Once the metadata is loaded, subscribe with `PCore.getPubSubUtils().subscribe(...)` to the dashboard-filter-change and dashboard-filter-clear-all events from `PCore.getConstants().PUB_SUB_EVENTS`, scoped to the accessor's context name, and to the promoted-filters update event from `PCore.getEvents().getTransientEvent()`. A change records the filter by its identifier and re-fetches; clear-all forgets every filter and re-fetches; a promoted-filter update converts each entered value into a filter — contains for text, equals otherwise — and re-fetches. Unsubscribe from all three when the component is removed.
 
-**Click handling:**
+### Link Rendering
 
-| Link type       | API call                                                              | Parameters                                     |
-| --------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
-| Assignment link | `getActionsApi().openAssignment(pzInsKey, pxRefObjectClass, options)` | `options = { containerName, channelName: '' }` |
-| Work item link  | `getActionsApi().openWorkByHandle(pxRefObjectKey, pxRefObjectClass)`  | —                                              |
+A column is a link when its descriptor's `additionalDetails` has the type `DISPLAY_LINK`, or when the descriptor sets `displayAsLink`. A link column is an **assignment link** when its class is `Assign-Worklist` or `Assign-WorkBasket`, and an **association link** when its value carries the case-association marker. Two column names are links even without either setting: `pxTaskLabel`, when the row has a class and an instance key, and `pxRefObjectInsName`, when the row has a class and a reference key.
 
-**Legacy column IDs** that also render as links (even without `displayAsLink`):
+On activation, through the accessor's actions interface:
 
-- `pxTaskLabel` → opens assignment (if `pxRefObjectClass` + `pzInsKey` exist on the row)
-- `pxRefObjectInsName` → opens work item (if `pxRefObjectClass` + `pxRefObjectKey` exist)
+- An assignment link calls `openAssignment(instanceKey, objectClass, options)`, with the row's `pzInsKey` and `pxObjClass` and options naming the primary container and an empty channel.
+- Any other configured link calls `openWorkByHandle(instanceKey, objectClass)`. For an association link, the instance key comes from the row's field formed by the association's category, a colon, and `pzInsKey`.
+- `pxTaskLabel` opens the assignment named by the row's `pzInsKey` and `pxRefObjectClass`, in the accessor's own container. On failure, show a brief error message.
+- `pxRefObjectInsName` opens the work item named by the row's `pxRefObjectKey` and its `pxRefObjectClass` — or, failing that, its `pxObjClass` — when both are present.
 
-### Snackbar Toast
+On a page, link cells render as links. Inside a form, cells show formatted values only.
 
-- Shown on fetch errors or action feedback.
-- Auto-hides after 3000ms.
+### Error Messages
+
+Show fetch and action failures as a brief, dismissible message that hides itself after a few seconds.
 
 ## Visual Specifications
 
-| Element        | Description                                              |
-| -------------- | -------------------------------------------------------- |
-| Toolbar        | Search input + filter button + (optional) action buttons |
-| Table head     | Sticky header with sort labels and column menu           |
-| Table body     | Striped rows, hover state, selected state                |
-| Pagination bar | Below table, page size selector + page nav               |
+| Element     | Description                                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| Heading     | The title, with the search input beside it when shown                                           |
+| Table head  | Stays visible while the body scrolls; carries the sort controls and, on a page, the column menu |
+| Table body  | Hover and selected states on rows                                                               |
+| Paging      | Below the table: a page-size choice and page navigation                                         |
+| Empty state | The localized message "No records found." when there are no rows                                |
+
+**Cell values.** Each cell shows the row's value under the column's name. Format by the column's type: dates and date-times with the locale's long date format (plus the time for a date-time), currency with the locale's currency options, and the numeric types — Decimal, Integer, Percentage, Currency — right-aligned. An empty value shows `---`.
 
-**CSS-only implementation notes:**
+**Containment.** The table must never widen or lengthen its surroundings. Put it in its own scrolling region: it scrolls horizontally when the columns are wider than the space available, and vertically beyond a maximum height, with the header staying in view. The region itself must be allowed to shrink to the width its container gives it, however wide its content — otherwise one wide table widens every field around it.
 
-- Table container: `overflow-x: auto`.
-- Header row: `background: var(--table-header-bg); font-weight: 600`.
-- Selected row: `background: var(--selection-highlight-bg)`.
-- Hover row: `background: var(--hover-bg)`.
-- Sticky header: `position: sticky; top: 0; z-index: 1`.
+**Theme tokens.** Take the header background, the selected-row highlight and the hover highlight from the project's theme tokens rather than fixed colours, and give the header a heavier font weight than the body.
 
 ## Edge Cases & Special Logic
 
-- `bInForm: true` — remove outer padding, hide some toolbar elements.
-- Empty result set — show empty state message `"No records found"`.
-- `compositeKeys` — used for unique row key generation when no single ID field exists.
-- Column visibility changes are local state only — not persisted by default.
-- Large datasets — pagination is mandatory; do not load all rows at once.
+- **Inside a form,** remove the outer padding and the page-level column menu.
+- **No rows:** show the empty-state message.
+- **Composite keys** identify a row when no single identifying property exists — see Selection.
+- **Missing presets** mean the parent wired the table wrongly: render nothing and report it.
+- **A row without `pyGUID` or `pyID`** cannot be selected reliably; report it when a selection mode is set.
+- **Search, sort, paging and column filters** all act on the loaded rows. Only a parameter change, a dashboard filter or a promoted-filter update re-fetches.
 
 ## Dependencies
 
-- Local utility helpers: an initialization utility, `filterData`, `buildFieldsForTable`, `getConfigFields`, `initializeColumns`.
-- `PCore.getDataApiUtils().getData()` and `PCore.getDataPageUtils().getDataAsync()` — data fetching.
-- `PCore.getAnalyticsUtils().getDataViewMetadata()` — column metadata.
-- The design system's table, pagination, dialog, search, and link components.
+- `PCore.getAnalyticsUtils().getDataViewMetadata(...)` and `PCore.getAnalyticsUtils().getFieldsForDataSource(...)` — column metadata and report columns.
+- `PCore.getDataPageUtils().getDataAsync(...)` and `PCore.getDataApiUtils().getData(...)` — rows.
+- `PCore.getMetadataUtils().getPropertyMetadata(...)` and `PCore.getLocaleUtils().getLocaleValue(...)` — labels.
+- The accessor's list actions and actions interface — selection and links.
+- `PCore.getPubSubUtils()` — dashboard and promoted filters.
+- The design system's table, paging, search input, selection controls, dialog and link, or native equivalents.
 
 ## Design System Mapping
 
-**UI control type:** Full-featured data table with sorting, pagination, search, selection, and filtering.
-
-When implementing in a specific design system, map the following:
-
-- **Table** → use the DS's data table component with header/body/row/cell sub-components
-- **Pagination** → use the DS's pagination component (page size selector + page navigation)
-- **Search toolbar** → use the DS's search/text-input component in a toolbar area above the table
-- **Link cells** → use the DS's link component for `displayAsLink` columns
-- **Selection** → use radio (single) or checkbox (multi) components per row
-- **Dialog/Modal** → use the DS's dialog for filter dialogs and column menu
-- **Sorting** → use the DS's sort indicator on column headers (e.g., up/down arrows)
-- `bInForm` affects layout — tighten spacing and remove outer chrome when `true`
-- Sorting, pagination, and search all trigger data re-fetches — do not filter client-side for server-paged data
-- Selection mode (`single`/`multi`) requires different controls and callbacks
+**UI control type:** Data table with sorting, paging, search and selection.
+
+- **Table** → the design system's data table, with its header, body, row and cell parts
+- **Paging** → the design system's pagination, with a page-size choice and page navigation
+- **Search** → the design system's search or text input beside the heading
+- **Link cells** → the design system's link
+- **Selection** → a single-choice control per row for single selection, a multiple-choice control per row and in the header for multi-selection
+- **Filter dialog** → the design system's dialog
+- **Sorting** → the design system's sort indicator on each header
+- **Inside a form** → tighter spacing and no outer chrome
+
+## Generation Self-Check
+
+- Columns come only from this table's own presets, in configured order, and never from the rows.
+- No column is filtered by name or prefix, and no label is taken from metadata by position.
+- The data API matches `bInForm`, and the rows are read from the matching response path.
+- Selection is written through `setSelectedRows` and `clearSelectedRows`, with composite keys when supplied.
+- Configured filters and grouping are ignored; the user's own sort, paging, search and column filters act on the loaded rows.
+- The table scrolls inside its own region and never widens the form around it.