@pega/sdk 0.0.3 → 0.0.4

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

@@ -11,9 +11,12 @@ Read the user's message carefully. Extract:
 - **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, 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 DSE components be generated? (e.g. `src/components/designSystemExtension/`)
 
@@ -23,19 +26,19 @@ 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 |
+| 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           |
 
 ---
 
@@ -44,6 +47,7 @@ Once both are known, continue to Step 1.
 Read the full contents of `.github/skills/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
@@ -56,19 +60,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 components from `dist/index.d.ts`
-- Focus on display primitives used by Pattern B components: Alert, Card, Avatar, Badge, Tag, Notification
-- Read prop interfaces for these components from `.d.ts` files
+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 display primitives from installed files
 
 > 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.
 
 ---
@@ -78,7 +114,9 @@ Build a **DS display primitive reference map** from this discovery. Reuse it for
 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"
@@ -91,41 +129,77 @@ 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/design-system-extension-skills/<ComponentName>.md` fully
-- Identify the component's pattern (B / A / C) from the skill file
-- Pay attention to:
-  - **Behavioral Contract** — prop handling, variant mapping, rendering logic, edge cases
-  - **Design System Mapping** table — the recommended DS primitive for Pattern B components
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `.github/skills/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
-Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
-- Create `<outputPath>/<ComponentName>/` directory
-- Create `<ComponentName>.tsx` using:
-  - **Pattern B** (Pure display — AlertBanner, Banner, Operator, WssQuickCreate): use DS alert/card/avatar primitive from Step 2 API map in the `// [DS RENDER]` section; apply variant mapping from the skill file
-  - **Pattern A** (PConnect display — CaseSummaryFields, DetailsFields, FieldValueList): use CSS classes or DS typography props; no DS component primitives
-  - **Pattern C** (Complex display — FieldGroup, FieldGroupList, Pulse, RichTextEditor): use PConnect bridge (`createElement(createPConnectComponent(), ...)`); no DS primitives
-- Create `index.tsx` if required by the skill file:
-  ```typescript
-  export { default } from './<ComponentName>';
-  ```
-- Create any CSS file required by the skill file
+
+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
-Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
-- Add the import to `src/components/component-map.ts` in the Design System Extension section
-- Add the entry to `getSampleComponentMap()` under the DSE 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 **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 — 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>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"
 
 ---
 
 ## 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-field-components.prompt.md

@@ -11,9 +11,12 @@ Read the user's message carefully. Extract:
 - **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, 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 field components be generated? (e.g. `src/components/field/`)
 
@@ -23,35 +26,35 @@ 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 |
+| 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 |
+| 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   |
 
 ---
 
@@ -60,6 +63,7 @@ Once both are known, continue to Step 1.
 Read the full contents of `.github/skills/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
@@ -70,16 +74,54 @@ 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 all exported components from `dist/index.d.ts`
-- Read prop interfaces for the control types needed across the component list
-- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+   ```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.
 
@@ -90,7 +132,9 @@ Build a **DS API reference map** from this discovery. You will 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"
@@ -103,42 +147,77 @@ 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/field-skills/<ComponentName>.md` fully
-- Pay attention to:
-  - **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
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `.github/skills/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
-Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
-- Create `<outputPath>/<ComponentName>/` directory
-- Create `<ComponentName>.tsx` using:
-  - The abstract behavioral skeleton from `field-components.md` (read in Step 1)
-  - The Behavioral Contract from the component skill file
-  - The DS API confirmed in Step 2 (from the DS API reference map — no new terminal commands needed)
-  - Display mode guards (`DISPLAY_ONLY`, `STACKED_LARGE_VAL`) via `getComponentFromRegistry('FieldValueList')`
-  - `data-test-id={testId}` on the underlying interactive element
-- Create `index.tsx`:
-  ```typescript
-  export { default } from './<ComponentName>';
-  ```
+
+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
-Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
-- Add the import to `src/components/component-map.ts` in the Fields section
-- Add the entry to `getSampleComponentMap()` under the fields 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 **Fields** section:
+   ```typescript
+   import <ComponentName> from './field/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the fields 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 component name>`"
 
 ---
 
 ## 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`.