@pega/sdk 0.0.3 → 0.0.5

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

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

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

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

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

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