@pega/sdk 0.0.4 → 0.0.5

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

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

@@ -26,6 +26,46 @@ 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                                          |
 
+## Component Skeleton
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface MultiReferenceReadOnlyProps extends PConnProps {
+  config: { referenceList: any; readonlyContextList: any };
+  label: string;
+  hideLabel: boolean;
+  displayMode?: any;
+  displayAs?: any;
+}
+
+export default function MultiReferenceReadOnly(props: MultiReferenceReadOnlyProps) {
+  const { getPConnect, label = '', hideLabel = false, config, displayMode, displayAs } = props;
+  const { referenceList, readonlyContextList } = config;
+
+  // 1. Route: SimpleTableSelectReadonly for specific displayAs values
+  if (['readonlyMulti', 'combobox', 'checkboxgroup'].includes(displayAs)) {
+    return getPConnect().createComponent({
+      type: 'SimpleTableSelectReadonly',
+      config: { ...config, displayMode, label, hideLabel, displayAs },
+    });
+  }
+
+  // 2. Fallback: use readonlyContextList if referenceList is not a property annotation
+  let readonlyContextObject;
+  if (!PCore.getAnnotationUtils().isProperty(referenceList)) {
+    readonlyContextObject = { referenceList: readonlyContextList };
+  }
+
+  // 3. Route: SimpleTable for all other displayAs values
+  const component = getPConnect().createComponent(
+    { type: 'SimpleTable', config: { ...config, ...readonlyContextObject, label, hideLabel } },
+    '', 0, {},
+  );
+  return <>{component}</>;
+}
+```
+
 ## Behavioral Contract
 
 ### Routing by `displayAs`

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

@@ -63,6 +63,72 @@ All extend `PConnProps`.
 | `showHighlightedData` | `boolean`  | No       | Whether to render highlighted data fields above children. Default `false` |
 | `getPConnect`         | `function` | Yes      | PConnect getter                                                           |
 
+## Component Skeletons
+
+### NarrowWide (core)
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import type { PConnProps } from '@pega/sdk-react';
+import './NarrowWide.css';
+
+interface NarrowWideProps extends PConnProps {
+  a: any; b: any; title?: string; cols?: string; icon?: string;
+}
+
+export default function NarrowWide(props: PropsWithChildren<NarrowWideProps>) {
+  const { a, b, children } = props;
+  return (
+    <>
+      {children && (children as ReactElement[]).length === 2 && (
+        <div className="psdk-narrow-wide-column">
+          <div className="psdk-narrow-column-column">{children[0]}</div>
+          <div className="psdk-wide-column-column">{children[1]}</div>
+        </div>
+      )}
+      {a && b && (
+        <div className="psdk-narrow-wide-column">
+          <div className="psdk-narrow-column-column">{a}</div>
+          <div className="psdk-wide-column-column">{b}</div>
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+### NarrowWidePage
+
+```typescript
+const NarrowWide = getComponentFromRegistry('NarrowWide');
+const { children, title, templateCol = '1fr 1fr', icon = '' } = props;
+return <NarrowWide a={children[0]} b={children[1]} title={title}
+  cols={templateCol} icon={icon?.replace('pi pi-', '')} />;
+```
+
+### NarrowWideForm
+
+```typescript
+const { children } = props;
+return children?.length === 2 ? (
+  <div className="psdk-narrow-wide-column">
+    <div className="psdk-narrow-column-column">{children[0]}</div>
+    <div className="psdk-wide-column-column">{children[1]}</div>
+  </div>
+) : null;
+```
+
+### NarrowWideDetails
+
+Same pattern as `Details` but uses `COLUMN_WIDTHS = [4, 8]`:
+
+```typescript
+const COLUMN_WIDTHS = [4, 8];
+// highlighted data: <GridItem xs={COLUMN_WIDTHS[i]}>
+// regular children: <GridItem xs={COLUMN_WIDTHS[i]}>
+// Wrap in FieldGroup, setInheritedProp DISPLAY_ONLY + readOnly
+```
+
 ## Behavioral Contract
 
 ### NarrowWide

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

@@ -24,6 +24,40 @@ Renders all children stacked vertically in a single full-width column. Three clo
 
 All extend `PConnProps`. Children are received as React `children`.
 
+## Component Skeletons
+
+### OneColumn (core)
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import type { PConnProps } from '@pega/sdk-react';
+
+export default function OneColumn(props: PropsWithChildren<PConnProps>) {
+  const { children } = props;
+  return (
+    <GridContainer spacing={2}>
+      <GridItem xs={12} className="col-styles">
+        {(children as ReactElement[]).map(child => child)}
+      </GridItem>
+    </GridContainer>
+  );
+}
+// CSS: .col-styles { display: grid; gap: 1rem; align-content: baseline; }
+```
+
+### OneColumnPage
+
+```typescript
+const OneColumn = getComponentFromRegistry('OneColumn');
+return <OneColumn {...props} />;
+```
+
+### OneColumnTab
+
+```typescript
+return <div id="OneColumnTab">{children}</div>;
+```
+
 ## Props
 
 | Prop       | Type          | Required | Description                                         |

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

@@ -27,6 +27,98 @@ Renders promoted filter controls above a list view. Filter fields are created dy
 | `isSearchable`    | `boolean`  | No       | Whether the ListView below shows a global search input        |
 | `getPConnect`     | `function` | Yes      | PConnect getter                                               |
 
+## Component Skeleton
+
+```typescript
+import React, { useCallback, useMemo, useState, createElement } from 'react';
+import { isEmptyObject } from '../../helpers/common-utils';
+import { getComponentFromRegistry, PConnectComponent } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+import './PromotedFilters.css';
+
+const SUPPORTED_TYPES_IN_PROMOTED_FILTERS = [
+  'TextInput','Percentage','Email','Integer','Decimal','Checkbox',
+  'DateTime','Date','Time','Text','TextArea','Currency','URL','RichText',
+];
+
+// Sub-component: renders each filter field via PCore.createPConnect
+function Filters({ filters, transientItemID, localeReference }) {
+  return filters.map((filter, index) => {
+    const filterClone = { ...filter };
+    if (!SUPPORTED_TYPES_IN_PROMOTED_FILTERS.includes(filterClone.type)) {
+      filterClone.type = 'TextInput';
+      delete filterClone.config.placeholder;
+    }
+    filterClone.config.contextName = transientItemID;
+    filterClone.config.readOnly = false;
+    filterClone.config.context = transientItemID;
+    filterClone.config.localeReference = localeReference;
+    const c11nEnv = PCore.createPConnect({
+      meta: filterClone,
+      options: { hasForm: true, contextName: transientItemID },
+    });
+    return <React.Fragment key={index}>{createElement(PConnectComponent, c11nEnv)}</React.Fragment>;
+  });
+}
+
+export default function PromotedFilters(props: PromotedFilterProps) {
+  const ListView = getComponentFromRegistry('ListView');
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const { getPConnect, viewName, filters, listViewProps, pageClass, parameters } = props;
+  const [initTable, setInitTable] = useState(false);
+  const [payload, setPayload] = useState({});
+
+  // 1. Build transient item on mount (useMemo)
+  const filtersProperties = {};
+  filters.forEach(f => { filtersProperties[PCore.getAnnotationUtils().getPropertyName(f.config.value)] = ''; });
+  const transientItemID = useMemo(() => {
+    return getPConnect().getContainerManager().addTransientItem({
+      id: viewName, data: { ...filtersProperties, classID: pageClass },
+    });
+  }, []);
+
+  // 2. Search handler: read form changes, format filters, set payload
+  const getFilterData = useCallback((e) => {
+    e.preventDefault();
+    const changes = PCore.getFormUtils().getChanges(transientItemID);
+    const formValues = {};
+    Object.keys(changes).forEach(key => {
+      if (!['context_data','pageInstructions'].includes(key)) formValues[key] = changes[key];
+    });
+    const promotedFilters = formatPromotedFilters(formValues);
+    if (PCore.getFormUtils().isFormValid(transientItemID) && isValidInput(formValues)) {
+      setInitTable(true);
+      const Query: any = { dataViewParameters: parameters };
+      if (!isEmptyObject(promotedFilters)) Query.query = { filter: { filterConditions: promotedFilters } };
+      setPayload(Query);
+    }
+  }, [transientItemID]);
+
+  // 3. Clear handler
+  const clearFilterData = useCallback(() => {
+    PCore.getContainerUtils().clearTransientData(transientItemID);
+    setInitTable(false);
+    getPConnect()?.getListActions?.()?.setSelectedRows([]);
+  }, [transientItemID]);
+
+  // 4. Render: title + filter fields + Clear/Search buttons + conditional ListView
+  return (
+    <>
+      <div>{listViewProps.title}</div>
+      <div className="psdk-grid-filter">
+        <Filters filters={filters} transientItemID={transientItemID}
+          localeReference={listViewProps.localeReference} />
+      </div>
+      <div>
+        <ClearButton onClick={clearFilterData}>Clear</ClearButton>
+        <SearchButton onClick={getFilterData}>Search</SearchButton>
+      </div>
+      {initTable && <ListView {...listViewProps} title="" payload={payload} isSearchable />}
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### Transient Data Setup