@pega/sdk 0.0.12 → 0.0.14

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.
Files changed (62) hide show
  1. package/README.md +32 -11
  2. package/package.json +1 -1
  3. package/templates/angular-sdk-reference/angular.json +2 -1
  4. package/templates/angular-sdk-reference/package.json +1 -0
  5. package/templates/angular-sdk-reference/pega-constellationjs-0.26.3-local.tgz +0 -0
  6. package/templates/angular-sdk-reference/src/app/app.component.ts +232 -15
  7. package/templates/angular-sdk-reference/src/components/component-map.ts +90 -0
  8. package/templates/angular-sdk-reference/src/components/fields/auto-complete/auto-complete.component.ts +267 -0
  9. package/templates/angular-sdk-reference/src/components/fields/checkbox/checkbox.component.ts +84 -0
  10. package/templates/angular-sdk-reference/src/components/fields/currency/currency.component.ts +97 -0
  11. package/templates/angular-sdk-reference/src/components/fields/date-input/date-input.component.ts +88 -0
  12. package/templates/angular-sdk-reference/src/components/fields/dropdown/dropdown.component.ts +101 -0
  13. package/templates/angular-sdk-reference/src/components/fields/email/email.component.ts +91 -0
  14. package/templates/angular-sdk-reference/src/components/fields/integer/integer.component.ts +93 -0
  15. package/templates/angular-sdk-reference/src/components/fields/phone/phone.component.ts +91 -0
  16. package/templates/angular-sdk-reference/src/components/fields/radio-buttons/radio-buttons.component.ts +102 -0
  17. package/templates/angular-sdk-reference/src/components/fields/text-area/text-area.component.ts +98 -0
  18. package/templates/angular-sdk-reference/src/components/fields/text-input/text-input.component.ts +97 -0
  19. package/templates/angular-sdk-reference/src/components/fields/url-input/url-input.component.ts +94 -0
  20. package/templates/angular-sdk-reference/src/components/infra/assignment/assignment.component.ts +206 -0
  21. package/templates/angular-sdk-reference/src/components/infra/case-summary/case-summary.component.ts +76 -0
  22. package/templates/angular-sdk-reference/src/components/infra/case-view/case-view.component.ts +114 -0
  23. package/templates/angular-sdk-reference/src/components/infra/flow-container/flow-container.component.ts +411 -0
  24. package/templates/angular-sdk-reference/src/components/infra/reference/reference.component.ts +158 -0
  25. package/templates/angular-sdk-reference/src/components/infra/region/region.component.ts +39 -0
  26. package/templates/angular-sdk-reference/src/components/infra/root-container/root-container.component.ts +193 -0
  27. package/templates/angular-sdk-reference/src/components/infra/stages/stages.component.ts +78 -0
  28. package/templates/angular-sdk-reference/src/components/infra/view/view.component.ts +139 -0
  29. package/templates/angular-sdk-reference/src/components/infra/view-container/view-container.component.ts +191 -0
  30. package/templates/angular-sdk-reference/src/components/templates/default-form/default-form.component.ts +101 -0
  31. package/templates/angular-sdk-reference/src/components/templates/narrow-wide/narrow-wide.component.ts +37 -0
  32. package/templates/angular-sdk-reference/src/components/templates/one-column/one-column.component.ts +37 -0
  33. package/templates/angular-sdk-reference/src/components/templates/two-column/two-column.component.ts +37 -0
  34. package/templates/angular-sdk-reference/src/components/templates/wide-narrow/wide-narrow.component.ts +37 -0
  35. package/templates/angular-sdk-reference/src/helpers/event-utils.ts +18 -0
  36. package/templates/angular-sdk-reference/src/helpers/utils.ts +38 -0
  37. package/templates/angular-sdk-reference/src/helpers/versionHelpers.ts +14 -0
  38. package/templates/angular-sdk-reference/tsconfig.json +5 -2
  39. package/templates/react-sdk-reference/.ai-common/agents/embedded-flow-expert.md +20 -13
  40. package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions-embedded.md +2 -2
  41. package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions.md +1 -1
  42. package/templates/react-sdk-reference/.ai-common/instructions/dse-component.md +1 -1
  43. package/templates/react-sdk-reference/.ai-common/instructions/embedded-component.md +1 -1
  44. package/templates/react-sdk-reference/.ai-common/instructions/field-component.md +1 -1
  45. package/templates/react-sdk-reference/.ai-common/instructions/infra-component.md +1 -1
  46. package/templates/react-sdk-reference/.ai-common/instructions/template-component.md +1 -1
  47. package/templates/react-sdk-reference/.ai-common/instructions/widget-component.md +1 -1
  48. package/templates/react-sdk-reference/.ai-common/prompts/component-manifest.json +7 -0
  49. package/templates/react-sdk-reference/.ai-common/prompts/embedded-component-manifest.md +2 -2
  50. package/templates/react-sdk-reference/.ai-common/prompts/generate-all-components.md +4 -2
  51. package/templates/react-sdk-reference/.ai-common/prompts/generate-embedded-components.md +10 -11
  52. package/templates/react-sdk-reference/.ai-common/skills/connect-pega-server.md +84 -31
  53. package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md +11 -2
  54. package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/wire-integration.md +6 -6
  55. package/templates/react-sdk-reference/.ai-common/skills/field-components.md +75 -29
  56. package/templates/react-sdk-reference/.ai-common/skills/field-skills/AutoComplete.md +133 -101
  57. package/templates/react-sdk-reference/.ai-common/skills/field-skills/EmbeddedData.md +385 -0
  58. package/templates/react-sdk-reference/.ai-common/skills/field-skills/EmbeddedDataMulti.md +506 -0
  59. package/templates/react-sdk-reference/.ai-common/skills/field-skills/ObjectReference.md +549 -86
  60. package/templates/react-sdk-reference/.ai-common/skills/field-skills/UserReference.md +181 -83
  61. package/templates/react-sdk-reference/.ai-common/skills/template-skills/ListView.md +125 -153
  62. package/templates/react-sdk-reference/.ai-common/skills/template-skills/SimpleTable.md +90 -81
@@ -4,51 +4,104 @@ ai-description: Ensure the Pega server connection (MCP config + sdk-config.json)
4
4
 
5
5
  # Pega Server Connection Gate
6
6
 
7
- Run this **before** the first Pega data source is executed in a chat session. It ensures the MCP server this session talks to, and `sdk-config.json`, both carry real connection values instead of the placeholder markers the project scaffolding step leaves behind. Scaffolding never asks for these — this gate is where they are actually collected, the first time a workflow needs them.
7
+ Run this **before** the first Pega data source is executed in a chat session. It applies to both full-portal and embedded workflows. It resolves connection values from the project's existing configuration, asks once for everything still missing, and synchronizes the active MCP config and browser-served `sdk-config.json`.
8
8
 
9
- ## 1. Locate the MCP config file
9
+ ## 1. Locate the active configuration files
10
10
 
11
- Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or path, and do not ask the user which file to edit — discover it by what it contains: a server entry whose key starts with `pega-`, holding a `url` that points at an `/api/service/v1/mcp/` endpoint. Search the project for a file matching that shape.
11
+ ### 1.1 MCP config
12
12
 
13
- ## 2. Check whether it is already configured
13
+ Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or ask the user which file to edit. Search the project for a server entry whose key starts with `pega-` and whose `url` contains `/api/service/v1/mcp/`.
14
14
 
15
- Read that file and `sdk-config.json`. Treat the connection as **already configured** only when none of the following markers remain, literally, in either file: `{InfinityURL}`, `{AppAlias}`, `{MCPRuleName}`, `{MCPRuleInsKey}`, `{ClientId}`, `{ClientSecret}`, and `sdk-config.json`'s `serverConfig.infinityRestServerUrl` / `serverConfig.appAlias` / `authConfig.mashupClientId` are non-empty.
15
+ Classify the active MCP entry by its shape:
16
16
 
17
- If already configured, skip the rest of this gate and continue with the workflow that invoked it.
17
+ - **Cursor-style authenticated MCP** — the entry contains `auth.clientId` and `auth.clientSecret`. Both fields are required for this MCP connection.
18
+ - **URL-only MCP** — the entry has no auth fields, as in Copilot and Claude Code. Do not require, search for, warn about, or mention a client secret for this entry.
18
19
 
19
- ## 3. Ask only for what is still missing
20
+ ### 1.2 Browser-served SDK config
20
21
 
21
- Check each value independently — ask only for the ones still a marker or blank, never re-ask for a value already present:
22
+ Find the `sdk-config.json` the application actually serves to the browser. Do not automatically choose a same-named file at the project root:
22
23
 
23
- - Pega server URL
24
- - Application alias
25
- - OAuth client ID
26
- - MCP rule name
27
- - MCP rule instance key
28
- - **Client secret — only if the MCP config's server entry has an `auth` block containing a `clientSecret` field.** Some MCP configurations authenticate this way and some do not; let the file's own structure decide whether to ask, rather than deciding by which AI tool is running. If there is no `auth` block, do not ask for a client secret at all.
24
+ - For an embedded project, identify the framework's served static directory (for example `public/`, `static/`, or another directory established by its build configuration) and use the `sdk-config.json` there.
25
+ - For a full-portal project, use its scaffolded application `sdk-config.json`.
26
+ - If more than one copy exists, determine which one the application serves. Report other copies as potentially stale and do not update them.
29
27
 
30
- Ask these as a single batch of questions, not one at a time.
28
+ ### 1.3 Environment files
31
29
 
32
- ## 4. Write the values
30
+ Environment files are commonly excluded by `.gitignore`, so do not rely on an ordinary recursive file search or glob to discover them. First enumerate the project-root directory, including dotfiles, then read every root entry named `.env` or beginning with `.env.` directly by its exact path. If directory enumeration is unavailable, search with ignored files explicitly included. A zero-result ignore-aware search is not evidence that no environment files exist.
33
31
 
34
- **MCP config file** — replace each marker with the value collected for it, and rename the `pega-{MCPRuleName}` server key using the real rule name:
32
+ Read project-root environment files such as `.env`, `.env.local`, `.env.development`, `.env.production`, and other `.env.*` variants. Never print a secret value.
35
33
 
36
- - `{InfinityURL}` → server URL
37
- - `{AppAlias}` → application alias
38
- - `{MCPRuleName}` → MCP rule name (in both the server key and the URL path)
39
- - `{MCPRuleInsKey}` → MCP rule instance key
40
- - `{ClientId}` → client ID, if the entry has an `auth` block
41
- - `{ClientSecret}` → client secret, if the `auth` block has that field
34
+ ## 2. Build the connection inventory
42
35
 
43
- **`sdk-config.json`** — write into the existing structure, do not create new fields:
36
+ Resolve each field independently from every applicable source. A value is unresolved when it is blank or still contains its scaffold marker.
44
37
 
45
- - `serverConfig.infinityRestServerUrl` → server URL
46
- - `serverConfig.appAlias` → application alias
47
- - `authConfig.mashupClientId` → client ID
48
- - `authConfig.portalClientId` → client ID (same value as `mashupClientId`)
38
+ | Field | Allowed sources | Destinations |
39
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
40
+ | Pega server URL | `serverConfig.infinityRestServerUrl`, the MCP URL, or a matching environment key | SDK config and MCP URL |
41
+ | Application alias | `serverConfig.appAlias`, the MCP URL, or a matching environment key | SDK config and MCP URL |
42
+ | MCP rule name | The `pega-*` MCP server key or a matching environment key | MCP server key only |
43
+ | MCP rule instance key | The MCP URL segment after `/api/service/v1/mcp/` or a matching environment key | MCP URL |
44
+ | OAuth client ID | `authConfig.mashupClientId`, `authConfig.portalClientId`, MCP `auth.clientId` when present, or a matching environment key | Both SDK client-ID fields and MCP `auth.clientId` when present |
45
+ | Pega MCP client secret | A private environment key only, and only when the MCP entry contains `auth.clientSecret` | MCP `auth.clientSecret` only |
49
46
 
50
- Never write the client secret into `sdk-config.json` — it belongs only in the MCP config file's `auth.clientSecret`.
47
+ The five non-secret fields are required for every tool. The client ID is a public OAuth identifier and may be supplied in chat. A client secret is required only by a Cursor-style authenticated MCP entry; it is not required for the browser SDK or a URL-only Copilot/Claude Code MCP entry.
51
48
 
52
- ## 5. Tell the user to reconnect
49
+ For non-secret environment values, recognize clear semantic keys ending in `INFINITY_URL`, `SERVER_URL`, `APP_ALIAS`, `MCP_RULE_NAME`, `MCP_RULE_INS_KEY`, `MCP_RULE_INSTANCE_KEY`, or `CLIENT_ID`, including project conventions such as `PEGA_`, `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, and `EXPO_PUBLIC_`.
53
50
 
54
- Most AI tools read their MCP config once at startup. After writing these values, tell the user the MCP server configuration changed and they need to reload or reconnect it (tool-dependent — e.g. restarting the MCP connection or reloading the window) before their request can proceed, and ask them to retry once reconnected.
51
+ For a client secret, accept only a private key such as `PEGA_CLIENT_SECRET` or `CLIENT_SECRET`. Reject browser-exposed names beginning with `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, or `EXPO_PUBLIC_`. Never infer a value from an unrelated key merely because it is the only candidate.
52
+
53
+ Record each field's source and status: configured, missing, or conflicting. For a secret, record presence and source only, never its value.
54
+
55
+ ## 3. Resolve conflicts before writing
56
+
57
+ If allowed sources contain different real values for the same non-secret field, show the field and each source/value pair and ask the user which source is authoritative. Do not silently choose or overwrite.
58
+
59
+ If private environment files contain different client-secret values for a Cursor-style MCP entry, state that the secret sources disagree and name only the files and keys. Ask which environment key is authoritative without exposing either value.
60
+
61
+ Equivalent values across sources are not conflicts; consolidate them without asking.
62
+
63
+ ## 4. Ask once for every unresolved value
64
+
65
+ After reading all sources, make the first user interaction complete. Show a status table for every applicable field, using only **configured**, **missing**, or **conflicting**. For the client secret, show presence only.
66
+
67
+ In that same response:
68
+
69
+ 1. Ask for every missing or conflict-resolved **non-secret** value as one batch. The user may provide these values directly in chat.
70
+ 2. Explain that the user may instead edit any allowed source and say when it is ready. Name the exact destinations:
71
+ - Environment: matching semantic keys for any non-secret field.
72
+ - Active `sdk-config.json`: `serverConfig.infinityRestServerUrl`, `serverConfig.appAlias`, `authConfig.mashupClientId`, and `authConfig.portalClientId`.
73
+ - MCP config: `{InfinityURL}` and `{AppAlias}` in the URL, `{MCPRuleName}` in the server key, `{MCPRuleInsKey}` in the URL, and `auth.clientId` when that field exists.
74
+ 3. If and only if the active MCP entry contains `auth.clientSecret` and no valid private environment value exists, explain in this first response that the **Pega MCP client secret** is missing. Tell the user to add `PEGA_CLIENT_SECRET` or another private `CLIENT_SECRET`-style key to a project-root environment file and confirm when ready. Never ask them to paste it into chat, put it in `sdk-config.json`, use a browser-exposed env key, or enter it directly into the MCP JSON.
75
+
76
+ Do not stop after reporting a missing Cursor secret without also asking for every missing non-secret value. On every reply or retry, re-read all configuration sources and ask again only for fields that remain unresolved.
77
+
78
+ ## 5. Synchronize resolved values
79
+
80
+ Once all five non-secret fields are resolved — and, for a Cursor-style MCP entry, a private environment-sourced secret is resolved — update the active files while preserving unrelated fields.
81
+
82
+ **MCP config:**
83
+
84
+ - Replace `{InfinityURL}` with the server URL.
85
+ - Replace `{AppAlias}` with the application alias.
86
+ - Rename the `pega-{MCPRuleName}` server key with the real MCP rule name. The rule name belongs in the server key, not the endpoint URL.
87
+ - Replace `{MCPRuleInsKey}` with the MCP rule instance key.
88
+ - When `auth.clientId` exists, write the resolved client ID.
89
+ - When `auth.clientSecret` exists, write the private environment-sourced secret without displaying it.
90
+ - Never add an auth block to a URL-only MCP entry.
91
+
92
+ **Active browser-served `sdk-config.json`:**
93
+
94
+ - Write the server URL to `serverConfig.infinityRestServerUrl`.
95
+ - Write the application alias to `serverConfig.appAlias`.
96
+ - Write the client ID to both `authConfig.mashupClientId` and `authConfig.portalClientId`.
97
+ - Do not create new fields or change unrelated values.
98
+
99
+ Never write a client secret into `sdk-config.json`, including `authConfig.portalClientSecret`. This file is served to the browser and is publicly readable. The user's browser-runtime OAuth grant configuration remains their choice; this gate only ensures the required public client ID is present.
100
+
101
+ After writing, re-read both active files and repeat the inventory check. Continue only when all applicable markers are gone, the five non-secret values are non-empty and consistent, and a Cursor-style `auth.clientSecret` was populated from a private environment value. A URL-only MCP entry is complete without any client secret.
102
+
103
+ ## 6. Continue or reconnect
104
+
105
+ - If the MCP config changed, tell the user it must be reloaded or reconnected before a Pega data source can run, then stop. Ask them to retry the original request; the invoking workflow must rerun this gate first. If MCP tools were started or attached after the conversation began and are not bound to this session, tell the user to start a new chat session.
106
+ - If only `sdk-config.json` changed and the MCP connection is already available to the conversation, continue the invoking workflow without requiring an unnecessary MCP reconnect.
107
+ - If neither file needed changes, continue immediately.
@@ -28,6 +28,15 @@ When Pega case flows are embedded into a customer's existing application, the ge
28
28
 
29
29
  ## Steps
30
30
 
31
+ ### Step 0 — Resolve the output path
32
+
33
+ Every downstream skill and prompt writes generated components to one location: `{output_path}`. Resolve it once, here, before anything else runs. This is separate from the Design Profile document itself, which always lives at the fixed `docs/design-profile.md` and never moves with `{output_path}`.
34
+
35
+ 1. **Check for an existing profile first.** Look for `docs/design-profile.md` at the project root — this is its one fixed location, independent of `{output_path}`. If it exists, read its **Output Path** field (Section 1) and reuse that value as `{output_path}` — skip the rest of this step entirely. Do not ask the user again.
36
+ 2. **Otherwise, ask.** Ask the user where in their own project the generated Pega components should live. Suggest `pega-components/` at the project root as the default/recommended answer, but accept any path they type instead.
37
+ 3. **Validate the answer stays inside the project.** Reject an absolute path outside the project, any `..` traversal segment, or anything else that would resolve outside the project root — re-ask when this happens rather than writing outside the repo.
38
+ 4. **Record the confirmed path** as `{output_path}`. It is written into the Design Profile in Step 6 below, and every other embedded-flow skill/prompt reads it from there instead of asking again or assuming a fixed name.
39
+
31
40
  ### Step 1 — Identify project fundamentals
32
41
 
33
42
  Read the project's dependency manifest (the file that lists packages and their versions). From it, determine:
@@ -105,7 +114,7 @@ This is what makes it possible to offer the user real choices in their own vocab
105
114
 
106
115
  Produce a structured markdown document with the following sections. Use heading levels for organization and bullet lists for values. Do not include source code — describe patterns in prose and reference file paths for the AI to read during generation.
107
116
 
108
- **Section 1: Project Fundamentals** — list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
117
+ **Section 1: Project Fundamentals** — start with the **Output Path** resolved in Step 0, then list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
109
118
 
110
119
  **Section 2: Design Tokens** — organize by sub-sections: Colors (primary, secondary, accent, error, warning, success, background, text, border with their semantic names and values), Spacing (scale), Typography (font families, sizes, weights), Borders and Radii (values), Shadows (elevation values), Breakpoints (if defined).
111
120
 
@@ -119,7 +128,7 @@ Produce a structured markdown document with the following sections. Use heading
119
128
 
120
129
  **Section 7: Navigation and Surfaces** — list the routing approach and how navigation is triggered, the overlay primitives the project uses and where they come from, the layout shell that wraps a routed page, and a table of existing task entry points giving each control's visible label, its file, and what it does today. The wiring workflow reads this section to decide where the embedded flow renders.
121
130
 
122
- Save this document to `pega-components/.design-profile.md` in the customer's project.
131
+ Save this document to `docs/design-profile.md` in the customer's project, creating the `docs/` folder at the project root first if it does not already exist. This location is fixed — it does not move with `{output_path}`.
123
132
 
124
133
  ---
125
134
 
@@ -6,7 +6,7 @@ Guide the wiring of generated Pega components into a customer's existing applica
6
6
 
7
7
  ## Purpose
8
8
 
9
- After the `pega-components/` folder has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
9
+ After the generated components folder (its location is resolved during analysis and recorded in the Design Profile) has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
10
10
 
11
11
  **Step 0 is the exception.** It is a gate, not an integration step, and it runs _before_ generation — see its own heading for why.
12
12
 
@@ -14,7 +14,7 @@ After the `pega-components/` folder has been generated (via the component genera
14
14
 
15
15
  ## Prerequisites
16
16
 
17
- - The `pega-components/` folder exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
17
+ - The generated components folder (its location is resolved during analysis and recorded in the Design Profile) exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
18
18
  - The customer has a Pega Infinity environment with:
19
19
  - An OAuth 2.0 client configured for the application
20
20
  - A case type to embed (e.g., a service request, onboarding flow)
@@ -155,7 +155,7 @@ Add the following Pega packages to the project's dependency manifest:
155
155
  | The Pega SDK types package | Shared type definitions and interfaces |
156
156
  | The Pega ConstellationJS core package | Runtime engine that provides the PCore global |
157
157
 
158
- These are the only external additions. The generated `pega-components/` use the customer's existing UI library — no additional design system packages are needed.
158
+ These are the only external additions. The generated components use the customer's existing UI library — no additional design system packages are needed.
159
159
 
160
160
  If SDK packages were provided as `.tgz` files (interim distribution), they should already be in the project root with `file:` references in the dependency manifest. Run the project's package install command to link them.
161
161
 
@@ -295,7 +295,7 @@ The module-scoped singleton avoids this entirely because it is immune to compone
295
295
 
296
296
  1. **Authenticate** — use the SDK auth client to perform login (OAuth redirect or silent renewal)
297
297
  2. **Bootstrap in embedded/mashup mode** — initialize the SDK runtime in mashup mode (not full portal), capturing the render context returned by bootstrap
298
- 3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated `pega-components/component-map` registry file
298
+ 3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated components folder's `component-map` registry file
299
299
  4. **Register the component creator** — tell the SDK runtime to use the registered components for rendering
300
300
 
301
301
  This module should expose:
@@ -433,7 +433,7 @@ Do not report the integration as complete on static checks alone.
433
433
  │ │ │ │ │ │
434
434
  │ │ │ SDK Bridge Component │ │ │
435
435
  │ │ │ ↓ resolves from registry │ │ │
436
- │ │ │ pega-components/ (generated, customer-styled) │ │ │
436
+ │ │ │ generated components folder (generated, customer-styled) │ │ │
437
437
  │ │ │ ↓ wired to │ │ │
438
438
  │ │ │ PConnect (Pega runtime state + actions) │ │ │
439
439
  │ │ └─────────────────────────────────────────────────┘ │ │
@@ -470,7 +470,7 @@ Common integration failures and their resolutions. These are ordered by how they
470
470
 
471
471
  ## Notes
472
472
 
473
- - The generated `pega-components/` folder has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
473
+ - The generated components folder (its location is resolved during analysis and recorded in the Design Profile) has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
474
474
  - The bootstrap module should handle token refresh/silent renewal automatically via the SDK auth client.
475
475
  - If the customer's app already has authentication, coordinate with their auth flow — the SDK auth client can share tokens if the same OAuth provider is used.
476
476
  - The Pega rendering container can be a modal, a sidebar, an inline section, or a full page. Which one is not a matter of taste — it is resolved in Step 0.2 from what the user asked for or from what their application already does.
@@ -45,6 +45,50 @@ Extend the field input contract for component-specific additional inputs (e.g.,
45
45
 
46
46
  ---
47
47
 
48
+ ## Condition Encoding
49
+
50
+ Several configuration settings describe a _condition_ rather than a fixed value. This section states their contract once; individual field skills may reference it instead of restating it.
51
+
52
+ ### The six shapes
53
+
54
+ A condition-style setting can arrive in one of six forms: absent, the boolean true, the boolean false, an empty string, an expression-marked string, or a When-Rule-marked string. **All six are already resolved to a plain boolean by the runtime before the component receives the input.**
55
+
56
+ This applies to `readOnly`, `required`, `disabled`, `visibility`, the nested visibility that governs a field-input warning message, and the same settings on any nested field descriptor. Because a descriptor is itself an ordinary field, the contract applies **recursively** to every level of nesting.
57
+
58
+ ### Consequences
59
+
60
+ - Type every one of these inputs as a plain boolean. Never inspect its raw string form.
61
+ - Never treat a non-empty string as automatically true. Doing so makes every expression-based or rule-based setting permanently active — the single most common way to get this wrong.
62
+ - Treat absent, an empty string, and an explicitly-emitted default value as equivalent to the setting's documented default.
63
+ - Ensure a resolved `disabled` or `readOnly` genuinely prevents interaction, rather than being accepted as an unused input.
64
+
65
+ ### Key presence never indicates intent
66
+
67
+ Configuration does not clear a setting's key consistently when its control stops being relevant. All of the following occur:
68
+
69
+ - A control that becomes hidden may leave its last value behind as a stale key.
70
+ - A control that becomes hidden may instead have its key cleared.
71
+ - A key cleared by one change may reappear later carrying a **re-seeded default**, not the value that was last configured for it.
72
+ - Some presentations emit a setting's default explicitly while others omit it entirely, for the identical setting at the identical value.
73
+
74
+ Therefore: decide which settings are active from the component's mode and presentation, never from which keys are present, and never assume a key's value reflects the last choice made for it.
75
+
76
+ ### Convenience visibility choices
77
+
78
+ Visibility offers extra options phrased as "if not blank" and "if not zero". These are authoring conveniences that compile to ordinary expressions evaluated against the field's own bound value — they introduce no new value shape. They are offered only where the field has a single scalar bound value to test; a field bound to a list, or one presented as an embedded form, offers only the always / expression / rule choices.
79
+
80
+ Never implement show/hide logic from `visibility`. A field whose visibility resolves to false is not rendered by the surrounding runtime at all.
81
+
82
+ ### Exception: conditions scoped to a single row
83
+
84
+ A condition that governs an individual row of a list does **not** arrive resolved.
85
+
86
+ Such a setting must be read from the component's **raw** configuration — the resolved inputs do not carry it — and evaluated per row against that row's own data, using the platform's expression engine. The configuration surface offers these settings only three choices: never, always, and a custom condition. The When-Rule option is deliberately absent, because a When Rule resolves once and cannot vary from row to row.
87
+
88
+ Two failure modes to avoid. Typing such a setting as a boolean silently discards the per-row behaviour and applies one verdict to the whole list. Truthiness-checking the raw marked string makes the action permanently available for every row. Handle the three real cases explicitly: absent or true means allowed, an expression means evaluate per row, and anything else means denied.
89
+
90
+ ---
91
+
48
92
  ## Implementation Pattern
49
93
 
50
94
  ### Abstract Field Component Pattern
@@ -146,35 +190,37 @@ After creating a component, register it in the project's component map: import t
146
190
 
147
191
  ## Existing Field Components
148
192
 
149
- | Component | Pega Name | Description |
150
- | --------------- | --------------- | --------------------------------- |
151
- | AutoComplete | AutoComplete | Typeahead search field |
152
- | CancelAlert | CancelAlert | Cancel confirmation dialog |
153
- | Checkbox | Checkbox | Single checkbox with label |
154
- | Currency | Currency | Currency input with formatting |
155
- | Date | Date | Date picker |
156
- | DateTime | DateTime | Date + time picker |
157
- | Decimal | Decimal | Decimal number input |
158
- | Dropdown | Dropdown | Select/dropdown with options |
159
- | Email | Email | Email input with icon |
160
- | Group | Group | Field group container |
161
- | Integer | Integer | Integer-only input |
162
- | Location | Location | Google Maps location picker |
163
- | Multiselect | Multiselect | Multi-select dropdown |
164
- | ObjectReference | ObjectReference | Reference to another object |
165
- | Percentage | Percentage | Percentage input |
166
- | Phone | Phone | Phone input with country selector |
167
- | RadioButtons | RadioButtons | Radio button group |
168
- | RichText | RichText | Rich text editor |
169
- | ScalarList | ScalarList | List of scalar values |
170
- | SelectableCard | SelectableCard | Card-style selection |
171
- | SemanticLink | SemanticLink | Clickable link to another case |
172
- | TextArea | TextArea | Multi-line text input |
173
- | TextContent | TextContent | Static text display |
174
- | TextInput | TextInput | Single-line text input |
175
- | Time | Time | Time picker |
176
- | URL | URL | URL input with validation |
177
- | UserReference | UserReference | User picker |
193
+ | Component | Pega Name | Description |
194
+ | ----------------- | ----------------- | ---------------------------------------------- |
195
+ | AutoComplete | AutoComplete | Typeahead search field |
196
+ | CancelAlert | CancelAlert | Cancel confirmation dialog |
197
+ | Checkbox | Checkbox | Single checkbox with label |
198
+ | Currency | Currency | Currency input with formatting |
199
+ | Date | Date | Date picker |
200
+ | DateTime | DateTime | Date + time picker |
201
+ | Decimal | Decimal | Decimal number input |
202
+ | Dropdown | Dropdown | Select/dropdown with options |
203
+ | Email | Email | Email input with icon |
204
+ | EmbeddedData | EmbeddedData | Single embedded record shown as a picker |
205
+ | EmbeddedDataMulti | EmbeddedDataMulti | List of embedded records (table, groups, tabs) |
206
+ | Group | Group | Field group container |
207
+ | Integer | Integer | Integer-only input |
208
+ | Location | Location | Google Maps location picker |
209
+ | Multiselect | Multiselect | Multi-select dropdown |
210
+ | ObjectReference | ObjectReference | Reference to another object |
211
+ | Percentage | Percentage | Percentage input |
212
+ | Phone | Phone | Phone input with country selector |
213
+ | RadioButtons | RadioButtons | Radio button group |
214
+ | RichText | RichText | Rich text editor |
215
+ | ScalarList | ScalarList | List of scalar values |
216
+ | SelectableCard | SelectableCard | Card-style selection |
217
+ | SemanticLink | SemanticLink | Clickable link to another case |
218
+ | TextArea | TextArea | Multi-line text input |
219
+ | TextContent | TextContent | Static text display |
220
+ | TextInput | TextInput | Single-line text input |
221
+ | Time | Time | Time picker |
222
+ | URL | URL | URL input with validation |
223
+ | UserReference | UserReference | User picker |
178
224
 
179
225
  ---
180
226