@pega/sdk 0.0.4 → 0.0.5

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

@@ -6,6 +6,32 @@ Repeating field group template. Renders a list of field group rows from a refere
 
 ---
 
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> This template manages a repeating list of field groups with add/delete actions. It MUST NOT be reduced to a simple delegation to `FieldGroup` or `FieldGroupList`. The following are MANDATORY:
+>
+> 1. `getReferenceList(pConn)` from `../../helpers/field-group-utils` — resolves the reference list path
+> 2. `buildView(pConn, index, lookForChildInConfig)` from `../../helpers/field-group-utils` — builds each row's view
+> 3. `pConn.setReferenceList(resolvedList)` — sets the reference list on PConnect
+> 4. `pConn.getListActions().initDefaultPageInstructions(resolvedList)` — initializes list instructions
+> 5. `useLayoutEffect` for list initialization (not useEffect)
+> 6. Add/delete record handlers using `pConn.getListActions().insert()` and `.deleteEntry()`
+> 7. `useMemo` for `MemoisedChildren` built from `referenceList.map(...)` + `buildView`
+> 8. `allowActions` handling (allowAdd, allowDelete)
+> 9. `isReadonlyMode` check switching between FieldGroupList (edit) and FieldGroup (read-only)
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `getReferenceList` and `buildView` imported from `../../helpers/field-group-utils`
+> - [ ] `pConn.getListActions()` used for insert/delete
+> - [ ] `useLayoutEffect` for `initDefaultPageInstructions`
+> - [ ] `addRecord` and `deleteFieldGroupItem` handlers
+> - [ ] Edit mode → `<FieldGroupList items={...} onAdd={...} onDelete={...} />`
+> - [ ] Read-only mode → `<FieldGroup>` with `buildView` children
+> - [ ] `allowActions` / `allowTableEdit` props respected
+
+---
+
 ## Component Purpose
 
 Renders a repeating list of field group rows sourced from a PConnect reference list. In edit mode, rows can be added and deleted via list actions. In read-only mode (DISPLAY_ONLY), delegates to a read-only `FieldGroup` renderer. Each row is built via `buildView`.
@@ -28,6 +54,99 @@ Renders a repeating list of field group rows sourced from a PConnect reference l
 | `readOnly`       | `boolean`  | No       | Alternative read-only flag                                       |
 | `getPConnect`    | `function` | Yes      | PConnect getter                                                  |
 
+## Component Skeleton
+
+```typescript
+import { useLayoutEffect, useMemo } from 'react';
+import { getReferenceList, buildView } from '../../helpers/field-group-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface FieldGroupTemplateProps extends PConnProps {
+  referenceList?: any[];
+  contextClass: string;
+  renderMode?: string;
+  heading?: string;
+  lookForChildInConfig?: boolean;
+  displayMode?: string;
+  fieldHeader?: string;
+  allowTableEdit: boolean;
+  allowActions?: any;
+}
+
+export default function FieldGroupTemplate(props: FieldGroupTemplateProps) {
+  const FieldGroup = getComponentFromRegistry('FieldGroup');
+  const FieldGroupList = getComponentFromRegistry('FieldGroupList');
+
+  const {
+    referenceList = [], renderMode, contextClass, getPConnect,
+    lookForChildInConfig, heading = '', displayMode, fieldHeader,
+    allowActions, allowTableEdit: allowAddEdit,
+  } = props;
+  const pConn = getPConnect();
+  const resolvedList = getReferenceList(pConn);
+  pConn.setReferenceList(resolvedList);
+  const pageReference = `${pConn.getPageReference()}${resolvedList}`;
+  const isReadonlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY';
+  const HEADING = heading ?? 'Row';
+
+  // 1. Resolve allowAdd/allowDelete from allowActions or allowTableEdit
+  const hasAllowActions = Object.keys(allowActions ?? {}).length > 0;
+  const { allowAdd: actionAdd, allowDelete: actionDelete } = allowActions ?? {};
+  const allowAdd = hasAllowActions ? (actionAdd ?? true) : (allowAddEdit ?? true);
+  const allowDelete = hasAllowActions ? (actionDelete ?? true) : (allowAddEdit ?? true);
+
+  // 2. Init page instructions on mount (edit mode only)
+  useLayoutEffect(() => {
+    if (!isReadonlyMode) {
+      pConn.getListActions().initDefaultPageInstructions(resolvedList);
+    }
+  }, [referenceList?.length]);
+
+  // 3. Dynamic header per row
+  const getDynamicHeaderProp = (item, index) => {
+    if (fieldHeader === 'propertyRef' && heading && item[heading.substring(1)])
+      return item[heading.substring(1)];
+    return `Row ${index + 1}`;
+  };
+
+  // 4. Add/delete handlers
+  const addRecord = () => {
+    if (PCore.getPCoreVersion()?.includes('8.7'))
+      pConn.getListActions().insert({ classID: contextClass }, referenceList.length, pageReference);
+    else pConn.getListActions().insert({}, referenceList.length);
+  };
+  const deleteRecord = (index) => {
+    if (PCore.getPCoreVersion()?.includes('8.7'))
+      pConn.getListActions().deleteEntry(index, pageReference);
+    else pConn.getListActions().deleteEntry(index);
+  };
+
+  // 5. Edit mode: auto-add first row if empty, render FieldGroupList
+  if (!isReadonlyMode) {
+    if (referenceList.length === 0 && allowAdd) addRecord();
+    const items = useMemo(() => referenceList.map((item, index) => ({
+      id: index,
+      name: fieldHeader === 'propertyRef' ? getDynamicHeaderProp(item, index) : `${HEADING} ${index + 1}`,
+      children: buildView(pConn, index, lookForChildInConfig),
+    })), [referenceList?.length]);
+    return <FieldGroupList items={items}
+      onAdd={allowAdd ? addRecord : undefined}
+      onDelete={allowDelete ? deleteRecord : undefined} />;
+  }
+
+  // 6. Read-only mode: FieldGroup per row
+  pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY');
+  const readOnlyList = useMemo(() => referenceList.map((item, index) => (
+    <FieldGroup key={item[heading] || `field-group-row-${index}`}
+      name={fieldHeader === 'propertyRef' ? getDynamicHeaderProp(item, index) : `${HEADING} ${index + 1}`}>
+      {buildView(pConn, index, lookForChildInConfig)}
+    </FieldGroup>
+  )), []);
+  return <div>{readOnlyList}</div>;
+}
+```
+
 ## Behavioral Contract
 
 ### Read-Only Mode

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

@@ -24,6 +24,51 @@ Renders a multi-step form where each section is a tab. Tabs display error badges
 | `instructions` | `string`      | No       | HTML instruction text shown above the tab bar |
 | `getPConnect`  | `function`    | Yes      | PConnect getter                               |
 
+## Component Skeleton
+
+```typescript
+import { type PropsWithChildren } from 'react';
+import { useHierarchicalForm, type HierarchicalFormProps } from './hooks';
+
+export default function HierarchicalForm(props: PropsWithChildren<HierarchicalFormProps>) {
+  // 1. Custom hook handles: active tab, tab click, error counts, instructions, processed tabs
+  const { currentTabId, handleTabClick, processedTabs, instructions } = useHierarchicalForm(props);
+
+  // 2. Guard: no visible tabs
+  if (!currentTabId) return null;
+
+  // 3. Render: instructions + TabContext + Tabs (with error badges) + TabPanels
+  return (
+    <FlexColumn>
+      {instructions && <div dangerouslySetInnerHTML={{ __html: instructions }} />}
+      <TabContext value={currentTabId.toString()}>
+        <TabBar onChange={handleTabClick} value={currentTabId.toString()} variant="scrollable">
+          {processedTabs.map(tab => {
+            const tabLabel = tab.name || tab.label;
+            return (
+              <Tab key={tab.id} value={tab.id?.toString()} label={
+                tab.errors
+                  ? <Tooltip title={`${tabLabel} has errors`}>
+                      <span>{tabLabel} <Badge badgeContent={tab.errors} color="error" /></span>
+                    </Tooltip>
+                  : tabLabel
+              } />
+            );
+          })}
+        </TabBar>
+        {processedTabs.map(tab => (
+          <TabPanel key={tab.id} value={tab.id?.toString()} tabIndex={+tab.id} keepMounted>
+            {tab.content || 'No content exists'}
+          </TabPanel>
+        ))}
+      </TabContext>
+    </FlexColumn>
+  );
+}
+```
+
+> **Key implementation note:** All tab logic (active tab persistence, error counting, tab filtering) is encapsulated in the `useHierarchicalForm` hook. Implement that hook separately — it uses `PCore.getNavigationUtils()` for tab persistence and `useGetTabsCount` for error tracking.
+
 ## Behavioral Contract
 
 ### Hook: `useHierarchicalForm`

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

@@ -25,6 +25,47 @@ Renders an inline dashboard layout consisting of a title heading, a main content
 | `children`       | `ReactNode[]` | Yes      | `children[0]` = main content, `children[1]` = filter panel                    |
 | `getPConnect`    | `function`    | Yes      | PConnect getter                                                               |
 
+## Component Skeleton
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface InlineDashboardProps extends PConnProps {
+  title: string;
+  filterPosition?: string;
+}
+
+export default function InlineDashboard(props: PropsWithChildren<InlineDashboardProps>) {
+  const { children, title, filterPosition } = props;
+  const childrenToRender = children as ReactElement[];
+
+  // 1. Direction for side layout
+  const direction = filterPosition === 'inline-start' ? 'row-reverse' : 'row';
+
+  // 2. Render: title + layout based on filterPosition
+  return (
+    <>
+      <Heading variant="h4">{title}</Heading>
+
+      {filterPosition === 'block-start' ? (
+        // Stacked: filter above content (column-reverse so filter renders visually above)
+        <GridContainer direction="column-reverse">
+          <GridItem xs={12}>{childrenToRender[0]}</GridItem>
+          <GridItem id="filters" xs={12}>{childrenToRender[1]}</GridItem>
+        </GridContainer>
+      ) : (
+        // Side: content left, filters right (or reversed if inline-start)
+        <GridContainer direction={direction}>
+          <GridItem xs={9}>{childrenToRender[0]}</GridItem>
+          <GridItem id="filters" xs={3}>{childrenToRender[1]}</GridItem>
+        </GridContainer>
+      )}
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### Title

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

@@ -6,6 +6,26 @@ Inline dashboard page template. Builds filter components from promoted filters m
 
 ---
 
+> ⚠️ **CRITICAL — Must use `buildFilterComponents` from `@pega/sdk-react`**
+>
+> This component MUST use `buildFilterComponents(getPConnect, allFilters)` imported from `@pega/sdk-react` to generate proper filter UI components. Without this, dashboard filters will not render correctly.
+>
+> **Mandatory implementation details:**
+>
+> 1. `import { buildFilterComponents } from '@pega/sdk-react'` — filter component builder
+> 2. `getPConnect().getRawMetadata().children[1]` — extract filter metadata
+> 3. `useEffect` + `useState` for `filterComponents` — build filters on mount
+> 4. Assemble `inlineProps.children[1] = filterComponents` for InlineDashboard
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `buildFilterComponents` imported from `@pega/sdk-react`
+> - [ ] `filterComponents` state populated via `useEffect`
+> - [ ] Filter metadata extracted from `getRawMetadata().children[1]`
+> - [ ] InlineDashboard receives filter components as children
+
+---
+
 ## Component Purpose
 
 Page-level wrapper for the inline dashboard. Extracts promoted filter definitions from the PConnect metadata, builds React filter components from them, and passes them to `InlineDashboard` as the second child (filter panel). The first child (main content) is passed through unchanged.
@@ -27,6 +47,42 @@ Page-level wrapper for the inline dashboard. Extracts promoted filter definition
 | `filterPosition` | `string`      | No       | Filter position: `'block-start'` or side        |
 | `getPConnect`    | `function`    | Yes      | PConnect getter                                 |
 
+## Component Skeleton
+
+```typescript
+import { useMemo, Children, useEffect, useState, type PropsWithChildren } from 'react';
+import { buildFilterComponents, getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface InlineDashboardPageProps extends PConnProps {
+  title: string;
+  icon?: string;
+  filterPosition?: string;
+}
+
+export default function InlineDashboardPage(props: PropsWithChildren<InlineDashboardPageProps>) {
+  const InlineDashboard = getComponentFromRegistry('InlineDashboard');
+  const { children, getPConnect, filterPosition = 'block-start' } = props;
+  const [filterComponents, setFilterComponents] = useState([]);
+  const childArray = useMemo(() => Children.toArray(children), [children]);
+
+  // 1. Build filter components from metadata on mount
+  const allFilters = (getPConnect().getRawMetadata() as any).children[1];
+  useEffect(() => {
+    setFilterComponents(buildFilterComponents(getPConnect, allFilters));
+  }, []);
+
+  // 2. Assemble props for InlineDashboard
+  const inlineProps = { ...props };
+  inlineProps.children = [];
+  inlineProps.children[0] = childArray[0]; // main content
+  inlineProps.children[1] = filterComponents; // built filters
+
+  // 3. Delegate to InlineDashboard
+  return <InlineDashboard {...inlineProps} />;
+}
+```
+
 ## Behavioral Contract
 
 ### Filter Component Construction

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

@@ -30,6 +30,24 @@ All props are forwarded to `ListView`. Key props:
 | `payload`      | `object`   | No       | Query payload                  |
 | `getPConnect`  | `function` | Yes      | PConnect getter                |
 
+## Component Skeleton
+
+Simplest possible template — pure pass-through to `ListView` with one prop override.
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface ListPageProps extends PConnProps {
+  parameters: object;
+}
+
+export default function ListPage(props: ListPageProps) {
+  const ListView = getComponentFromRegistry('ListView');
+  return <ListView {...props} bInForm={false} />;
+}
+```
+
 ## Behavioral Contract
 
 ```tsx