@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.claude/skills/run-and-verify.md

@@ -0,0 +1,68 @@
+# Skill: Run and Verify
+
+Build the application, run the dev server, and verify changes work correctly.
+
+---
+
+## Build Verification
+
+### If inside the pega-sdk monorepo:
+
+```bash
+# Full build (all packages + samples)
+cd /path/to/pega-sdk
+npm run build
+
+# Force rebuild sdk-react (if you modified it)
+npx nx run sdk-react:build --skip-nx-cache
+```
+
+### If standalone repo:
+
+```bash
+npm run build
+```
+
+### What to check:
+- Zero TypeScript errors
+- Zero build warnings related to missing imports
+- Output bundle is generated
+
+---
+
+## Dev Server
+
+```bash
+npm run dev
+# Opens on http://localhost:3500
+```
+
+### What to verify:
+1. App loads without console errors
+2. "Create Case" button appears after auth
+3. Clicking "Create Case" renders the form
+4. Field inputs accept keyboard input
+5. Tabbing between fields triggers blur (values persist)
+6. Validation errors appear when required fields are empty
+7. Form submission works (assignment completes)
+
+---
+
+## Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "X is not registered" console error | Component missing from `component-map.ts` | Add the import + map entry |
+| Field value doesn't persist after blur | `handleEvent` not called on blur | Add `onBlur` handler calling `handleEvent(actions, 'changeNblur', propName, value)` |
+| Read-only view shows nothing | Missing `displayMode` handling | Add the `DISPLAY_ONLY` / `STACKED_LARGE_VAL` checks |
+| TypeScript error on `getPConnect` | Wrong props interface | Extend `PConnFieldProps` or `PConnProps` from `@pega/sdk-react` |
+| Build fails on CSS import | Missing CSS loader config | Ensure Vite config handles `.css` imports |
+| "Cannot read property of undefined" on theme | Design system provider missing | Wrap app in the design system's ThemeProvider/Provider |
+
+---
+
+## Quick Lint Check
+
+```bash
+npx tsc --noEmit   # TypeScript only, no output
+```

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

@@ -0,0 +1,322 @@
+# Skill: Template Components
+
+Create or replace template components (layouts and page structures) in the react-sdk-reference application. Template components arrange child components into visual layouts (columns, tabs, forms, pages).
+
+---
+
+## Architecture Overview
+
+```
+src/components/template/<ComponentName>/
+├── <ComponentName>.tsx      # Component implementation
+├── index.tsx                # Re-export (if present)
+├── <ComponentName>.css      # Styles (CSS file, optional)
+├── utils.ts                 # Template-specific utilities (optional)
+└── config-ext.json          # Metadata (optional)
+```
+
+Some templates have nested sub-templates:
+
+```
+src/components/template/TwoColumn/
+├── TwoColumn/TwoColumn.tsx
+├── TwoColumnPage/TwoColumnPage.tsx
+└── TwoColumnTab/TwoColumnTab.tsx
+```
+
+---
+
+## Props Interface
+
+Template components extend `PConnProps`:
+
+```typescript
+import type { PConnProps } from '../../../types/PConnProps';
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect;
+}
+```
+
+Templates typically receive children through `getPConnect().getChildren()` rather than React `children` prop, though layout templates (TwoColumn, OneColumn) receive React children directly.
+
+---
+
+## Implementation Patterns
+
+### Layout Template (renders React children in grid)
+
+Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
+
+This pattern is design-system agnostic. The `// [DS GRID]` section must be replaced with your design system's grid or flex layout primitive — see the "Design System Adaptation" section below.
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+// Import your design system layout primitive here:
+// e.g. import { Grid } from 'antd';
+// e.g. import { SimpleGrid } from '@chakra-ui/react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface TwoColumnProps extends PConnProps {
+  templateCol?: string; // e.g. '1fr 1fr', '2fr 1fr'
+}
+
+export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
+  const { children, templateCol = '1fr 1fr' } = props;
+  const childrenToRender = children as ReactElement[];
+
+  // Parse templateCol into column width ratios
+  // Strip unit suffixes, split on whitespace, convert to numbers
+  const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
+  const totalCols = colArray.reduce((v, itm) => itm + v, 0);
+  // colArray[0] / totalCols = left column fraction
+  // colArray[1] / totalCols = right column fraction
+
+  // [DS GRID] — render two children in a responsive grid using the computed ratios
+  // On mobile (narrow viewport): both columns should stack to full width
+  // On desktop: apply the computed left/right ratio
+  return (
+    <YourDesignSystemGrid>
+      <YourDesignSystemColumn ratio={colArray[0] / totalCols}>
+        {childrenToRender[0]}
+      </YourDesignSystemColumn>
+      <YourDesignSystemColumn ratio={colArray[1] / totalCols}>
+        {childrenToRender[1]}
+      </YourDesignSystemColumn>
+    </YourDesignSystemGrid>
+  );
+}
+```
+
+---
+
+## 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.
+
+**1. Check the component-specific skill file** — `.claude/skills/template-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
+
+**2. If the chosen design system is not listed** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
+
+**3. Discover the API from installed packages** — confirm layout component names and props from `.d.ts` before writing JSX:
+```bash
+find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Grid\|Columns\|Flex" | head -5
+grep -A 30 "interface.*Props" <path-to-file>
+```
+
+**4. Column ratio mapping** — the `templateCol` prop (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
+
+| `templateCol` | Fraction | MUI 12-col | 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 props or a CSS media query.
+
+### Form Template (renders children via PConnect bridge)
+
+Used for: DefaultForm, HierarchicalForm
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+import connectToState from '../../helpers/state-utils';
+import type { PConnProps } from '../../../types/PConnProps';
+
+interface DefaultFormProps extends PConnProps {
+  NumCols: string;
+  instructions: string;
+}
+
+export default function DefaultForm(props: DefaultFormProps) {
+  const { getPConnect, NumCols = '1' } = props;
+
+  // Get children from the first region
+  const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
+
+  // Wrap each child in a PConnect component
+  const dfChildren = arChildren?.map((kid, i) => (
+    createElement(createPConnectComponent(), { ...kid, key: `child-${i}` })
+  ));
+
+  return <div className={`form-${NumCols}-col`}>{dfChildren}</div>;
+}
+```
+
+### Page Template (renders regions from PConnect children)
+
+Used for: CaseView, DefaultPage, ObjectPage
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+import type { PConnProps } from '../../../types/PConnProps';
+
+interface CaseViewProps extends PConnProps {
+  header?: string;
+  subheader?: string;
+}
+
+export default function CaseView(props: CaseViewProps) {
+  const { getPConnect, header } = props;
+  const pConn = getPConnect();
+  const children = pConn.getChildren();
+
+  return (
+    <div>
+      <h2>{header}</h2>
+      {children.map((child, index) => (
+        createElement(createPConnectComponent(), { ...child, key: `region-${index}` })
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Rendering Children
+
+Templates use two patterns to render child components:
+
+### 1. React children (layout templates)
+
+```typescript
+// TwoColumn, OneColumn, etc. receive children as React props
+const { children } = props;
+const childrenToRender = children as ReactElement[];
+```
+
+### 2. PConnect children (form/page templates)
+
+```typescript
+import { createElement } from 'react';
+import createPConnectComponent from '../../helpers/react_pconnect';
+
+// Get child PConnect objects
+const children = getPConnect().getChildren();
+
+// Render each child through the PConnect bridge
+children.map((child, i) =>
+  createElement(createPConnectComponent(), { ...child, key: `child-${i}` }),
+);
+```
+
+### 3. State-connected children (DefaultForm pattern)
+
+```typescript
+import connectToState from '../../helpers/state-utils';
+import createPConnectComponent from '../../helpers/react_pconnect';
+
+// connectToState HOC subscribes to Redux store for visibility/props
+const Child = connectToState(mapStateToProps)((props) => {
+  const { key, visibility, ...rest } = props;
+  return createElement(createPConnectComponent(), { ...rest, key, visibility });
+});
+```
+
+---
+
+## Helper Utilities
+
+### `createPConnectComponent` (from `../../helpers/react_pconnect`)
+
+Factory that returns the PConnect bridge component. Used to render child PConnect objects:
+
+```typescript
+import createPConnectComponent from '../../helpers/react_pconnect';
+createElement(createPConnectComponent(), childPConnectProps);
+```
+
+### `connectToState` (from `../../helpers/state-utils`)
+
+HOC that connects a component to the Redux store for visibility and dynamic props:
+
+```typescript
+import connectToState from '../../helpers/state-utils';
+const ConnectedChild = connectToState(mapStateToProps)(ChildComponent);
+```
+
+### `getInstructions` (from `../../helpers/template-utils`)
+
+Extracts instruction text for forms:
+
+```typescript
+import { getInstructions } from '../../helpers/template-utils';
+const instructions = getInstructions(getPConnect(), props.instructions);
+```
+
+---
+
+## Registration
+
+Register templates in `src/components/component-map.ts`:
+
+```typescript
+import MyTemplate from './template/MyTemplate';
+
+// In getSampleComponentMap():
+{
+  ...sdkComponents,
+  MyTemplate,  // Key must match Pega component name
+}
+```
+
+For nested templates (e.g., TwoColumn/TwoColumnPage/TwoColumnTab), register each separately:
+
+```typescript
+import TwoColumn from './template/TwoColumn/TwoColumn/TwoColumn';
+import TwoColumnPage from './template/TwoColumn/TwoColumnPage';
+import TwoColumnTab from './template/TwoColumn/TwoColumnTab';
+
+{
+  TwoColumn,
+  TwoColumnPage,
+  TwoColumnTab,
+}
+```
+
+---
+
+## 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** — `export default function TemplateName`.
+2. **Children from PConnect** — Use `getPConnect().getChildren()` to access child regions.
+3. **createElement pattern** — Use `createElement(createPConnectComponent(), childProps)` to render PConnect children.
+4. **CSS files** — Template-specific styles go in `<TemplateName>.css` alongside the component.
+5. **Responsive** — Use MUI Grid with `xs: 12` for mobile and `md: <size>` for desktop breakpoints.
+6. **templateCol** — Layout templates often receive a `templateCol` prop (e.g., `"1fr 1fr"`, `"2fr 1fr"`) to control column ratios.

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

@@ -0,0 +1,144 @@
+# 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 React context (`DataReferenceAdvancedSearchContext`).
+
+## Pega Metadata
+
+- **Registration key:** `AdvancedSearch` (in `component-map.ts`)
+- **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 |
+
+## 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 `fields` array.
+
+### 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.
+- Deduplication is applied per-group in order — earlier groups take precedence.
+
+### Context (`DataReferenceAdvancedSearchContext`)
+
+Provides shared config to `SearchGroups`:
+```tsx
+<DataReferenceAdvancedSearchContext.Provider value={{ dataPageName, parameters, getPConnect }}>
+  {searchGroups.map((group) => <SearchGroups key={group.label} group={group} />)}
+</DataReferenceAdvancedSearchContext.Provider>
+```
+
+### Render Structure
+
+```
+<div className="psdk-advanced-search">
+  {searchGroups.map(group => (
+    <SearchGroups group={group} key={group.label} />
+  ))}
+</div>
+```
+
+---
+
+## Sub-Component: SearchGroups
+
+Renders a single search group section: a heading + a list of editable search fields.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `group` | `object` | `{ label: string, fields: array }` |
+
+### 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.
+
+### 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>
+```
+
+## Visual Specifications
+
+### AdvancedSearch Container
+
+| Element | Description |
+|---------|-------------|
+| Outer container | Vertical stack of search group sections |
+
+### SearchGroups Section
+
+| Element | Description |
+|---------|-------------|
+| Group heading | `<h4>` with group label |
+| Field rows | Each field rendered as a form control |
+
+**CSS-only implementation notes:**
+- 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`.
+
+## 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.
+
+## Dependencies
+
+- `DataReferenceAdvancedSearchContext` — shared context (defined in `./context` or inline)
+- `PConnectComponent` from `@pega/sdk-react` — renders created field components
+- `getRawMetadata()` — for search group config extraction
+
+## 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)`

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

@@ -0,0 +1,122 @@
+# 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.
+
+---
+
+## 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 |
+
+## 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
+
+1. On mount, fetch case types via `PCore.getDataPageUtils().getPageDataAsync('D_pyPortalTypeList', 'root', {})`.
+2. Store result in `caseTypes` state (overrides the prop default).
+3. Pass `caseTypes` to the nav bar.
+
+### NavContext
+
+- Wrap children in `<NavContext.Provider value={{ links, caseTypes }}>`.
+- `links` is derived from `pages` prop: `pages.map(p => ({ label: p.pyLabel, url: p.linkUrl, id: p.name }))`.
+
+### Render Structure
+
+```
+<div className="psdk-app-shell">
+  <NavBar | WssNavBar (with logo, caseTypes, operatorInfo, links) />
+  <AlertBanner (if messages) />
+  <main className="psdk-app-shell-content">
+    <NavContext.Provider>
+      {children}
+    </NavContext.Provider>
+  </main>
+</div>
+```
+
+## 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