@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/{.cursor/rules/skills/template-skills/InlineDashboardPage.mdrules → .ai-common/skills/template-skills/InlineDashboardPage.md}

@@ -1,8 +1,3 @@
----
-description: Template component skill: InlineDashboardPage
-alwaysApply: false
----
-
 # Skill: InlineDashboardPage
 
 Inline dashboard page template. Builds filter components from promoted filters metadata and delegates rendering to `InlineDashboard`.
@@ -11,6 +6,26 @@ Inline dashboard page template. Builds filter components from promoted filters m
 
 ---
 
+> ⚠️ **CRITICAL — Must use `buildFilterComponents` from `@pega/sdk-react`**
+>
+> This component MUST use `buildFilterComponents(getPConnect, allFilters)` imported from `@pega/sdk-react` to generate proper filter UI components. Without this, dashboard filters will not render correctly.
+>
+> **Mandatory implementation details:**
+>
+> 1. `import { buildFilterComponents } from '@pega/sdk-react'` — filter component builder
+> 2. `getPConnect().getRawMetadata().children[1]` — extract filter metadata
+> 3. `useEffect` + `useState` for `filterComponents` — build filters on mount
+> 4. Assemble `inlineProps.children[1] = filterComponents` for InlineDashboard
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `buildFilterComponents` imported from `@pega/sdk-react`
+> - [ ] `filterComponents` state populated via `useEffect`
+> - [ ] 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 React filter components from them, and passes them to `InlineDashboard` as the second child (filter panel). The first child (main content) is passed through unchanged.
@@ -25,12 +40,48 @@ Page-level wrapper for the inline dashboard. Extracts promoted filter definition
 
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | 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 |
+| Prop             | Type          | Required | Description                                     |
+| ---------------- | ------------- | -------- | ----------------------------------------------- |
+| `children`       | `ReactNode[]` | 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                                 |
+
+## Component Skeleton
+
+```typescript
+import { useMemo, Children, useEffect, useState, type PropsWithChildren } from 'react';
+import { buildFilterComponents, getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface InlineDashboardPageProps extends PConnProps {
+  title: string;
+  icon?: string;
+  filterPosition?: string;
+}
+
+export default function InlineDashboardPage(props: PropsWithChildren<InlineDashboardPageProps>) {
+  const InlineDashboard = getComponentFromRegistry('InlineDashboard');
+  const { children, getPConnect, filterPosition = 'block-start' } = props;
+  const [filterComponents, setFilterComponents] = useState([]);
+  const childArray = useMemo(() => Children.toArray(children), [children]);
+
+  // 1. Build filter components from metadata on mount
+  const allFilters = (getPConnect().getRawMetadata() as any).children[1];
+  useEffect(() => {
+    setFilterComponents(buildFilterComponents(getPConnect, allFilters));
+  }, []);
+
+  // 2. Assemble props for InlineDashboard
+  const inlineProps = { ...props };
+  inlineProps.children = [];
+  inlineProps.children[0] = childArray[0]; // main content
+  inlineProps.children[1] = filterComponents; // built filters
+
+  // 3. Delegate to InlineDashboard
+  return <InlineDashboard {...inlineProps} />;
+}
+```
 
 ## Behavioral Contract
 
@@ -47,13 +98,9 @@ In `useEffect([])` (on mount):
 ### Render
 
 ```tsx
-<InlineDashboard
-  title={title}
-  filterPosition={filterPosition}
-  getPConnect={getPConnect}
->
-  {children[0]}           {/* main content */}
-  {filterComponents}      {/* built filter components */}
+<InlineDashboard title={title} filterPosition={filterPosition} getPConnect={getPConnect}>
+  {children[0]} {/* main content */}
+  {filterComponents} {/* built filter components */}
 </InlineDashboard>
 ```
 
@@ -85,6 +132,7 @@ Listed design systems are examples only.
 This component is a thin orchestration layer. All visual implementation is in `InlineDashboard`. The only implementation detail is `buildFilterComponents` — which creates filter field components from metadata definitions.
 
 When implementing in a specific design system:
+
 - `buildFilterComponents` must create proper PConnect-backed filter field components
 - If `promotedFilters` is empty, skip the filter panel entirely
 - All layout and styling is delegated to `InlineDashboard`

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

@@ -1,8 +1,3 @@
----
-description: Template component skill: ListPage
-alwaysApply: false
----
-
 # Skill: ListPage
 
 List page template. Thin wrapper that renders `ListView` in standalone page mode (`bInForm: false`).
@@ -27,13 +22,31 @@ Renders a full-page list view by forwarding all props to `ListView` with `bInFor
 
 All props are forwarded to `ListView`. Key props:
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `dataPageName` | `string` | Yes | Data page to load records from |
-| `columns` | `array` | No | Column definitions |
-| `isSearchable` | `boolean` | No | Whether global search is shown |
-| `payload` | `object` | No | Query payload |
-| `getPConnect` | `function` | Yes | PConnect getter |
+| Prop           | Type       | Required | Description                    |
+| -------------- | ---------- | -------- | ------------------------------ |
+| `dataPageName` | `string`   | Yes      | Data page to load records from |
+| `columns`      | `array`    | No       | Column definitions             |
+| `isSearchable` | `boolean`  | No       | Whether global search is shown |
+| `payload`      | `object`   | No       | Query payload                  |
+| `getPConnect`  | `function` | Yes      | PConnect getter                |
+
+## Component Skeleton
+
+Simplest possible template — pure pass-through to `ListView` with one prop override.
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface ListPageProps extends PConnProps {
+  parameters: object;
+}
+
+export default function ListPage(props: ListPageProps) {
+  const ListView = getComponentFromRegistry('ListView');
+  return <ListView {...props} bInForm={false} />;
+}
+```
 
 ## Behavioral Contract
 
@@ -46,6 +59,7 @@ That is the complete implementation. `bInForm: false` ensures ListView renders w
 ## Visual Specifications
 
 Identical to `ListView` with `bInForm: false`:
+
 - Full outer padding applied.
 - Toolbar occupies full width.
 - Table stretches to fill page width.
@@ -69,5 +83,6 @@ 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.
 
 When implementing in a specific design system:
+
 - `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,419 @@
+# 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: `useState<any[]>([])`
+> 4. NEVER put `referenceList` directly into state or call `.filter()` on it
+>
+> ```typescript
+> // ❌ WRONG — will crash with "rows.filter is not a function"
+> const [rows, setRows] = useState(referenceList);
+>
+> // ✅ CORRECT — fetch data from the reference string
+> const [rows, setRows] = useState<any[]>([]);
+> useEffect(() => {
+>   if (Array.isArray(referenceList)) {
+>     setRows(referenceList);
+>     return;
+>   }
+>   const dataRef = typeof referenceList === 'string' ? referenceList : dataPageName;
+>   if (dataRef) {
+>     PCore.getDataApiUtils()
+>       .getData(dataRef, payload ?? {})
+>       .then((response) => setRows(response?.data?.data ?? response?.data?.pxResults ?? []))
+>       .catch(() => setRows([]));
+>   }
+> }, [referenceList]);
+> ```
+
+---
+
+> ⚠️ **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
+>
+> ```typescript
+> // ❌ WRONG — shows ALL raw data keys as columns (pzInsKey, pxRefObjectClass, etc.)
+> const fields = Object.keys(rows[0]).map((key) => ({ id: key, label: key }));
+>
+> // ✅ CORRECT — extract configured columns from PConnect presets + metadata
+> const componentConfig = getPConnect().getComponentConfig();
+> const columnFields = componentConfig.presets[0].children[0].children;
+> const metaResponse = await PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, false);
+> const fieldDefs = metaResponse?.data?.fields ?? [];
+>
+> const columns = columnFields.map((field, index) => {
+>   let fieldId = field.config.value.substring(field.config.value.indexOf(' ') + 1);
+>   if (fieldId.startsWith('.')) fieldId = fieldId.substring(1);
+>   const { additionalDetails = {} } = field.config;
+>   const displayAsLink =
+>     additionalDetails.type === 'DISPLAY_LINK' || ('displayAsLink' in field.config && field.config.displayAsLink);
+>   return {
+>     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:
+>
+> ```typescript
+> // Page-level (bInForm = false) — e.g., worklist landing page
+> const result = await PCore.getDataApiUtils().getData(referenceList, payload ?? {});
+> const rows = result?.data?.data ?? [];
+>
+> // Form-level (bInForm = true) — e.g., embedded list in a case form
+> const context = getPConnect().getContextName();
+> const result = await PCore.getDataPageUtils().getDataAsync(referenceList, context, parameters, null, query);
+> const rows = 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 `component-map.ts`)
+- **Category:** Data display template
+- **Extends:** `PConnProps`
+
+## Props
+
+| 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                                                               |
+
+## Component Skeleton
+
+> ⚠️ **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 `package.json` for the installed design system and use its table primitives:
+>
+> | If installed DS is... | Import from...     | Table components                                                                                                                    |
+> | --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+> | `@carbon/react`       | `@carbon/react`    | `Table, TableHead, TableRow, TableHeader, TableBody, TableCell, TableContainer, TableToolbar, TableToolbarSearch, Pagination, Link` |
+> | `@mui/material`       | `@mui/material`    | `Table, TableHead, TableRow, TableCell, TableBody, TableContainer, TablePagination, TableSortLabel, Link`                           |
+> | `antd`                | `antd`             | `Table` (with `columns` + `dataSource` props, built-in pagination)                                                                  |
+> | `@chakra-ui/react`    | `@chakra-ui/react` | `Table, Thead, Tbody, Tr, Th, Td, Link` + custom pagination                                                                         |
+> | None / CSS-only       | N/A                | Plain `<table>/<thead>/<tbody>` with CSS classes                                                                                    |
+>
+> **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`)
+>
+> ❌ **NEVER** render raw `Object.values(row)` or dump all data keys as columns.
+> ❌ **NEVER** use plain HTML when a design system is installed.
+
+This is the largest template component. The implementation MUST include these critical sections:
+
+```typescript
+import { useCallback, useEffect, useState } from 'react';
+import type { PConnProps } from '@pega/sdk-react';
+
+const AssignDashObjects = ['Assign-Worklist', 'Assign-WorkBasket'];
+
+interface ListViewProps extends PConnProps {
+  bInForm?: boolean;
+  globalSearch?: boolean;
+  referenceList?: any;
+  selectionMode?: string;
+  referenceType?: string;
+  payload?: any;
+  parameters?: any;
+  compositeKeys?: any;
+  localeReference?: string;
+}
+
+export default function ListView(props: ListViewProps) {
+  const { getPConnect, bInForm = true, globalSearch, referenceList, payload, parameters, localeReference } = props;
+
+  const [arRows, setRows] = useState<any[]>([]);
+  const [arColumns, setColumns] = useState<any[]>([]);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(10);
+  const [searchValue, setSearchValue] = useState('');
+  const [title, setTitle] = useState('');
+
+  const thePConn = getPConnect();
+  const componentConfig = thePConn.getComponentConfig();
+  const resolvedConfigProps: any = thePConn.getConfigProps();
+
+  // ═══════════════════════════════════════════════════════════════
+  // CRITICAL: Extract column definitions from PConnect presets
+  // ═══════════════════════════════════════════════════════════════
+  const getHeaderCells = useCallback((columnFields: any[], fieldDefs: any[]) => {
+    return columnFields.map((field: any, index: number) => {
+      let theField = field.config.value.substring(field.config.value.indexOf(' ') + 1);
+      if (theField.startsWith('.')) theField = theField.substring(1);
+      const colIndex = fieldDefs.findIndex((ele) => ele.name === theField);
+      const { additionalDetails = {} } = field.config;
+      let displayAsLink = additionalDetails.type === 'DISPLAY_LINK';
+      if (!displayAsLink) displayAsLink = 'displayAsLink' in field.config && field.config.displayAsLink;
+      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),
+      };
+    });
+  }, []);
+
+  // ═══════════════════════════════════════════════════════════════
+  // CRITICAL: Fetch metadata + data in useEffect
+  // ═══════════════════════════════════════════════════════════════
+  useEffect(() => {
+    let isActive = true;
+    async function fetchData() {
+      // Step 1: Get field definitions from metadata API
+      const metaResponse: any = await PCore.getAnalyticsUtils().getDataViewMetadata(referenceList, false);
+      const fieldDefs = metaResponse?.data?.fields ?? [];
+
+      // Step 2: Get configured columns from presets
+      const columnFields = componentConfig?.presets?.[0]?.children?.[0]?.children ?? [];
+      if (columnFields.length) {
+        const myColumns = getHeaderCells(columnFields, fieldDefs);
+        myColumns.forEach((col) => {
+          if (localeReference) col.label = PCore.getLocaleUtils().getLocaleValue(col.label, localeReference);
+        });
+        if (isActive) setColumns(myColumns);
+      }
+
+      // Step 3: Fetch data — API differs by bInForm
+      let dataResult: any;
+      if (!bInForm) {
+        dataResult = await PCore.getDataApiUtils().getData(referenceList, payload ?? {});
+      } else {
+        const context = thePConn.getContextName();
+        dataResult = await (PCore.getDataPageUtils() as any).getDataAsync(
+          referenceList,
+          context,
+          parameters,
+          null,
+          null,
+        );
+      }
+      const tableData = !bInForm ? (dataResult?.data?.data ?? []) : (dataResult?.data ?? []);
+      if (isActive) setRows(Array.isArray(tableData) ? tableData : []);
+    }
+    fetchData();
+    return () => {
+      isActive = false;
+    };
+  }, [referenceList, bInForm, payload, parameters]);
+
+  // ═══════════════════════════════════════════════════════════════
+  // CRITICAL: Link click handlers for navigation
+  // ═══════════════════════════════════════════════════════════════
+  function handleLinkClick(row: any, column: any) {
+    if (column.isAssignmentLink) {
+      const { pxRefObjectClass, pzInsKey } = row;
+      thePConn.getActionsApi().openAssignment(pzInsKey, pxRefObjectClass, {
+        containerName: thePConn.getContainerName(),
+        channelName: '',
+      });
+    } else {
+      const pxRefObjectKey = row.pxRefObjectKey ?? row.pzInsKey;
+      const pxRefObjectClass = row.pxRefObjectClass ?? row.pxObjClass;
+      if (pxRefObjectClass && pxRefObjectKey) {
+        thePConn.getActionsApi().openWorkByHandle(pxRefObjectKey, pxRefObjectClass);
+      }
+    }
+  }
+
+  // Search, pagination, sort, selection, render...
+}
+```
+
+> **Note:** This skeleton shows 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
+
+`useInit(getPConnect, columns, dataPageName, payload)` hook:
+
+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:**
+
+```typescript
+const AssignDashObjects = ['Assign-Worklist', 'Assign-WorkBasket'];
+
+// A column is a link if:
+const isLink = column.displayAsLink;
+
+// It's an assignment link if its classID is a worklist/workbasket class:
+const isAssignmentLink = 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
+
+- `useInit`, `filterData`, `buildFieldsForTable`, `getConfigFields`, `initializeColumns` from `./utils`
+- `PCore.getDataApiUtils().getDataAsync()` — data fetching
+- MUI: `<Table>`, `<TableHead>`, `<TableBody>`, `<TableRow>`, `<TableCell>`, `<TableSortLabel>`, `<TablePagination>`, `<Checkbox>`, `<Radio>`, `<Dialog>`, `<TextField>`, `<Menu>`, `<MenuItem>`, `<Snackbar>`
+
+## Design System Mapping
+
+**UI control type:** Full-featured data table with sorting, pagination, search, selection, and filtering.
+
+Listed design systems are examples only.
+
+| Design System      | Table                                                                                  | Pagination                 | Dialog             | Search           | Link                |
+| ------------------ | -------------------------------------------------------------------------------------- | -------------------------- | ------------------ | ---------------- | ------------------- |
+| Default (CSS only) | `<table>/<thead>/<tbody>`                                                              | Custom pagination controls | `<dialog>` element | `<input>`        | `<a>`               |
+| MUI                | `<Table>` + sub-components                                                             | `<TablePagination>`        | `<Dialog>`         | `<TextField>`    | `<Link>`            |
+| Carbon             | `<DataTable>` + `<Table>/<TableHead>/<TableBody>/<TableRow>/<TableCell>/<TableHeader>` | `<Pagination>`             | `<Modal>`          | `<Search>`       | `<Link>`            |
+| Ant Design         | `<Table>`                                                                              | Built-in pagination prop   | `<Modal>`          | `<Input.Search>` | `<Typography.Link>` |
+| Chakra UI          | `<Table>`                                                                              | Custom or `react-table`    | `<Modal>`          | `<Input>`        | `<Link>`            |
+| Shadcn/ui          | `<Table>` + TanStack Table                                                             | Custom pagination          | `<Dialog>`         | `<Input>`        | `<a>`               |
+
+When implementing in a specific design system:
+
+- **ALWAYS check `package.json`** to identify the installed design system BEFORE writing any render code
+- Import and use the DS's table/pagination/search/link components — do NOT fall back to plain HTML
+- If the DS provides a `DataTable` wrapper (e.g., Carbon), use it for built-in toolbar/search integration
+- `bInForm` prop 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