@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,216 @@
+---
+ai-description: Generate all (or a subset of) design system extension components 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`)
+- **Output base path** — the folder where DSE components should be generated (e.g. `src/components/designSystemExtension/`)
+- **Component list** — which components to generate (default: all 11 listed below)
+
+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, `{{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 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 DSE components be generated? (e.g. `src/components/designSystemExtension/`)
+
+If the user specified a subset (e.g., "just AlertBanner and FieldValueList"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 11 DSE components)
+
+| Component         | Pattern              | DS needed?    |
+| ----------------- | -------------------- | ------------- |
+| AlertBanner       | B — Pure display     | Yes           |
+| Banner            | B — Pure display     | Yes           |
+| CaseSummaryFields | A — PConnect display | Minimal       |
+| DetailsFields     | A — PConnect display | Minimal       |
+| FieldGroup        | C — Complex display  | No            |
+| FieldGroupList    | C — Complex display  | No            |
+| FieldValueList    | A — PConnect display | No (CSS only) |
+| Operator          | B — Pure display     | Yes           |
+| Pulse             | C — Complex display  | No            |
+| RichTextEditor    | C — Complex display  | No            |
+| WssQuickCreate    | B — Pure display     | Yes           |
+
+---
+
+## Step 1 — Read `design-system-extension.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/design-system-extension.md`.
+
+This gives you:
+
+- All three implementation patterns (Pure display, Field value display, Complex display with PConnect)
+- The `// [DS RENDER]` placeholder approach for Pattern B components
+- The Design System Adaptation section — pattern categorisation, variant mapping table, DS discovery guidance
+- Styling patterns — when to use CSS files vs DS style props
+- Registration conventions
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## 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 — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify from README for exact paths):
+
+| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| 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.
+
+> Pattern A/C components (FieldValueList, FieldGroup, Pulse, etc.) use PConnect bridge or plain CSS — they do not use the DS API. Only Pattern B components consume DS primitives.
+
+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 display primitives (Alert, Card, Avatar, Badge, Tag, Notification):
+
+   ```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 display primitive you plan to use, read its prop interface:
+
+   ```bash
+   find node_modules/<designSystem> -name "Alert.d.ts" -o -name "Card.d.ts" -o -name "Avatar.d.ts" | head -5
+   grep -A 40 "interface.*Props" <path-from-above>
+   ```
+
+4. Check for **variant/type/severity prop names** — each DS uses different names for alert severity (e.g., `type`, `status`, `severity`, `variant`).
+
+Only use component names and prop names confirmed in these files.
+
+Build a **DS display primitive reference map** from this discovery. Reuse it for every Pattern B component — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+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"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — 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 file (`design-system-extension.md`) provides the pattern skeletons. The component-specific skill file provides the **exact prop interface, variant logic, and edge cases**. Both are needed — generating from only the general skill will produce components that render empty or with incorrect variant handling.
+
+### 4b — Generate the component files
+
+Create the directory `<outputPath>/<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 (exact props, variant logic, edge cases).
+
+Create `index.tsx` if required by the skill file:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS file required by the skill file.
+
+### 4c — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top of the file in the **Design System Extension** section:
+   ```typescript
+   import <ComponentName> from './designSystemExtension/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the DSE comment:
+   ```typescript
+   <ComponentName>,
+   ```
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"
+
+---
+
+## 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`.

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

@@ -0,0 +1,239 @@
+---
+ai-description: Generate all (or a subset of) field components 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`)
+- **Output base path** — the folder where field components should be generated (e.g. `src/components/field/`, `app/ui/fields/`)
+- **Component list** — which components to generate (default: all 27 listed below)
+
+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, `{{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 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 field components be generated? (e.g. `src/components/field/`)
+
+If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default)
+
+| Component       | Pega Name       |
+| --------------- | --------------- |
+| AutoComplete    | AutoComplete    |
+| CancelAlert     | CancelAlert     |
+| Checkbox        | Checkbox        |
+| Currency        | Currency        |
+| Date            | Date            |
+| DateTime        | DateTime        |
+| Decimal         | Decimal         |
+| Dropdown        | Dropdown        |
+| Email           | Email           |
+| Group           | Group           |
+| Integer         | Integer         |
+| Location        | Location        |
+| Multiselect     | Multiselect     |
+| ObjectReference | ObjectReference |
+| Percentage      | Percentage      |
+| Phone           | Phone           |
+| RadioButtons    | RadioButtons    |
+| RichText        | RichText        |
+| ScalarList      | ScalarList      |
+| SelectableCard  | SelectableCard  |
+| SemanticLink    | SemanticLink    |
+| TextArea        | TextArea        |
+| TextContent     | TextContent     |
+| TextInput       | TextInput       |
+| Time            | Time            |
+| URL             | URL             |
+| UserReference   | UserReference   |
+
+---
+
+## Step 1 — Read `field-components.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/field-components.md`.
+
+This gives you:
+
+- The behavioral skeleton every field component must follow (state, effects, event handling, display modes)
+- The Design System Adaptation guide (prop mapping conventions, form layout wrappers)
+- The abstract template to use as a base for all components
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## 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 — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify from README for exact paths):
+
+| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| 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"
+   ```
+
+3. For every input control you plan to use (Input, Select, Checkbox, DatePicker, Radio, etc.), 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 **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.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+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"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — 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 file (`field-components.md`) provides the behavioral skeleton. The component-specific skill file provides the **exact event handling, option-loading logic, and edge cases**. Both are needed — generating from only the general skill will produce generic inputs that miss component-specific behavior (e.g., AutoComplete's async search, Currency's formatting).
+
+### 4b — Generate the component files
+
+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)`
+
+Pass `data-test-id={testId}` on the underlying interactive element.
+
+Create `index.tsx`:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+### 4c — Register the component
+
+Edit `src/components/component-map.ts`:
+
+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>,
+   ```
+
+⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping:
+
+- `Date: DateField` (not `DateField,`) — `Date` is a reserved JS global
+- `URL: URLComponent` (not `URLComponent,`) — `URL` is a reserved JS global
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Report progress
+
+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`.