@pega/sdk 0.0.3 → 0.0.5

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

@@ -1,8 +1,3 @@
----
-description: Template component skill: MultiReferenceReadOnly
-alwaysApply: false
----
-
 # Skill: MultiReferenceReadOnly
 
 Multi-reference read-only template. Routes to `SimpleTableSelectReadonly` or `SimpleTable` based on `displayAs` for read-only rendering of multi-value reference fields.
@@ -23,13 +18,53 @@ Renders a multi-value reference field in read-only mode. Routing is based on the
 
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `displayAs` | `string` | Yes | UI variant that was used in edit mode |
-| `referenceList` | `string` | No | Property path to the reference list |
-| `readonlyContextList` | `array` | No | Fallback data array when `referenceList` is not resolved |
-| `fieldMetadata` | `object` | No | Field-level metadata |
-| `getPConnect` | `function` | Yes | PConnect getter |
+| Prop                  | Type       | Required | Description                                              |
+| --------------------- | ---------- | -------- | -------------------------------------------------------- |
+| `displayAs`           | `string`   | Yes      | UI variant that was used in edit mode                    |
+| `referenceList`       | `string`   | No       | Property path to the reference list                      |
+| `readonlyContextList` | `array`    | No       | Fallback data array when `referenceList` is not resolved |
+| `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
 
@@ -55,6 +90,7 @@ else:
 See `SimpleTable.md` and `ListView.md` for detailed visual specs.
 
 **CSS-only notes:**
+
 - Fallback to `readonlyContextList` renders identically to the resolved reference list.
 - No edit controls in either variant.
 
@@ -75,11 +111,12 @@ See `SimpleTable.md` and `ListView.md` for detailed visual specs.
 
 Listed design systems are examples only.
 
-| `displayAs` | Routing | DS Implementation |
-|---|---|---|
-| `readonlyMulti`, `combobox`, `checkboxgroup` | `SimpleTableSelectReadonly` | Link/chip + modal |
-| All others | `SimpleTable` | Flat read-only table |
+| `displayAs`                                  | Routing                     | DS Implementation    |
+| -------------------------------------------- | --------------------------- | -------------------- |
+| `readonlyMulti`, `combobox`, `checkboxgroup` | `SimpleTableSelectReadonly` | Link/chip + modal    |
+| All others                                   | `SimpleTable`               | Flat read-only table |
 
 When implementing in a specific design system:
+
 - The `displayAs` routing list must match the edit-mode variants defined in `DataReference.md`
 - `readonlyContextList` fallback is critical — reference list data may not be available on initial render

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

@@ -0,0 +1,209 @@
+# Skill: NarrowWide
+
+Asymmetric two-column layout with a narrow left column (~33%) and a wide right column (~67%). Includes four sub-variants for different contexts.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders two children side by side with the left column narrower than the right. Used for case layouts where a sidebar panel sits beside a main content area. Four sub-variants:
+
+- **`NarrowWide`** — core CSS-based layout, accepts either `a`/`b` slot props or React `children[0]`/`children[1]`
+- **`NarrowWidePage`** — wrapper that passes React children as `a` and `b` slot props to `NarrowWide`
+- **`NarrowWideForm`** — simplified wrapper using only `children` (no `a`/`b` slots, no title/icon)
+- **`NarrowWideDetails`** — details read-only variant; sets children to DISPLAY_ONLY mode and supports highlighted data
+
+## Pega Metadata
+
+| Variant           | Registration Key    |
+| ----------------- | ------------------- |
+| NarrowWide        | `NarrowWide`        |
+| NarrowWidePage    | `NarrowWidePage`    |
+| NarrowWideForm    | `NarrowWideForm`    |
+| NarrowWideDetails | `NarrowWideDetails` |
+
+All extend `PConnProps`.
+
+## Props
+
+### NarrowWide
+
+| Prop       | Type          | Required | Description                                                |
+| ---------- | ------------- | -------- | ---------------------------------------------------------- |
+| `children` | `ReactNode[]` | No       | Two children rendered in narrow/wide slots                 |
+| `a`        | `any`         | No       | Narrow (left) column content                               |
+| `b`        | `any`         | No       | Wide (right) column content                                |
+| `title`    | `string`      | No       | Optional title (not rendered in reference implementation)  |
+| `cols`     | `string`      | No       | Column template (not rendered in reference implementation) |
+| `icon`     | `string`      | No       | Optional icon (not rendered in reference implementation)   |
+
+### NarrowWidePage
+
+| Prop          | Type          | Required | Description                                           |
+| ------------- | ------------- | -------- | ----------------------------------------------------- |
+| `children`    | `ReactNode[]` | Yes      | Two children — `[0]` → narrow slot, `[1]` → wide slot |
+| `title`       | `string`      | Yes      | Page title (passed to NarrowWide)                     |
+| `templateCol` | `string`      | No       | Column ratio (default `'1fr 1fr'`)                    |
+| `icon`        | `string`      | No       | Icon name (strips `'pi pi-'` prefix)                  |
+
+### NarrowWideForm
+
+| Prop       | Type          | Required | Description                                           |
+| ---------- | ------------- | -------- | ----------------------------------------------------- |
+| `children` | `ReactNode[]` | Yes      | Two children — `[0]` → narrow slot, `[1]` → wide slot |
+
+### NarrowWideDetails
+
+| Prop                  | Type       | Required | Description                                                               |
+| --------------------- | ---------- | -------- | ------------------------------------------------------------------------- |
+| `label`               | `string`   | Yes      | Section label for FieldGroup                                              |
+| `showLabel`           | `boolean`  | No       | Whether to show the label. Default `true`                                 |
+| `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
+
+1. If `children` is provided and has exactly 2 items, render `children[0]` in `.psdk-narrow-column-column` and `children[1]` in `.psdk-wide-column-column` (both wrapped in `.psdk-narrow-wide-column`).
+2. If `a` and `b` are provided (and children is empty/not 2 items), render `a` in the narrow slot and `b` in the wide slot.
+3. The two render paths are independent — priority is `children` if length === 2, otherwise `a`/`b`.
+
+### NarrowWidePage
+
+1. Extract `childrenToRender = children as ReactElement[]`.
+2. Retrieve `NarrowWide` from the component registry.
+3. Render `<NarrowWide a={childrenToRender[0]} b={childrenToRender[1]} title={title} cols={templateCol} icon={icon?.replace('pi pi-', '')} />`.
+
+### NarrowWideForm
+
+1. Render exactly as `NarrowWide` with `children` path — checks `children.length === 2`, renders narrow/wide slots.
+2. Does not support `a`/`b` props.
+
+### NarrowWideDetails
+
+1. Call `getPConnect().getInheritedProps()` and merge with `{ label, showLabel }` for `propsToUse`.
+2. Set `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `setInheritedProp('readOnly', true)`.
+3. Map `getPConnect().getChildren()` → `createElement(PConnectComponent, { ...configObject, key: index })`.
+4. If `showHighlightedData` is true, read `getRawMetadata().config.highlightedData`, set each field's `displayMode = 'STACKED_LARGE_VAL'`, mark `pyStatusWork` fields as `type='TextInput', displayAsStatus=true`, and create components via `getPConnect().createComponent(field, '', 0, {})`.
+5. Wrap everything in `<FieldGroup name={theName}>` where `theName = propsToUse.showLabel && propsToUse.label ? propsToUse.label : ''`.
+6. Layout: highlighted data in `Grid size={{ xs: COLUMN_WIDTHS[i] }}` where `COLUMN_WIDTHS = [4, 8]`, then children in `Grid size={{ xs: 12 }}` rows.
+
+## Visual Specifications
+
+Derived from `NarrowWide.css`:
+
+### Container
+
+| CSS Class                    | Property | Value                         |
+| ---------------------------- | -------- | ----------------------------- |
+| `.psdk-narrow-wide-column`   | Display  | flex or grid (two-column row) |
+| `.psdk-narrow-column-column` | Width    | ~33% (1 of 3 parts)           |
+| `.psdk-wide-column-column`   | Width    | ~67% (2 of 3 parts)           |
+
+**CSS-only implementation notes:**
+
+- `.psdk-narrow-wide-column`: `display: grid; grid-template-columns: 1fr 2fr; gap: 1rem`.
+- `.psdk-narrow-column-column`: takes the first (narrower) grid column.
+- `.psdk-wide-column-column`: takes the second (wider) grid column.
+- On mobile: `grid-template-columns: 1fr` (stacks vertically).
+
+## Edge Cases & Special Logic
+
+- `NarrowWide` supports both `children` and `a`/`b` slot patterns — check `children` length first.
+- `NarrowWideDetails` highlighted data grid uses `[4, 8]` column widths (narrow left, wide right for STACKED_LARGE_VAL fields).
+- `NarrowWideDetails` reads `theName` from `propsToUse` (which merges inherited props) — the `label` prop alone may be overridden by inherited props.
+- Icon cleanup in `NarrowWidePage`: strip `'pi pi-'` prefix from the icon string before passing to `NarrowWide`.
+
+## Dependencies
+
+- `NarrowWidePage`: `getComponentFromRegistry` from `@pega/sdk-react`
+- `NarrowWideDetails`: `getComponentFromRegistry('FieldGroup')`, `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Asymmetric two-column layout (sidebar + main content).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                            |
+| ------------------ | -------------------------------------------------------------------------------- |
+| Default (CSS only) | CSS Grid `grid-template-columns: 1fr 2fr; gap: 1rem`                             |
+| MUI                | `<Grid container><Grid size={{ xs: 12, md: 4 }}><Grid size={{ xs: 12, md: 8 }}>` |
+| Ant Design         | `<Row gutter={16}><Col xs={24} md={8}><Col xs={24} md={16}>`                     |
+| Chakra UI          | `<Grid templateColumns={{ base: '1fr', md: '1fr 2fr' }} gap={4}>`                |
+| Shadcn/ui          | Tailwind `grid grid-cols-1 md:grid-cols-[1fr_2fr] gap-4`                         |
+
+When implementing in a specific design system:
+
+- Narrow column ≈ 33% width (1fr of 3fr total)
+- Wide column ≈ 67% width (2fr of 3fr total)
+- `NarrowWideDetails` always forces DISPLAY_ONLY + readOnly on children

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

@@ -1,8 +1,3 @@
----
-description: Template component skill: OneColumn
-alwaysApply: false
----
-
 # Skill: OneColumn
 
 Single-column layout template that stacks all children in a full-width column.
@@ -21,25 +16,60 @@ Renders all children stacked vertically in a single full-width column. Three clo
 
 ## Pega Metadata
 
-| Variant | Registration Key |
-|---------|-----------------|
-| OneColumn | `OneColumn` |
-| OneColumnPage | `OneColumnPage` |
-| OneColumnTab | `OneColumnTab` |
+| Variant       | Registration Key |
+| ------------- | ---------------- |
+| OneColumn     | `OneColumn`      |
+| OneColumnPage | `OneColumnPage`  |
+| OneColumnTab  | `OneColumnTab`   |
 
 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 |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | Yes | One or more children to render in the single column |
+| Prop       | Type          | Required | Description                                         |
+| ---------- | ------------- | -------- | --------------------------------------------------- |
+| `children` | `ReactNode[]` | Yes      | One or more children to render in the single column |
 
 ## Sub-Variants
 
 ### OneColumnPage
 
 Thin pass-through wrapper. Retrieves `OneColumn` from the component registry and renders with all props forwarded:
+
 ```typescript
 const OneColumn = getComponentFromRegistry('OneColumn');
 return <OneColumn {...props} />;
@@ -48,9 +78,11 @@ return <OneColumn {...props} />;
 ### OneColumnTab
 
 Minimal wrapper — renders children in a plain `<div>` with `id='OneColumnTab'`:
+
 ```typescript
 return <div id='OneColumnTab'>{children}</div>;
 ```
+
 No grid or column styles applied. Used purely as a slot container inside tab panels.
 
 ## Behavioral Contract
@@ -67,19 +99,20 @@ Derived from `OneColumn.tsx` makeStyles:
 
 ### Column Style
 
-| Property | Value |
-|----------|-------|
-| Display | grid |
-| Gap | 1rem |
+| Property      | Value                                 |
+| ------------- | ------------------------------------- |
+| Display       | grid                                  |
+| Gap           | 1rem                                  |
 | Align content | baseline (children stack top-aligned) |
 
 ### Grid Spacing
 
-| Property | Value |
-|----------|-------|
+| Property          | Value      |
+| ----------------- | ---------- |
 | Container spacing | 2 (≈ 16px) |
 
 **CSS-only implementation notes:**
+
 - Column: `display: grid; gap: 1rem; align-content: baseline; width: 100%`.
 - Outer container: `display: grid; grid-template-columns: 1fr; gap: 16px`.
 - `OneColumnTab`: just `<div>` with no special styling.
@@ -101,14 +134,15 @@ Derived from `OneColumn.tsx` makeStyles:
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
+| Design System      | Recommended Component                                    |
+| ------------------ | -------------------------------------------------------- |
 | Default (CSS only) | `<div style="display:grid;gap:1rem;">` wrapping children |
-| MUI | `<Grid container spacing={2}><Grid size={{ xs: 12 }}>` |
-| Ant Design | `<Row><Col span={24}>` |
-| Chakra UI | `<Stack spacing={4}>` or `<Grid templateColumns='1fr'>` |
-| Shadcn/ui | Tailwind `flex flex-col gap-4` |
+| MUI                | `<Grid container spacing={2}><Grid size={{ xs: 12 }}>`   |
+| Ant Design         | `<Row><Col span={24}>`                                   |
+| Chakra UI          | `<Stack spacing={4}>` or `<Grid templateColumns='1fr'>`  |
+| Shadcn/ui          | Tailwind `flex flex-col gap-4`                           |
 
 When implementing in a specific design system:
+
 - All children render in a single column, top-aligned
 - `OneColumnTab` variant is a minimal `<div>` container with no layout styling

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

@@ -0,0 +1,222 @@
+# Skill: PromotedFilters
+
+Promoted filters template. Renders a set of promoted filter fields above a `ListView`, allowing users to filter list data through a Clear/Search workflow using transient data.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders promoted filter controls above a list view. Filter fields are created dynamically via `PCore.createPConnect` and managed as transient data. On search, filter values are formatted and passed to the `ListView` as a query payload. The component also handles the `ListView` rendering below the filters.
+
+## Pega Metadata
+
+- **Registration key:** `PromotedFilters` (in `component-map.ts`)
+- **Category:** Search / Filter template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop              | Type       | Required | Description                                                   |
+| ----------------- | ---------- | -------- | ------------------------------------------------------------- |
+| `viewName`        | `string`   | Yes      | Name of the promoted filters view — used as transient item ID |
+| `dataPageName`    | `string`   | Yes      | Data page name passed to `ListView`                           |
+| `promotedFilters` | `array`    | Yes      | Array of filter field definitions `{ name, classID, ... }`    |
+| `payload`         | `object`   | No       | Base query payload for the data page                          |
+| `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
+
+On mount:
+
+1. Build `filtersWithClassID`: add `classID` to each filter from `getPConnect().getContextName()` or metadata.
+2. Call `PCore.getDataPageUtils().addTransientItem({ id: viewName, data: filtersWithClassID })`.
+3. This creates a transient data context for the filter fields.
+
+### Filters Sub-Component
+
+The `<Filters>` inline sub-component:
+
+1. Creates each filter field via `PCore.createPConnect({ ... filterFieldConfig, contextName: viewName + '.' + filter.name })`.
+2. Renders each created pConnect as a field component via `createElement(PConnectComponent, { ...fieldConfig })`.
+
+### Search
+
+On Search button click:
+
+1. Call `getFilterData(viewName, promotedFilters)`:
+   - For each filter, read current value from transient store.
+   - Build filter objects: `{ lhs: { field: filter.name }, comparator: 'EQ', rhs: { value: currentValue } }`.
+   - Skip filters with empty/null values.
+2. Pass the resulting filter array to `ListView` as `payload.filters`.
+3. `ListView` re-fetches with the filter payload.
+
+### Clear
+
+On Clear button click:
+
+1. Call `clearFilterData(viewName, promotedFilters)`:
+   - For each filter, reset the transient value to `''` or `null`.
+2. Reset `payload.filters` to `[]`.
+3. `ListView` re-fetches without filters.
+
+### Render Structure
+
+```
+<div className="psdk-promoted-filters">
+  <div className="psdk-promoted-filters-fields">
+    <Filters />   {/* filter fields */}
+  </div>
+  <div className="psdk-promoted-filters-actions">
+    <Button onClick={handleClear}>Clear</Button>
+    <Button onClick={handleSearch}>Search</Button>
+  </div>
+  <ListView bInForm={true} isSearchable={isSearchable} dataPageName={dataPageName} payload={activePayload} />
+</div>
+```
+
+## Visual Specifications
+
+| Element           | Description                                |
+| ----------------- | ------------------------------------------ |
+| Filter fields row | Horizontal flex row of filter field inputs |
+| Action buttons    | Clear + Search buttons, right-aligned      |
+| ListView          | Below the filter row, full width           |
+
+**CSS-only implementation notes:**
+
+- Outer container: `display: flex; flex-direction: column; gap: 1rem`.
+- Filter fields row: `display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: flex-end`.
+- Action buttons row: `display: flex; gap: 0.5rem; justify-content: flex-end`.
+
+## Edge Cases & Special Logic
+
+- Transient item must be cleaned up on unmount: call `PCore.getDataPageUtils().removeTransientItem(viewName)`.
+- `getFilterData` skips empty values — a filter with no input is not sent to the query.
+- If all filters are empty, the Search returns unfiltered results.
+- `PCore.createPConnect` creates new pConnect instances for each filter — these must be properly keyed and managed.
+
+## Dependencies
+
+- `getFilterData`, `clearFilterData` from `./utils`
+- `PCore.getDataPageUtils().addTransientItem()` — transient context setup
+- `PCore.createPConnect()` — creates pConnect instances for filter fields
+- `ListView` — the list below the filters
+- `PConnectComponent` from `@pega/sdk-react`
+- MUI: `<Button>`
+
+## Design System Mapping
+
+**UI control type:** Filter bar above a list view — transient field inputs + Clear/Search actions.
+
+Listed design systems are examples only.
+
+| Design System      | Filter Row                                     | Action Buttons                       |
+| ------------------ | ---------------------------------------------- | ------------------------------------ |
+| Default (CSS only) | `display: flex; flex-wrap: wrap` inputs        | `<button>` for Clear/Search          |
+| MUI                | `<Box display='flex' flexWrap='wrap' gap={1}>` | `<Button>` variants                  |
+| Ant Design         | `<Space wrap>`                                 | `<Button type='primary'>` for Search |
+| Chakra UI          | `<HStack wrap='wrap'>`                         | `<Button colorScheme='blue'>`        |
+| Shadcn/ui          | Tailwind `flex flex-wrap gap-2`                | `<Button>` variants                  |
+
+When implementing in a specific design system:
+
+- Transient data pattern is critical — each filter field must read/write to `PCore`'s transient store
+- `getFilterData` builds the query filter payload — use it unchanged
+- Transient item cleanup on unmount is required to avoid stale data