@pega/sdk 0.0.4 → 0.0.6

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

@@ -1,24 +1,39 @@
 # Skill: DataReference
 
-Data reference template. Routes to field, table, or search renderers based on `selectionMode` and `displayAs` props. Handles deferred data source loading, dropdown options, and multi-select variants.
+Data reference template. Routes to field, table, or search renderers based on `selectionMode` and `displayAs` inputs. Handles deferred data source loading, dropdown options, and multi-select variants.
 
 > **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
 
 ---
 
+> ⚠️ **CRITICAL — DataReference is a CONTENT-PROJECTION PASS-THROUGH**
+>
+> This component MUST render children provided via content projection directly. The PConnect bridge already resolves the correct sub-components (Dropdown, AutoComplete, SingleReferenceReadOnly, etc.) and passes them as projected content. DataReference just passes them through.
+>
+> The correct implementation is a simple pass-through: normalize the projected children to a list (if already a list use it directly, otherwise wrap the single item in a list filtering out empty entries), then return the single child directly if there is exactly one, otherwise wrap the list in a container element.
+>
+> ❌ **NEVER call `pConn.createComponent()`** — causes "Maximum call stack size exceeded" (infinite recursion back to form templates)
+> ❌ **NEVER call `firstChildPConnect().createComponent()`** — causes "getPConnect is not a function" when child PConnect isn't ready
+> ❌ **NEVER try to manually route to Dropdown/AutoComplete/etc based on `displayAs`** — the bridge already does this
+>
+> **Why the reference is ~460 lines but the generated version should be ~10:**
+> The reference adds advanced features (deferred datasource fetching, review-mode editing, advanced search, card variants) that require careful PConnect lifecycle management. These features are NOT needed for the component to function correctly — the bridge handles core rendering. Attempting to replicate the reference's `createComponent` pattern without the full ~460 lines of config manipulation will crash.
+
+---
+
 ## Component Purpose
 
 Renders a data reference field that can be displayed as a dropdown, autocomplete, checkbox group, radiobutton group, or a card-selection layout. In read-only mode, delegates to `SingleReferenceReadOnly` (single selection) or `MultiReferenceReadOnly` (multi-selection). Supports deferred/parameterized data sources.
 
 ## Pega Metadata
 
-- **Registration key:** `DataReference` (in `component-map.ts`)
+- **Registration key:** `DataReference` (in the project's component map)
 - **Category:** Form template — data selection
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop                 | Type       | Required | Description                                                                                            |
+| Input                | Type       | Required | Description                                                                                            |
 | -------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------ |
 | `label`              | `string`   | Yes      | Field label                                                                                            |
 | `displayAs`          | `string`   | Yes      | UI variant: `'dropdown'`, `'autocomplete'`, `'checkbox'`, `'radiobutton'`, `'listview'`, `'searchbox'` |
@@ -36,15 +51,25 @@ Renders a data reference field that can be displayed as a dropdown, autocomplete
 | `fieldMetadata`      | `object`   | No       | Extra field-level metadata                                                                             |
 | `getPConnect`        | `function` | Yes      | PConnect getter                                                                                        |
 
+## Implementation Structure
+
+**Main Component Logic** — steps in order:
+
+This component is a pure pass-through wrapper. The PConnect bridge resolves the correct sub-components (Dropdown, AutoComplete, SingleReferenceReadOnly, MultiReferenceReadOnly, etc.) and passes them as projected content. Do NOT call `pConn.createComponent()` or `firstChildPConnect().createComponent()` here — it causes "getPConnect is not a function" errors or infinite recursion.
+
+1. Receive inputs, including projected children content.
+2. Normalize the projected children into a list: if already a list use it directly, otherwise wrap the single item in a list filtering out empty entries.
+3. Return the single child directly if the list has exactly one element; otherwise wrap the full list in a container element.
+
 ## Behavioral Contract
 
 ### Read-Only Routing
 
 If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
 
-- `selectionMode === 'single'` → render `<SingleReferenceReadOnly />`.
-- `selectionMode === 'multi'` → render `<MultiReferenceReadOnly />`.
-- Both receive all relevant props plus `getPConnect`.
+- `selectionMode === 'single'` → render `SingleReferenceReadOnly`.
+- `selectionMode === 'multi'` → render `MultiReferenceReadOnly`.
+- Both receive all relevant inputs plus `getPConnect`.
 
 ### Edit Routing (by `displayAs`)
 
@@ -61,17 +86,17 @@ If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
 ### Deferred Data Source (`isDDSourceDeferred === true`)
 
 1. On mount, call `PCore.getDataApiUtils().getData(dataSourceName, parameters)`.
-2. Store result in `dropDownDataSource` state.
-3. Pass `dropDownDataSource` to the rendered field component as `datasource`.
+2. Store result in local state for the dropdown data source.
+3. Pass that data source to the rendered field component as `datasource`.
 
 ### Localized Placeholder
 
-- Generate a localized "Please select..." option via `localizedPlaceholderOption` using `PCore.getLocaleUtils().getLocaleValue(...)`.
-- Prepend this option to `dropDownDataSource` for dropdown/autocomplete variants.
+- Generate a localized "Please select..." option via `PCore.getLocaleUtils().getLocaleValue(...)`.
+- Prepend this option to the dropdown data source for dropdown/autocomplete variants.
 
 ### SearchForm Sub-Component
 
-When `displayAs === 'searchbox'`, renders an inline `<SearchForm>` sub-component that:
+When `displayAs === 'searchbox'`, renders an inline SearchForm sub-component that:
 
 1. Shows a text input with search icon.
 2. On submit: calls `getPConnect().getListActions().search(searchText)`.
@@ -79,27 +104,25 @@ When `displayAs === 'searchbox'`, renders an inline `<SearchForm>` sub-component
 
 ## Visual Specifications
 
-**CSS-only implementation notes:**
-
-- Wrapper: `display: flex; flex-direction: column; gap: 4px`.
-- Label: `font-size: 0.875rem; font-weight: 500; margin-bottom: 4px`.
+- Wrapper: vertical flex layout with 4px gap.
+- Label: 0.875rem font size, weight 500, 4px bottom margin.
 - Dropdown/Autocomplete: standard select input, full-width.
 - Checkbox/Radio group: grid layout matching `numCols`.
-- SearchForm: `display: flex; gap: 8px` (input + search button).
+- SearchForm: horizontal flex layout with 8px gap (input + search button).
 
 ## Edge Cases & Special Logic
 
-- `isDDSourceDeferred` — data is not available synchronously; show a loading indicator until `dropDownDataSource` resolves.
+- `isDDSourceDeferred` — data is not available synchronously; show a loading indicator until the dropdown data source resolves.
 - `parameters` may contain property references — resolve them via `pConn.getValue(paramRef)` before passing to `getData`.
 - `listType === 'associated'` — use `pConn.getFieldMetadata().options` directly instead of fetching from data page.
-- Card variant (`displayAs === 'listview'`) — may include image props (`image`, `imagePlaceholder`) from `getComponentConfig()`.
+- Card variant (`displayAs === 'listview'`) — may include image inputs (`image`, `imagePlaceholder`) from `getComponentConfig()`.
 - Multi-select with `displayAs === 'checkbox'` — values stored as comma-separated string in the property.
 
 ## Dependencies
 
 - `SingleReferenceReadOnly` (registered DSE or template component)
 - `MultiReferenceReadOnly` (registered template component)
-- Field components from registry: `Dropdown`, `AutoComplete`, `CheckboxGroup`, `RadioButtons`
+- Field components from the project's component registry: `Dropdown`, `AutoComplete`, `CheckboxGroup`, `RadioButtons`
 - `PCore.getDataApiUtils().getData()` — for deferred data source fetch
 - `PCore.getLocaleUtils().getLocaleValue()` — for localized placeholder
 
@@ -107,17 +130,9 @@ When `displayAs === 'searchbox'`, renders an inline `<SearchForm>` sub-component
 
 **UI control type:** Polymorphic data selection field — dropdown, autocomplete, checkbox, radiobutton, or search variants.
 
-Listed design systems are examples only.
-
-| Design System      | Dropdown              | Autocomplete     | Checkbox Group                 | Radio Group                 |
-| ------------------ | --------------------- | ---------------- | ------------------------------ | --------------------------- |
-| Default (CSS only) | `<select>`            | Custom combobox  | `<input type='checkbox'>` list | `<input type='radio'>` list |
-| MUI                | `<Select>/<MenuItem>` | `<Autocomplete>` | `<FormGroup><Checkbox>`        | `<RadioGroup><Radio>`       |
-| Ant Design         | `<Select>`            | `<AutoComplete>` | `<Checkbox.Group>`             | `<Radio.Group>`             |
-| Chakra UI          | `<Select>`            | Custom           | `<CheckboxGroup>`              | `<RadioGroup>`              |
-| Shadcn/ui          | `<Select>` + combobox | `<Combobox>`     | custom                         | `<RadioGroup>`              |
+When implementing in a specific design system, use the appropriate select/combobox component for dropdown and autocomplete variants, a checkbox group component for the checkbox variant, a radio group component for the radiobutton variant, and native or custom search input for the searchbox variant. Each design system will have its own equivalents for these control types.
 
-When implementing in a specific design system:
+Design considerations:
 
 - Always check `displayMode`/`readOnly` first and route to read-only components before rendering editable variants
 - Deferred loading must be handled — show skeleton/spinner until data is ready

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

@@ -0,0 +1,141 @@
+# 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.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> This component REQUIRES the project's state-connection wrapper to function. Without it, **form fields will NOT render** because they won't receive visibility and state updates from the application store.
+>
+> **NEVER** replace the state-connection wrapper pattern with plain rendering of the project's PConnect bridge utility. That pattern does not subscribe children to the store and results in invisible/non-functional form fields.
+>
+> **MANDATORY artifacts when generating this component:**
+>
+> 1. Main component file — with state-connection wrapper wrapping each child
+> 2. A utilities module — containing `mapStateToProps` and `getKeyForMappedField`
+> 3. Companion styles — column layout styles (or DS equivalent)
+> 4. Re-export module
+
+---
+
+## 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 application store via the project's state-connection wrapper so visibility and state updates flow reactively. Instruction HTML is displayed above the form when present.
+
+## Pega Metadata
+
+- **Registration key:** `DefaultForm` (in the project's component map)
+- **Category:** Form template
+- **Extends:** The project's base component interface
+
+## Inputs
+
+| Input          | 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                                          |
+
+## Implementation Structure
+
+**Module Setup:** This component needs: an element-creation utility from the framework; the project's template-utils helper (provides `getInstructions`); the project's PConnect bridge utility (renders each child field); the project's state-connection wrapper (connects fields to the application store); `getKeyForMappedField` and `mapStateToProps` from the companion utilities module; the project's base component interface (for typing); and companion styles for column layouts. The component's input contract extends the base component interface with `NumCols: string` and `instructions: string`.
+
+Outside the main component logic, define a `Child` wrapper using the project's state-connection wrapper invoked with `mapStateToProps`. This wrapper receives `key`, `visibility`, and the remaining inputs, then renders the project's PConnect bridge utility with those values. Defining this outside the component ensures it isn't recreated on every render cycle.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: extract `getPConnect` and `NumCols` (default `'1'`); compute `instructions = getInstructions(getPConnect(), inputs.instructions)`.
+2. **Resolve column count:** switch on `NumCols || '1'` to pick a 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`.
+3. **Unwrap region children:** the first child is a region wrapper, so drill into it via `getPConnect().getChildren()[0].getPConnect().getChildren()` to get the actual array of form fields (`arChildren`).
+4. **Wrap each child:** map `arChildren` to a `Child` element with `key={getKeyForMappedField(kid)}` and all field data spread as inputs, producing `dfChildren`.
+5. **Render:** when `instructions` is truthy, render a `psdk-default-form-instruction-text` container holding another element with the instructions as raw inner HTML; always render a container with the resolved column class (`divClass`) containing `dfChildren`.
+
+## 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(), inputs.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 the project's state-connection wrapper invoked with `mapStateToProps`, which in turn renders the project's PConnect bridge utility. Map each field to a Child element with `key={getKeyForMappedField(kid)}` and all field data spread.
+5. **Render:**
+   - If instructions, render a `psdk-default-form-instruction-text` container with raw HTML content of the instructions.
+   - Render a container with `divClass` holding `dfChildren`.
+
+## Visual Specifications
+
+Derived from companion styles:
+
+### 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 as inner HTML of container |
+
+## 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.
+- The project's state-connection wrapper with `mapStateToProps` subscribes each field to the application store — if the store is not available, fall back to rendering the PConnect bridge utility directly without the wrapper.
+- `getKeyForMappedField(kid)` generates a stable key for each field from the field's metadata path — provided by the companion utilities module.
+- Instructions HTML is server-sanitized (comment in source code) — do not sanitize again on the client.
+
+## Dependencies
+
+- The project's template-utils helper (provides `getInstructions`) — extracts instruction text from PConnect metadata
+- The project's state-connection wrapper — connects each child to the application store for visibility and state updates
+- The project's PConnect bridge utility — renders each child field
+- `getKeyForMappedField`, `mapStateToProps` from the companion utilities module — key generation and state mapping
+
+## Mandatory File: Utilities Module
+
+You MUST create a utilities module alongside the main component file. Without it, the component will not compile. It must export two members:
+
+- `mapStateToProps`: a function taking `(_, ownInputs)` that extracts `getPConnect` from `ownInputs` and returns `{ visibility: getPConnect().getComputedVisibility(), getPConnect }`.
+- `getKeyForMappedField`: a function taking a `field` that generates a stable render key. If `field` is an array, recursively map `getKeyForMappedField` over each item and join the results with `'__'`. Otherwise, read `field?.getPConnect?.()`; if its `meta` is present, return `JSON.stringify(pConnect.meta)`; otherwise fall back to `crypto.randomUUID()`.
+
+## Post-Generation Checklist
+
+After generating this component, verify ALL of the following:
+
+- [ ] The project's state-connection wrapper is imported from the state-utils helper
+- [ ] `mapStateToProps` and `getKeyForMappedField` are imported from the utilities module
+- [ ] The state-connected `Child` wrapper is defined OUTSIDE the main component logic
+- [ ] Each child field is rendered via the `Child` wrapper with `key={getKeyForMappedField(kid)}` and all field data spread
+- [ ] The utilities module is created with `mapStateToProps` and `getKeyForMappedField`
+- [ ] Column count CSS classes or DS grid component is applied based on `NumCols`
+
+If ANY of these are missing, the form fields will NOT render at runtime.
+
+## Design System Mapping
+
+**UI control type:** Multi-column form field grid with optional instruction text header.
+
+When implementing in a specific design system, map the following:
+
+- The column grid can be realized with CSS Grid driven by `NumCols`, a grid layout component from your design system, or utility-class-based grid layouts.
+- `NumCols` is always a string (`'1'`/`'2'`/`'3'`) — parse before use if the grid API expects a number.
+- Instructions HTML is rendered above the form, before any fields.
+- Each child field must be subscribed to the store via the project's state-connection wrapper for reactive visibility and state updates.

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

@@ -8,20 +8,20 @@ Flexible page layout template that renders children in a configurable column lay
 
 ## 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.
+Renders a page's child regions in a responsive grid layout. The number and proportions of columns are driven by the `layout` input. 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`)
+- **Registration key:** `DefaultPage` (in the project's component map)
 - **Category:** Page template
-- **Extends:** `CommonPageProps` (does NOT directly extend `PConnProps` — no `getPConnect` in props)
+- **Extends:** `CommonPageProps` (does NOT directly extend the base component interface — no `getPConnect` in inputs)
 
-## Props
+## Inputs
 
-| Prop              | Type                                                                          | Required | Description                                                      |
+| Input             | 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                     |
+| `children`        | renderable content (single or array)                                          | 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                                             |
@@ -33,37 +33,51 @@ Renders a page's child regions in a responsive grid layout. The number and propo
 | `backgroundColor` | `string`                                                                      | No       | Banner background color. Default `''`                            |
 | `tintImage`       | `boolean`                                                                     | No       | Banner image tint flag                                           |
 
+## Implementation Structure
+
+**Module Setup:** This component needs: a children-to-array utility from the framework, and the project's component registry (provides `Banner` at runtime). Declare a constant `COLUMNS_WIDTHS` mapping each layout name to its column width array: `'one-column'` → `[12]`, `'two-column'` → `[6, 6]`, `'narrow-wide'` → `[4, 8]`, `'wide-narrow'` → `[8, 4]`.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: extract `layout` (default `'one-column'`), `children`, `enableBanner`, `heading` (default `''`), `message` (default `''`), `imageTheme`, `backgroundImage` (default `''`), `backgroundColor` (default `''`), and `tintImage` from the component's inputs.
+2. Retrieve `Banner` from the project's component registry.
+3. Convert `children` to an array using the framework's children-to-array utility, as a memoized computation depending on `children`.
+4. **Banner mode:** if `enableBanner` is true, render a `Banner` with `variant` set to `layout` (substituting `'two-column'` when `layout === 'one-column'`), `a={[childArray[0]]}`, `b={[childArray[1]]}`, and a `banner` configuration object combining `variant: imageTheme`, `backgroundColor`, `title: heading`, `message`, `backgroundImage`, `tintImage`.
+5. **Standard grid mode:** otherwise, render a grid container with spacing of 1 unit containing one grid item per child, each sized according to `COLUMNS_WIDTHS[layout][index]`.
+
+> **Note:** `DefaultPage` does NOT have a `getPConnect` input — it extends `CommonPageProps`, not the base component interface.
+
 ## Behavioral Contract
 
 ### Without Banner (`enableBanner` is falsy)
 
-1. Convert children to an array using `Children.toArray(children)` (memoized).
+1. Convert children to an array using the framework's children-to-array utility (as a memoized computation).
 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>`.
+3. Render a grid container with spacing of 1 unit.
+4. Map over children array: for each child at index `i`, render a grid item sized to `COLUMNS_WIDTHS[layout][i]` containing the child.
 
 ### With Banner (`enableBanner` is true)
 
-1. Retrieve `Banner` from the component registry.
+1. Retrieve `Banner` from the project's 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 }} />`.
+3. Render `Banner` with `variant`, `a={[childArray[0]]}`, `b={[childArray[1]]}`, and `banner` configuration: `{ 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                       |
+| `layout`        | Column sizes (12-unit grid) |
+| --------------- | --------------------------- |
+| `'one-column'`  | 12                          |
+| `'two-column'`  | 6, 6                        |
+| `'narrow-wide'` | 4, 8                        |
+| `'wide-narrow'` | 8, 4                        |
 
 ### Grid Spacing
 
@@ -84,29 +98,21 @@ Renders a page's child regions in a responsive grid layout. The number and propo
 
 - `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.
+- Children are converted to an array via a memoized computation 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)
+- When `enableBanner` is true: the project's component registry (to retrieve `Banner` at runtime)
+- A grid layout mechanism (CSS Grid, a design system grid component, or utility classes)
 
 ## 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:
+When implementing in a specific design system, map the following:
 
-- 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)
+- The `layout` input drives column proportions — translate to the appropriate column template or grid configuration for your chosen system.
+- The 12-unit grid widths (`[12]`, `[6, 6]`, `[4, 8]`, `[8, 4]`) can map to any proportional grid (e.g., a 24-unit grid by doubling values, or fractional CSS Grid columns).
+- Banner mode delegates to the `Banner` component — implement Banner first.
+- All children are sized uniformly within their column (no per-child overrides).
+- Grid spacing of 1 unit (≈ 8px) should be applied between columns.

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

@@ -0,0 +1,96 @@
+# 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 configuration. Optionally renders a "highlighted data" banner row at the top (full-width, stacked-large-val display).
+
+## Pega Metadata
+
+- **Registration key:** `Details` (in the project's component map)
+- **Category:** Display template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input                 | 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                                     |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the project's PConnect bridge utility (for rendering child PConnect nodes) and the project's component registry lookup function. The component accepts `label` (string), `showLabel` (boolean), `showHighlightedData` (boolean), and `getPConnect` (function) as its inputs.
+
+**Main Component Logic** — steps in order:
+
+1. Retrieve `FieldGroup` from the project's component registry; receive `label`, `showLabel`, `getPConnect`, and `showHighlightedData` from inputs.
+2. Merge inherited configuration: `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }` (inherited values can override the direct inputs).
+3. Force all children into display-only mode as a side effect: call `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `getPConnect().setInheritedProp('readOnly', true)`.
+4. Build the children array: map each entry of `getPConnect().getChildren()` to a renderable PConnect bridge element using the config object and a unique key.
+5. If `showHighlightedData` is true, read `highlightedData` (default empty array) from `getPConnect().getRawMetadata().config`, and for each field: set `field.config.displayMode = 'STACKED_LARGE_VAL'`; if `field.config.value === '@P .pyStatusWork'`, set `field.type = 'TextInput'` and `field.config.displayAsStatus = true`; then create the component via `getPConnect().createComponent(field, '', 0, {})` and collect the results into `highlightedDataArr`.
+6. Render a FieldGroup named `propsToUse.showLabel ? propsToUse.label : ''`, containing (when `showHighlightedData` is true and non-empty) a single-column grid container with spacing and bottom padding holding one full-width grid item per highlighted field, followed by a second single-column grid container with spacing holding one full-width grid item per regular child.
+
+## Behavioral Contract
+
+1. **Inherited inputs merge:** `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }` — inherited values 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()` → renderable content via the project's PConnect bridge utility, passing each config object with a unique key.
+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 a FieldGroup with name set to `propsToUse.showLabel ? propsToUse.label : ''`.
+   - Highlighted data: single-column grid container with ~8px gap and bottom padding (~1rem below).
+   - Regular children: single-column grid container with ~8px gap.
+
+## Visual Specifications
+
+### Overall Layout
+
+| Property                 | Value                                        |
+| ------------------------ | -------------------------------------------- |
+| Column structure         | Single column (full width for each child)    |
+| Inner spacing            | ~8px between fields                          |
+| Highlighted data padding | ~1rem bottom padding before regular children |
+
+**CSS-only implementation notes:**
+
+- Outer wrapper: `FieldGroup` component (see `FieldGroupDSE.md` for styles).
+- Children grid: single-column layout with ~8px gap between items.
+- Highlighted data row: single-column layout with ~8px gap and ~1rem bottom padding.
+- 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
+
+- The project's PConnect bridge utility (for rendering child PConnect nodes)
+- The project's component registry (to retrieve `FieldGroup`)
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with vertically stacked fields.
+
+When implementing in a specific design system, map the following:
+
+- The outer wrapper is a labeled group container (e.g., a fieldset/legend, a card with a title header, or a boxed section with a heading). Use whatever grouped-section primitive your design system provides.
+- Each child occupies the full width of the container (single column). Use your design system's grid or stack primitive with a single column and ~8px spacing between items.
+- Highlighted data renders in the same single-column layout with additional bottom padding (~1rem) separating it from regular children.
+- 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/.ai-common/skills/template-skills/DetailsSubTabs.md

@@ -0,0 +1,103 @@
+# 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 tab utilities as `SubTabs` but is scoped to a details/display context. Optionally shows a section heading above the tabs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsSubTabs` (in the project's component map)
+- **Category:** Navigation / Display template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Name          | Type               | Required | Description                                                       |
+| ------------- | ------------------ | -------- | ----------------------------------------------------------------- |
+| `children`    | renderable content | 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                                                   |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the shared tab utilities (`getVisibleTabs`, `getTransientTabs`, `tabClick`) from the project's SubTabs tab-utility module. These helpers are framework-independent and work with any rendering approach.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `children` (default empty array), `label`, `showLabel` (default `true`), and `getPConnect`.
+2. Merge inherited display settings: `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }`.
+3. Extract the deferred tabs container from the first child element; initialize `availableTabs` to an empty array.
+4. On mount (lifecycle effect), compute `availableTabs` via `getVisibleTabs(deferLoadedTabs, 'detailsSubTabs')`.
+5. Declare local state: `currentTabId` (string, initialized to `'0'`) and `tabItems` (array, initialized empty).
+6. In a lifecycle effect keyed on `currentTabId`, recompute `tabItems` via `getTransientTabs(availableTabs, currentTabId, tabItems)`.
+7. Define a tab-click handler that sets `currentTabId` to the clicked index and calls `tabClick(index, availableTabs, currentTabId, setCurrentTabId, tabItems)`.
+8. Render: an optional heading (shown when `propsToUse.showLabel` is true, displaying `propsToUse.label`), followed by a tab context wrapping a tab bar (one tab per `tabItems` entry, labeled `tab.name`) and a set of tab panels (each showing `tab.content` or a "No content exists" fallback).
+
+## Behavioral Contract
+
+1. **Inherited settings merge:** `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }`.
+2. **Extract deferred tabs:** `deferLoadedTabs` = first element from children array.
+3. **Compute visible tabs:** On mount and when `availableTabs` changes, call `getVisibleTabs(deferLoadedTabs, 'detailsSubTabs')` to get the filtered visible tab list.
+4. **Local 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)` → sets `currentTabId` to `index` and calls `tabClick(index, availableTabs, currentTabId, setCurrentTabId, tabItems)` from the tab utilities.
+7. **Render:**
+   - If `propsToUse.showLabel`, render a heading with `propsToUse.label`.
+   - Render a tab context bound to `currentTabId`.
+   - Render a tab bar with one tab per `tabItems` entry (keyed by `tab.id`, labeled `tab.name`, valued `tab.id`).
+   - Render one tab panel per `tabItems` entry containing `tab.content` or the fallback text "No content exists".
+
+## Visual Specifications
+
+### Heading
+
+| Property        | Value                           |
+| --------------- | ------------------------------- |
+| Semantic level  | Third-level heading (`<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 a lifecycle effect (not immediately) — this means the initial render uses an empty array, and tabs populate after mount.
+- The lifecycle effect watching `availableTabs` has a stale closure issue in the reference implementation — use an instance reference or memoized computation for production implementations if needed.
+- `tabItems` starts as an empty array — the tab bar renders empty until the first `currentTabId` change triggers `getTransientTabs`.
+- `propsToUse` label/showLabel may be overridden by inherited settings — always use `propsToUse` for the label, not the raw inputs.
+
+## Dependencies
+
+- `getTransientTabs`, `getVisibleTabs`, `tabClick` from the project's SubTabs tab-utility module (framework-independent helpers)
+
+## Design System Mapping
+
+**UI control type:** Tabbed section container for read-only details content.
+
+When implementing in a specific design system, map the following:
+
+- A tab context/wrapper that tracks the active tab
+- A tab bar with clickable tab items
+- Tab panels that show/hide based on active selection
+- `getVisibleTabs` and `getTransientTabs` are tab-utility helpers — use them regardless of UI library
+- Tab content is lazily loaded via the transient tab pattern
+- Optional heading above the tab bar (controlled by `showLabel`)