@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.github/skills/widget-skills/ToDo.md

@@ -1,198 +0,0 @@
-# Skill: ToDo
-
-Assignment worklist widget. Displays the current user's pending assignments with expand/collapse, click-to-open, priority indicators, badge counts, responsive layout, and snackbar error notifications.
-
-> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, props interface, data-fetching patterns, and registration conventions common to ALL widget components.
-
----
-
-## Component Purpose
-
-Renders a compact to-do / worklist panel showing the user's pending assignments. Shows the top 3 items by default with a "Show more" / "Show less" toggle. Supports two modes: `worklist` (personal workbasket) and `todo` (case-level assignments). Clicking an item opens the assignment. A badge in the card header shows the total count.
-
-## Pega Metadata
-
-- **Registration key:** `Todo` (note: lowercase `o` in the key; file is `ToDo.tsx`)
-- **Category:** Widget — assignment / action
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop           | Type       | Required | Description                                                                                        |
-| -------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------- |
-| `datasource`   | `any`      | No       | Array of assignments passed directly (used in `todo` type). If provided, skips the data page fetch |
-| `myWorkList`   | `any`      | No       | Work list config object `{ datapage: string, fields: [...] }` — for `worklist` type                |
-| `caseInfoID`   | `string`   | No       | Case ID to filter assignments (used in `todo` type)                                                |
-| `headerText`   | `string`   | No       | Widget title. Default: `"To do"`                                                                   |
-| `itemKey`      | `string`   | No       | Field key (reserved, currently unused)                                                             |
-| `showTodoList` | `boolean`  | No       | Whether to show the assignment list. Default `true`                                                |
-| `type`         | `string`   | No       | `'worklist'` (personal work) or `'todo'` (case-level). Default `'worklist'`                        |
-| `context`      | `string`   | No       | Context name for API calls. Falls back to `pConn.getContextName()`                                 |
-| `isConfirm`    | `boolean`  | No       | Confirmation mode — adjusts rendering for post-submit confirmation view                            |
-| `getPConnect`  | `function` | Yes      | PConnect getter                                                                                    |
-
-## Behavioral Contract
-
-### Data Source Resolution
-
-**`type === 'todo'` (case-level):**
-
-- Use `datasource` prop directly (array of assignment objects).
-- `caseInfoID` is used to scope the assignments.
-
-**`type === 'worklist'` (personal work):**
-
-- Fetch from `myWorkList.datapage` (e.g., `D_WorkList`) via:
-  ```
-  PCore.getDataPageUtils().getDataAsync(
-    myWorkList.datapage,
-    context,
-    {},
-    { pageNumber: 1, pageSize: 50 },
-    { select: myWorkList.fields },
-    { invalidateCache: true }
-  )
-  ```
-- Map the response to assignment objects.
-
-### Top 3 + Show More
-
-- `showCount` state: default `3`.
-- Render only `assignments.slice(0, showCount)`.
-- If `assignments.length > 3`:
-  - Show a `"Show more"` button → sets `showCount = assignments.length`.
-  - When expanded: show `"Show less"` button → sets `showCount = 3`.
-
-### Badge Count
-
-- Render a `<Badge badgeContent={assignments.length}>` on the card header or alongside the title.
-- Badge shows the total count of assignments, not the currently-visible count.
-
-### Open Assignment
-
-On item click:
-
-```typescript
-pConn.getActionsApi().openAssignment(
-  assignment.pxRefObjectKey, // case key
-  assignment.pxRefObjectClass, // class name
-  {
-    containerName: pConn.getContainerName() || PCore.getConstants().APP.APP,
-    channelName: '',
-  },
-);
-```
-
-### Assignment Item Rendering
-
-For each assignment, show:
-
-- **Avatar:** Circle with user initials (derived from `pConn.getContextObject?.().pyLabel` or operator name).
-- **Name/title:** `assignment.pyLabel` — the assignment task name.
-- **Status badge (worklist only):** `assignment.pyStatusWork` — colored status pill.
-- **Priority/urgency:** `assignment.pyUrgencyWork` — urgency level indicator.
-- **Child case indicator:** If `assignment.isChild === true`, show an indent or nested indicator.
-- **Arrow icon:** Right-pointing arrow (`<ArrowForwardIosOutlinedIcon>`) indicating clickable.
-
-### Responsive Layout
-
-Use `useMediaQuery(theme.breakpoints.down('sm'))` (MUI) to detect mobile:
-
-- **Desktop:** Show avatar, name, status, priority, and arrow in a horizontal row.
-- **Mobile:** Stack or truncate elements for narrow display.
-
-### `canPerform` Permission Check
-
-If an assignment has `canPerform === false`, render it as non-clickable (greyed out, no onClick handler).
-
-### Snackbar Error
-
-- On `openAssignment` failure, catch the error and show a `<Snackbar>` with the error message.
-- Auto-hide after 3000ms.
-- `<IconButton>` (`<CloseIcon>`) to manually dismiss.
-
-### Operator Avatar Initials
-
-Extract initials from `PCore.getEnvironmentInfo().getOperatorName()`:
-
-```typescript
-const initials = operatorName
-  .split(' ')
-  .map((w) => w[0])
-  .join('')
-  .substring(0, 2)
-  .toUpperCase();
-```
-
-## Visual Specifications
-
-### Card Layout
-
-| Element               | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| Card header           | `headerText` (default `"To do"`) + badge with count |
-| Assignment rows       | Up to `showCount` items                             |
-| Show more/less button | Below the last visible item                         |
-
-### Assignment Row
-
-| Element            | Desktop   | Mobile          |
-| ------------------ | --------- | --------------- |
-| Avatar circle      | Shown     | Shown           |
-| Task name          | Full text | Truncated       |
-| Status badge       | Shown     | Hidden or small |
-| Priority indicator | Shown     | Simplified      |
-| Arrow icon         | Shown     | Shown           |
-
-**CSS-only implementation notes:**
-
-- Card: standard card layout.
-- Assignment row: `display: flex; align-items: center; gap: 0.75rem; padding: 10px 0; cursor: pointer; border-bottom: 1px solid var(--divider-color)`.
-- Avatar: `width: 36px; height: 36px; border-radius: 50%; background: var(--avatar-bg); display: flex; align-items: center; justify-content: center; font-size: 0.875rem; font-weight: 600`.
-- Status badge: `padding: 2px 6px; border-radius: 10px; font-size: 0.75rem; background: var(--status-bg-color)`.
-- Priority: `font-size: 0.75rem; color: var(--secondary-text-color)`.
-- Arrow: `margin-left: auto; color: var(--secondary-text-color)`.
-- Non-clickable (canPerform=false): `opacity: 0.5; cursor: not-allowed`.
-- Show more button: `width: 100%; text-align: center; padding: 8px; color: var(--app-primary-color)`.
-
-## Edge Cases & Special Logic
-
-- `type` defaults to `'worklist'` — handle the fallback gracefully if `type` is undefined.
-- `datasource` prop vs fetch: if `datasource` is provided (non-empty), skip the data page fetch entirely.
-- `myWorkList` may be undefined for `todo` type — do not attempt a fetch if it's missing.
-- `showTodoList === false` — render only the card header (with badge count) and hide the list body.
-- `isConfirm === true` — used in the Confirmation template context; may adjust layout to hide certain elements (e.g., hide status badge, show simpler view).
-- Empty assignments — show a `"No tasks"` or `"You're all caught up!"` empty state message.
-- `canPerform` check: if `false`, disable click and show cursor `not-allowed`. Do not open the assignment.
-- Container name fallback: `pConn.getContainerName() || PCore.getConstants().APP.APP` — always provide a container name to `openAssignment`.
-
-## Dependencies
-
-- `PCore.getDataPageUtils().getDataAsync()` — worklist data page fetch
-- `PCore.getEnvironmentInfo()` — operator name for avatar initials
-- `PCore.getConstants()` — CASE_INFO, WORK_BASKET, TODO, APP constants
-- `PCore.getLocaleUtils()` — assignment label localization
-- `pConn.getActionsApi().openAssignment()` — opens the selected assignment
-- MUI: `<Card>`, `<CardContent>`, `<CardHeader>`, `<Avatar>`, `<Typography>`, `<Badge>`, `<List>`, `<ListItem>`, `<ListItemText>`, `<Button>`, `<Snackbar>`, `<IconButton>`, `useMediaQuery`, `useTheme`
-- MUI Icons: `<CloseIcon>`, `<ArrowForwardIosOutlinedIcon>`
-
-## Design System Mapping
-
-**UI control type:** Assignment worklist widget with expand/collapse, click-to-open, badge count, and error toast.
-
-Listed design systems are examples only.
-
-| Design System      | Card                      | List                | Badge               | Snackbar                      |
-| ------------------ | ------------------------- | ------------------- | ------------------- | ----------------------------- |
-| Default (CSS only) | `<div>` card              | `<ul>/<li>`         | CSS counter badge   | Custom toast overlay          |
-| MUI                | `<Card>` + `<CardHeader>` | `<List>/<ListItem>` | `<Badge>`           | `<Snackbar>/<Alert>`          |
-| Ant Design         | `<Card>`                  | `<List>`            | `<Badge count={N}>` | `message.error()`             |
-| Chakra UI          | `<Card>`                  | `<VStack>`          | `<Badge>`           | `useToast()`                  |
-| Shadcn/ui          | `<Card>`                  | `<ul>/<li>`         | Custom badge        | `<Toaster>` + `toast.error()` |
-
-When implementing in a specific design system:
-
-- Show top 3 items by default — `showCount` state controls slice; "Show more/less" toggles between 3 and full length
-- `canPerform === false` must make the row non-clickable — check this before calling `openAssignment`
-- `type === 'worklist'` fetches from a data page; `type === 'todo'` uses the `datasource` prop — both paths must be implemented
-- Operator initials for the avatar must be derived from `PCore.getEnvironmentInfo().getOperatorName()`

package/templates/react-sdk-reference/AGENTS.md

@@ -1,246 +0,0 @@
-# AGENTS — React SDK Reference
-
-> Claude Code instructions for the Pega React SDK reference application.
-> Skill files and workflow prompts are in `.claude/skills/` and `.claude/prompts/`. Read them when asked to generate or replace components.
-
-You are assisting developers in a React reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (MUI, Chakra, Radix, Shadcn, Ant Design, or any other).
-
----
-
-## 1. Repository Purpose
-
-This is a **reference implementation** — not a framework. The UI components (fields, templates, widgets) are intentionally simple MUI-based implementations meant to be swapped out. The SDK wiring (bootstrap, PConnect bridge, component registry) is reusable infrastructure that should NOT be modified.
-
----
-
-## 2. What Is Replaceable vs. Infrastructure
-
-### Replaceable (customer modifies these)
-
-| Directory                               | Purpose                                                     |
-| --------------------------------------- | ----------------------------------------------------------- |
-| `src/components/field/`                 | Form field components (TextInput, Dropdown, Date, etc.)     |
-| `src/components/template/`              | Layout templates (OneColumn, TwoColumn, Details, etc.)      |
-| `src/components/widget/`                | Data widgets (ToDo, Attachment, CaseHistory, etc.)          |
-| `src/components/designSystemExtension/` | Extended UI (AlertBanner, FieldGroup, RichTextEditor, etc.) |
-
-### Infrastructure (do NOT modify unless you know what you're doing)
-
-| File/Directory                          | Purpose                                                   |
-| --------------------------------------- | --------------------------------------------------------- |
-| `src/MashupApp.tsx`                     | Auth + bootstrap + root rendering                         |
-| `src/components/component-map.ts`       | Registry wiring (only add/remove entries)                 |
-| `src/components/infra/`                 | Infrastructure components (ActionButtons, Stages, NavBar) |
-| `src/components/helpers/event-utils.ts` | PConnect event handler utility                            |
-| `@pega/sdk-react`                       | SDK bridge — never modify                                 |
-
----
-
-## 3. Component Architecture
-
-### The PConnect Bridge
-
-Every component receives `getPConnect` as a prop. This is the bridge to the Pega platform:
-
-```typescript
-const pConn = getPConnect();
-const actions = pConn.getActionsApi(); // For field updates
-const propName = (pConn.getStateProps() as any).value; // Property path
-```
-
-### Event Handling Pattern
-
-All field components use this pattern for two-way binding:
-
-```typescript
-import handleEvent from '../../helpers/event-utils';
-
-// On change (local state only):
-function handleChange(event) {
-  setInputValue(event.target.value);
-}
-
-// On blur (push to platform):
-function handleBlur() {
-  handleEvent(actions, 'changeNblur', propName, inputValue);
-}
-```
-
-### Display Mode Handling
-
-Field components must handle `displayMode` prop:
-
-- `undefined` → render editable input
-- `'DISPLAY_ONLY'` → render read-only value via `FieldValueList`
-- `'STACKED_LARGE_VAL'` → render stacked read-only via `FieldValueList` with `variant='stacked'`
-
-### Component Registry
-
-Components are registered by name in `src/components/component-map.ts`:
-
-```typescript
-import { sdkComponents } from '@pega/sdk-react';
-
-function getSampleComponentMap() {
-  return {
-    ...sdkComponents, // Infrastructure (View, Region, FlowContainer, etc.)
-    TextInput, // Your field components
-    Dropdown,
-    // ...
-  };
-}
-```
-
-To add a new component: add the import + add to the map object.
-To replace a component: change the import to point to your new implementation.
-
----
-
-## 4. Props Interfaces
-
-### Field Components (`PConnFieldProps`)
-
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface PConnFieldProps {
-  getPConnect: () => typeof PConnect;
-  label: string;
-  required: boolean;
-  disabled: boolean;
-  value?: string;
-  validatemessage: string;
-  status?: string; // 'error' | 'warning' | undefined
-  onChange: any;
-  onBlur?: any;
-  readOnly: boolean;
-  testId: string;
-  helperText: string;
-  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL'
-  hideLabel: boolean;
-  placeholder?: string;
-}
-```
-
-### Template/Widget Components (`PConnProps`)
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-
-interface PConnProps {
-  getPConnect: () => typeof PConnect;
-}
-```
-
----
-
-## 5. Rules for Replacing Components
-
-1. **Keep the same default export name** — the component-map references it.
-2. **Keep `getPConnect` wiring intact** — extract props, call `handleEvent` on blur.
-3. **Handle `displayMode`** — return `FieldValueList` for read-only modes.
-4. **Handle validation** — show `validatemessage` when `status === 'error'`.
-5. **Preserve `data-test-id`** — pass `testId` to the root interactive element.
-6. **Use `getComponentFromRegistry`** to render sub-components (e.g., `FieldValueList`) — don't hardcode imports for components that might also be replaced.
-
----
-
-## 6. Build & Dev Commands
-
-```bash
-# From monorepo root (if developing locally with source packages):
-npm run build              # Build all packages + samples
-npm run dev:react          # Build + dev server
-
-# From this directory (standalone):
-npm run dev                # Vite dev server (port 3500)
-npm run build              # Production build
-```
-
----
-
-## 7. Key Imports
-
-```typescript
-// From SDK (never modify these)
-import {
-  PConnectComponent,
-  PegaStoreContext,
-  registerComponentCreator,
-  getComponentFromRegistry,
-  sdkComponents,
-} from '@pega/sdk-react';
-import type { PConnProps, PConnFieldProps } from '@pega/sdk-react';
-
-// Event utility (preserve this)
-import handleEvent from '../../helpers/event-utils';
-```
-
----
-
-## 8. Do NOT
-
-- Modify `MashupApp.tsx` bootstrap flow when replacing design system components.
-- Import from `@pega/sdk-react/src/...` — use the package entry point only.
-- Hardcode component references — use `getComponentFromRegistry('Name')` for components that may be overridden.
-- Remove the `...sdkComponents` spread from `component-map.ts`.
-- Use `any` without justification — prefer `unknown` and narrow.
-- Add `@ts-ignore` — use `@ts-expect-error` with explanation if truly needed.
-
----
-
-## 9. Component Generation Workflow — Single Component
-
-When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
-read the full contents of `.claude/prompts/add-component.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
-> For generating **multiple field components** at once, see Section 10.
-
----
-
-## 10. Batch Field Component Generation
-
-When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
-read the full contents of `.claude/prompts/generate-field-components.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
----
-
-## 11. Batch Template Component Generation
-
-When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
-read the full contents of `.claude/prompts/generate-template-components.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
----
-
-## 12. Batch Widget Component Generation
-
-When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
-read the full contents of `.claude/prompts/generate-widget-components.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
----
-
-## 13. Batch Design System Extension Component Generation
-
-When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
-read the full contents of `.claude/prompts/generate-dse-components.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
----
-
-## 14. Generate All Components (Multi-Type)
-
-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"),
-read the full contents of `.claude/prompts/generate-all-components.md` and
-execute every step in order before writing any code.
-Do not skip steps or proceed without reading the required skill files first.
-
-> Use this section when the request spans more than one component type. For a single type, use Sections 10–13.