@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension.mdrules

@@ -0,0 +1,294 @@
+---
+description: design-system-extension
+alwaysApply: false
+---
+
+# 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.
+
+---
+
+## 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)
+```
+
+---
+
+## Props Interface
+
+DSE components have varying prop 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';
+}
+```
+
+### 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)
+
+```typescript
+import type { PConnFieldProps } from '../../../types/PConnProps';
+
+interface RichTextEditorProps extends PConnFieldProps {
+  content?: string;
+}
+```
+
+---
+
+## Implementation Patterns
+
+### Pure Display Component (no PConnect)
+
+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}
+    />
+  );
+}
+```
+
+### 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>
+  );
+}
+```
+
+### 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>
+  );
+}
+```
+
+---
+
+## Styling Patterns
+
+DSE components use one of three approaches depending on the component and design system:
+
+### 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);
+}
+
+.field-value-large {
+  font-size: 1.25rem;
+  font-weight: 500;
+}
+```
+
+### Design System Style Props (use if your DS provides them)
+
+If the chosen design system provides built-in spacing, typography, or layout props, 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 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
+
+---
+
+## Design System Adaptation
+
+DSE components fall into three patterns with different DS dependencies:
+
+| Pattern | Examples | DS needed? |
+|---|---|---|
+| **B — Pure display** (no PConnect) | AlertBanner, Banner, Operator, WssQuickCreate | Yes — DS provides alert/card/avatar primitives |
+| **A — PConnect display** | CaseSummaryFields, DetailsFields, FieldValueList | Minimal — CSS-based layout; DS typography optional |
+| **C — Complex display** (PConnect bridge) | FieldGroup, FieldGroupList, Pulse | No — PConnect bridge is DS-agnostic; semantic HTML |
+
+The component-specific skill file specifies which pattern applies.
+
+**1. Check the component-specific skill file** — `.cursor/rules/skills/design-system-extension-skills/<ComponentName>.mdrules` contains a **Design System Mapping** table where available.
+
+**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>
+```
+
+**4. Variant mapping** — always map Pega's variant names to your DS equivalent before passing to DS components:
+
+| Pega variant | Meaning | Typical DS equivalent |
+|---|---|---|
+| `urgent` | Critical / error | `error`, `danger`, `critical` |
+| `warning` | Warning | `warning` |
+| `info` | Informational | `info` |
+| `success` | Success | `success` |
+
+---
+
+## Registration
+
+Register DSE components in `src/components/component-map.ts`:
+
+```typescript
+import AlertBanner from './designSystemExtension/AlertBanner';
+import FieldValueList from './designSystemExtension/FieldValueList';
+
+// In getSampleComponentMap():
+{
+  ...sdkComponents,
+  AlertBanner,
+  FieldValueList,
+}
+```
+
+---
+
+## Existing DSE Components
+
+| Component         | PConnect? | Description                             |
+| ----------------- | --------- | --------------------------------------- |
+| AlertBanner       | No        | Alert/notification banner with variants |
+| Banner            | No        | Promotional/informational banner        |
+| CaseSummaryFields | Yes       | Summary fields for case header          |
+| DetailsFields     | Yes       | Key-value fields in a details region    |
+| FieldGroup        | Yes       | Grouped fields with label/legend        |
+| FieldGroupList    | Yes       | List of field groups (repeating)        |
+| FieldValueList    | Yes       | Single field-value pair display         |
+| Operator          | No        | Operator avatar + name display          |
+| Pulse             | Yes       | Activity feed/comments stream           |
+| RichTextEditor    | Yes       | Rich text editor (TinyMCE-based)        |
+| WssQuickCreate    | No        | WSS quick case creation component       |
+
+---
+
+## 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).
+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.
+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.
+8. **Accessible markup** — Use semantic HTML (fieldset/legend for groups, proper heading levels, ARIA labels).

package/templates/react-sdk-reference/.cursor/rules/skills/field-components.mdrules

@@ -0,0 +1,299 @@
+---
+description: field-components
+alwaysApply: false
+---
+
+# Skill: Field Components
+
+Create or replace field components (form inputs) in the react-sdk-reference application. Field components render individual form controls that bind to Pega case properties.
+
+---
+
+## Architecture Overview
+
+```
+src/components/field/<ComponentName>/
+├── <ComponentName>.tsx      # Component implementation
+├── index.tsx                # Re-export: export { default } from './<ComponentName>'
+└── config-ext.json          # Metadata (name, label, description, type, subtype)
+```
+
+Components are registered in `src/components/component-map.ts` and resolved at runtime via `getComponentFromRegistry` from `@pega/sdk-react`.
+
+---
+
+## Props Interface
+
+All field components extend `PConnFieldProps` from `src/types/PConnProps.d.ts`:
+
+```typescript
+import type { PConnFieldProps } from '../../../types/PConnProps';
+
+interface PConnFieldProps extends PConnProps {
+  label: string; // Field label text
+  required: boolean; // Whether the field is required
+  disabled: boolean; // Whether the field is disabled
+  value?: string; // Current field value from the store
+  validatemessage: string; // Validation error message
+  status?: string; // 'error' | 'warning' | undefined
+  onChange: any; // Change handler (wired by platform)
+  onBlur?: any; // Blur handler (wired by platform)
+  readOnly: boolean; // Whether the field is read-only
+  testId: string; // Test identifier for automation
+  helperText: string; // Helper/hint text below the field
+  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL' | undefined
+  hideLabel: boolean; // Whether to hide the label
+  placeholder?: string; // Placeholder text
+}
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect; // Returns the PConnect API object
+}
+```
+
+Extend `PConnFieldProps` for component-specific additional props:
+
+```typescript
+interface MyFieldProps extends PConnFieldProps {
+  fieldMetadata?: any;
+  maxLength?: number;
+}
+```
+
+---
+
+## Implementation Pattern
+
+### Abstract Field Component Template
+
+This template is design-system agnostic. It defines the **behavioral skeleton** every field component must follow. Replace the `// [DS RENDER]` section with your design system's input primitive — see the "Design System Adaptation" section below for guidance.
+
+```typescript
+import { useState, useEffect } from 'react';
+// Import your design system component here:
+// e.g. import { Input } from 'antd';
+// e.g. import { Input } from '@chakra-ui/react';
+
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface MyFieldProps extends PConnFieldProps {
+  // Add component-specific props here
+}
+
+export default function MyField(props: MyFieldProps) {
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  const {
+    getPConnect,
+    label,
+    required,
+    disabled,
+    value = '',
+    validatemessage,
+    status,
+    readOnly,
+    testId,
+    helperText,
+    displayMode,
+    hideLabel,
+    placeholder
+  } = props;
+
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 1. Track input value locally — do NOT commit on every keystroke
+  const [inputValue, setInputValue] = useState(value);
+
+  // 2. Sync local state when the store value changes
+  useEffect(() => {
+    setInputValue(value);
+  }, [value]);
+
+  // 3. Display modes — must short-circuit before any interactive rendering
+  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. Event handlers
+  function handleChange(newValue: string) {
+    setInputValue(newValue); // update local state only
+  }
+
+  function handleBlur() {
+    handleEvent(actions, 'changeNblur', propName, inputValue); // commit to Pega store
+  }
+
+  // 5. [DS RENDER] — replace with your design system's input primitive
+  // Refer to "Design System Adaptation" below for prop mapping guidance
+  return (
+    <YourDesignSystemInput
+      value={inputValue}
+      onChange={handleChange}
+      onBlur={!readOnly ? handleBlur : undefined}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      placeholder={placeholder}
+      label={label}
+      helperText={helperTextToDisplay}
+      isInvalid={status === 'error'}
+      data-test-id={testId}
+    />
+  );
+}
+```
+
+---
+
+## Design System Adaptation
+
+When filling in the `// [DS RENDER]` section with a specific design system:
+
+**1. Check the component-specific skill file** — `.cursor/rules/skills/field-skills/<ComponentName>.mdrules` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
+
+**2. If the chosen design system is not in the mapping table** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
+
+**3. Discover the API from installed packages** — before writing any render JSX, confirm all prop names from `.d.ts` files. Never rely on training-knowledge of a DS API:
+```bash
+find node_modules/<ds-package> -name "ComponentName.d.ts" | head -3
+grep -A 40 "interface.*Props" <path-to-file>
+```
+
+**4. Prop mapping conventions** — adapt these Pega/SDK props to whatever your DS component calls them:
+
+| Pega/SDK prop | Meaning | Typical DS equivalent |
+|---|---|---|
+| `status === 'error'` | Validation error state | `error`, `status="error"`, `invalid`, `isInvalid` |
+| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra` |
+| `readOnly` | Non-editable, still visible | `readOnly`, `isReadOnly`, `variant="borderless"` |
+| `testId` | Automation selector | `data-test-id` on the underlying `<input>` element |
+| `required` | Required field marker | `required`, `isRequired` |
+| `hideLabel` | Suppress label display | Pass empty string `''` as label |
+
+**5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., `<Form.Item>` in Ant Design, `<FormControl>` in Chakra UI), use it rather than composing them manually.
+
+---
+
+## Event Handling
+
+Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
+
+```typescript
+import handleEvent from '../../helpers/event-utils';
+
+// Get references
+const actions = pConn.getActionsApi();
+const propName = (pConn.getStateProps() as any).value;
+
+// Options:
+handleEvent(actions, 'change', propName, value); // Update store only
+handleEvent(actions, 'blur', propName, value); // Trigger validation only
+handleEvent(actions, 'changeNblur', propName, value); // Update + validate (most common)
+```
+
+**Pattern:** Track local state with `useState`, update on user input, then call `handleEvent` on blur to commit.
+
+---
+
+## Display Modes
+
+Every field component MUST handle these `displayMode` values:
+
+| Mode                  | Behavior                                                       |
+| --------------------- | -------------------------------------------------------------- |
+| `undefined` / `null`  | Render editable form control                                   |
+| `'DISPLAY_ONLY'`      | Render read-only via `FieldValueList` (inline layout)          |
+| `'STACKED_LARGE_VAL'` | Render read-only via `FieldValueList` with `variant='stacked'` |
+
+Use `getComponentFromRegistry('FieldValueList')` to get the display component.
+
+---
+
+## Resolving Other Components
+
+Use `getComponentFromRegistry` from `@pega/sdk-react` to resolve components by name:
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+
+const FieldValueList = getComponentFromRegistry('FieldValueList');
+const TextInput = getComponentFromRegistry('TextInput');
+```
+
+This is used when:
+
+- Rendering display modes (FieldValueList)
+- Delegating to another field component (e.g., Date delegates to TextInput for readOnly)
+
+---
+
+## Registration
+
+After creating a component, register it in `src/components/component-map.ts`:
+
+```typescript
+import MyField from './field/MyField';
+
+// In the getSampleComponentMap() return object:
+{
+  ...sdkComponents,
+  // ... other fields ...
+  MyField,      // Key must match the Pega component name exactly
+}
+```
+
+---
+
+## Existing Field Components
+
+| Component       | Pega Name       | Description                                    |
+| --------------- | --------------- | ---------------------------------------------- |
+| AutoComplete    | AutoComplete    | Typeahead search field                         |
+| CancelAlert     | CancelAlert     | Cancel confirmation dialog                     |
+| Checkbox        | Checkbox        | Single checkbox with label                     |
+| Currency        | Currency        | Currency input with formatting                 |
+| Date            | Date            | Date picker (uses @mui/x-date-pickers + dayjs) |
+| DateTime        | DateTime        | Date + time picker                             |
+| Decimal         | Decimal         | Decimal number input                           |
+| Dropdown        | Dropdown        | Select/dropdown with options from data page    |
+| Email           | Email           | Email input with icon                          |
+| Group           | Group           | Field group container                          |
+| Integer         | Integer         | Integer-only input                             |
+| Location        | Location        | Google Maps location picker                    |
+| Multiselect     | Multiselect     | Multi-select dropdown                          |
+| ObjectReference | ObjectReference | Reference to another object                    |
+| Percentage      | Percentage      | Percentage input                               |
+| Phone           | Phone           | Phone input (uses mui-tel-input)               |
+| RadioButtons    | RadioButtons    | Radio button group                             |
+| RichText        | RichText        | Rich text editor (TinyMCE)                     |
+| ScalarList      | ScalarList      | List of scalar values                          |
+| SelectableCard  | SelectableCard  | Card-style selection                           |
+| SemanticLink    | SemanticLink    | Clickable link to another case/object          |
+| TextArea        | TextArea        | Multi-line text input                          |
+| TextContent     | TextContent     | Static text display                            |
+| TextInput       | TextInput       | Single-line text input                         |
+| Time            | Time            | Time picker                                    |
+| URL             | URL             | URL input with validation                      |
+| UserReference   | UserReference   | User picker                                    |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component uses `export default function`.
+2. **index.tsx** — Re-exports: `export { default } from './ComponentName'`.
+3. **Local state** — Track input value locally, sync from `value` prop via `useEffect`.
+4. **Commit on blur** — Use `handleEvent(actions, 'changeNblur', propName, localValue)` on blur, not on every keystroke.
+5. **Error display** — Show `validatemessage` or `helperText` below the field; set `error={status === 'error'}`.
+6. **Read-only** — Set `readOnly` on input props or render a display-only component.
+7. **Test IDs** — Pass `data-test-id={testId}` to the underlying input element.
+8. **No PCore imports** — Access PCore globals directly (they're declared globally by `@pega/pcore-pconnect-typedefs`).