@pega/sdk 0.0.3 → 0.0.4

package/templates/react-sdk-reference/.github/prompts/generate-template-components.prompt.md

@@ -11,9 +11,12 @@ Read the user's message carefully. Extract:
 - **Output base path** — the folder where template components should be generated (e.g. `src/components/template/`)
 - **Component list** — which templates to generate (default: all 32 listed below)
 
-Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `.instructions.md` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
 
 Example questions (ask only the ones that are actually missing):
+
 1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
 2. Where should the template components be generated? (e.g. `src/components/template/`)
 
@@ -25,40 +28,40 @@ Once both are known, continue to Step 1.
 
 ### Full component list (default — 32 templates)
 
-| Component | Category |
-|---|---|
-| AdvancedSearch | Page |
-| AppShell | Page |
-| BannerPage | Page |
-| CaseSummary | Page |
-| CaseView | Page |
-| CaseViewActionsMenu | Widget |
-| Confirmation | Page |
-| DataReference | Form |
-| DefaultForm | Form |
-| DefaultPage | Page |
-| Details | Layout |
-| DetailsSubTabs | Layout |
-| DetailsThreeColumn | Layout |
-| DetailsTwoColumn | Layout |
-| DynamicTabs | Navigation |
-| FieldGroupTemplate | Form |
-| HierarchicalForm | Form |
-| InlineDashboard | Page |
-| InlineDashboardPage | Page |
-| ListPage | Page |
-| ListView | Page |
-| MultiReferenceReadOnly | Display |
-| NarrowWide | Layout |
-| OneColumn | Layout |
-| PromotedFilters | Widget |
-| SelfServiceCaseView | Page |
-| SimpleTable | Table |
-| SingleReferenceReadOnly | Display |
-| SubTabs | Navigation |
-| TwoColumn | Layout |
-| WideNarrow | Layout |
-| WssNavBar | Navigation |
+| Component               | Category   |
+| ----------------------- | ---------- |
+| AdvancedSearch          | Page       |
+| AppShell                | Page       |
+| BannerPage              | Page       |
+| CaseSummary             | Page       |
+| CaseView                | Page       |
+| CaseViewActionsMenu     | Widget     |
+| Confirmation            | Page       |
+| DataReference           | Form       |
+| DefaultForm             | Form       |
+| DefaultPage             | Page       |
+| Details                 | Layout     |
+| DetailsSubTabs          | Layout     |
+| DetailsThreeColumn      | Layout     |
+| DetailsTwoColumn        | Layout     |
+| DynamicTabs             | Navigation |
+| FieldGroupTemplate      | Form       |
+| HierarchicalForm        | Form       |
+| InlineDashboard         | Page       |
+| InlineDashboardPage     | Page       |
+| ListPage                | Page       |
+| ListView                | Page       |
+| MultiReferenceReadOnly  | Display    |
+| NarrowWide              | Layout     |
+| OneColumn               | Layout     |
+| PromotedFilters         | Widget     |
+| SelfServiceCaseView     | Page       |
+| SimpleTable             | Table      |
+| SingleReferenceReadOnly | Display    |
+| SubTabs                 | Navigation |
+| TwoColumn               | Layout     |
+| WideNarrow              | Layout     |
+| WssNavBar               | Navigation |
 
 ---
 
@@ -67,6 +70,7 @@ Once both are known, continue to Step 1.
 Read the full contents of `.github/skills/template-components.md`.
 
 This gives you:
+
 - **Layout template pattern** — DS-agnostic grid skeleton with `// [DS GRID]` placeholder; `templateCol` parsing logic; responsive behavior rules
 - **Design System Adaptation section** — how to map the chosen DS's grid/flex primitive to the computed column ratios
 - **Form template pattern** — PConnect bridge via `createElement(createPConnectComponent(), ...)` and `connectToState`; no DS involved
@@ -79,19 +83,51 @@ Keep this context active throughout the entire generation session. Do not re-rea
 
 ## Step 2 — Install and discover the design system (once)
 
-Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Check `package.json` for the DS package
-- Install if missing, including any peer dependencies
-- Report what was installed
+### 2a — Check and install the DS package
+
+Run this command in your terminal:
+
+```bash
+cat package.json | grep "<design-system-package>"
+```
 
-Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Read the DS README from `node_modules`
-- Discover exported layout components (Grid, Columns, Flex, SimpleGrid, etc.) from `dist/index.d.ts`
-- Read prop interfaces for the grid/layout components needed by layout templates
-- Note responsive breakpoint APIs and column sizing conventions
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+
+```bash
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+### 2b — Discover the DS layout API from installed files
 
 > You only need layout-related DS components. Form and page templates do not use the DS.
 
+Run these commands to discover the actual API (do NOT rely on training knowledge):
+
+1. Read the README for correct import paths and usage patterns:
+
+   ```bash
+   cat node_modules/<designSystem>/README.md
+   ```
+
+2. List every exported component — focus on layout primitives (Grid, Columns, Flex, SimpleGrid, Row, Col):
+
+   ```bash
+   grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"
+   ```
+
+3. For every grid/layout component you plan to use, read its prop interface:
+
+   ```bash
+   find node_modules/<designSystem> -name "Grid.d.ts" -o -name "Col.d.ts" -o -name "Flex.d.ts" | head -5
+   grep -A 40 "interface.*Props" <path-from-above>
+   ```
+
+4. Note **responsive breakpoint APIs** and **column sizing conventions** (e.g., 12-column grid, fractional units, span props).
+
+Only use component names and prop names confirmed in these files.
+
 Build a **DS layout API reference** from this discovery. Reuse it for every layout template — do not repeat these commands per component.
 
 ---
@@ -101,7 +137,9 @@ Build a **DS layout API reference** from this discovery. Reuse it for every layo
 For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
 
 If **any** exist, report them all at once and ask:
+
 > "The following N components already exist: [list]. How should I proceed?
+>
 > - **Overwrite all** — replace all existing implementations
 > - **Skip existing** — only generate components that don't exist yet
 > - **Cancel** — stop without generating anything"
@@ -114,43 +152,78 @@ Wait for the user's answer before proceeding. If none exist, continue immediatel
 
 For each component in the resolved list (in the order listed in Step 0):
 
-### 4a — Read the component-specific skill file
-Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
-- Read `.github/skills/template-skills/<ComponentName>.md` fully
-- Identify the template category from the skill file:
-  - **Layout** — uses DS grid primitives from Step 2's API reference
-  - **Form** — uses PConnect bridge + CSS classes; ignore DS
-  - **Page** — uses region extraction + PConnect bridge; ignore DS
-- Pay attention to Behavioral Contract, sub-variants, and any Design System Mapping table
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `.github/skills/template-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component — do not rely solely on the general `template-components.md`.
+
+After reading, extract and keep active:
+
+- **Template category** — Layout (uses DS grid from Step 2) | Form (PConnect bridge + CSS) | Page (region extraction + PConnect bridge)
+- **Behavioral Contract** — sub-variants, region handling, slot rendering logic
+- **Design System Mapping** table — the recommended DS layout primitive (for Layout templates only)
+
+If no skill file exists at that path, use the general pattern from `template-components.md` loaded in Step 1.
+
+⚠️ The general skill file (`template-components.md`) provides the pattern skeletons. The component-specific skill file provides the **exact region structure, sub-variant keys, and rendering logic**. Both are needed — generating from only the general skill will produce templates with wrong region counts or missing sub-variant registrations.
 
 ### 4b — Generate the component files
-Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
-- Create `<outputPath>/<ComponentName>/` directory
-- Create `<ComponentName>.tsx` using:
-  - **Layout templates**: DS-agnostic skeleton from `template-components.md` with the `// [DS GRID]` section filled in using DS layout API confirmed in Step 2
-  - **Form/Page templates**: PConnect bridge pattern from `template-components.md`; no DS primitives
-  - Behavioral Contract from the component skill file
-- Create `index.tsx` if required by the skill file:
-  ```typescript
-  export { default } from './<ComponentName>';
-  ```
-- Create any CSS file required by the skill file (e.g., `DefaultForm.css` with grid classes)
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create `<ComponentName>.tsx` using the structure matching the template category from `template-components.md` (loaded in Step 1):
+
+- **Layout**: `PropsWithChildren` + `templateCol` parsing (split on whitespace, strip units, compute ratios) + DS grid/flex from Step 2 rendering children in computed column ratios. On mobile: columns must stack to full width.
+- **Form**: `createElement(createPConnectComponent(), ...)` for each child from `getPConnect().getChildren()[0].getPConnect().getChildren()`. No DS primitives.
+- **Page**: `createElement(createPConnectComponent(), ...)` for each region from `getPConnect().getChildren()`. No DS primitives.
+
+Apply the Behavioral Contract from the component skill file (sub-variants, region handling, slot logic).
+
+Create `index.tsx` if required by the skill file:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS file required by the skill file (e.g., `DefaultForm.css` with grid classes).
 
 ### 4c — Register the component
-Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
-- Add the import to `src/components/component-map.ts` in the Templates section
-- Add the entry to `getSampleComponentMap()` under the templates comment
-- For sub-variants (e.g., TwoColumnPage, TwoColumnTab), register each key separately pointing to its own file or a shared implementation as specified in the skill file
-- Do not reorder or restructure any existing entries
 
-### 4d — Report progress
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top of the file in the **Templates** section:
+   ```typescript
+   import <ComponentName> from './template/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the templates comment:
+   ```typescript
+   <ComponentName>,
+   ```
+3. For sub-variants (e.g., TwoColumnPage, TwoColumnTab), register each key separately pointing to its own file or a shared implementation as specified in the skill file.
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Batch checkpoint
+
+After every **5 components**, run:
+
+```bash
+npm run build
+```
+
+Fix any TypeScript or build errors before continuing to the next component. This prevents error accumulation.
+
+### 4e — Report progress
+
 After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template`<, using <DS component name> for grid>` if layout"
 
 ---
 
 ## Step 5 — Verify the build
 
-Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Run `npm run build`
-- Fix any TypeScript or build errors before reporting completion
-- Report a summary: list of all files created and all entries added to `component-map.ts`
+Run:
+
+```bash
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report a summary: list of all files created and all entries added to `component-map.ts`.

package/templates/react-sdk-reference/.github/prompts/generate-widget-components.prompt.md

@@ -11,9 +11,12 @@ Read the user's message carefully. Extract:
 - **Output base path** — the folder where widget components should be generated (e.g. `src/components/widget/`)
 - **Component list** — which widgets to generate (default: all 9 listed below)
 
-Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `.instructions.md` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
 
 Example questions (ask only the ones that are actually missing):
+
 1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
 2. Where should the widget components be generated? (e.g. `src/components/widget/`)
 
@@ -23,17 +26,17 @@ Once both are known, continue to Step 1.
 
 ### Full component list (default — 9 widgets)
 
-| Component | Description |
-|---|---|
-| AppAnnouncement | System-wide announcements |
-| Attachment | File upload/download |
-| CaseHistory | Case audit trail |
-| FileUtility | File management utility |
-| Followers | Case followers list |
-| QuickCreate | Quick case creation buttons |
-| SummaryItem | Single summary card |
-| SummaryList | List of summary cards |
-| ToDo | Assignment worklist |
+| Component       | Description                 |
+| --------------- | --------------------------- |
+| AppAnnouncement | System-wide announcements   |
+| Attachment      | File upload/download        |
+| CaseHistory     | Case audit trail            |
+| FileUtility     | File management utility     |
+| Followers       | Case followers list         |
+| QuickCreate     | Quick case creation buttons |
+| SummaryItem     | Single summary card         |
+| SummaryList     | List of summary cards       |
+| ToDo            | Assignment worklist         |
 
 ---
 
@@ -42,6 +45,7 @@ Once both are known, continue to Step 1.
 Read the full contents of `.github/skills/widget-components.md`.
 
 This gives you:
+
 - The DS-agnostic data-fetching skeleton with `// [DS RENDER]` placeholder
 - The Design System Adaptation guide (primitive mapping table, icon discovery rules)
 - All common Pega APIs used in widgets: `PCore.getDataPageUtils()`, `PCore.getMashupApi()`, `PCore.getAttachmentUtils()`, `pConn.getCaseInfo()`, etc.
@@ -55,17 +59,52 @@ Keep this context active throughout the entire generation session. Do not re-rea
 
 ## Step 2 — Install and discover the design system (once)
 
-Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Check `package.json` for the DS package
-- Install if missing, including any peer dependencies
-- Report what was installed
+### 2a — Check and install the DS package
+
+Run this command in your terminal:
+
+```bash
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+
+```bash
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+### 2b — Discover the DS API from installed files
+
+Run these commands to discover the actual API (do NOT rely on training knowledge):
+
+1. Read the README for correct import paths and usage patterns:
 
-Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Read the DS README from `node_modules`
-- Discover exported components from `dist/index.d.ts`
-- Focus on presentation primitives used in widgets: Card, List, Table, Button, Badge, Spinner, Skeleton, Empty state
-- Read prop interfaces for these components from `.d.ts` files
-- If the DS has a companion icon package, discover its exports
+   ```bash
+   cat node_modules/<designSystem>/README.md
+   ```
+
+2. List every exported component:
+
+   ```bash
+   grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"
+   ```
+
+3. For every component you plan to use (Card, List, Table, Button, Badge, Spinner), read its prop interface:
+
+   ```bash
+   find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3
+   grep -A 40 "interface.*Props" <path-from-above>
+   ```
+
+4. Check for a **companion icon package** — if it exists, read its exports before using any icon name. Never guess icon names.
+
+5. Check for **size/variant conventions** — use built-in props rather than custom padding.
+
+6. Check for **CSS tokens** — use design system CSS custom properties for spacing; never hardcode `px` values.
+
+Only use component names and prop names confirmed in these files.
 
 Build a **DS UI primitive reference map** from this discovery. Reuse it for every widget — do not repeat these commands per component.
 
@@ -76,7 +115,9 @@ Build a **DS UI primitive reference map** from this discovery. Reuse it for ever
 For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
 
 If **any** exist, report them all at once and ask:
+
 > "The following N components already exist: [list]. How should I proceed?
+>
 > - **Overwrite all** — replace all existing implementations
 > - **Skip existing** — only generate components that don't exist yet
 > - **Cancel** — stop without generating anything"
@@ -89,41 +130,79 @@ Wait for the user's answer before proceeding. If none exist, continue immediatel
 
 For each component in the resolved list (in the order listed in Step 0):
 
-### 4a — Read the component-specific skill file
-Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
-- Read `.github/skills/widget-skills/<ComponentName>.md` fully if it exists
-- Pay attention to:
-  - **Behavioral Contract** — data fetching logic, PCore API calls, state management, action handlers
-  - **Design System Mapping** table — the recommended DS component for presentation
-- If no skill file exists (e.g., `SummaryList`), use the general data-fetching pattern from `widget-components.md`
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `.github/skills/widget-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `widget-components.md`.
+
+After reading, extract and keep active:
+
+- **Behavioral Contract** — the exact PCore API calls, state variables, event handlers, and edge cases specific to this widget
+- **Design System Mapping** table — the recommended DS primitive for this component's presentation layer
+- **Props interface** — any required/optional props beyond the base `PConnProps`
+
+If no skill file exists at that path (e.g., `SummaryList`), use the general data-fetching pattern from `widget-components.md` loaded in Step 1.
+
+⚠️ The general skill file (`widget-components.md`) provides the skeleton. The component-specific skill file provides the **exact data flow and behavioral logic**. Both are needed — generating from only the general skill will produce components that render but don't fetch or display data correctly.
 
 ### 4b — Generate the component files
-Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
-- Create `<outputPath>/<ComponentName>/` directory
-- Create `<ComponentName>.tsx` using:
-  - The DS-agnostic data-fetching skeleton from `widget-components.md` (read in Step 1)
-  - The Behavioral Contract from the component skill file (PCore API calls, state, actions)
-  - The DS UI primitives confirmed in Step 2 (from the DS primitive reference map — no new terminal commands needed) filling in the `// [DS RENDER]` section
-- Create `index.tsx` if required by the skill file:
-  ```typescript
-  export { default } from './<ComponentName>';
-  ```
-- Create any CSS or utility files required by the skill file
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create `<ComponentName>.tsx` using this structure from `widget-components.md` (loaded in Step 1):
+
+1. Imports (React hooks + DS components from Step 2 + `PConnProps` from `@pega/sdk-react`)
+2. Interface extending PConnProps with props from the component skill file's Props table
+3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
+4. `useEffect` → data fetch using the exact PCore API call from the skill file's Behavioral Contract
+5. Return → DS Card/List/Table primitive from Step 2 API map, rendering the fetched data
+
+Fill in the `// [DS RENDER]` section with DS primitives confirmed in Step 2. The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls.
+
+Create `index.tsx`:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS or utility files required by the skill file.
 
 ### 4c — Register the component
-Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
-- Add the import to `src/components/component-map.ts` in the Widgets section
-- Add the entry to `getSampleComponentMap()` under the widgets comment
-- Do not reorder or restructure any existing entries
 
-### 4d — Report progress
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top of the file in the **Widgets** section:
+   ```typescript
+   import <ComponentName> from './widget/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the widgets comment:
+   ```typescript
+   <ComponentName>,
+   ```
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Batch checkpoint
+
+After every **5 components**, run:
+
+```bash
+npm run build
+```
+
+Fix any TypeScript or build errors before continuing to the next component. This prevents error accumulation.
+
+### 4e — Report progress
+
 After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
 
 ---
 
 ## Step 5 — Verify the build
 
-Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
-- Run `npm run build`
-- Fix any TypeScript or build errors before reporting completion
-- Report a summary: list of all files created and all entries added to `component-map.ts`
+Run:
+
+```bash
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report a summary: list of all files created and all entries added to `component-map.ts`.