@pega/sdk 0.0.5 → 0.0.6

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

@@ -12,150 +12,189 @@ Renders a multi-step form where each section is a tab. Tabs display error badges
 
 ## Pega Metadata
 
-- **Registration key:** `HierarchicalForm` (in `component-map.ts`)
+- **Registration key:** `HierarchicalForm` (in the project's component map)
 - **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                               |
-
-## Component Skeleton
-
-```typescript
-import { type PropsWithChildren } from 'react';
-import { useHierarchicalForm, type HierarchicalFormProps } from './hooks';
-
-export default function HierarchicalForm(props: PropsWithChildren<HierarchicalFormProps>) {
-  // 1. Custom hook handles: active tab, tab click, error counts, instructions, processed tabs
-  const { currentTabId, handleTabClick, processedTabs, instructions } = useHierarchicalForm(props);
-
-  // 2. Guard: no visible tabs
-  if (!currentTabId) return null;
-
-  // 3. Render: instructions + TabContext + Tabs (with error badges) + TabPanels
-  return (
-    <FlexColumn>
-      {instructions && <div dangerouslySetInnerHTML={{ __html: instructions }} />}
-      <TabContext value={currentTabId.toString()}>
-        <TabBar onChange={handleTabClick} value={currentTabId.toString()} variant="scrollable">
-          {processedTabs.map(tab => {
-            const tabLabel = tab.name || tab.label;
-            return (
-              <Tab key={tab.id} value={tab.id?.toString()} label={
-                tab.errors
-                  ? <Tooltip title={`${tabLabel} has errors`}>
-                      <span>{tabLabel} <Badge badgeContent={tab.errors} color="error" /></span>
-                    </Tooltip>
-                  : tabLabel
-              } />
-            );
-          })}
-        </TabBar>
-        {processedTabs.map(tab => (
-          <TabPanel key={tab.id} value={tab.id?.toString()} tabIndex={+tab.id} keepMounted>
-            {tab.content || 'No content exists'}
-          </TabPanel>
-        ))}
-      </TabContext>
-    </FlexColumn>
-  );
-}
-```
-
-> **Key implementation note:** All tab logic (active tab persistence, error counting, tab filtering) is encapsulated in the `useHierarchicalForm` hook. Implement that hook separately — it uses `PCore.getNavigationUtils()` for tab persistence and `useGetTabsCount` for error tracking.
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input                | Type               | Required | Description                                                                                       |
+| -------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `children`           | child element list | Yes      | One child per tab section                                                                         |
+| `instructions`       | string             | No       | HTML instruction text shown above the tab bar                                                     |
+| `getPConnect`        | function           | Yes      | PConnect getter                                                                                   |
+| `tabsVisibility`     | object             | No       | Record mapping tab index to boolean visibility                                                    |
+| `template`           | string             | No       | Template identifier passed to deferred tab loading                                                |
+| `lastUpdateCaseTime` | string or number   | No       | Timestamp of last case update (falls back to `getPConnect().getValue('caseInfo.lastUpdateTime')`) |
+
+## Implementation Structure
+
+**Module Setup:** This component needs the project's base component interface for typing. The tab logic is encapsulated in a separate composable/helper module that handles active-tab persistence, tab-click handling, per-tab error counting, instructions extraction, and tab processing. Additionally, tab utility helpers (`getActiveTabId`, `getFirstVisibleTabId`, `tabClick`) and an instructions helper (`getInstructions`) are needed from the project's shared template utilities.
+
+**Main Component Logic** — steps in order:
+
+1. Invoke the extracted tab-logic composable, passing the component's inputs. It returns `currentTabId`, `handleTabClick`, `processedTabs`, and `instructions`.
+2. Guard: if there is no `currentTabId` (no visible tabs), render nothing.
+3. Render a flex column containing (if present) the instructions HTML rendered as raw HTML content, followed by a tab context wrapping a scrollable tab bar and tab panels.
+4. Build each tab bar entry from `processedTabs`: the label is `tab.name || tab.label`; if `tab.errors` is truthy, wrap the label in a tooltip reading "`{label} has errors`" and append a badge showing the error count; otherwise render the plain label.
+5. Render one tab panel per processed tab (keeping content mounted), showing `tab.content` or a "No content exists" fallback.
+
+> **Key implementation note:** All tab logic (active tab persistence, error counting, tab filtering, PubSub subscriptions) is encapsulated in the composable. It uses `PCore.getNavigationUtils()` for tab persistence, `PCore.getContextTreeManager().onViewMutate()` for field-level error tracking, and `PCore.getMessagingServiceManager()` for case refresh subscriptions.
 
 ## Behavioral Contract
 
-### Hook: `useHierarchicalForm`
+### Tab Logic Composable
+
+The extracted tab-logic composable accepts the component's inputs and returns:
+
+- `currentTabId`: currently selected tab index (string, e.g. `'0'`)
+- `handleTabClick`: cached callback for tab selection changes
+- `processedTabs`: array of tab objects augmented with computed `errors` count
+- `instructions`: sanitized HTML string (or empty)
 
-`useHierarchicalForm(getPConnect, numTabs)` returns:
+Internally it manages:
 
-- `activeTabId`: currently selected tab index (string, e.g. `'0'`)
-- `setActiveTabId`: setter for `activeTabId`
-- `tabErrorCounts`: `Record<string, number>` — error count per tab index key
+- Local state for `currentTabId` and `tabErrors` (record of per-field errors per tab)
+- Instance references for `tabErrors` and `submitAttempted` (to avoid stale closures)
+- Memoized computation for `navigationKey`, `tabItems` (visible tabs), and `processedTabs`
+- Cached callbacks for `handleTabClick`, `updateTabErrorsOnViewMutate`, `navigateToFirstErrorTab`, and `highlightFirstErrorTab`
 
-Internally it calls `useGetTabsCount(getPConnect)` to compute `tabErrorCounts`.
+### Navigation Key Derivation
+
+- `navigationKey` is built from: `{caseInfoId or landingPageViewName}-{metadataName}-HierarchicalForm`
+- `getLandingPageViewName(contextName)`: strips the trailing segment from contextName, then uses `PCore.getContainerUtils().getActiveContainerItemName(target)` and `PCore.getContainerUtils().getContainerItemData(target, activeItemID)` to get `containerItemData.view.config.name`
+- Must be stable across re-renders — derive it once via memoized computation.
 
 ### 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.
+- On initialization, read persisted tab from `PCore.getNavigationUtils().getComponentState(navigationKey)` — extract `activeTab` from the stored state, or fall back to `getFirstVisibleTabId(deferLoadedTabs)`.
+- On tab change, persist via `PCore.getNavigationUtils().setComponentState(navigationKey, { activeTab: currentTabId })`.
+- Also persist an `ActiveTab` key for the CaseView: `{caseInfoId}-CaseView-ActiveTab` → `{ id: currentTabId }`.
+- On cleanup, if the context is a modal (`getContextName()` includes `/modal`), reset the stored tab to `firstTabId`.
+
+### Deferred Tab Loading
+
+- The first child is a deferred-loaded tabs container. Set the inherited `template` on it via `deferLoadedTabs.getPConnect().setInheritedProp('template', template)`.
+- `tabsFromChildren` is obtained from `deferLoadedTabs.getPConnect().getChildren()`.
+
+### Tab Visibility
+
+- On initialization, iterate the deferred children; for each child whose raw config has a `visibility` property, store `tabsVisibility[index] = rawConfigProps.visibility`.
+- Register additional inputs: `getPConnect().registerAdditionalProps({ tabsVisibility })` and `getPConnect().registerAdditionalProps({ lastUpdateCaseTime: '@P caseInfo.lastUpdateTime' })`.
+- When `tabsVisibility` changes and all values are booleans, serialize them to a string key to trigger tab re-evaluation.
+
+### Case Refresh Subscription
+
+- If `fullCaseId` is available: subscribe to case messages via `PCore.getMessagingServiceManager().getCaseSubscription(fullCaseId).subscribe({ caseId: fullCaseId }, handleCaseRefresh)`.
+- `handleCaseRefresh`: if `message.subtype === 'tab'`, call `refreshTabData()`.
+- On cleanup: unsubscribe from the case subscription.
+
+### Tab Data and Active Tab Sync
+
+- Use a tab-count helper (from the project's SDK utilities) initialized with `(deferLoadedTabs, 'hierarchical', currentTabId, template)` to get `tabData` and `refreshTabData`.
+- Refresh tab data when `lastUpdateCaseTime` changes.
+- When `tabData` changes or tab visibility changes, re-evaluate the active tab via `getActiveTabId(tabData, currentTabId)` and update if changed.
+
+### Error Tracking
+
+- `tabErrors`: a record mapping `tab.id` → `{ fieldName: messages[] }` — tracks per-field validation errors per tab.
+- `updateTabErrorsOnViewMutate(messageObject, tab)`: called by `PCore.getContextTreeManager().onViewMutate()` for each tab's context. If the message type is `MESSAGES_TYPE_ERROR`, adds the field errors; otherwise removes them.
+- Register `onViewMutate` callbacks for each visible tab item, using `tab.getPConnect().getContextName()`, `tab.getPConnect().getPageReference()`, and `tab.getPConnect()._rawConfig.config.name`.
+
+### Error Navigation on Submit
+
+- Subscribe to `PCore.getConstants().PUB_SUB_EVENTS.ERROR_ON_FINISH_ASSIGNMENT`: when triggered, call `highlightFirstErrorTab()` which sets `submitAttempted` to true and navigates to the first tab with errors.
+- Subscribe to `PCore.getConstants().PUB_SUB_EVENTS.CASE_EVENTS.CURRENT_ASSIGNMENT_UPDATED`: when triggered, reset all tab errors and clear `submitAttempted`.
+- When `tabErrors` changes and `submitAttempted` is true, re-navigate to the first error tab (handles late-arriving validation messages).
 
 ### 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.
+- Call `getInstructions(getPConnect(), inputs.instructions)` to get sanitized HTML.
+- If non-empty, render as raw HTML content 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)`.
+- `tabItems`: memoized computation filtering `tabData` to only visible tabs (those where `tab.visibility()` returns true).
+- Each tab has `id`, `name`/`label`, `content`, `errors`, and PConnect methods.
 
 ### 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>`.
+- `processedTabs`: memoized computation that augments each visible tab with an `errors` count — the total number of error messages across all fields in `tabErrors[tab.id]`.
+- If `errors` is truthy: wrap the tab label with a tooltip reading "`{label} has errors`" and display a badge with the error count.
 - Else: render the label plain.
 
+### Tab Click
+
+- `handleTabClick(event, id)`: cached callback that delegates to `tabClick(id, tabData, currentTabId, setCurrentTabId)` — a shared utility that handles tab selection logic.
+
 ### 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.
+1. Optional instruction block (rendered as raw HTML, above tabs).
+2. Tab context wrapper with value set to `currentTabId`.
+3. Scrollable tab bar containing one tab entry per `processedTabs` item (with error badge label if applicable, text-transform disabled).
+4. Tab panels (kept mounted) per processed tab containing `tab.content` or "No content exists" fallback.
 
 ## Visual Specifications
 
 ### Tab Bar
 
-| Property    | Value                                                  |
-| ----------- | ------------------------------------------------------ |
-| Orientation | Horizontal                                             |
-| Error badge | Red MUI Badge with tooltip showing error count message |
+| Property    | Value                                                       |
+| ----------- | ----------------------------------------------------------- |
+| Orientation | Horizontal, scrollable                                      |
+| Error badge | Red badge with tooltip showing error count message          |
+| Border      | Bottom border on the tab bar container (1px, divider color) |
 
 **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`.
+- Tab bar: `display: flex; border-bottom: 1px solid var(--divider)`.
+- Error badge: red circle badge positioned inline next to the tab label text (not overlaid).
+- Error badge and label wrapped in a flex container with `align-items: center; gap: 0.5rem`.
+- Instruction text: rendered with bottom margin (approximately 0.5rem) above the tab bar.
+- Tab panels: no horizontal padding (panel content fills available width).
+- Tab labels: no text-transform applied (preserve original case).
 
 ## 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).
+- The tab-count helper tracks validation errors per tab section and must be refreshed on case updates.
+- `getActiveTabId` / `getFirstVisibleTabId` are shared tab utilities — they handle the case where the persisted tab is no longer visible.
+- `navigationKey` must be stable across re-renders — derive it once via memoized computation from the case ID (or landing page view name), metadata name, and the component name.
+- If no visible tabs, render nothing.
+- When the component is in a modal context, reset persisted tab state on cleanup to avoid stale navigation state.
+- The `_rawConfig` property on PConnect is used to access the raw view config name for `onViewMutate` registration.
+- Error navigation on submit attempts only occurs after `ERROR_ON_FINISH_ASSIGNMENT` fires — it does not proactively validate on tab switch.
+- `CURRENT_ASSIGNMENT_UPDATED` clears all error state, preventing stale error badges from persisting across assignment transitions.
 
 ## 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`
+- Tab-logic composable (custom extracted module) — encapsulates all tab state, persistence, and error tracking
+- Tab utility helpers (`getActiveTabId`, `getFirstVisibleTabId`, `tabClick`) — shared tab navigation logic from the project's SubTabs utilities
+- `getInstructions` — shared template utility for sanitizing instruction HTML
+- Tab-count helper from the project's SDK utilities — for computing per-tab validation data
+- `PCore.getNavigationUtils()` — for persisting and retrieving active tab state
+- `PCore.getContextTreeManager().onViewMutate()` — for registering per-field validation error listeners
+- `PCore.getMessagingServiceManager().getCaseSubscription()` — for subscribing to case refresh messages
+- `PCore.getPubSubUtils()` — for subscribing to `ERROR_ON_FINISH_ASSIGNMENT` and `CURRENT_ASSIGNMENT_UPDATED` events
+- `PCore.getContainerUtils()` — for deriving the landing page view name (used in navigation key)
+- `PCore.getConstants()` — for PubSub event keys, message type constants, and case info constants
 
 ## 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.
+When implementing in a specific design system, map the following:
 
-| 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                 |
+- **Tab bar container:** Use the design system's horizontal tab strip with scrollable overflow support and a bottom border divider.
+- **Tab entries:** Use the design system's tab trigger component with no text-transform; label text should preserve original case.
+- **Error badge:** Use the design system's inline badge component (red/error color) positioned next to the tab label text within a flex row. Wrap the badge-label group in a tooltip showing "`{label} has errors`".
+- **Tab panels:** Use the design system's tab panel or content container that supports keep-mounted behavior (all panels remain in DOM, only one is visible).
+- **Instruction block:** A block-level element rendering sanitized HTML, positioned above the tab bar with bottom margin spacing.
+- **Layout:** A vertical flex column containing the optional instruction block, the tab bar with bottom border, and the tab panel area.
 
-When implementing in a specific design system:
+Implementation constraints regardless of design system:
 
-- Error badge is mandatory — always show error counts when `tabErrorCounts[id] > 0`
+- Error badge is mandatory — always show error counts when `processedTabs[i].errors > 0`
 - Active tab must be persisted via `PCore.getNavigationUtils()` for correct navigation behavior
 - Instructions HTML renders above the entire tab bar, not per-tab
+- Tab panels must remain mounted (not destroyed on tab switch) to preserve form state
+- On submit error (`ERROR_ON_FINISH_ASSIGNMENT`), automatically navigate to the first tab with errors
+- On assignment update (`CURRENT_ASSIGNMENT_UPDATED`), clear all error badges

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

@@ -12,81 +12,52 @@ Renders an inline dashboard layout consisting of a title heading, a main content
 
 ## Pega Metadata
 
-- **Registration key:** `InlineDashboard` (in `component-map.ts`)
+- **Registration key:** `InlineDashboard` (in the project's component map)
 - **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                                                               |
-
-## Component Skeleton
-
-```typescript
-import type { PropsWithChildren, ReactElement } from 'react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface InlineDashboardProps extends PConnProps {
-  title: string;
-  filterPosition?: string;
-}
-
-export default function InlineDashboard(props: PropsWithChildren<InlineDashboardProps>) {
-  const { children, title, filterPosition } = props;
-  const childrenToRender = children as ReactElement[];
-
-  // 1. Direction for side layout
-  const direction = filterPosition === 'inline-start' ? 'row-reverse' : 'row';
-
-  // 2. Render: title + layout based on filterPosition
-  return (
-    <>
-      <Heading variant="h4">{title}</Heading>
-
-      {filterPosition === 'block-start' ? (
-        // Stacked: filter above content (column-reverse so filter renders visually above)
-        <GridContainer direction="column-reverse">
-          <GridItem xs={12}>{childrenToRender[0]}</GridItem>
-          <GridItem id="filters" xs={12}>{childrenToRender[1]}</GridItem>
-        </GridContainer>
-      ) : (
-        // Side: content left, filters right (or reversed if inline-start)
-        <GridContainer direction={direction}>
-          <GridItem xs={9}>{childrenToRender[0]}</GridItem>
-          <GridItem id="filters" xs={3}>{childrenToRender[1]}</GridItem>
-        </GridContainer>
-      )}
-    </>
-  );
-}
-```
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input            | 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`       | child node array | Yes      | `children[0]` = main content, `children[1]` = filter panel                    |
+| `getPConnect`    | function         | Yes      | PConnect getter                                                               |
+
+## Implementation Structure
+
+**Module Setup:** The component requires the project's base component interface and companion styles for layout classes (header, container, column, filter container, and inline styles).
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: extract `children`, `title`, and `filterPosition`. Treat `children` as a renderable element array (`childrenToRender`).
+2. Compute the side-layout `direction`: `'row-reverse'` when `filterPosition === 'inline-start'`, otherwise `'row'`.
+3. Render a heading (level 4) showing `title`, followed by one of two grid layouts:
+   - **When `filterPosition === 'block-start'`:** a grid container with column-reverse direction (so the filter panel appears visually above the content even though it's declared second in the DOM), containing a full-width item for `childrenToRender[0]` (main content) and a full-width item with `id="filters"` for `childrenToRender[1]` (filter panel).
+   - **Otherwise (side layout):** a grid container with the computed `direction`, containing a 9-column-wide item for `childrenToRender[0]` (main content) and a 3-column-wide item with `id="filters"` for `childrenToRender[1]` (filter panel).
 
 ## Behavioral Contract
 
 ### Title
 
-- If `title` is non-empty, render `<Typography variant='h4'>{title}</Typography>` above the grid.
+- If `title` is non-empty, render a level-4 heading with `title` 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 }}>`.
+- Grid container with column-reverse direction (reverse so filter renders visually above content).
+- Filter panel: full-width (12-column) grid item with `id='filters'`.
+- Main content: full-width (12-column) grid item.
 
 ### 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 }}>`.
+- Grid container with computed row direction (optionally reversed based on position value).
+- Main content: 9-column-wide grid item.
+- Filter panel: 3-column-wide grid item with `id='filters'`.
 
 ### Children Assignment
 
@@ -97,16 +68,11 @@ Side-by-side layout — main content left, filters right:
 
 ### Block-Start Layout (filter above content)
 
-```
-[Filter panel — xs:12]
-[Main content — xs:12]
-```
+A stacked layout: the filter panel occupies the full width above the main content, which also occupies the full width below it.
 
 ### Side Layout (filter to side)
 
-```
-[Main content — xs:9]  [Filters — xs:3]
-```
+A side-by-side layout: the main content occupies the majority width (75%) on one side, with the filters occupying the remaining width (25%) beside it.
 
 **CSS-only implementation notes:**
 
@@ -116,34 +82,29 @@ Side-by-side layout — main content left, filters right:
 - Filter panel: `id='filters'` — required for accessibility/selector targeting.
 - Responsive: collapse side layout to stacked on mobile.
 
+**Companion styles** define classes for: header (font-weight 500, font-size 1.25rem), container (vertical margins), column (grid with gap and baseline alignment), filter container (7-column repeat grid), and inline (grid with gap, baseline alignment, top margin).
+
 ## 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).
+- Column-reverse direction in block-start mode — in plain CSS, use flexbox column direction with `order` property.
+- `title` is optional — if absent, skip the heading 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`
+- A design-system heading component (level 4) for the title
+- A design-system grid/layout component for the responsive container
+- Companion styles for spacing and alignment classes
 
 ## 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, map the following: a level-4 heading for the title; a responsive grid container supporting directional flow (row, row-reverse, column-reverse); grid items that accept column-span sizing (full-width for stacked, 9/3 split for side layout). In a CSS-only approach, use a native heading element and CSS grid or flexbox. Other design systems provide equivalent grid and typography primitives.
 
-When implementing in a specific design system:
+When implementing:
 
-- `filterPosition === 'block-start'` requires stacked layout (12/12) — not side layout (9/3)
+- `filterPosition === 'block-start'` requires stacked layout (full-width / full-width) — not side layout (9/3)
 - Filter panel must always have `id='filters'`
-- Title heading (`h4` level) is optional — only render when `title` is provided
+- Title heading (level 4) is optional — only render when `title` is provided