@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,132 +14,47 @@ Renders a telephone number input with an integrated country code selector (flag
 
 - **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';
-```
-
-## Component Skeleton
-
-Follow this exact structure. Replace `<PhoneInputWidget>` with equivalents from your chosen design system / phone library.
-
-```typescript
-import { useEffect, useState } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-import handleEvent from '../../helpers/event-utils';
-
-interface PhoneProps extends PConnFieldProps {}
-
-export default function Phone(props: PhoneProps) {
-  // 1. Registry lookup
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props — note: onChange is used in readOnly mode
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, onChange, readOnly, testId,
-    helperText, displayMode, hideLabel, placeholder,
-  } = props;
-
-  // 3. PConnect setup
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-
-  // 4. State + sync
-  const [inputValue, setInputValue] = useState(value);
-  useEffect(() => setInputValue(value), [value]);
-
-  // 5. Derived values
-  const helperTextToDisplay = validatemessage || helperText;
-  let testProp = { 'data-test-id': testId };
-
-  // 6. Display mode returns
-  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" />;
-  }
-
-  // 7. Read-only return — keeps phone widget but disables dropdown + sets input readOnly
-  //    Uses onChange from PROPS (not local handler), value from PROPS (not state)
-  if (readOnly) {
-    return (
-      <div>
-        <PhoneInputWidget
-          defaultCountry="US" value={value} onChange={onChange}
-          disableDropdown={true}
-          slotProps={{ input: { readOnly: true, ...testProp } }}
-          /* + label, helperText, required, disabled, error, size, placeholder */
-        />
-      </div>
-    );
-  }
-
-  // 8. Editable handlers
-  const handleChange = (inputVal) => { setInputValue(inputVal); };
-  const handleBlur = (event) => {
-    const phoneValue = event?.target?.value;
-    let phoneNumber = phoneValue.split(' ').slice(1).join();
-    phoneNumber = phoneNumber ? `+${phoneValue.replace(/\\D+/g, '')}` : '';
-    handleEvent(actions, 'changeNblur', propName, phoneNumber);
-  };
-
-  // 9. Main render — phone input with country selector
-  //    Key props:
-  //    - fullWidth, variant: 'outlined', size: 'small'
-  //    - defaultCountry: 'US'
-  //    - value: inputValue, onChange: handleChange
-  //    - onBlur: !readOnly ? handleBlur : undefined
-  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //    - required, disabled, error: status === 'error'
-  //    - slotProps: { input: { ...testProp } }
-  return <PhoneInputWidget ... />;
-}
-```
+- **Registration key:** `Phone` (in the project's component map)
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. Replace the phone-input widget with an equivalent from your chosen design system / phone library.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`) and the project's event-commit utility (for committing value changes to the store). It also uses a phone-input library that provides a country-code picker with flag display and dial-code formatting. Define the input contract as the project's field input contract with no additional fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `onChange` (note: this raw input is used directly in read-only mode), `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name.
+4. **Local state and sync** — `inputValue` initialized from `value`; a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+5. **Derived values** — `helperTextToDisplay = validatemessage || helperText` and a test-id attribute object built from `testId`.
+6. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+7. **Read-only return** — keeps the phone widget visible but disables the country dropdown and sets the input itself to read-only. Notably, this branch uses the raw `onChange` input (not a local handler) and the raw `value` input (not local state). Render the phone widget wrapped in a container element, configured with default country `US`, `value` set to the raw value, `onChange` set to the raw onChange input, country dropdown disabled, and the read-only/test-id attributes merged into the input element, alongside the usual label/helperText/required/disabled/error/size/placeholder configuration.
+8. **Editable handlers** — the change handler updates local `inputValue` state only. The blur handler extracts the raw phone value from the event, strips the country-code prefix by splitting on spaces and dropping the first segment, then normalizes to E.164 format by stripping all non-digit characters and prefixing with `+` (or produces an empty string if nothing remains); it then commits via the project's event-commit utility with event type `'changeNblur'`, the property name, and the normalized phone number.
+9. **Render** — a phone input with country selector, configured with: full width, an outlined style, small size, default country `US`, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and the test-id attribute applied to the underlying input element.
 
 ## Behavioral Contract
 
-1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop. `useEffect` watching `value` → `setInputValue(value)`.
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` input. A lifecycle effect watching `value` updates `inputValue`.
 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.
+4. **On blur (editable):** Extract and normalize the phone number to E.164 format: read the raw target value from the event, strip the country-code prefix by splitting the string on spaces and discarding the first segment, then strip all non-digit characters from the original value and prefix the result with `+` (producing an empty string if the stripped-prefix segment was empty). Commit the normalized value via the project's event-commit utility with event type `'changeNblur'`, the property name, and the normalized phone number.
+5. **Read-only:** Render the phone input with the read-only attribute on the input element and country dropdown disabled. Keep the country flag/code visible but non-interactive. The `onChange` handler used is the raw platform-wired `onChange` input (not the local state updater). Do NOT call the event-commit utility in read-only mode.
+6. **testId:** Pass as a test-identifier 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' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw phone string.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## 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>
-```
+Render the phone input wrapped in a container element, with a read-only attribute applied to the input element and the country dropdown disabled. The `onChange` handler passed through is the raw `onChange` from the field input contract (not a local handler), and `value` is the raw input value (not local state), with default country `US` still applied.
 
 ## Visual Specifications
 
@@ -153,58 +68,33 @@ Render phone input with `readOnly: true` and `disableDropdown: true` on the coun
 | 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;
-}
-```
+**Visual-only styling notes:** For a CSS-only implementation, build a two-part flex container: an outer wrapper with a 1px solid outlined border, 4px border radius, and hidden overflow so the two inner sections share one visual border; a country-select segment with no border of its own but a right-side divider border, horizontal padding, and a transparent background; and a number-input segment that flexes to fill remaining space, has no border, standard input padding, small font size, and no focus outline (since the outer wrapper conveys the focus/border state).
 
 ## 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.
+- **Read-only uses the raw `onChange` input** (not the local change handler) — this is the platform-wired handler, not the local state updater. Do NOT call the event-commit utility in read-only mode.
+- Country dropdown is disabled 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.
+- A phone input library with country code selector and E.164 formatting support.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 **For CSS-only / non-library implementations:**
 
-- Use a `<select>` for country code + a text `<input>` for the number.
+- Use a `<select>` for country code + a text `<input type="tel">` 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.
+When implementing in a specific design system, map the following:
 
-| 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 |
+- **Phone input** → use the DS's phone/telephone input or a third-party phone-input library compatible with the project's framework
+- **Country code selector** → a dropdown with flag + dial code as a prefix/adornment on the input
+- **Read-only mode** → keep the country flag visible but disable the dropdown and set the input to read-only
+- **E.164 normalization** → perform on blur before committing to the store

package/templates/react-sdk-reference/.ai-common/skills/field-skills/RadioButtons.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,126 +14,55 @@ Renders a group of radio buttons for single-selection from a list of options. Su
 
 - **Pega Name:** `RadioButtons`
 - **Type / Subtype:** `Field` / `Picklist-Radio`
-- **Registration key:** `RadioButtons` (in `component-map.ts`)
+- **Registration key:** `RadioButtons` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop                   | Type                 | Description                                                                     |
+| Name                   | 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                          |
+| `additionalProps`      | `any` (optional)     | Extra inputs 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                                                     |
 
-## Component Skeleton
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
 
 Follow this exact structure. Includes localization metadata derivation (same pattern as Dropdown).
 
-```typescript
-import { useState, useEffect } from 'react';
-import Utils from '../../helpers/utils';
-import handleEvent from '../../helpers/event-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface RadioButtonsProps extends PConnFieldProps {
-  inline: boolean;
-  fieldMetadata?: any;
-  variant?: string;
-  hideFieldLabels?: boolean;
-  additionalProps?: any;
-  imagePosition?: string;
-  imageSize?: string;
-  showImageDescription?: boolean;
-  datasource?: any;
-}
-
-export default function RadioButtons(props: RadioButtonsProps) {
-  // 1. Registry lookups
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-  const SelectableCard = getComponentFromRegistry('SelectableCard');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, value = '', readOnly, validatemessage,
-    helperText, status, required, inline, displayMode, hideLabel,
-    fieldMetadata, variant, hideFieldLabels, additionalProps,
-    datasource, imagePosition, imageSize, showImageDescription,
-  } = props;
-
-  // 3. State
-  const [theSelectedButton, setSelectedButton] = useState(value);
-
-  // 4. PConnect setup
-  const thePConn = getPConnect();
-  const theConfigProps = thePConn.getConfigProps();
-  const actionsApi = thePConn.getActionsApi();
-  const propName = (thePConn.getStateProps() as any).value;
-  const helperTextToDisplay = validatemessage || helperText;
-  const className = thePConn.getCaseInfo().getClassName();
-
-  // 5. Localization keys (same pattern as Dropdown)
-  let configProperty = (thePConn.getRawMetadata() as any)?.config?.value || '';
-  configProperty = configProperty.startsWith('@P') ? configProperty.substring(3) : configProperty;
-  configProperty = configProperty.startsWith('.') ? configProperty.substring(1) : configProperty;
-  const metaData = Array.isArray(fieldMetadata)
-    ? fieldMetadata.filter(f => f?.classID === className)[0] : fieldMetadata;
-  let displayName = metaData?.datasource?.propertyForDisplayText;
-  displayName = displayName?.slice(displayName.lastIndexOf('.') + 1);
-  const localeContext = metaData?.datasource?.tableType === 'DataPage' ? 'datapage' : 'associated';
-  const localeClass = localeContext === 'datapage' ? '@baseclass' : className;
-  const localeName = localeContext === 'datapage' ? metaData?.datasource?.name : configProperty;
-  const localePath = localeContext === 'datapage' ? displayName : localeName;
-
-  // 6. Load options (synchronous)
-  const theOptions = Utils.getOptionList(theConfigProps, thePConn.getDataObject(''));
-
-  // 7. useEffect: sync selected from value — deps: [value]
-  useEffect(() => { setSelectedButton(value); }, [value]);
-
-  // 8. Display mode returns (with localization)
-  if (displayMode === 'DISPLAY_ONLY') {
-    return <FieldValueList name={hideLabel ? '' : label}
-      value={thePConn.getLocalizedValue(value, localePath,
-        thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))} />;
-  }
-  if (displayMode === 'STACKED_LARGE_VAL') { /* same with variant="stacked" */ }
-
-  // 9. Event handlers
-  const handleChange = (event) => {
-    handleEvent(actionsApi, 'changeNblur', propName, event.target.value);
-  };
-  const handleBlur = (event) => {
-    thePConn.getValidationApi().validate(event.target.value, '');
-  };
-
-  // 10. Card variant return (variant === 'card')
-  //     → heading + grid + SelectableCard with type='radio'
-
-  // 11. Standard variant return
-  //     FormControl > FormLabel > RadioGroup(row={inline}) >
-  //       FormControlLabel per option (localized label) >
-  //     FormHelperText
-  return <RadioGroupWidget ... />;
-}
-```
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `SelectableCard`), the project's event-commit utility, and the project's utility helpers (for loading option lists). Define the input contract as an extension of the project's field input contract, adding `inline`, and optional `fieldMetadata`, `variant`, `hideFieldLabels`, `additionalProps`, `imagePosition`, `imageSize`, `showImageDescription`, and `datasource` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `SelectableCard` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `value` (default `''`), `readOnly`, `validatemessage`, `helperText`, `status`, `required`, `inline`, `displayMode`, `hideLabel`, `fieldMetadata`, `variant`, `hideFieldLabels`, `additionalProps`, `datasource`, `imagePosition`, `imageSize`, `showImageDescription`.
+3. **Local state** — `theSelectedButton` initialized from `value`.
+4. **PConnect setup** — obtain the PConnect instance, its config inputs via `thePConn.getConfigProps()`, actions API, bound property name, `helperTextToDisplay = validatemessage || helperText`, and `className` via `thePConn.getCaseInfo().getClassName()`.
+5. **Localization keys** (same pattern as Dropdown) — derive `configProperty` from the raw metadata config value (default `''`), stripping a leading `@P` prefix and then a leading `.`; derive `metaData`, `displayName`, `localeContext`, `localeClass`, `localeName`, and `localePath` the same way Dropdown does, except `localeName` falls back to `configProperty` (instead of `refName`) for the associated case.
+6. **Load options synchronously** — load the option list via the project's utility helper using the component's config inputs and the PConnect data object (no async fetching).
+7. **Sync effect** — a lifecycle effect watching `value` updates `theSelectedButton`.
+8. **Display mode returns (with localization)** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with `value` set to the localized display label via `thePConn.getLocalizedValue(value, localePath, thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))`.
+9. **Event handlers** — the change handler commits immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the selected value; the blur handler calls `thePConn.getValidationApi().validate(event.target.value, '')`.
+10. **Card variant return** (`variant === 'card'`) — a heading plus a CSS grid wrapper containing a `SelectableCard` configured with `type='radio'`; see the Behavioral Contract "Card" section for the full input wiring.
+11. **Standard variant return** — a form control containing a group label, a radio group (rendered as a horizontal row when `inline` is true) with one radio option per entry (each labeled with its localized text), and helper text below.
 
 ## 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)`.
+1. **Local state:** Maintain `theSelectedButton` (string). Initialize from the `value` input. A lifecycle effect watching `value` updates `theSelectedButton`.
+2. **Options:** Load options via the project's utility helper — returns an array of `{key: string, value: string}` objects.
+3. **On change:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the selected 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.
+5. **Inline layout:** Render the radio group as a horizontal row when `inline` is true.
+6. **Read-only:** Disable radio inputs (set `disabled` to the `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()`).
+   - Strip `@P ` prefix and leading `.` from `configProperty` (from the raw metadata).
    - `localeContext`: `'datapage'` if `fieldMetadata.datasource.tableType === 'DataPage'`, else `'associated'`.
    - `localeClass`: `'@baseclass'` for datapage, else `className`.
    - `localeName`: datapage name or property name.
@@ -141,89 +70,53 @@ export default function RadioButtons(props: RadioButtonsProps) {
 
 ### Variant: Standard (default)
 
-Render a radio group with `FormControl > FormLabel > RadioGroup > FormControlLabel (Radio)` pattern:
+Render a radio group with a form control, group label, radio group container, and individual radio option labels:
 
-- `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`
+- Group label: the `label` input
+- Radio group: value bound to `theSelectedButton`, change handler, blur handler wired only when not read-only, row layout when `inline` is true
+- Each radio option: `value` set to `option.key`, label set to the localized `option.value`, radio control disabled when `readOnly` is true
+- Helper text below for `helperTextToDisplay`
+- Error state on the form control when `status === 'error'`
 
 ### 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()`
+Render a heading with the `label`, then delegate to `SelectableCard`: a wrapping container with the heading (no top/bottom margin) followed by a CSS grid container (columns `repeat(auto-fit, minmax(min(200px, 100%), 1fr))`, gap `1rem`) holding a single `SelectableCard` configured with `type='radio'`, `dataSource` set to `datasource`, `recordKey` set to the last segment of the state's `value` path, `cardLabel` set to the last segment of the state's `primaryField` path, `radioBtnValue` set to `value`, `onChange` set to the change handler, an `image` config object (`imagePosition`, `imageSize`, `showImageDescription`, `imageField`, `imageDescription` — each derived by taking the last segment of the respective state path), `setIsRadioCardSelected` set to the state updater unless `displayMode === 'DISPLAY_ONLY'` (in which case `undefined`), `hideFieldLabels`, `additionalProps`, and `getPConnect`.
+
+**Critical: state prop key mapping for the `image` config object:**
+
+| SelectableCard image prop | Derived from state prop key | Transformation                  |
+| ------------------------- | --------------------------- | ------------------------------- |
+| `imageField`              | `image`                     | Take the last segment after `.` |
+| `imageDescription`        | `imageDescription`          | Take the last segment after `.` |
+
+The state prop key for the image property path is **`image`** (NOT `imageField`). The `imageField` name only refers to the prop passed INTO SelectableCard — it is derived by extracting the last dot-separated segment from the state prop whose key is `image`. For example, if `stateProps.image` is `'.PhoneImage'`, then `imageField` becomes `'PhoneImage'`.
+
+Similarly, `recordKey` is derived from `stateProps.value` (last segment), and `cardLabel` from `stateProps.primaryField` (last segment).
 
 ## 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' />`
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the localized value.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
-Where `localizedValue = pConn.getLocalizedValue(value, localePath, localeRuleName)`.
+Where the localized value is obtained via `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;
-}
-```
+| 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 (end placement) |
+| Group label         | Legend/label 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                |
+
+**Visual-only styling notes:** The radio group is a flex column with a small gap by default; the inline variant switches to a wrapping flex row with a slightly larger gap. Each radio label row is a flex container with centered items, a small gap, and a pointer cursor. Disabled radio inputs are shown at reduced opacity with a default (not-allowed-style) cursor.
 
 ### Card Variant
 
@@ -231,30 +124,30 @@ input[type='radio']:disabled {
 | -------- | ----------------------------------------------------------------------- |
 | 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                  |
+| Heading  | Heading element with no top/bottom margin 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.
+- Options are loaded synchronously via the project's utility helper on every render — no async fetching.
+- `theSelectedButton` tracks the selected key locally and syncs from the `value` input via a lifecycle effect.
+- Card variant uses a state update 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.
+- The project's utility helpers — for loading option lists.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- The project's component registry, resolving `SelectableCard` — for card variant.
 
 ## Design System Mapping
 
 **UI control type:** Radio button group (single selection).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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                          |
+- **Radio group** → use the DS's radio group component with individual radio options
+- **Inline layout** → render as a horizontal row when `inline` is true
+- **Card variant** → delegate to the `SelectableCard` component in a CSS grid
+- **Group wrapper** → use the DS's form control with legend/label, error state, and helper text
+- **Option labels** → localize via `pConn.getLocalizedValue()` before display
+- **Read-only** → disable radio inputs (do NOT use a separate read-only component)