@pega/sdk 0.0.1 → 0.0.3

package/dist/index.js

@@ -343,9 +343,6 @@ var SKIP_ENTRIES = /* @__PURE__ */ new Set([
   ".expo",
   ".angular"
 ]);
-function shouldSkipFile(name) {
-  return name.endsWith(".tgz");
-}
 async function scaffold(choices, targetDir, onProgress) {
   const report = (message) => onProgress?.(message);
   const {
@@ -413,7 +410,7 @@ async function scaffold(choices, targetDir, onProgress) {
     }
   }
   if (!aiTool) {
-    for (const dir of [".github", ".cursor", "AGENTS.md"]) {
+    for (const dir of [".github", ".cursor", "AGENTS.md", ".claude"]) {
       const target = path.join(targetDir, dir);
       if (fs.existsSync(target)) {
         fs.rmSync(target, { recursive: true });
@@ -423,7 +420,7 @@ async function scaffold(choices, targetDir, onProgress) {
     const AI_TOOL_PATHS = {
       copilot: [".github"],
       cursor: [".cursor"],
-      "claude-code": ["AGENTS.md"]
+      "claude-code": ["AGENTS.md", ".claude"]
     };
     const allAiPaths = Object.values(AI_TOOL_PATHS).flat();
     const keepPaths = AI_TOOL_PATHS[aiTool];
@@ -464,19 +461,6 @@ function transformPackageJson(pkgJsonPath, projectName) {
   const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
   pkgJson.name = projectName;
   delete pkgJson.private;
-  const fileDepsMap = {
-    "@pega/auth": "^0.2.42",
-    "@pega/constellationjs": "^0.26.2"
-  };
-  for (const section of ["dependencies", "devDependencies"]) {
-    const deps = pkgJson[section];
-    if (!deps) continue;
-    for (const [name, version] of Object.entries(deps)) {
-      if (typeof version === "string" && version.startsWith("file:")) {
-        deps[name] = fileDepsMap[name] || "*";
-      }
-    }
-  }
   fs.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
 }
 function transformTsConfig(tsconfigPath) {
@@ -541,7 +525,6 @@ function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     if (SKIP_ENTRIES.has(entry.name)) continue;
-    if (!entry.isDirectory() && shouldSkipFile(entry.name)) continue;
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@pega/sdk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Scaffold a Pega SDK application project",
   "type": "module",
   "bin": {
     "sdk": "./dist/index.js"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "files": [
     "dist",
     "templates",

package/templates/react-sdk-reference/.claude/instructions/component-map.md

@@ -0,0 +1,38 @@
+<!-- Applies to: **/component-map.ts -->
+
+# Component Map Rules
+
+The component map (`src/components/component-map.ts`) is the registry that maps Pega component names to React implementations.
+
+## Structure
+
+```typescript
+import { sdkComponents } from '@pega/sdk-react';
+
+function getSampleComponentMap() {
+  return {
+    ...sdkComponents,   // NEVER remove this — provides infrastructure
+    // Your components below:
+    TextInput,
+    Dropdown,
+    // ...
+  };
+}
+```
+
+## Rules
+
+1. **NEVER remove `...sdkComponents`** — it provides View, Region, Reference, RootContainer, FlowContainer, ViewContainer, Assignment, AssignmentCard, ErrorBoundary, MultiStep, CaseSummary, and their aliases.
+
+2. **Map keys must match Pega component names exactly** — these are resolved at runtime by the platform. The key is what Pega sends; the value is your React component.
+
+3. **To replace a component**: change its import path to your new implementation. Do NOT rename the key.
+
+4. **To add a new component**: add the import + add a new key-value entry.
+
+5. **Key naming exceptions** (where key differs from variable name):
+   - `Date: DateField` (Date is reserved in JS)
+   - `URL: URLComponent` (URL is a global)
+   - `Todo: ToDo` (casing difference)
+
+6. **Keep the `registerSampleComponents` function** — it registers all entries into the `ComponentRegistry` instance used by the PConnect bridge.

package/templates/react-sdk-reference/.claude/instructions/dse-component.md

@@ -0,0 +1,75 @@
+<!-- Applies to: src/components/designSystemExtension/**/*.tsx -->
+
+# Design System Extension Component Rules
+
+When creating or modifying DSE components, follow these rules:
+
+## What Are DSE Components?
+
+Design System Extension components are display-focused presentational components. They sit between pure UI and data-fetching widgets. Some receive `getPConnect`, others receive only display props.
+
+## Patterns
+
+### Pattern A: With PConnect (data-aware display)
+
+Used for: FieldValueList, CaseSummaryFields, DetailsFields
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface FieldValueListProps extends PConnProps {
+  name?: string;
+  value?: string;
+  variant?: 'stacked' | 'inline';
+}
+
+export default function FieldValueList(props: FieldValueListProps) {
+  const { name, value, variant = 'inline' } = props;
+  // Render a label-value pair
+}
+```
+
+### Pattern B: Without PConnect (pure presentation)
+
+Used for: AlertBanner, Banner, Operator
+
+```typescript
+interface AlertBannerProps {
+  variant: 'urgent' | 'warning' | 'info' | 'success';
+  heading?: string;
+  messages: Array<string | { label?: string; description?: string }>;
+  onClose?: () => void;
+}
+
+export default function AlertBanner(props: AlertBannerProps) {
+  // Render an alert/notification banner
+}
+```
+
+### Pattern C: Rich editor (extends PConnFieldProps)
+
+Used for: RichTextEditor
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface RichTextEditorProps extends PConnFieldProps {
+  content?: string;
+}
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- DSE components are the **most commonly referenced by other components** via `getComponentFromRegistry('FieldValueList')` — every field uses FieldValueList for display modes
+- Keep the same export name (default export) and prop interface shape
+- If you replace FieldValueList, ensure it accepts `name`, `value`, and optional `variant` props
+- AlertBanner must handle the `messages` array format (both strings and `{label, description}` objects)
+- Do NOT drop visual styles when removing `makeStyles` — always map them to an equivalent

package/templates/react-sdk-reference/.claude/instructions/field-component.md

@@ -0,0 +1,71 @@
+<!-- Applies to: src/components/field/**/*.tsx -->
+
+# Field Component Rules
+
+When creating or modifying field components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnFieldProps } from '@pega/sdk-react';
+   ```
+
+2. **Define a props interface extending `PConnFieldProps`**:
+   ```typescript
+   interface MyFieldProps extends PConnFieldProps {
+     // additional props specific to this field
+   }
+   ```
+
+3. **Export as default function component**:
+   ```typescript
+   export default function MyField(props: MyFieldProps) { ... }
+   ```
+
+## Required Behaviors
+
+1. **Extract standard props**: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
+
+2. **Get PConnect APIs**:
+   ```typescript
+   const pConn = getPConnect();
+   const actions = pConn.getActionsApi();
+   const propName = (pConn.getStateProps() as any).value;
+   ```
+
+3. **Handle displayMode** (MUST be before the main return):
+   ```typescript
+   if (displayMode === 'DISPLAY_ONLY') {
+     return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+   }
+   if (displayMode === 'STACKED_LARGE_VAL') {
+     return <FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />;
+   }
+   ```
+
+4. **Use local state + blur pattern**:
+   - `onChange` → update local state only
+   - `onBlur` → call `handleEvent(actions, 'changeNblur', propName, localValue)`
+
+5. **Show validation**: Display `validatemessage` and apply error styling when `status === 'error'`
+
+6. **Pass test ID**: Set `data-test-id={testId}` on the interactive element
+
+7. **Use `getComponentFromRegistry('FieldValueList')`** — never hardcode FieldValueList import
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, {{designSystem}} component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Do NOT
+
+- Skip `displayMode` handling — it breaks read-only views
+- Call `handleEvent` on every keystroke — only on blur
+- Hardcode component imports for components that exist in the registry
+- Remove the `handleEvent` import from `../../helpers/event-utils`
+- Drop visual styles when removing `makeStyles` — always map them to an equivalent

package/templates/react-sdk-reference/.claude/instructions/template-component.md

@@ -0,0 +1,92 @@
+<!-- Applies to: src/components/template/**/*.tsx -->
+
+# Template Component Rules
+
+When creating or modifying template/layout components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnProps } from '@pega/sdk-react';
+   ```
+
+2. **Export as default function component**:
+   ```typescript
+   export default function MyTemplate(props: MyTemplateProps) { ... }
+   ```
+
+## Template Categories
+
+### Layout Templates (TwoColumn, OneColumn, NarrowWide, WideNarrow)
+
+Receive React `children` directly:
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+
+interface TwoColumnProps extends PConnProps {
+  templateCol?: string;  // e.g. "1fr 1fr", "2fr 1fr"
+}
+
+export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
+  const { children, templateCol = '1fr 1fr' } = props;
+  const childrenToRender = children as ReactElement[];
+  // Render childrenToRender[0], childrenToRender[1], etc. in grid columns
+}
+```
+
+### Form/View Templates (DefaultForm, Details, CaseView)
+
+Render children via `getPConnect().getChildren()`:
+
+```typescript
+export default function DefaultForm(props: DefaultFormProps) {
+  const { getPConnect } = props;
+  const pConn = getPConnect();
+  const children = pConn.getChildren() as any[];
+
+  return (
+    <div>
+      {children.map((child, i) => (
+        <PConnectComponent key={i} getPConnect={() => child.getPConnect()} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Page Templates (OneColumnPage, TwoColumnPage)
+
+Wrap a layout with page-level chrome (title, actions):
+
+```typescript
+export default function OneColumnPage(props: PageProps) {
+  const { getPConnect, children } = props;
+  const pConn = getPConnect();
+  const title = pConn.getDataObject('')?.caseInfo?.name;
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      {children}
+    </div>
+  );
+}
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's layout props, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Use `PConnectComponent` from `@pega/sdk-react` to render PConnect children
+- Grid proportions come from `templateCol` prop — parse it to calculate column ratios
+- Templates must not call `handleEvent` or interact with field state
+- Templates are layout-only — they arrange, not edit
+- Do NOT drop column gap, padding, or alignment styles when removing MUI `Grid` — replicate them in the replacement layout

package/templates/react-sdk-reference/.claude/instructions/widget-component.md

@@ -0,0 +1,87 @@
+<!-- Applies to: src/components/widget/**/*.tsx -->
+
+# Widget Component Rules
+
+When creating or modifying widget components, follow these rules:
+
+## Required Structure
+
+1. **Import types from `@pega/sdk-react`**:
+   ```typescript
+   import type { PConnProps } from '@pega/sdk-react';
+   // or PConnFieldProps if the widget behaves like a field (e.g., Attachment)
+   ```
+
+2. **Export as default function component**:
+   ```typescript
+   export default function MyWidget(props: MyWidgetProps) { ... }
+   ```
+
+## Widget Patterns
+
+### Data-Fetching Widget (ToDo, CaseHistory, Followers)
+
+Fetches data from Pega data pages on mount:
+
+```typescript
+export default function MyWidget(props: MyWidgetProps) {
+  const { getPConnect, datasource, headerText } = props;
+  const pConn = getPConnect();
+  const [data, setData] = useState<any[]>([]);
+
+  useEffect(() => {
+    const context = pConn.getContextName();
+    PCore.getDataPageUtils()
+      .getDataAsync(datasource?.source, context, {})
+      .then((response: any) => {
+        setData(response.data || []);
+      });
+  }, []);
+
+  return (
+    <Card>
+      <CardHeader title={headerText} />
+      <CardContent>{/* render data */}</CardContent>
+    </Card>
+  );
+}
+```
+
+### Action Widget (ToDo)
+
+Triggers case actions:
+
+```typescript
+// Get assignments and trigger actions
+import { getToDoAssignments } from '@pega/sdk-react';
+
+const assignments = getToDoAssignments(getPConnect);
+// Each assignment has: onClick callback, urgency, name, etc.
+```
+
+### File Widget (Attachment, FileUtility)
+
+Handles file upload/download via PCore attachment APIs:
+
+```typescript
+PCore.getAttachmentUtils().uploadAttachment(file, onUploadProgress, errorHandler, context);
+PCore.getAttachmentUtils().downloadAttachment(attachmentId, context);
+```
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via inline `style` props, the new design system's component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Widgets are self-contained — they manage their own data fetching
+- Use `PCore.getDataPageUtils()` for data page access
+- Use `PCore.getAttachmentUtils()` for file operations
+- Always handle loading and error states
+- Widgets may use `PCore.getPubSubUtils()` to subscribe to events
+- Clean up subscriptions in `useEffect` return function
+- Do NOT drop card padding, list item spacing, or avatar sizing when removing MUI components — replicate them in the replacement

package/templates/react-sdk-reference/.claude/prompts/add-component.md

@@ -0,0 +1,144 @@
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component name** — the exact name (e.g. `AutoComplete`, `DatePicker`)
+- **Component type** — one of: `field` | `template` | `widget` | `designSystemExtension`
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output path** — the exact or relative path where the component should be generated (e.g. `src/components/field/AutoComplete`)
+
+If any of the four are missing or ambiguous, ask the user all unresolved items in **one numbered list** and wait for their answers before continuing. Do not guess or proceed with assumptions.
+
+Example questions to ask (only ask the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is the exact component name?
+3. What type of component is this? (field / template / widget / designSystemExtension)
+4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
+
+### Case-insensitive component name matching
+
+The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `.claude/skills/field-skills/`, `.claude/skills/template-skills/`, `.claude/skills/widget-skills/`, and `.claude/skills/design-system-extension-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+
+Once all four are known, continue to Step 1.
+
+---
+
+## Step 1 — Check for existing component (overwrite check)
+
+Before generating, check if a component already exists at the resolved output path:
+
+1. Check if `<outputPath>/<ComponentName>.tsx` (or the directory) already exists.
+2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - If the user says **yes**, proceed to overwrite.
+   - If the user says **no**, stop and skip generation.
+3. If it **does not exist**, continue to Step 2.
+
+---
+
+## Step 2 — Check for skill files
+
+Always read the **general type skill** for the component type:
+
+| Component Type | General Skill File |
+|---|---|
+| `field` | `.claude/skills/field-components.md` |
+| `template` | `.claude/skills/template-components.md` |
+| `widget` | `.claude/skills/widget-components.md` |
+| `designSystemExtension` | `.claude/skills/design-system-extension.md` |
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type | Specific Skill Location |
+|---|---|
+| `field` | `.claude/skills/field-skills/<ComponentName>.md` |
+| `template` | `.claude/skills/template-skills/<ComponentName>.md` |
+| `widget` | `.claude/skills/widget-skills/<ComponentName>.md` |
+| `designSystemExtension` | `.claude/skills/design-system-extension-skills/<ComponentName>.md` |
+
+If the component-specific skill file exists, read it fully. Pay special attention to:
+- **Behavioral Contract** — state management, event handling, option loading, edge cases
+- **Design System Mapping** table — the recommended component for the chosen design system
+
+You must read **both** the general type skill and the component-specific skill (if it exists) before proceeding.
+
+Examples:
+- `AutoComplete` (field) → read `field-components.md` + `field-skills/AutoComplete.md`
+- `AdvancedSearch` (template) → read `template-components.md` + `template-skills/AdvancedSearch.md`
+- `AppAnnouncement` (widget) → read `widget-components.md` + `widget-skills/AppAnnouncement.md`
+- `AlertBanner` (designSystemExtension) → read `design-system-extension.md` + `design-system-extension-skills/AlertBanner.md`
+
+If no component-specific skill file exists, continue using the general pattern from the type skill.
+
+---
+
+## Step 3 — Check and install dependencies
+
+Run:
+```
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+```
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+---
+
+## Step 4 — Discover the design system's API
+
+Before writing any code, inspect the installed package:
+
+1. `cat node_modules/<designSystem>/README.md` — note the correct import path and usage patterns for the installed version.
+2. `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"` — lists every component actually exported by the installed version.
+3. For every component you plan to use, read its TypeScript prop interface from the installed `.d.ts`:
+   `find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3`, then `grep -A 40 "interface.*Props"` on the result.
+4. Only use component names and prop names confirmed in those files. Do not rely on training knowledge of the API.
+
+Also check:
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+---
+
+## Step 5 — Generate the component
+
+Create the component directory at the resolved output path (from Step 0).
+
+Create `<ComponentName>.tsx` using the pattern for the component type:
+
+- **field**: Extend `PConnFieldProps` from `@pega/sdk-react`. Extract `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Call `handleEvent(actions, 'changeNblur', propName, value)` on blur. Handle `displayMode === 'DISPLAY_ONLY'` and `'STACKED_LARGE_VAL'` using `getComponentFromRegistry('FieldValueList')`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+- **template**: Extend `PConnProps`, render children via the design system's grid/layout primitives
+- **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
+- **designSystemExtension**: Pure display props or extend `PConnProps`
+
+Create `index.tsx`:
+```typescript
+export { default } from './<ComponentName>';
+```
+
+---
+
+## Step 6 — Register in component-map.ts
+
+Edit `src/components/component-map.ts`:
+
+1. Add the import at the top of the file, in the correct section (Fields / Templates / Widgets / Design System Extension)
+2. Add an entry in `getSampleComponentMap()` under the matching category comment
+
+Do not restructure or reorder any existing entries.
+
+---
+
+## Step 7 — Verify the build
+
+Run:
+```
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report what files were created and what was added to `component-map.ts`.