@pega/sdk 0.0.5 → 0.0.7

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

@@ -1,22 +1,16 @@
 # 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 CHILDREN PASS-THROUGH**
+> ⚠️ **CRITICAL — DataReference is a CONTENT-PROJECTION PASS-THROUGH**
 >
-> This component MUST render its React `children` directly. The PConnect bridge already resolves
-> the correct sub-components (Dropdown, AutoComplete, SingleReferenceReadOnly, etc.) and passes
-> them as `children`. DataReference just passes them 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.
 >
-> ```typescript
-> // ✅ CORRECT — simple children pass-through
-> const childArray = Array.isArray(children) ? children : [children].filter(Boolean);
-> return childArray.length === 1 ? childArray[0] : <div>{childArray}</div>;
-> ```
+> 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
@@ -33,13 +27,13 @@ Renders a data reference field that can be displayed as a dropdown, autocomplete
 
 ## 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'` |
@@ -57,34 +51,15 @@ 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                                                                                        |
 
-## Component Skeleton
-
-```typescript
-import { type PropsWithChildren, type ReactElement } from 'react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface DataReferenceProps extends PConnProps {
-  displayMode?: string;
-  selectionMode?: string;
-  displayAs?: string;
-  parameters?: any;
-  hideLabel?: boolean;
-}
-
-export default function DataReference(props: PropsWithChildren<DataReferenceProps>) {
-  // DataReference is a pass-through wrapper.
-  // The PConnect bridge resolves the correct sub-components (Dropdown, AutoComplete,
-  // SingleReferenceReadOnly, MultiReferenceReadOnly, etc.) and passes them as children.
-  // ⚠️ DO NOT call pConn.createComponent() or firstChildPConnect().createComponent() here —
-  // it causes "getPConnect is not a function" errors or infinite recursion.
-  const { children } = props;
-  const childArray = Array.isArray(children) ? children : [children].filter(Boolean);
-
-  return childArray.length === 1
-    ? (childArray[0] as ReactElement ?? null)
-    : <div>{childArray}</div>;
-}
-```
+## 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
 
@@ -92,9 +67,9 @@ export default function DataReference(props: PropsWithChildren<DataReferenceProp
 
 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`)
 
@@ -111,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)`.
@@ -129,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
 
@@ -157,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

@@ -8,92 +8,50 @@ Standard form layout template supporting 1, 2, or 3 column arrangements. Renders
 
 > ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
 >
-> This component REQUIRES the `connectToState` HOC to function. Without it, **form fields will NOT render** because they won't receive visibility and state props from the Redux store.
+> 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 `connectToState` pattern with plain `createElement(PConnectComponent, ...)`. That pattern does not subscribe children to the store and results in invisible/non-functional form fields.
+> **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. `DefaultForm.tsx` — with `connectToState` HOC wrapping each child
-> 2. `utils/index.ts` — containing `mapStateToProps` and `getKeyForMappedField`
-> 3. `DefaultForm.css` — column layout styles (or DS equivalent)
-> 4. `index.tsx` — re-export
+> 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 Redux store via a `connectToState` HOC so visibility and prop updates flow reactively. Instruction HTML is displayed above the form when present.
+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 `component-map.ts`)
+- **Registration key:** `DefaultForm` (in the project's component map)
 - **Category:** Form template
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
-| Prop           | Type       | Required | Description                                              |
+| 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                                          |
 
-## Component Skeleton
-
-```typescript
-import { createElement } from 'react';
-import { getInstructions } from '../../helpers/template-utils';
-import { PConnectComponent } from '@pega/sdk-react';
-import connectToState from '../../helpers/state-utils';
-import { getKeyForMappedField, mapStateToProps } from './utils';
-import type { PConnProps } from '@pega/sdk-react';
-import './DefaultForm.css';
-
-interface DefaultFormProps extends PConnProps {
-  NumCols: string;
-  instructions: string;
-}
-
-// HOC: wraps each field in Redux store subscription
-const Child = connectToState(mapStateToProps)((props) => {
-  const { key, visibility, ...rest } = props;
-  return createElement(PConnectComponent, { ...rest, key, visibility });
-});
-
-export default function DefaultForm(props) {
-  const { getPConnect, NumCols = '1' } = props;
-  const instructions = getInstructions(getPConnect(), props.instructions);
-
-  // 1. Determine CSS class from NumCols
-  const numCols = NumCols || '1';
-  let divClass;
-  switch (numCols) {
-    case '1': divClass = 'psdk-default-form-one-column'; break;
-    case '2': divClass = 'psdk-default-form-two-column'; break;
-    case '3': divClass = 'psdk-default-form-three-column'; break;
-    default: divClass = 'psdk-default-form-one-column'; break;
-  }
-
-  // 2. Unwrap region children (first child is a region → get ITS children)
-  const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
-  const dfChildren = arChildren?.map(kid =>
-    <Child key={getKeyForMappedField(kid)} {...kid} />
-  );
-
-  // 3. Render: optional instructions HTML + column grid of children
-  return (
-    <>
-      {instructions && (
-        <div className="psdk-default-form-instruction-text">
-          <div dangerouslySetInnerHTML={{ __html: instructions }} />
-        </div>
-      )}
-      <div className={divClass}>{dfChildren}</div>
-    </>
-  );
-}
-```
+## 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
 
@@ -102,19 +60,16 @@ export default function DefaultForm(props) {
    - `'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.
+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 `connectToState(mapStateToProps)` HOC wrapping `PConnectComponent`. Map each field:
-   ```
-   arChildren.map((kid) => <Child key={getKeyForMappedField(kid)} {...kid} />)
-   ```
+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 `<div className='psdk-default-form-instruction-text'>` with `dangerouslySetInnerHTML={{ __html: instructions }}`.
-   - Render `<div className={divClass}>{dfChildren}</div>`.
+   - 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 `DefaultForm.css`:
+Derived from companion styles:
 
 ### Column Layouts
 
@@ -134,68 +89,42 @@ Derived from `DefaultForm.css`:
 
 ### Instruction Text
 
-| Property  | Value                                            |
-| --------- | ------------------------------------------------ |
-| CSS class | `psdk-default-form-instruction-text`             |
-| Content   | Raw HTML rendered with `dangerouslySetInnerHTML` |
+| 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.
-- `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`.
+- 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
 
-- `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
-
-## Mandatory File: `utils/index.ts`
-
-You MUST create this file alongside `DefaultForm.tsx`. Without it, the component will not compile.
+- 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
 
-```typescript
-export const mapStateToProps: any = (_, ownProps) => {
-  const { getPConnect } = ownProps;
+## Mandatory File: Utilities Module
 
-  return {
-    visibility: getPConnect().getComputedVisibility(),
-    getPConnect,
-  };
-};
+You MUST create a utilities module alongside the main component file. Without it, the component will not compile. It must export two members:
 
-export const getKeyForMappedField = (field) => {
-  if (Array.isArray(field)) {
-    return field
-      .map((item) => {
-        return getKeyForMappedField(item);
-      })
-      .join('__');
-  }
-
-  const pConnect = field?.getPConnect?.();
-
-  if (pConnect?.meta) {
-    return JSON.stringify(pConnect.meta);
-  }
-
-  return crypto.randomUUID();
-};
-```
+- `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:
 
-- [ ] `connectToState` is imported from `../../helpers/state-utils`
-- [ ] `mapStateToProps` and `getKeyForMappedField` are imported from `./utils`
-- [ ] `const Child = connectToState(mapStateToProps)(...)` is defined OUTSIDE the component function
-- [ ] Each child field is rendered via `<Child key={getKeyForMappedField(kid)} {...kid} />`
-- [ ] `utils/index.ts` file is created with `mapStateToProps` and `getKeyForMappedField`
+- [ ] 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.
@@ -204,18 +133,9 @@ If ANY of these are missing, the form fields will NOT render at runtime.
 
 **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:
+When implementing in a specific design system, map the following:
 
-- `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
+- 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/.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,86 +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                                           |
 
-## Component Skeleton
-
-```typescript
-import { useMemo, Children } from 'react';
-import type { ReactNode } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-
-const COLUMNS_WIDTHS = {
-  'one-column': [12],
-  'two-column': [6, 6],
-  'narrow-wide': [4, 8],
-  'wide-narrow': [8, 4],
-};
-
-export default function DefaultPage({
-  layout = 'one-column', children, enableBanner,
-  heading = '', message = '', imageTheme, backgroundImage = '',
-  backgroundColor = '', tintImage,
-}: DefaultPageProps) {
-  const Banner = getComponentFromRegistry('Banner');
-  const childArray = useMemo(() => Children.toArray(children), [children]);
-
-  // 1. Banner mode
-  if (enableBanner) {
-    return (
-      <Banner
-        variant={layout === 'one-column' ? 'two-column' : layout}
-        a={[childArray[0]]}
-        b={[childArray[1]]}
-        banner={{ variant: imageTheme, backgroundColor, title: heading, message, backgroundImage, tintImage }}
-      />
-    );
-  }
-
-  // 2. Standard grid mode
-  return (
-    <GridContainer spacing={1}>
-      {childArray.map((child, index) => (
-        <GridItem key={index} size={COLUMNS_WIDTHS[layout][index]}>
-          {child}
-        </GridItem>
-      ))}
-    </GridContainer>
-  );
-}
-```
-
-> **Note:** `DefaultPage` does NOT have a `getPConnect` prop — it extends `CommonPageProps`, not `PConnProps`.
+## 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
 
@@ -133,29 +98,21 @@ export default function DefaultPage({
 
 - `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.