@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,528 @@
+---
+ai-description: Generate components across multiple types (field, template, widget, designSystemExtension) using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Base components folder** — the root folder that contains (or will contain) the component type subfolders (e.g. `src/components/`)
+- **Component types in scope** — which types to generate (default: all four if not specified)
+
+Both **design system** and **base components folder** 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, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the base components folder, 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. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, and `designSystemExtension/` will be used under it.
+
+### Component type scope
+
+Extract which types the user wants from the message:
+
+| User says                                  | Types in scope                                    |
+| ------------------------------------------ | ------------------------------------------------- |
+| "generate all components"                  | field + template + widget + designSystemExtension |
+| "generate field and widget components"     | field + widget                                    |
+| "generate widget, template components"     | widget + template                                 |
+| "generate all components except templates" | field + widget + designSystemExtension            |
+| "replace everything"                       | field + template + widget + designSystemExtension |
+
+Default to **all four types** if the message does not restrict the scope.
+
+### Derived output paths
+
+Once the base folder is known, derive the output path for each type in scope:
+
+| Type                  | Derived path                    |
+| --------------------- | ------------------------------- |
+| field                 | `<base>/field/`                 |
+| template              | `<base>/template/`              |
+| widget                | `<base>/widget/`                |
+| designSystemExtension | `<base>/designSystemExtension/` |
+
+Once design system, base folder, and type scope are resolved, continue to Step 1.
+
+---
+
+## Step 1 — Read general skill files (once, for each type in scope)
+
+Read the general skill file for every type in scope. Do this upfront — do not re-read per component.
+
+| Type                  | Skill file to read                         |
+| --------------------- | ------------------------------------------ |
+| field                 | `{{SKILL_DIR}}/field-components.md`        |
+| template              | `{{SKILL_DIR}}/template-components.md`     |
+| widget                | `{{SKILL_DIR}}/widget-components.md`       |
+| designSystemExtension | `{{SKILL_DIR}}/design-system-extension.md` |
+
+Keep all loaded skill files active throughout the entire session.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+### 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.
+
+### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+
+Design systems require their global stylesheet to be loaded — without it, components render as unstyled browser-native HTML. This step is **not optional**.
+
+#### Known DS style requirements (examples — verify from README for exact paths):
+
+| Design System | Styles Package to Install        | CSS Import to Add in `src/main.tsx` (example) | Provider Wrapper (example)                    |
+| ------------- | -------------------------------- | --------------------------------------------- | --------------------------------------------- |
+| Carbon        | `@carbon/styles`                 | `import '@carbon/react/css/styles.css';`      | `<Theme>` from `@carbon/react`                |
+| Ant Design    | (included in `antd`)             | `import 'antd/dist/reset.css';`               | `<ConfigProvider>` from `antd`                |
+| Radix Themes  | `@radix-ui/themes`               | `import '@radix-ui/themes/styles.css';`       | `<Theme>` from `@radix-ui/themes`             |
+| Chakra UI     | (included in `@chakra-ui/react`) | (no CSS file needed)                          | `<ChakraProvider>` from `@chakra-ui/react`    |
+| Shadcn/ui     | (Tailwind CSS)                   | `import './globals.css';` (Tailwind output)   | None (uses Tailwind classes directly)         |
+| MUI           | (included in `@mui/material`)    | (no CSS file needed — CSS-in-JS)              | `<ThemeProvider>` from `@mui/material/styles` |
+
+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`) — paths may differ across versions.
+
+#### If the DS is in the table above:
+
+1. Install the styles package (if separate): `npm install <styles-package>`
+2. Add the CSS import as the **first import** in `src/main.tsx` (before any component imports)
+3. Add the Provider wrapper in `src/AppProviders.tsx`
+
+#### If the DS is NOT in the table:
+
+1. Check `node_modules/<designSystem>/README.md` for CSS/styles setup instructions
+2. Search for a CSS entry point:
+   ```bash
+   find node_modules/<designSystem> -name "*.css" -path "*/dist/*" | head -5
+   ```
+3. Install and import whatever is found
+4. Check if a Provider/ThemeProvider is documented in the README
+
+#### Verification (non-visual):
+
+After adding the CSS import, confirm it exists in the entry file:
+
+```bash
+grep -n "import.*css\|import.*styles\|import.*reset" src/main.tsx
+```
+
+If this grep returns nothing, the CSS was NOT added correctly — fix it before proceeding.
+
+⛔ **Do NOT proceed to Step 2b until the CSS import is confirmed present in `src/main.tsx`.** Without it, every generated component will render unstyled.
+
+### 2b — Deep-dive into the installed DS package
+
+After installation, build a comprehensive understanding of the design system by reading its source declarations. Do NOT rely on training knowledge — read the actual installed files.
+
+#### Step 2b.1 — Read the README and understand the DS architecture
+
+```bash
+cat node_modules/<designSystem>/README.md
+```
+
+Extract:
+
+- Correct import paths (named exports from root vs subpath imports like `<ds>/Button`)
+- Whether it uses a **Provider/ThemeProvider** wrapper (if so, note the setup requirements)
+- Whether it has a **CSS reset or global styles** requirement
+
+#### Step 2b.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 -5 | xargs grep "^export"
+```
+
+Save this full export list — it is the authoritative source of what components exist. Any component name not in this list does NOT exist and must NOT be used.
+
+#### Step 2b.3 — Read every exported component's prop interface
+
+For EACH exported component from Step 2b.2, read its TypeScript declarations to understand:
+
+- All available props (required and optional)
+- Supported variants, sizes, and states (e.g., `variant: 'outlined' | 'filled'`)
+- Event handler prop names (e.g., `onChange`, `onValueChange`, `onSelect`)
+- Slot/composition patterns (e.g., `renderInput`, `startAdornment`, `prefix`)
+- Whether it accepts `children` or uses named slots
+
+```bash
+# For each component, find and read its type declarations:
+find node_modules/<designSystem> -name "*.d.ts" -path "*ComponentName*" | head -3
+grep -A 60 "interface.*Props" <path-from-above>
+```
+
+Organize your findings into a **DS Component Catalog** grouped by UI category:
+
+**Form inputs:** Input, Select, Checkbox, Radio, DatePicker, TimePicker, Autocomplete/Combobox, NumberInput, Textarea, Switch, etc.
+
+- For each: note the exact prop names for `value`, `onChange`, `error/invalid`, `disabled`, `readOnly`, `placeholder`, `label`, `helperText/description`
+
+**Layout:** Grid, Flex, Stack, SimpleGrid, Columns, Box, Container, etc.
+
+- For each: note how column counts/ratios are specified (e.g., `columns={2}`, `templateColumns`, `span`)
+- Note responsive breakpoint props (e.g., `{{ base: 1, md: 2 }}`)
+
+**Data display:** Table, List, Card, Badge, Tag, Avatar, Typography/Text, etc.
+
+- For each: note sub-components (e.g., `Table.Head`, `Card.Header`)
+
+**Feedback:** Alert, Toast/Snackbar, Dialog/Modal, Popover, Progress, Spinner, etc.
+
+- For each: note severity/status prop names and how to show/dismiss
+
+**Navigation:** Tabs, Menu/Dropdown, Link, Button, IconButton, etc.
+
+#### Step 2b.4 — Check supporting features
+
+- **Form layout wrapper** — does the DS provide a component that combines label + input + helper text + error message? (e.g., `Form.Item`, `FormControl`, `Field`). If yes, use it for ALL field components instead of composing label/input/helper manually.
+- **Companion icons package** — list the package name and read its exports. Never guess icon names:
+  ```bash
+  ls node_modules/<designSystem>-icons/dist/ 2>/dev/null | head -20
+  ```
+- **CSS tokens / design tokens** — does the DS expose CSS custom properties or a token system? Use them for spacing instead of hardcoded `px` values.
+- **Theme variants** — what `size` values are available? (e.g., `sm`, `md`, `lg`). What `variant` values? (e.g., `outlined`, `filled`, `ghost`).
+
+#### Step 2b.5 — Build the DS API reference map
+
+Compile all findings into a single reference map structured as:
+
+```
+DS API Reference Map
+====================
+Package: <name>@<version>
+Import pattern: import { Component } from '<path>'
+Provider required: yes/no (ThemeProvider, etc.)
+
+Form Inputs:
+  Input: { value, onChange, onBlur, placeholder, disabled, readOnly, invalid/error, size, variant }
+  Select: { value, onChange, options/children, placeholder, disabled, ... }
+  ...
+
+Layout:
+  Grid: { columns, gap, children }
+  ...
+
+Data Display:
+  Card: { children } → Card.Header, Card.Body, Card.Footer
+  Table: { children } → Table.Head, Table.Body, Table.Row, Table.Cell
+  ...
+
+Feedback:
+  Alert: { status/severity, title, description, closable/onClose }
+  ...
+```
+
+Keep this map active throughout the entire session. Reference it whenever generating a component — do NOT re-run discovery commands per component.
+
+---
+
+## Step 3 — Overwrite check (all types, all at once)
+
+For every type in scope, check whether each component's `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+Collect all existing components across all types and report them in one consolidated list:
+
+> "The following N components already exist across [types]: [list grouped by type]. 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"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+⚠️ **This decision is final for the entire session.** Do NOT re-check file existence or re-ask this overwrite question during Steps 4–7. When you encounter a component file that already exists during generation, silently apply the decision made here (overwrite it or skip it) without prompting again. This applies even after retries, transport errors, or subagent restarts — the user's answer here governs all subsequent component generation in this conversation.
+
+---
+
+## Step 4 — Generate field components (skip if field not in scope)
+
+If `field` is in scope, generate each of the 27 field components in order:
+
+**For each field component:**
+
+### 4.1 — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/field-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 `field-components.md`.
+
+After reading, extract and keep active:
+
+- **Behavioral Contract** — state management, option loading, edge cases specific to this component
+- **Design System Mapping** table — the recommended DS component for the chosen design system
+- **UI control type** — use this to select the closest DS primitive if the chosen DS is not in the mapping table
+
+If no skill file exists at that path, use the general behavioral skeleton from `field-components.md` loaded in Step 1.
+
+⚠️ The general skill provides the skeleton. The component-specific skill provides the **exact event handling, option-loading logic, and edge cases**. Both are needed.
+
+### 4.2 — Generate the component files
+
+Create the directory `<base>/field/<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)`
+
+Pass `data-test-id={testId}` on the underlying interactive element.
+
+Create `index.tsx`:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+### 4.3 — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top in the **Fields** section
+2. Add an entry in `getSampleComponentMap()` under the fields comment
+
+⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping (Pega sends a name that differs from the JS variable):
+
+- `Date: DateField` (not `DateField,`)
+- `URL: URLComponent` (not `URLComponent,`)
+- `Checkbox: CheckboxComponent` (if your variable name differs from `Checkbox`)
+
+### 4.4 — Report progress
+
+After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
+
+---
+
+## Step 5 — Generate template components (skip if template not in scope)
+
+If `template` is in scope, generate each of the 32 template components in order:
+
+**For each template component:**
+
+### 5.1 — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/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 provides the pattern skeletons. The component-specific skill provides the **exact region structure, sub-variant keys, and rendering logic**. Both are needed.
+
+### 5.2 — Generate the component files
+
+Create the directory `<base>/template/<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.
+
+Create `index.tsx` if required by the skill file:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS file required by the skill file.
+
+### 5.2.1 — Create sub-variant files (MANDATORY for Layout templates)
+
+⛔ **Do NOT skip this step.** Without sub-variants, portal pages and tabs won't render column layouts.
+
+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` |
+
+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. These files go in the same directory as the base component (e.g., `template/TwoColumn/TwoColumnPage.tsx`).
+
+### 5.3 — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top in the **Templates** section
+2. Add an entry in `getSampleComponentMap()` under the templates comment
+3. **Also import and register ALL sub-variant files** created in Step 5.2.1. Each sub-variant gets its own import and its own entry in the map.
+
+### 5.4 — Report progress
+
+After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template"
+
+---
+
+## Step 6 — Generate widget components (skip if widget not in scope)
+
+If `widget` is in scope, generate each of the 9 widget components in order:
+
+**For each widget component:**
+
+### 6.1 — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/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 provides the skeleton. The component-specific skill 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.
+
+### 6.2 — Generate the component files
+
+Create the directory `<base>/widget/<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.
+
+### 6.3 — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top in the **Widgets** section
+2. Add an entry in `getSampleComponentMap()` under the widgets comment
+
+⚠️ **Key name exception for widgets** — this MUST use explicit key mapping:
+
+- `Todo: ToDo` (not `ToDo,`) — Pega engine sends `Todo` (lowercase 'odo'), not `ToDo`
+
+### 6.4 — Report progress
+
+After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
+
+---
+
+## Step 7 — Generate design system extension components (skip if DSE not in scope)
+
+If `designSystemExtension` is in scope, generate each of the 11 DSE components in order:
+
+**For each DSE component:**
+
+### 7.1 — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/design-system-extension-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 `design-system-extension.md`.
+
+After reading, extract and keep active:
+
+- **Pattern classification** — B (Pure display) / A (PConnect display) / C (Complex display)
+- **Behavioral Contract** — prop handling, variant mapping, rendering logic, edge cases
+- **Design System Mapping** table — the recommended DS primitive (Pattern B components only)
+
+If no skill file exists at that path, use the general pattern from `design-system-extension.md` loaded in Step 1.
+
+⚠️ The general skill provides the pattern skeletons. The component-specific skill provides the **exact prop interface, variant logic, and edge cases**. Both are needed.
+
+### 7.2 — Generate the component files
+
+Create the directory `<base>/designSystemExtension/<ComponentName>/`.
+
+Create `<ComponentName>.tsx` using the structure matching the pattern from `design-system-extension.md` (loaded in Step 1):
+
+- **Pattern B** (Pure display — AlertBanner, Banner, Operator, WssQuickCreate): variant mapping (urgent→error, warning→warning, info→info, success→success) + DS Alert/Card/Avatar primitive from Step 2. No `getPConnect`.
+- **Pattern A** (PConnect display — CaseSummaryFields, DetailsFields, FieldValueList): CSS classes + optional DS typography, no DS component primitives. May use `getPConnect`.
+- **Pattern C** (Complex display — FieldGroup, FieldGroupList, Pulse, RichTextEditor): `createElement(createPConnectComponent(), ...)` for PConnect children, semantic HTML. No DS primitives.
+
+Apply the 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.
+
+### 7.3 — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top in the **Design System Extension** section
+2. Add an entry in `getSampleComponentMap()` under the DSE comment
+
+### 7.4 — Report progress
+
+After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`"
+
+---
+
+## Step 8 — Verify the build
+
+Run:
+
+```bash
+npm run build
+```
+
+Fix any TypeScript or build errors before reporting completion.
+
+### 8.1 — Validate component-map key names
+
+After a clean build, verify these key name exceptions in `component-map.ts`:
+
+- [ ] `Date: DateField` (not `DateField,`)
+- [ ] `URL: URLComponent` (not `URLComponent,`)
+- [ ] `Todo: ToDo` (not `ToDo,`)
+
+These are cases where the Pega engine sends a component name that differs from the JavaScript variable name. If any are registered using shorthand (e.g., `ToDo,`), fix them to use explicit key mapping (e.g., `Todo: ToDo,`).
+
+Report a final summary:
+
+- Total components generated, grouped by type
+- All entries added to `component-map.ts`
+- Any components skipped (if "skip existing" was chosen in Step 3)