@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,198 @@
+# Skill: Confirmation
+
+Case confirmation template. Renders the post-submission confirmation view with a Done button, optionally showing ToDo assignments that remain after the case is submitted.
+
+> **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**
+>
+> The close event MUST use `PCore.getContainerUtils()` to get the proper container info for the pub/sub payload. Without this, the confirmation view won't close properly and the case won't transition correctly.
+>
+> **Mandatory implementation details:**
+>
+> 1. `PCore.getContainerUtils().getActiveContainerItemName(getPConnect().getTarget())` — gets active container item
+> 2. `PCore.getContainerUtils().getContainerItemData(target, activeItemID)` — gets root info for close event
+> 3. `PCore.getPubSubUtils().publish(CONSTS.PUB_SUB_EVENTS.CASE_EVENTS.CLOSE_CONFIRM_VIEW, rootInfo)` — proper close event with payload
+> 4. `getComponentFromRegistry('Details')` — for rendering case details in confirmation
+> 5. `getToDoAssignments(getPConnect())` — from `PCore.getSDKUtils().getSDKContainerUtils()`
+> 6. Check `showDetails` before rendering Details component
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `PCore.getContainerUtils()` used for close event (NOT a simple `setShowConfirmView(false)`)
+> - [ ] `rootInfo` passed to `CLOSE_CONFIRM_VIEW` pub/sub event
+> - [ ] Details component rendered when `showDetails` is true
+> - [ ] ToDo component rendered with `getToDoAssignments` when `showTasks` is true
+> - [ ] Two render states: confirmation view (with Done button) and post-close (just ToDo if any)
+
+---
+
+## Component Purpose
+
+Displayed after a case or assignment is submitted. Shows the confirmation view (with `Details` region) and a Done button. If outstanding ToDo assignments remain after the user clicks Done, they are displayed. When the user truly finishes, publishes `CLOSE_CONFIRM_VIEW` to close the container.
+
+## Pega Metadata
+
+- **Registration key:** `Confirmation` (in `component-map.ts`)
+- **Category:** Page template — confirmation
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop          | Type          | Required | Description                                                                   |
+| ------------- | ------------- | -------- | ----------------------------------------------------------------------------- |
+| `children`    | `ReactNode[]` | Yes      | Region children: `[0]` = ToDo region, `[1]` = Details region (when available) |
+| `getPConnect` | `function`    | Yes      | PConnect getter                                                               |
+
+## Component Skeleton
+
+```typescript
+import { type PropsWithChildren, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface ConfirmationProps extends PConnProps {
+  datasource: { source: any };
+  label: string;
+  showLabel: boolean;
+  showTasks: boolean;
+}
+
+export default function Confirmation(props: PropsWithChildren<ConfirmationProps>) {
+  const ToDo = getComponentFromRegistry('Todo'); // NOTE: 'Todo' not 'ToDo'
+  const Details = getComponentFromRegistry('Details');
+
+  const CONSTS = PCore.getConstants();
+  const [showConfirmView, setShowConfirmView] = useState(true);
+  const { showTasks, getPConnect, showLabel, label } = props;
+
+  // 1. Get active container + root info
+  const activeContainerItemID = PCore.getContainerUtils()
+    .getActiveContainerItemName(getPConnect().getTarget() || '');
+  const rootInfo = PCore.getContainerUtils()
+    .getContainerItemData(getPConnect().getTarget(), activeContainerItemID);
+
+  // 2. Get todo assignments
+  const { getToDoAssignments } = PCore.getSDKUtils().getSDKContainerUtils();
+  const toDoList = getToDoAssignments(getPConnect());
+
+  // 3. Done button handler
+  const onConfirmViewClose = () => {
+    setShowConfirmView(false);
+    PCore.getPubSubUtils().publish(
+      PCore.getConstants().PUB_SUB_EVENTS.CASE_EVENTS.CLOSE_CONFIRM_VIEW, rootInfo
+    );
+  };
+
+  // 4. Show details check
+  const showDetails = props.children?.[0]?.props?.getPConnect()?.getChildren()?.length > 0;
+
+  // 5. Render: confirm view OR todo view
+  if (showConfirmView) {
+    return (
+      <Card>
+        <h2>{showLabel ? label : ''}</h2>
+        {showDetails && <Details {...props} showLabel={false} />}
+        {showTasks && toDoList?.length > 0 && (
+          <ToDo datasource={{ source: toDoList }} getPConnect={getPConnect}
+            type={CONSTS.TODO} headerText="Open Tasks" isConfirm />
+        )}
+        <DoneButton onClick={onConfirmViewClose}>Done</DoneButton>
+      </Card>
+    );
+  }
+  return toDoList?.length > 0 ? (
+    <Card>
+      <ToDo datasource={{ source: toDoList }} getPConnect={getPConnect}
+        type={CONSTS.TODO} headerText="Tasks" isConfirm />
+    </Card>
+  ) : null;
+}
+```
+
+## Behavioral Contract
+
+### State
+
+- `showConfirmView`: boolean, initially `true`.
+- `toDoAssignments`: array from `getToDoAssignments(getPConnect())` — pending assignments.
+
+### Done Button Click
+
+1. Call `getPConnect().getContainerManager().closeContainerItem(getPConnect().getContainerName())`.
+2. OR call `PCore.getContainerUtils().getActiveContainerItemName(getPConnect().getContainerName())`.
+3. Check remaining `toDoAssignments`.
+4. If assignments remain: `setShowConfirmView(false)` — show ToDo view instead.
+5. If no assignments remain: publish `PCore.getPubSubUtils().publish(CLOSE_CONFIRM_VIEW, {})`.
+
+### Show Details
+
+- `showDetails`: `children.length > 1` — true when a Details region is present.
+
+### Render: Confirm View (`showConfirmView === true`)
+
+1. Confirmation message header (localized `"Your submission is confirmed"` or equivalent).
+2. If `showDetails`: render `children[1]` (Details region) using `createElement(PConnectComponent, ...)`.
+3. Done button (`localized "Done"`) — triggers done click handler above.
+
+### Render: ToDo View (`showConfirmView === false`)
+
+- Render `children[0]` (ToDo region) using `createElement(PConnectComponent, ...)`.
+
+## Visual Specifications
+
+### Confirm View
+
+| Element             | Description                                   |
+| ------------------- | --------------------------------------------- |
+| Confirmation header | Success icon + heading text                   |
+| Details section     | Optional — rendered below confirmation header |
+| Done button         | Primary button, bottom of the form            |
+
+**CSS-only implementation notes:**
+
+- Confirm view: `display: flex; flex-direction: column; align-items: center; gap: 1.5rem; padding: 2rem`.
+- Success icon: large checkmark or success indicator, centered.
+- Confirmation heading: `font-size: 1.5rem; font-weight: 600; text-align: center`.
+- Done button: `align-self: flex-end` or centered.
+
+### ToDo View
+
+- Full-width ToDo region rendered in place of confirmation.
+- No additional wrapping — render the region directly.
+
+## Edge Cases & Special Logic
+
+- `getToDoAssignments(getPConnect())` — returns empty array if no assignments remain; triggers close publish immediately.
+- `children[1]` may not exist — always check `showDetails` before rendering.
+- `CLOSE_CONFIRM_VIEW` is a PubSub constant — ensure it matches the consuming container's subscription key.
+- The confirmation view should not be navigable backward — Done is the only exit.
+
+## Dependencies
+
+- `getToDoAssignments` from `../../helpers/case-utils` (or equivalent)
+- `PCore.getPubSubUtils().publish()` — for CLOSE_CONFIRM_VIEW event
+- `PCore.getContainerUtils()` — for container item management
+- `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Post-submission confirmation page with done action and optional todo view.
+
+Listed design systems are examples only.
+
+| Design System      | Success Indicator              | Done Button                    | Layout                                        |
+| ------------------ | ------------------------------ | ------------------------------ | --------------------------------------------- |
+| Default (CSS only) | CSS checkmark SVG              | `<button class='primary'>`     | Centered flexbox column                       |
+| MUI                | `<CheckCircleIcon>`            | `<Button variant='contained'>` | `<Box display='flex' flexDirection='column'>` |
+| Ant Design         | `<Result status='success'>`    | `<Button type='primary'>`      | Ant Result component                          |
+| Chakra UI          | `<CheckCircleIcon>` + `<Text>` | `<Button colorScheme='blue'>`  | `<VStack>`                                    |
+| Shadcn/ui          | Custom icon + `<h2>`           | `<Button>`                     | Tailwind centered div                         |
+
+When implementing in a specific design system:
+
+- Done button must check remaining `toDoAssignments` before deciding whether to show ToDo view or close
+- `CLOSE_CONFIRM_VIEW` publish must happen only after confirming no assignments remain
+- `showDetails` check must guard `children[1]` access

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

@@ -0,0 +1,174 @@
+# 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.
+
+> **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**
+>
+> 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.
+>
+> ```typescript
+> // ✅ CORRECT — simple children pass-through
+> const childArray = Array.isArray(children) ? children : [children].filter(Boolean);
+> return childArray.length === 1 ? childArray[0] : <div>{childArray}</div>;
+> ```
+>
+> ❌ **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`)
+- **Category:** Form template — data selection
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop                 | Type       | Required | Description                                                                                            |
+| -------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `label`              | `string`   | Yes      | Field label                                                                                            |
+| `displayAs`          | `string`   | Yes      | UI variant: `'dropdown'`, `'autocomplete'`, `'checkbox'`, `'radiobutton'`, `'listview'`, `'searchbox'` |
+| `selectionMode`      | `string`   | Yes      | `'single'` or `'multi'`                                                                                |
+| `displayMode`        | `string`   | No       | `'DISPLAY_ONLY'` for read-only rendering                                                               |
+| `readOnly`           | `boolean`  | No       | Alternative read-only flag                                                                             |
+| `ruleClass`          | `string`   | Yes      | Data page class reference                                                                              |
+| `dataRelationship`   | `string`   | No       | Relationship type                                                                                      |
+| `isDDSourceDeferred` | `boolean`  | No       | Whether data source is loaded asynchronously                                                           |
+| `parameters`         | `object`   | No       | Parameters passed to the data page for deferred sources                                                |
+| `allowSearch`        | `boolean`  | No       | Show search input inside dropdown/autocomplete                                                         |
+| `searchIcon`         | `boolean`  | No       | Show search icon in the field                                                                          |
+| `numCols`            | `string`   | No       | Column count for checkbox/radiobutton layouts: `'1'`, `'2'`, `'3'`                                     |
+| `listType`           | `string`   | No       | `'associated'` or `'datapage'`                                                                         |
+| `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>;
+}
+```
+
+## 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`.
+
+### Edit Routing (by `displayAs`)
+
+| `displayAs`      | Rendered component                        |
+| ---------------- | ----------------------------------------- |
+| `'dropdown'`     | Registered `Dropdown` field component     |
+| `'autocomplete'` | Registered `AutoComplete` field component |
+| `'checkbox'`     | Registered `CheckboxGroup` with `numCols` |
+| `'radiobutton'`  | Registered `RadioButtons` with `numCols`  |
+| `'listview'`     | Inline `ListView` sub-component           |
+| `'searchbox'`    | Inline `SearchForm` sub-component         |
+| Default          | `Dropdown`                                |
+
+### 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`.
+
+### Localized Placeholder
+
+- Generate a localized "Please select..." option via `localizedPlaceholderOption` using `PCore.getLocaleUtils().getLocaleValue(...)`.
+- Prepend this option to `dropDownDataSource` for dropdown/autocomplete variants.
+
+### SearchForm Sub-Component
+
+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)`.
+3. Renders the search results list below the input using `buildView`.
+
+## 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`.
+- Dropdown/Autocomplete: standard select input, full-width.
+- Checkbox/Radio group: grid layout matching `numCols`.
+- SearchForm: `display: flex; gap: 8px` (input + search button).
+
+## Edge Cases & Special Logic
+
+- `isDDSourceDeferred` — data is not available synchronously; show a loading indicator until `dropDownDataSource` 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()`.
+- 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`
+- `PCore.getDataApiUtils().getData()` — for deferred data source fetch
+- `PCore.getLocaleUtils().getLocaleValue()` — for localized placeholder
+
+## Design System Mapping
+
+**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:
+
+- 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
+- `numCols` applies to checkbox and radiobutton layouts only

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

@@ -0,0 +1,221 @@
+# 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 `connectToState` HOC to function. Without it, **form fields will NOT render** because they won't receive visibility and state props from the Redux 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.
+>
+> **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
+
+---
+
+## 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                                          |
+
+## 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>
+    </>
+  );
+}
+```
+
+## 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
+
+## Mandatory File: `utils/index.ts`
+
+You MUST create this file alongside `DefaultForm.tsx`. Without it, the component will not compile.
+
+```typescript
+export const mapStateToProps: any = (_, ownProps) => {
+  const { getPConnect } = ownProps;
+
+  return {
+    visibility: getPConnect().getComputedVisibility(),
+    getPConnect,
+  };
+};
+
+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();
+};
+```
+
+## 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`
+- [ ] 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.
+
+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