@pega/sdk 0.0.1 → 0.0.3

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

@@ -0,0 +1,115 @@
+---
+description: Field component skill: Phone
+alwaysApply: false
+---
+
+# Skill: Phone
+
+Telephone input field with country code selector, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a telephone number input with an integrated country code selector (flag + dial code). Stores the phone number in E.164 format (e.g., `+15551234567`). Uses a specialized phone input library for the country picker. Separate handling for read-only mode (keeps country picker but sets input as read-only).
+
+## Pega Metadata
+
+- **Pega Name:** `Phone`
+- **Type / Subtype:** `Field` / `Text-Phone`
+- **Registration key:** `Phone` (in `component-map.ts`)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop. `useEffect` watching `value` → `setInputValue(value)`.
+2. **Default country:** `'US'` — the country code selector defaults to United States.
+3. **On change (editable):** Update local `inputValue` state with the formatted phone string from the library callback.
+4. **On blur (editable):** Extract and normalize the phone number to E.164 format:
+   ```
+   const phoneValue = event?.target?.value
+   let phoneNumber = phoneValue.split(' ').slice(1).join()  // remove country code prefix
+   phoneNumber = phoneNumber ? `+${phoneValue.replace(/\D+/g, '')}` : ''
+   handleEvent(actions, 'changeNblur', propName, phoneNumber)
+   ```
+5. **Read-only:** Render the phone input with `readOnly: true` on the input element and `disableDropdown: true` (country picker dropdown disabled). Keep the country flag/code visible but non-interactive. `onBlur` and `onChange` are NOT committed — use the `onChange` prop from the component itself but disable dropdown.
+6. **testId:** Pass as attribute on the input element.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw phone string.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Render phone input with `readOnly: true` and `disableDropdown: true` on the country picker. The `onChange` prop is `onChange` from `PConnFieldProps` (passed through). Wrapped in a `<div>`.
+
+```
+<div>
+  <PhoneInput
+    readOnly: true on input
+    disableDropdown={true}
+    onChange={onChange}  // from props — not local handler
+    value={value}
+    defaultCountry='US'
+  />
+</div>
+```
+
+## Visual Specifications
+
+| Property | Editable | Read-only |
+|----------|----------|-----------|
+| Width | 100% | 100% |
+| Size | Small | Small |
+| Variant | Outlined | Outlined (same, with readOnly input) |
+| Country selector | Dropdown with flag + dial code | Flag + dial code shown, dropdown disabled |
+| Default country | US (`+1`) | US (`+1`) |
+| Error state | Red border + red helper text | — |
+| Helper text | Below input | Below input |
+
+**CSS-only notes:**
+For a CSS-only implementation, create a two-part input:
+```css
+.phone-input-wrapper { display: flex; border: 1px solid rgba(0,0,0,0.23); border-radius: 4px; overflow: hidden; }
+.phone-country-select { border: none; border-right: 1px solid rgba(0,0,0,0.23); padding: 0 8px; background: none; }
+.phone-number-input { flex: 1; border: none; padding: 8px 12px; font-size: 0.875rem; outline: none; }
+```
+
+## Edge Cases & Special Logic
+
+- **E.164 normalization on blur:** Strip all non-digit chars from the full value (including country code), then prepend `+`. If the result after stripping the country part is empty, store `''`.
+- **Read-only uses `onChange` from props** (not the local `handleChange`) — this is the platform-wired handler, not our local state updater. Do NOT call `handleEvent` in read-only mode.
+- `disableDropdown: true` in read-only — prevents country switching.
+- The library provides the formatted display value (e.g., `+1 (555) 123-4567`) in the callback; we normalize it to E.164 only on blur.
+
+## Dependencies
+
+- A phone input library with country code selector and E.164 formatting support (e.g., `mui-tel-input`).
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+**For CSS-only / non-library implementations:**
+- Use a `<select>` for country code + a text `<input>` for the number.
+- On blur, combine dial code + number and strip non-digits, then format as `+{digits}`.
+
+## Design System Mapping
+
+**UI control type:** Telephone input with integrated country code selector.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<select>` (country) + `<input type="tel">` |
+| MUI | `<MuiTelInput>` from `mui-tel-input` |
+| Ant Design | `<Input addonBefore={countrySelect}>` |
+| Chakra UI | `<InputGroup>` with `<InputLeftAddon>` for country |

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

@@ -0,0 +1,151 @@
+---
+description: Field component skill: RadioButtons
+alwaysApply: false
+---
+
+# Skill: RadioButtons
+
+Radio button group field with optional card-style variant and localized option labels.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a group of radio buttons for single-selection from a list of options. Supports standard radio button layout (inline or stacked) and a card-style visual variant. Option labels are localized. Commits value immediately on selection.
+
+## Pega Metadata
+
+- **Pega Name:** `RadioButtons`
+- **Type / Subtype:** `Field` / `Picklist-Radio`
+- **Registration key:** `RadioButtons` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `inline` | `boolean` | If `true`, render radio buttons in a horizontal row; if `false`, vertical stack |
+| `fieldMetadata` | `any` (optional) | For localization context (tableType, datasource name, display text property) |
+| `variant` | `string` (optional) | `'card'` — renders options as selectable cards instead of radio buttons |
+| `hideFieldLabels` | `boolean` (optional) | Hide field labels inside card variant |
+| `additionalProps` | `any` (optional) | Extra props passed to `SelectableCard` in card variant |
+| `imagePosition` | `string` (optional) | Card image position: `'inline-start'`, `'inline-end'`, or block |
+| `imageSize` | `string` (optional) | Card image size |
+| `showImageDescription` | `boolean` (optional) | Whether to show image description in cards |
+| `datasource` | `any` (optional) | Datasource for card variant |
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `theSelectedButton` (string). Initialize from `value` prop. `useEffect` watching `value` → `setSelectedButton(value)`.
+2. **Options:** Load options from `Utils.getOptionList(theConfigProps, pConn.getDataObject(''))` — returns `Array<{key: string, value: string}>`.
+3. **On change:** Commit via `handleEvent(actionsApi, 'changeNblur', propName, event.target.value)`.
+4. **On blur:** Validate via `pConn.getValidationApi().validate(event.target.value, '')`. Second arg is empty string (optional parameter).
+5. **Inline layout:** Use `row={inline}` on the radio group — horizontal when `inline=true`.
+6. **Read-only:** Disable radio inputs (set `disabled` to `readOnly` value) — do NOT use a separate read-only component.
+7. **Localization:** Option labels are localized via `pConn.getLocalizedValue(option.value, localePath, localeRuleName)`.
+8. **Localization keys derivation:**
+   - Strip `@P ` prefix and leading `.` from `configProperty` (from `pConn.getRawMetadata()`).
+   - `localeContext`: `'datapage'` if `fieldMetadata.datasource.tableType === 'DataPage'`, else `'associated'`.
+   - `localeClass`: `'@baseclass'` for datapage, else `className`.
+   - `localeName`: datapage name or property name.
+   - `localePath`: display text property or localeName.
+
+### Variant: Standard (default)
+
+Render a radio group with `FormControl > FormLabel > RadioGroup > FormControlLabel (Radio)` pattern:
+- `FormLabel`: the `label` prop
+- `RadioGroup`: `value={theSelectedButton}`, `onChange={handleChange}`, `onBlur`, `row={inline}`
+- Each `FormControlLabel`: `value={option.key}`, `label={localizedLabel}`, `control={<Radio color='primary' disabled={readOnly} />}`
+- Wrap in `FormHelperText` for `helperTextToDisplay`
+- `error={status === 'error'}` on `FormControl`
+
+### Variant: Card (`variant === 'card'`)
+
+Render a heading (`<h4>`) with the `label`, then delegate to `SelectableCard` component:
+```
+<div>
+  <h4 style={{ marginTop: 0, marginBottom: 0 }}>{label}</h4>
+  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(min(200px, 100%), 1fr))', gap: '1rem' }}>
+    <SelectableCard
+      type='radio'
+      dataSource={datasource}
+      recordKey={stateProps.value?.split('.').pop()}
+      cardLabel={stateProps.primaryField?.split('.').pop()}
+      radioBtnValue={value}
+      onChange={handleChange}
+      image={{ imagePosition, imageSize, showImageDescription, imageField, imageDescription }}
+      setIsRadioCardSelected={displayMode !== 'DISPLAY_ONLY' ? setSelectedButton : undefined}
+      hideFieldLabels={hideFieldLabels}
+      additionalProps={additionalProps}
+      getPConnect={getPConnect}
+    />
+  </div>
+</div>
+```
+- `imageField`: `stateProps.image?.split('.').pop()`
+- `imageDescription`: `stateProps.imageDescription?.split('.').pop()`
+
+## Display Mode Rendering
+
+Both modes render the localized display label of the selected option:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedValue} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={localizedValue} variant='stacked' />`
+
+Where `localizedValue = pConn.getLocalizedValue(value, localePath, localeRuleName)`.
+
+## Visual Specifications
+
+### Standard Variant
+
+| Property | Value |
+|----------|-------|
+| Layout | Vertical stack (or horizontal row when `inline=true`) |
+| Radio indicator | Circle button with filled inner circle when selected |
+| Label | Label text to the right of the radio button (`labelPlacement='end'`) |
+| Group label | `<legend>` / `<FormLabel>` above the group |
+| Error state | Group border or text in red |
+| Helper text | Below the group |
+| Disabled (readOnly) | Greyed-out radio buttons, not-allowed cursor |
+
+**CSS-only notes:**
+```css
+.radio-group { display: flex; flex-direction: column; gap: 4px; }
+.radio-group.inline { flex-direction: row; flex-wrap: wrap; gap: 8px; }
+.radio-label { display: flex; align-items: center; gap: 8px; cursor: pointer; }
+input[type="radio"]:disabled { opacity: 0.38; cursor: default; }
+```
+
+### Card Variant
+
+| Property | Value |
+|----------|-------|
+| Layout | CSS Grid: `repeat(auto-fit, minmax(min(200px, 100%), 1fr))`, gap `1rem` |
+| Card | Elevated card with click handler that activates the radio |
+| Heading | `<h4>` with `marginTop: 0, marginBottom: 0` above grid |
+
+## Edge Cases & Special Logic
+
+- `theOptions` is loaded synchronously from `Utils.getOptionList()` on every render — no async fetching.
+- `theSelectedButton` tracks the selected key locally and syncs from `value` prop via `useEffect`.
+- Card variant uses `setIsRadioCardSelected` callback to inform parent when a radio card is selected.
+
+## Dependencies
+
+- `Utils.getOptionList()` from `../../helpers/utils`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `getComponentFromRegistry('SelectableCard')` for card variant.
+
+## Design System Mapping
+
+**UI control type:** Radio button group (single selection).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="radio">` with `<label>` per option |
+| MUI | `<RadioGroup>` with `<FormControlLabel control={<Radio />}>` |
+| Ant Design | `<Radio.Group>` with `<Radio>` options |
+| Chakra UI | `<RadioGroup>` with `<Radio>` items |

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

@@ -0,0 +1,143 @@
+---
+description: Field component skill: RichText
+alwaysApply: false
+---
+
+# Skill: RichText
+
+Rich text editor field with HTML content support, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a rich text (WYSIWYG) editor for HTML content. Uses a registry-resolved `RichTextEditor` component. Handles both read-only and editable states. Commits HTML content on blur by reading from the editor's internal ref.
+
+## Pega Metadata
+
+- **Pega Name:** `RichText`
+- **Type / Subtype:** `Field` / `Text-RichText`
+- **Registration key:** `RichText` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `additionalProps` | `object` (optional) | Extra props forwarded to the `RichTextEditor` |
+
+## Behavioral Contract
+
+1. **Editor ref:** Maintain an `editorRef` (via `useRef`) — the editor exposes its content via `editorRef.current.getContent({ format: 'html' })`.
+2. **No local state** — unlike text inputs, value is NOT tracked in local state. The editor manages its own internal content via `defaultValue`.
+3. **Props coercion:** `readOnly`, `required`, `disabled` must be coerced to booleans:
+   ```typescript
+   [readOnly, required, disabled] = [readOnly, required, disabled].map(
+     prop => prop === true || (typeof prop === 'string' && prop === 'true')
+   )
+   ```
+4. **Editable mode:**
+   - Track `status` for error state.
+   - **On change:** If `status === 'error'`, clear error messages via:
+     ```
+     pConn.clearErrorMessages({ property, category: '', context: '' })
+     ```
+   - **On blur:** Read HTML from editor ref and commit:
+     ```
+     const editorValue = editorRef.current.getContent({ format: 'html' })
+     handleEvent(actionsApi, 'changeNblur', property, editorValue)
+     ```
+5. **Read-only mode:** Render `RichTextEditor` with `readOnly` prop only — no `onChange`/`onBlur`.
+6. **`RichTextEditor` component:** Resolved via `getComponentFromRegistry('RichTextEditor')`. This is a design-system extension component that wraps the actual WYSIWYG library (e.g., TinyMCE).
+
+### Editable RichTextEditor props
+```
+label, labelHidden={hideLabel}, info={helperTextToDisplay}, defaultValue={value},
+placeholder, disabled, required, testId, ref={editorRef},
+error={status === 'error'}, onBlur={handleBlur}, onChange={handleChange}
+```
+
+### Read-only RichTextEditor props
+```
+label, labelHidden={hideLabel}, defaultValue={value}, testId, info={helperTextToDisplay},
+ref={editorRef}, readOnly
+```
+
+## Display Mode Rendering
+
+Display modes pass `isHtml={true}` to render HTML content safely:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml variant='stacked' />`
+
+## Read-Only Rendering
+
+Render `RichTextEditor` with `readOnly` prop. Uses same `editorRef`.
+
+## Visual Specifications
+
+The visual appearance of the rich text editor depends on the underlying `RichTextEditor` implementation. The reference implementation uses TinyMCE theming via CSS variables:
+
+```css
+/* RichText.css — must be imported */
+.tox .tox-toolbar { background-color: var(--app-background-color) !important; }
+.tox .tox-toolbar__primary { background-color: var(--app-background-color) !important; }
+.tox .tox-toolbar__button { color: var(--app-text-color) !important; }
+.tox .tox-toolbar__button--enabled {
+  background: var(--app-primary-color) !important;
+  color: #fff !important;
+}
+.tox .tox-dialog {
+  background-color: var(--modal-top-color) !important;
+  color: var(--app-text-color) !important;
+  border: 1px solid var(--modal-border-color) !important;
+  padding: 20px !important;
+  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color) !important;
+}
+.tox .tox-dialog__header {
+  background-color: var(--modal-top-color) !important;
+  color: var(--app-text-color) !important;
+  font-weight: 500;
+  border-bottom: 1px solid var(--modal-border-color);
+}
+```
+
+**Note:** Import `./RichText.css` in the component file. The CSS variables (`--app-background-color`, `--app-text-color`, etc.) are set by the application theme.
+
+When implementing with a different design system:
+- Custom CSS for toolbar theming may be needed
+- The editor container should be full-width
+- Minimum height: ~200px for a usable editing area
+
+## Edge Cases & Special Logic
+
+- **Props coercion to boolean:** Pega may pass these props as strings (`'true'`/`'false'`) — always coerce.
+- **On blur, NOT on change:** Content is committed to the store only on blur (when user leaves the editor), not on every keystroke.
+- **Error clearing:** When `status === 'error'`, the `onChange` handler clears the error message from Pega so it doesn't persist after the user starts editing.
+- **`editorRef.current.getContent`:** This is specific to the TinyMCE API. For other rich text libraries, use the equivalent method to get HTML content.
+- **`FieldValueList` with `isHtml`:** The display mode renders HTML — ensure XSS protection in the `FieldValueList` component (use `dangerouslySetInnerHTML` only with sanitization, or a trusted HTML renderer).
+
+## Dependencies
+
+- `getComponentFromRegistry('RichTextEditor')` — the actual editor widget (e.g., TinyMCE wrapper).
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `handleEvent` from `../../helpers/event-utils`.
+- `./RichText.css` — must be imported for TinyMCE toolbar theming.
+- `useRef` from React.
+
+**For other rich text editors:**
+- Any WYSIWYG editor that exposes `ref.current.getContent()` or equivalent.
+- Examples: Quill, Draft.js, Slate.js, CKEditor.
+
+## Design System Mapping
+
+**UI control type:** WYSIWYG rich text editor (HTML content).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `contenteditable` div + custom toolbar OR TinyMCE |
+| MUI | `RichTextEditor` custom extension (TinyMCE) |
+| Ant Design | Quill or TinyMCE with Ant styling |
+| Chakra UI | Quill or TipTap with Chakra styling |

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

@@ -0,0 +1,129 @@
+---
+description: Field component skill: ScalarList
+alwaysApply: false
+---
+
+# Skill: ScalarList
+
+Read-only display component that renders a list of scalar values by creating a child component for each item.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a list of scalar (primitive) values by dynamically creating a child component of a specified type for each item. Used for read-only display of list-type properties. Not an editable input.
+
+## Pega Metadata
+
+- **Pega Name:** `ScalarList`
+- **Type / Subtype:** `Field` / `ScalarList`
+- **Registration key:** `ScalarList` (in `component-map.ts`)
+
+## Props (component-specific)
+
+> ScalarList uses `PConnProps` (NOT `PConnFieldProps`) because its `value` is an array, not a string:
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `any[]` | Array of scalar values to display |
+| `componentType` | `string` | The Pega component type to use for each item (e.g., `'TextInput'`, `'Date'`) |
+| `label` | `string` | Field label |
+| `displayMode` | `string` | Display mode |
+| `hideLabel` | `boolean` | Whether to hide the label |
+| `displayInModal` | `boolean` | Whether this is displayed in a modal context |
+
+All remaining props (`...restProps`) are forwarded to each child component.
+
+## Behavioral Contract
+
+1. **No state, no event handling** — purely display/read-only.
+2. **Item rendering:** Map each value in `scalarValues` to a component via `getPConnect().createComponent(...)`:
+   ```typescript
+   const items = scalarValues?.map(scalarValue =>
+     getPConnect().createComponent(
+       {
+         type: componentType,
+         config: {
+           value: scalarValue,
+           displayMode: 'DISPLAY_ONLY',
+           label,
+           ...restProps,
+           readOnly: 'true'
+         }
+       },
+       '',   // 2nd arg: empty string
+       '',   // 3rd arg: empty string
+       {}    // 4th arg: empty object
+     )
+   )
+   ```
+3. **`CommaSeparatedList` sub-component:** A local component that renders items as `<span>` elements inside a `<ul>` with no list styling:
+   ```html
+   <ul style="padding: 0; margin: 0;">
+     <span>item1</span>
+     <span>item2</span>
+     ...
+   </ul>
+   ```
+
+## Display Mode Rendering
+
+**`STACKED_LARGE_VAL` or `DISPLAY_ONLY`:**
+```html
+<div>
+  <CommaSeparatedList items={items} />
+</div>
+```
+No `FieldValueList` wrapper in these modes — the items are rendered directly.
+
+**Default (no display mode):**
+```
+<FieldValueList name={hideLabel ? '' : label} value={<CommaSeparatedList items={items} />} variant='stacked' />
+```
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| List style | No bullets, no padding, no margin on `<ul>` |
+| Item display | Each item rendered as `<span>` (inline) |
+| Separator | Items are adjacent spans (no comma separator despite the name) |
+| Layout | Vertical stack when wrapped in `FieldValueList variant='stacked'` |
+
+**CSS-only notes:**
+```css
+.scalar-list { list-style: none; padding: 0; margin: 0; }
+.scalar-list-item { display: inline; }
+```
+
+## Edge Cases & Special Logic
+
+- `scalarValues` may be `undefined` — the `?.map()` safely returns `undefined`; ensure null-check before rendering.
+- Each child component is created with `displayMode: 'DISPLAY_ONLY'` and `readOnly: 'true'` (as string) — the read-only is passed as a string, not boolean.
+- `restProps` includes all remaining props from the parent beyond the destructured ones — these are forwarded to each child component config.
+- `createComponent` takes 4 args — 2nd, 3rd, 4th are empty string/object as the typedef marks them optional.
+
+## Dependencies
+
+- `getComponentFromRegistry('FieldValueList')` for default display.
+- `getPConnect().createComponent()` — for creating each child component.
+- No `handleEvent` — read-only component.
+
+## Design System Mapping
+
+**UI control type:** Read-only list of scalar values.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<ul>` with `<span>` items |
+| MUI | `<List>` with `<ListItem>` or just `<Typography>` per item |
+| Ant Design | `<List>` items or `<Space>` with `<Tag>` |
+| Chakra UI | `<List>` or `<HStack>` with `<Tag>` |