@pega/sdk 0.0.5 → 0.0.7

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

@@ -1,6 +1,6 @@
 # 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.
+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.
 
@@ -8,98 +8,32 @@ Advanced search template. Renders grouped search field sections with deduplicati
 
 ## 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 React context (`DataReferenceAdvancedSearchContext`).
+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 `component-map.ts`)
+- **Registration key:** `AdvancedSearch` (in the project's component map)
 - **Category:** Search / Filter template
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop           | Type       | Required | Description                        |
-| -------------- | ---------- | -------- | ---------------------------------- |
-| `dataPageName` | `string`   | Yes      | Data page for search results       |
-| `parameters`   | `object`   | No       | Parameters passed to the data page |
-| `getPConnect`  | `function` | Yes      | PConnect getter                    |
-
-## Component Skeleton
-
-```typescript
-import { useContext, useState } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import DataReferenceAdvancedSearchContext from '../DataReference/DataReferenceAdvancedSearchContext';
-import { getFirstChildConfig } from '../DataReference/utils';
-
-export default function AdvancedSearch(props) {
-  const { getPConnect, targetObjectClass, localeReference } = props;
-  const SearchGroups = getComponentFromRegistry('SearchGroups');
-
-  // 1. Context — shared config from DataReference parent
-  const {
-    dataReferenceConfigToChild, isCreateNewReferenceEnabled,
-    disableStartingFieldsForReference, pyID, searchSelectCacheKey,
-  } = useContext(DataReferenceAdvancedSearchContext) as any;
-
-  // 2. Selection state check
-  const { selectionMode, value: singleSelectFieldValue, readonlyContextList: multiSelectField } =
-    dataReferenceConfigToChild;
-  const { MULTI } = PCore.getConstants().LIST_SELECTION_MODE;
-  const isSelectionExist = selectionMode === MULTI
-    ? getPConnect().getValue(multiSelectField)?.length || false
-    : getPConnect().getValue(singleSelectFieldValue) || false;
-  const [showRecords, setShowRecords] = useState(isSelectionExist);
-
-  // 3. Metadata + field deduplication
-  const pConn = getPConnect();
-  const rawViewMetadata = pConn.getRawMetadata();
-  const searchFieldsSet = new Set();
-  const searchFields: any = [];
-  rawViewMetadata.config.searchGroups.forEach((group) => {
-    group.children.forEach((child) => {
-      if (!searchFieldsSet.has(child.config.value) && !child.config.validator) {
-        searchFields.push(child);
-        searchFieldsSet.add(child.config.value);
-      }
-    });
-  });
-
-  // 4. Create editable field component from first child
-  const firstChildPConnect = getPConnect().getChildren()[0].getPConnect;
-  const [firstChildMeta] = rawViewMetadata.children;
-  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-  const cache = PCore.getNavigationUtils().getComponentCache(searchSelectCacheKey) ?? {};
-
-  const editableFieldComp = firstChildPConnect().createComponent({
-    type: firstChildMeta.type,
-    config: {
-      ...getFirstChildConfig({ firstChildMeta, getPConnect, rawViewMetadata,
-        contextClass: targetObjectClass, dataReferenceConfigToChild,
-        isCreateNewReferenceEnabled, disableStartingFieldsForReference, pyID }),
-      searchFields, showRecords,
-      label: localizedVal('Search results', 'DataReference'),
-      searchSelectCacheKey, cache,
-    },
-  });
-
-  // 5. Derive editable field path
-  const { selectionList, dataRelationshipContext } =
-    editableFieldComp.props.getPConnect().getConfigProps();
-  const editableField = selectionMode === MULTI
-    ? selectionList.substring(1) : dataRelationshipContext;
-
-  // 6. Render: SearchGroups + editableFieldComp
-  return (
-    <>
-      <SearchGroups getPConnect={getPConnect} editableField={editableField}
-        localeReference={localeReference} setShowRecords={setShowRecords}
-        searchSelectCacheKey={searchSelectCacheKey} cache={cache} />
-      {editableFieldComp}
-    </>
-  );
-}
-```
+
+## 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
 
@@ -107,121 +41,86 @@ export default function AdvancedSearch(props) {
 
 1. `rawViewMetadata = getPConnect().getRawMetadata()`.
 2. `searchGroups = rawViewMetadata.config.searchGroups` — array of group config objects.
-3. Each group has a `label` and a `fields` array.
+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.value` already in Set, skip it.
-- Else add `field.value` to Set and include the field.
+- 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.
 
-### Context (`DataReferenceAdvancedSearchContext`)
-
-Provides shared config to `SearchGroups`:
+### Shared Search-Configuration Context
 
-```tsx
-<DataReferenceAdvancedSearchContext.Provider value={{ dataPageName, parameters, getPConnect }}>
-  {searchGroups.map((group) => (
-    <SearchGroups key={group.label} group={group} />
-  ))}
-</DataReferenceAdvancedSearchContext.Provider>
-```
+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
 
-```
-<div className="psdk-advanced-search">
-  {searchGroups.map(group => (
-    <SearchGroups group={group} key={group.label} />
-  ))}
-</div>
-```
+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
 
-Renders a single search group section: a heading + a list of editable search fields.
+Manages search group selection, transient data for filter state, and search execution. It handles group switching, field initialization, caching, and triggering search.
 
-### Props
+### Inputs
 
-| Prop    | Type     | Description                        |
-| ------- | -------- | ---------------------------------- |
-| `group` | `object` | `{ label: string, fields: array }` |
+| 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
 
-For each field in `group.fields`:
-
-1. Get `firstChildPConnect = getPConnect().getChildren()[0]`.
-2. Create an editable field component: `firstChildPConnect.createComponent({ type: field.type, config: { ...field.config } })`.
-3. Render the created component alongside a `<SearchGroups>` label row.
+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
 
-```
-<div className="psdk-search-group">
-  <h4>{group.label}</h4>
-  {group.fields.map((field, i) => (
-    <div key={i} className="psdk-search-group-field">
-      {createdFieldComponent[i]}
-    </div>
-  ))}
-</div>
-```
+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
 
-| Element         | Description                             |
-| --------------- | --------------------------------------- |
-| Outer container | Vertical stack of search group sections |
+Vertical stack of sections: search groups control area followed by the editable results field.
 
 ### SearchGroups Section
 
-| Element       | Description                           |
-| ------------- | ------------------------------------- |
-| Group heading | `<h4>` with group label               |
-| Field rows    | Each field rendered as a form control |
-
-**CSS-only implementation notes:**
+- 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.
 
-- Outer container: `display: flex; flex-direction: column; gap: 1.5rem`.
-- Group section: `display: flex; flex-direction: column; gap: 0.75rem`.
-- Group heading: `font-size: 1rem; font-weight: 600; margin-bottom: 0.25rem`.
-- Field row: `display: grid; grid-template-columns: 200px 1fr; align-items: center; gap: 0.5rem`.
+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 `[]`.
-- Field deduplication is by `field.value` (the property path), not by label.
-- `firstChildPConnect.createComponent` — must use the correct field type from `field.type`; the created component is a live PConnect view.
-- Context is required by `SearchGroups` — always wrap `SearchGroups` with the context provider.
+- `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
 
-- `DataReferenceAdvancedSearchContext` — shared context (defined in `./context` or inline)
-- `PConnectComponent` from `@pega/sdk-react` — renders created field components
-- `getRawMetadata()` — for search group config extraction
+- 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
 
-**UI control type:** Multi-section advanced search form with grouped field rows.
-
-Listed design systems are examples only.
-
-| Design System      | Group Heading                  | Field Layout                   |
-| ------------------ | ------------------------------ | ------------------------------ |
-| Default (CSS only) | `<h4>`                         | CSS grid 2-col (label + input) |
-| MUI                | `<Typography variant='h6'>`    | `<Grid container>`             |
-| Ant Design         | `<Typography.Title level={5}>` | `<Form.Item>`                  |
-| Chakra UI          | `<Heading size='sm'>`          | `<FormControl>` rows           |
-| Shadcn/ui          | `<h4>` or `<Label>`            | Tailwind grid                  |
-
-When implementing in a specific design system:
-
-- `DataReferenceAdvancedSearchContext` must be provided — `SearchGroups` consumes it via `useContext`
-- Field deduplication by `field.value` must happen before rendering
-- `createComponent` creates live editable fields — render via `createElement(PConnectComponent, fieldConfig)`
+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

@@ -1,6 +1,6 @@
 # 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 NavContext to child components.
+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.
 
@@ -8,7 +8,7 @@ Top-level application shell template. Renders the outer portal/WSS portal frame:
 
 > ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
 >
-> **NavBar requires `pConn` prop.** Without it, `pConn.resolveConfigProps()` throws `TypeError: Cannot read properties of undefined`. ALWAYS pass `pConn={pConn}` where `const pConn = getPConnect()`.
+> **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.
 >
@@ -16,14 +16,14 @@ Top-level application shell template. Renders the outer portal/WSS portal frame:
 >
 > 1. `const pConn = getPConnect()` — and pass `pConn` to NavBar
 > 2. WSS vs standard portal detection (`portalTemplate === 'wss'`)
-> 3. `NavContext.Provider` wrapping the standard portal layout
+> 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
-> - [ ] `NavContext.Provider` wrapping standard portal
+> - [ ] Navigation store context wrapping standard portal
 > - [ ] WSS vs standard portal detection
 > - [ ] AlertBanner with combined messages
 > - [ ] Operator info from `PCore.getEnvironmentInfo()`
@@ -32,158 +32,70 @@ Top-level application shell template. Renders the outer portal/WSS portal frame:
 
 ## Component Purpose
 
-The outermost container for the Pega SDK React app. 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.
+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 `component-map.ts`)
+- **Registration key:** `AppShell` (in the project's component map)
 - **Category:** Page template — application shell
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop          | 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`    | `ReactNode` | Yes      | Main content area                                            |
-
-## Component Skeleton
-
-```typescript
-import { type PropsWithChildren, useEffect, useState } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-import { Utils } from '../../helpers/utils';
-import { NavContext } from '../../helpers/reactContextHelpers';
-import './AppShell.css';
-
-interface AppShellProps extends PConnProps {
-  showAppName: boolean;
-  pages: { pxPageViewIcon: string; pyClassName: string; pyLabel: string; pyRuleName: string; pyURLContent: string }[];
-  caseTypes?: object[];
-  portalTemplate: string;
-  portalName: string;
-  portalLogo: string;
-  navDisplayOptions: { alignment: string; position: string };
-  httpMessages: string[];
-  pageMessages: string[];
-}
-
-export default function AppShell(props: PropsWithChildren<AppShellProps>) {
-  // 1. Registry lookups
-  const NavBar = getComponentFromRegistry('NavBar');
-  const WssNavBar = getComponentFromRegistry('WssNavBar');
-  const AlertBanner = getComponentFromRegistry('AlertBanner');
-
-  // 2. Destructure props
-  const {
-    pages = [], caseTypes = [], showAppName, children = [],
-    getPConnect, httpMessages = [], pageMessages = [],
-    portalTemplate, portalName, portalLogo, navDisplayOptions,
-  } = props;
-
-  // 3. State + PConnect setup
-  const [open, setOpen] = useState(true);
-  const pConn = getPConnect();
-  const envInfo = PCore.getEnvironmentInfo();
-  const userName = envInfo.getOperatorName() || '';
-  const currentUserInitials = Utils.getInitials(userName);
-  const appNameToDisplay = showAppName ? envInfo.getApplicationLabel() : '';
-  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-  const [iconURL, setIconURL] = useState('');
-
-  // 4. Messages/banners
-  const messages = [...httpMessages, ...pageMessages];
-  const hasBanner = messages.length > 0;
-
-  // 5. useEffect: load portal logo async
-  // 6. useEffect: fetch case types from data page
-  // 7. useEffect: set pyPortalTemplate for WSS
-
-  // 8. Build nav links from pages
-  const links = pages.map(page => ({
-    text: localizedVal(page.pyLabel, '', ''),
-    onClick: () => !page.pyURLContent
-      ? pConn.getActionsApi().showPage(page.pyRuleName, page.pyClassName)
-      : window.open(page.pyURLContent, '_blank'),
-  }));
-
-  // 9. Render: WSS portal vs standard portal
-  if (portalTemplate === 'wss') {
-    return (
-      <div id="AppShell">
-        <WssNavBar portalName={portalName} imageSrc={iconURL} navLinks={links}
-          operator={{ name: userName, currentUserInitials }} navDisplayOptions={navDisplayOptions} />
-        <div>{hasBanner && <AlertBanner messages={messages} />}{children}</div>
-      </div>
-    );
-  }
-  return (
-    <NavContext.Provider value={{ open, setOpen }}>
-      <div id="AppShell" style={{ display: 'flex' }}>
-        <NavBar getPConnect={getPConnect} pConn={pConn}
-          appName={appNameToDisplay} pages={pages} caseTypes={caseTypes} />
-        <div>{hasBanner && <AlertBanner messages={messages} />}{children}</div>
-      </div>
-    </NavContext.Provider>
-  );
-}
-```
+- **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.
+- 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 `<AlertBanner>` DSE component above the main content.
+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 `portalLogoUrl` state.
-3. Pass `portalLogoUrl` to the nav bar as the `logo` prop.
+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` prop.
-- Render operator avatar (initials) in the nav bar via the `operatorInfo` prop.
+- 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:
-
-```typescript
-useEffect(() => {
-  // @ts-expect-error - environmentInfoObject may not be in typedefs
-  const caseTypesDP = PCore.getEnvironmentInfo().environmentInfoObject?.pxApplication?.pyCaseTypesAvailableToCreateDP;
-  if (caseTypesDP) {
-    const portalID = pConn.getValue('.pyOwner', '');
-    PCore.getDataPageUtils()
-      .getPageDataAsync(caseTypesDP, pConn.getContextName(), { PortalName: portalID })
-      .then((response) => {
-        if (response?.pyCaseTypesAvailableToCreate) {
-          pConn.replaceState('.pyCaseTypesAvailableToCreate', response.pyCaseTypesAvailableToCreate, {
-            skipDirtyValidation: true,
-          });
-        }
-      })
-      .catch(() => undefined);
-  }
-}, []);
-```
+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:
 
@@ -192,39 +104,24 @@ Key points:
 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 PROP, not from PConnect state.** Do NOT shadow the `caseTypes` prop with `useState`. Pass the prop directly to NavBar:
->
-> ```typescript
-> const { caseTypes = [] } = props;  // direct from props, NO useState
-> <NavBar caseTypes={caseTypes} />   // pass the prop through
-> ```
+> ⚠️ **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 use `useState(caseTypes)`, NavBar will receive an empty array because the React state is never updated by `replaceState`.
+> If you store `caseTypes` in local state, NavBar will receive an empty array because the local state is never updated by `replaceState`.
 
-### NavContext
+### Navigation Store Context
 
-- Wrap children in `<NavContext.Provider value={{ open, setOpen }}>`.
+- Wrap children in the navigation store context providing `{ open, setOpen }`.
 
 ### Render Structure
 
-```
-<NavContext.Provider value={{ open, setOpen }}>
-  <div id="AppShell" style={{ display: 'flex' }}>
-    <NavBar caseTypes={caseTypes} ... />
-    <main style={{ flexGrow: 1, height: '100vh', overflow: 'auto', margin: '0 1rem' }}>
-      <AlertBanner (if messages) />
-      {children}
-    </main>
-  </div>
-</NavContext.Provider>
-```
-
-> ⚠️ The `<main>` element MUST have:
+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 (matches reference's `theme.spacing(2)` = 16px)
+> - `margin: 0 1rem` — horizontal spacing between NavBar and content (approximately 16px)
 
 ## Visual Specifications
 
@@ -238,17 +135,17 @@ Key points:
 ## 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` prop.
+- 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` DSE component — standard portal navigation
+- `NavBar` component — standard portal navigation (from the project's component registry)
 - `WssNavBar` template component — WSS portal navigation (see `WssNavBar.md`)
-- `AlertBanner` DSE component — message display
-- `NavContext` from `../../context/nav-context`
+- `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
 
@@ -256,18 +153,8 @@ Key points:
 
 **UI control type:** Application shell layout — fixed nav + scrollable content area.
 
-Listed design systems are examples only.
-
-| Design System      | Nav Bar                  | Alert Banner         | Shell Layout                                  |
-| ------------------ | ------------------------ | -------------------- | --------------------------------------------- |
-| Default (CSS only) | `<header>` + custom nav  | `<div role='alert'>` | CSS flexbox column                            |
-| MUI                | `<AppBar>` + `<Toolbar>` | `<Alert>`            | `<Box display='flex' flexDirection='column'>` |
-| Ant Design         | `<Layout.Header>`        | `<Alert>`            | `<Layout>`                                    |
-| Chakra UI          | `<Box as='header'>`      | `<Alert>`            | `<Flex direction='column'>`                   |
-| Shadcn/ui          | Custom header            | `<Alert>`            | Tailwind `flex flex-col h-screen`             |
-
-When implementing in a specific design system:
+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 must remain — the nav bar component differs for each
-- Logo URL must be loaded asynchronously from `PCore.getAssetLoader()`
-- `NavContext.Provider` must wrap children so descendant nav-aware components can access links
+- 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