@pega/sdk 0.0.4 → 0.0.5

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

@@ -0,0 +1,221 @@
+# 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`.
+
+## Component Skeleton
+
+Follow this exact structure. Replace `<DatePickerWidget>` with equivalents from your chosen design system.
+
+```typescript
+import { useEffect, useState } from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { dateFormatInfoDefault, getDateFormatInfo } from '../../helpers/date-format-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+// ── Helper function (top-level, outside component) ────────
+// Returns date as YYYY-MM-DD string for POSTing to server
+function getFormattedDate(date) {
+  return `${date.$y.toString()}-${(date.$M + 1).toString().padStart(2, '0')}-${date.$D.toString().padStart(2, '0')}`;
+}
+
+// ── Props interface ──────────────────────────────────────────
+interface DateProps extends PConnFieldProps {}
+
+// ── Component ────────────────────────────────────────────────
+export default function Date(props: DateProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value,
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel,
+  } = props;
+
+  // 3. State — initialize from value prop (null if empty)
+  const [dateValue, setDateValue] = useState<Dayjs | null>(
+    value ? dayjs(value) : null
+  );
+
+  // 4. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Date format info (mutate default with locale-specific values)
+  const dateFormatInfo = dateFormatInfoDefault;
+  const theDateFormat = getDateFormatInfo();
+  dateFormatInfo.dateFormatString = theDateFormat.dateFormatString;
+  dateFormatInfo.dateFormatStringLC = theDateFormat.dateFormatStringLC;
+  dateFormatInfo.dateFormatMask = theDateFormat.dateFormatMask;
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setDateValue(dayjs(value)); }, [value]);
+
+  // 7. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    const formattedDate = format(props.value, 'date', {
+      format: dateFormatInfo.dateFormatString,
+    });
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedDate} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    const formattedDate = format(props.value, 'date', {
+      format: dateFormatInfo.dateFormatString,
+    });
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedDate} variant="stacked" />;
+  }
+
+  // 8. Read-only return (BEFORE event handlers)
+  if (readOnly) {
+    return <TextInput {...props} />;
+  }
+
+  // 9. Test ID prop
+  const testProps: any = { 'data-test-id': testId };
+
+  // 10. handleChange — only commits valid dates
+  const handleChange = (date) => {
+    if (date && date.isValid()) {
+      setDateValue(date);
+      handleEvent(actions, 'changeNblur', propName, getFormattedDate(date));
+    }
+  };
+
+  // 11. Main render — date picker
+  //     Key props:
+  //     - label, disabled, value: dateValue
+  //     - format: dateFormatInfo.dateFormatString
+  //     - onChange: handleChange
+  //     - textField slot: required, variant: 'outlined', size: 'small',
+  //       placeholder: dateFormatInfo.dateFormatStringLC,
+  //       error: status === 'error', helperText: helperTextToDisplay,
+  //       InputProps: { ...testProps }
+  return <DatePickerWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `dateValue` as a `Dayjs | null`. Initialize: `value ? dayjs(value) : null`.
+2. **Sync from store:** `useEffect` with deps **`[value]`** → `setDateValue(dayjs(value))`.
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+4. **Date format info:** Start from `dateFormatInfoDefault`, then **mutate** its properties with locale-specific values from `getDateFormatInfo()`:
+   ```
+   const dateFormatInfo = dateFormatInfoDefault;
+   const theDateFormat = getDateFormatInfo();
+   dateFormatInfo.dateFormatString = theDateFormat.dateFormatString;
+   dateFormatInfo.dateFormatStringLC = theDateFormat.dateFormatStringLC;
+   dateFormatInfo.dateFormatMask = theDateFormat.dateFormatMask;
+   ```
+5. **On change (valid date selected):**
+   - Guard: `if (date && date.isValid())` — skip invalid/incomplete dates.
+   - Update state: `setDateValue(date)`.
+   - Format to `YYYY-MM-DD` using `getFormattedDate(date)` (see Helper Function below).
+   - Commit immediately: `handleEvent(actions, 'changeNblur', propName, formattedDate)`.
+6. **Read-only:** Return early with `<TextInput {...props} />` — delegates rendering entirely.
+7. **Placeholder:** Use `dateFormatInfo.dateFormatStringLC` (lowercase format, e.g., `'mm/dd/yyyy'`).
+8. **Test ID:** Build `testProps = { 'data-test-id': testId }` and pass via `InputProps` on the text field slot.
+
+## Helper Function
+
+Top-level pure function (outside the component). Uses dayjs internal properties:
+
+```typescript
+function getFormattedDate(date) {
+  return `${date.$y.toString()}-${(date.$M + 1).toString().padStart(2, '0')}-${date.$D.toString().padStart(2, '0')}`;
+}
+```
+
+**Note:** `date.$y` = year, `date.$M` = month (0-indexed), `date.$D` = day. If using a different date library, replace with equivalent accessors.
+
+## 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.
+- **Render ordering:** display modes → readOnly return → testProps → handleChange → main render. The readOnly check comes BEFORE handler definitions.
+- `dateFormatInfoDefault` is mutated in place (not spread-copied) — this is the existing pattern, maintain it.
+- `getFormattedDate` accesses dayjs internals (`$y`, `$M`, `$D`) — if using a different date library, adapt the accessors.
+
+## 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/.ai-common/skills/field-skills/DateTime.md

@@ -0,0 +1,213 @@
+# 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';
+```
+
+## Component Skeleton
+
+Follow this exact structure. Replace `<DateTimePickerWidget>` with equivalents from your chosen design system.
+
+```typescript
+import { useEffect, useState } from 'react';
+import dayjs, { Dayjs } from 'dayjs';
+import DateFormatter from '../../helpers/formatters/Date';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { dateFormatInfoDefault, getDateFormatInfo } from '../../helpers/date-format-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface DateTimeProps extends PConnFieldProps {}
+
+export default function DateTime(props: DateTimeProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel,
+  } = props;
+
+  // 3. Timezone
+  const environmentInfo = PCore.getEnvironmentInfo();
+  const timezone = environmentInfo && environmentInfo.getTimeZone();
+
+  // 4. State — convert UTC value to environment timezone for display
+  const [dateValue, setDateValue] = useState<Dayjs | null>(
+    value ? dayjs(DateFormatter.convertToTimezone(value, { timezone })) : null
+  );
+
+  // 5. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 6. Date format info (mutate default with locale values)
+  const dateFormatInfo = dateFormatInfoDefault;
+  const theDateFormat = getDateFormatInfo();
+  dateFormatInfo.dateFormatString = theDateFormat.dateFormatString;
+  dateFormatInfo.dateFormatStringLC = theDateFormat.dateFormatStringLC;
+  dateFormatInfo.dateFormatMask = theDateFormat.dateFormatMask;
+
+  // 7. useEffect: sync from store — deps: [value]
+  useEffect(() => {
+    setDateValue(dayjs(DateFormatter.convertToTimezone(value, { timezone })));
+  }, [value]);
+
+  // 8. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    const formattedDateTime = format(props.value, 'datetime', {
+      format: `${dateFormatInfo.dateFormatString} hh:mm a`,
+    });
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    const formattedDateTime = format(props.value, 'datetime', {
+      format: `${dateFormatInfo.dateFormatString} hh:mm a`,
+    });
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} variant="stacked" />;
+  }
+
+  // 9. Read-only return
+  if (readOnly) {
+    const formattedDateTime = format(props.value, 'datetime');
+    return <TextInput {...props} value={formattedDateTime} />;
+  }
+
+  // 10. Test ID prop
+  const testProps: any = { 'data-test-id': testId };
+
+  // 11. handleChange — convert to timezone-aware ISO, commit immediately
+  const handleChange = (date) => {
+    const timeZoneDateTime = (dayjs as any).tz(
+      date.format('YYYY-MM-DDTHH:mm:ss'), timezone
+    );
+    const changeValue = timeZoneDateTime?.isValid()
+      ? timeZoneDateTime.toISOString() : '';
+    setDateValue(timeZoneDateTime);
+    handleEvent(actions, 'changeNblur', propName, changeValue);
+  };
+
+  // 12. Main render — datetime picker
+  //     Key props:
+  //     - disabled, label, value: dateValue
+  //     - format: `${dateFormatInfo.dateFormatString} hh:mm a`
+  //     - minutesStep: 5
+  //     - onChange: handleChange
+  //     - textField slot: variant 'outlined', required, size 'small',
+  //       placeholder: `${dateFormatInfo.dateFormatStringLC} hh:mm a`,
+  //       error: status === 'error', helperText: helperTextToDisplay,
+  //       InputProps: { ...testProps }
+  return <DateTimePickerWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Timezone:** Read the environment timezone at render time:
+   ```
+   const environmentInfo = PCore.getEnvironmentInfo();
+   const timezone = environmentInfo && environmentInfo.getTimeZone();
+   ```
+2. **Local state:** Maintain `dateValue` as `Dayjs | null`. Initialize: `value ? dayjs(DateFormatter.convertToTimezone(value, { timezone })) : null`.
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+4. **Sync from store:** `useEffect` with deps **`[value]`** → `setDateValue(dayjs(DateFormatter.convertToTimezone(value, { timezone })))`.
+5. **Date/time format:** Mutate `dateFormatInfoDefault` with locale values from `getDateFormatInfo()` (same pattern as Date component). Combined format: `` `${dateFormatString} hh:mm a` ``.
+6. **Minutes step:** `minutesStep={5}` — time picker snaps to 5-minute increments.
+7. **On change:**
+   - Convert the selected date to timezone-aware ISO string:
+     ```
+     const timeZoneDateTime = (dayjs as any).tz(date.format('YYYY-MM-DDTHH:mm:ss'), timezone)
+     const changeValue = timeZoneDateTime?.isValid() ? timeZoneDateTime.toISOString() : ''
+     ```
+   - Update state: `setDateValue(timeZoneDateTime)`.
+   - Commit immediately: `handleEvent(actions, 'changeNblur', propName, changeValue)`.
+8. **Read-only:** Format with `format(props.value, 'datetime')` (no format option), delegate to `TextInput`.
+9. **Test ID:** `testProps = { 'data-test-id': testId }` — passed via `InputProps` on the text field slot.
+10. **Render ordering:** display modes → readOnly → testProps → handleChange → main render.
+
+## 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/{.claude → .ai-common}/skills/field-skills/Decimal.md

@@ -25,22 +25,121 @@ Renders a numeric input that accepts decimal values. Supports configurable decim
 | `showGroupSeparators` | `boolean` (optional) | —       | Whether to show thousands separators                                                         |
 | `formatter`           | `string` (optional)  | —       | `'Currency'` or `'Percentage'` — changes display mode formatting and read-only prefix/suffix |
 
+## Component Skeleton
+
+Follow this exact structure. Nearly identical to Currency but with configurable precision and conditional prefix/suffix.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getCurrencyCharacters, getCurrencyOptions } from '../Currency/currency-utils';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface DecimalProps extends PConnFieldProps {
+  currencyISOCode?: string;
+  decimalPrecision?: number;
+  showGroupSeparators?: boolean;
+  formatter?: string;
+}
+
+export default function Decimal(props: DecimalProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, helperText, displayMode,
+    hideLabel, currencyISOCode = 'USD', decimalPrecision,
+    showGroupSeparators, testId, placeholder, formatter,
+  } = props;
+
+  // 3. State
+  const [values, setValues] = useState(value.toString());
+
+  // 4. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Currency/decimal symbols
+  const theSymbols = getCurrencyCharacters(currencyISOCode);
+  const theCurrDec = theSymbols.theDecimalIndicator;
+  const theCurrSep = theSymbols.theDigitGroupSeparator;
+  const theCurrSym = theSymbols.theCurrencySymbol;
+  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setValues(value.toString()); }, [value]);
+
+  // 7. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Formatted value (computed eagerly, before display mode check)
+  let formattedValue = '';
+  if (formatter === 'Currency') {
+    formattedValue = format(value, formatter.toLowerCase(), theCurrencyOptions);
+  } else {
+    formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+  }
+
+  // 9. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant="stacked" />;
+  }
+
+  // 10. Test ID + event handlers
+  const testProps: any = { 'data-test-id': testId };
+  function decimalOnBlur() { handleEvent(actions, 'changeNblur', propName, values); }
+  const handleChange = (val) => { setValues(val.value); };
+
+  // 11. Main render — numeric format input
+  //     Key props:
+  //     - valueIsNumericString: true, fullWidth: true
+  //     - value: values
+  //     - variant: readOnly ? 'standard' : 'outlined'
+  //     - prefix: readOnly && formatter === 'Currency' ? theCurrSym : ''
+  //     - suffix: readOnly && formatter === 'Percentage' ? '%' : ''
+  //     - decimalSeparator: theCurrDec
+  //     - thousandSeparator: showGroupSeparators ? theCurrSep : ''
+  //     - decimalScale: readOnly && formatter === 'Currency' ? undefined : decimalPrecision
+  //     - onValueChange, onBlur: !readOnly ? decimalOnBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error', size: 'small'
+  //     - slotProps: { input: { ...readOnlyProp, inputProps: { ...testProps } } }
+  return <NumericFormatInput ... />;
+}
+```
+
 ## 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.
+2. **Sync from store:** `useEffect` with deps **`[value]`** → `setValues(value.toString())`.
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+4. **Separators:** Derive `theCurrDec` and `theCurrSep` from `getCurrencyCharacters(currencyISOCode)`. Apply `thousandSeparator` only when `showGroupSeparators` is truthy (otherwise pass `''`).
+5. **Formatted value (computed eagerly):**
+   ```
+   if (formatter === 'Currency') {
+     formattedValue = format(value, formatter.toLowerCase(), theCurrencyOptions);
+   } else {
+     formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+   }
+   ```
+6. **Prefix/Suffix (read-only only):**
+   - `prefix`: `readOnly && formatter === 'Currency' ? theCurrSym : ''`
+   - `suffix`: `readOnly && formatter === 'Percentage' ? '%' : ''`
+7. **Decimal scale:** `readOnly && formatter === 'Currency' ? undefined : decimalPrecision`.
+8. **On value change:** `setValues(val.value)` — raw numeric string.
+9. **On blur:** `handleEvent(actions, 'changeNblur', propName, values)`.
+10. **Read-only:** Set `readOnly: true` via `readOnlyProp`. Variant switches to `'standard'` (flat). `onBlur` omitted.
+11. **Render ordering:** state → readOnlyProp → formattedValue → display modes → testProps + handlers → main render.
 
 ## Display Mode Rendering