@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.claude/skills/field-skills/Multiselect.md

@@ -0,0 +1,164 @@
+# Skill: Multiselect
+
+Multi-select autocomplete field supporting flat lists, grouped/hierarchical data, reference list binding, and debounced search.
+
+> **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 multi-value typeahead input where users can search and select multiple items. Supports flat datasources, grouped/hierarchical data, reference lists (embedded page lists), and debounced async search. Manages selection state and commits changes via reference list instructions.
+
+## Pega Metadata
+
+- **Pega Name:** `Multiselect`
+- **Type / Subtype:** `Field` / `Picklist-Multi`
+- **Registration key:** `Multiselect` (in `component-map.ts`)
+
+> **Note:** `Multiselect` does NOT extend `PConnFieldProps` — it uses raw `props` (no typed interface in the reference implementation). Define props as needed for your implementation.
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `getPConnect` | `function` | — | PConnect accessor |
+| `label` | `string` | — | Field label |
+| `placeholder` | `string` | — | Input placeholder |
+| `referenceList` | `any[]` | — | Currently selected items from embedded page list |
+| `selectionKey` | `string` | — | Property path used as the selection key |
+| `primaryField` | `string` | — | Property path for the primary display field |
+| `initialCaseClass` | `string` | — | Case class for context in search |
+| `selectionList` | `string` | — | Property path of the reference list |
+| `datasource` | `any[]` | `[]` | Flat data source |
+| `columns` | `any[]` | `[{}]` | Column config for key/value extraction |
+| `listType` | `string` | `''` | `'associated'`, `'datapage'`, `'promptList'`, `'localList'` |
+| `isGroupData` | `boolean` | `false` | Whether to use grouped/hierarchical data |
+| `groupDataSource` | `any[]` | `[]` | Data source for grouped display |
+| `groupColumnsConfig` | `any[]` | `[{}]` | Column config for group display |
+| `referenceType` | `string` | — | `'Case'` or `'Data'` |
+| `secondaryFields` | `any` | — | Additional secondary display fields |
+| `showSecondaryInSearchOnly` | `boolean` | `false` | Show secondary fields only during search |
+| `parameters` | `object` | `{}` | Data page query parameters |
+| `matchPosition` | `string` | `'contains'` | Search match position (`'contains'`, `'startsWith'`) |
+| `maxResultsDisplay` | `string` | — | Max results to display (`'100'` default) |
+| `value` | `any` | — | Current value |
+
+## Behavioral Contract
+
+### Reference List Mode (when `referenceList.length > 0`)
+
+When `referenceList` has items, override datasource and columns:
+- `datasource = referenceList`
+- Build `columns`: primary display field, key field, secondary columns (from `secondaryFields` or default to `selectionKey`)
+- If `referenceType === 'Case'`: append secondary columns
+
+### Data Config
+
+Build a `dataConfig` object (memoized with deep comparison) containing:
+- `dataSource`, `groupDataSource`, `isGroupData`, `showSecondaryInSearchOnly`, `parameters`, `matchPosition`, `listType`, `maxResultsDisplay`
+- `columns`: preprocessed (strip leading `.` from value fields)
+- `groupColumnsConfig`: preprocessed
+
+### Items Tree
+
+- `displayFieldMeta`: derived from `columns` when `listType !== 'associated'`
+- `groupsDisplayFieldMeta`: derived from `groupColumnsConfig` when `listType !== 'associated'`
+- `itemsTree` state: for `isGroupData` mode, initialized from `getGroupDataForItemsTree(groupDataSource, groupsDisplayFieldMeta, showSecondaryInSearchOnly)`; otherwise `[]`
+
+### Data API Initialization
+
+In `useEffect` watching `dataConfig` (non-associated lists):
+```
+PCore.getDataApi().init(dataConfig, contextName).then(dataObj => {
+  dataApiObj.current = dataObj
+  if (!isGroupData) {
+    getCaseListBasedOnParamsDebounced.current(inputValue ?? '', '', [...selectedItems], [...itemsTree])
+  }
+})
+```
+
+### Search
+
+`getCaseListBasedOnParams(searchText, group, selectedRows, currentItemsTree, isTriggeredFromSearch)`:
+1. If `referenceList.length > 0`: get currently selected rows from `listActions.getSelectedRows(true)`, map to `{id, primary}` format, update `selectedItems` state.
+2. Build `initalItemsTree`: use fresh data if `isTriggeredFromSearch || !currentItemsTree`, else current.
+3. Call `doSearch(...)` to get filtered results.
+4. `setItemsTree(results)`.
+
+**Debounce:** 500ms debounce on `getCaseListBasedOnParams` via `getCaseListBasedOnParamsDebounced` ref.
+
+### Mount Effects
+
+- `useEffect([pConn])`: if `referenceList.length > 0`, call `pConn.setReferenceList(selectionList)`.
+- `useEffect([])`: set up debounced search ref.
+
+### Selection Changes (`handleChange`)
+
+When selection changes (user adds/removes item):
+1. Mark all currently selected items as `selected: true`.
+2. Determine if this was an add or remove.
+3. Update `itemsTree` selections in-place.
+4. `setSelectedItems(updatedItems)`, `setItemsTree(itemsTree)`.
+5. Reset `inputValue` to `''`.
+6. If `referenceList`: call `setSelectedItemsForReferenceList(clickedItem[0])`.
+
+`setSelectedItemsForReferenceList`: calls `insertInstruction` (if `selected: true`) or `deleteInstruction` (if `selected: false`) and clears error messages.
+
+### Search Input
+
+`onSearchHandler`: updates `inputValue` state and calls debounced search with `isTriggeredFromSearch=true`.
+
+## Display Mode Rendering
+
+No explicit `displayMode` handling in the reference implementation — Multiselect is rendered directly by parent components when display mode is needed. If `displayMode` support is needed, implement similar to Dropdown.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant | Outlined |
+| Multiple values | Tags/chips shown inside the input box |
+| Dropdown | Shows filtered options with checkboxes |
+| Close on select | Off (`disableCloseOnSelect`) — user can select multiple before closing |
+| Option label | `option.primary` field |
+| Placeholder | From `placeholder` prop |
+| Error state | Red border + red helper text |
+
+**CSS-only notes:**
+```css
+.multiselect-tags { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px; border: 1px solid rgba(0,0,0,0.23); border-radius: 4px; }
+.multiselect-tag { background: rgba(0,0,0,0.08); border-radius: 16px; padding: 2px 8px; font-size: 0.8125rem; display: flex; align-items: center; gap: 4px; }
+.multiselect-tag-delete { cursor: pointer; font-size: 0.75rem; }
+```
+
+## Edge Cases & Special Logic
+
+- **`dataConfig` deep memoization:** Use custom deep-equal hook (`useDeepMemo`) to avoid re-initializing data API on every render.
+- `itemsTreeBaseData` is fixed at render time — used as the base for each fresh search.
+- When `isGroupData=false`: debounced search fires after data API init.
+- When `isGroupData=true`: groups are pre-populated from `groupDataSource`.
+- The `selected` flag on items in `itemsTree` tracks selection state in the dropdown.
+
+## Dependencies
+
+- `doSearch`, `getDisplayFieldsMetaData`, `useDeepMemo`, `preProcessColumns`, `getGroupDataForItemsTree` from `./utils` (local utils file).
+- `insertInstruction`, `deleteInstruction` from `../../helpers/instructions-utils`.
+- `debounce` from `throttle-debounce` library (or any debounce utility).
+- `PCore.getDataApi()` — for data initialization.
+- Multi-select autocomplete UI widget.
+
+## Design System Mapping
+
+**UI control type:** Multi-select combobox with tags/chips and searchable dropdown.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | Custom tag input + filterable dropdown list |
+| MUI | `<Autocomplete multiple disableCloseOnSelect>` |
+| Ant Design | `<Select mode="multiple" showSearch>` |
+| Chakra UI | Third-party multi-select (e.g., Chakra React Select) |

package/templates/react-sdk-reference/.claude/skills/field-skills/ObjectReference.md

@@ -0,0 +1,164 @@
+# Skill: ObjectReference
+
+Composite field that dynamically renders a child component (Dropdown, AutoComplete, or SemanticLink) for referencing another Pega case or data object. Supports editable-in-review mode with direct case update.
+
+> **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
+
+Does NOT render a UI control directly. Instead, it reads the raw metadata to determine which child component type to render (`Dropdown`, `AutoComplete`, or `SemanticLink`), constructs that child component via `getPConnect().createComponent(...)`, and renders it inside a grid container. Also handles editable-in-review mode where the user can change a reference field while viewing a case.
+
+## Pega Metadata
+
+- **Pega Name:** `ObjectReference`
+- **Type / Subtype:** `Field` / `Reference`
+- **Registration key:** `ObjectReference` (in `component-map.ts`)
+
+## Props (component-specific)
+
+> Uses `Omit<PConnFieldProps, 'value'>` — no direct `value` prop.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `getPConnect` | `any` | — | PConnect accessor |
+| `displayMode` | `any` | — | Display mode |
+| `allowAndPersistChangesInReviewMode` | `any` | `false` | Whether the reference can be edited while in review/display mode |
+| `targetObjectType` | `any` | — | `'case'` or `'data'` — determines `referenceType` |
+| `mode` | `string` | `''` | `'single'` or `'multi'` (SELECTION_MODE) |
+| `parameters` | `object` | — | Data page query parameters |
+| `hideLabel` | `boolean` | `false` | Whether to hide label |
+| `inline` | `boolean` | `false` | Whether to render inline |
+| `showPromotedFilters` | `boolean` | `false` | Show promoted filters in child |
+| `additionalFields` | `any` | — | Additional fields for read-only display |
+
+## Behavioral Contract
+
+### Setup
+
+1. `referenceType = targetObjectType === 'case' ? 'Case' : 'Data'`
+2. `rawViewMetadata = pConn.getRawMetadata()` — the raw component metadata from Pega config
+3. `refFieldMetadata = pConn.getFieldMetadata(rawViewMetadata?.config?.value?.split('.', 2)[1])`
+4. `propsToUse = { ...pConn.getInheritedProps(), ...props }` — merged inherited + local props
+5. `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`
+6. `canBeChangedInReviewMode = editableInReview && ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType)`
+
+### Subsection: Read-only variants (display mode, non-editable)
+
+**If `componentType === 'SemanticLink'` and `!canBeChangedInReviewMode`:**
+Build a SemanticLink config from rawViewMetadata and call `getPConnect().createComponent({ type: 'SemanticLink', config: {...} })`. Config includes:
+- `displayField` → `primaryField` and `text`
+- `value` → `caseID`
+- `resourceParams: { workID: value }`, `resourcePayload: { caseClassName: caseClass }`
+- `displayMode`, `referenceType`, `hideLabel`, `dataRelationshipContext`
+
+**If `isDisplayModeEnabled && !canBeChangedInReviewMode` (other types):**
+Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, passing:
+- `label`, `type`, `displayAs='readonly'`, `displayMode`, `referenceType`, `hideLabel`, `dataRelationshipContext`, `additionalFields`
+
+### Subsection: Editable variants (including editable-in-review)
+
+**If NOT in a read-only case:**
+
+1. **Set datasource:** Call `generateColumns(rawViewMetadata.config, pConn, referenceType)` to populate column config.
+   - Set `rawViewMetadata.config.deferDatasource = true`
+   - Set `rawViewMetadata.config.listType = 'datapage'`
+   - Set default placeholder `'@L Select...'` for Dropdown/AutoComplete if missing
+
+2. **Pass-through configs:**
+   - `rawViewMetadata.config.showPromotedFilters = showPromotedFilters`
+   - If `!canBeChangedInReviewMode`: set `rawViewMetadata.config.displayMode = displayMode`
+
+3. **Build fieldMetaData:**
+   ```
+   fieldMetaData = { datasourceMetadata: { datasource: { parameters: {} } } }
+   ```
+   - Set `propertyForDisplayText` from `datasource.fields.text` (strip `@P ` prefix)
+   - Set `propertyForValue` from `datasource.fields.value` (strip `@P ` prefix)
+   - Set `name` from `referenceList`
+   - If `rawViewMetadata.config.parameters`: assign `parameters` prop
+
+4. **Create child component:**
+   ```
+   getPConnect().createComponent({
+     type,  // 'Dropdown' or 'AutoComplete'
+     config: {
+       ...rawViewMetadata.config,
+       descriptors: mode === SELECTION_MODE.SINGLE ? refFieldMetadata?.descriptors : null,
+       datasourceMetadata: fieldMetaData.datasourceMetadata,
+       required, visibility, disabled, label, parameters, readOnly: false,
+       localeReference, referenceType (for single mode only),
+       contextClass: targetObjectClass,
+       primaryField: displayField,
+       dataRelationshipContext,
+       hideLabel, onRecordChange, inline
+     }
+   })
+   ```
+
+### `onRecordChange` handler
+
+Called when user selects a new value in editable/editable-in-review mode:
+1. Build `refreshOptions = { autoDetectRefresh: true, propertyName: rawViewMetadata.config?.value }`
+2. If `!canBeChangedInReviewMode || !pConn.getValue('__currentPageTabViewName')`: call `getPConnect().getActionsApi().refreshCaseView(caseKey, viewName, pgRef, refreshOptions)`.
+3. Extract `propValue = event?.id || event?.target?.value`.
+4. For multi mode (`SimpleTableSelect`): `propName = getPropertyName(rawViewMetadata.config.selectionList)`, else `propName = getPropertyName(rawViewMetadata.config.value)`.
+5. If `propValue && canBeChangedInReviewMode && isDisplayModeEnabled`:
+   - Get edit lock via `PCore.getCaseUtils().getCaseEditLock(caseKey, '')`
+   - Build commit data from page reference path
+   - Call `PCore.getCaseUtils().updateCaseEditFieldsData(...)` to persist the change
+   - Update container's last update time and etag
+
+### Memoization
+
+`recreatedFirstChild` is memoized with `useMemo` — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+
+## Display Mode Rendering
+
+Display mode is passed through to the child component — the child (Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly) handles its own display mode rendering.
+
+## Visual Specifications
+
+ObjectReference itself renders a minimal grid container:
+```
+<Grid container>
+  <Grid>{recreatedFirstChild}</Grid>
+</Grid>
+```
+
+The visual appearance is entirely determined by the child component being rendered. No additional styling is applied by `ObjectReference` itself.
+
+**CSS-only implementation:**
+```css
+.object-reference-container { display: grid; width: 100%; }
+```
+
+## Edge Cases & Special Logic
+
+- **`generateColumns`**: a utility from `./utils` that populates `rawViewMetadata.config` with proper column definitions for the child Dropdown/AutoComplete.
+- **`getDataRelationshipContextFromKey`**: extracts the relationship context from a field key (also from `./utils`).
+- `rawViewMetadata.config` is mutated in place before being passed to `createComponent` — this is intentional but means the component re-creates the child on relevant prop changes.
+- For `SemanticLink` type, the child is created via `createComponent`, not rendered as a direct React element.
+- `SELECTION_MODE.SINGLE` and `SELECTION_MODE.MULTI` constants from `./utils`.
+
+## Dependencies
+
+- `SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey` from `./utils` (local).
+- `getComponentFromRegistry('SingleReferenceReadOnly')` — for display-only non-SemanticLink.
+- `PCore.getCaseUtils()`, `PCore.getAnnotationUtils()`, `PCore.getContainerUtils()` — for editable-in-review updates.
+- `useMemo` from React.
+- No `handleEvent` — selection handling is done by the child component via `onRecordChange`.
+
+## Design System Mapping
+
+**UI control type:** Composite wrapper — renders Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly. No dedicated UI control.
+
+Listed design systems are examples only.
+
+| Scenario | Rendered Child |
+|----------|----------------|
+| `componentType='Dropdown'` (editable) | `Dropdown` component |
+| `componentType='AutoComplete'` (editable) | `AutoComplete` component |
+| `componentType='SemanticLink'` | `SemanticLink` component |
+| `displayMode='DISPLAY_ONLY'` (non-editable-in-review) | `SingleReferenceReadonly` component |

package/templates/react-sdk-reference/.claude/skills/field-skills/Percentage.md

@@ -0,0 +1,92 @@
+# Skill: Percentage
+
+Percentage numeric input with a `%` suffix and locale-aware decimal/thousands separators.
+
+> **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 numeric input for percentage values. Always appends a `%` suffix in the input. Supports configurable decimal precision and optional thousands separator. Shows a formatted percentage string in display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `Percentage`
+- **Type / Subtype:** `Field` / `Decimal-Percentage`
+- **Registration key:** `Percentage` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO code used for locale-aware decimal/thousands separator lookup only (not for currency symbol) |
+| `showGroupSeparators` | `string` (optional) | — | Whether to show thousands separators (passed as string, truthy check applies) |
+| `decimalPrecision` | `number` (optional) | — | Number of decimal places |
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Separators:** Derive `decimalSeparator` and `thousandSeparator` from locale lookup using `currencyISOCode` (same as Currency/Decimal). Apply `thousandSeparator` only when `showGroupSeparators` is truthy.
+4. **Suffix:** Always append `%` suffix to the numeric input.
+5. **Decimal scale:** Use `decimalPrecision` prop.
+6. **No prefix:** Unlike Currency, no prefix symbol.
+7. **On value change:** Update local `values` state with the raw numeric string.
+8. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, values)`.
+9. **Read-only:** Set `readOnly: true` on the input. Flat/borderless style. `onBlur` omitted.
+
+## Display Mode Rendering
+
+Format the value using the percentage formatter before display:
+- `formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), currencyOptions)`
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Keep numeric format input with `readOnly: true` and `%` suffix still visible. Flat/borderless style.
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | 100% |
+| Size | Small |
+| Variant editable | Outlined |
+| Variant read-only | Standard (flat) |
+| Suffix | `%` (always shown after the value) |
+| Thousands separator | Only when `showGroupSeparators` is truthy |
+| Decimal scale | `decimalPrecision` |
+| Placeholder | From `placeholder` prop |
+| Error state | Red border + red helper text |
+
+**CSS-only notes:** Achieve the `%` suffix by wrapping the input in a relative container and absolutely positioning a `%` label at the right side, or using an input with a `::after` pseudo-element technique.
+
+## Edge Cases & Special Logic
+
+- `showGroupSeparators` is typed as `string` (not `boolean`) in the reference implementation — apply truthy check.
+- `currencyISOCode` is only used for separator lookup (decimal/thousands), NOT for a currency symbol.
+- The stored value is always a raw numeric string (e.g., `'45.5'`), not `'45.5%'`.
+
+## Dependencies
+
+- Numeric formatting library (e.g., `react-number-format`'s `NumericFormat`).
+- `getCurrencyCharacters(currencyISOCode)` — for `theDecimalIndicator`, `theDigitGroupSeparator`.
+- `getCurrencyOptions(currencyISOCode)` — for `format()` call.
+- `format()` from `../../helpers/formatters`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Percentage numeric input with `%` suffix.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` + custom masking + `%` suffix span |
+| MUI | `NumericFormat` with `suffix='%'` and `customInput={TextField}` |
+| Ant Design | `<InputNumber suffix="%" precision={decimalPrecision} />` |
+| Chakra UI | `<NumberInput>` + `<InputRightAddon>%</InputRightAddon>` |

package/templates/react-sdk-reference/.claude/skills/field-skills/Phone.md

@@ -0,0 +1,110 @@
+# 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/.claude/skills/field-skills/RadioButtons.md

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