@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.claude/skills/template-skills/FieldGroupTemplate.md

@@ -0,0 +1,109 @@
+# Skill: FieldGroupTemplate
+
+Repeating field group template. Renders a list of field group rows from a reference list, supporting add/delete row actions and a read-only display mode.
+
+> **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 repeating list of field group rows sourced from a PConnect reference list. In edit mode, rows can be added and deleted via list actions. In read-only mode (DISPLAY_ONLY), delegates to a read-only `FieldGroup` renderer. Each row is built via `buildView`.
+
+## Pega Metadata
+
+- **Registration key:** `FieldGroupTemplate` (in `component-map.ts`)
+- **Category:** Form template — repeating
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Section heading |
+| `showLabel` | `boolean` | No | Whether to show the heading. Default `true` |
+| `fieldHeader` | `string` | No | Property ref for the dynamic row heading. E.g. `'.pyStatusWork'` |
+| `allowTableEdit` | `boolean` | No | Whether to show add/delete row controls. Default `true` |
+| `displayMode` | `string` | No | `'DISPLAY_ONLY'` triggers read-only rendering |
+| `readOnly` | `boolean` | No | Alternative read-only flag |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Read-Only Mode
+
+If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
+1. Set `setInheritedProp('DISPLAY_ONLY', true)` on the pConn.
+2. Render `<FieldGroup>` — the DSE component that shows data in a read-only layout.
+
+### Edit Mode
+
+1. **Get reference list:** `resolvedList = getReferenceList(pConn)` — extracts the array of row data objects.
+2. **Set reference list:** `pConn.setReferenceList(resolvedList)` — ensures the pConn has the resolved list.
+3. **Build row views:** For each row index `i`, call `buildView(pConn, i, true)` to get the PConnect view for that row.
+4. **Render `<FieldGroupList>`** — the DSE component for edit mode, receiving:
+   - `resolvedList` for row count
+   - Row views as children
+   - `onAdd`: calls `pConn.getListActions().insert({})`
+   - `onDelete(index)`: calls `pConn.getListActions().deleteEntry(index)`
+   - `fieldHeader`: evaluated property ref for dynamic row heading
+   - `allowActions`: from `allowTableEdit` prop (controls visibility of add/delete buttons)
+
+### `allowActions` Override
+
+If the field group is inside a read-only context (parent has set `readOnly` or `DISPLAY_ONLY`), `allowActions` is forced to `false` regardless of `allowTableEdit`.
+
+## Visual Specifications
+
+### Edit Mode
+
+- Section heading (`label`) at top (if `showLabel`).
+- List of row sections, each with:
+  - Dynamic heading from `fieldHeader` property value (e.g. `"Active"`, `"Pending"`).
+  - Row fields in a grid layout.
+  - Delete button (trash icon) per row.
+- Add row button at the bottom (e.g. `"+ Add row"`).
+
+### Read-Only Mode
+
+- Section heading at top (if `showLabel`).
+- Flat list of rows — no add/delete controls.
+
+**CSS-only implementation notes:**
+- Row section: `border: 1px solid var(--border-color); border-radius: 4px; padding: 1rem; margin-bottom: 0.5rem`.
+- Add button: text button, below the last row.
+- Delete button: icon button, top-right of each row section.
+
+## Edge Cases & Special Logic
+
+- `getReferenceList(pConn)` returns `undefined` if the reference list is not yet loaded — guard and render empty list.
+- `buildView(pConn, index, true)` — third argument `lookForChildInConfig=true` — required for embedded field groups.
+- Row index must be passed to `deleteEntry` as a number (not string).
+- `fieldHeader` is a property ref like `'.pyStatusWork'` — evaluate it per-row via `pConn.getValue(fieldHeader, index)` to get the display label for each row heading.
+- `FieldGroupList` and `FieldGroup` are DSE (design system extension) components registered in the component registry.
+
+## Dependencies
+
+- `getReferenceList`, `buildView` from `../../helpers/field-group-utils`
+- `getComponentFromRegistry('FieldGroupList')` — edit mode renderer
+- `getComponentFromRegistry('FieldGroup')` — read-only renderer
+- `PConnectComponent` from `@pega/sdk-react` — used inside `buildView`
+
+## Design System Mapping
+
+**UI control type:** Repeating list of grouped form sections with add/delete row management.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Custom row card list with add/delete buttons |
+| MUI | `<Paper>` per row + `<IconButton>` for delete + `<Button>` for add |
+| Ant Design | `<Form.List>` with `<Card>` per row |
+| Chakra UI | Custom repeating section with `<Box>` rows |
+| Shadcn/ui | Custom list with `<Card>` per row + `<Button variant='ghost'>` |
+
+When implementing in a specific design system:
+- The add/delete controls must be hidden when `allowActions` is false
+- Row heading is dynamic — evaluate `fieldHeader` property ref per row
+- `buildView` generates child PConnect views — render them inside each row section

package/templates/react-sdk-reference/.claude/skills/template-skills/HierarchicalForm.md

@@ -0,0 +1,113 @@
+# Skill: HierarchicalForm
+
+Multi-step tabbed form template. Renders form sections as horizontal tabs with per-tab validation error badges and persisted active tab navigation.
+
+> **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-step form where each section is a tab. Tabs display error badges when their content has validation errors. The active tab index is persisted to navigation state so it survives renders. Optional instruction HTML is displayed above the tab bar.
+
+## Pega Metadata
+
+- **Registration key:** `HierarchicalForm` (in `component-map.ts`)
+- **Category:** Form template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | One child per tab section |
+| `instructions` | `string` | No | HTML instruction text shown above the tab bar |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Hook: `useHierarchicalForm`
+
+`useHierarchicalForm(getPConnect, numTabs)` returns:
+- `activeTabId`: currently selected tab index (string, e.g. `'0'`)
+- `setActiveTabId`: setter for `activeTabId`
+- `tabErrorCounts`: `Record<string, number>` — error count per tab index key
+
+Internally it calls `useGetTabsCount(getPConnect)` to compute `tabErrorCounts`.
+
+### Active Tab Persistence
+
+- On mount, read persisted tab from `PCore.getNavigationUtils().getComponentState(navigationKey)` — use `getActiveTabId(componentState)` to extract the stored tab index, or fall back to `getFirstVisibleTabId(tabItems)`.
+- On tab change, persist via `PCore.getNavigationUtils().setComponentState(navigationKey, { activeTabId: newId })`.
+- `navigationKey` is derived from the component's fully-qualified context path.
+
+### Instructions
+
+- Call `getInstructions(getPConnect(), props.instructions)` to get sanitized HTML.
+- If non-empty, render `<div className='psdk-default-form-instruction-text' dangerouslySetInnerHTML={{ __html: instructions }} />` above the tabs.
+
+### Tab Items
+
+- Build `tabItems` from `children` — each entry has `{ id: index.toString(), name: child.label }`.
+- Filter to visible tabs via `getFirstVisibleTabId(tabItems)`.
+
+### Error Badge
+
+- For each tab, read `tabErrorCounts[tabIndex]`.
+- If `> 0`: wrap the tab label with `<Tooltip title={errorCountMsg}><Badge badgeContent={count} color='error'>{label}</Badge></Tooltip>`.
+- Else: render the label plain.
+
+### Render
+
+1. Optional instruction block (above tabs).
+2. `<TabContext value={activeTabId}>` wrapper.
+3. `<Tabs onChange={handleTabChange} value={activeTabId}>` containing `<Tab>` per visible tab (with error badge label if applicable).
+4. `<TabPanel value={tabId}>` per tab containing the corresponding child.
+
+## Visual Specifications
+
+### Tab Bar
+
+| Property | Value |
+|----------|-------|
+| Orientation | Horizontal |
+| Error badge | Red MUI Badge with tooltip showing error count message |
+
+**CSS-only implementation notes:**
+- Tab bar: same as `DetailsSubTabs` — `display: flex; border-bottom: 2px solid var(--divider)`.
+- Error badge: red circle badge overlaid top-right of the tab label text.
+- Instruction text: `padding: 0.5rem 0; margin-bottom: 0.5rem; font-size: 0.875rem`.
+
+## Edge Cases & Special Logic
+
+- `useGetTabsCount` is a custom hook specific to `HierarchicalForm` — it tracks validation errors per tab section.
+- `getActiveTabId` / `getFirstVisibleTabId` are helpers from `tabUtils` — they handle the case where the persisted tab is no longer visible.
+- `navigationKey` must be stable across re-renders — derive it once in `useMemo` from `getPConnect().getStateProps()` or equivalent.
+- If no visible tabs, render nothing (null).
+
+## Dependencies
+
+- `useHierarchicalForm`, `useGetTabsCount` from `./hooks`
+- `getActiveTabId`, `getFirstVisibleTabId`, `tabClick` from `../SubTabs/tabUtils`
+- `getInstructions` from `../../helpers/template-utils`
+- `TabContext`, `TabPanel` from `@mui/lab`
+- `Tab`, `Tabs`, `Badge`, `Tooltip` from `@mui/material`
+
+## Design System Mapping
+
+**UI control type:** Multi-step tabbed form with per-tab error indicators and persistent active tab.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Custom tab bar + CSS badge (red circle via pseudo-element) |
+| MUI | `<Tabs>` + `<Badge>` + `<Tooltip>` + `<TabContext>/<TabPanel>` |
+| Ant Design | `<Tabs>` with custom `tabBarExtraContent` for error badges |
+| Chakra UI | `<Tabs>` + `<Badge colorScheme='red'>` inside tab label |
+| Shadcn/ui | `<Tabs>` + custom badge overlay on tab trigger |
+
+When implementing in a specific design system:
+- Error badge is mandatory — always show error counts when `tabErrorCounts[id] > 0`
+- Active tab must be persisted via `PCore.getNavigationUtils()` for correct navigation behavior
+- Instructions HTML renders above the entire tab bar, not per-tab

package/templates/react-sdk-reference/.claude/skills/template-skills/InlineDashboard.md

@@ -0,0 +1,104 @@
+# Skill: InlineDashboard
+
+Inline dashboard template. Renders a dashboard with a title, a main content area, and an optional filter panel whose position is configurable.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders an inline dashboard layout consisting of a title heading, a main content panel, and an optional filter panel. The filter panel position is configurable: `block-start` places filters above the content in a stacked layout; any other position places filters to the side using a 9/3 column split.
+
+## Pega Metadata
+
+- **Registration key:** `InlineDashboard` (in `component-map.ts`)
+- **Category:** Page template — dashboard
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `title` | `string` | No | Dashboard title displayed above the content area |
+| `filterPosition` | `string` | No | Filter panel position: `'block-start'` (above) or other (side). Default: side |
+| `children` | `ReactNode[]` | Yes | `children[0]` = main content, `children[1]` = filter panel |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Title
+
+- If `title` is non-empty, render `<Typography variant='h4'>{title}</Typography>` above the grid.
+
+### Filter Position: `'block-start'`
+
+Stacked layout — filter panel above main content:
+- `<Grid container direction='column-reverse'>` (reverse so filter renders visually above content).
+- Filter panel: `<Grid id='filters' size={{ xs: 12 }}>`.
+- Main content: `<Grid size={{ xs: 12 }}>`.
+
+### Filter Position: Other (side)
+
+Side-by-side layout — main content left, filters right:
+- `<Grid container direction={...}>` (optionally `row-reverse` based on position value).
+- Main content: `<Grid size={{ xs: 9 }}>`.
+- Filter panel: `<Grid id='filters' size={{ xs: 3 }}>`.
+
+### Children Assignment
+
+- `children[0]` = main content panel.
+- `children[1]` = filter panel (may be absent if no filters configured).
+
+## Visual Specifications
+
+### Block-Start Layout (filter above content)
+
+```
+[Filter panel — xs:12]
+[Main content — xs:12]
+```
+
+### Side Layout (filter to side)
+
+```
+[Main content — xs:9]  [Filters — xs:3]
+```
+
+**CSS-only implementation notes:**
+- Title: `font-size: 1.5rem; font-weight: 600; margin-bottom: 1rem`.
+- Block-start: `display: flex; flex-direction: column; gap: 1rem` (filter div first in DOM but ordered last visually with `order: -1`).
+- Side: `display: grid; grid-template-columns: 3fr 1fr; gap: 1rem`.
+- Filter panel: `id='filters'` — required for accessibility/selector targeting.
+- Responsive: collapse side layout to stacked on mobile.
+
+## Edge Cases & Special Logic
+
+- If `children[1]` is absent (no filters), render only the main content without the grid.
+- `direction='column-reverse'` in block-start mode — this is the MUI Grid direction prop; in plain CSS, use flexbox `column` direction with `order` property.
+- `title` is optional — if absent, skip the `<Typography h4>` entirely (no empty heading).
+- Filter grid always gets `id='filters'` — this is used by `PromotedFilters` for integration.
+
+## Dependencies
+
+- MUI: `<Typography variant='h4'>`, `<Grid container>`, `<Grid>` (child)
+- `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Dashboard layout with configurable title and filter panel position.
+
+Listed design systems are examples only.
+
+| Design System | Title | Content/Filter Grid |
+|---|---|---|
+| Default (CSS only) | `<h2>` | CSS grid or flexbox |
+| MUI | `<Typography variant='h4'>` | `<Grid container>` |
+| Ant Design | `<Typography.Title level={2}>` | `<Row>/<Col>` |
+| Chakra UI | `<Heading>` | `<Grid>` or `<HStack>` |
+| Shadcn/ui | `<h2>` | Tailwind grid |
+
+When implementing in a specific design system:
+- `filterPosition === 'block-start'` requires stacked layout (12/12) — not side layout (9/3)
+- Filter panel must always have `id='filters'`
+- Title heading (`h4` level) is optional — only render when `title` is provided

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

@@ -0,0 +1,85 @@
+# Skill: InlineDashboardPage
+
+Inline dashboard page template. Builds filter components from promoted filters metadata and delegates rendering to `InlineDashboard`.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## 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.
+
+> 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`)
+- **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 |
+
+## Behavioral Contract
+
+### Filter Component Construction
+
+In `useEffect([])` (on mount):
+
+1. Get promoted filters: `allFilters = getPConnect().getRawMetadata().config.promotedFilters || []`.
+2. Call `buildFilterComponents(getPConnect, 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.
+
+### 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]`).
+
+## Visual Specifications
+
+Identical to `InlineDashboard` — see `InlineDashboard.md`. The only difference is that the filter panel children are programmatically built, not passed directly.
+
+## 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.
+
+## Dependencies
+
+- `buildFilterComponents` from `./utils` — constructs filter field components from promoted filter config
+- `InlineDashboard` — the layout template this component wraps
+
+## 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.
+
+When implementing in a specific design system:
+- `buildFilterComponents` must create proper PConnect-backed filter field components
+- If `promotedFilters` is empty, skip the filter panel entirely
+- All layout and styling is delegated to `InlineDashboard`

package/templates/react-sdk-reference/.claude/skills/template-skills/ListPage.md

@@ -0,0 +1,68 @@
+# Skill: ListPage
+
+List page template. Thin wrapper that renders `ListView` in standalone page mode (`bInForm: false`).
+
+> **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 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."
+
+> See `ListView.md` for full documentation of all capabilities.
+
+## Pega Metadata
+
+- **Registration key:** `ListPage` (in `component-map.ts`)
+- **Category:** Page template — list page
+- **Extends:** `PConnProps`
+
+## Props
+
+All props are forwarded to `ListView`. Key props:
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `dataPageName` | `string` | Yes | Data page to load records from |
+| `columns` | `array` | No | Column definitions |
+| `isSearchable` | `boolean` | No | Whether global search is shown |
+| `payload` | `object` | No | Query payload |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## 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).
+
+## Visual Specifications
+
+Identical to `ListView` with `bInForm: false`:
+- Full outer padding applied.
+- Toolbar occupies full width.
+- Table stretches to fill page width.
+
+See `ListView.md` for all visual details.
+
+## Edge Cases & Special Logic
+
+None beyond `ListView`. The only constraint is that `bInForm` is always `false` for `ListPage`.
+
+## Dependencies
+
+- `ListView` — the primary list template component
+
+## 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.
+
+When implementing in a specific design system:
+- `bInForm: false` signals that the list should have page-level layout (more padding, full-width toolbar)
+- No additional logic beyond `ListView` is required

package/templates/react-sdk-reference/.claude/skills/template-skills/ListView.md

@@ -0,0 +1,139 @@
+# 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