@pega/sdk 0.0.5 → 0.0.6

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

@@ -12,13 +12,13 @@ Renders promoted filter controls above a list view. Filter fields are created dy
 
 ## Pega Metadata
 
-- **Registration key:** `PromotedFilters` (in `component-map.ts`)
+- **Registration key:** `PromotedFilters` (in the project's component map)
 - **Category:** Search / Filter template
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop              | Type       | Required | Description                                                   |
+| Input             | 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`                           |
@@ -27,97 +27,20 @@ Renders promoted filter controls above a list view. Filter fields are created dy
 | `isSearchable`    | `boolean`  | No       | Whether the ListView below shows a global search input        |
 | `getPConnect`     | `function` | Yes      | PConnect getter                                               |
 
-## Component Skeleton
-
-```typescript
-import React, { useCallback, useMemo, useState, createElement } from 'react';
-import { isEmptyObject } from '../../helpers/common-utils';
-import { getComponentFromRegistry, PConnectComponent } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-import './PromotedFilters.css';
-
-const SUPPORTED_TYPES_IN_PROMOTED_FILTERS = [
-  'TextInput','Percentage','Email','Integer','Decimal','Checkbox',
-  'DateTime','Date','Time','Text','TextArea','Currency','URL','RichText',
-];
-
-// Sub-component: renders each filter field via PCore.createPConnect
-function Filters({ filters, transientItemID, localeReference }) {
-  return filters.map((filter, index) => {
-    const filterClone = { ...filter };
-    if (!SUPPORTED_TYPES_IN_PROMOTED_FILTERS.includes(filterClone.type)) {
-      filterClone.type = 'TextInput';
-      delete filterClone.config.placeholder;
-    }
-    filterClone.config.contextName = transientItemID;
-    filterClone.config.readOnly = false;
-    filterClone.config.context = transientItemID;
-    filterClone.config.localeReference = localeReference;
-    const c11nEnv = PCore.createPConnect({
-      meta: filterClone,
-      options: { hasForm: true, contextName: transientItemID },
-    });
-    return <React.Fragment key={index}>{createElement(PConnectComponent, c11nEnv)}</React.Fragment>;
-  });
-}
-
-export default function PromotedFilters(props: PromotedFilterProps) {
-  const ListView = getComponentFromRegistry('ListView');
-  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-  const { getPConnect, viewName, filters, listViewProps, pageClass, parameters } = props;
-  const [initTable, setInitTable] = useState(false);
-  const [payload, setPayload] = useState({});
-
-  // 1. Build transient item on mount (useMemo)
-  const filtersProperties = {};
-  filters.forEach(f => { filtersProperties[PCore.getAnnotationUtils().getPropertyName(f.config.value)] = ''; });
-  const transientItemID = useMemo(() => {
-    return getPConnect().getContainerManager().addTransientItem({
-      id: viewName, data: { ...filtersProperties, classID: pageClass },
-    });
-  }, []);
-
-  // 2. Search handler: read form changes, format filters, set payload
-  const getFilterData = useCallback((e) => {
-    e.preventDefault();
-    const changes = PCore.getFormUtils().getChanges(transientItemID);
-    const formValues = {};
-    Object.keys(changes).forEach(key => {
-      if (!['context_data','pageInstructions'].includes(key)) formValues[key] = changes[key];
-    });
-    const promotedFilters = formatPromotedFilters(formValues);
-    if (PCore.getFormUtils().isFormValid(transientItemID) && isValidInput(formValues)) {
-      setInitTable(true);
-      const Query: any = { dataViewParameters: parameters };
-      if (!isEmptyObject(promotedFilters)) Query.query = { filter: { filterConditions: promotedFilters } };
-      setPayload(Query);
-    }
-  }, [transientItemID]);
-
-  // 3. Clear handler
-  const clearFilterData = useCallback(() => {
-    PCore.getContainerUtils().clearTransientData(transientItemID);
-    setInitTable(false);
-    getPConnect()?.getListActions?.()?.setSelectedRows([]);
-  }, [transientItemID]);
-
-  // 4. Render: title + filter fields + Clear/Search buttons + conditional ListView
-  return (
-    <>
-      <div>{listViewProps.title}</div>
-      <div className="psdk-grid-filter">
-        <Filters filters={filters} transientItemID={transientItemID}
-          localeReference={listViewProps.localeReference} />
-      </div>
-      <div>
-        <ClearButton onClick={clearFilterData}>Clear</ClearButton>
-        <SearchButton onClick={getFilterData}>Search</SearchButton>
-      </div>
-      {initTable && <ListView {...listViewProps} title="" payload={payload} isSearchable />}
-    </>
-  );
-}
-```
+## Implementation Structure
+
+**Constants:** Define a `SUPPORTED_TYPES_IN_PROMOTED_FILTERS` list containing field types that can be rendered as filters directly: `TextInput`, `Percentage`, `Email`, `Integer`, `Decimal`, `Checkbox`, `DateTime`, `Date`, `Time`, `Text`, `TextArea`, `Currency`, `URL`, `RichText`.
+
+**Filters Sub-Component** — accepts `filters`, `transientItemID`, and `localeReference`. For each filter: clone the filter object; if its `type` is not in the supported types list, coerce it to `'TextInput'` and remove its `config.placeholder`; set `config.contextName`, `config.readOnly = false`, `config.context`, and `config.localeReference` on the clone; create a PConnect environment via `PCore.createPConnect({ meta: filterClone, options: { hasForm: true, contextName: transientItemID } })`; and render the resulting component via the project's component registry bridge component.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve the `ListView` component from the project's component registry; bind `localizedVal` to `PCore.getLocaleUtils().getLocaleValue`.
+2. Receive inputs: `getPConnect`, `viewName`, `filters`, `listViewProps`, `pageClass`, and `parameters`. Initialize local state for `initTable` (boolean, default `false`) and `payload` (object, default `{}`).
+3. Build a transient item on mount (memoized computation, empty dependency list): construct a `filtersProperties` object mapping each filter's resolved property name (via `PCore.getAnnotationUtils().getPropertyName(f.config.value)`) to an empty string, then call `getPConnect().getContainerManager().addTransientItem({ id: viewName, data: { ...filtersProperties, classID: pageClass } })` and store the resulting `transientItemID`.
+4. Define a cached callback search handler (keyed on `transientItemID`) that: prevents the default event; reads form changes via `PCore.getFormUtils().getChanges(transientItemID)`; builds a `formValues` object from those changes, excluding the `context_data` and `pageInstructions` keys; formats the values into `promotedFilters` via a `formatPromotedFilters` helper; and, if the form is valid (`PCore.getFormUtils().isFormValid(transientItemID)`) and the input passes `isValidInput(formValues)`, sets `initTable` to `true` and builds a query object (`{ dataViewParameters: parameters }`, adding a `query.filter.filterConditions` when `promotedFilters` is non-empty) and stores it in the payload local state.
+5. Define a cached callback clear handler (keyed on `transientItemID`) that clears the transient data via `PCore.getContainerUtils().clearTransientData(transientItemID)`, resets `initTable` to `false`, and clears any selected rows via `getPConnect()?.getListActions?.()?.setSelectedRows([])`.
+6. Render: the `listViewProps.title` in a heading element; the Filters sub-component (passed `filters`, `transientItemID`, and `listViewProps.localeReference`); a container with a Clear button (wired to the clear handler) and a Search button (wired to the search handler); and, when `initTable` is true, a `ListView` spread with `listViewProps`, an empty `title`, the computed `payload`, and `isSearchable` set.
 
 ## Behavioral Contract
 
@@ -125,51 +48,42 @@ export default function PromotedFilters(props: PromotedFilterProps) {
 
 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.
+1. Build `filtersWithClassID`: map each filter's property name (via `PCore.getAnnotationUtils().getPropertyName(filter.config.value)`) to an empty string, then add `classID` from `pageClass`.
+2. Call `getPConnect().getContainerManager().addTransientItem({ id: viewName, data: filtersWithClassID })`.
+3. This creates a transient data context for the filter fields and returns a `transientItemID`.
 
 ### Filters Sub-Component
 
-The `<Filters>` inline sub-component:
+The Filters 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 })`.
+1. Creates each filter field via `PCore.createPConnect({ meta: filterClone, options: { hasForm: true, contextName: transientItemID } })`.
+2. If the filter type is not in `SUPPORTED_TYPES_IN_PROMOTED_FILTERS`, coerces it to `TextInput` and removes the placeholder.
+3. Renders each created PConnect as a field component via the project's component registry bridge.
 
 ### 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.
+1. Prevent default form submission.
+2. Read form changes via `PCore.getFormUtils().getChanges(transientItemID)`.
+3. Build `formValues` from the changes, excluding `context_data` and `pageInstructions` keys.
+4. Format filter values via `formatPromotedFilters`: for each non-empty field, build `{ lhs: { field }, comparator: 'EQ', rhs: { value } }`.
+5. Validate with `PCore.getFormUtils().isFormValid(transientItemID)` and `isValidInput(formValues)`.
+6. If valid, set `initTable` to true and build a query object with `dataViewParameters` and, if filters are non-empty, `query.filter.filterConditions`.
+7. Store the query in payload local state — `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.
+1. Call `PCore.getContainerUtils().clearTransientData(transientItemID)`.
+2. Reset `initTable` to `false`.
+3. Clear any selected rows via `getPConnect()?.getListActions?.()?.setSelectedRows([])`.
+4. `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>
-```
+An outer container holding: a title heading element; a fields container with the Filters sub-component; an actions container with Clear and Search buttons (localized via `PCore.getLocaleUtils().getLocaleValue('Clear', 'SimpleTable')` and `PCore.getLocaleUtils().getLocaleValue('Search', 'SimpleTable')`); and a `ListView` below (shown only when `initTable` is true), receiving `listViewProps`, an empty `title`, the active `payload`, and `isSearchable` set.
 
 ## Visual Specifications
 
@@ -179,44 +93,40 @@ On Clear button click:
 | 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`.
+- Outer container: vertical flex layout with 1rem gap.
+- Filter fields row: horizontal flex layout, wrapping enabled, 0.5rem gap, items aligned to bottom.
+- Action buttons row: horizontal flex layout, 0.5rem gap, justified to 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.
+- Transient item must be cleaned up on unmount: call `PCore.getContainerUtils().clearTransientData(transientItemID)` or equivalent lifecycle cleanup.
+- The search handler 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.
+- `PCore.createPConnect` creates new PConnect instances for each filter — these must be properly keyed and managed.
+- `isValidInput` returns true only if at least one filter value is truthy.
 
 ## 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>`
+- `formatPromotedFilters` — builds EQ filter condition objects from form values
+- `isValidInput` — validates that at least one filter field has a value
+- `PCore.getContainerManager().addTransientItem()` — transient context setup
+- `PCore.getContainerUtils().clearTransientData()` — transient context teardown
+- `PCore.getFormUtils().getChanges()` — reads transient form state
+- `PCore.getFormUtils().isFormValid()` — validates transient form
+- `PCore.getAnnotationUtils().getPropertyName()` — resolves property names from value references
+- `PCore.createPConnect()` — creates PConnect instances for filter fields
+- `PCore.getLocaleUtils().getLocaleValue()` — localizes button labels
+- `ListView` — the list below the filters (from the project's component registry)
 
 ## 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, use the appropriate button component for Clear and Search actions, and a horizontal flex/wrap layout for the filter fields row. The filter fields themselves are rendered dynamically via PConnect and will use whatever field components are registered in the project's component registry. Each design system will have its own equivalents for the action buttons and layout containers.
 
-When implementing in a specific design system:
+Design considerations:
 
 - 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
+- The `formatPromotedFilters` helper builds the query filter payload — use it unchanged
 - Transient item cleanup on unmount is required to avoid stale data
+- Button labels must be localized via `PCore.getLocaleUtils().getLocaleValue`

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

@@ -12,78 +12,56 @@ A case view variant designed for self-service portal channels. Uses a horizontal
 
 ## Pega Metadata
 
-- **Registration key:** `SelfServiceCaseView` (in `component-map.ts`)
+- **Registration key:** `SelfServiceCaseView` (in the project's component map)
 - **Category:** Page template — self-service case workspace
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop           | Type          | Required | Description                                                     |
-| -------------- | ------------- | -------- | --------------------------------------------------------------- |
-| `children`     | `ReactNode[]` | Yes      | Region children (variable count based on `isObjectType`)        |
-| `isObjectType` | `boolean`     | No       | Whether the case is an object-type (affects child region count) |
-| `getPConnect`  | `function`    | Yes      | PConnect getter                                                 |
-
-## Component Skeleton
-
-```typescript
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import { prepareCaseSummaryData, filterUtilities } from '../utils';
-import { Utils } from '../../helpers/utils';
-
-export default function SelfServiceCaseView(props) {
-  const CaseViewActionsMenu = getComponentFromRegistry('CaseViewActionsMenu');
-  const CaseSummary = getComponentFromRegistry('CaseSummary');
-  const {
-    icon = '', getPConnect, header, subheader,
-    showCaseLifecycle = true, showSummaryRegion = true,
-    showUtilitiesRegion = true, showCaseActions = true,
-    children, caseClass,
-    caseInfo: { availableActions = [], availableProcesses = [], caseTypeID = '', caseTypeName = '' },
-  } = props;
-  const pConnect = getPConnect();
-
-  // 1. Boolean coercion (props may be strings)
-  const [bShowCaseLifecycle, bShowSummaryRegion, bShowUtilitiesRegion, bShowCaseActions] =
-    [showCaseLifecycle, showSummaryRegion, showUtilitiesRegion, showCaseActions]
-      .map(p => p === true || p === 'true');
-
-  // 2. Object type check — affects child indexing
-  const isObjectType = (PCore.getCaseUtils() as any).isObjectCaseType(caseClass);
-
-  // 3. Region assignment by child index
-  const renderedRegions = isObjectType
-    ? { caseSummary: children[0], utilities: filterUtilities(children[2]) }
-    : { caseSummary: children[0], stages: children[1], todo: children[2], utilities: filterUtilities(children[4]) };
-
-  // 4. Filter summary fields for self-service channel
-  const { primarySummaryFields, secondarySummaryFields } = prepareCaseSummaryData(
-    renderedRegions.caseSummary,
-    (config) => config?.availableInChannel?.selfService === true
-  );
-
-  // 5. Utilities visibility check
-  const showUtilities = bShowUtilitiesRegion && isUtilitiesRegionNotEmpty();
-  const showSummary = bShowSummaryRegion && (primarySummaryFields.length > 0 || secondarySummaryFields.length > 0);
-
-  // 6. Render: header bar + flex row (summary 25% | main flex:1 | utilities 25%)
-  return (
-    <div>
-      <HeaderBar>{header} {bShowCaseActions && <CaseViewActionsMenu ... />}</HeaderBar>
-      <div style={{ display: 'flex', flexDirection: 'row' }}>
-        {showSummary && <div style={{ flex: '0 0 25%' }}><CaseSummary ... /></div>}
-        <div style={{ flex: 1 }}>{bShowCaseLifecycle && renderedRegions.stages}{renderedRegions.todo}</div>
-        {showUtilities && <div style={{ flex: '0 0 25%' }}>{renderedRegions.utilities}</div>}
-      </div>
-    </div>
-  );
-}
-```
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Name                  | Type                | Required | Description                                                                              |
+| --------------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `children`            | renderable content  | Yes      | Region children (variable count based on `isObjectType`)                                 |
+| `icon`                | `string`            | No       | Icon identifier for the case type avatar                                                 |
+| `header`              | `string`            | Yes      | Case type display name / header text                                                     |
+| `subheader`           | `string`            | No       | Secondary header text (typically case ID)                                                |
+| `showCaseLifecycle`   | `boolean \| string` | No       | Whether to show the lifecycle/stages region (default `true`)                             |
+| `showSummaryRegion`   | `boolean \| string` | No       | Whether to show the summary column (default `true`)                                      |
+| `showUtilitiesRegion` | `boolean \| string` | No       | Whether to show the utilities column (default `true`)                                    |
+| `showCaseActions`     | `boolean \| string` | No       | Whether to show the actions menu (default `true`)                                        |
+| `caseClass`           | `string`            | No       | Case class used to determine object-type behavior                                        |
+| `caseInfo`            | `object`            | No       | Object containing `availableActions`, `availableProcesses`, `caseTypeID`, `caseTypeName` |
+| `getPConnect`         | `function`          | Yes      | PConnect getter                                                                          |
+
+## Implementation Structure
+
+**Module Setup:** The component needs the project's component registry (to retrieve `CaseViewActionsMenu` and `CaseSummary` at runtime), a `prepareCaseSummaryData` utility for filtering summary fields, a `filterUtilities` utility for filtering non-self-service utilities, a `Utils` helper for resolving image sources, and companion styles for the layout and header.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `CaseViewActionsMenu` and `CaseSummary` from the project's component registry.
+2. Receive inputs: `icon` (default `''`), `getPConnect`, `header`, `subheader`, `showCaseLifecycle`/`showSummaryRegion`/`showUtilitiesRegion`/`showCaseActions` (each defaulting to `true`), `children`, `caseClass`, and `caseInfo` fields (`availableActions`, `availableProcesses`, `caseTypeID`, `caseTypeName`, each with sensible defaults); call `getPConnect()` once and reuse the result.
+3. Coerce the four `show*` boolean-ish inputs (which may arrive as strings) to real booleans by checking `p === true || p === 'true'` for each.
+4. Determine `isObjectType` via `PCore.getCaseUtils().isObjectCaseType(caseClass)` — this affects how children are indexed.
+5. Get the locale key via `pConnect.getCaseLocaleReference()`.
+6. Resolve the case icon image source via `Utils.getImageSrc(icon, Utils.getSDKStaticConentUrl())`.
+7. **Assign regions using TWO parallel arrays:** rendered children (for display) and PConnect child envs (for metadata access). Get `renderChildren` from the framework's content projection input (as a renderable array). Get `pConnChildren` from `pConnect.getChildren()` (PConnect child envs that DO have `getPConnect` methods). Index both by the same positions. For rendering: `stagesElement = renderChildren[1]`, `todoElement = renderChildren[2]`, `utilitiesElement = renderChildren[4]` (non-object) or `mainElement = renderChildren[1]`, `utilitiesElement = renderChildren[2]` (object). For metadata: `summaryEnv = pConnChildren[0]`, `utilitiesEnv = pConnChildren[4]` (non-object) or `pConnChildren[2]` (object). **Do NOT call `.getPConnect()` on rendered children** — they are rendered elements without a direct `getPConnect` method.
+8. Filter summary fields for the self-service channel: call `prepareCaseSummaryData(summaryEnv, filterFn)` where `summaryEnv` is from `pConnChildren` (not from rendered children). The helper calls `summaryEnv.getPConnect().getChildren()` which works because PConnect child envs have `getPConnect` methods.
+9. Compute utilities visibility: `isUtilitiesRegionNotEmpty(utilitiesEnv)` uses the PConnect child env (from `pConnChildren`) to check whether utilities have visible children.
+10. Compute visibility flags: `showUtilities` is true when `bShowUtilitiesRegion` and `isUtilitiesRegionNotEmpty()`; `showSummary` is true when `bShowSummaryRegion` and either summary field list is non-empty.
+11. Render a self-service header bar (class `selfServiceCaseViewHeader`) showing the localized `header` text and (when `bShowCaseActions`) the `CaseViewActionsMenu` component with the action inputs passed through.
+12. Below the header, render a horizontal flex row with three sections: the summary region at `flex: 0 0 25%` (rendered only when `showSummary`, containing a card with the case icon avatar, localized header, subheader, dividers, and the `CaseSummary` component with `arPrimaryFields` and `arSecondaryFields`); the main content area at `flex: 1` (containing the stages element directly when `bShowCaseLifecycle`, followed by the todo/main element directly); and the utilities region at `flex: 0 0 25%` (rendered only when `showUtilities`, rendering the utilities element directly). **Render children directly in the template** — do NOT pass them through the PConnect bridge component.
 
 ## Behavioral Contract
 
 ### Region Assignment by Child Index
 
+> ⚠️ **CRITICAL:** Use TWO parallel arrays for child access:
+>
+> - `renderChildren` (from the framework's content projection input) — for RENDERING regions directly in the template
+> - `pConnChildren` (from `pConnect.getChildren()`) — for METADATA access (filtering, field extraction)
+>
+> **Do NOT call `.getPConnect()` on rendered children** — they are rendered elements without a direct `getPConnect` method. Only PConnect child envs (from `pConnect.getChildren()`) have `getPConnect`.
+
 Child indexing depends on `isObjectType`:
 
 **`isObjectType === false` (5 children):**
@@ -106,45 +84,34 @@ Child indexing depends on `isObjectType`:
 
 Show/hide individual regions based on:
 
-- `showSummary`: always show summary region.
+- `showSummary`: show summary only when the region has filtered content.
 - `showMain`: always show main content region.
-- `showUtilities`: show utilities only if the region has content.
+- `showUtilities`: show utilities only if the region has visible children.
 
-### `selfServiceCaseViewHeader`
+### Self-Service Case View Header
 
 Renders a slim header bar above the main flex layout showing:
 
-- Case ID / case type name
-- Case status badge
+- Localized header text via `PCore.getLocaleUtils().getLocaleValue(header, '', localeKey)`
+- The `CaseViewActionsMenu` component (when `bShowCaseActions` is true)
 
 ### Case Summary Data
 
-Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` with a filter:
+Call `prepareCaseSummaryData(summaryEnv, filterFn)` where `summaryEnv` is a PConnect child env (from `pConnect.getChildren()`, NOT from rendered children). The helper accesses `summaryEnv.getPConnect().getChildren()` to iterate region children.
 
 - Only include fields where `availableInChannel.selfService === true`.
 
 ### Utilities Filter
 
-Call `filterUtilities(utilitiesChildren, getPConnect)` to remove utilities not appropriate for self-service channels.
+The `isUtilitiesRegionNotEmpty` function uses the PConnect child env (from `pConnect.getChildren()`) to access `utilitiesEnv.getPConnect().getChildren()` and check visibility.
+
+### Utilities Visibility Check
+
+Uses the PConnect child env — NOT the rendered element — to access children metadata via `getPConnect().getChildren()` and verify at least one child has `getConfigProps().visibility !== false`.
 
 ### Render Structure
 
-```
-<div className="psdk-ss-case-view">
-  <selfServiceCaseViewHeader />
-  <div className="psdk-ss-case-view-body" style="display:flex; flex-direction:row">
-    <div style="flex: 0 0 25%">   {/* Summary */}
-      {showSummary && summaryRegion}
-    </div>
-    <div style="flex: 1">         {/* Main content */}
-      {showMain && mainRegion}
-    </div>
-    <div style="flex: 0 0 25%">  {/* Utilities */}
-      {showUtilities && utilitiesRegion}
-    </div>
-  </div>
-</div>
-```
+An outer container holding the self-service header (`psdk-ss-case-view-header` or equivalent class), followed by a flex row body (`display: flex; flex-direction: row`) with three children: a `flex: 0 0 25%` box showing the summary card when `showSummary` is true; a `flex: 1` box showing the main region; and a `flex: 0 0 25%` box showing the utilities region when `showUtilities` is true.
 
 ## Visual Specifications
 
@@ -154,45 +121,53 @@ Call `filterUtilities(utilitiesChildren, getPConnect)` to remove utilities not a
 | Main      | flex: 1     | Main case content / assignment form         |
 | Utilities | 25% (fixed) | Filtered utilities                          |
 
-**CSS-only implementation notes:**
+**Companion styles:**
 
 - Body layout: `display: flex; flex-direction: row; gap: 1rem`.
 - Summary column: `flex: 0 0 25%; min-width: 0`.
 - Main column: `flex: 1 1 auto; min-width: 0`.
 - Utilities column: `flex: 0 0 25%; min-width: 0`.
-- Header bar: `display: flex; align-items: center; gap: 1rem; padding: 0.5rem 0; margin-bottom: 1rem`.
+- Header bar: `margin: 10px 8px 0 8px; height: 50px; display: flex; justify-content: space-between; align-items: center; padding: 0 8px`. Background uses the primary light color with contrasting text.
+- Summary card root: padding and margin of one spacing unit on all sides.
+- Summary card header: uses the info light background with contrasting text, rounded corners.
+- Case icon box: info dark background, fixed size (e.g. 64x64), with padding.
 - Responsive: collapse to single column on mobile.
 
 ## Edge Cases & Special Logic
 
 - `isObjectType` changes the number of `children` — always derive regions by index based on this flag.
-- `filterUtilities` may return empty array — `showUtilities` should be `false` in that case (hide the column entirely).
-- Summary fields filtered by `availableInChannel.selfService` — if all fields are filtered out, the summary column may be empty.
+- `filterUtilities` may return an empty array — `showUtilities` should be `false` in that case (hide the column entirely).
+- Summary fields filtered by `availableInChannel.selfService` — if all fields are filtered out, the summary column is hidden.
 - The self-service header differs from the standard case header — it is a separate sub-component, not the full `CaseView` header.
+- The four `show*` inputs may arrive as string `"true"`/`"false"` — coerce to boolean before use.
 
 ## Dependencies
 
-- `prepareCaseSummaryData` from `./utils` — with self-service channel filter applied
-- `filterUtilities` from `./utils` — removes non-self-service utilities
-- `selfServiceCaseViewHeader` — inline sub-component or imported header
-- `PConnectComponent` from `@pega/sdk-react`
+- `prepareCaseSummaryData` from the template utilities — with self-service channel filter applied
+- `filterUtilities` from the template utilities — removes non-self-service utilities
+- `Utils.getImageSrc` / `Utils.getSDKStaticConentUrl` — resolves case icon image paths
+- `PCore.getCaseUtils().isObjectCaseType()` — determines child region indexing
+- `PCore.getLocaleUtils().getLocaleValue()` — header localization
+- `pConnect.getCaseLocaleReference()` — locale key for the case
+- The project's component registry — to retrieve `CaseViewActionsMenu` and `CaseSummary`
+- The project's base component interface
 
 ## Design System Mapping
 
-**UI control type:** Self-service portal case workspace — horizontal 3-panel flex layout.
+**UI control type:** Self-service portal case workspace — horizontal 3-panel flex layout with card-based summary.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Layout                                                                 | Header Bar                  |
-| ------------------ | ---------------------------------------------------------------------- | --------------------------- |
-| Default (CSS only) | CSS `display:flex` with percentage widths                              | Custom `<header>`           |
-| MUI                | `<Box display='flex' flexDirection='row'>` with `<Box flex='0 0 25%'>` | `<Box>` with `<Typography>` |
-| Ant Design         | `<Layout>` with `<Sider>` + `<Content>`                                | `<PageHeader>`              |
-| Chakra UI          | `<HStack align='stretch'>` with width constraints                      | `<Flex>`                    |
-| Shadcn/ui          | Tailwind `flex flex-row`                                               | Custom header               |
+- **Layout container:** Use the design system's flex/grid primitives for the 3-column row. The key constraint is 25%/flex-1/25% proportions.
+- **Summary card:** Use the design system's card component with a header section (avatar + title + subtitle) and dividers between sections. The header should use the theme's info/primary color.
+- **Avatar/Icon:** Use the design system's avatar component (square variant) with the resolved case icon image.
+- **Header bar:** Use the design system's flex container with space-between alignment. Background should be the theme's primary-light color with contrasting text.
+- **Dividers:** Use the design system's divider/separator component between card sections.
+- **Typography:** Use the design system's heading (h6) for the case name and body text for the case ID.
 
-When implementing in a specific design system:
+Key constraints regardless of design system:
 
 - `isObjectType` determines child count — do not assume fixed child order without checking this flag
 - Self-service channel filter on summary data is mandatory — `availableInChannel.selfService === true`
 - `filterUtilities` result controls utilities column visibility
+- Utilities visibility requires checking child `getConfigProps().visibility !== false`