@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/SelfServiceCaseView.mdrules

@@ -0,0 +1,140 @@
+---
+description: Template component skill: SelfServiceCaseView
+alwaysApply: false
+---
+
+# Skill: SelfServiceCaseView
+
+Self-service portal case view template. Renders a case workspace optimized for self-service channels, with a compact summary sidebar, main content area, and optional utilities panel.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+A case view variant designed for self-service portal channels. Uses a horizontal flex layout (25% summary / flex:1 main / 25% utilities) instead of the 3-column grid of `CaseView`. Filters case summary data to only include fields available in the self-service channel, and filters utilities to self-service-appropriate actions.
+
+## Pega Metadata
+
+- **Registration key:** `SelfServiceCaseView` (in `component-map.ts`)
+- **Category:** Page template — self-service case workspace
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Region children (variable count based on `isObjectType`) |
+| `isObjectType` | `boolean` | No | Whether the case is an object-type (affects child region count) |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Region Assignment by Child Index
+
+Child indexing depends on `isObjectType`:
+
+**`isObjectType === false` (5 children):**
+| Index | Region |
+|-------|--------|
+| 0 | Summary |
+| 1 | (Header/Stages) |
+| 2 | Main content |
+| 3 | Utilities |
+| 4 | (Additional) |
+
+**`isObjectType === true` (3 children):**
+| Index | Region |
+|-------|--------|
+| 0 | Summary |
+| 1 | Main content |
+| 2 | Utilities |
+
+Show/hide individual regions based on:
+- `showSummary`: always show summary region.
+- `showMain`: always show main content region.
+- `showUtilities`: show utilities only if the region has content.
+
+### `selfServiceCaseViewHeader`
+
+Renders a slim header bar above the main flex layout showing:
+- Case ID / case type name
+- Case status badge
+
+### Case Summary Data
+
+Call `prepareCaseSummaryData(primaryFields, secondaryFields, getPConnect)` with a filter:
+- Only include fields where `availableInChannel.selfService === true`.
+
+### Utilities Filter
+
+Call `filterUtilities(utilitiesChildren, getPConnect)` to remove utilities not appropriate for self-service channels.
+
+### Render Structure
+
+```
+<div className="psdk-ss-case-view">
+  <selfServiceCaseViewHeader />
+  <div className="psdk-ss-case-view-body" style="display:flex; flex-direction:row">
+    <div style="flex: 0 0 25%">   {/* Summary */}
+      {showSummary && summaryRegion}
+    </div>
+    <div style="flex: 1">         {/* Main content */}
+      {showMain && mainRegion}
+    </div>
+    <div style="flex: 0 0 25%">  {/* Utilities */}
+      {showUtilities && utilitiesRegion}
+    </div>
+  </div>
+</div>
+```
+
+## Visual Specifications
+
+| Column | Width | Contents |
+|--------|-------|----------|
+| Summary | 25% (fixed) | Case summary fields (self-service filtered) |
+| Main | flex: 1 | Main case content / assignment form |
+| Utilities | 25% (fixed) | Filtered utilities |
+
+**CSS-only implementation notes:**
+- Body layout: `display: flex; flex-direction: row; gap: 1rem`.
+- Summary column: `flex: 0 0 25%; min-width: 0`.
+- Main column: `flex: 1 1 auto; min-width: 0`.
+- Utilities column: `flex: 0 0 25%; min-width: 0`.
+- Header bar: `display: flex; align-items: center; gap: 1rem; padding: 0.5rem 0; margin-bottom: 1rem`.
+- Responsive: collapse to single column on mobile.
+
+## Edge Cases & Special Logic
+
+- `isObjectType` changes the number of `children` — always derive regions by index based on this flag.
+- `filterUtilities` may return empty array — `showUtilities` should be `false` in that case (hide the column entirely).
+- Summary fields filtered by `availableInChannel.selfService` — if all fields are filtered out, the summary column may be empty.
+- The self-service header differs from the standard case header — it is a separate sub-component, not the full `CaseView` header.
+
+## Dependencies
+
+- `prepareCaseSummaryData` from `./utils` — with self-service channel filter applied
+- `filterUtilities` from `./utils` — removes non-self-service utilities
+- `selfServiceCaseViewHeader` — inline sub-component or imported header
+- `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Self-service portal case workspace — horizontal 3-panel flex layout.
+
+Listed design systems are examples only.
+
+| Design System | Layout | Header Bar |
+|---|---|---|
+| Default (CSS only) | CSS `display:flex` with percentage widths | Custom `<header>` |
+| MUI | `<Box display='flex' flexDirection='row'>` with `<Box flex='0 0 25%'>` | `<Box>` with `<Typography>` |
+| Ant Design | `<Layout>` with `<Sider>` + `<Content>` | `<PageHeader>` |
+| Chakra UI | `<HStack align='stretch'>` with width constraints | `<Flex>` |
+| Shadcn/ui | Tailwind `flex flex-row` | Custom header |
+
+When implementing in a specific design system:
+- `isObjectType` determines child count — do not assume fixed child order without checking this flag
+- Self-service channel filter on summary data is mandatory — `availableInChannel.selfService === true`
+- `filterUtilities` result controls utilities column visibility

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/SimpleTable.mdrules

@@ -0,0 +1,132 @@
+---
+description: Template component skill: SimpleTable
+alwaysApply: false
+---
+
+# 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/.cursor/rules/skills/template-skills/SingleReferenceReadOnly.mdrules

@@ -0,0 +1,108 @@
+---
+description: Template component skill: SingleReferenceReadOnly
+alwaysApply: false
+---
+
+# 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/.cursor/rules/skills/template-skills/SubTabs.mdrules

@@ -0,0 +1,84 @@
+---
+description: Template component skill: SubTabs
+alwaysApply: false
+---
+
+# 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/.cursor/rules/skills/template-skills/TwoColumn.mdrules

@@ -0,0 +1,136 @@
+---
+description: Template component skill: TwoColumn
+alwaysApply: false
+---
+
+# 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