@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/ListView.mdrules

@@ -0,0 +1,144 @@
+---
+description: Template component skill: ListView
+alwaysApply: false
+---
+
+# 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.
+
+---
+
+## 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 |
+
+## 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.
+
+### 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 |
+|---|---|---|---|
+| Default (CSS only) | `<table>/<thead>/<tbody>` | Custom pagination controls | `<dialog>` element |
+| MUI | `<Table>` + sub-components | `<TablePagination>` | `<Dialog>` |
+| Ant Design | `<Table>` | Built-in pagination prop | `<Modal>` |
+| Chakra UI | `<Table>` | Custom or `react-table` | `<Modal>` |
+| Shadcn/ui | `<Table>` + TanStack Table | Custom pagination | `<Dialog>` |
+
+When implementing in a specific design system:
+- `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/.cursor/rules/skills/template-skills/MultiReferenceReadOnly.mdrules

@@ -0,0 +1,85 @@
+---
+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.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a multi-value reference field in read-only mode. Routing is based on the `displayAs` prop: certain display variants use `SimpleTableSelectReadonly` (link + modal), while others use `SimpleTable` directly.
+
+## Pega Metadata
+
+- **Registration key:** `MultiReferenceReadOnly` (in `component-map.ts`)
+- **Category:** Display template — read-only multi-reference
+- **Extends:** `PConnProps`
+
+## 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 |
+
+## Behavioral Contract
+
+### Routing by `displayAs`
+
+```
+if displayAs in ['readonlyMulti', 'combobox', 'checkboxgroup']:
+  → render SimpleTableSelectReadonly
+else:
+  → render SimpleTable (with readOnly=true / displayMode='DISPLAY_ONLY')
+```
+
+### Reference List Fallback
+
+- Primary: `pConn.getValue(referenceList + '.pxResults')`.
+- Fallback: use `readonlyContextList` directly if the above is undefined/empty.
+
+## Visual Specifications
+
+- `SimpleTableSelectReadonly` variant: link/chip showing selection count + modal dialog.
+- `SimpleTable` variant: flat read-only table of values.
+
+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.
+
+## Edge Cases & Special Logic
+
+- `readonlyContextList` is the fallback — always use it when `pConn.getValue(referenceList)` returns nothing.
+- `displayAs` check uses an inclusion array: `['readonlyMulti', 'combobox', 'checkboxgroup']` — extend this list if new multi-select display variants are added.
+- The component is only reached in `DISPLAY_ONLY`/`readOnly` mode — never needs to handle edit states.
+
+## Dependencies
+
+- `SimpleTableSelectReadonly` (see `SimpleTable.md`)
+- `SimpleTable` (see `SimpleTable.md`)
+
+## Design System Mapping
+
+**UI control type:** Read-only multi-value reference display — routes to modal table or flat table.
+
+Listed design systems are examples only.
+
+| `displayAs` | Routing | DS Implementation |
+|---|---|---|
+| `readonlyMulti`, `combobox`, `checkboxgroup` | `SimpleTableSelectReadonly` | Link/chip + modal |
+| All others | `SimpleTable` | Flat read-only table |
+
+When implementing in a specific design system:
+- 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/.cursor/rules/skills/template-skills/NarrowWide.mdrules

@@ -0,0 +1,146 @@
+---
+description: Template component skill: NarrowWide
+alwaysApply: false
+---
+
+# 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 |
+
+## 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

@@ -0,0 +1,114 @@
+---
+description: Template component skill: OneColumn
+alwaysApply: false
+---
+
+# Skill: OneColumn
+
+Single-column layout template that stacks all children in a full-width column.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders all children stacked vertically in a single full-width column. Three closely related sub-variants:
+
+- **`OneColumn`** — core layout with internal grid and column style
+- **`OneColumnPage`** — thin wrapper that delegates to `OneColumn` via the component registry
+- **`OneColumnTab`** — minimal pass-through wrapper for tab context (`<div id='OneColumnTab'>`)
+
+## Pega Metadata
+
+| Variant | Registration Key |
+|---------|-----------------|
+| OneColumn | `OneColumn` |
+| OneColumnPage | `OneColumnPage` |
+| OneColumnTab | `OneColumnTab` |
+
+All extend `PConnProps`. Children are received as React `children`.
+
+## Props
+
+| 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} />;
+```
+
+### 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
+
+1. Render a Grid container with `spacing={2}`.
+2. Render a single inner Grid at `size={{ xs: 12 }}` with `colStyles` applied.
+3. Map over all `children` and render each child.
+4. `OneColumnPage` delegates all rendering to `OneColumn` from the registry.
+5. `OneColumnTab` renders children in a plain `<div>` — no Grid, no styles.
+
+## Visual Specifications
+
+Derived from `OneColumn.tsx` makeStyles:
+
+### Column Style
+
+| Property | Value |
+|----------|-------|
+| Display | grid |
+| Gap | 1rem |
+| Align content | baseline (children stack top-aligned) |
+
+### Grid Spacing
+
+| 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.
+
+## Edge Cases & Special Logic
+
+- `OneColumn` maps over all children (not just first/second) — supports any number of children.
+- `OneColumnPage` uses the registry — if an override exists for `OneColumn`, it will be used.
+- `OneColumnTab` does NOT apply the `colStyles` grid — it is intentionally simpler.
+
+## Dependencies
+
+- `OneColumnPage`: `getComponentFromRegistry` from `@pega/sdk-react`
+- `OneColumn` / `OneColumnTab`: no special dependencies
+
+## Design System Mapping
+
+**UI control type:** Single full-width column layout.
+
+Listed design systems are examples only.
+
+| 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` |
+
+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/.cursor/rules/skills/template-skills/PromotedFilters.mdrules

@@ -0,0 +1,129 @@
+---
+description: Template component skill: PromotedFilters
+alwaysApply: false
+---
+
+# 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 |
+
+## 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