@pega/sdk 0.0.4 → 0.0.5

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

@@ -1,294 +0,0 @@
----
-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

@@ -1,299 +0,0 @@
----
-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`).