@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,157 +14,59 @@ Renders a combined date and time picker. Stores values as ISO 8601 UTC strings.
 
 - **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 ... />;
-}
-```
+- **Registration key:** `DateTime` (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 date-time picker widget with an equivalent from your chosen design system.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`), the project's event-commit utility, a date-to-timezone conversion helper from the project's date formatter module, the project's formatting helpers, and the project's date-format utility (for locale-aware format strings). It also uses a date manipulation library with timezone support and a date-time picker UI component. Define the input contract as the project's field input contract with no additional fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `TextInput` and `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`.
+3. **Timezone** — read the environment timezone at render time via `PCore.getEnvironmentInfo().getTimeZone()`.
+4. **Local state** — `dateValue` typed as a date object or null, initialized by converting `value` to the environment timezone via the project's date-to-timezone conversion helper and wrapping in the date library's parser (or `null` when `value` is empty).
+5. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+6. **Date format info** — start from the project's default date-format info and mutate its `dateFormatString`, `dateFormatStringLC`, and `dateFormatMask` properties with locale-specific values from the project's date-format utility (same pattern as the Date component).
+7. **Sync from store** — a lifecycle effect watching `value` re-runs the same timezone conversion and updates `dateValue`.
+8. **Display mode returns** — for both `DISPLAY_ONLY` and `STACKED_LARGE_VAL`, compute the formatted date-time using the project's formatting helper with format type `'datetime'` and options `{ format: '<dateFormatString> hh:mm a' }`, then return `FieldValueList` with that value (the latter with a stacked variant).
+9. **Read-only return** — compute the formatted date-time using the project's formatting helper with format type `'datetime'` (no format option) and render the `TextInput` component with all inputs passed through, overriding `value` with the formatted string.
+10. **Test ID** — build a test-id attribute from `testId`.
+11. **Change handler — convert to timezone-aware ISO, commit immediately** — build a timezone-aware date instance from the selected date's `'YYYY-MM-DDTHH:mm:ss'` string and the environment timezone; if that instance is valid, convert it to an ISO string, otherwise use an empty string; update local state with the timezone-aware instance and immediately commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the ISO string.
+12. **Render** — a datetime picker configured with: `disabled`, `label`, current `dateValue`, a combined format of the locale-aware date format string plus `' hh:mm a'`, minutes step of `5`, the change handler, and a nested text-field slot configured with an outlined style, `required`, small size, a combined placeholder of the lowercase date format plus `' hh:mm a'`, an error state when `status === 'error'`, `helperText: helperTextToDisplay`, and the test-id attribute applied to the input element.
 
 ## 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`.
+1. **Timezone:** Read the environment timezone at render time via `PCore.getEnvironmentInfo()` and its `getTimeZone()` accessor (guard against a missing environment info object).
+2. **Local state:** Maintain `dateValue` as a date object or null. Initialize: convert `value` from UTC to the environment timezone using the project's date-to-timezone conversion helper, then parse with the date library (or `null` when `value` is empty).
 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.
+4. **Sync from store:** A lifecycle effect watching `value` re-runs the timezone conversion and updates `dateValue`.
+5. **Date/time format:** Mutate the default date-format info with locale values from the project's date-format utility (same pattern as Date component). Combined format: the date format string plus `' hh:mm a'`.
+6. **Minutes step:** `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.
+   - Convert the selected date to a timezone-aware ISO string: build a timezone-aware date instance from the date formatted as `'YYYY-MM-DDTHH:mm:ss'` and the environment timezone; if that instance is valid, convert to an ISO string, otherwise use an empty string.
+   - Update state with the timezone-aware date instance.
+   - Commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the ISO string.
+8. **Read-only:** Format with the project's formatting helper using format type `'datetime'` (no format option), then delegate to `TextInput` with the formatted string as the `value` override.
+9. **Test ID:** Build a test-id attribute from `testId` and pass via the text field slot's input element.
+10. **Render ordering:** display modes → readOnly → test-id → change handler → main render.
 
 ## Display Mode Rendering
 
-Format using `format(value, 'datetime', { format: \`${dateFormatString} hh:mm a\` })`:
+Format using the project's formatting helper with format type `'datetime'` and options `{ format: '<dateFormatString> hh:mm a' }`:
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} />`.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedDateTime} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the formatted date-time.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Format value as `format(props.value, 'datetime')` then pass to `TextInput`:
-
-```
-return <TextInput {...props} value={formattedDateTime} />
-```
+Format value using the project's formatting helper with format type `'datetime'` (no format option), then pass it as the `value` override to `TextInput`, along with all other inputs.
 
 ## Visual Specifications
 
@@ -184,30 +86,30 @@ return <TextInput {...props} value={formattedDateTime} />
 
 - 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 `''`.
+- If the timezone-aware date instance is invalid, commit an empty string `''`.
 - Commits on **change** (picker selection), not on blur.
-- `dayjs.tz` requires `dayjs-timezone` plugin.
+- The date library's timezone plugin is required for timezone-aware conversions.
 
 ## 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.
+- A date manipulation library with timezone support (e.g., the date library plus its timezone plugin).
+- The project's date-to-timezone conversion helper — converts stored UTC value to display timezone.
+- The project's formatting helpers — specifically the named `format` export (not a method on the default export). Use it as a standalone function, not as a property of the default-exported object.
+- The project's date-format utility — for locale date format string.
+- A date-time picker UI component (for the combined calendar + time popup).
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
 **UI control type:** Combined date and time picker with timezone awareness.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                        |
-| ------------------ | ------------------------------------------------------------ |
-| Default (CSS only) | `<input type="datetime-local">` (no timezone control)        |
-| MUI                | `<DateTimePicker />` from `@mui/x-date-pickers` + `dayjs.tz` |
-| Ant Design         | `<DatePicker showTime />`                                    |
-| Chakra UI          | Third-party datetime picker                                  |
+- **Date-time picker** → use the DS's combined date-time picker component or a compatible third-party picker
+- **Date format** → pass the combined locale-aware format string (date portion plus `' hh:mm a'`)
+- **Timezone conversion** → convert UTC ↔ environment timezone on read/write using the project's date-to-timezone helper
+- **Minutes step** → configure the time picker to snap to 5-minute increments
+- **Read-only mode** → format the value and delegate to `TextInput`
+- **Commit behavior** → commit on valid selection (not on blur)

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

@@ -2,158 +2,80 @@
 
 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.
+> **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 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.
+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` input.
 
 ## Pega Metadata
 
 - **Pega Name:** `Decimal`
 - **Type / Subtype:** `Field` / `Decimal`
-- **Registration key:** `Decimal` (in `component-map.ts`)
+- **Registration key:** `Decimal` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop                  | Type                 | Default | Description                                                                                  |
+| Name                  | 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 |
 
-## Component Skeleton
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
 
 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 ... />;
-}
-```
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`), the project's event-commit utility, the project's currency utility helpers (for decimal/separator/symbol lookup), and the project's formatting helpers (for display-mode value formatting). It also uses a numeric-format masking library that handles locale-aware decimal/thousands display within a text input. Define the input contract as an extension of the project's field input contract, adding optional `currencyISOCode`, `decimalPrecision`, `showGroupSeparators`, and `formatter` 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`, `readOnly`, `helperText`, `displayMode`, `hideLabel`, `currencyISOCode` (default `'USD'`), `decimalPrecision`, `showGroupSeparators`, `testId`, `placeholder`, `formatter`.
+3. **Local state** — `values` initialized from `value.toString()`.
+4. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+5. **Currency/decimal symbols** — derive the decimal indicator, digit group separator, and currency symbol via the project's currency utility helpers using `currencyISOCode`, and obtain the currency formatting options object.
+6. **Sync from store** — a lifecycle effect watching `value` updates `values` (as a string) whenever it changes.
+7. **Read-only flag** — build a read-only configuration, set to mark the input read-only only when `readOnly` is true.
+8. **Formatted value** — computed eagerly, before the display-mode check: if `formatter === 'Currency'`, compute the formatted value using the project's formatting helper with format key `'currency'` and the currency options; otherwise compute using the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key with the same currency options.
+9. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the formatted value, the latter with a stacked variant.
+10. **Test ID and event handlers** — build a test-id attribute from `testId`; the blur handler commits via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`; the value-change handler updates `values` with the raw numeric string from the masking library's callback.
+11. **Render** — a numeric-format input configured with: value-is-numeric-string flag, full width, current `values`, an outlined style when editable or flat/borderless style when read-only, prefix set to the currency symbol only when read-only AND `formatter === 'Currency'` (otherwise empty), suffix set to `'%'` only when read-only AND `formatter === 'Percentage'` (otherwise empty), decimal separator set to the locale-derived decimal indicator, thousands separator set to the locale-derived group separator only when `showGroupSeparators` is truthy (otherwise empty string), decimal scale set to `undefined` when read-only AND `formatter === 'Currency'` (otherwise `decimalPrecision`), the value-change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, small size, and the read-only/test-id attributes applied to the underlying input element.
 
 ## Behavioral Contract
 
 1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
-2. **Sync from store:** `useEffect` with deps **`[value]`** → `setValues(value.toString())`.
+2. **Sync from store:** A lifecycle effect watching `value` updates `values` (converted to string).
 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);
-   }
-   ```
+4. **Separators:** Derive the decimal indicator and digit group separator from the project's currency utility helpers using `currencyISOCode`. Apply the thousands separator only when `showGroupSeparators` is truthy (otherwise pass an empty string).
+5. **Formatted value (computed eagerly):** When `formatter === 'Currency'`, compute the formatted value using the project's formatting helper with format key `'currency'` and the currency options; otherwise compute using the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key with the same options.
 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.
+   - Prefix: the currency symbol when read-only AND `formatter === 'Currency'`, otherwise empty.
+   - Suffix: `'%'` when read-only AND `formatter === 'Percentage'`, otherwise empty.
+7. **Decimal scale:** `undefined` when read-only AND `formatter === 'Currency'` (let the formatter decide), otherwise `decimalPrecision`.
+8. **On value change:** Update `values` with the raw numeric string from the masking library's callback.
+9. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`.
+10. **Read-only:** Set the read-only attribute on the underlying input. Switch to a flat/borderless visual style. Omit the blur handler.
+11. **Render ordering:** state → read-only flag → formatted value → display modes → test-id + handlers → main render.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the formatted value.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
-`formattedValue` is computed before display-mode check:
+The formatted value is computed before the display-mode check:
 
 - `formatter === 'Currency'` → currency-formatted string.
-- Otherwise → decimal-formatted string using `pConn.getComponentName()?.toLowerCase()` as format key.
+- Otherwise → decimal-formatted string using the component's type name as the format key.
 
 ## Read-Only Rendering
 
-Keep numeric format input with `readOnly: true`. Apply prefix (`$`) or suffix (`%`) based on `formatter`. Flat/borderless visual style.
+Keep the numeric-format input with the read-only attribute set. Apply prefix (currency symbol) or suffix (`%`) based on `formatter`. Use a flat/borderless visual style.
 
 ## Visual Specifications
 
@@ -161,38 +83,37 @@ Keep numeric format input with `readOnly: true`. Apply prefix (`$`) or suffix (`
 | ------------------- | ------------------------------------ | ---------------------------------------------------- |
 | Width               | 100%                                 | 100%                                                 |
 | Size                | Small                                | Small                                                |
-| Variant             | Outlined                             | Standard (flat)                                      |
+| Variant             | Outlined                             | Flat/borderless                                      |
 | 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              | —                                                    |
+| Placeholder         | From the `placeholder` input         | —                                                    |
 
 ## 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.
+- In read-only Currency mode, decimal scale is set to `undefined` (let the formatter decide), not `decimalPrecision`.
+- `thousandSeparator` defaults to empty string (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.
+- A numeric-format masking library (for locale-aware decimal/thousands display within a text input).
+- The project's currency utility helpers — for decimal indicator, digit group separator, and currency symbol lookup.
+- The project's currency options helper — for formatting options based on ISO code.
+- The project's formatting helpers — specifically the named `format` export (not a method on the default export). Use it as a standalone function, not as a property of the default-exported object.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
 **UI control type:** Decimal / numeric formatted input.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                             |
-| ------------------ | ------------------------------------------------- |
-| Default (CSS only) | `<input type="text">` with custom numeric masking |
-| MUI                | `NumericFormat` with `customInput={TextField}`    |
-| Ant Design         | `<InputNumber precision={decimalPrecision} />`    |
-| Chakra UI          | `<NumberInput>`                                   |
+- **Numeric format input** → use a numeric masking library compatible with the project's framework, or implement custom input masking
+- **Decimal/thousands separators** → derive from the currency utility helpers based on the ISO code
+- **Read-only prefix/suffix** → conditionally display the currency symbol or `%` sign
+- **Error state** → the DS's error/danger visual state
+- **Flat/borderless style** → the DS's read-only/standard input variant