@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/prompts/generate-field-components.md

@@ -73,29 +73,33 @@ Keep this context active throughout the entire generation session. Do not re-rea
 
 ## Step 2 — Install and discover the design system (once)
 
-### 2a — Check and install the DS package
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
 
-Run this command in your terminal:
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
 
-```bash
-cat package.json | grep "<design-system-package>"
-```
+You MUST also thoroughly inspect the installed design system package:
 
-If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+1. **Discover all available components** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every input control the package actually provides (Input, Select, Checkbox, DatePicker, Radio, etc.). Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map each field component to the best available DS component** — the component names in the list (e.g. `AutoComplete`, `Dropdown`) may not have an exact name match in the installed design system. Using the complete list you just discovered, identify which DS component best serves the same purpose. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every component you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
 
-```bash
-npm install <design-system-package>
-```
+Also check:
 
-Also install any peer dependencies documented in the package's README. Report what was installed.
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
 
-### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+Build a **DS API reference map** from this discovery. You will reuse it for every component — do not repeat this discovery per component.
+
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
 
 Design systems require their global stylesheet — without it, components render unstyled.
 
-#### Known DS style requirements (examples — verify from README for exact paths):
+#### Known DS style requirements (examples — verify against the README you already read):
 
-| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| Design System | Styles Package (example) | CSS Import (example)                     | Provider Wrapper (example) |
 | ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
 | Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
 | Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
@@ -104,53 +108,20 @@ Design systems require their global stylesheet — without it, components render
 | Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
 | MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
 
-These are **examples** based on common versions. Always verify the exact import path and provider name from the installed package's README (`node_modules/<ds>/README.md`).
-
-If in table: install styles package (if separate), add CSS import as **first import** in `src/main.tsx`, add Provider in `src/AppProviders.tsx`.
-If not in table: check README and `find node_modules/<ds> -name "*.css" -path "*/dist/*" | head -5`.
-
-Verification: `grep -n "import.*css\|import.*styles" src/main.tsx` must return a result. Do NOT proceed until confirmed.
-
-Report what was installed and configured.
-
-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:
-
-   ```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"
-   ```
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
 
-3. For every input control you plan to use (Input, Select, Checkbox, DatePicker, Radio, etc.), read its prop interface:
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
 
-   ```bash
-   find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3
-   grep -A 40 "interface.*Props" <path-from-above>
-   ```
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
 
-4. Check for a **form layout wrapper** (label + input + helper text) — e.g., `<Form.Item>` in Ant Design, `<FormControl>` in Chakra UI. Use it instead of manual margins.
-
-5. Check for **size/density/variant conventions** — use built-in props rather than custom padding.
-
-6. Check for a **companion icons package** — read its exports before using any icon name. Never guess icon names.
-
-7. 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 API reference map** from this discovery. You will reuse it for every component — do not repeat these commands per component.
+Report what was installed/configured (or "already configured").
 
 ---
 
 ## Step 3 — Overwrite check (all at once)
 
-For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+For each component in the list, check whether the component's file or directory already exists at the output path.
 
 If **any** exist, report them all at once and ask:
 
@@ -186,34 +157,20 @@ If no skill file exists at that path, use the general behavioral skeleton from `
 
 Create the directory `<outputPath>/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using this structure from `field-components.md` (loaded in Step 1):
-
-1. Imports (React hooks + `handleEvent` from `../../helpers/event-utils` + `getComponentFromRegistry` from `@pega/sdk-react` + `PConnFieldProps` + DS input from Step 2)
-2. Interface extending `PConnFieldProps` with any extra props from the component skill file
-3. Destructure: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
-4. Display mode guards: if `DISPLAY_ONLY` or `STACKED_LARGE_VAL` → return `FieldValueList`
-5. Return → DS form input from Step 2, with `onBlur` calling `handleEvent(actions, 'changeNblur', propName, inputValue)`
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
 
-Pass `data-test-id={testId}` on the underlying interactive element.
+Follow the implementation structure described in `field-components.md` (loaded in Step 1). That file specifies the exact imports, interface, props handling, display mode guards, event handling, and render approach for this project's framework. Use the DS component you identified in Step 2 as the primary input element.
 
-Create `index.tsx`:
+Apply the Behavioral Contract from the component skill file (state management, option loading, event sequences, edge cases specific to this component).
 
-```typescript
-export { default } from './<ComponentName>';
-```
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
 
 ### 4c — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file (the file that maps component names to their implementations) and:
 
-1. Add an import at the top of the file in the **Fields** section:
-   ```typescript
-   import <ComponentName> from './field/<ComponentName>';
-   ```
-2. Add an entry in the return object of `getSampleComponentMap()` under the fields comment:
-   ```typescript
-   <ComponentName>,
-   ```
+1. Add an import at the top of the file in the **Fields** section
+2. Add an entry in the component map object under the fields comment
 
 ⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping:
 
@@ -230,10 +187,4 @@ After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
 
 ## Step 5 — Verify the build
 
-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`.
+Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.

package/templates/react-sdk-reference/.ai-common/prompts/generate-template-components.md

@@ -72,10 +72,10 @@ Read the full contents of `{{SKILL_DIR}}/template-components.md`.
 
 This gives you:
 
-- **Layout template pattern** — DS-agnostic grid skeleton with `// [DS GRID]` placeholder; `templateCol` parsing logic; responsive behavior rules
+- **Layout template pattern** — DS-agnostic grid skeleton; column-ratio 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 `connectToState` HOC wrapping `PConnectComponent`; `utils/index.ts` with `mapStateToProps`; no DS involved
-- **Page template pattern** — region extraction via `getRawMetadata()` and PConnect bridge; complex PCore API interactions; no DS involved
+- **Form template pattern** — PConnect bridge using a higher-order state-subscription pattern; a companion utilities module; no DS involved
+- **Page template pattern** — region extraction and PConnect bridge; complex API interactions with the underlying engine; no DS involved
 - Registration conventions and helper utilities
 
 Keep this context active throughout the entire generation session. Do not re-read it per component.
@@ -84,29 +84,28 @@ Keep this context active throughout the entire generation session. Do not re-rea
 
 ## Step 2 — Install and discover the design system (once)
 
-### 2a — Check and install the DS package
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
 
-Run this command in your terminal:
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
 
-```bash
-cat package.json | grep "<design-system-package>"
-```
+> You only need layout-related DS components. Form and page templates do not use the DS.
 
-If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+You MUST also thoroughly inspect the installed design system package, focusing on layout primitives (Grid, Columns, Flex, SimpleGrid, Row, Col):
 
-```bash
-npm install <design-system-package>
-```
+1. **Discover all available layout primitives** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every layout primitive the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map the layout templates to the best available DS layout primitive** — identify which DS component best serves grid/column layout needs. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every layout primitive you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Pay special attention to **responsive breakpoint APIs** and **column sizing conventions** (e.g., 12-column grid, fractional units, span props). Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
 
-Also install any peer dependencies documented in the package's README. Report what was installed.
+Build a **DS layout API reference** from this discovery. Reuse it for every layout template — do not repeat this discovery per component.
 
-### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
 
 Design systems require their global stylesheet — without it, components render unstyled.
 
-#### Known DS style requirements (examples — verify from README for exact paths):
+#### Known DS style requirements (examples — verify against the README you already read):
 
-| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| Design System | Styles Package (example) | CSS Import (example)                     | Provider Wrapper (example) |
 | ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
 | Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
 | Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
@@ -115,49 +114,20 @@ Design systems require their global stylesheet — without it, components render
 | Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
 | MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
 
-These are **examples** based on common versions. Always verify the exact import path and provider name from the installed package's README (`node_modules/<ds>/README.md`).
-
-If in table: install styles package (if separate), add CSS import as **first import** in `src/main.tsx`, add Provider in `src/AppProviders.tsx`.
-If not in table: check README and `find node_modules/<ds> -name "*.css" -path "*/dist/*" | head -5`.
-
-Verification: `grep -n "import.*css\|import.*styles" src/main.tsx` must return a result. Do NOT proceed until confirmed.
-
-Report what was installed and configured.
-
-> 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):
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
 
-   ```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"
-   ```
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
 
-3. For every grid/layout component you plan to use, read its prop interface:
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
 
-   ```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.
+Report what was installed/configured (or "already configured").
 
 ---
 
 ## Step 3 — Overwrite check (all at once)
 
-For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+For each component in the list, check whether the component's file or directory already exists at the output path.
 
 If **any** exist, report them all at once and ask:
 
@@ -193,21 +163,19 @@ If no skill file exists at that path, use the general pattern from `template-com
 
 Create the directory `<outputPath>/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using the structure matching the template category from `template-components.md` (loaded in Step 1):
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
 
-- **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**: Use the `connectToState` HOC pattern from the skill file. Each child field MUST be wrapped in `connectToState(mapStateToProps)` for Redux store subscription. Plain `createElement(PConnectComponent, ...)` without `connectToState` will cause fields to NOT render. Also create `utils/index.ts` with `mapStateToProps` and `getKeyForMappedField`.
-- **Page**: The generated component MUST include ALL props, side effects, PCore API calls, useEffect hooks, and state management from the skill file's Component Skeleton. Page templates are complex — they interact with PCore APIs and infrastructure components. NEVER simplify a Page template to a single return statement or a pass-through wrapper.
+Follow the implementation structure described in `template-components.md` (loaded in Step 1) for the component's template category, as identified in Step 4a:
 
-⚠️ **CRITICAL RULE for Form and Page templates:** The component-specific skill file's Component Skeleton is the **minimum implementation**. You must include every `useState`, `useEffect`, `getComponentFromRegistry`, `PCore.*` call, helper function, and utility import shown in that skeleton. If your generated output is significantly shorter than the skeleton, you have over-simplified and MUST add the missing logic.
+- **Layout**: column-ratio parsing (split on whitespace, strip units, compute ratios) + the DS grid/flex primitive from Step 2, rendering children in computed column ratios. On mobile: columns must stack to full width.
+- **Form**: use the higher-order state-subscription pattern described in the skill file so that each child field is properly wired into the project's state management. Also create the companion utilities module described in the skill file.
+- **Page**: the generated component MUST include ALL props, side effects, API calls, lifecycle hooks, and state management from the skill file's Component Skeleton. Page templates are complex — they interact with the underlying engine's APIs and infrastructure components. NEVER simplify a Page template to a single return statement or a pass-through wrapper.
 
-Apply the Behavioral Contract from the component skill file (sub-variants, region handling, slot logic).
+⚠️ **CRITICAL RULE for Form and Page templates:** The component-specific skill file's Component Skeleton is the **minimum implementation**. You must include every state variable, lifecycle hook, registry lookup, engine API call, helper function, and utility import shown in that skeleton. If your generated output is significantly shorter than the skeleton, you have over-simplified and MUST add the missing logic.
 
-Create `index.tsx` if required by the skill file:
+Apply the Behavioral Contract from the component skill file (sub-variants, region handling, slot logic).
 
-```typescript
-export { default } from './<ComponentName>';
-```
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
 
 Create any CSS file required by the skill file (e.g., `DefaultForm.css` with grid classes).
 
@@ -217,9 +185,9 @@ Create any `utils/` or helper files mandated by the skill file (e.g., `utils/ind
 
 After generating each Form or Page template, verify:
 
-1. **Form templates:** `connectToState` is imported and used; `mapStateToProps` + `getKeyForMappedField` are in `utils/index.ts`; each child field uses the `<Child key={getKeyForMappedField(kid)} {...kid} />` pattern.
-2. **Page templates:** All props listed in the skill file's Props table are destructured; all `getComponentFromRegistry()` lookups from the skeleton are present; all `useEffect` hooks from the skeleton are present; all PCore API calls (`PCore.getEnvironmentInfo()`, `PCore.getPubSubUtils()`, etc.) from the skeleton are present; infrastructure components (NavBar, VerticalTabs, DeferLoad, etc.) receive ALL required props from the skeleton.
-3. **Both:** The generated file is NOT a single-line return. If the skill file skeleton is 50+ lines, your output should be comparable in length.
+1. **Form templates:** the higher-order state-subscription pattern is imported and used; the companion utilities module contains the helpers described in the skill file; each child field is wired through those helpers.
+2. **Page templates:** all props listed in the skill file's Props table are destructured; all registry lookups from the skeleton are present; all lifecycle hooks from the skeleton are present; all engine API calls from the skeleton are present; infrastructure components (NavBar, VerticalTabs, DeferLoad, etc.) receive ALL required props from the skeleton.
+3. **Both:** the generated file is NOT a single-line return. If the skill file skeleton is 50+ lines, your output should be comparable in length.
 
 If any check fails, revise the generated output before proceeding.
 
@@ -229,39 +197,21 @@ If any check fails, revise the generated output before proceeding.
 
 After generating **TwoColumn**, **OneColumn**, **NarrowWide**, or **WideNarrow**, you MUST immediately create these additional files in the same directory:
 
-| Base template | Sub-variant files to create                                         |
-| ------------- | ------------------------------------------------------------------- |
-| TwoColumn     | `TwoColumnPage.tsx`, `TwoColumnTab.tsx`                             |
-| OneColumn     | `OneColumnPage.tsx`, `OneColumnTab.tsx`                             |
-| NarrowWide    | `NarrowWideForm.tsx`, `NarrowWidePage.tsx`                          |
-| WideNarrow    | `WideNarrowDetails.tsx`, `WideNarrowForm.tsx`, `WideNarrowPage.tsx` |
+| Base template | Sub-variants to create                                  |
+| ------------- | ------------------------------------------------------- |
+| TwoColumn     | `TwoColumnPage`, `TwoColumnTab`                         |
+| OneColumn     | `OneColumnPage`, `OneColumnTab`                         |
+| NarrowWide    | `NarrowWideForm`, `NarrowWidePage`                      |
+| WideNarrow    | `WideNarrowDetails`, `WideNarrowForm`, `WideNarrowPage` |
 
-Each sub-variant is a one-line passthrough that delegates to the base component via the registry:
-
-```typescript
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-
-export default function TwoColumnPage(props: PConnProps & Record<string, any>) {
-  const TwoColumn = getComponentFromRegistry('TwoColumn');
-  return <TwoColumn {...props} />;
-}
-```
-
-Replace `TwoColumnPage`/`TwoColumn` with the appropriate names for each sub-variant.
+Each sub-variant is a passthrough component (using the file naming convention established for this project) that delegates to the base component via the project's component registry — follow the passthrough pattern described in `template-components.md` (loaded in Step 1), substituting the appropriate base component and sub-variant name each time.
 
 ### 4c — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file (the file that maps component names to their implementations) and:
 
-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>,
-   ```
+1. Add an import at the top of the file in the **Templates** section
+2. Add an entry in the component map object under the templates comment
 3. **Also import and register ALL sub-variant files** created in Step 4b.2. Each gets its own import and map entry.
 
 Do not reorder or restructure any existing entries.
@@ -274,10 +224,4 @@ After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` templa
 
 ## Step 5 — Verify the build
 
-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`.
+Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.

package/templates/react-sdk-reference/.ai-common/prompts/generate-widget-components.md

@@ -46,12 +46,12 @@ Read the full contents of `{{SKILL_DIR}}/widget-components.md`.
 
 This gives you:
 
-- The DS-agnostic data-fetching skeleton with `// [DS RENDER]` placeholder
+- The DS-agnostic data-fetching skeleton
 - 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.
+- All common engine APIs used in widgets for data pages, mashup interactions, attachments, case info, etc.
 - Registration conventions
 
-> The PCore data-fetching logic is always identical regardless of design system. Only the `// [DS RENDER]` section changes per DS.
+> The data-fetching logic is always identical regardless of design system. Only the presentation layer changes per DS.
 
 Keep this context active throughout the entire generation session. Do not re-read it per component.
 
@@ -59,29 +59,32 @@ Keep this context active throughout the entire generation session. Do not re-rea
 
 ## Step 2 — Install and discover the design system (once)
 
-### 2a — Check and install the DS package
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
 
-Run this command in your terminal:
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
 
-```bash
-cat package.json | grep "<design-system-package>"
-```
+You MUST also thoroughly inspect the installed design system package, focusing on presentation primitives (Card, List, Table, Button, Badge, Spinner):
 
-If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+1. **Discover all available components** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every component the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map each widget to the best available DS primitive** — using the complete list you just discovered, identify which DS component best serves each widget's presentation needs. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every primitive you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
 
-```bash
-npm install <design-system-package>
-```
+Also check:
 
-Also install any peer dependencies documented in the package's README. Report what was installed.
+- Whether the design system has a **companion icon package** — read its exports before using any icon name; never guess icon names
+- Whether it has **size/variant conventions** — use built-in props rather than custom padding
+- Whether it has **CSS tokens** — use design system CSS custom properties for spacing; never hardcode `px` values
 
-### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+Build a **DS UI primitive reference map** from this discovery. Reuse it for every widget — do not repeat this discovery per component.
+
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
 
 Design systems require their global stylesheet — without it, components render unstyled.
 
-#### Known DS style requirements (examples — verify from README for exact paths):
+#### Known DS style requirements (examples — verify against the README you already read):
 
-| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| Design System | Styles Package (example) | CSS Import (example)                     | Provider Wrapper (example) |
 | ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
 | Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
 | Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
@@ -90,51 +93,20 @@ Design systems require their global stylesheet — without it, components render
 | Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
 | MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
 
-These are **examples** based on common versions. Always verify the exact import path and provider name from the installed package's README (`node_modules/<ds>/README.md`).
-
-If in table: install styles package (if separate), add CSS import as **first import** in `src/main.tsx`, add Provider in `src/AppProviders.tsx`.
-If not in table: check README and `find node_modules/<ds> -name "*.css" -path "*/dist/*" | head -5`.
-
-Verification: `grep -n "import.*css\|import.*styles" src/main.tsx` must return a result. Do NOT proceed until confirmed.
-
-Report what was installed and configured.
-
-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:
-
-   ```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"
-   ```
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
 
-3. For every component you plan to use (Card, List, Table, Button, Badge, Spinner), read its prop interface:
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
 
-   ```bash
-   find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3
-   grep -A 40 "interface.*Props" <path-from-above>
-   ```
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
 
-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.
+Report what was installed/configured (or "already configured").
 
 ---
 
 ## Step 3 — Overwrite check (all at once)
 
-For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+For each component in the list, check whether the component's file or directory already exists at the output path.
 
 If **any** exist, report them all at once and ask:
 
@@ -160,7 +132,7 @@ 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`
+- **Props interface** — any required/optional props beyond the base component props
 
 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.
 
@@ -170,36 +142,20 @@ If no skill file exists at that path (e.g., `SummaryList`), use the general data
 
 Create the directory `<outputPath>/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using this structure from `widget-components.md` (loaded in Step 1):
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
 
-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
+Follow the implementation structure described in `widget-components.md` (loaded in Step 1). That file specifies the exact imports, interface, data-fetching lifecycle, and render approach for this project's framework. Use the DS primitives you identified in Step 2 for presentation. The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls.
 
-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>';
-```
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
 
 Create any CSS or utility files required by the skill file.
 
 ### 4c — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file (the file that maps component names to their implementations) and:
 
-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>,
-   ```
+1. Add an import at the top of the file in the **Widgets** section
+2. Add an entry in the component map object under the widgets comment
 
 ⚠️ **Key name exception:** `ToDo` MUST be registered as `Todo: ToDo` (not `ToDo,`). The Pega engine sends `Todo` (capital T, lowercase 'odo'). Using shorthand `ToDo,` creates key `ToDo` which won't match.
 
@@ -213,10 +169,4 @@ After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>
 
 ## Step 5 — Verify the build
 
-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`.
+Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.