@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,198 @@
+# Skill: Template Components
+
+Create or replace template components (layouts and page structures) in the project. Template components arrange child components into visual layouts (columns, tabs, forms, pages).
+
+---
+
+## Architecture Overview
+
+Each template component lives under the project's template components directory in its own folder, named after the component. The folder typically contains: the component implementation file; an optional re-export module; an optional companion stylesheet; an optional utilities module for template-specific helpers; and an optional metadata file.
+
+Some templates have nested sub-templates instead of a flat structure. For example, `TwoColumn` organizes its three variants as separate sub-folders, each containing its own implementation file.
+
+---
+
+## Input Contract
+
+Template components extend the project's **base component interface**, which declares a single required member, `getPConnect` — a function returning the `PConnect` instance for the component.
+
+Templates typically receive children through `getPConnect().getChildren()` rather than via the framework's content projection mechanism, though layout templates (TwoColumn, OneColumn) receive children via content projection directly.
+
+---
+
+## Implementation Patterns
+
+### Layout Template (renders children in grid)
+
+Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
+
+This pattern is design-system agnostic — the grid/flex section must be replaced with your design system's grid or flex layout primitive; see the "Design System Adaptation" section below.
+
+**Module Setup:** Define the input contract as an extension of the project's base component interface, adding an optional `templateCol` string (e.g. `'1fr 1fr'`, `'2fr 1fr'`) representing the CSS grid column template. The component accepts children via the framework's content projection mechanism.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `children` and `templateCol` (defaulting to `'1fr 1fr'`) from inputs; treat `children` as an array of child elements.
+2. `templateCol` maps directly to CSS `grid-template-columns` — no conversion needed.
+3. Render an outer container with `display: grid`, `gridTemplateColumns: templateCol`, a `gap`, and `width: 100%` so the layout always fills its parent.
+4. Inside, render two inner wrapper elements — one per column — each with `display: grid`, a `gap`, and `alignContent: baseline`; the first wraps `children[0]`, the second wraps `children[1]`.
+5. On mobile, use a media query or container query to stack the columns into a single column.
+
+> ⚠️ **Do NOT use DS-specific grid components** for layout templates. Many DS grids have built-in `max-width` constraints that prevent the layout from filling its parent container. Use plain CSS grid with `grid-template-columns: templateCol` — this works with every design system and guarantees full-width rendering.
+
+---
+
+## Design System Adaptation (Layout Templates Only)
+
+> Form templates and page templates use the PConnect bridge pattern and do **not** use any design system primitives. This section applies only to layout templates: TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants.
+>
+> **Use plain CSS grid** (`display: grid; grid-template-columns; width: 100%`) for all layout templates. The `templateCol` input value (e.g., `'1fr 1fr'`, `'2fr 1fr'`) maps directly to `grid-template-columns`. Do NOT use DS grid components — they may have max-width constraints.
+
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/template-skills/<ComponentName>.md` contains a **Design System Mapping** section where available. Use it as a starting point.
+
+**2. If the chosen design system is not covered** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
+
+**3. Discover the API from installed packages** — before writing the component's markup, confirm the layout component names and inputs by searching the installed design-system package's type declaration files for grid/column/flex primitives, then inspecting the exported input interface.
+
+**4. Column ratio mapping** — the `templateCol` input (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
+
+| `templateCol` | Fraction  | 12-col grid | CSS `grid-template-columns` |
+| ------------- | --------- | ----------- | --------------------------- |
+| `'1fr 1fr'`   | 50% / 50% | 6 / 6       | `1fr 1fr`                   |
+| `'2fr 1fr'`   | 67% / 33% | 8 / 4       | `2fr 1fr`                   |
+| `'1fr 2fr'`   | 33% / 67% | 4 / 8       | `1fr 2fr`                   |
+
+**5. Responsive behavior** — on mobile, both columns must stack to full width. Use your DS's responsive breakpoint mechanism or a CSS media query.
+
+### Form Template (renders children via PConnect bridge)
+
+Used for: DefaultForm, HierarchicalForm
+
+> ⚠️ **CRITICAL:** Form templates MUST use the project's state-connection wrapper pattern. Without it, form fields will not render because they won't be subscribed to the application store for visibility and input updates.
+
+**Module Setup:** The component depends on the framework's element-creation utility, the project's PConnect bridge utility, the project's state-connection wrapper (from the project's state utilities), and `getKeyForMappedField` / `mapStateToInputs` from the companion utilities module. Define the input contract as an extension of the project's base component interface with `NumCols: string` and `instructions: string`.
+
+Outside the main component logic, define a `Child` wrapper using the project's state-connection wrapper invoked with `mapStateToInputs`. This is MANDATORY — it subscribes each field to the application store. Inside `Child`, receive `key`, `visibility`, and the remaining inputs, then render the project's PConnect bridge utility with those values.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect` and `NumCols` (defaulting to `'1'`) from inputs.
+2. Unwrap the region children: the first child returned by `getPConnect().getChildren()` is a region, so call `.getPConnect().getChildren()` on it to get the actual field children.
+3. Map each child through the `Child` wrapper defined above — every child MUST be rendered via the `Child` wrapper with `key` set to `getKeyForMappedField(kid)` and all field data spread, never directly through the PConnect bridge utility alone.
+4. Return a container element with a class name derived from `NumCols` (e.g. `form-${NumCols}-col`) containing the mapped children.
+
+> ❌ **INCORRECT pattern** (will cause fields to not render): mapping children directly through the PConnect bridge utility, bypassing the state-connection wrapper entirely. This causes fields to never subscribe to the application store, so they silently fail to render or update.
+
+### Page Template (renders regions from PConnect children)
+
+Used for: CaseView, DefaultPage, ObjectPage, AppShell, Confirmation
+
+> ⚠️ **CRITICAL:** Page templates are NOT simple wrappers. They contain PCore API calls, lifecycle effects, state management, and complex input drilling to infrastructure components. NEVER simplify a Page template to a single return statement. Always follow the component-specific skill file's Implementation Structure faithfully.
+>
+> After generating a Page template, compare your output against the skill file's Implementation Structure. Every piece of state, every effect, every registry lookup, every PCore API call, helper function, and utility dependency described there MUST appear in your generated output. If your output is significantly shorter than what's described, you have over-simplified.
+>
+> ⚠️ **COMMON ERROR — `tabconfig` must be an array, NOT a rendered element:**
+> The `VerticalTabs` infrastructure component expects `tabconfig` to be an array of `{ name: string; id: number }` objects. You MUST use the `extractTabsInfo` SDK utility to build this array. NEVER pass a raw rendered region element to `VerticalTabs` — it causes `TypeError: tabconfig.map is not a function`.
+>
+> ⚠️ **CRITICAL — Do NOT call `child.getPConnect()` on framework-rendered children:**
+> Children passed to page templates via the framework's content projection mechanism are **rendered elements** — they do NOT expose `getPConnect` as a direct method. Calling `child.getPConnect()` on them causes `TypeError: child.getPConnect is not a function`. For named region extraction, use `PCore.getSDKUtils().getSDKCaseUtils().getChildRegionByName(childArr, name)`. For tab info, use `PCore.getSDKUtils().getSDKCaseUtils().extractTabsInfo(tabsRegion)`. For field extraction in CaseSummary, use `PCore.getSDKUtils().getSDKCaseUtils().filterSummaryFields(getPConnect)`. If you need PConnect metadata access by index (e.g., SelfServiceCaseView), use `getPConnect().getChildren()` which returns PConnect child envs that DO have `getPConnect` methods. Render extracted regions directly in the template — do NOT pass them through the PConnect bridge component.
+
+**Module Setup:** The component depends on the project's component registry (to resolve infrastructure components like `VerticalTabs` and `DeferLoad`), SDK utilities from `PCore.getSDKUtils()`, local state management, and lifecycle effects. Define the input contract as an extension of the project's base component interface.
+
+**Main Component Logic** — general shape for any Page template:
+
+1. Look up infrastructure components from the project's component registry, e.g. `VerticalTabs` and `DeferLoad`.
+2. Receive ALL inputs described in the component-specific skill file (e.g. `getPConnect`, `children`, `header`, etc.), then call `getPConnect()` once and reuse the result.
+3. Declare ALL state, effects, and handlers described in the skill file — for example local state for active tab tracking, and lifecycle effects for event listeners or pub/sub subscriptions.
+4. Use SDK utilities from `PCore.getSDKUtils().getSDKCaseUtils()` for region extraction (e.g., `getChildRegionByName`, `extractTabsInfo`, `filterSummaryFields`). For positional child access needing metadata, use `getPConnect().getChildren()` (PConnect child envs). **NEVER implement custom region extraction that calls `child.getPConnect()` on framework-rendered children.**
+5. Render the full layout structure described in the skill file. Render extracted regions directly in the template — they are already renderable elements.
+
+---
+
+## Rendering Children
+
+Templates use three patterns to render child components:
+
+### 1. Children via content projection (layout templates)
+
+TwoColumn, OneColumn, and similar layout templates receive children via the framework's content projection mechanism. Receive `children` from inputs and treat it as an array of child elements before indexing into it.
+
+### 2. PConnect children (form/page templates)
+
+Get the child PConnect objects via `getPConnect().getChildren()`, then render each one through the project's PConnect bridge utility, passing the child's configuration object and a unique key for each child.
+
+### 3. State-connected children (REQUIRED for Form templates)
+
+> ⚠️ This is the ONLY correct pattern for Form templates (DefaultForm, HierarchicalForm). Using pattern #2 above for form fields will result in fields not rendering.
+
+The component depends on the project's PConnect bridge utility, the project's state-connection wrapper (from the project's state utilities), and `getKeyForMappedField` / `mapStateToInputs` from the companion utilities module. Define a `Child` wrapper using the state-connection wrapper invoked with `mapStateToInputs` — this subscribes each field to the application store for visibility and dynamic input updates. Inside the wrapped component, receive `key`, `visibility`, and the remaining inputs, then render the PConnect bridge utility with those values.
+
+To use it: unwrap the first region's children via `getPConnect().getChildren()[0].getPConnect().getChildren()`, then map each child through the `Child` wrapper with `key` set to `getKeyForMappedField(kid)` and all field data spread.
+
+---
+
+## Helper Utilities
+
+### PConnect bridge utility
+
+The project's PConnect bridge component, used to render child PConnect objects. Use the framework's element-creation mechanism to create an instance of the bridge component for each child, passing the child's PConnect configuration and a unique key.
+
+### State-connection wrapper
+
+A higher-order utility that connects a component to the application store for visibility and dynamic input updates. Apply it with a state-mapping function to produce a store-connected version of the child component. Located in the project's state utilities module.
+
+### Instructions helper
+
+Extracts instruction text for forms. Located in the project's template utilities module. Call it with `getPConnect()` and the component's `instructions` input to obtain the resolved instruction HTML string.
+
+---
+
+## Registration
+
+Register templates in the project's component map by importing the template's default export from its folder under the template components directory and adding it to the object returned by the project's component registration function, using a key that matches the Pega component name.
+
+For nested templates (e.g., TwoColumn/TwoColumnPage/TwoColumnTab), import each sub-variant from its own nested path and register all variants as separate keys in the component map.
+
+---
+
+## Existing Template Components
+
+| Component                                       | Type       | Description                          |
+| ----------------------------------------------- | ---------- | ------------------------------------ |
+| AdvancedSearch                                  | Page       | Advanced search with filters         |
+| AppShell                                        | Page       | Top-level app layout with nav        |
+| BannerPage                                      | Page       | Page with banner section             |
+| CaseSummary                                     | Page       | Case summary header                  |
+| CaseView                                        | Page       | Main case view with regions          |
+| CaseViewActionsMenu                             | Widget     | Case action dropdown menu            |
+| Confirmation                                    | Page       | Case completion confirmation         |
+| DataReference                                   | Form       | Embedded data reference lookup       |
+| DefaultForm                                     | Form       | Standard form layout (1/2/3 columns) |
+| DefaultPage                                     | Page       | Default page structure               |
+| Details / DetailsTwoColumn / DetailsThreeColumn | Layout     | Details region layouts               |
+| FieldGroupTemplate                              | Form       | Repeating field group                |
+| HierarchicalForm                                | Form       | Multi-step hierarchical form         |
+| InlineDashboard                                 | Page       | Inline dashboard container           |
+| ListPage                                        | Page       | List/table page                      |
+| ListView                                        | Page       | Data table with filtering/sorting    |
+| MultiReferenceReadOnly                          | Display    | Read-only multi-reference display    |
+| NarrowWide / WideNarrow                         | Layout     | Asymmetric two-column layouts        |
+| ObjectPage                                      | Page       | Object detail page                   |
+| OneColumn                                       | Layout     | Single-column layout                 |
+| PromotedFilters                                 | Widget     | Filter bar for lists                 |
+| SimpleTable                                     | Table      | Editable/read-only data tables       |
+| SingleReferenceReadOnly                         | Display    | Read-only single reference           |
+| SubTabs                                         | Navigation | Tab container                        |
+| TwoColumn                                       | Layout     | Two-column layout                    |
+| WssNavBar                                       | Navigation | WSS navigation bar                   |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component is exported as the module's default export.
+2. **Children from PConnect** — Use `getPConnect().getChildren()` to access child regions.
+3. **PConnect bridge pattern** — Use the project's PConnect bridge utility to render PConnect children.
+4. **CSS files** — Template-specific styles go in a companion stylesheet alongside the component.
+5. **Responsive** — Use CSS grid with full-width on mobile and computed column widths on desktop breakpoints.
+6. **templateCol** — Layout templates often receive a `templateCol` input (e.g., `"1fr 1fr"`, `"2fr 1fr"`) to control column ratios.

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

@@ -0,0 +1,126 @@
+# Skill: AdvancedSearch
+
+Advanced search template. Renders grouped search field sections with deduplication, delegating each section to a SearchGroups sub-component. Also covers the SearchGroups sub-component.
+
+> **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-section advanced search form where search fields are organized into groups. Deduplicates search fields by value across groups. Each group is rendered by the SearchGroups sub-component. Shares search configuration via a shared search-configuration context (provided by the parent DataReference component).
+
+## Pega Metadata
+
+- **Registration key:** `AdvancedSearch` (in the project's component map)
+- **Category:** Search / Filter template
+
+## Inputs
+
+| Input               | Type       | Required | Description                               |
+| ------------------- | ---------- | -------- | ----------------------------------------- |
+| `targetObjectClass` | `string`   | Yes      | Class of the target object being searched |
+| `localeReference`   | `string`   | No       | Locale reference for i18n labels          |
+| `getPConnect`       | `function` | Yes      | PConnect getter                           |
+
+## Main Component Logic
+
+Steps in order:
+
+1. Receive inputs: `getPConnect`, `targetObjectClass`, and `localeReference`. Retrieve SearchGroups from the project's component registry.
+2. **Read shared context:** consume a shared search-configuration context (provided by the parent DataReference). From it, obtain `dataReferenceConfigToChild`, `isCreateNewReferenceEnabled`, `disableStartingFieldsForReference`, `pyID`, and `searchSelectCacheKey`.
+3. **Check for an existing selection:** from `dataReferenceConfigToChild`, obtain `selectionMode`, `value` (the single-select field value path), and `readonlyContextList` (the multi-select field path). Read the `MULTI` constant from `PCore.getConstants().LIST_SELECTION_MODE`. Compute whether a selection already exists — for multi-select, check if `getPConnect().getValue(multiSelectField)` has a non-zero length; for single-select, check if `getPConnect().getValue(singleSelectFieldValue)` is truthy. Initialize local state `showRecords` from this computed boolean.
+4. **Deduplicate search fields from metadata:** call `getPConnect()` into `pConn`. Read `rawViewMetadata = pConn.getRawMetadata()`. Iterate `rawViewMetadata.config.searchGroups`, and for each group's children, add the child to a `searchFields` collection only if its `config.value` hasn't been seen yet (tracked via a set of seen values) and it has no `config.validator`. This prevents duplicate fields from appearing across groups.
+5. **Create the editable field component from the first child:** get `firstChildPConnect` from `getPConnect().getChildren()[0].getPConnect`. Read `firstChildMeta` from `rawViewMetadata.children[0]`. Bind `localizedVal = PCore.getLocaleUtils().getLocaleValue`. Resolve `cache` via `PCore.getNavigationUtils().getComponentCache(searchSelectCacheKey)` (default empty object). Call `firstChildPConnect().createComponent(...)` with `type: firstChildMeta.type` and a config that merges the output of `getFirstChildConfig(...)` (a utility from the DataReference helpers that assembles config from `firstChildMeta`, `getPConnect`, `rawViewMetadata`, `contextClass: targetObjectClass`, `dataReferenceConfigToChild`, `isCreateNewReferenceEnabled`, `disableStartingFieldsForReference`, and `pyID`) together with `searchFields`, `showRecords`, `label: localizedVal('Search results', 'DataReference')`, `searchSelectCacheKey`, and `cache`.
+6. **Derive the editable field path:** from the created component's PConnect config, obtain `selectionList` and `dataRelationshipContext`. Set `editableField` to `selectionList.substring(1)` for multi-select mode, or `dataRelationshipContext` otherwise.
+7. Render the SearchGroups component (passed `getPConnect`, `editableField`, `localeReference`, the `setShowRecords` state updater, `searchSelectCacheKey`, and `cache`) followed by the created editable field component.
+
+## Behavioral Contract
+
+### Search Groups from Metadata
+
+1. `rawViewMetadata = getPConnect().getRawMetadata()`.
+2. `searchGroups = rawViewMetadata.config.searchGroups` — array of group config objects.
+3. Each group has a `label` and a `children` array containing field definitions.
+
+### Field Deduplication
+
+- Track seen field values in a set.
+- For each field across all groups: if `field.config.value` already in the set, skip it.
+- Also skip fields that have a `config.validator` (these are validation-only fields, not user-visible search fields).
+- Deduplication is applied per-group in order — earlier groups take precedence.
+
+### Shared Search-Configuration Context
+
+The parent DataReference provides a shared context (a framework-appropriate context or dependency injection mechanism). This context supplies: `dataReferenceConfigToChild` (containing `selectionMode`, `value`, `readonlyContextList`), `isCreateNewReferenceEnabled`, `disableStartingFieldsForReference`, `pyID`, and `searchSelectCacheKey`. The AdvancedSearch component consumes this context to configure its search behavior.
+
+### Render Structure
+
+The component renders two things sequentially: the SearchGroups sub-component (which manages search field inputs and group switching) followed by the dynamically created editable field component (which displays search results).
+
+---
+
+## Sub-Component: SearchGroups
+
+Manages search group selection, transient data for filter state, and search execution. It handles group switching, field initialization, caching, and triggering search.
+
+### Inputs
+
+| Input                  | Type       | Description                                         |
+| ---------------------- | ---------- | --------------------------------------------------- |
+| `getPConnect`          | `function` | PConnect getter                                     |
+| `editableField`        | `string`   | The reference field name for search results binding |
+| `localeReference`      | `string`   | Locale reference for i18n labels                    |
+| `setShowRecords`       | `function` | State updater to toggle search results visibility   |
+| `searchSelectCacheKey` | `string`   | Cache key for persisting search state               |
+| `cache`                | `object`   | Previously cached search state (or empty object)    |
+
+### Behavioral Contract
+
+1. **Initialize search fields:** For each field in the active search group, resolve its initial value from (in priority order): cached values for the field, a property-annotation default, a literal default, or empty string. Also resolve nested classID metadata for compound property paths.
+2. **Manage transient data:** On mount, register a transient item with `getPConnect().getContainerManager().addTransientItem(...)` containing the initialized filter values plus the reference list classID. When the active group changes, replace the transient data via `PCore.getContainerUtils().replaceTransientData(...)`.
+3. **Group switching:** Maintain local state for the active group ID. When the user selects a different group, update the active group and reinitialize transient data.
+4. **Search execution:** On search trigger, gather form data from the transient context via `PCore.getFormUtils().getSubmitData(transientItemID, { isTransientContext: true, includeDisabledFields: true })`, flatten nested objects, and use the flattened values as filter parameters.
+5. **Caching:** Persist search state (active group, field values, results) via `PCore.getNavigationUtils()` component cache for restoration on re-entry.
+
+### Render Structure
+
+The SearchGroups component renders: a group selector (when multiple groups exist), the search fields for the active group (created as live PConnect components), and a search action button.
+
+## Visual Specifications
+
+### AdvancedSearch Container
+
+Vertical stack of sections: search groups control area followed by the editable results field.
+
+### SearchGroups Section
+
+- Group selector (dropdown or tabs when multiple groups exist).
+- Search fields rendered as standard form controls in a vertical or grid layout.
+- Search button to trigger the query.
+
+Use companion styles for layout: vertical flex with appropriate gap between sections, grid or stacked layout for search fields (label plus input), and standard button styling for the search action.
+
+## Edge Cases & Special Logic
+
+- `rawViewMetadata.config.searchGroups` may be undefined if the view has no search groups — default to an empty array.
+- Field deduplication is by `field.config.value` (the property path), not by label.
+- `firstChildPConnect().createComponent(...)` — must use the correct field type from the first child metadata; the created component is a live PConnect view.
+- The shared search-configuration context is required — SearchGroups depends on it for configuration. Always ensure the context is provided by the parent DataReference.
+- The `getFirstChildConfig` utility (from the DataReference helpers) assembles configuration needed for the editable search results component.
+- Cache retrieval via `PCore.getNavigationUtils().getComponentCache(searchSelectCacheKey)` may return null — always default to an empty object.
+
+## Dependencies
+
+- A shared search-configuration context provided by the parent DataReference component
+- A `getFirstChildConfig` utility from the DataReference helpers
+- The project's component registry to retrieve SearchGroups
+- The project's base component interface for rendering dynamically created PConnect components
+- `PCore.getLocaleUtils().getLocaleValue` for i18n labels
+- `PCore.getNavigationUtils().getComponentCache(...)` for search state caching
+- `PCore.getContainerUtils().replaceTransientData(...)` for filter state management
+- `PCore.getFormUtils().getSubmitData(...)` for collecting search form values
+
+## Design System Mapping
+
+Use a vertical stacked layout for the overall advanced search form. The group selector (when multiple groups exist) can be a dropdown, tabs, or segmented control depending on the design system. Search fields should render in a two-column grid (label plus input) or vertical stack. The search button uses the design system's primary or secondary button style. The editable results component renders below the search controls. All layout should respect the shared search-configuration context for selection mode (single vs. multi-select) to determine how results are displayed and selected.

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

@@ -0,0 +1,160 @@
+# Skill: AppShell
+
+Top-level application shell template. Renders the outer portal/WSS portal frame: navigation bar, alert banners, operator avatar, portal logo, and case types. Provides a navigation store context to child components.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> **NavBar requires `pConn` input.** Without it, `pConn.resolveConfigProps()` throws `TypeError: Cannot read properties of undefined`. ALWAYS pass `pConn` where `const pConn = getPConnect()`.
+>
+> This component has **mandatory side effects** (portal logo loading, case type fetching from data page, WSS vs standard portal detection). Do NOT collapse to a single-line return statement.
+>
+> **Minimum Viable Implementation must include:**
+>
+> 1. `const pConn = getPConnect()` — and pass `pConn` to NavBar
+> 2. WSS vs standard portal detection (`portalTemplate === 'wss'`)
+> 3. Navigation store context wrapping the standard portal layout
+> 4. NavBar receiving: `getPConnect`, `pConn`, `appName`, `pages`, `caseTypes`
+> 5. AlertBanner rendering messages from `httpMessages` + `pageMessages`
+>
+> **Post-Generation Checklist:**
+>
+> - [ ] `pConn` passed to NavBar
+> - [ ] Navigation store context wrapping standard portal
+> - [ ] WSS vs standard portal detection
+> - [ ] AlertBanner with combined messages
+> - [ ] Operator info from `PCore.getEnvironmentInfo()`
+
+---
+
+## Component Purpose
+
+The outermost container for the application. Determines whether the app is running in WSS portal or standard portal mode, renders the appropriate navigation bar, handles HTTP and page-level alert messages, loads the portal logo asynchronously, and passes navigation links and case types to the nav bar.
+
+## Pega Metadata
+
+- **Registration key:** `AppShell` (in the project's component map)
+- **Category:** Page template — application shell
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input         | Type       | Required | Description                                                  |
+| ------------- | ---------- | -------- | ------------------------------------------------------------ |
+| `pages`       | `array`    | Yes      | Array of portal page objects `{ name, pyLabel, linkUrl }`    |
+| `caseTypes`   | `array`    | No       | Fallback case types (overridden by data page fetch if empty) |
+| `portalName`  | `string`   | Yes      | Portal identifier — determines WSS vs standard rendering     |
+| `displayName` | `string`   | No       | Operator display name for avatar                             |
+| `getPConnect` | `function` | Yes      | PConnect getter                                              |
+| `children`    | slot       | Yes      | Main content area                                            |
+
+## Implementation Structure
+
+**Module Setup:** Use the project's base component interface for typing. Bring in the utility module that provides `getInitials` (the project's shared helpers), the navigation store context (shared context for nav drawer state), and a companion styles file. Register the component under its key in the project's component map.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `NavBar`, `WssNavBar`, and `AlertBanner` from the project's component registry.
+2. Receive inputs: `pages` (default `[]`), `caseTypes` (default `[]`), `showAppName`, `children` (default `[]`), `getPConnect`, `httpMessages`/`pageMessages` (default `[]`), `portalTemplate`, `portalName`, `portalLogo`, and `navDisplayOptions`.
+3. Declare local state `open` (boolean, default `true`) for the nav drawer; call `getPConnect()` once into `pConn`; read `envInfo = PCore.getEnvironmentInfo()`, derive `userName = envInfo.getOperatorName() || ''`, `currentUserInitials = Utils.getInitials(userName)`, `appNameToDisplay = showAppName ? envInfo.getApplicationLabel() : ''`, bind `localizedVal = PCore.getLocaleUtils().getLocaleValue`, and declare local state `iconURL` (string, default `''`) for the async-loaded logo.
+4. Combine `httpMessages` and `pageMessages` into a single `messages` array; compute `hasBanner = messages.length > 0`.
+5. Add three lifecycle effects: one to asynchronously load the portal logo and store its URL in `iconURL`; one to fetch case types from the environment-provided data page (see the Case Types section below); and one to set the `pyPortalTemplate` value for WSS detection.
+6. Build `links` from `pages`: for each page, the click handler either calls `pConn.getActionsApi().showPage(page.pyRuleName, page.pyClassName)` when there's no external URL, or opens `page.pyURLContent` in a new tab; the label is `localizedVal(page.pyLabel, '', '')`.
+7. **Render — WSS portal:** when `portalTemplate === 'wss'`, render a container `#AppShell` containing `WssNavBar` (passed `portalName`, `imageSrc` as `iconURL`, `navLinks` as `links`, `operator` as `{ name: userName, currentUserInitials }`, `navDisplayOptions`) followed by a content region showing the `AlertBanner` (when `hasBanner`) and `children`.
+8. **Render — standard portal:** otherwise, wrap everything in the navigation store context (providing `{ open, setOpen }`) containing a flex container `#AppShell` with `NavBar` (passed `getPConnect`, `pConn`, `appName` as `appNameToDisplay`, `pages`, `caseTypes`) followed by a content region showing the `AlertBanner` (when `hasBanner`) and `children`.
+
+## Behavioral Contract
+
+### Portal Type Detection
+
+- Check `portalName` (or metadata flag) against WSS portal identifier.
+- WSS portal → render `WssNavBar` component.
+- Standard portal → render `NavBar` component.
+
+### Alert Banners
+
+1. Subscribe to `getPConnect()` for `httpMessages` and `pageMessages` updates.
+2. If either array is non-empty, render the `AlertBanner` component above the main content.
+3. `AlertBanner` receives the combined message array and a dismiss handler.
+
+### Portal Logo
+
+1. On mount, call `PCore.getAssetLoader().getSvcImageUrl(logoAssetName)` asynchronously.
+2. Store the resolved URL in local state `portalLogoUrl`.
+3. Pass `portalLogoUrl` to the nav bar as the `logo` input.
+
+### Operator Avatar
+
+- Read `displayName` from `getPConnect().getValue('.pyUserName')` or the `displayName` input.
+- Render operator avatar (initials) in the nav bar via the `operatorInfo` input.
+
+### Case Types
+
+> ⚠️ **DO NOT hardcode `'D_pyPortalTypeList'`** — this data page does not exist in most environments and will 404.
+
+The correct pattern reads the data page name dynamically from the environment, inside a lifecycle effect that runs once on mount: read `caseTypesDP = PCore.getEnvironmentInfo().environmentInfoObject?.pxApplication?.pyCaseTypesAvailableToCreateDP` (note this property may not appear in the type definitions, so a type suppression comment may be needed). When `caseTypesDP` is truthy, resolve `portalID = pConn.getValue('.pyOwner', '')`, then call `PCore.getDataPageUtils().getPageDataAsync(caseTypesDP, pConn.getContextName(), { PortalName: portalID })`; on success, if the response includes `pyCaseTypesAvailableToCreate`, store it via `pConn.replaceState('.pyCaseTypesAvailableToCreate', response.pyCaseTypesAvailableToCreate, { skipDirtyValidation: true })`; swallow any errors silently.
+
+Key points:
+
+1. Data page name comes from `environmentInfoObject.pxApplication.pyCaseTypesAvailableToCreateDP` (dynamic)
+2. Context is `pConn.getContextName()` (NOT `'root'`)
+3. Parameter `{ PortalName: portalID }` is required
+4. Result is stored via `pConn.replaceState('.pyCaseTypesAvailableToCreate', ...)` — this populates PConnect state for other consumers
+
+> ⚠️ **NavBar reads `caseTypes` from its INPUT, not from PConnect state.** Do NOT shadow the `caseTypes` input with local state. Instead, receive `caseTypes` (default empty array) directly from inputs and pass that same value straight through to `NavBar caseTypes`.
+>
+> If you store `caseTypes` in local state, NavBar will receive an empty array because the local state is never updated by `replaceState`.
+
+### Navigation Store Context
+
+- Wrap children in the navigation store context providing `{ open, setOpen }`.
+
+### Render Structure
+
+The navigation store context (providing `{ open, setOpen }`) wraps a flex container `#AppShell` containing `NavBar` (with `caseTypes` and other inputs) followed by a content region (`flexGrow: 1`, full viewport `height`, `overflow: auto`, horizontal `margin`) that shows the `AlertBanner` when there are messages, then `children`.
+
+> ⚠️ The content region MUST have:
+>
+> - `flexGrow: 1` — fill remaining viewport width beside NavBar
+> - `height: 100vh` — full viewport height
+> - `overflow: auto` — scroll when content exceeds viewport
+> - `margin: 0 1rem` — horizontal spacing between NavBar and content (approximately 16px)
+
+## Visual Specifications
+
+**CSS-only implementation notes:**
+
+- Shell wrapper: `display: flex; flex-direction: column; height: 100vh`.
+- Nav bar: `flex: 0 0 auto` (fixed height).
+- Alert banner: `flex: 0 0 auto` (shown below nav, pushes content down).
+- Content area: `flex: 1 1 auto; overflow-y: auto`.
+
+## Edge Cases & Special Logic
+
+- Logo loading is async — show fallback (app name or blank) until URL resolves.
+- Case types fetch may fail — catch errors and fall back to the `caseTypes` input.
+- `httpMessages` are transient (from API errors) — clear them after display or on next navigation.
+- `pageMessages` are persistent until explicitly dismissed.
+- If `pages` is empty, `links` array is empty — nav bar may render without page links.
+
+## Dependencies
+
+- `NavBar` component — standard portal navigation (from the project's component registry)
+- `WssNavBar` template component — WSS portal navigation (see `WssNavBar.md`)
+- `AlertBanner` component — message display (from the project's component registry)
+- Navigation store context — shared nav drawer state for descendant components
+- `PCore.getAssetLoader().getSvcImageUrl()` — logo URL resolution
+- `PCore.getDataPageUtils().getPageDataAsync()` — case types data page
+
+## Design System Mapping
+
+**UI control type:** Application shell layout — fixed nav + scrollable content area.
+
+When implementing, choose the design system's shell, nav bar, and alert components that match the project's chosen library. The structure should provide a fixed-height navigation bar at top, an optional alert region below it, and a scrollable content area filling remaining space. All design systems must preserve:
+
+- WSS vs portal detection — the nav bar component differs for each mode
+- Logo URL loaded asynchronously from `PCore.getAssetLoader()`
+- Navigation store context wrapping children so descendant nav-aware components can access drawer state and links

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

@@ -0,0 +1,90 @@
+# Skill: BannerPage
+
+Page template that wraps the `Banner` DSE component, rendering a hero image section with a configurable two-column content area below.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+A thin template wrapper that delegates entirely to the `Banner` DSE component. Translates page-template inputs (heading, message, layout, backgroundImage) into the Banner component's inputs and passes the first two children as the `a` (left) and `b` (right) content slot.
+
+## Pega Metadata
+
+- **Registration key:** `BannerPage` (in the project's component map)
+- **Category:** Page template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input             | Type                    | Required | Description                                                                                    |
+| ----------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `children`        | array of child elements | Yes      | At least 2 children — `[0]` → left (`a`) slot, `[1]` → right (`b`) slot                        |
+| `layout`          | `string`                | No       | Column layout variant for `Banner`: `'two-column'` (default), `'narrow-wide'`, `'wide-narrow'` |
+| `heading`         | `string`                | No       | Hero section heading text. Default `''`                                                        |
+| `message`         | `string`                | No       | Hero section message/subtitle. Default `''`                                                    |
+| `imageTheme`      | `string`                | No       | Banner image theme (e.g., `'light'`). Default `'light'`                                        |
+| `backgroundImage` | `string`                | No       | URL of the background image for the hero. Default `''`                                         |
+| `backgroundColor` | `string`                | No       | Background color for the hero. Default `''`                                                    |
+| `tintImage`       | `boolean`               | No       | Whether to tint the background image. Default `false`                                          |
+
+## Implementation Structure
+
+Simplest template — pure pass-through to the `Banner` DSE component.
+
+**Module Setup:** This component requires access to the project's component registry (to resolve `Banner` at runtime) and the project's base component interface. Define a component input contract extending the base component interface with optional `layout`, `heading`, `message`, `imageTheme`, `backgroundImage`, `backgroundColor` (all strings), and `tintImage` (boolean).
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `Banner` from the project's component registry (keyed by `'Banner'`).
+2. Receive inputs: `children`, `layout` (default `'two-column'`), `heading` (default `''`), `message` (default `''`), `imageTheme` (default `'light'`), `backgroundImage` (default `''`), `backgroundColor` (default `''`), and `tintImage` (default `false`).
+3. Normalize `children` to an array via a memoized computation keyed on `children`.
+4. Render a single `Banner` element with: `variant={layout}`; `a={childArray[0]}`; `b={childArray[1]}`; and a `banner` input object combining `variant: imageTheme`, `backgroundColor`, `title: heading`, `message`, `backgroundImage`, and `tintImage`.
+
+## Behavioral Contract
+
+1. Retrieve `Banner` from the project's component registry (keyed by `'Banner'`).
+2. Normalize `children` to an array (memoized computation).
+3. Render `Banner` with the following inputs:
+   - `variant={layout}` — controls column widths below the hero
+   - `a={childArray[0]}` — left/first column content
+   - `b={childArray[1]}` — right/second column content
+   - `banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}`
+4. No additional wrapper or layout — this component IS a single `Banner` render.
+
+## Visual Specifications
+
+This component has no independent visual output — all visual behavior is defined by the `Banner` DSE component. See [`design-system-extension-skills/Banner.md`](../design-system-extension-skills/Banner.md) for full visual specs.
+
+Key visual behaviors inherited from `Banner`:
+
+- Hero: full-width background image section, height `19rem`, centered title and message overlay
+- Content area: two-column grid below the hero, column widths driven by `variant`/`layout`
+
+**CSS-only implementation notes:**
+
+- This template creates no CSS of its own — implement it as a pure pass-through to `Banner`.
+- The `layout` input maps directly to `Banner`'s `variant` input.
+- `heading` → `Banner.banner.title`, `message` → `Banner.banner.message`.
+
+## Edge Cases & Special Logic
+
+- Children are normalized to an array via a memoized computation — only recomputed when `children` changes.
+- If only one child is provided, `childArray[1]` will be `undefined` — `Banner` receives `b={undefined}` and should render an empty second column.
+- `BannerPage` does NOT call `getPConnect()` itself for layout — children are passed by the Pega rendering engine via content projection.
+
+## Dependencies
+
+- The project's component registry — to resolve the `Banner` component at runtime
+- A utility to normalize children to an array — for child array normalization
+
+## Design System Mapping
+
+**UI control type:** Full-width banner hero page with configurable two-column content area.
+
+When implementing in a specific design system, map the following:
+
+- `BannerPage` is always a thin wrapper — implement `Banner` first, then `BannerPage` simply delegates to it
+- Input mapping: `layout` → `variant`, `heading` → `banner.title`, `message` → `banner.message`, `backgroundImage` → `banner.backgroundImage`
+- The Banner component renders a hero section (full-width background image with title/message overlay) plus a two-column content grid below; use your design system's layout primitives to achieve this