@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,100 @@
+# 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, input contract, 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 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` 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: 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`:** 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 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
+
+| 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                               |
+
+**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 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.
+- 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 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.
+
+When implementing in a specific design system, map the following:
+
+- **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

@@ -0,0 +1,153 @@
+# 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, input contract, 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 the project's component map)
+
+## Inputs (component-specific)
+
+| 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 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                                                     |
+
+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).
+
+**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 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:** 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 the raw metadata).
+   - `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 a form control, group label, radio group container, and individual radio option labels:
+
+- 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 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`:** 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 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 (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
+
+| 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  | Heading element with no top/bottom margin above grid                    |
+
+## Edge Cases & Special Logic
+
+- 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
+
+- 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).
+
+When implementing in a specific design system, map the following:
+
+- **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)

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

@@ -0,0 +1,117 @@
+# Skill: RichText
+
+Rich text editor field with HTML content support, binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a rich text (WYSIWYG) editor for HTML content. Uses a registry-resolved `RichTextEditor` component. Handles both read-only and editable states. Commits HTML content on blur by reading from the editor's internal instance reference.
+
+## Pega Metadata
+
+- **Pega Name:** `RichText`
+- **Type / Subtype:** `Field` / `Text-RichText`
+- **Registration key:** `RichText` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name              | Type                | Description                                    |
+| ----------------- | ------------------- | ---------------------------------------------- |
+| `additionalProps` | `object` (optional) | Extra inputs forwarded to the `RichTextEditor` |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. The `RichTextEditor` is resolved from the registry — it wraps whatever WYSIWYG library you choose.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `RichTextEditor`), the project's event-commit utility, and a companion stylesheet for editor theming. Define the input contract as an extension of the project's field input contract, adding an optional `additionalProps` field.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `RichTextEditor` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `value`, `placeholder`, `validatemessage`, `label`, `hideLabel`, `helperText`, `testId`, `displayMode`, `additionalProps`; also obtain the PConnect instance and create an instance reference for the editor (initialized to `null`).
+3. **Input coercion** — Pega may pass `readOnly`, `required`, and `disabled` as the strings `'true'`/`'false'` rather than booleans; map each to a real boolean by checking `prop === true || (typeof prop === 'string' && prop === 'true')`.
+4. **Derived** — `helperTextToDisplay = validatemessage || helperText`.
+5. **Display mode returns** (note the `isHtml` flag) — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` (the latter with a stacked variant) both return `FieldValueList` with `value` and `isHtml` set.
+6. **Read-only render** (no change/blur handlers) — render `RichTextEditor` with `additionalProps` spread, plus `label`, `labelHidden` set to `hideLabel`, `defaultValue` set to `value`, `testId`, `info` set to `helperTextToDisplay`, the editor instance reference, and `readOnly`.
+7. **Editable handlers** — obtain the actions API from PConnect; set a local `status` variable to `'error'` when `validatemessage !== ''`; the change handler clears error messages (via `pConn.clearErrorMessages({ property, category: '', context: '' })`, where `property` is the bound property name) when `status === 'error'`; the blur handler reads the HTML content from the editor instance reference (via its `getContent({ format: 'html' })` method) and commits it via the project's event-commit utility with event type `'changeNblur'`, the property name, and the HTML content.
+8. **Editable render** — render `RichTextEditor` with `additionalProps` spread, plus `label`, `labelHidden` set to `hideLabel`, `info` set to `helperTextToDisplay`, `defaultValue` set to `value`, `placeholder`, `disabled`, `required`, `testId`, the editor instance reference, `error` set to `status === 'error'`, the blur handler, and the change handler.
+
+## Behavioral Contract
+
+1. **Editor instance reference:** Maintain an instance reference for the editor — the editor exposes its content via the reference's `getContent({ format: 'html' })` method.
+2. **No local state** — unlike text inputs, value is NOT tracked in local state. The editor manages its own internal content via `defaultValue`.
+3. **Input coercion:** `readOnly`, `required`, `disabled` must be coerced to booleans by mapping each value to `prop === true || (typeof prop === 'string' && prop === 'true')`.
+4. **Editable mode:**
+   - Track `status` for error state.
+   - **On change:** If `status === 'error'`, clear error messages via `pConn.clearErrorMessages({ property, category: '', context: '' })`.
+   - **On blur:** Read HTML from the editor instance reference via its `getContent({ format: 'html' })` method and commit it via the project's event-commit utility with event type `'changeNblur'`, the property name, and the HTML content.
+5. **Read-only mode:** Render `RichTextEditor` with `readOnly` flag only — no change/blur handlers.
+6. **`RichTextEditor` component:** Resolved via the project's component registry. This is a design-system extension component that wraps the actual WYSIWYG library (e.g., TinyMCE).
+
+### Editable RichTextEditor inputs
+
+Spread `additionalProps` first, then pass `label`, `labelHidden` set to `hideLabel`, `info` set to `helperTextToDisplay`, `defaultValue` set to `value`, `placeholder`, `disabled`, `required`, `testId`, the editor instance reference, `error` set to `status === 'error'`, the blur handler, and the change handler.
+
+### Read-only RichTextEditor inputs
+
+Spread `additionalProps` first, then pass `label`, `labelHidden` set to `hideLabel`, `defaultValue` set to `value`, `testId`, `info` set to `helperTextToDisplay`, the editor instance reference, and `readOnly`.
+
+## Display Mode Rendering
+
+Display modes pass `isHtml` to render HTML content safely:
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true), `value`, and `isHtml` set.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant and `isHtml` set.
+
+## Read-Only Rendering
+
+Render `RichTextEditor` with `readOnly` flag. Uses the same editor instance reference.
+
+## Visual Specifications
+
+The visual appearance of the rich text editor depends on the underlying `RichTextEditor` implementation. The reference implementation uses editor theming via CSS variables, imported from a companion stylesheet: the toolbar and primary toolbar background use `--app-background-color`; toolbar buttons use `--app-text-color` for their icon color, and enabled/active toolbar buttons use `--app-primary-color` as background with white text; dialogs use `--modal-top-color` for background, `--app-text-color` for text, a 1px border in `--modal-border-color`, 20px padding, and a box shadow using `--modal-box-shadow-color`; the dialog header shares the same background/text colors with medium font weight and a bottom border in `--modal-border-color`.
+
+**Note:** Import the companion stylesheet in the component file. The CSS variables (`--app-background-color`, `--app-text-color`, etc.) are set by the application theme.
+
+When implementing with a different design system:
+
+- Custom CSS for toolbar theming may be needed
+- The editor container should be full-width
+- Minimum height: ~200px for a usable editing area
+
+## Edge Cases & Special Logic
+
+- **Input coercion to boolean:** Pega may pass these inputs as strings (`'true'`/`'false'`) — always coerce.
+- **On blur, NOT on change:** Content is committed to the store only on blur (when user leaves the editor), not on every keystroke.
+- **Error clearing:** When `status === 'error'`, the change handler clears the error message from Pega so it doesn't persist after the user starts editing.
+- **`editorRef.current.getContent`:** This method is specific to the TinyMCE API. For other rich text libraries, use the equivalent method to get HTML content.
+- **`FieldValueList` with `isHtml`:** The display mode renders HTML — ensure XSS protection in the `FieldValueList` component (use the framework's trusted HTML injection mechanism with proper sanitization).
+
+## Dependencies
+
+- The project's component registry, resolving `RichTextEditor` — the actual editor widget (e.g., TinyMCE wrapper).
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- The project's event-commit utility.
+- A companion stylesheet for editor toolbar theming.
+
+**For other rich text editors:**
+
+- Any WYSIWYG editor that exposes a method to get HTML content from an instance reference.
+- Examples: Quill, Slate.js, CKEditor, Tiptap.
+
+## Design System Mapping
+
+**UI control type:** WYSIWYG rich text editor (HTML content).
+
+When implementing in a specific design system, map the following:
+
+- **Rich text editor** → resolve the `RichTextEditor` component from the project's component registry
+- **Read-only** → pass the `readOnly` flag to the editor, which renders as static HTML display
+- **Display modes** → render `FieldValueList` with `isHtml` set for HTML content
+- **Blur commit** → read HTML from the editor's instance reference on blur and commit to store
+- **Theming** → import a companion stylesheet to theme the editor toolbar using CSS variables

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

@@ -0,0 +1,95 @@
+# Skill: ScalarList
+
+Read-only display component that renders a list of scalar values by creating a child component for each item.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a list of scalar (primitive) values by dynamically creating a child component of a specified type for each item. Used for read-only display of list-type properties. Not an editable input.
+
+## Pega Metadata
+
+- **Pega Name:** `ScalarList`
+- **Type / Subtype:** `Field` / `ScalarList`
+- **Registration key:** `ScalarList` (in the project's component map)
+
+## Inputs (component-specific)
+
+> ScalarList uses the project's base component interface (NOT the field input contract) because its `value` is an array, not a string.
+
+| Prop             | Type      | Description                                                                  |
+| ---------------- | --------- | ---------------------------------------------------------------------------- |
+| `value`          | `any[]`   | Array of scalar values to display                                            |
+| `componentType`  | `string`  | The Pega component type to use for each item (e.g., `'TextInput'`, `'Date'`) |
+| `label`          | `string`  | Field label                                                                  |
+| `displayMode`    | `string`  | Display mode                                                                 |
+| `hideLabel`      | `boolean` | Whether to hide the label                                                    |
+| `displayInModal` | `boolean` | Whether this is displayed in a modal context                                 |
+
+All remaining inputs are forwarded to each child component.
+
+## Implementation Structure
+
+Read-only display component — no state, no event handling.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`). Define the input contract as an extension of the project's base component interface (not the field input contract) with `displayInModal`, `hideLabel`, `value` (array), `componentType`, `label`, and `displayMode` fields.
+
+**Local sub-component `CommaSeparatedList`:** renders the given items as inline elements inside an unstyled list (no padding, no margin) — despite the name, there is no comma separator; items are simply adjacent inline elements.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `label`, `getPConnect`, `componentType`, `value` (aliased to `scalarValues`), `displayMode`, `hideLabel`, and the remaining inputs collected into `restInputs` for forwarding to each child.
+3. **Create child components for each scalar value** — map each entry in `scalarValues` to a child component created via `getPConnect().createComponent(...)`, passing a config object of `type: componentType` and a `config` object containing `value: scalarValue`, `displayMode: 'DISPLAY_ONLY'`, `label`, the spread remaining inputs, and `readOnly: 'true'`; the second, third, and fourth arguments to `createComponent` are an empty string, empty string, and empty object respectively (per its type signature).
+4. **Display mode: `STACKED_LARGE_VAL` or `DISPLAY_ONLY`** — return the items wrapped directly in a `<div>` containing `<CommaSeparatedList items={items} />`, with no `FieldValueList` wrapper.
+5. **Default** — wrap in `FieldValueList` with `name={hideLabel ? '' : label}`, `value={<CommaSeparatedList items={items} />}`, and `variant="stacked"`.
+
+## Behavioral Contract
+
+1. **No state, no event handling** — purely display/read-only.
+2. **Item rendering:** Map each value in `scalarValues` to a component via `getPConnect().createComponent(...)`, passing `type: componentType` and a `config` object with `value: scalarValue`, `displayMode: 'DISPLAY_ONLY'`, `label`, the spread remaining inputs, and `readOnly: 'true'`; the remaining three call arguments are an empty string, empty string, and empty object.
+3. **`CommaSeparatedList` sub-component:** A local component that renders items as inline elements inside a list with no list styling (zero padding, zero margin).
+
+## Display Mode Rendering
+
+**`STACKED_LARGE_VAL` or `DISPLAY_ONLY`:** the items are rendered directly inside a `<div>` wrapping a `<CommaSeparatedList items={items} />` — no `FieldValueList` wrapper in these modes.
+
+**Default (no display mode):** wrap in `FieldValueList` with `name={hideLabel ? '' : label}`, `value={<CommaSeparatedList items={items} />}`, and `variant='stacked'`.
+
+## Visual Specifications
+
+| Property     | Value                                                             |
+| ------------ | ----------------------------------------------------------------- |
+| List style   | No bullets, no padding, no margin on `<ul>`                       |
+| Item display | Each item rendered as `<span>` (inline)                           |
+| Separator    | Items are adjacent spans (no comma separator despite the name)    |
+| Layout       | Vertical stack when wrapped in `FieldValueList variant='stacked'` |
+
+**Visual-only styling notes:** The `<ul>` has no bullet markers and zero padding/margin. Each item span is rendered inline with no additional styling.
+
+## Edge Cases & Special Logic
+
+- `scalarValues` may be `undefined` — the `?.map()` safely returns `undefined`; ensure null-check before rendering.
+- Each child component is created with `displayMode: 'DISPLAY_ONLY'` and `readOnly: 'true'` (as string) — the read-only is passed as a string, not boolean.
+- `restInputs` includes all remaining inputs from the parent beyond the destructured ones — these are forwarded to each child component config.
+- `createComponent` takes 4 args — 2nd, 3rd, 4th are empty string/object as the typedef marks them optional.
+
+## Dependencies
+
+- The project's component registry, resolving `FieldValueList` — for default display.
+- `getPConnect().createComponent()` — for creating each child component.
+- No event-commit utility — read-only component.
+
+## Design System Mapping
+
+**UI control type:** Read-only list of scalar values.
+
+When implementing in a specific design system, map the following:
+
+- **List container** → an unstyled list element (no bullets, no padding/margin)
+- **List items** → inline elements for each rendered child component
+- **Default display** → wrap in `FieldValueList` with a stacked variant
+- **Display modes** → render the list directly without `FieldValueList` wrapper