@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,110 @@
+# Skill: InlineDashboard
+
+Inline dashboard template. Renders a dashboard with a title, a main content area, and an optional filter panel whose position is configurable.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders an inline dashboard layout consisting of a title heading, a main content panel, and an optional filter panel. The filter panel position is configurable: `block-start` places filters above the content in a stacked layout; any other position places filters to the side using a 9/3 column split.
+
+## Pega Metadata
+
+- **Registration key:** `InlineDashboard` (in the project's component map)
+- **Category:** Page template — dashboard
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input            | Type             | Required | Description                                                                   |
+| ---------------- | ---------------- | -------- | ----------------------------------------------------------------------------- |
+| `title`          | string           | No       | Dashboard title displayed above the content area                              |
+| `filterPosition` | string           | No       | Filter panel position: `'block-start'` (above) or other (side). Default: side |
+| `children`       | child node array | Yes      | `children[0]` = main content, `children[1]` = filter panel                    |
+| `getPConnect`    | function         | Yes      | PConnect getter                                                               |
+
+## Implementation Structure
+
+**Module Setup:** The component requires the project's base component interface and companion styles for layout classes (header, container, column, filter container, and inline styles).
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: extract `children`, `title`, and `filterPosition`. Treat `children` as a renderable element array (`childrenToRender`).
+2. Compute the side-layout `direction`: `'row-reverse'` when `filterPosition === 'inline-start'`, otherwise `'row'`.
+3. Render a heading (level 4) showing `title`, followed by one of two grid layouts:
+   - **When `filterPosition === 'block-start'`:** a grid container with column-reverse direction (so the filter panel appears visually above the content even though it's declared second in the DOM), containing a full-width item for `childrenToRender[0]` (main content) and a full-width item with `id="filters"` for `childrenToRender[1]` (filter panel).
+   - **Otherwise (side layout):** a grid container with the computed `direction`, containing a 9-column-wide item for `childrenToRender[0]` (main content) and a 3-column-wide item with `id="filters"` for `childrenToRender[1]` (filter panel).
+
+## Behavioral Contract
+
+### Title
+
+- If `title` is non-empty, render a level-4 heading with `title` above the grid.
+
+### Filter Position: `'block-start'`
+
+Stacked layout — filter panel above main content:
+
+- Grid container with column-reverse direction (reverse so filter renders visually above content).
+- Filter panel: full-width (12-column) grid item with `id='filters'`.
+- Main content: full-width (12-column) grid item.
+
+### Filter Position: Other (side)
+
+Side-by-side layout — main content left, filters right:
+
+- Grid container with computed row direction (optionally reversed based on position value).
+- Main content: 9-column-wide grid item.
+- Filter panel: 3-column-wide grid item with `id='filters'`.
+
+### Children Assignment
+
+- `children[0]` = main content panel.
+- `children[1]` = filter panel (may be absent if no filters configured).
+
+## Visual Specifications
+
+### Block-Start Layout (filter above content)
+
+A stacked layout: the filter panel occupies the full width above the main content, which also occupies the full width below it.
+
+### Side Layout (filter to side)
+
+A side-by-side layout: the main content occupies the majority width (75%) on one side, with the filters occupying the remaining width (25%) beside it.
+
+**CSS-only implementation notes:**
+
+- Title: `font-size: 1.5rem; font-weight: 600; margin-bottom: 1rem`.
+- Block-start: `display: flex; flex-direction: column; gap: 1rem` (filter div first in DOM but ordered last visually with `order: -1`).
+- Side: `display: grid; grid-template-columns: 3fr 1fr; gap: 1rem`.
+- Filter panel: `id='filters'` — required for accessibility/selector targeting.
+- Responsive: collapse side layout to stacked on mobile.
+
+**Companion styles** define classes for: header (font-weight 500, font-size 1.25rem), container (vertical margins), column (grid with gap and baseline alignment), filter container (7-column repeat grid), and inline (grid with gap, baseline alignment, top margin).
+
+## Edge Cases & Special Logic
+
+- If `children[1]` is absent (no filters), render only the main content without the grid.
+- Column-reverse direction in block-start mode — in plain CSS, use flexbox column direction with `order` property.
+- `title` is optional — if absent, skip the heading entirely (no empty heading).
+- Filter grid always gets `id='filters'` — this is used by `PromotedFilters` for integration.
+
+## Dependencies
+
+- A design-system heading component (level 4) for the title
+- A design-system grid/layout component for the responsive container
+- Companion styles for spacing and alignment classes
+
+## Design System Mapping
+
+**UI control type:** Dashboard layout with configurable title and filter panel position.
+
+When implementing in a specific design system, map the following: a level-4 heading for the title; a responsive grid container supporting directional flow (row, row-reverse, column-reverse); grid items that accept column-span sizing (full-width for stacked, 9/3 split for side layout). In a CSS-only approach, use a native heading element and CSS grid or flexbox. Other design systems provide equivalent grid and typography primitives.
+
+When implementing:
+
+- `filterPosition === 'block-start'` requires stacked layout (full-width / full-width) — not side layout (9/3)
+- Filter panel must always have `id='filters'`
+- Title heading (level 4) is optional — only render when `title` is provided

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

@@ -0,0 +1,105 @@
+# Skill: InlineDashboardPage
+
+Inline dashboard page template. Builds filter components from promoted filters metadata and delegates rendering to `InlineDashboard`.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — Must use the project's filter-component builder utility**
+>
+> This component MUST use the project's filter-component builder utility (invoked with `getPConnect` and the filters array) to generate proper filter UI components. Without this, dashboard filters will not render correctly.
+>
+> **Mandatory implementation details:**
+>
+> 1. Obtain the filter-component builder utility from the project's SDK bridge layer
+> 2. `getPConnect().getRawMetadata().children[1]` — extract filter metadata
+> 3. Local state for `filterComponents` populated via a lifecycle effect on mount
+> 4. Assemble forwarded children so index 1 contains the built filter components
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] Filter-component builder utility obtained from the project's SDK bridge
+> - [ ] `filterComponents` local state populated via lifecycle effect
+> - [ ] Filter metadata extracted from `getRawMetadata().children[1]`
+> - [ ] InlineDashboard receives filter components as children
+
+---
+
+## Component Purpose
+
+Page-level wrapper for the inline dashboard. Extracts promoted filter definitions from the PConnect metadata, builds filter components from them, and passes them to `InlineDashboard` as the second child (filter panel). The first child (main content) is passed through unchanged.
+
+> See `InlineDashboard.md` for the layout and rendering behavior. This component only handles filter component construction.
+
+## Pega Metadata
+
+- **Registration key:** `InlineDashboardPage` (in the project's component map)
+- **Category:** Page template — dashboard page
+- **Extends:** The project's base component interface
+
+## Inputs
+
+| Input            | Type               | Required | Description                                     |
+| ---------------- | ------------------ | -------- | ----------------------------------------------- |
+| `children`       | child element list | Yes      | Main content children passed to InlineDashboard |
+| `title`          | `string`           | No       | Dashboard title                                 |
+| `filterPosition` | `string`           | No       | Filter position: `'block-start'` or side        |
+| `getPConnect`    | `function`         | Yes      | PConnect getter                                 |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the project's filter-component builder utility from the SDK bridge layer and the `InlineDashboard` component from the project's component registry. The component requires local state management and a lifecycle effect for initialization.
+
+The component's interface extends the project's base component interface with `title: string`, optional `icon?: string`, and optional `filterPosition?: string`.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `InlineDashboard` from the project's component registry. Receive inputs: `children`, `getPConnect`, and `filterPosition` (default `'block-start'`). Declare local state `filterComponents` (array, initially empty). Create a memoized computation that converts children into a flat array.
+2. Build filter components from metadata on mount: read `allFilters = getPConnect().getRawMetadata().children[1]`, then inside a lifecycle effect that runs once on initialization, invoke the project's filter-component builder utility with `getPConnect` and `allFilters`, and store the result in `filterComponents` local state.
+3. Assemble the inputs to forward to `InlineDashboard`: shallow-copy the received inputs into a forwarding object, then set its children to a new array whose index 0 is the first child element (the main content) and whose index 1 is `filterComponents` (the built filters).
+4. Delegate rendering entirely to `InlineDashboard`, spreading all assembled inputs.
+
+## Behavioral Contract
+
+### Filter Component Construction
+
+In a lifecycle effect (on mount, runs once):
+
+1. Get promoted filters: `allFilters = getPConnect().getRawMetadata().children[1]`.
+2. Invoke the project's filter-component builder utility with `getPConnect` and `allFilters`:
+   - For each filter in `allFilters`, creates a PConnect-based filter field component.
+   - Returns an array of rendered filter elements ready to display.
+3. Store result in `filterComponents` local state.
+
+### Render
+
+Delegate to `InlineDashboard`, forwarding `title`, `filterPosition`, and `getPConnect`, with two children: children index 0 (the main content region) and `filterComponents` (the built filter elements, replacing the raw children index 1).
+
+## Visual Specifications
+
+Identical to `InlineDashboard` — see `InlineDashboard.md`. The only difference is that the filter panel children are programmatically built, not passed directly.
+
+## Edge Cases & Special Logic
+
+- `allFilters` may be empty — if no promoted filters exist, `filterComponents` is an empty array, and `InlineDashboard` renders without a filter panel.
+- The filter-component builder utility may be async in some implementations — show a loading state if needed until filters are ready.
+- Children index 0 is always the main content — index is stable.
+- `filterComponents` replaces children index 1 entirely — do not render both.
+
+## Dependencies
+
+- The project's filter-component builder utility — constructs filter field components from promoted filter config; accepts `getPConnect` and a filters array and returns rendered filter components
+- `InlineDashboard` — the layout template this component wraps (resolved via the project's component registry)
+
+## Design System Mapping
+
+**UI control type:** Dashboard page — programmatic filter construction + InlineDashboard delegation.
+
+This component is a thin orchestration layer. All visual implementation is in `InlineDashboard`. The only implementation detail is the filter-component builder utility — which creates filter field components from metadata definitions.
+
+When implementing in a specific design system, map the following:
+
+- The filter-component builder utility must create proper PConnect-backed filter field components
+- If promoted filters metadata is empty, skip the filter panel entirely
+- All layout and styling is delegated to `InlineDashboard`

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/template-skills/ListPage.md

@@ -8,21 +8,21 @@ List page template. Thin wrapper that renders `ListView` in standalone page mode
 
 ## Component Purpose
 
-Renders a full-page list view by forwarding all props to `ListView` with `bInForm: false`. There is no additional logic — this component exists solely to provide a registration key that signals "this is a page, not an inline table."
+Renders a full-page list view by forwarding all inputs to `ListView` with `bInForm: false`. There is no additional logic — this component exists solely to provide a registration key that signals "this is a page, not an inline table."
 
 > See `ListView.md` for full documentation of all capabilities.
 
 ## Pega Metadata
 
-- **Registration key:** `ListPage` (in `component-map.ts`)
+- **Registration key:** `ListPage` (in the project's component map)
 - **Category:** Page template — list page
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
-All props are forwarded to `ListView`. Key props:
+All inputs are forwarded to `ListView`. Key inputs:
 
-| Prop           | Type       | Required | Description                    |
+| Input          | Type       | Required | Description                    |
 | -------------- | ---------- | -------- | ------------------------------ |
 | `dataPageName` | `string`   | Yes      | Data page to load records from |
 | `columns`      | `array`    | No       | Column definitions             |
@@ -30,13 +30,20 @@ All props are forwarded to `ListView`. Key props:
 | `payload`      | `object`   | No       | Query payload                  |
 | `getPConnect`  | `function` | Yes      | PConnect getter                |
 
-## Behavioral Contract
+## Implementation Structure
+
+Simplest possible template — pure pass-through to `ListView` with one input override.
 
-```tsx
-<ListView {...props} bInForm={false} />
-```
+**Module Setup:** Obtain `ListView` from the project's component registry. The component's interface extends the project's base component interface with `parameters: object`.
 
-That is the complete implementation. `bInForm: false` ensures ListView renders with full page chrome (outer padding, page-level toolbar layout).
+**Main Component Logic** — steps in order:
+
+1. Retrieve `ListView` from the project's component registry.
+2. Render `ListView` forwarding all received inputs and overriding `bInForm` to `false`.
+
+## Behavioral Contract
+
+The complete implementation renders `ListView` forwarding all inputs with `bInForm` overridden to `false`. `bInForm: false` ensures ListView renders with full page chrome (outer padding, page-level toolbar layout).
 
 ## Visual Specifications
 
@@ -54,17 +61,15 @@ None beyond `ListView`. The only constraint is that `bInForm` is always `false`
 
 ## Dependencies
 
-- `ListView` — the primary list template component
+- `ListView` — the primary list template component (resolved via the project's component registry)
 
 ## Design System Mapping
 
 **UI control type:** Full-page data list — pass-through to `ListView` with page-mode flag.
 
-Listed design systems are examples only.
-
-Implement identically to `ListView` — `ListPage` adds no new UI. The distinction is purely in the `bInForm` prop which controls spacing/chrome.
+Implement identically to `ListView` — `ListPage` adds no new UI. The distinction is purely in the `bInForm` input which controls spacing/chrome.
 
-When implementing in a specific design system:
+When implementing in a specific design system, map the following:
 
 - `bInForm: false` signals that the list should have page-level layout (more padding, full-width toolbar)
 - No additional logic beyond `ListView` is required

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

@@ -0,0 +1,234 @@
+# Skill: ListView
+
+Full-featured list view template. Renders a data table with sorting, pagination, global search, single/multi selection, column menu, and filter dialog.
+
+> **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**
+>
+> 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.
+
+---
+
+> ⚠️ **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.
+>
+> **How to extract configured columns:**
+>
+> 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
+>
+> 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 }`.
+>
+> **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
+
+---
+
+> ⚠️ **CRITICAL — Data fetching differs by `bInForm`**
+>
+> 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 ?? []`.
+>
+> Using the wrong API will return empty data or fail silently.
+
+---
+
+## 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.
+
+## Pega Metadata
+
+- **Registration key:** `ListView` (in the project's component map)
+- **Category:** Data display template
+- **Extends:** The project's base component interface
+
+## 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                                                               |
+
+## 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.
+
+**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.
+
+**Main Component Logic** — steps 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.
+
+## 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'`.
+
+### Pagination
+
+- `<TablePagination>` component below the table.
+- `rowsPerPageOptions`: `[5, 10, 25]`.
+- On page/rows change: re-fetch with `startIndex` and `maxResults` params.
+
+### Global Search
+
+- Shown when `isSearchable === true`.
+- `<TextField>` input above the table (toolbar area).
+- On submit/debounce: re-fetch with `searchText` param.
+
+### Selection
+
+| `selectionMode` | Control per row | Callback                     |
+| --------------- | --------------- | ---------------------------- |
+| `'single'`      | `<Radio>`       | `onRowSelect(rowData)`       |
+| `'multi'`       | `<Checkbox>`    | `onRowsSelect(selectedRows)` |
+| absent          | None            | None                         |
+
+- Select-all checkbox in the header for multi-selection.
+- Selected rows highlighted with `selected` row class.
+
+### Column Menu
+
+- `<MoreVertIcon>` button in each column header.
+- Opens `<Menu>` with options: Show/Hide column, Pin column.
+- Column visibility stored in local state `columnVisibility`.
+
+### Filter Dialog
+
+- 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.
+
+### Link Rendering (Navigation)
+
+Columns configured with `displayAsLink: true` (or `additionalDetails.type === 'DISPLAY_LINK'`) render as clickable links that navigate to assignments or work items.
+
+**Detection logic:**
+
+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)`).
+
+**Click handling:**
+
+| Link type       | API call                                                              | Parameters                                     |
+| --------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
+| Assignment link | `getActionsApi().openAssignment(pzInsKey, pxRefObjectClass, options)` | `options = { containerName, channelName: '' }` |
+| Work item link  | `getActionsApi().openWorkByHandle(pxRefObjectKey, pxRefObjectClass)`  | —                                              |
+
+**Legacy column IDs** that also render as links (even without `displayAsLink`):
+
+- `pxTaskLabel` → opens assignment (if `pxRefObjectClass` + `pzInsKey` exist on the row)
+- `pxRefObjectInsName` → opens work item (if `pxRefObjectClass` + `pxRefObjectKey` exist)
+
+### Snackbar Toast
+
+- Shown on fetch errors or action feedback.
+- Auto-hides after 3000ms.
+
+## 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               |
+
+**CSS-only implementation notes:**
+
+- 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`.
+
+## 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.
+
+## 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.
+
+## 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

package/templates/react-sdk-reference/{.github → .ai-common}/skills/template-skills/MultiReferenceReadOnly.md

@@ -8,17 +8,17 @@ Multi-reference read-only template. Routes to `SimpleTableSelectReadonly` or `Si
 
 ## Component Purpose
 
-Renders a multi-value reference field in read-only mode. Routing is based on the `displayAs` prop: certain display variants use `SimpleTableSelectReadonly` (link + modal), while others use `SimpleTable` directly.
+Renders a multi-value reference field in read-only mode. Routing is based on the `displayAs` input: certain display variants use `SimpleTableSelectReadonly` (link + modal), while others use `SimpleTable` directly.
 
 ## Pega Metadata
 
-- **Registration key:** `MultiReferenceReadOnly` (in `component-map.ts`)
+- **Registration key:** `MultiReferenceReadOnly` (in the project's component map)
 - **Category:** Display template — read-only multi-reference
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop                  | Type       | Required | Description                                              |
+| Input                 | Type       | Required | Description                                              |
 | --------------------- | ---------- | -------- | -------------------------------------------------------- |
 | `displayAs`           | `string`   | Yes      | UI variant that was used in edit mode                    |
 | `referenceList`       | `string`   | No       | Property path to the reference list                      |
@@ -26,16 +26,16 @@ Renders a multi-value reference field in read-only mode. Routing is based on the
 | `fieldMetadata`       | `object`   | No       | Field-level metadata                                     |
 | `getPConnect`         | `function` | Yes      | PConnect getter                                          |
 
-## Behavioral Contract
+## Implementation Structure
 
-### Routing by `displayAs`
+**Module Setup:** This component requires the project's base component interface. Define a component input contract extending the base interface with `config: { referenceList, readonlyContextList }`, `label` (string), `hideLabel` (boolean), and optional `displayMode`/`displayAs`.
 
-```
-if displayAs in ['readonlyMulti', 'combobox', 'checkboxgroup']:
-  → render SimpleTableSelectReadonly
-else:
-  → render SimpleTable (with readOnly=true / displayMode='DISPLAY_ONLY')
-```
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `getPConnect`, `label` (default `''`), `hideLabel` (default `false`), `config`, `displayMode`, and `displayAs`; further extract `referenceList` and `readonlyContextList` from `config`.
+2. **Route to `SimpleTableSelectReadonly`:** if `displayAs` is one of `'readonlyMulti'`, `'combobox'`, or `'checkboxgroup'`, return `getPConnect().createComponent({ type: 'SimpleTableSelectReadonly', config: { ...config, displayMode, label, hideLabel, displayAs } })`.
+3. **Reference list fallback:** if `referenceList` is not recognized as a property annotation (checked via `PCore.getAnnotationUtils().isProperty(referenceList)`), build a `readonlyContextObject = { referenceList: readonlyContextList }` to use in its place.
+4. **Route to `SimpleTable`:** for all other `displayAs` values, call `getPConnect().createComponent({ type: 'SimpleTable', config: { ...config, ...readonlyContextObject, label, hideLabel } }, '', 0, {})` and render the result.
 
 ### Reference List Fallback
 
@@ -69,14 +69,9 @@ See `SimpleTable.md` and `ListView.md` for detailed visual specs.
 
 **UI control type:** Read-only multi-value reference display — routes to modal table or flat table.
 
-Listed design systems are examples only.
-
-| `displayAs`                                  | Routing                     | DS Implementation    |
-| -------------------------------------------- | --------------------------- | -------------------- |
-| `readonlyMulti`, `combobox`, `checkboxgroup` | `SimpleTableSelectReadonly` | Link/chip + modal    |
-| All others                                   | `SimpleTable`               | Flat read-only table |
-
-When implementing in a specific design system:
+When implementing in a specific design system, map the following:
 
-- The `displayAs` routing list must match the edit-mode variants defined in `DataReference.md`
-- `readonlyContextList` fallback is critical — reference list data may not be available on initial render
+- When `displayAs` is `'readonlyMulti'`, `'combobox'`, or `'checkboxgroup'`, route to `SimpleTableSelectReadonly` — typically rendered as a link/chip showing selection count with a modal dialog for details.
+- For all other `displayAs` values, route to `SimpleTable` — typically rendered as a flat read-only table.
+- The `displayAs` routing list must match the edit-mode variants defined in `DataReference.md`.
+- `readonlyContextList` fallback is critical — reference list data may not be available on initial render.