@pega/sdk 0.0.1 → 0.0.3

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

@@ -0,0 +1,107 @@
+---
+description: Template component skill: DefaultForm
+alwaysApply: false
+---
+
+# Skill: DefaultForm
+
+Standard form layout template supporting 1, 2, or 3 column arrangements. Renders form fields from the first PConnect region child and optionally displays instruction text above.
+
+> **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 form's fields in a 1, 2, or 3-column grid layout. Children come from a PConnect region (unwrapped one level). Each child field is connected to the Redux store via a `connectToState` HOC so visibility and prop updates flow reactively. Instruction HTML is displayed above the form when present.
+
+## Pega Metadata
+
+- **Registration key:** `DefaultForm` (in `component-map.ts`)
+- **Category:** Form template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `NumCols` | `string` | No | Number of columns: `'1'`, `'2'`, or `'3'`. Default `'1'` |
+| `instructions` | `string` | No | HTML instruction text shown above the form |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+1. **Resolve column count:** Use `NumCols || '1'`. Switch to CSS class:
+   - `'1'` → `psdk-default-form-one-column`
+   - `'2'` → `psdk-default-form-two-column`
+   - `'3'` → `psdk-default-form-three-column`
+   - Default → `psdk-default-form-one-column`
+2. **Get instructions:** Call `getInstructions(getPConnect(), props.instructions)` — returns sanitized HTML string or empty.
+3. **Unwrap region children:** `arChildren = getPConnect().getChildren()[0].getPConnect().getChildren()` — the first child is a region; its children are the actual form fields.
+4. **Wrap each child:** Create a `Child` component using `connectToState(mapStateToProps)` HOC wrapping `PConnectComponent`. Map each field:
+   ```
+   arChildren.map((kid) => <Child key={getKeyForMappedField(kid)} {...kid} />)
+   ```
+5. **Render:**
+   - If instructions, render `<div className='psdk-default-form-instruction-text'>` with `dangerouslySetInnerHTML={{ __html: instructions }}`.
+   - Render `<div className={divClass}>{dfChildren}</div>`.
+
+## Visual Specifications
+
+Derived from `DefaultForm.css`:
+
+### Column Layouts
+
+| Class | Layout |
+|-------|--------|
+| `psdk-default-form-one-column` | Single column, full width |
+| `psdk-default-form-two-column` | Two equal columns |
+| `psdk-default-form-three-column` | Three equal columns |
+
+**CSS-only implementation notes:**
+- One column: `display: grid; grid-template-columns: 1fr; gap: 1rem`.
+- Two column: `display: grid; grid-template-columns: 1fr 1fr; gap: 1rem`.
+- Three column: `display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1rem`.
+- Instructions container: `padding: 0.5rem 0; margin-bottom: 0.5rem; font-size: 0.875rem`.
+- Responsive: collapse multi-column to single column on mobile.
+
+### Instruction Text
+
+| Property | Value |
+|----------|-------|
+| CSS class | `psdk-default-form-instruction-text` |
+| Content | Raw HTML rendered with `dangerouslySetInnerHTML` |
+
+## Edge Cases & Special Logic
+
+- `NumCols` is a string (not number) — always compare with string literals `'1'`, `'2'`, `'3'`.
+- The region unwrap (`getChildren()[0].getPConnect().getChildren()`) assumes the form metadata has exactly one region child. Guard against `undefined` if the region child is missing.
+- `connectToState(mapStateToProps)` HOC subscribes each field to the Redux store — if Redux is not available, fall back to rendering `PConnectComponent` directly without the HOC.
+- `getKeyForMappedField(kid)` generates a stable key for each field from the field's metadata path — import from `./utils`.
+- Instructions HTML is server-sanitized (comment in source code) — do not sanitize again on the client.
+
+## Dependencies
+
+- `getInstructions` from `../../helpers/template-utils` — extracts instruction text from PConnect metadata
+- `connectToState` from `../../helpers/state-utils` — HOC for Redux store subscription
+- `PConnectComponent` from `@pega/sdk-react` — renders each child field
+- `getKeyForMappedField`, `mapStateToProps` from `./utils` — key generation and state mapping
+
+## Design System Mapping
+
+**UI control type:** Multi-column form field grid with optional instruction text header.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS Grid with column count driven by `NumCols` |
+| MUI | CSS Grid via `sx` prop or makeStyles |
+| Ant Design | `<Form layout='vertical'>` with `<Row>/<Col>` for multi-column |
+| Chakra UI | `<SimpleGrid columns={N} spacing={4}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-1/2/3 gap-4` |
+
+When implementing in a specific design system:
+- `NumCols` is always a string (`'1'`/`'2'`/`'3'`) — parse before use
+- Instructions HTML is rendered above the form, before any fields
+- Each child field must be subscribed to the store for reactive visibility/prop updates

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

@@ -0,0 +1,115 @@
+---
+description: Template component skill: DefaultPage
+alwaysApply: false
+---
+
+# Skill: DefaultPage
+
+Flexible page layout template that renders children in a configurable column layout, with optional banner hero section.
+
+> **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 page's child regions in a responsive grid layout. The number and proportions of columns are driven by the `layout` prop. When `enableBanner` is true, delegates to the `Banner` DSE component for a full-width hero section with the child columns below it.
+
+## Pega Metadata
+
+- **Registration key:** `DefaultPage` (in `component-map.ts`)
+- **Category:** Page template
+- **Extends:** `CommonPageProps` (does NOT directly extend `PConnProps` — no `getPConnect` in props)
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `layout` | `'one-column' \| 'two-column' \| 'narrow-wide' \| 'wide-narrow' \| 'dynamic'` | No | Column layout. Default `'one-column'` |
+| `children` | `ReactNode \| ReactNode[]` | Yes | Child region components to render in columns |
+| `title` | `string` | Yes | Page title (part of `CommonPageProps`, not directly rendered) |
+| `icon` | `string` | Yes | Page icon (part of `CommonPageProps`, not directly rendered) |
+| `localeReference` | `string` | Yes | Locale reference key |
+| `enableBanner` | `boolean` | No | If `true`, render `Banner` hero with children as `a`/`b` columns |
+| `heading` | `string` | No | Banner heading. Default `''` |
+| `message` | `string` | No | Banner message. Default `''` |
+| `imageTheme` | `'light' \| 'dark' \| undefined` | No | Banner image theme |
+| `backgroundImage` | `string` | No | Banner background image URL. Default `''` |
+| `backgroundColor` | `string` | No | Banner background color. Default `''` |
+| `tintImage` | `boolean` | No | Banner image tint flag |
+
+## Behavioral Contract
+
+### Without Banner (`enableBanner` is falsy)
+
+1. Convert children to an array using `Children.toArray(children)` (memoized).
+2. Look up column widths from `COLUMNS_WIDTHS` map using `layout`:
+   - `'one-column'`: `[12]` (single column, full width)
+   - `'two-column'`: `[6, 6]` (equal split)
+   - `'narrow-wide'`: `[4, 8]`
+   - `'wide-narrow'`: `[8, 4]`
+3. Render a `<Grid container spacing={1}>`.
+4. Map over children array: for each child at index `i`, render `<Grid key={i} size={COLUMNS_WIDTHS[layout][i]}>{child}</Grid>`.
+
+### With Banner (`enableBanner` is true)
+
+1. Retrieve `Banner` from the component registry.
+2. Determine banner variant:
+   - If `layout === 'one-column'`, use `'two-column'` for the banner layout (equal split for `a`/`b`).
+   - Otherwise use the `layout` value directly.
+3. Render `<Banner variant={...} a={[childArray[0]]} b={[childArray[1]]} banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }} />`.
+
+## Visual Specifications
+
+### Column Widths
+
+| `layout` | Column sizes (MUI 12-grid) |
+|----------|--------------------------|
+| `'one-column'` | 12 |
+| `'two-column'` | 6, 6 |
+| `'narrow-wide'` | 4, 8 |
+| `'wide-narrow'` | 8, 4 |
+
+### Grid Spacing
+
+| Property | Value |
+|----------|-------|
+| Container spacing | 1 (≈ 8px between columns) |
+
+**CSS-only implementation notes:**
+- One-column: `display: grid; grid-template-columns: 1fr; gap: 8px`.
+- Two-column: `display: grid; grid-template-columns: 1fr 1fr; gap: 8px`.
+- Narrow-wide: `display: grid; grid-template-columns: 1fr 2fr; gap: 8px`.
+- Wide-narrow: `display: grid; grid-template-columns: 2fr 1fr; gap: 8px`.
+- With banner: delegate to Banner component structure (see `Banner.md`).
+- Responsive: collapse all to single column on mobile.
+
+## Edge Cases & Special Logic
+
+- `layout='dynamic'` is listed in the type union but has no entry in `COLUMNS_WIDTHS` — if accessed, it returns `undefined`, and no columns are rendered. This is a known stub.
+- When `enableBanner` is true and `layout === 'one-column'`, the banner layout is forced to `'two-column'` to provide a meaningful two-slot layout for `a` and `b`.
+- Children are memoized via `useMemo(() => Children.toArray(children), [children])` to avoid unnecessary re-renders.
+
+## Dependencies
+
+- When `enableBanner` is true: `getComponentFromRegistry('Banner')` from `@pega/sdk-react`
+- `Grid` from `@mui/material` (or equivalent CSS grid in non-MUI implementations)
+
+## Design System Mapping
+
+**UI control type:** Responsive multi-column page grid layout with optional banner hero.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS Grid with column template driven by `layout` prop |
+| MUI | `<Grid container spacing={1}>` with `<Grid size={N}>` per child |
+| Ant Design | `<Row gutter={8}>` with `<Col span={N * 2}>` (24-col grid) |
+| Chakra UI | `<SimpleGrid columns={{ base: 1, md: N }}>` |
+| Shadcn/ui | Tailwind grid utilities matching the layout |
+
+When implementing in a specific design system:
+- Map `layout` prop to the appropriate column template
+- Banner mode delegates to the `Banner` component — implement Banner first
+- All children are sized uniformly within their column (no per-child overrides)

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

@@ -0,0 +1,93 @@
+---
+description: Template component skill: Details
+alwaysApply: false
+---
+
+# Skill: Details
+
+Read-only single-column details template. Renders all child fields in DISPLAY_ONLY mode inside a labeled FieldGroup, with optional highlighted data strip above.
+
+> **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 labeled group of read-only fields in a single-column vertical stack. Forces all children into `DISPLAY_ONLY` + `readOnly` mode via inherited props. Optionally renders a "highlighted data" banner row at the top (full-width, stacked-large-val display).
+
+## Pega Metadata
+
+- **Registration key:** `Details` (in `component-map.ts`)
+- **Category:** Display template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Section heading for the FieldGroup wrapper |
+| `showLabel` | `boolean` | Yes | Whether to show the section label |
+| `showHighlightedData` | `boolean` | Yes | Whether to render highlighted fields above children |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+1. **Inherited props merge:** `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }` — inherited props can override label/showLabel.
+2. **Force display mode:** Call `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `getPConnect().setInheritedProp('readOnly', true)` — ensures all child fields render in read-only display mode.
+3. **Render children:** Map `getPConnect().getChildren()` → `createElement(PConnectComponent, { ...configObject, key: index.toString() })`.
+4. **Highlighted data (when `showHighlightedData` is true):**
+   a. Read `getPConnect().getRawMetadata().config.highlightedData` (defaults to `[]`).
+   b. For each highlighted field, set `field.config.displayMode = 'STACKED_LARGE_VAL'`.
+   c. For fields with `field.config.value === '@P .pyStatusWork'`: set `field.type = 'TextInput'` and `field.config.displayAsStatus = true`.
+   d. Create each field via `getPConnect().createComponent(field, '', 0, {})`.
+5. **Layout:**
+   - Wrap all content in `<FieldGroup name={propsToUse.showLabel ? propsToUse.label : ''}>`.
+   - Highlighted data: `<Grid container spacing={1} style={{ padding: '0 0 1em' }}>` with each child at `Grid size={{ xs: 12 }}`.
+   - Regular children: `<Grid container spacing={1}>` with each child at `Grid size={{ xs: 12 }}`.
+
+## Visual Specifications
+
+### Overall Layout
+
+| Property | Value |
+|----------|-------|
+| Column structure | Single column (xs: 12 for each child) |
+| Inner spacing | Grid spacing 1 (≈ 8px between fields) |
+| Highlighted data padding | `padding: 0 0 1em` (space below before regular children) |
+
+**CSS-only implementation notes:**
+- Outer wrapper: `FieldGroup` component (see `FieldGroupDSE.md` for styles).
+- Children grid: `display: grid; grid-template-columns: 1fr; gap: 8px`.
+- Highlighted data row: `display: grid; grid-template-columns: 1fr; gap: 8px; padding-bottom: 1rem`.
+- Fields inside highlighted data use `STACKED_LARGE_VAL` display (larger value typography).
+
+## Edge Cases & Special Logic
+
+- `setInheritedProp` is called with side effects before rendering — this modifies the PConnect context and affects all children.
+- The `highlightedData` array defaults to `[]` if not present in metadata.
+- The `pyStatusWork` special case: sets both `type` and `displayAsStatus` to ensure the status field renders as a badge/chip rather than plain text.
+- `showHighlightedData` must be explicitly `true` — even if `highlightedData` has items, they won't render if the flag is false.
+
+## Dependencies
+
+- `createElement` from React
+- `PConnectComponent`, `getComponentFromRegistry('FieldGroup')` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with vertically stacked fields.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<fieldset>/<legend>` wrapper with CSS grid single column |
+| MUI | `<Grid container spacing={1}>` with `<Grid size={{ xs: 12 }}>` per field |
+| Ant Design | `<Card title={label}>` with `<Row><Col span={24}>` per field |
+| Chakra UI | `<Box>` with heading + `<Stack spacing={2}>` |
+| Shadcn/ui | `<Card><CardHeader><CardContent>` with stacked field items |
+
+When implementing in a specific design system:
+- All children must have `displayMode='DISPLAY_ONLY'` and `readOnly=true` inherited
+- Highlighted data uses `STACKED_LARGE_VAL` — larger/bolder value display
+- `showLabel=false` hides the section heading entirely

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

@@ -0,0 +1,100 @@
+---
+description: Template component skill: DetailsSubTabs
+alwaysApply: false
+---
+
+# Skill: DetailsSubTabs
+
+Read-only tabbed details template. Renders sub-tabs with deferred-loaded tab content, using shared tab utilities.
+
+> **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 tabbed layout for a details region. Each tab contains display-only content loaded on demand. Uses the same `tabUtils` as `SubTabs` but is scoped to a details/display context. Optionally shows a section heading above the tabs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsSubTabs` (in `component-map.ts`)
+- **Category:** Navigation / Display template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Tab content — `children[0]` is the deferred-loaded tabs container |
+| `label` | `string` | Yes | Section heading shown above tabs when `showLabel` is true |
+| `showLabel` | `boolean` | No | Whether to show the section heading. Default `true` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+1. **Inherited props merge:** `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }`.
+2. **Extract deferred tabs:** `deferLoadedTabs = Children.toArray(children)[0]`.
+3. **Compute visible tabs:** On mount and when `availableTabs` changes, call `getVisibleTabs(deferLoadedTabs, 'detailsSubTabs')` to get the filtered visible tab list.
+4. **State:** `currentTabId` (string, default `'0'`), `tabItems` (array of `{ id, name, content }` objects).
+5. **Transient tabs:** On `currentTabId` change, call `getTransientTabs(availableTabs, currentTabId, tabItems)` and update `tabItems` state.
+6. **Tab click handler:** `handleTabClick(id, index)` → calls `setCurrentTabId(index)` and `tabClick(index, availableTabs, currentTabId, setCurrentTabId, tabItems)` from `tabUtils`.
+7. **Render:**
+   - If `propsToUse.showLabel`, render `<h3>{propsToUse.label}</h3>`.
+   - Render `<TabContext value={currentTabId}>`.
+   - Render `<Tabs onChange={handleTabClick} value={currentTabId}>` with one `<Tab key={tab.id} label={tab.name} value={tab.id} />` per `tabItems` entry.
+   - Render one `<TabPanel key={tab.id} value={tab.id} tabIndex={+tab.id}>` per `tabItems` entry containing `tab.content || 'No content exists'`.
+
+## Visual Specifications
+
+### Heading
+
+| Property | Value |
+|----------|-------|
+| Tag | `<h3>` |
+| Shown only when | `propsToUse.showLabel === true` |
+
+### Tab Bar
+
+| Property | Value |
+|----------|-------|
+| Scrollable | Not specified (default non-scrollable in reference implementation) |
+| Tab text transform | Inherits design system default |
+
+**CSS-only implementation notes:**
+- Heading: `font-size: 1.25rem; font-weight: 600; margin-bottom: 8px`.
+- Tab bar: `display: flex; border-bottom: 2px solid var(--divider); gap: 0`.
+- Each tab: `padding: 8px 16px; cursor: pointer; border-bottom: 2px solid transparent`.
+- Active tab: `border-bottom-color: var(--app-primary-color)`.
+- Tab panel: `padding: 16px 0`.
+
+## Edge Cases & Special Logic
+
+- `availableTabs` is computed inside `useEffect` (not via useState) — this means the initial render uses an empty array, and tabs populate after mount.
+- The `useEffect` on `[availableTabs]` has a stale closure issue in the reference implementation — use a `useRef` or `useMemo` for production implementations if needed.
+- `tabItems` starts as `[]` — the tab bar renders empty until the first `currentTabId` change triggers `getTransientTabs`.
+- `propsToUse` label/showLabel may be overridden by inherited props — always use `propsToUse` for the label, not raw `label`/`showLabel` props.
+
+## Dependencies
+
+- `getTransientTabs`, `getVisibleTabs`, `tabClick` from `../../SubTabs/tabUtils`
+- `TabContext`, `TabPanel` from `@mui/lab`
+- `Tab`, `Tabs` from `@mui/material`
+
+## Design System Mapping
+
+**UI control type:** Tabbed section container for read-only details content.
+
+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:
+- `getVisibleTabs` and `getTransientTabs` are tabUtils helpers — use them regardless of UI library
+- Tab content is lazily loaded via the transient tab pattern
+- Optional `<h3>` heading above the tab bar (controlled by `showLabel`)

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

@@ -0,0 +1,83 @@
+---
+description: Template component skill: DetailsThreeColumn
+alwaysApply: false
+---
+
+# Skill: DetailsThreeColumn
+
+Read-only three-column details template. Renders child fields in DISPLAY_ONLY mode in a 3-column grid inside a FieldGroup, with optional highlighted data.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Identical to `Details` and `DetailsTwoColumn` in all behavior except children are distributed into a **three-column grid** (`xs: 4` per child). Used in wide details regions where the design calls for three equal columns of fields.
+
+> The implementation is nearly identical to `Details`. See `Details.md` for full pattern descriptions. Only the column width differs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsThreeColumn` (in `component-map.ts`)
+- **Category:** Display template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Section heading for the FieldGroup wrapper |
+| `showLabel` | `boolean` | No | Whether to show the section label. Default `true` |
+| `showHighlightedData` | `boolean` | No | Whether to render highlighted fields above children. Default `false` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+All steps identical to `Details`, except:
+
+- **Regular children grid:** Each child renders at `Grid size={{ xs: 4 }}` (three per row).
+- **Highlighted data grid:** Each highlighted field also renders at `Grid size={{ xs: 4 }}`.
+- All other behaviors (inherited props merge, `setInheritedProp('displayMode', 'DISPLAY_ONLY')`, `setInheritedProp('readOnly', true)`, FieldGroup wrapper, pyStatusWork handling) are identical to `Details`.
+
+## Visual Specifications
+
+### Column Structure
+
+| | Details | DetailsTwoColumn | DetailsThreeColumn |
+|-|---------|-----------------|-------------------|
+| Column width per child | xs: 12 | xs: 6 | **xs: 4** |
+| Columns per row | 1 | 2 | **3** |
+| Highlighted data column | xs: 12 | xs: 6 | **xs: 4** |
+
+**CSS-only implementation notes:**
+- Children grid: `display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px`.
+- Highlighted data row: `display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px; padding-bottom: 1rem`.
+- Wrap in FieldGroup (see `FieldGroup.md` DSE skill).
+
+## Edge Cases & Special Logic
+
+All edge cases identical to `Details`. See `Details.md`.
+
+## Dependencies
+
+- `createElement` from React
+- `PConnectComponent`, `getComponentFromRegistry('FieldGroup')` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with fields in a three-column grid.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<fieldset>/<legend>` with CSS `grid-template-columns: 1fr 1fr 1fr; gap: 8px` |
+| MUI | `<Grid container spacing={1}>` with `<Grid size={{ xs: 4 }}>` per field |
+| Ant Design | `<Descriptions column={3}>` or `<Row><Col span={8}>` per field |
+| Chakra UI | `<SimpleGrid columns={3} spacing={2}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-3 gap-2` |
+
+When implementing in a specific design system:
+- 3-column layout — each field takes one-third of the available width
+- All other behaviors inherited from `Details` (DISPLAY_ONLY, readOnly, FieldGroup, highlighted data)

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

@@ -0,0 +1,83 @@
+---
+description: Template component skill: DetailsTwoColumn
+alwaysApply: false
+---
+
+# Skill: DetailsTwoColumn
+
+Read-only two-column details template. Renders child fields in DISPLAY_ONLY mode in a 2-column grid inside a FieldGroup, with optional highlighted data.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Identical to `Details` in all behavior except children are distributed into a **two-column grid** (`xs: 6` per child) instead of single-column. Used in details regions where the design calls for side-by-side field pairs.
+
+> The implementation is nearly identical to `Details`. See `Details.md` for full pattern descriptions. Only the column width differs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsTwoColumn` (in `component-map.ts`)
+- **Category:** Display template
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Section heading for the FieldGroup wrapper |
+| `showLabel` | `boolean` | No | Whether to show the section label. Default `true` |
+| `showHighlightedData` | `boolean` | No | Whether to render highlighted fields above children. Default `false` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+All steps identical to `Details`, except:
+
+- **Regular children grid:** Each child renders at `Grid size={{ xs: 6 }}` (two per row, side by side).
+- **Highlighted data grid:** Each highlighted field also renders at `Grid size={{ xs: 6 }}`.
+- All other behaviors (inherited props merge, `setInheritedProp('displayMode', 'DISPLAY_ONLY')`, `setInheritedProp('readOnly', true)`, FieldGroup wrapper, pyStatusWork handling) are identical to `Details`.
+
+## Visual Specifications
+
+### Column Structure
+
+| | Details | DetailsTwoColumn |
+|-|---------|-----------------|
+| Column width per child | xs: 12 (full width) | **xs: 6 (half width)** |
+| Columns per row | 1 | **2** |
+| Highlighted data column | xs: 12 | **xs: 6** |
+
+**CSS-only implementation notes:**
+- Children grid: `display: grid; grid-template-columns: 1fr 1fr; gap: 8px`.
+- Highlighted data row: `display: grid; grid-template-columns: 1fr 1fr; gap: 8px; padding-bottom: 1rem`.
+- Wrap in FieldGroup (see `FieldGroup.md` DSE skill).
+
+## Edge Cases & Special Logic
+
+All edge cases identical to `Details`. See `Details.md`.
+
+## Dependencies
+
+- `createElement` from React
+- `PConnectComponent`, `getComponentFromRegistry('FieldGroup')` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with fields in a two-column grid.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<fieldset>/<legend>` with CSS `grid-template-columns: 1fr 1fr; gap: 8px` |
+| MUI | `<Grid container spacing={1}>` with `<Grid size={{ xs: 6 }}>` per field |
+| Ant Design | `<Descriptions column={2}>` or `<Row><Col span={12}>` per field |
+| Chakra UI | `<SimpleGrid columns={2} spacing={2}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-2 gap-2` |
+
+When implementing in a specific design system:
+- 2-column layout — each field takes half the available width
+- All other behaviors inherited from `Details` (DISPLAY_ONLY, readOnly, FieldGroup, highlighted data)