@pega/sdk 0.0.5 → 0.0.6

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

@@ -6,21 +6,21 @@ Inline dashboard page template. Builds filter components from promoted filters m
 
 ---
 
-> ⚠️ **CRITICAL — Must use `buildFilterComponents` from `@pega/sdk-react`**
+> ⚠️ **CRITICAL — Must use the project's filter-component builder utility**
 >
-> 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.
+> 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. `import { buildFilterComponents } from '@pega/sdk-react'` — filter component builder
+> 1. Obtain the filter-component builder utility from the project's SDK bridge layer
 > 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
+> 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:**
 >
-> - [ ] `buildFilterComponents` imported from `@pega/sdk-react`
-> - [ ] `filterComponents` state populated via `useEffect`
+> - [ ] 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
 
@@ -28,84 +28,53 @@ Inline dashboard page template. Builds filter components from promoted filters m
 
 ## 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.
+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 `component-map.ts`)
+- **Registration key:** `InlineDashboardPage` (in the project's component map)
 - **Category:** Page template — dashboard page
-- **Extends:** `PConnProps`
-
-## 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                                 |
-
-## 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} />;
-}
-```
+- **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 `useEffect([])` (on mount):
+In a lifecycle effect (on mount, runs once):
 
-1. Get promoted filters: `allFilters = getPConnect().getRawMetadata().config.promotedFilters || []`.
-2. Call `buildFilterComponents(getPConnect, allFilters)`:
+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 React elements ready to render.
-3. Store result in `filterComponents` state.
+   - Returns an array of rendered filter elements ready to display.
+3. Store result in `filterComponents` local state.
 
 ### Render
 
-```tsx
-<InlineDashboard title={title} filterPosition={filterPosition} getPConnect={getPConnect}>
-  {children[0]} {/* main content */}
-  {filterComponents} {/* built filter components */}
-</InlineDashboard>
-```
-
-- `children[0]` = main content region.
-- `filterComponents` = built filter elements (replaces raw `children[1]`).
+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
 
@@ -114,25 +83,23 @@ Identical to `InlineDashboard` — see `InlineDashboard.md`. The only difference
 ## 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.
-- `buildFilterComponents` is async in some implementations — show a loading state if needed until filters are ready.
-- `children[0]` is always the main content — index is stable.
-- `filterComponents` replaces `children[1]` entirely — do not render both.
+- 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
 
-- `buildFilterComponents` from `./utils` — constructs filter field components from promoted filter config
-- `InlineDashboard` — the layout template this component wraps
+- 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.
 
-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.
+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:
+When implementing in a specific design system, map the following:
 
-- `buildFilterComponents` must create proper PConnect-backed filter field components
-- If `promotedFilters` is empty, skip the filter panel entirely
+- 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/.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,31 +30,20 @@ All props are forwarded to `ListView`. Key props:
 | `payload`      | `object`   | No       | Query payload                  |
 | `getPConnect`  | `function` | Yes      | PConnect getter                |
 
-## Component Skeleton
+## Implementation Structure
 
-Simplest possible template — pure pass-through to `ListView` with one prop override.
+Simplest possible template — pure pass-through to `ListView` with one input override.
 
-```typescript
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
+**Module Setup:** Obtain `ListView` from the project's component registry. The component's interface extends the project's base component interface with `parameters: object`.
 
-interface ListPageProps extends PConnProps {
-  parameters: object;
-}
+**Main Component Logic** — steps in order:
 
-export default function ListPage(props: ListPageProps) {
-  const ListView = getComponentFromRegistry('ListView');
-  return <ListView {...props} bInForm={false} />;
-}
-```
+1. Retrieve `ListView` from the project's component registry.
+2. Render `ListView` forwarding all received inputs and overriding `bInForm` to `false`.
 
 ## Behavioral Contract
 
-```tsx
-<ListView {...props} bInForm={false} />
-```
-
-That is the complete implementation. `bInForm: false` ensures ListView renders with full page chrome (outer padding, page-level toolbar layout).
+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
 
@@ -72,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

@@ -12,29 +12,10 @@ Full-featured list view template. Renders a data table with sorting, pagination,
 >
 > 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[]>([])`
+> 3. Initialize row state as empty array
 > 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]);
-> ```
+> 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.
 
 ---
 
@@ -48,31 +29,7 @@ Full-featured list view template. Renders a data table with sorting, pagination,
 > 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,
->   };
-> });
-> ```
+> 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:**
 >
@@ -85,18 +42,7 @@ Full-featured list view template. Renders a data table with sorting, pagination,
 
 > ⚠️ **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 ?? [];
-> ```
+> 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.
 
@@ -108,11 +54,11 @@ The primary data table component. Renders a sortable, paginated, filterable, and
 
 ## Pega Metadata
 
-- **Registration key:** `ListView` (in `component-map.ts`)
+- **Registration key:** `ListView` (in the project's component map)
 - **Category:** Data display template
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
 | Prop                    | Type       | Required | Description                                                                   |
 | ----------------------- | ---------- | -------- | ----------------------------------------------------------------------------- |
@@ -127,160 +73,43 @@ The primary data table component. Renders a sortable, paginated, filterable, and
 | `payload`               | `object`   | No       | Query payload for data page requests                                          |
 | `getPConnect`           | `function` | Yes      | PConnect getter                                                               |
 
-## Component Skeleton
+## 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 `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:
+> 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`)
 >
-> ❌ **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.
+> 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
 
-`useInit(getPConnect, columns, dataPageName, payload)` hook:
+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.
@@ -336,15 +165,7 @@ Columns configured with `displayAsLink: true` (or `additionalDetails.type === 'D
 
 **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);
-```
+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:**
 
@@ -390,30 +211,24 @@ const isAssignmentLink = AssignDashObjects.includes(column.classID);
 
 ## 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>`
+- 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.
 
-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:
+When implementing in a specific design system, map the following:
 
-- **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`
+- **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