@pega/sdk 0.0.1 → 0.0.3

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

@@ -0,0 +1,127 @@
+# Skill: SimpleTable
+
+Simple table template. Routes to FieldGroupTemplate, ListView (read-only), or the manual editable table based on configuration. Also covers `SimpleTableManual`, `SimpleTableSelect`, and `SimpleTableSelectReadonly` sub-variants.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Entry-point template for embedded table data in a form or detail view. Routes to the appropriate sub-component based on `multiRecordDisplayAs`, `fieldMetadata.dataRetrievalType`, and `readOnly`/`displayMode` flags. Sub-variants handle selection, read-only display, and full manual editing.
+
+## Pega Metadata
+
+- **Registration keys:** `SimpleTable`, `SimpleTableManual`, `SimpleTableSelect`, `SimpleTableSelectReadonly` (all in `component-map.ts`)
+- **Category:** Data display / Form template — embedded table
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `multiRecordDisplayAs` | `string` | No | `'fieldGroup'` delegates to FieldGroupTemplate; else table |
+| `fieldMetadata` | `object` | No | Field-level metadata including `dataRetrievalType` |
+| `referenceList` | `string` | No | Property path to the reference list |
+| `displayAs` | `string` | No | For SimpleTableSelectReadonly: `'readonlyMulti'`, `'combobox'`, `'checkboxgroup'` routing |
+| `selectionMode` | `string` | No | `'single'` or `'multi'` (for SimpleTableSelect) |
+| `displayMode` | `string` | No | `'DISPLAY_ONLY'` triggers read-only sub-variant |
+| `readOnly` | `boolean` | No | Alternative read-only flag |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### SimpleTable — Routing Logic
+
+```
+if multiRecordDisplayAs === 'fieldGroup':
+  → render FieldGroupTemplate
+else if fieldMetadata.dataRetrievalType === 'refer':
+  → render ListView (read-only, bInForm: true)
+else:
+  → render SimpleTableManual (editable table)
+```
+
+### SimpleTableManual — Full Editable Table
+
+Full MUI table with add/delete rows, inline editing, sort, filter, and column customization (~600+ lines).
+
+Key behaviors:
+1. **Row data source:** `referenceList` property path via `pConn.getValue(referenceList + '.pxResults')`.
+2. **Add row:** `pConn.getListActions().insert({})`.
+3. **Delete row:** `pConn.getListActions().deleteEntry(index)`.
+4. **Inline field editing:** Each cell renders the field's registered edit component via `buildView(pConn, rowIndex, colFieldName)`.
+5. **Sort:** Client-side sort on loaded data.
+6. **Column customization:** Visibility toggles per column via a settings popover.
+7. **Filter dialog:** Same filter pattern as ListView.
+
+### SimpleTableSelect — Selection Mode
+
+Wraps `ListView` with additional selection configuration:
+- Passes `additionalTableConfig` with `selectionMode: 'single'` or `'multi'`.
+- On selection: calls `pConn.getListActions().setSelectedRow(selectedData)`.
+- Used when `DataReference` routes to table-based selection.
+
+### SimpleTableSelectReadonly — Read-Only with Modal
+
+1. Renders a link/chip showing the current selection count.
+2. On click: opens a `<Dialog>` containing a `<SimpleTableManual>` in read-only mode.
+3. Props: same as `SimpleTableManual` but all fields locked (no add/delete/edit).
+
+## Visual Specifications
+
+### SimpleTableManual
+
+| Element | Description |
+|---------|-------------|
+| Toolbar | Column settings button, filter button, optional search |
+| Table | Full-width, alternating row colors |
+| Add row | `"+ Add row"` button below the table |
+| Delete row | Trash icon per row (rightmost column) |
+| Column settings | Popover with checkboxes for visibility toggles |
+
+**CSS-only implementation notes:**
+- Table: `width: 100%; border-collapse: collapse`.
+- Add row button: `margin-top: 0.5rem; text-align: left`.
+- Delete cell: `width: 40px; text-align: center`.
+- Read-only mode: hide add/delete controls; cells show plain text.
+
+### SimpleTableSelectReadonly
+
+| Element | Description |
+|---------|-------------|
+| Trigger | Link or chip showing selection count |
+| Modal | Full-screen or large dialog with SimpleTableManual |
+| Modal close | `X` button in modal header |
+
+## Edge Cases & Special Logic
+
+- `multiRecordDisplayAs === 'fieldGroup'` — completely bypasses table; delegates to `FieldGroupTemplate`.
+- `dataRetrievalType === 'refer'` — data comes from a reference list, not a full data page; use `ListView` in read-only mode.
+- `SimpleTableManual` with 600+ lines — break into sub-hooks if re-implementing.
+- Row keys must be unique — use composite keys from `compositeKeys` config if available.
+- Column customization state is local — not persisted across navigation.
+
+## Dependencies
+
+- `FieldGroupTemplate` (for `multiRecordDisplayAs === 'fieldGroup'` routing)
+- `ListView` (for `dataRetrievalType === 'refer'` routing)
+- `buildView` from `../../helpers/field-group-utils` (for inline cell rendering in SimpleTableManual)
+- MUI: `<Table>`, `<Dialog>`, `<Popover>`, `<IconButton>`, `<Button>`, `<Checkbox>`
+
+## Design System Mapping
+
+**UI control type:** Embedded data table with routing to field group, read-only list, or fully editable table.
+
+Listed design systems are examples only.
+
+| Sub-variant | Default (CSS only) | MUI |
+|---|---|---|
+| SimpleTableManual | `<table>` + custom controls | MUI `<Table>` |
+| SimpleTableSelect | Custom table + radio/checkbox | `<ListView>` wrapper |
+| SimpleTableSelectReadonly | Link + `<dialog>` | Chip + `<Dialog>` |
+
+When implementing in a specific design system:
+- Always check `multiRecordDisplayAs === 'fieldGroup'` first — this bypasses the table entirely
+- `SimpleTableManual` add/delete row controls must be hidden when `readOnly === true` or `displayMode === 'DISPLAY_ONLY'`
+- `SimpleTableSelect` uses the same `ListView` but adds selection callbacks

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

@@ -0,0 +1,103 @@
+# Skill: SingleReferenceReadOnly
+
+Single reference read-only template. Renders a read-only reference field as a semantic link for editable field types, or as a plain label otherwise.
+
+> **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 single data reference field in read-only mode. For fields that were displayed as editable selection controls (autocomplete, table select, dropdown), renders a `SemanticLink` component so the reference value is clickable/navigable. For other display types, renders a plain read-only label.
+
+## Pega Metadata
+
+- **Registration key:** `SingleReferenceReadOnly` (in `component-map.ts`)
+- **Category:** Display template — read-only reference
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Field label |
+| `displayAs` | `string` | Yes | The edit-mode display type this field was configured with |
+| `value` | `string` | No | Current field value (display text) |
+| `caseClass` | `string` | No | Class identifier for the referenced case |
+| `text` | `string` | No | Display text for the semantic link |
+| `caseID` | `string` | No | Case ID for the semantic link |
+| `contextPage` | `string` | No | Context page identifier |
+| `resourceParams` | `object` | No | Parameters for the referenced resource |
+| `resourcePayload` | `object` | No | Payload for resource navigation |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Editable Component Check
+
+```
+editableComponents = ['AutoComplete', 'SimpleTableSelect', 'Dropdown']
+```
+
+If `displayAs` is in `editableComponents`:
+1. Build config with: `caseClass`, `text`, `caseID`, `contextPage`, `resourceParams`, `resourcePayload`.
+2. Create: `createComponent({ type: 'SemanticLink', config: { ...builtConfig } })`.
+3. Render the created `SemanticLink` component.
+
+Else:
+- Render a plain read-only display using `<FormControl variant='standard'>` + `<FormLabel>` + value text.
+
+### Layout
+
+For both variants, wrap with:
+```tsx
+<FormControl variant='standard' sx={{ flexDirection: 'row' }}>
+  <FormLabel sx={{ marginRight: '2rem' }}>{label}</FormLabel>
+  {semanLinkOrValue}
+</FormControl>
+```
+
+## Visual Specifications
+
+| Variant | Layout |
+|---------|--------|
+| SemanticLink | Label (left) + clickable link (right) |
+| Plain read-only | Label (left) + plain text (right) |
+
+**CSS-only implementation notes:**
+- Wrapper: `display: flex; flex-direction: row; align-items: baseline; gap: 1rem`.
+- Label: `font-size: 0.875rem; color: var(--secondary-text-color); min-width: 120px`.
+- Semantic link: `color: var(--link-color); text-decoration: underline; cursor: pointer`.
+- Plain value: `font-size: 0.875rem; color: var(--primary-text-color)`.
+
+## Edge Cases & Special Logic
+
+- `displayAs` check is case-sensitive — values are `'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'` (exact match).
+- `createComponent` returns a PConnect config — render via `createElement(PConnectComponent, { ...createdConfig })`.
+- If `text` is empty/undefined, the semantic link shows the `caseID` as fallback text.
+- `SemanticLink` navigation requires `caseClass` and `caseID` — if either is missing, fall back to plain read-only display.
+
+## Dependencies
+
+- `PConnectComponent` from `@pega/sdk-react` — for rendering the `SemanticLink`
+- `getPConnect().createComponent()` — creates the SemanticLink component config
+- MUI: `<FormControl>`, `<FormLabel>`
+
+## Design System Mapping
+
+**UI control type:** Read-only reference field — semantic link for navigable references, plain label otherwise.
+
+Listed design systems are examples only.
+
+| Design System | Semantic Link | Plain Read-Only |
+|---|---|---|
+| Default (CSS only) | `<a>` with case navigation | `<span>` |
+| MUI | `SemanticLink` rendered via `createComponent` | `<Typography>` |
+| Ant Design | `<Typography.Link>` | `<Typography.Text>` |
+| Chakra UI | `<Link>` | `<Text>` |
+| Shadcn/ui | Custom link | `<span>` |
+
+When implementing in a specific design system:
+- The `editableComponents` list (`'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'`) controls semantic link vs plain display
+- `SemanticLink` must be rendered via `createComponent` — do not implement the link logic directly in this component
+- Horizontal label + value layout (row direction) is required

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

@@ -0,0 +1,79 @@
+# Skill: SubTabs
+
+Sub-tabs navigation template. Renders a tab container for case view sections using shared tab utilities with deferred content loading.
+
+> **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 horizontal tab bar for navigating between case view sections. Uses shared `tabUtils` for tab state management (visible tabs, transient tabs, tab click). Tab content is deferred — only the active tab loads content. No section heading.
+
+## Pega Metadata
+
+- **Registration key:** `SubTabs` (in `component-map.ts`)
+- **Category:** Navigation template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | `children[0]` is the deferred-loaded tabs container |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+1. **Extract deferred tabs:** `deferLoadedTabs = Children.toArray(children)[0]`.
+2. **State:** `currentTabId` (string, default `'0'`), `tabItems` (array).
+3. **Compute visible tabs:** `getVisibleTabs(deferLoadedTabs, 'tabsSubs')` in `useEffect([deferLoadedTabs])` → `availableTabs`.
+4. **Transient tabs:** `useEffect([currentTabId])` → `setTabItems(getTransientTabs(availableTabs, currentTabId, tabItems))`.
+5. **Tab click:** `tabClick(index, availableTabs, currentTabId, setCurrentTabId, tabItems)` from `tabUtils`.
+6. **Render:**
+   - `<TabContext value={currentTabId}>`
+   - `<Tabs onChange={handleTabClick} value={currentTabId}>` — one `<Tab>` per `tabItems`
+   - One `<TabPanel>` per `tabItems` with `tab.content || ''`
+7. No section heading (unlike `DetailsSubTabs`).
+
+> **Difference from `DetailsSubTabs`:** SubTabs has no `label`/`showLabel` props and no `<h3>` heading. Uses `'tabsSubs'` identifier for `getVisibleTabs` (vs `'detailsSubTabs'`).
+
+## Visual Specifications
+
+Identical to `DetailsSubTabs` except no heading above the tab bar.
+
+**CSS-only implementation notes:**
+- Tab bar: `display: flex; border-bottom: 2px solid var(--divider)`.
+- Each tab: `padding: 8px 16px; cursor: pointer; border-bottom: 2px solid transparent`.
+- Active tab: `border-bottom-color: var(--app-primary-color); font-weight: 600`.
+- Tab panel: `padding: 16px 0`.
+
+## Edge Cases & Special Logic
+
+See `DetailsSubTabs.md` for shared edge cases. Additional:
+- `tabUtils` identifier string `'tabsSubs'` must match exactly — it is used internally by `getVisibleTabs` for scoping.
+
+## Dependencies
+
+- `getTransientTabs`, `getVisibleTabs`, `tabClick` from `./tabUtils`
+- `TabContext`, `TabPanel` from `@mui/lab`
+- `Tab`, `Tabs` from `@mui/material`
+
+## Design System Mapping
+
+**UI control type:** Tab navigation container — no heading, deferred content loading.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Custom tab bar with CSS underline indicator |
+| MUI | `<TabContext>` + `<Tabs>` + `<TabPanel>` from `@mui/lab` |
+| Ant Design | `<Tabs>` with `items` array |
+| Chakra UI | `<Tabs>` + `<TabList>` + `<TabPanels>` |
+| Shadcn/ui | `<Tabs>` + `<TabsList>` + `<TabsContent>` |
+
+When implementing in a specific design system:
+- Use `getVisibleTabs(tabs, 'tabsSubs')` — the identifier string must be `'tabsSubs'`
+- No heading above the tab bar (unlike `DetailsSubTabs`)
+- Deferred loading: content populates lazily via `getTransientTabs`

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

@@ -0,0 +1,131 @@
+# Skill: TwoColumn
+
+Two-column layout template that splits children into two responsive grid columns with configurable width ratios.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders two child components side by side in a responsive grid. Column widths are driven by the `templateCol` prop (e.g., `'1fr 1fr'`, `'2fr 1fr'`). On mobile (`xs`), both columns collapse to full width. Three closely related sub-variants share this same layout logic:
+
+- **`TwoColumn`** — core layout, used inside forms and views
+- **`TwoColumnPage`** — thin wrapper that delegates to `TwoColumn` via the component registry
+- **`TwoColumnTab`** — identical layout implementation used inside tab contexts
+
+## Pega Metadata
+
+| Variant | Registration Key |
+|---------|-----------------|
+| TwoColumn | `TwoColumn` |
+| TwoColumnPage | `TwoColumnPage` |
+| TwoColumnTab | `TwoColumnTab` |
+
+All three extend `PConnProps`. Children are received as React `children` (not via `getPConnect().getChildren()`).
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Exactly 2 children (left column, right column) |
+| `templateCol` | `string` | No | Column width ratio string, e.g., `'1fr 1fr'`, `'2fr 1fr'`. Default `'1fr 1fr'` |
+
+## Sub-Variants
+
+### TwoColumnPage
+
+Thin pass-through wrapper. Retrieves `TwoColumn` from the component registry and renders it with all props forwarded:
+
+```typescript
+const TwoColumn = getComponentFromRegistry('TwoColumn');
+return <TwoColumn {...props} />;
+```
+
+### TwoColumnTab
+
+Identical implementation to `TwoColumn` — same grid layout, same `templateCol` parsing, same column styles. Registered separately under `TwoColumnTab` key to support tab context rendering.
+
+## Behavioral Contract
+
+1. Accept exactly 2 children. If a different count is received, log an error (console only — still render).
+2. Parse `templateCol` to compute MUI Grid column sizes:
+   - Strip unit suffixes (e.g., `'fr'`) from each token using regex: `.replaceAll(/[a-z]+/g, '')`.
+   - Split on whitespace and convert to numbers.
+   - Compute `totalCols = sum(colArray)`.
+   - Compute `ratio = 12 / totalCols`.
+   - `aSize = ratio * colArray[0]`, `bSize = ratio * colArray[1]` (both clamped to MUI's 1–12 GridSize range).
+3. Render a Grid container with `spacing={1}`.
+4. Render `children[0]` in the left column at `size={{ xs: 12, md: aSize }}`.
+5. Render `children[1]` in the right column at `size={{ xs: 12, md: bSize }}`.
+6. Apply `colStyles` class to each column: `display: grid; gap: 1rem; alignContent: baseline`.
+
+## Visual Specifications
+
+Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
+
+### Column Style
+
+| Property | Value |
+|----------|-------|
+| Display | grid |
+| Gap | 1rem |
+| Align content | baseline (children stack top-aligned) |
+
+### Grid Spacing
+
+| Property | Value |
+|----------|-------|
+| Container spacing | 1 (≈ 8px between columns) |
+
+### Responsive Behavior
+
+| Breakpoint | Column A | Column B |
+|-----------|----------|----------|
+| xs (mobile) | 12/12 (full width) | 12/12 (full width, stacks below) |
+| md+ (desktop) | `aSize`/12 | `bSize`/12 |
+
+**Column ratio examples:**
+
+| `templateCol` | Column A | Column B |
+|--------------|----------|----------|
+| `'1fr 1fr'` | 6/12 (50%) | 6/12 (50%) |
+| `'2fr 1fr'` | 8/12 (67%) | 4/12 (33%) |
+| `'1fr 2fr'` | 4/12 (33%) | 8/12 (67%) |
+| `'3fr 1fr'` | 9/12 (75%) | 3/12 (25%) |
+
+**CSS-only implementation notes:**
+- Column container: `display: grid; gap: 1rem; align-content: start`.
+- Outer grid: `display: grid; grid-template-columns: <aFraction>fr <bFraction>fr; gap: 8px`.
+- Mobile: `grid-template-columns: 1fr` (single column stack).
+- Each column has `display: grid; gap: 1rem; align-content: baseline` for internal stacking.
+
+## Edge Cases & Special Logic
+
+- Default `templateCol` is `'1fr 1fr'` (equal split) when not provided.
+- The `templateCol` parsing is regex-based — any non-numeric suffix is stripped. If only numbers are provided (e.g., `'6 6'`), it still works.
+- `TwoColumnPage` uses `getComponentFromRegistry('TwoColumn')` — if the registry returns an override, that override is used instead of the default `TwoColumn` implementation.
+
+## Dependencies
+
+- `TwoColumnPage`: `getComponentFromRegistry` from `@pega/sdk-react` — to resolve the `TwoColumn` component at runtime
+- `TwoColumn` / `TwoColumnTab`: no special dependencies beyond layout
+
+## Design System Mapping
+
+**UI control type:** Responsive two-column grid layout.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS Grid with `grid-template-columns: <a>fr <b>fr; gap: 8px` |
+| MUI | `<Grid container spacing={1}><Grid size={{ xs: 12, md: N }}>` |
+| Ant Design | `<Row gutter={8}><Col xs={24} md={N * 2}>` (Ant uses 24-column grid) |
+| Chakra UI | `<SimpleGrid columns={{ base: 1, md: 2 }} spacing={2}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-1 md:grid-cols-[<a>fr_<b>fr] gap-2` |
+
+When implementing in a specific design system:
+- Parse `templateCol` using the same ratio algorithm (strip units, divide 12 by total)
+- Apply `align-content: baseline` so children within each column stack top-aligned
+- Collapse to single column on mobile breakpoint

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

@@ -0,0 +1,150 @@
+# Skill: WideNarrow
+
+Asymmetric two-column layout with a wide left column (~67%) and a narrow right column (~33%). Mirror of NarrowWide. Includes four sub-variants.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders two children side by side with the left column wider than the right. Typically used when the main content occupies the left and a utility/sidebar panel sits on the right. Four sub-variants:
+
+- **`WideNarrow`** — core CSS-based layout, accepts either `a`/`b` slot props or React `children[0]`/`children[1]`
+- **`WideNarrowPage`** — wrapper that passes React children as `a` and `b` slot props to `WideNarrow`
+- **`WideNarrowForm`** — simplified wrapper using only `children`
+- **`WideNarrowDetails`** — details read-only variant; sets children to DISPLAY_ONLY mode and supports highlighted data
+
+> This component is the mirror of `NarrowWide`. All behavioral and structural patterns are identical except column order and CSS class names. See the `NarrowWide` skill for detailed pattern descriptions.
+
+## Pega Metadata
+
+| Variant | Registration Key |
+|---------|-----------------|
+| WideNarrow | `WideNarrow` |
+| WideNarrowPage | `WideNarrowPage` |
+| WideNarrowForm | `WideNarrowForm` |
+| WideNarrowDetails | `WideNarrowDetails` |
+
+All extend `PConnProps`.
+
+## Props
+
+### WideNarrow
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | No | Two children — `[0]` → wide (left), `[1]` → narrow (right) |
+| `a` | `any` | No | Wide (left) column content |
+| `b` | `any` | No | Narrow (right) column content |
+| `title` | `string` | No | Optional title (not rendered) |
+| `cols` | `string` | No | Column template (not rendered) |
+| `icon` | `string` | No | Icon name (not rendered) |
+
+### WideNarrowPage
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Two children — `[0]` → wide slot, `[1]` → narrow slot |
+| `title` | `string` | Yes | Page title (passed to WideNarrow) |
+| `templateCol` | `string` | No | Column ratio (default `'1fr 1fr'`) |
+| `icon` | `string` | No | Icon name (strips `'pi pi-'` prefix) |
+
+### WideNarrowForm
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Two children rendered in wide/narrow slots |
+
+### WideNarrowDetails
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | No | Section label for FieldGroup |
+| `showLabel` | `boolean` | No | Whether to show the label. Default `true` |
+| `showHighlightedData` | `boolean` | No | Whether to render highlighted data fields. Default `false` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### WideNarrow
+
+1. If `children` is provided and has exactly 2 items: render `children[0]` in `.psdk-wide-column-column` and `children[1]` in `.psdk-narrow-column-column` (both wrapped in `.psdk-wide-narrow-column`).
+2. If `a` and `b` are provided: render `a` in the wide slot and `b` in the narrow slot.
+3. `children` takes priority over `a`/`b` when both are present.
+
+### WideNarrowPage
+
+1. Extract `childArray = Children.toArray(children)`.
+2. Retrieve `WideNarrow` from the component registry.
+3. Render `<WideNarrow a={childArray[0]} b={childArray[1]} title={title} cols={templateCol} icon={icon?.replace('pi pi-', '')} />`.
+
+### WideNarrowForm
+
+1. Render using `children` path — checks `children.length === 2`, renders wide/narrow CSS divs.
+
+### WideNarrowDetails
+
+1. Set `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `setInheritedProp('readOnly', true)`.
+2. Map `getPConnect().getChildren()` → `createElement(PConnectComponent, { ...configObject, key: index })`.
+3. If `showHighlightedData` is true, read `getRawMetadata().config.highlightedData`, set each field's `displayMode = 'STACKED_LARGE_VAL'`, mark `pyStatusWork` as `displayAsStatus=true`, and create components via `getPConnect().createComponent(field, '', 0, {})`.
+4. Wrap in `<FieldGroup name={theName}>` using `propsToUse.showLabel && propsToUse.label`.
+5. Layout: highlighted data in `Grid size={{ xs: COLUMN_WIDTHS[i] }}` where **`COLUMN_WIDTHS = [8, 4]`** (wide left, narrow right — reversed vs NarrowWideDetails).
+6. Children rendered in `Grid size={{ xs: 12 }}` rows.
+
+## Visual Specifications
+
+Derived from `WideNarrow.css`:
+
+### Container
+
+| CSS Class | Property | Value |
+|-----------|----------|-------|
+| `.psdk-wide-narrow-column` | Display | two-column row layout |
+| `.psdk-wide-column-column` | Width | ~67% (2 of 3 parts) — LEFT column |
+| `.psdk-narrow-column-column` | Width | ~33% (1 of 3 parts) — RIGHT column |
+
+**CSS-only implementation notes:**
+- `.psdk-wide-narrow-column`: `display: grid; grid-template-columns: 2fr 1fr; gap: 1rem`.
+- Wide column (left): `2fr` — takes the first grid column.
+- Narrow column (right): `1fr` — takes the second grid column.
+- On mobile: `grid-template-columns: 1fr` (stacks vertically, wide on top).
+
+### Key Difference from NarrowWide
+
+| | NarrowWide | WideNarrow |
+|---|---|---|
+| Left column | Narrow (~33%) | Wide (~67%) |
+| Right column | Wide (~67%) | Narrow (~33%) |
+| CSS container class | `.psdk-narrow-wide-column` | `.psdk-wide-narrow-column` |
+| `COLUMN_WIDTHS` (Details) | `[4, 8]` | `[8, 4]` |
+
+## Edge Cases & Special Logic
+
+- `WideNarrowDetails` defaults `children` to empty (`= []`) — safe even if no children are provided.
+- Highlighted data guard: check `if (!theConfigObject) theConfigObject = {}` before creating PConnectComponent — prevents crash on null config objects.
+- Icon cleanup in `WideNarrowPage`: strip `'pi pi-'` from icon string before passing to `WideNarrow`.
+
+## Dependencies
+
+- `WideNarrowPage`: `getComponentFromRegistry` from `@pega/sdk-react`
+- `WideNarrowDetails`: `getComponentFromRegistry('FieldGroup')`, `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Asymmetric two-column layout (main content + sidebar).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS Grid `grid-template-columns: 2fr 1fr; gap: 1rem` |
+| MUI | `<Grid container><Grid size={{ xs: 12, md: 8 }}><Grid size={{ xs: 12, md: 4 }}>` |
+| Ant Design | `<Row gutter={16}><Col xs={24} md={16}><Col xs={24} md={8}>` |
+| Chakra UI | `<Grid templateColumns={{ base: '1fr', md: '2fr 1fr' }} gap={4}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-1 md:grid-cols-[2fr_1fr] gap-4` |
+
+When implementing in a specific design system:
+- Wide column ≈ 67% width (left side)
+- Narrow column ≈ 33% width (right side)
+- `WideNarrowDetails` forces DISPLAY_ONLY + readOnly on all children