@pega/sdk 0.0.5 → 0.0.7

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension.md

@@ -1,57 +1,37 @@
 # Skill: Design System Extension (DSE) Components
 
-Create or replace Design System Extension components in the react-sdk-reference application. DSE components are display-focused presentational components that render structured data without direct PConnect binding. Some receive `getPConnect`, others receive only display props.
+Create or replace Design System Extension components in the project. DSE components are display-focused presentational components that render structured data without direct PConnect binding. Some receive `getPConnect`, others receive only display inputs.
 
 ---
 
 ## Architecture Overview
 
-```
-src/components/designSystemExtension/<ComponentName>/
-├── <ComponentName>.tsx      # Component implementation
-├── index.tsx                # Re-export (if present)
-├── <ComponentName>.css      # Styles (optional)
-└── config-ext.json          # Metadata (optional)
-```
+Each DSE component lives in its own folder under the project's design-system-extension components directory, named after the component. The folder contains:
+
+| File                          | Purpose                                                 |
+| ----------------------------- | ------------------------------------------------------- |
+| Component implementation file | The component's logic and markup                        |
+| Re-export module (if present) | Re-exports the component as the folder's default export |
+| Companion styles (optional)   | Styles scoped to the component                          |
+| Metadata (optional)           | Registration metadata (name, label, description, type)  |
 
 ---
 
-## Props Interface
+## Input Contract
 
-DSE components have varying prop patterns:
+DSE components have varying input patterns:
 
 ### Pattern A: With PConnect (data-aware display)
 
-```typescript
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface FieldValueListProps extends PConnProps {
-  name?: string;
-  value?: string;
-  variant?: 'stacked' | 'inline';
-}
-```
+The component's input contract extends the project's base component interface, which provides `getPConnect()` — a function returning the PConnect API object — in addition to its own custom inputs. Example: a field-value display component extending the base interface with additional fields like `name`, `value`, and `variant`.
 
 ### Pattern B: Without PConnect (pure presentation)
 
-```typescript
-interface AlertBannerProps {
-  variant: 'urgent' | 'warning' | 'info' | 'success';
-  heading?: string;
-  messages: Array<string | { label?: string; description?: string }>;
-  onClose?: () => void;
-}
-```
-
-### Pattern C: Extended field props (display-only fields)
+The component's input contract is standalone — it does NOT extend the base component interface. All rendering data arrives via direct inputs. Example: an alert-banner component with fields like `variant`, `heading`, `messages`, and `onClose`.
 
-```typescript
-import type { PConnFieldProps } from '../../../types/PConnProps';
+### Pattern C: Extended field input contract (display-only fields)
 
-interface RichTextEditorProps extends PConnFieldProps {
-  content?: string;
-}
-```
+The component's input contract extends the project's field input contract, which provides standard field-level inputs (`label`, `value`, `displayMode`, `required`, `disabled`, `readOnly`, `status`, `validatemessage`, `helperText`, `hideLabel`, `placeholder`, `testId`) plus `getPConnect()`. The component adds its own domain-specific inputs on top. Example: a rich-text-editor component extending the field input contract with an additional `content` field.
 
 ---
 
@@ -61,115 +41,38 @@ interface RichTextEditorProps extends PConnFieldProps {
 
 Used for: AlertBanner, Banner, Operator
 
-This pattern is design-system agnostic. The variant-mapping logic and message normalisation are always the same. The `// [DS RENDER]` section must be replaced with your design system's alert/notification primitive — see "Design System Adaptation" below.
-
-```typescript
-// Import your design system alert/notification component:
-// e.g. import { Alert } from 'antd';
-// e.g. import { Alert } from '@chakra-ui/react';
-
-interface AlertBannerProps {
-  variant: 'urgent' | 'warning' | 'info' | 'success';
-  heading?: string;
-  messages: Array<string | { label?: string; description?: string }>;
-  onClose?: () => void;
-}
-
-export default function AlertBanner(props: AlertBannerProps) {
-  const { variant, heading, messages = [], onClose } = props;
-
-  // Map Pega variant names to your DS equivalent
-  // e.g. MUI: urgent → 'error' | Ant Design: urgent → 'error' | Chakra: urgent → 'error'
-  const variantMap: Record<string, string> = {
-    urgent: 'error',
-    warning: 'warning',
-    info: 'info',
-    success: 'success'
-  };
-
-  // Normalise messages — Pega may send a plain string or an object
-  function renderMessage(msg: string | { label?: string; description?: string }) {
-    if (typeof msg === 'string') return msg;
-    return `${msg.label ?? ''} ${msg.description ?? ''}`.trim();
-  }
-
-  // [DS RENDER] — replace with your design system's alert/notification primitive
-  // The variantMap value above should be passed as the DS severity/type/status prop
-  return (
-    <YourDesignSystemAlert
-      type={variantMap[variant] ?? 'info'}
-      message={heading}
-      description={messages.map(renderMessage).join(' ')}
-      closable={!!onClose}
-      onClose={onClose}
-    />
-  );
-}
-```
+This pattern is design-system agnostic. The variant-mapping logic and message normalisation are always the same — only the final rendered output changes based on the chosen design system (see "Design System Adaptation" below).
+
+**Structure:**
+
+1. **Use** the design system's alert/notification primitive as the visual foundation.
+2. **Define the input contract** (Pattern B — no PConnect). Include the Pega-facing inputs: `variant`, `heading`/`messages`, and an optional close/dismiss handler.
+3. **Define a variant map** at module level — a plain lookup mapping Pega variant strings (`urgent`, `warning`, `info`, `success`) to the design system's equivalent severity/type value. Unknown variants fall back to `info`.
+4. **Define a message normaliser** — a helper function that accepts either a plain string or an object (`{ label?, description? }`) and returns formatted content. Pega may send either format.
+5. **Render** using the design system's alert primitive. Pass the mapped severity as the type/severity/status input. Wire the dismiss handler to the design system's close input only if provided. Render message content inside the alert body.
 
 ### Field Value Display Component
 
 Used for: FieldValueList, CaseSummaryFields, DetailsFields
 
-```typescript
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface FieldValueListProps extends PConnProps {
-  name?: string;
-  value?: string;
-  variant?: 'stacked' | 'inline';
-}
-
-export default function FieldValueList(props: FieldValueListProps) {
-  const { name, value, variant = 'inline' } = props;
-
-  if (variant === 'stacked') {
-    return (
-      <div className='field-value-stacked'>
-        <span className='field-label'>{name}</span>
-        <span className='field-value-large'>{value}</span>
-      </div>
-    );
-  }
-
-  return (
-    <div className='field-value-inline'>
-      {name && <span className='field-label'>{name}: </span>}
-      <span className='field-value'>{value}</span>
-    </div>
-  );
-}
-```
+**Structure:**
+
+1. **Define the input contract** (Pattern A — extends the project's base component interface) with fields for `name` (optional string), `value` (any), and `variant` (optional — `'stacked'` or `'inline'`, defaulting to `'inline'`).
+2. **Stacked variant** — when `variant` is `'stacked'`, render the label on its own line above the value. The value should use a larger/emphasized typography style.
+3. **Inline variant** (default) — render the label and value side by side. The label occupies roughly 1/3 width, value occupies 2/3. If `name` is not provided, render only the value at full width.
+4. **Empty value handling** — if `value` is undefined or an empty string, display a placeholder (`'---'`).
 
 ### Complex Display Component (with PConnect for data)
 
 Used for: FieldGroup, FieldGroupList, Pulse
 
-```typescript
-import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface FieldGroupProps extends PConnProps {
-  label?: string;
-  showLabel?: boolean;
-}
-
-export default function FieldGroup(props: FieldGroupProps) {
-  const { getPConnect, label, showLabel = true } = props;
-  const pConn = getPConnect();
-  const children = pConn.getChildren();
-
-  return (
-    <fieldset>
-      {showLabel && label && <legend>{label}</legend>}
-      {children.map((child, i) =>
-        createElement(createPConnectComponent(), { ...child, key: `fg-${i}` })
-      )}
-    </fieldset>
-  );
-}
-```
+**Structure:**
+
+1. **Define the input contract** (Pattern A — extends the project's base component interface) with component-specific fields (e.g., `label`, `showLabel`).
+2. **Obtain the PConnect instance** by calling `getPConnect()` from the component's inputs.
+3. **Retrieve children** via `pConn.getChildren()` — this returns an array of child component configurations from the Pega engine.
+4. **Render children dynamically** — iterate over the children array and render each child configuration using the project's PConnect bridge utility, keyed uniquely. This bridges the Pega component tree into the chosen framework's rendering model.
+5. **Wrap in semantic HTML** — use appropriate semantic elements (e.g., `<fieldset>` with `<legend>` for grouped fields). Conditionally show labels based on the `showLabel` input.
 
 ---
 
@@ -179,33 +82,22 @@ DSE components use one of three approaches depending on the component and design
 
 ### CSS File Pattern (DS-agnostic, preferred for Field Value components)
 
-```css
-/* FieldValueList.css */
-.field-value-inline {
-  display: flex;
-  gap: 0.5rem;
-  align-items: baseline;
-}
-
-.field-label {
-  font-weight: 600;
-  color: var(--text-secondary);
-}
+Create a co-located `.css` file named after the component. Typical CSS conventions for DSE components:
 
-.field-value-large {
-  font-size: 1.25rem;
-  font-weight: 500;
-}
-```
+- **Inline layout** — use `display: flex` with a small gap (`0.5rem`) and `align-items: baseline` for label/value pairs.
+- **Labels** — `font-weight: 600` with a secondary text color (use a CSS custom property like `var(--text-secondary)`).
+- **Large values (stacked variant)** — `font-size: 1.25rem`, `font-weight: 500`.
+- Use CSS custom properties (design tokens) for colors and spacing — never hardcode pixel values for spacing.
+- Class names follow the pattern `.component-name-element` (e.g., `.field-value-inline`, `.field-label`).
 
-### Design System Style Props (use if your DS provides them)
+### Design System Style Inputs (use if your DS provides them)
 
-If the chosen design system provides built-in spacing, typography, or layout props, prefer them over plain CSS:
+If the chosen design system provides built-in spacing, typography, or layout inputs, prefer them over plain CSS:
 
-- Use the DS's layout wrapper (e.g., `<Stack>`, `<Flex>`, `<HStack>`) instead of manual flex CSS
-- Use DS typography components (e.g., `<Text>`, `<Heading>`) instead of raw `<span>`/`<div>`
+- Use the DS's layout primitives (e.g., a stack, flex, or grid wrapper component) instead of manual flex CSS
+- Use the DS's typography primitives (e.g., a text or heading component) instead of raw `<span>`/`<div>`
 - Use DS CSS custom properties or tokens for spacing — never hardcode `px` values
-- Discover which style props are available from the installed `.d.ts` files before using them
+- Discover which style inputs are available from the design system's type declarations before using them
 
 ---
 
@@ -225,12 +117,7 @@ The component-specific skill file specifies which pattern applies.
 
 **2. If the chosen design system is not listed** — use the component purpose and pattern category above to pick the closest DS primitive.
 
-**3. Discover the API from installed packages** — confirm component names and props from `.d.ts` before writing JSX:
-
-```bash
-find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Alert\|Badge\|Avatar" | head -5
-grep -A 30 "interface.*Props" <path-to-file>
-```
+**3. Discover the API from installed packages** — confirm component names and inputs from the design system's type declarations before writing the component's markup. Search the design system package's type declarations for relevant component interfaces (e.g., look for files mentioning `Alert`, `Badge`, or `Avatar` and read the exported input interface to confirm available input names and types).
 
 **4. Variant mapping** — always map Pega's variant names to your DS equivalent before passing to DS components:
 
@@ -245,19 +132,10 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 ## Registration
 
-Register DSE components in `src/components/component-map.ts`:
-
-```typescript
-import AlertBanner from './designSystemExtension/AlertBanner';
-import FieldValueList from './designSystemExtension/FieldValueList';
+Register DSE components in the project's component map:
 
-// In getSampleComponentMap():
-{
-  ...sdkComponents,
-  AlertBanner,
-  FieldValueList,
-}
-```
+1. **Import** the component's default export from its folder under the design-system-extension components directory.
+2. **Add the component** to the object returned by the project's component registration function, using the component name as the key (must match the Pega registration key exactly). The component is spread alongside the base component map.
 
 ---
 
@@ -281,11 +159,11 @@ import FieldValueList from './designSystemExtension/FieldValueList';
 
 ## Key Conventions
 
-1. **Default export** — `export default function ComponentName`.
-2. **Flexible messages** — Always handle both `string` and `object` formats for text props (Pega may send either).
+1. **Default export** — export the component as the module's default export.
+2. **Flexible messages** — Always handle both `string` and `object` formats for text inputs (Pega may send either).
 3. **No side effects** — DSE components should be pure renderers. No data fetching or mutations.
-4. **Variant mapping** — Map Pega variant names (urgent, warning, etc.) to your design system's equivalents.
+4. **Variant mapping** — Map Pega variant names (urgent, warning, etc.) to the design system's equivalents.
 5. **Display modes** — If a DSE component is also used as a display mode by field components (e.g., FieldValueList), it should be simple and fast to render.
-6. **Graceful fallbacks** — Handle missing/undefined props gracefully with defaults.
-7. **CSS over styled-components** — DSE components in react-sample typically use plain CSS files or MUI `sx` prop, not styled-components.
+6. **Graceful fallbacks** — Handle missing/undefined inputs gracefully with defaults.
+7. **Prefer plain CSS or the design system's built-in styling mechanism** over CSS-in-JS libraries, unless the project's conventions dictate otherwise.
 8. **Accessible markup** — Use semantic HTML (fieldset/legend for groups, proper heading levels, ARIA labels).

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md

@@ -0,0 +1,130 @@
+# Skill: Analyze Customer Repository
+
+Scan a customer's application codebase and produce a structured **Design Profile** document that captures their design system, coding conventions, and component patterns. This profile is consumed by the component generation workflow to produce Pega components that blend seamlessly with the customer's existing application.
+
+---
+
+## Purpose
+
+When Pega case flows are embedded into a customer's existing application, the generated Pega components must visually and structurally match the host application. This skill extracts the information needed to achieve that match.
+
+---
+
+## What to Extract
+
+| Aspect                           | Discovery approach                                                                       | Output                                                                                                                                                               |
+| -------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Framework & language**         | Read project configuration and dependency manifest                                       | Framework name + version, primary language, module system                                                                                                            |
+| **UI component library**         | Identify UI/component packages in dependencies                                           | Library name + version (or "custom" if no third-party library)                                                                                                       |
+| **Theme & design tokens**        | Search for theme configuration files, token/variable definitions, style constants        | Token inventory: colors (primary, secondary, error, background, text), spacing scale, typography (font families, sizes, weights), border radii, shadows, breakpoints |
+| **Component structure patterns** | Read 3–5 representative form-like components (text inputs, selects, buttons, checkboxes) | How they define their input interface, internal state, event handling, and output/rendering                                                                          |
+| **Styling approach**             | Detect the styling mechanism used across components                                      | Identifier (utility classes, CSS modules, CSS-in-JS, scoped styles, inline, etc.) + import/usage pattern                                                             |
+| **File & folder conventions**    | Analyze the project's component directory structure                                      | Naming convention (casing, separators), folder-per-component vs flat, barrel/re-export pattern, test co-location                                                     |
+| **Form & state management**      | Identify form-handling libraries or patterns in dependencies and source                  | Library or pattern name + how values, validation, and submission are handled                                                                                         |
+| **Import & module conventions**  | Analyze import statements across multiple files                                          | Path aliasing, barrel imports, relative vs absolute, grouping order                                                                                                  |
+| **Validation & error display**   | Observe how existing components show validation feedback                                 | Pattern: inline message, tooltip, border color change, icon, combination                                                                                             |
+
+---
+
+## Steps
+
+### Step 1 — Identify project fundamentals
+
+Read the project's dependency manifest (the file that lists packages and their versions). From it, determine:
+
+- The application framework and its version
+- The primary language and its configuration
+- The UI component library (if any) and version
+- Any form-handling, state management, or validation libraries
+- The styling library (if separate from the UI library)
+
+### Step 2 — Locate theme and design token configuration
+
+Search the project for theme/token definitions. Look for:
+
+- Files with "theme", "tokens", "variables", "palette", "colors", or "design" in their name or path
+- Style variable definition files (custom properties, constants, exported objects)
+- Configuration files for utility-class frameworks (if applicable)
+
+Read the discovered files and extract:
+
+- **Color palette** — primary, secondary, accent, error/danger, warning, success, neutral/background, text colors
+- **Spacing scale** — the progression of spacing values used
+- **Typography** — font families, size scale, weight scale, line heights
+- **Border radii** — small, medium, large, full/rounded values
+- **Shadows** — elevation levels used
+- **Breakpoints** — responsive design boundaries (if defined)
+
+### Step 3 — Analyze representative components
+
+Find 3–5 components that handle user input (text fields, selects/dropdowns, checkboxes, date pickers, buttons). Prioritize components that:
+
+- Accept user input and emit value changes
+- Show validation feedback
+- Support disabled/read-only states
+
+For each component, note:
+
+1. **Input interface** — how the component defines what it accepts (typed props, attributes, inputs, parameters)
+2. **Internal state** — how it manages transient state (controlled vs uncontrolled, local vs lifted)
+3. **Event handling** — how it reports value changes and blur/commit events to the parent
+4. **Validation display** — how it shows error messages, styling changes, or icons on invalid state
+5. **Styling mechanism** — how it applies visual styles (class names, style objects, utility classes, scoped selectors)
+6. **Accessibility** — labels, ARIA attributes, focus management
+
+### Step 4 — Determine file and folder conventions
+
+List the project's component directory and observe:
+
+- **Folder structure** — flat list, folder-per-component, grouped by type/feature, or nested
+- **Naming convention** — PascalCase, camelCase, kebab-case, snake_case for files and folders
+- **Module boundaries** — barrel files (index re-exports), direct imports, or path-based resolution
+- **Co-located files** — whether tests, styles, and types live alongside the component or separately
+
+### Step 5 — Analyze import conventions
+
+Read 5–10 import sections across different files and determine:
+
+- **Path resolution** — aliases (e.g., `@/`, `~/`, `#`) vs relative paths
+- **Grouping order** — external packages first, then internal modules, then relative imports (or other order)
+- **Named vs default imports** — which pattern dominates
+- **Style imports** — how stylesheets or style modules are imported
+
+### Step 5.1 — Analyze navigation and presentation surfaces
+
+The embedded flow has to appear somewhere, and that surface should be one the application already uses. Capture how this application presents a self-contained task:
+
+- **Routing approach** — how routes are declared and navigated (file-based, configuration-based, or a router API), and how a route change is triggered from a control
+- **Overlay primitives** — which of dialog, modal, drawer, sheet or popover the project actually uses, where those primitives come from, and how one is opened and dismissed
+- **Existing task entry points** — find 2–3 places where a control starts a multi-step or form-based task, and record for each: the control's visible label, the file it lives in, and what it does — opens an overlay, navigates to a route, or reveals a region in place
+- **Layout shell** — what wraps a routed page (navigation, header, sidebar), so a flow mounted at a route keeps the surroundings the customer expects
+
+This is what makes it possible to offer the user real choices in their own vocabulary instead of a generic list of surfaces, and to infer the right surface when a launch control already has behaviour. Record what exists; do not recommend a surface here.
+
+### Step 6 — Synthesize into Design Profile
+
+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.
+
+**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.
+
+**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).
+
+**Section 3: Component Patterns** — describe each convention as a sub-section: Input Interface Convention (how components define what they accept), State Management Convention (how local state is handled), Event Handling Convention (how value changes are reported — immediate, on blur, debounced), Validation Display Convention (where errors appear, how error styling is applied), Styling Convention (how styles are applied to elements, how conditional styles work).
+
+**Section 4: File Conventions** — list the folder structure type, naming convention (casing), re-export/barrel pattern, test file location, and style file location.
+
+**Section 5: Import Conventions** — list path resolution approach (aliases or relative), grouping order, default vs named import preference, and style import pattern.
+
+**Section 6: Representative Component Examples** — list the 3–5 components analyzed with their file paths and why each was selected (e.g., "text input with validation", "select with async options"). These serve as reference points the generation workflow can re-read for detailed implementation guidance.
+
+**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.
+
+Save this document to `pega-components/.design-profile.md` in the customer's project.
+
+---
+
+## Notes
+
+- If the project uses no third-party UI library (fully custom components), the "UI Library" field should be "Custom" and the representative component analysis becomes especially important — the generated Pega components will directly replicate the customer's custom primitives.
+- If multiple styling approaches are mixed (e.g., utility classes for layout + component library for inputs), document both and specify which is used where.
+- Do not include actual source code in the Design Profile. Describe patterns in prose. Reference file paths for the AI to read during generation.