@pega/sdk 0.0.1

package/templates/react-sdk-reference/.github/skills/field-skills/Checkbox.md

@@ -0,0 +1,158 @@
+# Skill: Checkbox
+
+Checkbox field supporting single boolean toggle, multi-selection mode, and optional card-style variant.
+
+> **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 one or more checkboxes. Supports three usage modes: (1) a single boolean checkbox, (2) a multi-select list of checkboxes bound to a reference list, and (3) a card-style selectable grid. Display mode shows the true/false label rather than the raw boolean.
+
+## Pega Metadata
+
+- **Pega Name:** `Checkbox`
+- **Type / Subtype:** `Field` / `Boolean`
+- **Registration key:** `Checkbox` (mapped to `CheckboxComponent` import in `component-map.ts`)
+
+## Props (component-specific)
+
+> Note: `Checkbox` uses `Omit<PConnFieldProps, 'value'>` with its own `value?: boolean`. Import type as:
+> ```typescript
+> import type { PConnFieldProps } from '@pega/sdk-react';
+> ```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `boolean` (optional) | Checked state for single-mode checkbox |
+| `caption` | `string` (optional) | Label shown next to the single checkbox (not the group label) |
+| `trueLabel` | `string` (optional) | Display text when `value` is `true` (used in display modes) |
+| `falseLabel` | `string` (optional) | Display text when `value` is `false` (used in display modes) |
+| `selectionMode` | `string` (optional) | `'multi'` — enables multi-selection mode from a datasource list |
+| `datasource` | `any` (optional) | Options source for multi/card modes |
+| `selectionKey` | `string` (optional) | The property path used as the key in selection list |
+| `selectionList` | `any` (optional) | Property path for the reference list (multi mode) |
+| `primaryField` | `string` | Primary display field for multi/card mode |
+| `readonlyContextList` | `any` | Array of currently selected items (for multi/card read-only display) |
+| `referenceList` | `string` | Reference list property path |
+| `variant` | `string` (optional) | `'card'` — renders options as selectable card grid |
+| `hideFieldLabels` | `boolean` | Hide field labels inside card variant |
+| `additionalProps` | `any` | Extra props passed to card or checkbox |
+| `imagePosition` | `string` | Card image position |
+| `imageSize` | `string` | Card image size |
+| `showImageDescription` | `string` | Whether to show image description |
+| `renderMode` | `string` | `'ReadOnly'` — sets read-only mode alongside `readOnly` prop |
+| `image` | `string` | Image field path for card variant |
+
+## Behavioral Contract
+
+### Common
+
+1. **Read-only determination:** `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`.
+2. **Local state:** Maintain `checked` (boolean) from `value` prop. `useEffect` watching `value` → `setChecked(value)`.
+3. **Reference list init:** On mount (`useEffect` watching `pConn`), if `referenceList.length > 0 && !readOnlyMode`, call `pConn.setReferenceList(selectionList)` and `updateNewInstuctions(pConn, selectionList)`.
+
+### Variant: Single checkbox (default)
+
+Render a single checkbox with:
+- `checked={checked}`
+- `onChange={!readOnly ? handleChange : undefined}`
+- `onBlur={!readOnly ? handleBlur : undefined}`
+- Label = `caption` (next to checkbox)
+- Group label = `label` (above, hidden if `hideLabel`)
+- **On change:** `handleEvent(actionsApi, 'changeNblur', propName, event.target.checked)` — passes boolean.
+- **On blur:** `pConn.getValidationApi().validate(event.target.checked)`.
+
+### Variant: Multi-select (`selectionMode === 'multi'`)
+
+Render a list of checkboxes from `datasource.source`:
+- Each option: `key` from `selectionKey` extraction, `text`/`value` as label.
+- `checked` per option: `selectedvalues.some(data => data[dataField] === element.key)` where `dataField = selectionKey.split('.')[1]`.
+- **On change per checkbox:**
+  - If checked: `insertInstruction(pConn, selectionList, selectionKey, primaryField, { id, primary })`.
+  - If unchecked: `deleteInstruction(pConn, selectionList, selectionKey, { id, primary })`.
+  - `pConn.clearErrorMessages({ property: selectionList, category: '', context: '' })`.
+- Layout: vertical column (`display: flex, flexDirection: column`).
+
+### Variant: Card (`variant === 'card'`)
+
+Render a heading (`<h4>`) + CSS Grid + `SelectableCard` component:
+- Grid: `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, `gridAutoRows: '1fr'`, `gap: '0.5rem'`.
+- `SelectableCard` props:
+  - `type='checkbox'`
+  - `dataSource={datasource}`
+  - `readOnlyList={selectedvalues}` (for read-only display)
+  - `readOnly={renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly}`
+  - `recordKey={selectionKey?.split('.').pop()}`
+  - `cardLabel={primaryField.split('.').pop()}`
+  - `image` config from `imagePosition`, `imageSize`, `showImageDescription`, `image` props
+  - `showNoValue={(readOnlyMode) && selectedvalues.length === 0}`
+  - `onChange`: calls `handleCheckboxChange` on each item
+  - `onBlur`: `pConn.getValidationApi().validate(selectedvalues, selectionList)`
+
+## Display Mode Rendering
+
+Display mode uses `caption` (not `label`) and shows true/false label:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : caption} value={value ? trueLabel : falseLabel} variant='stacked' />`
+
+## Read-Only Rendering
+
+Single mode: Set `readOnly` on checkbox element; disable `onChange`/`onBlur`.
+Multi/Card mode: `readOnlyMode` flag prevents `insertInstruction`/`deleteInstruction`; cards show `readOnlyList`.
+
+## Visual Specifications
+
+### Standard / Multi-select
+
+| Property | Value |
+|----------|-------|
+| Checkbox size | Default (24px) |
+| Label placement | End (right of checkbox) |
+| Group label | `<legend>` above group, hidden if `hideLabel` |
+| Layout | Single: single row. Multi: vertical column |
+| Helper text | Below group |
+| Error state | Red text/border on helper |
+| Disabled/readOnly | Greyed out, pointer-events none |
+
+**CSS-only:**
+```css
+.checkbox-group { display: flex; flex-direction: column; gap: 4px; }
+.checkbox-label { display: flex; align-items: center; gap: 8px; cursor: pointer; }
+input[type="checkbox"]:disabled { opacity: 0.38; }
+```
+
+### Card Variant
+
+| Property | Value |
+|----------|-------|
+| Layout | CSS Grid `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, row height equal (`1fr`), gap `0.5rem` |
+| Heading | `<h4>` with `marginTop: 0, marginBottom: 0` |
+
+## Edge Cases & Special Logic
+
+- **`handleCheckboxChange`** (card mode): Finds the selected item from `datasource.source` by matching `item[recordKey] === e.target.id`, then calls `insertInstruction`/`deleteInstruction`.
+- `updateNewInstuctions` is called on mount to sync reference list state.
+- `clearErrorMessages` is called after every multi-select change.
+- For card read-only: use `readOnlyList` prop populated from `selectedvalues`.
+
+## Dependencies
+
+- `insertInstruction`, `deleteInstruction`, `updateNewInstuctions` from `../../helpers/instructions-utils` — for multi-selection reference list management.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `getComponentFromRegistry('SelectableCard')` for card variant.
+
+## Design System Mapping
+
+**UI control type:** Single or multi-select checkbox (boolean or list).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="checkbox">` with `<label>` |
+| MUI | `<Checkbox>` in `<FormControlLabel>`, `<FormGroup>` |
+| Ant Design | `<Checkbox>` / `<Checkbox.Group>` |
+| Chakra UI | `<Checkbox>` / `<CheckboxGroup>` |

package/templates/react-sdk-reference/.github/skills/field-skills/Currency.md

@@ -0,0 +1,106 @@
+# Skill: Currency
+
+Currency input field with locale-aware symbol, decimal separator, and thousands separator. Supports ISO currency codes.
+
+> **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 formatted as a currency value. Displays the correct currency symbol, decimal separator, and thousands separator for the given ISO currency code. Uses a numeric formatting library to handle locale-aware input. Shows formatted read-only values in display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `Currency`
+- **Type / Subtype:** `Field` / `Decimal-Currency`
+- **Registration key:** `Currency` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`, `'GBP'`) |
+| `allowDecimals` | `boolean` | — | Whether to allow decimal input. If `false`, `decimalScale=0`. If `true`, fixed 2 decimal places shown. |
+
+All other props from `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Currency symbols:** Derive the currency symbol, decimal indicator, and digit group separator from the `currencyISOCode` using locale-aware lookup:
+   - Call locale-aware currency formatter for the ISO code to determine: `theCurrencySymbol`, `theDecimalIndicator`, `theDigitGroupSeparator`.
+   - Default: `$`, `.`, `,` (USD/en-US).
+4. **Numeric format config:**
+   - `prefix`: the currency symbol
+   - `decimalSeparator`: `theDecimalIndicator`
+   - `thousandSeparator`: `theDigitGroupSeparator`
+   - `decimalScale`: `allowDecimals !== false ? 2 : 0`
+   - `fixedDecimalScale`: `allowDecimals` — forces exactly 2 decimal places when `true`
+   - `valueIsNumericString`: `true`
+5. **On value change:** Update local `values` state with the raw numeric string (from the numeric format library's callback).
+6. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, values)`.
+7. **Read-only:** Set `readOnly: true` on the input. Visual style switches to flat/borderless. The formatted display value (from `format()` helper) is shown rather than raw numeric.
+
+## Display Mode Rendering
+
+Format the value before display using a currency formatter with `currencyISOCode`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />` where `formattedValue = format(value, 'currency', currencyOptions)`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+The `formattedValue` uses the locale and currency from `currencyISOCode` to produce a localized string (e.g., `$1,234.56`).
+
+## Read-Only Rendering
+
+Keep the numeric format input but set `readOnly: true` on the input element. Switch the visual variant to flat/borderless. The `onBlur` handler is omitted (`onBlur={!readOnly ? currOnBlur : undefined}`).
+
+## Visual Specifications
+
+| Property | Standard (editable) | Read-only |
+|----------|---------------------|-----------|
+| Width | 100% | 100% |
+| Size | Small | Small |
+| Variant | Outlined | Standard (flat) |
+| Prefix | Currency symbol (e.g., `$`) | Currency symbol |
+| Alignment | Left-aligned text | Left-aligned |
+| Decimal places | 2 (when `allowDecimals`) | 2 |
+| Error state | Red border + red helper text | — |
+| Placeholder | From `placeholder` prop | — |
+
+## Edge Cases & Special Logic
+
+- **EUR uses `nl-NL` locale:** When `currencyISOCode === 'EUR'`, use NL locale for symbol/separator lookup.
+- **Fallback:** If `currencyISOCode` lookup fails, fall back to USD (`$`, `.`, `,`).
+- **`allowDecimals` vs `fixedDecimalScale`:** `fixedDecimalScale` is only applied when `allowDecimals` is explicitly `true`. It forces `decimalScale=2` and shows trailing zeros.
+- The input stores the raw numeric string (e.g., `'1234.56'`) in state and in the Pega store — not the formatted display string.
+- `data-test-id` is passed via `inputProps` on the inner input element.
+
+## Dependencies
+
+- A numeric formatting library (e.g., `react-number-format`'s `NumericFormat`) — handles locale-aware separators, prefix, and decimal scale.
+- `format()` from `../../helpers/formatters` — for display mode value formatting.
+- `getCurrencyCharacters(currencyISOCode)` — returns `{ theCurrencySymbol, theDecimalIndicator, theDigitGroupSeparator }`.
+- `getCurrencyOptions(currencyISOCode)` — returns `{ locale, style: 'currency', currency }` for the `format()` call.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+**For CSS-only / design-system-agnostic implementations:**
+- The numeric format library handles the input masking. Use any numeric format library that supports prefix, decimal separator, and thousands separator configuration.
+- Alternatively, implement manually: on change, strip non-numeric chars, insert separators, prepend symbol.
+
+## Design System Mapping
+
+**UI control type:** Currency / numeric formatted input with prefix symbol.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` + custom numeric formatting logic |
+| MUI | `NumericFormat` (from `react-number-format`) with `customInput={TextField}` |
+| Ant Design | `<InputNumber prefix="$" precision={2} />` |
+| Chakra UI | `<NumberInput>` + custom formatting |

package/templates/react-sdk-reference/.github/skills/field-skills/Date.md

@@ -0,0 +1,99 @@
+# Skill: Date
+
+Date picker field with locale-aware date format string, 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 date picker input. Stores dates as `YYYY-MM-DD` strings. Displays dates according to locale-aware format (e.g., `MM/DD/YYYY` for en-US). Uses a date picker library for the calendar UI. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Date`
+- **Type / Subtype:** `Field` / `Date`
+- **Registration key:** `Date` (mapped to `DateField` import in `component-map.ts` to avoid conflicts with the JS `Date` global)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+> **Important naming note:** The component file exports a function named `Date`. In `component-map.ts`, import it as `DateField` and register it as `Date: DateField`.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `dateValue` as a date object (e.g., a `dayjs` object or `Date` instance), initialized from `value` prop using the date library's parser. Default to `null` if value is empty/falsy.
+2. **Sync from store:** `useEffect` watching `value` → re-parse and `setDateValue(dayjs(value))`.
+3. **Date format:** Get locale-aware format string via `getDateFormatInfo()`:
+   - Returns `dateFormatString` (display format, e.g., `'MM/DD/YYYY'`), `dateFormatStringLC` (lowercase for placeholder, e.g., `'mm/dd/yyyy'`), `dateFormatMask`.
+   - Start from `dateFormatInfoDefault` and override with locale-specific values.
+4. **On change (valid date selected):** 
+   - Validate the date is valid (e.g., `date.isValid()`).
+   - Format to `YYYY-MM-DD` string: `${year}-${(month+1).padStart(2,'0')}-${day.padStart(2,'0')}`.
+   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, formattedDate)`.
+   - Update local `dateValue` state.
+5. **Invalid dates:** If `date.isValid()` is false, do NOT commit — ignore the change.
+6. **Read-only:** Delegate to `TextInput`: `return <TextInput {...props} />`.
+7. **Placeholder:** Use lowercase format string (e.g., `'mm/dd/yyyy'`).
+
+## Display Mode Rendering
+
+Format the value before display using `format(value, 'date', { format: dateFormatInfo.dateFormatString })`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDate} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDate} variant='stacked' />`.
+- Both modes compute `formattedDate` from the raw `props.value` (not local state).
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`. The raw `YYYY-MM-DD` string is displayed as-is (or formatted by `TextInput`'s read-only rendering).
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | Auto (date picker natural width) |
+| Size | Small |
+| Variant | Outlined |
+| Placeholder | Lowercase format string (e.g., `mm/dd/yyyy`) |
+| Calendar popup | Opens below the input |
+| Error state | Red border + red helper text |
+| Required indicator | `*` on label |
+| Format display | Locale-aware (e.g., `MM/DD/YYYY`, `DD/MM/YYYY`) |
+
+**CSS-only notes:** For a CSS-only date input, use `<input type="date">` — note that the display format is browser-controlled. A custom date picker component is needed for locale-aware format strings.
+
+## Edge Cases & Special Logic
+
+- Commit on **change** (when a valid date is selected), not on blur — this differs from text inputs.
+- Always store value as `YYYY-MM-DD` regardless of display format.
+- Invalid/incomplete dates (e.g., partially typed) are ignored — only commit when `isValid()` returns true.
+- Locale format info is derived at render time from `getDateFormatInfo()` — this reads the Pega environment locale.
+
+## Dependencies
+
+- Date manipulation library (e.g., `dayjs`) — for parsing, formatting, validity checking.
+- Date picker UI component (e.g., `@mui/x-date-pickers/DatePicker`) — for calendar popup.
+- `getDateFormatInfo()` from `../../helpers/date-format-utils` — for locale-aware format string.
+- `dateFormatInfoDefault` from same helper — default fallback.
+- `format()` from `../../helpers/formatters` — for display mode formatting.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only delegation.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Date picker with calendar popup.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="date">` (browser native, limited locale control) |
+| MUI | `<DatePicker />` from `@mui/x-date-pickers` with `dayjs` adapter |
+| Ant Design | `<DatePicker format="MM/DD/YYYY" />` |
+| Chakra UI | Third-party date picker or `<input type="date">` |

package/templates/react-sdk-reference/.github/skills/field-skills/DateTime.md

@@ -0,0 +1,103 @@
+# Skill: DateTime
+
+Date and time picker with timezone conversion, 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 combined date and time picker. Stores values as ISO 8601 UTC strings. Converts to/from the Pega environment's configured timezone for display. Shows formatted date-time in display modes. Delegates read-only rendering to `TextInput` with a formatted string.
+
+## Pega Metadata
+
+- **Pega Name:** `DateTime`
+- **Type / Subtype:** `Field` / `DateTime`
+- **Registration key:** `DateTime` (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. **Timezone:** Read the environment timezone at render time:
+   ```
+   const timezone = PCore.getEnvironmentInfo().getTimeZone()
+   ```
+2. **Local state:** Maintain `dateValue` as a timezone-aware date object. Initialize from `value` prop by converting to the environment timezone using `DateFormatter.convertToTimezone(value, { timezone })`.
+3. **Sync from store:** `useEffect` watching `value` → re-convert and `setDateValue(dayjs(DateFormatter.convertToTimezone(value, { timezone })))`.
+4. **Date/time format:** Get locale-aware format from `getDateFormatInfo()`. Combined format: `${dateFormatString} hh:mm a` (e.g., `'MM/DD/YYYY hh:mm a'`). Placeholder: `${dateFormatStringLC} hh:mm a`.
+5. **Minutes step:** `minutesStep={5}` — time picker snaps to 5-minute increments.
+6. **On change:**
+   - Convert the selected date to timezone-aware ISO string:
+     ```
+     const timeZoneDateTime = dayjs.tz(date.format('YYYY-MM-DDTHH:mm:ss'), timezone)
+     const changeValue = timeZoneDateTime?.isValid() ? timeZoneDateTime.toISOString() : ''
+     ```
+   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, changeValue)`.
+   - Update local `dateValue`.
+7. **Read-only:** Format value as string using `format(value, 'datetime')`, then delegate: `return <TextInput {...props} value={formattedDateTime} />`.
+
+## Display Mode Rendering
+
+Format using `format(value, 'datetime', { format: \`${dateFormatString} hh:mm a\` })`:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Format value as `format(props.value, 'datetime')` then pass to `TextInput`:
+```
+return <TextInput {...props} value={formattedDateTime} />
+```
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| Width | Auto |
+| Size | Small |
+| Variant | Outlined |
+| Format | `MM/DD/YYYY hh:mm a` (locale-aware date + 12h time) |
+| Placeholder | Lowercase format, e.g., `mm/dd/yyyy hh:mm a` |
+| Minutes step | 5 minutes |
+| Error state | Red border + red helper text |
+
+**Note on known issue:** Keyboard input in the minute field may jump to the am/pm field after one digit — this is a known quirk of some date-time picker library versions.
+
+## Edge Cases & Special Logic
+
+- All stored values are **UTC ISO 8601 strings** (e.g., `'2024-03-15T14:30:00.000Z'`).
+- **Timezone conversion** is critical: always convert from UTC → environment timezone for display, and from environment timezone → UTC when committing.
+- If `timeZoneDateTime.isValid()` is false, commit an empty string `''`.
+- Commits on **change** (picker selection), not on blur.
+- `dayjs.tz` requires `dayjs-timezone` plugin.
+
+## Dependencies
+
+- Date manipulation library with timezone support (e.g., `dayjs` + `dayjs/plugin/timezone`).
+- `DateFormatter.convertToTimezone(value, { timezone })` from `../../helpers/formatters/Date` — converts stored UTC value to display timezone.
+- `format()` from `../../helpers/formatters` — for display mode formatting.
+- `getDateFormatInfo()` from `../../helpers/date-format-utils` — for locale date format string.
+- Date-time picker UI component (e.g., `@mui/x-date-pickers/DateTimePicker`).
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Combined date and time picker with timezone awareness.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="datetime-local">` (no timezone control) |
+| MUI | `<DateTimePicker />` from `@mui/x-date-pickers` + `dayjs.tz` |
+| Ant Design | `<DatePicker showTime />` |
+| Chakra UI | Third-party datetime picker |

package/templates/react-sdk-reference/.github/skills/field-skills/Decimal.md

@@ -0,0 +1,98 @@
+# Skill: Decimal
+
+Decimal number input with configurable precision, group separators, and optional currency/percentage display formatting.
+
+> **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 that accepts decimal values. Supports configurable decimal precision, optional thousands separator, and optional formatter override (`'Currency'` or `'Percentage'`). Differs from `Currency` in that it's more generic — it can display values as currency, percentage, or plain decimal based on a `formatter` prop.
+
+## Pega Metadata
+
+- **Pega Name:** `Decimal`
+- **Type / Subtype:** `Field` / `Decimal`
+- **Registration key:** `Decimal` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO code for symbol/separator lookup (used when `formatter === 'Currency'`) |
+| `decimalPrecision` | `number` (optional) | — | Number of decimal places to show |
+| `showGroupSeparators` | `boolean` (optional) | — | Whether to show thousands separators |
+| `formatter` | `string` (optional) | — | `'Currency'` or `'Percentage'` — changes display mode formatting and read-only prefix/suffix |
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
+3. **Separators:** Always derive `decimalSeparator` and `thousandSeparator` from locale lookup using `currencyISOCode`. Apply `thousandSeparator` only when `showGroupSeparators` is `true`.
+4. **Decimal scale:** Use `decimalPrecision` prop for `decimalScale` — except in read-only mode with `formatter === 'Currency'`, where `decimalScale` is `undefined`.
+5. **Prefix/Suffix in read-only:**
+   - If `readOnly && formatter === 'Currency'`: show currency symbol as prefix.
+   - If `readOnly && formatter === 'Percentage'`: show `%` as suffix.
+   - Otherwise: no prefix/suffix.
+6. **Formatted display value:**
+   - If `formatter === 'Currency'`: `formattedValue = format(value, 'currency', currencyOptions)`.
+   - Otherwise: `formattedValue = format(value, 'decimal', currencyOptions)`.
+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. Visual style switches to flat/borderless. `onBlur` omitted.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+`formattedValue` is computed before display-mode check:
+- `formatter === 'Currency'` → currency-formatted string.
+- Otherwise → decimal-formatted string using `pConn.getComponentName()?.toLowerCase()` as format key.
+
+## Read-Only Rendering
+
+Keep numeric format input with `readOnly: true`. Apply prefix (`$`) or suffix (`%`) based on `formatter`. Flat/borderless visual style.
+
+## Visual Specifications
+
+| Property | Standard (editable) | Read-only |
+|----------|---------------------|-----------|
+| Width | 100% | 100% |
+| Size | Small | Small |
+| Variant | Outlined | Standard (flat) |
+| Prefix | None (unless read-only Currency) | Currency symbol if `formatter='Currency'` |
+| Suffix | None (unless read-only Percentage) | `%` if `formatter='Percentage'` |
+| Thousands separator | Only when `showGroupSeparators=true` | Same |
+| Decimal scale | From `decimalPrecision` | Undefined for Currency, `decimalPrecision` otherwise |
+| Placeholder | From `placeholder` prop | — |
+
+## Edge Cases & Special Logic
+
+- In read-only Currency mode, `decimalScale` is set to `undefined` (let the formatter decide), not `decimalPrecision`.
+- `thousandSeparator` defaults to `''` (disabled) unless `showGroupSeparators` is `true`.
+- `prefix` and `suffix` are only rendered in read-only mode — NOT in editable mode.
+- The stored value is always a raw numeric string, not the formatted display string.
+
+## Dependencies
+
+- Numeric formatting library (e.g., `react-number-format`'s `NumericFormat`).
+- `getCurrencyCharacters(currencyISOCode)` — for `theDecimalIndicator` and `theDigitGroupSeparator`.
+- `getCurrencyOptions(currencyISOCode)` — for `format()` options.
+- `format()` from `../../helpers/formatters`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Decimal / numeric formatted input.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<input type="text">` with custom numeric masking |
+| MUI | `NumericFormat` with `customInput={TextField}` |
+| Ant Design | `<InputNumber precision={decimalPrecision} />` |
+| Chakra UI | `<NumberInput>` |