@pega/sdk 0.0.4 → 0.0.5

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

@@ -0,0 +1,273 @@
+# 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.
+
+> **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` prop.** Without it, `pConn.resolveConfigProps()` throws `TypeError: Cannot read properties of undefined`. ALWAYS pass `pConn={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. `NavContext.Provider` 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
+> - [ ] WSS vs standard portal detection
+> - [ ] AlertBanner with combined messages
+> - [ ] Operator info from `PCore.getEnvironmentInfo()`
+
+---
+
+## 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.
+
+## Pega Metadata
+
+- **Registration key:** `AppShell` (in `component-map.ts`)
+- **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>
+  );
+}
+```
+
+## 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 `<AlertBanner>` DSE 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.
+
+### Operator Avatar
+
+- Read `displayName` from `getPConnect().getValue('.pyUserName')` or the `displayName` prop.
+- Render operator avatar (initials) in the nav bar via the `operatorInfo` prop.
+
+### 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);
+  }
+}, []);
+```
+
+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 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
+> ```
+>
+> If you use `useState(caseTypes)`, NavBar will receive an empty array because the React state is never updated by `replaceState`.
+
+### NavContext
+
+- Wrap children in `<NavContext.Provider value={{ 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:
+>
+> - `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)
+
+## 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` prop.
+- `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
+- `WssNavBar` template component — WSS portal navigation (see `WssNavBar.md`)
+- `AlertBanner` DSE component — message display
+- `NavContext` from `../../context/nav-context`
+- `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.
+
+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:
+
+- 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

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/template-skills/BannerPage.md

@@ -29,6 +29,45 @@ A thin template wrapper that delegates entirely to the `Banner` DSE component. T
 | `backgroundColor` | `string`      | No       | Background color for the hero. Default `''`                                                    |
 | `tintImage`       | `boolean`     | No       | Whether to tint the background image. Default `false`                                          |
 
+## Component Skeleton
+
+Simplest template — pure pass-through to `Banner` DSE component.
+
+```typescript
+import { Children, type PropsWithChildren, useMemo } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface BannerPageProps extends PConnProps {
+  layout?: string;
+  heading?: string;
+  message?: string;
+  imageTheme?: string;
+  backgroundImage?: string;
+  backgroundColor?: string;
+  tintImage?: boolean;
+}
+
+export default function BannerPage(props: PropsWithChildren<BannerPageProps>) {
+  const Banner = getComponentFromRegistry('Banner');
+  const {
+    children, layout = 'two-column', heading = '', message = '',
+    imageTheme = 'light', backgroundImage = '', backgroundColor = '', tintImage = false,
+  } = props;
+
+  const childArray = useMemo(() => Children.toArray(children), [children]);
+
+  return (
+    <Banner
+      variant={layout}
+      a={childArray[0]}
+      b={childArray[1]}
+      banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}
+    />
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. Retrieve `Banner` from the component registry via `getComponentFromRegistry('Banner')`.

package/templates/react-sdk-reference/{.github → .ai-common}/skills/template-skills/CaseSummary.md

@@ -6,6 +6,28 @@ Case summary template. Renders a summary panel with primary and secondary case f
 
 ---
 
+> ⚠️ **CRITICAL — Children extraction is MANDATORY**
+>
+> The `arPrimaryFields` and `arSecondaryFields` props are almost always EMPTY at runtime. The Pega engine passes field data as **React children** (regions named "primary fields" and "secondary fields"), not as pre-computed array props.
+>
+> You MUST include the children-extraction block:
+>
+> ```typescript
+> if (arPrimaryFields.length === 0 && arSecondaryFields.length === 0) {
+>   for (const child of childArr) {
+>     const childPConn = child.props.getPConnect();
+>     const childPConnData = childPConn.resolveConfigProps(childPConn.getRawMetadata());
+>     if (childPConnData.name.toLowerCase() === 'primary fields') {
+>       arPrimaryFields = childPConnData.children;
+>     } else if (childPConnData.name.toLowerCase() === 'secondary fields') {
+>       arSecondaryFields = childPConnData.children;
+>     }
+>   }
+> }
+> ```
+>
+> Without this, the summary will render completely empty.
+
 ## Component Purpose
 
 Displays a case's key summary data in a structured summary panel. Primary fields are shown prominently; secondary fields are shown with labels. Data is sourced either directly from props or by extracting child regions. All field values are localized before display.
@@ -25,6 +47,63 @@ Displays a case's key summary data in a structured summary panel. Primary fields
 | `arSecondaryFields` | `array`       | No       | Array of secondary field objects (direct prop)          |
 | `getPConnect`       | `function`    | Yes      | PConnect getter                                         |
 
+## Component Skeleton
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface CaseSummaryProps extends PConnProps {
+  arPrimaryFields: any[];
+  arSecondaryFields: any[];
+}
+
+export default function CaseSummary(props: PropsWithChildren<CaseSummaryProps>) {
+  const CaseSummaryFields = getComponentFromRegistry('CaseSummaryFields');
+  const { children } = props;
+  let { arPrimaryFields = [], arSecondaryFields = [] } = props;
+
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+  const localeCategory = 'ModalContainer';
+
+  // 1. Helper: create component from metadata and return { value: createdComponent }
+  function prepareComponentInCaseSummary(pConnectMeta, getPConnect) { /* ... */ }
+
+  // 2. Helper: convert children to summary data array
+  function prepareCaseSummaryData(summaryFieldChildren) { /* ... */ }
+
+  // 3. If direct props empty, extract from children regions
+  if (arPrimaryFields.length === 0 && arSecondaryFields.length === 0) {
+    for (const child of children as ReactElement[]) {
+      const childPConn = (child as ReactElement).props.getPConnect();
+      const childPConnData = childPConn.resolveConfigProps(childPConn.getRawMetadata());
+      if (childPConnData.name.toLowerCase() === 'primary fields') {
+        arPrimaryFields = childPConnData.children;
+        arPrimaryFields.forEach(field => {
+          if (field.config?.value && typeof field.config?.value === 'string')
+            field.config.value = localizedVal(field.config.value, localeCategory);
+        });
+      } else if (childPConnData.name.toLowerCase() === 'secondary fields') {
+        const secondarySummaryFields = prepareCaseSummaryData(childPConn);
+        arSecondaryFields = childPConnData.children;
+        arSecondaryFields.forEach((field, index) => {
+          field.config.displayLabel = secondarySummaryFields[index]?.value?.props?.label;
+        });
+      }
+    }
+  }
+
+  // 4. Render
+  return (
+    <div id="CaseSummary">
+      <CaseSummaryFields theFields={arPrimaryFields} />
+      <CaseSummaryFields theFields={arSecondaryFields} />
+    </div>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### Field Sourcing