@pega/sdk 0.0.7 → 0.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -0
- package/dist/index.js +279 -109
- package/package.json +1 -1
- package/templates/react-sdk-reference/.ai-common/agents/implementation-expert.md +43 -23
- package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions.md +25 -9
- package/templates/react-sdk-reference/.ai-common/instructions/infra-component.md +76 -0
- package/templates/react-sdk-reference/.ai-common/prompts/generate-all-components.md +212 -29
- package/templates/react-sdk-reference/.ai-common/prompts/generate-infra-components.md +222 -0
- package/templates/react-sdk-reference/package.minimal.json +1 -1
|
@@ -10,9 +10,10 @@ migrating the design system of components that already exist. You execute these
|
|
|
10
10
|
written, rather than improvising your own approach.
|
|
11
11
|
|
|
12
12
|
This repo is a reference implementation customers clone and re-skin: the UI components (fields, templates, widgets,
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
bootstrap/auth logic) is reusable
|
|
13
|
+
design system extensions, and the three overridable infrastructure chrome components) are meant to be replaced with
|
|
14
|
+
any design system, while the SDK wiring (component map registry mechanics, the SDK-provided infrastructure
|
|
15
|
+
components, event handling helpers, the SDK bridge package, and the application bootstrap/auth logic) is reusable
|
|
16
|
+
infrastructure you must never break.
|
|
16
17
|
|
|
17
18
|
## Startup behavior
|
|
18
19
|
|
|
@@ -27,6 +28,7 @@ The **first time you respond in a conversation**, before doing any routing or fi
|
|
|
27
28
|
2. A short bulleted menu of the flows you support, each with a one-line example trigger phrase, e.g.:
|
|
28
29
|
- **Add/replace a single component** — "add a Dropdown field using Chakra UI"
|
|
29
30
|
- **Batch-generate one type** — "generate all widget components with Ant Design"
|
|
31
|
+
- **Generate infrastructure chrome** — "generate infra components with Carbon"
|
|
30
32
|
- **Generate everything** — "generate all components using Radix"
|
|
31
33
|
- **Identify components from a screenshot** — attach an image and ask "what components are in this screenshot"
|
|
32
34
|
- **Migrate the design system** — "replace all field components with Carbon" or "migrate the whole app to Chakra UI"
|
|
@@ -35,10 +37,14 @@ The **first time you respond in a conversation**, before doing any routing or fi
|
|
|
35
37
|
- **Flow**: options = Add/replace a single component | Batch-generate one type | Generate everything |
|
|
36
38
|
Identify components from a screenshot | Migrate the design system.
|
|
37
39
|
- **Component type** (skip only if "Identify from screenshot" chosen): options = Field | Template | Widget |
|
|
38
|
-
Design System Extension | **All** (`All` = Field + Template + Widget + Design System
|
|
40
|
+
Design System Extension | Infra (chrome) | **All** (`All` = Field + Template + Widget + Design System
|
|
41
|
+
Extension + Infra together).
|
|
39
42
|
Enable multi-select so the user can combine individual types into a custom subset (e.g. Field + Widget),
|
|
40
43
|
but treat **All** as its own exclusive/standalone choice — if the flow is "Generate everything", default
|
|
41
44
|
the selection to **All** and don't present it as something to combine with the individual type options.
|
|
45
|
+
For the "Generate everything" flow, **All** means every type is eligible — not that every component gets
|
|
46
|
+
generated. The concrete list comes from the portal the user picks inside
|
|
47
|
+
`generate-all-components{{PROMPT_EXT}}`, so don't ask for component names here.
|
|
42
48
|
- **Design system**: options = Ant Design | Chakra UI | Radix | Shadcn | Carbon | MUI | Other (freeform allowed).
|
|
43
49
|
Every question should list selectable options (`allowFreeformInput: true` so the user can still type something
|
|
44
50
|
not listed) instead of asking open-ended questions in plain chat text.
|
|
@@ -53,16 +59,17 @@ before writing any code**. Never paraphrase or execute steps from memory — alw
|
|
|
53
59
|
skill file it tells you to read) at the start of the task, and follow every numbered step in order without
|
|
54
60
|
skipping or shortcutting any of them.
|
|
55
61
|
|
|
56
|
-
| Request shape | Prompt file to read and follow
|
|
57
|
-
| --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
-
| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI") | `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}`
|
|
59
|
-
| Multiple/all field components, one design system | `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}`
|
|
60
|
-
| Multiple/all template components, one design system | `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}`
|
|
61
|
-
| Multiple/all widget components, one design system | `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}`
|
|
62
|
-
| Multiple/all design system extension components, one design system | `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}`
|
|
63
|
-
| Multiple
|
|
64
|
-
|
|
|
65
|
-
|
|
|
62
|
+
| Request shape | Prompt file to read and follow |
|
|
63
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI") | `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}` |
|
|
65
|
+
| Multiple/all field components, one design system | `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}` |
|
|
66
|
+
| Multiple/all template components, one design system | `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}` |
|
|
67
|
+
| Multiple/all widget components, one design system | `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}` |
|
|
68
|
+
| Multiple/all design system extension components, one design system | `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}` |
|
|
69
|
+
| Multiple/all infrastructure (chrome) components, one design system | `{{PROMPT_DIR}}/generate-infra-components{{PROMPT_EXT}}` (only `ActionButtons`, `Stages`, `MultiStep` — every other infra component is SDK-provided) |
|
|
70
|
+
| Multiple component types at once, or "generate all components" | `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` (opens with a mandatory server-driven gate — pick a portal, choose landing pages and/or case types, then pick components — then wave-based orchestration over that selection only: launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt) |
|
|
71
|
+
| A screenshot/image is attached and the user wants to know what components are in it (no migration requested) | `{{PROMPT_DIR}}/identify-components{{PROMPT_EXT}}` — output only the single `components="..."` line it specifies |
|
|
72
|
+
| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `{{PROMPT_DIR}}/replace-design-system{{PROMPT_EXT}}` (reads `{{PROMPT_DIR}}/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise) |
|
|
66
73
|
|
|
67
74
|
If a request mixes generation and migration ambiguously, use `vscode_askQuestions` to ask which they mean (options:
|
|
68
75
|
"Generate/replace" vs "Migrate existing") before picking a prompt — generation prompts assume the component
|
|
@@ -74,8 +81,8 @@ change.
|
|
|
74
81
|
- That prompt tells you to launch per-component subagents using prompts named `replace-field` (fields) and
|
|
75
82
|
`replace-component` (everything else). **These files do not exist in `{{PROMPT_DIR}}/`.** When launching those
|
|
76
83
|
subagents yourself via `runSubagent`, give each one the equivalent instructions inline instead: the relevant
|
|
77
|
-
general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`,
|
|
78
|
-
`design-system-extension.md`), the component-specific skill file
|
|
84
|
+
general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`,
|
|
85
|
+
`design-system-extension.md`, or `infra-components.md`), the component-specific skill file
|
|
79
86
|
(`{{SKILL_DIR}}/{type}-skills/<Name>.md`), the target design system, and the same "preserve visual intent /
|
|
80
87
|
keep default export name / update in place" constraints that `add-component{{PROMPT_EXT}}` uses for a single
|
|
81
88
|
component.
|
|
@@ -89,28 +96,41 @@ Every generation prompt requires: component name(s), component type, target desi
|
|
|
89
96
|
(screenshot, `components=` list, or `scope=` folder/shorthand) — if none are given, it defaults to a full 9-wave
|
|
90
97
|
migration, so confirm that's really what the user wants before proceeding. If any required input is missing or
|
|
91
98
|
ambiguous, use the `vscode_askQuestions` tool to ask — present concrete, selectable options (e.g. the known
|
|
92
|
-
design systems, the
|
|
99
|
+
design systems, the five component types, folder/named-shorthand scopes from `component-manifest.json`) rather
|
|
93
100
|
than a plain open-ended question, while still allowing freeform input for anything not listed. Do not guess a
|
|
94
101
|
design system or silently default to MUI.
|
|
95
102
|
|
|
96
103
|
## Guardrails
|
|
97
104
|
|
|
98
|
-
- **
|
|
99
|
-
|
|
100
|
-
|
|
105
|
+
- **In the "generate all components" flow, the generation set is server-resolved.** That prompt's Step 0.5 picks
|
|
106
|
+
a portal, then landing pages and/or case types within it, then a component list from those — and nothing outside
|
|
107
|
+
that selection may be generated. Do not widen it with components you expect a portal to need, and do not skip
|
|
108
|
+
the gate because the user said "everything".
|
|
109
|
+
- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget,
|
|
110
|
+
designSystemExtension, or infra) must be created at `<outputPath>/<ComponentName>/` with a main implementation file
|
|
111
|
+
plus a sibling barrel/re-export file following the project's established convention — exactly as
|
|
101
112
|
Step 5/6 of `add-component{{PROMPT_EXT}}` specifies. Never write multiple components into one file, never
|
|
102
113
|
create a catch-all file like `generated/<designSystem>Components`, and never export a single bundled object
|
|
103
114
|
(e.g. `generatedComponents`) that the component map spreads in one line. This applies identically whether you
|
|
104
115
|
generate one component, a batch of one type, or "all components" via `generate-all-components{{PROMPT_EXT}}` — the
|
|
105
116
|
wave/subagent orchestration in that flow does not change the per-component file-and-folder contract.
|
|
106
117
|
- The project's component map file must get one **named import + one map entry per component**, added under the matching
|
|
107
|
-
category comment (Fields / Templates / Widgets / Design System Extension), never a single spread of a bundled
|
|
118
|
+
category comment (Fields / Templates / Widgets / Design System Extension / Infra), never a single spread of a bundled
|
|
108
119
|
object.
|
|
109
|
-
- Never modify the auth/bootstrap logic in the application's bootstrap modules, infrastructure
|
|
110
|
-
(beyond what a migration prompt explicitly directs), the event handling helper module, or anything in the
|
|
120
|
+
- Never modify the auth/bootstrap logic in the application's bootstrap modules, the SDK-provided infrastructure
|
|
121
|
+
components (beyond what a migration prompt explicitly directs), the event handling helper module, or anything in the
|
|
111
122
|
SDK bridge package. The one exception: `replace-design-system{{PROMPT_EXT}}` explicitly requires wrapping the
|
|
112
123
|
existing provider tree in the application's bootstrap module with a new design-system provider — that specific,
|
|
113
124
|
additive change is allowed only during a migration flow.
|
|
125
|
+
- **Only three infrastructure components may ever be generated** — `ActionButtons`, `Stages`, and `MultiStep`. Every
|
|
126
|
+
other infrastructure component (`NavBar`, `DeferLoad`, `VerticalTabs`, `DashboardFilter`, and anything else) is
|
|
127
|
+
SDK-provided plumbing: skip it and say why. That list never grows.
|
|
128
|
+
- An infra entry in the component map is an **override** of a component the SDK already contributes, so it must be
|
|
129
|
+
listed **after** the SDK's built-in component spread. Listed before it, the spread wins and the override silently
|
|
130
|
+
does nothing.
|
|
131
|
+
- Infrastructure components have a fixed runtime contract — inputs, callback signatures, and localization come from
|
|
132
|
+
the SDK component being replaced. Only markup and styling are yours to change. `ActionButtons` receives plain
|
|
133
|
+
display props and must not be given a PConnect accessor.
|
|
114
134
|
- Never remove the SDK's built-in component spread in the project's component map file — only add or replace entries.
|
|
115
135
|
- Field components must handle `displayMode` (`DISPLAY_ONLY` / `STACKED_LARGE_VAL`) via the field-value display
|
|
116
136
|
component, obtained through the component registry, never a hardcoded import.
|
|
@@ -20,16 +20,19 @@ This is a **reference implementation** — not a framework. The UI components (f
|
|
|
20
20
|
| Template components directory | Layout templates (OneColumn, TwoColumn, Details, etc.) |
|
|
21
21
|
| Widget components directory | Data widgets (ToDo, Attachment, CaseHistory, etc.) |
|
|
22
22
|
| DSE components directory | Extended UI (AlertBanner, FieldGroup, RichTextEditor, etc.) |
|
|
23
|
+
| Infra components directory | Overridable chrome — ActionButtons, Stages, MultiStep only |
|
|
23
24
|
|
|
24
25
|
### Infrastructure (do NOT modify unless you know what you're doing)
|
|
25
26
|
|
|
26
|
-
| Area | Purpose
|
|
27
|
-
| ---------------------------- |
|
|
28
|
-
| Application bootstrap module | Auth + bootstrap + root rendering
|
|
29
|
-
| Component map file | Registry wiring (only add/remove entries)
|
|
30
|
-
|
|
|
31
|
-
| Event handling helper module | PConnect event handler utility
|
|
32
|
-
| SDK bridge package | SDK bridge — never modify
|
|
27
|
+
| Area | Purpose |
|
|
28
|
+
| ---------------------------- | ------------------------------------------------ |
|
|
29
|
+
| Application bootstrap module | Auth + bootstrap + root rendering |
|
|
30
|
+
| Component map file | Registry wiring (only add/remove entries) |
|
|
31
|
+
| SDK-provided infra | NavBar, DeferLoad, VerticalTabs, DashboardFilter |
|
|
32
|
+
| Event handling helper module | PConnect event handler utility |
|
|
33
|
+
| SDK bridge package | SDK bridge — never modify |
|
|
34
|
+
|
|
35
|
+
Infrastructure components are the chrome the runtime draws _around_ a case or an assignment. Most of them ship from the SDK adapter package and are never generated. Exactly three are overridable — `ActionButtons`, `Stages`, and `MultiStep` — because they render inline with the form, where SDK styling is the most visible mismatch. That list never grows.
|
|
33
36
|
|
|
34
37
|
---
|
|
35
38
|
|
|
@@ -182,11 +185,24 @@ Do not skip steps or proceed without reading the required skill files first.
|
|
|
182
185
|
|
|
183
186
|
---
|
|
184
187
|
|
|
185
|
-
## 14.
|
|
188
|
+
## 14. Batch Infrastructure Component Generation
|
|
189
|
+
|
|
190
|
+
When the user asks to generate, create, or replace **infrastructure components**, **chrome components**, or **all infra components** with a design system (e.g., "generate infra components with Ant Design", "replace the infrastructure components with Chakra UI", "generate chrome components using Carbon"),
|
|
191
|
+
read the full contents of `{{PROMPT_DIR}}/generate-infra-components{{PROMPT_EXT}}` and
|
|
192
|
+
execute every step in order before writing any code.
|
|
193
|
+
Do not skip steps or proceed without reading the required skill files first.
|
|
194
|
+
|
|
195
|
+
> Only `ActionButtons`, `Stages`, and `MultiStep` may be generated. Every other infrastructure component is SDK-provided — if the user names one, skip it and say why. Infra entries in the component map must be listed **after** the SDK's built-in component spread, or the override silently does nothing.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## 15. Generate All Components (Multi-Type)
|
|
186
200
|
|
|
187
201
|
When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
|
|
188
202
|
read the full contents of `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` and
|
|
189
203
|
execute every step in order before writing any code.
|
|
190
204
|
Do not skip steps or proceed without reading the required skill files first.
|
|
191
205
|
|
|
192
|
-
> Use this section when the request spans more than one component type. For a single type, use Sections 10–
|
|
206
|
+
> Use this section when the request spans more than one component type. For a single type, use Sections 10–14.
|
|
207
|
+
>
|
|
208
|
+
> That prompt does not generate the full catalogue. Its Step 0.5 is a mandatory gate: resolve the application's portals from the server, ask which one to generate for, ask whether to convert its landing pages, its cases, or both, resolve the components for whatever was chosen, and ask which of them to generate. Only the confirmed selection is generated.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
ai-globs: **/infra/**/*
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Infrastructure (Chrome) Component Rules
|
|
6
|
+
|
|
7
|
+
When creating or modifying infrastructure components, follow these rules:
|
|
8
|
+
|
|
9
|
+
## What Are Infrastructure Components?
|
|
10
|
+
|
|
11
|
+
Infrastructure components are the chrome the Pega runtime draws _around_ a case or an assignment — the action button row, the stage progress indicator, the step navigation — rather than the fields inside it. They differ from every other category in one important way: **they already exist**. Generating one produces an override of the SDK's implementation.
|
|
12
|
+
|
|
13
|
+
## What May Be Generated
|
|
14
|
+
|
|
15
|
+
| Component | Role | Generate? |
|
|
16
|
+
| ------------- | ---------------------------------------------------- | --------- |
|
|
17
|
+
| ActionButtons | The Cancel / Save / Submit row beneath an assignment | Yes |
|
|
18
|
+
| Stages | The case stage progress indicator | Yes |
|
|
19
|
+
| MultiStep | Step navigation within a multi-step assignment | Yes |
|
|
20
|
+
|
|
21
|
+
⛔ `NavBar`, `DeferLoad`, `VerticalTabs`, and `DashboardFilter` are structural plumbing tied to the SDK's own internals. They are always sourced from the SDK adapter package and are **never** generated. If a request names one, skip it and say why. This list never grows.
|
|
22
|
+
|
|
23
|
+
## Patterns
|
|
24
|
+
|
|
25
|
+
### Display-only chrome (no PConnect accessor)
|
|
26
|
+
|
|
27
|
+
Used for: ActionButtons
|
|
28
|
+
|
|
29
|
+
Receives everything it needs as plain display props and reports interaction through a supplied callback. It holds no local state and reads nothing from the store. This is the one exception to the rule that every Pega component receives the PConnect accessor — do not add one to it.
|
|
30
|
+
|
|
31
|
+
### Case-aware chrome (PConnect accessor, read-only)
|
|
32
|
+
|
|
33
|
+
Used for: Stages
|
|
34
|
+
|
|
35
|
+
Receives the accessor so it can read case state and localize, but never writes. Normalize the runtime's raw input through the SDK utility the component's skill file documents, read case-level state using the runtime's constants rather than literal property names, and derive a display model before rendering.
|
|
36
|
+
|
|
37
|
+
### Container chrome (renders children)
|
|
38
|
+
|
|
39
|
+
Used for: MultiStep
|
|
40
|
+
|
|
41
|
+
Wraps the form content the runtime hands it and arranges other Pega components around it. Resolve every Pega sub-component through the project's component registry, derive which part of the structure is active from the runtime's state flags (applying the documented fallback when nothing is marked active), and forward the accessor, item key, button definitions, and press callback to the resolved sub-component unchanged.
|
|
42
|
+
|
|
43
|
+
## The Contract Is Fixed
|
|
44
|
+
|
|
45
|
+
Inputs, callback signatures, derivation logic, and localization come from the SDK component being replaced. **Only markup and styling are yours to change.**
|
|
46
|
+
|
|
47
|
+
- Do not rename inputs or reshape callback signatures.
|
|
48
|
+
- Treat every array input as optional and default it to empty.
|
|
49
|
+
- Keep repeated elements stable — every item in a rendered collection needs a stable identity.
|
|
50
|
+
|
|
51
|
+
## Localization
|
|
52
|
+
|
|
53
|
+
Every label an infrastructure component renders comes from Pega, not from the component. Button and action labels resolve through the Pega locale utilities using the locale category the SDK component uses; case and stage names resolve through the localization service on the PConnect accessor. The value arriving in the input is a key, not display text — rendering it directly looks correct in an English environment and breaks in every other one.
|
|
54
|
+
|
|
55
|
+
## Visual Preservation
|
|
56
|
+
|
|
57
|
+
The replacement must look the same as the original component:
|
|
58
|
+
|
|
59
|
+
1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
|
|
60
|
+
2. Replicate those styles via the new design system's props/variants, inline styles, or by keeping the CSS import — whichever produces the closest match.
|
|
61
|
+
3. Do NOT silently drop legacy styling utility classes — map each one to an equivalent style.
|
|
62
|
+
|
|
63
|
+
## Registration
|
|
64
|
+
|
|
65
|
+
⛔ **Ordering is load-bearing for this category.** An infra entry is an override of a component the SDK already contributes, so it must be listed **after** the SDK's built-in component spread. Listed before it, the spread replaces it and the override silently does nothing.
|
|
66
|
+
|
|
67
|
+
Never remove the spread — it supplies the infrastructure components that are not overridable, and removing it breaks rendering entirely.
|
|
68
|
+
|
|
69
|
+
## Key Rules
|
|
70
|
+
|
|
71
|
+
- Only `ActionButtons`, `Stages`, and `MultiStep` may be generated
|
|
72
|
+
- The three do not share an input shape — take each one's inputs from its own skill file
|
|
73
|
+
- Chrome is display-only — these components report interaction through the callback they were given and never write to the store
|
|
74
|
+
- Resolve sub-components from the registry, never by direct import, or customer overrides are discarded
|
|
75
|
+
- Derive the display model from the runtime's raw inputs first, then render it — this is what keeps the component portable across design systems
|
|
76
|
+
- Case chrome is not assignment chrome — `Stages` belongs to the case view and never appears inside an embedded assignment; `ActionButtons` and `MultiStep` do
|